@zhalker/gentle-shell-codegraph-subagents 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @zhalker/gentle-shell-codegraph-subagents
+
+Pi package that keeps CodeGraph reachable from gentle-shell subagents. On every session start it checks the global agent definitions and `mcp.json` and fixes what gentle-ai or the gentle-pi package left behind. Nothing is rewritten when everything is already right.
+
+> **This package edits files in your Pi configuration.** On every session start it rewrites the agent definitions in `~/.pi/agent/agents/` and `~/.pi/agent/subagents/` and the `codegraph` entry in `~/.pi/agent/mcp.json`. It keeps a one-time backup of each file it changes as `<file>.pre-codegraph-subagents.bak`. Read "What it does" before installing, and see "Uninstall" to go back.
+
+Upstream issue: Gentleman-Programming/gentle-shell#2804. License: MIT.
+
+## What it does
+
+In `~/.pi/agent/agents/` and `~/.pi/agent/subagents/` (or `$PI_CODING_AGENT_DIR`):
+
+- Removes the blocks gentle-ai writes between `<!-- gentle-ai:pi-codegraph-tool -->` / `<!-- gentle-ai:pi-codegraph-guidance -->` and `<!-- /gentle-ai:pi-codegraph -->`.
+- Removes the dead `mcp` entry (the retired `pi-mcp-adapter` proxy) and the `"*": false` entry from every `tools:` list.
+- Adds `mcp__codegraph__codegraph_explore` to `gentle-ai-explore`, `gentle-ai-verify`, `gentle-ai-worker`, `jd-fix-agent`, `jd-judge-a` and `jd-judge-b`, removes the `codegraph` extension tool from `gentle-ai-explore`, and rewrites that agent's own CodeGraph instructions to use the MCP tool. Adds a routing marker to `gentle-ai-worker` for its first-prompt skill reminder.
+- Leaves the `review-*` agents without CodeGraph.
+
+The package also provides the `codegraph-workflow` skill. When Pi loads this packaged skill, the extension adds a reminder before the first user prompt of the parent session and the first prompt of `gentle-ai-worker` children. It does not add the reminder to other children. Pi handles skill name collisions; if Pi selects a different skill with that name, the extension does not direct the model to it as if it were the packaged skill. A local package is discovered in place rather than copied to the user's skills directory.
+
+In `mcp.json`: selects `"direct"` for `codegraph_explore` under `toolExposure`, without changing the server-wide exposure. Explicit tool settings (including matching patterns), disabled servers, and hidden servers are preserved. At session start Pi warns when the CodeGraph MCP server is not configured, without creating it, or when direct subagent access may be unavailable; it also warns if a hidden server has an explicit direct explore exception, which Pi can still expose. Trusted project MCP configuration and servers registered by extensions are considered. A configuration change may require a reload before Pi uses it.
+
+In a subagent that only reads and holds `mcp__codegraph__codegraph_explore` (the explorer), a `before_agent_start` hook also runs `codegraph_explore` for its task once before the first model call and hands the output to the model as a message, bounded to 20 s and 12,000 characters. It asks the project's running CodeGraph daemon directly (the same text as the CLI, locally ~75 ms against ~590 ms); when there is no usable daemon it runs `codegraph explore <task>` instead, and it never starts a daemon. If the project has no `.codegraph/` index, the package's init lock is held, or neither way works, nothing is added and the run continues as before.
+
+In the directory where Pi starts, a new session also looks after the CodeGraph index, in the background (the session never waits for it):
+
+- If `.codegraph/` exists, it runs `codegraph sync`. The CodeGraph file watcher does not work on SMB mounts, so without this the index stays as it was.
+- If there is no `.codegraph/`, but there is a `.git` and one of `composer.json`, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `pom.xml`, `build.gradle` or `build.gradle.kts`, it runs `codegraph init -y`. In any other directory nothing is created.
+- When there is an index (existing, or just created), it then warms the project's CodeGraph daemon: a short MCP client runs one small `codegraph_explore` and disconnects, and the daemon stays up for as long as your session keeps it. The first real call of the orchestrator and of every subagent is then fast (locally 620-650 ms cold against ~70 ms warm). The explorer's pre-fetch asks that same daemon, so it gets the same speed-up.
+- Pi shows a notice when each step starts ("syncing the CodeGraph index...", "creating the CodeGraph index of this project...", "warming up CodeGraph...") and another when it ends ("CodeGraph index synced", "CodeGraph index created", "CodeGraph ready"), or a warning if it failed.
+- Concurrent rewrites of agent files and `mcp.json` are tolerated (an existing backup is kept, and transient collisions are retried). A per-project lock in the user's temp folder coordinates package-started initializations: a session that finds it held skips init, sync and warm-up, and the explorer skips its prefetch. When a session exits during init, the package also checks CodeGraph's writer lock. On Windows it conservatively holds the package lock for 60 seconds after spawning the shell, covering the period before CodeGraph writes its own lock. Locks are treated as stale after 11 minutes.
+- Subagent children and `/reload` do nothing; startup, new, resume and fork do.
+
+Before the first change to a file it saves the original next to it as `<file>.pre-codegraph-subagents.bak`; later changes never overwrite that backup.
+
+## Install
+
+```
+pi install npm:@zhalker/gentle-shell-codegraph-subagents
+```
+
+Changes apply on the next session start. Reinstalling, or running `gentle-ai sync` again, is corrected the same way on the following start.
+
+## Uninstall
+
+Remove the package, then copy each `*.pre-codegraph-subagents.bak` over its original if you want the previous files back.
+
+## Known limits
+
+- Only the global agent directory is handled, not `<project>/.pi/agents/`.
+- The warm-up has only been measured on local disks, not on a network share. It never kills the processes it starts, because the daemon is shared with your own sessions.
+- CodeGraph's own `init` can hang when two start at once, or when a daemon opens the project just after the index is created. The package lock only coordinates sessions sharing the same user temp folder; it cannot prevent access by a terminal, another tool, another user, or Pi's own MCP connection. On Windows, if the session and shell exit before CodeGraph writes its own lock and that takes more than 60 seconds, the package cannot tell that init is still running. The 11-minute stale-lock limit can also expire while a process remains alive.
+- The index sync is a background command: a prefetch that runs before it finishes can see the previous index. The sync only looks at the directory where Pi starts, not at parents or subfolders. Treat prefetched results as navigation hints, not authoritative evidence: they can be stale, incomplete, truncated or incorrect; verify findings against source files.
+- Asking the daemon directly relies on two internal details of CodeGraph: the registry in `~/.codegraph/daemons/` and the hello line with `protocol: 1`. If either changes, or the daemon answers anything unexpected, the CLI is used, as before. A daemon that is there but does not answer within 20 s is not retried through the CLI.
+- The explorer prefetch requires the launcher to set `GENTLE_PI_AGENTS_CHILD=1` and `GENTLE_PI_AGENTS_REQUESTED_TOOLS` to the child's declared comma-separated tool list. It recognizes a read-only child with the CodeGraph MCP tool and no writing tools; this declaration does not prove the MCP tool actually connected. Without these launcher variables the prefetch is skipped. The first 300 sanitized characters of the task become the query, so verbose instructions can broaden the result; the returned context is capped at 12,000 characters.
+- The rewrite of the explorer's own instructions matches known sentences; if gentle-pi rewords them, they are left as they are.
+- The `codegraph` MCP server has to be configured or registered by an extension; the package never creates it. When Pi is launched from a GUI or service, its `PATH` may differ from your shell. An absolute MCP server command can fix the server launch, but this package's `init`, `sync` and CLI fallback still need `codegraph` on Pi's `PATH`.
+- Tested with Pi 1.4.0 and node 24.
+
+## Development
+
+`npm test` runs the unit tests with Node's built-in runner.

