@uniqbit/mate-core 0.17.0-canary.8 → 0.17.1

package/src/cli/commands/update.ts

@@ -1,4 +1,3 @@
-import path from "node:path";
 import { spawnSync } from "node:child_process";
 
 import { FRAMEWORK_NAME } from "../../framework";
@@ -14,6 +13,7 @@ import {
   isNewer,
 } from "../../lib/update-checker";
 import { confirmPrompt } from "../../lib/components/confirm-prompt";
+import { resolvePackageRoot } from "../../lib/package-root";
 
 type InstallResult = ReturnType<typeof installPublicPackageSync>;
 
@@ -38,11 +38,11 @@ export const updateCommandDeps = {
   getCurrentVersion,
   isNewer,
   confirmPrompt,
-  isNpmManagedInstall: () =>
-    isPackageInstalledAtNpmGlobalRoot(
-      path.resolve(import.meta.dirname, "../../.."),
-      getUpdateConfig().packageName,
-    ),
+  isNpmManagedInstall: () => {
+    const packageName = getUpdateConfig().packageName;
+    const packageRoot = resolvePackageRoot(process.argv[1], packageName);
+    return packageRoot !== undefined && isPackageInstalledAtNpmGlobalRoot(packageRoot, packageName);
+  },
   installLatest: (latest: string): InstallResult => {
     const { packageName, registry } = getUpdateConfig();
     return installPublicPackageSync(`${packageName}@${latest}`, registry);
@@ -55,14 +55,17 @@ export const updateCommandDeps = {
       latestVersion: latest,
     });
   },
+  /** Re-runs install from dev (`cli.ts`) or prod (`cli.mjs`/bootstrap) entrypoints so config reconciles during `mate update`. */
   runPostInstall: (skipConfirm: boolean): InstallResult => {
     const entrypoint = process.argv[1];
-    if (!entrypoint?.endsWith("/cli.ts") && !entrypoint?.endsWith("\\cli.ts")) {
+    if (!entrypoint || !/(?:^|[\\/])(?:cli\.ts|cli\.mjs|cli-bootstrap\.cjs)$/.test(entrypoint)) {
       return { status: 0, error: undefined } as InstallResult;
     }
     const args = [entrypoint, "install", ...(skipConfirm ? ["--yes"] : [])];
-    return spawnSync(process.execPath, args, { stdio: "inherit" }) as InstallResult;
+    return updateCommandDeps.spawnPostInstall(process.execPath, args);
   },
+  spawnPostInstall: (executable: string, args: string[]): InstallResult =>
+    spawnSync(executable, args, { stdio: "inherit" }) as InstallResult,
   warmOpenCodePluginCache: (latest: string) =>
     warmOpenCodePluginCache(latest, process.env, getUpdateConfig().registry),
 };

package/src/cli/companion-link-wizard.tsx

@@ -8,7 +8,7 @@ import { WizardHeader } from "../lib/components/wizard-header";
 import type { CompanionSource } from "../lib/orchestrator/types";
 import { parseRepoLinkInput } from "./wizard-key-input";
 
