oh-my-opencode 4.10.0 → 4.11.0

package/packages/omo-codex/plugin/components/codegraph/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@sisyphuslabs/codex-codegraph",
+	"version": "4.11.0",
+	"description": "Codex plugin MCP wrapper for CodeGraph.",
+	"type": "module",
+	"private": true,
+	"bin": {
+		"omo-codegraph": "./dist/cli.js"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "bun build src/serve.ts --target node --format esm --outfile dist/serve.js && bun build src/cli.ts --target node --format esm --outfile dist/cli.js",
+		"test": "bun test test/*.test.ts",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@oh-my-opencode/utils": "file:../../../../utils",
+		"@types/node": "^25.9.3",
+		"bun-types": "^1.3.1",
+		"typescript": "^6.0.3"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	}
+}

package/packages/omo-codex/plugin/components/codegraph/src/cli.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { stderr as processStderr } from "node:process";
+import { fileURLToPath } from "node:url";
+
+import {
+	runCodegraphSessionStartHook,
+	runCodegraphSessionStartWorker,
+	type SessionStartHookOptions,
+	type SessionStartWorkerOptions,
+} from "./hook.js";
+import { runCodegraphServeCli } from "./serve.js";
+
+export interface RunCodegraphCliOptions extends SessionStartHookOptions {
+	readonly workerOptions?: SessionStartWorkerOptions;
+}
+
+export async function runCodegraphCli(options: RunCodegraphCliOptions = {}): Promise<number> {
+	const argv = options.argv ?? process.argv;
+	const command = argv[2];
+	const subcommand = argv[3];
+
+	if (command === "hook" && subcommand === "session-start") {
+		return runCodegraphSessionStartHook(options);
+	}
+
+	if (command === "hook" && subcommand === "session-start-worker") {
+		const workerOptions: SessionStartWorkerOptions = {
+			...options.workerOptions,
+			...(options.workerOptions?.cwd === undefined && options.cwd !== undefined ? { cwd: options.cwd } : {}),
+			...(options.workerOptions?.env === undefined && options.env !== undefined ? { env: options.env } : {}),
+		};
+		await runCodegraphSessionStartWorker(workerOptions);
+		return 0;
+	}
+
+	await runCodegraphServeCli();
+	return process.exitCode === undefined ? 0 : Number(process.exitCode);
+}
+
+if (isDirectInvocation(process.argv[1])) {
+	runCodegraphCli().catch((error: unknown) => {
+		processStderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+		process.exitCode = 1;
+	});
+}
+
+function isDirectInvocation(argvPath: string | undefined): boolean {
+	if (argvPath === undefined) return false;
+	const modulePath = fileURLToPath(import.meta.url);
+	const moduleName = basename(modulePath);
+	if (moduleName !== "cli.js" && moduleName !== "cli.ts") return false;
+	return realpathSync(resolve(argvPath)) === realpathSync(modulePath);
+}

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

