@os-eco/overstory-cli 0.8.4 → 0.8.5

package/README.md

@@ -20,6 +20,7 @@ Requires [Bun](https://bun.sh) v1.0+, git, and tmux. At least one supported agen
 - [Codex](https://github.com/openai/codex) (`codex` CLI)
 - [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini` CLI)
 - [Sapling](https://github.com/jayminwest/sapling) (`sp` CLI)
+- [OpenCode](https://opencode.ai) (`opencode` CLI)
 
 ```bash
 bun install -g @os-eco/overstory-cli
@@ -282,7 +283,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, Gemini, Sapling)
+    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini, Sapling, OpenCode)
     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.8.4",
+	"version": "0.8.5",
 	"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

@@ -551,13 +551,17 @@ describe("resolveModel", () => {
 
 	test("returns manifest model when no config override", () => {
 		const config = makeConfig();
-		expect(resolveModel(config, baseManifest, "coordinator", "haiku")).toEqual({ model: "opus" });
+		expect(resolveModel(config, baseManifest, "coordinator", "haiku")).toEqual({
+			model: "opus",
+			isExplicitOverride: false,
+		});
 	});
 
 	test("config override takes precedence over manifest", () => {
 		const config = makeConfig({ coordinator: "sonnet" });
 		expect(resolveModel(config, baseManifest, "coordinator", "haiku")).toEqual({
 			model: "sonnet",
+			isExplicitOverride: true,
 		});
 	});
 
@@ -565,12 +569,16 @@ describe("resolveModel", () => {
 		const config = makeConfig();
 		expect(resolveModel(config, baseManifest, "unknown-role", "haiku")).toEqual({
 			model: "haiku",
+			isExplicitOverride: false,
 		});
 	});
 
 	test("config override works for roles not in manifest", () => {
 		const config = makeConfig({ supervisor: "opus" });
-		expect(resolveModel(config, baseManifest, "supervisor", "sonnet")).toEqual({ model: "opus" });
+		expect(resolveModel(config, baseManifest, "supervisor", "sonnet")).toEqual({
+			model: "opus",
+			isExplicitOverride: true,
+		});
 	});
 
 	test("returns gateway env for provider-prefixed model", () => {
@@ -592,6 +600,7 @@ describe("resolveModel", () => {
 				ANTHROPIC_API_KEY: "",
 				ANTHROPIC_DEFAULT_SONNET_MODEL: "openai/gpt-5.3",
 			},
+			isExplicitOverride: true,
 		});
 	});
 
@@ -618,6 +627,7 @@ describe("resolveModel", () => {
 					ANTHROPIC_DEFAULT_SONNET_MODEL: "openai/gpt-5.3",
 					ANTHROPIC_AUTH_TOKEN: "test-token-123",
 				},
+				isExplicitOverride: true,
 			});
 		} finally {
 			if (savedEnv === undefined) {
@@ -631,7 +641,7 @@ describe("resolveModel", () => {
 	test("unknown provider falls through to model as-is", () => {
 		const config = makeConfig({ coordinator: "unknown-provider/some-model" });
 		const result = resolveModel(config, baseManifest, "coordinator", "opus");
-		expect(result).toEqual({ model: "unknown-provider/some-model" });
+		expect(result).toEqual({ model: "unknown-provider/some-model", isExplicitOverride: true });
 	});
 
 	test("native provider returns model string without env", () => {
@@ -640,7 +650,7 @@ describe("resolveModel", () => {
 			{ "native-gw": { type: "native" } },
 		);
 		const result = resolveModel(config, baseManifest, "coordinator", "opus");
-		expect(result).toEqual({ model: "native-gw/claude-3-5-sonnet" });
+		expect(result).toEqual({ model: "native-gw/claude-3-5-sonnet", isExplicitOverride: true });
 	});
 
 	test("handles deeply nested model ID (slashes in model name)", () => {
@@ -676,6 +686,18 @@ describe("resolveModel", () => {
 		expect(result.model).toBe("sonnet");
 		expect(result.env?.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe("org/model/version");
 	});
+
+	test("resolveModel sets isExplicitOverride true when config.models has override", () => {
+		const config = makeConfig({ builder: "opus" });
+		const result = resolveModel(config, baseManifest, "builder", "haiku");
+		expect(result.isExplicitOverride).toBe(true);
+	});
+
+	test("resolveModel sets isExplicitOverride false when using manifest default", () => {
+		const config = makeConfig();
+		const result = resolveModel(config, baseManifest, "coordinator", "haiku");
+		expect(result.isExplicitOverride).toBe(false);
+	});
 });
 
 describe("expandAliasFromEnv", () => {
@@ -783,7 +805,10 @@ describe("resolveModel env var expansion", () => {
 		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" });
+			expect(result).toEqual({
+				model: "us.anthropic.claude-3-5-haiku-20241022-v1:0",
+				isExplicitOverride: false,
+			});
 		} finally {
 			if (saved === undefined) {
 				delete process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL;
@@ -798,7 +823,7 @@ describe("resolveModel env var expansion", () => {
 		delete process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL;
 		try {
 			const result = resolveModel(makeConfig(), baseManifest, "scout", "sonnet");
-			expect(result).toEqual({ model: "haiku" });
+			expect(result).toEqual({ model: "haiku", isExplicitOverride: false });
 		} finally {
 			if (saved !== undefined) {
 				process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL = saved;
@@ -813,7 +838,7 @@ describe("resolveModel env var expansion", () => {
 			// 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" });
+			expect(result).toEqual({ model: "claude-3-5-sonnet-20241022", isExplicitOverride: true });
 		} finally {
 			if (saved === undefined) {
 				delete process.env.ANTHROPIC_DEFAULT_SONNET_MODEL;
@@ -829,7 +854,7 @@ describe("resolveModel env var expansion", () => {
 		try {
 			const config = makeConfig({ scout: "opus" });
 			const result = resolveModel(config, baseManifest, "scout", "haiku");
-			expect(result).toEqual({ model: "bedrock-opus-id" });
+			expect(result).toEqual({ model: "bedrock-opus-id", isExplicitOverride: true });
 		} finally {
 			if (saved === undefined) {
 				delete process.env.ANTHROPIC_DEFAULT_OPUS_MODEL;

package/src/agents/manifest.ts

@@ -353,10 +353,11 @@ export function resolveModel(
 ): ResolvedModel {
 	const configModel = config.models[role];
 	const rawModel = configModel ?? manifest.agents[role]?.model ?? fallback;
+	const isExplicitOverride = configModel !== undefined;
 
 	// Simple alias — expand via env var if set (e.g. ANTHROPIC_DEFAULT_SONNET_MODEL)
 	if (MODEL_ALIASES.has(rawModel)) {
-		return { model: expandAliasFromEnv(rawModel) };
+		return { model: expandAliasFromEnv(rawModel), isExplicitOverride };
 	}
 
 	// Provider-prefixed: split on first "/" to get provider name and model ID
@@ -366,10 +367,10 @@ export function resolveModel(
 		const modelId = rawModel.substring(slashIdx + 1);
 		const providerEnv = resolveProviderEnv(providerName, modelId, config.providers);
 		if (providerEnv) {
-			return { model: DEFAULT_GATEWAY_ALIAS, env: providerEnv };
+			return { model: DEFAULT_GATEWAY_ALIAS, env: providerEnv, isExplicitOverride };
 		}
 	}
 
 	// Unknown format — return as-is (may be a direct model string)
-	return { model: rawModel };
+	return { model: rawModel, isExplicitOverride };
 }

package/src/commands/inspect.test.ts

@@ -9,7 +9,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtemp } from "node:fs/promises";
+import { mkdir, mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { ValidationError } from "../errors.ts";
@@ -672,6 +672,7 @@ describe("inspectCommand", () => {
 				toolStats: [],
 				tokenUsage: null,
 				tmuxOutput: null,
+				headlessTurnInfo: null,
 			};
 
 			printInspectData(data);
@@ -710,6 +711,7 @@ describe("inspectCommand", () => {
 				toolStats: [],
 				tokenUsage: null,
 				tmuxOutput: "[Headless agent — showing recent tool events]",
+				headlessTurnInfo: null,
 			};
 
 			printInspectData(data);
@@ -720,6 +722,401 @@ describe("inspectCommand", () => {
 		});
 	});
 
+	// === stdout.log fallback (headless agents) ===
+
+	describe("stdout.log fallback", () => {
+		/** Create a headless session in SessionStore and return the overstoryDir. */
+		async function setupHeadlessSession(
+			agentName: string,
+			worktreePathVal = "/tmp/wt",
+		): Promise<string> {
+			const overstoryDir = join(tempDir, ".overstory");
+			const sessionsDbPath = join(overstoryDir, "sessions.db");
+			const store = createSessionStore(sessionsDbPath);
+			store.upsert({
+				id: `sess-${agentName}`,
+				agentName,
+				capability: "builder",
+				worktreePath: worktreePathVal,
+				branchName: `overstory/headless/${agentName}`,
+				taskId: "overstory-h10",
+				tmuxSession: "", // headless
+				state: "working",
+				pid: process.pid,
+				parentAgent: null,
+				depth: 0,
+				runId: null,
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			});
+			store.close();
+			return overstoryDir;
+		}
+
+		/** Write NDJSON events to stdout.log in the agent's log dir. */
+		async function writeStdoutLog(
+			overstoryDir: string,
+			agentName: string,
+			events: Record<string, unknown>[],
+		): Promise<void> {
+			const logDir = join(overstoryDir, "logs", agentName, "2026-03-05T14-30-00-000Z");
+			await mkdir(logDir, { recursive: true });
+			const ndjson = `${events.map((e) => JSON.stringify(e)).join("\n")}\n`;
+			await Bun.write(join(logDir, "stdout.log"), ndjson);
+		}
+
+		test("populates recentToolCalls from stdout.log when events.db is empty", async () => {
+			const overstoryDir = await setupHeadlessSession("stdout-tools");
+			await writeStdoutLog(overstoryDir, "stdout-tools", [
+				{
+					type: "tool_start",
+					timestamp: "2026-03-05T14:30:01.000Z",
+					toolName: "Read",
+					argsSummary: "src/index.ts",
+				},
+				{
+					type: "tool_end",
+					timestamp: "2026-03-05T14:30:01.050Z",
+					toolName: "Read",
+					success: true,
+					durationMs: 50,
+				},
+				{
+					type: "tool_start",
+					timestamp: "2026-03-05T14:30:02.000Z",
+					toolName: "Edit",
+					argsSummary: "src/commands/inspect.ts",
+				},
+				{
+					type: "tool_end",
+					timestamp: "2026-03-05T14:30:02.200Z",
+					toolName: "Edit",
+					success: true,
+					durationMs: 200,
+				},
+			]);
+
+			const data = await gatherInspectData(tempDir, "stdout-tools", { noTmux: true });
+
+			expect(data.recentToolCalls.length).toBe(2);
+			expect(data.recentToolCalls[0]?.toolName).toBe("Read");
+			expect(data.recentToolCalls[0]?.durationMs).toBe(50);
+			expect(data.recentToolCalls[0]?.args).toBe("src/index.ts");
+			expect(data.recentToolCalls[1]?.toolName).toBe("Edit");
+			expect(data.recentToolCalls[1]?.durationMs).toBe(200);
+		});
+
+		test("populates tokenUsage from turn_end events when metrics.db is absent", async () => {
+			const overstoryDir = await setupHeadlessSession("stdout-tokens");
+			await writeStdoutLog(overstoryDir, "stdout-tokens", [
+				{
+					type: "turn_start",
+					timestamp: "2026-03-05T14:30:00.000Z",
+					turn: 1,
+				},
+				{
+					type: "turn_end",
+					timestamp: "2026-03-05T14:30:05.000Z",
+					inputTokens: 1000,
+					outputTokens: 500,
+					cacheReadTokens: 200,
+					model: "claude-sonnet-4-6",
+					contextUtilization: 0.3,
+				},
+				{
+					type: "turn_start",
+					timestamp: "2026-03-05T14:30:06.000Z",
+					turn: 2,
+				},
+				{
+					type: "turn_end",
+					timestamp: "2026-03-05T14:30:10.000Z",
+					inputTokens: 800,
+					outputTokens: 300,
+					cacheReadTokens: 150,
+					model: "claude-sonnet-4-6",
+					contextUtilization: 0.45,
+				},
+			]);
+
+			const data = await gatherInspectData(tempDir, "stdout-tokens", { noTmux: true });
+
+			// Token usage should be cumulative across turn_end events
+			expect(data.tokenUsage).not.toBeNull();
+			expect(data.tokenUsage?.inputTokens).toBe(1800);
+			expect(data.tokenUsage?.outputTokens).toBe(800);
+			expect(data.tokenUsage?.cacheReadTokens).toBe(350);
+			expect(data.tokenUsage?.modelUsed).toBe("claude-sonnet-4-6");
+			expect(data.tokenUsage?.cacheCreationTokens).toBe(0);
+			expect(data.tokenUsage?.estimatedCostUsd).toBeNull();
+		});
+
+		test("populates headlessTurnInfo with turn number, context utilization, and isMidTool", async () => {
+			const overstoryDir = await setupHeadlessSession("stdout-turn-info");
+			await writeStdoutLog(overstoryDir, "stdout-turn-info", [
+				{
+					type: "turn_start",
+					timestamp: "2026-03-05T14:30:00.000Z",
+					turn: 3,
+				},
+				{
+					type: "tool_start",
+					timestamp: "2026-03-05T14:30:01.000Z",
+					toolName: "Bash",
+					argsSummary: "bun test",
+				},
+				// No tool_end — still mid-tool
+			]);
+
+			const data = await gatherInspectData(tempDir, "stdout-turn-info", { noTmux: true });
+
+			expect(data.headlessTurnInfo).not.toBeNull();
+			expect(data.headlessTurnInfo?.currentTurn).toBe(3);
+			expect(data.headlessTurnInfo?.isMidTool).toBe(true);
+		});
+
+		test("isMidTool is false when last event is not tool_start", async () => {
+			const overstoryDir = await setupHeadlessSession("stdout-between-turns");
+			await writeStdoutLog(overstoryDir, "stdout-between-turns", [
+				{
+					type: "turn_start",
+					timestamp: "2026-03-05T14:30:00.000Z",
+					turn: 2,
+				},
+				{
+					type: "turn_end",
+					timestamp: "2026-03-05T14:30:05.000Z",
+					inputTokens: 500,
+					outputTokens: 200,
+					cacheReadTokens: 0,
+					model: "claude-sonnet-4-6",
+					contextUtilization: 0.2,
+				},
+			]);
+
+			const data = await gatherInspectData(tempDir, "stdout-between-turns", { noTmux: true });
+
+			expect(data.headlessTurnInfo?.isMidTool).toBe(false);
+			expect(data.headlessTurnInfo?.contextUtilization).toBeCloseTo(0.2);
+		});
+
+		test("does not overwrite tokenUsage from metrics.db with stdout.log data", async () => {
+			const overstoryDir = await setupHeadlessSession("stdout-no-override");
+			const metricsDbPath = join(overstoryDir, "metrics.db");
+
+			// Metrics DB has authoritative data
+			const metricsStore = createMetricsStore(metricsDbPath);
+			metricsStore.recordSession(
+				makeMetrics({
+					agentName: "stdout-no-override",
+					inputTokens: 9999,
+					outputTokens: 8888,
+					modelUsed: "claude-opus-4-6",
+				}),
+			);
+			metricsStore.close();
+
+			// stdout.log also has token data
+			await writeStdoutLog(overstoryDir, "stdout-no-override", [
+				{
+					type: "turn_end",
+					timestamp: "2026-03-05T14:30:05.000Z",
+					inputTokens: 100,
+					outputTokens: 50,
+					cacheReadTokens: 0,
+					model: "claude-sonnet-4-6",
+					contextUtilization: 0.1,
+				},
+			]);
+
+			const data = await gatherInspectData(tempDir, "stdout-no-override", { noTmux: true });
+
+			// metrics.db data wins
+			expect(data.tokenUsage?.inputTokens).toBe(9999);
+			expect(data.tokenUsage?.modelUsed).toBe("claude-opus-4-6");
+		});
+
+		test("gracefully handles missing stdout.log", async () => {
+			const overstoryDir = await setupHeadlessSession("stdout-missing");
+			// Create log dir but no stdout.log inside it
+			await mkdir(join(overstoryDir, "logs", "stdout-missing", "2026-03-05T14-30-00-000Z"), {
+				recursive: true,
+			});
+
+			const data = await gatherInspectData(tempDir, "stdout-missing", { noTmux: true });
+
+			expect(data.recentToolCalls).toEqual([]);
+			expect(data.tokenUsage).toBeNull();
+			expect(data.headlessTurnInfo).toBeNull();
+		});
+
+		test("gracefully handles no log dir at all", async () => {
+			await setupHeadlessSession("stdout-no-log-dir");
+			// Don't create any log dir
+
+			const data = await gatherInspectData(tempDir, "stdout-no-log-dir", { noTmux: true });
+
+			expect(data.recentToolCalls).toEqual([]);
+			expect(data.headlessTurnInfo).toBeNull();
+		});
+
+		test("respects limit when populating recentToolCalls from stdout.log", async () => {
+			const overstoryDir = await setupHeadlessSession("stdout-limit");
+			const events: Record<string, unknown>[] = [];
+			for (let i = 0; i < 10; i++) {
+				events.push({
+					type: "tool_start",
+					timestamp: `2026-03-05T14:30:0${i}.000Z`,
+					toolName: "Read",
+					argsSummary: `src/file${i}.ts`,
+				});
+				events.push({
+					type: "tool_end",
+					timestamp: `2026-03-05T14:30:0${i}.050Z`,
+					toolName: "Read",
+					success: true,
+					durationMs: 50,
+				});
+			}
+			await writeStdoutLog(overstoryDir, "stdout-limit", events);
+
+			const data = await gatherInspectData(tempDir, "stdout-limit", {
+				noTmux: true,
+				limit: 3,
+			});
+
+			expect(data.recentToolCalls.length).toBe(3);
+		});
+
+		test("printInspectData shows Turn Progress section when headlessTurnInfo is set", () => {
+			const data = {
+				session: {
+					id: "sess-tp",
+					agentName: "headless-turn-progress",
+					capability: "builder",
+					worktreePath: "/tmp/wt",
+					branchName: "overstory/headless/tp",
+					taskId: "overstory-tp",
+					tmuxSession: "",
+					state: "working" as const,
+					pid: 12345,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+				timeSinceLastActivity: 1000,
+				recentToolCalls: [],
+				currentFile: null,
+				toolStats: [],
+				tokenUsage: null,
+				tmuxOutput: null,
+				headlessTurnInfo: {
+					currentTurn: 5,
+					contextUtilization: 0.625,
+					isMidTool: false,
+				},
+			};
+
+			printInspectData(data);
+
+			const out = output();
+			expect(out).toContain("Turn Progress");
+			expect(out).toContain("5");
+			expect(out).toContain("62.5%");
+			expect(out).toContain("between turns");
+		});
+
+		test("printInspectData shows executing tool status when isMidTool is true", () => {
+			const data = {
+				session: {
+					id: "sess-mid",
+					agentName: "headless-mid-tool",
+					capability: "builder",
+					worktreePath: "/tmp/wt",
+					branchName: "overstory/headless/mid",
+					taskId: "overstory-mid",
+					tmuxSession: "",
+					state: "working" as const,
+					pid: 12345,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+				timeSinceLastActivity: 500,
+				recentToolCalls: [],
+				currentFile: null,
+				toolStats: [],
+				tokenUsage: null,
+				tmuxOutput: null,
+				headlessTurnInfo: {
+					currentTurn: 2,
+					contextUtilization: null,
+					isMidTool: true,
+				},
+			};
+
+			printInspectData(data);
+
+			const out = output();
+			expect(out).toContain("Turn Progress");
+			expect(out).toContain("executing tool");
+		});
+
+		test("uses latest log dir when multiple exist", async () => {
+			const overstoryDir = await setupHeadlessSession("stdout-multi-dir");
+			const agentLogsDir = join(overstoryDir, "logs", "stdout-multi-dir");
+
+			// Create two log dirs — the later one has the important data
+			const oldDir = join(agentLogsDir, "2026-03-05T10-00-00-000Z");
+			const newDir = join(agentLogsDir, "2026-03-05T14-30-00-000Z");
+			await mkdir(oldDir, { recursive: true });
+			await mkdir(newDir, { recursive: true });
+
+			// Old dir: no useful data
+			await Bun.write(join(oldDir, "stdout.log"), "");
+
+			// New dir: has turn data
+			const events = [
+				{
+					type: "turn_start",
+					timestamp: "2026-03-05T14:30:00.000Z",
+					turn: 7,
+				},
+				{
+					type: "turn_end",
+					timestamp: "2026-03-05T14:30:05.000Z",
+					inputTokens: 2000,
+					outputTokens: 700,
+					cacheReadTokens: 300,
+					model: "claude-sonnet-4-6",
+					contextUtilization: 0.55,
+				},
+			];
+			await Bun.write(
+				join(newDir, "stdout.log"),
+				`${events.map((e) => JSON.stringify(e)).join("\n")}\n`,
+			);
+
+			const data = await gatherInspectData(tempDir, "stdout-multi-dir", { noTmux: true });
+
+			expect(data.headlessTurnInfo?.currentTurn).toBe(7);
+			expect(data.tokenUsage?.inputTokens).toBe(2000);
+		});
+	});
+
 	// === Human-readable output ===
 
 	describe("human-readable output", () => {