@os-eco/overstory-cli 0.9.2 → 0.9.3

package/README.md

@@ -295,6 +295,7 @@ overstory/
       checkpoint.ts               Session checkpoint save/restore
       lifecycle.ts                Handoff orchestration
       hooks-deployer.ts           Deploy hooks + tool enforcement
+      copilot-hooks-deployer.ts   Deploy hooks config to Copilot worktrees
       guard-rules.ts              Shared guard constants (tool lists, bash patterns)
     worktree/                     Git worktree + tmux management
     mail/                         SQLite mail system (typed protocol, broadcast)

package/agents/coordinator.md

@@ -319,16 +319,16 @@ When a batch is complete (task group auto-closed, all issues resolved):
 4. **Only then** close the issue: `{{TRACKER_CLI}} close <id> --reason "Merged branch <branch-name>"`.
 
 1. Verify all issues are closed: run `{{TRACKER_CLI}} show <id>` for each issue in the group.
-2. Verify all branches are merged: check `ov status` for unmerged branches. If any branch is unmerged, do NOT proceed — wait for the lead's `merge_ready` signal.
-3. Clean up worktrees: `ov worktree clean --completed`.
-4. Record orchestration insights: `ml record <domain> --type <type> --classification <foundational|tactical|observational> --description "<insight>"`.
-5. Commit and sync state files: after all work is merged and issues are closed, commit any outstanding state changes so runtime state is not left uncommitted when the coordinator goes idle:
+2. Verify all branches are merged: check `ov status` for unmerged branches. If any branch is unmerged, do NOT proceed — wait for the lead's `merge_ready` signal. **Note:** merged branches carry each worker's committed `.mulch/` changes into the canonical branch — this is how discovery scout findings reach the main repo.
+3. Record orchestration insights: `ml record <domain> --type <type> --classification <foundational|tactical|observational> --description "<insight>"`.
+4. Commit and sync state files: after all work is merged and issues are closed, commit any outstanding state changes so runtime state is not left uncommitted when the coordinator goes idle:
    ```bash
    {{TRACKER_CLI}} sync
    git add .overstory/ .mulch/
    git diff --cached --quiet || git commit -m "chore: sync runtime state"
    git push
    ```
+5. Clean up worktrees: `ov worktree clean --completed`. **Only run this after branches are merged and .mulch/ state is committed** — cleaning worktrees before merging destroys any uncommitted scout findings.
 6. Report to the human operator: summarize what was accomplished, what was merged, any issues encountered.
 7. Check for follow-up work: `{{TRACKER_CLI}} ready` to see if new issues surfaced during the batch.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.9.2",
+	"version": "0.9.3",
 	"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/copilot-hooks-deployer.test.ts

