@oh-my-pi/pi-coding-agent 17.2.12 → 17.2.13

package/src/cli/update-cli.ts

@@ -63,9 +63,14 @@ function currentNativeTag(): string {
 	return `${process.platform}-${process.arch}`;
 }
 
+/** Distribution channel advertised by a release's published npm manifest. */
+export type ReleaseDist = "npm" | "binary";
+
 interface ReleaseInfo {
 	tag: string;
 	version: string;
+	/** Parsed `omp.dist` from the registry manifest; undefined when absent. */
+	dist?: ReleaseDist;
 }
 
 export interface ReleaseBinaryAsset {
@@ -80,6 +85,47 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
+/**
+ * Parse the `omp.dist` field from a published package manifest.
+ *
+ * Forward-compatibility contract with future releases: a release that is not
+ * installable as an npm package (e.g. a native rewrite) publishes
+ * `"omp": { "dist": "binary" }` in its package.json. Any value other than
+ * "npm" — including values this updater does not know yet — maps to "binary"
+ * so already-deployed updaters never run a package-manager install against a
+ * release that no longer supports it.
+ */
+export function resolveReleaseDist(manifest: unknown): ReleaseDist | undefined {
+	if (!isRecord(manifest) || !isRecord(manifest.omp)) return undefined;
+	const dist = manifest.omp.dist;
+	if (dist === undefined) return undefined;
+	return dist === "npm" ? "npm" : "binary";
+}
+
+function majorVersion(version: string): number {
+	const major = Number.parseInt(version, 10);
+	return Number.isNaN(major) ? 0 : major;
+}
+
+/**
+ * Whether the update must bypass bun/npm and install the release binary.
+ *
+ * An explicit `omp.dist` wins in both directions. Without one, a release with
+ * a higher major than the running build is assumed not npm-installable: the
+ * runtime may have changed out from under the package layout, and the pinned
+ * `@oh-my-pi/pi-natives*` companions ({@link buildBunInstallArgs}) may not
+ * exist at that version, which would strand bun/npm-managed installs behind a
+ * hard install failure. Homebrew and mise installs are unaffected — both
+ * already pull GitHub release binaries.
+ */
+export function shouldForceBinaryUpdate(
+	release: { version: string; dist?: ReleaseDist },
+	currentVersion: string = VERSION,
+): boolean {
+	if (release.dist !== undefined) return release.dist === "binary";
+	return majorVersion(release.version) > majorVersion(currentVersion);
+}
+
 /**
  * Select and validate the binary asset from GitHub release metadata.
  */
@@ -394,9 +440,9 @@ interface UpdateMethodResolutionOptions {
 type UpdateTarget =
 	| { method: "brew" }
 	| { method: "mise" }
-	| { method: "bun" }
-	| { method: "npm" }
-	| { method: "binary"; path: string };
+	| { method: "bun"; path?: string }
+	| { method: "npm"; path?: string }
+	| { method: "binary"; path: string; replacesSymlink: boolean };
 
 function resolveUpdateMethod(
 	ompPath: string,
@@ -433,9 +479,18 @@ export function resolveUpdateMethodForTest(
 ): UpdateMethod {
 	return resolveUpdateMethod(ompPath, bunBinDir, options);
 }
-async function resolveUpdateTarget(): Promise<UpdateTarget> {
-	const bunBinDir = await getBunGlobalBinDir();
-	const npmBinDir = await getNpmGlobalBinDir();
+/**
+ * Resolve how the running install should be updated.
+ *
+ * `allowPackageManagers: false` skips the `bun pm bin -g` / `npm prefix -g`
+ * probes entirely — used for binary-only releases, where routing through a
+ * package manager is never valid and the probes would be wasted subprocesses.
+ * Homebrew/mise detection always runs: both managers install GitHub release
+ * binaries and stay valid regardless of how the release is distributed.
+ */
+async function resolveUpdateTarget(options: { allowPackageManagers: boolean }): Promise<UpdateTarget> {
+	const bunBinDir = options.allowPackageManagers ? await getBunGlobalBinDir() : undefined;
+	const npmBinDir = options.allowPackageManagers ? await getNpmGlobalBinDir() : undefined;
 	const homebrewPrefix = await getHomebrewFormulaPrefix();
 	const miseAvailable = $which("mise") !== undefined;
 	const miseBinDirs = miseAvailable ? await getMiseBinDirs() : [];
@@ -448,9 +503,11 @@ async function resolveUpdateTarget(): Promise<UpdateTarget> {
 		// overlaps the installer's default (~/.local/bin), that file type — not
 		// directory containment — distinguishes a binary install from npm/bun.
 		let ompIsRegularFile = false;
+		let ompIsSymlink = false;
 		try {
 			const stat = fs.lstatSync(ompPath);
 			ompIsRegularFile = stat.isFile() && !stat.isSymbolicLink();
+			ompIsSymlink = stat.isSymbolicLink();
 		} catch {}
 		const method = resolveUpdateMethod(ompPath, bunBinDir, {
 			homebrewPrefix,
@@ -459,7 +516,8 @@ async function resolveUpdateTarget(): Promise<UpdateTarget> {
 			npmBinDir,
 			ompIsRegularFile,
 		});
-		if (method === "binary") return { method, path: ompPath };
+		if (method === "binary") return { method, path: ompPath, replacesSymlink: ompIsSymlink };
+		if (method === "bun" || method === "npm") return { method, path: ompPath };
 		return { method };
 	}
 
@@ -488,13 +546,16 @@ async function getLatestRelease(): Promise<ReleaseInfo> {
 		throw new Error(`Failed to fetch release info: ${response.statusText}`);
 	}
 
-	const data = (await response.json()) as { version: string };
+	const data: unknown = await response.json();
+	if (!isRecord(data) || typeof data.version !== "string") {
+		throw new Error("Malformed npm registry response: missing version");
+	}
 	const version = data.version;
-	const tag = `v${version}`;
 
 	return {
-		tag,
+		tag: `v${version}`,
 		version,
+		dist: resolveReleaseDist(data),
 	};
 }
 
@@ -788,24 +849,31 @@ function resolveOmpPath(): string | undefined {
 }
 
 /**
- * Run the resolved omp binary and check if it reports the expected version.
+ * Run a specific binary and check if it reports the expected version.
  */
-async function verifyInstalledVersion(expectedVersion: string): Promise<InstalledVersionVerification> {
-	const ompPath = resolveOmpPath();
-	if (!ompPath) return { ok: false };
+async function verifyBinaryAtPath(binaryPath: string, expectedVersion: string): Promise<InstalledVersionVerification> {
 	try {
-		const result = await $`${ompPath} --version`.quiet().nothrow();
-		if (result.exitCode !== 0) return { ok: false, path: ompPath };
+		const result = await $`${binaryPath} --version`.quiet().nothrow();
+		if (result.exitCode !== 0) return { ok: false, path: binaryPath };
 		const output = result.text().trim();
 		// Output format: "omp/X.Y.Z"
 		const match = output.match(/\/(\d+\.\d+\.\d+)/);
 		const actual = match?.[1];
-		return { ok: actual === expectedVersion, actual, path: ompPath };
+		return { ok: actual === expectedVersion, actual, path: binaryPath };
 	} catch {
-		return { ok: false, path: ompPath };
+		return { ok: false, path: binaryPath };
 	}
 }
 
+/**
+ * Run the PATH-resolved omp binary and check if it reports the expected version.
+ */
+async function verifyInstalledVersion(expectedVersion: string): Promise<InstalledVersionVerification> {
+	const ompPath = resolveOmpPath();
+	if (!ompPath) return { ok: false };
+	return await verifyBinaryAtPath(ompPath, expectedVersion);
+}
+
 function printVerifiedVersion(expectedVersion: string): void {
 	console.log(chalk.green(`\n${theme.status.success} Updated to ${expectedVersion}`));
 }
@@ -1108,6 +1176,145 @@ export async function updateViaBinaryAt(
 	console.log(chalk.dim(`Restart ${APP_NAME} to use the new version`));
 }
 
+/**
+ * In-place forwarder bodies, by shim extension, for launchers that cannot be
+ * renamed aside during a script-shim takeover; each execs the sibling
+ * `omp.exe`. Rewriting matters for the shims that outrank `.exe` at command
+ * resolution: PowerShell prefers `.ps1` and Git Bash resolves the
+ * extensionless sh shim first, so leaving the old body behind would keep
+ * launching the replaced install.
+ */
+const SHIM_FORWARDERS: Record<string, string> = {
+	"": `#!/bin/sh\nexec "$(dirname "$0")/${APP_NAME}.exe" "$@"\n`,
+	".cmd": `@"%~dp0${APP_NAME}.exe" %*\r\n`,
+	".bat": `@"%~dp0${APP_NAME}.exe" %*\r\n`,
+	".ps1": `& "$PSScriptRoot\\${APP_NAME}.exe" @args\nexit $LASTEXITCODE\n`,
+};
+
+/**
+ * Take over a Windows script-launcher install for a binary-only release.
+ *
+ * npm-managed Windows installs are launched through script shims
+ * (`omp`/`omp.cmd`/`omp.ps1`) that cannot be overwritten with a native
+ * executable. The release binary is installed as `omp.exe` beside them and
+ * the shims are then renamed aside: cmd.exe would already prefer `.exe` via
+ * PATHEXT, but PowerShell resolves `.ps1` first, so the takeover only sticks
+ * once the shims are out of the way. A working launcher exists at every
+ * step — the exe lands before any shim moves, a shim that refuses to move
+ * (a running `.cmd` can be renamed but may be held open some other way) is
+ * rewritten in place as a forwarder to the exe, and a failed version
+ * verification moves everything back.
+ */
+export async function updateViaShimTakeover(
+	shimPath: string,
+	expectedVersion: string,
+	options: {
+		binaryName?: string;
+		fetchImpl?: Fetch;
+		githubToken?: string;
+		verifyBinary?: typeof verifyBinaryAtPath;
+	} = {},
+): Promise<void> {
+	const binaryName = options.binaryName ?? getBinaryName();
+	const launcherDir = path.dirname(shimPath);
+	const exePath = path.join(launcherDir, `${APP_NAME}.exe`);
+	const tempPath = `${exePath}.new`;
+	const asset = await getReleaseBinaryAsset(expectedVersion, binaryName, options.fetchImpl, options.githubToken);
+	console.log(chalk.dim(`Downloading ${binaryName}…`));
+	await downloadVerifiedBinary({
+		url: asset.url,
+		targetPath: tempPath,
+		expectedSize: asset.size,
+		expectedDigest: asset.digest,
+		fetchImpl: options.fetchImpl,
+	});
+	console.log(chalk.dim(`Verified ${asset.digest}`));
+
+	console.log(chalk.dim(`Installing ${APP_NAME}.exe beside the script launcher...`));
+	await fs.promises.rename(tempPath, exePath);
+	// Retire the shims so PATH resolution lands on the new exe. Renamed, not
+	// deleted: restorable on verification failure, and Windows permits
+	// renaming a batch file that is still executing. A shim that cannot be
+	// renamed (held open without delete sharing) is rewritten in place as a
+	// forwarder to the exe — write and rename take different Windows locks,
+	// so one can succeed where the other fails.
+	const backupSuffix = `${Date.now()}.${process.pid}.bak`;
+	const retired: Array<{ launcher: string; backup: string }> = [];
+	const forwarded: Array<{ launcher: string; original: string }> = [];
+	const stuck: string[] = [];
+	for (const ext of ["", ".cmd", ".ps1", ".bat"]) {
+		const launcher = path.join(launcherDir, `${APP_NAME}${ext}`);
+		const backup = `${launcher}.${backupSuffix}`;
+		try {
+			await fs.promises.rename(launcher, backup);
+			retired.push({ launcher, backup });
+		} catch (err) {
+			if (isEnoent(err)) continue;
+			try {
+				const original = await Bun.file(launcher).text();
+				await Bun.write(launcher, SHIM_FORWARDERS[ext]);
+				forwarded.push({ launcher, original });
+			} catch {
+				stuck.push(launcher);
+			}
+		}
+	}
+
+	// Verify the exe by its explicit path: $which cached the shim path when
+	// the update target was resolved, and the shim was just renamed away, so
+	// a PATH re-resolution here would test a file that no longer exists.
+	const verify = options.verifyBinary ?? verifyBinaryAtPath;
+	const verification = await verify(exePath, expectedVersion);
+	if (!verification.ok) {
+		for (const { launcher, backup } of retired) {
+			try {
+				await fs.promises.rename(backup, launcher);
+			} catch {}
+		}
+		for (const { launcher, original } of forwarded) {
+			try {
+				await Bun.write(launcher, original);
+			} catch {}
+		}
+		await unlinkIfExists(exePath);
+		throw new Error(
+			`${formatVerificationFailure(verification, expectedVersion)}; restored previous ${APP_NAME} launcher`,
+		);
+	}
+	for (const { backup } of retired) {
+		await removeBackupBestEffort(backup);
+	}
+	// Reclaim exe backups and retired-shim leftovers from earlier attempts.
+	for (const ext of [".exe", "", ".cmd", ".ps1", ".bat"]) {
+		await sweepStaleBackups(path.join(launcherDir, `${APP_NAME}${ext}`));
+	}
+	for (const { launcher } of forwarded) {
+		console.log(chalk.dim(`Converted ${launcher} to a forwarder (it could not be removed).`));
+	}
+	for (const launcher of stuck) {
+		console.log(
+			chalk.yellow(
+				`Could not retire ${launcher}; shells that prefer it may keep launching the old version until it is deleted manually.`,
+			),
+		);
+	}
+	printVerifiedVersion(expectedVersion);
+	console.log(chalk.dim(`Restart ${APP_NAME} to use the new version`));
+}
+
+/**
+ * Platform-appropriate installer one-liner for recovery instructions.
+ *
+ * Forces the installer's binary mode (`--binary` / `-Binary`): the default
+ * mode prefers a bun-based install whenever bun is present, which would send
+ * a user recovering from a binary-only release straight back through bun.
+ */
+function installerHint(): string {
+	return process.platform === "win32"
+		? "& ([scriptblock]::Create((irm https://omp.sh/install.ps1))) -Binary"
+		: "curl -fsSL https://omp.sh/install | sh -s -- --binary";
+}
+
 /**
  * Run the update command.
  */
@@ -1141,19 +1348,47 @@ export async function runUpdateCommand(opts: { force: boolean; check: boolean })
 		return;
 	}
 
-	// Choose update method based on the prioritized omp binary in PATH
+	// Choose update method based on the prioritized omp binary in PATH. For
+	// binary-only releases the package managers are never consulted: a bun/npm
+	// symlink resolves to method "binary" and is replaced in place, keeping the
+	// same PATH entry live.
 	try {
-		const target = await resolveUpdateTarget();
+		const forceBinary = shouldForceBinaryUpdate(release);
+		const target = await resolveUpdateTarget({ allowPackageManagers: !forceBinary });
 		if (target.method === "brew") {
 			await updateViaHomebrew(release.version, opts.force);
 		} else if (target.method === "mise") {
 			await updateViaMise(release.version, opts.force);
-		} else if (target.method === "bun") {
-			await updateViaBun(release.version);
-		} else if (target.method === "npm") {
-			await updateViaNpm(release.version);
+		} else if (target.method === "bun" || target.method === "npm") {
+			if (forceBinary) {
+				// Reachable in forced mode only through a Windows script
+				// launcher resolved from PATH (the bun/npm bin-dir probes are
+				// skipped), so the launcher path is always known.
+				if (!target.path) throw new Error(`Could not resolve ${APP_NAME} launcher path in PATH`);
+				console.log(chalk.dim("This release ships as a standalone binary; replacing the script launcher."));
+				await updateViaShimTakeover(target.path, release.version);
+				console.log(
+					chalk.yellow(
+						`This install is no longer managed by ${target.method}. Removing the old global package may delete this launcher; if it does, reinstall with: ${installerHint()}`,
+					),
+				);
+			} else if (target.method === "bun") {
+				await updateViaBun(release.version);
+			} else {
+				await updateViaNpm(release.version);
+			}
 		} else {
+			if (forceBinary && target.replacesSymlink) {
+				console.log(chalk.dim("Replacing the package-manager launcher with the standalone binary."));
+			}
 			await updateViaBinaryAt(target.path, release.version);
+			if (forceBinary && target.replacesSymlink) {
+				console.log(
+					chalk.yellow(
+						`This install is no longer managed by bun/npm. Removing the old global package may delete this launcher; if it does, reinstall with: ${installerHint()}`,
+					),
+				);
+			}
 		}
 	} catch (err) {
 		console.error(chalk.red(`Update failed: ${err}`));

package/src/config/keybindings.ts

@@ -654,12 +654,52 @@ export class KeybindingsManager extends TuiKeybindingsManager {
 
 /**
  * Key hint formatting utilities for UI labels.
+ *
+ * Modifier labels are platform-aware: macOS names the physical keys `Option`
+ * (`alt`) and `Cmd` (`super`), so rendering `Alt`/`Super` there would name keys
+ * absent from a Mac keyboard. Every other platform keeps `Alt`/`Super`.
  */
-const MODIFIER_LABELS: Record<string, string> = {
-	ctrl: "Ctrl",
-	shift: "Shift",
-	alt: "Alt",
-};
+
+/**
+ * Platform override for key-hint rendering; `undefined` resolves to the host
+ * `process.platform`. Mirrors `setKittyProtocolActive` in the TUI keys module:
+ * a single seam that keeps hint output deterministic in tests without mutating
+ * the global `process.platform`.
+ */
+let keyHintPlatformOverride: NodeJS.Platform | undefined;
+
+/** Pin the platform used to render modifier labels (test seam). */
+export function setKeyHintPlatform(platform: NodeJS.Platform | undefined): void {
+	keyHintPlatformOverride = platform;
+}
+
+/** Platform currently used for key-hint rendering. */
+export function keyHintPlatform(): NodeJS.Platform {
+	return keyHintPlatformOverride ?? process.platform;
+}
+
+type Modifier = "ctrl" | "shift" | "alt" | "super";
+
+function isModifier(part: string): part is Modifier {
+	return part === "ctrl" || part === "shift" || part === "alt" || part === "super";
+}
+
+/**
+ * Human label for a modifier, using each platform's own key names. `ctrl` and
+ * `shift` are the same everywhere; `alt`/`super` become `Option`/`Cmd` on macOS.
+ */
+export function modifierLabel(mod: Modifier, platform: NodeJS.Platform = keyHintPlatform()): string {
+	switch (mod) {
+		case "ctrl":
+			return "Ctrl";
+		case "shift":
+			return "Shift";
+		case "alt":
+			return platform === "darwin" ? "Option" : "Alt";
+		case "super":
+			return platform === "darwin" ? "Cmd" : "Super";
+	}
+}
 
 const KEY_LABELS: Record<string, string> = {
 	esc: "Esc",
@@ -680,10 +720,9 @@ const KEY_LABELS: Record<string, string> = {
 	right: "Right",
 };
 
-function formatKeyPart(part: string): string {
+function formatKeyPart(part: string, platform: NodeJS.Platform): string {
 	const lower = part.toLowerCase();
-	const modifier = MODIFIER_LABELS[lower];
-	if (modifier) return modifier;
+	if (isModifier(lower)) return modifierLabel(lower, platform);
 	const label = KEY_LABELS[lower];
 	if (label) return label;
 	if (part.length === 1) return part.toUpperCase();
@@ -691,7 +730,11 @@ function formatKeyPart(part: string): string {
 }
 
 export function formatKeyHint(key: KeyId): string {
-	return key.split("+").map(formatKeyPart).join("+");
+	const platform = keyHintPlatform();
+	return key
+		.split("+")
+		.map(part => formatKeyPart(part, platform))
+		.join("+");
 }
 
 export function formatKeyHints(keys: KeyId | KeyId[]): string {

package/src/config/model-resolver.ts

@@ -1138,14 +1138,30 @@ function resolveEffectiveAgentModelSelection(
 	return { patterns: resolveConfiguredModelPatterns(fallback, settings) };
 }
 
-/** Return the raw selector source that supplies the effective agent patterns. */
-export function resolveAgentModelSource(options: AgentModelPatternResolutionOptions): string | string[] | undefined {
-	return resolveEffectiveAgentModelSelection(options).source;
+/** Effective agent model patterns paired with the pre-expansion role alias behind them. */
+export interface AgentModelSelection {
+	/** Expanded model patterns to spawn with. */
+	patterns: string[];
+	/** Role alias the patterns came from (`@task` -> `task`), when the source named one. */
+	role: string | undefined;
+}
+
+/**
+ * Resolve an agent's model patterns together with the role identity they were
+ * expanded from. Spawn paths MUST take both from this single call: the child's
+ * inherited retry-fallback chain is keyed off the role, which the expansion
+ * discards, and deriving the two halves separately is how they drift apart.
+ */
+export function resolveAgentModelSelection(options: AgentModelPatternResolutionOptions): AgentModelSelection {
+	const { source, patterns } = resolveEffectiveAgentModelSelection(options);
+	return { patterns, role: resolveExplicitModelRole(source, options.settings) };
 }
 
+/** Effective agent model patterns alone, for callers with no interest in role identity. */
 export function resolveAgentModelPatterns(options: AgentModelPatternResolutionOptions): string[] {
 	return resolveEffectiveAgentModelSelection(options).patterns;
 }
+
 /** Default prewalk hand-off target when no explicit target is configured. */
 export const DEFAULT_PREWALK_TARGET = "@smol";
 

package/src/config/settings-schema.ts

@@ -5471,6 +5471,11 @@ export const SETTINGS_SCHEMA = {
 		default: undefined,
 	},
 
+	"searxng.safesearch": {
+		type: "number",
+		default: undefined,
+	},
+
 	"commit.mapReduceEnabled": { type: "boolean", default: true },
 
 	"commit.mapReduceMinFiles": { type: "number", default: 4 },

package/src/cursor.ts

@@ -18,6 +18,7 @@ import type {
 	ToolResultMessage,
 } from "@oh-my-pi/pi-ai";
 import {
+	omitUndefinedArgs,
 	piEscapeRegexLiteral,
 	piGrepSkip,
 	piJoinPath,
@@ -239,7 +240,11 @@ async function executeTool(
 		return createToolResultMessage(toolCallId, toolName, result, true);
 	}
 
-	options.emitEvent?.({ type: "tool_execution_start", toolCallId, toolName, args });
+	// Same rule as synthesizeCursorExecToolCall: optional kwargs must be absent,
+	// not `undefined`, or ArkType validation rejects the call.
+	const toolArgs = omitUndefinedArgs(args);
+
+	options.emitEvent?.({ type: "tool_execution_start", toolCallId, toolName, args: toolArgs });
 
 	let result: AgentToolResult<unknown>;
 	let isError = false;
@@ -254,7 +259,7 @@ async function executeTool(
 					type: "tool_execution_update",
 					toolCallId,
 					toolName,
-					args,
+					args: toolArgs,
 					partialResult: sanitizedResult,
 				});
 			}
@@ -263,7 +268,7 @@ async function executeTool(
 	try {
 		result = await tool.execute(
 			toolCallId,
-			args as Record<string, unknown>,
+			toolArgs as Record<string, unknown>,
 			undefined,
 			onUpdate,
 			options.getToolContext?.(),
@@ -509,11 +514,11 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 		}
 
 		const timeoutSeconds = args.timeout && args.timeout > 0 ? args.timeout : undefined;
-		const toolArgs: Record<string, unknown> = {
+		const toolArgs = omitUndefinedArgs({
 			command: args.command,
 			cwd: args.workingDirectory || undefined,
 			timeout: timeoutSeconds,
-		};
+		});
 
 		this.options.emitEvent?.({ type: "tool_execution_start", toolCallId, toolName, args: toolArgs });
 

package/src/discovery/agents-md.ts

@@ -15,43 +15,81 @@ import { calculateDepth, createSourceMeta } from "./helpers";
 const PROVIDER_ID = "agents-md";
 const DISPLAY_NAME = "AGENTS.md";
 
+/**
+ * Compare paths while tolerating Windows drive casing.
+ */
+function samePath(left: string, right: string): boolean {
+	const normalizedLeft = path.resolve(left);
+	const normalizedRight = path.resolve(right);
+	return process.platform === "win32"
+		? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+		: normalizedLeft === normalizedRight;
+}
+
+/**
+ * Return whether `child` is at or below `parent`.
+ */
+function isWithin(parent: string, child: string): boolean {
+	const normalizedParent = path.resolve(parent);
+	const normalizedChild = path.resolve(child);
+	const relative = path.relative(
+		process.platform === "win32" ? normalizedParent.toLowerCase() : normalizedParent,
+		process.platform === "win32" ? normalizedChild.toLowerCase() : normalizedChild,
+	);
+	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
 /**
  * Load standalone AGENTS.md files.
+ *
+ * When a repository is nested below the user's home directory, continue past
+ * the Git root to discover workspace-level AGENTS.md files, but stop before
+ * loading the home directory's own AGENTS.md as project context.
  */
-async function loadAgentsMd(ctx: LoadContext): Promise<LoadResult<ContextFile>> {
+export async function loadAgentsMd(ctx: LoadContext): Promise<LoadResult<ContextFile>> {
 	const items: ContextFile[] = [];
 	const warnings: string[] = [];
+	const home = path.resolve(ctx.home);
+	const cwd = path.resolve(ctx.cwd);
+	const repoRoot = ctx.repoRoot ? path.resolve(ctx.repoRoot) : null;
+	const filesystemRoot = path.parse(cwd).root;
+	const cwdIsUnderHome = isWithin(home, cwd);
+	const repoIsUnderHome = repoRoot !== null && isWithin(home, repoRoot);
+	const scanToHome = repoRoot !== null && cwdIsUnderHome && repoIsUnderHome;
+	const boundary = scanToHome ? home : (repoRoot ?? (cwdIsUnderHome ? home : filesystemRoot));
+	const includeBoundary = repoRoot === null ? cwdIsUnderHome : !samePath(boundary, home);
+	const excludeHome = scanToHome;
 
-	// Walk up from cwd looking for AGENTS.md files
-	let current = ctx.cwd;
-
+	let current = cwd;
 	while (true) {
-		const candidate = path.join(current, "AGENTS.md");
-		const content = await readFile(candidate);
+		const atBoundary = samePath(current, boundary);
+		const atHome = excludeHome && samePath(current, home);
+		if (!(atHome || (atBoundary && !includeBoundary))) {
+			const candidate = path.join(current, "AGENTS.md");
+			const content = await readFile(candidate);
 
-		if (content !== null) {
-			const parent = path.dirname(candidate);
-			const baseName = parent.split(path.sep).pop() ?? "";
+			if (content !== null) {
+				const parent = path.dirname(candidate);
+				const baseName = parent.split(path.sep).pop() ?? "";
 
-			if (!baseName.startsWith(".")) {
-				const fileDir = path.dirname(candidate);
-				const calculatedDepth = calculateDepth(ctx.cwd, fileDir, path.sep);
+				if (!baseName.startsWith(".")) {
+					const fileDir = path.dirname(candidate);
+					const calculatedDepth = calculateDepth(cwd, fileDir, path.sep);
 
-				items.push({
-					path: candidate,
-					content,
-					level: "project",
-					depth: calculatedDepth,
-					_source: createSourceMeta(PROVIDER_ID, candidate, "project"),
-				});
+					items.push({
+						path: candidate,
+						content,
+						level: "project",
+						depth: calculatedDepth,
+						_source: createSourceMeta(PROVIDER_ID, candidate, "project"),
+					});
+				}
 			}
 		}
+		if (atBoundary) break;
 
-		if (current === (ctx.repoRoot ?? ctx.home)) break; // scanned repo root or home, stop
-
-		// Move to parent directory
 		const parent = path.dirname(current);
-		if (parent === current) break; // Reached filesystem root
+		if (parent === current) break;
 		current = parent;
 	}