oh-my-opencode 4.12.1 → 4.13.0

package/packages/omo-codex/plugin/components/codegraph/src/session-start-worker.ts

@@ -28,6 +28,9 @@ export const SESSION_START_CWD_ENV = "OMO_CODEGRAPH_SESSION_START_CWD";
 const CODEGRAPH_VERSION = "1.0.1";
 const COMMAND_TIMEOUT_MS = 60_000;
 const WINDOWS_CMD_EXTENSIONS = new Set([".bat", ".cmd"]);
+type CodegraphBootstrapConfig = CodegraphConfig & {
+	readonly trustedCodegraphInstallDir?: string;
+};
 
 const defaultDeps: CodegraphSessionStartDeps = {
 	ensureGitignored: ensureCodegraphGitignored,
@@ -49,12 +52,16 @@ export async function runCodegraphSessionStartWorker(options: SessionStartWorker
 	}
 
 	const nodeSupport = evaluateCodegraphNodeSupport({ env, nodeVersion: options.nodeVersion });
-	return runBootstrap(projectRoot, config.codegraph ?? {}, env, homeDir, nodeSupport, { ...defaultDeps, ...options.deps }, logOutcome);
+	const bootstrapConfig: CodegraphBootstrapConfig = {
+		...(config.codegraph ?? {}),
+		...(config.trustedCodegraphInstallDir === undefined ? {} : { trustedCodegraphInstallDir: config.trustedCodegraphInstallDir }),
+	};
+	return runBootstrap(projectRoot, bootstrapConfig, env, homeDir, nodeSupport, { ...defaultDeps, ...options.deps }, logOutcome);
 }
 
 async function runBootstrap(
 	projectRoot: string,
-	config: CodegraphConfig,
+	config: CodegraphBootstrapConfig,
 	env: Record<string, string | undefined>,
 	homeDir: string,
 	nodeSupport: CodegraphNodeSupport,
@@ -72,7 +79,7 @@ async function runBootstrap(
 
 		deps.prepareWorkspace(projectRoot, { homeDir });
 		deps.ensureGitignored(projectRoot);
-		const codegraphEnv = config.install_dir === undefined ? buildCodegraphEnv({ homeDir }) : { ...buildCodegraphEnv({ homeDir }), CODEGRAPH_INSTALL_DIR: config.install_dir };
+		const codegraphEnv = codegraphEnvForConfig(config, homeDir);
 		const status = await deps.runCommand(projectRoot, command.resolution.command, [...command.resolution.argsPrefix, "status", "--json"], { env: codegraphEnv, timeoutMs: COMMAND_TIMEOUT_MS });
 		const decision = decideStartupAction(status);
 		if (decision.kind === "skip") return finish("skipped-status", { error: decision.reason, projectRoot }, logOutcome);
@@ -97,26 +104,32 @@ type ResolutionResult =
 
 async function resolveOrProvisionCommand(
 	deps: CodegraphSessionStartDeps,
-	config: CodegraphConfig,
+	config: CodegraphBootstrapConfig,
 	env: Record<string, string | undefined>,
 	homeDir: string,
 	nodeSupport: CodegraphNodeSupport,
 ): Promise<ResolutionResult> {
-	const resolved = deps.resolveCommand({ env, homeDir, provisioned: () => provisionedBinFromInstallDir(config.install_dir) });
+	const trustedInstallDir = config.trustedCodegraphInstallDir;
+	const resolved = deps.resolveCommand({ env, homeDir, provisioned: () => provisionedBinFromInstallDir(trustedInstallDir) });
 	if (resolved.exists && canUseResolvedCommand(resolved, nodeSupport)) {
 		return { kind: "resolved", resolution: resolved };
 	}
 	if (resolved.exists && config.auto_provision === false) return { kind: "unsupported-node" };
 	if (config.auto_provision === false) return { error: "codegraph binary unavailable and auto_provision is disabled", kind: "unavailable", source: resolved.source };
 
-	const installDir = config.install_dir ?? join(homeDir, ".omo", "codegraph");
-	const provisioned = await deps.ensureProvisioned({ installDir, lockDir: join(installDir, "locks"), version: CODEGRAPH_VERSION });
+	const installDir = trustedInstallDir ?? join(homeDir, ".omo", "codegraph");
+	const provisioned = await deps.ensureProvisioned({ installDir, lockDir: join(installDir, ".locks"), version: CODEGRAPH_VERSION });
 	if (!provisioned.provisioned || provisioned.binPath === undefined) {
 		return { error: provisioned.error ?? "provisioning did not produce a binary", kind: "unavailable", source: resolved.source };
 	}
 	return { kind: "resolved", resolution: { argsPrefix: [], command: provisioned.binPath, exists: true, source: "provisioned" } };
 }
 
+function codegraphEnvForConfig(config: CodegraphBootstrapConfig, homeDir: string): Record<string, string> {
+	const env = buildCodegraphEnv({ homeDir });
+	return config.trustedCodegraphInstallDir === undefined ? env : { ...env, CODEGRAPH_INSTALL_DIR: config.trustedCodegraphInstallDir };
+}
+
 function canUseResolvedCommand(resolved: CodegraphCommandResolution, nodeSupport: CodegraphNodeSupport): boolean {
 	return !codegraphCommandRequiresSupportedLocalNode(resolved) || nodeSupport.supported;
 }

package/packages/omo-codex/plugin/components/codegraph/test/hook.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { Readable } from "node:stream";
@@ -8,9 +8,7 @@ import { fileURLToPath } from "node:url";
 import { runCodegraphCli } from "../src/cli.ts";
 import {
 	executeCodegraphSessionStartHook,
-	resolveCodegraphCommandInvocation,
 	runCodegraphPostToolUseHook,
-	runCodegraphSessionStartWorker,
 	type WorkerSpawnInvocation,
 } from "../src/hook.ts";
 
@@ -247,236 +245,6 @@ describe("CodeGraph SessionStart hook", () => {
 		}
 	});
 
-	it("#given CodeGraph cannot be resolved or provisioned #when worker runs #then it logs a graceful skip", async () => {
-		// given
-		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-"));
-		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-home-"));
-		const outcomes: unknown[] = [];
-		const calls: string[] = [];
-
-		try {
-			// when
-			const result = await runCodegraphSessionStartWorker({
-				cwd: workspace,
-				env: { HOME: homeDir },
-				nodeVersion: "22.14.0",
-				logOutcome: (outcome) => outcomes.push(outcome),
-				deps: {
-					ensureGitignored: () => {
-						calls.push("ensureGitignored");
-						return true;
-					},
-					ensureProvisioned: () => Promise.resolve({ error: "offline", provisioned: false }),
-					prepareWorkspace: () => {
-						calls.push("prepareWorkspace");
-						return {
-							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
-							dataRoot: join(homeDir, ".omo/codegraph"),
-							linked: true,
-							mode: "global-linked",
-							projectLink: join(workspace, ".codegraph"),
-						};
-					},
-					resolveCommand: () => ({ argsPrefix: [], command: "codegraph", exists: false, source: "path" }),
-					runCommand: () => {
-						calls.push("runCommand");
-						return Promise.resolve({ exitCode: 0, stdout: "", timedOut: false });
-					},
-				},
-			});
-
-			// then
-			expect(result).toEqual({ action: "skipped-unavailable" });
-			expect(calls).toEqual([]);
-			expect(outcomes).toEqual([
-				{
-					action: "skipped-unavailable",
-					error: "offline",
-					projectRoot: workspace,
-					source: "path",
-				},
-			]);
-		} finally {
-			rmSync(workspace, { recursive: true, force: true });
-			rmSync(homeDir, { recursive: true, force: true });
-		}
-	});
-
-	it("#given CodeGraph is unavailable and auto provisioning is disabled #when worker runs #then it leaves the project untouched", async () => {
-		// given
-		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-unavailable-"));
-		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-unavailable-home-"));
-		const outcomes: unknown[] = [];
-
-		try {
-			// when
-			const result = await runCodegraphSessionStartWorker({
-				config: { codegraph: { auto_provision: false, enabled: true }, sources: [], warnings: [] },
-				nodeVersion: "22.14.0",
-				cwd: workspace,
-				env: { HOME: homeDir },
-				logOutcome: (outcome) => outcomes.push(outcome),
-				deps: {
-					ensureProvisioned: () => {
-						throw new Error("auto provision should not run");
-					},
-					resolveCommand: () => ({ argsPrefix: [], command: "missing-codegraph", exists: false, source: "path" }),
-					runCommand: () => {
-						throw new Error("codegraph command should not run");
-					},
-				},
-			});
-
-			// then
-			expect(result).toEqual({ action: "skipped-unavailable" });
-			expect(existsSync(join(workspace, ".codegraph"))).toBe(false);
-			expect(existsSync(join(workspace, ".git", "info", "exclude"))).toBe(false);
-			expect(outcomes).toEqual([
-				{
-					action: "skipped-unavailable",
-					error: "codegraph binary unavailable and auto_provision is disabled",
-					projectRoot: workspace,
-					source: "path",
-				},
-			]);
-		} finally {
-			rmSync(workspace, { recursive: true, force: true });
-			rmSync(homeDir, { recursive: true, force: true });
-		}
-	});
-
-	it("#given Windows install_dir has codegraph.cmd #when worker resolves provisioned CodeGraph #then it uses the cmd shim", async () => {
-		await withProcessPlatform("win32", async () => {
-			// given
-			const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-"));
-			const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-home-"));
-			const installDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-install-"));
-			const binPath = join(installDir, "bin", "codegraph.cmd");
-			const calls: { readonly args: readonly string[]; readonly command: string; readonly env: Record<string, string> }[] = [];
-			const outcomes: unknown[] = [];
-			try {
-				mkdirSync(join(installDir, "bin"), { recursive: true });
-				writeFileSync(binPath, "");
-
-				// when
-				const result = await runCodegraphSessionStartWorker({
-					config: { codegraph: { enabled: true, install_dir: installDir }, sources: [], warnings: [] },
-					nodeVersion: "22.14.0",
-					cwd: workspace,
-					env: { HOME: homeDir },
-					logOutcome: (outcome) => outcomes.push(outcome),
-					deps: {
-						ensureGitignored: () => true,
-						ensureProvisioned: () => {
-							throw new Error("provisioning should not run when install_dir binary exists");
-						},
-						prepareWorkspace: () => ({
-							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
-							dataRoot: join(homeDir, ".omo/codegraph"),
-							linked: true,
-							mode: "global-linked",
-							projectLink: join(workspace, ".codegraph"),
-						}),
-						resolveCommand: (options) => {
-							const provisioned = options?.provisioned?.() ?? null;
-							return { argsPrefix: [], command: provisioned ?? "missing-codegraph", exists: provisioned !== null, source: provisioned === null ? "path" : "provisioned" };
-						},
-						runCommand: (_projectRoot, command, args, options) => {
-							calls.push({ args, command, env: options.env });
-							return Promise.resolve({ exitCode: 0, stdout: calls.length === 1 ? '{"initialized":false}' : "", timedOut: false });
-						},
-					},
-				});
-
-				// then
-				expect(result).toEqual({ action: "initialized" });
-				expect(calls.map((call) => ({ args: [...call.args], command: call.command }))).toEqual([
-					{ args: ["status", "--json"], command: binPath },
-					{ args: ["init"], command: binPath },
-				]);
-				expect(calls[0]?.env["CODEGRAPH_INSTALL_DIR"]).toBe(installDir);
-				expect(outcomes).toEqual([{ action: "initialized", exitCode: 0, projectRoot: workspace, source: "provisioned", timedOut: false }]);
-			} finally {
-				rmSync(workspace, { recursive: true, force: true });
-				rmSync(homeDir, { recursive: true, force: true });
-				rmSync(installDir, { recursive: true, force: true });
-			}
-		});
-	});
-
-	it("#given Windows codegraph.cmd #when default worker runner builds invocation #then it runs through cmd.exe", () => {
-		// given
-		const command = "C:\\Users\\test\\.omo\\codegraph\\bin\\codegraph.cmd";
-
-		// when
-		const invocation = resolveCodegraphCommandInvocation(command, ["status", "--json"], "win32");
-
-		// then
-		expect(invocation).toEqual({
-			args: ["/d", "/s", "/c", command, "status", "--json"],
-			command: "cmd.exe",
-		});
-	});
-
-	it("#given non-Windows codegraph command #when default worker runner builds invocation #then it executes directly", () => {
-		// given
-		const command = "/home/test/.omo/codegraph/bin/codegraph";
-
-		// when
-		const invocation = resolveCodegraphCommandInvocation(command, ["sync"], "linux");
-
-		// then
-		expect(invocation).toEqual({ args: ["sync"], command });
-	});
-
-	it("#given resolved CodeGraph status #when worker runs #then it runs status before init or sync", async () => {
-		for (const scenario of [
-			{ action: "initialized", args: [["status", "--json"], ["init"]], stdout: '{"initialized":false}' },
-			{ action: "synced", args: [["status", "--json"], ["sync"]], stdout: '{"initialized":true}' },
-		] as const) {
-			// given
-			const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-status-"));
-			const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-status-home-"));
-			const calls: { readonly args: readonly string[]; readonly command: string; readonly env: Record<string, string> }[] = [];
-			const outcomes: unknown[] = [];
-			try {
-				// when
-				const result = await runCodegraphSessionStartWorker({
-					config: { codegraph: { enabled: true, install_dir: "/tmp/codegraph-install" }, sources: [], warnings: [] },
-					nodeVersion: "22.14.0",
-					cwd: workspace,
-					env: { HOME: homeDir },
-					logOutcome: (outcome) => outcomes.push(outcome),
-					deps: {
-						ensureGitignored: () => true,
-						ensureProvisioned: () => Promise.resolve({ binPath: "/tmp/codegraph", provisioned: true }),
-						prepareWorkspace: () => ({
-							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
-							dataRoot: join(homeDir, ".omo/codegraph"),
-							linked: true,
-							mode: "global-linked",
-							projectLink: join(workspace, ".codegraph"),
-						}),
-						resolveCommand: () => ({ argsPrefix: [], command: "/tmp/codegraph", exists: true, source: "path" }),
-						runCommand: (_projectRoot, command, args, options) => {
-							calls.push({ args, command, env: options.env });
-							return Promise.resolve({ exitCode: 0, stdout: calls.length === 1 ? scenario.stdout : "", timedOut: false });
-						},
-					},
-				});
-
-				// then
-				expect(result).toEqual({ action: scenario.action });
-				expect(calls.map((call) => [...call.args])).toEqual(scenario.args.map((args) => [...args]));
-				expect(calls[0]?.env["CODEGRAPH_INSTALL_DIR"]).toBe("/tmp/codegraph-install");
-				expect(outcomes).toEqual([{ action: scenario.action, exitCode: 0, projectRoot: workspace, source: "path", timedOut: false }]);
-			} finally {
-				rmSync(workspace, { recursive: true, force: true });
-				rmSync(homeDir, { recursive: true, force: true });
-			}
-		}
-	});
-
 	it("#given malformed hook input with CodeGraph disabled #when SessionStart fires #then it stays silent and exits zero", async () => {
 		// given
 		const stdout: string[] = [];
@@ -514,13 +282,3 @@ describe("CodeGraph SessionStart hook", () => {
 		);
 	});
 });
