@os-eco/overstory-cli 0.8.4 → 0.8.6

package/src/runtimes/pi.ts

@@ -179,10 +179,12 @@ export class PiRuntime implements AgentRuntime {
 	/**
 	 * Parse a Pi transcript JSONL file into normalized token usage.
 	 *
-	 * Pi JSONL format differs from Claude Code:
-	 * - Token counts are in `message_end` events with TOP-LEVEL `inputTokens` / `outputTokens`
-	 *   (not nested under message.usage)
-	 * - Model identity comes from `model_change` events with a `model` field
+	 * Pi JSONL format (version 3):
+	 * - Session metadata: `{ type: "session", version: 3, id, cwd }`
+	 * - Model identity: `{ type: "model_change", provider, modelId }`
+	 * - Token usage: on `{ type: "message" }` events where `message.role === "assistant"`,
+	 *   nested under `message.usage`: `{ input, output, cacheRead, cacheWrite, totalTokens, cost }`
+	 * - Cost data: `message.usage.cost.total` (USD)
 	 *
 	 * Returns null if the file does not exist or cannot be parsed.
 	 *
@@ -212,18 +214,49 @@ export class PiRuntime implements AgentRuntime {
 					continue;
 				}
 
+				// Model identity from model_change events.
+				if (entry.type === "model_change") {
+					if (typeof entry.modelId === "string") {
+						model = entry.modelId;
+					} else if (typeof entry.model === "string") {
+						model = entry.model;
+					}
+				}
+
+				// Token usage from assistant message events.
+				// Pi v3 format: message.usage.input / message.usage.output
+				if (entry.type === "message") {
+					const msg = entry.message as Record<string, unknown> | undefined;
+					if (msg?.role === "assistant") {
+						const usage = msg.usage as Record<string, unknown> | undefined;
+						if (usage) {
+							if (typeof usage.input === "number") {
+								inputTokens += usage.input;
+							}
+							if (typeof usage.output === "number") {
+								outputTokens += usage.output;
+							}
+							// Also count cache tokens toward input for compatibility.
+							if (typeof usage.cacheRead === "number") {
+								inputTokens += usage.cacheRead;
+							}
+						}
+
+						// Capture model from message if model_change was missed.
+						if (typeof msg.model === "string" && model === "") {
+							model = msg.model;
+						}
+					}
+				}
+
+				// Fallback: message_end events (older Pi versions).
 				if (entry.type === "message_end") {
-					// Pi top-level token fields (not nested under message.usage).
 					if (typeof entry.inputTokens === "number") {
 						inputTokens += entry.inputTokens;
 					}
 					if (typeof entry.outputTokens === "number") {
 						outputTokens += entry.outputTokens;
 					}
-				} else if (entry.type === "model_change") {
-					if (typeof entry.model === "string") {
-						model = entry.model;
-					}
 				}
 			}
 
@@ -246,8 +279,24 @@ export class PiRuntime implements AgentRuntime {
 		return model.env ?? {};
 	}
 
-	/** Pi uses RPC — no transcript files. */
-	getTranscriptDir(_projectRoot: string): string | null {
-		return null;
+	/**
+	 * Return the directory containing Pi session transcript files.
+	 *
+	 * Pi stores JSONL transcripts in `~/.pi/agent/sessions/{encoded-project-path}/`.
+	 * The project path is encoded by replacing path separators with `--` and
+	 * prefixing/suffixing with `--`.
+	 *
+	 * Example: `/home/user/project` → `~/.pi/agent/sessions/--home-user-project--/`
+	 *
+	 * @param projectRoot - Absolute path to the project root
+	 * @returns Absolute path to the transcript directory
+	 */
+	getTranscriptDir(projectRoot: string): string | null {
+		const home = process.env.HOME ?? process.env.USERPROFILE;
+		if (!home) return null;
+
+		// Pi encodes the project path: replace separators with dashes, wrap with --
+		const encoded = `--${projectRoot.replace(/[\\/]/g, "-").replace(/:/g, "")}--`;
+		return join(home, ".pi", "agent", "sessions", encoded);
 	}
 }

package/src/runtimes/registry.test.ts

@@ -4,6 +4,7 @@ import { ClaudeRuntime } from "./claude.ts";
 import { CodexRuntime } from "./codex.ts";
 import { CopilotRuntime } from "./copilot.ts";
 import { GeminiRuntime } from "./gemini.ts";
+import { OpenCodeRuntime } from "./opencode.ts";
 import { PiRuntime } from "./pi.ts";
 import { getRuntime } from "./registry.ts";
 
@@ -22,7 +23,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, gemini, sapling',
+			'Unknown runtime: "unknown-runtime". Available: claude, codex, pi, copilot, gemini, sapling, opencode',
 		);
 	});
 
