fix(deploy): pin exact runtime version in generated sandbox package.json

packages/deploy/src/bundle.test.ts

@@ -1,13 +1,16 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import os from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { bundleStager } from './bundle.js';
 import { runtimeContextEnv } from './runtime-context.js';
 import type { PersonaSpec } from '@agentworkforce/persona-kit';
 
+const require = createRequire(import.meta.url);
+
 function persona(overrides: Partial<PersonaSpec> = {}): PersonaSpec {
   return {
     id: 'bundle-fixture',
@@ -79,6 +82,18 @@ test('bundleStager produces an executable, importable bundle from a real onEvent
     const bundleSource = await readFile(result.bundlePath, 'utf8');
     assert.match(bundleSource, /^import /m);
     assert.match(bundleSource, /from\s+['"]@agentworkforce\/runtime['"]/);
+
+    // package.json pins the exact installed runtime version — never a
+    // wildcard a sandbox's npm install could silently satisfy with a
+    // stale pre-baked/cached copy.
+    const generatedPackageJson = JSON.parse(await readFile(result.packageJsonPath, 'utf8'));
+    const runtimeDep = generatedPackageJson.dependencies['@agentworkforce/runtime'];
+    const installedRuntimePackageJsonPath = require.resolve('@agentworkforce/runtime/package.json');
+    const installedRuntimeVersion = JSON.parse(
+      await readFile(installedRuntimePackageJsonPath, 'utf8')
+    ).version;
+    assert.equal(runtimeDep, installedRuntimeVersion);
+    assert.notEqual(runtimeDep, '*');
   } finally {
     await rm(dir, { recursive: true, force: true });
   }

packages/deploy/src/bundle.ts

@@ -1,9 +1,11 @@
 import { mkdir, writeFile, stat } from 'node:fs/promises';
-import { builtinModules } from 'node:module';
+import { builtinModules, createRequire } from 'node:module';
 import path from 'node:path';
 import { build } from 'esbuild';
 import type { BundleStageInput, BundleResult, BundleStager } from './types.js';
 
+const require = createRequire(import.meta.url);
+
 /**
  * Versioned identifier embedded in the generated runner so a future
  * bundle reader can detect format drift. Bumped whenever the runner
@@ -82,7 +84,7 @@ export const bundleStager: BundleStager = {
 
     await writeFile(personaCopyPath, JSON.stringify(input.persona, null, 2) + '\n', 'utf8');
 
-    await writeFile(packageJsonPath, buildPackageJson(input.persona.id), 'utf8');
+    await writeFile(packageJsonPath, buildPackageJson(input.persona.id, resolveRuntimeVersion()), 'utf8');
 
     await writeFile(runnerPath, renderRunner(), 'utf8');
 
@@ -100,7 +102,35 @@ export const bundleStager: BundleStager = {
   }
 };
 
-function buildPackageJson(personaId: string): string {
+/**
+ * Resolve the exact `@agentworkforce/runtime` version this copy of
+ * `@agentworkforce/deploy` was built against, by reading the installed
+ * package's own `package.json`. In a published install this is the exact
+ * version `workspace:*` was pinned to at publish time (see
+ * `packages/deploy/package.json`'s own dependency); in the monorepo it's
+ * whatever's checked out locally. Either way it's the version the CLI
+ * actually knows how to talk to — never a wildcard the sandbox's npm
+ * install could silently satisfy with a stale cached/pre-baked copy.
+ */
+function resolveRuntimeVersion(): string {
+  let packageJsonPath: string;
+  try {
+    packageJsonPath = require.resolve('@agentworkforce/runtime/package.json');
+  } catch (err) {
+    throw new Error(
+      `bundle: could not resolve @agentworkforce/runtime/package.json to pin an exact version (${
+        err instanceof Error ? err.message : String(err)
+      })`
+    );
+  }
+  const pkg = require(packageJsonPath) as { version?: unknown };
+  if (typeof pkg.version !== 'string' || pkg.version.length === 0) {
+    throw new Error(`bundle: ${packageJsonPath} has no valid "version" field`);
+  }
+  return pkg.version;
+}
+
+function buildPackageJson(personaId: string, runtimeVersion: string): string {
   return (
     JSON.stringify(
       {
@@ -110,10 +140,10 @@ function buildPackageJson(personaId: string): string {
         type: 'module',
         main: './runner.mjs',
         dependencies: {
-          '@agentworkforce/runtime': '*'
+          '@agentworkforce/runtime': runtimeVersion
         },
         comment:
-          'Generated by workforce deploy. The runtime dep is pinned to "*" because deploys resolve the runtime version from the active workspace.'
+          'Generated by workforce deploy. The runtime dep is pinned to the exact version this deploy CLI was built against so the sandbox installs the same runtime the bundle was compiled for, instead of trusting whatever is pre-baked or cached.'
       },
       null,
       2