-
-async function withProcessPlatform(platform: NodeJS.Platform, run: () => Promise<void>): Promise<void> {
-	const descriptor = Object.getOwnPropertyDescriptor(process, "platform");
-	Object.defineProperty(process, "platform", { configurable: true, enumerable: true, value: platform });
-	try {
-		await run();
-	} finally {
-		if (descriptor !== undefined) Object.defineProperty(process, "platform", descriptor);
-	}
-}

package/packages/omo-codex/plugin/components/codegraph/test/package-runtime.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+type CodegraphPackageJson = {
+	readonly files?: readonly string[];
+	readonly optionalDependencies?: Readonly<Record<string, string>>;
+};
+
+const componentRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = resolve(componentRoot, "../../../../..");
+
+function readCodegraphPackageJson(): CodegraphPackageJson {
+	const parsed: unknown = JSON.parse(readFileSync(resolve(componentRoot, "package.json"), "utf8"));
+	if (!isCodegraphPackageJson(parsed)) throw new TypeError("Invalid CodeGraph package metadata");
+	return parsed;
+}
+
+function isCodegraphPackageJson(value: unknown): value is CodegraphPackageJson {
+	return isRecord(value) && maybeStringArray(value["files"]) && maybeStringRecord(value["optionalDependencies"]);
+}
+
+function maybeStringArray(value: unknown): value is readonly string[] | undefined {
+	return value === undefined || (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+
+function maybeStringRecord(value: unknown): value is Readonly<Record<string, string>> | undefined {
+	return value === undefined || (isRecord(value) && Object.values(value).every((item) => typeof item === "string"));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+describe("CodeGraph component runtime package metadata", () => {
+	it("#given the CodeGraph component package #when validating runtime distribution metadata #then upstream CodeGraph installs optionally with shipped legal files", () => {
+		// given
+		const packageJson = readCodegraphPackageJson();
+
+		// when
+		const optionalDependencies = packageJson.optionalDependencies ?? {};
+		const files = packageJson.files ?? [];
+
+		// then
+		expect(optionalDependencies["@colbymchenry/codegraph"]).toBe("1.0.1");
+		expect(files).toContain("LICENSE");
+		expect(files).toContain("NODE-RUNTIME-LICENSES.md");
+		expect(files).toContain("NOTICE");
+		expect(existsSync(resolve(componentRoot, "LICENSE"))).toBe(true);
+		expect(existsSync(resolve(componentRoot, "NODE-RUNTIME-LICENSES.md"))).toBe(true);
+		expect(existsSync(resolve(componentRoot, "NOTICE"))).toBe(true);
+		expect(existsSync(resolve(componentRoot, "dist", "cli.d.ts"))).toBe(false);
+		expect(existsSync(resolve(componentRoot, "dist", "serve.d.ts"))).toBe(false);
+	});
+
+	it("#given marketplace payload includes only the plugin tree #when reading CodeGraph NOTICE #then it is self-contained", () => {
+		// given
+		const notice = readFileSync(resolve(componentRoot, "NOTICE"), "utf8");
+
+		expect(notice).toContain("@colbymchenry/codegraph@1.0.1");
+		expect(notice).toContain("MIT license");
+		expect(notice).toContain("Node.js v24.16.0 runtime");
+		expect(notice).toContain("NODE-RUNTIME-LICENSES.md");
+		expect(notice).not.toContain("packages/omo-codex/THIRD-PARTY-NOTICES.md");
+	});
+
+	it("#given CodeGraph platform bundles include Node #when reading runtime licenses #then Node license text ships with the component", () => {
+		// given
+		const licenseText = readFileSync(resolve(componentRoot, "NODE-RUNTIME-LICENSES.md"), "utf8");
+
+		// then
+		expect(licenseText).toContain("Node.js v24.16.0 LICENSE text");
+		expect(licenseText).toContain("Copyright Node.js contributors");
+		expect(licenseText).toContain("The externally maintained libraries used by Node.js are:");
+	});
+
+	it("#given third-party notices #when validating CodeGraph component notices #then aggregate Codex notices list CodeGraph as shipped", () => {
+		// given
+		const codexNotice = readFileSync(resolve(repoRoot, "packages/omo-codex/THIRD-PARTY-NOTICES.md"), "utf8");
+
+		// when
+		const listsCodegraphComponent = codexNotice.includes("@sisyphuslabs/codex-codegraph");
+		const listsUpstreamRuntime = codexNotice.includes("@colbymchenry/codegraph");
+
+		// then
+		expect(listsCodegraphComponent).toBe(true);
+		expect(listsUpstreamRuntime).toBe(true);
+		expect(codexNotice).not.toContain("not currently an omo-codex plugin component");
+	});
+});

package/packages/omo-codex/plugin/components/codegraph/test/provisioned-node-guard.test.ts

@@ -45,7 +45,7 @@ describe("CodeGraph provisioned launcher Node guard", () => {
 
 			// when
 			const result = await runCodegraphSessionStartWorker({
-				config: { codegraph: { enabled: true, install_dir: installDir }, sources: [], warnings: [] },
+				config: { codegraph: { enabled: true, install_dir: installDir }, sources: [], trustedCodegraphInstallDir: installDir, warnings: [] },
 				nodeVersion: "26.3.0",
 				cwd: workspace,
 				env: { HOME: homeDir },

package/packages/omo-codex/plugin/components/codegraph/test/serve-mcp-facade.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "bun:test";
+import { PassThrough } from "node:stream";
+
+import { runCodegraphServe } from "../src/serve.ts";
+
+describe("runCodegraphServe MCP unavailable facade", () => {
+	it("#given CodeGraph is unavailable #when an MCP client initializes #then it answers with an empty-tool facade", async () => {
+		// given
+		const input = new PassThrough();
+		const output = new PassThrough();
+		const stderr: string[] = [];
+		let stdout = "";
+		output.on("data", (chunk: Buffer) => {
+			stdout += chunk.toString("utf8");
+		});
+
+		const run = runCodegraphServe({
+			config: { codegraph: { auto_provision: false, enabled: true }, sources: [], warnings: [] },
+			env: { PATH: "/bin" },
+			buildEnv: () => ({}),
+			resolve: () => ({ argsPrefix: [], command: "codegraph", exists: false, source: "path" }),
+			stderr: { write: (chunk: string) => stderr.push(chunk) },
+			stdin: input,
+			stdout: output,
+		});
+
+		// when
+		input.end(frameMcpRequest({
+			id: 1,
+			method: "initialize",
+			params: {
+				capabilities: {},
+				clientInfo: { name: "ulw-red", version: "0.0.0" },
+				protocolVersion: "2025-06-18",
+			},
+		}));
+		const exitCode = await run;
+
+		// then
+		expect(exitCode).toBe(0);
+		expect(stderr).toEqual([
+			"CodeGraph MCP skipped: codegraph binary not found. Install CodeGraph or set OMO_CODEGRAPH_BIN.\n",
+		]);
+		expect(parseFirstJsonRpcBody(stdout)).toEqual({
+			id: 1,
+			jsonrpc: "2.0",
+			result: {
+				capabilities: { tools: { listChanged: false } },
+				protocolVersion: "2025-06-18",
+				serverInfo: { name: "codegraph", version: "1.0.1" },
+			},
+		});
+	});
+});
+
+function frameMcpRequest(request: {
+	readonly id: number;
+	readonly method: string;
+	readonly params: Record<string, unknown>;
+}): string {
+	const body = JSON.stringify({ jsonrpc: "2.0", ...request });
+	return `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+}
+
+function parseFirstJsonRpcBody(transcript: string): unknown {
+	const [, body = ""] = transcript.split("\r\n\r\n", 2);
+	return JSON.parse(body);
+}

package/packages/omo-codex/plugin/components/codegraph/test/serve-node-support.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "bun:test";
+import { PassThrough } from "node:stream";
 
 import { CODEGRAPH_UNSAFE_NODE_ENV } from "../../../../../utils/src/codegraph/node-support.ts";
 import { runCodegraphServe } from "../src/serve.ts";
@@ -11,6 +12,7 @@ describe("runCodegraphServe node support", () => {
 
 		// when
 		const exitCode = await runCodegraphServe({
+			...closedMcpStdio(),
 			env: { PATH: "/bin" },
 			nodeVersion: "26.3.0",
 			buildEnv: () => ({}),
@@ -23,7 +25,7 @@ describe("runCodegraphServe node support", () => {
 		});
 
 		// then
-		expect(exitCode).toBe(1);
+		expect(exitCode).toBe(0);
 		expect(spawned).toEqual([]);
 		expect(stderr).toHaveLength(1);
 		expect(stderr[0]).toContain("CodeGraph MCP skipped");
@@ -31,3 +33,11 @@ describe("runCodegraphServe node support", () => {
 		expect(stderr[0]).toContain(CODEGRAPH_UNSAFE_NODE_ENV);
 	});
 });
+
+function closedMcpStdio(): { readonly stdin: PassThrough; readonly stdout: PassThrough } {
+	const stdin = new PassThrough();
+	const stdout = new PassThrough();
+	stdout.resume();
+	stdin.end();
+	return { stdin, stdout };
+}

package/packages/omo-codex/plugin/components/codegraph/test/serve-unavailable.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PassThrough } from "node:stream";
+
+import { runCodegraphServe } from "../src/serve.ts";
+
+describe("runCodegraphServe unavailable CodeGraph paths", () => {
+	it("#given CodeGraph is unresolved #when serving MCP #then exposes an empty facade with a skip hint", async () => {
+		// given
+		const stderr: string[] = [];
+		const spawned: string[] = [];
+
+		// when
+		const exitCode = await runCodegraphServe({
+			...closedMcpStdio(),
+			config: { codegraph: { auto_provision: false, enabled: true }, sources: [], warnings: [] },
+			env: { PATH: "/bin" },
+			buildEnv: () => ({}),
+			resolve: () => ({ argsPrefix: [], command: "codegraph", exists: false, source: "path" }),
+			runProcess: (command: string) => {
+				spawned.push(command);
+				return Promise.resolve(0);
+			},
+			stderr: { write: (chunk: string) => stderr.push(chunk) },
+		});
+
+		// then
+		expect(exitCode).toBe(0);
+		expect(spawned).toEqual([]);
+		expect(stderr).toEqual([
+			"CodeGraph MCP skipped: codegraph binary not found. Install CodeGraph or set OMO_CODEGRAPH_BIN.\n",
+		]);
+	});
+
+	it("#given an unsupported local Node #when serving MCP #then exposes an empty facade without spawning codegraph", async () => {
+		// given
+		const stderr: string[] = [];
+		const spawned: string[] = [];
+
+		// when
+		const exitCode = await runCodegraphServe({
+			...closedMcpStdio(),
+			env: {},
+			nodeVersion: "26.3.0",
+			buildEnv: () => ({}),
+			resolve: () => ({ argsPrefix: [], command: "codegraph", exists: true, source: "path" }),
+			runProcess: (command: string) => {
+				spawned.push(command);
+				return Promise.resolve(0);
+			},
+			stderr: { write: (chunk: string) => stderr.push(chunk) },
+		});
+
+		// then
+		expect(exitCode).toBe(0);
+		expect(spawned).toEqual([]);
+		expect(stderr).toHaveLength(1);
+		expect(stderr[0]).toContain("CodeGraph MCP skipped");
+		expect(stderr[0]).toContain("CODEGRAPH_ALLOW_UNSAFE_NODE");
+	});
+
+	it("#given OMO_CODEGRAPH_BIN points at a missing path #when serving MCP #then exposes an empty facade before spawn", async () => {
+		// given
+		const stderr: string[] = [];
+		const spawned: string[] = [];
+
+		// when
+		const exitCode = await runCodegraphServe({
+			...closedMcpStdio(),
+			buildEnv: () => ({}),
+			commandExists: () => false,
+			resolve: () => ({ argsPrefix: [], command: "/nonexistent", exists: true, source: "env" }),
+			runProcess: (command: string) => {
+				spawned.push(command);
+				return Promise.resolve(0);
+			},
+			stderr: { write: (chunk: string) => stderr.push(chunk) },
+		});
+
+		// then
+		expect(exitCode).toBe(0);
+		expect(spawned).toEqual([]);
+		expect(stderr).toEqual([
+			"CodeGraph MCP skipped: codegraph binary not found. Install CodeGraph or set OMO_CODEGRAPH_BIN.\n",
+		]);
+	});
+
+	it("#given Codex SOT disables CodeGraph #when serving MCP #then exposes an empty facade with a disabled hint", async () => {
+		// given
+		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-serve-disabled-home-"));
+		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-serve-disabled-workspace-"));
+		const stderr: string[] = [];
+		const spawned: string[] = [];
+		try {
+			mkdirSync(join(homeDir, ".omo"), { recursive: true });
+			mkdirSync(join(workspace, ".omo"), { recursive: true });
+			writeFileSync(join(homeDir, ".omo", "config.jsonc"), '{ "codegraph": { "enabled": true } }\n');
+			writeFileSync(join(workspace, ".omo", "config.jsonc"), '{ "[codex]": { "codegraph": { "enabled": false } } }\n');
+
+			// when
+			const exitCode = await runCodegraphServe({
+				...closedMcpStdio(),
+				cwd: workspace,
+				env: { HOME: homeDir },
+				runProcess: (command: string) => {
+					spawned.push(command);
+					return Promise.resolve(0);
+				},
+				stderr: { write: (chunk: string) => stderr.push(chunk) },
+			});
+
+			// then
+			expect(exitCode).toBe(0);
+			expect(spawned).toEqual([]);
+			expect(stderr).toEqual([
+				"CodeGraph MCP skipped: disabled by OMO SOT config. Set [codex].codegraph.enabled=true to enable it.\n",
+			]);
+		} finally {
+			rmSync(homeDir, { recursive: true, force: true });
+			rmSync(workspace, { recursive: true, force: true });
+		}
+	});
+});
+
+function closedMcpStdio(): { readonly stdin: PassThrough; readonly stdout: PassThrough } {
+	const stdin = new PassThrough();
+	const stdout = new PassThrough();
+	stdout.resume();
+	stdin.end();
+	return { stdin, stdout };
+}