@oh-my-pi/pi-coding-agent 16.4.2 → 16.4.3

package/src/extensibility/plugins/legacy-pi-compat.ts

@@ -1,82 +1,62 @@
+/// <reference path="./legacy-pi-virtual-modules.d.ts" />
 import * as fs from "node:fs";
 import { isBuiltin } from "node:module";
 import * as path from "node:path";
 import * as url from "node:url";
 import { isCompiledBinary, stripWindowsExtendedLengthPathPrefix } from "@oh-my-pi/pi-utils";
 import { registerPluginCacheInvalidator } from "../../discovery/helpers";
-import { BUNDLED_PI_REGISTRY_KEYS } from "./legacy-pi-bundled-keys";
 
 const IS_COMPILED_BINARY = isCompiledBinary();
 
-// === Bundled host-package registry (issue #3423) ===
+// === Bundled host modules (issue #3423) ===
 //
 // Bun 1.3.14 stopped exposing `--compile` extras through any filesystem-style
 // API: `fs.existsSync`, `Bun.file().exists()`, `Bun.resolveSync`, and even
 // `import("/$bunfs/...")` / `import("file:///$bunfs/...")` all fail for the
-// embedded entries — only the main binary itself answers from
-// `/$bunfs/root/<binary-name>`. The previous strategy of rewriting
-// `@(scope)/pi-*` imports to a `file:///$bunfs/...` URL therefore breaks
-// every legacy extension in compiled mode (issue #3423; see also issues
-// #3329, #2168). Bun.plugin `onResolve` for bare specifiers also no longer
-// fires for transitive imports inside runtime-loaded extensions, so the
-// fallback hook in `installLegacyPiSpecifierShim()` cannot rescue them.
+// embedded entries. Bun.plugin `onResolve` also no longer fires for transitive
+// imports inside runtime-loaded extensions.
 //
-// Instead we keep a JS-heap reference to every bundled pi-* surface (the
-// canonical host packages and the legacy shims) and re-export them through a
-// Bun.plugin `onLoad` against a custom namespace. Extension source rewrites
-// emit `omp-legacy-pi-bundled:<key>` specifiers that the synthetic loader
-// resolves against the registry — no bunfs path ever leaves this module in
-// compiled mode. Dev / source-link / installed-package modes keep the
-// historical `file://` rewrite (the source files exist on disk and load fine
-// through Bun's standard URL loader).
-//
-// The registry lives in a sibling file (`legacy-pi-bundled-registry.ts`)
-// loaded via a conditional dynamic import: its transitive deps include the
-// coding-agent root which pulls in generated artifacts (e.g.
-// `export/html/tool-views.generated.js`) that only exist after a build, so a
-// static import would crash every dev/test run that touches
-// `legacy-pi-compat.ts`. This is the documented "conditional platform code"
-// exception to the static-import rule.
+// Compiled builds therefore keep live JS-heap references to the host packages
+// and serve requested surfaces through `omp-legacy-pi-bundled:<key>` synthetic
+// modules. `scripts/legacy-pi-virtual-module.ts` derives the static import edges
+// from current package exports inside a Bun build plugin: no generated source
+// or duplicate key list exists on disk. Runtime extension loading stays lazy —
+// the virtual module is evaluated only when an extension requests a host
+// package — but the compiler still sees every possible edge at build time.
 const BUNDLED_VIRTUAL_SCHEME = "omp-legacy-pi-bundled:";
 const BUNDLED_VIRTUAL_NAMESPACE = "omp-legacy-pi-bundled";
-const BUNDLED_REGISTRY_GLOBAL = "__ompLegacyPiBundledRegistry";
-const TYPEBOX_BUNDLED_REGISTRY_KEY = "typebox";
+const BUNDLED_MODULES_GLOBAL = "__ompLegacyPiBundledModules";
+const TYPEBOX_BUNDLED_MODULE_KEY = "typebox";
 
-type BundledRegistry = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+type BundledModules = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
 
-let bundledRegistryPromise: Promise<BundledRegistry> | null = null;
+let bundledModulesPromise: Promise<BundledModules> | null = null;
 
 /**
- * Lazy-load the bundled host-package registry and stash it on `globalThis`
- * for the synthetic loader emitted by `synthesizeBundledModuleSource`.
- *
- * `globalThis` is the bridge, not laziness: each synthesized
- * `omp-legacy-pi-bundled:<key>` module is a *separate* ES module Bun compiles
- * from a source string, so it cannot close over the registry in this file's
- * lexical scope and the live (non-serializable) function/object exports cannot
- * be inlined — the only runtime channel back to the host objects is a global.
+ * Lazy-load the build-supplied host modules and stash them on `globalThis` for
+ * the synthetic module source emitted by `synthesizeBundledModuleSource`.
  *
- * The dynamic import is gated by `IS_COMPILED_BINARY` so dev/test runs (where
- * the registry's transitive deps include build-time-generated artifacts)
- * never trigger the cascade.
+ * `globalThis` is the bridge: each `omp-legacy-pi-bundled:<key>` source string
+ * becomes a separate ES module and cannot close over this file's lexical scope.
+ * The dynamic import is intentional conditional build code. Dev/test runs
+ * never execute it; binary builds resolve the literal through the in-memory
+ * plugin in `scripts/legacy-pi-virtual-module.ts`.
  */
