@moxxy/core 0.4.0 → 0.5.1

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']);
+  });
 });

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'));