mulmoclaude 0.5.2 → 0.6.0

package/server/plugins/preset-list.ts

@@ -0,0 +1,52 @@
+// Preset plugins shipped with the repo (#1043 C-2 follow-up).
+//
+// Each entry is a published npm package that lives in mulmoclaude's
+// `node_modules`; the boot loader registers it through the same path
+// as a user-installed runtime plugin (workspace ledger), so the
+// frontend dynamic-import + Vue View pipeline runs end-to-end on
+// every fresh checkout — no manual `yarn plugin:install` needed for
+// testing or for first-launch UX.
+//
+// Presets and user-installed plugins share the runtime registry. On
+// tool-name collision the preset wins (loaded first; static MCP
+// built-ins still win over both).
+//
+// Adding a preset:
+//   1. `yarn add <package>` (or extend an existing dep)
+//   2. Append a row below
+//   3. Restart the server
+//
+// Removing a preset:
+//   1. Remove the row
+//   2. Optionally `yarn remove <package>`
+//   3. Restart
+
+export interface PresetPlugin {
+  /** npm package name (the directory under `node_modules`). */
+  packageName: string;
+}
+
+export const PRESET_PLUGINS: readonly PresetPlugin[] = [
+  // #1145 — runtime-plugin shape of the built-in todo plugin.
+  // Loaded as a preset (resolved via `node_modules/@mulmoclaude/todo-plugin/`
+  // through the yarn-workspaces symlink) so it boots on every fresh
+  // checkout. Owns `manageTodoList` end-to-end now that the static
+  // entry under `src/plugins/todo/` has been removed.
+  { packageName: "@mulmoclaude/todo-plugin" },
+  // #1162 — Spotify integration (Liked Songs / playlists / recently
+  // played). PR 1 ships OAuth + token persistence; PR 2 adds the
+  // listening-data kinds and the Vue View. Loaded the same way as
+  // todo-plugin via the workspace symlink at
+  // `node_modules/@mulmoclaude/spotify-plugin/`.
+  { packageName: "@mulmoclaude/spotify-plugin" },
+  // #1175 / #1169 PR-A — recipe-book runtime plugin. First slice of
+  // the Cooking Coach plugin set. Stores recipes as one markdown file
+  // per recipe under the plugin's `files.data` scope; demonstrates
+  // markdown-per-record storage on the v0.3 runtime API.
+  { packageName: "@mulmoclaude/recipe-book-plugin" },
+  // Encore plan PR 1 follow-up — dev-only debug playground plugin.
+  // Owns the standalone `/debug` page; the toolbar entry is gated on
+  // `VITE_DEV_MODE=1` so production builds hide the launcher button
+  // (the page itself is still reachable by typing the URL).
+  { packageName: "@mulmoclaude/debug-plugin" },
+];

package/server/plugins/preset-loader.ts

