@moretea-labs/forge 1.7.2 → 1.8.0

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

@@ -1,10 +1,9 @@
 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 { createPlatformServiceManagerHost, probeSystemdUserAvailable, type PlatformServiceManagerHost, type PlatformServiceManagerKind, type SystemdUserUnitInput } from '../platform/service-manager';
 import { RUNTIME_WRITE_CLAIM_ENV } from './write-fence';
 import {
   activeRuntimeEntrypoint,
@@ -18,16 +17,10 @@ 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';
 
-export type PackageRuntimeServiceMode = 'launchd' | 'systemd-user' | 'portable';
+export type PackageRuntimeServiceMode = PlatformServiceManagerKind;
 
 export type PackageRuntimeActivationStatus = 'activation_scheduled' | 'activated' | 'failed+rollback';
 
@@ -124,45 +117,17 @@ 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 {
@@ -177,56 +142,55 @@ function cleanRuntimeInstallerEnvironment(env: NodeJS.ProcessEnv, releaseEnviron
 }
 
 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,7 +468,6 @@ 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,
@@ -516,13 +477,15 @@ export async function installPackageRuntimeService(
   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 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 +507,7 @@ export async function installPackageRuntimeService(
       receiptPath: paths.receiptPath,
       helperLabel,
       helperSourcePlistPath: paths.helperSourcePlistPath,
-      helperInstalledPlistPath: launchAgentPath(helperLabel),
+      helperInstalledPlistPath: serviceHost.launchdInstalledPath(helperLabel),
       createdAt,
     };
     writeActivationRequest(request);
@@ -584,14 +547,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'

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

@@ -0,0 +1,71 @@
+import { runProcess } from '../../effects/process-runner';
+import { PROCESS_RUNTIME_RELEASE_CANARY_ARG } from '../execution/process-runtime/canary';
+import {
+  assertRuntimeReleaseExecutionSurface,
+  type RuntimeReleaseExecutionSurface,
+} from './release-manifest';
+
+export interface RuntimeReleaseExecutionCanaryCommand {
+  name: RuntimeReleaseExecutionSurface['entries'][number]['name'];
+  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. A manifest-owned executable that only works because Homebrew, Bun,
+ * nvm, etc. happens to be present is not an immutable Runtime artifact.
+ */
+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 exact manifest-owned Process/Check Runner artifacts in bounded no-op mode. */
+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: 10_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 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));
+    }
+  }
+  return surface;
+}

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

@@ -0,0 +1,68 @@
+import { createHash } from 'crypto';
+import { readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { pathToFileURL } from 'url';
+
+export const RUNTIME_BUNDLE_ENTRYPOINT = 'forge-runtime-bundle.js' as const;
+
+interface RuntimeBundleManifestRecord {
+  runtimeBundleEntrypoint?: unknown;
+  runtimeBundleArtifactIdentity?: 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;
+} {
+  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 bundlePath = join(dirname(manifestPath), RUNTIME_BUNDLE_ENTRYPOINT);
+  let actualIdentity: string;
+  try {
+    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');
+  }
+  return { manifestPath, bundlePath, artifactIdentity };
+}
+
+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');
+  }
+  await loaded.runCanonicalRuntimeCli(argv);
+}
+
+if (import.meta.main) {
+  runCompiledRuntimeLoader().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

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

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync, realpathSync } from 'fs';
-import { resolve } from 'path';
+import { createHash } from 'crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'fs';
+import { dirname, join, resolve } from 'path';
 import { CONTROL_PLANE_SCHEMA_VERSION } from '../control-plane/persistence/sqlite-store';
 import type { RuntimeReleaseManifest } from './types';
 