@@ -0,0 +1,162 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import { deployCopilotHooks } from "./copilot-hooks-deployer.ts";
+import { PATH_PREFIX } from "./hooks-deployer.ts";
+
+describe("deployCopilotHooks", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-copilot-hooks-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	test("writes hooks.json to .github/hooks/ directory", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "my-builder");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const exists = await Bun.file(hooksPath).exists();
+		expect(exists).toBe(true);
+	});
+
+	test("creates .github/hooks/ directory if it does not exist", async () => {
+		const worktreePath = join(tempDir, "new-worktree");
+		// Directory does not exist before the call
+		await deployCopilotHooks(worktreePath, "builder-1");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		expect(await Bun.file(hooksPath).exists()).toBe(true);
+	});
+
+	test("output file is valid JSON", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const raw = await Bun.file(hooksPath).text();
+		expect(() => JSON.parse(raw)).not.toThrow();
+	});
+
+	test("output has Copilot schema structure (top-level hooks with onSessionStart)", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as Record<string, unknown>;
+
+		expect(config).toHaveProperty("hooks");
+		const hooks = config.hooks as Record<string, unknown>;
+		expect(hooks).toHaveProperty("onSessionStart");
+		expect(Array.isArray(hooks.onSessionStart)).toBe(true);
+	});
+
+	test("replaces {{AGENT_NAME}} with agentName in all commands", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "scout-agent-42");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const raw = await Bun.file(hooksPath).text();
+
+		expect(raw).toContain("scout-agent-42");
+		expect(raw).not.toContain("{{AGENT_NAME}}");
+	});
+
+	test("prepends PATH_PREFIX to all hook commands", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "builder-1");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: Record<string, Array<{ command: string }>>;
+		};
+
+		const allCommands = Object.values(config.hooks)
+			.flat()
+			.map((e) => e.command);
+		expect(allCommands.length).toBeGreaterThan(0);
+		for (const cmd of allCommands) {
+			expect(cmd).toStartWith(PATH_PREFIX);
+		}
+	});
+
+	test("onSessionStart entries are objects with command field only (no matcher, no type)", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "builder-1");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: { onSessionStart: Array<Record<string, unknown>> };
+		};
+
+		for (const entry of config.hooks.onSessionStart) {
+			expect(typeof entry.command).toBe("string");
+			// Copilot schema has no matcher or type fields
+			expect(entry).not.toHaveProperty("matcher");
+			expect(entry).not.toHaveProperty("type");
+		}
+	});
+
+	test("onSessionStart includes ov prime command", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "prime-test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: { onSessionStart: Array<{ command: string }> };
+		};
+
+		const commands = config.hooks.onSessionStart.map((e) => e.command);
+		expect(commands.some((c) => c.includes("ov prime") && c.includes("prime-test-agent"))).toBe(
+			true,
+		);
+	});
+
+	test("onSessionStart includes ov mail check --inject command", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "mail-test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: { onSessionStart: Array<{ command: string }> };
+		};
+
+		const commands = config.hooks.onSessionStart.map((e) => e.command);
+		expect(
+			commands.some((c) => c.includes("ov mail check --inject") && c.includes("mail-test-agent")),
+		).toBe(true);
+	});
+
+	test("all hook commands include ENV_GUARD pattern", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "guard-test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: Record<string, Array<{ command: string }>>;
+		};
+
+		const allCommands = Object.values(config.hooks)
+			.flat()
+			.map((e) => e.command);
+		for (const cmd of allCommands) {
+			expect(cmd).toContain("OVERSTORY_AGENT_NAME");
+		}
+	});
+
+	test("template file exists and is valid JSON after substitution", async () => {
+		// Verify template file is present and parseable (basic template health check).
+		const templatePath = join(import.meta.dir, "..", "..", "templates", "copilot-hooks.json.tmpl");
+		const exists = await Bun.file(templatePath).exists();
+		expect(exists).toBe(true);
+
+		const raw = (await Bun.file(templatePath).text()).replace(/\{\{AGENT_NAME\}\}/g, "test");
+		expect(() => JSON.parse(raw)).not.toThrow();
+	});
+});

package/src/agents/copilot-hooks-deployer.ts