@@ -0,0 +1,112 @@
+// Preset plugin loader (#1043 C-2 follow-up).
+//
+// Reads `server/plugins/preset-list.ts` at boot and resolves each
+// entry against the package's installed location via Node's standard
+// module-resolution (`import.meta.resolve`). The package is already
+// laid out by `npm install` / `yarn install`; no tgz unpack step.
+// The result is the same `RuntimePlugin` shape user-installed plugins
+// produce, so both flows share the runtime registry, the dispatch
+// route, and the asset route.
+//
+// Why not a hardcoded `node_modules/<pkg>` join: yarn workspaces
+// hoist deps to the repo root, so the launcher sees the package in
+// `<repo>/node_modules/...` while `<repo>/packages/mulmoclaude/node_modules/`
+// is empty. `import.meta.resolve` walks the same way Node does at
+// runtime, so it finds the package wherever the package manager put
+// it. (npm's flat install doesn't have this issue — it lands under
+// `<package>/node_modules/...` directly. Both work with the same
+// resolver call.)
+//
+// Trust model: the package name comes from the server-side hardcoded
+// preset list, not from user input. We trust the resolved path
+// without an `ensureInsideBase` anchor because there is no base —
+// the resolver returns wherever the package manager chose. The asset
+// route's `realpathSync(plugin.cachePath)` still pins to whatever was
+// resolved here at registration time; a route caller cannot redirect
+// to a different path via URL params.
+//
+// Failures don't abort boot. A missing preset (install drift, rare)
+// logs a warning; healthy presets still register.
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PRESET_PLUGINS } from "./preset-list.js";
+import { loadPluginFromCacheDir, type LoaderDeps, type RuntimePlugin } from "./runtime-loader.js";
+import { log } from "../system/logger/index.js";
+
+const LOG_PREFIX = "plugins/preset";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+interface PackageJsonShape {
+  version?: string;
+}
+
+/** Resolve the on-disk root of a preset package by walking up from
+ *  this file looking for `<dir>/node_modules/<pkg>/`. Mirrors Node's
+ *  CommonJS resolution algorithm so it works in every layout the
+ *  installer might choose:
+ *
+ *    - yarn workspaces: deps hoisted to the repo root's `node_modules`
+ *    - npm flat install: package's `node_modules` directly
+ *    - npm nested install: under a parent package's `node_modules`
+ *
+ *  Why not `import.meta.resolve('<pkg>/package.json')`: many packages
+ *  (including `@gui-chat-plugin/*`) ship an `exports` field that
+ *  doesn't expose `./package.json`, so the ESM resolver throws
+ *  `ERR_PACKAGE_PATH_NOT_EXPORTED`. The walk-up sidesteps the
+ *  exports gate entirely. */
+function resolvePresetRoot(packageName: string): string | null {
+  let dir = __dirname;
+  while (true) {
+    const candidate = path.join(dir, "node_modules", packageName);
+    if (existsSync(path.join(candidate, "package.json"))) {
+      return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+async function loadOnePreset(packageName: string, deps: LoaderDeps = {}): Promise<RuntimePlugin | null> {
+  const cachePath = resolvePresetRoot(packageName);
+  if (!cachePath) {
+    log.warn(LOG_PREFIX, "preset package not resolvable — run `yarn install`?", { packageName });
+    return null;
+  }
+  const pkgJsonPath = path.join(cachePath, "package.json");
+  let pkg: PackageJsonShape;
+  try {
+    pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8")) as PackageJsonShape;
+  } catch (err) {
+    log.warn(LOG_PREFIX, "preset package.json read/parse failed", { packageName, error: String(err) });
+    return null;
+  }
+  const { version } = pkg;
+  if (typeof version !== "string" || version.length === 0) {
+    log.warn(LOG_PREFIX, "preset package has no version", { packageName });
+    return null;
+  }
+  return loadPluginFromCacheDir(packageName, version, cachePath, deps);
+}
+
+/** Load every preset declared in `server/plugins/preset-list.ts`.
+ *  Returns the loaded set; failures are logged and silently
+ *  skipped.
+ *
+ *  Pass `deps.runtimeFactory` from the parent server so factory-shape
+ *  presets get a real runtime; the MCP child can omit it (definition-
+ *  only). */
+export async function loadPresetPlugins(deps: LoaderDeps = {}): Promise<RuntimePlugin[]> {
+  if (PRESET_PLUGINS.length === 0) return [];
+  const loaded: RuntimePlugin[] = [];
+  for (const entry of PRESET_PLUGINS) {
+    const plugin = await loadOnePreset(entry.packageName, deps);
+    if (plugin) loaded.push(plugin);
+  }
+  log.info(LOG_PREFIX, "loaded", { requested: PRESET_PLUGINS.length, succeeded: loaded.length });
+  return loaded;
+}

package/server/plugins/runtime-chat-api.ts

@@ -0,0 +1,38 @@
+// Plugin-facing chat API. The host attaches a per-plugin instance of
+// `ChatRuntimeApi` to the `PluginRuntime` it constructs for each
+// plugin (`server/plugins/runtime.ts`).
+//
+// `start()` opens a normal chat seeded with a plugin-supplied first
+// message. The seed is persisted as the first user turn; Claude
+// responds to it as if the user had typed it. Pair the returned
+// `chatId` with `runtime.notifier.publish({ navigateTarget:
+// `/chat/${chatId}`, ... })` so the user can land on the chat from
+// the bell. The chat is permanent — appears in the user's chat list
+// like any other.
+//
+// Plugin authors access this surface via the `MulmoclaudeRuntime`
+// cast. See `runtime-tasks-api.ts` for the same pattern.
+
+export interface ChatStartInput {
+  /** First user turn. Phrase as the user would — Claude reads it as a
+   *  user instruction and responds. Visually marked as plugin-seeded
+   *  in the chat history so the user can tell it came from a plugin,
+   *  not from them. */
+  initialMessage: string;
+  /** Role to start the chat in. Defaults to `"general"`. */
+  role?: string;
+}
+
+export interface ChatStartResult {
+  /** New chat session id. Pair with notifier `navigateTarget` to send
+   *  the user there. */
+  chatId: string;
+}
+
+export interface ChatRuntimeApi {
+  /** Open a new chat seeded with `initialMessage` as the first user
+   *  turn. Returns the new chat session id. No cap on calls per
+   *  plugin. Throws if the underlying `startChat` fails (invalid
+   *  role, internal error). */
+  start: (input: ChatStartInput) => Promise<ChatStartResult>;
+}

package/server/plugins/runtime-loader.ts

@@ -0,0 +1,430 @@
+// Runtime plugin loader (#1043 C-2).
+//
+// At server boot:
+//   1. Read the install ledger (`plugins/plugins.json`).
+//   2. For each entry, ensure the tgz is extracted to
+//      `plugins/.cache/<name>/<version>/` (cache hit = skip).
+//   3. Dynamic-import the plugin's `dist/index.js` to pull out
+//      `TOOL_DEFINITION`. The plugin module is bundled (per the
+//      contract documented in `docs/plugin-development.md`) so its
+//      bare imports resolve against the on-disk chunk siblings, not
+//      against a non-existent `node_modules/` underneath the cache.
+//
+// This module is called from BOTH the parent server (`server/index.ts`)
+// and the spawned MCP child (`server/agent/mcp-server.ts`) — they share
+// the cache, so the second call is fast (no re-extract).
+//
+// Failures don't abort boot. A bad ledger entry, missing tgz, or a
+// definition that fails to import gets logged and skipped; healthy
+// plugins still load.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { PluginRuntime, ToolDefinition } from "gui-chat-protocol";
+import { isPluginFactory } from "gui-chat-protocol";
+import { WORKSPACE_PATHS } from "../workspace/paths.js";
+import { readLedger, type LedgerEntry } from "../utils/files/plugins-io.js";
+import { log } from "../system/logger/index.js";
+
+const LOG_PREFIX = "plugins/runtime";
+
+export interface RuntimePlugin {
+  /** npm package name, e.g. `@gui-chat-plugin/weather`. */
+  name: string;
+  /** Semver string from the tgz's `package.json`. */
+  version: string;
+  /** Absolute path to the extracted plugin directory under
+   *  `plugins/.cache/<name>/<version>/`. */
+  cachePath: string;
+  /** TOOL_DEFINITION export from the plugin's `dist/index.js`. The
+   *  shape matches static plugins in `plugin-names.ts`, so the same
+   *  MCP merge / dispatch path applies. */
+  definition: ToolDefinition;
+  /** Server-side handler the dispatch route calls. The convention
+   *  across @gui-chat-plugin packages is to export it under the same
+   *  key as `TOOL_DEFINITION.name` (e.g. weather → `fetchWeather`,
+   *  browse → `browse`); we capture it at load time so the dispatch
+   *  route doesn't have to re-resolve. The signature follows
+   *  gui-chat-protocol's `ToolPluginCore.execute`:
+   *  `(context: ToolContext, args) => Promise<ToolResult>` — context
+   *  first, args second. `null` means the module shipped a
+   *  TOOL_DEFINITION but no matching handler — the dispatch will 500
+   *  with a useful message. */
+  execute: ((context: unknown, args: unknown) => unknown) | null;
+  /** Optional short, URL-safe alias for the OAuth callback route
+   *  (#1162). When the plugin's module exports
+   *  `OAUTH_CALLBACK_ALIAS = "<alias>"`, the host registers
+   *  `/api/plugins/runtime/oauth-callback/<alias>` and forwards
+   *  `kind: "oauthCallback"` dispatch args to this plugin. The
+   *  package-name-in-path shape was rejected by Spotify Dashboard
+   *  because of the percent-encoded `@` / `/` characters, so OAuth
+   *  plugins declare a short alias (e.g. `"spotify"`) instead. Null
+   *  for non-OAuth plugins. */
+  oauthCallbackAlias: string | null;
+}
+
+interface PackageJson {
+  name?: string;
+  version?: string;
+  exports?: string | Record<string, unknown>;
+  main?: string;
+  module?: string;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null;
+
+const isToolDefinition = (value: unknown): value is ToolDefinition => {
+  if (!isRecord(value)) return false;
+  return typeof value.name === "string" && typeof value.description === "string";
+};
+
+/** Resolve the entry-point path from a plugin's `package.json`. Covers
+ *  the four legal `exports` shapes per the Node.js spec, then falls
+ *  through to `module` / `main` for legacy packages.
+ *
+ *  Legal `exports` forms (Node.js docs):
+ *    1. String sugar:     `"exports": "./index.js"`
+ *    2. Conditional root: `"exports": { "import": "./esm.js", … }`
+ *    3. Subpath map:      `"exports": { ".": "./index.js", "./util": "./util.js", … }`
+ *    4. Subpath + cond.:  `"exports": { ".": { "import": "./esm.js", "require": "./cjs.js" } }`
+ *
+ *  Earlier the loader only matched form (4) and fell straight through
+ *  to `module` / `main`. Real npm packages using forms (1)-(3) failed
+ *  to load (#1077 review). */
+function resolveEntrySpecifier(pkg: PackageJson): string | null {
+  const fromExports = resolveExportsField(pkg.exports);
+  if (fromExports) return fromExports;
+  if (typeof pkg.module === "string") return pkg.module;
+  if (typeof pkg.main === "string") return pkg.main;
+  return null;
+}
+
+function resolveExportsField(exportsField: PackageJson["exports"]): string | null {
+  // Form 1: top-level string sugar.
+  // Form A: array fallback chain (e.g. ["./dist/index.js", "./fallback.js"]).
+  // Form 2: conditional root (e.g. `{ import, require, default }`).
+  // Form 3 / 4: subpath map keyed by `.` — value can be a string,
+  //   array, or condition object (Codex review iter-2 on #1116).
+  const root = pickExportsTarget(exportsField);
+  if (root) return root;
+  if (isRecord(exportsField)) {
+    return pickExportsTarget(exportsField["."]);
+  }
+  return null;
+}
+
+/** Walk a Node.js `exports` value and return the first string entry
+ *  point this ESM loader can use. Handles every legal target shape:
+ *
+ *    - string: return it directly.
+ *    - array: try each element in order; first resolvable wins.
+ *      Per the spec arrays are a fallback chain — Node tries each
+ *      until one resolves on disk. We don't probe disk here, so
+ *      "first string-or-resolvable-condition" approximates that.
+ *    - condition object: prefer `import` (ESM-specific), then
+ *      `default` (universal fallback).
+ *    - everything else (e.g. only `require`, only nested arrays of
+ *      condition objects with no string targets): null. */
+function pickExportsTarget(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const resolved = pickExportsTarget(entry);
+      if (resolved) return resolved;
+    }
+    return null;
+  }
+  if (!isRecord(value)) return null;
+  // Condition object — `import` first (the ESM-specific condition
+  // match), then `default` (the universal fallback that "always
+  // matches" per the Node.js spec).
+  const fromImport = pickExportsTarget(value.import);
+  if (fromImport) return fromImport;
+  return pickExportsTarget(value.default);
+}
+
+/** Sentinel file written at the end of a successful extract. The
+ *  loader uses its presence (not just `existsSync(cachePath)`) as the
+ *  cache-validity check, so a partial extract (interrupted tar, ENOSPC
+ *  half-write) is detected and re-extracted on the next boot instead
+ *  of becoming a permanent broken state. */
+export const EXTRACT_MARKER = ".extract-complete";
+
+export function isCacheValid(cachePath: string): boolean {
+  return existsSync(path.join(cachePath, EXTRACT_MARKER));
+}
+
+/** Run `tar xzf` to extract a tgz into the version-keyed cache slot.
+ *  `--strip-components=1` drops the `package/` prefix that npm packs
+ *  add. `execFileSync` (not `execSync`) so paths bypass shell parsing
+ *  and never trip on metacharacters in workspace paths. Synchronous
+ *  because boot is single-threaded and the alternative (a stream
+ *  pipeline) adds dependencies for no benefit.
+ *
+ *  On failure, the partial directory is removed so the next boot
+ *  re-extracts cleanly (no sticky broken state). The completion
+ *  marker is written ONLY after tar exits 0 — readers should test
+ *  `isCacheValid()`, not `existsSync(cachePath)`. */
+function extractTgz(tgzAbs: string, destDir: string): void {
+  // Wipe any leftover from a previous failed extract before writing.
+  if (existsSync(destDir)) rmSync(destDir, { recursive: true, force: true });
+  mkdirSync(destDir, { recursive: true });
+  try {
+    execFileSync("tar", ["-xzf", tgzAbs, "-C", destDir, "--strip-components=1"], { stdio: "pipe" });
+    writeFileSync(path.join(destDir, EXTRACT_MARKER), "");
+  } catch (err) {
+    // Tear down the partial tree so isCacheValid() stays false next boot.
+    try {
+      rmSync(destDir, { recursive: true, force: true });
+    } catch {
+      // best-effort cleanup
+    }
+    throw err;
+  }
+}
+
+function readPackageJson(cachePath: string): PackageJson | null {
+  const pkgPath = path.join(cachePath, "package.json");
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf-8")) as PackageJson;
+  } catch (err) {
+    log.warn(LOG_PREFIX, "package.json read/parse failed", { path: pkgPath, error: String(err) });
+    return null;
+  }
+}
+
+/** Optional per-plugin runtime factory (#1110). When provided, plugins
+ *  whose `dist/index.js` exports a factory via `export default
+ *  definePlugin(...)` get the constructed runtime injected at load
+ *  time. When omitted, factory plugins are loaded with a stub runtime
+ *  whose handler call throws — fine for the MCP child process which
+ *  only needs `TOOL_DEFINITION` for `tools/list`; not OK for the
+ *  parent server which actually invokes the handler. The parent
+ *  always passes `runtimeFactory`; the child does not. */
+export interface LoaderDeps {
+  runtimeFactory?: (pkgName: string) => PluginRuntime;
+}
+
+/** Stub runtime — the factory pattern requires SOME runtime to call,
+ *  even if we only care about extracting `TOOL_DEFINITION`. Methods
+ *  throw rather than silently no-op so a plugin that mistakenly does
+ *  I/O at setup time fails loudly during boot instead of at first
+ *  call.
+ *
+ *  Two host extensions (`tasks`, `chat` — Phase 1 of the Encore plan)
+ *  are also stubbed here so plugins that destructure `runtime as
+ *  MulmoclaudeRuntime` and call `tasks.register(...)` at setup time
+ *  don't crash the definition-only load (e.g. the MCP child
+ *  extracting `tools/list`). `tasks.register` is a SILENT no-op
+ *  because tick registration is parent-only by design — the child
+ *  process has no task manager to register against. `chat.start`
+ *  matches the throw pattern of `fetch` / `files`, since starting a
+ *  chat is a parent-only side effect a plugin should never trigger
+ *  at setup time. The stub deliberately doesn't carry the
+ *  `MulmoclaudeRuntime` type — the cast lives at the plugin call
+ *  site (Phase 3 of Encore upstreams these into PluginRuntime). */
+function makeStubRuntime(name: string): PluginRuntime {
+  const error = (operation: string) => () => {
+    throw new Error(`plugin/${name}: runtime.${operation} unavailable in this process (definition-only load)`);
+  };
+  const fileOps = {
+    read: error("files.read"),
+    readBytes: error("files.readBytes"),
+    write: error("files.write"),
+    readDir: error("files.readDir"),
+    stat: error("files.stat"),
+    exists: error("files.exists"),
+    unlink: error("files.unlink"),
+  };
+  const stub = {
+    pubsub: { publish: () => undefined },
+    locale: "en",
+    files: { data: fileOps, config: fileOps },
+    log: { debug: () => undefined, info: () => undefined, warn: () => undefined, error: () => undefined },
+    fetch: error("fetch") as unknown as PluginRuntime["fetch"],
+    fetchJson: error("fetchJson") as unknown as PluginRuntime["fetchJson"],
+    notifier: {
+      publish: error("notifier.publish") as unknown as (...args: unknown[]) => Promise<{ id: string }>,
+      clear: error("notifier.clear") as unknown as (id: string) => Promise<void>,
+    },
+    tasks: {
+      // Silent no-op: definition-only loads (MCP child) shouldn't fail
+      // just because the plugin declared a tick at setup time.
+      register: () => undefined,
+    },
+    chat: {
+      start: error("chat.start") as unknown as (...args: unknown[]) => Promise<{ chatId: string }>,
+    },
+  };
+  // Returned typed as `PluginRuntime` — host extensions (notifier /
+  // tasks / chat) are accessed by plugins via the `MulmoclaudeRuntime`
+  // cast and thus aren't part of the stub's nominal type yet.
+  return stub as unknown as PluginRuntime;
+}
+
+/** Two carrier shapes (#1110 backward compatibility):
+ *
+ *   1. **Factory** (`export default definePlugin(setup)`) — `mod.default`
+ *      is a function. Call it with the plugin's runtime; the return
+ *      value carries `TOOL_DEFINITION` and the handler keyed by
+ *      `TOOL_DEFINITION.name`. Closure over runtime gives the handler
+ *      access to scoped pubsub / files / log without per-call context
+ *      threading.
+ *   2. **Legacy** (`export const TOOL_DEFINITION = ...; export async
+ *      function <name>(context, args) ...`) — `mod.TOOL_DEFINITION` and
+ *      `mod[<name>]` directly. Continues to work; existing
+ *      @gui-chat-plugin packages don't need to migrate.
+ */
+function resolveCarrier(name: string, mod: Record<string, unknown>, deps: LoaderDeps): { carrier: Record<string, unknown>; usingFactory: boolean } {
+  const defaultExport = mod.default;
+  if (isPluginFactory(defaultExport)) {
+    const runtime = deps.runtimeFactory ? deps.runtimeFactory(name) : makeStubRuntime(name);
+    return { carrier: defaultExport(runtime) as unknown as Record<string, unknown>, usingFactory: true };
+  }
+  return { carrier: mod, usingFactory: false };
+}
+
+/** Pull the executable from a carrier. Factory-shape handlers take
+ *  `(args)` only (runtime is closed over) so we wrap to discard the
+ *  legacy `context` arg the dispatch route passes. Legacy-shape
+ *  handlers keep the `(context, args)` signature unchanged. Returns
+ *  null when no function is exported under `definition.name` — the
+ *  plugin still appears in `tools/list` but dispatch logs + 500s. */
+function resolveExecute(
+  carrier: Record<string, unknown>,
+  definitionName: string,
+  usingFactory: boolean,
+): ((context: unknown, args: unknown) => unknown) | null {
+  const handler = carrier[definitionName];
+  if (typeof handler !== "function") return null;
+  if (usingFactory) {
+    const factoryHandler = handler as (args: unknown) => unknown;
+    return (_context, args) => factoryHandler(args);
+  }
+  return handler as (context: unknown, args: unknown) => unknown;
+}
+
+/** Read the optional `OAUTH_CALLBACK_ALIAS` named export. Validated
+ *  against `^[a-z0-9][a-z0-9-]{0,30}$` — short, lowercase,
+ *  URL-friendly, can't be `..` or contain `/`. A bad alias is logged
+ *  and ignored (the plugin still loads; just skips the OAuth route
+ *  registration). */
+const OAUTH_CALLBACK_ALIAS_RE = /^[a-z0-9][a-z0-9-]{0,30}$/;
+function resolveOauthCallbackAlias(name: string, mod: Record<string, unknown>): string | null {
+  const raw = mod.OAUTH_CALLBACK_ALIAS;
+  if (raw === undefined) return null;
+  if (typeof raw !== "string" || !OAUTH_CALLBACK_ALIAS_RE.test(raw)) {
+    log.warn(LOG_PREFIX, "OAUTH_CALLBACK_ALIAS export is not a valid alias — ignoring", { name, raw: String(raw) });
+    return null;
+  }
+  return raw;
+}
+
+/** Load a plugin from an already-extracted cache directory. Pure
+ *  function — accepts paths explicitly, so tests don't need a real
+ *  workspace. Returns null on any structural failure (missing
+ *  package.json, missing TOOL_DEFINITION, broken import); the caller
+ *  treats nulls as "skip". */
+export async function loadPluginFromCacheDir(name: string, version: string, cachePath: string, deps: LoaderDeps = {}): Promise<RuntimePlugin | null> {
+  const pkg = readPackageJson(cachePath);
+  if (!pkg) return null;
+  const entrySpec = resolveEntrySpecifier(pkg);
+  if (!entrySpec) {
+    log.warn(LOG_PREFIX, "no entry specifier in package.json — skipping", { name });
+    return null;
+  }
+  const entryAbs = path.join(cachePath, entrySpec);
+  try {
+    const mod = (await import(pathToFileURL(entryAbs).href)) as Record<string, unknown>;
+    const { carrier, usingFactory } = resolveCarrier(name, mod, deps);
+    const definition = carrier.TOOL_DEFINITION;
+    if (!isToolDefinition(definition)) {
+      log.warn(LOG_PREFIX, "no TOOL_DEFINITION export — skipping", { name, entrySpec, shape: usingFactory ? "factory" : "legacy" });
+      return null;
+    }
+    const execute = resolveExecute(carrier, definition.name, usingFactory);
+    if (!execute) {
+      log.warn(LOG_PREFIX, "no execute handler matching TOOL_DEFINITION.name — dispatch will fail", {
+        name,
+        expectedExport: definition.name,
+        shape: usingFactory ? "factory" : "legacy",
+      });
+    }
+    const oauthCallbackAlias = resolveOauthCallbackAlias(name, mod);
+    return { name, version, cachePath, definition, execute, oauthCallbackAlias };
+  } catch (err) {
+    log.error(LOG_PREFIX, "import failed", { name, entrySpec, error: String(err) });
+    return null;
+  }
+}
+
+/** Lexical anchor: confirm `candidate` resolves inside `base`. Catches
+ *  malformed ledger entries (`name` containing `../../etc`) before we
+ *  touch the disk. The asset route trusts registry membership, so a
+ *  registered cachePath that escaped the base would expose arbitrary
+ *  files via the unauthenticated GET — this check is the first
+ *  line of defence (defence-in-depth: realpath after extract is the
+ *  symlink-escape backstop). Exported for testing. */
+export function ensureInsideBase(candidate: string, base: string): boolean {
+  const resolvedCandidate = path.resolve(candidate);
+  const resolvedBase = path.resolve(base);
+  return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(resolvedBase + path.sep);
+}
+
+async function loadOne(entry: LedgerEntry, deps: LoaderDeps = {}): Promise<RuntimePlugin | null> {
+  const tgzAbs = path.join(WORKSPACE_PATHS.plugins, entry.tgz);
+  const cachePath = path.join(WORKSPACE_PATHS.pluginCache, entry.name, entry.version);
+  // Anchor checks BEFORE any disk probe (`existsSync` / `realpath`).
+  // The ledger has two separate user-controlled fields — `tgz` and
+  // (`name`, `version`) — and each joins against a different base
+  // (`WORKSPACE_PATHS.plugins` vs. `pluginCache`). Both must stay
+  // inside their respective bases; otherwise even a stat-only probe
+  // would touch a path outside the intended roots.
+  if (!ensureInsideBase(tgzAbs, WORKSPACE_PATHS.plugins)) {
+    log.warn(LOG_PREFIX, "ledger entry tgz escapes plugins root — skipping", { name: entry.name, tgz: entry.tgz });
+    return null;
+  }
+  if (!ensureInsideBase(cachePath, WORKSPACE_PATHS.pluginCache)) {
+    log.warn(LOG_PREFIX, "ledger entry escapes plugin cache root — skipping", {
+      name: entry.name,
+      version: entry.version,
+    });
+    return null;
+  }
+  if (!existsSync(tgzAbs)) {
+    log.warn(LOG_PREFIX, "tgz missing — skipping", { name: entry.name, tgz: entry.tgz });
+    return null;
+  }
+  if (!isCacheValid(cachePath)) {
+    try {
+      extractTgz(tgzAbs, cachePath);
+      log.info(LOG_PREFIX, "extracted", { name: entry.name, version: entry.version });
+    } catch (err) {
+      log.error(LOG_PREFIX, "extract failed", { name: entry.name, error: String(err) });
+      return null;
+    }
+  }
+  return loadPluginFromCacheDir(entry.name, entry.version, cachePath, deps);
+}
+
+/** Read the ledger and load every healthy plugin. Returns the loaded
+ *  set; failures are logged and silently skipped (see module
+ *  comment).
+ *
+ *  Pass `deps.runtimeFactory` from the parent server so factory-shape
+ *  plugins (`export default definePlugin(...)`) get a real runtime.
+ *  The MCP child can call without deps — its only consumer is
+ *  `tools/list` which needs `TOOL_DEFINITION` only. */
+export async function loadRuntimePlugins(deps: LoaderDeps = {}): Promise<RuntimePlugin[]> {
+  const entries = readLedger();
+  if (entries.length === 0) return [];
+  const loaded: RuntimePlugin[] = [];
+  for (const entry of entries) {
+    const plugin = await loadOne(entry, deps);
+    if (plugin) loaded.push(plugin);
+  }
+  log.info(LOG_PREFIX, "loaded", { requested: entries.length, succeeded: loaded.length });
+  return loaded;
+}