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

package/package.json

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

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

@@ -3,7 +3,7 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 
-import { frameworkConfig } from "../../../framework";
+import { FRAMEWORK_NAME } from "../../../framework";
 import {
   selectCompanionLinkInputs,
   type CompanionLinkInputs,
@@ -48,7 +48,7 @@ interface CompanionLinkCommandDeps {
 
 /** All companions surfaced by the "existing companion" picker live under this directory. */
 function companionsHomeDir(): string {
-  return path.join(os.homedir(), `.${frameworkConfig.name}`, "companions");
+  return path.join(os.homedir(), `.${FRAMEWORK_NAME}`, "companions");
 }
 
 function isInsideDir(parentDir: string, candidatePath: string): boolean {

package/src/cli/commands/config.ts

@@ -1,9 +1,9 @@
 import os from "node:os";
 import path from "node:path";
 import { execSync } from "node:child_process";
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 
-const getGlobalConfigDir = () => path.join(os.homedir(), `.${frameworkConfig.name}`);
+const getGlobalConfigDir = () => path.join(os.homedir(), `.${FRAMEWORK_NAME}`);
 
 /**
  * @command mate config

package/src/cli/commands/doctor.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME, frameworkConfig } from "../../framework";
 import { getActiveDistribution } from "../../distribution";
 import { CompanionResolver } from "../../lib/orchestrator/companion-resolver";
 import { CompanionStore, resolvePolicyFromConfig } from "../../lib/orchestrator/companion-store";
@@ -34,7 +34,7 @@ interface ToolCheck {
 }
 
 function storesForCompanion(companionPath: string): CompanionStores {
-  const configDir = path.join(companionPath, `.${frameworkConfig.name}`, "config");
+  const configDir = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config");
   return {
     configStore: new ConfigStore(path.join(configDir, "framework.yaml")),
     workingRepoStore: new WorkingRepoStore(path.join(configDir, "registry.yaml")),
@@ -42,7 +42,7 @@ function storesForCompanion(companionPath: string): CompanionStores {
 }
 
 async function hasLocalCompanionConfig(cwd: string): Promise<boolean> {
-  const localDir = path.join(cwd, `.${frameworkConfig.name}`);
+  const localDir = path.join(cwd, `.${FRAMEWORK_NAME}`);
   const localLegacyDirs = frameworkConfig.legacyNames.map((name) => path.join(cwd, `.${name}`));
   await migrateConfigDir(localDir, localLegacyDirs);
 

package/src/cli/commands/install.ts

@@ -1,4 +1,5 @@
 import { confirm } from "../confirm";
+import { frameworkCommandName } from "../../framework";
 import {
   buildInstallPlan,
   inspectInstallPlan,
@@ -44,7 +45,9 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     if (missing.length > 0 && !skipConfirm) {
       const ok = await confirm("Install the missing requirements? [y/N] ");
       if (!ok) {
-        process.stderr.write("Installation declined. Run `mate install --yes` to continue.\n");
+        process.stderr.write(
+          `Installation declined. Run \`${frameworkCommandName()} install --yes\` to continue.\n`,
+        );
         process.exitCode = 1;
         return false;
       }
@@ -54,7 +57,7 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     printPlanText(plan);
     if (!skipConfirm) {
       process.stderr.write(
-        "mate: installation requires confirmation in a TTY. Re-run with `mate install --yes`.\n",
+        `${frameworkCommandName()}: installation requires confirmation in a TTY. Re-run with \`${frameworkCommandName()} install --yes\`.\n`,
       );
       process.exitCode = 1;
       return false;
@@ -73,9 +76,13 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
   }
   if (!execution.ok) {
     for (const result of execution.results.filter((item) => item.status === "failed")) {
-      process.stderr.write(`mate: ${result.id} failed: ${result.error ?? "unknown error"}\n`);
+      process.stderr.write(
+        `${frameworkCommandName()}: ${result.id} failed: ${result.error ?? "unknown error"}\n`,
+      );
     }
-    process.stderr.write("Installation is incomplete. Re-run `mate install` after remediation.\n");
+    process.stderr.write(
+      `Installation is incomplete. Re-run \`${frameworkCommandName()} install\` after remediation.\n`,
+    );
     process.exitCode = 1;
     return false;
   }
@@ -85,9 +92,11 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     await saveCompleteInstallState(plan, execution.results);
   } catch (error) {
     process.stderr.write(
-      `mate: installation completed but companion reconciliation failed: ${error instanceof Error ? error.message : String(error)}\n`,
+      `${frameworkCommandName()}: installation completed but companion reconciliation failed: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.stderr.write(
+      `Installation is incomplete. Re-run \`${frameworkCommandName()} install\`.\n`,
     );
-    process.stderr.write("Installation is incomplete. Re-run `mate install`.\n");
     process.exitCode = 1;
     return false;
   }

package/src/cli/commands/launch/shared.ts

@@ -1,3 +1,4 @@
+import { frameworkCommandName } from "../../../framework";
 import { FrameworkLauncher } from "../../../lib/orchestrator/launcher";
 import {
   LaunchPreflightError,
@@ -42,7 +43,7 @@ export function parseLaunchArgs(argv: string[]): ParsedLaunchArgs | null {
   const agentArgs = separatorIndex >= 0 ? argv.slice(separatorIndex + 1) : [];
 
   for (const arg of optionArgs) {
-    process.stderr.write(`mate: unknown launch option: ${arg}\n`);
+    process.stderr.write(`${frameworkCommandName()}: unknown launch option: ${arg}\n`);
     process.exitCode = 1;
     return null;
   }
@@ -107,14 +108,16 @@ export async function runLaunchToolCommand(
     progress?.stop();
 
     if (error instanceof ToolNotAllowedError) {
-      process.stderr.write(`mate: \`${tool}\` is disallowed by active repository policy.\n`);
+      process.stderr.write(
+        `${frameworkCommandName()}: \`${tool}\` is disallowed by active repository policy.\n`,
+      );
       process.exitCode = 1;
       return;
     }
 
     if (error instanceof RepositoryNotSelectedError) {
       process.stderr.write(`${error.message}\n`);
-      process.stderr.write("Run `mate companion link` first.\n");
+      process.stderr.write(`Run \`${frameworkCommandName()} companion link\` first.\n`);
       process.exitCode = 1;
       return;
     }

package/src/cli/commands/setup.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../../framework";
 import { ConfigStore, defaultConfig } from "../../lib/orchestrator/config-store";
 import { executeSetup } from "../../tools/setup";
 import {
@@ -98,7 +98,7 @@ async function runSetupFlow(
     if (await checkWorkingRepo(cwd)) {
       process.stderr.write(
         `Warning: this directory looks like a working repository (project files detected).\n` +
-          `Initializing it as a ${frameworkConfig.name} companion here may not be what you want.\n`,
+          `Initializing it as a ${frameworkCommandName()} companion here may not be what you want.\n`,
       );
     }
     const ok = await askConfirm("Initialize this directory as a Mate companion repository? [y/N] ");
@@ -156,7 +156,7 @@ async function runSetupFlow(
       ? getSetupSelectionsFromConfig(defaultConfig())
       : getSetupSelectionsFromConfig(
           await new ConfigStore(
-            path.join(targetCwd, `.${frameworkConfig.name}`, "config", "framework.yaml"),
+            path.join(targetCwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
           ).load(),
         );
 

package/src/cli/commands/update.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
-import { frameworkConfig } from "../../framework";
+import { frameworkCommandName } from "../../framework";
 import {
   OPENCODE_PLUGIN_PACKAGE_NAME,
   warmOpenCodePluginCache,
@@ -20,7 +20,7 @@ type InstallResult = ReturnType<typeof installPublicPackageSync>;
 function writeNpmOnlyRecoveryMessage(): void {
   const { packageName, registry } = getUpdateConfig();
   process.stderr.write(
-    `${frameworkConfig.name}: self-update is only supported for npm-installed Mate.\n`,
+    `${frameworkCommandName()}: self-update is only supported for npm-installed Mate.\n`,
   );
   if (packageName.startsWith("@uniqbit/")) {
     process.stderr.write(
@@ -88,7 +88,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
     latest = await updateCommandDeps.fetchLatestVersion();
   } catch {
     process.stderr.write(
-      `${frameworkConfig.name}: could not reach registry to check for updates\n`,
+      `${frameworkCommandName()}: could not reach registry to check for updates\n`,
     );
     process.exitCode = 1;
     return;
@@ -96,7 +96,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
 
   if (checkOnly) {
     if (updateCommandDeps.isNewer(latest, current)) {
-      console.log(`${frameworkConfig.name}: update available (${current} → ${latest})`);
+      console.log(`${frameworkCommandName()}: update available (${current} → ${latest})`);
       process.exitCode = 1;
     } else {
       console.log("Up to date.");
@@ -127,11 +127,11 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
       process.stderr.write(
-        `${frameworkConfig.name}: npm is required for self-update but was not found on PATH\n`,
+        `${frameworkCommandName()}: npm is required for self-update but was not found on PATH\n`,
       );
     } else {
       process.stderr.write(
-        `${frameworkConfig.name}: could not verify the npm installation used for self-update\n`,
+        `${frameworkCommandName()}: could not verify the npm installation used for self-update\n`,
       );
     }
     writeNpmOnlyRecoveryMessage();
@@ -148,7 +148,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   const result = updateCommandDeps.installLatest(latest);
   if (result.status !== 0 || result.error) {
     process.stderr.write(
-      `${frameworkConfig.name}: upgrade command exited with status ${result.status ?? 1}\n`,
+      `${frameworkCommandName()}: upgrade command exited with status ${result.status ?? 1}\n`,
     );
     process.exitCode = 1;
     return;
@@ -163,7 +163,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   if (!warmed.ok) {
     process.stderr.write(
       [
-        `${frameworkConfig.name}: could not pre-fetch ${OPENCODE_PLUGIN_PACKAGE_NAME}@${latest} for OpenCode.`,
+        `${frameworkCommandName()}: could not pre-fetch ${OPENCODE_PLUGIN_PACKAGE_NAME}@${latest} for OpenCode.`,
         "The next managed OpenCode launch will download it (requires registry access).",
         ...(warmed.detail ? [`Details: ${warmed.detail}`] : []),
       ].join("\n") + "\n",
@@ -173,7 +173,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   const postInstall = updateCommandDeps.runPostInstall(skipConfirm);
   if (postInstall.status !== 0 || postInstall.error) {
     process.stderr.write(
-      `\nUpgraded to ${latest}, but installation is incomplete. Run \`mate install\`.\n`,
+      `\nUpgraded to ${latest}, but installation is incomplete. Run \`${frameworkCommandName()} install\`.\n`,
     );
     process.exitCode = 1;
     return;

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 import { getActiveDistribution } from "../distribution";
+import { frameworkCommandName } from "../framework";
 import {
   enforceUpdateIfRequired,
   scheduleBackgroundCheck,
@@ -81,8 +82,10 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
   if (!isInstallRecoveryCommand(command, subcommand)) {
     const preflight = await deps.inspectInstallPreflight();
     if (!preflight.ok) {
-      console.error(`mate: ${preflight.reason ?? "installation is incomplete"}`);
-      console.error("Run `mate install` before continuing.");
+      console.error(
+        `${frameworkCommandName()}: ${preflight.reason ?? "installation is incomplete"}`,
+      );
+      console.error(`Run \`${frameworkCommandName()} install\` before continuing.`);
       process.exitCode = 1;
       return;
     }

package/src/cli/plugin-commands.ts

@@ -1,4 +1,5 @@
 import { getActiveDistribution } from "../distribution";
+import { frameworkCommandName } from "../framework";
 import { resolveInstallContext } from "../lib/install";
 import type { FrameworkConfig } from "../lib/orchestrator/types";
 import type { Plugin, PluginCliCommand } from "../tools/setup/plugin";
@@ -85,7 +86,7 @@ export async function ensureCapabilityEnabled(
   const loadConfig = deps.loadConfig ?? (async () => (await resolveInstallContext()).config);
   if (plugin?.isEnabled(await loadConfig())) return true;
 
-  const name = distribution.config.name;
+  const name = frameworkCommandName();
   console.error(
     `${name}: the "${pluginId}" capability is not enabled for this companion. ` +
       `Enable it via \`${name} companion setup\`.`,
@@ -95,7 +96,7 @@ export async function ensureCapabilityEnabled(
 }
 
 function usageFor(plugin: Plugin): string {
-  const distributionName = getActiveDistribution().config.name;
+  const distributionName = frameworkCommandName();
   const namespace = namespaceOf(plugin);
   const lines = (plugin.cliCommands ?? []).map(
     (command) => `  ${distributionName} cap ${namespace} ${command.name}  ${command.description}`,

package/src/cli/usage.ts

@@ -1,9 +1,12 @@
-import { frameworkConfig } from "../framework";
+import { getActiveDistribution } from "../distribution";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../framework";
 
 export function usage(): string {
-  const n = frameworkConfig.name;
+  const n = frameworkCommandName();
+  const packageName =
+    getActiveDistribution().config.update?.packageName ?? `@uniqbit/${FRAMEWORK_NAME}`;
   return [
-    `${n.charAt(0).toUpperCase() + n.slice(1)} CLI (@uniqbit/${n})`,
+    `${n.charAt(0).toUpperCase() + n.slice(1)} CLI (${packageName})`,
     "",
     "Commands:",
     ` ${n} install [--yes]`,

package/src/create-mate.ts

@@ -1,5 +1,6 @@
 import { main } from "./cli/main";
 import { setActiveDistribution, type DistributionConfig } from "./distribution";
+import { FRAMEWORK_NAME } from "./framework";
 import { createBunPlugin } from "./tools/setup/package-managers/bun";
 import { createUvPlugin } from "./tools/setup/package-managers/uv";
 import type { PluginRegistration } from "./tools/setup/plugin";
@@ -23,15 +24,15 @@ export interface MateCli {
  * Assemble a distribution from an identity config and plugin registration
  * entries. Distributions choose their plugin set; the framework always adds
  * bun and uv as required runtime substrate, plus gitignore management named
- * after `config.name` (built last since it reads the full plugin set).
- * Returns the runnable CLI.
+ * after the framework identity (built last since it reads the full plugin
+ * set). Returns the runnable CLI.
  */
 export function createMate({ config, plugins, main: runMain = main }: CreateMateOptions): MateCli {
   const registry = new PluginRegistry([
     ...plugins,
     { plugin: createBunPlugin(), policy: "required" },
     { plugin: createUvPlugin(), policy: "required" },
-    createGitignorePlugin(config.name),
+    createGitignorePlugin(FRAMEWORK_NAME),
   ]);
   setActiveDistribution({ config, registry });
   return {

package/src/framework.ts

@@ -1,5 +1,25 @@
 import { getActiveDistribution } from "./distribution";
 
+/**
+ * Framework identity: names everything identity-shaped regardless of how the
+ * CLI is invoked — state directories (`~/.mate`, `.mate/`), managed-block
+ * markers, `MATE_*` env values, and the `companion-policy framework`
+ * attribute. A whitelabel distribution changes the invocation name only;
+ * identity stays `mate`. Use `frameworkCommandName()` for anything the user
+ * or an agent types.
+ */
+export const FRAMEWORK_NAME = "mate";
+
+/**
+ * Invocation name: how this distribution's CLI is invoked, derived from the
+ * package's `bin` key (`config.name`). Drives usage output, command hints,
+ * error prefixes, agent guidance, and permission entries — never paths,
+ * markers, or env values (use `FRAMEWORK_NAME` for those).
+ */
+export function frameworkCommandName(): string {
+  return getActiveDistribution().config.name;
+}
+
 /**
  * Live view of the active distribution's identity. Framework modules read
  * identity through this object; the values always come from the config the

package/src/index.ts

@@ -24,6 +24,7 @@ export { ensureCapabilityEnabled, type EnsureCapabilityEnabledDeps } from "./cli
 export type {
   CapabilityPlugin,
   InstructionsService,
+  LaunchPreflightContext,
   McpServerDescriptor,
   McpService,
   Plugin,

package/src/lib/context-mode-package.ts

@@ -0,0 +1,94 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { PUBLIC_NPM_REGISTRY } from "./public-npm";
+
+export const CONTEXT_MODE_PACKAGE_NAME = "context-mode";
+export const CONTEXT_MODE_VERSION = "1.0.169";
+export const CONTEXT_MODE_NODE_REQUIREMENT = ">=22.5.0";
+
+export function getContextModePackageReference(): string {
+  return `${CONTEXT_MODE_PACKAGE_NAME}@${CONTEXT_MODE_VERSION}`;
+}
+
+export function isContextModePackageReference(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    (value === CONTEXT_MODE_PACKAGE_NAME || value.startsWith(`${CONTEXT_MODE_PACKAGE_NAME}@`))
+  );
+}
+
+export function getContextModeInstallDir(companionPath: string): string {
+  return path.join(companionPath, ".mate", "dependencies", CONTEXT_MODE_PACKAGE_NAME);
+}
+
+export function getContextModePackageRoot(companionPath: string): string {
+  return path.join(
+    getContextModeInstallDir(companionPath),
+    "node_modules",
+    CONTEXT_MODE_PACKAGE_NAME,
+  );
+}
+
+export function isContextModeNodeVersionSupported(version: string): boolean {
+  const [major = 0, minor = 0] = version.replace(/^v/, "").split(".").map(Number);
+  return major > 22 || (major === 22 && minor >= 5);
+}
+
+export function validateContextModeNodeRuntime(): void {
+  const result = spawnSync("node", ["--version"], { encoding: "utf8" });
+  const version = result.stdout?.trim() ?? "";
+  if (result.status !== 0 || !isContextModeNodeVersionSupported(version)) {
+    throw new Error(
+      `context-mode ${CONTEXT_MODE_VERSION} requires Node.js ${CONTEXT_MODE_NODE_REQUIREMENT}; found ${version || "no usable node executable"}.`,
+    );
+  }
+}
+
+export async function validateContextModePackage(companionPath: string): Promise<void> {
+  validateContextModeNodeRuntime();
+  const root = getContextModePackageRoot(companionPath);
+  const manifest = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8")) as {
+    version?: string;
+  };
+  if (manifest.version !== CONTEXT_MODE_VERSION) {
+    throw new Error(
+      `Expected ${getContextModePackageReference()} at ${root}; found ${manifest.version ?? "an unknown version"}. Re-run \`mate companion setup\`.`,
+    );
+  }
+  await Promise.all(
+    [
+      ".claude-plugin/plugin.json",
+      "hooks/hooks.json",
+      "skills/context-mode/SKILL.md",
+      "build/adapters/opencode/plugin.js",
+    ].map((asset) => fs.access(path.join(root, asset))),
+  );
+}
+
+export async function installContextModePackage(companionPath: string): Promise<void> {
+  validateContextModeNodeRuntime();
+  const installDir = getContextModeInstallDir(companionPath);
+  await fs.mkdir(installDir, { recursive: true });
+  await fs.writeFile(
+    path.join(installDir, "package.json"),
+    JSON.stringify(
+      { private: true, dependencies: { [CONTEXT_MODE_PACKAGE_NAME]: CONTEXT_MODE_VERSION } },
+      null,
+      2,
+    ) + "\n",
+    "utf8",
+  );
+  const result = spawnSync(
+    "npm",
+    ["install", "--no-audit", "--no-fund", "--silent", "--registry", PUBLIC_NPM_REGISTRY],
+    { cwd: installDir, encoding: "utf8" },
+  );
+  if (result.error || result.status !== 0) {
+    throw new Error(
+      `Could not install ${getContextModePackageReference()}: ${result.error?.message ?? result.stderr?.trim() ?? `npm exited with ${result.status}`}`,
+    );
+  }
+  await validateContextModePackage(companionPath);
+}

package/src/lib/install.ts

@@ -8,7 +8,7 @@ import { CompanionResolver } from "./orchestrator/companion-resolver";
 import { checkEngineRequirement } from "./orchestrator/engine-guard";
 import { GlobalConfigStore } from "./orchestrator/global-config-store";
 import { YamlFileStore } from "./orchestrator/yaml-file-store";
-import { frameworkConfig } from "../framework";
+import { FRAMEWORK_NAME } from "../framework";
 import type { FrameworkConfig } from "./orchestrator/types";
 import { getActiveDistribution } from "../distribution";
 import { createBunPlugin } from "../tools/setup/package-managers/bun";
@@ -55,7 +55,7 @@ export interface InstallState {
 }
 
 function defaultInstallStateRoot(): string {
-  return path.join(os.homedir(), `.${frameworkConfig.name}`, "install-state");
+  return path.join(os.homedir(), `.${FRAMEWORK_NAME}`, "install-state");
 }
 
 export function getInstallStatePath(
@@ -107,12 +107,7 @@ function coreContext(): InstallContext {
 }
 
 async function contextForCompanion(companionPath: string): Promise<InstallContext> {
-  const configPath = path.join(
-    companionPath,
-    `.${frameworkConfig.name}`,
-    "config",
-    "framework.yaml",
-  );
+  const configPath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
   const config = mergeWithDefaults(await new ConfigStore(configPath).load());
   return {
     kind: "companion",
@@ -124,7 +119,7 @@ async function contextForCompanion(companionPath: string): Promise<InstallContex
 
 async function hasLocalConfig(cwd: string): Promise<boolean> {
   try {
-    await fs.access(path.join(cwd, `.${frameworkConfig.name}`, "config", "framework.yaml"));
+    await fs.access(path.join(cwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
     return true;
   } catch {
     return false;

package/src/lib/opencode-plugin-package.ts

@@ -44,53 +44,50 @@ export const opencodePluginCacheDeps = {
     }),
 };
 
-/**
- * Pre-fetch the pinned plugin package into OpenCode's npm plugin environment
- * (`<cache>/packages/<spec>/`), mirroring OpenCode's own on-demand install
- * layout, so the first managed launch after a setup or update does not depend
- * on registry access. Best effort: failures are reported, never thrown.
- */
-export async function warmOpenCodePluginCache(
-  version: string = getCurrentVersion(),
+export async function warmOpenCodePackageCache(
+  packageName: string,
+  packageReference: string,
   env: NodeJS.ProcessEnv = process.env,
   registry = PUBLIC_NPM_REGISTRY,
 ): Promise<WarmPluginCacheResult> {
-  // Escape hatch for tests and intentionally offline environments: skip the
-  // pre-fetch entirely instead of attempting a registry install.
   if (env.MATE_DISABLE_OPENCODE_PLUGIN_PREFETCH === "1") {
     return { ok: true, detail: "pre-fetch disabled via MATE_DISABLE_OPENCODE_PLUGIN_PREFETCH" };
   }
-
-  const reference = getOpenCodePluginPackageReference(version);
-  const specDir = path.join(getOpenCodeCacheDir(env), "packages", reference);
-
+  const version = packageReference.slice(packageName.length + 1);
+  const specDir = path.join(getOpenCodeCacheDir(env), "packages", packageReference);
   try {
     await fs.mkdir(specDir, { recursive: true });
     await fs.writeFile(
       path.join(specDir, "package.json"),
-      JSON.stringify({ dependencies: { [OPENCODE_PLUGIN_PACKAGE_NAME]: version } }, null, 2) + "\n",
+      JSON.stringify({ dependencies: { [packageName]: version } }, null, 2) + "\n",
       "utf8",
     );
-
     const result = opencodePluginCacheDeps.runInstall(specDir, registry);
-    if (result.error) {
-      return { ok: false, detail: result.error.message };
-    }
+    if (result.error) return { ok: false, detail: result.error.message };
     if (result.status !== 0) {
-      const output = `${result.stderr ?? ""}`.trim() || `npm install exited with ${result.status}`;
-      return { ok: false, detail: output };
+      return {
+        ok: false,
+        detail: `${result.stderr ?? ""}`.trim() || `npm install exited with ${result.status}`,
+      };
     }
-
-    await fs.access(
-      path.join(
-        specDir,
-        "node_modules",
-        ...OPENCODE_PLUGIN_PACKAGE_NAME.split("/"),
-        "package.json",
-      ),
-    );
+    await fs.access(path.join(specDir, "node_modules", ...packageName.split("/"), "package.json"));
     return { ok: true };
   } catch (error) {
     return { ok: false, detail: (error as Error).message };
   }
 }
+
+/**
+ * Pre-fetch the pinned plugin package into OpenCode's npm plugin environment
+ * (`<cache>/packages/<spec>/`), mirroring OpenCode's own on-demand install
+ * layout, so the first managed launch after a setup or update does not depend
+ * on registry access. Best effort: failures are reported, never thrown.
+ */
+export async function warmOpenCodePluginCache(
+  version: string = getCurrentVersion(),
+  env: NodeJS.ProcessEnv = process.env,
+  registry = PUBLIC_NPM_REGISTRY,
+): Promise<WarmPluginCacheResult> {
+  const reference = getOpenCodePluginPackageReference(version);
+  return warmOpenCodePackageCache(OPENCODE_PLUGIN_PACKAGE_NAME, reference, env, registry);
+}

package/src/lib/orchestrator/adapters/base.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 
 import { version } from "../../../../package.json";
 import { isCommandOnPath } from "../../fs-utils";
-import { frameworkConfig } from "../../../framework";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../../../framework";
 import { getReactDoctorBinPath, getWrapperBinPath } from "../../package-paths";
 import {
   GRAPHIFY_OUTPUT_SUBDIR,
@@ -77,7 +77,8 @@ export abstract class LaunchAdapter {
     const wrapperBinPath = getWrapperBinPath();
     const env: NodeJS.ProcessEnv = {
       ...process.env,
-      MATE_NAME: frameworkConfig.name,
+      MATE_NAME: FRAMEWORK_NAME,
+      MATE_COMMAND: frameworkCommandName(),
       MATE_VERSION: version,
       MATE_ARTIFACT_PATH: context.companionPath,
       MATE_WRAPPER_BIN_PATH: wrapperBinPath,
@@ -148,7 +149,7 @@ export abstract class LaunchAdapter {
         command: this.toolName,
         args: builtArgs,
         env,
-        warning: `${frameworkConfig.name}: headroom capability enabled but \`headroom\` was not found on PATH; install with \`uv tool install "headroom-ai[all]"\`; launching ${this.toolName} directly\n`,
+        warning: `${frameworkCommandName()}: headroom capability enabled but \`headroom\` was not found on PATH; install with \`uv tool install "headroom-ai[all]"\`; launching ${this.toolName} directly\n`,
       };
     }
 
@@ -182,7 +183,7 @@ export abstract class LaunchAdapter {
           command: this.toolName,
           args: builtArgs,
           env,
-          warning: `${frameworkConfig.name}: headroom proxy failed to become ready on port ${port} after ${maxProxyStartAttempts} attempts; launching ${this.toolName} directly${errorDetail}\n`,
+          warning: `${frameworkCommandName()}: headroom proxy failed to become ready on port ${port} after ${maxProxyStartAttempts} attempts; launching ${this.toolName} directly${errorDetail}\n`,
         };
       }
     }