@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -1,11 +1,11 @@
 import { randomUUID } from 'crypto';
-import { spawn, spawnSync, type SpawnSyncReturns } from 'child_process';
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
-import { homedir } from 'os';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
 import { setTimeout as sleep } from 'timers/promises';
 import { dirname, join, resolve } from 'path';
 import { resolveControllerHome } from '../../cli/repositories/controller-home';
-import { RUNTIME_WRITE_CLAIM_ENV } from './write-fence';
+import { createPlatformServiceManagerHost, probeSystemdUserAvailable, type PlatformServiceManagerHost, type PlatformServiceManagerKind, type SystemdUserUnitInput } from '../platform/service-manager';
+import { reconcileRetiredForgePersistentServices, type ForgeRetiredServiceReconciliation } from '../platform/service-inventory';
+import { runtimeAuthorityFreeEnvironment } from '../shared/process-environment';
 import {
   activeRuntimeEntrypoint,
   activeRuntimeLaunchSpec,
@@ -18,16 +18,11 @@ import {
 } from './service';
 import { materializePackageRuntimeRelease, type PackageRuntimeRelease } from './package-runtime-release';
 import { readRuntimeReleaseAuthority, revertInitialRuntimeReleasePublication, rollbackRuntimeRelease } from './release-store';
-import { loadMcpServiceLocalConfig } from '../../cli/mcp/auth';
+import { loadMcpServiceLocalConfig } from '../../../adapters/mcp/auth';
 import { ensurePackageConnectorService, type PackageConnectorServiceResult } from './package-connector-service';
-import {
-  bootstrapLaunchAgentWithRetryV2,
-  currentUserLaunchdDomain,
-  installLaunchAgent,
-  launchAgentPath,
-} from '../../cli/controller/launch-agents';
+import { normalizeRuntimeDeploymentTopology, type RuntimeDeploymentTopology } from './deployment-topology';
 
-export type PackageRuntimeServiceMode = 'launchd' | 'systemd-user' | 'portable';
+export type PackageRuntimeServiceMode = PlatformServiceManagerKind;
 
 export type PackageRuntimeActivationStatus = 'activation_scheduled' | 'activated' | 'failed+rollback';
 
@@ -81,6 +76,7 @@ export interface PackageRuntimeServiceInstallResult {
   pid?: number;
   warnings: string[];
   connector?: PackageConnectorServiceResult;
+  retiredServices?: ForgeRetiredServiceReconciliation[];
   activation?: {
     operationId: string;
     status: 'activation_scheduled';
@@ -96,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 {
@@ -108,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 {
@@ -124,109 +121,76 @@ function atomicWrite(path: string, content: string, mode = 0o600): void {
   renameSync(temporary, path);
 }
 
-function systemdEscape(value: string): string {
-  return `"${value.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
-}
-
 export function renderForgeRuntimeSystemdUserUnit(input: {
   description?: string;
   executable: string;
   args: string[];
   environment: Record<string, string>;
 }): string {
-  const environment = Object.entries(input.environment)
-    .sort(([left], [right]) => left.localeCompare(right))
-    .map(([key, value]) => `Environment=${systemdEscape(`${key}=${value}`)}`)
-    .join('\n');
-  return [
-    '[Unit]',
-    `Description=${input.description ?? 'Forge Runtime'}`,
-    'After=network-online.target',
-    '',
-    '[Service]',
-    'Type=simple',
-    `ExecStart=${[input.executable, ...input.args].map(systemdEscape).join(' ')}`,
-    ...(environment ? [environment] : []),
-    'Restart=on-failure',
-    'RestartSec=5',
-    '',
-    '[Install]',
-    'WantedBy=default.target',
-    '',
-  ].join('\n');
-}
-
-function commandSucceeded(command: string, args: string[], env: NodeJS.ProcessEnv): SpawnSyncReturns<string> {
-  return spawnSync(command, args, { encoding: 'utf8', env, timeout: 30_000 });
+  return createPlatformServiceManagerHost({ platform: 'linux', systemdUserAvailable: true }).renderSystemdUserUnit({ ...input, description: input.description ?? 'Forge Runtime' });
 }
 
 export function systemdUserAvailable(env: NodeJS.ProcessEnv = process.env): boolean {
-  const result = commandSucceeded('systemctl', ['--user', 'show-environment'], env);
-  return result.status === 0;
+  return probeSystemdUserAvailable(env);
 }
 
 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[][] {
-  // `enable --now` only starts an inactive unit. When Forge is already running,
-  // replacing the unit file and calling enable --now leaves the old ExecStart
-  // process alive even though release authority has advanced, fencing that
-  // process from writes. Enable and restart are intentionally separate so both
-  // first install and in-place immutable-release activation converge on the
-  // just-written unit while systemd remains the sole lifecycle owner.
-  return [
-    ['--user', 'daemon-reload'],
-    ['--user', 'enable', unitName],
-    ['--user', 'restart', unitName],
-  ];
+  return createPlatformServiceManagerHost({ platform: 'linux', systemdUserAvailable: true }).systemdUserInstallCommands(unitName);
 }
 
-function installSystemdUserService(controllerHome: string, env: NodeJS.ProcessEnv): string {
+export function packageRuntimeSystemdUserUnitInput(controllerHome: string): SystemdUserUnitInput {
   const entrypoint = activeRuntimeEntrypoint(controllerHome);
   const launch = activeRuntimeLaunchSpec(controllerHome);
   if (!entrypoint || !launch) throw new Error('FORGE_PACKAGE_RUNTIME_LAUNCH_SPEC_MISSING');
-  const label = forgeRuntimeServicePaths(controllerHome).label;
-  const unitName = `${label}.service`;
-  const unitPath = join(env.HOME ?? homedir(), '.config', 'systemd', 'user', unitName);
-  atomicWrite(unitPath, renderForgeRuntimeSystemdUserUnit({ executable: entrypoint, args: launch.args, environment: launch.environment }), 0o644);
-  for (const args of systemdRuntimeInstallCommands(unitName)) {
-    const result = commandSucceeded('systemctl', args, env);
-    if (result.status !== 0) throw new Error(`FORGE_RUNTIME_SYSTEMD_INSTALL_FAILED: systemctl ${args.join(' ')}: ${(result.stderr || result.stdout || '').trim()}`);
-  }
-  return unitPath;
+  return { description: 'Forge Runtime', executable: entrypoint, args: launch.args, environment: launch.environment };
+}
+
+export function renderPackageRuntimeSystemdUserService(controllerHome: string): string {
+  return createPlatformServiceManagerHost({ platform: 'linux', systemdUserAvailable: true }).renderSystemdUserUnit(packageRuntimeSystemdUserUnitInput(controllerHome));
+}
+
+export function writePackageRuntimeSystemdUserService(
+  controllerHome: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return createPlatformServiceManagerHost({ platform: 'linux', env, systemdUserAvailable: true }).writeSystemdUserUnit(
+    forgeRuntimeServicePaths(controllerHome).label,
+    packageRuntimeSystemdUserUnitInput(controllerHome),
+    env,
+  );
 }
 
-function startPortableRuntime(controllerHome: string, env: NodeJS.ProcessEnv): number {
+function installSystemdUserService(controllerHome: string, env: NodeJS.ProcessEnv, host: PlatformServiceManagerHost): string {
+  return host.installSystemdUserUnit({
+    unitName: forgeRuntimeServicePaths(controllerHome).label,
+    unit: packageRuntimeSystemdUserUnitInput(controllerHome),
+    env,
+    errorPrefix: 'FORGE_RUNTIME_SYSTEMD_INSTALL_FAILED',
+  });
+}
+
+function startPortableRuntime(controllerHome: string, env: NodeJS.ProcessEnv, host: PlatformServiceManagerHost): number {
   const entrypoint = activeRuntimeEntrypoint(controllerHome);
   const launch = activeRuntimeLaunchSpec(controllerHome);
   if (!entrypoint || !launch) throw new Error('FORGE_PACKAGE_RUNTIME_LAUNCH_SPEC_MISSING');
   const paths = forgeRuntimeServicePaths(controllerHome);
-  mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
-  const stdout = openSync(paths.stdoutPath, 'a', 0o600);
-  const stderr = openSync(paths.stderrPath, 'a', 0o600);
-  try {
-    const child = spawn(entrypoint, launch.args, {
-      detached: true,
-      stdio: ['ignore', stdout, stderr],
-      env: cleanRuntimeInstallerEnvironment(env, launch.environment),
-    });
-    if (!child.pid) throw new Error('FORGE_PORTABLE_RUNTIME_START_FAILED: child pid unavailable');
-    child.unref();
-    atomicWrite(join(paths.serviceRoot, 'portable.json'), `${JSON.stringify({ schemaVersion: 1, pid: child.pid, startedAt: new Date().toISOString() }, null, 2)}\n`);
-    return child.pid;
-  } finally {
-    closeSync(stdout);
-    closeSync(stderr);
-  }
+  const pid = host.startDetached({
+    executable: entrypoint,
+    args: launch.args,
+    environment: cleanRuntimeInstallerEnvironment(env, launch.environment),
+    stdoutPath: paths.stdoutPath,
+    stderrPath: paths.stderrPath,
+    errorCode: 'FORGE_PORTABLE_RUNTIME_START_FAILED',
+  });
+  atomicWrite(join(paths.serviceRoot, 'portable.json'), `${JSON.stringify({ schemaVersion: 1, pid, startedAt: new Date().toISOString() }, null, 2)}\n`);
+  return pid;
 }
 
 
@@ -334,9 +298,10 @@ export function renderPackageRuntimeActivationLaunchAgent(request: PackageRuntim
 
 async function scheduleDarwinPackageRuntimeActivation(request: PackageRuntimeActivationRequest): Promise<{ label: string; servicePath: string }> {
   if (process.platform !== 'darwin') throw new Error('FORGE_PACKAGE_RUNTIME_ACTIVATION_HELPER_PLATFORM_UNSUPPORTED');
+  const host = createPlatformServiceManagerHost({ platform: 'darwin' });
   atomicWrite(request.helperSourcePlistPath, renderPackageRuntimeActivationLaunchAgent(request), 0o600);
-  installLaunchAgent(request.helperSourcePlistPath, request.helperLabel);
-  const result = await bootstrapLaunchAgentWithRetryV2({ label: request.helperLabel, plistPath: request.helperInstalledPlistPath });
+  host.installLaunchd(request.helperSourcePlistPath, request.helperLabel);
+  const result = await host.bootstrapLaunchd({ label: request.helperLabel, plistPath: request.helperInstalledPlistPath });
   if (!result.ok) throw new Error(`FORGE_PACKAGE_RUNTIME_ACTIVATION_HELPER_BOOTSTRAP_FAILED: ${result.diagnostics.join('; ')}`);
   return { label: request.helperLabel, servicePath: request.helperInstalledPlistPath };
 }
@@ -359,13 +324,7 @@ async function waitForInstallerExit(pid: number): Promise<void> {
 async function cleanupActivationHelper(request: PackageRuntimeActivationRequest): Promise<void> {
   rmSync(request.helperSourcePlistPath, { force: true });
   rmSync(request.helperInstalledPlistPath, { force: true });
-  if (process.platform !== 'darwin') return;
-  const child = spawn('/bin/launchctl', ['bootout', `${currentUserLaunchdDomain()}/${request.helperLabel}`], {
-    detached: true,
-    stdio: 'ignore',
-    env: { PATH: '/usr/bin:/bin:/usr/sbin:/sbin' },
-  });
-  child.unref();
+  createPlatformServiceManagerHost({ platform: process.platform }).detachLaunchdBootout(request.helperLabel);
 }
 
 async function rollbackPackageRuntimeActivation(
@@ -400,9 +359,12 @@ async function rollbackPackageRuntimeActivation(
   if (request.priorAuthorityPresent && request.priorConfigBytes !== undefined) {
     try {
       const priorConfig = readForgeRuntimeServiceConfig(servicePaths.configPath);
+      const restoredAuthority = readRuntimeReleaseAuthority(request.controllerHome);
+      if (!restoredAuthority) throw new Error('FORGE_PACKAGE_RUNTIME_ROLLBACK_RELEASE_AUTHORITY_MISSING');
+      const restoredReleaseRoot = dirname(resolve(restoredAuthority.active.manifestPath));
       await installDarwinService({
         config: priorConfig,
-        runnerPath: join(priorConfig.repositoryRoot, 'bin', 'forge-runtime-service.mjs'),
+        runnerPath: join(restoredReleaseRoot, 'package', 'bin', 'forge-runtime-service.mjs'),
         nodeExecutable: request.nodeExecutable,
       });
     } catch (error) {
@@ -506,23 +468,29 @@ export async function installPackageRuntimeService(
   const config: ForgeRuntimeServiceConfig = {
     schemaVersion: 1,
     controllerHome,
-    repositoryRoot: release.packageRoot,
     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);
   const platform = options.platform ?? process.platform;
   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');
   const connectorEndpoint = loadMcpServiceLocalConfig(controllerHome)?.chatgpt?.localEndpoint;
 
   let base: PackageRuntimeServiceInstallResult;
-  if (!options.forcePortable && platform === 'darwin' && activationMode === 'detached') {
+  if (serviceManager.kind === 'launchd' && activationMode === 'detached') {
     const paths = activationPaths(controllerHome, operationId);
     const helperLabel = `com.moretea.forge.runtime-activation.${operationId.replace(/[^A-Za-z0-9.-]+/g, '-').slice(-48)}`;
     const createdAt = new Date().toISOString();
@@ -544,7 +512,7 @@ export async function installPackageRuntimeService(
       receiptPath: paths.receiptPath,
       helperLabel,
       helperSourcePlistPath: paths.helperSourcePlistPath,
-      helperInstalledPlistPath: launchAgentPath(helperLabel),
+      helperInstalledPlistPath: serviceHost.launchdInstalledPath(helperLabel),
       createdAt,
     };
     writeActivationRequest(request);
@@ -584,14 +552,14 @@ export async function installPackageRuntimeService(
     };
   } else {
     try {
-      if (!options.forcePortable && platform === 'darwin') {
+      if (serviceManager.kind === 'launchd') {
         const paths = await installDarwinService({ config, runnerPath: join(release.packageRoot, 'bin', 'forge-runtime-service.mjs'), nodeExecutable: process.execPath });
         base = { status: 'activated', mode: 'launchd', persistent: true, controllerHome, release, servicePath: paths.installedPlistPath, warnings: [] };
-      } else if (!options.forcePortable && platform === 'linux' && systemdUserAvailable(env)) {
-        const unitPath = installSystemdUserService(controllerHome, env);
+      } else if (serviceManager.kind === 'systemd-user') {
+        const unitPath = installSystemdUserService(controllerHome, env, serviceHost);
         base = { status: 'activated', mode: 'systemd-user', persistent: true, controllerHome, release, servicePath: unitPath, warnings: [] };
       } else {
-        const pid = startPortableRuntime(controllerHome, env);
+        const pid = startPortableRuntime(controllerHome, env, serviceHost);
         base = {
           status: 'activated', mode: 'portable', persistent: false, controllerHome, release, pid,
           warnings: [platform === 'win32'
@@ -629,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

@@ -0,0 +1,103 @@
+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'] | 'connector_cli';
+  executable: string;
+  args: string[];
+}
+
+export interface RuntimeReleaseExecutionCanaryDependencies {
+  runExecutionEntryCanary?: (input: RuntimeReleaseExecutionCanaryCommand) => {
+    ok: boolean;
+    stderr?: string;
+    stdout?: string;
+    error?: string;
+  };
+}
+
+/**
+ * Release execution canaries deliberately do not inherit developer-tool PATH
+ * 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,
+  platform: NodeJS.Platform = process.platform,
+): NodeJS.ProcessEnv {
+  if (platform === 'win32') {
+    const systemRoot = env.SystemRoot ?? env.SYSTEMROOT;
+    const systemPath = systemRoot
+      ? `${systemRoot}\\System32;${systemRoot};${systemRoot}\\System32\\Wbem`
+      : '';
+    return { ...env, PATH: systemPath };
+  }
+  return { ...env, PATH: '/usr/bin:/bin:/usr/sbin:/sbin' };
+}
+
+/**
+ * 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,
+  dependencies: RuntimeReleaseExecutionCanaryDependencies = {},
+): RuntimeReleaseExecutionSurface {
+  const surface = assertRuntimeReleaseExecutionSurface(manifestPath, controllerHome);
+  const runExecutionEntryCanary = dependencies.runExecutionEntryCanary ?? ((request: RuntimeReleaseExecutionCanaryCommand) => runProcess(
+    request.executable,
+    request.args,
+    {
+      cwd: surface.releaseRoot,
+      env: runtimeReleaseCanaryEnvironment(),
+      timeoutMs: 30_000,
+      maxOutputBytes: 64 * 1024,
+    },
+  ));
+  const assertCanary = (canary: RuntimeReleaseExecutionCanaryCommand): void => {
+    const result = runExecutionEntryCanary(canary);
+    if (!result.ok) {
+      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

@@ -0,0 +1,150 @@
+import { spawn } from 'child_process';
+import { createHash } from 'crypto';
+import { lstatSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+
+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 {
+  const index = argv.indexOf('--release-manifest');
+  const value = index >= 0 ? argv[index + 1] : undefined;
+  if (!value?.trim()) throw new Error('RUNTIME_RELEASE_MANIFEST_ARGUMENT_REQUIRED');
+  return resolve(value);
+}
+
+export function resolveCompiledRuntimeBundle(argv: readonly string[] = process.argv): {
+  manifestPath: string;
+  bundlePath: string;
+  artifactIdentity: string;
+  interpreterPath: string;
+  interpreterArtifactIdentity: string;
+} {
+  const manifestPath = releaseManifestPath(argv);
+  let manifest: RuntimeBundleManifestRecord;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as RuntimeBundleManifestRecord;
+  } catch (error) {
+    throw new Error(`RUNTIME_RELEASE_LOADER_MANIFEST_INVALID: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (manifest.runtimeBundleEntrypoint !== RUNTIME_BUNDLE_ENTRYPOINT) {
+    throw new Error(`RUNTIME_RELEASE_BUNDLE_ENTRYPOINT_INVALID: expected ${RUNTIME_BUNDLE_ENTRYPOINT}`);
+  }
+  const artifactIdentity = typeof manifest.runtimeBundleArtifactIdentity === 'string'
+    ? manifest.runtimeBundleArtifactIdentity.trim().toLowerCase()
+    : '';
+  if (!/^sha256:[a-f0-9]{64}$/.test(artifactIdentity)) {
+    throw new Error('RUNTIME_RELEASE_BUNDLE_IDENTITY_INVALID');
+  }
+  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)}`);
+  }
+  if (actualIdentity !== artifactIdentity) {
+    throw new Error('RUNTIME_RELEASE_BUNDLE_ARTIFACT_IDENTITY_MISMATCH');
+  }
+  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 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);
+  }
+}
+
+if (import.meta.main) {
+  runCompiledRuntimeLoader().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}