-export const companionLinkWizardDeps = {
+const companionLinkWizardDeps = {
   render: inkRender,
 };
 

package/src/cli/companion-selector.tsx

@@ -11,7 +11,7 @@ export interface CompanionSelectorOptions {
   stderr?: NodeJS.WriteStream;
 }
 
-export const companionSelectorDeps = {
+const companionSelectorDeps = {
   render: inkRender,
 };
 

package/src/cli/launch-selector.tsx

@@ -45,7 +45,7 @@ export interface LaunchWizardOptions {
   resolvePreview(target: LaunchTarget): Promise<LaunchPreviewData>;
 }
 
-export const launchSelectorDeps = {
+const launchSelectorDeps = {
   render: inkRender,
 };
 

package/src/cli/main.ts

@@ -206,10 +206,11 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
         case "hub":
           if (!(await gate({ updateGuard: true, notCompanionRoot: true }))) return;
           break;
-        // open/tui/sync consume a companion context.
+        // open/tui/sync/update consume a companion context.
         case "open":
         case "tui":
         case "sync":
+        case "update":
           if (!(await gate({ updateGuard: true, notHubRoot: true, companion: true }))) return;
           break;
         // list and unknown subcommands (which fail inside the command).

package/src/cli/usage.ts

@@ -10,13 +10,14 @@ export function usage(): string {
     `Mate CLI (${packageName})`,
     "",
     "Commands:",
-    ` ${n} install [--yes]`,
+    ` ${n} install [--yes] [--frozen-plugins]`,
     ` ${n} companion link`,
     ` ${n} companion setup`,
     ` ${n} companion register [path]`,
     ` ${n} companion prepare --from <bundle> [path]`,
     ` ${n} companion list`,
     ` ${n} companion sync`,
+    ` ${n} companion update [--yes]`,
     ` ${n} companion open`,
     ` ${n} companion tui`,
     ` ${n} working cleanup`,
@@ -30,8 +31,10 @@ export function usage(): string {
     ` ${n} artifact pending [--json]`,
     ` ${n} doctor`,
     ` ${n} report [--days N] [--input FILE|-] [--json]`,
-    ` ${n} studio [--writable]`,
-    ` ${n} studio serve --port <port> [--host <host>] [--writable]`,
+    ` ${n} studio [--writable] [--terminal] [--detach-timeout <minutes>]`,
+    ` ${n} studio serve --port <port> [--host <host>] [--writable] [--terminal]`,
+    "   [--detach-timeout <minutes>] [--token <value>] [--allowed-host <host>]",
+    "   [--public-origin <origin>] [--companion <path>] [--no-git]",
     ` ${n} config`,
     ` ${n} claude [args...] (after --: --no-git, --companion, --yes no-op)`,
     ` ${n} opencode [args...] (after --: --no-git, --companion, --yes no-op)`,
@@ -39,6 +42,7 @@ export function usage(): string {
     ` ${n} cap graphify <subcommand> [args...]`,
     ` ${n} cap index [--graphify] [--tokensave]`,
     ` ${n} plugin install <package>[@version]`,
+    ` ${n} plugin verify`,
     ...pluginCliCommandLines(),
     ` ${n} update`,
     ` ${n} update --check`,

package/src/cli/write-json-stdout.ts

@@ -5,9 +5,9 @@
  * before the write flushes (observed at exactly the 64KB pipe boundary) —
  * awaiting the write callback is what actually guarantees delivery.
  */
-export function writeJsonStdout(data: unknown): Promise<void> {
+export function writeJsonStdout(data: unknown, options: { space?: number } = {}): Promise<void> {
   return new Promise((resolve, reject) => {
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`, (error) =>
+    process.stdout.write(`${JSON.stringify(data, null, options.space ?? 2)}\n`, (error) =>
       error ? reject(error) : resolve(),
     );
   });

package/src/lib/components/spinner.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useState } from "react";
 
-export const SPINNER_FRAMES = ["·", "✦", "✧", "✦"];
-export const SPINNER_INTERVAL_MS = 120;
+const SPINNER_FRAMES = ["·", "✦", "✧", "✦"];
+const SPINNER_INTERVAL_MS = 120;
 
 export function useSpinnerFrame(active: boolean, intervalMs: number = SPINNER_INTERVAL_MS): string {
   const [frame, setFrame] = useState(0);

package/src/lib/components/startup-progress.tsx

@@ -38,7 +38,7 @@ export interface StartupProgressAppProps {
   steps: StartupStep[];
 }
 
-export function StartupProgressApp({ title, steps }: StartupProgressAppProps) {
+function StartupProgressApp({ title, steps }: StartupProgressAppProps) {
   return (
     <Box flexDirection="column">
       <Text bold color={MIDNIGHT_PURPLE_BRIGHT}>

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

@@ -39,7 +39,7 @@ export function isContextModeNodeVersionSupported(version: string): boolean {
   return major > 22 || (major === 22 && minor >= 5);
 }
 
-export function validateContextModeNodeRuntime(): void {
+function validateContextModeNodeRuntime(): void {
   // env passed explicitly: bun's spawnSync otherwise ignores in-process PATH
   // changes when resolving the executable.
   const result = spawnSync("node", ["--version"], { encoding: "utf8", env: process.env });

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

@@ -21,6 +21,9 @@ export function getOpenCodePluginPackageReference(version: string = getCurrentVe
 
 /** Matches the published reference and a reference bound to an installed copy alike. */
 export function isMateOpenCodePluginReference(value: unknown): boolean {
+  if (typeof value === "object" && value !== null && !Array.isArray(value) && "package" in value) {
+    return isMateOpenCodePluginReference(value.package);
+  }
   if (typeof value !== "string") return false;
   if (
     value === OPENCODE_PLUGIN_PACKAGE_NAME ||

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

@@ -1,4 +1,6 @@
 // oxlint-disable no-await-in-loop
+import { spawnSync } from "node:child_process";
+
 const fs = await import("node:fs/promises");
 const path = await import("node:path");
 
@@ -21,18 +23,61 @@ import { buildOpenCodeGuidance } from "../opencode-guidance";
 import { LaunchPreflightError } from "../types";
 import { type AdapterContext, LaunchAdapter } from "./base";
 
+/** The Mate plugin is a V2 plugin; an older host rejects it at load time. */
+const MIN_OPENCODE_MAJOR = 2;
+
+/**
+ * OpenCode 2.x attaches to a shared background service by default; plugins and
+ * config load in that server, so the per-launch Mate env never reaches it.
+ */
+const STANDALONE_FLAG = "--standalone";
+
+/** Raw `opencode --version` output, or `undefined` when the binary cannot run. */
+export type OpenCodeVersionProbe = () => string | undefined;
+
+const probeOpenCodeVersion: OpenCodeVersionProbe = () => {
+  const result = spawnSync("opencode", ["--version"], { encoding: "utf8", timeout: 10_000 });
+  return result.status === 0 ? result.stdout.trim() : undefined;
+};
+
+function parseOpenCodeMajor(output: string | undefined): number | undefined {
+  const match = output?.match(/(\d+)\.\d+\.\d+/);
+  return match ? Number(match[1]) : undefined;
+}
+
 export class OpenCodeAdapter extends LaunchAdapter {
   readonly toolName = "opencode";
   readonly interactive = true;
+  private readonly requiredRuntimeAssets = [path.join(".opencode", "opencode.json")] as const;
+
+  constructor(private readonly probeVersion: OpenCodeVersionProbe = probeOpenCodeVersion) {
+    super();
+  }
 
-  private readonly requiredRuntimeAssets = [
-    path.join(".opencode", "opencode.json"),
-    path.join(".opencode", "tui.json"),
-  ] as const;
+  private validateOpenCodeVersion(): void {
+    const output = this.probeVersion();
+    const major = parseOpenCodeMajor(output);
+    if (major !== undefined && major >= MIN_OPENCODE_MAJOR) return;
+    throw new LaunchPreflightError(
+      [
+        output === undefined
+          ? "OpenCode is not installed or `opencode --version` failed."
+          : `OpenCode ${output} is not supported.`,
+        `Mate requires OpenCode ${MIN_OPENCODE_MAJOR}.x or newer. Upgrade OpenCode and retry.`,
+      ].join("\n"),
+    );
+  }
 
   buildArgs(context: AdapterContext, args: string[]): string[] {
     const codeDir = context.launchWorkingDirectory;
-    return args.length === 0 || args[0]?.startsWith("-") ? [codeDir, ...args] : args;
+    const isTui = args.length === 0 || args[0]?.startsWith("-");
+    const [command, ...rest] = isTui ? [codeDir, ...args] : args;
+    if (!command) return args;
+    const hostsServer = isTui || command === "run";
+    const choosesServer = rest.some(
+      (arg) => arg === "--standalone" || arg === "--server" || arg.startsWith("--server="),
+    );
+    return hostsServer && !choosesServer ? [command, STANDALONE_FLAG, ...rest] : [command, ...rest];
   }
 
   extendEnvironment(context: AdapterContext): NodeJS.ProcessEnv {
@@ -40,9 +85,7 @@ export class OpenCodeAdapter extends LaunchAdapter {
       OPENCODE_CONFIG_DIR: path.join(context.companionPath, ".opencode"),
       OPENCODE_CONFIG_CONTENT: mergeOpenCodeConfigContent(
         {
-          permission: {
-            external_directory: renderCompanionExternalDirectoryPermissions(context.companionPath),
-          },
+          permissions: renderCompanionExternalDirectoryPermissions(context.companionPath),
           references: {
             mate: context.companionPath,
           },
@@ -63,6 +106,8 @@ export class OpenCodeAdapter extends LaunchAdapter {
   }
 
   async validateLaunch(context: AdapterContext): Promise<void> {
+    this.validateOpenCodeVersion();
+
     const missingAssets = await Promise.all(
       this.requiredRuntimeAssets.map(async (asset) => {
         const assetPath = path.join(context.companionPath, asset);
@@ -92,11 +137,6 @@ export class OpenCodeAdapter extends LaunchAdapter {
         path.join(".opencode", "opencode.json"),
         expectedPluginReference,
       )),
-      ...(await this.validatePluginReference(
-        context,
-        path.join(".opencode", "tui.json"),
-        expectedPluginReference,
-      )),
       ...this.validateGuidance(context),
     ];
     if (errors.length > 0) {

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

@@ -63,7 +63,7 @@ function isInsideDir(parent: string, candidate: string): boolean {
   return relative !== "" && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
 }
 
-export function normalizeHubMemberId(value: string): string {
+function normalizeHubMemberId(value: string): string {
   const normalized = value
     .replace(/\.git$/i, "")
     .replace(/[^a-zA-Z0-9._-]+/g, "-")
@@ -72,7 +72,7 @@ export function normalizeHubMemberId(value: string): string {
   return normalized;
 }
 
-export function validateHubMemberPath(hubPath: string, memberPath: string): string {
+function validateHubMemberPath(hubPath: string, memberPath: string): string {
   if (!memberPath || path.isAbsolute(memberPath)) {
     throw new Error("Hub member path must be relative to the hub root.");
   }
@@ -266,7 +266,7 @@ function syncTarget(memberPath: string, git: GitCommand): string | null {
   return upstream.stdout;
 }
 
-export async function syncHubMember(
+async function syncHubMember(
   hubPath: string,
   member: HubMember,
   git: GitCommand = defaultGitCommand,

package/src/lib/orchestrator/companion-registry-store.ts

@@ -5,7 +5,7 @@ import { migrateRegistryData } from "./migration";
 import { YamlFileStore } from "./yaml-file-store";
 import { ConfigError, type CompanionRegistryConfig } from "./types";
 
-export function getDefaultCompanionRegistryPath(): string {
+function getDefaultCompanionRegistryPath(): string {
   return `.${FRAMEWORK_NAME}/config/registry.yaml`;
 }
 

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

@@ -30,7 +30,7 @@ interface LegacyProfilesShape {
  * list (`profiles.default.allowedAgents` wins; other profiles are dropped).
  * The new shape persists on the next save.
  */
-export function migrateProfilesToAllowedAgents(config: FrameworkConfig): FrameworkConfig {
+function migrateProfilesToAllowedAgents(config: FrameworkConfig): FrameworkConfig {
   const legacy = config as FrameworkConfig & LegacyProfilesShape;
   if (!legacy.profiles) return config;
   const { profiles, ...rest } = legacy;
@@ -130,7 +130,7 @@ 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 {
+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)) {

package/src/lib/orchestrator/editor.ts

@@ -13,7 +13,7 @@ const CURSOR_FALLBACK_PATHS = [
   "/opt/homebrew/bin/cursor",
 ];
 
-export function isCursorSession(env: NodeJS.ProcessEnv = process.env): boolean {
+function isCursorSession(env: NodeJS.ProcessEnv = process.env): boolean {
   const termProgram = env.TERM_PROGRAM?.toLowerCase() ?? "";
   const bundleId = env.__CFBundleIdentifier ?? "";
   return (
@@ -21,7 +21,7 @@ export function isCursorSession(env: NodeJS.ProcessEnv = process.env): boolean {
   );
 }
 
-export function isVsCodeSession(env: NodeJS.ProcessEnv = process.env): boolean {
+function isVsCodeSession(env: NodeJS.ProcessEnv = process.env): boolean {
   const termProgram = env.TERM_PROGRAM?.toLowerCase() ?? "";
   const bundleId = env.__CFBundleIdentifier ?? "";
   return (
@@ -69,18 +69,10 @@ function resolveEditorCli(cli: string): { cli: string; binary: string } | null {
   return null;
 }
 
-export function writeMissingEditorCliGuidance(
-  cli: string,
-  write: (chunk: string) => boolean = process.stderr.write.bind(process.stderr),
-): void {
-  write(`mate: warning: ${cli} CLI not found on PATH.\n`);
-  write(`mate: run "Install '${cli}' command in PATH" from the Command Palette to enable this.\n`);
-}
-
 /** The Projection Root owns the path; this is the editor's name for it. */
 export const editorWorkspacePath = workspaceDocumentPath;
 
-export interface WorkspaceDocument {
+interface WorkspaceDocument {
   workspacePath: string;
   folders: [string, string];
 }
@@ -91,7 +83,7 @@ export interface WorkspaceDocument {
  * order. Called by editor-launching `injectEditorFolder`, which backs
  * `mate companion open`.
  */
-export async function writeWorkspaceDocument(
+async function writeWorkspaceDocument(
   companionPath: string,
   repoPath: string,
 ): Promise<WorkspaceDocument> {

package/src/lib/orchestrator/engine-guard.ts

@@ -27,7 +27,15 @@ export function checkEngineRequirement(
     };
   }
 
-  const satisfied = semver.satisfies(currentVersion, range, { includePrerelease: true });
+  const current = semver.parse(currentVersion);
+  const currentReleaseVersion =
+    current && current.prerelease.length > 0
+      ? `${current.major}.${current.minor}.${current.patch}`
+      : null;
+  const satisfied =
+    semver.satisfies(currentVersion, range, { includePrerelease: true }) ||
+    (currentReleaseVersion !== null &&
+      semver.satisfies(currentReleaseVersion, range, { includePrerelease: true }));
   if (!satisfied) {
     return {
       ok: false,

package/src/lib/orchestrator/projection-entries.ts

@@ -52,7 +52,7 @@ import {
 } from "./repo-local-store";
 import type { ProjectionEntry, ProjectionInput } from "./projection-types";
 
-export const WORKSPACE_DOCUMENT_FILE = "workspace.code-workspace";
+const WORKSPACE_DOCUMENT_FILE = "workspace.code-workspace";
 
 /** The shared editor workspace document, inside the Projection Root. */
 export function workspaceDocumentPath(repoPath: string): string {

package/src/lib/orchestrator/projection-record.ts

@@ -13,7 +13,7 @@ import {
 import { getReactDoctorBinPath, getWrapperBinPath } from "../package-paths";
 import type { LinkedRepository } from "./types";
 
-export const COMPANION_GRAPHIFY_REPOSITORY_ID = "__companion__";
+const COMPANION_GRAPHIFY_REPOSITORY_ID = "__companion__";
 
 /**
  * The one derivation of the projected paths. Both the Projection Root and a

package/src/lib/orchestrator/projection-types.ts

@@ -159,10 +159,6 @@ export interface ProjectionDescription {
   projection: ProjectionFile | null;
 }
 
-export function anyChanged(outcomes: ProjectionEntryOutcome[]): boolean {
-  return outcomes.some((outcome) => outcome.state === "written" || outcome.state === "removed");
-}
-
 /** A degradable entry's failure is reported in the outcomes and nowhere else. */
 export function firstFailure(outcomes: ProjectionEntryOutcome[]): ProjectionEntryOutcome | null {
   return outcomes.find((outcome) => outcome.state === "failed" && !outcome.degradable) ?? null;

package/src/lib/orchestrator/repo-local-registry.ts

@@ -24,7 +24,6 @@ export { pathIsDirectory } from "../fs-utils";
 export {
   RepoLocalRegistryStore,
   upsertRepoLocalCompanionPointer,
-  upsertRepoLocalLinkedRepository,
   writeRepoLocalFrameworkConfig,
   type RepoLocalCompanionPointer,
   type RepoLocalRegistry,

package/src/lib/orchestrator/root-context.ts

@@ -101,7 +101,7 @@ export async function resolveRootContext(
 }
 
 /** Nearest ancestor of `cwd` (inclusive) holding `.<framework>/config/framework.yaml`. */
-export async function findConfiguredRoot(cwd: string): Promise<string | null> {
+async function findConfiguredRoot(cwd: string): Promise<string | null> {
   let dir = path.resolve(cwd);
   for (;;) {
     try {

package/src/lib/orchestrator/setup-compatibilities.ts

@@ -8,7 +8,7 @@ import type {
 
 export type OpenSpecSchemaSelection = OpenSpecSchemaProfile | "default";
 export type GitModeSelection = GitModeProfile | "default";
-export const DEFAULT_OPENSPEC_SCHEMA_SELECTION: OpenSpecSchemaSelection = "default";
+const DEFAULT_OPENSPEC_SCHEMA_SELECTION: OpenSpecSchemaSelection = "default";
 export const DEFAULT_GIT_MODE_SELECTION: GitModeSelection = "default";
 
 export interface OpenSpecSchemaCompatibility {

package/src/lib/orchestrator/setup-preflight.ts

@@ -124,7 +124,7 @@ export async function looksLikeWorkingRepo(cwd: string): Promise<boolean> {
   return false;
 }
 
-export async function hasLocalCompanionConfig(cwd: string): Promise<boolean> {
+async function hasLocalCompanionConfig(cwd: string): Promise<boolean> {
   const resolvedCwd = path.resolve(cwd);
   return fileExists(path.join(resolvedCwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
 }

package/src/lib/orchestrator/types.ts

@@ -1,4 +1,4 @@
-export class MateError extends Error {}
+class MateError extends Error {}
 
 export class ConfigError extends MateError {}
 

package/src/lib/orchestrator/working-repo-projection.ts

@@ -110,7 +110,7 @@ export async function unproject(input: ProjectionRemovalInput): Promise<Projecti
 }
 
 /** Removes entries that wrap owns but an unwrap must withdraw independently. */
-export async function removeWorkingRepositoryUnwrapEntries(
+async function removeWorkingRepositoryUnwrapEntries(
   repoPath: string,
 ): Promise<ProjectionEntryOutcome[]> {
   const entries = projectionEntries().filter(

package/src/lib/orchestrator/workspace-inventory.ts

@@ -6,7 +6,7 @@ import { GlobalConfigStore } from "./global-config-store";
 import type { LinkedRepository } from "./types";
 
 /** Envelope version for the aggregate inventory shape; bump on any breaking shape change. */
-export const WORKSPACE_INVENTORY_SCHEMA_VERSION = 1;
+const WORKSPACE_INVENTORY_SCHEMA_VERSION = 1;
 
 export type CompanionInventoryHealth = "ready" | "missing" | "unreadable";
 export type PairingInventoryHealth =
@@ -41,7 +41,7 @@ export interface WorkspaceInventoryDeps {
   readCompanionRegistry: typeof readCompanionRegistry;
 }
 
-export function defaultWorkspaceInventoryDeps(
+function defaultWorkspaceInventoryDeps(
   globalConfigStore = new GlobalConfigStore(),
 ): WorkspaceInventoryDeps {
   return {

package/src/lib/package-paths.ts

@@ -3,19 +3,9 @@ import { createRequire } from "node:module";
 import path from "node:path";
 
 import { getActiveDistribution } from "../distribution";
-import { mateInstallPath } from "../runtime/install";
 
 const require = createRequire(import.meta.url);
 
-/**
- * Root of the installed mate-core package. A stamp input for the durable
- * projection: a mate installed at a different path resolves different wrapper
- * and plugin assets.
- */
-export function getMateInstallPath(): string {
-  return mateInstallPath();
-}
-
 /**
  * Resolved wrapper directory: a distribution asset root that ships
  * `wrappers/bin` wins over core's bundled default.
@@ -42,7 +32,7 @@ export function getClaudePluginRoot(): string {
   return path.resolve(import.meta.dirname, "../../claude-plugin");
 }
 
-export const CLAUDE_PLUGIN_HOOK_SHIMS = [
+const CLAUDE_PLUGIN_HOOK_SHIMS = [
   "validate-artifact-path.mjs",
   "session-banner.mjs",
   "session-guidance.mjs",

package/src/lib/package-root.ts

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Resolve the distribution package containing a CLI entrypoint.
+ *
+ * Missing manifests are skipped while walking upward; malformed manifests and
+ * filesystem errors stop the search so callers cannot guess a package root.
+ */
+export function resolvePackageRoot(
+  entrypoint: string | undefined,
+  packageName: string,
+): string | undefined {
+  if (!entrypoint || !packageName) return undefined;
+
+  let current: string;
+  try {
+    current = path.dirname(fs.realpathSync(entrypoint));
+  } catch {
+    return undefined;
+  }
+
+  while (true) {
+    try {
+      const manifest = JSON.parse(
+        fs.readFileSync(path.join(current, "package.json"), "utf8"),
+      ) as unknown;
+      if (
+        manifest &&
+        typeof manifest === "object" &&
+        (manifest as { name?: unknown }).name === packageName
+      ) {
+        return current;
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") return undefined;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}

package/src/lib/prebuilt-workspace.ts

@@ -17,7 +17,7 @@ import { getLocalWorkspaceDir } from "./preinstalled-plugins";
  * Packages the distribution selects and pins for the machine-local workspace.
  * A bundle may carry any subset; it may carry nothing else.
  */
-export function getDistributionLocalDependencies(): Record<string, string> {
+function getDistributionLocalDependencies(): Record<string, string> {
   return {
     [CONTEXT_MODE_PACKAGE_NAME]: CONTEXT_MODE_VERSION,
     [OPENCODE_PLUGIN_PACKAGE_NAME]: getCurrentVersion(),

package/src/lib/public-npm.ts

@@ -113,7 +113,7 @@ export function installPublicPackageSync(packageSpec: string, registry = PUBLIC_
   );
 }
 
-export function getNpmGlobalPackageRootSync(packageName: string): string {
+function getNpmGlobalPackageRootSync(packageName: string): string {
   const npmRoot = publicNpmDeps
     .execFileSync("npm", ["root", "-g"], {
       encoding: "utf8",