@os-eco/overstory-cli 0.7.8 → 0.7.9

package/README.md

@@ -6,7 +6,7 @@ Multi-agent orchestration for AI coding agents.
 [![CI](https://github.com/jayminwest/overstory/actions/workflows/ci.yml/badge.svg)](https://github.com/jayminwest/overstory/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Overstory turns a single coding session into a multi-agent team by spawning worker agents in git worktrees via tmux, coordinating them through a custom SQLite mail system, and merging their work back with tiered conflict resolution. A pluggable `AgentRuntime` interface lets you swap between runtimes — Claude Code, [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent), or your own adapter.
+Overstory turns a single coding session into a multi-agent team by spawning worker agents in git worktrees via tmux, coordinating them through a custom SQLite mail system, and merging their work back with tiered conflict resolution. A pluggable `AgentRuntime` interface lets you swap between runtimes — Claude Code, [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or your own adapter.
 
 > **Warning: Agent swarms are not a universal solution.** Do not deploy Overstory without understanding the risks of multi-agent orchestration — compounding error rates, cost amplification, debugging complexity, and merge conflicts are the normal case, not edge cases. Read [STEELMAN.md](STEELMAN.md) for a full risk analysis and the [Agentic Engineering Book](https://github.com/jayminwest/agentic-engineering-book) ([web version](https://jayminwest.com/agentic-engineering-book)) before using this tool in production.
 
@@ -18,6 +18,7 @@ Requires [Bun](https://bun.sh) v1.0+, git, and tmux. At least one supported agen
 - [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) (`pi` CLI)
 - [GitHub Copilot](https://github.com/features/copilot) (`copilot` CLI)
 - [Codex](https://github.com/openai/codex) (`codex` CLI)
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini` CLI)
 
 ```bash
 bun install -g @os-eco/overstory-cli
@@ -175,6 +176,7 @@ Overstory is runtime-agnostic. The `AgentRuntime` interface (`src/runtimes/types
 | Pi | `pi` | `.pi/extensions/` guard extension | Active development |
 | Copilot | `copilot` | (none — `--allow-all-tools`) | Active development |
 | Codex | `codex` | OS-level sandbox (Seatbelt/Landlock) | Active development |
+| Gemini | `gemini` | `--sandbox` flag | Active development |
 
 ## How It Works
 
@@ -271,7 +273,7 @@ overstory/
     metrics/                      SQLite metrics + pricing + transcript parsing
     doctor/                       Health check modules (11 checks)
     insights/                     Session insight analyzer for auto-expertise
-    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex)
+    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini)
     tracker/                      Pluggable task tracker (beads + seeds backends)
     mulch/                        mulch client (programmatic API + CLI wrapper)
     e2e/                          End-to-end lifecycle tests

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.7.8",
+	"version": "0.7.9",
 	"description": "Multi-agent orchestration for AI coding agents — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution. Pluggable runtime adapters for Claude Code, Pi, and more.",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/agents/manifest.test.ts

@@ -5,7 +5,12 @@ import { join } from "node:path";
 import { AgentError } from "../errors.ts";
 import { cleanupTempDir } from "../test-helpers.ts";
 import type { AgentManifest, OverstoryConfig } from "../types.ts";
-import { createManifestLoader, resolveModel, resolveProviderEnv } from "./manifest.ts";
+import {
+	createManifestLoader,
+	expandAliasFromEnv,
+	resolveModel,
+	resolveProviderEnv,
+} from "./manifest.ts";
 
 const VALID_MANIFEST = {
 	version: "1.0",
@@ -673,6 +678,168 @@ describe("resolveModel", () => {
 	});
 });
 
+describe("expandAliasFromEnv", () => {
+	test("returns expanded model ID when env var is set", () => {
+		expect(
+			expandAliasFromEnv("haiku", {
+				ANTHROPIC_DEFAULT_HAIKU_MODEL: "us.anthropic.claude-3-5-haiku-20241022-v1:0",
+			}),
+		).toBe("us.anthropic.claude-3-5-haiku-20241022-v1:0");
+	});
+
+	test("returns alias unchanged when env var is unset", () => {
+		expect(expandAliasFromEnv("haiku", {})).toBe("haiku");
+	});
+
+	test("expands all three aliases via their env vars", () => {
+		const env = {
+			ANTHROPIC_DEFAULT_HAIKU_MODEL: "bedrock-haiku-id",
+			ANTHROPIC_DEFAULT_SONNET_MODEL: "bedrock-sonnet-id",
+			ANTHROPIC_DEFAULT_OPUS_MODEL: "bedrock-opus-id",
+		};
+		expect(expandAliasFromEnv("haiku", env)).toBe("bedrock-haiku-id");
+		expect(expandAliasFromEnv("sonnet", env)).toBe("bedrock-sonnet-id");
+		expect(expandAliasFromEnv("opus", env)).toBe("bedrock-opus-id");
+	});
+
+	test("trims whitespace from env var value", () => {
+		expect(
+			expandAliasFromEnv("sonnet", {
+				ANTHROPIC_DEFAULT_SONNET_MODEL: "  bedrock-sonnet-id  ",
+			}),
+		).toBe("bedrock-sonnet-id");
+	});
+
+	test("returns alias when env var is empty string", () => {
+		expect(expandAliasFromEnv("sonnet", { ANTHROPIC_DEFAULT_SONNET_MODEL: "" })).toBe("sonnet");
+	});
+
+	test("returns alias when env var is whitespace only", () => {
+		expect(expandAliasFromEnv("sonnet", { ANTHROPIC_DEFAULT_SONNET_MODEL: "   " })).toBe("sonnet");
+	});
+
+	test("returns unknown alias unchanged", () => {
+		expect(expandAliasFromEnv("gpt-4", {})).toBe("gpt-4");
+	});
+});
+
+describe("resolveModel env var expansion", () => {
+	const baseManifest: AgentManifest = {
+		version: "1.0",
+		agents: {
+			scout: {
+				file: "scout.md",
+				model: "haiku",
+				tools: ["Read"],
+				capabilities: ["explore"],
+				canSpawn: false,
+				constraints: [],
+			},
+			builder: {
+				file: "builder.md",
+				model: "sonnet",
+				tools: ["Read", "Write"],
+				capabilities: ["implement"],
+				canSpawn: false,
+				constraints: [],
+			},
+		},
+		capabilityIndex: { explore: ["scout"], implement: ["builder"] },
+	};
+
+	function makeConfig(models: OverstoryConfig["models"] = {}): OverstoryConfig {
+		return {
+			project: { name: "test", root: "/tmp/test", canonicalBranch: "main" },
+			agents: {
+				manifestPath: ".overstory/agent-manifest.json",
+				baseDir: ".overstory/agent-defs",
+				maxConcurrent: 5,
+				staggerDelayMs: 1000,
+				maxDepth: 2,
+				maxSessionsPerRun: 0,
+				maxAgentsPerLead: 5,
+			},
+			worktrees: { baseDir: ".overstory/worktrees" },
+			taskTracker: { backend: "auto", enabled: false },
+			mulch: { enabled: false, domains: [], primeFormat: "markdown" },
+			merge: { aiResolveEnabled: false, reimagineEnabled: false },
+			providers: { anthropic: { type: "native" } },
+			watchdog: {
+				tier0Enabled: false,
+				tier0IntervalMs: 30000,
+				tier1Enabled: false,
+				tier2Enabled: false,
+				staleThresholdMs: 300000,
+				zombieThresholdMs: 600000,
+				nudgeIntervalMs: 60000,
+			},
+			models,
+			logging: { verbose: false, redactSecrets: true },
+		};
+	}
+
+	test("expands alias when env var is set", () => {
+		const saved = process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL;
+		process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL = "us.anthropic.claude-3-5-haiku-20241022-v1:0";
+		try {
+			const result = resolveModel(makeConfig(), baseManifest, "scout", "sonnet");
+			expect(result).toEqual({ model: "us.anthropic.claude-3-5-haiku-20241022-v1:0" });
+		} finally {
+			if (saved === undefined) {
+				delete process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL;
+			} else {
+				process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL = saved;
+			}
+		}
+	});
+
+	test("passes alias through when env var is unset", () => {
+		const saved = process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL;
+		delete process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL;
+		try {
+			const result = resolveModel(makeConfig(), baseManifest, "scout", "sonnet");
+			expect(result).toEqual({ model: "haiku" });
+		} finally {
+			if (saved !== undefined) {
+				process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL = saved;
+			}
+		}
+	});
+
+	test("config override to full model ID is not affected by env vars", () => {
+		const saved = process.env.ANTHROPIC_DEFAULT_SONNET_MODEL;
+		process.env.ANTHROPIC_DEFAULT_SONNET_MODEL = "bedrock-sonnet";
+		try {
+			// Config overrides to a direct model string (not an alias)
+			const config = makeConfig({ builder: "claude-3-5-sonnet-20241022" });
+			const result = resolveModel(config, baseManifest, "builder", "haiku");
+			expect(result).toEqual({ model: "claude-3-5-sonnet-20241022" });
+		} finally {
+			if (saved === undefined) {
+				delete process.env.ANTHROPIC_DEFAULT_SONNET_MODEL;
+			} else {
+				process.env.ANTHROPIC_DEFAULT_SONNET_MODEL = saved;
+			}
+		}
+	});
+
+	test("config override to alias also expands via env var", () => {
+		const saved = process.env.ANTHROPIC_DEFAULT_OPUS_MODEL;
+		process.env.ANTHROPIC_DEFAULT_OPUS_MODEL = "bedrock-opus-id";
+		try {
+			const config = makeConfig({ scout: "opus" });
+			const result = resolveModel(config, baseManifest, "scout", "haiku");
+			expect(result).toEqual({ model: "bedrock-opus-id" });
+		} finally {
+			if (saved === undefined) {
+				delete process.env.ANTHROPIC_DEFAULT_OPUS_MODEL;
+			} else {
+				process.env.ANTHROPIC_DEFAULT_OPUS_MODEL = saved;
+			}
+		}
+	});
+});
+
 describe("resolveProviderEnv", () => {
 	test("returns null for unknown provider", () => {
 		const result = resolveProviderEnv("unknown", "some/model", {});

package/src/agents/manifest.ts

@@ -34,6 +34,27 @@ interface RawManifest {
 
 const MODEL_ALIASES = new Set(["sonnet", "opus", "haiku"]);
 
+// Env var mapping: alias → ANTHROPIC_DEFAULT_{ALIAS}_MODEL
+const ALIAS_ENV_VARS: Record<string, string> = {
+	haiku: "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+	sonnet: "ANTHROPIC_DEFAULT_SONNET_MODEL",
+	opus: "ANTHROPIC_DEFAULT_OPUS_MODEL",
+};
+
+/**
+ * Expand a model alias via its corresponding ANTHROPIC_DEFAULT_{ALIAS}_MODEL env var.
+ * Returns the env var value if set, otherwise the original alias.
+ */
+export function expandAliasFromEnv(
+	alias: string,
+	env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+): string {
+	const envVar = ALIAS_ENV_VARS[alias];
+	if (!envVar) return alias;
+	const value = env[envVar];
+	return value?.trim() || alias;
+}
+
 /**
  * Validate that a raw parsed object conforms to the AgentDefinition shape.
  * Returns a list of error messages for any violations.
@@ -333,9 +354,9 @@ export function resolveModel(
 	const configModel = config.models[role];
 	const rawModel = configModel ?? manifest.agents[role]?.model ?? fallback;
 
-	// Simple alias — no provider env needed
+	// Simple alias — expand via env var if set (e.g. ANTHROPIC_DEFAULT_SONNET_MODEL)
 	if (MODEL_ALIASES.has(rawModel)) {
-		return { model: rawModel };
+		return { model: expandAliasFromEnv(rawModel) };
 	}
 
 	// Provider-prefixed: split on first "/" to get provider name and model ID

package/src/commands/agents.ts

@@ -34,6 +34,7 @@ export interface DiscoveredAgent {
 const KNOWN_INSTRUCTION_PATHS = [
 	join(".claude", "CLAUDE.md"), // Claude Code, Pi
 	"AGENTS.md", // Codex (future)
+	"GEMINI.md", // Gemini CLI
 ];
 
 /**

package/src/commands/init.test.ts

@@ -166,6 +166,7 @@ describe("initCommand: .overstory/.gitignore", () => {
 		expect(content).toContain("!hooks.json\n");
 		expect(content).toContain("!groups.json\n");
 		expect(content).toContain("!agent-defs/\n");
+		expect(content).toContain("!agent-defs/**\n");
 
 		// Verify it matches the exported constant
 		expect(content).toBe(OVERSTORY_GITIGNORE);

package/src/commands/init.ts

@@ -588,6 +588,7 @@ export const OVERSTORY_GITIGNORE = `# Wildcard+whitelist: ignore everything, whi
 !hooks.json
 !groups.json
 !agent-defs/
+!agent-defs/**
 !README.md
 `;
 

package/src/commands/prime.test.ts

@@ -366,6 +366,7 @@ recentTasks: []
 !hooks.json
 !groups.json
 !agent-defs/
+!agent-defs/**
 !README.md
 `;
 

package/src/doctor/structure.test.ts

@@ -114,6 +114,7 @@ describe("checkStructure", () => {
 !hooks.json
 !groups.json
 !agent-defs/
+!agent-defs/**
 `,
 		);
 

package/src/doctor/structure.ts

@@ -111,6 +111,7 @@ export const checkStructure: DoctorCheckFn = async (
 		"!hooks.json",
 		"!groups.json",
 		"!agent-defs/",
+		"!agent-defs/**",
 	];
 
 	try {

package/src/index.ts

@@ -45,7 +45,7 @@ import { OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.7.8";
+export const VERSION = "0.7.9";
 
 const rawArgs = process.argv.slice(2);
 

package/src/runtimes/gemini.test.ts

@@ -0,0 +1,537 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import type { ResolvedModel } from "../types.ts";
+import { GeminiRuntime } from "./gemini.ts";
+import type { SpawnOpts } from "./types.ts";
+
+describe("GeminiRuntime", () => {
+	const runtime = new GeminiRuntime();
+
+	describe("id and instructionPath", () => {
+		test("id is 'gemini'", () => {
+			expect(runtime.id).toBe("gemini");
+		});
+
+		test("instructionPath is GEMINI.md", () => {
+			expect(runtime.instructionPath).toBe("GEMINI.md");
+		});
+	});
+
+	describe("buildSpawnCommand", () => {
+		test("bypass permission mode includes --approval-mode yolo", () => {
+			const opts: SpawnOpts = {
+				model: "gemini-2.5-pro",
+				permissionMode: "bypass",
+				cwd: "/tmp/worktree",
+				env: {},
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toBe("gemini -m gemini-2.5-pro --approval-mode yolo");
+		});
+
+		test("ask permission mode omits approval flag", () => {
+			const opts: SpawnOpts = {
+				model: "gemini-2.5-flash",
+				permissionMode: "ask",
+				cwd: "/tmp/worktree",
+				env: {},
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toBe("gemini -m gemini-2.5-flash");
+			expect(cmd).not.toContain("--approval-mode");
+			expect(cmd).not.toContain("yolo");
+		});
+
+		test("appendSystemPrompt is ignored (gemini has no such flag)", () => {
+			const opts: SpawnOpts = {
+				model: "gemini-2.5-pro",
+				permissionMode: "bypass",
+				cwd: "/tmp/worktree",
+				env: {},
+				appendSystemPrompt: "You are a builder agent.",
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toBe("gemini -m gemini-2.5-pro --approval-mode yolo");
+			expect(cmd).not.toContain("append-system-prompt");
+			expect(cmd).not.toContain("You are a builder agent");
+		});
+
+		test("appendSystemPromptFile is ignored (gemini has no such flag)", () => {
+			const opts: SpawnOpts = {
+				model: "gemini-2.5-pro",
+				permissionMode: "bypass",
+				cwd: "/project",
+				env: {},
+				appendSystemPromptFile: "/project/.overstory/agent-defs/coordinator.md",
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toBe("gemini -m gemini-2.5-pro --approval-mode yolo");
+			expect(cmd).not.toContain("cat");
+			expect(cmd).not.toContain("coordinator.md");
+		});
+
+		test("cwd and env are not embedded in command string", () => {
+			const opts: SpawnOpts = {
+				model: "gemini-2.5-pro",
+				permissionMode: "bypass",
+				cwd: "/some/specific/path",
+				env: { GEMINI_API_KEY: "test-key" },
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).not.toContain("/some/specific/path");
+			expect(cmd).not.toContain("test-key");
+			expect(cmd).not.toContain("GEMINI_API_KEY");
+		});
+
+		test("model alias is passed through unchanged", () => {
+			const opts: SpawnOpts = {
+				model: "flash",
+				permissionMode: "bypass",
+				cwd: "/tmp/worktree",
+				env: {},
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toContain("-m flash");
+		});
+	});
+
+	describe("buildPrintCommand", () => {
+		test("basic prompt produces gemini -p argv with --yolo", () => {
+			const cmd = runtime.buildPrintCommand("Resolve this conflict");
+			expect(cmd).toEqual(["gemini", "-p", "Resolve this conflict", "--yolo"]);
+		});
+
+		test("with model override adds -m flag", () => {
+			const cmd = runtime.buildPrintCommand("Triage this failure", "gemini-2.5-flash");
+			expect(cmd).toEqual([
+				"gemini",
+				"-p",
+				"Triage this failure",
+				"--yolo",
+				"-m",
+				"gemini-2.5-flash",
+			]);
+		});
+
+		test("without model omits -m flag", () => {
+			const cmd = runtime.buildPrintCommand("Classify this error");
+			expect(cmd).not.toContain("-m");
+		});
+
+		test("prompt with special characters is preserved", () => {
+			const prompt = 'Fix the "bug" in file\'s path & run tests';
+			const cmd = runtime.buildPrintCommand(prompt);
+			expect(cmd[2]).toBe(prompt);
+		});
+
+		test("empty prompt is passed through", () => {
+			const cmd = runtime.buildPrintCommand("");
+			expect(cmd).toEqual(["gemini", "-p", "", "--yolo"]);
+		});
+	});
+
+	describe("deployConfig", () => {
+		let tempDir: string;
+
+		beforeEach(async () => {
+			tempDir = await mkdtemp(join(tmpdir(), "ov-gemini-test-"));
+		});
+
+		afterEach(async () => {
+			await cleanupTempDir(tempDir);
+		});
+
+		test("writes GEMINI.md to worktree root", async () => {
+			await runtime.deployConfig(
+				tempDir,
+				{ content: "# Task\nBuild the feature." },
+				{ agentName: "test-agent", capability: "builder", worktreePath: tempDir },
+			);
+
+			const file = Bun.file(join(tempDir, "GEMINI.md"));
+			expect(await file.exists()).toBe(true);
+			expect(await file.text()).toBe("# Task\nBuild the feature.");
+		});
+
+		test("no-op when overlay is undefined", async () => {
+			await runtime.deployConfig(tempDir, undefined, {
+				agentName: "test-agent",
+				capability: "coordinator",
+				worktreePath: tempDir,
+			});
+
+			const file = Bun.file(join(tempDir, "GEMINI.md"));
+			expect(await file.exists()).toBe(false);
+		});
+
+		test("hooks parameter is unused (no guard deployment)", async () => {
+			await runtime.deployConfig(
+				tempDir,
+				{ content: "# Instructions" },
+				{
+					agentName: "my-builder",
+					capability: "builder",
+					worktreePath: tempDir,
+					qualityGates: [
+						{ command: "bun test", name: "tests", description: "all tests must pass" },
+					],
+				},
+			);
+
+			// Only GEMINI.md should exist — no settings files or guard extensions.
+			const geminiFile = Bun.file(join(tempDir, "GEMINI.md"));
+			expect(await geminiFile.exists()).toBe(true);
+
+			// No Claude Code settings file.
+			const settingsFile = Bun.file(join(tempDir, ".claude", "settings.local.json"));
+			expect(await settingsFile.exists()).toBe(false);
+
+			// No Pi guard extension.
+			const piGuardFile = Bun.file(join(tempDir, ".pi", "extensions", "overstory-guard.ts"));
+			expect(await piGuardFile.exists()).toBe(false);
+		});
+
+		test("overwrites existing GEMINI.md", async () => {
+			await Bun.write(join(tempDir, "GEMINI.md"), "# Old content");
+
+			await runtime.deployConfig(
+				tempDir,
+				{ content: "# New content" },
+				{ agentName: "test-agent", capability: "builder", worktreePath: tempDir },
+			);
+
+			const file = Bun.file(join(tempDir, "GEMINI.md"));
+			expect(await file.text()).toBe("# New content");
+		});
+
+		test("creates parent directories if needed", async () => {
+			const nestedDir = join(tempDir, "nested", "deep");
+
+			await runtime.deployConfig(
+				nestedDir,
+				{ content: "# Nested" },
+				{ agentName: "test-agent", capability: "builder", worktreePath: nestedDir },
+			);
+
+			const file = Bun.file(join(nestedDir, "GEMINI.md"));
+			expect(await file.exists()).toBe(true);
+		});
+	});
+
+	describe("detectReady", () => {
+		test("returns ready when placeholder and gemini branding visible", () => {
+			const pane = "✨ Gemini CLI v1.0.0\n\n> Type your message or @path/to/file";
+			expect(runtime.detectReady(pane)).toEqual({ phase: "ready" });
+		});
+
+		test("returns ready with > prefix and gemini text", () => {
+			const pane = "gemini-2.5-pro | model: gemini\n> ";
+			expect(runtime.detectReady(pane)).toEqual({ phase: "ready" });
+		});
+
+		test("returns ready with ❯ prompt and gemini text", () => {
+			const pane = "Gemini CLI\n❯ ";
+			expect(runtime.detectReady(pane)).toEqual({ phase: "ready" });
+		});
+
+		test("returns loading when no prompt indicator", () => {
+			const pane = "Starting Gemini CLI...";
+			expect(runtime.detectReady(pane)).toEqual({ phase: "loading" });
+		});
+
+		test("returns loading when no gemini branding", () => {
+			const pane = "> Type your message or @path/to/file";
+			expect(runtime.detectReady(pane)).toEqual({ phase: "loading" });
+		});
+
+		test("returns loading for empty pane", () => {
+			expect(runtime.detectReady("")).toEqual({ phase: "loading" });
+		});
+
+		test("returns loading during initialization", () => {
+			const pane = "Loading model...";
+			expect(runtime.detectReady(pane)).toEqual({ phase: "loading" });
+		});
+
+		test("case-insensitive gemini detection", () => {
+			const pane = "GEMINI CLI v1.0\n> ready";
+			expect(runtime.detectReady(pane)).toEqual({ phase: "ready" });
+		});
+
+		test("case-insensitive placeholder detection", () => {
+			const pane = "Gemini\nType Your Message here";
+			expect(runtime.detectReady(pane)).toEqual({ phase: "ready" });
+		});
+
+		test("never returns dialog phase (gemini has no trust dialog)", () => {
+			// Try various pane contents — should never get "dialog" phase.
+			const panes = ["", "Gemini CLI", "> ready", "Gemini\n> ", "Loading...", "trust this folder"];
+			for (const pane of panes) {
+				const result = runtime.detectReady(pane);
+				expect(result.phase).not.toBe("dialog");
+			}
+		});
+	});
+
+	describe("requiresBeaconVerification", () => {
+		test("not defined — defaults to true (gets resend loop)", () => {
+			// GeminiRuntime does not override requiresBeaconVerification.
+			// When omitted, the orchestrator defaults to true (resend loop enabled).
+			// Verify the method is not present on the instance.
+			expect("requiresBeaconVerification" in runtime).toBe(false);
+		});
+	});
+
+	describe("parseTranscript", () => {
+		let tempDir: string;
+
+		beforeEach(async () => {
+			tempDir = await mkdtemp(join(tmpdir(), "ov-gemini-transcript-"));
+		});
+
+		afterEach(async () => {
+			await cleanupTempDir(tempDir);
+		});
+
+		test("returns null for missing file", async () => {
+			const result = await runtime.parseTranscript(join(tempDir, "nonexistent.jsonl"));
+			expect(result).toBeNull();
+		});
+
+		test("parses init event for model", async () => {
+			const transcript = [
+				'{"type":"init","timestamp":"2026-01-01T00:00:00Z","session_id":"abc","model":"gemini-2.5-pro"}',
+				'{"type":"result","timestamp":"2026-01-01T00:01:00Z","status":"success","stats":{"input_tokens":100,"output_tokens":50,"total_tokens":150,"cached":0,"input":100,"duration_ms":1000,"tool_calls":0}}',
+			].join("\n");
+
+			const path = join(tempDir, "transcript.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 100,
+				outputTokens: 50,
+				model: "gemini-2.5-pro",
+			});
+		});
+
+		test("aggregates token usage from multiple result events", async () => {
+			const transcript = [
+				'{"type":"init","model":"gemini-2.5-flash"}',
+				'{"type":"result","stats":{"input_tokens":200,"output_tokens":100}}',
+				'{"type":"result","stats":{"input_tokens":150,"output_tokens":75}}',
+			].join("\n");
+
+			const path = join(tempDir, "transcript.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 350,
+				outputTokens: 175,
+				model: "gemini-2.5-flash",
+			});
+		});
+
+		test("handles transcript with no token usage", async () => {
+			const transcript = [
+				'{"type":"init","model":"gemini-2.5-pro"}',
+				'{"type":"message","role":"user","content":"hello"}',
+				'{"type":"message","role":"assistant","content":"hi","delta":true}',
+			].join("\n");
+
+			const path = join(tempDir, "transcript.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 0,
+				outputTokens: 0,
+				model: "gemini-2.5-pro",
+			});
+		});
+
+		test("skips malformed JSON lines", async () => {
+			const transcript = [
+				'{"type":"init","model":"gemini-2.5-pro"}',
+				"this is not json",
+				'{"type":"result","stats":{"input_tokens":500,"output_tokens":200}}',
+				"{broken json",
+			].join("\n");
+
+			const path = join(tempDir, "transcript.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 500,
+				outputTokens: 200,
+				model: "gemini-2.5-pro",
+			});
+		});
+
+		test("returns empty model when no init event", async () => {
+			const transcript = '{"type":"result","stats":{"input_tokens":100,"output_tokens":50}}';
+
+			const path = join(tempDir, "transcript.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 100,
+				outputTokens: 50,
+				model: "",
+			});
+		});
+
+		test("handles empty file", async () => {
+			const path = join(tempDir, "empty.jsonl");
+			await Bun.write(path, "");
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 0,
+				outputTokens: 0,
+				model: "",
+			});
+		});
+
+		test("handles result event with missing stats", async () => {
+			const transcript = [
+				'{"type":"init","model":"gemini-2.5-pro"}',
+				'{"type":"result","status":"error"}',
+			].join("\n");
+
+			const path = join(tempDir, "transcript.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 0,
+				outputTokens: 0,
+				model: "gemini-2.5-pro",
+			});
+		});
+
+		test("handles result event with partial stats", async () => {
+			const transcript = [
+				'{"type":"init","model":"gemini-2.5-pro"}',
+				'{"type":"result","stats":{"input_tokens":300}}',
+			].join("\n");
+
+			const path = join(tempDir, "transcript.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 300,
+				outputTokens: 0,
+				model: "gemini-2.5-pro",
+			});
+		});
+
+		test("fallback model from any event with model field", async () => {
+			const transcript = [
+				'{"type":"message","role":"assistant","model":"gemini-2.5-pro","content":"hello"}',
+				'{"type":"result","stats":{"input_tokens":50,"output_tokens":25}}',
+			].join("\n");
+
+			const path = join(tempDir, "transcript.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 50,
+				outputTokens: 25,
+				model: "gemini-2.5-pro",
+			});
+		});
+
+		test("init event model takes precedence over fallback", async () => {
+			const transcript = [
+				'{"type":"message","model":"gemini-2.5-flash"}',
+				'{"type":"init","model":"gemini-2.5-pro"}',
+				'{"type":"result","stats":{"input_tokens":10,"output_tokens":5}}',
+			].join("\n");
+
+			const path = join(tempDir, "transcript.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 10,
+				outputTokens: 5,
+				model: "gemini-2.5-pro",
+			});
+		});
+
+		test("handles trailing newline", async () => {
+			const transcript =
+				'{"type":"init","model":"gemini-2.5-pro"}\n{"type":"result","stats":{"input_tokens":100,"output_tokens":50}}\n';
+
+			const path = join(tempDir, "transcript.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 100,
+				outputTokens: 50,
+				model: "gemini-2.5-pro",
+			});
+		});
+
+		test("full stream-json transcript with all event types", async () => {
+			const transcript = [
+				'{"type":"init","timestamp":"2026-03-01T12:00:00Z","session_id":"sess-123","model":"gemini-2.5-pro"}',
+				'{"type":"message","timestamp":"2026-03-01T12:00:01Z","role":"user","content":"Fix the bug"}',
+				'{"type":"message","timestamp":"2026-03-01T12:00:02Z","role":"assistant","content":"I will","delta":true}',
+				'{"type":"tool_use","timestamp":"2026-03-01T12:00:03Z","tool_name":"Read","tool_id":"read-1","parameters":{"file_path":"/src/main.ts"}}',
+				'{"type":"tool_result","timestamp":"2026-03-01T12:00:04Z","tool_id":"read-1","status":"success","output":"contents"}',
+				'{"type":"message","timestamp":"2026-03-01T12:00:05Z","role":"assistant","content":"Fixed it","delta":true}',
+				'{"type":"result","timestamp":"2026-03-01T12:00:06Z","status":"success","stats":{"total_tokens":1500,"input_tokens":1000,"output_tokens":500,"cached":200,"input":800,"duration_ms":5000,"tool_calls":1}}',
+			].join("\n");
+
+			const path = join(tempDir, "full-session.jsonl");
+			await Bun.write(path, transcript);
+
+			const result = await runtime.parseTranscript(path);
+			expect(result).toEqual({
+				inputTokens: 1000,
+				outputTokens: 500,
+				model: "gemini-2.5-pro",
+			});
+		});
+	});
+
+	describe("buildEnv", () => {
+		test("returns model env vars when present", () => {
+			const model: ResolvedModel = {
+				model: "gemini-2.5-pro",
+				env: { GEMINI_API_KEY: "test-key-123" },
+			};
+			expect(runtime.buildEnv(model)).toEqual({ GEMINI_API_KEY: "test-key-123" });
+		});
+
+		test("returns empty object when model has no env", () => {
+			const model: ResolvedModel = { model: "gemini-2.5-pro" };
+			expect(runtime.buildEnv(model)).toEqual({});
+		});
+
+		test("passes through multiple env vars", () => {
+			const model: ResolvedModel = {
+				model: "gemini-2.5-pro",
+				env: {
+					GEMINI_API_KEY: "key",
+					GOOGLE_CLOUD_PROJECT: "my-project",
+				},
+			};
+			expect(runtime.buildEnv(model)).toEqual({
+				GEMINI_API_KEY: "key",
+				GOOGLE_CLOUD_PROJECT: "my-project",
+			});
+		});
+	});
+});

package/src/runtimes/gemini.ts

@@ -0,0 +1,235 @@
+// Gemini CLI runtime adapter for overstory's AgentRuntime interface.
+// Implements the AgentRuntime contract for Google's `gemini` CLI.
+//
+// Key characteristics:
+// - TUI: `gemini` maintains an interactive Ink-based TUI in tmux
+// - Instruction file: GEMINI.md (read automatically from workspace root)
+// - No hooks: Gemini CLI has no hook/guard mechanism (like Copilot)
+// - Sandbox: `--sandbox` flag + `--approval-mode yolo` for bypass
+// - Headless: `gemini -p "prompt"` for one-shot calls
+// - Transcripts: `--output-format stream-json` produces NDJSON events
+
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { ResolvedModel } from "../types.ts";
+import type {
+	AgentRuntime,
+	HooksDef,
+	OverlayContent,
+	ReadyState,
+	SpawnOpts,
+	TranscriptSummary,
+} from "./types.ts";
+
+/**
+ * Gemini CLI runtime adapter.
+ *
+ * Implements AgentRuntime for Google's `gemini` CLI (Gemini coding agent).
+ * Gemini maintains an interactive Ink-based TUI, similar to Copilot.
+ *
+ * Security: Gemini CLI supports `--sandbox` for filesystem isolation
+ * (Seatbelt on macOS, container-based on Linux) but has no hook/guard
+ * mechanism for per-tool interception. The `_hooks` parameter in
+ * `deployConfig` is unused.
+ *
+ * Instructions are delivered via `GEMINI.md` (Gemini's native context
+ * file convention), which the CLI reads automatically from the workspace.
+ */
+export class GeminiRuntime implements AgentRuntime {
+	/** Unique identifier for this runtime. */
+	readonly id = "gemini";
+
+	/** Relative path to the instruction file within a worktree. */
+	readonly instructionPath = "GEMINI.md";
+
+	/**
+	 * Build the shell command string to spawn an interactive Gemini agent.
+	 *
+	 * Maps SpawnOpts to `gemini` CLI flags:
+	 * - `model` → `-m <model>`
+	 * - `permissionMode === "bypass"` → `--approval-mode yolo`
+	 * - `permissionMode === "ask"` → no approval flag
+	 * - `appendSystemPrompt` and `appendSystemPromptFile` are IGNORED —
+	 *   the `gemini` CLI has no `--append-system-prompt` equivalent.
+	 *   Role definitions are deployed via GEMINI.md instead.
+	 *
+	 * @param opts - Spawn options (model, permissionMode; appendSystemPrompt ignored)
+	 * @returns Shell command string suitable for tmux new-session -c
+	 */
+	buildSpawnCommand(opts: SpawnOpts): string {
+		let cmd = `gemini -m ${opts.model}`;
+
+		if (opts.permissionMode === "bypass") {
+			cmd += " --approval-mode yolo";
+		}
+
+		// appendSystemPrompt and appendSystemPromptFile are intentionally ignored.
+		// The gemini CLI has no --append-system-prompt equivalent. Role definitions
+		// are deployed via GEMINI.md (the instruction file) by deployConfig().
+
+		return cmd;
+	}
+
+	/**
+	 * Build the argv array for a headless one-shot Gemini invocation.
+	 *
+	 * Returns an argv array suitable for `Bun.spawn()`. The `-p` flag
+	 * triggers headless mode — the CLI processes the prompt (including tool
+	 * invocations) and exits. `--yolo` auto-approves tool calls; without it,
+	 * unapproved tool calls fail rather than hang.
+	 *
+	 * Used by merge/resolver.ts and watchdog/triage.ts for AI-assisted operations.
+	 *
+	 * @param prompt - The prompt to pass via `-p`
+	 * @param model - Optional model override
+	 * @returns Argv array for Bun.spawn
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const cmd = ["gemini", "-p", prompt, "--yolo"];
+		if (model !== undefined) {
+			cmd.push("-m", model);
+		}
+		return cmd;
+	}
+
+	/**
+	 * Deploy per-agent instructions to a worktree.
+	 *
+	 * Writes the overlay to `GEMINI.md` in the worktree root (Gemini's
+	 * native context file convention). The CLI reads GEMINI.md automatically
+	 * when starting in a directory that contains one.
+	 *
+	 * The `hooks` parameter is unused — Gemini CLI has no hook mechanism
+	 * for per-tool interception. Security depends on `--sandbox` and
+	 * `--approval-mode` flags instead.
+	 *
+	 * @param worktreePath - Absolute path to the agent's git worktree
+	 * @param overlay - Overlay content to write as GEMINI.md, or undefined to skip
+	 * @param _hooks - Unused for Gemini runtime
+	 */
+	async deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		_hooks: HooksDef,
+	): Promise<void> {
+		if (!overlay) return;
+
+		const geminiPath = join(worktreePath, this.instructionPath);
+		await mkdir(dirname(geminiPath), { recursive: true });
+		await Bun.write(geminiPath, overlay.content);
+	}
+
+	/**
+	 * Detect Gemini TUI readiness from a tmux pane content snapshot.
+	 *
+	 * Gemini uses an Ink-based React TUI. Detection requires both a
+	 * prompt indicator AND a Gemini branding indicator:
+	 *
+	 * - Prompt: "> " prefix, placeholder "type your message", or U+276F (❯)
+	 * - Branding: "gemini" visible in the TUI header or status area
+	 *
+	 * No trust dialog phase exists for Gemini (unlike Claude Code).
+	 *
+	 * @param paneContent - Captured tmux pane content to analyze
+	 * @returns Current readiness phase (never "dialog" for Gemini)
+	 */
+	detectReady(paneContent: string): ReadyState {
+		const lower = paneContent.toLowerCase();
+
+		// Prompt indicator: placeholder text, "> " at line start, or ❯ character.
+		const hasPrompt =
+			lower.includes("type your message") ||
+			/^> /m.test(paneContent) ||
+			paneContent.includes("\u276f");
+
+		// Branding indicator: "gemini" visible in TUI header/status.
+		const hasGemini = lower.includes("gemini");
+
+		if (hasPrompt && hasGemini) {
+			return { phase: "ready" };
+		}
+
+		return { phase: "loading" };
+	}
+
+	/**
+	 * Parse a Gemini NDJSON transcript file into normalized token usage.
+	 *
+	 * Gemini's `--output-format stream-json` produces NDJSON with these events:
+	 * - `init`: carries `model` and `session_id`
+	 * - `message`: user/assistant messages (content chunks when delta=true)
+	 * - `tool_use` / `tool_result`: tool call lifecycle
+	 * - `result`: final event with `stats.input_tokens` and `stats.output_tokens`
+	 *
+	 * Returns null if the file does not exist or cannot be parsed.
+	 *
+	 * @param path - Absolute path to the Gemini NDJSON transcript file
+	 * @returns Aggregated token usage, or null if unavailable
+	 */
+	async parseTranscript(path: string): Promise<TranscriptSummary | null> {
+		const file = Bun.file(path);
+		if (!(await file.exists())) {
+			return null;
+		}
+
+		try {
+			const text = await file.text();
+			const lines = text.split("\n").filter((l) => l.trim().length > 0);
+
+			let inputTokens = 0;
+			let outputTokens = 0;
+			let model = "";
+
+			for (const line of lines) {
+				let event: Record<string, unknown>;
+				try {
+					event = JSON.parse(line) as Record<string, unknown>;
+				} catch {
+					// Skip malformed lines — partial writes during capture.
+					continue;
+				}
+
+				// Model from init event.
+				if (event.type === "init" && typeof event.model === "string") {
+					model = event.model;
+				}
+
+				// Token usage from result event's stats field.
+				if (event.type === "result" && typeof event.stats === "object" && event.stats !== null) {
+					const stats = event.stats as Record<string, unknown>;
+					const inp = stats.input_tokens;
+					const out = stats.output_tokens;
+					if (typeof inp === "number") {
+						inputTokens += inp;
+					}
+					if (typeof out === "number") {
+						outputTokens += out;
+					}
+				}
+
+				// Fallback: capture model from any event that carries it.
+				if (typeof event.model === "string" && event.model && !model) {
+					model = event.model;
+				}
+			}
+
+			return { inputTokens, outputTokens, model };
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Build runtime-specific environment variables for model/provider routing.
+	 *
+	 * Returns the provider environment variables from the resolved model.
+	 * For Google native: may include GEMINI_API_KEY.
+	 * For gateway providers: may include gateway-specific auth and routing vars.
+	 *
+	 * @param model - Resolved model with optional provider env vars
+	 * @returns Environment variable map (may be empty)
+	 */
+	buildEnv(model: ResolvedModel): Record<string, string> {
+		return model.env ?? {};
+	}
+}

package/src/runtimes/registry.test.ts

@@ -3,6 +3,7 @@ import type { OverstoryConfig } from "../types.ts";
 import { ClaudeRuntime } from "./claude.ts";
 import { CodexRuntime } from "./codex.ts";
 import { CopilotRuntime } from "./copilot.ts";
+import { GeminiRuntime } from "./gemini.ts";
 import { PiRuntime } from "./pi.ts";
 import { getRuntime } from "./registry.ts";
 
@@ -21,7 +22,7 @@ describe("getRuntime", () => {
 
 	it("throws with a helpful message for an unknown runtime", () => {
 		expect(() => getRuntime("unknown-runtime")).toThrow(
-			'Unknown runtime: "unknown-runtime". Available: claude, codex, pi, copilot',
+			'Unknown runtime: "unknown-runtime". Available: claude, codex, pi, copilot, gemini',
 		);
 	});
 
@@ -103,4 +104,17 @@ describe("getRuntime", () => {
 		const b = getRuntime("copilot");
 		expect(a).not.toBe(b);
 	});
+
+	it("returns GeminiRuntime when name is 'gemini'", () => {
+		const runtime = getRuntime("gemini");
+		expect(runtime).toBeInstanceOf(GeminiRuntime);
+		expect(runtime.id).toBe("gemini");
+	});
+
+	it("uses config.runtime.default 'gemini' when name is omitted", () => {
+		const config = { runtime: { default: "gemini" } } as OverstoryConfig;
+		const runtime = getRuntime(undefined, config);
+		expect(runtime).toBeInstanceOf(GeminiRuntime);
+		expect(runtime.id).toBe("gemini");
+	});
 });

package/src/runtimes/registry.ts

@@ -5,6 +5,7 @@ import type { OverstoryConfig } from "../types.ts";
 import { ClaudeRuntime } from "./claude.ts";
 import { CodexRuntime } from "./codex.ts";
 import { CopilotRuntime } from "./copilot.ts";
+import { GeminiRuntime } from "./gemini.ts";
 import { PiRuntime } from "./pi.ts";
 import type { AgentRuntime } from "./types.ts";
 
@@ -14,6 +15,7 @@ const runtimes = new Map<string, () => AgentRuntime>([
 	["codex", () => new CodexRuntime()],
 	["pi", () => new PiRuntime()],
 	["copilot", () => new CopilotRuntime()],
+	["gemini", () => new GeminiRuntime()],
 ]);
 
 /**