oh-my-opencode 4.9.1 → 4.10.0

package/packages/omo-codex/plugin/components/bootstrap/src/hook.ts

@@ -0,0 +1,108 @@
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import type { Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
+
+import { DEFAULT_LOCK_STALE_MS } from "../../../scripts/auto-update-state.mjs";
+import { resolveBootstrapLockPath, resolveBootstrapStatePath } from "./environment.ts";
+import { readBootstrapState, readPluginVersion } from "./worker.ts";
+
+export const BOOTSTRAP_RESTART_NOTICE =
+	"LazyCodex bootstrap running in background — restart the session when it completes";
+
+export type SessionStartAction =
+	| "spawned"
+	| "skip-completed"
+	| "skip-locked"
+	| "skip-missing-env"
+	| "skip-version-unresolved";
+
+export interface WorkerSpawnInvocation {
+	readonly command: string;
+	readonly args: readonly string[];
+	readonly env: Record<string, string | undefined>;
+}
+
+export interface SessionStartHookOptions {
+	readonly env: Record<string, string | undefined>;
+	readonly stdin?: Readable & { readonly isTTY?: boolean };
+	readonly now?: number;
+	readonly spawnWorker?: (invocation: WorkerSpawnInvocation) => void;
+	readonly workerCliPath?: string;
+	readonly writeNotice?: (line: string) => void;
+}
+
+export interface SessionStartHookResult {
+	readonly exitCode: 0;
+	readonly action: SessionStartAction;
+}
+
+export async function runSessionStartHook(options: SessionStartHookOptions): Promise<number> {
+	return (await executeSessionStartHook(options)).exitCode;
+}
+
+export async function executeSessionStartHook(options: SessionStartHookOptions): Promise<SessionStartHookResult> {
+	if (options.stdin !== undefined) await drainStdin(options.stdin);
+	const now = options.now ?? Date.now();
+	const pluginRoot = options.env["PLUGIN_ROOT"]?.trim();
+	const pluginData = options.env["PLUGIN_DATA"]?.trim();
+	if (pluginRoot === undefined || pluginRoot.length === 0 || pluginData === undefined || pluginData.length === 0) {
+		return { action: "skip-missing-env", exitCode: 0 };
+	}
+
+	const pluginVersion = await readPluginVersion(pluginRoot);
+	if (pluginVersion === undefined) return { action: "skip-version-unresolved", exitCode: 0 };
+
+	const state = await readBootstrapState(resolveBootstrapStatePath(pluginData));
+	if (state.completedForVersion === pluginVersion) return { action: "skip-completed", exitCode: 0 };
+
+	if (await isLockFresh(resolveBootstrapLockPath(pluginData), now)) return { action: "skip-locked", exitCode: 0 };
+
+	const spawnWorker = options.spawnWorker ?? spawnDetachedWorker;
+	spawnWorker({
+		args: [options.workerCliPath ?? defaultWorkerCliPath(), "worker"],
+		command: process.execPath,
+		env: options.env,
+	});
+	const writeNotice = options.writeNotice ?? ((line: string) => process.stdout.write(`${line}\n`));
+	writeNotice(
+		JSON.stringify({
+			hookSpecificOutput: {
+				hookEventName: "SessionStart",
+				additionalContext: BOOTSTRAP_RESTART_NOTICE,
+			},
+		}),
+	);
+	return { action: "spawned", exitCode: 0 };
+}
+
+function spawnDetachedWorker(invocation: WorkerSpawnInvocation): void {
+	const child = spawn(invocation.command, [...invocation.args], {
+		detached: true,
+		env: invocation.env,
+		stdio: "ignore",
+	});
+	child.unref();
+}
+
+function defaultWorkerCliPath(): string {
+	// In the esbuild bundle every module shares import.meta.url, so this
+	// resolves to dist/cli.js — the file the detached worker must re-enter.
+	return fileURLToPath(import.meta.url);
+}
+
+async function isLockFresh(lockPath: string, now: number): Promise<boolean> {
+	try {
+		const lockStat = await stat(lockPath);
+		return now - lockStat.mtimeMs < DEFAULT_LOCK_STALE_MS;
+	} catch {
+		return false;
+	}
+}
+
+async function drainStdin(stdin: NonNullable<SessionStartHookOptions["stdin"]>): Promise<void> {
+	if (stdin.isTTY === true) return;
+	for await (const chunk of stdin) {
+		void chunk;
+	}
+}

package/packages/omo-codex/plugin/components/bootstrap/src/provision.ts

@@ -0,0 +1,243 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { inflateRawSync } from "node:zlib";
+
+// Cross-package source import (bundled into dist/cli.js at build time) so the
+// preexisting-sg probe order can never drift from the MCP's own resolver.
+import { findSgCliPathSync } from "../../../../../ast-grep-mcp/src/sg-cli-path.ts";
+import { downloadChecksummedAsset, loadAssetManifest } from "./download.ts";
+import type { FetchLike } from "./download.ts";
+import { appendBootstrapLog, BOOTSTRAP_DOCTOR_HINT } from "./worker.ts";
+import type { BootstrapStepOutcome, BootstrapWorkerContext } from "./worker.ts";
+
+export const SG_PROVISION_COMPONENT = "ast_grep";
+export const SG_FORCE_PROVISION_ENV_KEY = "OMO_BOOTSTRAP_FORCE_PROVISION";
+const SG_MANIFEST_NAME = "ast-grep";
+
+export interface ResolvePreexistingSgOptions {
+	readonly arch: string;
+	readonly codexHome: string;
+	readonly env: Record<string, string | undefined>;
+	readonly platform: NodeJS.Platform;
+}
+
+export interface SgProvisionSeams {
+	readonly arch?: string;
+	readonly fetchImpl?: FetchLike;
+	readonly resolvePreexistingSg?: (options: ResolvePreexistingSgOptions) => string | null;
+	readonly runVersionProbe?: (binaryPath: string) => Promise<string>;
+}
+
+export function sgProvisionDestination(context: BootstrapWorkerContext, arch: string): string {
+	const binaryName = context.platform === "win32" ? "sg.exe" : "sg";
+	return join(context.codexHome, "runtime", "ast-grep", `${context.platform}-${arch}`, binaryName);
+}
+
+export async function runSgProvision(
+	context: BootstrapWorkerContext,
+	seams: SgProvisionSeams = {},
+): Promise<BootstrapStepOutcome> {
+	const arch = seams.arch ?? process.arch;
+	const destination = sgProvisionDestination(context, arch);
+
+	if (context.env[SG_FORCE_PROVISION_ENV_KEY] !== "1") {
+		const preexisting = (seams.resolvePreexistingSg ?? defaultResolvePreexistingSg)({
+			arch,
+			codexHome: context.codexHome,
+			env: context.env,
+			platform: context.platform,
+		});
+		if (preexisting !== null) {
+			await appendBootstrapLog(context.pluginData, context.now, "sg-provision", { sg: `preexisting:${preexisting}` });
+			return { degraded: [] };
+		}
+	}
+
+	const stagingDir = join(dirname(destination), `.staging-${randomUUID().slice(0, 8)}`);
+	try {
+		const version = await provisionFromManifest(context, seams, { arch, destination, stagingDir });
+		await appendBootstrapLog(context.pluginData, context.now, "sg-provision", {
+			sg: `provisioned:${destination}`,
+			version,
+		});
+		return { degraded: [] };
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		await appendBootstrapLog(context.pluginData, context.now, "sg-provision-failed", { reason });
+		return { degraded: [{ component: SG_PROVISION_COMPONENT, hint: BOOTSTRAP_DOCTOR_HINT, reason }] };
+	} finally {
+		await rm(stagingDir, { force: true, recursive: true });
+	}
+}
+
+async function provisionFromManifest(
+	context: BootstrapWorkerContext,
+	seams: SgProvisionSeams,
+	layout: { readonly arch: string; readonly destination: string; readonly stagingDir: string },
+): Promise<string> {
+	const manifest = await loadAssetManifest(SG_MANIFEST_NAME, context.flags.manifestDir);
+	const platformKey = `${context.platform}-${layout.arch}`;
+	const asset = manifest.platforms[platformKey];
+	if (asset === undefined) {
+		throw new Error(
+			`ast-grep ${manifest.version} has no asset for unsupported platform "${platformKey}" (available: ${Object.keys(manifest.platforms).join(", ")}).`,
+		);
+	}
+
+	await mkdir(layout.stagingDir, { recursive: true });
+	const archivePath = await downloadChecksummedAsset({
+		destination: join(layout.stagingDir, basename(new URL(asset.url).pathname)),
+		env: context.env as NodeJS.ProcessEnv,
+		sha256: asset.sha256,
+		url: asset.url,
+		...(seams.fetchImpl === undefined ? {} : { fetchImpl: seams.fetchImpl }),
+	});
+
+	const binaryBytes = extractStandaloneSgBinary(await readFile(archivePath), context.platform);
+	const stagedBinary = join(layout.stagingDir, basename(layout.destination));
+	await writeFile(stagedBinary, binaryBytes);
+	await chmod(stagedBinary, 0o755);
+	await rename(stagedBinary, layout.destination);
+
+	await verifyProvisionedVersion(layout.destination, manifest.version, seams);
+	return manifest.version;
+}
+
+async function verifyProvisionedVersion(
+	destination: string,
+	pinnedVersion: string,
+	seams: SgProvisionSeams,
+): Promise<void> {
+	let reported: string;
+	try {
+		reported = (await (seams.runVersionProbe ?? defaultVersionProbe)(destination)).trim();
+	} catch (error) {
+		await rm(destination, { force: true });
+		throw new Error(
+			`provisioned sg at ${destination} failed its --version probe: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	if (!reported.includes(pinnedVersion)) {
+		await rm(destination, { force: true });
+		throw new Error(
+			`provisioned sg at ${destination} reported "${reported}" but the manifest pins version ${pinnedVersion}; removed the binary.`,
+		);
+	}
+}
+
+function defaultResolvePreexistingSg(options: ResolvePreexistingSgOptions): string | null {
+	return findSgCliPathSync({
+		arch: options.arch,
+		env: { ...options.env, CODEX_HOME: options.codexHome },
+		platform: options.platform,
+	});
+}
+
+const execFileAsync = promisify(execFile);
+
+async function defaultVersionProbe(binaryPath: string): Promise<string> {
+	const { stdout } = await execFileAsync(binaryPath, ["--version"]);
+	return String(stdout);
+}
+
+// Release zips (verified against 0.42.3) contain two entries: a tiny `sg`
+// alias shim that exec's `ast-grep` via PATH search ONLY (it fails standalone
+// even with a sibling ast-grep), and the standalone `ast-grep` binary. The
+// standalone entry is therefore installed under the destination name sg[.exe].
+function extractStandaloneSgBinary(zip: Buffer, platform: NodeJS.Platform): Buffer {
+	const suffix = platform === "win32" ? ".exe" : "";
+	const entries = listZipEntries(zip);
+	const preferredNames = [`ast-grep${suffix}`, `sg${suffix}`];
+	for (const preferred of preferredNames) {
+		const entry = entries.find((candidate) => zipEntryBaseName(candidate.name) === preferred);
+		if (entry !== undefined) return readZipEntryBytes(zip, entry);
+	}
+	throw new Error(
+		`ast-grep release zip has no ${preferredNames.join(" or ")} entry (found: ${entries.map((entry) => entry.name).join(", ")}).`,
+	);
+}
+
+function zipEntryBaseName(entryName: string): string {
+	const segments = entryName.split("/");
+	return segments[segments.length - 1] ?? entryName;
+}
+
+interface ZipCentralEntry {
+	readonly compressedSize: number;
+	readonly localHeaderOffset: number;
+	readonly method: number;
+	readonly name: string;
+	readonly uncompressedSize: number;
+}
+
+// Minimal zip reader (EOCD -> central directory -> local header) so extraction
+// stays pure-node and deterministic; offsets follow APPNOTE.TXT 4.3.
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const LOCAL_SIGNATURE = 0x04034b50;
+const ZIP64_SENTINEL = 0xffffffff;
+
+function listZipEntries(zip: Buffer): ZipCentralEntry[] {
+	const eocdOffset = findEndOfCentralDirectory(zip);
+	const entryCount = zip.readUInt16LE(eocdOffset + 10);
+	let cursor = zip.readUInt32LE(eocdOffset + 16);
+	const entries: ZipCentralEntry[] = [];
+	for (let index = 0; index < entryCount; index += 1) {
+		if (cursor + 46 > zip.length || zip.readUInt32LE(cursor) !== CENTRAL_SIGNATURE) {
+			throw new Error("zip central directory is corrupt (bad entry signature)");
+		}
+		const nameLength = zip.readUInt16LE(cursor + 28);
+		const extraLength = zip.readUInt16LE(cursor + 30);
+		const commentLength = zip.readUInt16LE(cursor + 32);
+		entries.push({
+			compressedSize: zip.readUInt32LE(cursor + 20),
+			localHeaderOffset: zip.readUInt32LE(cursor + 42),
+			method: zip.readUInt16LE(cursor + 10),
+			name: zip.subarray(cursor + 46, cursor + 46 + nameLength).toString("utf8"),
+			uncompressedSize: zip.readUInt32LE(cursor + 24),
+		});
+		cursor += 46 + nameLength + extraLength + commentLength;
+	}
+	return entries;
+}
+
+function findEndOfCentralDirectory(zip: Buffer): number {
+	const lowestOffset = Math.max(0, zip.length - 22 - 65_535);
+	for (let offset = zip.length - 22; offset >= lowestOffset; offset -= 1) {
+		if (zip.readUInt32LE(offset) === EOCD_SIGNATURE) return offset;
+	}
+	throw new Error("downloaded asset is not a zip archive (end-of-central-directory record missing)");
+}
+
+function readZipEntryBytes(zip: Buffer, entry: ZipCentralEntry): Buffer {
+	if (
+		entry.compressedSize === ZIP64_SENTINEL ||
+		entry.uncompressedSize === ZIP64_SENTINEL ||
+		entry.localHeaderOffset === ZIP64_SENTINEL
+	) {
+		throw new Error(`zip entry ${entry.name} uses unsupported zip64 extensions`);
+	}
+	if (zip.readUInt32LE(entry.localHeaderOffset) !== LOCAL_SIGNATURE) {
+		throw new Error(`zip entry ${entry.name} has a corrupt local header`);
+	}
+	const nameLength = zip.readUInt16LE(entry.localHeaderOffset + 26);
+	const extraLength = zip.readUInt16LE(entry.localHeaderOffset + 28);
+	const dataStart = entry.localHeaderOffset + 30 + nameLength + extraLength;
+	const raw = zip.subarray(dataStart, dataStart + entry.compressedSize);
+	const bytes = decompressZipEntry(raw, entry);
+	if (bytes.length !== entry.uncompressedSize) {
+		throw new Error(
+			`zip entry ${entry.name} inflated to ${bytes.length} bytes but the archive declares ${entry.uncompressedSize}`,
+		);
+	}
+	return bytes;
+}
+
+function decompressZipEntry(raw: Buffer, entry: ZipCentralEntry): Buffer {
+	if (entry.method === 0) return Buffer.from(raw);
+	if (entry.method === 8) return inflateRawSync(raw);
+	throw new Error(`zip entry ${entry.name} uses unsupported compression method ${entry.method}`);
+}

package/packages/omo-codex/plugin/components/bootstrap/src/setup.ts

@@ -0,0 +1,294 @@
+import { execFile } from "node:child_process";
+import { copyFile, mkdir, readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+// These relative imports resolve at BUILD time in the monorepo; esbuild
+// inlines the install modules into dist/cli.js so PLUGIN_ROOT ships nothing
+// beyond the bundle.
+import {
+	capturePreservedAgentReasoning,
+	capturePreservedAgentServiceTier,
+	linkCachedPluginAgents,
+} from "../../../../scripts/install/agents.mjs";
+import { resolveCodexInstallerBinDir } from "../../../../scripts/install/bin-dir.mjs";
+import { linkCachedPluginBins, linkRootRuntimeBin } from "../../../../scripts/install/bin-links.mjs";
+import { updateCodexConfig } from "../../../../scripts/install/config.mjs";
+import type { CodexAgentConfig } from "../../../../scripts/install/config.mjs";
+import { stampGitBashMcpEnv } from "../../../../scripts/install/git-bash-mcp-env.mjs";
+import { prepareGitBashForInstall } from "../../../../scripts/install/git-bash.mjs";
+import type { GitBashResolution } from "../../../../scripts/install/git-bash.mjs";
+import { trustedHookStatesForPlugin } from "../../../../scripts/install/hook-trust.mjs";
+import { appendBootstrapLog, BOOTSTRAP_DOCTOR_HINT } from "./worker.ts";
+import type { BootstrapDegradedEntry, BootstrapStepOutcome } from "./worker.ts";
+
+export const SETUP_MARKETPLACE_NAME = "sisyphuslabs";
+export const SETUP_PLUGIN_NAME = "omo";
+export const GIT_BASH_INSTALL_HINT = "winget install --id Git.Git -e --source winget";
+
+export type SetupRunCommand = (command: string, args: readonly string[], options: { cwd: string }) => Promise<unknown>;
+
+export interface WorkerSetupOptions {
+	readonly codexHome: string;
+	readonly env: Record<string, string | undefined>;
+	readonly pluginData: string;
+	readonly pluginRoot: string;
+	readonly platform: NodeJS.Platform;
+	/** Timestamp used for bootstrap.log entries; the worker passes its run time. */
+	readonly now?: number;
+	/** Test seam: command runner for the win32 Git Bash auto-install. */
+	readonly runCommand?: SetupRunCommand;
+	/** Test seam: overrides Git Bash discovery (win32 only). */
+	readonly resolveGitBash?: () => GitBashResolution;
+}
+
+interface AgentLinkOutcome {
+	readonly agentConfigs: readonly CodexAgentConfig[];
+	readonly degraded: readonly BootstrapDegradedEntry[];
+}
+
+// Worker setup sequence (every sub-step is idempotent and degraded-not-fatal,
+// unlike the npx installer which throws): Git Bash preflight -> bundled agent
+// TOML linking -> config blocks + hook trust re-stamp -> git_bash MCP env ->
+// version-aware bin links. Bin linking re-runs whenever the worker re-runs,
+// and the worker re-runs whenever completedForVersion changes (Task 7 marker
+// semantics), so links always point at the CURRENT versioned PLUGIN_ROOT even
+// though Codex deletes old version dirs on upgrade (core-plugins store.rs).
+export async function runWorkerSetup(options: WorkerSetupOptions): Promise<BootstrapStepOutcome> {
+	const degraded: BootstrapDegradedEntry[] = [];
+	const gitBashEnabled = await resolveGitBashStep(options, degraded);
+	const agents = await linkBundledAgentsStep(options);
+	degraded.push(...agents.degraded);
+	await updateConfigStep(options, { agentConfigs: agents.agentConfigs, gitBashEnabled }, degraded);
+	await stampGitBashEnvStep(options, degraded);
+	await linkComponentBinsStep(options, degraded);
+	return { degraded };
+}
+
+async function resolveGitBashStep(options: WorkerSetupOptions, degraded: BootstrapDegradedEntry[]): Promise<boolean> {
+	if (options.platform !== "win32") return false;
+	try {
+		const resolution = await prepareGitBashForInstall({
+			cwd: options.pluginRoot,
+			env: options.env,
+			platform: options.platform,
+			runCommand: options.runCommand ?? defaultRunCommand,
+			...(options.resolveGitBash === undefined ? {} : { resolveGitBash: options.resolveGitBash }),
+		});
+		if (resolution.found) return true;
+		degraded.push({
+			component: "git-bash",
+			hint: GIT_BASH_INSTALL_HINT,
+			reason: "Git Bash was not found on this Windows machine; the omo git_bash MCP server stays disabled",
+		});
+	} catch (error) {
+		degraded.push({
+			component: "git-bash",
+			hint: GIT_BASH_INSTALL_HINT,
+			reason: `Git Bash preflight failed: ${errorMessage(error)}`,
+		});
+	}
+	return false;
+}
+
+async function linkBundledAgentsStep(options: WorkerSetupOptions): Promise<AgentLinkOutcome> {
+	const agentsTarget = join(options.codexHome, "agents");
+	try {
+		// linkCachedPluginAgents writes its .installed-agents.json manifest next
+		// to the agent sources, so the bundled TOMLs are staged under PLUGIN_DATA
+		// first: bootstrap must never persist anything under PLUGIN_ROOT (the
+		// Codex-managed marketplace cache).
+		const stageRoot = join(options.pluginData, "bootstrap", "agents-stage");
+		await stageBundledAgents(options.pluginRoot, stageRoot);
+		const preservedReasoning = await capturePreservedAgentReasoning({ codexHome: options.codexHome });
+		const preservedServiceTier = await capturePreservedAgentServiceTier({ codexHome: options.codexHome });
+		const linked = await linkCachedPluginAgents({
+			codexHome: options.codexHome,
+			pluginRoot: stageRoot,
+			preservedReasoning,
+			preservedServiceTier,
+		});
+		const agentConfigs = linked
+			.map((link) => ({ configFile: `./agents/${link.name}`, name: agentNameFromToml(link.name) }))
+			.sort((left, right) => left.name.localeCompare(right.name));
+		return { agentConfigs, degraded: [] };
+	} catch (error) {
+		return {
+			agentConfigs: [],
+			degraded: [
+				{
+					component: "agents",
+					hint: BOOTSTRAP_DOCTOR_HINT,
+					reason: `failed to link bundled agents into ${agentsTarget}: ${errorMessage(error)}`,
+				},
+			],
+		};
+	}
+}
+
+async function stageBundledAgents(pluginRoot: string, stageRoot: string): Promise<void> {
+	await rm(stageRoot, { force: true, recursive: true });
+	await mkdir(stageRoot, { recursive: true });
+	const componentsRoot = join(pluginRoot, "components");
+	for (const componentName of await directoryNames(componentsRoot)) {
+		const agentsDir = join(componentsRoot, componentName, "agents");
+		const agentFiles = (await fileNames(agentsDir)).filter((name) => name.endsWith(".toml"));
+		if (agentFiles.length === 0) continue;
+		const stagedAgentsDir = join(stageRoot, "components", componentName, "agents");
+		await mkdir(stagedAgentsDir, { recursive: true });
+		for (const agentFile of agentFiles) {
+			await copyFile(join(agentsDir, agentFile), join(stagedAgentsDir, agentFile));
+		}
+	}
+}
+
+async function updateConfigStep(
+	options: WorkerSetupOptions,
+	inputs: { agentConfigs: readonly CodexAgentConfig[]; gitBashEnabled: boolean },
+	degraded: BootstrapDegradedEntry[],
+): Promise<void> {
+	const configPath = join(options.codexHome, "config.toml");
+	try {
+		await assertWritableConfigIfPresent(configPath);
+		// Re-stamping trusted hook hashes after an upgrade is what makes the
+		// next session's hooks trusted again once the user re-approved the
+		// bootstrap hook itself.
+		const trustedHookStates = await trustedHookStatesForPlugin({
+			marketplaceName: SETUP_MARKETPLACE_NAME,
+			pluginName: SETUP_PLUGIN_NAME,
+			pluginRoot: options.pluginRoot,
+		});
+		await updateCodexConfig({
+			agentConfigs: inputs.agentConfigs,
+			// Hard invariant: the bootstrap worker NEVER writes permission keys
+			// (approval/sandbox/network policies stay installer-flag-only).
+			autonomousPermissions: false,
+			configPath,
+			gitBashEnabled: inputs.gitBashEnabled,
+			marketplaceName: SETUP_MARKETPLACE_NAME,
+			platform: options.platform,
+			pluginNames: [SETUP_PLUGIN_NAME],
+			preserveMarketplaceSource: true,
+			// The marketplace plugin tree has no <root>/plugin/model-catalog.json,
+			// so updateCodexConfig falls back to the catalog bundled into this
+			// dist; bootstrap-setup.test.mjs guards against drift between the two.
+			repoRoot: options.pluginRoot,
+			trustedHookStates,
+		});
+	} catch (error) {
+		degraded.push({
+			component: "config",
+			hint: BOOTSTRAP_DOCTOR_HINT,
+			reason: `failed to update ${configPath}: ${errorMessage(error)}`,
+		});
+	}
+}
+
+async function assertWritableConfigIfPresent(configPath: string): Promise<void> {
+	try {
+		if (((await stat(configPath)).mode & 0o222) === 0) throw new Error(`${configPath} has no write permission bits set`);
+	} catch (error) {
+		if (errorCode(error) === "ENOENT") return;
+		throw error;
+	}
+}
+
+function errorCode(error: unknown): string | undefined {
+	return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : undefined;
+}
+
+async function linkComponentBinsStep(options: WorkerSetupOptions, degraded: BootstrapDegradedEntry[]): Promise<void> {
+	const binDir = resolveCodexInstallerBinDir({ codexHome: options.codexHome, env: options.env });
+	try {
+		await linkCachedPluginBins({ binDir, pluginRoot: options.pluginRoot, platform: options.platform });
+	} catch (error) {
+		degraded.push({
+			component: "bin-links",
+			hint: BOOTSTRAP_DOCTOR_HINT,
+			reason: `failed to link component bins into ${binDir}: ${errorMessage(error)}`,
+		});
+	}
+	await linkRuntimeWrapperStep(options, binDir, degraded);
+}
+
+// The marketplace payload intentionally ships without <pluginRoot>/dist/cli
+// (thin payload), so linkRootRuntimeBin returning null is the expected
+// degraded mode there: record the omo-cli ledger entry and log the same
+// warning install-local.mjs prints instead of leaving a broken `omo` link.
+async function linkRuntimeWrapperStep(
+	options: WorkerSetupOptions,
+	binDir: string,
+	degraded: BootstrapDegradedEntry[],
+): Promise<void> {
+	const cliPath = join(options.pluginRoot, "dist", "cli", "index.js");
+	try {
+		const linked = await linkRootRuntimeBin({
+			binDir,
+			codexHome: options.codexHome,
+			platform: options.platform,
+			repoRoot: options.pluginRoot,
+		});
+		if (linked !== null) return;
+		degraded.push({
+			component: "omo-cli",
+			hint: "use npx lazycodex-ai for the omo CLI",
+			reason: "marketplace payload has no dist/cli",
+		});
+		await appendBootstrapLog(options.pluginData, options.now ?? Date.now(), "omo-cli-degraded", {
+			warning: `Warning: skipped the omo runtime wrapper because ${cliPath} is missing; omo sparkshell/ulw-loop commands will be unavailable until a package shipping dist/cli is installed`,
+		});
+	} catch (error) {
+		degraded.push({
+			component: "omo-cli",
+			hint: BOOTSTRAP_DOCTOR_HINT,
+			reason: `failed to link the omo runtime wrapper into ${binDir}: ${errorMessage(error)}`,
+		});
+	}
+}
+
+async function stampGitBashEnvStep(options: WorkerSetupOptions, degraded: BootstrapDegradedEntry[]): Promise<void> {
+	try {
+		await stampGitBashMcpEnv({ env: options.env, platform: options.platform, pluginRoot: options.pluginRoot });
+	} catch (error) {
+		degraded.push({
+			component: "git-bash-env",
+			hint: BOOTSTRAP_DOCTOR_HINT,
+			reason: `failed to stamp ${join(options.pluginRoot, ".mcp.json")}: ${errorMessage(error)}`,
+		});
+	}
+}
+
+const execFileAsync = promisify(execFile);
+
+async function defaultRunCommand(command: string, args: readonly string[], options: { cwd: string }): Promise<unknown> {
+	return execFileAsync(command, [...args], { cwd: options.cwd });
+}
+
+async function directoryNames(root: string): Promise<string[]> {
+	return entryNames(root, (entry) => entry.isDirectory());
+}
+
+async function fileNames(root: string): Promise<string[]> {
+	return entryNames(root, (entry) => entry.isFile());
+}
+
+async function entryNames(root: string, keep: (entry: { isDirectory(): boolean; isFile(): boolean }) => boolean): Promise<string[]> {
+	try {
+		const entries = await readdir(root, { withFileTypes: true });
+		return entries
+			.filter((entry) => keep(entry))
+			.map((entry) => entry.name)
+			.sort();
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+function agentNameFromToml(fileName: string): string {
+	return fileName.endsWith(".toml") ? fileName.slice(0, -".toml".length) : fileName;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}