@os-eco/overstory-cli 0.6.11 → 0.7.0

package/src/runtimes/claude.ts

@@ -0,0 +1,218 @@
+// Claude Code runtime adapter for overstory's AgentRuntime interface.
+// Pure extraction — no new behavior. All implementation delegates to existing code.
+// Phase 0: file exists and compiles. Callers are not rewired until Phase 2.
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { deployHooks } from "../agents/hooks-deployer.ts";
+import { estimateCost, parseTranscriptUsage } from "../metrics/transcript.ts";
+import type { ResolvedModel } from "../types.ts";
+import type {
+	AgentRuntime,
+	HooksDef,
+	OverlayContent,
+	ReadyState,
+	SpawnOpts,
+	TranscriptSummary,
+} from "./types.ts";
+
+/**
+ * Claude Code runtime adapter.
+ *
+ * Implements AgentRuntime for the `claude` CLI (Anthropic's Claude Code).
+ * All methods delegate to existing overstory subsystems — this adapter
+ * only provides the runtime-agnostic interface layer.
+ *
+ * Phase 0: file exists, compiles, and exports the class.
+ * Phase 2 will rewire callers (sling.ts, coordinator.ts, etc.) to use this adapter.
+ */
+export class ClaudeRuntime implements AgentRuntime {
+	/** Unique identifier for this runtime. */
+	readonly id = "claude";
+
+	/** Relative path to the instruction file within a worktree. */
+	readonly instructionPath = ".claude/CLAUDE.md";
+
+	/**
+	 * Build the shell command string to spawn an interactive Claude Code agent.
+	 *
+	 * Maps SpawnOpts to the `claude` CLI flags:
+	 * - `model` → `--model <model>`
+	 * - `permissionMode` → `--permission-mode <mode>`
+	 *   - "bypass" maps to "bypassPermissions"
+	 *   - "ask" maps to "default"
+	 * - `appendSystemPrompt` → `--append-system-prompt '<escaped>'`
+	 *
+	 * The returned string is passed directly to tmux as the initial command.
+	 * The `cwd` and `env` fields of SpawnOpts are handled by the tmux session
+	 * creator, not embedded in the command string.
+	 *
+	 * @param opts - Spawn options (model, permissionMode, appendSystemPrompt)
+	 * @returns Shell command string suitable for tmux new-session -c
+	 */
+	buildSpawnCommand(opts: SpawnOpts): string {
+		const permMode = opts.permissionMode === "bypass" ? "bypassPermissions" : "default";
+		let cmd = `claude --model ${opts.model} --permission-mode ${permMode}`;
+
+		if (opts.appendSystemPrompt) {
+			// Single-quote the content for safe shell expansion.
+			// POSIX single-quoted strings cannot contain single quotes, so escape
+			// them using the standard technique: end quote, escaped quote, start quote.
+			const escaped = opts.appendSystemPrompt.replace(/'/g, "'\\''");
+			cmd += ` --append-system-prompt '${escaped}'`;
+		}
+
+		return cmd;
+	}
+
+	/**
+	 * Build the argv array for a headless one-shot Claude invocation.
+	 *
+	 * Returns an argv array suitable for `Bun.spawn()`. The `--print` flag
+	 * causes Claude Code to run the prompt and exit, writing output to stdout.
+	 *
+	 * Used by merge/resolver.ts (AI-assisted conflict resolution) and
+	 * watchdog/triage.ts (AI-assisted failure classification).
+	 *
+	 * @param prompt - The prompt to pass via `-p`
+	 * @param model - Optional model override (omit to use Claude Code's default)
+	 * @returns Argv array for Bun.spawn
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const cmd = ["claude", "--print", "-p", prompt];
+		if (model !== undefined) {
+			cmd.push("--model", model);
+		}
+		return cmd;
+	}
+
+	/**
+	 * Deploy per-agent instructions and guards to a worktree.
+	 *
+	 * For Claude Code this means writes to the worktree's `.claude/` directory:
+	 * 1. `CLAUDE.md` — the agent's task-specific overlay (generated by ov sling).
+	 *    Skipped when overlay is undefined (hooks-only deployment for coordinator/supervisor/monitor).
+	 * 2. `settings.local.json` — Claude Code hooks for security guards
+	 *
+	 * The `overlay.content` is written verbatim when provided. The hooks are generated by
+	 * `deployHooks()` from `src/agents/hooks-deployer.ts`.
+	 *
+	 * @param worktreePath - Absolute path to the agent's git worktree
+	 * @param overlay - Overlay content to write as CLAUDE.md, or undefined for hooks-only deployment
+	 * @param hooks - Hook definition used by deployHooks
+	 * @throws {AgentError} If the hooks template is missing or writes fail
+	 */
+	async deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		hooks: HooksDef,
+	): Promise<void> {
+		if (overlay) {
+			const claudeDir = join(worktreePath, ".claude");
+			await mkdir(claudeDir, { recursive: true });
+
+			const claudeMdPath = join(claudeDir, "CLAUDE.md");
+			await Bun.write(claudeMdPath, overlay.content);
+		}
+
+		await deployHooks(hooks.worktreePath, hooks.agentName, hooks.capability, hooks.qualityGates);
+	}
+
+	/**
+	 * Detect Claude Code TUI readiness from a tmux pane content snapshot.
+	 *
+	 * Uses the same heuristics as `waitForTuiReady()` in `src/worktree/tmux.ts`,
+	 * but operates on a pre-captured pane string rather than polling tmux directly.
+	 * The caller is responsible for capturing pane content and acting on the result
+	 * (e.g. sending "Enter" to dismiss a trust dialog).
+	 *
+	 * Detection phases:
+	 * - Trust dialog: "trust this folder" detected → `{ phase: "dialog", action: "Enter" }`
+	 * - Ready: prompt indicator (❯ or 'Try "') AND status bar ("bypass permissions"
+	 *   or "shift+tab") both present → `{ phase: "ready" }`
+	 * - Otherwise → `{ phase: "loading" }`
+	 *
+	 * @param paneContent - Captured tmux pane content to analyze
+	 * @returns Current readiness phase
+	 */
+	detectReady(paneContent: string): ReadyState {
+		// Trust dialog takes precedence — it replaces the normal TUI temporarily.
+		// The caller should send the action key to dismiss it.
+		if (paneContent.includes("trust this folder")) {
+			return { phase: "dialog", action: "Enter" };
+		}
+
+		// Phase 1: prompt indicator confirms Claude Code has started.
+		// ❯ is the claude prompt character; 'Try "' appears in the welcome banner.
+		const hasPrompt = paneContent.includes("\u276f") || paneContent.includes('Try "');
+
+		// Phase 2: status bar text confirms full TUI render.
+		const hasStatusBar =
+			paneContent.includes("bypass permissions") || paneContent.includes("shift+tab");
+
+		if (hasPrompt && hasStatusBar) {
+			return { phase: "ready" };
+		}
+
+		return { phase: "loading" };
+	}
+
+	/**
+	 * Parse a Claude Code transcript JSONL file into normalized token usage.
+	 *
+	 * Reads the JSONL file at `path` and aggregates token usage across all
+	 * assistant turns. Returns null if the file does not exist or cannot be read.
+	 *
+	 * Delegates to `parseTranscriptUsage()` and `estimateCost()` from
+	 * `src/metrics/transcript.ts`. The `estimatedCostUsd` is computed but
+	 * not exposed here because `TranscriptSummary` only carries the three
+	 * core fields (inputTokens, outputTokens, model). Cost data is available
+	 * via `src/metrics/transcript.ts` directly for callers that need it.
+	 *
+	 * @param path - Absolute path to the transcript JSONL 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 usage = await parseTranscriptUsage(path);
+			// estimateCost is called to validate the model is recognized,
+			// though the result is not surfaced in TranscriptSummary.
+			if (usage.modelUsed !== null) {
+				estimateCost(usage);
+			}
+			return {
+				inputTokens: usage.inputTokens,
+				outputTokens: usage.outputTokens,
+				model: usage.modelUsed ?? "",
+			};
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Build runtime-specific environment variables for model/provider routing.
+	 *
+	 * Returns the provider environment variables from the resolved model.
+	 * For Anthropic native: may include ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL.
+	 * For gateway providers: may include gateway-specific auth and routing vars.
+	 *
+	 * Returns an empty object if the resolved model has no provider env vars.
+	 * Callers (sling.ts, coordinator.ts) merge this with OVERSTORY_AGENT_NAME
+	 * and OVERSTORY_WORKTREE_PATH before passing to createSession().
+	 *
+	 * @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 ?? {};
+	}
+}
+
+/** Singleton instance for use in callers that do not need DI. */
+export const claudeRuntime = new ClaudeRuntime();

package/src/runtimes/registry.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "bun:test";
+import type { OverstoryConfig } from "../types.ts";
+import { ClaudeRuntime } from "./claude.ts";
+import { getRuntime } from "./registry.ts";
+
+describe("getRuntime", () => {
+	it("returns a ClaudeRuntime by default (no args)", () => {
+		const runtime = getRuntime();
+		expect(runtime).toBeInstanceOf(ClaudeRuntime);
+		expect(runtime.id).toBe("claude");
+	});
+
+	it('returns a ClaudeRuntime when name is "claude"', () => {
+		const runtime = getRuntime("claude");
+		expect(runtime).toBeInstanceOf(ClaudeRuntime);
+		expect(runtime.id).toBe("claude");
+	});
+
+	it("throws with a helpful message for an unknown runtime", () => {
+		expect(() => getRuntime("unknown-runtime")).toThrow(
+			'Unknown runtime: "unknown-runtime". Available: claude',
+		);
+	});
+
+	it("uses config.runtime.default when name is omitted", () => {
+		const config = { runtime: { default: "claude" } } as OverstoryConfig;
+		const runtime = getRuntime(undefined, config);
+		expect(runtime).toBeInstanceOf(ClaudeRuntime);
+		expect(runtime.id).toBe("claude");
+	});
+
+	it("explicit name overrides config.runtime.default", () => {
+		const config = { runtime: { default: "claude" } } as OverstoryConfig;
+		// Both are "claude" here since that's the only registered runtime,
+		// but the name arg takes precedence over config.
+		const runtime = getRuntime("claude", config);
+		expect(runtime).toBeInstanceOf(ClaudeRuntime);
+	});
+
+	it("throws for unknown runtime even when config default is set", () => {
+		const config = { runtime: { default: "codex" } } as OverstoryConfig;
+		// No name arg — falls back to config default "codex" which is unknown.
+		expect(() => getRuntime(undefined, config)).toThrow(
+			'Unknown runtime: "codex". Available: claude',
+		);
+	});
+
+	it("returns a new instance on each call (factory pattern)", () => {
+		const a = getRuntime();
+		const b = getRuntime();
+		expect(a).not.toBe(b);
+	});
+});

package/src/runtimes/registry.ts

@@ -0,0 +1,33 @@
+// Runtime registry — maps runtime names to adapter factory functions.
+// This is the ONLY module that imports concrete adapter classes.
+
+import type { OverstoryConfig } from "../types.ts";
+import { ClaudeRuntime } from "./claude.ts";
+import type { AgentRuntime } from "./types.ts";
+
+/** Registry of available runtime adapters (name → factory). */
+const runtimes = new Map<string, () => AgentRuntime>([["claude", () => new ClaudeRuntime()]]);
+
+/**
+ * Resolve a runtime adapter by name.
+ *
+ * Lookup order:
+ * 1. Explicit `name` argument (if provided)
+ * 2. `config.runtime.default` (if config is provided)
+ * 3. `"claude"` (hardcoded fallback)
+ *
+ * @param name - Runtime name to resolve (e.g. "claude"). Omit to use config default.
+ * @param config - Overstory config for reading the default runtime.
+ * @throws {Error} If the resolved runtime name is not registered.
+ * @returns A fresh AgentRuntime instance.
+ */
+export function getRuntime(name?: string, config?: OverstoryConfig): AgentRuntime {
+	const runtimeName = name ?? config?.runtime?.default ?? "claude";
+	const factory = runtimes.get(runtimeName);
+	if (!factory) {
+		throw new Error(
+			`Unknown runtime: "${runtimeName}". Available: ${[...runtimes.keys()].join(", ")}`,
+		);
+	}
+	return factory();
+}

package/src/runtimes/types.ts

@@ -0,0 +1,125 @@
+// Runtime abstraction types for multi-provider agent support.
+// See docs/runtime-abstraction.md for design rationale and coupling inventory.
+
+import type { QualityGate, ResolvedModel } from "../types.ts";
+
+// === Spawn ===
+
+/** Options for spawning an interactive agent process. */
+export interface SpawnOpts {
+	/** Model ref (alias or provider-qualified, e.g. "sonnet" or "openrouter/gpt-5"). */
+	model: string;
+	/** Permission mode: bypass for trusted builders, ask for interactive agents. */
+	permissionMode: "bypass" | "ask";
+	/** Optional system prompt prefix injected before the agent's base instructions. */
+	systemPrompt?: string;
+	/** Optional system prompt suffix appended after the base instructions. */
+	appendSystemPrompt?: string;
+	/** Working directory for the spawned process. */
+	cwd: string;
+	/** Additional environment variables to pass to the spawned process. */
+	env: Record<string, string>;
+}
+
+// === Readiness ===
+
+/**
+ * Discrete phases of agent TUI readiness, detected from tmux pane content.
+ * Headless runtimes (codex exec, pi --mode rpc) always return { phase: "ready" }.
+ */
+export type ReadyState =
+	| { phase: "loading" }
+	| { phase: "dialog"; action: string }
+	| { phase: "ready" };
+
+// === Config Deployment ===
+
+/** Runtime-agnostic overlay content to write into a worktree. */
+export interface OverlayContent {
+	/** Full markdown text to write as the agent's instruction file. */
+	content: string;
+}
+
+/**
+ * Runtime-agnostic hook/guard configuration for deployment to a worktree.
+ * Each runtime adapter translates this into its native guard mechanism
+ * (e.g., settings.local.json hooks for Claude Code, guard extensions for Pi).
+ */
+export interface HooksDef {
+	/** Agent name injected into hook commands. */
+	agentName: string;
+	/** Agent capability (builder, scout, reviewer, lead, etc.). */
+	capability: string;
+	/** Absolute path to the agent's worktree for path-boundary enforcement. */
+	worktreePath: string;
+	/** Quality gates agents must pass before reporting completion. */
+	qualityGates?: QualityGate[];
+}
+
+// === Transcripts ===
+
+/** Normalized token usage extracted from any runtime's session transcript. */
+export interface TranscriptSummary {
+	inputTokens: number;
+	outputTokens: number;
+	/** Model identifier as reported by the runtime (e.g. "claude-sonnet-4-6"). */
+	model: string;
+}
+
+// === Runtime Interface ===
+
+/**
+ * Contract that all agent runtime adapters must implement.
+ *
+ * Each runtime (Claude Code, Codex, Pi, OpenCode, ...) provides a ~200-400 line
+ * adapter file implementing this interface. The orchestration engine calls only
+ * these methods — never the runtime's CLI directly.
+ */
+export interface AgentRuntime {
+	/** Unique runtime identifier (e.g. "claude", "codex", "pi"). */
+	id: string;
+
+	/** Relative path to the instruction file within a worktree (e.g. ".claude/CLAUDE.md"). */
+	readonly instructionPath: string;
+
+	/** Build the shell command string to spawn an interactive agent in a tmux pane. */
+	buildSpawnCommand(opts: SpawnOpts): string;
+
+	/**
+	 * Build the argv array for a headless one-shot AI call.
+	 * Used by merge/resolver.ts and watchdog/triage.ts for AI-assisted operations.
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[];
+
+	/**
+	 * Deploy per-agent instructions and guards to a worktree.
+	 * Claude Code writes .claude/CLAUDE.md + settings.local.json hooks.
+	 * Codex writes AGENTS.md (no hook deployment needed).
+	 * Pi writes .claude/CLAUDE.md + a guard extension in .pi/extensions/.
+	 * When overlay is undefined, only hooks are deployed (no instruction file written).
+	 */
+	deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		hooks: HooksDef,
+	): Promise<void>;
+
+	/**
+	 * Detect agent readiness from tmux pane content.
+	 * Headless runtimes that exit when done should return { phase: "ready" } unconditionally.
+	 */
+	detectReady(paneContent: string): ReadyState;
+
+	/**
+	 * Parse a session transcript file into normalized token usage.
+	 * Returns null if the transcript does not exist or cannot be parsed.
+	 */
+	parseTranscript(path: string): Promise<TranscriptSummary | null>;
+
+	/**
+	 * Build runtime-specific environment variables for model/provider routing.
+	 * Claude Code uses ANTHROPIC_API_KEY; Codex uses OPENAI_API_KEY; Pi passes
+	 * the provider's authTokenEnv directly.
+	 */
+	buildEnv(model: ResolvedModel): Record<string, string>;
+}

