@oh-my-pi/pi-coding-agent 16.1.17 → 16.1.19

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

@@ -2,9 +2,148 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as url from "node:url";
 import { isCompiledBinary } from "@oh-my-pi/pi-utils";
+import { BUNDLED_PI_REGISTRY_KEYS } from "./legacy-pi-bundled-keys";
 
 const IS_COMPILED_BINARY = isCompiledBinary();
 
+// === Bundled host-package registry (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.
+//
+// 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.
+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";
+
+type BundledRegistry = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+
+let bundledRegistryPromise: Promise<BundledRegistry> | 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.
+ *
+ * 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.
+ */
+function ensureBundledRegistryLoaded(): Promise<BundledRegistry> {
+	if (!IS_COMPILED_BINARY) {
+		return Promise.reject(
+			new Error("omp:legacy-pi-shim: bundled registry is only available in compiled-binary 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;
+		});
+	}
+	return bundledRegistryPromise;
+}
+
+function bundledRegistryVirtualSpecifier(registryKey: string): string {
+	return `${BUNDLED_VIRTUAL_SCHEME}${registryKey}`;
+}
+
+function isBundledVirtualSpecifier(value: string): boolean {
+	return value.startsWith(BUNDLED_VIRTUAL_SCHEME);
+}
+
+/**
+ * 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.
+ */
+function synthesizeBundledModuleSourceFromRegistry(registryKey: string, registry: BundledRegistry): string {
+	const mod = registry[registryKey];
+	if (!mod) {
+		throw new Error(`omp:legacy-pi-shim: no bundled module registered for ${registryKey}`);
+	}
+	const lines: string[] = [
+		`const __omp_bundled = globalThis[${JSON.stringify(BUNDLED_REGISTRY_GLOBAL)}][${JSON.stringify(registryKey)}];`,
+	];
+	let hasDefault = false;
+	for (const exportName in mod) {
+		if (exportName === "default") {
+			hasDefault = true;
+			continue;
+		}
+		lines.push(`export const ${exportName} = __omp_bundled[${JSON.stringify(exportName)}];`);
+	}
+	if (hasDefault) {
+		lines.push("export default __omp_bundled.default;");
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+
+/**
+ * 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.
+ */
+async function synthesizeBundledModuleSource(registryKey: string): Promise<string> {
+	const registry = await ensureBundledRegistryLoaded();
+	return synthesizeBundledModuleSourceFromRegistry(registryKey, registry);
+}
+
+/**
+ * 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>>>>,
+): string {
+	return synthesizeBundledModuleSourceFromRegistry(registryKey, registry);
+}
+
+/**
+ * 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;
+}
+
 // Canonical scope for in-process pi packages. Plugins published against any of
 // the aliased scopes below (mariozechner's original publish, earendil-works'
 // fork, or the canonical @oh-my-pi scope itself) are remapped to this scope and
@@ -73,57 +212,14 @@ const PACKAGE_IMPORT_EXCLUDED = Symbol("packageImportExcluded");
 // not provide and plugins relying on them must vendor TypeBox directly.
 const TYPEBOX_SPECIFIER_FILTER = /^(?:@sinclair\/typebox|typebox)$/;
 
-// Compat shim and bundled-package paths used in compiled-binary mode. The shim
-// paths must point at files that ship inside the bunfs root; in dev /
-// source-link / installed-package mode the canonical specifier resolves via
-// `Bun.resolveSync` so only the shim files need explicit paths there.
-//
-// `BUNFS_PACKAGE_ROOT` is derived from `import.meta.dir` rather than hardcoded
-// as `/$bunfs/root/packages` so the prefix stays platform-native: on Windows
-// the bunfs mount appears as `<drive>:\~BUN\root\…` (see oven-sh/bun#15766),
-// and a hardcoded POSIX literal would normalize to `\$bunfs\root\…` and fail
-// to resolve. Compiled Bun modules currently report the bunfs root itself from
-// `import.meta.dir`, so appending `packages` lands on the `--root ../..`
-// package directory used by `scripts/build-binary.ts`.
-//
-// Every shim listed below must also be registered as an explicit `--compile`
-// entrypoint in `scripts/build-binary.ts` or release builds fail with
-// missing-module errors. Non-shim bundled packages are resolved via
-// `Bun.resolveSync` (see `resolveCanonicalPiSpecifier`) outside compiled mode,
-// so they keep working when on-disk layout differs from the monorepo tree.
-/**
- * Compute the bunfs package root from the compiled binary's `import.meta.dir`
- * (or any stand-in supplied by tests). Bun compiled binaries report one of:
- *
- * - the bunfs mount root itself — `/$bunfs/root` or `<drive>:\~BUN\root` (Bun
- *   1.2.x and early 1.3.x). Append `packages` for the canonical layout.
- * - the bunfs mount root followed by the binary's basename — `//root/<bin>`
- *   on POSIX or `<drive>:\~BUN\root\<bin>.exe` on Windows (observed on Bun
- *   1.3.14 with the cross-compiled `omp-darwin-arm64` release asset — issue
- *   #3329). The trailing segment is stripped so the result still lands on
- *   `<root>/packages`.
- * - the module's own source directory if a future Bun release switches to
- *   module-specific `import.meta.dir` values:
- *   `<bunfs>/packages/coding-agent/src/extensibility/plugins`.
- * The bunfs-root-with-binary branch slices the original `metaDir`, and
- * `bunfsPath` uses a matching double-slash-preserving join, so the bunfs-native
- * prefix is preserved verbatim — `path.posix.join` collapses `//root` to
- * `/root`, but Bun's bunfs lookup is keyed on the exact `//root` form.
- *
- * Exported for tests; production callers use `BUNFS_PACKAGE_ROOT` below.
- */
-export function __computeBunfsPackageRoot(metaDir: string, pathImpl: typeof path = path): string {
-	const pluginsDirSuffix = pathImpl.join("packages", "coding-agent", "src", "extensibility", "plugins");
-	const normalizedMetaDir = pathImpl.normalize(metaDir);
-	if (normalizedMetaDir.endsWith(pluginsDirSuffix)) {
-		return pathImpl.resolve(metaDir, "..", "..", "..", "..");
-	}
-	const parent = pathImpl.dirname(metaDir);
-	if (pathImpl.basename(pathImpl.normalize(parent)) === "root") {
-		return `${parent + pathImpl.sep}packages`;
-	}
-	return pathImpl.join(metaDir, "packages");
-}
+// 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
+// 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
+// `sourceShimPath` computes either from the npm prebuilt `dist/cli.js`
+// bundle (`PI_BUNDLED=true`) or directly from the monorepo source tree.
 
 /**
  * Compute the package root for the npm prebuilt `dist/cli.js` bundle.
@@ -147,35 +243,6 @@ export function __computeBundledSelfPackageRoot(metaDir: string, pathImpl: typeo
 	return pathImpl.resolve(metaDir);
 }
 
-const BUNFS_PACKAGE_ROOT = IS_COMPILED_BINARY ? __computeBunfsPackageRoot(import.meta.dir) : null;
-
-/**
- * Join a computed bunfs package root with descendants without collapsing
- * Bun's POSIX `//root` mount prefix.
- *
- * Exported for tests; production callers use `bunfsPath` below.
- */
-export function __joinBunfsPath(root: string, segments: readonly string[], pathImpl: typeof path = path): string {
-	const joined = pathImpl.join(root, ...segments);
-	const doubleRootPrefix = pathImpl.sep + pathImpl.sep;
-	const tripleRootPrefix = doubleRootPrefix + pathImpl.sep;
-	if (
-		root.startsWith(doubleRootPrefix) &&
-		!root.startsWith(tripleRootPrefix) &&
-		!joined.startsWith(doubleRootPrefix)
-	) {
-		return pathImpl.sep + joined;
-	}
-	return joined;
-}
-
-function bunfsPath(...segments: string[]): string {
-	if (!BUNFS_PACKAGE_ROOT) {
-		throw new Error("bunfsPath is only valid in compiled-binary mode");
-	}
-	return __joinBunfsPath(BUNFS_PACKAGE_ROOT, segments);
-}
-
 function resolveBundledSelfPackageRoot(): string | undefined {
 	if (!process.env.PI_BUNDLED) return undefined;
 	return __computeBundledSelfPackageRoot(import.meta.dir);
@@ -189,9 +256,36 @@ function sourceShimPath(file: string): string {
 		: path.resolve(import.meta.dir, "..", file);
 }
 
-const TYPEBOX_SHIM_PATH = BUNFS_PACKAGE_ROOT
-	? bunfsPath("coding-agent", "src", "extensibility", "typebox.js")
-	: sourceShimPath("typebox.ts");
+/**
+ * Resolve the path the TypeBox compatibility shim ships at, then drop it when
+ * the source file is missing.
+ *
+ * In compiled-binary mode the shim is served through the
+ * `omp-legacy-pi-bundled:` virtual namespace (issue #3423) — bunfs paths are
+ * unreachable on Bun 1.3.14+, so the virtual specifier is always available and
+ * needs no filesystem probe. In dev / source-link / installed-package mode the
+ * shim is an on-disk source file; validation mirrors
+ * `__validateLegacyPiPackageRootOverrides` (#2168): if the computed candidate
+ * doesn't exist (e.g. an install that dropped the source — issue #3414),
+ * `resolveTypeBoxSpecifier` returns `undefined` and
+ * `rewriteLegacyExtensionSource` leaves bare `typebox` / `@sinclair/typebox`
+ * specifiers alone, so Bun falls through to native resolution against the
+ * extension's own `node_modules`.
+ *
+ * Exported for tests; production callers use `TYPEBOX_SHIM_PATH`.
+ */
+export function __resolveTypeBoxShimPath(
+	isCompiled: boolean,
+	sourcePath: string,
+	pathExistsSync: (p: string) => boolean = fs.existsSync,
+): string | null {
+	if (isCompiled) {
+		return bundledRegistryVirtualSpecifier(TYPEBOX_BUNDLED_REGISTRY_KEY);
+	}
+	return pathExistsSync(sourcePath) ? sourcePath : null;
+}
+
+const TYPEBOX_SHIM_PATH = __resolveTypeBoxShimPath(IS_COMPILED_BINARY, sourceShimPath("typebox.ts"));
 
 // Legacy extensions historically imported `Type` (and `Static`/`TSchema`) from
 // the package root of `@(scope)/pi-ai`. pi-ai 15.1.0 removed the runtime `Type`
@@ -201,62 +295,84 @@ const TYPEBOX_SHIM_PATH = BUNFS_PACKAGE_ROOT
 // plus the borrowed `Type` runtime from the Zod-backed TypeBox shim. Subpath
 // 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 = BUNFS_PACKAGE_ROOT
-	? bunfsPath("coding-agent", "src", "extensibility", "legacy-pi-ai-shim.js")
+const LEGACY_PI_AI_SHIM_PATH = IS_COMPILED_BINARY
+	? bundledRegistryVirtualSpecifier(`${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). Legacy `@(scope)/pi-coding-agent` root
-// imports therefore resolve through a sibling shim whose distinct file path
-// avoids that collision while re-exporting the canonical package surface.
-const LEGACY_PI_CODING_AGENT_SHIM_PATH = BUNFS_PACKAGE_ROOT
-	? bunfsPath("coding-agent", "src", "extensibility", "legacy-pi-coding-agent-shim.js")
+// 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
+// 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`)
 	: sourceShimPath("legacy-pi-coding-agent-shim.ts");
 
-// Package-root overrides. Shim entries are always applied because they replace
-// (or augment) the canonical surface even in non-compiled installs. The bunfs
-// entries are added only in compiled-binary mode — in dev / source-link /
-// installed-package mode the canonical specifier resolves cleanly through
-// `Bun.resolveSync`, and hardcoding a relative source-tree path would break
-// installs where the bundled packages live at `node_modules/@oh-my-pi/pi-*`
-// rather than `packages/*`.
+// Package-root overrides. Shim entries (`pi-ai`, `pi-coding-agent`) always
+// replace the canonical surface so the legacy `Type` runtime and the legacy
+// helpers stay reachable. The bundled host packages (`pi-agent-core`,
+// `pi-natives`, `pi-tui`, `pi-utils`) are added only in compiled-binary mode
+// to route extensions onto the in-process module instance — in dev /
+// source-link / installed-package mode the canonical specifier resolves
+// cleanly through `Bun.resolveSync` and hardcoding a source-tree path would
+// miss installs where the bundled packages live at `node_modules/@oh-my-pi/pi-*`.
 //
-// Every override target is validated against the on-disk filesystem at module
-// init: any entry whose file is missing (e.g. a compiled binary where Bun's
-// `--compile` quietly dropped an additional entrypoint — issue #2168) is left
-// out so `resolveCanonicalPiSpecifier` falls through to `getResolvedSpecifier`,
-// which throws under bunfs and triggers the catch in `rewriteLegacyPiImports`.
-// That catch leaves the specifier untouched so Bun resolves the canonical
-// `@oh-my-pi/pi-*` import from the extension's own `node_modules` instead of
-// emitting a bunfs `file://` URL to a module that isn't actually present.
+// Compiled-binary entries are `omp-legacy-pi-bundled:<key>` specifiers handed
+// to the synthetic onLoad in `installLegacyPiSpecifierShim()` — bunfs paths
+// are unusable on Bun 1.3.14+ (issue #3423). Filesystem-shaped overrides are
+// still validated against on-disk presence so a missing dev-mode shim falls
+// through to `getResolvedSpecifier`.
 
 /**
- * Drop overrides whose targets are missing on disk so they can fall through to
- * the canonical-resolution path. Exported for the test seam in #2168.
+ * 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).
  *
- * `pathExistsSync` defaults to `fs.existsSync`; the tests inject a stub to
+ * `pathExistsSync` defaults to `fs.existsSync`; tests inject a stub to
  * simulate the missing-entrypoint failure mode without touching the real FS.
  */
 export function __validateLegacyPiPackageRootOverrides(
 	candidates: Record<string, string>,
 	pathExistsSync: (p: string) => boolean = fs.existsSync,
 ): Record<string, string> {
-	return Object.fromEntries(Object.entries(candidates).filter(([, candidate]) => pathExistsSync(candidate)));
-}
-
-const LEGACY_PI_PACKAGE_ROOT_OVERRIDES = __validateLegacyPiPackageRootOverrides({
-	[`${CANONICAL_PI_SCOPE}/pi-ai`]: LEGACY_PI_AI_SHIM_PATH,
-	[`${CANONICAL_PI_SCOPE}/pi-coding-agent`]: LEGACY_PI_CODING_AGENT_SHIM_PATH,
-	...(BUNFS_PACKAGE_ROOT
-		? {
-				[`${CANONICAL_PI_SCOPE}/pi-agent-core`]: bunfsPath("agent", "src", "index.js"),
-				[`${CANONICAL_PI_SCOPE}/pi-natives`]: bunfsPath("natives", "native", "index.js"),
-				[`${CANONICAL_PI_SCOPE}/pi-tui`]: bunfsPath("tui", "src", "index.js"),
-				[`${CANONICAL_PI_SCOPE}/pi-utils`]: bunfsPath("utils", "src", "index.js"),
-			}
-		: {}),
-});
+	return Object.fromEntries(
+		Object.entries(candidates).filter(
+			([, candidate]) => isBundledVirtualSpecifier(candidate) || pathExistsSync(candidate),
+		),
+	);
+}
+
+/**
+ * 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.
+ */
+export function __buildLegacyPiPackageRootOverrides(isCompiled: boolean): 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);
+		}
+	}
+	return __validateLegacyPiPackageRootOverrides(candidates);
+}
+
+const LEGACY_PI_PACKAGE_ROOT_OVERRIDES = __buildLegacyPiPackageRootOverrides(IS_COMPILED_BINARY);
 
 let isLegacyPiSpecifierShimInstalled = false;
 
