oh-my-opencode 4.19.2 → 4.19.4

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

@@ -0,0 +1,106 @@
+import { join } from "node:path";
+import { env as processEnv, stderr as processStderr } from "node:process";
+
+import { buildCodegraphChildEnv, buildCodegraphEnv } from "../../../../../utils/src/codegraph/env.ts";
+import { CODEGRAPH_PINNED_VERSION } from "../../../../../utils/src/codegraph/manifest.ts";
+import type { CodegraphNodeSupport } from "../../../../../utils/src/codegraph/node-support.ts";
+import {
+	codegraphCommandRequiresSupportedLocalNode,
+	type CodegraphCommandResolution,
+} from "../../../../../utils/src/codegraph/resolve.ts";
+import { runProcessWithTreeTimeout } from "../../../../../utils/src/process-tree.ts";
+import type { CodegraphCommandResult, CodegraphConfig, CodegraphSessionStartDeps } from "./hook-types.js";
+import { resolveServeProcessInvocation } from "./serve-invocation.js";
+
+export const SESSION_START_COMMAND_TIMEOUT_MS = 60_000;
+
+export type CodegraphBootstrapConfig = CodegraphConfig & {
+	readonly trustedCodegraphInstallDir?: string;
+};
+
+export type SessionStartCommandResolution =
+	| { readonly kind: "resolved"; readonly resolution: CodegraphCommandResolution }
+	| { readonly kind: "unsupported-node" }
+	| { readonly error: string; readonly kind: "unavailable"; readonly source: CodegraphCommandResolution["source"] };
+
+export async function resolveSessionStartCommand(options: {
+	readonly config: CodegraphBootstrapConfig;
+	readonly deps: CodegraphSessionStartDeps;
+	readonly env: Record<string, string | undefined>;
+	readonly homeDir: string;
+	readonly nodeSupport: CodegraphNodeSupport;
+}): Promise<SessionStartCommandResolution> {
+	const trustedInstallDir = options.config.trustedCodegraphInstallDir;
+	const installDir = trustedInstallDir ?? join(options.homeDir, ".omo", "codegraph");
+	const resolved = options.deps.resolveCommand({
+		env: options.env,
+		homeDir: options.homeDir,
+		provisioned: () => options.deps.resolveManagedBin(installDir),
+	});
+	const managedBin = options.deps.resolveManagedBin(installDir);
+	if (resolved.source !== "env" && managedBin !== null) {
+		return { kind: "resolved", resolution: { argsPrefix: [], command: managedBin, exists: true, source: "provisioned" } };
+	}
+	if (resolved.source !== "env" && options.config.auto_provision !== false && options.deps.managedInstallExists(installDir)) {
+		const upgraded = await options.deps.ensureProvisioned({
+			installDir,
+			lockDir: join(installDir, ".locks"),
+			version: CODEGRAPH_PINNED_VERSION,
+		});
+		if (upgraded.provisioned && upgraded.binPath !== undefined) {
+			return { kind: "resolved", resolution: { argsPrefix: [], command: upgraded.binPath, exists: true, source: "provisioned" } };
+		}
+	}
+	if (resolved.exists && canUseResolvedCommand(resolved, options.nodeSupport)) {
+		return { kind: "resolved", resolution: resolved };
+	}
+	if (resolved.exists && options.config.auto_provision === false) return { kind: "unsupported-node" };
+	if (options.config.auto_provision === false) {
+		return { error: "codegraph binary unavailable and auto_provision is disabled", kind: "unavailable", source: resolved.source };
+	}
+
+	const provisioned = await options.deps.ensureProvisioned({
+		installDir,
+		lockDir: join(installDir, ".locks"),
+		version: CODEGRAPH_PINNED_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" } };
+}
+
+export function sessionStartCodegraphEnv(config: CodegraphBootstrapConfig, homeDir: string): Record<string, string> {
+	const env = buildCodegraphEnv({ daemon: false, homeDir });
+	return config.trustedCodegraphInstallDir === undefined ? env : { ...env, CODEGRAPH_INSTALL_DIR: config.trustedCodegraphInstallDir };
+}
+
+export async function runSessionStartCodegraphCommand(
+	projectRoot: string,
+	command: string,
+	args: readonly string[],
+	options: { readonly env: Record<string, string>; readonly timeoutMs: number },
+): Promise<CodegraphCommandResult> {
+	const invocation = resolveCodegraphCommandInvocation(command, args);
+	return runProcessWithTreeTimeout({
+		args: invocation.args,
+		command: invocation.command,
+		cwd: projectRoot,
+		env: buildCodegraphChildEnv({ ambientEnv: processEnv, codegraphEnv: options.env }),
+		maxBuffer: 1024 * 1024,
+		onTerminationReport: (report) => processStderr.write(`[codegraph-session-start] process tree termination ${JSON.stringify(report)}\n`),
+		timeoutMs: options.timeoutMs,
+	}).then(({ exitCode, stderr, stdout, timedOut }) => ({ exitCode, stderr, stdout, timedOut }));
+}
+
+export function resolveCodegraphCommandInvocation(
+	command: string,
+	args: readonly string[],
+	platform: NodeJS.Platform = process.platform,
+): { readonly args: readonly string[]; readonly command: string } {
+	return resolveServeProcessInvocation(command, args, platform);
+}
+
+function canUseResolvedCommand(resolved: CodegraphCommandResolution, nodeSupport: CodegraphNodeSupport): boolean {
+	return !codegraphCommandRequiresSupportedLocalNode(resolved) || nodeSupport.supported;
+}

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

@@ -0,0 +1,145 @@
+import { mkdirSync, readFileSync, rmSync } from "node:fs";
+
+import { writeFileAtomically } from "../../../../../utils/src/atomic-write.ts";
+import { resolveSessionStartStatePaths, stateParent } from "./session-start-paths.js";
+
+export const DEFAULT_SESSION_START_COOLDOWN_MS = 15 * 60 * 1_000;
+export const MAX_SESSION_START_COOLDOWN_MS = 24 * 60 * 60 * 1_000;
+
+export type SessionStartFailureAction =
+	| "failed"
+	| "skipped-probe-error"
+	| "skipped-status"
+	| "skipped-unavailable"
+	| "skipped-unsupported-node"
+	| "spawn-failed"
+	| "stale-lock"
+	| "timeout";
+
+export interface SessionStartCooldownState {
+	readonly action: SessionStartFailureAction;
+	readonly cooldownUntil: number;
+	readonly failureCount: number;
+	readonly lastFailureAt: number;
+	readonly projectRoot: string;
+	readonly version: 1;
+}
+
+export type SessionStartCooldownDecision =
+	| { readonly cooldownUntil: number; readonly failureCount: number; readonly kind: "active" }
+	| { readonly failureCount: number; readonly kind: "inactive" }
+	| { readonly kind: "inconclusive"; readonly reason: string };
+
+export interface SessionStartCooldownOptions {
+	readonly baseCooldownMs: number;
+	readonly homeDir: string;
+	readonly maxCooldownMs?: number;
+	readonly nowMs: number;
+	readonly projectRoot: string;
+}
+
+export function readSessionStartCooldown(options: SessionStartCooldownOptions): SessionStartCooldownDecision {
+	const paths = resolveSessionStartStatePaths(options.homeDir, options.projectRoot);
+	const state = readCooldownState(paths.cooldownPath, paths.canonicalProjectRoot);
+	if (state.kind === "inconclusive") return state;
+	if (state.kind === "missing") return { failureCount: 0, kind: "inactive" };
+	const cooldownUntil = state.value.lastFailureAt + cooldownDuration(
+		options.baseCooldownMs,
+		state.value.failureCount,
+		options.maxCooldownMs ?? MAX_SESSION_START_COOLDOWN_MS,
+	);
+	return options.nowMs < cooldownUntil
+		? { cooldownUntil, failureCount: state.value.failureCount, kind: "active" }
+		: { failureCount: state.value.failureCount, kind: "inactive" };
+}
+
+export function recordSessionStartFailure(
+	options: SessionStartCooldownOptions & { readonly action: SessionStartFailureAction },
+): SessionStartCooldownState {
+	const paths = resolveSessionStartStatePaths(options.homeDir, options.projectRoot);
+	const existing = readCooldownState(paths.cooldownPath, paths.canonicalProjectRoot);
+	const failureCount = existing.kind === "present" ? existing.value.failureCount + 1 : 1;
+	const cooldownUntil = options.nowMs + cooldownDuration(
+		options.baseCooldownMs,
+		failureCount,
+		options.maxCooldownMs ?? MAX_SESSION_START_COOLDOWN_MS,
+	);
+	const state: SessionStartCooldownState = {
+		action: options.action,
+		cooldownUntil,
+		failureCount,
+		lastFailureAt: options.nowMs,
+		projectRoot: paths.canonicalProjectRoot,
+		version: 1,
+	};
+	mkdirSync(stateParent(paths.cooldownPath), { recursive: true });
+	writeFileAtomically(paths.cooldownPath, `${JSON.stringify(state)}\n`);
+	return state;
+}
+
+export function clearSessionStartCooldown(options: { readonly homeDir: string; readonly projectRoot: string }): void {
+	const path = resolveSessionStartStatePaths(options.homeDir, options.projectRoot).cooldownPath;
+	rmSync(path, { force: true });
+}
+
+function cooldownDuration(baseCooldownMs: number, failureCount: number, maxCooldownMs: number): number {
+	let duration = Math.min(baseCooldownMs, maxCooldownMs);
+	for (let attempt = 1; attempt < failureCount && duration < maxCooldownMs; attempt += 1) {
+		duration = Math.min(duration * 2, maxCooldownMs);
+	}
+	return duration;
+}
+
+type CooldownReadResult =
+	| { readonly kind: "inconclusive"; readonly reason: string }
+	| { readonly kind: "missing" }
+	| { readonly kind: "present"; readonly value: SessionStartCooldownState };
+
+function readCooldownState(path: string, projectRoot: string): CooldownReadResult {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		const state = parseCooldownState(parsed, projectRoot);
+		return state === null
+			? { kind: "inconclusive", reason: "cooldown state is invalid" }
+			: { kind: "present", value: state };
+	} catch (error) {
+		if (!(error instanceof Error)) throw error;
+		if (errorCode(error) === "ENOENT") return { kind: "missing" };
+		return { kind: "inconclusive", reason: error.message };
+	}
+}
+
+function parseCooldownState(value: unknown, projectRoot: string): SessionStartCooldownState | null {
+	if (typeof value !== "object" || value === null) return null;
+	const action = Reflect.get(value, "action");
+	const cooldownUntil = Reflect.get(value, "cooldownUntil");
+	const failureCount = Reflect.get(value, "failureCount");
+	const lastFailureAt = Reflect.get(value, "lastFailureAt");
+	const recordedRoot = Reflect.get(value, "projectRoot");
+	const version = Reflect.get(value, "version");
+	if (!isFailureAction(action)) return null;
+	if (typeof cooldownUntil !== "number" || !Number.isFinite(cooldownUntil)) return null;
+	if (typeof failureCount !== "number" || !Number.isInteger(failureCount) || failureCount < 1) return null;
+	if (typeof lastFailureAt !== "number" || !Number.isFinite(lastFailureAt)) return null;
+	if (recordedRoot !== projectRoot || version !== 1) return null;
+	return { action, cooldownUntil, failureCount, lastFailureAt, projectRoot: recordedRoot, version };
+}
+
+function isFailureAction(value: unknown): value is SessionStartFailureAction {
+	return typeof value === "string" && [
+		"failed",
+		"skipped-probe-error",
+		"skipped-status",
+		"skipped-unavailable",
+		"skipped-unsupported-node",
+		"spawn-failed",
+		"stale-lock",
+		"timeout",
+	].includes(value);
+}
+
+function errorCode(error: unknown): string | undefined {
+	if (typeof error !== "object" || error === null) return undefined;
+	const code = Reflect.get(error, "code");
+	return typeof code === "string" ? code : undefined;
+}

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

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+
+import type { HookStdout, WorkerSpawnInvocation } from "./hook-types.js";
+
+export function spawnDetachedSessionStartWorker(invocation: WorkerSpawnInvocation): void {
+	const child = spawn(invocation.command, [...invocation.args], {
+		detached: true,
+		env: invocation.env,
+		stdio: "ignore",
+	});
+	child.unref();
+}
+
+export function writeSessionStartNotice(stdout: HookStdout, notice: string): void {
+	stdout.write(`${JSON.stringify({
+		hookSpecificOutput: {
+			hookEventName: "SessionStart",
+			additionalContext: notice,
+		},
+	})}\n`);
+}

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

@@ -0,0 +1,139 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+
+import { resolveSessionStartStatePaths, stateParent } from "./session-start-paths.js";
+
+export interface SessionStartLock {
+	readonly path: string;
+	readonly token: string;
+}
+
+export type SessionStartLockResult =
+	| { readonly kind: "acquired"; readonly lock: SessionStartLock; readonly recoveredStale: boolean }
+	| { readonly kind: "inconclusive"; readonly reason: string }
+	| { readonly kind: "locked" };
+
+export interface AcquireSessionStartLockOptions {
+	readonly homeDir: string;
+	readonly nowMs: number;
+	readonly projectRoot: string;
+	readonly staleMs: number;
+}
+
+type LockSnapshot =
+	| { readonly kind: "inconclusive"; readonly reason: string }
+	| { readonly kind: "missing" }
+	| { readonly kind: "present"; readonly mtimeMs: number; readonly raw: string; readonly token: string };
+
+export function acquireSessionStartLock(options: AcquireSessionStartLockOptions): SessionStartLockResult {
+	const paths = resolveSessionStartStatePaths(options.homeDir, options.projectRoot);
+	const lockPath = paths.lockPath;
+	const canonicalOptions = { ...options, projectRoot: paths.canonicalProjectRoot };
+	try {
+		mkdirSync(stateParent(lockPath), { recursive: true });
+	} catch (error) {
+		if (error instanceof Error) return { kind: "inconclusive", reason: error.message };
+		throw error;
+	}
+
+	const initial = tryCreateLock(lockPath, canonicalOptions.projectRoot);
+	if (initial.kind !== "locked") return initial;
+
+	const snapshot = readLockSnapshot(lockPath);
+	if (snapshot.kind === "missing") return tryCreateLock(lockPath, canonicalOptions.projectRoot);
+	if (snapshot.kind === "inconclusive") return snapshot;
+	if (canonicalOptions.nowMs - snapshot.mtimeMs < canonicalOptions.staleMs) return { kind: "locked" };
+	return reclaimStaleLock(lockPath, snapshot, canonicalOptions);
+}
+
+export function releaseSessionStartLock(lock: SessionStartLock): boolean {
+	const snapshot = readLockSnapshot(lock.path);
+	if (snapshot.kind !== "present" || snapshot.token !== lock.token) return false;
+	try {
+		rmSync(lock.path, { force: true });
+		return true;
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+}
+
+export function sessionStartLockIsOwned(lock: SessionStartLock): boolean {
+	const snapshot = readLockSnapshot(lock.path);
+	return snapshot.kind === "present" && snapshot.token === lock.token;
+}
+
+function reclaimStaleLock(
+	lockPath: string,
+	staleSnapshot: Extract<LockSnapshot, { readonly kind: "present" }>,
+	options: AcquireSessionStartLockOptions,
+): SessionStartLockResult {
+	const reclaimPath = `${lockPath}.reclaim`;
+	const reclaim = tryCreateMarker(reclaimPath);
+	if (reclaim.kind !== "acquired") return reclaim;
+
+	try {
+		const current = readLockSnapshot(lockPath);
+		if (current.kind === "inconclusive") return current;
+		if (current.kind === "present") {
+			const changed = current.raw !== staleSnapshot.raw || current.mtimeMs !== staleSnapshot.mtimeMs;
+			if (changed || options.nowMs - current.mtimeMs < options.staleMs) return { kind: "locked" };
+			rmSync(lockPath, { force: true });
+		}
+		const acquired = tryCreateLock(lockPath, options.projectRoot);
+		return acquired.kind === "acquired" ? { ...acquired, recoveredStale: true } : acquired;
+	} catch (error) {
+		if (error instanceof Error) return { kind: "inconclusive", reason: error.message };
+		throw error;
+	} finally {
+		rmSync(reclaimPath, { force: true });
+	}
+}
+
+function tryCreateLock(lockPath: string, projectRoot: string): SessionStartLockResult {
+	const token = randomUUID();
+	try {
+		writeFileSync(lockPath, `${JSON.stringify({ projectRoot, token })}\n`, {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 0o600,
+		});
+		return { kind: "acquired", lock: { path: lockPath, token }, recoveredStale: false };
+	} catch (error) {
+		if (!(error instanceof Error)) throw error;
+		if (errorCode(error) === "EEXIST") return { kind: "locked" };
+		return { kind: "inconclusive", reason: error.message };
+	}
+}
+
+function tryCreateMarker(path: string): { readonly kind: "acquired" } | { readonly kind: "inconclusive"; readonly reason: string } | { readonly kind: "locked" } {
+	try {
+		writeFileSync(path, `${randomUUID()}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+		return { kind: "acquired" };
+	} catch (error) {
+		if (!(error instanceof Error)) throw error;
+		if (errorCode(error) === "EEXIST") return { kind: "locked" };
+		return { kind: "inconclusive", reason: error.message };
+	}
+}
+
+function readLockSnapshot(path: string): LockSnapshot {
+	try {
+		const raw = readFileSync(path, "utf8");
+		const parsed: unknown = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return { kind: "inconclusive", reason: "lock body is not an object" };
+		const token = Reflect.get(parsed, "token");
+		if (typeof token !== "string" || token.length === 0) return { kind: "inconclusive", reason: "lock token is missing" };
+		return { kind: "present", mtimeMs: statSync(path).mtimeMs, raw, token };
+	} catch (error) {
+		if (!(error instanceof Error)) throw error;
+		if (errorCode(error) === "ENOENT") return { kind: "missing" };
+		return { kind: "inconclusive", reason: error.message };
+	}
+}
+
+function errorCode(error: unknown): string | undefined {
+	if (typeof error !== "object" || error === null) return undefined;
+	const code = Reflect.get(error, "code");
+	return typeof code === "string" ? code : undefined;
+}

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

@@ -0,0 +1,15 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { codegraphDataRoot } from "../../../../../utils/src/codegraph/paths.ts";
+import type { CodegraphSessionStartOutcome } from "./hook-types.js";
+
+export function appendSessionStartOutcome(
+	homeDir: string,
+	outcome: CodegraphSessionStartOutcome,
+	nowMs: number = Date.now(),
+): void {
+	const path = join(codegraphDataRoot(homeDir), "session-start.jsonl");
+	mkdirSync(dirname(path), { recursive: true });
+	appendFileSync(path, `${JSON.stringify({ ...outcome, timestamp: new Date(nowMs).toISOString() })}\n`);
+}

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

@@ -0,0 +1,32 @@
+import { basename, dirname, join } from "node:path";
+
+import {
+	canonicalizeCodegraphPath,
+	resolveCodegraphWorkspacePaths,
+} from "../../../../../utils/src/codegraph/paths.ts";
+
+export interface SessionStartStatePaths {
+	readonly canonicalProjectRoot: string;
+	readonly cooldownPath: string;
+	readonly lockPath: string;
+	readonly outcomePath: string;
+	readonly stateDirectory: string;
+}
+
+export function resolveSessionStartStatePaths(homeDir: string, projectRoot: string): SessionStartStatePaths {
+	const canonicalProjectRoot = canonicalizeCodegraphPath(projectRoot);
+	const workspacePaths = resolveCodegraphWorkspacePaths(canonicalProjectRoot, { homeDir });
+	const projectKey = basename(workspacePaths.dataDir);
+	const stateDirectory = join(workspacePaths.dataRoot, "session-start");
+	return {
+		canonicalProjectRoot,
+		cooldownPath: join(stateDirectory, "cooldowns", `${projectKey}.json`),
+		lockPath: join(stateDirectory, "locks", `${projectKey}.lock`),
+		outcomePath: join(workspacePaths.dataRoot, "session-start.jsonl"),
+		stateDirectory,
+	};
+}
+
+export function stateParent(path: string): string {
+	return dirname(path);
+}

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

@@ -0,0 +1,109 @@
+import { realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export type CodegraphProjectState =
+	| { readonly kind: "inconclusive"; readonly reason: string }
+	| { readonly kind: "initialized" }
+	| { readonly ancestorRoot: string; readonly kind: "nested-root" }
+	| { readonly kind: "uninitialized" };
+
+export type CodegraphAncestorState = Exclude<CodegraphProjectState, { readonly kind: "initialized" }>;
+export type CodegraphExactProjectState = Extract<
+	CodegraphProjectState,
+	{ readonly kind: "inconclusive" | "initialized" | "uninitialized" }
+>;
+
+type DatabaseState =
+	| { readonly kind: "inconclusive"; readonly reason: string }
+	| { readonly kind: "missing" }
+	| { readonly kind: "present" };
+
+export interface CodegraphProjectProbeOptions {
+	readonly probeDatabase?: (directory: string) => DatabaseState;
+}
+
+export function probeCodegraphProject(
+	projectRoot: string,
+	options: CodegraphProjectProbeOptions = {},
+): CodegraphProjectState {
+	const resolved = resolveProjectRoot(projectRoot);
+	if (resolved.kind === "inconclusive") return resolved;
+
+	const probeDatabase = options.probeDatabase ?? probeDatabaseAt;
+	const exact = probeResolvedExactProject(resolved.projectRoot, probeDatabase);
+	if (exact.kind !== "uninitialized") return exact;
+	return probeResolvedAncestors(resolved.projectRoot, probeDatabase);
+}
+
+export function probeExactCodegraphProject(
+	projectRoot: string,
+	options: CodegraphProjectProbeOptions = {},
+): CodegraphExactProjectState {
+	const resolved = resolveProjectRoot(projectRoot);
+	if (resolved.kind === "inconclusive") return resolved;
+	return probeResolvedExactProject(resolved.projectRoot, options.probeDatabase ?? probeDatabaseAt);
+}
+
+export function probeCodegraphAncestors(
+	projectRoot: string,
+	options: CodegraphProjectProbeOptions = {},
+): CodegraphAncestorState {
+	const resolved = resolveProjectRoot(projectRoot);
+	if (resolved.kind === "inconclusive") return resolved;
+	return probeResolvedAncestors(resolved.projectRoot, options.probeDatabase ?? probeDatabaseAt);
+}
+
+function probeResolvedExactProject(
+	projectRoot: string,
+	probeDatabase: (directory: string) => DatabaseState,
+): CodegraphExactProjectState {
+	const exact = probeDatabase(projectRoot);
+	if (exact.kind === "present") return { kind: "initialized" };
+	if (exact.kind === "inconclusive") return exact;
+	return { kind: "uninitialized" };
+}
+
+function probeResolvedAncestors(
+	projectRoot: string,
+	probeDatabase: (directory: string) => DatabaseState,
+): CodegraphAncestorState {
+	let ancestorRoot = dirname(projectRoot);
+	while (ancestorRoot !== projectRoot) {
+		const database = probeDatabase(ancestorRoot);
+		if (database.kind === "present") return { ancestorRoot, kind: "nested-root" };
+		if (database.kind === "inconclusive") return database;
+		const parent = dirname(ancestorRoot);
+		if (parent === ancestorRoot) break;
+		ancestorRoot = parent;
+	}
+	return { kind: "uninitialized" };
+}
+
+function resolveProjectRoot(projectRoot: string):
+	| { readonly kind: "inconclusive"; readonly reason: string }
+	| { readonly kind: "resolved"; readonly projectRoot: string } {
+	try {
+		return { kind: "resolved", projectRoot: realpathSync(projectRoot) };
+	} catch (error) {
+		if (error instanceof Error) return { kind: "inconclusive", reason: error.message };
+		throw error;
+	}
+}
+
+function probeDatabaseAt(directory: string): DatabaseState {
+	try {
+		statSync(join(directory, ".codegraph", "codegraph.db"));
+		return { kind: "present" };
+	} catch (error) {
+		if (!(error instanceof Error)) throw error;
+		const code = errorCode(error);
+		if (code === "ENOENT" || code === "ENOTDIR") return { kind: "missing" };
+		return { kind: "inconclusive", reason: error.message };
+	}
+}
+
+function errorCode(error: unknown): string | undefined {
+	if (typeof error !== "object" || error === null) return undefined;
+	const code = Reflect.get(error, "code");
+	return typeof code === "string" ? code : undefined;
+}