package/src/types.ts

@@ -86,6 +86,10 @@ export interface OverstoryConfig {
 		verbose: boolean;
 		redactSecrets: boolean;
 	};
+	runtime?: {
+		/** Default runtime adapter name (default: "claude"). */
+		default: string;
+	};
 }
 
 // === Agent Manifest ===

package/src/worktree/tmux.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import { AgentError } from "../errors.ts";
+import type { ReadyState } from "../runtimes/types.ts";
 import {
 	capturePaneContent,
 	createSession,
@@ -940,6 +941,20 @@ describe("capturePaneContent", () => {
 	});
 });
 
+/** Claude-like detectReady for tests — matches the existing hardcoded behavior. */
+function claudeDetectReady(paneContent: string): ReadyState {
+	if (paneContent.includes("trust this folder")) {
+		return { phase: "dialog", action: "Enter" };
+	}
+	const hasPrompt = paneContent.includes("\u276f") || paneContent.includes('Try "');
+	const hasStatusBar =
+		paneContent.includes("bypass permissions") || paneContent.includes("shift+tab");
+	if (hasPrompt && hasStatusBar) {
+		return { phase: "ready" };
+	}
+	return { phase: "loading" };
+}
+
 describe("waitForTuiReady", () => {
 	let spawnSpy: ReturnType<typeof spyOn>;
 	let sleepSpy: ReturnType<typeof spyOn>;
@@ -961,7 +976,7 @@ describe("waitForTuiReady", () => {
 			mockSpawnResult('Try "help" to get started\nbypass permissions', "", 0),
 		);
 
-		const ready = await waitForTuiReady("overstory-agent", 5_000, 500);
+		const ready = await waitForTuiReady("overstory-agent", claudeDetectReady, 5_000, 500);
 
 		expect(ready).toBe(true);
 		// Should not have needed to sleep (content found on first poll)
@@ -985,7 +1000,7 @@ describe("waitForTuiReady", () => {
 			return mockSpawnResult("", "", 0);
 		});
 
-		const ready = await waitForTuiReady("overstory-agent", 10_000, 500);
+		const ready = await waitForTuiReady("overstory-agent", claudeDetectReady, 10_000, 500);
 
 		expect(ready).toBe(true);
 		// Should have slept 3 times (3 empty capture-pane polls before content appeared)
@@ -996,7 +1011,7 @@ describe("waitForTuiReady", () => {
 		// Pane always empty
 		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
 
-		const ready = await waitForTuiReady("overstory-agent", 2_000, 500);
+		const ready = await waitForTuiReady("overstory-agent", claudeDetectReady, 2_000, 500);
 
 		expect(ready).toBe(false);
 		// 2000ms / 500ms = 4 polls, 4 sleeps
@@ -1006,7 +1021,7 @@ describe("waitForTuiReady", () => {
 	test("returns false when capture-pane always fails", async () => {
 		spawnSpy.mockImplementation(() => mockSpawnResult("", "session not found", 1));
 
-		const ready = await waitForTuiReady("dead-session", 1_000, 500);
+		const ready = await waitForTuiReady("dead-session", claudeDetectReady, 1_000, 500);
 
 		expect(ready).toBe(false);
 	});
@@ -1015,7 +1030,7 @@ describe("waitForTuiReady", () => {
 		// Return content immediately with both indicators
 		spawnSpy.mockImplementation(() => mockSpawnResult('Try "help"\nshift+tab', "", 0));
 
-		const ready = await waitForTuiReady("overstory-agent");
+		const ready = await waitForTuiReady("overstory-agent", claudeDetectReady);
 
 		expect(ready).toBe(true);
 	});
@@ -1031,7 +1046,7 @@ describe("waitForTuiReady", () => {
 			return mockSpawnResult("", "can't find session", 1);
 		});
 
-		const ready = await waitForTuiReady("dead-session", 15_000, 500);
+		const ready = await waitForTuiReady("dead-session", claudeDetectReady, 15_000, 500);
 
 		expect(ready).toBe(false);
 		// Should NOT have polled the full timeout (no sleeps — returned immediately)
@@ -1052,7 +1067,7 @@ describe("waitForTuiReady", () => {
 		});
 
 		// Use a short timeout so the test doesn't take long
-		const ready = await waitForTuiReady("loading-session", 1_000, 500);
+		const ready = await waitForTuiReady("loading-session", claudeDetectReady, 1_000, 500);
 
 		expect(ready).toBe(false);
 		// Should have polled multiple times (not returned early)
@@ -1071,7 +1086,7 @@ describe("waitForTuiReady", () => {
 			return mockSpawnResult("", "", 0);
 		});
 
-		const ready = await waitForTuiReady("overstory-agent", 1_000, 500);
+		const ready = await waitForTuiReady("overstory-agent", claudeDetectReady, 1_000, 500);
 
 		expect(ready).toBe(false);
 	});
@@ -1087,7 +1102,7 @@ describe("waitForTuiReady", () => {
 			return mockSpawnResult("", "", 0);
 		});
 
-		const ready = await waitForTuiReady("overstory-agent", 1_000, 500);
+		const ready = await waitForTuiReady("overstory-agent", claudeDetectReady, 1_000, 500);
 
 		expect(ready).toBe(false);
 	});
@@ -1109,7 +1124,7 @@ describe("waitForTuiReady", () => {
 			return mockSpawnResult("", "", 0);
 		});
 
-		const ready = await waitForTuiReady("overstory-agent", 10_000, 500);
+		const ready = await waitForTuiReady("overstory-agent", claudeDetectReady, 10_000, 500);
 
 		expect(ready).toBe(true);
 		// Should have slept at least twice (2 polls with only prompt before both appeared)
@@ -1138,7 +1153,7 @@ describe("waitForTuiReady", () => {
 			return mockSpawnResult("", "", 0);
 		});
 
-		const ready = await waitForTuiReady("overstory-agent", 10_000, 500);
+		const ready = await waitForTuiReady("overstory-agent", claudeDetectReady, 10_000, 500);
 
 		expect(ready).toBe(true);
 		// sendKeys should have been called once to confirm the trust dialog
@@ -1169,10 +1184,10 @@ describe("waitForTuiReady", () => {
 			return mockSpawnResult("", "", 0);
 		});
 
-		const ready = await waitForTuiReady("overstory-agent", 10_000, 500);
+		const ready = await waitForTuiReady("overstory-agent", claudeDetectReady, 10_000, 500);
 
 		expect(ready).toBe(true);
-		// sendKeys must be called exactly once — trustHandled prevents duplicate Enter sends
+		// sendKeys must be called exactly once — dialogHandled prevents duplicate Enter sends
 		expect(sendKeysCalls).toHaveLength(1);
 	});
 });

