oh-my-opencode 4.19.2 → 4.19.4

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

@@ -1,6 +1,6 @@
 {
 	"name": "@sisyphuslabs/codex-codegraph",
-	"version": "4.19.2",
+	"version": "4.19.4",
 	"description": "Codex plugin MCP wrapper for CodeGraph.",
 	"type": "module",
 	"private": true,
@@ -25,7 +25,7 @@
 		"typescript": "^6.0.3"
 	},
 	"optionalDependencies": {
-		"@colbymchenry/codegraph": "1.4.1"
+		"@colbymchenry/codegraph": "1.5.0"
 	},
 	"engines": {
 		"node": ">=20.0.0"

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

@@ -0,0 +1,33 @@
+import { homedir } from "node:os";
+import type { Readable } from "node:stream";
+
+export function resolveHomeDir(env: Record<string, string | undefined>): string {
+	return env["HOME"] ?? env["USERPROFILE"] ?? homedir();
+}
+
+export function resolveHookProjectRoot(input: unknown, fallback: string): string {
+	if (!isRecord(input)) return fallback;
+	const cwd = input["cwd"];
+	return typeof cwd === "string" && cwd.trim().length > 0 ? cwd : fallback;
+}
+
+export 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);
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function parseJson(text: string): unknown {
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		if (error instanceof SyntaxError) return undefined;
+		throw error;
+	}
+}

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

@@ -10,10 +10,32 @@ import type {
 } 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";
+import type { CodegraphAncestorState, CodegraphProjectState } from "./session-start-project.js";
 
-export type SessionStartAction = "skipped-disabled" | "skipped-excluded" | "skipped-initialized" | "spawned";
+export type SessionStartAction =
+	| "skipped-cooldown"
+	| "skipped-disabled"
+	| "skipped-excluded"
+	| "skipped-inconclusive"
+	| "skipped-initialized"
+	| "skipped-locked"
+	| "skipped-nested-root"
+	| "skipped-spawn-error"
+	| "spawned";
 export type PostToolUseAction = "emitted-guidance" | "skipped";