@@ -50,11 +51,15 @@ function optionalRuntimeComponent<
 }
 
 export const COMPILED_RUNTIME_RELEASE_COMPONENT_FIELDS = [
+  'executionMode',
+  'runtimeBundleEntrypoint', 'runtimeBundleArtifactIdentity',
   'diagnosticEntrypoint', 'diagnosticArtifactIdentity',
   'browserNodeBridgeEntrypoint', 'browserNodeBridgeArtifactIdentity',
   'browserHandoffEntrypoint', 'browserHandoffArtifactIdentity',
   'processRunnerEntrypoint', 'processRunnerArtifactIdentity',
   'checkRunnerEntrypoint', 'checkRunnerArtifactIdentity',
+  'schedulerWorkerEntrypoint', 'schedulerWorkerArtifactIdentity',
+  'periodicCleanupEntrypoint', 'periodicCleanupArtifactIdentity',
   'pluginActionSidecarEntrypoint', 'pluginActionSidecarArtifactIdentity',
   'externalPluginProbeEntrypoint', 'externalPluginProbeArtifactIdentity',
   'codeGraphNodeEntrypoint', 'codeGraphNodeArtifactIdentity',
@@ -103,6 +108,18 @@ export function loadRuntimeReleaseManifest(
   if (entrypoint !== 'forge-runtime') {
     throw new Error(`RELEASE_MANIFEST_INVALID: entrypoint must be forge-runtime, got ${entrypoint}`);
   }
+  const executionMode = value.executionMode === undefined
+    ? undefined
+    : requireString(value.executionMode, 'executionMode');
+  if (executionMode !== undefined && executionMode !== 'standalone-binary') {
+    throw new Error(`RELEASE_MANIFEST_INVALID: executionMode must be standalone-binary, got ${executionMode}`);
+  }
+  const runtimeBundle = optionalRuntimeComponent({
+    value,
+    entryField: 'runtimeBundleEntrypoint',
+    identityField: 'runtimeBundleArtifactIdentity',
+    canonicalEntry: 'forge-runtime-bundle.js',
+  });
   if (value.configurationSchemaVersion !== 1) {
     throw new Error('RELEASE_MANIFEST_INVALID: configurationSchemaVersion must be 1');
   }
@@ -151,6 +168,18 @@ export function loadRuntimeReleaseManifest(
     identityField: 'checkRunnerArtifactIdentity',
     canonicalEntry: 'forge-check-runner',
   });
+  const schedulerWorker = optionalRuntimeComponent({
+    value,
+    entryField: 'schedulerWorkerEntrypoint',
+    identityField: 'schedulerWorkerArtifactIdentity',
+    canonicalEntry: 'forge-scheduler-worker',
+  });
+  const periodicCleanup = optionalRuntimeComponent({
+    value,
+    entryField: 'periodicCleanupEntrypoint',
+    identityField: 'periodicCleanupArtifactIdentity',
+    canonicalEntry: 'forge-periodic-cleanup',
+  });
   const pluginActionSidecar = optionalRuntimeComponent({
     value,
     entryField: 'pluginActionSidecarEntrypoint',
@@ -249,11 +278,15 @@ export function loadRuntimeReleaseManifest(
     releaseId: requireString(value.releaseId, 'releaseId'),
     artifactIdentity: requireString(value.artifactIdentity, 'artifactIdentity'),
     entrypoint: 'forge-runtime',
+    ...(executionMode ? { executionMode: 'standalone-binary' as const } : {}),
+    ...(runtimeBundle ?? {}),
     ...(diagnostic ?? {}),
     ...(browserNodeBridge ?? {}),
     ...(browserHandoff ?? {}),
     ...(processRunner ?? {}),
     ...(checkRunner ?? {}),
+    ...(schedulerWorker ?? {}),
+    ...(periodicCleanup ?? {}),
     ...(pluginActionSidecar ?? {}),
     ...(externalPluginProbe ?? {}),
     ...(browserAutomationHelper ?? {}),
@@ -265,9 +298,80 @@ export function loadRuntimeReleaseManifest(
     controllerHome,
     databaseSchemaCompatibility: { minimum, maximum },
     workerProtocolVersion,
+    ...(typeof value.sourceRepositoryId === 'string' && value.sourceRepositoryId.trim() ? { sourceRepositoryId: value.sourceRepositoryId.trim() } : {}),
     ...(typeof value.sourceCommit === 'string' && value.sourceCommit.trim() ? { sourceCommit: value.sourceCommit.trim() } : {}),
     ...(typeof value.releaseRevision === 'string' && value.releaseRevision.trim() ? { releaseRevision: value.releaseRevision.trim() } : {}),
     ...(typeof value.cleanWorkspace === 'boolean' ? { cleanWorkspace: value.cleanWorkspace } : {}),
     createdAt,
   };
 }
+
+export interface RuntimeReleaseExecutionSurface {
+  manifest: RuntimeReleaseManifest;
+  releaseRoot: string;
+  entries: Array<{
+    name: 'process_runner' | 'check_runner' | 'scheduler_worker' | 'periodic_cleanup';
+    path: string;
+    artifactIdentity: string;
+  }>;
+}
+
+/**
+ * Validate the manifest-owned minimum Process Runtime execution surface.
+ * This is physical artifact evidence only. Release publication, activation,
+ * known-good and rollback authority remain owned by their existing lifecycle.
+ */
+export function assertRuntimeReleaseExecutionSurface(
+  manifestPath: string,
+  expectedControllerHome: string,
+): RuntimeReleaseExecutionSurface {
+  const resolvedManifestPath = resolve(manifestPath);
+  const manifest = loadRuntimeReleaseManifest(resolvedManifestPath, expectedControllerHome);
+  if (!manifest.processRunnerEntrypoint || !manifest.processRunnerArtifactIdentity
+    || !manifest.checkRunnerEntrypoint || !manifest.checkRunnerArtifactIdentity) {
+    throw new Error('RUNTIME_RELEASE_PROCESS_RUNTIME_SURFACE_INCOMPLETE: process-runner.js and forge-check-runner are required');
+  }
+  if (manifest.executionMode === 'standalone-binary'
+    && (!manifest.schedulerWorkerEntrypoint || !manifest.schedulerWorkerArtifactIdentity
+      || !manifest.periodicCleanupEntrypoint || !manifest.periodicCleanupArtifactIdentity)) {
+    throw new Error('RUNTIME_RELEASE_SCHEDULER_SURFACE_INCOMPLETE: forge-scheduler-worker and forge-periodic-cleanup are required');
+  }
+  const releaseRoot = dirname(resolvedManifestPath);
+  const entries: RuntimeReleaseExecutionSurface['entries'] = [
+    {
+      name: 'process_runner',
+      path: join(releaseRoot, manifest.processRunnerEntrypoint),
+      artifactIdentity: manifest.processRunnerArtifactIdentity,
+    },
+    {
+      name: 'check_runner',
+      path: join(releaseRoot, manifest.checkRunnerEntrypoint),
+      artifactIdentity: manifest.checkRunnerArtifactIdentity,
+    },
+    ...(manifest.schedulerWorkerEntrypoint && manifest.schedulerWorkerArtifactIdentity ? [{
+      name: 'scheduler_worker' as const,
+      path: join(releaseRoot, manifest.schedulerWorkerEntrypoint),
+      artifactIdentity: manifest.schedulerWorkerArtifactIdentity,
+    }] : []),
+    ...(manifest.periodicCleanupEntrypoint && manifest.periodicCleanupArtifactIdentity ? [{
+      name: 'periodic_cleanup' as const,
+      path: join(releaseRoot, manifest.periodicCleanupEntrypoint),
+      artifactIdentity: manifest.periodicCleanupArtifactIdentity,
+    }] : []),
+  ];
+  for (const entry of entries) {
+    if (!existsSync(entry.path)) throw new Error(`RUNTIME_RELEASE_EXECUTION_ENTRY_MISSING: ${entry.name}: ${entry.path}`);
+    const status = lstatSync(entry.path);
+    if (status.isSymbolicLink() || !status.isFile()) {
+      throw new Error(`RUNTIME_RELEASE_EXECUTION_ENTRY_NOT_REGULAR: ${entry.name}: ${entry.path}`);
+    }
+    if ((status.mode & 0o111) === 0) {
+      throw new Error(`RUNTIME_RELEASE_EXECUTION_ENTRY_NOT_EXECUTABLE: ${entry.name}: ${entry.path}`);
+    }
+    const observed = `sha256:${createHash('sha256').update(readFileSync(entry.path)).digest('hex')}`;
+    if (observed !== entry.artifactIdentity) {
+      throw new Error(`RUNTIME_RELEASE_EXECUTION_ENTRY_IDENTITY_MISMATCH: ${entry.name}: expected ${entry.artifactIdentity} observed ${observed}`);
+    }
+  }
+  return { manifest, releaseRoot, entries };
+}