package/extensions/index.ts

@@ -0,0 +1,99 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { applyCodegraphSubagents, readExposureWarning, readMissingServerWarning } from "../src/apply.ts";
+import { prepareProject, runCodegraph, type SessionStartReason } from "../src/autoindex.ts";
+import { exploreViaDaemon } from "../src/daemonclient.ts";
+import { realInitLock } from "../src/initlock.ts";
+import { PREFETCH_TIMEOUT_MS, exploreDaemonFirst, exploreWithCodegraph, prefetchForExplorer } from "../src/prefetch.ts";
+import { warmUpDaemon } from "../src/warmup.ts";
+import { chooseSkillReminder, SKILL_REMINDER_TYPE } from "../src/skill-reminder.ts";
+
+// Starts the index sync (or first init) and then the daemon warm-up in the background; the session never waits for them.
+function startAutoIndex(reason: SessionStartReason, ctx: ExtensionContext): void {
+	const say = (text: string, level: "info" | "warning") => {
+		if (ctx.hasUI) ctx.ui.notify(`gentle-shell-codegraph-subagents: ${text}`, level);
+	};
+	prepareProject({
+		cwd: ctx.cwd,
+		env: process.env,
+		reason,
+		exists: existsSync,
+		run: runCodegraph,
+		lock: realInitLock,
+		warm: (cwd) => warmUpDaemon(cwd),
+		onStart: (action) => say(action === "init" ? "creating the CodeGraph index of this project..." : "syncing the CodeGraph index...", "info"),
+		onIndexed: (result) => {
+			if (result.joined) say("another session is creating the CodeGraph index of this project", "info");
+			else if (!result.ok) say(`codegraph ${result.action} failed in ${ctx.cwd}`, "warning");
+			else say(result.action === "init" ? "CodeGraph index created" : "CodeGraph index synced", "info");
+		},
+		onWarmStart: () => say("warming up CodeGraph...", "info"),
+	})
+		.then((result) => {
+			if (result.warm === "ok") say("CodeGraph ready", "info");
+			else if (result.warm === "failed") say(`CodeGraph warm-up failed in ${ctx.cwd}`, "warning");
+		})
+		.catch(() => {
+			// The session may already be gone; nothing to report to.
+		});
+}
+
+// Reapplied on every session start so a reinstall (pi install, gentle-shell install)
+// or a gentle-ai sync that rewrote the agent files is corrected on the next launch.
+export default function (pi: ExtensionAPI) {
+	let firstPromptSeen = false;
+	pi.on("session_start", async (event, ctx) => {
+		startAutoIndex(event.reason, ctx);
+		try {
+			const { changed, errors } = applyCodegraphSubagents(getAgentDir());
+			if (!ctx.hasUI) return;
+			if (changed.length > 0) ctx.ui.notify(`gentle-shell-codegraph-subagents: updated ${changed.length} file(s)`, "info");
+			if (errors.length > 0) ctx.ui.notify(`gentle-shell-codegraph-subagents: ${errors.length} file(s) skipped: ${errors[0]}`, "warning");
+			const registered = pi.getMcpServers?.().some((server) => server.name === "codegraph") ?? false;
+			if (process.env.GENTLE_PI_AGENTS_CHILD !== "1" && readMissingServerWarning(getAgentDir(), ctx.cwd, ctx.isProjectTrusted(), registered)) {
+				ctx.ui.notify("gentle-shell-codegraph-subagents: CodeGraph MCP server was not found in the current configuration. Subagents may not have direct access; configure the server to enable it.", "warning");
+			}
+			const exposure = readExposureWarning(getAgentDir(), ctx.cwd, ctx.isProjectTrusted());
+			if (exposure === "hidden-with-direct") ctx.ui.notify("gentle-shell-codegraph-subagents: CodeGraph server is hidden, but its direct explore exception is configured to expose that tool. Your settings were preserved.", "warning");
+			else if (exposure) ctx.ui.notify(`gentle-shell-codegraph-subagents: CodeGraph explore is configured as ${exposure}; direct subagent access may be unavailable. Your setting was preserved.`, "warning");
+		} catch {
+			// Never block a session over this.
+		}
+	});
+
+	// Only the explorer child: hand it `codegraph explore` for its task before its first model call.
+	// Without .codegraph, the CLI, or in time, the run goes on exactly as before.
+	pi.on("before_agent_start", async (event, ctx) => {
+		try {
+			const alreadySent = firstPromptSeen || ctx.sessionManager.getBranch().some((entry) => entry.type === "custom_message" && entry.customType === SKILL_REMINDER_TYPE);
+			const reminder = chooseSkillReminder({
+				expectedPath: join(import.meta.dirname, "..", "skills", "codegraph-workflow", "SKILL.md"),
+				skills: event.systemPromptOptions?.skills ?? [],
+				child: process.env.GENTLE_PI_AGENTS_CHILD === "1",
+				systemPrompt: event.systemPrompt,
+				alreadySent,
+				isUserPrompt: event.messageType === "user",
+			});
+			if (event.messageType === "user") firstPromptSeen = true;
+			const prompt = event.messageType === "user" ? event.prompt : undefined;
+			const content = await prefetchForExplorer({
+				env: process.env,
+				prompt,
+				cwd: process.cwd(),
+				exists: existsSync,
+				initRunning: (cwd) => realInitLock.isHeld(cwd),
+				explore: (query, cwd) =>
+					exploreDaemonFirst(query, cwd, {
+						daemon: (q, c) => exploreViaDaemon(c, q, PREFETCH_TIMEOUT_MS),
+						cli: exploreWithCodegraph,
+					}),
+			});
+			if (reminder) return { message: { customType: SKILL_REMINDER_TYPE, content: [reminder, content].filter(Boolean).join("\n\n"), display: false } };
+			if (content === undefined) return undefined;
+			return { message: { customType: "codegraph-prefetch", content, display: false } };
+		} catch {
+			return undefined;
+		}
+	});
+}

