@os-eco/overstory-cli 0.7.6 → 0.7.8

package/README.md

@@ -17,6 +17,7 @@ Requires [Bun](https://bun.sh) v1.0+, git, and tmux. At least one supported agen
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude` CLI)
 - [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)
 
 ```bash
 bun install -g @os-eco/overstory-cli
@@ -79,7 +80,7 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 | Command | Description |
 |---------|-------------|
 | `ov init` | Initialize `.overstory/` and bootstrap os-eco tools (`--yes`, `--name`, `--tools`, `--skip-mulch`, `--skip-seeds`, `--skip-canopy`, `--skip-onboard`, `--json`) |
-| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--json`) |
+| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--base-branch`, `--json`) |
 | `ov stop <agent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |
 | `ov prime` | Load context for orchestrator/agent (`--agent`, `--compact`) |
 | `ov spec write <task-id>` | Write a task specification (`--body`) |
@@ -173,6 +174,7 @@ Overstory is runtime-agnostic. The `AgentRuntime` interface (`src/runtimes/types
 | Claude Code | `claude` | `settings.local.json` hooks | Stable |
 | 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 |
 
 ## How It Works
 
@@ -269,7 +271,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)
+    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex)
     tracker/                      Pluggable task tracker (beads + seeds backends)
     mulch/                        mulch client (programmatic API + CLI wrapper)
     e2e/                          End-to-end lifecycle tests
