@zhalker/gentle-shell-codegraph-subagents 0.1.0 → 0.2.0

package/src/agents.ts

@@ -1,111 +1,116 @@
-export const CODEGRAPH_MCP_TOOL = "mcp__codegraph__codegraph_explore";
-
-const EXPLORER = "gentle-ai-explore";
-const AGENTS_WITH_MCP_TOOL = new Set([
-	"gentle-ai-explore",
-	"gentle-ai-verify",
-	"gentle-ai-worker",
-	"jd-fix-agent",
-	"jd-judge-a",
-	"jd-judge-b",
-]);
-
-const FRONTMATTER = /^(---\r?\n)([\s\S]*?)(\r?\n---)([\s\S]*)$/;
-const GENTLE_AI_BLOCK = /<!-- gentle-ai:pi-codegraph-(?:tool|guidance) -->[\s\S]*?<!-- \/gentle-ai:pi-codegraph -->/g;
-const MARKER = "\u0000";
-
-function unquote(value: string): string {
-	const v = value.trim();
-	return v.length >= 2 && (v[0] === '"' || v[0] === "'") && v[v.length - 1] === v[0] ? v.slice(1, -1) : v;
-}
-
-// The gentle-pi agent files ship a `- "*": false` list entry; Pi reads it as a tool named `*": false`.
-function isBrokenEntry(item: string): boolean {
-	return /\*["']?\s*:\s*false/.test(item);
-}
-
-const EXPLORER_STRUCTURAL_LINE = "- For structural questions, use the cwd-scoped `codegraph` tool";
-const EXPLORER_INDEX_LINE = "- `codegraph` may create or update only the current workspace `.codegraph/` index";
-const EXPLORER_READ_ONLY_PHRASE = "Other than the explicit `.codegraph/` index exception, read and search only.";
-
-// The explorer loses its `codegraph` extension tool, so the lines that tell it to use or initialize that tool would send it nowhere.
-function rewriteExplorerInstructions(body: string, eol: string): string {
-	if (!body.includes("codegraph")) return body;
-	const out: string[] = [];
-	for (const line of body.split(eol)) {
-		if (line.startsWith(EXPLORER_STRUCTURAL_LINE)) {
-			out.push(`- For structural questions, use the \`${CODEGRAPH_MCP_TOOL}\` tool before broad filesystem searches. It reads the existing \`.codegraph/\` index and cannot create one; when the project has none, use \`read\`, \`grep\`, and \`find\` and say so in the handoff.`);
-		} else if (line.startsWith(EXPLORER_INDEX_LINE)) {
-			continue;
-		} else {
-			out.push(line.replace(EXPLORER_READ_ONLY_PHRASE, "Read and search only."));
-		}
-	}
-	return out.join(eol);
-}
-
-function removeBlocks(body: string, eol: string): string {
-	if (!body.includes("gentle-ai:pi-codegraph")) return body;
-	const marked = body.replace(GENTLE_AI_BLOCK, MARKER);
-	return marked.replace(/\s*\u0000(?:\s*\u0000)*\s*/g, (match, offset: number) => {
-		if (offset === 0) return "";
-		return offset + match.length >= marked.length ? eol : eol + eol;
-	});
-}
-
-
-function editTools(front: string, eol: string): string {
-	const lines = front.split(/\r?\n/);
-	const nameLine = lines.find((line) => /^name:/.test(line));
-	const name = nameLine ? unquote(nameLine.slice("name:".length)) : "";
-	const at = lines.findIndex((line) => /^tools:/.test(line));
-	if (at === -1) return front;
-
-	const rest = lines[at].slice("tools:".length).trim();
-	let style: "bracket" | "csv" | "list";
-	let items: string[];
-	let consumed = 1;
-	let indent = "  ";
-	if (rest.startsWith("[")) {
-		style = "bracket";
-		items = rest.replace(/^\[/, "").replace(/\]$/, "").split(",").map((s) => s.trim()).filter(Boolean);
-	} else if (rest.length > 0) {
-		style = "csv";
-		items = rest.split(",").map((s) => s.trim()).filter(Boolean);
-	} else {
-		style = "list";
-		items = [];
-		for (let i = at + 1; i < lines.length; i++) {
-			const m = /^(\s*)-\s+(.*)$/.exec(lines[i]);
-			if (!m) break;
-			if (items.length === 0) indent = m[1];
-			items.push(m[2].trim());
-			consumed++;
-		}
-	}
-	if (items.length === 0) return front;
-
-	let next = items.filter((item) => unquote(item) !== "mcp" && !isBrokenEntry(item));
-	if (name === EXPLORER) next = next.filter((item) => unquote(item) !== "codegraph");
-	if (AGENTS_WITH_MCP_TOOL.has(name) && !next.some((item) => unquote(item) === CODEGRAPH_MCP_TOOL)) next.push(CODEGRAPH_MCP_TOOL);
-	// An empty list would hand the agent Pi's default tools; keep what was there instead.
-	if (next.length === 0 || next.join("\n") === items.join("\n")) return front;
-
-	const replacement =
-		style === "list" ? ["tools:", ...next.map((item) => `${indent}- ${item}`)]
-		: style === "bracket" ? [`tools: [${next.join(", ")}]`]
-		: [`tools: ${next.join(", ")}`];
-	return [...lines.slice(0, at), ...replacement, ...lines.slice(at + consumed)].join(eol);
-}
-
-/** Returns the agent definition with the CodeGraph wiring applied; identical text when nothing changes. */
-export function normalizeAgent(text: string): string {
-	const match = FRONTMATTER.exec(text);
-	if (!match) return text;
-	const [, open, front, close, body] = match;
-	const eol = text.includes("\r\n") ? "\r\n" : "\n";
-	const name = /^name:\s*(.+)$/m.exec(front)?.[1];
-	const cleaned = removeBlocks(body, eol);
-	const rewritten = name !== undefined && unquote(name) === EXPLORER ? rewriteExplorerInstructions(cleaned, eol) : cleaned;
-	return open + editTools(front, eol) + close + rewritten;
-}
+import { WORKER_MARKER } from "./skill-reminder.ts";
+
+export const CODEGRAPH_MCP_TOOL = "mcp__codegraph__codegraph_explore";
+
+const EXPLORER = "gentle-ai-explore";
+const AGENTS_WITH_MCP_TOOL = new Set([
+	"gentle-ai-explore",
+	"gentle-ai-verify",
+	"gentle-ai-worker",
+	"jd-fix-agent",
+	"jd-judge-a",
+	"jd-judge-b",
+]);
+
+const FRONTMATTER = /^(---\r?\n)([\s\S]*?)(\r?\n---)([\s\S]*)$/;
+const GENTLE_AI_BLOCK = /<!-- gentle-ai:pi-codegraph-(?:tool|guidance) -->[\s\S]*?<!-- \/gentle-ai:pi-codegraph -->/g;
+const MARKER = "\u0000";
+
+function unquote(value: string): string {
+	const v = value.trim();
+	return v.length >= 2 && (v[0] === '"' || v[0] === "'") && v[v.length - 1] === v[0] ? v.slice(1, -1) : v;
+}
+
+// The gentle-pi agent files ship a `- "*": false` list entry; Pi reads it as a tool named `*": false`.
+function isBrokenEntry(item: string): boolean {
+	return /\*["']?\s*:\s*false/.test(item);
+}
+
+const EXPLORER_STRUCTURAL_LINE = "- For structural questions, use the cwd-scoped `codegraph` tool";
+const EXPLORER_INDEX_LINE = "- `codegraph` may create or update only the current workspace `.codegraph/` index";
+const EXPLORER_READ_ONLY_PHRASE = "Other than the explicit `.codegraph/` index exception, read and search only.";
+
+// The explorer loses its `codegraph` extension tool, so the lines that tell it to use or initialize that tool would send it nowhere.
+function rewriteExplorerInstructions(body: string, eol: string): string {
+	if (!body.includes("codegraph")) return body;
+	const out: string[] = [];
+	for (const line of body.split(eol)) {
+		if (line.startsWith(EXPLORER_STRUCTURAL_LINE)) {
+			out.push(`- For structural questions, use the \`${CODEGRAPH_MCP_TOOL}\` tool before broad filesystem searches. It reads the existing \`.codegraph/\` index and cannot create one; when the project has none, use \`read\`, \`grep\`, and \`find\` and say so in the handoff.`);
+		} else if (line.startsWith(EXPLORER_INDEX_LINE)) {
+			continue;
+		} else {
+			out.push(line.replace(EXPLORER_READ_ONLY_PHRASE, "Read and search only."));
+		}
+	}
+	return out.join(eol);
+}
+
+function removeBlocks(body: string, eol: string): string {
+	if (!body.includes("gentle-ai:pi-codegraph")) return body;
+	const marked = body.replace(GENTLE_AI_BLOCK, MARKER);
+	return marked.replace(/\s*\u0000(?:\s*\u0000)*\s*/g, (match, offset: number) => {
+		if (offset === 0) return "";
+		return offset + match.length >= marked.length ? eol : eol + eol;
+	});
+}
+
+
+function editTools(front: string, eol: string): string {
+	const lines = front.split(/\r?\n/);
+	const nameLine = lines.find((line) => /^name:/.test(line));
+	const name = nameLine ? unquote(nameLine.slice("name:".length)) : "";
+	const at = lines.findIndex((line) => /^tools:/.test(line));
+	if (at === -1) return front;
+
+	const rest = lines[at].slice("tools:".length).trim();
+	let style: "bracket" | "csv" | "list";
+	let items: string[];
+	let consumed = 1;
+	let indent = "  ";
+	if (rest.startsWith("[")) {
+		style = "bracket";
+		items = rest.replace(/^\[/, "").replace(/\]$/, "").split(",").map((s) => s.trim()).filter(Boolean);
+	} else if (rest.length > 0) {
+		style = "csv";
+		items = rest.split(",").map((s) => s.trim()).filter(Boolean);
+	} else {
+		style = "list";
+		items = [];
+		for (let i = at + 1; i < lines.length; i++) {
+			const m = /^(\s*)-\s+(.*)$/.exec(lines[i]);
+			if (!m) break;
+			if (items.length === 0) indent = m[1];
+			items.push(m[2].trim());
+			consumed++;
+		}
+	}
+	if (items.length === 0) return front;
+
+	let next = items.filter((item) => unquote(item) !== "mcp" && !isBrokenEntry(item));
+	if (name === EXPLORER) next = next.filter((item) => unquote(item) !== "codegraph");
+	if (AGENTS_WITH_MCP_TOOL.has(name) && !next.some((item) => unquote(item) === CODEGRAPH_MCP_TOOL)) next.push(CODEGRAPH_MCP_TOOL);
+	// An empty list would hand the agent Pi's default tools; keep what was there instead.
+	if (next.length === 0 || next.join("\n") === items.join("\n")) return front;
+
+	const replacement =
+		style === "list" ? ["tools:", ...next.map((item) => `${indent}- ${item}`)]
+		: style === "bracket" ? [`tools: [${next.join(", ")}]`]
+		: [`tools: ${next.join(", ")}`];
+	return [...lines.slice(0, at), ...replacement, ...lines.slice(at + consumed)].join(eol);
+}
+
+/** Returns the agent definition with the CodeGraph wiring applied; identical text when nothing changes. */
+export function normalizeAgent(text: string): string {
+	const match = FRONTMATTER.exec(text);
+	if (!match) return text;
+	const [, open, front, close, body] = match;
+	const eol = text.includes("\r\n") ? "\r\n" : "\n";
+	const name = /^name:\s*(.+)$/m.exec(front)?.[1];
+	const cleaned = removeBlocks(body, eol);
+	let rewritten = name !== undefined && unquote(name) === EXPLORER ? rewriteExplorerInstructions(cleaned, eol) : cleaned;
+	if (name !== undefined && unquote(name) === "gentle-ai-worker" && !rewritten.includes(WORKER_MARKER)) {
+		rewritten = rewritten.trimEnd() + eol + eol + WORKER_MARKER + eol;
+	}
+	return open + editTools(front, eol) + close + rewritten;
+}

package/src/apply.ts

@@ -1,60 +1,119 @@
-import { existsSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { normalizeAgent } from "./agents.ts";
-import { normalizeMcpConfig } from "./mcp.ts";
-
-export interface ApplyResult {
-	/** Files that were rewritten. */
-	changed: string[];
-	/** One message per file that could not be processed. */
-	errors: string[];
-}
-
-const BACKUP_SUFFIX = ".pre-codegraph-subagents.bak";
-
-// Write beside the target and rename, so a reader never sees a half-written file.
-function writeAtomic(file: string, text: string): void {
-	const temp = `${file}.${process.pid}.tmp`;
-	try {
-		writeFileSync(temp, text);
-		renameSync(temp, file);
-	} catch (error) {
-		try { unlinkSync(temp); } catch { /* nothing to clean */ }
-		throw error;
-	}
-}
-
-function rewrite(file: string, normalize: (text: string) => string, result: ApplyResult): void {
-	try {
-		const before = readFileSync(file, "utf8");
-		const after = normalize(before);
-		if (after === before) return;
-		const backup = file + BACKUP_SUFFIX;
-		if (!existsSync(backup)) writeFileSync(backup, before, { flag: "wx" });
-		writeAtomic(file, after);
-		result.changed.push(file);
-	} catch (error) {
-		result.errors.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
-	}
-}
-
-/**
- * Applies the CodeGraph wiring to the global agent definitions and to mcp.json
- * under `agentDir`. Idempotent and never throws: failures are returned in `errors`.
- */
-export function applyCodegraphSubagents(agentDir: string): ApplyResult {
-	const result: ApplyResult = { changed: [], errors: [] };
-	for (const folder of ["agents", "subagents"]) {
-		const dir = join(agentDir, folder);
-		let entries: string[];
-		try {
-			entries = readdirSync(dir).filter((entry) => entry.toLowerCase().endsWith(".md")).sort();
-		} catch {
-			continue;
-		}
-		for (const entry of entries) rewrite(join(dir, entry), normalizeAgent, result);
-	}
-	const mcp = join(agentDir, "mcp.json");
-	if (existsSync(mcp)) rewrite(mcp, normalizeMcpConfig, result);
-	return result;
-}
+import { existsSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { normalizeAgent } from "./agents.ts";
+import { inspectEffectiveMcpExposure, isCodegraphServerMissing, normalizeMcpConfig } from "./mcp.ts";
+
+export interface ApplyResult {
+	/** Files that were rewritten. */
+	changed: string[];
+	/** One message per file that could not be processed. */
+	errors: string[];
+}
+
+const BACKUP_SUFFIX = ".pre-codegraph-subagents.bak";
+
+/** Reads the effective file settings only; untrusted project configuration is not loaded by Pi. */
+export function readExposureWarning(agentDir: string, cwd: string, projectTrusted: boolean): string | undefined {
+	const read = (path: string): string | undefined => {
+		try { return readFileSync(path, "utf8"); } catch { return undefined; }
+	};
+	const global = read(join(agentDir, "mcp.json")) ?? "{}";
+	const project = projectTrusted ? read(join(cwd, ".pi", "mcp.json")) : undefined;
+	return inspectEffectiveMcpExposure(global, project);
+}
+
+/** Reports absent file configuration without creating it; registered servers also count. */
+export function readMissingServerWarning(agentDir: string, cwd: string, projectTrusted: boolean, registered = false): boolean {
+	const read = (path: string): string | undefined => {
+		try { return readFileSync(path, "utf8"); } catch (error) {
+			return codeOf(error) === "ENOENT" ? undefined : "invalid";
+		}
+	};
+	const global = read(join(agentDir, "mcp.json")) ?? "{}";
+	const project = projectTrusted ? read(join(cwd, ".pi", "mcp.json")) : undefined;
+	return isCodegraphServerMissing(global, project, registered);
+}
+
+// Write beside the target and rename, so a reader never sees a half-written file.
+function writeAtomic(file: string, text: string): void {
+	const temp = `${file}.${process.pid}.tmp`;
+	try {
+		writeFileSync(temp, text);
+		renameSync(temp, file);
+	} catch (error) {
+		try { unlinkSync(temp); } catch { /* nothing to clean */ }
+		throw error;
+	}
+}
+
+// Several sessions can start at the same moment and rewrite the same files: on Windows a rename over a file
+// another session is replacing fails with one of these, and a retry finds the work already done.
+const TRANSIENT_CODES = new Set(["EPERM", "EBUSY", "EACCES", "ENOENT"]);
+const ATTEMPTS = 8;
+
+const codeOf = (error: unknown): string | undefined => (error as { code?: string } | null)?.code;
+
+function pauseBriefly(): void {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10 + Math.floor(Math.random() * 30));
+}
+
+// The backup holds the original, so whoever gets there first wins and the others leave it alone.
+function saveBackupOnce(file: string, original: string): void {
+	try {
+		writeFileSync(file + BACKUP_SUFFIX, original, { flag: "wx" });
+	} catch (error) {
+		if (codeOf(error) !== "EEXIST") throw error;
+	}
+}
+
+function alreadyNormalized(file: string, normalize: (text: string) => string): boolean {
+	try {
+		const text = readFileSync(file, "utf8");
+		return normalize(text) === text;
+	} catch {
+		return false;
+	}
+}
+
+function rewrite(file: string, normalize: (text: string) => string, result: ApplyResult): void {
+	let failure: unknown;
+	for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+		try {
+			const before = readFileSync(file, "utf8");
+			const after = normalize(before);
+			// Already right: nothing to do, or another session just did it.
+			if (after === before) return;
+			saveBackupOnce(file, before);
+			writeAtomic(file, after);
+			result.changed.push(file);
+			return;
+		} catch (error) {
+			failure = error;
+			if (!TRANSIENT_CODES.has(codeOf(error) ?? "")) break;
+			pauseBriefly();
+		}
+	}
+	if (alreadyNormalized(file, normalize)) return;
+	result.errors.push(`${file}: ${failure instanceof Error ? failure.message : String(failure)}`);
+}
+
+/**
+ * Applies the CodeGraph wiring to the global agent definitions and to mcp.json
+ * under `agentDir`. Idempotent and never throws: failures are returned in `errors`.
+ */
+export function applyCodegraphSubagents(agentDir: string): ApplyResult {
+	const result: ApplyResult = { changed: [], errors: [] };
+	for (const folder of ["agents", "subagents"]) {
+		const dir = join(agentDir, folder);
+		let entries: string[];
+		try {
+			entries = readdirSync(dir).filter((entry) => entry.toLowerCase().endsWith(".md")).sort();
+		} catch {
+			continue;
+		}
+		for (const entry of entries) rewrite(join(dir, entry), normalizeAgent, result);
+	}
+	const mcp = join(agentDir, "mcp.json");
+	if (existsSync(mcp)) rewrite(mcp, normalizeMcpConfig, result);
+	return result;
+}

package/src/autoindex.ts

@@ -0,0 +1,167 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { codegraphWritingIndex, type InitLock } from "./initlock.ts";
+import { killTree } from "./prefetch.ts";
+
+export { codegraphWritingIndex } from "./initlock.ts";
+
+/** One of these next to a `.git` is what makes a directory a project worth indexing automatically. */
+export const INIT_PROJECT_MARKERS = ["composer.json", "package.json", "pyproject.toml", "go.mod", "Cargo.toml", "Gemfile", "pom.xml", "build.gradle", "build.gradle.kts"];
+
+export const SYNC_TIMEOUT_MS = 120_000;
+export const INIT_TIMEOUT_MS = 600_000;
+
+const CHILD_ENV = "GENTLE_PI_AGENTS_CHILD";
+
+export type IndexAction = "sync" | "init" | "none";
+export type SessionStartReason = "startup" | "reload" | "new" | "resume" | "fork";
+
+/** An existing index is synced; a fresh git project with a marker file is initialised; anything else is left alone. */
+export function planIndexAction(cwd: string, exists: (path: string) => boolean): IndexAction {
+	if (exists(join(cwd, ".codegraph"))) return "sync";
+	if (exists(join(cwd, ".git")) && INIT_PROJECT_MARKERS.some((marker) => exists(join(cwd, marker)))) return "init";
+	return "none";
+}
+
+export interface AutoIndexInput {
+	/** Where Pi was started. */
+	cwd: string;
+	env: Record<string, string | undefined>;
+	reason: SessionStartReason;
+	exists(path: string): boolean;
+	/** One init per project across sessions; absent means no coordination (the unit tests). */
+	lock?: InitLock;
+	/** Called right before the command starts, so the user can be told what is going on. */
+	onStart?(action: "sync" | "init"): void;
+	/** Whether CodeGraph is writing this index right now; defaults to {@link codegraphWritingIndex}. */
+	codegraphBusy?(cwd: string): boolean;
+	/** Runs `codegraph <args>` in `cwd`; true when it exited 0. `onSpawn` gets the pid of that process. */
+	run(args: string[], cwd: string, timeoutMs: number, onSpawn?: (pid: number, options?: { proxy?: boolean }) => void): Promise<boolean>;
+}
+
+/** Subagent children share the parent's cwd and the parent already did the work; a /reload is not a new session. */
+function skipsSession(input: Pick<AutoIndexInput, "env" | "reason">): boolean {
+	return input.env[CHILD_ENV] === "1" || input.reason === "reload";
+}
+
+export interface AutoIndexResult {
+	action: IndexAction;
+	ok: boolean;
+	/** Another session was already creating the index, so this one left it alone. */
+	joined?: boolean;
+}
+
+/** Brings the CodeGraph index of the project Pi started in up to date, or creates it. Never rejects. */
+export async function autoIndex(input: AutoIndexInput): Promise<AutoIndexResult> {
+	try {
+		if (skipsSession(input)) return { action: "none", ok: true };
+		const action = planIndexAction(input.cwd, input.exists);
+		if (action === "none") return { action, ok: true };
+		const announce = () => { try { input.onStart?.(action); } catch { /* telling the user is never worth stopping the index */ } };
+		if (action === "sync") {
+			// Another session is creating the index: nothing may touch it meanwhile, a sync included.
+			if (input.lock?.isHeld(input.cwd)) return { action, ok: true, joined: true };
+			announce();
+			return { action, ok: await input.run(["sync", "-q"], input.cwd, SYNC_TIMEOUT_MS) };
+		}
+		const attempt = input.lock?.acquire(input.cwd);
+		if (attempt?.status === "busy") return { action, ok: true, joined: true };
+		const adopt = attempt?.status === "acquired" ? attempt.adopt : () => {};
+		try {
+			if (input.exists(join(input.cwd, ".codegraph"))) {
+				// Another party (another tool, a terminal) created the index while this session waited for the lock.
+				return { action, ok: true, joined: true };
+			}
+			announce();
+			// The lock records the pid of the init, so it stays held while that process lives, even after this session.
+			const initialised = await input.run(["init", "-y"], input.cwd, INIT_TIMEOUT_MS, (pid, options) => adopt(pid, options));
+			if (!initialised && (input.codegraphBusy ?? codegraphWritingIndex)(input.cwd)) {
+				// CodeGraph's own lock still names a live init: another party is building this index, not this session.
+				return { action, ok: true, joined: true };
+			}
+			// A failure of this session's own init, with or without a half-built index, is a failure.
+			return { action, ok: initialised };
+		} finally {
+			attempt?.release();
+		}
+	} catch {
+		return { action: planIndexAction(input.cwd, input.exists), ok: false };
+	}
+}
+
+/** How long a killed init may take to be gone before the timeout is reported anyway. */
+const KILL_WAIT_MS = 10_000;
+
+/**
+ * Runs the codegraph CLI with fixed arguments; the project is the working directory, never an argument.
+ * `onSpawn` gets the pid of the process, which the init lock records, and whether that pid is only the shell
+ * that was spawned around the real init (Windows runs the npm shim through a shell). A timeout kills the
+ * process tree and only reports the failure once that process is gone: its pid must not outlive the result.
+ */
+export function runCodegraph(args: string[], cwd: string, timeoutMs: number, onSpawn?: (pid: number, options?: { proxy?: boolean }) => void): Promise<boolean> {
+	return new Promise((resolve) => {
+		let settled = false;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let grace: ReturnType<typeof setTimeout> | undefined;
+		const finish = (ok: boolean) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			clearTimeout(grace);
+			resolve(ok);
+		};
+		let child;
+		// Windows needs a shell to run the .cmd shim that npm installs for codegraph: the pid that comes back is
+		// that shell, not the process that ends up writing the index.
+		const shelled = process.platform === "win32";
+		try {
+			child = shelled
+				? spawn(["codegraph", ...args].join(" "), { cwd, shell: true, windowsHide: true, stdio: "ignore" })
+				: spawn("codegraph", args, { cwd, windowsHide: true, stdio: "ignore" });
+		} catch {
+			resolve(false);
+			return;
+		}
+		if (child.pid !== undefined) {
+			try { onSpawn?.(child.pid, { proxy: shelled }); } catch { /* recording the pid is never worth failing the init */ }
+		}
+		timer = setTimeout(() => {
+			killTree(child.pid, child);
+			// A killed init may still be closing; the lock lookup waits for it, up to a point.
+			grace = setTimeout(() => finish(false), KILL_WAIT_MS);
+		}, timeoutMs);
+		child.on("error", () => finish(false));
+		child.on("close", (code) => finish(code === 0));
+	});
+}
+
+export interface PrepareInput extends AutoIndexInput {
+	/** Called as soon as the sync or init is over, before the warm-up starts. */
+	onIndexed?(result: AutoIndexResult): void;
+	/** Called right before the daemon warm-up starts. */
+	onWarmStart?(): void;
+	/** Makes the project's daemon ready for its first real call; true when it worked. */
+	warm(cwd: string): Promise<boolean>;
+}
+
+export interface PrepareResult {
+	index: AutoIndexResult;
+	warm: "ok" | "failed" | "skipped";
+}
+
+/** The index first (sync or init), then, when an index exists, the daemon warm-up. Never rejects. */
+export async function prepareProject(input: PrepareInput): Promise<PrepareResult> {
+	const index = await autoIndex(input);
+	if (index.action !== "none") {
+		try { input.onIndexed?.(index); } catch { /* telling the user is never worth stopping the warm-up */ }
+	}
+	// A sync that failed still leaves an index to warm; a failed init leaves nothing worth warming.
+	const hasIndex = !index.joined && (index.action === "sync" || (index.action === "init" && index.ok));
+	if (skipsSession(input) || !hasIndex) return { index, warm: "skipped" };
+	try { input.onWarmStart?.(); } catch { /* telling the user is never worth stopping the warm-up */ }
+	try {
+		return { index, warm: (await input.warm(input.cwd)) ? "ok" : "failed" };
+	} catch {
+		return { index, warm: "failed" };
+	}
+}