-function ensureBundledRegistryLoaded(): Promise<BundledRegistry> {
+function ensureBundledModulesLoaded(): Promise<BundledModules> {
 	if (!IS_COMPILED_BINARY) {
-		return Promise.reject(
-			new Error("omp:legacy-pi-shim: bundled registry is only available in compiled-binary mode"),
-		);
+		return Promise.reject(new Error("omp:legacy-pi-shim: bundled modules are only available in compiled mode"));
 	}
-	if (!bundledRegistryPromise) {
-		bundledRegistryPromise = import("./legacy-pi-bundled-registry").then(m => {
-			(globalThis as Record<string, unknown>)[BUNDLED_REGISTRY_GLOBAL] = m.BUNDLED_PI_REGISTRY;
-			return m.BUNDLED_PI_REGISTRY;
+	if (!bundledModulesPromise) {
+		bundledModulesPromise = import("omp-legacy-pi-modules").then(module => {
+			Reflect.set(globalThis, BUNDLED_MODULES_GLOBAL, module.BUNDLED_PI_MODULES);
+			return module.BUNDLED_PI_MODULES;
 		});
 	}
-	return bundledRegistryPromise;
+	return bundledModulesPromise;
 }
 
-function bundledRegistryVirtualSpecifier(registryKey: string): string {
-	return `${BUNDLED_VIRTUAL_SCHEME}${registryKey}`;
+function bundledModuleVirtualSpecifier(moduleKey: string): string {
+	return `${BUNDLED_VIRTUAL_SCHEME}${moduleKey}`;
 }
 
 function isBundledVirtualSpecifier(value: string): boolean {
@@ -84,19 +64,16 @@ function isBundledVirtualSpecifier(value: string): boolean {
 }
 
 /**
- * Build the synthetic ES module source for a `omp-legacy-pi-bundled:<key>`
- * import against an explicit registry. Pure: takes the live module namespace
- * and emits a string of ES exports rooted in `globalThis[BUNDLED_REGISTRY_GLOBAL]`.
- * `synthesizeBundledModuleSource` wraps this with the lazy registry load —
- * tests use this sync helper directly to assert export-shape preservation.
+ * Build a synthetic ES module for one live bundled namespace. Every export
+ * reads through the global bridge; no bunfs path or copied package is involved.
  */
-function synthesizeBundledModuleSourceFromRegistry(registryKey: string, registry: BundledRegistry): string {
-	const mod = registry[registryKey];
+function synthesizeBundledModuleSourceFromModules(moduleKey: string, modules: BundledModules): string {
+	const mod = modules[moduleKey];
 	if (!mod) {
-		throw new Error(`omp:legacy-pi-shim: no bundled module registered for ${registryKey}`);
+		throw new Error(`omp:legacy-pi-shim: no bundled module registered for ${moduleKey}`);
 	}
 	const lines: string[] = [
-		`const __omp_bundled = globalThis[${JSON.stringify(BUNDLED_REGISTRY_GLOBAL)}][${JSON.stringify(registryKey)}];`,
+		`const __omp_bundled = globalThis[${JSON.stringify(BUNDLED_MODULES_GLOBAL)}][${JSON.stringify(moduleKey)}];`,
 	];
 	let hasDefault = false;
 	for (const exportName in mod) {
@@ -114,36 +91,25 @@ function synthesizeBundledModuleSourceFromRegistry(registryKey: string, registry
 }
 
 /**
- * Build the synthetic ES module source served for an
- * `omp-legacy-pi-bundled:<key>` import. Enumerates the live module namespace
- * so legacy extensions see the same named/default exports they would have
- * gotten from a real `file://` load — without touching the inaccessible bunfs
- * filesystem.
+ * Build the synthetic source served for one
+ * `omp-legacy-pi-bundled:<key>` import.
  */
-async function synthesizeBundledModuleSource(registryKey: string): Promise<string> {
-	const registry = await ensureBundledRegistryLoaded();
-	return synthesizeBundledModuleSourceFromRegistry(registryKey, registry);
+async function synthesizeBundledModuleSource(moduleKey: string): Promise<string> {
+	const modules = await ensureBundledModulesLoaded();
+	return synthesizeBundledModuleSourceFromModules(moduleKey, modules);
 }
 
-/**
- * Test seam: builds the synthetic ES module source for a virtual specifier
- * against an explicit registry. Pure (no globalThis read); the emitted source
- * still routes runtime lookups through `globalThis[BUNDLED_REGISTRY_GLOBAL]`.
- */
-export function __synthesizeLegacyPiBundledSourceWithRegistry(
-	registryKey: string,
-	registry: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
+/** Test seam for the virtual module's named/default export forwarding. */
+export function __synthesizeLegacyPiBundledSourceWithModules(
+	moduleKey: string,
+	modules: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
 ): string {
-	return synthesizeBundledModuleSourceFromRegistry(registryKey, registry);
+	return synthesizeBundledModuleSourceFromModules(moduleKey, modules);
 }
 
-/**
- * Test seam: returns the globalThis key the synthetic loader reads from. Tests
- * assert that the emitted source addresses the exact stash key the install
- * function writes to, so a rename can't break extension loads silently.
- */
-export function __getLegacyPiBundledRegistryGlobal(): string {
-	return BUNDLED_REGISTRY_GLOBAL;
+/** Test seam for the global bridge key shared with synthetic module source. */
+export function __getLegacyPiBundledModulesGlobal(): string {
+	return BUNDLED_MODULES_GLOBAL;
 }
 
 // Canonical scope for in-process pi packages. Plugins published against any of
@@ -207,6 +173,9 @@ const nodePackageRootCache = new Map<string, Promise<string | null>>();
 const packageManifestCache = new Map<string, Promise<Record<string, unknown> | null>>();
 const bareDependencyResolutionCache = new Map<string, Promise<string | null>>();
 const realpathCache = new Map<string, Promise<string>>();
+const nativeAddonResolutionCache = new Map<string, Promise<string | null>>();
+const nativeAddonRequireScanCache = new Map<string, Promise<boolean>>();
+const nativeAddonLoaderModulePaths = new Set<string>();
 
 function clearLegacyPiResolutionCaches(): void {
 	resolvedSpecifierFallbacks.clear();
@@ -215,6 +184,9 @@ function clearLegacyPiResolutionCaches(): void {
 	nodePackageRootCache.clear();
 	packageManifestCache.clear();
 	bareDependencyResolutionCache.clear();
+	nativeAddonResolutionCache.clear();
+	nativeAddonRequireScanCache.clear();
+	nativeAddonLoaderModulePaths.clear();
 	realpathCache.clear();
 }
 
@@ -232,7 +204,7 @@ const TYPEBOX_SPECIFIER_FILTER = /^(?:@sinclair\/typebox|typebox)$/;
 
 // Compat-shim path resolution. In compiled-binary mode every bundled surface
 // is served through the `omp-legacy-pi-bundled:` virtual namespace (see the
-// registry block above) — bunfs paths are unreachable on Bun 1.3.14+, so the
+// bundled-module block above) — bunfs paths are unreachable on Bun 1.3.14+, so the
 // pre-#3423 helpers that derived `/$bunfs/root/...` paths from
 // `import.meta.dir` are gone. Dev / source-link / installed-package modes
 // still need a real filesystem path for the source shims, which
@@ -298,7 +270,7 @@ export function __resolveTypeBoxShimPath(
 	pathExistsSync: (p: string) => boolean = fs.existsSync,
 ): string | null {
 	if (isCompiled) {
-		return bundledRegistryVirtualSpecifier(TYPEBOX_BUNDLED_REGISTRY_KEY);
+		return bundledModuleVirtualSpecifier(TYPEBOX_BUNDLED_MODULE_KEY);
 	}
 	return pathExistsSync(sourcePath) ? sourcePath : null;
 }
@@ -314,18 +286,18 @@ const TYPEBOX_SHIM_PATH = __resolveTypeBoxShimPath(IS_COMPILED_BINARY, sourceShi
 // imports such as `@oh-my-pi/pi-ai/oauth` continue to resolve directly
 // against the bundled pi-ai package.
 const LEGACY_PI_AI_SHIM_PATH = IS_COMPILED_BINARY
-	? bundledRegistryVirtualSpecifier(`${CANONICAL_PI_SCOPE}/pi-ai`)
+	? bundledModuleVirtualSpecifier(`${CANONICAL_PI_SCOPE}/pi-ai`)
 	: sourceShimPath("legacy-pi-ai-shim.ts");
 
 // The coding-agent's own `./src/index.ts` cannot be listed as an extra
 // `bun --compile` entrypoint alongside the CLI entry without breaking binary
 // startup (issue #1474 follow-up). In compiled-binary mode the legacy
 // `@(scope)/pi-coding-agent` root therefore resolves through the bundled
-// registry shim; in dev / source-link / installed-package mode it points at
-// the sibling source shim whose distinct file path avoids the #1474 collision
+// module shim; in dev / source-link / installed-package mode it points at the
+// sibling source shim whose distinct file path avoids the #1474 collision
 // while still re-exporting the canonical package surface.
 const LEGACY_PI_CODING_AGENT_SHIM_PATH = IS_COMPILED_BINARY
-	? bundledRegistryVirtualSpecifier(`${CANONICAL_PI_SCOPE}/pi-coding-agent`)
+	? bundledModuleVirtualSpecifier(`${CANONICAL_PI_SCOPE}/pi-coding-agent`)
 	: sourceShimPath("legacy-pi-coding-agent-shim.ts");
 
 // Package-root overrides. Shim entries (`pi-ai`, `pi-coding-agent`) always
@@ -346,8 +318,8 @@ const LEGACY_PI_CODING_AGENT_SHIM_PATH = IS_COMPILED_BINARY
 /**
  * Drop overrides whose filesystem targets are missing so they can fall
  * through to the canonical-resolution path. Virtual `omp-legacy-pi-bundled:`
- * entries always pass — the bundled registry is the source of truth in
- * compiled-binary mode where bunfs paths are unreachable (issue #3423).
+ * entries always pass — live bundled module references are the source of truth
+ * in compiled mode where bunfs paths are unreachable (issue #3423).
  *
  * `pathExistsSync` defaults to `fs.existsSync`; tests inject a stub to
  * simulate the missing-entrypoint failure mode without touching the real FS.
@@ -356,41 +328,59 @@ export function __validateLegacyPiPackageRootOverrides(
 	candidates: Record<string, string>,
 	pathExistsSync: (p: string) => boolean = fs.existsSync,
 ): Record<string, string> {
-	return Object.fromEntries(
-		Object.entries(candidates).filter(
-			([, candidate]) => isBundledVirtualSpecifier(candidate) || pathExistsSync(candidate),
-		),
-	);
+	const valid: Record<string, string> = {};
+	for (const key in candidates) {
+		const candidate = candidates[key];
+		if (candidate && (isBundledVirtualSpecifier(candidate) || pathExistsSync(candidate))) {
+			valid[key] = candidate;
+		}
+	}
+	return valid;
 }
 
 /**
  * Compute the override map keyed by every canonical specifier the host serves
  * directly: the pi-ai / pi-coding-agent roots (compat shims that re-attach
- * legacy helpers) plus, in compiled-binary mode, every other canonical pi-*
- * package root AND every non-wildcard subpath registered in the bundled
- * registry (see `legacy-pi-bundled-keys.ts`). Subpath coverage is what stops
- * `@(scope)/pi-ai/oauth` and friends from falling through to the extension's
- * own — possibly absent — peer install when bunfs filesystem walks fail
- * (issue #3442 follow-up to #3423). Exported as a test seam so the
- * compiled-binary branch is verifiable from dev tests.
+ * legacy helpers) plus, in compiled mode, every build-supplied module key.
+ * Subpath coverage stops `@(scope)/pi-ai/oauth` and friends from falling
+ * through to the extension's absent peer install when bunfs walks fail.
  */
-export function __buildLegacyPiPackageRootOverrides(isCompiled: boolean): Record<string, string> {
+export function __buildLegacyPiPackageRootOverrides(
+	isCompiled: boolean,
+	bundledModuleKeys: Iterable<string> = [],
+): Record<string, string> {
 	const candidates: Record<string, string> = {
 		[`${CANONICAL_PI_SCOPE}/pi-ai`]: LEGACY_PI_AI_SHIM_PATH,
 		[`${CANONICAL_PI_SCOPE}/pi-coding-agent`]: LEGACY_PI_CODING_AGENT_SHIM_PATH,
 	};
 	if (isCompiled) {
-		for (const key of BUNDLED_PI_REGISTRY_KEYS) {
-			// Shim-bearing roots above already mapped to their compat surface;
-			// the bundled typebox shim has a dedicated TYPEBOX_SHIM_PATH route.
-			if (key in candidates || key === TYPEBOX_BUNDLED_REGISTRY_KEY) continue;
-			candidates[key] = bundledRegistryVirtualSpecifier(key);
+		for (const key of bundledModuleKeys) {
+			// Shim-bearing roots already map to their compat surfaces; TypeBox
+			// has a dedicated TYPEBOX_SHIM_PATH route.
+			if (key in candidates || key === TYPEBOX_BUNDLED_MODULE_KEY) continue;
+			candidates[key] = bundledModuleVirtualSpecifier(key);
 		}
 	}
 	return __validateLegacyPiPackageRootOverrides(candidates);
 }
 
-const LEGACY_PI_PACKAGE_ROOT_OVERRIDES = __buildLegacyPiPackageRootOverrides(IS_COMPILED_BINARY);
+// Seeded with compat roots at module init; first compiled extension load adds
+// every key supplied by the in-memory build module.
+let legacyPiPackageRootOverrides = __buildLegacyPiPackageRootOverrides(IS_COMPILED_BINARY);
+let legacyPiOverridesReadyPromise: Promise<void> | null = null;
+
+/** Complete compiled-mode overrides once from the lazily evaluated host modules. */
+function ensureLegacyPiOverridesReady(): Promise<void> {
+	if (!IS_COMPILED_BINARY) {
+		return Promise.resolve();
+	}
+	if (!legacyPiOverridesReadyPromise) {
+		legacyPiOverridesReadyPromise = ensureBundledModulesLoaded().then(modules => {
+			legacyPiPackageRootOverrides = __buildLegacyPiPackageRootOverrides(true, Object.keys(modules));
+		});
+	}
+	return legacyPiOverridesReadyPromise;
+}
 
 let isLegacyPiSpecifierShimInstalled = false;
 
@@ -428,7 +418,7 @@ function getResolvedSpecifier(specifier: string): string {
  * specifiers.
  */
 function resolveCanonicalPiSpecifier(remappedSpecifier: string): string {
-	const override = LEGACY_PI_PACKAGE_ROOT_OVERRIDES[remappedSpecifier];
+	const override = legacyPiPackageRootOverrides[remappedSpecifier];
 	if (override) {
 		return override;
 	}
@@ -438,7 +428,7 @@ function resolveCanonicalPiSpecifier(remappedSpecifier: string): string {
 function toImportSpecifier(resolvedPath: string): string {
 	// Virtual `omp-legacy-pi-bundled:` specifiers are served by the synthetic
 	// onLoad in `installLegacyPiSpecifierShim()`; wrapping them as `file://`
-	// would corrupt the scheme and bypass the bundled registry.
+	// would corrupt the scheme.
 	if (isBundledVirtualSpecifier(resolvedPath)) {
 		return resolvedPath;
 	}
@@ -492,6 +482,9 @@ async function rewriteLegacyExtensionSource(
 	importerPath: string,
 	mtimeTag: string | null = null,
 ): Promise<string> {
+	// Compiled mode completes the override map from the build-supplied module
+	// keys on first use; every rewrite path must see the full map.
+	await ensureLegacyPiOverridesReady();
 	const withPi = rewriteLegacyPiImports(source);
 	// When the TypeBox shim is missing (release build dropped the entrypoint —
 	// issue #3414), leave bare specifiers untouched so Bun resolves a real
@@ -506,10 +499,11 @@ async function rewriteLegacyExtensionSource(
 		: withPi;
 	const withPkg = await rewriteExtensionPackageImports(withTypeBox, importerPath, mtimeTag);
 	const withBare = await rewriteExtensionBareImports(withPkg, importerPath, mtimeTag);
+	const withNativeAddons = await rewriteExtensionNativeAddonRequires(withBare, importerPath);
 	if (!mtimeTag) {
-		return withBare;
+		return withNativeAddons;
 	}
-	return withBare.replace(
+	return withNativeAddons.replace(
 		RELATIVE_GRAPH_IMPORT_SPECIFIER_REGEX,
 		(_match, prefix: string, specifier: string, suffix: string) => `${prefix}${specifier}?mtime=${mtimeTag}${suffix}`,
 	);
@@ -950,6 +944,118 @@ async function resolveExtensionBareDependencyUncached(specifier: string, importe
 	return resolveNodePackageDependency(specifier, importerPath);
 }
 
+const NATIVE_ADDON_EXTENSION = ".node";
+
+// Match CommonJS require calls so bare native-addon specifiers can be pinned
+// to absolute paths. Only requires whose resolution lands on a `.node` addon
+// are rewritten; everything else stays on Bun's native resolver.
+const NATIVE_ADDON_REQUIRE_SPECIFIER_REGEX = /(\brequire\s*\(\s*["'])([^"'()\s]+)(["']\s*\))/g;
+
+/**
+ * Resolve a bare specifier whose target is a native `.node` addon — either a
+ * package subpath ending in `.node`, or a package whose `main` points at an
+ * addon (the napi-rs per-platform package convention, e.g.
+ * `@yuuang/ffi-rs-darwin-arm64` → `ffi-rs.darwin-arm64.node`). Returns the
+ * addon's absolute realpath, or null when the specifier is not a native addon.
+ */
+async function resolveExtensionNativeAddon(specifier: string, importerPath: string): Promise<string | null> {
+	if (!isBareExtensionDependencySpecifier(specifier)) {
+		return null;
+	}
+
+	const cacheKey = `${specifier}\0${path.resolve(path.dirname(importerPath))}`;
+	const cached = nativeAddonResolutionCache.get(cacheKey);
+	if (cached) return cached;
+
+	const promise = resolveExtensionNativeAddonUncached(specifier, importerPath);
+	nativeAddonResolutionCache.set(cacheKey, promise);
+	return promise;
+}
+
+async function resolveExtensionNativeAddonUncached(specifier: string, importerPath: string): Promise<string | null> {
+	const parsed = splitBarePackageSpecifier(specifier);
+	if (!parsed) return null;
+	const packageRoot = await findNodePackageRoot(parsed.name, importerPath);
+	if (!packageRoot) return null;
+
+	let target: string | null = null;
+	if (parsed.subpath !== null) {
+		target = parsed.subpath.endsWith(NATIVE_ADDON_EXTENSION) ? path.join(packageRoot, parsed.subpath) : null;
+	} else {
+		const manifest = await readPackageManifest(packageRoot);
+		const main = manifest?.main;
+		target =
+			typeof main === "string" && main.endsWith(NATIVE_ADDON_EXTENSION) ? path.resolve(packageRoot, main) : null;
+	}
+	if (!target || !(await pathExists(target))) {
+		return null;
+	}
+	return realpathOrSelf(target);
+}
+
+/**
+ * Rewrite bare `require()` specifiers that resolve to native `.node` addons
+ * into absolute-path requires. In `bun build --compile` binaries, Bun's bare
+ * resolution fails for packages whose `main` is a `.node` addon ("Cannot find
+ * module '@scope/pkg-<platform>'") even when the package sits in the
+ * extension's own node_modules; requiring the addon by absolute path works.
+ */
+async function rewriteExtensionNativeAddonRequires(source: string, importerPath: string): Promise<string> {
+	let rewritten = "";
+	let lastIndex = 0;
+	for (const match of source.matchAll(NATIVE_ADDON_REQUIRE_SPECIFIER_REGEX)) {
+		const matchIndex = match.index;
+		if (matchIndex === undefined) continue;
+
+		const [fullMatch, prefix, specifier, suffix] = match;
+		if (!prefix || !specifier || !suffix) continue;
+
+		const resolved = await resolveExtensionNativeAddon(specifier, importerPath);
+		if (!resolved) continue;
+
+		rewritten += source.slice(lastIndex, matchIndex);
+		// Forward slashes keep Windows paths valid inside single- or double-quoted literals.
+		rewritten += `${prefix}${stripWindowsExtendedLengthPathPrefix(resolved).replaceAll("\\", "/")}${suffix}`;
+		lastIndex = matchIndex + fullMatch.length;
+	}
+
+	if (lastIndex === 0) {
+		return source;
+	}
+	return `${rewritten}${source.slice(lastIndex)}`;
+}
+
+/**
+ * Whether a module's source contains a bare require that resolves to a native
+ * `.node` addon — i.e. a napi-rs style loader that must be hooked into the
+ * extension graph so {@link rewriteExtensionNativeAddonRequires} can pin its
+ * platform-package requires to absolute paths.
+ */
+async function moduleRequiresNativeAddon(modulePath: string): Promise<boolean> {
+	const cached = nativeAddonRequireScanCache.get(modulePath);
+	if (cached) return cached;
+
+	const promise = moduleRequiresNativeAddonUncached(modulePath);
+	nativeAddonRequireScanCache.set(modulePath, promise);
+	return promise;
+}
+
+async function moduleRequiresNativeAddonUncached(modulePath: string): Promise<boolean> {
+	let source: string;
+	try {
+		source = await Bun.file(modulePath).text();
+	} catch {
+		return false;
+	}
+	for (const match of source.matchAll(NATIVE_ADDON_REQUIRE_SPECIFIER_REGEX)) {
+		const specifier = match[2];
+		if (specifier && (await resolveExtensionNativeAddon(specifier, modulePath))) {
+			return true;
+		}
+	}
+	return false;
+}
+
 async function rewriteExtensionBareImports(
 	source: string,
 	importerPath: string,
@@ -986,7 +1092,9 @@ function escapeRegExp(value: string): string {
 // `imports` aliases such as `#src/*`, and extension-local bare dependency
 // entries. Bare imports inside node_modules dependencies remain native Bun
 // resolutions; once the dependency entry is hooked, its relative children are
-// still collected and rewritten with the reload mtime tag.
+// still collected and rewritten with the reload mtime tag. `require()` calls
+// are scanned too so CJS entries and napi-rs loaders reached without an
+// import statement still join the graph.
 const EXTENSION_GRAPH_SPECIFIER_REGEX = /((?:from\s+|import\s+|import\s*\(\s*)["'])([^"'()\s]+)(["'])/g;
 
 // Extension source realpaths already covered by an installed load-time hook for
@@ -1027,6 +1135,10 @@ async function realpathOrSelfUncached(p: string): Promise<string> {
  * Extension-local bare dependency entries are also included so their relative
  * children receive the reload mtime tag; bare imports inside those dependencies
  * remain native Bun resolutions to avoid taking over full third-party graphs.
+ * CommonJS dependency entries stay native too, with one exception: napi-rs
+ * style loaders whose bare requires resolve to `.node` addons are hooked so
+ * their requires can be pinned to absolute paths (unresolvable by bare
+ * specifier inside `bun build --compile` binaries).
  */
 async function collectExtensionModules(entryRealPath: string): Promise<Map<string, string>> {
 	const modules = new Map<string, string>();
@@ -1047,14 +1159,24 @@ async function collectExtensionModules(entryRealPath: string): Promise<Map<strin
 		let source: string;
 		try {
 			source = await Bun.file(file).text();
+			if (nativeAddonLoaderModulePaths.has(file)) {
+				// CJS requires cannot await an async onLoad hook. Resolve and
+				// rewrite native-addon paths before installing its sync hook.
+				source = await rewriteExtensionNativeAddonRequires(source, file);
+			}
 		} catch {
 			continue;
 		}
 		modules.set(file, source);
 		const dir = path.dirname(file);
+		const specifiers = new Set<string>();
 		for (const match of source.matchAll(EXTENSION_GRAPH_SPECIFIER_REGEX)) {
-			const specifier = match[2];
-			if (!specifier) continue;
+			if (match[2]) specifiers.add(match[2]);
+		}
+		for (const match of source.matchAll(NATIVE_ADDON_REQUIRE_SPECIFIER_REGEX)) {
+			if (match[2]) specifiers.add(match[2]);
+		}
+		for (const specifier of specifiers) {
 			try {
 				let resolved: string | null = null;
 				let nextFollowsBareDependencies = followBareDependencies;
@@ -1079,10 +1201,17 @@ async function collectExtensionModules(entryRealPath: string): Promise<Map<strin
 						dependencyExtension === ".cjs" ||
 						dependencyExtension === ".cts" ||
 						((dependencyExtension === ".js" || dependencyExtension === ".jsx") && manifest?.type !== "module");
-					resolved =
-						dependencyEntry && hasSourceModuleExtension(dependencyEntry) && !isCommonJsEntry
-							? await realpathOrSelf(dependencyEntry)
-							: null;
+					const isHookableEntry = Boolean(dependencyEntry && hasSourceModuleExtension(dependencyEntry));
+					const hookCommonJsEntry =
+						isHookableEntry && isCommonJsEntry && dependencyEntry
+							? await moduleRequiresNativeAddon(dependencyEntry)
+							: false;
+					if (isHookableEntry && dependencyEntry && (!isCommonJsEntry || hookCommonJsEntry)) {
+						resolved = await realpathOrSelf(dependencyEntry);
+						if (hookCommonJsEntry) {
+							nativeAddonLoaderModulePaths.add(resolved);
+						}
+					}
 					nextFollowsBareDependencies = false;
 				}
 				if (resolved && !modules.has(resolved)) {
@@ -1100,39 +1229,71 @@ async function collectExtensionModules(entryRealPath: string): Promise<Map<strin
 }
 
 /**
- * Install a `Bun.plugin()` `onLoad` hook scoped to a set of extension-owned
- * source modules. Runtime `onLoad` cannot fall through (Bun requires a result
- * object), so every hook uses an exact-path alternation for modules known to be
- * part of this entry's graph; reloads add supplemental hooks for newly
- * discovered modules instead of widening an existing filter to unrelated files.
+ * Install exact-path load hooks for the current extension graph. ESM/TS source
+ * retains the async rewrite path. Native-addon CJS loaders use a synchronous
+ * hook with source pre-rewritten during graph collection; Bun rejects a CJS
+ * `require()` whose onLoad callback returns a promise.
  */
-function installExtensionGraphHook(entryRealPath: string, modules: Map<string, string>): void {
-	const alternation = [...modules.keys()].map(escapeRegExp).join("|");
-	const filter = new RegExp(`^(?:${alternation})(?:\\?mtime=\\d+)?$`);
-	const hookId = Bun.hash(`${entryRealPath}\0${[...modules.keys()].join("\0")}`).toString(36);
-	Bun.plugin({
-		name: `omp:legacy-pi-ext:${hookId}`,
-		setup(build) {
-			build.onLoad({ filter, namespace: "file" }, async args => {
-				const queryIndex = args.path.indexOf("?mtime=");
-				const sourcePath = queryIndex >= 0 ? args.path.slice(0, queryIndex) : args.path;
-				const mtimeTag = queryIndex >= 0 ? args.path.slice(queryIndex + "?mtime=".length) : null;
-				const cached = modules.get(sourcePath);
-				let raw: string;
-				if (cached !== undefined) {
-					// consume-once: preserves ?mtime edit-pickup for the re-imported entry
-					modules.delete(sourcePath);
-					raw = cached;
-				} else {
-					raw = await Bun.file(sourcePath).text();
-				}
-				return {
-					contents: await rewriteLegacyExtensionSource(raw, sourcePath, mtimeTag),
-					loader: getLoader(sourcePath),
-				};
-			});
-		},
-	});
+function installExtensionGraphHook(
+	entryRealPath: string,
+	modules: Map<string, string>,
+): { asyncModules: Map<string, string>; syncCommonJsModules: Map<string, string> } {
+	const asyncModules = new Map<string, string>();
+	const syncCommonJsModules = new Map<string, string>();
+	for (const [modulePath, source] of modules) {
+		const destination = nativeAddonLoaderModulePaths.has(modulePath) ? syncCommonJsModules : asyncModules;
+		destination.set(modulePath, source);
+	}
+
+	if (asyncModules.size > 0) {
+		const alternation = [...asyncModules.keys()].map(escapeRegExp).join("|");
+		const filter = new RegExp(`^(?:${alternation})(?:\\?mtime=\\d+)?$`);
+		const hookId = Bun.hash(`${entryRealPath}\0async\0${[...asyncModules.keys()].join("\0")}`).toString(36);
+		Bun.plugin({
+			name: `omp:legacy-pi-ext:${hookId}`,
+			setup(build) {
+				build.onLoad({ filter, namespace: "file" }, async args => {
+					const queryIndex = args.path.indexOf("?mtime=");
+					const sourcePath = queryIndex >= 0 ? args.path.slice(0, queryIndex) : args.path;
+					const mtimeTag = queryIndex >= 0 ? args.path.slice(queryIndex + "?mtime=".length) : null;
+					const cached = asyncModules.get(sourcePath);
+					let raw: string;
+					if (cached !== undefined) {
+						// consume-once: preserves ?mtime edit-pickup for re-imports
+						asyncModules.delete(sourcePath);
+						raw = cached;
+					} else {
+						raw = await Bun.file(sourcePath).text();
+					}
+					return {
+						contents: await rewriteLegacyExtensionSource(raw, sourcePath, mtimeTag),
+						loader: getLoader(sourcePath),
+					};
+				});
+			},
+		});
+	}
+
+	if (syncCommonJsModules.size > 0) {
+		const alternation = [...syncCommonJsModules.keys()].map(escapeRegExp).join("|");
+		const filter = new RegExp(`^(?:${alternation})(?:\\?mtime=\\d+)?$`);
+		const hookId = Bun.hash(`${entryRealPath}\0sync-cjs\0${[...syncCommonJsModules.keys()].join("\0")}`).toString(36);
+		Bun.plugin({
+			name: `omp:legacy-pi-ext:${hookId}`,
+			setup(build) {
+				build.onLoad({ filter, namespace: "file" }, args => {
+					const queryIndex = args.path.indexOf("?mtime=");
+					const sourcePath = queryIndex >= 0 ? args.path.slice(0, queryIndex) : args.path;
+					const source = syncCommonJsModules.get(sourcePath);
+					if (source === undefined) {
+						throw new Error(`Missing pre-rewritten CommonJS extension source: ${sourcePath}`);
+					}
+					return { contents: source, loader: getLoader(sourcePath) };
+				});
+			},
+		});
+	}
+	return { asyncModules, syncCommonJsModules };
 }
 
 /**
@@ -1140,10 +1301,10 @@ function installExtensionGraphHook(entryRealPath: string, modules: Map<string, s
  * rewrite hook. The entry graph can grow across reloads, so each call collects
  * the current graph and registers hooks for paths not covered by earlier loads.
  *
- * Returns the newly collected path→source map so the caller can drop entries
- * the import never consumed; `undefined` when no new modules were discovered.
+ * Returns a clearable handle to drop cached sources that weren't consumed
+ * during the initial load; `undefined` when no new modules were discovered.
  */
-async function ensureExtensionGraphHook(entryRealPath: string): Promise<Map<string, string> | undefined> {
+async function ensureExtensionGraphHook(entryRealPath: string): Promise<{ clear(): void } | undefined> {
 	const currentModules = await collectExtensionModules(entryRealPath);
 	let hookedModules = extensionGraphHookModules.get(entryRealPath);
 	if (!hookedModules) {
@@ -1161,11 +1322,16 @@ async function ensureExtensionGraphHook(entryRealPath: string): Promise<Map<stri
 		return undefined;
 	}
 
-	installExtensionGraphHook(entryRealPath, pendingModules);
+	const { asyncModules, syncCommonJsModules } = installExtensionGraphHook(entryRealPath, pendingModules);
 	for (const modulePath of pendingModules.keys()) {
 		hookedModules.add(modulePath);
 	}
-	return pendingModules;
+	return {
+		clear() {
+			asyncModules.clear();
+			syncCommonJsModules.clear();
+		},
+	};
 }
 
 /**
@@ -1184,6 +1350,7 @@ export async function loadLegacyPiModule(resolvedPath: string): Promise<unknown>
 	// `bun link`/pnpm installs) so the rewrite filter matches the path Bun
 	// actually hands the hook.
 	const entryRealPath = await realpathOrSelf(path.resolve(resolvedPath));
+	await ensureLegacyPiOverridesReady();
 	const pendingSources = await ensureExtensionGraphHook(entryRealPath);
 	try {
 		// Dynamic import is required: legacy extension entry paths are user/plugin supplied at runtime.
@@ -1261,9 +1428,8 @@ export function installLegacyPiSpecifierShim(): void {
 		setup(build) {
 			build.onResolve({ filter: LEGACY_PI_SPECIFIER_FILTER, namespace: "file" }, resolveLegacyPiSpecifier);
 			build.onResolve({ filter: TYPEBOX_SPECIFIER_FILTER, namespace: "file" }, resolveTypeBoxSpecifier);
-			// Compiled-binary mode: serve `omp-legacy-pi-bundled:<key>` imports
-			// from the JS-heap registry. The rewrite path emits these specifiers
-			// in place of unreachable `file:///$bunfs/...` URLs (issue #3423).
+			// Compiled mode serves `omp-legacy-pi-bundled:<key>` imports from
+			// live host module references. No bunfs path leaves this loader.
 			build.onLoad({ filter: /.*/, namespace: BUNDLED_VIRTUAL_NAMESPACE }, async args => {
 				return { contents: await synthesizeBundledModuleSource(args.path), loader: "js" };
 			});