@uniqbit/mate-core 0.15.1-canary.2 → 0.15.1-canary.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.1-canary.2",
+  "version": "0.15.1-canary.4",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/cli/commands/install.ts

@@ -9,6 +9,23 @@ import {
   resolveInstallContext,
 } from "../../lib/install";
 import { renderInstallExecution } from "../install-plan";
+import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
+import {
+  installDeclaredPlugins,
+  type PluginInstallResult,
+} from "../../tools/setup/dynamic-plugins/install";
+
+export function reportPluginInstallResults(results: PluginInstallResult[]): void {
+  for (const result of results) {
+    if (result.status === "failed") {
+      process.stderr.write(
+        `${frameworkCommandName()}: plugin "${result.package}" failed to install: ${result.error ?? "unknown error"}\n`,
+      );
+    } else if (result.status === "installed") {
+      console.log(`  installed plugin ${result.package}@${result.resolvedVersion}`);
+    }
+  }
+}
 
 function printPlanText(plan: Awaited<ReturnType<typeof inspectInstallPlan>>): void {
   if (plan.context.message) process.stderr.write(`${plan.context.message}\n\n`);
@@ -37,6 +54,15 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     process.exitCode = 1;
     return false;
   }
+  // Companion-declared plugins install first and hydrate into the registry
+  // before the plan is built, so one run goes install → load → plan and their
+  // own install requirements are part of the plan.
+  if (context.kind === "companion" && context.companionPath && context.config.plugins?.length) {
+    reportPluginInstallResults(
+      await installDeclaredPlugins(context.companionPath, context.config.plugins),
+    );
+    await hydrateDynamicPlugins({ companionPath: context.companionPath });
+  }
   const plan = await inspectInstallPlan(buildInstallPlan(context));
   const missing = plan.requirements.filter((item) => !item.satisfied);
   let execution: Awaited<ReturnType<typeof renderInstallExecution>>;

package/src/cli/main.ts

@@ -18,29 +18,29 @@ import { runUpdateCommand } from "./commands/update";
 import { runInstallCommand } from "./commands/install";
 import { inspectInstallPreflight } from "../lib/install";
 import { ensureUnambiguousCompanion } from "./commands/shared/companion-selection";
+import { hydrateDynamicPlugins } from "../tools/setup/dynamic-plugins/hydrate";
 import { findPluginCliCommand } from "./plugin-commands";
 import { usage } from "./usage";
 
-export function isInstallRecoveryCommand(command?: string, subcommand?: string): boolean {
-  return (
-    command === "install" ||
-    command === "update" ||
-    command === "doctor" ||
-    command === "help" ||
-    command === "--help" ||
-    command === "-h" ||
-    (command === "companion" && (subcommand === "setup" || subcommand === "link"))
-  );
+export interface GateNeeds {
+  /** Block the command while an enforced update is pending. */
+  updateGuard?: boolean;
+  /** Require an unambiguous companion (selection wizard on ambiguity) before dispatch. */
+  companion?: boolean;
+  /** Require a complete installation (install preflight) before dispatch. */
+  install?: boolean;
 }
 
 export interface MainDeps {
   ensureUnambiguousCompanion: typeof ensureUnambiguousCompanion;
   inspectInstallPreflight: typeof inspectInstallPreflight;
+  hydrateDynamicPlugins: typeof hydrateDynamicPlugins;
 }
 
 const mainDeps: MainDeps = {
   ensureUnambiguousCompanion,
   inspectInstallPreflight,
+  hydrateDynamicPlugins,
 };
 
 export async function main(argv = process.argv, deps: MainDeps = mainDeps): Promise<void> {
@@ -51,78 +51,118 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
     return;
   }
 
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    console.log(usage());
+    return;
+  }
+
+  // Companion-declared plugins register before cap-command detection so
+  // their commands route like compiled-in ones (including MCP servers whose
+  // command is their own cap subcommand). Diagnostics stay on stderr; a
+  // missing or ambiguous companion makes this a no-op.
+  await deps.hydrateDynamicPlugins();
+
   // Plugin commands (`mate cap <namespace> <command>`) own their stdout (an
   // MCP server speaks JSON-RPC over it), so banners and background chatter
   // are suppressed for them.
   const isPluginCommand =
     command === "cap" && findPluginCliCommand(subcommand, rest[0]) !== undefined;
-  if (!isPluginCommand) {
-    const updateStore = new UpdateStateStore();
-    scheduleBackgroundCheck(updateStore);
-    if (
-      !isInstallRecoveryCommand(command, subcommand) &&
-      (await enforceUpdateIfRequired(updateStore))
-    ) {
-      process.exitCode = 1;
-      return;
-    }
-    await showUpdateBannerIfAvailable(updateStore);
-  }
 
