@moxxy/core 0.5.0 → 0.5.1

package/src/plugins/registry-kinds.ts

@@ -64,10 +64,29 @@ export interface RegistryKind<TDef> {
   readonly defs: (plugin: Plugin) => ReadonlyArray<TDef>;
   /** Extract the registry key from a def (mostly `.name`; surfaces use `.kind`). */
   readonly nameOf: (def: TDef) => string;
-  /** Register a single def into its registry (uses `register` or `replace`). */
-  readonly register: (opts: PluginHostOptions, def: TDef) => void;
+  /**
+   * Register a single def into its registry (uses `register` or `replace`).
+   * `trusted` is true for statically-registered builtins and false for
+   * discovered (untrusted) plugins; most kinds ignore it, but the isolator
+   * registry uses it to refuse letting a discovered plugin shadow a builtin.
+   *
+   * Returns `false` when the registration was REFUSED without taking effect
+   * (currently only the isolator registry, when an untrusted plugin tries to
+   * shadow a trusted name). PluginHost must NOT track a refused registration
+   * for rollback — unregistering it on a later mid-`applyPlugin` failure would
+   * delete a name this plugin never actually owned. `void`/`true` means applied.
+   */
+  readonly register: (opts: PluginHostOptions, def: TDef, trusted: boolean) => void | boolean;
   /** Remove a previously-registered name from its registry. */
   readonly unregister: (opts: PluginHostOptions, name: string) => void;
+  /**
+   * True when `register` is an override (`replace`) rather than a throw-on-
+   * duplicate insert. Such kinds are last-wins and may clobber a name seeded by
+   * core or another plugin, so PluginHost must NOT roll them back when a later
+   * kind throws mid-`applyPlugin` (unregistering would delete a def this plugin
+   * didn't actually own).
+   */
+  readonly overrideOnRegister?: boolean;
 }
 
 /**
@@ -124,6 +143,7 @@ export const REGISTRY_KINDS: ReadonlyArray<RegistryKind<unknown>> = [
     // viewRenderers use `replace` (override-allowed) on the register side.
     register: (o, v: ViewRendererDef) => o.viewRenderers.replace(v),
     unregister: (o, n) => o.viewRenderers.unregister(n),
+    overrideOnRegister: true,
   } satisfies RegistryKind<ViewRendererDef>,
   {
     kind: 'tunnelProvider',
@@ -133,6 +153,7 @@ export const REGISTRY_KINDS: ReadonlyArray<RegistryKind<unknown>> = [
     // tunnelProviders use `replace` (override-allowed) on the register side.
     register: (o, t: TunnelProviderDef) => o.tunnelProviders.replace(t),
     unregister: (o, n) => o.tunnelProviders.unregister(n),
+    overrideOnRegister: true,
   } satisfies RegistryKind<TunnelProviderDef>,
   {
     kind: 'channel',
@@ -196,7 +217,8 @@ export const REGISTRY_KINDS: ReadonlyArray<RegistryKind<unknown>> = [
     recordField: 'isolatorNames',
     defs: (p) => p.isolators ?? [],
     nameOf: (i: Isolator) => i.name,
-    register: (o, i: Isolator) => o.isolators.register(i),
+    register: (o, i: Isolator, trusted): boolean =>
+      o.isolators.register(i, { trusted, logger: o.logger }),
     unregister: (o, n) => o.isolators.unregister(n),
   } satisfies RegistryKind<Isolator>,
   {

package/src/plugins/toposort.ts

@@ -33,27 +33,55 @@ export function toposortPluginManifests(
   const order: ResolvedPluginManifest[] = [];
   const visited = new Set<string>();
   const onStack = new Set<string>();
-  const stack: string[] = [];
+  // Path of names from the current root, mirroring the old recursion stack so a
+  // detected cycle reports the same participating names.
+  const path: string[] = [];
 
-  const visit = (name: string): void => {
-    if (visited.has(name)) return;
-    if (onStack.has(name)) {
-      const startIdx = stack.indexOf(name);
-      throw new PluginCycleError(stack.slice(startIdx).concat(name));
-    }
-    const manifest = byPackage.get(name);
-    if (!manifest) return; // unknown dep — leave for readiness gate
+  // Explicit-stack iterative DFS (instead of recursion) so a pathological deep
+  // linear dependency chain — depth is plugin-author/package-controlled via
+  // package.json#moxxy.requirements — can't overflow the call stack and turn a
+  // load-time ordering concern into a process crash.
+  type Frame = { name: string; deps: ReadonlyArray<string>; next: number };
+
+  const visitRoot = (root: string): void => {
+    if (visited.has(root)) return;
+    const rootManifest = byPackage.get(root);
+    if (!rootManifest) return; // unknown dep — leave for readiness gate
 
-    onStack.add(name);
-    stack.push(name);
-    for (const dep of pluginDeps(manifest.requirements)) visit(dep);
-    onStack.delete(name);
-    stack.pop();
-    visited.add(name);
-    order.push(manifest);
+    const stack: Frame[] = [{ name: root, deps: pluginDeps(rootManifest.requirements), next: 0 }];
+    onStack.add(root);
+    path.push(root);
+
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      if (!frame) break;
+      if (frame.next < frame.deps.length) {
+        const dep = frame.deps[frame.next++];
+        if (dep === undefined) continue;
+        if (visited.has(dep)) continue;
+        if (onStack.has(dep)) {
+          const startIdx = path.indexOf(dep);
+          throw new PluginCycleError(path.slice(startIdx).concat(dep));
+        }
+        const depManifest = byPackage.get(dep);
+        if (!depManifest) continue; // unknown dep — leave for readiness gate
+        onStack.add(dep);
+        path.push(dep);
+        stack.push({ name: dep, deps: pluginDeps(depManifest.requirements), next: 0 });
+        continue;
+      }
+      // All deps emitted → post-order emit this frame, same as the recursive
+      // version pushed after its dependency loop.
+      const done = stack.pop()!;
+      onStack.delete(done.name);
+      path.pop();
+      visited.add(done.name);
+      const manifest = byPackage.get(done.name);
+      if (manifest) order.push(manifest);
+    }
   };
 
-  for (const m of manifests) visit(m.packageName);
+  for (const m of manifests) visitRoot(m.packageName);
   return order;
 }
 

package/src/preferences.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { promises as fs } from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -10,13 +10,18 @@ import { loadPreferences, preferencesPath, savePreferences } from './preferences
 let tmpHome: string;
 let savedHome: string | undefined;
 let savedUserProfile: string | undefined;
+let savedMoxxyHome: string | undefined;
 
 beforeEach(async () => {
   tmpHome = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-prefs-'));
   savedHome = process.env.HOME;
   savedUserProfile = process.env.USERPROFILE;
+  savedMoxxyHome = process.env.MOXXY_HOME;
   process.env.HOME = tmpHome;
   process.env.USERPROFILE = tmpHome;
+  // The default-home tests below assert the `~/.moxxy` fallback, so MOXXY_HOME
+  // must be unset for them (it would otherwise win).
+  delete process.env.MOXXY_HOME;
   await fs.mkdir(path.join(tmpHome, '.moxxy'), { recursive: true });
 });
 
@@ -25,6 +30,8 @@ afterEach(async () => {
   else process.env.HOME = savedHome;
   if (savedUserProfile === undefined) delete process.env.USERPROFILE;
   else process.env.USERPROFILE = savedUserProfile;
+  if (savedMoxxyHome === undefined) delete process.env.MOXXY_HOME;
+  else process.env.MOXXY_HOME = savedMoxxyHome;
   await fs.rm(tmpHome, { recursive: true, force: true });
 });
 
@@ -36,6 +43,28 @@ describe('preferences store', () => {
     expect(preferencesPath()).toBe(path.join(tmpHome, '.moxxy', 'preferences.json'));
   });
 
+  it('honors $MOXXY_HOME so preferences follow the relocated data dir', async () => {
+    const altHome = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-prefs-alt-'));
+    const prevMoxxyHome = process.env.MOXXY_HOME;
+    process.env.MOXXY_HOME = altHome;
+    try {
+      // Path now lives directly under MOXXY_HOME, NOT under ~/.moxxy.
+      expect(preferencesPath()).toBe(path.join(altHome, 'preferences.json'));
+      await savePreferences({ model: 'relocated' });
+      // Written to the relocated dir, not the homedir fallback.
+      const raw = await fs.readFile(path.join(altHome, 'preferences.json'), 'utf8');
+      expect(JSON.parse(raw).model).toBe('relocated');
+      // The homedir fallback location must remain empty.
+      await expect(
+        fs.readFile(path.join(tmpHome, '.moxxy', 'preferences.json'), 'utf8'),
+      ).rejects.toMatchObject({ code: 'ENOENT' });
+    } finally {
+      if (prevMoxxyHome === undefined) delete process.env.MOXXY_HOME;
+      else process.env.MOXXY_HOME = prevMoxxyHome;
+      await fs.rm(altHome, { recursive: true, force: true });
+    }
+  });
+
   it('returns an empty object when the file is missing', async () => {
     expect(await loadPreferences()).toEqual({});
   });
@@ -90,6 +119,28 @@ describe('preferences store', () => {
     expect(loaded.mode).toBe('goal');
   });
 
+  it('swallows a write failure: logs to stderr but never throws (best-effort contract)', async () => {
+    // savePreferences is documented best-effort — a persist failure must NOT
+    // bubble out and break the slash-command / shutdown that triggered it. Force
+    // an unwritable target by pointing MOXXY_HOME *under a regular file*, so the
+    // atomic writer's `mkdir(dirname)` fails with ENOTDIR.
+    const blocker = path.join(tmpHome, 'not-a-dir');
+    await fs.writeFile(blocker, 'x', 'utf8');
+    const prevMoxxyHome = process.env.MOXXY_HOME;
+    process.env.MOXXY_HOME = path.join(blocker, 'nested'); // dirname is a file → mkdir fails
+    const stderr = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+    try {
+      // Must resolve, not reject — the pick still took effect in-session.
+      await expect(savePreferences({ model: 'm' })).resolves.toBeUndefined();
+      // The failure is surfaced (not silently swallowed) on stderr.
+      expect(stderr).toHaveBeenCalled();
+    } finally {
+      stderr.mockRestore();
+      if (prevMoxxyHome === undefined) delete process.env.MOXXY_HOME;
+      else process.env.MOXXY_HOME = prevMoxxyHome;
+    }
+  });
+
   it('keeps ALL distinct keys present under many overlapping writers', async () => {
     const patches: Array<Partial<Record<`k${number}`, string>>> = [];
     for (let i = 0; i < 25; i++) patches.push({ [`k${i}`]: `v${i}` });

package/src/preferences.ts

@@ -1,8 +1,6 @@
 import { promises as fs } from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
 import { createMutex, migrateModeName } from '@moxxy/sdk';
-import { writeFileAtomic } from '@moxxy/sdk/server';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
 
 /**
  * User-level runtime preferences persisted at ~/.moxxy/preferences.json.
@@ -28,7 +26,10 @@ export interface MoxxyPreferences {
 }
 
 export function preferencesPath(): string {
-  return path.join(os.homedir(), '.moxxy', 'preferences.json');
+  // Route through `moxxyPath` so a `$MOXXY_HOME` override relocates preferences
+  // alongside the rest of the data dir (config.yaml, vault, providers.json, …).
+  // Identical to `~/.moxxy/preferences.json` when MOXXY_HOME is unset.
+  return moxxyPath('preferences.json');
 }
 
 /**

package/src/registries/active-backend-registry.ts

@@ -55,7 +55,16 @@ export class ActiveBackendRegistry<TDef extends { name: string }, TInstance> {
   replace(def: TDef, instance?: TInstance): void {
     this.defs.set(def.name, def);
     this.instances.delete(def.name);
-    if (instance) this.instances.set(def.name, instance);
+    if (instance) {
+      this.instances.set(def.name, instance);
+    } else if (this.active === def.name && !this.opts.buildOnRead) {
+      // For a non-buildOnRead registry, getActive() reads the cached instance
+      // directly and throws when it's missing. Dropping the active def's cache
+      // (e.g. a hot-reloaded plugin re-registering via replace) would otherwise
+      // strand getActive() until the next setActive. buildOnRead registries
+      // self-heal on read, so they don't need this.
+      this.instances.set(def.name, this.buildInstance(def.name));
+    }
   }
 
   unregister(name: string): void {

package/src/registries/channels.test.ts

@@ -0,0 +1,79 @@
+import type { ChannelDef, ChannelFactoryDeps } from '@moxxy/sdk';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ChannelRegistryImpl } from './channels.js';
+
+const deps = {} as ChannelFactoryDeps;
+
+function fakeChannel(
+  name: string,
+  isAvailable?: ChannelDef['isAvailable'],
+): ChannelDef {
+  return {
+    name,
+    description: `channel ${name}`,
+    create: () => ({}) as never,
+    ...(isAvailable ? { isAvailable } : {}),
+  };
+}
+
+describe('ChannelRegistryImpl.listWithAvailability', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('treats a channel without isAvailable as ok and maps a thrown probe to not-ok', async () => {
+    const reg = new ChannelRegistryImpl();
+    reg.register(fakeChannel('always'));
+    reg.register(
+      fakeChannel('throws', async () => {
+        throw new Error('boom');
+      }),
+    );
+    const out = await reg.listWithAvailability(deps);
+    const byName = Object.fromEntries(out.map((o) => [o.def.name, o.availability]));
+    expect(byName.always).toEqual({ ok: true });
+    expect(byName.throws).toEqual({ ok: false, reason: 'boom' });
+  });
+
+  it('does not let one hung probe block the others or the listing (bounded timeout)', async () => {
+    vi.useFakeTimers();
+    const reg = new ChannelRegistryImpl();
+    // This probe never resolves — without a timeout it would wedge the listing.
+    reg.register(fakeChannel('hung', () => new Promise<never>(() => {})));
+    reg.register(fakeChannel('fast', async () => ({ ok: true })));
+
+    const promise = reg.listWithAvailability(deps);
+    // Advance past the probe timeout so the hung probe resolves to not-ok.
+    await vi.advanceTimersByTimeAsync(5_000);
+    const out = await promise;
+    const byName = Object.fromEntries(out.map((o) => [o.def.name, o.availability]));
+    expect(byName.fast).toEqual({ ok: true });
+    expect(byName.hung.ok).toBe(false);
+    expect(byName.hung.reason).toMatch(/timed out/);
+  });
+
+  it('runs probes in parallel — a slow probe does not starve a later fast one', async () => {
+    vi.useFakeTimers();
+    const reg = new ChannelRegistryImpl();
+    let fastRan = false;
+    reg.register(
+      fakeChannel(
+        'slow',
+        () => new Promise<{ ok: true }>((resolve) => setTimeout(() => resolve({ ok: true }), 2_000)),
+      ),
+    );
+    reg.register(
+      fakeChannel('fast', async () => {
+        fastRan = true;
+        return { ok: true };
+      }),
+    );
+    const promise = reg.listWithAvailability(deps);
+    // The fast probe should already have started (parallel), before the slow
+    // one's timer is even advanced.
+    await Promise.resolve();
+    expect(fastRan).toBe(true);
+    await vi.advanceTimersByTimeAsync(2_000);
+    await promise;
+  });
+});

package/src/registries/channels.ts

@@ -6,11 +6,17 @@ import type {
 } from '@moxxy/sdk';
 import { DefMapRegistry } from './def-map-registry.js';
 
+/** Upper bound on a single channel availability probe. `isAvailable` hooks can
+ *  do network/process probes (tunnel reachability, binary presence); a hung one
+ *  (dead socket, no DNS) must not block the whole listing — which typically
+ *  backs a UI picker — indefinitely. */
+const AVAILABILITY_PROBE_TIMEOUT_MS = 4_000;
+
 /**
  * Flat name→def registry of channels ({@link DefMapRegistry}) plus
  * `listWithAvailability`, which pairs each channel with its current
  * availability (treating channels without an `isAvailable` hook as
- * `{ ok: true }` and mapping a thrown probe to `{ ok: false }`).
+ * `{ ok: true }` and mapping a thrown OR timed-out probe to `{ ok: false }`).
  */
 export class ChannelRegistryImpl extends DefMapRegistry<ChannelDef> implements ChannelRegistry {
   constructor() {
@@ -20,23 +26,32 @@ export class ChannelRegistryImpl extends DefMapRegistry<ChannelDef> implements C
   async listWithAvailability(
     deps: ChannelFactoryDeps,
   ): Promise<ReadonlyArray<{ def: ChannelDef; availability: ChannelAvailability }>> {
-    const out: Array<{ def: ChannelDef; availability: ChannelAvailability }> = [];
-    for (const def of this.defs.values()) {
-      let availability: ChannelAvailability;
-      if (def.isAvailable) {
-        try {
-          availability = await def.isAvailable(deps);
-        } catch (err) {
-          availability = {
-            ok: false,
-            reason: err instanceof Error ? err.message : String(err),
-          };
-        }
-      } else {
-        availability = { ok: true };
-      }
-      out.push({ def, availability });
+    // Probe in parallel — a serial loop meant one slow probe also starved every
+    // fast probe queued behind it — and bound each probe with a timeout so a
+    // single hung channel can't wedge the whole listing.
+    return Promise.all(
+      [...this.defs.values()].map(async (def) => ({
+        def,
+        availability: await this.probe(def, deps),
+      })),
+    );
+  }
+
+  private async probe(def: ChannelDef, deps: ChannelFactoryDeps): Promise<ChannelAvailability> {
+    if (!def.isAvailable) return { ok: true };
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const timeout = new Promise<ChannelAvailability>((resolve) => {
+        timer = setTimeout(
+          () => resolve({ ok: false, reason: 'availability check timed out' }),
+          AVAILABILITY_PROBE_TIMEOUT_MS,
+        );
+      });
+      return await Promise.race([Promise.resolve(def.isAvailable(deps)), timeout]);
+    } catch (err) {
+      return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
     }
-    return out;
   }
 }

package/src/registries/commands.test.ts

@@ -58,6 +58,71 @@ describe('CommandRegistry', () => {
     expect(reg.get('m')).toBeUndefined();
   });
 
+  it('replace() refuses to hijack an alias owned by a DIFFERENT command', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('compact', { aliases: ['c'] }));
+    reg.register(fakeCommand('clear'));
+    // Replacing /clear with an alias 'c' already owned by /compact must throw,
+    // not silently steal the alias (register() guards this; replace() now too).
+    expect(() => reg.replace(fakeCommand('clear', { aliases: ['c'] }))).toThrow(
+      /alias already in use/,
+    );
+    // /compact still owns 'c'.
+    expect(reg.get('c')?.name).toBe('compact');
+  });
+
+  it('replace() refuses an alias that collides with another command primary name', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('compact'));
+    reg.register(fakeCommand('mode', { aliases: ['m'] }));
+    // Re-defining /mode with an alias equal to another command's PRIMARY name
+    // would make get() ambiguous — reject it.
+    expect(() => reg.replace(fakeCommand('mode', { aliases: ['compact'] }))).toThrow(
+      /already in use/,
+    );
+  });
+
+  it('replace() still allows re-adding the command own primary name as an alias edge case is fine', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('mode', { aliases: ['m'] }));
+    // Replacing with the SAME alias set must not throw on the alias it already
+    // owns (cleared-then-readded).
+    expect(() => reg.replace(fakeCommand('mode', { aliases: ['m'], description: 'x' }))).not.toThrow();
+    expect(reg.get('m')?.name).toBe('mode');
+  });
+
+  it('register() leaves NO partial state when a later alias collides', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('compact', { aliases: ['cc'] }));
+    // The new command's FIRST alias is free, its SECOND ('cc') collides. The
+    // registration must throw atomically: neither the command nor its first
+    // alias may be left behind.
+    expect(() =>
+      reg.register(fakeCommand('clear', { aliases: ['fresh', 'cc'] })),
+    ).toThrow(/alias already in use/);
+    expect(reg.has('clear')).toBe(false);
+    expect(reg.get('fresh')).toBeUndefined();
+    // The first command is untouched.
+    expect(reg.get('cc')?.name).toBe('compact');
+  });
+
+  it('replace() leaves the PRIOR definition intact when a new alias collides', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('compact', { aliases: ['c'] }));
+    reg.register(fakeCommand('mode', { aliases: ['m'] }));
+    // Replacing /mode where the SECOND new alias ('c') is owned by /compact must
+    // throw without first destroying /mode's existing alias 'm' (the prior bug:
+    // delete-prior-then-add left the registry corrupted on a mid-loop throw).
+    expect(() =>
+      reg.replace(fakeCommand('mode', { aliases: ['m2', 'c'] })),
+    ).toThrow(/alias already in use/);
+    // /mode's original def + alias survive untouched.
+    expect(reg.get('m')?.name).toBe('mode');
+    expect(reg.get('m2')).toBeUndefined();
+    // /compact still owns 'c'.
+    expect(reg.get('c')?.name).toBe('compact');
+  });
+
   it('listForChannel filters channel-scoped commands', () => {
     const reg = new CommandRegistry();
     reg.register(fakeCommand('everywhere'));

package/src/registries/commands.ts

@@ -22,25 +22,42 @@ export class CommandRegistry {
     if (this.aliases.has(cmd.name)) {
       throw new Error(`Command name already in use as an alias: /${cmd.name}`);
     }
-    this.commands.set(cmd.name, cmd);
+    // Validate EVERY alias up front, before mutating any state, so a collision
+    // on the second alias can't leave the command half-registered (def set +
+    // some aliases) — the registry stays atomic on a throw.
     for (const alias of cmd.aliases ?? []) {
       if (this.aliases.has(alias) || this.commands.has(alias)) {
         throw new Error(`Command alias already in use: /${alias}`);
       }
-      this.aliases.set(alias, cmd.name);
     }
+    this.commands.set(cmd.name, cmd);
+    for (const alias of cmd.aliases ?? []) this.aliases.set(alias, cmd.name);
   }
 
   replace(cmd: CommandDef): void {
-    // Clean up any aliases of the prior definition before re-adding.
     const prior = this.commands.get(cmd.name);
-    if (prior) {
-      for (const alias of prior.aliases ?? []) this.aliases.delete(alias);
-    }
-    this.commands.set(cmd.name, cmd);
+    const priorAliases = new Set(prior?.aliases ?? []);
+    // Validate the new aliases BEFORE mutating anything, mirroring register()'s
+    // guards so replace() can't silently hijack an alias owned by a different
+    // command or shadow another command's primary name. Validating first (rather
+    // than deleting the prior aliases then re-adding) keeps replace() atomic: a
+    // collision on a later alias must not have already destroyed the prior
+    // definition's aliases. An alias the prior def itself owned is exempt (it's
+    // about to be re-added under the same name).
     for (const alias of cmd.aliases ?? []) {
-      this.aliases.set(alias, cmd.name);
+      const owner = this.aliases.get(alias);
+      if (owner && owner !== cmd.name && !priorAliases.has(alias)) {
+        throw new Error(`Command alias already in use: /${alias}`);
+      }
+      if (this.commands.has(alias) && alias !== cmd.name) {
+        throw new Error(`Command alias already in use as a command name: /${alias}`);
+      }
     }
+    // All validated — now mutate. Clean up the prior definition's aliases, then
+    // install the new def + its aliases.
+    for (const alias of priorAliases) this.aliases.delete(alias);
+    this.commands.set(cmd.name, cmd);
+    for (const alias of cmd.aliases ?? []) this.aliases.set(alias, cmd.name);
   }
 
   unregister(name: string): void {

package/src/registries/isolators.test.ts

@@ -32,6 +32,43 @@ describe('IsolatorRegistry (core contribution collection)', () => {
     expect(reg.get('worker')).toBe(second);
   });
 
+  it('refuses to let a discovered (untrusted) isolator shadow a trusted builtin', () => {
+    const reg = new IsolatorRegistry();
+    const trusted = fakeIsolator('worker');
+    const rogue = fakeIsolator('worker');
+    // Static builtins register as trusted (default).
+    expect(reg.register(trusted, { trusted: true })).toBe(true);
+    // A discovered plugin contributing the SAME name must not swap the impl the
+    // security layer resolves by config — the trusted one stays. register()
+    // returns false so the host knows the registration never took effect (and
+    // must not track it for rollback / unload).
+    expect(reg.register(rogue, { trusted: false })).toBe(false);
+    expect(reg.get('worker')).toBe(trusted);
+    expect(reg.list()).toHaveLength(1);
+  });
+
+  it('returns true when a registration actually takes effect', () => {
+    const reg = new IsolatorRegistry();
+    expect(reg.register(fakeIsolator('docker'), { trusted: false })).toBe(true);
+    expect(reg.register(fakeIsolator('docker'), { trusted: false })).toBe(true); // overwrite still applied
+  });
+
+  it('lets a trusted registration still overwrite (builtin re-register / bundled+discovered same role)', () => {
+    const reg = new IsolatorRegistry();
+    const a = fakeIsolator('subprocess');
+    const b = fakeIsolator('subprocess');
+    reg.register(a, { trusted: true });
+    reg.register(b, { trusted: true });
+    expect(reg.get('subprocess')).toBe(b);
+  });
+
+  it('allows a discovered isolator with a brand-new name', () => {
+    const reg = new IsolatorRegistry();
+    const novel = fakeIsolator('docker');
+    reg.register(novel, { trusted: false });
+    expect(reg.get('docker')).toBe(novel);
+  });
+
   it('has no concept of an active isolator (selection stays with the security layer)', () => {
     const reg = new IsolatorRegistry();
     reg.register(fakeIsolator('wasm'));

package/src/registries/isolators.ts

@@ -1,4 +1,15 @@
 import type { Isolator } from '@moxxy/sdk';
+import type { Logger } from '../logger.js';
+
+export interface IsolatorRegisterOptions {
+  /**
+   * True when the isolator comes from a statically-registered (trusted)
+   * builtin, false for a discovered (untrusted) plugin. A discovered isolator
+   * is never allowed to shadow a name already claimed by a trusted one.
+   */
+  readonly trusted?: boolean;
+  readonly logger?: Logger;
+}
 
 /**
  * Collection of capability isolators contributed by plugins via
@@ -10,18 +21,54 @@ import type { Isolator } from '@moxxy/sdk';
  * A contributed isolator is therefore NEVER auto-activated: registration only
  * makes it available; the user must opt in by name, so a rogue plugin can't
  * silently weaken isolation just by being installed.
+ *
+ * This is the one registry where "last wins" crosses a trust boundary: a
+ * discovered plugin contributing an isolator whose name matches a trusted
+ * builtin would silently swap the implementation the security layer resolves by
+ * `security.isolator`. So a discovered registration may NEVER overwrite a name
+ * a trusted registration already claimed; it's refused with a warning.
  */
 export class IsolatorRegistry {
   private readonly impls = new Map<string, Isolator>();
+  /** Names registered by a trusted (static) source — these are never shadowed. */
+  private readonly trustedNames = new Set<string>();
 
-  register(iso: Isolator): void {
+  /**
+   * Register an isolator by name. Returns `true` when the impl was stored,
+   * `false` when the registration was REFUSED (a discovered plugin trying to
+   * shadow a trusted name). The boolean lets the PluginHost avoid tracking a
+   * refused registration for rollback — otherwise a later mid-`applyPlugin`
+   * failure would `unregister(name)` and delete the very trusted isolator the
+   * refusal protected.
+   */
+  register(iso: Isolator, opts: IsolatorRegisterOptions = {}): boolean {
+    const trusted = opts.trusted ?? true;
+    if (!trusted && this.trustedNames.has(iso.name)) {
+      // A discovered plugin must not shadow a trusted isolator: that would let
+      // it silently weaken an isolation boundary the user already opted into.
+      opts.logger?.warn(
+        'IsolatorRegistry: refusing to let a discovered plugin shadow a trusted isolator',
+        { name: iso.name },
+      );
+      return false;
+    }
+    if (this.impls.has(iso.name) && !trusted) {
+      // Replacing an existing (untrusted) entry from another discovered copy:
+      // allowed (same name → same role) but surfaced so it isn't silent.
+      opts.logger?.warn('IsolatorRegistry: a discovered isolator overwrote an existing name', {
+        name: iso.name,
+      });
+    }
     // Overwrite by name: an isolator may arrive via more than one path (a
     // bundled built-in AND a discovered copy). Same name → same role; last wins.
     this.impls.set(iso.name, iso);
+    if (trusted) this.trustedNames.add(iso.name);
+    return true;
   }
 
   unregister(name: string): void {
     this.impls.delete(name);
+    this.trustedNames.delete(name);
   }
 
   get(name: string): Isolator | undefined {