@uniqbit/mate-core 0.18.1-canary.0 → 0.18.1-canary.1

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.18.1-canary.0",
+  "version": "0.18.1-canary.1",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uniqbit-ag/mate-cli.git",
+    "directory": "packages/mate-core"
+  },
   "files": [
     "src/",
     "wrappers/",

package/src/cli/commands/artifact/finish/git.ts

@@ -2,6 +2,8 @@ import fs from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 
+import { runPreferringSsh, type GitResult } from "../../../../runtime/companion-git";
+
 export interface RebaseResult {
   ok: boolean;
   conflictedPaths: string[];
@@ -46,7 +48,7 @@ export interface GitOps {
 
 function gitRun(
   companionPath: string,
-  args: string[],
+  args: readonly string[],
 ): { status: number; out: string; err: string } {
   const {
     GIT_DIR: _gitDir,
@@ -112,7 +114,13 @@ export function defaultGitOps(
   workingRepoPath = process.env.MATE_REPO_PATH,
 ): GitOps {
   assertSafeCompanionRoot(companionPath, workingRepoPath);
-  const exec = (args: string[]) => gitRun(companionPath, args);
+  const exec = (args: readonly string[]) => gitRun(companionPath, args);
+  const toResult = (res: ReturnType<typeof exec>): GitResult => ({
+    status: res.status,
+    stdout: res.out,
+    stderr: res.err,
+  });
+  const execNetwork = (args: string[]) => runPreferringSsh(exec, args, toResult);
   const execOrThrow = (args: string[]) => {
     const res = exec(args);
     if (res.status !== 0) {
@@ -185,7 +193,8 @@ export function defaultGitOps(
       return exec(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]).status === 0;
     },
     async fetch() {
-      execOrThrow(["fetch"]);
+      const res = execNetwork(["fetch"]);
+      if (res.status !== 0) throw new Error(`git fetch failed: ${res.err || res.out}`);
     },
     async rebaseOntoUpstream() {
       const res = exec(["rebase", "--autostash", "@{u}"]);
@@ -205,7 +214,7 @@ export function defaultGitOps(
       execOrThrow(["tag", "-a", name, "-m", message]);
     },
     async push() {
-      const res = exec(["push", "--follow-tags"]);
+      const res = execNetwork(["push", "--follow-tags"]);
       return { ok: res.status === 0, error: res.err || res.out };
     },
   };

package/src/cli/commands/companion/link.ts

@@ -19,6 +19,7 @@ import { runSetupFlowAtPath } from "../setup";
 import { runInstallCommand } from "../install";
 import type { CompanionSource, LinkedRepository } from "../../../lib/orchestrator/types";
 import { invalidateInstallState } from "../../../lib/install";
+import { toSshUrl } from "../../../runtime/companion-git";
 
 interface CompanionLinkCommandDeps {
   selectCompanionLinkInputs?: (
@@ -61,23 +62,6 @@ export async function runCompanionLinkCommand(argv: string[]): Promise<void> {
   return companionLinkCommandDeps.runCompanionLinkCommandWithDeps(argv);
 }
 
-function toSshUrl(url: string): string | null {
-  try {
-    const parsed = new URL(url.trim());
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
-    if (!parsed.hostname || parsed.pathname === "/") return null;
-
-    const repositoryPath = parsed.pathname.replace(/^\/+/, "");
-    if (!repositoryPath) return null;
-
-    // Keep the usual scp-style form when no SSH port is specified.
-    if (!parsed.port) return `git@${parsed.hostname}:${repositoryPath}`;
-    return `ssh://git@${parsed.hostname}:${parsed.port}/${repositoryPath}`;
-  } catch {
-    return null;
-  }
-}
-
 function exitWithError(message: string): never {
   process.stderr.write(`${message}\n`);
   process.exit(1);

package/src/cli/commands/install.ts

@@ -19,6 +19,7 @@ import {
   FrozenInstallError,
   installDeclaredPluginsFrozen,
 } from "../../tools/setup/dynamic-plugins/frozen";
+import { verifyTrackedPluginOutputs } from "../../tools/setup/dynamic-plugins/staging";
 import { verifyDeclaredPlugins } from "../../tools/setup/dynamic-plugins/verify";
 
 export function reportPluginInstallResults(results: PluginInstallResult[]): boolean {
@@ -158,7 +159,22 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
   }
 
   try {
-    await reconcileInstalledCompanion(plan);
+    if (frozen && plan.context.companionPath) {
+      const { syncCompanionFiles } = await import("../../tools/setup");
+      const drift = await verifyTrackedPluginOutputs(plan.context.companionPath, (staged) =>
+        syncCompanionFiles(staged, plan.context.config),
+      );
+      if (drift.length > 0) {
+        process.stderr.write(
+          `${FRAMEWORK_NAME}: plugin-generated files differ from the committed checkout: ${drift.join(", ")}\n` +
+            `Prepare and commit them in the companion's authoring flow; the checkout was left unchanged.\n`,
+        );
+        process.exitCode = 1;
+        return false;
+      }
+    } else {
+      await reconcileInstalledCompanion(plan);
+    }
     await saveCompleteInstallState(plan, execution.results);
   } catch (error) {
     process.stderr.write(

package/src/cli/commands/plugin/plugin.ts

@@ -11,7 +11,7 @@ export async function runPluginCommand(
       await runPluginInstallCommand(argv);
       return;
     case "verify":
-      await runPluginVerifyCommand(argv);
+      await runPluginVerifyCommand();
       return;
     default:
       console.error(`Unknown plugin command: ${subcommand ?? ""}`);

package/src/cli/commands/plugin/verify.ts

@@ -1,22 +1,19 @@
 import { FRAMEWORK_NAME } from "../../../framework";
 import { resolveInstallContext } from "../../../lib/install";
-import { inspectDeclaredPlugins } from "../../../tools/setup/dynamic-plugins/verify";
+import { verifyDeclaredPlugins } from "../../../tools/setup/dynamic-plugins/verify";
 
 /**
  * @command mate plugin verify
- * @description Strict, installation-free check that every plugin declared by the companion is installed, and loadable with the current environment. Exits non-zero naming each failing package. With `--json`, prints `{"capabilities": [...]}` listing the capability IDs the verified plugins provide.
+ * @description Strict, installation-free check that every plugin declared by the companion is allowed by `MATE_ALLOWED_PLUGINS`, installed, and loadable with the current environment. Exits non-zero naming each failing package.
  */
-export async function runPluginVerifyCommand(
-  argv: string[] = [],
-  cwd = process.cwd(),
-): Promise<boolean> {
+export async function runPluginVerifyCommand(cwd = process.cwd()): Promise<boolean> {
   const context = await resolveInstallContext(cwd);
   if ((context.kind !== "companion" && context.kind !== "hub") || !context.companionPath) {
     process.stderr.write(`${FRAMEWORK_NAME}: \`plugin verify\` requires a companion context.\n`);
     process.exitCode = 1;
     return false;
   }
-  const { failures, capabilities } = await inspectDeclaredPlugins(context.companionPath);
+  const failures = await verifyDeclaredPlugins(context.companionPath);
   for (const failure of failures) {
     process.stderr.write(`${FRAMEWORK_NAME}: plugin ${failure.package}: ${failure.reason}\n`);
   }
@@ -24,6 +21,5 @@ export async function runPluginVerifyCommand(
     process.exitCode = 1;
     return false;
   }
-  if (argv.includes("--json")) process.stdout.write(`${JSON.stringify({ capabilities })}\n`);
   return true;
 }

package/src/cli/commands/studio/terminal-launch.ts

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
@@ -27,56 +26,11 @@ export async function launchableAgents(
   return TERMINAL_AGENTS.filter((agent) => allowed.includes(agent) && installed(agent));
 }
 
-/** Lowercase letters, digits and hyphens, so a name can never carry shell syntax or a flag. */
-export const AGENT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
-
-const AGENT_DEFINITION_DIRS: Record<TerminalAgent, string> = {
-  claude: path.join(".claude", "agents"),
-  opencode: path.join(".opencode", "agents"),
-};
-
-export interface DefaultAgentOutcome {
-  agentArgs?: string[];
-  notice?: string;
-}
-
-/**
- * The companion's `studio.terminal.agent` for one provider. Never throws and
- * never echoes the configured value into the notice.
- */
-export async function defaultAgentFor(
-  companionPath: string,
-  agent: TerminalAgent,
-): Promise<DefaultAgentOutcome> {
-  const configPath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
-  if (!fs.existsSync(configPath)) return {};
-  let name: unknown;
-  try {
-    name = (await new ConfigStore(configPath).load()).studio?.terminal?.agent;
-  } catch {
-    return {};
-  }
-  if (name === undefined || name === null) return {};
-  if (typeof name !== "string" || !AGENT_NAME_PATTERN.test(name)) {
-    return {
-      notice: "Default agent not applied: studio.terminal.agent is not a valid agent name.",
-    };
-  }
-  const definition = path.join(companionPath, AGENT_DEFINITION_DIRS[agent], `${name}.md`);
-  if (!fs.existsSync(definition)) {
-    return {
-      notice: `Default agent "${name}" not applied: this companion has no ${agent} definition for it.`,
-    };
-  }
-  return { agentArgs: ["--agent", name] };
-}
-
 export interface LaunchResolverOptions {
   collectInventory: () => Promise<StudioInventory>;
   /** Pinned by `serve --companion`; overrides the page selection. */
   launchCompanion?: string | null;
   launchableAgents?: (companionPath: string) => Promise<TerminalAgent[]>;
-  defaultAgent?: (companionPath: string, agent: TerminalAgent) => Promise<DefaultAgentOutcome>;
 }
 
 /** The companion a launch targets: the pinned one, else the page's, both read from the current inventory. */
@@ -96,7 +50,6 @@ export function createLaunchResolver(
   options: LaunchResolverOptions,
 ): (agent: string, digest: string | null) => Promise<TerminalLaunchResolution> {
   const agents = options.launchableAgents ?? launchableAgents;
-  const defaultAgent = options.defaultAgent ?? defaultAgentFor;
   return async (agent, digest) => {
     const companion = await effectiveLaunchCompanion(
       await options.collectInventory(),
@@ -113,9 +66,6 @@ export function createLaunchResolver(
     if (!(await agents(companion.path)).includes(agent as TerminalAgent)) {
       return { reason: `${agent} is not allowed by this companion or is not installed` };
     }
-    return {
-      companionPath: companion.path,
-      ...(await defaultAgent(companion.path, agent as TerminalAgent)),
-    };
+    return { companionPath: companion.path };
   };
 }

package/src/cli/commands/studio/terminal.ts

@@ -177,15 +177,7 @@ export interface TerminalSessionInfo {
   startedAt: number;
 }
 
-export type TerminalLaunchResolution =
-  | {
-      companionPath: string;
-      /** Extra argv entries for the managed launch; set only by companion configuration. */
-      agentArgs?: string[];
-      /** Written to the terminal before the agent starts. */
-      notice?: string;
-    }
-  | { reason: string };
+export type TerminalLaunchResolution = { companionPath: string } | { reason: string };
 
 export interface TerminalRegistryOptions {
   detachMs: number;
@@ -396,7 +388,7 @@ export class TerminalRegistry {
       void this.finish(detached, { type: "ended", reason: "evicted" });
     }
 
-    const session = this.launch(agent, resolved.companionPath, size, resolved);
+    const session = this.launch(agent, resolved.companionPath, size);
     this.attachTo(connection, session, size);
   }
 
@@ -404,7 +396,6 @@ export class TerminalRegistry {
     agent: TerminalAgent,
     companionPath: string,
     size: { cols: number; rows: number },
-    extras: { agentArgs?: string[]; notice?: string } = {},
   ): Session {
     const env: Record<string, string> = {};
     for (const [key, value] of Object.entries(this.options.env ?? process.env)) {
@@ -422,7 +413,6 @@ export class TerminalRegistry {
       "--companion",
       "--yes",
       ...(this.options.noGit ? ["--no-git"] : []),
-      ...(extras.agentArgs ?? []),
     ];
 
     const session = {
@@ -437,7 +427,6 @@ export class TerminalRegistry {
       ending: null,
       exited: false,
     } as Omit<Session, "process"> as Session;
-    if (extras.notice) session.ring.push(new TextEncoder().encode(`${extras.notice}\r\n`));
     session.process = this.spawn({
       argv,
       cwd: companionPath,

package/src/lib/orchestrator/companion-git-sync.ts

@@ -10,7 +10,10 @@ import {
   gitEnvironment,
   isAuthenticationFailure,
   outputLines,
+  REMOTE_URLS_QUERY,
   resolveUpstreamTargetWith,
+  shouldRetryWithoutSsh,
+  sshRewriteArgs,
   type GitResult,
 } from "../../runtime/companion-git";
 import { recordCompanionSync } from "../../runtime/companion-git-state";
@@ -172,11 +175,7 @@ export class CompanionGitSync {
     }
     const dirty = outputLines(before.stdout).length > 0;
 
-    const fetch = await this.command(
-      companionPath,
-      ["fetch", target.remote, target.branch],
-      interactiveGit ? "interactive" : undefined,
-    );
+    const fetch = await this.fetch(companionPath, target, interactiveGit);
     if (fetch.status !== 0) {
       const authenticationFailure = isAuthenticationFailure(fetch);
       const recovery = interactiveGit
@@ -248,6 +247,25 @@ export class CompanionGitSync {
     };
   }
 
+  /**
+   * SSH attempt stays captured: a failure there is expected noise, and SSH
+   * still prompts for passphrases or host keys on the terminal itself.
+   */
+  private async fetch(
+    companionPath: string,
+    target: SyncTarget,
+    interactiveGit: boolean,
+  ): Promise<GitCommandResult> {
+    const args = ["fetch", target.remote, target.branch];
+    const remotes = await this.command(companionPath, REMOTE_URLS_QUERY);
+    const rewrite = remotes.status === 0 ? sshRewriteArgs(remotes.stdout) : [];
+    if (rewrite.length > 0) {
+      const overSsh = await this.command(companionPath, [...rewrite, ...args]);
+      if (!shouldRetryWithoutSsh(overSsh)) return overSsh;
+    }
+    return this.command(companionPath, args, interactiveGit ? "interactive" : undefined);
+  }
+
   private async mergeAndRestore(
     companionPath: string,
     target: SyncTarget,

package/src/lib/orchestrator/companion-hub.ts

@@ -17,6 +17,7 @@ import {
 import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
 import { applySetupCompatibilities } from "../../tools/setup";
 import { findRepoLocalRegistryFile } from "./repo-local-registry";
+import { runPreferringSsh, toSshUrl } from "../../runtime/companion-git";
 
 export interface GitCommandResult {
   status: number | null;
@@ -217,10 +218,15 @@ export async function materializeHubMember(
   await fs.mkdir(path.dirname(destination), { recursive: true });
   try {
     if (source.kind === "git") {
-      const args = ["clone"];
-      if (source.ref) args.push("--branch", source.ref);
-      args.push(source.url!, destination);
-      gitOutputOrThrow(git(hubPath, args), `Cloning ${source.url}`);
+      const branch = source.ref ? ["--branch", source.ref] : [];
+      const cloneFrom = (url: string) => git(hubPath, ["clone", ...branch, url, destination]);
+      const sshUrl = toSshUrl(source.url!);
+      let clone = sshUrl ? cloneFrom(sshUrl) : undefined;
+      if (!clone || clone.status !== 0) {
+        if (clone) await fs.rm(destination, { recursive: true, force: true });
+        clone = cloneFrom(source.url!);
+      }
+      gitOutputOrThrow(clone, `Cloning ${source.url}`);
     } else {
       await copyWithoutGit(source.path!, destination);
     }
@@ -288,7 +294,11 @@ async function syncHubMember(
     return { id: member.id, status: "dirty", message: "local changes must be resolved first" };
   }
 
-  const fetch = git(memberPath, ["fetch", "origin"]);
+  const fetch = runPreferringSsh(
+    (args) => git(memberPath, [...args]),
+    ["fetch", "origin"],
+    (result) => ({ ...result, status: result.status ?? 1 }),
+  );
   if (fetch.status !== 0) {
     return { id: member.id, status: "failed", message: fetch.stderr || "fetch failed" };
   }

package/src/lib/orchestrator/types.ts

@@ -120,11 +120,6 @@ export interface PluginDeclaration {
   config?: unknown;
 }
 
-export interface StudioTerminalConfig {
-  /** Persona selected with `--agent` when Studio's terminal starts a provider. */
-  agent?: string;
-}
-
 export interface FrameworkConfig {
   type?: FrameworkType;
   git?: GitModeProfile;
@@ -136,7 +131,6 @@ export interface FrameworkConfig {
   cliTools?: CliToolConfig[];
   packageManagers?: string[];
   engines?: EngineConstraints;
-  studio?: { terminal?: StudioTerminalConfig };
 }
 
 export interface CompanionRegistryConfig {

package/src/runtime/companion-git.ts

@@ -61,6 +61,72 @@ export function isAuthenticationFailure(result: GitResult): boolean {
   ].some((marker) => output.includes(marker));
 }
 
+/** `git@host:path` (`ssh://` when a port is given) for an HTTP(S) Git URL; `null` otherwise. */
+export function toSshUrl(url: string): string | null {
+  try {
+    const parsed = new URL(url.trim());
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    if (!parsed.hostname || parsed.pathname === "/") return null;
+
+    const repositoryPath = parsed.pathname.replace(/^\/+/, "");
+    if (!repositoryPath) return null;
+
+    if (!parsed.port) return `git@${parsed.hostname}:${repositoryPath}`;
+    return `ssh://git@${parsed.hostname}:${parsed.port}/${repositoryPath}`;
+  } catch {
+    return null;
+  }
+}
+
+/** Lists every configured remote URL, one `remote.<name>.<key> <url>` per line. */
+export const REMOTE_URLS_QUERY: readonly string[] = [
+  "config",
+  "--get-regexp",
+  String.raw`^remote\..+\.(url|pushurl)$`,
+];
+
+/**
+ * `-c url.<ssh>.insteadOf=<https>` per HTTP(S) remote in `REMOTE_URLS_QUERY`
+ * output, so one invocation reaches every remote over SSH without rewriting
+ * the stored configuration. Empty when no remote is HTTP(S).
+ */
+export function sshRewriteArgs(remoteUrlsOutput: string): string[] {
+  const urls = new Set(
+    outputLines(remoteUrlsOutput).flatMap((line) => {
+      const url = line.slice(line.indexOf(" ") + 1).trim();
+      return url ? [url] : [];
+    }),
+  );
+  return [...urls].flatMap((url) => {
+    const ssh = toSshUrl(url);
+    return ssh ? ["-c", `url.${ssh}.insteadOf=${url}`] : [];
+  });
+}
+
+/** A remote rejection is a verdict the configured URL would repeat; anything else may be SSH-only. */
+export function shouldRetryWithoutSsh(result: GitResult): boolean {
+  if (result.status === 0) return false;
+  return !/\[(?:remote )?rejected\]/.test(`${result.stderr}\n${result.stdout}`);
+}
+
+/**
+ * Runs a network command over SSH first when a remote is HTTP(S), then as
+ * configured. `run` is the caller's own Git driver.
+ */
+export function runPreferringSsh<R extends { status: number | null }>(
+  run: (args: readonly string[]) => R,
+  args: readonly string[],
+  toResult: (result: R) => GitResult,
+): R {
+  const remotes = toResult(run(REMOTE_URLS_QUERY));
+  const rewrite = remotes.status === 0 ? sshRewriteArgs(remotes.stdout) : [];
+  if (rewrite.length > 0) {
+    const overSsh = run([...rewrite, ...args]);
+    if (!shouldRetryWithoutSsh(toResult(overSsh))) return overSsh;
+  }
+  return run(args);
+}
+
 /**
  * Inherited `GIT_*` overrides would point Git at the session's own repository
  * rather than the companion, so they are stripped from every invocation.

package/src/runtime/companion-sync.ts

@@ -30,6 +30,7 @@ import {
   outputLines,
   resolveUpstreamTargetSync,
   runGitSync,
+  runPreferringSsh,
   type CompanionForkState,
 } from "./companion-git";
 import { hasLaunchEnvironment } from "./env";
@@ -130,10 +131,10 @@ export function syncCompanionUnattended(
     );
   }
 
-  const fetch = runGitSync(
-    companionPath,
+  const fetch = runPreferringSsh(
+    (args) => runGitSync(companionPath, args, remaining()),
     ["fetch", "--no-progress", target.remote, target.branch],
-    remaining(),
+    (result) => result,
   );
   if (fetch.status !== 0) {
     if (isAuthenticationFailure(fetch)) {

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

@@ -5,8 +5,14 @@ import path from "node:path";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
 import type { NpmInstallRunner, PluginInstallResult } from "./install";
 import { dynamicPluginsWorkspaceRoot } from "./paths";
-
-/** Raised before anything is installed: manifest or lockfile inputs are unusable. */
+import {
+  disallowedPluginMessage,
+  isPluginAllowed,
+  PluginPolicyError,
+  readPluginPolicy,
+} from "./policy";
+
+/** Raised before anything is installed: policy, manifest or lockfile inputs are unusable. */
 export class FrozenInstallError extends Error {}
 
 export interface FrozenInstallDeps {
@@ -106,7 +112,8 @@ async function treeMismatches(workspaceRoot: string, lock: Lockfile): Promise<st
 
 /**
  * Deployment restore: installs exactly what the committed lockfile records.
- * Inputs are validated before npm runs — the workspace manifest against the declarations, and the lockfile against the
+ * Inputs are validated before npm runs — the appliance allowlist, the
+ * workspace manifest against the declarations, and the lockfile against the
  * manifest — and neither tracked file is ever rewritten. An installed tree is
  * reused only when it matches the lockfile's versions and integrity.
  */
@@ -120,6 +127,20 @@ export async function installDeclaredPluginsFrozen(
   const desired: Record<string, string> = {};
   for (const declaration of sorted) desired[declaration.package] = declaration.version;
 
+  let policy: ReturnType<typeof readPluginPolicy>;
+  try {
+    policy = readPluginPolicy(deps.env ?? process.env);
+  } catch (error) {
+    if (error instanceof PluginPolicyError) throw new FrozenInstallError(error.message);
+    throw error;
+  }
+  const refused = sorted.filter((declaration) => !isPluginAllowed(policy, declaration.package));
+  if (refused.length > 0) {
+    throw new FrozenInstallError(
+      refused.map((declaration) => disallowedPluginMessage(declaration.package)).join("\n"),
+    );
+  }
+
   const manifestFile = path.join(workspaceRoot, "package.json");
   const lockFile = path.join(workspaceRoot, "package-lock.json");
   const [manifestText, lockText] = await Promise.all([readText(manifestFile), readText(lockFile)]);

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

@@ -14,6 +14,12 @@ import {
   type PluginHost,
 } from "./host";
 import { dynamicPluginsWorkspaceRoot, pluginPackageRoot } from "./paths";
+import {
+  disallowedPluginMessage,
+  isPluginAllowed,
+  PluginPolicyError,
+  readPluginPolicy,
+} from "./policy";
 
 interface PluginManifest {
   mate?: { pluginApiVersion?: unknown };
@@ -47,6 +53,16 @@ export async function loadDynamicPlugin(
   const name = declaration.package;
   const packageRoot = pluginPackageRoot(companionPath, name);
 
+  /** Fails closed: a malformed policy allows nothing. Checked before any plugin file is touched. */
+  try {
+    if (!isPluginAllowed(readPluginPolicy(deps.env ?? process.env), name)) {
+      return { ok: false, warning: `${disallowedPluginMessage(name)}; not loaded.` };
+    }
+  } catch (error) {
+    if (!(error instanceof PluginPolicyError)) throw error;
+    return { ok: false, warning: `plugin "${name}" not loaded: ${error.message}` };
+  }
+
   let manifest: PluginManifest;
   try {
     manifest = JSON.parse(

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

@@ -0,0 +1,55 @@
+/** Environment variable carrying the appliance's declared-plugin package allowlist. */
+export const ALLOWED_PLUGINS_ENV = "MATE_ALLOWED_PLUGINS";
+
+/**
+ * Parsed allowlist: exact package names and scope-wide `@scope/*` patterns.
+ * An empty list permits no package; the policy's absence permits all.
+ */
+export interface PluginPolicy {
+  exact: string[];
+  scopes: string[];
+}
+
+export class PluginPolicyError extends Error {}
+
+const EXACT_PATTERN = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const SCOPE_PATTERN = /^@[a-z0-9][a-z0-9._~-]*\/\*$/;
+
+/**
+ * Parses a comma-separated allowlist. `undefined` means no policy; an empty
+ * or blank string is an explicit empty policy. Malformed entries throw so a
+ * typo can never widen or silently narrow the trust decision.
+ */
+export function parseAllowedPlugins(raw: string | undefined): PluginPolicy | null {
+  if (raw === undefined) return null;
+  const policy: PluginPolicy = { exact: [], scopes: [] };
+  if (raw.trim() === "") return policy;
+  for (const part of raw.split(",")) {
+    const entry = part.trim();
+    if (SCOPE_PATTERN.test(entry)) policy.scopes.push(entry.slice(0, entry.indexOf("/") + 1));
+    else if (EXACT_PATTERN.test(entry)) policy.exact.push(entry);
+    else {
+      throw new PluginPolicyError(
+        `${ALLOWED_PLUGINS_ENV}: malformed entry ${JSON.stringify(entry)}; expected an exact package name or a scope pattern such as "@acme/*"`,
+      );
+    }
+  }
+  return policy;
+}
+
+/** Reads the effective policy from an environment; throws on a malformed value. */
+export function readPluginPolicy(
+  env: Record<string, string | undefined> = process.env,
+): PluginPolicy | null {
+  return parseAllowedPlugins(env[ALLOWED_PLUGINS_ENV]);
+}
+
+export function isPluginAllowed(policy: PluginPolicy | null, packageName: string): boolean {
+  if (policy === null) return true;
+  if (policy.exact.includes(packageName)) return true;
+  return policy.scopes.some((scope) => packageName.startsWith(scope));
+}
+
+export function disallowedPluginMessage(packageName: string): string {
+  return `plugin "${packageName}" is not allowed by ${ALLOWED_PLUGINS_ENV}`;
+}

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

@@ -0,0 +1,53 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export class TrackedOutputError extends Error {}
+
+export type StagedProjection = (stagingPath: string) => Promise<void>;
+
+function git(cwd: string, args: string[]): string {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    throw new TrackedOutputError(
+      `git ${args[0]} failed in ${cwd}: ${result.error?.message ?? result.stderr?.trim() ?? result.status}`,
+    );
+  }
+  return result.stdout;
+}
+
+function changedPaths(cwd: string): string[] {
+  return git(cwd, ["status", "--porcelain", "--untracked-files=all"])
+    .split("\n")
+    .filter((line) => line.trim() !== "")
+    .map((line) => line.slice(3));
+}
+
+/**
+ * Checks that what plugins would generate is already committed. The live
+ * checkout must have no edits of its own; the projection then runs against a
+ * disposable clone of its commit, and any file that differs afterwards is
+ * drift. Nothing is written back to the live checkout. Returns the drifting
+ * paths (empty when the checkout is complete).
+ */
+export async function verifyTrackedPluginOutputs(
+  companionPath: string,
+  project: StagedProjection,
+): Promise<string[]> {
+  const pending = changedPaths(companionPath);
+  if (pending.length > 0) {
+    throw new TrackedOutputError(
+      `the checkout has uncommitted changes, which frozen setup will not overwrite: ${pending.join(", ")}`,
+    );
+  }
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "mate-staging-"));
+  try {
+    const staged = path.join(root, "companion");
+    git(root, ["clone", "--quiet", "--no-hardlinks", companionPath, staged]);
+    await project(staged);
+    return changedPaths(staged);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+}

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

@@ -5,37 +5,38 @@ import type { PluginDeclaration } from "../../../lib/orchestrator/types";
 import { readDeclarations, validateDeclaration } from "./declarations";
 import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
 import { pluginPackageRoot } from "./paths";
+import {
+  disallowedPluginMessage,
+  isPluginAllowed,
+  PluginPolicyError,
+  readPluginPolicy,
+} from "./policy";
 
 export interface PluginVerificationFailure {
   package: string;
   reason: string;
 }
 
-export interface PluginInspection {
-  failures: PluginVerificationFailure[];
-  /** IDs of the capabilities the loaded plugins provide. */
-  capabilities: string[];
-}
-
 /**
- * Strict, installation-free check of every declared plugin: installed
+ * Strict, installation-free check of every declared plugin: allowed, installed
  * and loadable with the effective environment. Unlike hydration it fails
- * closed on the first-class problems ordinary commands only warn about.
+ * closed on the first-class problems ordinary commands only warn about. Only
+ * allowlisted packages are imported.
  */
 export async function verifyDeclaredPlugins(
   companionPath: string,
   deps: DynamicPluginLoadDeps = {},
 ): Promise<PluginVerificationFailure[]> {
-  return (await inspectDeclaredPlugins(companionPath, deps)).failures;
-}
-
-export async function inspectDeclaredPlugins(
-  companionPath: string,
-  deps: DynamicPluginLoadDeps = {},
-): Promise<PluginInspection> {
   const env = deps.env ?? process.env;
   const failures: PluginVerificationFailure[] = [];
-  const capabilities: string[] = [];
+  let policy: ReturnType<typeof readPluginPolicy>;
+  try {
+    policy = readPluginPolicy(env);
+  } catch (error) {
+    if (!(error instanceof PluginPolicyError)) throw error;
+    return [{ package: "(allowlist)", reason: error.message }];
+  }
+
   const declarations: PluginDeclaration[] = [];
   for (const entry of await readDeclarations(companionPath)) {
     const { declaration, error } = validateDeclaration(entry);
@@ -45,6 +46,10 @@ export async function inspectDeclaredPlugins(
 
   for (const declaration of declarations) {
     const name = declaration.package;
+    if (!isPluginAllowed(policy, name)) {
+      failures.push({ package: name, reason: disallowedPluginMessage(name) });
+      continue;
+    }
     // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
     const installed = await fs
       .access(pluginPackageRoot(companionPath, name))
@@ -60,7 +65,6 @@ export async function inspectDeclaredPlugins(
     // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
     const result = await loadDynamicPlugin(companionPath, declaration, { ...deps, env });
     if (!result.ok) failures.push({ package: name, reason: result.warning });
-    else if (result.plugin.kind === "capability") capabilities.push(result.plugin.id);
   }
-  return { failures, capabilities };
+  return failures;
 }