-  if (!command || command === "help" || command === "--help" || command === "-h") {
-    console.log(usage());
-    return;
-  }
-
-  if (!(await deps.ensureUnambiguousCompanion())) {
-    process.exitCode = 1;
-    return;
-  }
+  // Every dispatch case opens with a gate() call declaring what the command
+  // needs before it may run. Declared gates run in fixed order — update
+  // enforcement, companion selection, install preflight — and a blocked gate
+  // sets the exit code, so callers only need `if (!(await gate(...))) return`.
+  const gate = async (needs: GateNeeds): Promise<boolean> => {
+    if (!isPluginCommand) {
+      const updateStore = new UpdateStateStore();
+      scheduleBackgroundCheck(updateStore);
+      if (needs.updateGuard && (await enforceUpdateIfRequired(updateStore))) {
+        process.exitCode = 1;
+        return false;
+      }
+      await showUpdateBannerIfAvailable(updateStore);
+    }
 
-  if (!isInstallRecoveryCommand(command, subcommand)) {
-    const preflight = await deps.inspectInstallPreflight();
-    if (!preflight.ok) {
-      console.error(
-        `${frameworkCommandName()}: ${preflight.reason ?? "installation is incomplete"}`,
-      );
-      console.error(`Run \`${frameworkCommandName()} install\` before continuing.`);
+    if (needs.companion && !(await deps.ensureUnambiguousCompanion())) {
       process.exitCode = 1;
-      return;
+      return false;
     }
-  }
+
+    if (needs.install) {
+      const preflight = await deps.inspectInstallPreflight();
+      if (!preflight.ok) {
+        console.error(
+          `${frameworkCommandName()}: ${preflight.reason ?? "installation is incomplete"}`,
+        );
+        console.error(`Run \`${frameworkCommandName()} install\` before continuing.`);
+        process.exitCode = 1;
+        return false;
+      }
+    }
+
+    return true;
+  };
 
   switch (command) {
     case "install":
+      // Builds a companion-scoped context, so it needs an unambiguous
+      // companion — but must stay runnable when installation is incomplete.
+      if (!(await gate({ companion: true }))) return;
       await runInstallCommand(argv.slice(3));
       return;
     case "artifact":
+      if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
       await runArtifactCommand(subcommand, rest);
       return;
     case "companion":
+      switch (subcommand) {
+        // setup/link are recovery paths and must never be gated on the
+        // state they exist to repair.
+        case "setup":
+        case "link":
+          if (!(await gate({}))) return;
+          break;
+        // open/tui consume a companion context.
+        case "open":
+        case "tui":
+          if (!(await gate({ updateGuard: true, companion: true }))) return;
+          break;
+        // list and unknown subcommands (which fail inside the command).
+        default:
+          if (!(await gate({ updateGuard: true }))) return;
+      }
       await runCompanionCommand(subcommand, rest);
       return;
     case "claude":
+      if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
       await runLaunchClaudeCommand(argv.slice(3), { directPassthrough: true });
       return;
     case "opencode":
+      if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
       await runLaunchOpenCodeCommand(argv.slice(3), { directPassthrough: true });
       return;
     case "report":
+      if (!(await gate({ updateGuard: true }))) return;
       await runReportCommand(argv.slice(3));
       return;
     case "config":
+      if (!(await gate({ updateGuard: true }))) return;
       await runConfigCommand(argv.slice(3));
       return;
     case "doctor":
+      if (!(await gate({}))) return;
       await runDoctorCommand(argv.slice(3));
       return;
     case "cap":
+      if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
       await runCapCommand(subcommand, rest);
       return;
     case "update":
+      if (!(await gate({}))) return;
       await runUpdateCommand(argv.slice(3));
       return;
     default:
+      // Unknown commands fail fast: no case matched, so no gate ever ran.
       console.error(`Unknown command: ${command}`);
       console.error(usage());
       process.exitCode = 1;

package/src/index.ts

@@ -21,6 +21,16 @@ export {
   type NormalizedRegistration,
 } from "./tools/setup/registry";
 export { ensureCapabilityEnabled, type EnsureCapabilityEnabledDeps } from "./cli/plugin-commands";
+// Dynamic plugin authors: import from this package as TYPES ONLY. Runtime
+// imports resolve a second, uninitialized copy of mate-core inside the
+// plugin's own node_modules; all runtime behavior flows through PluginHost.
+export {
+  createPluginHost,
+  PLUGIN_API_VERSION,
+  SUPPORTED_PLUGIN_API_VERSIONS,
+  type CreatePlugin,
+  type PluginHost,
+} from "./tools/setup/dynamic-plugins/host";
 export type {
   CapabilityPlugin,
   InstructionsService,
@@ -36,4 +46,8 @@ export type {
   SetupContext,
   TemplatesService,
 } from "./tools/setup/plugin";
-export type { FrameworkConfig } from "./lib/orchestrator/types";
+export type {
+  FrameworkConfig,
+  PluginDeclaration,
+  PluginDeclarationPolicy,
+} from "./lib/orchestrator/types";

package/src/lib/orchestrator/config-store.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 import { FRAMEWORK_NAME } from "../../framework";
 import { getDefaultSetupSelections } from "./setup-compatibilities";
 import { YamlFileStore } from "./yaml-file-store";
-import { type FrameworkConfig } from "./types";
+import { ConfigError, type FrameworkConfig } from "./types";
 
 export const RTK_CAPABILITY_SPLIT_MIGRATION = "rtk-capability-split-v1";
 
@@ -54,6 +54,23 @@ export function migrateRtkCapabilitySplit(config: FrameworkConfig): FrameworkCon
   };
 }
 
+export const PLUGIN_DECLARATION_POLICIES = ["default", "optional"] as const;
+
+/**
+ * Validates the `plugins` list of a loaded config. Declared plugins may not
+ * claim `required` — required-ness is a distribution prerogative.
+ */
+export function validatePluginDeclarations(config: FrameworkConfig): void {
+  for (const declaration of config.plugins ?? []) {
+    const policy = declaration.policy as string | undefined;
+    if (policy !== undefined && !PLUGIN_DECLARATION_POLICIES.includes(policy as never)) {
+      throw new ConfigError(
+        `plugins entry "${declaration.package}": policy "${policy}" is not allowed for declared plugins (allowed: ${PLUGIN_DECLARATION_POLICIES.join(", ")}).`,
+      );
+    }
+  }
+}
+
 export class ConfigStore extends YamlFileStore<FrameworkConfig> {
   constructor(configPath = process.env.MATE_CONFIG ?? defaultConfigPath()) {
     super(path.resolve(configPath));
@@ -61,6 +78,7 @@ export class ConfigStore extends YamlFileStore<FrameworkConfig> {
 
   override async load(): Promise<FrameworkConfig> {
     const merged = mergeWithDefaults(await super.load());
+    validatePluginDeclarations(merged);
     const needsMigration = !(merged.migrations ?? []).includes(RTK_CAPABILITY_SPLIT_MIGRATION);
     const config = migrateRtkCapabilitySplit(merged);
     if (needsMigration) await this.save(config);

package/src/lib/orchestrator/types.ts

@@ -81,11 +81,34 @@ export interface CapabilityConfig {
  */
 export type EngineConstraints = Record<string, string>;
 
+/**
+ * Registration policy for a companion-declared plugin. `required` is a
+ * distribution prerogative and is rejected for declared plugins.
+ */
+export type PluginDeclarationPolicy = "default" | "optional";
+
+/**
+ * A companion-declared npm plugin: installed by setup/install into
+ * `.mate/dependencies/plugins/` and loaded on every invocation. Declaration
+ * registers the plugin; enablement stays in the `capabilities` list.
+ */
+export interface PluginDeclaration {
+  /** npm package name (e.g. `@acme/custom-plugin`). */
+  package: string;
+  /** Exact version, semver range, or the literal `latest`. */
+  version: string;
+  /** Registration policy; absent means `optional`. */
+  policy?: PluginDeclarationPolicy;
+  /** Opaque plugin parameters, passed to the plugin factory after resolution. */
+  config?: unknown;
+}
+
 export interface FrameworkConfig {
   type?: "working" | "companion";
   git?: GitModeProfile;
   profiles: Record<string, PolicyProfile>;
   capabilities?: CapabilityConfig[];
+  plugins?: PluginDeclaration[];
   migrations?: string[];
   cliTools?: CliToolConfig[];
   packageManagers?: string[];

package/src/lib/update-checker.ts

@@ -20,9 +20,24 @@ export const updateCheckerDeps = {
   toIsoString: () => new Date().toISOString(),
 };
 
+const updateStateFileSlug = (packageName: string): string =>
+  packageName.replace(/^@/, "").replace(/[^a-zA-Z0-9._-]+/g, "-");
+
+/**
+ * Every distribution built on mate-core shares `~/.mate`, but each checks its
+ * own update package — so the cached state is scoped per package. A shared
+ * file would let the default distribution's public-npm check poison a custom
+ * distribution's banner with a version it can never install.
+ */
 export class UpdateStateStore extends YamlFileStore<UpdateState> {
-  constructor() {
-    super(path.join(os.homedir(), `.${FRAMEWORK_NAME}`, "update-state.yaml"));
+  constructor(packageName: string = getUpdateConfig().packageName) {
+    super(
+      path.join(
+        os.homedir(),
+        `.${FRAMEWORK_NAME}`,
+        `update-state-${updateStateFileSlug(packageName)}.yaml`,
+      ),
+    );
   }
 
   protected onMissing(): Promise<UpdateState> {

package/src/templates/capabilities/openspec-cap/mate-v1/schema.yaml

@@ -272,4 +272,5 @@ apply:
   tracks: tasks.md
   instruction: |
     Read context files and work through pending tasks only within the proposal's affected Areas. Mark complete as you go.
+    When reporting information to me, be extremely concise and sacrifice grammar for the sake of concision. Apply this same preference to JSDoc.
     Pause if you hit blockers or need clarification.

package/src/templates/root/TEMPLATE_AGENTS.md

@@ -8,6 +8,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 ## Agent Notes
 
 - Use absolute paths when a tool needs a file path. Do not create literal `$MATE_REPO_PATH` or `$MATE_ARTIFACT_PATH` directories.
+- When reporting information to me, be extremely concise and sacrifice grammar for the sake of concision. Apply this same preference to JSDoc
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (`$MATE_REPO_PATH`) unless the user explicitly asks for it.
 

package/src/templates/root/TEMPLATE_CLAUDE.md

@@ -8,6 +8,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 ## Claude Notes
 
 - Use absolute paths when a tool needs a file path. Do not create literal `$MATE_REPO_PATH` or `$MATE_ARTIFACT_PATH` directories.
+- When reporting information to me, be extremely concise and sacrifice grammar for the sake of concision. Apply this same preference to JSDoc.
 - Claude Code receives `$MATE_ARTIFACT_PATH` via `--add-dir`; if `@` autocomplete does not show companion artifacts, reference them by absolute path.
 - The root `CLAUDE.md` in the companion repo is intentional and loaded by Mate. Do not create another project-level `CLAUDE.md` in the working repo unless the user explicitly asks for one.
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.

package/src/tools/setup/capabilities/tokensave.ts

@@ -16,10 +16,6 @@ const TOKENSAVE_CARGO_INSTALL_CMD = "cargo install tokensave";
 const TOKENSAVE_SCOOP_INSTALL_CMD =
   "scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucket && scoop install tokensave";
 
-function getTokensaveConfigPath(): string {
-  return path.join(process.env.HOME ?? "", ".tokensave", "config.toml");
-}
-
 interface CompanionOpenCodeSettings {
   mcp?: Record<string, unknown>;
   [key: string]: unknown;
@@ -132,47 +128,23 @@ async function tokensaveInstalled(repoPath: string): Promise<boolean> {
   return result.ok;
 }
 
-async function readTokensaveConfig(): Promise<string | null> {
-  try {
-    return await fs.readFile(getTokensaveConfigPath(), "utf8");
-  } catch {
-    return null;
-  }
-}
-
-async function writeTokensaveConfig(content: string): Promise<void> {
-  await fs.mkdir(path.dirname(getTokensaveConfigPath()), { recursive: true });
-  await fs.writeFile(getTokensaveConfigPath(), content, "utf8");
-}
-
-async function updateTokensaveInstalledAgents(providers: string[]): Promise<void> {
-  const content = await readTokensaveConfig();
-  if (!content) return;
-
+// Global agent integration (MCP entry, session hooks, wildcard permission grant, and
+// tokensave's own config bookkeeping) is owned by tokensave's installer — Mate never
+// hand-edits ~/.tokensave/config.toml. Runs in setup mode only; the installer is
+// idempotent, so re-running on every setup doubles as repair for stale global state.
+function installTokensaveAgentIntegrations(providers: string[], cwd: string): void {
   const agents = providers.filter((p) => TOKENSAVE_SUPPORTED_AGENTS.has(p)).sort();
-  if (agents.length === 0) return;
-
-  const existingLine = content.match(/^installed_agents\s*=\s*\[([^\]]*)\]/m);
-  if (!existingLine) return;
-
-  const existingStr = existingLine[1];
-  const existing = new Set(
-    existingStr
-      .split(",")
-      .map((s) => s.trim().replace(/^"|"$/g, ""))
-      .filter(Boolean),
-  );
-
   for (const agent of agents) {
-    existing.add(agent);
-  }
-
-  const sorted = [...existing].sort();
-  const newValue = `installed_agents = [${sorted.map((a) => `"${a}"`).join(", ")}]`;
-  const updated = content.replace(existingLine[0], newValue);
-
-  if (updated !== content) {
-    await writeTokensaveConfig(updated);
+    const result = tokensaveDeps.run(
+      ["install", "--agent", agent, "--git-hook", "no", "--wildcard-permissions"],
+      cwd,
+    );
+    if (!result.ok) {
+      const detail = result.stderr.trim();
+      process.stderr.write(
+        `tokensave: \`tokensave install --agent ${agent}\` failed${detail ? `: ${detail}` : ""} - continuing without global ${agent} integration\n`,
+      );
+    }
   }
 }
 
@@ -329,7 +301,9 @@ export function createTokensavePlugin(): CapabilityPlugin {
       if (!(await ensureTokensaveInstalled(targetPath))) {
         return;
       }
-      await updateTokensaveInstalledAgents(ctx.activeProviders);
+      if (ctx.mode === "setup") {
+        installTokensaveAgentIntegrations(ctx.activeProviders, targetPath);
+      }
     },
     async teardown(ctx) {
       if (!ctx.repoPath) return;

package/src/tools/setup/dynamic-plugins/config-resolution.ts

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+
+import { parse } from "yaml";
+
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { pluginLocalOverridesPath } from "./paths";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Deep-merges a local override over a committed plugin config: objects merge
+ * recursively, arrays and scalars from the override replace the committed
+ * value. Either side may be absent.
+ */
+export function deepMergePluginConfig(committed: unknown, override: unknown): unknown {
+  if (override === undefined) return committed;
+  if (!isRecord(committed) || !isRecord(override)) return override;
+  const merged: Record<string, unknown> = { ...committed };
+  for (const [key, value] of Object.entries(override)) {
+    merged[key] = deepMergePluginConfig(committed[key], value);
+  }
+  return merged;
+}
+
+const VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export interface InterpolationResult {
+  value: unknown;
+  /** Referenced-but-unset variable names, in first-seen order. */
+  missing: string[];
+}
+
+/**
+ * Replaces `${VAR}` occurrences in every string value with the corresponding
+ * environment value, recursively through objects and arrays. Unset variables
+ * are collected instead of substituted.
+ */
+export function interpolateEnvVars(
+  value: unknown,
+  env: Record<string, string | undefined>,
+): InterpolationResult {
+  const missing: string[] = [];
+  const visit = (node: unknown): unknown => {
+    if (typeof node === "string") {
+      return node.replace(VAR_PATTERN, (placeholder, name: string) => {
+        const resolved = env[name];
+        if (resolved === undefined) {
+          if (!missing.includes(name)) missing.push(name);
+          return placeholder;
+        }
+        return resolved;
+      });
+    }
+    if (Array.isArray(node)) return node.map(visit);
+    if (isRecord(node)) {
+      return Object.fromEntries(Object.entries(node).map(([key, entry]) => [key, visit(entry)]));
+    }
+    return node;
+  };
+  return { value: visit(value), missing };
+}
+
+/**
+ * Reads the gitignored `.mate/config/plugins.local.yaml`, a `plugins:` map
+ * keyed by package name. A missing or malformed file yields no overrides.
+ */
+export async function readLocalPluginOverrides(
+  companionPath: string,
+): Promise<Record<string, unknown>> {
+  try {
+    const raw = await fs.readFile(pluginLocalOverridesPath(companionPath), "utf8");
+    const parsed = parse(raw) as unknown;
+    if (!isRecord(parsed) || !isRecord(parsed.plugins)) return {};
+    return parsed.plugins;
+  } catch {
+    return {};
+  }
+}
+
+export type EffectivePluginConfigResult =
+  | { ok: true; config: unknown }
+  | { ok: false; missingVariables: string[] };
+
+/**
+ * Computes the config passed to a plugin factory: committed `config` block,
+ * deep-merged with the local override entry for the package, then `${VAR}`
+ * interpolated from the environment. Resolved values are never written back.
+ */
+export async function resolveEffectivePluginConfig(
+  companionPath: string,
+  declaration: PluginDeclaration,
+  env: Record<string, string | undefined> = process.env,
+): Promise<EffectivePluginConfigResult> {
+  const overrides = await readLocalPluginOverrides(companionPath);
+  const merged = deepMergePluginConfig(declaration.config, overrides[declaration.package]);
+  const { value, missing } = interpolateEnvVars(merged, env);
+  if (missing.length > 0) return { ok: false, missingVariables: missing };
+  return { ok: true, config: value };
+}

package/src/tools/setup/dynamic-plugins/host.ts

@@ -0,0 +1,51 @@
+import { getActiveDistribution } from "../../../distribution";
+import { ensureCapabilityEnabled } from "../../../cli/plugin-commands";
+import type { CapabilityPlugin, Plugin } from "../plugin";
+
+/** Host API version this core constructs. Grows only on breaking changes. */
+export const PLUGIN_API_VERSION = 1;
+
+/** Plugin API versions this core can load. */
+export const SUPPORTED_PLUGIN_API_VERSIONS: readonly number[] = [PLUGIN_API_VERSION];
+
+/**
+ * The sole runtime surface a dynamic plugin receives into the running core.
+ *
+ * Dynamic plugin packages must not import runtime values from
+ * `@uniqbit/mate-core` — a dynamically imported plugin would resolve a second
+ * bundled copy whose module-level state was never initialized. Type-only
+ * imports are safe (erased at build); all behavior flows through this host.
+ * The surface evolves additively within an `apiVersion`.
+ */
+export interface PluginHost {
+  apiVersion: typeof PLUGIN_API_VERSION;
+  /** Identity of the running distribution. */
+  distribution: { name: string; version: string };
+  /**
+   * Verifies the named capability is enabled for the active companion,
+   * reporting guidance and setting a failing exit code when it is not.
+   */
+  ensureCapabilityEnabled(name: string): Promise<boolean>;
+}
+
+/**
+ * The factory a dynamic plugin package exports — as the default export, or as
+ * a named `createPlugin` export when no default function exists. Called once
+ * per invocation with the plugin's effective config (committed block merged
+ * with local overrides, env-interpolated). Config validation is the plugin's
+ * responsibility: throw with a descriptive message to reject it.
+ */
+export type CreatePlugin = (config: unknown, host: PluginHost) => Plugin | CapabilityPlugin;
+
+/** Builds the host bound to the running core instance. */
+export function createPluginHost(): PluginHost {
+  const distribution = getActiveDistribution();
+  return {
+    apiVersion: PLUGIN_API_VERSION,
+    distribution: {
+      name: distribution.config.name,
+      version: distribution.config.version,
+    },
+    ensureCapabilityEnabled: (name) => ensureCapabilityEnabled(name),
+  };
+}

package/src/tools/setup/dynamic-plugins/hydrate.ts

@@ -0,0 +1,156 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { getActiveDistribution } from "../../../distribution";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../../../framework";
+import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver";
+import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
+import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { PluginRegistry } from "../registry";
+import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
+import { PluginPinStore } from "./pin-store";
+
+// Packages already registered in this process; re-hydration (e.g. right after
+// an install inside the same run) only picks up plugins that failed before.
+const hydratedPackages = new Set<string>();
+
+export function resetDynamicPluginHydration(): void {
+  hydratedPackages.clear();
+}
+
+export interface HydrateDynamicPluginsDeps extends DynamicPluginLoadDeps {
+  cwd?: string;
+  /** Explicit companion context; skips quiet resolution. */
+  companionPath?: string;
+  registry?: PluginRegistry;
+  warn?: (message: string) => void;
+}
+
+function commandName(): string {
+  try {
+    return frameworkCommandName();
+  } catch {
+    return FRAMEWORK_NAME;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Quiet variant of companion resolution: never prompts, never errors. An
+ * ambiguous or absent companion means hydration is a no-op —
+ * `ensureUnambiguousCompanion` later in `main()` stays the authoritative,
+ * user-facing resolution.
+ */
+async function resolveCompanionQuietly(
+  cwd: string,
+  env: Record<string, string | undefined>,
+): Promise<string | null> {
+  const pinned = env.MATE_ARTIFACT_PATH;
+  if (pinned) return path.resolve(pinned);
+  const resolver = new CompanionResolver(new GlobalConfigStore());
+  const resolution = await resolver.resolveWithDiagnostics(path.resolve(cwd));
+  if (resolution.ambiguousMatches.length > 1) return null;
+  if (resolution.match) return resolution.match.companionPath;
+  try {
+    // Running inside a companion directory itself.
+    await fs.access(path.join(cwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
+    return path.resolve(cwd);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Raw read of the companion's `plugins:` list. Deliberately avoids
+ * `ConfigStore.load()` — hydration runs on every invocation and must never
+ * create or migrate config files as a side effect.
+ */
+async function readDeclarations(companionPath: string): Promise<unknown[]> {
+  try {
+    const raw = await fs.readFile(
+      path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
+      "utf8",
+    );
+    const parsed = parse(raw) as unknown;
+    if (!isRecord(parsed) || !Array.isArray(parsed.plugins)) return [];
+    return parsed.plugins;
+  } catch {
+    return [];
+  }
+}
+
+function validateDeclaration(entry: unknown): { declaration?: PluginDeclaration; error?: string } {
+  if (!isRecord(entry) || typeof entry.package !== "string" || typeof entry.version !== "string") {
+    return { error: `ignoring malformed plugins entry: ${JSON.stringify(entry)}` };
+  }
+  const policy = entry.policy;
+  if (policy !== undefined && !PLUGIN_DECLARATION_POLICIES.includes(policy as never)) {
+    return {
+      error: `plugin "${entry.package}": policy "${String(policy)}" is not allowed for declared plugins (allowed: ${PLUGIN_DECLARATION_POLICIES.join(", ")}).`,
+    };
+  }
+  return { declaration: entry as unknown as PluginDeclaration };
+}
+
+/**
+ * Registers the companion's declared plugins into the active registry —
+ * compiled-in plugins first (they are already registered), declared order
+ * after. Runs before cap-command detection on every invocation. No-op
+ * without a companion or `plugins:` entries; all diagnostics go to stderr;
+ * never throws.
+ */
+export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}): Promise<void> {
+  const warn =
+    deps.warn ?? ((message: string) => process.stderr.write(`${commandName()}: ${message}\n`));
+  try {
+    const env = deps.env ?? process.env;
+    const companionPath =
+      deps.companionPath ?? (await resolveCompanionQuietly(deps.cwd ?? process.cwd(), env));
+    if (!companionPath) return;
+
+    const entries = await readDeclarations(companionPath);
+    if (entries.length === 0) return;
+
+    const pins = (await new PluginPinStore(companionPath).load()).plugins;
+    const registry = deps.registry ?? getActiveDistribution().registry;
+
+    for (const entry of entries) {
+      const { declaration, error } = validateDeclaration(entry);
+      if (!declaration) {
+        if (error) warn(error);
+        continue;
+      }
+      if (hydratedPackages.has(declaration.package)) continue;
+
+      // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
+      const result = await loadDynamicPlugin(companionPath, declaration, pins, deps);
+      if (!result.ok) {
+        warn(result.warning);
+        continue;
+      }
+
+      const namespace = result.plugin.cliNamespace ?? result.plugin.id;
+      const holder = registry
+        .getAll()
+        .find((existing) => (existing.cliNamespace ?? existing.id) === namespace);
+      if (holder) {
+        warn(
+          `plugin "${declaration.package}" ("${result.plugin.id}") claims cap namespace "${namespace}" already registered by "${holder.id}"; first registration wins.`,
+        );
+      }
+
+      registry.register({ plugin: result.plugin, policy: declaration.policy ?? "optional" });
+      hydratedPackages.add(declaration.package);
+    }
+  } catch (error) {
+    warn(
+      `dynamic plugin hydration failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/tools/setup/dynamic-plugins/install.ts

@@ -0,0 +1,171 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { pluginInstallDir, pluginPackageRoot } from "./paths";
+import { PluginPinStore, type PluginPin } from "./pin-store";
+
+export type BunInstallRunner = (
+  installDir: string,
+) => Promise<{ ok: boolean; detail?: string }> | { ok: boolean; detail?: string };
+
+export interface PluginInstallDeps {
+  runBunInstall?: BunInstallRunner;
+}
+
+export interface PluginInstallResult {
+  package: string;
+  status: "installed" | "unchanged" | "failed";
+  resolvedVersion?: string;
+  error?: string;
+}
+
+/** Runs `bun install` in the plugin workspace, honoring the user's ambient registry/auth config. */
+function defaultBunInstall(installDir: string): { ok: boolean; detail?: string } {
+  const result = spawnSync("bun", ["install", "--silent"], { cwd: installDir, encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    return {
+      ok: false,
+      detail:
+        result.error?.message ??
+        result.stderr?.trim() ??
+        `bun install exited with ${result.status}`,
+    };
+  }
+  return { ok: true };
+}
+
+async function readInstalledVersion(packageRoot: string): Promise<string | null> {
+  try {
+    const manifest = JSON.parse(
+      await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
+    ) as { version?: string };
+    return manifest.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Best-effort integrity extraction from bun's text lockfile. The lockfile is
+ * JSONC (trailing commas); package entries are tuples whose last string is
+ * the registry integrity hash. Absence is tolerated per spec.
+ */
+async function readIntegrityFromBunLock(
+  installDir: string,
+  packageName: string,
+): Promise<string | undefined> {
+  try {
+    const raw = await fs.readFile(path.join(installDir, "bun.lock"), "utf8");
+    const parsed = JSON.parse(raw.replace(/,(\s*[}\]])/g, "$1")) as {
+      packages?: Record<string, unknown>;
+    };
+    const entry = parsed.packages?.[packageName];
+    if (!Array.isArray(entry)) return undefined;
+    return entry.find(
+      (element): element is string => typeof element === "string" && element.startsWith("sha"),
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Installs each declared plugin into `.mate/dependencies/plugins/<sanitized>/`
+ * and records `{ package, declaredVersion, resolvedVersion, integrity }` in
+ * the committed pin file. Exact/range versions resolve once and stay pinned
+ * until the declaration changes; `latest` re-resolves on every run. Matching
+ * pinned installs are left untouched.
+ */
+export async function installDeclaredPlugins(
+  companionPath: string,
+  declarations: PluginDeclaration[],
+  deps: PluginInstallDeps = {},
+): Promise<PluginInstallResult[]> {
+  const runBunInstall = deps.runBunInstall ?? defaultBunInstall;
+  const pinStore = new PluginPinStore(companionPath);
+  const previousPins = (await pinStore.load()).plugins;
+  const nextPins: PluginPin[] = [];
+  const results: PluginInstallResult[] = [];
+
+  for (const declaration of declarations) {
+    const pin = previousPins.find((candidate) => candidate.package === declaration.package);
+    const installDir = pluginInstallDir(companionPath, declaration.package);
+    const packageRoot = pluginPackageRoot(companionPath, declaration.package);
+    // oxlint-disable-next-line no-await-in-loop -- installs mutate a shared pin file sequentially
+    const installedVersion = await readInstalledVersion(packageRoot);
+
+    const pinMatches =
+      declaration.version !== "latest" &&
+      pin !== undefined &&
+      pin.declaredVersion === declaration.version &&
+      installedVersion === pin.resolvedVersion;
+    if (pinMatches) {
+      nextPins.push(pin);
+      results.push({
+        package: declaration.package,
+        status: "unchanged",
+        resolvedVersion: pin.resolvedVersion,
+      });
+      continue;
+    }
+
+    // oxlint-disable-next-line no-await-in-loop
+    const result = await installOne(installDir, packageRoot, declaration, runBunInstall);
+    results.push(result);
+    if (result.status === "installed" && result.resolvedVersion) {
+      nextPins.push({
+        package: declaration.package,
+        declaredVersion: declaration.version,
+        resolvedVersion: result.resolvedVersion,
+        // oxlint-disable-next-line no-await-in-loop
+        integrity: await readIntegrityFromBunLock(installDir, declaration.package),
+      });
+    }
+  }
+
+  // Pins mirror the declaration list; undeclared packages drop out.
+  if (JSON.stringify(nextPins) !== JSON.stringify(previousPins)) {
+    await pinStore.save({ plugins: nextPins });
+  }
+  return results;
+}
+
+async function installOne(
+  installDir: string,
+  packageRoot: string,
+  declaration: PluginDeclaration,
+  runBunInstall: BunInstallRunner,
+): Promise<PluginInstallResult> {
+  try {
+    // Fresh workspace per (re)install so `latest` and edited declarations
+    // actually re-resolve instead of reusing a stale lockfile.
+    await fs.rm(installDir, { recursive: true, force: true });
+    await fs.mkdir(installDir, { recursive: true });
+    await fs.writeFile(
+      path.join(installDir, "package.json"),
+      JSON.stringify(
+        { private: true, dependencies: { [declaration.package]: declaration.version } },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+    const outcome = await runBunInstall(installDir);
+    if (!outcome.ok) {
+      throw new Error(outcome.detail ?? "bun install failed");
+    }
+    const resolvedVersion = await readInstalledVersion(packageRoot);
+    if (!resolvedVersion) {
+      throw new Error(`installed tree is missing ${declaration.package}/package.json`);
+    }
+    return { package: declaration.package, status: "installed", resolvedVersion };
+  } catch (error) {
+    return {
+      package: declaration.package,
+      status: "failed",
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/tools/setup/dynamic-plugins/loader.ts

@@ -0,0 +1,171 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { FRAMEWORK_NAME, frameworkCommandName } from "../../../framework";
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { Plugin } from "../plugin";
+import { resolveEffectivePluginConfig } from "./config-resolution";
+import {
+  createPluginHost,
+  SUPPORTED_PLUGIN_API_VERSIONS,
+  type CreatePlugin,
+  type PluginHost,
+} from "./host";
+import { pluginPackageRoot } from "./paths";
+import type { PluginPin } from "./pin-store";
+
+interface PluginManifest {
+  version?: string;
+  main?: string;
+  module?: string;
+  exports?: unknown;
+  mate?: { pluginApiVersion?: unknown };
+}
+
+export type DynamicPluginLoadResult = { ok: true; plugin: Plugin } | { ok: false; warning: string };
+
+export interface DynamicPluginLoadDeps {
+  env?: Record<string, string | undefined>;
+  importModule?: (specifier: string) => Promise<Record<string, unknown>>;
+  host?: PluginHost;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function commandName(): string {
+  try {
+    return frameworkCommandName();
+  } catch {
+    return FRAMEWORK_NAME;
+  }
+}
+
+function resolveEntryFromExports(exportsField: unknown): string | undefined {
+  if (typeof exportsField === "string") return exportsField;
+  if (!isRecord(exportsField)) return undefined;
+  const dot = "." in exportsField ? exportsField["."] : exportsField;
+  if (typeof dot === "string") return dot;
+  if (!isRecord(dot)) return undefined;
+  for (const condition of ["bun", "import", "default", "require"]) {
+    const candidate = dot[condition];
+    if (typeof candidate === "string") return candidate;
+    if (isRecord(candidate) && typeof candidate.default === "string") return candidate.default;
+  }
+  return undefined;
+}
+
+/**
+ * Loads one declared plugin from its installed tree: pin verification, API
+ * version gate before import, dynamic import, factory resolution, effective
+ * config, factory invocation. Every failure class returns a single warning
+ * instead of throwing, so one broken plugin never takes down the CLI.
+ */
+export async function loadDynamicPlugin(
+  companionPath: string,
+  declaration: PluginDeclaration,
+  pins: PluginPin[],
+  deps: DynamicPluginLoadDeps = {},
+): Promise<DynamicPluginLoadResult> {
+  const name = declaration.package;
+  const packageRoot = pluginPackageRoot(companionPath, name);
+
+  let manifest: PluginManifest;
+  try {
+    manifest = JSON.parse(
+      await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
+    ) as PluginManifest;
+  } catch {
+    return {
+      ok: false,
+      warning: `plugin "${name}" is not installed; run \`${commandName()} install\`.`,
+    };
+  }
+
+  const pin = pins.find((candidate) => candidate.package === name);
+  if (!pin) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" has no recorded pin; run \`${commandName()} install\`.`,
+    };
+  }
+  if (pin.declaredVersion !== declaration.version) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" declares version "${declaration.version}" but was pinned from "${pin.declaredVersion}"; run \`${commandName()} install\`.`,
+    };
+  }
+  if (manifest.version !== pin.resolvedVersion) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" has version ${manifest.version ?? "unknown"} installed but ${pin.resolvedVersion} pinned; run \`${commandName()} install\`.`,
+    };
+  }
+
+  // Version negotiation happens before any plugin code executes.
+  const apiVersion = manifest.mate?.pluginApiVersion ?? 1;
+  if (typeof apiVersion !== "number" || !SUPPORTED_PLUGIN_API_VERSIONS.includes(apiVersion)) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" requires plugin API version ${String(apiVersion)}; this CLI supports: ${SUPPORTED_PLUGIN_API_VERSIONS.join(", ")}.`,
+    };
+  }
+
+  const configResult = await resolveEffectivePluginConfig(companionPath, declaration, deps.env);
+  if (!configResult.ok) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" references unset environment variable${configResult.missingVariables.length > 1 ? "s" : ""}: ${configResult.missingVariables.join(", ")}.`,
+    };
+  }
+
+  const entryRelative =
+    resolveEntryFromExports(manifest.exports) ?? manifest.module ?? manifest.main ?? "index.js";
+  const entryPath = path.resolve(packageRoot, entryRelative);
+  const importModule =
+    deps.importModule ??
+    ((specifier: string) => import(specifier) as Promise<Record<string, unknown>>);
+
+  let moduleExports: Record<string, unknown>;
+  try {
+    moduleExports = await importModule(pathToFileURL(entryPath).href);
+  } catch (error) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" could not be imported: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  const factory =
+    typeof moduleExports.default === "function"
+      ? (moduleExports.default as CreatePlugin)
+      : typeof moduleExports.createPlugin === "function"
+        ? (moduleExports.createPlugin as CreatePlugin)
+        : undefined;
+  if (!factory) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" has no factory export; expected a default-exported function or a named createPlugin export.`,
+    };
+  }
+
+  let plugin: Plugin;
+  try {
+    plugin = factory(configResult.config, deps.host ?? createPluginHost());
+  } catch (error) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" rejected its configuration: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  if (!isRecord(plugin) || typeof plugin.id !== "string" || plugin.id.length === 0) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" returned an invalid plugin object (missing id).`,
+    };
+  }
+  return { ok: true, plugin };
+}

package/src/tools/setup/dynamic-plugins/paths.ts

@@ -0,0 +1,39 @@
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+
+/** Flattens an npm package name into a single directory segment. */
+export function sanitizePluginDirName(packageName: string): string {
+  return packageName.replace(/^@/, "").replace(/\//g, "-");
+}
+
+export function dynamicPluginsRoot(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "dependencies", "plugins");
+}
+
+/** Per-plugin install workspace holding a private package.json and node_modules. */
+export function pluginInstallDir(companionPath: string, packageName: string): string {
+  return path.join(dynamicPluginsRoot(companionPath), sanitizePluginDirName(packageName));
+}
+
+/** Root of the installed plugin package itself. */
+export function pluginPackageRoot(companionPath: string, packageName: string): string {
+  return path.join(
+    pluginInstallDir(companionPath, packageName),
+    "node_modules",
+    ...packageName.split("/"),
+  );
+}
+
+/** Committed pin file recording resolved plugin versions. */
+export function pluginPinFilePath(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "plugins.lock.yaml");
+}
+
+/** Gitignored per-machine override file deep-merged over committed plugin config. */
+export function pluginLocalOverridesPath(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "plugins.local.yaml");
+}
+
+/** Companion-relative gitignore entry for the local override file. */
+export const PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY = `.${FRAMEWORK_NAME}/config/plugins.local.yaml`;

package/src/tools/setup/dynamic-plugins/pin-store.ts

@@ -0,0 +1,30 @@
+import { YamlFileStore } from "../../../lib/orchestrator/yaml-file-store";
+import { pluginPinFilePath } from "./paths";
+
+/** Committed record of one declared plugin's resolved install. */
+export interface PluginPin {
+  package: string;
+  declaredVersion: string;
+  resolvedVersion: string;
+  integrity?: string;
+}
+
+export interface PluginPinFile {
+  plugins: PluginPin[];
+}
+
+export class PluginPinStore extends YamlFileStore<PluginPinFile> {
+  constructor(companionPath: string) {
+    super(pluginPinFilePath(companionPath));
+  }
+
+  override async load(): Promise<PluginPinFile> {
+    const parsed = await super.load();
+    return { plugins: Array.isArray(parsed?.plugins) ? parsed.plugins : [] };
+  }
+
+  protected onMissing(): Promise<PluginPinFile> {
+    // The pin file appears only once install records a resolved plugin.
+    return Promise.resolve({ plugins: [] });
+  }
+}

package/src/tools/setup/plugins/gitignore.ts

@@ -1,4 +1,6 @@
 import { getActiveDistribution } from "../../../distribution";
+import { FRAMEWORK_NAME } from "../../../framework";
+import { PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY } from "../dynamic-plugins/paths";
 import type { Plugin, SetupContext } from "../plugin";
 
 const MANAGED_START = (name: string) => `# ${name} managed: start`;
@@ -55,9 +57,24 @@ export async function writeManagedGitignoreBlock(
 }
 
 export function collectManagedGitignoreEntries(ctx: SetupContext, plugins: Plugin[]): string[] {
-  return plugins
-    .filter((p) => p.kind !== "root" && (p.isEnabled(ctx.config) || p.persistGitignoreEntries))
-    .flatMap((p) => p.gitignoreEntries?.(ctx) ?? []);
+  // Baseline for every companion: node_modules never versions wherever a tool
+  // materializes it, and everything under the dependencies tree (dynamic
+  // plugins, context-mode, future consumers) is regenerated by setup/install —
+  // version pins live in .mate/config and in code, never in the tree itself.
+  const entries = [
+    "node_modules/",
+    `.${FRAMEWORK_NAME}/dependencies/`,
+    ...plugins
+      .filter((p) => p.kind !== "root" && (p.isEnabled(ctx.config) || p.persistGitignoreEntries))
+      .flatMap((p) => p.gitignoreEntries?.(ctx) ?? []),
+  ];
+  // Dynamic-plugin loading artifacts: the local override file never versions;
+  // the pin file (plugins.lock.yaml) stays committed and is deliberately not
+  // listed here.
+  if (ctx.config.plugins?.length) {
+    entries.push(PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY);
+  }
+  return entries;
 }
 
 export function createGitignorePlugin(

package/src/tools/setup.ts

@@ -31,6 +31,8 @@ import { createUvPlugin } from "./setup/package-managers/uv";
 import type { PackageManagerSetupDeps } from "./setup/package-managers/uv";
 import { applyRequiredSelectionsToConfig } from "./setup/policy";
 import { invalidateInstallState } from "../lib/install";
+import { hydrateDynamicPlugins } from "./setup/dynamic-plugins/hydrate";
+import { installDeclaredPlugins } from "./setup/dynamic-plugins/install";
 import {
   buildSetupInstallationPlan,
   executeSetupInstallationPlan,
@@ -181,6 +183,19 @@ export async function executeSetup(
   await configStore.save(config);
 
   const companionPath = path.resolve(cwd);
+  // Declared plugin packages install and hydrate before the setup plan runs,
+  // so a fresh clone reaches a fully applied state from one setup run
+  // (install → load → plan).
+  if (config.plugins?.length) {
+    for (const result of await installDeclaredPlugins(companionPath, config.plugins)) {
+      if (result.status === "failed") {
+        process.stderr.write(
+          `${FRAMEWORK_NAME}: plugin "${result.package}" failed to install: ${result.error ?? "unknown error"}\n`,
+        );
+      }
+    }
+    await hydrateDynamicPlugins({ companionPath });
+  }
   await applySetupCompatibilities(companionPath, config, "setup");
   await invalidateInstallState({ kind: "companion", companionPath });