-export type WorkerAction = "failed" | "initialized" | "skipped-disabled" | "skipped-status" | "skipped-unavailable" | "skipped-unsupported-node" | "synced";
+export type WorkerAction =
+	| "failed"
+	| "initialized"
+	| "skipped-disabled"
+	| "skipped-initialized"
+	| "skipped-locked"
+	| "skipped-nested-root"
+	| "skipped-probe-error"
+	| "skipped-status"
+	| "skipped-unavailable"
+	| "skipped-unsupported-node"
+	| "synced";
+export type SessionStartOutcomeAction = SessionStartAction | WorkerAction;
 
 export interface WorkerSpawnInvocation {
 	readonly args: readonly string[];
@@ -49,9 +71,12 @@ export type CodegraphProvisionResult = SharedCodegraphProvisionResult;
 export type CodegraphWorkspacePreparation = SharedCodegraphWorkspacePreparation;
 
 export interface CodegraphSessionStartOutcome {
-	readonly action: WorkerAction;
+	readonly action: SessionStartOutcomeAction;
+	readonly ancestorRoot?: string;
+	readonly cooldownUntil?: number;
 	readonly error?: string;
 	readonly exitCode?: number;
+	readonly failureCount?: number;
 	readonly projectRoot?: string;
 	readonly source?: CodegraphCommandResolution["source"];
 	readonly timedOut?: boolean;
@@ -60,8 +85,10 @@ export interface CodegraphSessionStartOutcome {
 export interface CodegraphSessionStartDeps {
 	readonly ensureGitignored: (projectRoot: string) => boolean;
 	readonly ensureProvisioned: (options: { readonly installDir?: string; readonly lockDir: string; readonly version: typeof CODEGRAPH_PINNED_VERSION }) => Promise<CodegraphProvisionResult>;
+	readonly managedInstallExists: (installDir: string) => boolean;
 	readonly prepareWorkspace: (projectRoot: string, options: { readonly homeDir: string }) => CodegraphWorkspacePreparation;
 	readonly resolveCommand: (options?: ResolveCodegraphCommandOptions) => CodegraphCommandResolution;
+	readonly resolveManagedBin: (installDir: string) => string | null;
 	readonly runCommand: (
 		projectRoot: string,
 		command: string,
@@ -71,18 +98,15 @@ export interface CodegraphSessionStartDeps {
 }
 
 export interface SessionStartHookOptions {
+	readonly ancestorProbe?: (projectRoot: string) => CodegraphAncestorState;
 	readonly argv?: readonly string[];
 	readonly config?: CodexOmoConfig;
 	readonly cwd?: string;
 	readonly env?: Record<string, string | undefined>;
+	readonly lockStaleMs?: number;
+	readonly logOutcome?: (outcome: CodegraphSessionStartOutcome) => void;
+	readonly nowMs?: number;
 	readonly spawnWorker?: (invocation: WorkerSpawnInvocation) => void;
-	readonly statusProbe?: (options: {
-		readonly daemon: boolean;
-		readonly env: Record<string, string | undefined>;
-		readonly homeDir: string;
-		readonly projectRoot: string;
-		readonly trustedCodegraphInstallDir?: string;
-	}) => Promise<boolean>;
 	readonly stdin?: Readable & { readonly isTTY?: boolean };
 	readonly stdout?: HookStdout;
 	readonly sweepZombies?: (options: SweepCodegraphZombiesOptions) => Promise<unknown> | unknown;
@@ -102,4 +126,6 @@ export interface SessionStartWorkerOptions {
 	readonly env?: Record<string, string | undefined>;
 	readonly logOutcome?: (outcome: CodegraphSessionStartOutcome) => void;
 	readonly nodeVersion?: string;
+	readonly nowMs?: number;
+	readonly projectProbe?: (projectRoot: string) => CodegraphProjectState;
 }

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

@@ -1,5 +1,3 @@
-import { spawn } from "node:child_process";
-import { homedir } from "node:os";
 import {
 	cwd as processCwd,
 	env as processEnv,
@@ -7,27 +5,33 @@ import {
 	stdin as processStdin,
 	stdout as processStdout,
 } from "node:process";
-import type { Readable } from "node:stream";
 import { fileURLToPath } from "node:url";
 
-import { buildCodegraphChildEnv, buildCodegraphEnv } from "../../../../../utils/src/codegraph/env.ts";
-import { buildCodegraphInitGuidanceForToolResult } from "../../../../../utils/src/codegraph/guidance.ts";
-import { resolvePinnedCodegraphBin } from "../../../../../utils/src/codegraph/managed-runtime.ts";
-import { resolveCodegraphCommand } from "../../../../../utils/src/codegraph/resolve.ts";
-import { runProcessWithTreeTimeout } from "../../../../../utils/src/process-tree.ts";
+import { buildCodegraphChildEnv } from "../../../../../utils/src/codegraph/env.ts";
 import { shouldExcludeCodegraphProject } from "../../../../../utils/src/codegraph/workspace.ts";
 import { getCodexOmoConfig } from "../../../shared/src/config-loader.ts";
 import { pruneCodegraphProjectStoresBestEffort } from "./cache-gc.js";
+import { readHookInput, resolveHomeDir, resolveHookProjectRoot } from "./hook-input.js";
 import { sweepCodegraphZombiesBestEffort } from "./hook-sweep.js";
-import { resolveCodegraphCommandInvocation, SESSION_START_CWD_ENV } from "./session-start-worker.js";
 import type {
-	HookStdout,
-	PostToolUseHookOptions,
-	PostToolUseHookResult,
+	CodegraphSessionStartOutcome,
 	SessionStartHookOptions,
 	SessionStartHookResult,
-	WorkerSpawnInvocation,
 } from "./hook-types.js";
+import {
+	DEFAULT_SESSION_START_COOLDOWN_MS,
+	readSessionStartCooldown,
+	recordSessionStartFailure,
+} from "./session-start-cooldown.js";
+import { spawnDetachedSessionStartWorker, writeSessionStartNotice } from "./session-start-hook-runtime.js";
+import { acquireSessionStartLock, releaseSessionStartLock, type SessionStartLock } from "./session-start-lock.js";
+import { appendSessionStartOutcome } from "./session-start-outcome.js";
+import {
+	probeCodegraphAncestors,
+	probeExactCodegraphProject,
+	type CodegraphProjectState,
+} from "./session-start-project.js";
+import { SESSION_START_CWD_ENV, SESSION_START_LOCK_TOKEN_ENV } from "./session-start-worker.js";
 
 export type {
 	CodegraphCommandResult,
@@ -48,37 +52,45 @@ export type {
 	WorkerAction,
 	WorkerSpawnInvocation,
 } from "./hook-types.js";
-export { resolveCodegraphCommandInvocation, runCodegraphSessionStartWorker } from "./session-start-worker.js";
+export {
+	executeCodegraphPostToolUseHook,
+	runCodegraphPostToolUseHook,
+	runCodegraphPostToolUseHookCli,
+} from "./post-tool-use-hook.js";
+export { resolveCodegraphCommandInvocation } from "./session-start-command.js";
+export { runCodegraphSessionStartWorker } from "./session-start-worker.js";
 
 export const CODEGRAPH_SESSION_START_NOTICE = "LazyCodex CodeGraph bootstrap scheduled in background";
-const STATUS_PROBE_TIMEOUT_MS = 2_000;
+export const DEFAULT_SESSION_START_LOCK_STALE_MS = 10 * 60 * 1_000;
+
+type HookContext = {
+	readonly baseCooldownMs: number;
+	readonly env: Record<string, string | undefined>;
+	readonly homeDir: string;
+	readonly logOutcome: (outcome: CodegraphSessionStartOutcome) => void;
+	readonly nowMs: number;
+	readonly options: SessionStartHookOptions;
+	readonly projectRoot: string;
+};
 
 export async function runCodegraphSessionStartHook(options: SessionStartHookOptions = {}): Promise<number> {
 	return (await executeCodegraphSessionStartHook(options)).exitCode;
 }
 
-export async function runCodegraphPostToolUseHookCli(options: PostToolUseHookOptions = {}): Promise<number> {
-	return (await executeCodegraphPostToolUseHook(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 projectRoot = resolveHookProjectRoot(input, options.cwd ?? processCwd());
 	const homeDir = resolveHomeDir(env);
 	const config = options.config ?? getCodexOmoConfig({ cwd: projectRoot, env, homeDir });
+	if (config.codegraph?.enabled === false) return { action: "skipped-disabled", exitCode: 0 };
 
-	if (config.codegraph?.enabled === false) {
-		return { action: "skipped-disabled", exitCode: 0 };
-	}
 	const excludedRoots = config.codegraph?.excluded_roots;
 	const exclusion = shouldExcludeCodegraphProject(projectRoot, {
 		homeDir,
 		...(excludedRoots === undefined ? {} : { excludedRoots }),
 	});
-	if (exclusion.excluded) {
-		return { action: "skipped-excluded", exitCode: 0 };
-	}
+	if (exclusion.excluded) return { action: "skipped-excluded", exitCode: 0 };
 
 	pruneCodegraphProjectStoresBestEffort(homeDir, { debugLog: writeDebugLog });
 	await sweepCodegraphZombiesBestEffort({
@@ -88,164 +100,157 @@ export async function executeCodegraphSessionStartHook(options: SessionStartHook
 		log: writeDebugLog,
 	}, options.sweepZombies);
 
-	const isInitialized = await (options.statusProbe ?? isCodegraphProjectInitialized)({
-		daemon: config.codegraph?.daemon !== false,
+	const nowMs = options.nowMs ?? Date.now();
+	const context: HookContext = {
+		baseCooldownMs: config.codegraph?.session_start_cooldown_ms ?? DEFAULT_SESSION_START_COOLDOWN_MS,
 		env,
 		homeDir,
+		logOutcome: options.logOutcome ?? ((outcome) => appendSessionStartOutcome(homeDir, outcome, nowMs)),
+		nowMs,
+		options,
 		projectRoot,
-		...(config.trustedCodegraphInstallDir === undefined ? {} : { trustedCodegraphInstallDir: config.trustedCodegraphInstallDir }),
-	});
-	if (isInitialized) {
-		return { action: "skipped-initialized", exitCode: 0 };
-	}
+	};
+	const projectDecision = handleProjectState(resolveHookProjectState(context), context);
+	if (projectDecision !== null) return projectDecision;
 
-	(options.spawnWorker ?? spawnDetachedWorker)({
-		args: [options.workerCliPath ?? defaultWorkerCliPath(), "hook", "session-start-worker"],
-		command: process.execPath,
-		env: buildCodegraphChildEnv({
-			ambientEnv: env,
-			codegraphEnv: { [SESSION_START_CWD_ENV]: projectRoot },
-			runtimeEnv: env,
-		}),
+	const cooldown = readSessionStartCooldown({
+		baseCooldownMs: context.baseCooldownMs,
+		homeDir,
+		nowMs,
+		projectRoot,
 	});
-	writeHookJson(options.stdout ?? processStdout);
-	return { action: "spawned", exitCode: 0 };
-}
+	if (cooldown.kind === "inconclusive") return { action: "skipped-inconclusive", exitCode: 0 };
+	if (cooldown.kind === "active") {
+		safeLogOutcome(context.logOutcome, {
+			action: "skipped-cooldown",
+			cooldownUntil: cooldown.cooldownUntil,
+			failureCount: cooldown.failureCount,
+			projectRoot,
+		});
+		return { action: "skipped-cooldown", exitCode: 0 };
+	}
 
-async function isCodegraphProjectInitialized(options: {
-	readonly daemon: boolean;
-	readonly env: Record<string, string | undefined>;
-	readonly homeDir: string;
-	readonly projectRoot: string;
-	readonly trustedCodegraphInstallDir?: string;
-}): Promise<boolean> {
-	const resolved = resolveCodegraphCommand({
-		env: options.env,
-		homeDir: options.homeDir,
-		provisioned: () => provisionedBinFromInstallDir(options.trustedCodegraphInstallDir),
+	const lockResult = acquireSessionStartLock({
+		homeDir,
+		nowMs,
+		projectRoot,
+		staleMs: options.lockStaleMs ?? DEFAULT_SESSION_START_LOCK_STALE_MS,
 	});
-	if (!resolved.exists) return false;
-
-	const invocation = resolveCodegraphCommandInvocation(resolved.command, [...resolved.argsPrefix, "status", "--json"]);
-	const codegraphEnv = {
-		...buildCodegraphEnv({ daemon: options.daemon, homeDir: options.homeDir }),
-		...(options.trustedCodegraphInstallDir === undefined ? {} : { CODEGRAPH_INSTALL_DIR: options.trustedCodegraphInstallDir }),
-	};
-	const status = await runStatusProbe(
-		options.projectRoot,
-		invocation.command,
-		invocation.args,
-		buildCodegraphChildEnv({ ambientEnv: options.env, codegraphEnv, runtimeEnv: options.env }),
-	);
-	if (status.exitCode !== 0 || status.timedOut) return false;
-	return codegraphStatusSaysInitialized(status.stdout);
-}
-
-function runStatusProbe(
-	projectRoot: string,
-	command: string,
-	args: readonly string[],
-	env: Record<string, string>,
-): Promise<{ readonly exitCode: number; readonly stdout: string; readonly timedOut: boolean }> {
-	return runProcessWithTreeTimeout({
-		args,
-		command,
-		cwd: projectRoot,
-		env,
-		maxBuffer: 1024 * 1024,
-		timeoutMs: STATUS_PROBE_TIMEOUT_MS,
-	}).then(({ exitCode, stdout, timedOut }) => ({ exitCode, stdout, timedOut }));
-}
-
-function codegraphStatusSaysInitialized(stdout: string): boolean {
-	const parsed = parseJson(stdout);
-	if (!isRecord(parsed)) return false;
-	const initialized = parsed["initialized"] ?? parsed["isInitialized"] ?? parsed["ready"];
-	if (typeof initialized === "boolean") return initialized;
-	const status = parsed["status"];
-	if (typeof status !== "string") return false;
-	const normalized = status.toLowerCase();
-	return (normalized.includes("initialized") || normalized.includes("ready")) && !normalized.includes("not initialized") && !normalized.includes("uninitialized");
-}
-
-function provisionedBinFromInstallDir(installDir: string | undefined): string | null {
-	return resolvePinnedCodegraphBin(installDir);
-}
-
-export async function executeCodegraphPostToolUseHook(options: PostToolUseHookOptions = {}): Promise<PostToolUseHookResult> {
-	const env = options.env ?? processEnv;
-	const input = await readHookInput(options.stdin ?? processStdin);
-	const output = runCodegraphPostToolUseHook(input, { homeDir: resolveHomeDir(env) });
-	if (output.length === 0) return { action: "skipped", exitCode: 0 };
-
-	(options.stdout ?? processStdout).write(output);
-	return { action: "emitted-guidance", exitCode: 0 };
-}
+	if (lockResult.kind === "inconclusive") return { action: "skipped-inconclusive", exitCode: 0 };
+	if (lockResult.kind === "locked") {
+		safeLogOutcome(context.logOutcome, { action: "skipped-locked", projectRoot });
+		return { action: "skipped-locked", exitCode: 0 };
+	}
+	if (lockResult.recoveredStale) return handleRecoveredStaleLock(lockResult.lock, context);
 
-export function runCodegraphPostToolUseHook(input: unknown, options: { readonly homeDir?: string } = {}): string {
-	const toolName = isRecord(input) ? input["tool_name"] : undefined;
-	const cwd = isRecord(input) ? input["cwd"] : undefined;
-	const toolOutput = isRecord(input) ? (input["tool_response"] ?? input["tool_output"] ?? input["response"]) : input;
-	const guidance = buildCodegraphInitGuidanceForToolResult({ cwd, toolName, toolOutput }, options);
-	if (guidance === null) return "";
-
-	return `${JSON.stringify({
-		hookSpecificOutput: {
-			hookEventName: "PostToolUse",
-			additionalContext: guidance,
-		},
-	})}\n`;
-}
+	const lockedProjectDecision = handleProjectState(resolveHookProjectState(context), context);
+	if (lockedProjectDecision !== null) {
+		releaseSessionStartLock(lockResult.lock);
+		return lockedProjectDecision;
+	}
 
-function writeHookJson(stdout: HookStdout): void {
-	const output = {
-		hookSpecificOutput: {
-			hookEventName: "SessionStart",
-			additionalContext: CODEGRAPH_SESSION_START_NOTICE,
-		},
-	};
-	stdout.write(`${JSON.stringify(output)}\n`);
-}
+	try {
+		(options.spawnWorker ?? spawnDetachedSessionStartWorker)({
+			args: [options.workerCliPath ?? defaultWorkerCliPath(), "hook", "session-start-worker"],
+			command: process.execPath,
+			env: buildCodegraphChildEnv({
+				ambientEnv: env,
+				codegraphEnv: {
+					[SESSION_START_CWD_ENV]: projectRoot,
+					[SESSION_START_LOCK_TOKEN_ENV]: lockResult.lock.token,
+				},
+				runtimeEnv: env,
+			}),
+		});
+	} catch (error) {
+		if (error instanceof Error) return handleSpawnFailure(error, lockResult.lock, context);
+		throw error;
+	}
 
-function writeDebugLog(message: string): void {
-	if (processEnv["OMO_CODEGRAPH_DEBUG"] !== "1") return;
-	processStderr.write(`${message}\n`);
+	writeSessionStartNotice(options.stdout ?? processStdout, CODEGRAPH_SESSION_START_NOTICE);
+	return { action: "spawned", exitCode: 0 };
 }
 
-function spawnDetachedWorker(invocation: WorkerSpawnInvocation): void {
-	const child = spawn(invocation.command, [...invocation.args], { detached: true, env: invocation.env, stdio: "ignore" });
-	child.unref();
+function resolveHookProjectState(context: HookContext): CodegraphProjectState {
+	const exact = probeExactCodegraphProject(context.projectRoot);
+	if (exact.kind !== "uninitialized") return exact;
+	return (context.options.ancestorProbe ?? probeCodegraphAncestors)(context.projectRoot);
 }
 
-function resolveHomeDir(env: Record<string, string | undefined>): string {
-	return env["HOME"] ?? env["USERPROFILE"] ?? homedir();
+function handleProjectState(state: CodegraphProjectState, context: HookContext): SessionStartHookResult | null {
+	switch (state.kind) {
+		case "inconclusive":
+			return { action: "skipped-inconclusive", exitCode: 0 };
+		case "initialized":
+			return { action: "skipped-initialized", exitCode: 0 };
+		case "nested-root":
+			safeLogOutcome(context.logOutcome, { action: "skipped-nested-root", ancestorRoot: state.ancestorRoot, projectRoot: context.projectRoot });
+			return { action: "skipped-nested-root", exitCode: 0 };
+		case "uninitialized":
+			return null;
+	}
 }
 
-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;
+function handleRecoveredStaleLock(lock: SessionStartLock, context: HookContext): SessionStartHookResult {
+	try {
+		const cooldown = recordSessionStartFailure({
+			action: "stale-lock",
+			baseCooldownMs: context.baseCooldownMs,
+			homeDir: context.homeDir,
+			nowMs: context.nowMs,
+			projectRoot: context.projectRoot,
+		});
+		releaseSessionStartLock(lock);
+		safeLogOutcome(context.logOutcome, {
+			action: "skipped-cooldown",
+			cooldownUntil: cooldown.cooldownUntil,
+			error: "recovered stale SessionStart worker lock",
+			failureCount: cooldown.failureCount,
+			projectRoot: context.projectRoot,
+		});
+		return { action: "skipped-cooldown", exitCode: 0 };
+	} catch (error) {
+		if (error instanceof Error) return { action: "skipped-inconclusive", exitCode: 0 };
+		throw error;
+	}
 }
 
-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 handleSpawnFailure(error: unknown, lock: SessionStartLock, context: HookContext): SessionStartHookResult {
+	try {
+		const cooldown = recordSessionStartFailure({
+			action: "spawn-failed",
+			baseCooldownMs: context.baseCooldownMs,
+			homeDir: context.homeDir,
+			nowMs: context.nowMs,
+			projectRoot: context.projectRoot,
+		});
+		releaseSessionStartLock(lock);
+		safeLogOutcome(context.logOutcome, {
+			action: "skipped-spawn-error",
+			cooldownUntil: cooldown.cooldownUntil,
+			error: error instanceof Error ? error.message : String(error),
+			failureCount: cooldown.failureCount,
+			projectRoot: context.projectRoot,
+		});
+	} catch (cooldownError) {
+		if (cooldownError instanceof Error) return { action: "skipped-inconclusive", exitCode: 0 };
+		throw cooldownError;
+	}
+	return { action: "skipped-spawn-error", exitCode: 0 };
 }
 
-function parseJson(text: string): unknown {
+function safeLogOutcome(logOutcome: (outcome: CodegraphSessionStartOutcome) => void, outcome: CodegraphSessionStartOutcome): void {
 	try {
-		return JSON.parse(text);
+		logOutcome(outcome);
 	} catch (error) {
-		if (error instanceof SyntaxError) return undefined;
-		throw error;
+		if (error instanceof Error) writeDebugLog(`failed to write SessionStart outcome: ${error.message}`);
+		else throw error;
 	}
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
+function writeDebugLog(message: string): void {
+	if (processEnv["OMO_CODEGRAPH_DEBUG"] !== "1") return;
+	processStderr.write(`${message}\n`);
 }
 
 function defaultWorkerCliPath(): string {

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

@@ -0,0 +1,34 @@
+import { env as processEnv, stdin as processStdin, stdout as processStdout } from "node:process";
+
+import { buildCodegraphInitGuidanceForToolResult } from "../../../../../utils/src/codegraph/guidance.ts";
+import { isRecord, readHookInput, resolveHomeDir } from "./hook-input.js";
+import type { PostToolUseHookOptions, PostToolUseHookResult } from "./hook-types.js";
+
+export async function runCodegraphPostToolUseHookCli(options: PostToolUseHookOptions = {}): Promise<number> {
+	return (await executeCodegraphPostToolUseHook(options)).exitCode;
+}
+
+export async function executeCodegraphPostToolUseHook(options: PostToolUseHookOptions = {}): Promise<PostToolUseHookResult> {
+	const env = options.env ?? processEnv;
+	const input = await readHookInput(options.stdin ?? processStdin);
+	const output = runCodegraphPostToolUseHook(input, { homeDir: resolveHomeDir(env) });
+	if (output.length === 0) return { action: "skipped", exitCode: 0 };
+
+	(options.stdout ?? processStdout).write(output);
+	return { action: "emitted-guidance", exitCode: 0 };
+}
+
+export function runCodegraphPostToolUseHook(input: unknown, options: { readonly homeDir?: string } = {}): string {
+	const toolName = isRecord(input) ? input["tool_name"] : undefined;
+	const cwd = isRecord(input) ? input["cwd"] : undefined;
+	const toolOutput = isRecord(input) ? (input["tool_response"] ?? input["tool_output"] ?? input["response"]) : input;
+	const guidance = buildCodegraphInitGuidanceForToolResult({ cwd, toolName, toolOutput }, options);
+	if (guidance === null) return "";
+
+	return `${JSON.stringify({
+		hookSpecificOutput: {
+			hookEventName: "PostToolUse",
+			additionalContext: guidance,
+		},
+	})}\n`;
+}

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

@@ -16,7 +16,7 @@ import {
 	buildCodegraphChildEnv,
 	buildCodegraphEnv,
 } from "../../../../../utils/src/codegraph/env.ts";
-import { resolvePinnedCodegraphBin } from "../../../../../utils/src/codegraph/managed-runtime.ts";
+import { hasCodegraphManagedInstall, resolvePinnedCodegraphBin } from "../../../../../utils/src/codegraph/managed-runtime.ts";
 import type { ParentWatchdogConfig } from "../../../../../mcp-stdio-core/src/index.ts";
 import { CODEGRAPH_PINNED_VERSION } from "../../../../../utils/src/codegraph/manifest.ts";
 import {
@@ -73,6 +73,8 @@ export interface RunCodegraphServeOptions {
 	readonly cwd?: string;
 	readonly env?: Record<string, string | undefined>;
 	readonly homeDir?: string;
+	readonly managedInstallExists?: (installDir: string) => boolean;
+	readonly resolveManagedBin?: (installDir: string) => string | null;
 	readonly stdin?: Readable;
 	readonly stdout?: Writable;
 	readonly nodeVersion?: string;
@@ -114,12 +116,28 @@ export async function runCodegraphServe(options: RunCodegraphServeOptions = {}):
 	}
 
 	const trustedInstallDir = config.trustedCodegraphInstallDir;
+	const installDir = trustedInstallDir ?? join(homeDir, ".omo", "codegraph");
 	const resolutionOptions = {
 		env,
 		homeDir,
-		provisioned: () => provisionedBinFromInstallDir(trustedInstallDir),
+		provisioned: () => provisionedBinFromInstallDir(installDir),
 	} satisfies ResolveCodegraphCommandOptions;
 	let resolution = options.resolve?.(resolutionOptions) ?? resolveCodegraphCommand(resolutionOptions);
+	const resolveManagedBin = options.resolveManagedBin ?? (options.resolve === undefined ? provisionedBinFromInstallDir : () => null);
+	const managedInstallExists = options.managedInstallExists ?? (options.resolve === undefined ? hasCodegraphManagedInstall : () => false);
+	const managedBin = resolveManagedBin(installDir);
+	if (resolution.source !== "env" && managedBin !== null) {
+		resolution = { argsPrefix: [], command: managedBin, exists: true, source: "provisioned" };
+	} else if (resolution.source !== "env" && codegraphConfig.auto_provision !== false && managedInstallExists(installDir)) {
+		const upgraded = await provisionMissingCodegraph({
+			config: codegraphConfig,
+			ensureProvisioned: options.ensureProvisioned ?? ensureCodegraphProvisioned,
+			homeDir,
+			resolution,
+			...(trustedInstallDir === undefined ? {} : { trustedInstallDir }),
+		});
+		if (upgraded !== null) resolution = upgraded;
+	}
 	const nodeSupport = evaluateCodegraphNodeSupport({ env, nodeVersion: options.nodeVersion });
 	if (!resolution.exists || shouldSkipResolvedCommand(resolution, options.commandExists ?? existsSync)) {
 		if (resolution.source === "path" && !nodeSupport.supported) {