@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/root/package-runtime-release.ts

@@ -10,6 +10,7 @@ import { assertRuntimeReleaseExecutionSurface } from './release-manifest';
 import { assertRuntimeReleaseExecutionCanaries } from './release-execution-canary';
 import type { RuntimeReleaseManifest } from './types';
 import { assertStorageHeadroom } from '../shared/storage-capacity';
+import { PROCESS_RUNTIME_RELEASE_CANARY_ARG } from '../execution/process-runtime/canary';
 
 export interface PackageRuntimeFileRecord {
   path: string;
@@ -35,10 +36,33 @@ export interface PackageRuntimeRelease {
 // TypeScript entrypoints import both `src/` and the top-level modular-monolith
 // roots at runtime, so retaining only `src/` creates a release that passes
 // staging but cannot start after the installed package moves or disappears.
-const PACKAGE_RUNTIME_ROOTS = ['src', 'adapters', 'packages', 'bin', 'assets', 'scripts', 'node_modules'] as const;
+const PACKAGE_RUNTIME_ROOTS = ['src', 'adapters', 'packages', 'supervisor', 'bin', 'assets', 'scripts', 'node_modules'] as const;
 const PACKAGE_RUNTIME_FILES = ['package.json'] as const;
+// Compiled releases execute only compiled/bundled artifacts. Keep a tiny package
+// projection for browser-extension installation plus two legacy Recovery
+// recognition sentinels; neither sentinel is executed when the compiled
+// Connector sidecar is present.
+const COMPILED_RUNTIME_PACKAGE_ROOTS = ['adapters/computer/chrome-extension'] as const;
+const COMPILED_RUNTIME_PACKAGE_FILES = [
+  'package.json',
+  'src/cli/index.ts',
+  'src/runtime/shared/node-ts-loader.mjs',
+] as const;
 const PACKAGE_RUNTIME_STAGING_RESERVE_BYTES = 256 * 1024 * 1024;
 
+function isNonRuntimePackageHelper(path: string): boolean {
+  if (path.startsWith('scripts/benchmark-')) return true;
+  if (path.startsWith('scripts/check-release-')) return true;
+  if (path.startsWith('scripts/public-release')) return true;
+  return path === 'scripts/route-nl-vs-ts-eval.ts'
+    || path === 'scripts/check-npm-release.sh'
+    || path === 'scripts/check-public-release-surface.sh'
+    || path === 'scripts/check-tarball-install-smoke.sh'
+    || path === 'scripts/publish-release-tarball.sh'
+    || path === 'scripts/stage-runtime-release.ts'
+    || path === 'scripts/package-source-archive.sh';
+}
+
 function sha256(value: Buffer | string): string {
   return createHash('sha256').update(value).digest('hex');
 }
@@ -50,7 +74,7 @@ function atomicWrite(path: string, content: string, mode = 0o600): void {
   renameSync(temporary, path);
 }
 
-function walkRegularFiles(root: string, current: string, output: string[]): void {
+function walkRegularFiles(root: string, current: string, output: string[], prefix = ''): void {
   if (!existsSync(current)) return;
   const stat = lstatSync(current);
   // Package managers such as Bun can materialize dependency files as
@@ -59,38 +83,89 @@ function walkRegularFiles(root: string, current: string, output: string[]): void
   // regular files beneath its own immutable package root.
   if (stat.isSymbolicLink()) {
     const target = statSync(current);
-    if (target.isFile()) output.push(relative(root, current).split('\\').join('/'));
+    if (target.isFile()) {
+      const relativePath = relative(root, current).split('\\').join('/');
+      output.push(prefix ? `${prefix}/${relativePath}` : relativePath);
+    }
     return;
   }
   if (stat.isFile()) {
-    output.push(relative(root, current).split('\\').join('/'));
+    const relativePath = relative(root, current).split('\\').join('/');
+    output.push(prefix ? `${prefix}/${relativePath}` : relativePath);
     return;
   }
   if (!stat.isDirectory()) return;
-  for (const entry of readdirSync(current).sort()) walkRegularFiles(root, join(current, entry), output);
+  for (const entry of readdirSync(current).sort()) walkRegularFiles(root, join(current, entry), output, prefix);
 }
 
-export function packageRuntimeFileIndex(packageRoot = packageRuntimeSourceRoot()): PackageRuntimeFileRecord[] {
+function packageSourcePath(packageRoot: string, path: string, dependencyRoot = packageRoot): string {
+  return path === 'node_modules' || path.startsWith('node_modules/')
+    ? join(resolve(dependencyRoot), path)
+    : join(resolve(packageRoot), path);
+}
+
+function packageFileIndex(
+  packageRoot: string,
+  roots: readonly string[],
+  files: readonly string[],
+  dependencyRoot = packageRoot,
+): PackageRuntimeFileRecord[] {
   const root = resolve(packageRoot);
+  const dependencies = resolve(dependencyRoot);
   const paths: string[] = [];
-  for (const directory of PACKAGE_RUNTIME_ROOTS) walkRegularFiles(root, join(root, directory), paths);
-  for (const file of PACKAGE_RUNTIME_FILES) walkRegularFiles(root, join(root, file), paths);
-  const unique = [...new Set(paths)].sort();
-  if (!unique.includes('package.json') || !unique.some((path) => path === 'bin/forge-runtime.mjs')) {
-    throw new Error(`PACKAGE_RUNTIME_SURFACE_INCOMPLETE: ${root}`);
+  for (const directory of roots) {
+    if (directory === 'node_modules' && dependencies !== root) {
+      const dependencyNodeModules = join(dependencies, 'node_modules');
+      walkRegularFiles(dependencyNodeModules, dependencyNodeModules, paths, 'node_modules');
+    } else {
+      walkRegularFiles(root, join(root, directory), paths);
+    }
   }
-  return unique.map((path) => {
-    const bytes = readFileSync(join(root, path));
+  for (const file of files) walkRegularFiles(root, join(root, file), paths);
+  return [...new Set(paths)].sort().map((path) => {
+    const bytes = readFileSync(packageSourcePath(root, path, dependencies));
     return { path, sha256: sha256(bytes), bytes: bytes.length };
   });
 }
 
+export function packageRuntimeFileIndex(packageRoot = packageRuntimeSourceRoot(), dependencyRoot = packageRoot): PackageRuntimeFileRecord[] {
+  const root = resolve(packageRoot);
+  const records = packageFileIndex(root, PACKAGE_RUNTIME_ROOTS, PACKAGE_RUNTIME_FILES, dependencyRoot)
+    .filter((record) => !isNonRuntimePackageHelper(record.path));
+  const paths = new Set(records.map((record) => record.path));
+  if (!paths.has('package.json') || !paths.has('bin/forge-runtime.mjs')) {
+    throw new Error(`PACKAGE_RUNTIME_SURFACE_INCOMPLETE: ${root}`);
+  }
+  return records;
+}
+
+export function compiledRuntimePackageFileIndex(packageRoot = packageRuntimeSourceRoot()): PackageRuntimeFileRecord[] {
+  const root = resolve(packageRoot);
+  const records = packageFileIndex(root, COMPILED_RUNTIME_PACKAGE_ROOTS, COMPILED_RUNTIME_PACKAGE_FILES);
+  const paths = new Set(records.map((record) => record.path));
+  for (const required of COMPILED_RUNTIME_PACKAGE_FILES) {
+    if (!paths.has(required)) throw new Error(`COMPILED_RUNTIME_PACKAGE_SURFACE_INCOMPLETE: ${required}`);
+  }
+  if (![...paths].some((path) => path.startsWith('adapters/computer/chrome-extension/'))) {
+    throw new Error('COMPILED_RUNTIME_PACKAGE_SURFACE_INCOMPLETE: adapters/computer/chrome-extension');
+  }
+  return records;
+}
+
 export function packageRuntimeFingerprint(records: PackageRuntimeFileRecord[]): string {
   const hash = createHash('sha256');
   for (const record of records) hash.update(record.path).update('\0').update(record.sha256).update('\0').update(String(record.bytes)).update('\n');
   return hash.digest('hex');
 }
 
+function packageRuntimeArtifactIdentity(root: string, records: PackageRuntimeFileRecord[]): string {
+  const hash = createHash('sha256');
+  for (const record of records) {
+    hash.update(record.path).update('\0').update(readFileSync(join(root, record.path))).update('\0');
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
 function assertPackageRuntimeSnapshot(snapshotRoot: string, records: PackageRuntimeFileRecord[]): void {
   if (!existsSync(snapshotRoot)) throw new Error('PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: package snapshot is missing');
   const rootStat = lstatSync(snapshotRoot);
@@ -111,10 +186,15 @@ function assertPackageRuntimeSnapshot(snapshotRoot: string, records: PackageRunt
   }
 }
 
-export function stagePackageRuntimeSnapshot(sourceRoot: string, snapshotRoot: string, records: PackageRuntimeFileRecord[]): void {
+export function stagePackageRuntimeSnapshot(
+  sourceRoot: string,
+  snapshotRoot: string,
+  records: PackageRuntimeFileRecord[],
+  dependencyRoot = sourceRoot,
+): void {
   mkdirSync(snapshotRoot, { recursive: false, mode: 0o700 });
   for (const record of records) {
-    const source = join(sourceRoot, record.path);
+    const source = packageSourcePath(sourceRoot, record.path, dependencyRoot);
     const link = lstatSync(source);
     const stat = link.isSymbolicLink() ? statSync(source) : link;
     if (!stat.isFile()) throw new Error(`PACKAGE_RUNTIME_SOURCE_CHANGED_DURING_STAGE: ${record.path}`);
@@ -146,6 +226,7 @@ function launcherSource(input: {
   indexSha256: string;
   entryRelativePath?: string;
   managerSignalsProcessGroup?: boolean;
+  ownsProcessRuntimeCanary?: boolean;
 }): string {
   const entryRelativePath = input.entryRelativePath ?? 'src/runtime/root/entry.ts';
   return `#!${process.execPath}\n`
@@ -154,7 +235,12 @@ function launcherSource(input: {
     + `import { dirname, join } from 'node:path';\n`
     + `import { fileURLToPath } from 'node:url';\n`
     + `import { spawn } from 'node:child_process';\n`
-    + `const releaseRoot=dirname(fileURLToPath(import.meta.url));\n`
+    // macOS runs a byte-for-byte mirror of this launcher from its fixed,
+    // TCC-stable service path. The mirrored file is not its immutable release
+    // directory, so use the launch contract's attested release binding when it
+    // is present. Direct execution from the immutable release still derives
+    // the same root from the entrypoint location.
+    + `const releaseRoot=process.env.FORGE_RELEASE_PATH?.trim()||dirname(fileURLToPath(import.meta.url));\n`
     + `const packageRoot=join(releaseRoot,'package');\n`
     + `const indexPath=join(releaseRoot,'package-files.json');\n`
     + `const expectedIndex=${JSON.stringify(input.indexSha256)};\n`
@@ -163,6 +249,8 @@ function launcherSource(input: {
     + `if(digest(raw)!==expectedIndex){console.error('FORGE_PACKAGE_RUNTIME_INDEX_CHANGED');process.exit(78);}\n`
     + `let records; try { records=JSON.parse(raw.toString('utf8')).files; } catch { console.error('FORGE_PACKAGE_RUNTIME_INDEX_INVALID'); process.exit(78); }\n`
     + `for(const record of records){const path=join(packageRoot,record.path);if(!existsSync(path)||digest(readFileSync(path))!==record.sha256){console.error('FORGE_PACKAGE_RUNTIME_SOURCE_CHANGED: '+record.path);process.exit(78);}}\n`
+    + `const ownsProcessRuntimeCanary=${input.ownsProcessRuntimeCanary === true ? 'true' : 'false'};\n`
+    + `if(ownsProcessRuntimeCanary&&process.argv.length===3&&process.argv[2]===${JSON.stringify(PROCESS_RUNTIME_RELEASE_CANARY_ARG)})process.exit(0);\n`
     + `const entry=join(packageRoot,...${JSON.stringify(entryRelativePath.split('/'))});\n`
     + `const loader=join(packageRoot,'src','runtime','shared','node-ts-loader.mjs');\n`
     + `const args=process.versions?.bun?[entry,...process.argv.slice(2)]:['--loader',loader,entry,...process.argv.slice(2)];\n`
@@ -224,7 +312,12 @@ function assertImmutablePackageRuntimeRelease(input: {
     && manifest.checkRunnerArtifactIdentity === expected.checkRunnerArtifactIdentity
     && JSON.stringify(manifest.arguments ?? []) === JSON.stringify(expected.arguments ?? [])
     && manifest.configurationSchemaVersion === expected.configurationSchemaVersion
-    && resolve(manifest.controllerHome) === resolve(expected.controllerHome)
+    && manifest.deploymentScope === expected.deploymentScope
+    && (manifest.deploymentScope === 'portable'
+      ? expected.deploymentScope === 'portable'
+      : typeof manifest.controllerHome === 'string'
+        && typeof expected.controllerHome === 'string'
+        && resolve(manifest.controllerHome) === resolve(expected.controllerHome))
     && JSON.stringify(manifest.databaseSchemaCompatibility) === JSON.stringify(expected.databaseSchemaCompatibility)
     && manifest.workerProtocolVersion === expected.workerProtocolVersion
     && manifest.releaseRevision === expected.releaseRevision
@@ -232,6 +325,7 @@ function assertImmutablePackageRuntimeRelease(input: {
     && typeof manifest.createdAt === 'string'
     && Number.isFinite(Date.parse(manifest.createdAt));
   if (!compatible) throw new Error('PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: manifest identity changed');
+  if (!expected.controllerHome) throw new Error('PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: package release must remain ControllerHome-bound');
   assertRuntimeReleaseExecutionSurface(input.manifestPath, expected.controllerHome);
 }
 
@@ -245,8 +339,9 @@ export function materializePackageRuntimeRelease(input: {
   const version = packageVersion(sourcePackageRoot);
   const records = packageRuntimeFileIndex(sourcePackageRoot);
   const fingerprint = packageRuntimeFingerprint(records);
+  const packageArtifactIdentity = packageRuntimeArtifactIdentity(sourcePackageRoot, records);
   const safeVersion = version.replace(/[^A-Za-z0-9._-]+/g, '-');
-  const launcherBinding = sha256(`${resolve(process.execPath)}\0package-launcher-v5`);
+  const launcherBinding = sha256(`${resolve(process.execPath)}\0package-launcher-v9`);
   const releaseId = `package-${safeVersion}-${fingerprint.slice(0, 16)}-${launcherBinding.slice(0, 12)}`;
   const releasesRoot = join(controllerHome, 'runtime', 'releases');
   const releaseRoot = join(releasesRoot, releaseId);
@@ -262,6 +357,7 @@ export function materializePackageRuntimeRelease(input: {
   const processRunnerLauncher = launcherSource({
     indexSha256,
     entryRelativePath: 'src/runtime/execution/process-runtime/process-runner-entry.ts',
+    ownsProcessRuntimeCanary: true,
   });
   const processRunnerArtifactIdentity = `sha256:${sha256(Buffer.from(processRunnerLauncher))}`;
   const checkRunnerEntrypoint = 'forge-check-runner' as const;
@@ -269,6 +365,7 @@ export function materializePackageRuntimeRelease(input: {
   const checkRunnerLauncher = launcherSource({
     indexSha256,
     entryRelativePath: 'src/runtime/execution/process-runtime/check-runner-sidecar.ts',
+    ownsProcessRuntimeCanary: true,
   });
   const checkRunnerArtifactIdentity = `sha256:${sha256(Buffer.from(checkRunnerLauncher))}`;
   const expectedManifest: Omit<RuntimeReleaseManifest, 'createdAt'> = {
@@ -280,6 +377,8 @@ export function materializePackageRuntimeRelease(input: {
     processRunnerArtifactIdentity,
     checkRunnerEntrypoint,
     checkRunnerArtifactIdentity,
+    packageRoot: 'package',
+    packageArtifactIdentity,
     arguments: [],
     configurationSchemaVersion: 1,
     controllerHome,

package/src/runtime/root/package-runtime-service.ts

@@ -4,7 +4,8 @@ import { setTimeout as sleep } from 'timers/promises';
 import { dirname, join, resolve } from 'path';
 import { resolveControllerHome } from '../../cli/repositories/controller-home';
 import { createPlatformServiceManagerHost, probeSystemdUserAvailable, type PlatformServiceManagerHost, type PlatformServiceManagerKind, type SystemdUserUnitInput } from '../platform/service-manager';
-import { RUNTIME_WRITE_CLAIM_ENV } from './write-fence';
+import { reconcileRetiredForgePersistentServices, type ForgeRetiredServiceReconciliation } from '../platform/service-inventory';
+import { runtimeAuthorityFreeEnvironment } from '../shared/process-environment';
 import {
   activeRuntimeEntrypoint,
   activeRuntimeLaunchSpec,
@@ -19,6 +20,7 @@ import { materializePackageRuntimeRelease, type PackageRuntimeRelease } from './
 import { readRuntimeReleaseAuthority, revertInitialRuntimeReleasePublication, rollbackRuntimeRelease } from './release-store';
 import { loadMcpServiceLocalConfig } from '../../../adapters/mcp/auth';
 import { ensurePackageConnectorService, type PackageConnectorServiceResult } from './package-connector-service';
+import { normalizeRuntimeDeploymentTopology, type RuntimeDeploymentTopology } from './deployment-topology';
 
 export type PackageRuntimeServiceMode = PlatformServiceManagerKind;
 
@@ -74,6 +76,7 @@ export interface PackageRuntimeServiceInstallResult {
   pid?: number;
   warnings: string[];
   connector?: PackageConnectorServiceResult;
+  retiredServices?: ForgeRetiredServiceReconciliation[];
   activation?: {
     operationId: string;
     status: 'activation_scheduled';
@@ -89,11 +92,11 @@ export interface PackageRuntimeServiceOptions {
   host?: string;
   port?: number;
   authTokenFile: string;
-  exclusiveWorkId?: string;
   platform?: NodeJS.Platform;
   env?: NodeJS.ProcessEnv;
   forcePortable?: boolean;
   refreshConnector?: boolean;
+  topology?: RuntimeDeploymentTopology;
 }
 
 export interface PackageRuntimeServiceDependencies {
@@ -101,6 +104,7 @@ export interface PackageRuntimeServiceDependencies {
   ensureConnectorService?: typeof ensurePackageConnectorService;
   scheduleDarwinActivation?: (request: PackageRuntimeActivationRequest) => Promise<{ label: string; servicePath: string }>;
   activationMode?: 'detached' | 'inline';
+  reconcileRetiredServices?: typeof reconcileRetiredForgePersistentServices;
 }
 
 export interface PackageRuntimeActivationDependencies {
@@ -131,14 +135,10 @@ export function systemdUserAvailable(env: NodeJS.ProcessEnv = process.env): bool
 }
 
 function cleanRuntimeInstallerEnvironment(env: NodeJS.ProcessEnv, releaseEnvironment: Record<string, string>): NodeJS.ProcessEnv {
-  const next = { ...env };
-  for (const key of Object.values(RUNTIME_WRITE_CLAIM_ENV)) delete next[key];
-  delete next.FORGE_CONTROLLER_LIFECYCLE_OWNER;
-  delete next.FORGE_RELEASE_PATH;
-  delete next.FORGE_RELEASE_REVISION;
-  delete next.FORGE_RELEASE_SOURCE_COMMIT;
-  delete next.FORGE_RELEASE_CLEAN_WORKSPACE;
-  return { ...next, ...releaseEnvironment };
+  // The selected immutable release is the only authority reintroduced below.
+  // Do not carry an installer, host Runtime or Supervisor writer claim across
+  // this service boundary.
+  return { ...runtimeAuthorityFreeEnvironment(env), ...releaseEnvironment };
 }
 
 export function systemdRuntimeInstallCommands(unitName: string): string[][] {
@@ -471,7 +471,7 @@ export async function installPackageRuntimeService(
     host: options.host ?? '127.0.0.1',
     port: options.port ?? 8765,
     authTokenFile: options.authTokenFile,
-    ...(options.exclusiveWorkId?.trim() ? { exclusiveWorkId: options.exclusiveWorkId.trim() } : {}),
+    topology: normalizeRuntimeDeploymentTopology(options.topology),
   };
   writeForgeRuntimeServiceConfig(config);
   syncForgeRuntimeActiveEntrypoint(controllerHome);
@@ -479,6 +479,11 @@ export async function installPackageRuntimeService(
   const env = options.env ?? process.env;
   const serviceHost = createPlatformServiceManagerHost({ platform, env, forcePortable: options.forcePortable });
   const serviceManager = serviceHost.selection;
+  const retiredServices = await (dependencies.reconcileRetiredServices ?? reconcileRetiredForgePersistentServices)({
+    host: serviceHost,
+    env,
+    accountHome: env.HOME,
+  });
   const installDarwinService = dependencies.installDarwinService ?? installForgeRuntimeService;
   const explicitInjectedInline = Boolean(dependencies.installDarwinService && !dependencies.scheduleDarwinActivation && !dependencies.activationMode);
   const activationMode = dependencies.activationMode ?? (explicitInjectedInline ? 'inline' : 'detached');
@@ -592,6 +597,7 @@ export async function installPackageRuntimeService(
     }
   }
 
+  base = { ...base, retiredServices };
   if (!connectorEndpoint || base.status === 'activation_scheduled') return base;
   const ensureConnectorService = dependencies.ensureConnectorService ?? ensurePackageConnectorService;
   const connector = await ensureConnectorService({

package/src/runtime/root/release-execution-canary.ts

@@ -1,12 +1,14 @@
+import { join } from 'path';
 import { runProcess } from '../../effects/process-runner';
 import { PROCESS_RUNTIME_RELEASE_CANARY_ARG } from '../execution/process-runtime/canary';
+import { resolveBunExecutable } from '../shared/process-environment';
 import {
   assertRuntimeReleaseExecutionSurface,
   type RuntimeReleaseExecutionSurface,
 } from './release-manifest';
 
 export interface RuntimeReleaseExecutionCanaryCommand {
-  name: RuntimeReleaseExecutionSurface['entries'][number]['name'];
+  name: RuntimeReleaseExecutionSurface['entries'][number]['name'] | 'connector_cli';
   executable: string;
   args: string[];
 }
@@ -22,8 +24,10 @@ export interface RuntimeReleaseExecutionCanaryDependencies {
 
 /**
  * Release execution canaries deliberately do not inherit developer-tool PATH
- * entries. A manifest-owned executable that only works because Homebrew, Bun,
- * nvm, etc. happens to be present is not an immutable Runtime artifact.
+ * entries. Standalone-binary artifacts must execute without Homebrew, Bun, nvm,
+ * or similar PATH dependencies. Legacy script releases predate the embedded
+ * Runtime interpreter and are probed through the same explicitly resolved Bun
+ * executable that their Process Runtime uses in production.
  */
 export function runtimeReleaseCanaryEnvironment(
   env: NodeJS.ProcessEnv = process.env,
@@ -39,7 +43,12 @@ export function runtimeReleaseCanaryEnvironment(
   return { ...env, PATH: '/usr/bin:/bin:/usr/sbin:/sbin' };
 }
 
-/** Execute the exact manifest-owned Process/Check Runner artifacts in bounded no-op mode. */
+/**
+ * Execute the minimum immutable Runtime execution surface plus the package
+ * Connector CLI import graph. The latter is intentionally a help-only command:
+ * it loads the exact CLI dependency closure used by the persistent Connector
+ * without opening a listener or mutating Runtime authority.
+ */
 export function assertRuntimeReleaseExecutionCanaries(
   manifestPath: string,
   controllerHome: string,
@@ -52,20 +61,43 @@ export function assertRuntimeReleaseExecutionCanaries(
     {
       cwd: surface.releaseRoot,
       env: runtimeReleaseCanaryEnvironment(),
-      timeoutMs: 10_000,
+      timeoutMs: 30_000,
       maxOutputBytes: 64 * 1024,
     },
   ));
-  for (const entry of surface.entries) {
-    const canary: RuntimeReleaseExecutionCanaryCommand = {
-      name: entry.name,
-      executable: entry.path,
-      args: [PROCESS_RUNTIME_RELEASE_CANARY_ARG],
-    };
+  const assertCanary = (canary: RuntimeReleaseExecutionCanaryCommand): void => {
     const result = runExecutionEntryCanary(canary);
     if (!result.ok) {
-      throw new Error(`RUNTIME_RELEASE_EXECUTION_CANARY_FAILED: ${canary.name}: ${result.stderr || result.stdout || result.error || 'unknown failure'}`.slice(0, 2_000));
+      const detail = result.stderr || result.stdout || result.error || 'unknown failure';
+      const legacyCheckRunnerUsageProbe = surface.manifest.executionMode !== 'standalone-binary'
+        && canary.name === 'check_runner'
+        && detail.trim() === 'PERSISTED_CHECK_USAGE: missing --repo';
+      if (legacyCheckRunnerUsageProbe) return;
+      throw new Error(`RUNTIME_RELEASE_EXECUTION_CANARY_FAILED: ${canary.name}: ${detail}`.slice(0, 2_000));
     }
+  };
+
+  for (const entry of surface.entries) {
+    const args = entry.canary === 'runtime_interpreter' ? ['--version'] : [PROCESS_RUNTIME_RELEASE_CANARY_ARG];
+    const legacyScript = surface.manifest.executionMode !== 'standalone-binary'
+      && /\.(?:[cm]?js|tsx?)$/i.test(entry.path);
+    assertCanary({
+      name: entry.name,
+      executable: legacyScript ? resolveBunExecutable(process.execPath, process.env) : entry.path,
+      args: legacyScript ? [entry.path, ...args] : args,
+    });
   }
+
+  // Package launcher releases execute source-backed CLI code from their own
+  // immutable snapshot. Compiled standalone releases have a different closed
+  // artifact surface and therefore do not use this source CLI probe.
+  if (surface.manifest.executionMode !== 'standalone-binary' && surface.manifest.packageRoot) {
+    assertCanary({
+      name: 'connector_cli',
+      executable: resolveBunExecutable(process.execPath, process.env),
+      args: [join(surface.releaseRoot, 'package', 'src', 'cli', 'index.ts'), 'mcp', 'serve', '--help'],
+    });
+  }
+
   return surface;
 }

package/src/runtime/root/release-loader.ts

@@ -1,13 +1,18 @@
+import { spawn } from 'child_process';
 import { createHash } from 'crypto';
-import { readFileSync } from 'fs';
+import { lstatSync, readFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
-import { pathToFileURL } from 'url';
 
 export const RUNTIME_BUNDLE_ENTRYPOINT = 'forge-runtime-bundle.js' as const;
+export const RUNTIME_INTERPRETER_ENTRYPOINT = process.platform === 'win32'
+  ? 'forge-runtime-bun.exe' as const
+  : 'forge-runtime-bun' as const;
 
 interface RuntimeBundleManifestRecord {
   runtimeBundleEntrypoint?: unknown;
   runtimeBundleArtifactIdentity?: unknown;
+  runtimeInterpreterEntrypoint?: unknown;
+  runtimeInterpreterArtifactIdentity?: unknown;
 }
 
 function releaseManifestPath(argv: readonly string[]): string {
@@ -21,6 +26,8 @@ export function resolveCompiledRuntimeBundle(argv: readonly string[] = process.a
   manifestPath: string;
   bundlePath: string;
   artifactIdentity: string;
+  interpreterPath: string;
+  interpreterArtifactIdentity: string;
 } {
   const manifestPath = releaseManifestPath(argv);
   let manifest: RuntimeBundleManifestRecord;
@@ -38,9 +45,14 @@ export function resolveCompiledRuntimeBundle(argv: readonly string[] = process.a
   if (!/^sha256:[a-f0-9]{64}$/.test(artifactIdentity)) {
     throw new Error('RUNTIME_RELEASE_BUNDLE_IDENTITY_INVALID');
   }
-  const bundlePath = join(dirname(manifestPath), RUNTIME_BUNDLE_ENTRYPOINT);
+  const releaseRoot = dirname(manifestPath);
+  const bundlePath = join(releaseRoot, RUNTIME_BUNDLE_ENTRYPOINT);
   let actualIdentity: string;
   try {
+    const status = lstatSync(bundlePath);
+    if (status.isSymbolicLink() || !status.isFile()) {
+      throw new Error('bundle must be a regular file');
+    }
     actualIdentity = `sha256:${createHash('sha256').update(readFileSync(bundlePath)).digest('hex')}`;
   } catch (error) {
     throw new Error(`RUNTIME_RELEASE_BUNDLE_READ_FAILED: ${error instanceof Error ? error.message : String(error)}`);
@@ -48,16 +60,86 @@ export function resolveCompiledRuntimeBundle(argv: readonly string[] = process.a
   if (actualIdentity !== artifactIdentity) {
     throw new Error('RUNTIME_RELEASE_BUNDLE_ARTIFACT_IDENTITY_MISMATCH');
   }
-  return { manifestPath, bundlePath, artifactIdentity };
+  if (manifest.runtimeInterpreterEntrypoint !== RUNTIME_INTERPRETER_ENTRYPOINT) {
+    throw new Error(`RUNTIME_RELEASE_INTERPRETER_ENTRYPOINT_INVALID: expected ${RUNTIME_INTERPRETER_ENTRYPOINT}`);
+  }
+  const interpreterArtifactIdentity = typeof manifest.runtimeInterpreterArtifactIdentity === 'string'
+    ? manifest.runtimeInterpreterArtifactIdentity.trim().toLowerCase()
+    : '';
+  if (!/^sha256:[a-f0-9]{64}$/.test(interpreterArtifactIdentity)) {
+    throw new Error('RUNTIME_RELEASE_INTERPRETER_IDENTITY_INVALID');
+  }
+  const interpreterPath = join(releaseRoot, RUNTIME_INTERPRETER_ENTRYPOINT);
+  let actualInterpreterIdentity: string;
+  try {
+    const status = lstatSync(interpreterPath);
+    if (status.isSymbolicLink() || !status.isFile() || (status.mode & 0o111) === 0) {
+      throw new Error('interpreter must be a regular executable file');
+    }
+    actualInterpreterIdentity = `sha256:${createHash('sha256').update(readFileSync(interpreterPath)).digest('hex')}`;
+  } catch (error) {
+    throw new Error(`RUNTIME_RELEASE_INTERPRETER_READ_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (actualInterpreterIdentity !== interpreterArtifactIdentity) {
+    throw new Error('RUNTIME_RELEASE_INTERPRETER_ARTIFACT_IDENTITY_MISMATCH');
+  }
+  return { manifestPath, bundlePath, artifactIdentity, interpreterPath, interpreterArtifactIdentity };
+}
+
+function runtimeChildArgs(argv: readonly string[]): string[] {
+  const firstRuntimeArgument = argv.findIndex((argument) => argument.startsWith('--'));
+  if (firstRuntimeArgument < 0 || !argv.includes('--controller-home')) {
+    throw new Error('RUNTIME_CONTROLLER_HOME_ARGUMENT_REQUIRED');
+  }
+  return argv.slice(firstRuntimeArgument);
 }
 
 export async function runCompiledRuntimeLoader(argv: string[] = process.argv): Promise<void> {
   const bundle = resolveCompiledRuntimeBundle(argv);
-  const loaded = await import(pathToFileURL(bundle.bundlePath).href) as { runCanonicalRuntimeCli?: (argv?: string[]) => Promise<void> };
-  if (typeof loaded.runCanonicalRuntimeCli !== 'function') {
-    throw new Error('RUNTIME_RELEASE_BUNDLE_ENTRY_EXPORT_MISSING');
+  const child = spawn(bundle.interpreterPath, [bundle.bundlePath, ...runtimeChildArgs(argv)], {
+    cwd: dirname(bundle.manifestPath),
+    stdio: 'inherit',
+    env: process.env,
+  });
+  let childExited = false;
+  const forwardSignal = (signal: NodeJS.Signals): void => {
+    if (childExited) return;
+    try { child.kill(signal); } catch { /* child lifecycle reconciliation owns terminal state */ }
+  };
+  const terminateChildOnLauncherExit = (): void => {
+    if (childExited) return;
+    try { child.kill('SIGTERM'); } catch { /* launcher is already exiting */ }
+  };
+  const forwardedSignals: NodeJS.Signals[] = process.platform === 'win32'
+    ? ['SIGINT', 'SIGTERM']
+    : ['SIGINT', 'SIGTERM', 'SIGUSR1', 'SIGUSR2'];
+  const signalHandlers = new Map<NodeJS.Signals, () => void>();
+  for (const signal of forwardedSignals) {
+    const handler = () => forwardSignal(signal);
+    signalHandlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+  process.once('exit', terminateChildOnLauncherExit);
+  try {
+    const outcome = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolveChild, rejectChild) => {
+      child.once('error', rejectChild);
+      child.once('exit', (code, signal) => {
+        childExited = true;
+        resolveChild({ code, signal });
+      });
+    });
+    if (outcome.signal) {
+      for (const [signal, handler] of signalHandlers) process.off(signal, handler);
+      signalHandlers.clear();
+      process.off('exit', terminateChildOnLauncherExit);
+      process.kill(process.pid, outcome.signal);
+      return;
+    }
+    if (outcome.code !== 0) process.exitCode = outcome.code ?? 1;
+  } finally {
+    for (const [signal, handler] of signalHandlers) process.off(signal, handler);
+    process.off('exit', terminateChildOnLauncherExit);
   }
-  await loaded.runCanonicalRuntimeCli(argv);
 }
 
 if (import.meta.main) {