package/package.json

@@ -1,6 +1,39 @@
-{
-  "name": "@zhalker/gentle-shell-codegraph-subagents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@zhalker/gentle-shell-codegraph-subagents",
+  "version": "0.2.0",
+  "description": "Pi package that keeps CodeGraph reachable from gentle-shell subagents: normalizes agent tool lists and the codegraph MCP exposure on every session start, and pre-fetches CodeGraph for the explorer.",
+  "license": "MIT",
+  "author": "zhalker",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "codegraph",
+    "subagents",
+    "gentle-shell",
+    "gentle-ai",
+    "mcp"
+  ],
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.ts\"",
+    "prepublishOnly": "npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/skills/codegraph-workflow/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: codegraph-workflow
+description: "Trigger: investigate, analyze, refactor, fix, or review code. Use CodeGraph to navigate indexed code before broad symbol searches."
+---
+
+# CodeGraph workflow
+
+## Activation Contract
+
+Use this workflow for code investigation, analysis, refactoring, fixes,
+or review. For unrelated tasks, do not invoke CodeGraph just because
+this skill is available.
+
+## Hard Rules
+
+- When an applicable index and a CodeGraph tool are available, use
+  CodeGraph before broad symbol searches.
+- Do not run `codegraph index` before every query.
+- Do not initialize or update an index independently of the package's
+  startup policy or explicit user authorization.
+- Treat CodeGraph results as navigation hints, not authoritative source.
+  Confirm relevant behavior and findings against the source files.
+
+## Decision Gates
+
+- For exact strings, filenames, configuration, or a known file, use the
+  appropriate file or search tool directly.
+- If CodeGraph is unavailable, fails, or has no applicable index, continue
+  with the available read and search tools. Do not repeatedly retry it.
+- If indexing or synchronization is still running, do not assume the
+  results are current. Do not start another index operation.
+- When working across projects or worktrees, use only an index and a
+  project path the current tool and the user's scope permit.
+
+## Delegation
+
+- If a subagent cannot use CodeGraph, the parent may query it and include
+  relevant findings and paths in the handoff.
+- Respect each subagent's tool restrictions. Do not require `bash` from
+  a read-only explorer.
+
+## Output Contract
+
+When relevant, report unavailable or potentially stale index evidence and
+distinguish CodeGraph findings from behavior verified in source.

package/src/agents.ts

@@ -0,0 +1,116 @@
+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

@@ -0,0 +1,119 @@
+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;
+}