@uniqbit/mate-core 0.17.0-canary.2 → 0.17.0-canary.5

package/package.json

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

package/src/lib/node-engine-version.ts

@@ -0,0 +1,15 @@
+/**
+ * The Node.js version an `engines.node` range may be enforced against, or null
+ * where there is none to enforce.
+ *
+ * Under Bun, `process.versions.node` is a compatibility claim rather than an
+ * installed Node release: it trails upstream on Bun's own schedule, and Bun
+ * ignores `engines` when loading a package anyway. Comparing a real range such
+ * as `^24.15.0` against that claim refuses graphs the runtime loads perfectly
+ * well, so there is nothing meaningful to compare and the check is skipped.
+ */
+export function enforceableNodeVersion(
+  versions: NodeJS.ProcessVersions = process.versions,
+): string | null {
+  return versions.bun === undefined ? versions.node : null;
+}

package/src/lib/prebuilt-workspace.ts

@@ -10,6 +10,7 @@ import {
   CONTEXT_MODE_PACKAGE_NAME,
   CONTEXT_MODE_VERSION,
 } from "./context-mode-package";
+import { enforceableNodeVersion } from "./node-engine-version";
 import { getLocalWorkspaceDir } from "./preinstalled-plugins";
 
 /**
@@ -41,7 +42,8 @@ const DECLARED_NODE_REQUIREMENTS: Record<string, string> = {
 export interface PrebuiltWorkspaceTarget {
   platform: string;
   arch: string;
-  nodeVersion: string;
+  /** Null where no installed Node release backs the runtime, which leaves `engines.node` unenforced. */
+  nodeVersion: string | null;
 }
 
 export interface PrebuiltWorkspaceValidation {
@@ -53,7 +55,7 @@ export interface PrebuiltWorkspaceValidation {
 }
 
 export function currentTarget(): PrebuiltWorkspaceTarget {
-  return { platform: process.platform, arch: process.arch, nodeVersion: process.versions.node };
+  return { platform: process.platform, arch: process.arch, nodeVersion: enforceableNodeVersion() };
 }
 
 interface InstalledManifest {
@@ -182,7 +184,11 @@ export async function validatePrebuiltWorkspace(
     }
 
     const declaredRequirement = DECLARED_NODE_REQUIREMENTS[name];
-    if (declaredRequirement && !semver.satisfies(target.nodeVersion, declaredRequirement)) {
+    if (
+      declaredRequirement &&
+      target.nodeVersion !== null &&
+      !semver.satisfies(target.nodeVersion, declaredRequirement)
+    ) {
       failures.push(
         `${name}: requires Node.js ${declaredRequirement}; the target runs ${target.nodeVersion}.`,
       );
@@ -215,7 +221,11 @@ export async function validatePrebuiltWorkspace(
         `${name}: built for ${installed.cpu.join(", ")}; the target architecture is ${target.arch}.`,
       );
     }
-    if (installed.engines?.node && !semver.satisfies(target.nodeVersion, installed.engines.node)) {
+    if (
+      installed.engines?.node &&
+      target.nodeVersion !== null &&
+      !semver.satisfies(target.nodeVersion, installed.engines.node)
+    ) {
       failures.push(
         `${name}: requires Node.js ${installed.engines.node}; the target runs ${target.nodeVersion}.`,
       );

package/src/lib/preinstalled-plugins.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import semver from "semver";
 
 import { FRAMEWORK_NAME } from "../framework";
+import { enforceableNodeVersion } from "./node-engine-version";
 
 /**
  * A plugin reference bound to installed files is an absolute path to the
@@ -49,7 +50,7 @@ export async function resolvePreinstalledPluginReference(
   companionPath: string,
   packageName: string,
   expectedVersion: string,
-  nodeVersion: string = process.versions.node,
+  nodeVersion: string | null = enforceableNodeVersion(),
 ): Promise<string | null> {
   const workspace = getLocalWorkspaceDir(companionPath);
   const supplied = await fs.access(path.join(workspace, PREBUILT_BUNDLE_MARKER)).then(
@@ -73,7 +74,11 @@ export async function resolvePreinstalledPluginReference(
       `${packageName}: the installed copy at ${dir} is ${manifest.version ?? "an unknown version"}; the capability declares ${expectedVersion}.`,
     );
   }
-  if (manifest.engines?.node && !semver.satisfies(nodeVersion, manifest.engines.node)) {
+  if (
+    manifest.engines?.node &&
+    nodeVersion !== null &&
+    !semver.satisfies(nodeVersion, manifest.engines.node)
+  ) {
     throw new PreinstalledPluginMismatchError(
       `${packageName}: the installed copy at ${dir} requires Node.js ${manifest.engines.node}; this runtime is ${nodeVersion}.`,
     );

package/src/tools/setup/__snapshots__/runtime-surface-golden.test.ts.snap

@@ -241,7 +241,7 @@ exports[`runtime surface golden fixtures setup graphify × opencode 1`] = `
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -277,7 +277,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -367,7 +367,7 @@ exports[`runtime surface golden fixtures setup graphify × opencode 3`] = `
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -460,7 +460,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -496,7 +496,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -717,7 +717,7 @@ exports[`runtime surface golden fixtures setup graphify × claude+opencode 3`] =
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -1019,7 +1019,7 @@ exports[`runtime surface golden fixtures setup tokensave × opencode 1`] = `
       },
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -1034,7 +1034,7 @@ exports[`runtime surface golden fixtures setup tokensave × opencode 1`] = `
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -1121,7 +1121,7 @@ exports[`runtime surface golden fixtures setup tokensave × opencode 3`] = `
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -1257,7 +1257,7 @@ exports[`runtime surface golden fixtures setup tokensave × claude+opencode 1`]
       },
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -1272,7 +1272,7 @@ exports[`runtime surface golden fixtures setup tokensave × claude+opencode 1`]
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -1505,7 +1505,7 @@ exports[`runtime surface golden fixtures setup tokensave × claude+opencode 3`]
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -1747,7 +1747,7 @@ Canonical Mate policy and any more specific tool-routing instructions remain aut
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
       "context-mode@1.0.169",
     ],
     "references": {
@@ -1763,7 +1763,7 @@ Canonical Mate policy and any more specific tool-routing instructions remain aut
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
       "context-mode@1.0.169",
     ],
   },
@@ -1843,7 +1843,7 @@ exports[`runtime surface golden fixtures setup context-mode × opencode 3`] = `
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -1913,7 +1913,7 @@ Canonical Mate policy and any more specific tool-routing instructions remain aut
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
       "context-mode@1.0.169",
     ],
     "references": {
@@ -1929,7 +1929,7 @@ Canonical Mate policy and any more specific tool-routing instructions remain aut
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
       "context-mode@1.0.169",
     ],
   },
@@ -2129,7 +2129,7 @@ exports[`runtime surface golden fixtures setup context-mode × claude+opencode 3
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -2377,7 +2377,7 @@ exports[`runtime surface golden fixtures setup react-doctor × opencode 1`] = `
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -2395,7 +2395,7 @@ exports[`runtime surface golden fixtures setup react-doctor × opencode 1`] = `
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -2474,7 +2474,7 @@ exports[`runtime surface golden fixtures setup react-doctor × opencode 3`] = `
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -2567,7 +2567,7 @@ exports[`runtime surface golden fixtures setup react-doctor × claude+opencode 1
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -2585,7 +2585,7 @@ exports[`runtime surface golden fixtures setup react-doctor × claude+opencode 1
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -2783,7 +2783,7 @@ exports[`runtime surface golden fixtures setup react-doctor × claude+opencode 3
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -3047,7 +3047,7 @@ exports[`runtime surface golden fixtures setup openspec × opencode 1`] = `
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -3080,7 +3080,7 @@ exports[`runtime surface golden fixtures setup openspec × opencode 1`] = `
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -3161,7 +3161,7 @@ exports[`runtime surface golden fixtures setup openspec × opencode 3`] = `
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -3255,7 +3255,7 @@ exports[`runtime surface golden fixtures setup openspec × claude+opencode 1`] =
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -3288,7 +3288,7 @@ exports[`runtime surface golden fixtures setup openspec × claude+opencode 1`] =
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -3503,7 +3503,7 @@ exports[`runtime surface golden fixtures setup openspec × claude+opencode 3`] =
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -3723,7 +3723,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
       },
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
       "context-mode@1.0.169",
     ],
     "references": {
@@ -3779,7 +3779,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
       "context-mode@1.0.169",
     ],
   },
@@ -4050,7 +4050,7 @@ exports[`runtime surface golden fixtures setup all capabilities × claude+openco
         ],
         "kind": "list",
         "values": [
-          "@uniqbit/mate-opencode-plugin@0.16.0",
+          "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
         ],
       },
       {
@@ -4126,7 +4126,7 @@ exports[`runtime surface golden fixtures teardown graphify × claude+opencode 1`
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -4141,7 +4141,7 @@ exports[`runtime surface golden fixtures teardown graphify × claude+opencode 1`
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -4188,7 +4188,7 @@ exports[`runtime surface golden fixtures teardown tokensave × claude+opencode 1
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -4203,7 +4203,7 @@ exports[`runtime surface golden fixtures teardown tokensave × claude+opencode 1
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -4251,7 +4251,7 @@ exports[`runtime surface golden fixtures teardown context-mode × claude+opencod
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -4266,7 +4266,7 @@ exports[`runtime surface golden fixtures teardown context-mode × claude+opencod
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -4313,7 +4313,7 @@ exports[`runtime surface golden fixtures teardown react-doctor × claude+opencod
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -4328,7 +4328,7 @@ exports[`runtime surface golden fixtures teardown react-doctor × claude+opencod
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }
@@ -4375,7 +4375,7 @@ exports[`runtime surface golden fixtures teardown openspec × claude+opencode 1`
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
     "references": {
       "mate": "..",
@@ -4390,7 +4390,7 @@ exports[`runtime surface golden fixtures teardown openspec × claude+opencode 1`
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.16.0",
+      "@uniqbit/mate-opencode-plugin@0.17.0-canary.2",
     ],
   },
 }

package/src/tools/setup/capabilities/context-mode.ts

@@ -11,6 +11,7 @@ import {
   validateContextModePackage,
 } from "../../../lib/context-mode-package";
 import { warmOpenCodePackageCache } from "../../../lib/opencode-plugin-package";
+import { isPreinstalledPluginPath } from "../../../lib/preinstalled-plugins";
 import type {
   CapabilityPlugin,
   LaunchPreflightContext,
@@ -70,17 +71,60 @@ async function assertNoMcpConflict(ctx: SetupContext, provider: "claude" | "open
   }
 }
 
+/**
+ * The version behind a reference bound to an installed copy.
+ *
+ * A published reference carries its version in the string; a bound one carries
+ * it in the package it points at, so staleness has to be read off disk.
+ */
+async function installedVersionAt(packageRoot: string): Promise<string | undefined> {
+  try {
+    const manifest = JSON.parse(
+      await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
+    ) as { version?: string };
+    return manifest.version;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Both spellings of a current reference are accepted, because the Runtime
+ * Surface writes either one: the published spec on an ordinary workstation, and
+ * an absolute path into the machine-local workspace where the distribution
+ * supplied an installed copy. Accepting only the first would refuse the launch
+ * on exactly the deployments preinstalled binding exists for.
+ *
+ * Staleness is still caught in both cases — a published reference by its
+ * version, a bound one by the version of the copy it points at — so this is not
+ * the looser check it might look like.
+ */
 async function validateOpenCodeReferences(ctx: LaunchPreflightContext): Promise<string[]> {
   const expected = getContextModePackageReference();
   const diagnostics: string[] = [];
   for (const name of ["opencode.json", "tui.json"]) {
     const configPath = path.join(ctx.companionPath, ".opencode", name);
     const { config } = await readOpenCodeConfig(configPath);
-    if (!getOpenCodePluginReferences(config).includes(expected)) {
+    const references = getOpenCodePluginReferences(config);
+    if (references.includes(expected)) continue;
+
+    const bound = references.find(
+      (reference): reference is string =>
+        typeof reference === "string" &&
+        isPreinstalledPluginPath(reference, CONTEXT_MODE_PACKAGE_NAME),
+    );
+    if (bound !== undefined) {
+      const version = await installedVersionAt(bound);
+      if (version === CONTEXT_MODE_VERSION) continue;
       diagnostics.push(
-        `Missing or stale context-mode package reference in ${configPath}; expected ${expected}.`,
+        `Stale context-mode package reference in ${configPath}; it points at ${bound}, which is ${version ?? "not installed"} rather than ${CONTEXT_MODE_VERSION}.`,
       );
+      continue;
     }
+
+    diagnostics.push(
+      `Missing or stale context-mode package reference in ${configPath}; expected ${expected}.`,
+    );
   }
   return diagnostics;
 }

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

@@ -6,7 +6,7 @@ import { promisify } from "node:util";
 import { getOpenSpecSchemaSelection } from "../../../lib/orchestrator/setup-compatibilities";
 import { getWrapperBinPath } from "../../../lib/package-paths";
 import { fetchPublicPackageVersion } from "../../../lib/public-npm";
-import { isNewer } from "../../../lib/update-checker";
+import { isNewer, isPinnedDeployment } from "../../../lib/update-checker";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { confirm } from "../../../cli/confirm";
 import type { CapabilityPlugin, RuntimeContributionsByRuntime, SetupContext } from "../plugin";
@@ -63,6 +63,7 @@ export interface OpenSpecPluginDeps {
   wrapperBinPath?: () => string;
   getInstalledVersion?: (pathValue: string) => Promise<string | undefined>;
   fetchLatestVersion?: () => Promise<string | undefined>;
+  isPinnedDeployment?: () => boolean;
 }
 
 const OPEN_SPEC_SUPPORTED_TOOLS = Object.keys(OPENSPEC_TOOL_DIRS) as OpenSpecTool[];
@@ -170,10 +171,17 @@ async function updateOpenSpecIfOutdated(
   deps: Required<
     Pick<
       OpenSpecPluginDeps,
-      "installCommand" | "pathValue" | "getInstalledVersion" | "fetchLatestVersion"
+      | "installCommand"
+      | "pathValue"
+      | "getInstalledVersion"
+      | "fetchLatestVersion"
+      | "isPinnedDeployment"
     >
   >,
 ): Promise<void> {
+  /** Pinned artifacts change tool versions by replacement, never reconciliation. */
+  if (deps.isPinnedDeployment()) return;
+
   const installed = await deps.getInstalledVersion(deps.pathValue());
   if (!installed) return;
 
@@ -204,6 +212,7 @@ async function ensureOpenSpecInstalled(
       | "pathValue"
       | "getInstalledVersion"
       | "fetchLatestVersion"
+      | "isPinnedDeployment"
     >
   >,
 ): Promise<boolean> {
@@ -326,6 +335,7 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
     wrapperBinPath: deps.wrapperBinPath ?? getWrapperBinPath,
     getInstalledVersion: deps.getInstalledVersion ?? defaultGetInstalledVersion,
     fetchLatestVersion: deps.fetchLatestVersion ?? defaultFetchLatestVersion,
+    isPinnedDeployment: deps.isPinnedDeployment ?? (() => isPinnedDeployment()),
   };
 
   return {