@@ -118,6 +119,25 @@ describe("getRuntime", () => {
 		expect(runtime.id).toBe("gemini");
 	});
 
+	it("returns OpenCodeRuntime when name is 'opencode'", () => {
+		const runtime = getRuntime("opencode");
+		expect(runtime).toBeInstanceOf(OpenCodeRuntime);
+		expect(runtime.id).toBe("opencode");
+	});
+
+	it("uses config.runtime.default 'opencode' when name is omitted", () => {
+		const config = { runtime: { default: "opencode" } } as OverstoryConfig;
+		const runtime = getRuntime(undefined, config);
+		expect(runtime).toBeInstanceOf(OpenCodeRuntime);
+		expect(runtime.id).toBe("opencode");
+	});
+
+	it("opencode runtime returns a new instance on each call", () => {
+		const a = getRuntime("opencode");
+		const b = getRuntime("opencode");
+		expect(a).not.toBe(b);
+	});
+
 	describe("capability routing", () => {
 		it("resolves capability-specific runtime from config", () => {
 			const config = {

package/src/runtimes/registry.ts

@@ -6,6 +6,7 @@ import { ClaudeRuntime } from "./claude.ts";
 import { CodexRuntime } from "./codex.ts";
 import { CopilotRuntime } from "./copilot.ts";
 import { GeminiRuntime } from "./gemini.ts";
+import { OpenCodeRuntime } from "./opencode.ts";
 import { PiRuntime } from "./pi.ts";
 import { SaplingRuntime } from "./sapling.ts";
 import type { AgentRuntime } from "./types.ts";
@@ -18,6 +19,7 @@ const runtimes = new Map<string, () => AgentRuntime>([
 	["copilot", () => new CopilotRuntime()],
 	["gemini", () => new GeminiRuntime()],
 	["sapling", () => new SaplingRuntime()],
+	["opencode", () => new OpenCodeRuntime()],
 ]);
 
 /**
@@ -37,6 +39,7 @@ export function getAllRuntimes(): AgentRuntime[] {
 		new CopilotRuntime(),
 		new GeminiRuntime(),
 		new SaplingRuntime(),
+		new OpenCodeRuntime(),
 	];
 }
 

package/src/runtimes/sapling.test.ts

@@ -365,6 +365,21 @@ describe("SaplingRuntime", () => {
 			const argv = runtime.buildDirectSpawn(opts);
 			expect(argv[3]).toBe("claude-sonnet-4-6");
 		});
+
+		test("omits --model when model is undefined (sapling uses own config)", () => {
+			const opts: DirectSpawnOpts = {
+				cwd: "/project/.overstory/worktrees/builder-1",
+				env: {},
+				instructionPath: "/project/.overstory/worktrees/builder-1/SAPLING.md",
+			};
+			const argv = runtime.buildDirectSpawn(opts);
+			expect(argv).not.toContain("--model");
+			expect(argv[0]).toBe("sp");
+			expect(argv[1]).toBe("run");
+			expect(argv).toContain("--json");
+			expect(argv).toContain("--cwd");
+			expect(argv).toContain("--system-prompt-file");
+		});
 	});
 
 	describe("buildEnv", () => {
@@ -464,6 +479,21 @@ describe("SaplingRuntime", () => {
 			expect(env.ANTHROPIC_DEFAULT_HAIKU_MODEL).toBe("custom/haiku-gateway-model");
 		});
 
+		test("clears ANTHROPIC_API_KEY by default (no gateway)", () => {
+			const model: ResolvedModel = { model: "sonnet" };
+			const env = runtime.buildEnv(model);
+			expect(env.ANTHROPIC_API_KEY).toBe("");
+		});
+
+		test("buildEnv sets ANTHROPIC_API_KEY from gateway provider ANTHROPIC_AUTH_TOKEN", () => {
+			const model: ResolvedModel = {
+				model: "sonnet",
+				env: { ANTHROPIC_AUTH_TOKEN: "sk-gw-test" },
+			};
+			const env = runtime.buildEnv(model);
+			expect(env.ANTHROPIC_API_KEY).toBe("sk-gw-test");
+		});
+
 		test("does NOT forward non-model env vars from model.env", () => {
 			const model: ResolvedModel = {
 				model: "sonnet",

package/src/runtimes/sapling.ts

@@ -424,39 +424,39 @@ export class SaplingRuntime implements AgentRuntime {
 	 * @returns Argv array for Bun.spawn — do not shell-interpolate
 	 */
 	buildDirectSpawn(opts: DirectSpawnOpts): string[] {
-		// Resolve the actual model name: if this is an alias (e.g. "sonnet") routed
-		// through a gateway, the real model ID is in the env vars. Sapling passes
-		// --model directly to the SDK, so it needs the actual model ID, not the alias.
-		let model = opts.model;
-		let resolved = false;
-		if (opts.env) {
-			const aliasKey = `ANTHROPIC_DEFAULT_${model.toUpperCase()}_MODEL`;
-			const envResolved = opts.env[aliasKey];
-			if (envResolved) {
-				model = envResolved;
-				resolved = true;
+		const argv = ["sp", "run"];
+		if (opts.model !== undefined) {
+			// Resolve the actual model name: if this is an alias (e.g. "sonnet") routed
+			// through a gateway, the real model ID is in the env vars. Sapling passes
+			// --model directly to the SDK, so it needs the actual model ID, not the alias.
+			let model = opts.model;
+			let resolved = false;
+			if (opts.env) {
+				const aliasKey = `ANTHROPIC_DEFAULT_${model.toUpperCase()}_MODEL`;
+				const envResolved = opts.env[aliasKey];
+				if (envResolved) {
+					model = envResolved;
+					resolved = true;
+				}
 			}
-		}
-		// Fallback: bare aliases (haiku/sonnet/opus) with no gateway env var → concrete model ID.
-		if (!resolved) {
-			const fallback = SAPLING_ALIAS_FALLBACKS[model];
-			if (fallback !== undefined) {
-				model = fallback;
+			// Fallback: bare aliases (haiku/sonnet/opus) with no gateway env var → concrete model ID.
+			if (!resolved) {
+				const fallback = SAPLING_ALIAS_FALLBACKS[model];
+				if (fallback !== undefined) {
+					model = fallback;
+				}
 			}
+			argv.push("--model", model);
 		}
-
-		return [
-			"sp",
-			"run",
-			"--model",
-			model,
+		argv.push(
 			"--json",
 			"--cwd",
 			opts.cwd,
 			"--system-prompt-file",
 			opts.instructionPath,
 			"Read SAPLING.md for your task assignment and begin immediately.",
-		];
+		);
+		return argv;
 	}
 
 	/**
@@ -667,6 +667,9 @@ export class SaplingRuntime implements AgentRuntime {
 			CLAUDECODE: "",
 			CLAUDE_CODE_SSE_PORT: "",
 			CLAUDE_CODE_ENTRYPOINT: "",
+			// Clear ANTHROPIC_API_KEY so the parent session's key doesn't leak
+			// into the sapling subprocess. Gateway providers re-set this below.
+			ANTHROPIC_API_KEY: "",
 		};
 
 		const providerEnv = model.env ?? {};

package/src/runtimes/types.ts

@@ -118,8 +118,8 @@ export interface DirectSpawnOpts {
 	cwd: string;
 	/** Environment variables for the subprocess. */
 	env: Record<string, string>;
-	/** Model ref (alias or provider-qualified). */
-	model: string;
+	/** Model ref (alias or provider-qualified). When undefined, the runtime omits --model and lets the agent use its own config. */
+	model?: string;
 	/** Path to the instruction/overlay file for this agent. */
 	instructionPath: string;
 }

package/src/types.ts

@@ -20,6 +20,8 @@ export interface ProviderConfig {
 export interface ResolvedModel {
 	model: string;
 	env?: Record<string, string>;
+	/** True when the model was explicitly set via config.models[capability]. */
+	isExplicitOverride?: boolean;
 }
 
 /** Configuration for the Pi runtime's model alias expansion. */
@@ -37,6 +39,19 @@ export type TaskTrackerBackend = "auto" | "seeds" | "beads";
 
 // === Project Configuration ===
 
+/**
+ * Conditions that trigger automatic coordinator shutdown.
+ * All triggers default to false for backward compatibility.
+ */
+export interface CoordinatorExitTriggers {
+	/** Exit when all spawned agents have completed and their branches have been merged. */
+	allAgentsDone: boolean;
+	/** Exit when the task tracker reports no unblocked work (sd/bd ready returns empty). */
+	taskTrackerEmpty: boolean;
+	/** Exit when a typed shutdown mail is received from an external caller (e.g., greenhouse). */
+	onShutdownSignal: boolean;
+}
+
 /** A single quality gate command that agents must pass before reporting completion. */
 export interface QualityGate {
 	/** Display name shown in the overlay (e.g., "Tests"). */
@@ -94,6 +109,10 @@ export interface OverstoryConfig {
 		verbose: boolean;
 		redactSecrets: boolean;
 	};
+	coordinator?: {
+		/** Conditions that trigger automatic coordinator shutdown. */
+		exitTriggers: CoordinatorExitTriggers;
+	};
 	runtime?: {
 		/** Default runtime adapter name (default: "claude"). */
 		default: string;

package/src/watchdog/daemon.test.ts

@@ -1977,3 +1977,260 @@ describe("buildCompletionMessage", () => {
 		expect(msg).toContain("3");
 	});
 });
+
+// === Bug fix tests: headless agent kill blast radius + stale detection ===
+
+describe("headless agent kill blast radius fix (Bug 1)", () => {
+	/**
+	 * Track PID kill calls without spawning real processes.
+	 * Also surfaces killTree calls so tests can assert on them.
+	 */
+	function processTracker(): {
+		isAlive: (pid: number) => boolean;
+		killTree: (pid: number) => Promise<void>;
+		killed: number[];
+	} {
+		const killed: number[] = [];
+		return {
+			isAlive: (pid: number) => {
+				try {
+					process.kill(pid, 0);
+					return true;
+				} catch {
+					return false;
+				}
+			},
+			killTree: async (pid: number) => {
+				killed.push(pid);
+			},
+			killed,
+		};
+	}
+
+	test("headless agent at escalation level 3 kills PID, not tmux session", async () => {
+		const nudgeIntervalMs = 60_000;
+		// stalledSince is 4 intervals ago — expectedLevel = floor(4) = 4, clamped to MAX (3)
+		const stalledSince = new Date(Date.now() - 4 * nudgeIntervalMs).toISOString();
+		const staleActivity = new Date(Date.now() - THRESHOLDS.staleThresholdMs * 2).toISOString();
+
+		const session = makeSession({
+			agentName: "headless-stalled",
+			tmuxSession: "", // headless
+			pid: process.pid, // alive PID — ZFC won't trigger direct terminate
+			state: "stalled",
+			lastActivity: staleActivity,
+			escalationLevel: 2,
+			stalledSince,
+		});
+
+		writeSessionsToStore(tempRoot, [session]);
+
+		const proc = processTracker();
+		// tmux mock: isSessionAlive("") returns true — simulates prefix-match bug scenario
+		const tmuxMock = tmuxWithLiveness({ "": true });
+
+		await runDaemonTick({
+			root: tempRoot,
+			...THRESHOLDS,
+			nudgeIntervalMs,
+			tier1Enabled: false,
+			_tmux: tmuxMock,
+			_triage: triageAlways("extend"),
+			_process: proc,
+			_eventStore: null,
+			_recordFailure: async () => {},
+			_getConnection: () => undefined,
+			_removeConnection: () => {},
+			_tailerRegistry: new Map(),
+			_findLatestStdoutLog: async () => null,
+		});
+
+		// PID was killed via killTree, NOT via tmux killSession("")
+		expect(proc.killed).toContain(process.pid);
+		expect(tmuxMock.killed).not.toContain("");
+	});
+
+	test("headless agent direct terminate kills PID, not tmux", async () => {
+		// PID 999999 is virtually guaranteed not to exist — health check sees it as dead
+		const deadPid = 999999;
+		const session = makeSession({
+			agentName: "headless-dead-pid",
+			tmuxSession: "", // headless
+			pid: deadPid,
+			state: "working",
+			lastActivity: new Date().toISOString(),
+		});
+
+		writeSessionsToStore(tempRoot, [session]);
+
+		const proc = processTracker();
+		// tmux mock: isSessionAlive("") returns true — would kill everything without the fix
+		const tmuxMock = tmuxWithLiveness({ "": true });
+
+		await runDaemonTick({
+			root: tempRoot,
+			...THRESHOLDS,
+			_tmux: tmuxMock,
+			_triage: triageAlways("extend"),
+			_process: proc,
+			_eventStore: null,
+			_recordFailure: async () => {},
+			_getConnection: () => undefined,
+			_removeConnection: () => {},
+			_tailerRegistry: new Map(),
+			_findLatestStdoutLog: async () => null,
+		});
+
+		// Should have attempted PID kill, NOT tmux killSession("")
+		expect(proc.killed).toContain(deadPid);
+		expect(tmuxMock.killed).not.toContain("");
+	});
+
+	test("triage terminate on headless agent kills PID, not tmux", async () => {
+		const nudgeIntervalMs = 60_000;
+		// stalledSince is 2.5 intervals ago — expectedLevel = floor(2.5) = 2 → triage fires
+		const stalledSince = new Date(Date.now() - 2.5 * nudgeIntervalMs).toISOString();
+		const staleActivity = new Date(Date.now() - THRESHOLDS.staleThresholdMs * 2).toISOString();
+
+		const session = makeSession({
+			agentName: "headless-triage-terminate",
+			tmuxSession: "", // headless
+			pid: process.pid, // alive
+			state: "stalled",
+			lastActivity: staleActivity,
+			escalationLevel: 1,
+			stalledSince,
+		});
+
+		writeSessionsToStore(tempRoot, [session]);
+
+		const proc = processTracker();
+		const tmuxMock = tmuxWithLiveness({ "": true });
+
+		await runDaemonTick({
+			root: tempRoot,
+			...THRESHOLDS,
+			nudgeIntervalMs,
+			tier1Enabled: true,
+			_tmux: tmuxMock,
+			_triage: triageAlways("terminate"), // AI triage says terminate
+			_nudge: nudgeTracker().nudge,
+			_process: proc,
+			_eventStore: null,
+			_recordFailure: async () => {},
+			_getConnection: () => undefined,
+			_removeConnection: () => {},
+			_tailerRegistry: new Map(),
+			_findLatestStdoutLog: async () => null,
+		});
+
+		// Should have killed the PID, not the tmux session
+		expect(proc.killed).toContain(process.pid);
+		expect(tmuxMock.killed).not.toContain("");
+	});
+});
+
+describe("headless agent stale detection via events.db (Bug 2)", () => {
+	test("headless agent with recent events in events.db is not flagged stale", async () => {
+		const staleActivity = new Date(Date.now() - THRESHOLDS.staleThresholdMs * 2).toISOString();
+
+		const session = makeSession({
+			agentName: "headless-active",
+			tmuxSession: "", // headless
+			pid: process.pid, // alive
+			state: "working",
+			lastActivity: staleActivity, // stale — would trigger escalate without event fallback
+		});
+
+		writeSessionsToStore(tempRoot, [session]);
+
+		const eventsDbPath = join(tempRoot, ".overstory", "events.db");
+		const eventStore = createEventStore(eventsDbPath);
+
+		try {
+			// Insert a recent event for this agent (within the stale threshold window)
+			eventStore.insert({
+				runId: null,
+				agentName: "headless-active",
+				sessionId: null,
+				eventType: "tool_end",
+				toolName: "Read",
+				toolArgs: null,
+				toolDurationMs: 100,
+				level: "info",
+				data: null,
+			});
+
+			const checks: HealthCheck[] = [];
+
+			await runDaemonTick({
+				root: tempRoot,
+				...THRESHOLDS,
+				onHealthCheck: (c) => checks.push(c),
+				_tmux: tmuxAllAlive(),
+				_triage: triageAlways("extend"),
+				_process: { isAlive: () => true, killTree: async () => {} },
+				_eventStore: eventStore,
+				_recordFailure: async () => {},
+				_getConnection: () => undefined,
+				_removeConnection: () => {},
+				_tailerRegistry: new Map(),
+				_findLatestStdoutLog: async () => null,
+			});
+
+			// Recent events found — lastActivity was refreshed, agent is NOT stalled
+			expect(checks).toHaveLength(1);
+			expect(checks[0]?.action).toBe("none");
+			expect(checks[0]?.state).toBe("working");
+
+			const reloaded = readSessionsFromStore(tempRoot);
+			expect(reloaded[0]?.state).toBe("working");
+		} finally {
+			eventStore.close();
+		}
+	});
+
+	test("headless agent with no recent events IS flagged stale", async () => {
+		const staleActivity = new Date(Date.now() - THRESHOLDS.staleThresholdMs * 2).toISOString();
+
+		const session = makeSession({
+			agentName: "headless-silent",
+			tmuxSession: "", // headless
+			pid: process.pid, // alive
+			state: "working",
+			lastActivity: staleActivity, // stale
+		});
+
+		writeSessionsToStore(tempRoot, [session]);
+
+		const eventsDbPath = join(tempRoot, ".overstory", "events.db");
+		const eventStore = createEventStore(eventsDbPath);
+
+		try {
+			// No events inserted for this agent — event fallback finds nothing
+
+			const checks: HealthCheck[] = [];
+
+			await runDaemonTick({
+				root: tempRoot,
+				...THRESHOLDS,
+				onHealthCheck: (c) => checks.push(c),
+				_tmux: tmuxAllAlive(),
+				_triage: triageAlways("extend"),
+				_process: { isAlive: () => true, killTree: async () => {} },
+				_eventStore: eventStore,
+				_recordFailure: async () => {},
+				_getConnection: () => undefined,
+				_removeConnection: () => {},
+				_tailerRegistry: new Map(),
+				_findLatestStdoutLog: async () => null,
+			});
+
+			// No recent events — lastActivity stays stale, agent IS flagged stalled
+			expect(checks).toHaveLength(1);
+			expect(checks[0]?.action).toBe("escalate");
+		} finally {
+			eventStore.close();
+		}
+	});
+});