oh-my-opencode 4.5.12 → 4.7.0

package/packages/omo-codex/scripts/install-local.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { mkdir, writeFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -12,6 +13,10 @@ import {
 } from "./install/cache.mjs";
 import { linkCachedPluginAgents } from "./install/agents.mjs";
 import { updateCodexConfig } from "./install/config.mjs";
+import {
+	emptyProjectLocalCodexCleanupResult,
+	repairNearestProjectLocalCodexArtifacts,
+} from "./install/project-local-cleanup.mjs";
 import { trustedHookStatesForPlugin } from "./install/hook-trust.mjs";
 import { defaultRunCommand } from "./install/process.mjs";
 import { writeInstalledMarketplaceSnapshot } from "./install/snapshot.mjs";
@@ -21,6 +26,10 @@ import {
 	resolvePluginSource,
 	validatePathSegment,
 } from "./install/marketplace.mjs";
+import { prepareGitBashForInstall, resolveGitBashForCurrentProcess } from "./install/git-bash.mjs";
+import { formatLazyCodexInstallHelp, parseLazyCodexInstallCliArgs } from "./install/cli-args.mjs";
+import { runDelegatedOmoCommand } from "./install/delegated-command.mjs";
+import { shouldBuildSourcePackages } from "./install/source-package-build.mjs";
 
 const LEGACY_CODEX_PLUGIN_MARKETPLACE = ["code", "yeongyu", "codex", "plugins"].join("-");
 const SISYPHUS_LEGACY_CACHE_MARKETPLACES = ["lazycodex", LEGACY_CODEX_PLUGIN_MARKETPLACE];
@@ -41,10 +50,24 @@ export async function installMarketplaceLocally(options = {}) {
 	const env = options.env ?? process.env;
 	const homeDir = resolve(options.homeDir ?? homedir());
 	const codexHome = resolve(options.codexHome ?? nonEmptyEnvValue(env, "CODEX_HOME") ?? join(homeDir, ".codex"));
+	const projectDirectory = resolve(options.projectDirectory ?? nonEmptyEnvValue(env, "OMO_CODEX_PROJECT") ?? process.cwd());
 	const binDir = resolve(options.binDir ?? resolveCodexInstallerBinDir({ codexHome, env, homeDir }));
 	const platform = options.platform ?? process.platform;
 	const runCommand = options.runCommand ?? defaultRunCommand;
 	const log = options.log ?? console.log;
+	const buildSource = await shouldBuildSourcePackages(repoRoot);
+	const gitBashResolution = await prepareGitBashForInstall({
+		platform,
+		env,
+		cwd: repoRoot,
+		runCommand,
+		resolveGitBash: platform === "win32"
+			? (options.gitBashResolver ?? (() => resolveGitBashForCurrentProcess({ platform, env })))
+			: undefined,
+	});
+	if (!gitBashResolution.found) {
+		throw new Error(gitBashResolution.installHint);
+	}
 	const codexPackageRoot = join(repoRoot, "packages", "omo-codex");
 	const marketplace = await readMarketplace(repoRoot, {
 		marketplacePath: join(codexPackageRoot, "marketplace.json"),
@@ -66,6 +89,7 @@ export async function installMarketplaceLocally(options = {}) {
 
 		log(`Building ${entry.name}@${version}`);
 		const plugin = await installCachedPlugin({
+			buildSource,
 			codexHome,
 			marketplaceName: marketplace.name,
 			name: entry.name,
@@ -120,15 +144,38 @@ export async function installMarketplaceLocally(options = {}) {
 		marketplaceName: marketplace.name,
 		marketplaceSource: { sourceType: "local", source: marketplaceRoot },
 		pluginNames,
+		platform,
 		trustedHookStates,
 		agentConfigs: [...agentConfigs.values()].sort((left, right) => left.name.localeCompare(right.name)),
+		autonomousPermissions: options.autonomousPermissions !== false,
 	});
+	const projectCleanup = await repairProjectLocalCodexArtifactsBestEffort({ startDirectory: projectDirectory, codexHome, log });
+	for (const configCleanup of projectCleanup.configs) {
+		if (!configCleanup.changed) continue;
+		log(`Repaired project Codex config ${configCleanup.configPath} (backup: ${configCleanup.backupPath})`);
+	}
+	for (const artifact of projectCleanup.artifacts) {
+		log(`Found project-local legacy artifact ${artifact.path}; left in place`);
+	}
 
 	for (const plugin of installed) {
 		log(`Installed ${plugin.name}@${marketplace.name} -> ${plugin.path}`);
 	}
 
-	return { marketplaceName: marketplace.name, installed };
+	return { marketplaceName: marketplace.name, installed, gitBashPath: gitBashResolution.path, projectCleanup };
+}
+
+async function repairProjectLocalCodexArtifactsBestEffort({ startDirectory, codexHome, log }) {
+	try {
+		return await repairNearestProjectLocalCodexArtifacts({ startDirectory, codexHome });
+	} catch (error) {
+		log(`Skipped project-local Codex cleanup: ${formatUnknownError(error)}`);
+		return emptyProjectLocalCodexCleanupResult();
+	}
+}
+
+function formatUnknownError(error) {
+	return error instanceof Error ? error.message : String(error);
 }
 
 function agentNameFromToml(fileName) {
@@ -170,21 +217,57 @@ function nonEmptyEnvValue(env, key) {
 	const value = env[key];
 	if (typeof value !== "string") return undefined;
 	const trimmed = value.trim();
-	return trimmed.length === 0 ? undefined : value;
+	return trimmed.length === 0 ? undefined : trimmed;
 }
 
 function legacyCacheMarketplaces(marketplaceName) {
 	return marketplaceName === "sisyphuslabs" ? SISYPHUS_LEGACY_CACHE_MARKETPLACES : [];
 }
 
+export function resolveDefaultRepoRoot() {
+	return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+}
+
 async function main() {
-	const repoRoot = process.argv[2] ? resolve(process.argv[2]) : process.cwd();
-	const result = await installMarketplaceLocally({ repoRoot });
+	const parsed = parseLazyCodexInstallCliArgs(process.argv.slice(2));
+	if (parsed.kind === "help") {
+		console.log(formatLazyCodexInstallHelp());
+		return;
+	}
+	if (parsed.kind === "version") {
+		const packageJson = JSON.parse(await readFile(join(resolveDefaultRepoRoot(), "package.json"), "utf8"));
+		const version = typeof packageJson.version === "string" ? packageJson.version : "unknown";
+		console.log(`lazycodex-ai ${version}`);
+		return;
+	}
+	if (parsed.kind === "command") {
+		await runDelegatedOmoCommand(parsed, { cwd: process.cwd(), log: console.log, runCommand: defaultRunCommand });
+		return;
+	}
+
+	const repoRoot = parsed.repoRoot ? resolve(parsed.repoRoot) : resolveDefaultRepoRoot();
+	const result = await installMarketplaceLocally({
+		repoRoot,
+		autonomousPermissions: parsed.autonomousPermissions,
+	});
 	console.log(`Installed ${result.installed.length} plugin(s) from ${result.marketplaceName}.`);
 }
 
-const invokedPath = process.argv[1] ? resolve(process.argv[1]) : "";
-if (invokedPath === fileURLToPath(import.meta.url)) {
+function resolveEntrypointPath(path) {
+	try {
+		return realpathSync(resolve(path));
+	} catch (error) {
+		if (error instanceof Error) return resolve(path);
+		throw error;
+	}
+}
+
+function isEntrypointInvocation(invokedPath) {
+	if (!invokedPath) return false;
+	return resolveEntrypointPath(invokedPath) === resolveEntrypointPath(fileURLToPath(import.meta.url));
+}
+
+if (isEntrypointInvocation(process.argv[1] ?? "")) {
 	main().catch((error) => {
 		console.error(error instanceof Error ? error.message : error);
 		process.exitCode = 1;

package/packages/omo-codex/scripts/install-local.test.mjs

@@ -67,6 +67,21 @@ test("#given explicit CODEX_LOCAL_BIN_DIR #when resolving local installer bin di
 	);
 });
 
+test("#given CODEX_LOCAL_BIN_DIR with surrounding whitespace #when resolving local installer bin dir #then trims the env value before use", () => {
+	const homeDir = join(tmpdir(), "omo-codex-home-trim");
+	const codexHome = join(tmpdir(), "omo-codex-install-trim");
+	const explicitBinDir = join(tmpdir(), "omo-codex-trim-bin");
+
+	assert.equal(
+		resolveCodexInstallerBinDir({
+			codexHome,
+			env: { CODEX_LOCAL_BIN_DIR: `  ${explicitBinDir}  ` },
+			homeDir,
+		}),
+		explicitBinDir,
+	);
+});
+
 test("#given omo plugin source #when inspecting identity #then uses sisyphuslabs omo metadata", async () => {
 	const pluginRoot = join(scriptDir, "..", "plugin");
 

package/packages/omo-codex/scripts/install-mcp-runtime.test.mjs

@@ -12,6 +12,7 @@ test("#given external MCP package runtime #when installing cached plugin #then r
 	const codexHome = await makeTempDir();
 	const sourceRoot = join(repoRoot, "packages", "omo-codex", "plugin");
 	const astGrepPackageRoot = join(repoRoot, "packages", "ast-grep-mcp");
+	const gitBashPackageRoot = join(repoRoot, "packages", "git-bash-mcp");
 	const lspPackageRoot = join(repoRoot, "packages", "lsp-tools-mcp");
 
 	await writeJson(join(astGrepPackageRoot, "package.json"), {
@@ -26,6 +27,12 @@ test("#given external MCP package runtime #when installing cached plugin #then r
 		type: "module",
 		bin: { "omo-lsp": "./dist/cli.js" },
 	});
+	await writeJson(join(gitBashPackageRoot, "package.json"), {
+		name: "@example/git-bash-mcp",
+		version: "0.1.0",
+		type: "module",
+		bin: { "omo-git-bash": "./dist/cli.js" },
+	});
 	await writeJson(join(sourceRoot, "package.json"), {
 		name: "@example/omo",
 		version: "0.1.0",
@@ -37,6 +44,11 @@ test("#given external MCP package runtime #when installing cached plugin #then r
 				args: ["../../ast-grep-mcp/dist/cli.js", "mcp"],
 				cwd: ".",
 			},
+			git_bash: {
+				command: "node",
+				args: ["../../git-bash-mcp/dist/cli.js", "mcp"],
+				cwd: ".",
+			},
 			lsp: {
 				command: "node",
 				args: ["../../lsp-tools-mcp/dist/cli.js", "mcp"],
@@ -45,6 +57,7 @@ test("#given external MCP package runtime #when installing cached plugin #then r
 		},
 	});
 	await writeJson(join(astGrepPackageRoot, "dist", "cli.js"), { executable: true });
+	await writeJson(join(gitBashPackageRoot, "dist", "cli.js"), { executable: true });
 	await writeJson(join(lspPackageRoot, "dist", "cli.js"), { executable: true });
 	await writeJson(join(lspPackageRoot, "dist", "lsp", "manager.js"), { copied: true });
 
@@ -59,13 +72,17 @@ test("#given external MCP package runtime #when installing cached plugin #then r
 
 	const cachedMcp = JSON.parse(await readFile(join(result.path, ".mcp.json"), "utf8"));
 	const copiedAstGrepCli = join(result.path, "mcp", "ast_grep", "dist", "cli.js");
+	const copiedGitBashCli = join(result.path, "mcp", "git_bash", "dist", "cli.js");
 	const copiedCli = join(result.path, "mcp", "lsp", "dist", "cli.js");
 
 	assert.deepEqual(cachedMcp.mcpServers.ast_grep.args, [copiedAstGrepCli, "mcp"]);
+	assert.deepEqual(cachedMcp.mcpServers.git_bash.args, [copiedGitBashCli, "mcp"]);
 	assert.deepEqual(cachedMcp.mcpServers.lsp.args, [copiedCli, "mcp"]);
 	assert.equal(Object.hasOwn(cachedMcp.mcpServers.ast_grep, "cwd"), false);
+	assert.equal(Object.hasOwn(cachedMcp.mcpServers.git_bash, "cwd"), false);
 	assert.equal(Object.hasOwn(cachedMcp.mcpServers.lsp, "cwd"), false);
 	assert.equal((await stat(copiedAstGrepCli)).isFile(), true);
+	assert.equal((await stat(copiedGitBashCli)).isFile(), true);
 	assert.equal((await stat(copiedCli)).isFile(), true);
 	assert.equal((await stat(join(result.path, "mcp", "lsp", "dist", "lsp", "manager.js"))).isFile(), true);
 });
@@ -171,3 +188,46 @@ test("#given structurally valid external MCP package without mcp suffix #when in
 	assert.deepEqual(cachedMcp.mcpServers.language_tools.args, [copiedCli, "mcp", join(sourceRoot, "..", "local-config.json")]);
 	assert.equal((await stat(copiedCli)).isFile(), true);
 });
+
+test("#given packaged external MCP runtime has only dist files #when installing cached plugin #then runtime is copied into the plugin cache", async () => {
+	// given
+	const repoRoot = await makeTempDir();
+	const codexHome = await makeTempDir();
+	const sourceRoot = join(repoRoot, "packages", "omo-codex", "plugin");
+	const lspPackageRoot = join(repoRoot, "packages", "lsp-tools-mcp");
+
+	await writeJson(join(sourceRoot, "package.json"), {
+		name: "@example/omo",
+		version: "0.1.0",
+	});
+	await writeJson(join(sourceRoot, ".mcp.json"), {
+		mcpServers: {
+			lsp: {
+				command: "node",
+				args: ["../../lsp-tools-mcp/dist/cli.js", "mcp"],
+				cwd: ".",
+			},
+		},
+	});
+	await writeJson(join(lspPackageRoot, "dist", "cli.js"), { executable: true });
+	await writeJson(join(lspPackageRoot, "dist", "lsp", "manager.js"), { copied: true });
+
+	// when
+	const result = await installCachedPlugin({
+		codexHome,
+		marketplaceName: "sisyphuslabs",
+		name: "omo",
+		runCommand: async () => {},
+		sourcePath: sourceRoot,
+		version: "0.1.0",
+	});
+
+	// then
+	const cachedMcp = JSON.parse(await readFile(join(result.path, ".mcp.json"), "utf8"));
+	const copiedCli = join(result.path, "mcp", "lsp", "dist", "cli.js");
+	assert.deepEqual(cachedMcp.mcpServers.lsp.args, [copiedCli, "mcp"]);
+	assert.equal(Object.hasOwn(cachedMcp.mcpServers.lsp, "cwd"), false);
+	assert.equal((await stat(copiedCli)).isFile(), true);
+	assert.equal((await stat(join(result.path, "mcp", "lsp", "dist", "lsp", "manager.js"))).isFile(), true);
+	assert.notEqual(cachedMcp.mcpServers.lsp.args[0], join(lspPackageRoot, "dist", "cli.js"));
+});

package/packages/omo-codex/scripts/install-packaged-local.test.mjs

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+
+import { installMarketplaceLocally } from "./install-local.mjs";
+import { makeTempDir, writeJson, writePluginAt } from "./install-test-fixtures.mjs";
+
+test("#given packaged lazycodex adapter #when installing locally #then uses bundled artifacts without source builds", async () => {
+	// given
+	const repoRoot = await makeTempDir();
+	const codexHome = await makeTempDir();
+	const binDir = await makeTempDir();
+	const codexPackageRoot = join(repoRoot, "packages", "omo-codex");
+	const pluginRoot = join(codexPackageRoot, "plugin");
+	const lspRuntimeRoot = join(repoRoot, "packages", "lsp-tools-mcp");
+
+	await writeJson(join(repoRoot, "package.json"), {
+		name: "lazycodex-ai",
+		version: "0.1.2",
+	});
+	await writeJson(join(codexPackageRoot, "marketplace.json"), {
+		name: "sisyphuslabs",
+		plugins: [{ name: "omo", source: "./plugins/omo" }],
+	});
+	await writePluginAt(pluginRoot, "omo", "0.1.0");
+	await writeJson(join(pluginRoot, ".mcp.json"), {
+		mcpServers: {
+			lsp: {
+				command: "node",
+				args: ["../../lsp-tools-mcp/dist/cli.js", "mcp"],
+				cwd: ".",
+			},
+		},
+	});
+	await mkdir(join(pluginRoot, "dist"), { recursive: true });
+	await writeFile(join(pluginRoot, "dist", "cli.js"), "#!/usr/bin/env node\nconsole.log('prebuilt')\n");
+	await writeJson(join(lspRuntimeRoot, "dist", "cli.js"), { executable: true });
+
+	const commands = [];
+
+	// when
+	const result = await installMarketplaceLocally({
+		repoRoot,
+		codexHome,
+		binDir,
+		platform: "linux",
+		runCommand: async (command, args, options) => {
+			commands.push([command, args.join(" "), options.cwd]);
+		},
+		log: () => {},
+	});
+
+	// then
+	const pluginCacheRoot = join(codexHome, "plugins", "cache", "sisyphuslabs", "omo", "0.1.0");
+	const cachedMcp = JSON.parse(await readFile(join(pluginCacheRoot, ".mcp.json"), "utf8"));
+	const cachedLspCli = join(pluginCacheRoot, "mcp", "lsp", "dist", "cli.js");
+
+	assert.deepEqual(result.installed.map((plugin) => `${plugin.name}@${plugin.version}`), ["omo@0.1.0"]);
+	assert.deepEqual(
+		commands.map(([command, args, cwd]) => [command, args, cwd]),
+		[["npm", "install --omit=dev", pluginCacheRoot]],
+	);
+	assert.deepEqual(cachedMcp.mcpServers.lsp.args, [cachedLspCli, "mcp"]);
+	assert.equal((await stat(cachedLspCli)).isFile(), true);
+	assert.notEqual(cachedMcp.mcpServers.lsp.args[0], join(lspRuntimeRoot, "dist", "cli.js"));
+});

package/packages/omo-codex/scripts/install-project-local-cleanup.test.mjs

@@ -0,0 +1,277 @@
+import assert from "node:assert/strict";
+import { lstat, mkdir, readFile, symlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+
+import { installMarketplaceLocally } from "./install-local.mjs";
+import { repairNearestProjectLocalCodexArtifacts } from "./install/project-local-cleanup.mjs";
+import { makeTempDir, writeJson, writePluginAt } from "./install-test-fixtures.mjs";
+
+test("#given stale project-local Codex config #when Node installer runs #then repairs the local conflict", async () => {
+	const repoRoot = await makeTempDir();
+	const codexHome = await makeTempDir();
+	const binDir = await makeTempDir();
+	const projectRoot = await makeTempDir();
+	const projectDirectory = join(projectRoot, "nested");
+	const codexPackageRoot = join(repoRoot, "packages", "omo-codex");
+	const pluginRoot = join(codexPackageRoot, "plugin");
+	const projectConfigPath = join(projectRoot, ".codex", "config.toml");
+
+	await mkdir(projectDirectory, { recursive: true });
+	await mkdir(join(projectRoot, ".git"), { recursive: true });
+	await mkdir(join(projectRoot, ".codex"), { recursive: true });
+	await writeJson(join(codexPackageRoot, "marketplace.json"), {
+		name: "debug-marketplace",
+		plugins: [{ name: "alpha", source: "./plugin" }],
+	});
+	await writePluginAt(pluginRoot, "alpha", "1.2.3");
+	await writeFile(
+		projectConfigPath,
+		[
+			"[features.multi_agent_v2]",
+			"enabled = true",
+			"",
+			"[agents]",
+			"  max_threads = 10",
+			"max_depth = 4",
+			"",
+		].join("\n"),
+	);
+
+	const result = await installMarketplaceLocally({
+		repoRoot,
+		codexHome,
+		binDir,
+		projectDirectory,
+		platform: "linux",
+		runCommand: async (command, args, options) => {
+			if (command === "npm" && args.join(" ") === "run build") {
+				await mkdir(join(options.cwd, "dist"), { recursive: true });
+				await writeFile(join(options.cwd, "dist", "cli.js"), "#!/usr/bin/env node\n");
+			}
+		},
+		log: () => {},
+	});
+
+	assert.equal(result.projectCleanup.configPath, projectConfigPath);
+	assert.equal(result.projectCleanup.changed, true);
+	assert.deepEqual(result.projectCleanup.removedKeys, ["max_threads"]);
+	assert.equal(result.projectCleanup.configs.length, 1);
+	assert.match(await readFile(result.projectCleanup.backupPath, "utf8"), /max_threads = 10/);
+	const content = await readFile(projectConfigPath, "utf8");
+	assert.doesNotMatch(content, /^\s*max_threads\s*=/m);
+	assert.match(content, /max_depth = 4/);
+});
+
+test("#given root and nested project-local Codex configs #when script cleanup runs #then it repairs every loaded project layer", async () => {
+	const projectRoot = await makeTempDir();
+	const projectDirectory = join(projectRoot, "nested");
+	const rootConfigPath = join(projectRoot, ".codex", "config.toml");
+	const nestedConfigPath = join(projectDirectory, ".codex", "config.toml");
+
+	await mkdir(join(projectRoot, ".git"), { recursive: true });
+	await mkdir(join(projectRoot, ".codex"), { recursive: true });
+	await mkdir(join(projectDirectory, ".codex"), { recursive: true });
+	await mkdir(join(projectDirectory, ".omx"), { recursive: true });
+	await writeFile(join(projectDirectory, ".codex", "hooks.json"), "{}\n");
+	await writeFile(
+		rootConfigPath,
+		[
+			"[features.multi_agent_v2]",
+			"enabled = true",
+			"",
+			"[agents]",
+			"max_threads = 10",
+			"max_depth = 4",
+			"",
+		].join("\n"),
+	);
+	await writeFile(
+		nestedConfigPath,
+		[
+			"[features.multi_agent_v2]",
+			"enabled = true",
+			"",
+			"[agents]",
+			"job_max_runtime_seconds = 7200",
+			"",
+		].join("\n"),
+	);
+
+	const result = await repairNearestProjectLocalCodexArtifacts({
+		startDirectory: projectDirectory,
+		now: () => new Date("2026-06-01T01:02:03.004Z"),
+	});
+
+	assert.equal(result.projectRoot, projectRoot);
+	assert.equal(result.changed, true);
+	assert.equal(result.configPath, rootConfigPath);
+	assert.deepEqual(
+		result.configs.map((config) => config.configPath),
+		[rootConfigPath, nestedConfigPath],
+	);
+	assert.deepEqual(
+		result.configs.map((config) => config.changed),
+		[true, false],
+	);
+	assert.equal(result.backupPath, `${rootConfigPath}.backup-2026-06-01T01-02-03-004Z`);
+	const rootContent = await readFile(rootConfigPath, "utf8");
+	const nestedContent = await readFile(nestedConfigPath, "utf8");
+	assert.doesNotMatch(rootContent, /^max_threads\s*=/m);
+	assert.match(rootContent, /max_depth = 4/);
+	assert.match(nestedContent, /job_max_runtime_seconds = 7200/);
+	assert.deepEqual(
+		result.artifacts.map((artifact) => artifact.path).sort(),
+		[join(projectDirectory, ".codex", "hooks.json"), join(projectDirectory, ".omx")],
+	);
+});
+
+test("#given no project-local config and CODEX_HOME in the parent chain #when script cleanup runs #then global Codex config is not treated as project state", async () => {
+	const homeRoot = await makeTempDir();
+	const codexHome = join(homeRoot, ".codex");
+	const projectDirectory = join(homeRoot, "workspace", "nested");
+	const globalConfigPath = join(codexHome, "config.toml");
+
+	await mkdir(projectDirectory, { recursive: true });
+	await mkdir(codexHome, { recursive: true });
+	await writeFile(
+		globalConfigPath,
+		[
+			"[features.multi_agent_v2]",
+			"enabled = true",
+			"",
+			"[agents]",
+			"max_threads = 10",
+			"max_depth = 4",
+			"",
+		].join("\n"),
+	);
+
+	const result = await repairNearestProjectLocalCodexArtifacts({ startDirectory: projectDirectory, codexHome });
+
+	assert.equal(result.configPath, null);
+	assert.equal(result.changed, false);
+	const content = await readFile(globalConfigPath, "utf8");
+	assert.match(content, /max_threads = 10/);
+	assert.match(content, /max_depth = 4/);
+});
+
+test("#given project-local config is a symlink to CODEX_HOME #when script cleanup runs #then it skips the link without mutating the target", async () => {
+	if (process.platform === "win32") return;
+
+	const codexHome = await makeTempDir();
+	const projectRoot = await makeTempDir();
+	const globalConfigPath = join(codexHome, "config.toml");
+	const projectConfigPath = join(projectRoot, ".codex", "config.toml");
+
+	await mkdir(join(projectRoot, ".git"), { recursive: true });
+	await mkdir(join(projectRoot, ".codex"), { recursive: true });
+	await writeFile(
+		globalConfigPath,
+		[
+			"[features.multi_agent_v2]",
+			"enabled = true",
+			"",
+			"[agents]",
+			"max_threads = 10",
+			"max_depth = 4",
+			"",
+		].join("\n"),
+	);
+	await symlink(globalConfigPath, projectConfigPath);
+
+	const result = await repairNearestProjectLocalCodexArtifacts({
+		startDirectory: projectRoot,
+		codexHome,
+		now: () => new Date("2026-06-01T00:00:00Z"),
+	});
+
+	assert.equal(result.configPath, null);
+	assert.equal(result.changed, false);
+	assert.equal(await pathExists(`${projectConfigPath}.backup-2026-06-01T00-00-00-000Z`), false);
+	const content = await readFile(globalConfigPath, "utf8");
+	assert.match(content, /max_threads = 10/);
+	assert.match(content, /max_depth = 4/);
+});
+
+test("#given malformed project directory from the environment #when script cleanup runs #then it skips project-local cleanup without failing install", async () => {
+	const codexHome = await makeTempDir();
+
+	const result = await repairNearestProjectLocalCodexArtifacts({
+		startDirectory: `bad${"\0"}path`,
+		codexHome,
+	});
+
+	assert.deepEqual(result, {
+		projectRoot: null,
+		configPath: null,
+		changed: false,
+		removedKeys: [],
+		configs: [],
+		artifacts: [],
+	});
+});
+
+test("#given absent project directory from the script surface #when script cleanup runs #then it skips project-local cleanup without throwing", async () => {
+	const codexHome = await makeTempDir();
+
+	const result = await repairNearestProjectLocalCodexArtifacts({ codexHome });
+
+	assert.deepEqual(result, {
+		projectRoot: null,
+		configPath: null,
+		changed: false,
+		removedKeys: [],
+		configs: [],
+		artifacts: [],
+	});
+});
+
+test("#given project cleanup hits a filesystem edge #when Node installer runs #then install succeeds and reports skipped cleanup", async () => {
+	const repoRoot = await makeTempDir();
+	const codexHome = await makeTempDir();
+	const binDir = await makeTempDir();
+	const projectRoot = await makeTempDir();
+	const projectDirectory = join(projectRoot, "not-a-directory");
+	const codexPackageRoot = join(repoRoot, "packages", "omo-codex");
+	const pluginRoot = join(codexPackageRoot, "plugin");
+	const logs = [];
+
+	await writeJson(join(codexPackageRoot, "marketplace.json"), {
+		name: "debug-marketplace",
+		plugins: [{ name: "alpha", source: "./plugin" }],
+	});
+	await writePluginAt(pluginRoot, "alpha", "1.2.3");
+	await writeFile(projectDirectory, "file, not directory\n");
+
+	const result = await installMarketplaceLocally({
+		repoRoot,
+		codexHome,
+		binDir,
+		projectDirectory,
+		platform: "linux",
+		runCommand: async (command, args, options) => {
+			if (command === "npm" && args.join(" ") === "run build") {
+				await mkdir(join(options.cwd, "dist"), { recursive: true });
+				await writeFile(join(options.cwd, "dist", "cli.js"), "#!/usr/bin/env node\n");
+			}
+		},
+		log: (message) => logs.push(message),
+	});
+
+	assert.equal(result.projectCleanup.projectRoot, null);
+	assert.equal(result.projectCleanup.changed, false);
+	assert.equal(logs.some((message) => message.includes("Skipped project-local Codex cleanup")), true);
+	assert.equal(logs.some((message) => message.includes("not a directory")), true);
+	assert.equal(await pathExists(join(codexHome, "config.toml")), true);
+});
+
+async function pathExists(path) {
+	try {
+		await lstat(path);
+		return true;
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+		throw error;
+	}
+}