@@ -0,0 +1,93 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { AgentError } from "../errors.ts";
+import { PATH_PREFIX } from "./hooks-deployer.ts";
+
+/** Copilot hook entry shape — simpler than Claude Code (no matcher, no type field). */
+interface CopilotHookEntry {
+	command: string;
+}
+
+/**
+ * Resolve the path to the Copilot hooks template file.
+ * The template lives at `templates/copilot-hooks.json.tmpl` relative to the repo root.
+ */
+function getTemplatePath(): string {
+	// src/agents/copilot-hooks-deployer.ts -> repo root is ../../
+	return join(dirname(import.meta.dir), "..", "templates", "copilot-hooks.json.tmpl");
+}
+
+/**
+ * Deploy Copilot lifecycle hooks to an agent's worktree.
+ *
+ * Reads `templates/copilot-hooks.json.tmpl`, replaces all `{{AGENT_NAME}}` tokens,
+ * prepends PATH_PREFIX to every hook command so CLIs (ov, ml, sd) resolve correctly
+ * under Copilot's minimal PATH, then writes the result to
+ * `<worktreePath>/.github/hooks/hooks.json`.
+ *
+ * Phase 1: lifecycle hooks only (onSessionStart). No security guards.
+ *
+ * @param worktreePath - Absolute path to the agent's git worktree
+ * @param agentName - The unique name of the agent (replaces {{AGENT_NAME}} in template)
+ * @throws {AgentError} If the template is missing or the write fails
+ */
+export async function deployCopilotHooks(worktreePath: string, agentName: string): Promise<void> {
+	const templatePath = getTemplatePath();
+	const file = Bun.file(templatePath);
+	const exists = await file.exists();
+
+	if (!exists) {
+		throw new AgentError(`Copilot hooks template not found: ${templatePath}`, {
+			agentName,
+		});
+	}
+
+	let template: string;
+	try {
+		template = await file.text();
+	} catch (err) {
+		throw new AgentError(`Failed to read Copilot hooks template: ${templatePath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	// Replace all occurrences of {{AGENT_NAME}}
+	let content = template;
+	while (content.includes("{{AGENT_NAME}}")) {
+		content = content.replace("{{AGENT_NAME}}", agentName);
+	}
+
+	// Parse the base config from the template
+	const config = JSON.parse(content) as { hooks: Record<string, CopilotHookEntry[]> };
+
+	// Extend PATH in all hook commands.
+	// Copilot CLI executes hooks with a minimal PATH — ~/.bun/bin (where ov, ml, sd live)
+	// is not included. Prepend PATH_PREFIX so CLIs resolve correctly.
+	for (const entries of Object.values(config.hooks)) {
+		for (const entry of entries) {
+			entry.command = `${PATH_PREFIX} ${entry.command}`;
+		}
+	}
+
+	const hooksDir = join(worktreePath, ".github", "hooks");
+	const outputPath = join(hooksDir, "hooks.json");
+
+	try {
+		await mkdir(hooksDir, { recursive: true });
+	} catch (err) {
+		throw new AgentError(`Failed to create .github/hooks/ directory at: ${hooksDir}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	try {
+		await Bun.write(outputPath, `${JSON.stringify(config, null, "\t")}\n`);
+	} catch (err) {
+		throw new AgentError(`Failed to write Copilot hooks config to: ${outputPath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}

package/src/beads/client.ts

@@ -194,9 +194,37 @@ export function createBeadsClient(cwd: string): BeadsClient {
 			if (options?.limit !== undefined) {
 				args.push("--limit", String(options.limit));
 			}
-			const { stdout } = await runBd(args, "list");
-			const raw = parseJsonOutput<RawBeadIssue[]>(stdout, "list");
-			return raw.map(normalizeIssue);
+			try {
+				const { stdout } = await runBd(args, "list");
+				const trimmed = stdout.trim();
+				if (trimmed === "") return [];
+				const parsed: unknown = JSON.parse(trimmed);
+				if (Array.isArray(parsed)) {
+					// Flat format: RawBeadIssue[]
+					return (parsed as RawBeadIssue[]).map(normalizeIssue);
+				}
+				if (typeof parsed === "object" && parsed !== null) {
+					// Tree format: { mol: RawBeadIssue[] } — flatten all groups
+					const tree = parsed as Record<string, unknown>;
+					const issues: BeadIssue[] = [];
+					for (const group of Object.values(tree)) {
+						if (Array.isArray(group)) {
+							for (const item of group) {
+								issues.push(normalizeIssue(item as RawBeadIssue));
+							}
+						}
+					}
+					if (issues.length > 0) return issues;
+				}
+			} catch {
+				// fall through to ready fallback
+			}
+			// Fallback: bd ready --json always returns a flat array
+			const { stdout: readyStdout } = await runBd(["ready", "--json"], "ready (list fallback)");
+			const readyTrimmed = readyStdout.trim();
+			if (readyTrimmed === "") return [];
+			const readyRaw = parseJsonOutput<RawBeadIssue[]>(readyTrimmed, "ready (list fallback)");
+			return readyRaw.map(normalizeIssue);
 		},
 	};
 }

package/src/commands/coordinator.ts

@@ -38,6 +38,7 @@ import {
 	isSessionAlive,
 	killSession,
 	sendKeys,
+	TMUX_SOCKET,
 	waitForTuiReady,
 } from "../worktree/tmux.ts";
 import { nudgeAgent } from "./nudge.ts";
@@ -630,7 +631,7 @@ export async function startCoordinatorSession(
 		}
 
 		if (shouldAttach) {
-			Bun.spawnSync(["tmux", "attach-session", "-t", tmuxSession], {
+			Bun.spawnSync(["tmux", "-L", TMUX_SOCKET, "attach-session", "-t", tmuxSession], {
 				stdio: ["inherit", "inherit", "inherit"],
 			});
 		}

package/src/commands/dashboard.ts

@@ -46,6 +46,7 @@ import type {
 	MailMessage,
 	OverstoryConfig,
 	StoredEvent,
+	TaskTrackerBackend,
 } from "../types.ts";
 import { evaluateHealth } from "../watchdog/health.ts";
 import { isProcessAlive } from "../worktree/tmux.ts";
@@ -356,6 +357,7 @@ async function loadDashboardData(
 	thresholds?: { staleMs: number; zombieMs: number },
 	eventBuffer?: EventBuffer,
 	runtimeConfig?: OverstoryConfig["runtime"],
+	taskTrackerBackend?: TaskTrackerBackend,
 ): Promise<DashboardData> {
 	// Get all sessions from the pre-opened session store — fall back to cache on SQLite errors.
 	let allSessions: AgentSession[];
@@ -516,7 +518,7 @@ async function loadDashboardData(
 	const now2 = Date.now();
 	if (!trackerCache || now2 - trackerCache.fetchedAt > TRACKER_CACHE_TTL_MS) {
 		try {
-			const backend = await resolveBackend("auto", root);
+			const backend = await resolveBackend(taskTrackerBackend ?? "auto", root);
 			const tracker = createTrackerClient(backend, root);
 			tasks = await tracker.list({ limit: 10 });
 			trackerCache = { tasks, fetchedAt: now2 };
@@ -1104,6 +1106,7 @@ async function executeDashboard(opts: DashboardOpts): Promise<void> {
 				thresholds,
 				eventBuffer,
 				config.runtime,
+				config.taskTracker.backend,
 			);
 			lastGoodData = data;
 			// If recovering from an error, clear the stale error line at the bottom

package/src/commands/init.ts

@@ -149,6 +149,39 @@ async function onboardTool(
 	}
 }
 
+/**
+ * Known runtime CLI candidates in detection priority order.
+ * First installed runtime wins.
+ */
+const RUNTIME_CANDIDATES: Array<{ name: string; cli: string }> = [
+	{ name: "claude", cli: "claude" },
+	{ name: "copilot", cli: "copilot" },
+	{ name: "gemini", cli: "gemini" },
+	{ name: "opencode", cli: "opencode" },
+	{ name: "sapling", cli: "sp" },
+	{ name: "pi", cli: "pi" },
+];
+
+/**
+ * Detect the default runtime by checking which coding agent CLIs are installed.
+ *
+ * Uses `which <cli>` via the spawner abstraction so detection is testable
+ * without real binaries on PATH. Returns the first installed runtime by
+ * priority order, or "claude" as the safe fallback.
+ *
+ * @param spawner - Spawner abstraction (defaults to Bun.spawn wrapper)
+ * @returns Runtime name suitable for config.runtime.default
+ */
+export async function detectDefaultRuntime(spawner: Spawner): Promise<string> {
+	for (const { name, cli } of RUNTIME_CANDIDATES) {
+		const result = await spawner(["which", cli]);
+		if (result.exitCode === 0) {
+			return name;
+		}
+	}
+	return "claude";
+}
+
 /**
  * Set up .gitattributes with merge=union entries for JSONL files.
  *
@@ -739,6 +772,12 @@ export async function initCommand(opts: InitOptions): Promise<void> {
 	// 2. Detect project info
 	const projectName = opts.name ?? (await detectProjectName(projectRoot));
 	const canonicalBranch = await detectCanonicalBranch(projectRoot);
+	let defaultRuntime = "claude";
+	try {
+		defaultRuntime = await detectDefaultRuntime(spawner);
+	} catch {
+		// Non-fatal: fall back to claude if runtime detection fails
+	}
 
 	process.stdout.write(`Initializing overstory for "${projectName}"...\n\n`);
 
@@ -775,6 +814,9 @@ export async function initCommand(opts: InitOptions): Promise<void> {
 	config.project.name = projectName;
 	config.project.root = projectRoot;
 	config.project.canonicalBranch = canonicalBranch;
+	if (config.runtime) {
+		config.runtime.default = defaultRuntime;
+	}
 
 	const configYaml = serializeConfigToYaml(config);
 	const configPath = join(overstoryPath, "config.yaml");

package/src/commands/inspect.ts

@@ -18,6 +18,7 @@ import { renderHeader, separator, stateIconColored } from "../logging/theme.ts";
 import { createMetricsStore } from "../metrics/store.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession, StoredEvent, ToolStats } from "../types.ts";
+import { TMUX_SOCKET } from "../worktree/tmux.ts";
 
 /**
  * Extract current file from most recent Edit/Write/Read tool_start event.
@@ -72,10 +73,13 @@ function summarizeArgs(toolArgs: string | null): string {
  */
 async function captureTmux(sessionName: string, lines: number): Promise<string | null> {
 	try {
-		const proc = Bun.spawn(["tmux", "capture-pane", "-t", sessionName, "-p", "-S", `-${lines}`], {
-			stdout: "pipe",
-			stderr: "pipe",
-		});
+		const proc = Bun.spawn(
+			["tmux", "-L", TMUX_SOCKET, "capture-pane", "-t", sessionName, "-p", "-S", `-${lines}`],
+			{
+				stdout: "pipe",
+				stderr: "pipe",
+			},
+		);
 		const exitCode = await proc.exited;
 		if (exitCode !== 0) {
 			return null;

package/src/commands/monitor.ts

@@ -25,7 +25,13 @@ import { printHint, printSuccess } from "../logging/color.ts";
 import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession } from "../types.ts";
-import { createSession, isSessionAlive, killSession, sendKeys } from "../worktree/tmux.ts";
+import {
+	createSession,
+	isSessionAlive,
+	killSession,
+	sendKeys,
+	TMUX_SOCKET,
+} from "../worktree/tmux.ts";
 import { isRunningAsRoot } from "./sling.ts";
 
 /** Default monitor agent name. */
@@ -215,7 +221,7 @@ async function startMonitor(opts: { json: boolean; attach: boolean }): Promise<v
 		}
 
 		if (shouldAttach) {
-			Bun.spawnSync(["tmux", "attach-session", "-t", tmuxSession], {
+			Bun.spawnSync(["tmux", "-L", TMUX_SOCKET, "attach-session", "-t", tmuxSession], {
 				stdio: ["inherit", "inherit", "inherit"],
 			});
 		}

package/src/commands/sling.ts

@@ -806,6 +806,11 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			// Resolve runtime before overlayConfig so we can pass runtime.instructionPath
 			const runtime = getRuntime(opts.runtime, config, capability);
 
+			// Runtime-specific worktree preparation (e.g., Copilot folder trust)
+			if (runtime.prepareWorktree) {
+				await runtime.prepareWorktree(worktreePath);
+			}
+
 			const overlayConfig: OverlayConfig = {
 				agentName: name,
 				taskId: taskId,

package/src/index.ts

@@ -51,7 +51,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.9.2";
+export const VERSION = "0.9.3";
 
 const rawArgs = process.argv.slice(2);
 

package/src/runtimes/codex.test.ts

@@ -203,7 +203,7 @@ describe("CodexRuntime", () => {
 			expect(cmd1).toBe(cmd2);
 		});
 
-		test("all model names pass through unchanged", () => {
+		test("all bare model names pass through unchanged", () => {
 			for (const model of ["gpt-5-codex", "gpt-4o", "o3", "custom-model-v2"]) {
 				const opts: SpawnOpts = {
 					model,
@@ -216,6 +216,30 @@ describe("CodexRuntime", () => {
 			}
 		});
 
+		test("provider-prefixed model strips prefix (openai/gpt-5.4 → gpt-5.4)", () => {
+			const opts: SpawnOpts = {
+				model: "openai/gpt-5.4",
+				permissionMode: "bypass",
+				cwd: "/tmp",
+				env: {},
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toContain("--model gpt-5.4");
+			expect(cmd).not.toContain("openai/");
+		});
+
+		test("provider-prefixed model with other providers strips prefix", () => {
+			const opts: SpawnOpts = {
+				model: "azure/gpt-4o",
+				permissionMode: "bypass",
+				cwd: "/tmp",
+				env: {},
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toContain("--model gpt-4o");
+			expect(cmd).not.toContain("azure/");
+		});
+
 		test("systemPrompt field is ignored", () => {
 			const opts: SpawnOpts = {
 				model: "gpt-5-codex",
@@ -248,6 +272,19 @@ describe("CodexRuntime", () => {
 			]);
 		});
 
+		test("provider-prefixed model strips prefix (openai/gpt-5.4 → gpt-5.4)", () => {
+			const argv = runtime.buildPrintCommand("Classify this error", "openai/gpt-5.4");
+			expect(argv).toEqual([
+				"codex",
+				"exec",
+				"--full-auto",
+				"--ephemeral",
+				"--model",
+				"gpt-5.4",
+				"Classify this error",
+			]);
+		});
+
 		test("model undefined omits --model flag", () => {
 			const argv = runtime.buildPrintCommand("Hello", undefined);
 			expect(argv).not.toContain("--model");

package/src/runtimes/codex.ts

@@ -49,6 +49,21 @@ export class CodexRuntime implements AgentRuntime {
 	 */
 	private static readonly MANIFEST_ALIASES = new Set(["sonnet", "opus", "haiku"]);
 
+	/**
+	 * Strip a provider prefix from a model ID.
+	 *
+	 * Codex CLI expects bare model names. The orchestrator may resolve a model to
+	 * a provider-qualified form (e.g. `"openai/gpt-5.4"`) — strip the `"openai/"`
+	 * prefix before passing to the CLI.
+	 *
+	 * @param model - Possibly provider-qualified model ID
+	 * @returns Bare model name (everything after the first `/`, or unchanged if no `/`)
+	 */
+	private static stripProviderPrefix(model: string): string {
+		const slashIdx = model.indexOf("/");
+		return slashIdx !== -1 ? model.slice(slashIdx + 1) : model;
+	}
+
 	/**
 	 * Escape a directory path for use in a single-quoted shell argument.
 	 *
@@ -75,11 +90,14 @@ export class CodexRuntime implements AgentRuntime {
 	 * @returns Shell command string suitable for tmux new-session -c
 	 */
 	buildSpawnCommand(opts: SpawnOpts): string {
+		// Strip provider prefix before alias check and model flag injection.
+		// Codex CLI expects bare model names (e.g. "gpt-5.4", not "openai/gpt-5.4").
+		const bareModel = CodexRuntime.stripProviderPrefix(opts.model);
 		// When model comes from default manifest aliases (sonnet/opus/haiku),
 		// omit --model so Codex uses the user's configured default model.
 		let cmd = "codex --full-auto";
-		if (!CodexRuntime.MANIFEST_ALIASES.has(opts.model)) {
-			cmd += ` --model ${opts.model}`;
+		if (!CodexRuntime.MANIFEST_ALIASES.has(bareModel)) {
+			cmd += ` --model ${bareModel}`;
 		}
 		for (const dir of opts.sharedWritableDirs ?? []) {
 			cmd += ` --add-dir '${CodexRuntime.shellEscape(dir)}'`;
@@ -119,7 +137,8 @@ export class CodexRuntime implements AgentRuntime {
 	buildPrintCommand(prompt: string, model?: string): string[] {
 		const cmd = ["codex", "exec", "--full-auto", "--ephemeral"];
 		if (model !== undefined) {
-			cmd.push("--model", model);
+			// Strip provider prefix — Codex CLI expects bare model names.
+			cmd.push("--model", CodexRuntime.stripProviderPrefix(model));
 		}
 		cmd.push(prompt);
 		return cmd;