@os-eco/overstory-cli 0.8.6 → 0.9.1

package/src/index.ts

@@ -16,6 +16,7 @@ import { createCompletionsCommand } from "./commands/completions.ts";
 import { createCoordinatorCommand } from "./commands/coordinator.ts";
 import { createCostsCommand } from "./commands/costs.ts";
 import { createDashboardCommand } from "./commands/dashboard.ts";
+import { createDiscoverCommand } from "./commands/discover.ts";
 import { createDoctorCommand } from "./commands/doctor.ts";
 import { createEcosystemCommand } from "./commands/ecosystem.ts";
 import { createErrorsCommand } from "./commands/errors.ts";
@@ -49,7 +50,7 @@ import { ConfigError, OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.8.6";
+export const VERSION = "0.9.1";
 
 const rawArgs = process.argv.slice(2);
 
@@ -76,6 +77,7 @@ const COMMANDS = [
 	"stop",
 	"status",
 	"dashboard",
+	"discover",
 	"inspect",
 	"clean",
 	"doctor",
@@ -286,6 +288,7 @@ program
 	.option("--dispatch-max-agents <n>", "Per-lead max agents ceiling (injected into overlay)")
 	.option("--runtime <name>", "Runtime adapter (default: config or claude)")
 	.option("--base-branch <branch>", "Base branch for worktree creation (default: current HEAD)")
+	.option("--profile <name>", "Canopy profile to apply to agent overlay")
 	.option("--json", "Output result as JSON")
 	.action(async (taskId, opts) => {
 		await slingCommand(taskId, opts);
@@ -329,6 +332,8 @@ program.addCommand(createStatusCommand());
 
 program.addCommand(createDashboardCommand());
 
+program.addCommand(createDiscoverCommand());
+
 program.addCommand(createInspectCommand());
 
 program

package/src/mail/store.ts

@@ -83,9 +83,10 @@ function migrateSchema(db: Database): void {
 	const hasCheckConstraints = row.sql.includes("CHECK");
 	const hasPayloadColumn = row.sql.includes("payload");
 	const hasProtocolTypes = row.sql.includes("worker_done");
+	const hasDecisionGate = row.sql.includes("decision_gate");
 
 	// If schema is fully up to date, nothing to do
-	if (hasCheckConstraints && hasPayloadColumn && hasProtocolTypes) {
+	if (hasCheckConstraints && hasPayloadColumn && hasProtocolTypes && hasDecisionGate) {
 		return;
 	}
 

package/src/merge/resolver.test.ts

@@ -22,6 +22,7 @@ import type { MergeEntry, ParsedConflictPattern } from "../types.ts";
 import {
 	buildConflictHistory,
 	createMergeResolver,
+	hasContentfulCanonical,
 	looksLikeProse,
 	parseConflictPatterns,
 	resolveConflictsUnion,
@@ -86,6 +87,20 @@ async function setupContentConflict(dir: string, baseBranch: string): Promise<vo
 	await commitFile(dir, "src/test.ts", "main modified content\n");
 }
 
+/**
+ * Set up a conflict where the canonical (HEAD) side is empty in the conflict marker.
+ * Main deletes a shared line; feature replaces it. Git produces a conflict with an
+ * empty HEAD side, so hasContentfulCanonical returns false and auto-resolve can safely
+ * keep the incoming content.
+ */
+async function setupEmptyCanonicalConflict(dir: string, baseBranch: string): Promise<void> {
+	await commitFile(dir, "src/test.ts", "line1\nshared line\nline3\n");
+	await runGitInDir(dir, ["checkout", "-b", "feature-branch"]);
+	await commitFile(dir, "src/test.ts", "line1\nnew content\nline3\n");
+	await runGitInDir(dir, ["checkout", baseBranch]);
+	await commitFile(dir, "src/test.ts", "line1\nline3\n"); // main deletes "shared line"
+}
+
 /**
  * Create a delete/modify conflict: file is deleted on main but modified on
  * the feature branch. This produces a conflict with NO conflict markers in
@@ -431,11 +446,13 @@ describe("createMergeResolver", () => {
 	});
 
 	describe("Tier 1 fail -> Tier 2: Auto-resolve", () => {
-		test("auto-resolves conflicts keeping incoming changes with correct content", async () => {
+		test("auto-resolves conflicts when canonical side is empty (keeps incoming)", async () => {
 			const repoDir = await createTempGitRepo();
 			try {
 				const defaultBranch = await getDefaultBranch(repoDir);
-				await setupContentConflict(repoDir, defaultBranch);
+				// Use empty-canonical setup: main deletes a line, feature replaces it.
+				// The conflict marker has an empty HEAD side, so auto-resolve is safe.
+				await setupEmptyCanonicalConflict(repoDir, defaultBranch);
 
 				const entry = makeTestEntry({
 					branchName: "feature-branch",
@@ -453,11 +470,12 @@ describe("createMergeResolver", () => {
 				expect(result.tier).toBe("auto-resolve");
 				expect(result.entry.status).toBe("merged");
 				expect(result.entry.resolvedTier).toBe("auto-resolve");
+				expect(result.warnings).toEqual([]);
 
 				// The resolved file should contain the incoming (feature branch) content
 				const file = Bun.file(join(repoDir, "src/test.ts"));
 				const content = await file.text();
-				expect(content).toBe("feature content\n");
+				expect(content).toContain("new content");
 			} finally {
 				await cleanupTempDir(repoDir);
 			}
@@ -688,6 +706,7 @@ describe("createMergeResolver", () => {
 			expect(result).toHaveProperty("tier");
 			expect(result).toHaveProperty("conflictFiles");
 			expect(result).toHaveProperty("errorMessage");
+			expect(result).toHaveProperty("warnings");
 		});
 
 		test("failed result preserves original entry fields", async () => {
@@ -806,6 +825,117 @@ describe("createMergeResolver", () => {
 		});
 	});
 
+	describe("hasContentfulCanonical", () => {
+		test("returns true when canonical side has content", () => {
+			const content = [
+				"<<<<<<< HEAD\n",
+				"canonical content\n",
+				"=======\n",
+				"incoming content\n",
+				">>>>>>> feature-branch\n",
+			].join("");
+			expect(hasContentfulCanonical(content)).toBe(true);
+		});
+
+		test("returns false when canonical side is empty", () => {
+			const content = [
+				"<<<<<<< HEAD\n",
+				"=======\n",
+				"incoming content\n",
+				">>>>>>> feature-branch\n",
+			].join("");
+			expect(hasContentfulCanonical(content)).toBe(false);
+		});
+
+		test("returns false when canonical is whitespace only", () => {
+			const content = [
+				"<<<<<<< HEAD\n",
+				"   \n",
+				"\t\n",
+				"=======\n",
+				"incoming content\n",
+				">>>>>>> feature-branch\n",
+			].join("");
+			expect(hasContentfulCanonical(content)).toBe(false);
+		});
+
+		test("returns false when no conflict markers", () => {
+			expect(hasContentfulCanonical("no conflicts here\n")).toBe(false);
+			expect(hasContentfulCanonical("")).toBe(false);
+		});
+
+		test("returns true if ANY block has canonical content (multiple blocks)", () => {
+			const block1 = "<<<<<<< HEAD\n=======\nonly incoming\n>>>>>>> branch\n";
+			const block2 = "<<<<<<< HEAD\ncanonical content\n=======\nincoming\n>>>>>>> branch\n";
+			const content = `${block1}middle\n${block2}`;
+			expect(hasContentfulCanonical(content)).toBe(true);
+		});
+	});
+
+	describe("auto-resolve: content protection", () => {
+		test("auto-resolve skips files with contentful canonical, result includes warning", async () => {
+			const repoDir = await createTempGitRepo();
+			try {
+				const defaultBranch = await getDefaultBranch(repoDir);
+				// setupContentConflict: both canonical and incoming have content
+				await setupContentConflict(repoDir, defaultBranch);
+
+				const entry = makeTestEntry({
+					branchName: "feature-branch",
+					filesModified: ["src/test.ts"],
+				});
+
+				// AI and reimagine disabled — should FAIL because auto-resolve correctly refuses
+				const resolver = createMergeResolver({
+					aiResolveEnabled: false,
+					reimagineEnabled: false,
+				});
+
+				const result = await resolver.resolve(entry, defaultBranch, repoDir);
+
+				expect(result.success).toBe(false);
+				expect(result.warnings.length).toBeGreaterThan(0);
+				expect(result.warnings[0]).toContain("src/test.ts");
+			} finally {
+				await cleanupTempDir(repoDir);
+			}
+		});
+	});
+
+	describe("untracked files: no silent commit", () => {
+		test("untracked overlapping files are deleted, not committed", async () => {
+			const repoDir = await createTempGitRepo();
+			try {
+				const defaultBranch = await getDefaultBranch(repoDir);
+				await setupCleanMerge(repoDir, defaultBranch);
+
+				// Place an untracked file at the path the feature branch will bring in
+				await Bun.write(`${repoDir}/src/feature-file.ts`, "local untracked content\n");
+
+				const entry = makeTestEntry({
+					branchName: "feature-branch",
+					filesModified: ["src/feature-file.ts"],
+				});
+
+				const resolver = createMergeResolver({
+					aiResolveEnabled: false,
+					reimagineEnabled: false,
+				});
+
+				const result = await resolver.resolve(entry, defaultBranch, repoDir);
+
+				expect(result.success).toBe(true);
+				expect(result.warnings.some((w) => w.includes("src/feature-file.ts"))).toBe(true);
+
+				// Verify git log does NOT contain the "commit untracked files before merge" commit
+				const log = await runGitInDir(repoDir, ["log", "--oneline"]);
+				expect(log).not.toContain("commit untracked files before merge");
+			} finally {
+				await cleanupTempDir(repoDir);
+			}
+		});
+	});
+
 	describe("Tier 3: AI-resolve prose rejection", () => {
 		test("rejects prose output and falls through to failure", async () => {
 			const repoDir = await createTempGitRepo();
@@ -858,7 +988,8 @@ describe("createMergeResolver", () => {
 			const repoDir = await createTempGitRepo();
 			try {
 				const defaultBranch = await getDefaultBranch(repoDir);
-				await setupContentConflict(repoDir, defaultBranch);
+				// Use empty-canonical setup so auto-resolve completes successfully
+				await setupEmptyCanonicalConflict(repoDir, defaultBranch);
 
 				const entry = makeTestEntry({
 					branchName: "feature-branch",
@@ -884,7 +1015,8 @@ describe("createMergeResolver", () => {
 			const repoDir = await createTempGitRepo();
 			try {
 				const defaultBranch = await getDefaultBranch(repoDir);
-				await setupContentConflict(repoDir, defaultBranch);
+				// Use empty-canonical setup so auto-resolve completes successfully
+				await setupEmptyCanonicalConflict(repoDir, defaultBranch);
 
 				const entry = makeTestEntry({
 					branchName: "feature-branch",
@@ -1014,7 +1146,8 @@ describe("createMergeResolver", () => {
 			const repoDir = await createTempGitRepo();
 			try {
 				const defaultBranch = await getDefaultBranch(repoDir);
-				await setupContentConflict(repoDir, defaultBranch);
+				// Use empty-canonical setup so auto-resolve completes successfully
+				await setupEmptyCanonicalConflict(repoDir, defaultBranch);
 
 				const entry = makeTestEntry({
 					branchName: "feature-branch",
@@ -1709,7 +1842,8 @@ describe("createMergeResolver", () => {
 			const repoDir = await createTempGitRepo();
 			try {
 				const defaultBranch = await getDefaultBranch(repoDir);
-				await setupContentConflict(repoDir, defaultBranch);
+				// Use empty-canonical setup so auto-resolve completes successfully
+				await setupEmptyCanonicalConflict(repoDir, defaultBranch);
 
 				const entry = makeTestEntry({
 					branchName: "feature-branch",

package/src/merge/resolver.ts

@@ -11,6 +11,7 @@
  * Disabled tiers are skipped. Uses Bun.spawn for all subprocess calls.
  */
 
+import { unlinkSync } from "node:fs";
 import { MergeError } from "../errors.ts";
 import type { MulchClient } from "../mulch/client.ts";
 import { getRuntime } from "../runtimes/registry.ts";
@@ -184,6 +185,24 @@ export function resolveConflictsUnion(content: string): string | null {
 	});
 }
 
+/**
+ * Detect if any conflict block has non-whitespace content on the canonical (HEAD) side.
+ * Returns true if auto-resolving with keep-incoming would silently discard canonical content.
+ * Use this before calling resolveConflictsKeepIncoming to prevent data loss.
+ */
+export function hasContentfulCanonical(content: string): boolean {
+	const conflictPattern = /^<{7} .+\n([\s\S]*?)^={7}\n([\s\S]*?)^>{7} .+\n?/gm;
+	let match = conflictPattern.exec(content);
+	while (match !== null) {
+		const canonical = match[1] ?? "";
+		if (canonical.trim().length > 0) {
+			return true;
+		}
+		match = conflictPattern.exec(content);
+	}
+	return false;
+}
+
 /**
  * Check if a file has the `merge=union` gitattribute set.
  * Returns true if `git check-attr merge -- <file>` ends with ": merge: union".
@@ -231,12 +250,15 @@ async function tryCleanMerge(
 /**
  * Tier 2: Auto-resolve conflicts by keeping incoming (agent) changes.
  * Parses conflict markers and keeps the content between ======= and >>>>>>>.
+ * Skips files where the canonical side has non-whitespace content to prevent
+ * silent data loss — those files are escalated to higher tiers.
  */
 async function tryAutoResolve(
 	conflictFiles: string[],
 	repoRoot: string,
-): Promise<{ success: boolean; remainingConflicts: string[] }> {
+): Promise<{ success: boolean; remainingConflicts: string[]; contentDropWarnings: string[] }> {
 	const remainingConflicts: string[] = [];
+	const contentDropWarnings: string[] = [];
 
 	for (const file of conflictFiles) {
 		const filePath = `${repoRoot}/${file}`;
@@ -244,6 +266,18 @@ async function tryAutoResolve(
 		try {
 			const content = await readFile(filePath);
 			const isUnion = await checkMergeUnion(repoRoot, file);
+
+			// For non-union files, check if the canonical side has content.
+			// If it does, auto-resolving would silently discard that content.
+			// Escalate to a higher tier instead.
+			if (!isUnion && hasContentfulCanonical(content)) {
+				contentDropWarnings.push(
+					`auto-resolve skipped for ${file}: canonical side has content that would be discarded`,
+				);
+				remainingConflicts.push(file);
+				continue;
+			}
+
 			const resolved = isUnion
 				? resolveConflictsUnion(content)
 				: resolveConflictsKeepIncoming(content);
@@ -265,12 +299,12 @@ async function tryAutoResolve(
 	}
 
 	if (remainingConflicts.length > 0) {
-		return { success: false, remainingConflicts };
+		return { success: false, remainingConflicts, contentDropWarnings };
 	}
 
 	// All files resolved — commit
 	const { exitCode } = await runGit(repoRoot, ["commit", "--no-edit"]);
-	return { success: exitCode === 0, remainingConflicts };
+	return { success: exitCode === 0, remainingConflicts, contentDropWarnings };
 }
 
 /**
@@ -689,13 +723,15 @@ export function createMergeResolver(options: {
 				didStash = true;
 			}
 
+			const warnings: string[] = [];
 			let lastTier: ResolutionTier = "clean-merge";
 			let conflictFiles: string[] = [];
 
 			try {
-				// Commit untracked files overlapping entry.filesModified before merging.
+				// Delete untracked files overlapping entry.filesModified before merging.
 				// git merge refuses to run if untracked files in the working tree would
-				// be overwritten by the incoming branch.
+				// be overwritten by the incoming branch. Deleting them lets the merge
+				// proceed and bring in the branch version.
 				const { stdout: untrackedOut } = await runGit(repoRoot, [
 					"ls-files",
 					"--others",
@@ -707,9 +743,18 @@ export function createMergeResolver(options: {
 					.filter((f) => f.length > 0);
 				const entryFileSet = new Set(entry.filesModified);
 				const overlappingUntracked = untrackedFiles.filter((f) => entryFileSet.has(f));
-				if (overlappingUntracked.length > 0) {
-					await runGit(repoRoot, ["add", ...overlappingUntracked]);
-					await runGit(repoRoot, ["commit", "-m", "chore: commit untracked files before merge"]);
+				for (const file of overlappingUntracked) {
+					const filePath = `${repoRoot}/${file}`;
+					try {
+						if (await Bun.file(filePath).exists()) {
+							unlinkSync(filePath);
+						}
+						warnings.push(
+							`untracked file deleted before merge: ${file} (branch version will be used)`,
+						);
+					} catch {
+						// Ignore errors removing untracked files
+					}
 				}
 
 				// Tier 1: Clean merge
@@ -732,6 +777,7 @@ export function createMergeResolver(options: {
 						tier: "clean-merge",
 						conflictFiles: [],
 						errorMessage: null,
+						warnings,
 					};
 				}
 				conflictFiles = cleanResult.conflictFiles;
@@ -750,6 +796,9 @@ export function createMergeResolver(options: {
 				if (!history.skipTiers.includes("auto-resolve")) {
 					lastTier = "auto-resolve";
 					const autoResult = await tryAutoResolve(conflictFiles, repoRoot);
+					if (autoResult.contentDropWarnings.length > 0) {
+						warnings.push(...autoResult.contentDropWarnings);
+					}
 					if (autoResult.success) {
 						if (options.mulchClient) {
 							recordConflictPattern(
@@ -777,6 +826,7 @@ export function createMergeResolver(options: {
 							tier: "auto-resolve",
 							conflictFiles,
 							errorMessage: null,
+							warnings,
 						};
 					}
 					conflictFiles = autoResult.remainingConflicts;
@@ -812,6 +862,7 @@ export function createMergeResolver(options: {
 							tier: "ai-resolve",
 							conflictFiles,
 							errorMessage: null,
+							warnings,
 						};
 					}
 					conflictFiles = aiResult.remainingConflicts;
@@ -847,6 +898,7 @@ export function createMergeResolver(options: {
 							tier: "reimagine",
 							conflictFiles: [],
 							errorMessage: null,
+							warnings,
 						};
 					}
 				}
@@ -868,6 +920,7 @@ export function createMergeResolver(options: {
 					tier: lastTier,
 					conflictFiles,
 					errorMessage: `All enabled resolution tiers failed (last attempted: ${lastTier})`,
+					warnings,
 				};
 			} finally {
 				if (didStash) {

package/src/runtimes/claude.test.ts

@@ -220,14 +220,16 @@ describe("ClaudeRuntime", () => {
 			expect(state).toEqual({ phase: "ready" });
 		});
 
-		test("returns ready for prompt indicator + shift+tab", () => {
+		test("returns loading for prompt indicator + shift+tab (no bypass permissions)", () => {
+			// shift+tab appears in ALL Claude Code sessions — it must NOT trigger ready
 			const state = runtime.detectReady("Claude Code\n\u276f\nshift+tab to chat");
-			expect(state).toEqual({ phase: "ready" });
+			expect(state).toEqual({ phase: "loading" });
 		});
 
-		test('returns ready for Try " + shift+tab', () => {
+		test('returns loading for Try " + shift+tab (no bypass permissions)', () => {
+			// False-positive scenario: shift+tab alone is not a reliable readiness signal
 			const state = runtime.detectReady('Try "help"\nshift+tab');
-			expect(state).toEqual({ phase: "ready" });
+			expect(state).toEqual({ phase: "loading" });
 		});
 
 		test("returns dialog for trust dialog", () => {
@@ -235,6 +237,20 @@ describe("ClaudeRuntime", () => {
 			expect(state).toEqual({ phase: "dialog", action: "Enter" });
 		});
 
+		test("returns dialog for bypass permissions confirmation", () => {
+			const state = runtime.detectReady(
+				"WARNING: Claude Code running in Bypass Permissions mode\n❯ 1. No, exit\n2. Yes, I accept",
+			);
+			expect(state).toEqual({ phase: "dialog", action: "type:2" });
+		});
+
+		test("bypass permissions confirmation takes precedence over ready indicators", () => {
+			const state = runtime.detectReady(
+				"WARNING: Claude Code running in Bypass Permissions mode\n❯ 1. No, exit\n2. Yes, I accept\nbypass permissions",
+			);
+			expect(state).toEqual({ phase: "dialog", action: "type:2" });
+		});
+
 		test("trust dialog takes precedence over ready indicators", () => {
 			const state = runtime.detectReady("trust this folder\n\u276f\nbypass permissions");
 			expect(state).toEqual({ phase: "dialog", action: "Enter" });
@@ -577,9 +593,10 @@ describe("ClaudeRuntime integration: detectReady matches pre-refactor tmux behav
 		expect(state.phase).toBe("ready");
 	});
 
-	test("ready: 'Try \"help\"' + 'shift+tab'", () => {
+	test("loading: 'Try \"help\"' + 'shift+tab' (no bypass permissions — false-positive fix)", () => {
+		// shift+tab appears in all Claude Code sessions, must not trigger ready without bypass permissions
 		const state = runtime.detectReady('Try "help"\nshift+tab');
-		expect(state.phase).toBe("ready");
+		expect(state.phase).toBe("loading");
 	});
 
 	test("not ready: only prompt (no status bar)", () => {
@@ -597,6 +614,14 @@ describe("ClaudeRuntime integration: detectReady matches pre-refactor tmux behav
 		expect(state.phase).toBe("dialog");
 		expect((state as { phase: "dialog"; action: string }).action).toBe("Enter");
 	});
+
+	test("dialog: bypass permissions confirmation", () => {
+		const state = runtime.detectReady(
+			"WARNING: Claude Code running in Bypass Permissions mode\n❯ 1. No, exit\n2. Yes, I accept",
+		);
+		expect(state.phase).toBe("dialog");
+		expect((state as { phase: "dialog"; action: string }).action).toBe("type:2");
+	});
 });
 
 describe("ClaudeRuntime integration: buildEnv matches pre-refactor env injection", () => {
@@ -652,6 +677,6 @@ describe("ClaudeRuntime integration: registry resolves 'claude' as default", ()
 	test("getRuntime rejects unknown runtimes", async () => {
 		const { getRuntime } = await import("./registry.ts");
 		expect(() => getRuntime("aider")).toThrow('Unknown runtime: "aider"');
-		expect(() => getRuntime("cursor")).toThrow('Unknown runtime: "cursor"');
+		expect(() => getRuntime("nonexistent")).toThrow('Unknown runtime: "nonexistent"');
 	});
 });

package/src/runtimes/claude.ts

@@ -31,6 +31,9 @@ export class ClaudeRuntime implements AgentRuntime {
 	/** Unique identifier for this runtime. */
 	readonly id = "claude";
 
+	/** Stability level. Claude Code is the primary runtime. */
+	readonly stability = "stable" as const;
+
 	/** Relative path to the instruction file within a worktree. */
 	readonly instructionPath = ".claude/CLAUDE.md";
 
@@ -136,14 +139,25 @@ export class ClaudeRuntime implements AgentRuntime {
 	 *
 	 * 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" }`
+	 * - Ready: prompt indicator (❯ or 'Try "') AND status bar ("bypass permissions")
+	 *   both present → `{ phase: "ready" }`
 	 * - Otherwise → `{ phase: "loading" }`
 	 *
 	 * @param paneContent - Captured tmux pane content to analyze
 	 * @returns Current readiness phase
 	 */
 	detectReady(paneContent: string): ReadyState {
+		// Claude Code v2.1.71+ shows a dedicated bypass confirmation screen.
+		// It already contains both a prompt marker and the phrase "bypass permissions",
+		// so it must be detected before the normal ready heuristics.
+		if (
+			paneContent.includes("WARNING: Claude Code running in Bypass Permissions mode") &&
+			paneContent.includes("1. No, exit") &&
+			paneContent.includes("2. Yes, I accept")
+		) {
+			return { phase: "dialog", action: "type:2" };
+		}
+
 		// 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")) {
@@ -155,8 +169,9 @@ export class ClaudeRuntime implements AgentRuntime {
 		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");
+		// Only match 'bypass permissions' — 'shift+tab' appears in ALL Claude Code sessions
+		// regardless of permission mode and would cause false-positive ready detection.
+		const hasStatusBar = paneContent.includes("bypass permissions");
 
 		if (hasPrompt && hasStatusBar) {
 			return { phase: "ready" };

package/src/runtimes/codex.test.ts

@@ -151,6 +151,19 @@ describe("CodexRuntime", () => {
 			expect(cmd).not.toContain("This inline content should be ignored");
 		});
 
+		test("sharedWritableDirs are exposed with --add-dir", () => {
+			const opts: SpawnOpts = {
+				model: "gpt-5-codex",
+				permissionMode: "bypass",
+				cwd: "/tmp/worktree",
+				sharedWritableDirs: ["/project/.overstory", "/project/.git"],
+				env: {},
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toContain("--add-dir '/project/.overstory'");
+			expect(cmd).toContain("--add-dir '/project/.git'");
+		});
+
 		test("without appendSystemPrompt uses default AGENTS.md prompt", () => {
 			const opts: SpawnOpts = {
 				model: "gpt-5-codex",

package/src/runtimes/codex.ts

@@ -37,6 +37,9 @@ export class CodexRuntime implements AgentRuntime {
 	/** Unique identifier for this runtime. */
 	readonly id = "codex";
 
+	/** Stability level. Codex adapter is experimental — not fully validated. */
+	readonly stability = "experimental" as const;
+
 	/** Relative path to the instruction file within a worktree. */
 	readonly instructionPath = "AGENTS.md";
 
@@ -46,6 +49,16 @@ export class CodexRuntime implements AgentRuntime {
 	 */
 	private static readonly MANIFEST_ALIASES = new Set(["sonnet", "opus", "haiku"]);
 
+	/**
+	 * Escape a directory path for use in a single-quoted shell argument.
+	 *
+	 * @param path - Absolute directory path
+	 * @returns POSIX shell-safe path string
+	 */
+	private static shellEscape(path: string): string {
+		return path.replace(/'/g, "'\\''");
+	}
+
 	/**
 	 * Build the shell command string to spawn a Codex agent in a tmux pane.
 	 *
@@ -68,16 +81,19 @@ export class CodexRuntime implements AgentRuntime {
 		if (!CodexRuntime.MANIFEST_ALIASES.has(opts.model)) {
 			cmd += ` --model ${opts.model}`;
 		}
+		for (const dir of opts.sharedWritableDirs ?? []) {
+			cmd += ` --add-dir '${CodexRuntime.shellEscape(dir)}'`;
+		}
 
 		if (opts.appendSystemPromptFile) {
 			// Read role definition from file at shell expansion time — avoids tmux
 			// IPC message size limits. Append the "read AGENTS.md" instruction.
-			const escaped = opts.appendSystemPromptFile.replace(/'/g, "'\\''");
+			const escaped = CodexRuntime.shellEscape(opts.appendSystemPromptFile);
 			cmd += ` "$(cat '${escaped}')"' Read AGENTS.md for your task assignment and begin immediately.'`;
 		} else if (opts.appendSystemPrompt) {
 			// Inline role definition + instruction to read AGENTS.md.
 			const prompt = `${opts.appendSystemPrompt}\n\nRead AGENTS.md for your task assignment and begin immediately.`;
-			const escaped = prompt.replace(/'/g, "'\\''");
+			const escaped = CodexRuntime.shellEscape(prompt);
 			cmd += ` '${escaped}'`;
 		} else {
 			cmd += ` 'Read AGENTS.md for your task assignment and begin immediately.'`;

package/src/runtimes/copilot.ts

@@ -28,6 +28,9 @@ export class CopilotRuntime implements AgentRuntime {
 	/** Unique identifier for this runtime. */
 	readonly id = "copilot";
 
+	/** Stability level. Copilot adapter is experimental — not fully validated. */
+	readonly stability = "experimental" as const;
+
 	/** Relative path to the instruction file within a worktree. */
 	readonly instructionPath = ".github/copilot-instructions.md";