@@ -0,0 +1,83 @@
+import type { Readable } from "node:stream";
+
+import type { CodexOmoConfig as SharedCodexOmoConfig } from "../../../shared/src/config-loader.ts";
+import type { CodegraphProvisionResult as SharedCodegraphProvisionResult } from "../../../../../utils/src/codegraph/provision.ts";
+import type {
+	CodegraphCommandResolution,
+	ResolveCodegraphCommandOptions,
+} from "../../../../../utils/src/codegraph/resolve.ts";
+import type { CodegraphWorkspacePreparation as SharedCodegraphWorkspacePreparation } from "../../../../../utils/src/codegraph/workspace.ts";
+import type { CodegraphConfig as SharedCodegraphConfig } from "../../../../../utils/src/omo-config.ts";
+
+export type SessionStartAction = "skipped-disabled" | "spawned";
+export type WorkerAction = "failed" | "initialized" | "skipped-disabled" | "skipped-status" | "skipped-unavailable" | "skipped-unsupported-node" | "synced";
+
+export interface WorkerSpawnInvocation {
+	readonly args: readonly string[];
+	readonly command: string;
+	readonly env: Record<string, string | undefined>;
+}
+
+export interface HookStdout {
+	readonly write: (chunk: string) => void;
+}
+
+export interface SessionStartHookResult {
+	readonly action: SessionStartAction;
+	readonly exitCode: 0;
+}
+
+export interface CodegraphCommandResult {
+	readonly exitCode: number;
+	readonly stderr?: string;
+	readonly stdout: string;
+	readonly timedOut: boolean;
+}
+
+export type CodegraphConfig = Partial<SharedCodegraphConfig>;
+export type CodexOmoConfig = SharedCodexOmoConfig;
+export type OmoConfigSource = CodexOmoConfig["sources"][number];
+export type CodegraphProvisionResult = SharedCodegraphProvisionResult;
+export type CodegraphWorkspacePreparation = SharedCodegraphWorkspacePreparation;
+
+export interface CodegraphSessionStartOutcome {
+	readonly action: WorkerAction;
+	readonly error?: string;
+	readonly exitCode?: number;
+	readonly projectRoot?: string;
+	readonly source?: CodegraphCommandResolution["source"];
+	readonly timedOut?: boolean;
+}
+
+export interface CodegraphSessionStartDeps {
+	readonly ensureGitignored: (projectRoot: string) => boolean;
+	readonly ensureProvisioned: (options: { readonly installDir?: string; readonly lockDir: string; readonly version: "1.0.1" }) => Promise<CodegraphProvisionResult>;
+	readonly prepareWorkspace: (projectRoot: string, options: { readonly homeDir: string }) => CodegraphWorkspacePreparation;
+	readonly resolveCommand: (options?: ResolveCodegraphCommandOptions) => CodegraphCommandResolution;
+	readonly runCommand: (
+		projectRoot: string,
+		command: string,
+		args: readonly string[],
+		options: { readonly env: Record<string, string>; readonly timeoutMs: number },
+	) => Promise<CodegraphCommandResult>;
+}
+
+export interface SessionStartHookOptions {
+	readonly argv?: readonly string[];
+	readonly config?: CodexOmoConfig;
+	readonly cwd?: string;
+	readonly env?: Record<string, string | undefined>;
+	readonly spawnWorker?: (invocation: WorkerSpawnInvocation) => void;
+	readonly stdin?: Readable & { readonly isTTY?: boolean };
+	readonly stdout?: HookStdout;
+	readonly workerCliPath?: string;
+}
+
+export interface SessionStartWorkerOptions {
+	readonly config?: CodexOmoConfig;
+	readonly cwd?: string;
+	readonly deps?: Partial<CodegraphSessionStartDeps>;
+	readonly env?: Record<string, string | undefined>;
+	readonly logOutcome?: (outcome: CodegraphSessionStartOutcome) => void;
+	readonly nodeVersion?: string;
+}

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