@@ -302,6 +418,12 @@ 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.
+	if (isBundledVirtualSpecifier(resolvedPath)) {
+		return resolvedPath;
+	}
 	return url.pathToFileURL(resolvedPath).href;
 }
 
@@ -341,12 +463,17 @@ const TYPEBOX_IMPORT_SPECIFIER_REGEX = /((?:from\s+|import\s+|import\s*\(\s*)["'
  */
 async function rewriteLegacyExtensionSource(source: string, importerPath: string): Promise<string> {
 	const withPi = rewriteLegacyPiImports(source);
-	const withTypeBox = withPi.replace(
-		TYPEBOX_IMPORT_SPECIFIER_REGEX,
-		(_match, prefix: string, _specifier: string, suffix: string) => {
-			return `${prefix}${toImportSpecifier(TYPEBOX_SHIM_PATH)}${suffix}`;
-		},
-	);
+	// When the TypeBox shim is missing (release build dropped the entrypoint —
+	// issue #3414), leave bare specifiers untouched so Bun resolves a real
+	// `typebox` / `@sinclair/typebox` install from the extension's own
+	// `node_modules`. `resolveTypeBoxSpecifier` mirrors the fall-through.
+	const withTypeBox = TYPEBOX_SHIM_PATH
+		? withPi.replace(
+				TYPEBOX_IMPORT_SPECIFIER_REGEX,
+				(_match, prefix: string, _specifier: string, suffix: string) =>
+					`${prefix}${toImportSpecifier(TYPEBOX_SHIM_PATH)}${suffix}`,
+			)
+		: withPi;
 	return rewriteExtensionPackageImports(withTypeBox, importerPath);
 }
 
@@ -719,8 +846,8 @@ function resolveLegacyPiSpecifier(args: { path: string; importer: string }): { p
 	}
 }
 
-function resolveTypeBoxSpecifier(): { path: string } {
-	return { path: TYPEBOX_SHIM_PATH };
+function resolveTypeBoxSpecifier(): { path: string } | undefined {
+	return TYPEBOX_SHIM_PATH ? { path: TYPEBOX_SHIM_PATH } : undefined;
 }
 
 export function installLegacyPiSpecifierShim(): void {
@@ -734,6 +861,12 @@ 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).
+			build.onLoad({ filter: /.*/, namespace: BUNDLED_VIRTUAL_NAMESPACE }, async args => {
+				return { contents: await synthesizeBundledModuleSource(args.path), loader: "js" };
+			});
 		},
 	});
 }