package/src/worktree/tmux.ts

@@ -9,6 +9,7 @@
 
 import { dirname, resolve } from "node:path";
 import { AgentError } from "../errors.ts";
+import type { ReadyState } from "../runtimes/types.ts";
 
 /**
  * Detect the directory containing the overstory binary.
@@ -435,58 +436,43 @@ export async function capturePaneContent(name: string, lines = 50): Promise<stri
 /**
  * Wait for a tmux session's TUI to become ready for input.
  *
- * Uses a two-phase readiness check:
- * 1. Phase 1 — prompt indicator: detects ❯ or 'Try "' confirming Claude Code has started
- * 2. Phase 2 — status bar: detects 'bypass permissions' or 'shift+tab' confirming full TUI render
- * Returns true only when BOTH phases have been observed.
- *
- * Additionally handles the workspace trust dialog: if 'trust this folder' is detected,
- * sends Enter to auto-confirm before continuing to wait for the real TUI. The trust
- * dialog check must precede phase checks since it replaces the normal TUI temporarily.
+ * Delegates all readiness detection to the provided `detectReady` callback,
+ * making this function runtime-agnostic. The callback inspects pane content
+ * and returns a ReadyState phase: "loading" (keep waiting), "dialog" (send
+ * Enter to dismiss, then continue), or "ready" (return true).
  *
  * @param name - Tmux session name to poll
+ * @param detectReady - Callback that inspects pane content and returns ReadyState
  * @param timeoutMs - Maximum time to wait before giving up (default 30s)
  * @param pollIntervalMs - Time between polls (default 500ms)
- * @returns true once both prompt indicator AND status bar text detected, false on timeout
+ * @returns true once detectReady returns { phase: "ready" }, false on timeout or dead session
  */
 export async function waitForTuiReady(
 	name: string,
+	detectReady: (paneContent: string) => ReadyState,
 	timeoutMs = 30_000,
 	pollIntervalMs = 500,
 ): Promise<boolean> {
 	const maxAttempts = Math.ceil(timeoutMs / pollIntervalMs);
-	let promptSeen = false;
-	let statusBarSeen = false;
-	let trustHandled = false;
+	let dialogHandled = false;
 
 	for (let i = 0; i < maxAttempts; i++) {
 		const content = await capturePaneContent(name);
 		if (content !== null) {
-			// Trust dialog detection — must come before phase checks since it replaces normal TUI
-			if (!trustHandled && content.includes("trust this folder")) {
+			const state = detectReady(content);
+
+			if (state.phase === "dialog" && !dialogHandled) {
 				await sendKeys(name, "");
-				trustHandled = true;
+				dialogHandled = true;
 				await Bun.sleep(pollIntervalMs);
 				continue;
 			}
 
-			// Phase 1: prompt indicator confirms Claude Code has started
-			if (content.includes("\u276f") || content.includes('Try "')) {
-				promptSeen = true;
-			}
-
-			// Phase 2: status bar text confirms full TUI render
-			if (content.includes("bypass permissions") || content.includes("shift+tab")) {
-				statusBarSeen = true;
-			}
-
-			// Return true only when both phases complete
-			if (promptSeen && statusBarSeen) {
+			if (state.phase === "ready") {
 				return true;
 			}
 		}
 
-		// Check if session died — no point waiting if it's gone
 		const alive = await isSessionAlive(name);
 		if (!alive) {
 			return false;