@moxxy/core 0.5.0 → 0.5.1

package/src/permissions/engine.ts

@@ -46,6 +46,49 @@ export type PermissionPolicy = z.infer<typeof permissionPolicySchema>;
 
 const emptyPolicy: PermissionPolicy = { allow: [], deny: [] };
 
+/**
+ * Upper bound on the candidate string a policy regex is tested against. The
+ * permission check sits on the synchronous critical path of EVERY tool call and
+ * runs author-supplied `inputMatches` patterns over MODEL-controlled tool input
+ * (the model proposes the call). A pathological pattern (e.g. `(a+)+$`) over a
+ * long model-supplied string can pin the event loop (ReDoS). No legitimate
+ * permission match needs more than a few KB, so we truncate the candidate first
+ * — bounding the worst-case backtracking work to a fixed input size. Truncation
+ * only affects matches that depend on content past 8 KB, which a permission
+ * pattern should never rely on.
+ */
+const MAX_MATCH_INPUT = 8192;
+
+/**
+ * Bounded cache of compiled regexes keyed by source string. `check()` walks every
+ * rule per tool call and the patterns never change between mutations, so without
+ * a cache a policy with N pattern rules recompiles N `RegExp`s on every one of M
+ * tool calls. Caching keeps `.test` the only per-call work. A `null` value
+ * memoizes an UNCOMPILABLE source so we don't re-throw on every check (the
+ * stderr warning is still emitted per check by the caller, preserving the
+ * documented fail-open/closed surfacing). Bounded to cap memory if a policy ever
+ * carries an unbounded set of distinct patterns; eviction just recompiles.
+ */
+const MAX_REGEX_CACHE = 512;
+const regexCache = new Map<string, RegExp | null>();
+
+function compileRegex(source: string): RegExp | null {
+  const cached = regexCache.get(source);
+  if (cached !== undefined) return cached;
+  let compiled: RegExp | null;
+  try {
+    compiled = new RegExp(source);
+  } catch {
+    compiled = null;
+  }
+  if (regexCache.size >= MAX_REGEX_CACHE) {
+    const oldest = regexCache.keys().next().value;
+    if (oldest !== undefined) regexCache.delete(oldest);
+  }
+  regexCache.set(source, compiled);
+  return compiled;
+}
+
 export class PermissionEngine {
   private policy: PermissionPolicy;
   private policyPath: string | null;
@@ -170,17 +213,15 @@ function matchRule(rule: PolicyRule, call: PendingToolCall, intent: 'allow' | 'd
     if (!input || typeof input !== 'object') return false;
     for (const [k, v] of Object.entries(rule.inputMatches)) {
       const candidate = stringifyCandidate(input[k]);
-      let re: RegExp;
-      try {
-        // `inputMatches` values are UNANCHORED regexes by design: `.test` does a
-        // substring/partial match, so the pattern matches if it occurs anywhere
-        // in `candidate`. This is the documented, stable contract (see
-        // PolicyRule.inputMatches) — never wrap it in `^(?:…)$`, as that would
-        // silently break existing permission files. Authors who need a full
-        // match anchor their own pattern with `^…$`.
-        re = new RegExp(v);
-      } catch (err) {
-        warnBadPattern(rule.name, k, v, intent, err);
+      // `inputMatches` values are UNANCHORED regexes by design: `.test` does a
+      // substring/partial match, so the pattern matches if it occurs anywhere
+      // in `candidate`. This is the documented, stable contract (see
+      // PolicyRule.inputMatches) — never wrap it in `^(?:…)$`, as that would
+      // silently break existing permission files. Authors who need a full
+      // match anchor their own pattern with `^…$`.
+      const re = compileRegex(v);
+      if (re === null) {
+        warnBadPattern(rule.name, k, v, intent, regexCompileError(v));
         // Uncompilable pattern: a deny rule must still deny (fail closed),
         // an allow rule must not grant (this field fails to match).
         if (intent === 'deny') continue;
@@ -198,17 +239,36 @@ function matchRule(rule: PolicyRule, call: PendingToolCall, intent: 'allow' | 'd
  * structured field (object/array) is JSON-serialized so a rule can match its
  * shape (e.g. `inputMatches: { args: '"--force"' }`) instead of silently
  * seeing `[object Object]` and never matching. `null`/`undefined` → `''`.
+ *
+ * The result is truncated to {@link MAX_MATCH_INPUT} so a long model-controlled
+ * field can't drive catastrophic regex backtracking on the tool-call hot path
+ * (see MAX_MATCH_INPUT).
  */
 function stringifyCandidate(value: unknown): string {
   if (value === null || value === undefined) return '';
   if (typeof value === 'object') {
     try {
-      return JSON.stringify(value) ?? '';
+      return capLength(JSON.stringify(value) ?? '');
     } catch {
-      return String(value);
+      return capLength(String(value));
     }
   }
-  return String(value);
+  return capLength(String(value));
+}
+
+function capLength(s: string): string {
+  return s.length > MAX_MATCH_INPUT ? s.slice(0, MAX_MATCH_INPUT) : s;
+}
+
+/** Re-derive the compile error for an uncompilable source (off the hot path —
+ * only when a rule's pattern is invalid) so `warnBadPattern` keeps its detail. */
+function regexCompileError(source: string): unknown {
+  try {
+    new RegExp(source);
+    return undefined;
+  } catch (err) {
+    return err;
+  }
 }
 
 function warnBadPattern(
@@ -232,8 +292,13 @@ function warnBadPattern(
 function nameMatches(pattern: string, candidate: string): boolean {
   if (pattern === candidate) return true;
   if (pattern.includes('*')) {
-    const re = new RegExp('^' + pattern.split('*').map(escapeRe).join('.*') + '$');
-    return re.test(candidate);
+    // Bound the candidate before the glob-derived `.test` (the glob escapes all
+    // metachars, so the only backtracking risk is sheer input length). The
+    // source is fully escaped, so `compileRegex` always succeeds here; the cache
+    // just avoids recompiling the same glob on every tool call.
+    const source = '^' + pattern.split('*').map(escapeRe).join('.*') + '$';
+    const re = compileRegex(source);
+    return re !== null && re.test(capLength(candidate));
   }
   return false;
 }

package/src/plugins/discovery.test.ts

@@ -1,7 +1,7 @@
 import { promises as fs } from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { silentLogger } from '../logger.js';
 import { discoverPlugins } from './discovery.js';
 import { createPluginLoader } from './loader.js';
@@ -85,6 +85,24 @@ describe('discoverPlugins + createPluginLoader (end-to-end)', () => {
     expect(manifests.find((m) => m.packageName === 'plain-pkg')).toBeUndefined();
   });
 
+  it('rejects a plugin entry that escapes its package directory (path traversal)', async () => {
+    const pkgRoot = path.join(cwd, 'node_modules', '@acme', 'mox-thing');
+    await fs.mkdir(pkgRoot, { recursive: true });
+    await fs.writeFile(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({
+        name: '@acme/mox-thing',
+        version: '1.0.0',
+        moxxy: { plugin: { entry: '../../../../../../tmp/evil.js' } },
+      }),
+    );
+    const manifests = await discoverPlugins({ cwd, logger: silentLogger });
+    const ours = manifests.find((m) => m.packageName === '@acme/mox-thing')!;
+    expect(ours).toBeDefined();
+    const loader = createPluginLoader({ cwd });
+    await expect(loader.load(ours)).rejects.toThrow(/escapes its package directory/);
+  });
+
   it('rejects entries that do not export a moxxy plugin object', async () => {
     const pkgRoot = path.join(cwd, 'node_modules', '@acme', 'mox-thing');
     await makePkg(pkgRoot, {
@@ -99,6 +117,46 @@ describe('discoverPlugins + createPluginLoader (end-to-end)', () => {
     await expect(loader.load(ours)).rejects.toThrow(/did not export a valid Plugin/);
   });
 
+  it('stays silent on a missing package.json but warns on a non-ENOENT read failure', async () => {
+    // A directory with NO package.json (ENOENT) is the common "not a package"
+    // case — must not warn.
+    const emptyDir = path.join(cwd, 'node_modules', 'no-pkgjson');
+    await fs.mkdir(emptyDir, { recursive: true });
+    // A directory whose package.json is malformed JSON (SyntaxError, not ENOENT)
+    // means a plugin may have been dropped for a non-structural reason → warn,
+    // not swallow it identically to "no package.json".
+    const badDir = path.join(cwd, 'node_modules', 'bad-pkgjson');
+    await fs.mkdir(badDir, { recursive: true });
+    await fs.writeFile(path.join(badDir, 'package.json'), '{ this is not json');
+
+    const warn = vi.fn();
+    const logger = { ...silentLogger, warn };
+    const manifests = await discoverPlugins({ cwd, logger });
+    expect(manifests.find((m) => m.packageName === 'no-pkgjson')).toBeUndefined();
+    expect(manifests.find((m) => m.packageName === 'bad-pkgjson')).toBeUndefined();
+    // Exactly the malformed one warned; the missing one did not.
+    const warnedPaths = warn.mock.calls.map((c) => String((c[1] as { path?: string })?.path ?? ''));
+    expect(warnedPaths.some((p) => p.includes('bad-pkgjson'))).toBe(true);
+    expect(warnedPaths.some((p) => p.includes('no-pkgjson'))).toBe(false);
+  });
+
+  it('discovers all plugins even when there are more than the concurrency cap', async () => {
+    // Bounding fd concurrency must not DROP plugins — create well over the cap
+    // and assert every one is found.
+    const count = 80;
+    for (let i = 0; i < count; i++) {
+      const pkgRoot = path.join(cwd, 'node_modules', `mox-bulk-${i}`);
+      await fs.mkdir(pkgRoot, { recursive: true });
+      await fs.writeFile(
+        path.join(pkgRoot, 'package.json'),
+        JSON.stringify({ name: `mox-bulk-${i}`, version: '1.0.0', moxxy: { plugin: { entry: './index.mjs' } } }),
+      );
+    }
+    const manifests = await discoverPlugins({ cwd, logger: silentLogger });
+    const found = manifests.filter((m) => m.packageName.startsWith('mox-bulk-'));
+    expect(found).toHaveLength(count);
+  });
+
   it('walks up parent dirs to find node_modules', async () => {
     const nested = path.join(cwd, 'deeply', 'nested');
     await fs.mkdir(nested, { recursive: true });

package/src/plugins/discovery.ts

@@ -10,6 +10,37 @@ import type { Logger } from '../logger.js';
  */
 const MAX_NODE_MODULES_WALK_DEPTH = 8;
 
+/**
+ * Cap on simultaneous fs handles opened while fanning out manifest reads /
+ * scoped-dir scans. A hoisted monorepo can have thousands of packages;
+ * an uncapped `Promise.all` opens that many fds at once and hits EMFILE/ENFILE,
+ * which `readPluginManifest` would then swallow as "no plugin" — silently
+ * dropping real plugins under fd pressure. Bounding it keeps discovery
+ * deterministic.
+ */
+const DISCOVERY_CONCURRENCY = 32;
+
+/** Map `items` through `fn` with at most `limit` in flight, preserving order. */
+async function mapWithConcurrency<T, R>(
+  items: ReadonlyArray<T>,
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const out = new Array<R>(items.length);
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      const item = items[i]!;
+      out[i] = await fn(item, i);
+    }
+  };
+  const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+  await Promise.all(workers);
+  return out;
+}
+
 export interface DiscoveryOptions {
   readonly cwd: string;
   readonly logger: Logger;
@@ -40,8 +71,8 @@ export async function discoverPlugins(opts: DiscoveryOptions): Promise<ReadonlyA
       seen.add(pkgPath);
       return true;
     });
-    const manifests = await Promise.all(
-      uniquePaths.map((pkgPath) => readPluginManifest(pkgPath, opts.logger)),
+    const manifests = await mapWithConcurrency(uniquePaths, DISCOVERY_CONCURRENCY, (pkgPath) =>
+      readPluginManifest(pkgPath, opts.logger),
     );
     for (const manifest of manifests) {
       if (manifest) out.push(manifest);
@@ -66,11 +97,15 @@ async function listPackageDirs(root: string): Promise<string[]> {
   const entries: import('node:fs').Dirent[] = await fs
     .readdir(root, { withFileTypes: true })
     .catch((): import('node:fs').Dirent[] => []);
-  // Resolve each top-level entry to its contributed package dirs in parallel
-  // (scoped `@org` dirs need their own readdir), then flatten in entry order so
-  // the result matches the prior sequential walk.
-  const perEntry = await Promise.all(
-    entries.map(async (entry): Promise<string[]> => {
+  // Resolve each top-level entry to its contributed package dirs with bounded
+  // concurrency (scoped `@org` dirs need their own readdir), then flatten in
+  // entry order so the result matches the prior sequential walk. Bounding the
+  // scoped readdirs avoids opening one fd per `@org` dir all at once on a large
+  // hoisted node_modules.
+  const perEntry = await mapWithConcurrency(
+    entries,
+    DISCOVERY_CONCURRENCY,
+    async (entry): Promise<string[]> => {
       if (!entry.isDirectory() && !entry.isSymbolicLink()) return [];
       const full = path.join(root, entry.name);
       if (entry.name.startsWith('@')) {
@@ -83,7 +118,7 @@ async function listPackageDirs(root: string): Promise<string[]> {
       }
       if (entry.name !== '.bin' && entry.name !== '.pnpm') return [full];
       return [];
-    }),
+    },
   );
   return perEntry.flat();
 }
@@ -96,7 +131,20 @@ async function readPluginManifest(
   let pkg: { name?: string; version?: string; moxxy?: unknown };
   try {
     pkg = JSON.parse(await fs.readFile(pkgJsonPath, 'utf8'));
-  } catch {
+  } catch (err) {
+    // A missing package.json (ENOENT) is the common, expected "not a package"
+    // case — stay silent. Any other errno (EMFILE/ENFILE under fd pressure,
+    // EACCES, a malformed JSON SyntaxError) means a plugin may have been DROPPED
+    // for a non-structural reason, so surface it instead of swallowing it
+    // identically to "no package.json".
+    const code = (err as NodeJS.ErrnoException | undefined)?.code;
+    if (code !== 'ENOENT') {
+      logger.warn('discovery: could not read package.json', {
+        path: pkgJsonPath,
+        ...(code ? { code } : {}),
+        err: err instanceof Error ? err.message : String(err),
+      });
+    }
     return null;
   }
   if (!pkg.moxxy) return null;

package/src/plugins/host.test.ts

@@ -418,6 +418,46 @@ describe('PluginHost', () => {
     });
   });
 
+  it('rolls back ALL contributions when one collides mid-registration (no orphans)', () => {
+    const { host, tools, providers } = makeHost();
+    // First plugin claims provider "dup".
+    host.registerStatic(
+      definePlugin({
+        name: 'first',
+        providers: [
+          defineProvider({
+            name: 'dup',
+            models: [],
+            createClient: () => ({ name: 'dup', models: [], stream: async function* () {}, countTokens: async () => 0 }),
+          }),
+        ],
+      }),
+    );
+    // Second plugin registers a tool FIRST (succeeds), then a provider named
+    // "dup" which collides → applyPlugin throws part way through. The already-
+    // registered tool must be rolled back, and no LoadedRecord must exist.
+    const colliding = definePlugin({
+      name: 'second',
+      tools: [
+        defineTool({ name: 'orphan-tool', description: '', inputSchema: z.any(), handler: () => null }),
+      ],
+      providers: [
+        defineProvider({
+          name: 'dup',
+          models: [],
+          createClient: () => ({ name: 'dup', models: [], stream: async function* () {}, countTokens: async () => 0 }),
+        }),
+      ],
+    });
+    expect(() => host.registerStatic(colliding)).toThrow(/already registered/);
+    // The tool registered before the collision must NOT be stranded.
+    expect(tools.has('orphan-tool')).toBe(false);
+    // The first plugin's provider survives; no duplicate from the failed load.
+    expect(providers.list().map((p) => p.name)).toEqual(['dup']);
+    // No half-loaded record for "second".
+    expect(host.list().map((p) => p.name)).toEqual(['first']);
+  });
+
   it('registerStatic + unload roundtrip transcribers', async () => {
     const { host, transcribers } = makeHost();
     const t = defineTranscriber({

package/src/plugins/host.ts

@@ -220,21 +220,59 @@ export class PluginHost implements PluginHostHandle {
   }
 
   private applyPlugin(plugin: Plugin, manifest?: ResolvedPluginManifest): LoadedRecord {
-    // Snapshot the contributed names BEFORE registering (same as the original
-    // two-phase order), keyed by REGISTRY_KINDS field. Building the names from
-    // the same table the registration loop uses keeps the two in lockstep.
-    const names = {} as Record<keyof RegistryNameRecord, ReadonlyArray<string>>;
-    for (const kind of REGISTRY_KINDS) {
-      names[kind.recordField] = kind.defs(plugin).map((def) => kind.nameOf(def));
-    }
+    // A statically-registered builtin (no manifest) is trusted; a discovered
+    // plugin (manifest present) is not. The isolator registry uses this to
+    // refuse letting a discovered plugin shadow a trusted isolator name.
+    const trusted = manifest === undefined;
 
     // Register in REGISTRY_KINDS order — the exact set + order the original
     // hand-written register sequence used (incl. viewRenderers/tunnelProviders
-    // via `replace`).
-    for (const kind of REGISTRY_KINDS) {
-      for (const def of kind.defs(plugin)) kind.register(this.opts, def);
+    // via `replace`). Track what we successfully registered so a mid-loop throw
+    // (e.g. a duplicate name colliding with an already-loaded plugin, since most
+    // registries throw on duplicate) doesn't strand half-registered
+    // contributions: no LoadedRecord is created on throw, so `unload` could
+    // never reach them. On failure, unregister in reverse before rethrowing.
+    const registered: Array<{ kind: (typeof REGISTRY_KINDS)[number]; name: string }> = [];
+    try {
+      for (const kind of REGISTRY_KINDS) {
+        for (const def of kind.defs(plugin)) {
+          // A `false` return means the registration was REFUSED without taking
+          // effect (an untrusted plugin shadowing a trusted isolator). Don't
+          // track it — neither for rollback (unregistering would delete the
+          // trusted impl this plugin never owned) NOR for the LoadedRecord (so
+          // a clean `unload` later doesn't delete that same trusted impl).
+          const applied = kind.register(this.opts, def, trusted);
+          if (applied === false) continue;
+          registered.push({ kind, name: kind.nameOf(def) });
+        }
+      }
+    } catch (err) {
+      for (let i = registered.length - 1; i >= 0; i--) {
+        const entry = registered[i];
+        if (!entry) continue;
+        const { kind, name } = entry;
+        // Don't roll back override-on-register kinds (view/tunnel): they're
+        // last-wins `replace`, so this plugin may have clobbered a def core or
+        // another plugin owned — unregistering would delete that shared def.
+        if (kind.overrideOnRegister) continue;
+        try {
+          kind.unregister(this.opts, name);
+        } catch {
+          // Best-effort rollback: keep unwinding the rest even if one
+          // unregister throws, so we don't leave further orphans behind.
+        }
+      }
+      throw err;
     }
 
+    // Build the LoadedRecord's per-kind name lists from what was ACTUALLY
+    // applied (the `registered` list), not from the raw `defs` snapshot — a
+    // refused isolator registration must not appear here, or `unload` would
+    // unregister a name this plugin never owned (deleting a trusted builtin).
+    const names = {} as Record<keyof RegistryNameRecord, string[]>;
+    for (const kind of REGISTRY_KINDS) names[kind.recordField] = [];
+    for (const { kind, name } of registered) names[kind.recordField].push(name);
+
     return {
       plugin,
       manifest,

package/src/plugins/lifecycle.test.ts

@@ -168,6 +168,35 @@ describe('HookDispatcherImpl', () => {
     expect(d.hasEventHooks()).toBe(true);
   });
 
+  it('does not surface an unhandledRejection when a hook rejects AFTER timing out', async () => {
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown): void => void unhandled.push(reason);
+    process.on('unhandledRejection', onUnhandled);
+    try {
+      // Hook stays pending past the (tiny) timeout, THEN rejects. The dispatcher
+      // must have a rejection handler attached to the hook promise so this
+      // late rejection is swallowed rather than crashing the process.
+      const slow = definePlugin({
+        name: 'slow',
+        hooks: {
+          onInit: () =>
+            new Promise<void>((_, reject) => {
+              setTimeout(() => reject(new Error('late boom')), 30);
+            }),
+        },
+      });
+      const d = new HookDispatcherImpl({ logger: silentLogger, hookTimeoutMs: 5 });
+      d.setPlugins([slow]);
+      await d.dispatchInit(appCtx); // resolves on timeout, not on the late reject
+      // Wait long enough for the late rejection to fire and any microtasks to
+      // flush, so a missing handler would have been observed by now.
+      await new Promise((r) => setTimeout(r, 60));
+      expect(unhandled).toEqual([]);
+    } finally {
+      process.off('unhandledRejection', onUnhandled);
+    }
+  });
+
   it('logs and continues when a hook throws', async () => {
     const failed = vi.fn();
     const bad = definePlugin({

package/src/plugins/lifecycle.ts

@@ -112,6 +112,13 @@ export class HookDispatcherImpl implements HookDispatcher {
     let timer: ReturnType<typeof setTimeout> | undefined;
     try {
       const p = Promise.resolve(fn() as Promise<T | undefined | void>);
+      // If the timeout wins the race, `p` is still pending and unobserved; a
+      // slow hook that later rejects would surface as an unhandledRejection
+      // (process-level crash/log spam in strict configs / the desktop main).
+      // Attach a no-op handler so a post-timeout rejection is swallowed too.
+      // (Promise.race still settles on the original `p`, so this doesn't mask
+      // the in-time error path below — that one is observed via the race.)
+      p.catch(() => undefined);
       const timeout = new Promise<never>((_, reject) => {
         timer = setTimeout(
           () => reject(new Error(`Hook ${hook} on ${entry.plugin.name} timed out`)),

package/src/plugins/loader.ts

@@ -5,20 +5,42 @@ import type { PluginLoader } from './host.js';
 
 export interface JitiLoaderOptions {
   readonly cwd: string;
+  /**
+   * When provided, its return value is appended as a `?v=` query to the ESM
+   * import URL so `import()` re-evaluates the module. Supplying this LEAKS a
+   * module instance per call — ESM modules can't be unloaded, so every distinct
+   * URL is retained for the process lifetime. Provide it ONLY for an explicit
+   * hot-reload of a changed `.js`/`.mjs` plugin; omit it for normal loads so a
+   * long-lived runner that reloads repeatedly doesn't grow memory without
+   * bound. (`.ts` plugins go through jiti, which has its own cache control.)
+   */
   readonly cacheBust?: () => string;
 }
 
-let jitiInstance: ((id: string) => unknown) | null = null;
+// Key the jiti cache by cwd: createPluginLoader is called per-session with the
+// session's cwd, so a single process-global instance rooted at the FIRST cwd
+// would resolve every later session's .ts plugins (and jiti's transform cache)
+// against the wrong base directory — non-deterministically by session order.
+// One jiti per distinct plugin root is bounded and correct.
+const jitiByCwd = new Map<string, ((id: string) => unknown) | null>();
 
 async function getJiti(cwd: string): Promise<((id: string) => unknown) | null> {
-  if (jitiInstance) return jitiInstance;
+  const cached = jitiByCwd.get(cwd);
+  if (cached !== undefined) return cached;
   try {
     const mod = await import('jiti');
     const factory = (mod as { createJiti?: (cwd: string, opts?: unknown) => (id: string) => unknown; default?: (cwd: string, opts?: unknown) => (id: string) => unknown }).createJiti ?? (mod as { default?: (cwd: string, opts?: unknown) => (id: string) => unknown }).default;
-    if (!factory) return null;
-    jitiInstance = factory(cwd, { interopDefault: true });
-    return jitiInstance;
+    if (!factory) {
+      jitiByCwd.set(cwd, null);
+      return null;
+    }
+    const instance = factory(cwd, { interopDefault: true });
+    jitiByCwd.set(cwd, instance);
+    return instance;
   } catch {
+    // Don't cache a transient import failure as a permanent null — a missing
+    // optional `jiti` dep is the only realistic cause and is stable, but not
+    // caching here keeps a one-off failure from poisoning all later loads.
     return null;
   }
 }
@@ -27,6 +49,17 @@ export function createPluginLoader(opts: JitiLoaderOptions): PluginLoader {
   return {
     async load(manifest: ResolvedPluginManifest): Promise<Plugin> {
       const entry = path.resolve(manifest.packagePath, manifest.entry);
+      // `manifest.entry` comes from the plugin's own package.json (validated only
+      // as a non-empty string). Reject an entry that escapes the package dir
+      // (e.g. `../../sibling/internals.js` or an absolute path) so a package can
+      // only execute code from inside its own tree — cheap defense-in-depth for
+      // provenance/auditing and any future sandbox-by-path assumptions.
+      const rel = path.relative(manifest.packagePath, entry);
+      if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new Error(
+          `Plugin entry escapes its package directory: ${manifest.entry} (package: ${manifest.packagePath})`,
+        );
+      }
       const isTs = entry.endsWith('.ts') || entry.endsWith('.tsx');
 
       let mod: unknown;
@@ -39,8 +72,13 @@ export function createPluginLoader(opts: JitiLoaderOptions): PluginLoader {
         }
         mod = jiti(entry);
       } else {
-        const bust = opts.cacheBust?.() ?? `${Date.now()}-${Math.random()}`;
-        const url = `${pathToFileURL(entry).href}?v=${bust}`;
+        // Only cache-bust on an explicit request (caller supplied cacheBust).
+        // Busting unconditionally appended a unique `?v=` on EVERY load, and
+        // since ESM never unloads a module, each load permanently retained a
+        // fresh copy of the plugin + its transitive graph — an unbounded leak
+        // across repeated reloads. The plain URL lets ESM reuse its cache.
+        const bust = opts.cacheBust?.();
+        const url = bust ? `${pathToFileURL(entry).href}?v=${bust}` : pathToFileURL(entry).href;
         mod = await import(url);
       }
 

package/src/plugins/registry-kinds.test.ts

@@ -159,4 +159,57 @@ describe('PluginHost register/unregister lockstep (REGISTRY_KINDS)', () => {
       expect(byKind[kind.kind]!.list().length, `${kind.kind} should be empty after unload`).toBe(0);
     }
   });
+
+  it('unloading a discovered plugin whose isolator was REFUSED keeps the trusted builtin', async () => {
+    const { host, byKind } = makeHost();
+    const isolators = byKind.isolator as IsolatorRegistry;
+    // A trusted builtin owns the name "worker".
+    const trustedWorker: Isolator = { name: 'worker', strength: 'none', run: async (_c, h) => h(undefined) };
+    host.registerStatic(definePlugin({ name: 'builtin-sec', isolators: [trustedWorker] }));
+    expect(isolators.get('worker')).toBe(trustedWorker);
+
+    // A discovered (untrusted) plugin tries to shadow "worker"; the registry
+    // refuses, so the plugin never owned it. Unloading the discovered plugin
+    // must NOT delete the trusted impl.
+    const rogueWorker: Isolator = { name: 'worker', strength: 'none', run: async (_c, h) => h(undefined) };
+    host.registerDiscovered(
+      definePlugin({ name: 'rogue', isolators: [rogueWorker] }),
+      { entry: './index.js', packageName: '@rogue/pkg', packageVersion: '1.0.0', packagePath: '/tmp/rogue' },
+    );
+    expect(isolators.get('worker')).toBe(trustedWorker); // refused, not shadowed
+
+    await host.unload('@rogue/pkg');
+    // The trusted worker must survive the rogue plugin's unload.
+    expect(isolators.get('worker')).toBe(trustedWorker);
+    expect(isolators.has('worker')).toBe(true);
+  });
+
+  it('a mid-load collision in a discovered plugin whose isolator was REFUSED does not delete the trusted builtin', () => {
+    const { host, byKind } = makeHost();
+    const isolators = byKind.isolator as IsolatorRegistry;
+    const tools = byKind.tool as ToolRegistryImpl;
+    const trustedWorker: Isolator = { name: 'worker', strength: 'none', run: async (_c, h) => h(undefined) };
+    host.registerStatic(definePlugin({ name: 'builtin-sec', isolators: [trustedWorker] }));
+    // Another plugin owns tool "dup".
+    host.registerStatic(
+      definePlugin({ name: 'first', tools: [defineTool({ name: 'dup', description: '', inputSchema: z.any(), handler: () => null })] }),
+    );
+
+    // A discovered plugin: its isolator "worker" is refused (untrusted shadow),
+    // then its tool "dup" collides → applyPlugin throws and rolls back. The
+    // rollback must NOT unregister "worker" (the plugin never owned it).
+    const rogue = definePlugin({
+      name: 'rogue',
+      isolators: [{ name: 'worker', strength: 'none', run: async (_c, h) => h(undefined) } as Isolator],
+      tools: [defineTool({ name: 'dup', description: '', inputSchema: z.any(), handler: () => null })],
+    });
+    expect(() =>
+      host.registerDiscovered(rogue, { entry: './index.js', packageName: '@rogue/pkg', packageVersion: '1.0.0', packagePath: '/tmp/rogue' }),
+    ).toThrow(/already registered/);
+    // Trusted worker untouched; first plugin's tool untouched.
+    expect(isolators.get('worker')).toBe(trustedWorker);
+    expect(tools.has('dup')).toBe(true);
+    // No half-loaded record for the rogue.
+    expect(host.list().map((p) => p.name).sort()).toEqual(['builtin-sec', 'first']);
+  });
 });