package/src/internal-urls/local-protocol.ts

@@ -49,6 +49,121 @@ function getContentType(filePath: string): InternalResource["contentType"] {
 	return "text/plain";
 }
 
+const LOCAL_TEXT_SNIFF_BYTES = 8 * 1024;
+const LOCAL_TEXT_RESOURCE_MAX_BYTES = 1024 * 1024;
+const BINARY_FILE_EXTENSIONS = new Set([
+	".7z",
+	".avi",
+	".bmp",
+	".bz2",
+	".db",
+	".doc",
+	".docx",
+	".gif",
+	".gz",
+	".ico",
+	".jpeg",
+	".jpg",
+	".m4v",
+	".mkv",
+	".mov",
+	".mp4",
+	".pdf",
+	".png",
+	".ppt",
+	".pptx",
+	".rar",
+	".sqlite",
+	".tgz",
+	".webm",
+	".webp",
+	".wmv",
+	".xls",
+	".xlsx",
+	".xz",
+	".zip",
+]);
+
+function formatLocalByteSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const kib = bytes / 1024;
+	if (kib < 1024) return `${kib.toFixed(1)} KiB`;
+	const mib = kib / 1024;
+	if (mib < 1024) return `${mib.toFixed(1)} MiB`;
+	return `${(mib / 1024).toFixed(1)} GiB`;
+}
+
+function buildNonTextLocalResource(url: InternalUrl, filePath: string, size: number, reason: string): InternalResource {
+	const content = `[Cannot read binary local:// file '${url.href}' (${formatLocalByteSize(size)}): ${reason}. This resource is not text. Use a metadata/key-frame/video-specific workflow instead.]`;
+	return {
+		url: url.href,
+		content,
+		contentType: "text/plain",
+		size: Buffer.byteLength(content, "utf-8"),
+		sourcePath: filePath,
+		notes: [LOCAL_WRITE_NOTE],
+	};
+}
+
+function buildLargeLocalTextResource(url: InternalUrl, filePath: string, size: number): InternalResource {
+	const content = `[Cannot materialize local:// file '${url.href}' as an internal text resource (${formatLocalByteSize(size)} exceeds ${formatLocalByteSize(LOCAL_TEXT_RESOURCE_MAX_BYTES)}). Use the read tool's filesystem path handling or a line selector so content is streamed with file-size safeguards.]`;
+	return {
+		url: url.href,
+		content,
+		contentType: "text/plain",
+		size: Buffer.byteLength(content, "utf-8"),
+		sourcePath: filePath,
+		notes: [LOCAL_WRITE_NOTE],
+	};
+}
+
+async function readFilePrefix(filePath: string, maxBytes: number): Promise<Uint8Array> {
+	if (maxBytes <= 0) return new Uint8Array();
+	const handle = await fs.open(filePath, "r");
+	try {
+		const buffer = Buffer.allocUnsafe(maxBytes);
+		const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+		return buffer.subarray(0, bytesRead);
+	} finally {
+		await handle.close();
+	}
+}
+
+function isUtf8Text(bytes: Uint8Array): boolean {
+	if (bytes.indexOf(0) !== -1) return false;
+	try {
+		new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function buildFileResource(
+	url: InternalUrl,
+	resolved: Extract<ResolvedLocalTarget, { kind: "file" }>,
+): Promise<InternalResource> {
+	if (BINARY_FILE_EXTENSIONS.has(path.extname(resolved.path).toLowerCase())) {
+		return buildNonTextLocalResource(url, resolved.path, resolved.size, "extension is a known binary/container type");
+	}
+	const sniffBytes = await readFilePrefix(resolved.path, Math.min(resolved.size, LOCAL_TEXT_SNIFF_BYTES));
+	if (!isUtf8Text(sniffBytes)) {
+		return buildNonTextLocalResource(url, resolved.path, resolved.size, "content is not valid UTF-8 text");
+	}
+	if (resolved.size > LOCAL_TEXT_RESOURCE_MAX_BYTES) {
+		return buildLargeLocalTextResource(url, resolved.path, resolved.size);
+	}
+	const content = await Bun.file(resolved.path).text();
+	return {
+		url: url.href,
+		content,
+		contentType: getContentType(resolved.path),
+		size: Buffer.byteLength(content, "utf-8"),
+		sourcePath: resolved.path,
+		notes: [LOCAL_WRITE_NOTE],
+	};
+}
+
 async function listFilesRecursively(rootPath: string): Promise<string[]> {
 	const pending = [""];
 	const files: string[] = [];
@@ -336,15 +451,7 @@ export class LocalProtocolHandler implements ProtocolHandler {
 			return buildDirectoryResource(url.href, resolved.path, [LOCAL_WRITE_NOTE]);
 		}
 
-		const content = await Bun.file(resolved.path).text();
-		return {
-			url: url.href,
-			content,
-			contentType: getContentType(resolved.path),
-			size: Buffer.byteLength(content, "utf-8"),
-			sourcePath: resolved.path,
-			notes: [LOCAL_WRITE_NOTE],
-		};
+		return buildFileResource(url, resolved);
 	}
 
 	async complete(_query?: string, context?: ResolveContext): Promise<UrlCompletion[]> {

package/src/internal-urls/skill-protocol.ts

@@ -13,7 +13,7 @@ import * as path from "node:path";
 import { isEnoent } from "@oh-my-pi/pi-utils";
 import { getActiveSkills } from "../extensibility/skills";
 import { buildDirectoryResource } from "./filesystem-resource";
-import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion } from "./types";
 
 function getContentType(filePath: string): InternalResource["contentType"] {
 	const ext = path.extname(filePath).toLowerCase();
@@ -42,8 +42,8 @@ export class SkillProtocolHandler implements ProtocolHandler {
 	readonly scheme = "skill";
 	readonly immutable = true;
 
-	async resolve(url: InternalUrl): Promise<InternalResource> {
-		const skills = getActiveSkills();
+	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
+		const skills = context?.skills ?? getActiveSkills();
 
 		const skillName = url.rawHost || url.hostname;
 		if (!skillName) {

package/src/internal-urls/types.ts

@@ -5,6 +5,7 @@
  * providing access to agent outputs and server resources without exposing filesystem paths.
  */
 
+import type { Skill } from "../extensibility/skills";
 import type { LocalProtocolOptions } from "./local-protocol";
 
 /**
@@ -90,6 +91,8 @@ export interface ResolveContext {
 	 * [#1608](https://github.com/can1357/oh-my-pi/issues/1608).
 	 */
 	localProtocolOptions?: LocalProtocolOptions;
+	/** Calling session's loaded skills. Prefer this over process-global skill state. */
+	skills?: readonly Skill[];
 }
 
 /**