@@ -0,0 +1,108 @@
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { cwd as processCwd, env as processEnv, stdin as processStdin, stdout as processStdout } from "node:process";
+import type { Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
+
+import { getCodexOmoConfig } from "../../../shared/src/config-loader.ts";
+import { SESSION_START_CWD_ENV } from "./session-start-worker.js";
+import type {
+	HookStdout,
+	SessionStartAction,
+	SessionStartHookOptions,
+	SessionStartHookResult,
+	WorkerSpawnInvocation,
+} from "./hook-types.js";
+
+export type {
+	CodegraphCommandResult,
+	CodegraphConfig,
+	CodegraphProvisionResult,
+	CodegraphSessionStartDeps,
+	CodegraphSessionStartOutcome,
+	CodegraphWorkspacePreparation,
+	CodexOmoConfig,
+	HookStdout,
+	OmoConfigSource,
+	SessionStartAction,
+	SessionStartHookOptions,
+	SessionStartHookResult,
+	SessionStartWorkerOptions,
+	WorkerAction,
+	WorkerSpawnInvocation,
+} from "./hook-types.js";
+export { resolveCodegraphCommandInvocation, runCodegraphSessionStartWorker } from "./session-start-worker.js";
+
+export const CODEGRAPH_SESSION_START_NOTICE = "LazyCodex CodeGraph bootstrap scheduled in background";
+
+export async function runCodegraphSessionStartHook(options: SessionStartHookOptions = {}): Promise<number> {
+	return (await executeCodegraphSessionStartHook(options)).exitCode;
+}
+
+export async function executeCodegraphSessionStartHook(options: SessionStartHookOptions = {}): Promise<SessionStartHookResult> {
+	const env = options.env ?? processEnv;
+	const input = await readHookInput(options.stdin ?? processStdin);
+	const projectRoot = resolveProjectRoot(input, options.cwd ?? processCwd());
+	const homeDir = resolveHomeDir(env);
+	const config = options.config ?? getCodexOmoConfig({ cwd: projectRoot, env, homeDir });
+
+	if (config.codegraph?.enabled === false) {
+		writeHookJson(options.stdout ?? processStdout, "skipped-disabled");
+		return { action: "skipped-disabled", exitCode: 0 };
+	}
+
+	(options.spawnWorker ?? spawnDetachedWorker)({
+		args: [options.workerCliPath ?? defaultWorkerCliPath(), "hook", "session-start-worker"],
+		command: process.execPath,
+		env: { ...env, [SESSION_START_CWD_ENV]: projectRoot },
+	});
+	writeHookJson(options.stdout ?? processStdout, "spawned");
+	return { action: "spawned", exitCode: 0 };
+}
+
+function writeHookJson(stdout: HookStdout, action: SessionStartAction): void {
+	const output = action === "spawned"
+		? { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: CODEGRAPH_SESSION_START_NOTICE }, codegraph: { action } }
+		: { hookSpecificOutput: { hookEventName: "SessionStart" }, codegraph: { action } };
+	stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+function spawnDetachedWorker(invocation: WorkerSpawnInvocation): void {
+	const child = spawn(invocation.command, [...invocation.args], { detached: true, env: invocation.env, stdio: "ignore" });
+	child.unref();
+}
+
+function resolveHomeDir(env: Record<string, string | undefined>): string {
+	return env["HOME"] ?? env["USERPROFILE"] ?? homedir();
+}
+
+function resolveProjectRoot(input: unknown, fallback: string): string {
+	if (!isRecord(input)) return fallback;
+	const cwd = input["cwd"];
+	return typeof cwd === "string" && cwd.trim().length > 0 ? cwd : fallback;
+}
+
+async function readHookInput(stdin: Readable & { readonly isTTY?: boolean }): Promise<unknown> {
+	if (stdin.isTTY === true) return undefined;
+	let text = "";
+	for await (const chunk of stdin) text += typeof chunk === "string" ? chunk : String(chunk);
+	if (text.trim().length === 0) return undefined;
+	return parseJson(text);
+}
+
+function parseJson(text: string): unknown {
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		if (error instanceof SyntaxError) return undefined;
+		throw error;
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function defaultWorkerCliPath(): string {
+	return fileURLToPath(import.meta.url);
+}

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

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, extname, join, resolve } from "node:path";
+import {
+	cwd as processCwd,
+	env as processEnv,
+	execPath as processExecPath,
+	stderr as processStderr,
+} from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { buildCodegraphEnv } from "../../../../../utils/src/codegraph/env.ts";
+import {
+	buildCodegraphNodeSkipHint,
+	evaluateCodegraphNodeSupport,
+} from "../../../../../utils/src/codegraph/node-support.ts";
+import {
+	resolveCodegraphCommand,
+	type CodegraphCommandResolution,
+	type ResolveCodegraphCommandOptions,
+} from "../../../../../utils/src/codegraph/resolve.ts";
+import { getCodexOmoConfig, type CodexOmoConfig } from "../../../shared/src/config-loader.ts";
+import type { CodegraphConfig } from "./hook.js";
+
+export type ServeStdio = "inherit";
+
+export interface CodegraphServeProcessOptions {
+	readonly env: Record<string, string | undefined>;
+	readonly stdio: ServeStdio;
+}
+
+export type CodegraphServeProcessRunner = (
+	command: string,
+	args: readonly string[],
+	options: CodegraphServeProcessOptions,
+) => Promise<number>;
+
+export interface ServeProcessInvocation {
+	readonly args: readonly string[];
+	readonly command: string;
+}
+
+export interface CodegraphServeStderr {
+	readonly write: (chunk: string) => void;
+}
+
+export interface RunCodegraphServeOptions {
+	readonly buildEnv?: (options: { readonly homeDir: string }) => Record<string, string>;
+	readonly commandExists?: (filePath: string) => boolean;
+	readonly config?: CodexOmoConfig;
+	readonly cwd?: string;
+	readonly env?: Record<string, string | undefined>;
+	readonly homeDir?: string;
+	readonly nodeVersion?: string;
+	readonly resolve?: (options: ResolveCodegraphCommandOptions) => ReturnType<typeof resolveCodegraphCommand>;
+	readonly runProcess?: CodegraphServeProcessRunner;
+	readonly stderr?: CodegraphServeStderr;
+}
+
+const CODEGRAPH_SKIP_HINT =
+	"CodeGraph MCP skipped: codegraph binary not found. Install CodeGraph or set OMO_CODEGRAPH_BIN.\n";
+const CODEGRAPH_DISABLED_HINT =
+	"CodeGraph MCP skipped: disabled by OMO SOT config. Set [codex].codegraph.enabled=true to enable it.\n";
+const WINDOWS_CMD_EXTENSIONS = new Set([".bat", ".cmd"]);
+const WINDOWS_NODE_SCRIPT_EXTENSIONS = new Set([".cjs", ".js", ".mjs"]);
+
+export async function runCodegraphServe(options: RunCodegraphServeOptions = {}): Promise<number> {
+	const env = options.env ?? processEnv;
+	const homeDir = options.homeDir ?? homedir();
+	const config = options.config ?? getCodexOmoConfig({ cwd: options.cwd ?? processCwd(), env, homeDir });
+	const codegraphConfig = config.codegraph ?? {};
+	if (codegraphConfig.enabled === false) {
+		(options.stderr ?? processStderr).write(CODEGRAPH_DISABLED_HINT);
+		return 1;
+	}
+
+	const resolutionOptions = {
+		env,
+		homeDir,
+		provisioned: () => provisionedBinFromInstallDir(codegraphConfig.install_dir),
+	} satisfies ResolveCodegraphCommandOptions;
+	const resolution = options.resolve?.(resolutionOptions) ?? resolveCodegraphCommand(resolutionOptions);
+	if (!resolution.exists || shouldSkipResolvedCommand(resolution, options.commandExists ?? existsSync)) {
+		(options.stderr ?? processStderr).write(CODEGRAPH_SKIP_HINT);
+		return 1;
+	}
+
+	const nodeSupport = evaluateCodegraphNodeSupport({ env, nodeVersion: options.nodeVersion });
+	if (resolution.source !== "bundled" && resolution.source !== "env" && !nodeSupport.supported) {
+		(options.stderr ?? processStderr).write(buildCodegraphNodeSkipHint(nodeSupport));
+		return 1;
+	}
+
+	const runProcess = options.runProcess ?? runChildProcess;
+	const codegraphEnv = codegraphEnvForConfig(codegraphConfig, homeDir, options.buildEnv);
+	const mergedEnv = {
+		...env,
+		...codegraphEnv,
+	};
+	return runProcess(resolution.command, [...resolution.argsPrefix, "serve", "--mcp"], {
+		env: mergedEnv,
+		stdio: "inherit",
+	});
+}
+
+function shouldSkipResolvedCommand(
+	resolution: CodegraphCommandResolution,
+	commandExists: (filePath: string) => boolean,
+): boolean {
+	if (resolution.source !== "env") return false;
+	if (!looksLikePath(resolution.command)) return false;
+	return !commandExists(resolution.command);
+}
+
+function looksLikePath(command: string): boolean {
+	return command.includes("/") || command.includes("\\");
+}
+
+function codegraphEnvForConfig(
+	config: CodegraphConfig,
+	homeDir: string,
+	buildEnv: ((options: { readonly homeDir: string }) => Record<string, string>) | undefined,
+): Record<string, string> {
+	const env = buildEnv?.({ homeDir }) ?? buildCodegraphEnv({ homeDir });
+	return config.install_dir === undefined ? env : { ...env, CODEGRAPH_INSTALL_DIR: config.install_dir };
+}
+
+function provisionedBinFromInstallDir(installDir: string | undefined): string | null {
+	if (installDir === undefined) return null;
+	const candidate = join(installDir, "bin", process.platform === "win32" ? "codegraph.cmd" : "codegraph");
+	return existsSync(candidate) ? candidate : null;
+}
+
+export async function runCodegraphServeCli(): Promise<void> {
+	process.exitCode = await runCodegraphServe();
+}
+
+async function runChildProcess(
+	command: string,
+	args: readonly string[],
+	options: CodegraphServeProcessOptions,
+): Promise<number> {
+	const invocation = resolveServeProcessInvocation(command, args);
+	const child = spawn(invocation.command, invocation.args, { env: options.env, stdio: options.stdio });
+	return new Promise<number>((resolve, reject) => {
+		child.once("error", reject);
+		child.once("exit", (code, signal) => {
+			if (code !== null) {
+				resolve(code);
+				return;
+			}
+			resolve(signal === null ? 0 : 1);
+		});
+	});
+}
+
+export function resolveServeProcessInvocation(
+	command: string,
+	args: readonly string[],
+	platform: NodeJS.Platform = process.platform,
+): ServeProcessInvocation {
+	if (platform !== "win32") return { args: [...args], command };
+
+	const extension = extname(command).toLowerCase();
+	if (WINDOWS_NODE_SCRIPT_EXTENSIONS.has(extension)) {
+		return { args: [command, ...args], command: processExecPath };
+	}
+
+	if (WINDOWS_CMD_EXTENSIONS.has(extension)) {
+		return { args: ["/d", "/s", "/c", command, ...args], command: "cmd.exe" };
+	}
+
+	return { args: [...args], command };
+}
+
+if (isDirectInvocation(process.argv[1])) {
+	runCodegraphServeCli().catch((error: unknown) => {
+		processStderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+		process.exitCode = 1;
+	});
+}
+
+function isDirectInvocation(argvPath: string | undefined): boolean {
+	if (argvPath === undefined) return false;
+	const modulePath = fileURLToPath(import.meta.url);
+	const moduleName = basename(modulePath);
+	if (moduleName !== "serve.js" && moduleName !== "serve.ts") return false;
+	return realpathSync(resolve(argvPath)) === realpathSync(modulePath);
+}

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

@@ -0,0 +1,213 @@
+import { execFile } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { extname, join } from "node:path";
+import { cwd as processCwd, env as processEnv, stderr as processStderr } from "node:process";
+
+import { getCodexOmoConfig } from "../../../shared/src/config-loader.ts";
+import { buildCodegraphEnv } from "../../../../../utils/src/codegraph/env.ts";
+import { evaluateCodegraphNodeSupport, type CodegraphNodeSupport } from "../../../../../utils/src/codegraph/node-support.ts";
+import { ensureCodegraphProvisioned } from "../../../../../utils/src/codegraph/provision.ts";
+import {
+	resolveCodegraphCommand,
+	type CodegraphCommandResolution,
+} from "../../../../../utils/src/codegraph/resolve.ts";
+import { ensureCodegraphGitignored, prepareCodegraphWorkspace } from "../../../../../utils/src/codegraph/workspace.ts";
+import type {
+	CodegraphCommandResult,
+	CodegraphConfig,
+	CodegraphSessionStartDeps,
+	CodegraphSessionStartOutcome,
+	SessionStartWorkerOptions,
+	WorkerAction,
+} from "./hook-types.js";
+
+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"]);
+
+const defaultDeps: CodegraphSessionStartDeps = {
+	ensureGitignored: ensureCodegraphGitignored,
+	ensureProvisioned: ensureCodegraphProvisioned,
+	prepareWorkspace: prepareCodegraphWorkspace,
+	resolveCommand: resolveCodegraphCommand,
+	runCommand: runCodegraphCommand,
+};
+
+export async function runCodegraphSessionStartWorker(options: SessionStartWorkerOptions = {}): Promise<{ readonly action: WorkerAction }> {
+	const env = options.env ?? processEnv;
+	const homeDir = resolveHomeDir(env);
+	const projectRoot = options.cwd ?? env[SESSION_START_CWD_ENV] ?? processCwd();
+	const config = options.config ?? getCodexOmoConfig({ cwd: projectRoot, env, homeDir });
+	const logOutcome = options.logOutcome ?? ((outcome) => appendOutcome(homeDir, outcome));
+
+	if (config.codegraph?.enabled === false) {
+		return finish("skipped-disabled", { projectRoot }, logOutcome);
+	}
+
+	const nodeSupport = evaluateCodegraphNodeSupport({ env, nodeVersion: options.nodeVersion });
+	return runBootstrap(projectRoot, config.codegraph ?? {}, env, homeDir, nodeSupport, { ...defaultDeps, ...options.deps }, logOutcome);
+}
+
+async function runBootstrap(
+	projectRoot: string,
+	config: CodegraphConfig,
+	env: Record<string, string | undefined>,
+	homeDir: string,
+	nodeSupport: CodegraphNodeSupport,
+	deps: CodegraphSessionStartDeps,
+	logOutcome: (outcome: CodegraphSessionStartOutcome) => void,
+): Promise<{ readonly action: WorkerAction }> {
+	try {
+		const command = await resolveOrProvisionCommand(deps, config, env, homeDir, nodeSupport);
+		if (command.kind === "unavailable") {
+			return finish("skipped-unavailable", { error: command.error, projectRoot, source: command.source }, logOutcome);
+		}
+		if (command.kind === "unsupported-node") {
+			return finish("skipped-unsupported-node", { projectRoot }, logOutcome);
+		}
+
+		deps.prepareWorkspace(projectRoot, { homeDir });
+		deps.ensureGitignored(projectRoot);
+		const codegraphEnv = config.install_dir === undefined ? buildCodegraphEnv({ homeDir }) : { ...buildCodegraphEnv({ homeDir }), CODEGRAPH_INSTALL_DIR: config.install_dir };
+		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);
+
+		const actionArgs = command.resolution.argsPrefix.concat(decision.kind === "init" ? ["init"] : ["sync"]);
+		const action = await deps.runCommand(projectRoot, command.resolution.command, actionArgs, { env: codegraphEnv, timeoutMs: COMMAND_TIMEOUT_MS });
+		return finish(decision.kind === "init" ? "initialized" : "synced", { exitCode: action.exitCode, projectRoot, source: command.resolution.source, timedOut: action.timedOut }, logOutcome);
+	} catch (error) {
+		return finish("failed", { error: error instanceof Error ? error.message : String(error), projectRoot }, logOutcome);
+	}
+}
+
+function finish(action: WorkerAction, detail: Omit<CodegraphSessionStartOutcome, "action">, logOutcome: (outcome: CodegraphSessionStartOutcome) => void): { readonly action: WorkerAction } {
+	safeLogOutcome(logOutcome, { ...detail, action });
+	return { action };
+}
+
+type ResolutionResult =
+	| { readonly kind: "resolved"; readonly resolution: CodegraphCommandResolution }
+	| { readonly kind: "unsupported-node" }
+	| { readonly error: string; readonly kind: "unavailable"; readonly projectRoot?: string; readonly source: CodegraphCommandResolution["source"] };
+
+async function resolveOrProvisionCommand(
+	deps: CodegraphSessionStartDeps,
+	config: CodegraphConfig,
+	env: Record<string, string | undefined>,
+	homeDir: string,
+	nodeSupport: CodegraphNodeSupport,
+): Promise<ResolutionResult> {
+	const resolved = deps.resolveCommand({ env, homeDir, provisioned: () => provisionedBinFromInstallDir(config.install_dir) });
+	if (resolved.exists) {
+		if (resolved.source !== "bundled" && resolved.source !== "env" && !nodeSupport.supported) {
+			return { kind: "unsupported-node" };
+		}
+		return { kind: "resolved", resolution: resolved };
+	}
+	if (!nodeSupport.supported) 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 });
+	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 decideStartupAction(status: CodegraphCommandResult): { readonly kind: "init" } | { readonly kind: "skip"; readonly reason: string } | { readonly kind: "sync" } {
+	if (status.timedOut) return { kind: "skip", reason: "status timed out" };
+	const text = `${status.stdout}\n${status.stderr ?? ""}`.toLowerCase();
+	if (text.includes("not initialized") || text.includes("uninitialized")) return { kind: "init" };
+	const initialized = jsonSaysInitialized(parseJson(status.stdout));
+	if (initialized === false) return { kind: "init" };
+	if (initialized === true) return { kind: "sync" };
+	if (status.exitCode !== 0) return { kind: "skip", reason: `status exited ${status.exitCode}` };
+	return { kind: "sync" };
+}
+
+function jsonSaysInitialized(value: unknown): boolean | undefined {
+	if (!isRecord(value)) return undefined;
+	const initialized = value["initialized"] ?? value["isInitialized"] ?? value["ready"];
+	if (typeof initialized === "boolean") return initialized;
+	const status = value["status"];
+	if (typeof status !== "string") return undefined;
+	const normalized = status.toLowerCase();
+	if (normalized.includes("not initialized") || normalized.includes("uninitialized")) return false;
+	if (normalized.includes("initialized") || normalized.includes("ready")) return true;
+	return undefined;
+}
+
+async function runCodegraphCommand(projectRoot: string, command: string, args: readonly string[], options: { readonly env: Record<string, string>; readonly timeoutMs: number }): Promise<CodegraphCommandResult> {
+	const invocation = resolveCodegraphCommandInvocation(command, args);
+	return new Promise((resolvePromise) => {
+		execFile(invocation.command, [...invocation.args], { cwd: projectRoot, encoding: "utf8", env: { ...process.env, ...options.env }, maxBuffer: 1024 * 1024, timeout: options.timeoutMs, windowsHide: true }, (error, stdout, stderr) => {
+			if (error === null) {
+				resolvePromise({ exitCode: 0, stderr: toOutputText(stderr), stdout: toOutputText(stdout), timedOut: false });
+				return;
+			}
+			resolvePromise({ exitCode: resolveExitCode(error), stderr: toOutputText(stderr), stdout: toOutputText(stdout), timedOut: error.killed === true });
+		});
+	});
+}
+
+export function resolveCodegraphCommandInvocation(
+	command: string,
+	args: readonly string[],
+	platform: NodeJS.Platform = process.platform,
+): { readonly args: readonly string[]; readonly command: string } {
+	if (platform !== "win32") return { args: [...args], command };
+	if (!WINDOWS_CMD_EXTENSIONS.has(extname(command).toLowerCase())) return { args: [...args], command };
+	return { args: ["/d", "/s", "/c", command, ...args], command: "cmd.exe" };
+}
+
+function appendOutcome(homeDir: string, outcome: CodegraphSessionStartOutcome): void {
+	const logDir = join(homeDir, ".omo", "codegraph");
+	mkdirSync(logDir, { recursive: true });
+	appendFileSync(join(logDir, "session-start.jsonl"), `${JSON.stringify({ ...outcome, timestamp: new Date().toISOString() })}\n`);
+}
+
+function safeLogOutcome(logOutcome: (outcome: CodegraphSessionStartOutcome) => void, outcome: CodegraphSessionStartOutcome): void {
+	try {
+		logOutcome(outcome);
+	} catch (error) {
+		if (error instanceof Error) processStderr.write(`[codegraph-session-start] failed to write outcome: ${error.message}\n`);
+		else throw error;
+	}
+}
+
+function provisionedBinFromInstallDir(installDir: string | undefined): string | null {
+	if (installDir === undefined) return null;
+	const candidate = join(installDir, "bin", process.platform === "win32" ? "codegraph.cmd" : "codegraph");
+	return existsSync(candidate) ? candidate : null;
+}
+
+function resolveExitCode(error: Error): number {
+	if ("code" in error && typeof error.code === "number") return error.code;
+	return 1;
+}
+
+function toOutputText(value: string | Buffer): string {
+	return Buffer.isBuffer(value) ? value.toString("utf8") : value;
+}
+
+function resolveHomeDir(env: Record<string, string | undefined>): string {
+	return env["HOME"] ?? env["USERPROFILE"] ?? homedir();
+}
+
+function parseJson(text: string): unknown {
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		if (error instanceof SyntaxError) return undefined;
+		throw error;
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}