@@ -277,6 +279,106 @@ overstory/
   templates/                      Templates for overlays and hooks
 ```
 
+## Configuration
+
+### Gateway Providers
+
+Route agent API calls through custom gateway endpoints (z.ai, OpenRouter, self-hosted proxies). Configure providers in `.overstory/config.yaml`:
+
+```yaml
+providers:
+  anthropic:
+    type: native
+  zai:
+    type: gateway
+    baseUrl: https://api.z.ai/v1
+    authTokenEnv: ZAI_API_KEY
+  openrouter:
+    type: gateway
+    baseUrl: https://openrouter.ai/api/v1
+    authTokenEnv: OPENROUTER_API_KEY
+models:
+  builder: zai/claude-sonnet-4-6
+  scout: openrouter/openai/gpt-4o
+```
+
+**How it works:** Model refs use `provider/model-id` format. Overstory sets `ANTHROPIC_BASE_URL` to the gateway `baseUrl`, `ANTHROPIC_AUTH_TOKEN` from the env var named in `authTokenEnv`, and `ANTHROPIC_API_KEY=""` to prevent direct Anthropic calls. The agent receives `"sonnet"` as a model alias and Claude Code routes via env vars.
+
+**Environment variable notes:**
+- `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_API_KEY` are mutually exclusive per-agent
+- Gateway agents get `ANTHROPIC_API_KEY=""` and `ANTHROPIC_AUTH_TOKEN` from provider config
+- Direct Anthropic API calls (merge resolver, watchdog triage) still need `ANTHROPIC_API_KEY` in the orchestrator env
+
+**Validation:** `ov doctor --category providers` checks reachability, auth tokens, model-provider refs, and tool-use compatibility.
+
+**`ProviderConfig` fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `native` or `gateway` | Yes | Provider type |
+| `baseUrl` | string | Gateway only | API endpoint URL |
+| `authTokenEnv` | string | Gateway only | Env var name holding auth token |
+
+## Troubleshooting
+
+### Coordinator died during startup
+
+This error means the coordinator tmux session exited before the TUI became ready. The most common cause is slow shell initialization.
+
+**Step 1: Measure shell startup time**
+
+```bash
+time zsh -i -c exit   # For zsh
+time bash -i -c exit  # For bash
+```
+
+If startup takes more than 1 second, slow shell init is likely the cause.
+
+**Step 2: Common slow-startup causes**
+
+| Cause | Typical delay | Fix |
+|-------|---------------|-----|
+| oh-my-zsh with many plugins | 1-5s | Reduce plugins, switch to lighter framework (zinit with lazy loading) |
+| nvm (Node Version Manager) | 1-3s | Use `--no-use` + lazy-load nvm, or switch to fnm/volta |
+| pyenv init | 0.5-2s | Lazy-load pyenv |
+| rbenv init | 0.5-1s | Lazy-load rbenv |
+| starship prompt | 0.5-1s | Check starship timings |
+| conda auto-activate | 1-3s | `auto_activate_base: false` in `.condarc` |
+| Homebrew shellenv | 0.5-1s | Cache output instead of evaluating every shell start |
+
+**Step 3: Configure `shellInitDelayMs`** in `.overstory/config.yaml`:
+
+```yaml
+runtime:
+  shellInitDelayMs: 3000
+```
+
+- Default: `0` (no delay)
+- Typical values: `1000`–`5000` depending on shell startup time
+- Values above `30000` (30s) trigger a warning
+- Inserts a delay between tmux session creation and TUI readiness polling
+
+**Step 4: Optimization examples**
+
+Lazy-load nvm (add to `~/.zshrc` or `~/.bashrc`):
+
+```bash
+# Lazy-load nvm — only activates when you first call nvm/node/npm
+export NVM_DIR="$HOME/.nvm"
+nvm() { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; nvm "$@"; }
+node() { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; node "$@"; }
+npm()  { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; npm  "$@"; }
+npx()  { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; npx  "$@"; }
+```
+
+Reduce oh-my-zsh plugins (edit `~/.zshrc`):
+
+```bash
+# Before: plugins=(git zsh-autosuggestions zsh-syntax-highlighting node npm python ruby rbenv pyenv ...)
+# After: keep only what you use regularly
+plugins=(git)
+```
+
 ## Part of os-eco
 
 Overstory is part of the [os-eco](https://github.com/jayminwest/os-eco) AI agent tooling ecosystem.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.7.6",
+	"version": "0.7.8",
 	"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/commands/coordinator.test.ts

@@ -38,6 +38,7 @@ interface TmuxCallTracker {
 		env?: Record<string, string>;
 	}>;
 	isSessionAlive: Array<{ name: string; result: boolean }>;
+	checkSessionState: Array<{ name: string; result: "alive" | "dead" | "no_server" }>;
 	killSession: Array<{ name: string }>;
 	sendKeys: Array<{ name: string; keys: string }>;
 	waitForTuiReady: Array<{ name: string }>;
@@ -68,6 +69,7 @@ function makeFakeTmux(
 	options: {
 		waitForTuiReadyResult?: boolean;
 		ensureTmuxAvailableError?: Error;
+		checkSessionStateMap?: Record<string, "alive" | "dead" | "no_server">;
 	} = {},
 ): {
 	tmux: NonNullable<CoordinatorDeps["_tmux"]>;
@@ -76,6 +78,7 @@ function makeFakeTmux(
 	const calls: TmuxCallTracker = {
 		createSession: [],
 		isSessionAlive: [],
+		checkSessionState: [],
 		killSession: [],
 		sendKeys: [],
 		waitForTuiReady: [],
@@ -97,6 +100,13 @@ function makeFakeTmux(
 			calls.isSessionAlive.push({ name, result: alive });
 			return alive;
 		},
+		checkSessionState: async (name: string): Promise<"alive" | "dead" | "no_server"> => {
+			const stateMap = options.checkSessionStateMap ?? {};
+			// Default: derive from sessionAliveMap for backwards compat
+			const state = stateMap[name] ?? (sessionAliveMap[name] ? "alive" : "dead");
+			calls.checkSessionState.push({ name, result: state });
+			return state;
+		},
 		killSession: async (name: string): Promise<void> => {
 			calls.killSession.push({ name });
 		},
@@ -325,7 +335,11 @@ function makeDeps(
 	sessionAliveMap: Record<string, boolean> = {},
 	watchdogConfig?: { running?: boolean; startSuccess?: boolean; stopSuccess?: boolean },
 	monitorConfig?: { running?: boolean; startSuccess?: boolean; stopSuccess?: boolean },
-	tmuxOptions?: { waitForTuiReadyResult?: boolean; ensureTmuxAvailableError?: Error },
+	tmuxOptions?: {
+		waitForTuiReadyResult?: boolean;
+		ensureTmuxAvailableError?: Error;
+		checkSessionStateMap?: Record<string, "alive" | "dead" | "no_server">;
+	},
 ): {
 	deps: CoordinatorDeps;
 	calls: TmuxCallTracker;
@@ -606,7 +620,7 @@ describe("startCoordinator", () => {
 
 	test("rejects duplicate when coordinator is already running", async () => {
 		// Write an existing active coordinator session
-		const existing = makeCoordinatorSession({ state: "working" });
+		const existing = makeCoordinatorSession({ state: "working", pid: process.pid });
 		saveSessionsToDb([existing]);
 
 		// Mock tmux as alive for the existing session
@@ -623,6 +637,29 @@ describe("startCoordinator", () => {
 		}
 	});
 
+	test("rejects duplicate when pid is null but tmux session is alive", async () => {
+		// Session has null pid (e.g. migrated from older schema) but tmux is alive.
+		// Cannot prove it's a zombie without a pid, so treat as active.
+		const existing = makeCoordinatorSession({ state: "working", pid: null });
+		saveSessionsToDb([existing]);
+
+		const { deps } = makeDeps(
+			{ "overstory-test-project-coordinator": true },
+			undefined,
+			undefined,
+			{ checkSessionStateMap: { "overstory-test-project-coordinator": "alive" } },
+		);
+
+		try {
+			await coordinatorCommand(["start"], deps);
+			expect(true).toBe(false); // Should have thrown
+		} catch (err) {
+			expect(err).toBeInstanceOf(AgentError);
+			const ae = err as AgentError;
+			expect(ae.message).toContain("already running");
+		}
+	});
+
 	test("cleans up dead session and starts new one", async () => {
 		// Write an existing session that claims to be working
 		const deadSession = makeCoordinatorSession({
@@ -656,6 +693,98 @@ describe("startCoordinator", () => {
 		expect(newSession?.id).not.toBe("session-dead-coordinator");
 	});
 
+	test("cleans up zombie session when tmux alive but PID dead", async () => {
+		// Session is "working" in DB, tmux session exists, but the PID is dead
+		const zombieSession = makeCoordinatorSession({
+			id: "session-zombie-coordinator",
+			state: "working",
+			pid: 999999, // Non-existent PID
+		});
+		saveSessionsToDb([zombieSession]);
+
+		// Tmux session is alive (pane exists) but PID 999999 is not running
+		const { deps } = makeDeps(
+			{ "overstory-test-project-coordinator": true },
+			undefined,
+			undefined,
+			{ checkSessionStateMap: { "overstory-test-project-coordinator": "alive" } },
+		);
+
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() => coordinatorCommand(["start"], deps));
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		// Zombie session should be cleaned up and new one created
+		const sessions = loadSessionsFromDb();
+		expect(sessions).toHaveLength(1);
+		const newSession = sessions[0];
+		expect(newSession?.state).toBe("booting");
+		expect(newSession?.id).not.toBe("session-zombie-coordinator");
+	});
+
+	test("cleans up stale session when tmux server is not running", async () => {
+		// Session is "booting" in DB but tmux server crashed
+		const staleSession = makeCoordinatorSession({
+			id: "session-stale-coordinator",
+			state: "booting",
+		});
+		saveSessionsToDb([staleSession]);
+
+		// checkSessionState returns no_server
+		const { deps } = makeDeps(
+			{ "overstory-test-project-coordinator": false },
+			undefined,
+			undefined,
+			{ checkSessionStateMap: { "overstory-test-project-coordinator": "no_server" } },
+		);
+
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() => coordinatorCommand(["start"], deps));
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		// Stale session cleaned up, new one created
+		const sessions = loadSessionsFromDb();
+		expect(sessions).toHaveLength(1);
+		const newSession = sessions[0];
+		expect(newSession?.state).toBe("booting");
+		expect(newSession?.id).not.toBe("session-stale-coordinator");
+	});
+
+	test("respects shellInitDelayMs config before polling TUI readiness", async () => {
+		// Append shellInitDelayMs to existing config (preserve tier2Enabled etc.)
+		const configPath = join(tempDir, ".overstory", "config.yaml");
+		const existing = await Bun.file(configPath).text();
+		await Bun.write(configPath, `${existing}\nruntime:\n  shellInitDelayMs: 500\n`);
+
+		const { deps } = makeDeps();
+
+		const sleepCalls: number[] = [];
+		const originalSleep = Bun.sleep;
+		Bun.sleep = ((ms: number | Date) => {
+			if (typeof ms === "number") sleepCalls.push(ms);
+			return Promise.resolve();
+		}) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() => coordinatorCommand(["start"], deps));
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		// The 500ms shell init delay should appear in the sleep calls
+		expect(sleepCalls).toContain(500);
+	});
+
 	test("throws AgentError when tmux is not available", async () => {
 		const { deps } = makeDeps({}, undefined, undefined, {
 			ensureTmuxAvailableError: new AgentError(

package/src/commands/coordinator.ts

@@ -27,7 +27,9 @@ import { createRunStore } from "../sessions/store.ts";
 import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
 import type { AgentSession } from "../types.ts";
 import { isProcessRunning } from "../watchdog/health.ts";
+import type { SessionState } from "../worktree/tmux.ts";
 import {
+	checkSessionState,
 	createSession,
 	ensureTmuxAvailable,
 	isSessionAlive,
@@ -58,6 +60,7 @@ export interface CoordinatorDeps {
 			env?: Record<string, string>,
 		) => Promise<number>;
 		isSessionAlive: (name: string) => Promise<boolean>;
+		checkSessionState: (name: string) => Promise<SessionState>;
 		killSession: (name: string) => Promise<void>;
 		sendKeys: (name: string, keys: string) => Promise<void>;
 		waitForTuiReady: (
@@ -275,6 +278,7 @@ async function startCoordinator(
 	const tmux = deps._tmux ?? {
 		createSession,
 		isSessionAlive,
+		checkSessionState,
 		killSession,
 		sendKeys,
 		waitForTuiReady,
@@ -308,15 +312,29 @@ async function startCoordinator(
 			existing.state !== "completed" &&
 			existing.state !== "zombie"
 		) {
-			const alive = await tmux.isSessionAlive(existing.tmuxSession);
-			if (alive) {
-				throw new AgentError(
-					`Coordinator is already running (tmux: ${existing.tmuxSession}, since: ${existing.startedAt})`,
-					{ agentName: COORDINATOR_NAME },
-				);
+			const sessionState = await tmux.checkSessionState(existing.tmuxSession);
+
+			if (sessionState === "alive") {
+				// Tmux session exists -- but is the process inside still running?
+				// A crashed Claude Code leaves a zombie tmux pane that blocks retries.
+				if (existing.pid !== null && !isProcessRunning(existing.pid)) {
+					// Zombie: tmux pane exists but agent process has exited.
+					// Kill the empty session and reclaim the slot.
+					await tmux.killSession(existing.tmuxSession);
+					store.updateState(COORDINATOR_NAME, "completed");
+				} else {
+					// Either the process is genuinely running (pid alive), or pid is null
+					// (e.g. sessions migrated from an older schema). In both cases we
+					// cannot prove the session is a zombie, so treat it as active.
+					throw new AgentError(
+						`Coordinator is already running (tmux: ${existing.tmuxSession}, since: ${existing.startedAt})`,
+						{ agentName: COORDINATOR_NAME },
+					);
+				}
+			} else {
+				// Session is dead or tmux server is not running -- clean up stale DB entry.
+				store.updateState(COORDINATOR_NAME, "completed");
 			}
-			// Session recorded but tmux is dead — mark as completed and continue
-			store.updateState(COORDINATOR_NAME, "completed");
 		}
 
 		// Resolve model and runtime early (needed for deployConfig and spawn)
@@ -413,6 +431,12 @@ async function startCoordinator(
 
 		store.upsert(session);
 
+		// Give slow shells time to finish initializing before polling for TUI readiness.
+		const shellDelay = config.runtime?.shellInitDelayMs ?? 0;
+		if (shellDelay > 0) {
+			await Bun.sleep(shellDelay);
+		}
+
 		// Wait for Claude Code TUI to render before sending input
 		const tuiReady = await tmux.waitForTuiReady(tmuxSession, (content) =>
 			runtime.detectReady(content),
@@ -423,8 +447,13 @@ async function startCoordinator(
 			if (!alive) {
 				// Clean up the stale session record
 				store.updateState(COORDINATOR_NAME, "completed");
+				const sessionState = await tmux.checkSessionState(tmuxSession);
+				const detail =
+					sessionState === "no_server"
+						? "The tmux server is no longer running. It may have crashed or been killed externally."
+						: "The Claude Code process may have crashed or exited immediately. Check tmux logs or try running the claude command manually.";
 				throw new AgentError(
-					`Coordinator tmux session "${tmuxSession}" died during startup. The Claude Code process may have crashed or exited immediately. Check tmux logs or try running the claude command manually.`,
+					`Coordinator tmux session "${tmuxSession}" died during startup. ${detail}`,
 					{ agentName: COORDINATOR_NAME },
 				);
 			}
@@ -512,6 +541,7 @@ async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps =
 	const tmux = deps._tmux ?? {
 		createSession,
 		isSessionAlive,
+		checkSessionState,
 		killSession,
 		sendKeys,
 		waitForTuiReady,
@@ -626,6 +656,7 @@ async function statusCoordinator(
 	const tmux = deps._tmux ?? {
 		createSession,
 		isSessionAlive,
+		checkSessionState,
 		killSession,
 		sendKeys,
 		waitForTuiReady,

package/src/commands/costs.test.ts

@@ -796,6 +796,7 @@ describe("costsCommand", () => {
 				cacheCreationTokens: 100,
 				estimatedCostUsd: 0.15,
 				modelUsed: "claude-sonnet-4-5",
+				runId: null,
 				createdAt: new Date().toISOString(),
 			});
 			metricsStore.close();
@@ -853,6 +854,7 @@ describe("costsCommand", () => {
 				cacheCreationTokens: 100,
 				estimatedCostUsd: 0.15,
 				modelUsed: "claude-sonnet-4-5",
+				runId: null,
 				createdAt: new Date().toISOString(),
 			});
 			metricsStore.close();
@@ -937,6 +939,7 @@ describe("costsCommand", () => {
 				cacheCreationTokens: 0,
 				estimatedCostUsd: 0.15,
 				modelUsed: "claude-sonnet-4-5",
+				runId: null,
 				createdAt: new Date().toISOString(),
 			});
 			metricsStore.recordSnapshot({
@@ -947,6 +950,7 @@ describe("costsCommand", () => {
 				cacheCreationTokens: 0,
 				estimatedCostUsd: 0.25,
 				modelUsed: "claude-sonnet-4-5",
+				runId: null,
 				createdAt: new Date().toISOString(),
 			});
 			metricsStore.close();
@@ -997,6 +1001,7 @@ describe("costsCommand", () => {
 				cacheCreationTokens: 0,
 				estimatedCostUsd: 0.3,
 				modelUsed: "claude-sonnet-4-5",
+				runId: null,
 				createdAt: new Date().toISOString(),
 			});
 			metricsStore.close();

package/src/commands/costs.ts

@@ -367,7 +367,7 @@ async function executeCosts(opts: CostsOpts): Promise<void> {
 		const { store: sessionStore } = openSessionStore(overstoryDir);
 
 		try {
-			const snapshots = metricsStore.getLatestSnapshots();
+			const snapshots = metricsStore.getLatestSnapshots(runId ?? undefined);
 			if (snapshots.length === 0) {
 				if (json) {
 					jsonOutput("costs", {

package/src/commands/dashboard.test.ts

@@ -21,6 +21,7 @@ import {
 	computeAgentPanelHeight,
 	dashboardCommand,
 	dimBox,
+	EventBuffer,
 	filterAgentsByRun,
 	horizontalLine,
 	openDashboardStores,
@@ -242,28 +243,28 @@ describe("dimBox", () => {
 
 describe("computeAgentPanelHeight", () => {
 	test("0 agents: clamps to minimum 8", () => {
-		// max(8, min(floor(30*0.5), 0+4)) = max(8, min(15,4)) = max(8,4) = 8
+		// max(8, min(floor(30*0.35)=10, 0+4)) = max(8, min(10,4)) = max(8,4) = 8
 		expect(computeAgentPanelHeight(30, 0)).toBe(8);
 	});
 
 	test("4 agents: still clamps to minimum 8", () => {
-		// max(8, min(15, 4+4)) = max(8, 8) = 8
+		// max(8, min(10, 4+4)) = max(8, 8) = 8
 		expect(computeAgentPanelHeight(30, 4)).toBe(8);
 	});
 
-	test("20 agents with height 30: clamps to floor(height*0.5)", () => {
-		// max(8, min(15, 24)) = max(8,15) = 15
-		expect(computeAgentPanelHeight(30, 20)).toBe(15);
+	test("20 agents with height 30: clamps to floor(height*0.35)", () => {
+		// max(8, min(floor(30*0.35)=10, 24)) = max(8,10) = 10
+		expect(computeAgentPanelHeight(30, 20)).toBe(10);
 	});
 
 	test("10 agents with height 30: grows with agent count", () => {
-		// max(8, min(15, 14)) = max(8,14) = 14
-		expect(computeAgentPanelHeight(30, 10)).toBe(14);
+		// max(8, min(10, 14)) = max(8,10) = 10
+		expect(computeAgentPanelHeight(30, 10)).toBe(10);
 	});
 
-	test("small height: respects 50% cap", () => {
-		// height=20: max(8, min(10, 20+4)) = max(8,10) = 10
-		expect(computeAgentPanelHeight(20, 20)).toBe(10);
+	test("small height: respects 35% cap", () => {
+		// height=20: max(8, min(floor(20*0.35)=7, 24)) = max(8,7) = 8
+		expect(computeAgentPanelHeight(20, 20)).toBe(8);
 	});
 });
 
@@ -302,6 +303,7 @@ function makeDashboardData(
 		metrics: { totalSessions: 0, avgDuration: 0, byCapability: {} },
 		tasks: overrides.tasks ?? [],
 		recentEvents: (overrides.recentEvents as never[]) ?? [],
+		feedColorMap: new Map(),
 	};
 }
 
@@ -366,6 +368,7 @@ describe("renderFeedPanel", () => {
 		const data = makeDashboardData({ recentEvents: [] });
 		const out = renderFeedPanel(data, 1, 80, 8, 1);
 		expect(out).toContain("Feed");
+		expect(out).toContain("(live)");
 	});
 
 	test("renders event agent name when events are present", () => {
@@ -554,6 +557,94 @@ describe("closeDashboardStores", () => {
 	});
 });
 
+describe("EventBuffer", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "event-buffer-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	function makeEvent(agentName: string) {
+		return {
+			agentName,
+			eventType: "tool_end" as const,
+			level: "info" as const,
+			runId: null,
+			sessionId: null,
+			toolName: null,
+			toolArgs: null,
+			toolDurationMs: null,
+			data: null,
+		};
+	}
+
+	test("starts empty", () => {
+		const buf = new EventBuffer();
+		expect(buf.size).toBe(0);
+		expect(buf.getEvents()).toEqual([]);
+	});
+
+	test("poll adds events from event store", async () => {
+		const overstoryDir = join(tempDir, ".overstory");
+		await mkdir(overstoryDir, { recursive: true });
+		const store = createEventStore(join(overstoryDir, "events.db"));
+		store.insert(makeEvent("agent-a"));
+
+		const buf = new EventBuffer();
+		buf.poll(store);
+		expect(buf.size).toBe(1);
+		store.close();
+	});
+
+	test("deduplicates by lastSeenId (double poll returns same count)", async () => {
+		const overstoryDir = join(tempDir, ".overstory");
+		await mkdir(overstoryDir, { recursive: true });
+		const store = createEventStore(join(overstoryDir, "events.db"));
+		store.insert(makeEvent("agent-a"));
+
+		const buf = new EventBuffer();
+		buf.poll(store);
+		buf.poll(store); // second poll should not duplicate
+		expect(buf.size).toBe(1);
+		store.close();
+	});
+
+	test("trims to maxSize keeping most recent events", async () => {
+		const overstoryDir = join(tempDir, ".overstory");
+		await mkdir(overstoryDir, { recursive: true });
+		const store = createEventStore(join(overstoryDir, "events.db"));
+		for (let i = 0; i < 5; i++) {
+			store.insert(makeEvent(`agent-${i}`));
+		}
+
+		const buf = new EventBuffer(3);
+		buf.poll(store);
+		expect(buf.size).toBe(3);
+		store.close();
+	});
+
+	test("builds color map across polls", async () => {
+		const overstoryDir = join(tempDir, ".overstory");
+		await mkdir(overstoryDir, { recursive: true });
+		const store = createEventStore(join(overstoryDir, "events.db"));
+		store.insert(makeEvent("agent-x"));
+
+		const buf = new EventBuffer();
+		buf.poll(store);
+		expect(buf.getColorMap().has("agent-x")).toBe(true);
+
+		store.insert(makeEvent("agent-y"));
+		buf.poll(store);
+		expect(buf.getColorMap().has("agent-x")).toBe(true);
+		expect(buf.getColorMap().has("agent-y")).toBe(true);
+		store.close();
+	});
+});
+
 // Type check: DashboardStores includes eventStore
 test("DashboardStores type includes eventStore field", () => {
 	const stores: DashboardStores = {