@moretea-labs/forge 1.7.2 → 1.8.0

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

@@ -1,10 +1,10 @@
 import { createHash } from 'crypto';
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { basename, dirname, join, resolve } from 'path';
-import { spawn, spawnSync } from 'child_process';
-import { bootstrapLaunchAgentWithRetryV2, installLaunchAgent, launchAgentPath, retireConflictingForgeLaunchAgents } from '../../cli/controller/launch-agents';
+import { loadMcpServiceLocalConfig } from '../../cli/mcp/auth';
 import type { PackageRuntimeRelease } from './package-runtime-release';
+import { createPlatformServiceManagerHost, platformLaunchdInstalledPath, type PlatformServiceManagerHost, type SystemdUserUnitInput } from '../platform/service-manager';
 
 export interface PackageConnectorServicePaths {
   label: string;
@@ -41,6 +41,8 @@ export interface PackageConnectorServiceResult {
   releaseRoot?: string;
 }
 
+export type PackageConnectorAuthMode = 'oauth' | 'none';
+
 function xml(value: string): string {
   return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
 }
@@ -61,7 +63,7 @@ export function packageConnectorServicePaths(controllerHome: string, accountHome
     label,
     serviceRoot,
     sourcePlistPath: join(serviceRoot, `${label}.plist`),
-    installedPlistPath: launchAgentPath(label, accountHome),
+    installedPlistPath: platformLaunchdInstalledPath(label, accountHome),
     stdoutPath: join(serviceRoot, 'logs', 'stdout.log'),
     stderrPath: join(serviceRoot, 'logs', 'stderr.log'),
     authorityPath: join(serviceRoot, 'authority.json'),
@@ -101,20 +103,34 @@ function writePackageConnectorServiceAuthority(input: { release: PackageConnecto
   atomicWrite(paths.authorityPath, `${JSON.stringify(authority, null, 2)}\n`);
 }
 
-export function packageConnectorEndpointStatusHealthy(status: number): boolean {
-  // The OAuth-protected MCP endpoint is healthy when it either answers directly
-  // or returns the expected unauthenticated Bearer challenge. Treating every
-  // received HTTP status as healthy masks upstream 5xx failures that are often
-  // surfaced remotely as 502 and prevents the persistent service from healing.
-  return status === 200 || status === 401;
+export function packageConnectorEndpointStatusHealthy(status: number, authMode: PackageConnectorAuthMode = 'oauth'): boolean {
+  // A Secure Tunnel owns external authentication and therefore its loopback
+  // Connector must answer directly. Accepting an OAuth challenge in `none`
+  // mode hides a stale service unit that was rewritten by an older lifecycle
+  // path, then makes every tunneled request fail remotely with 401.
+  return status === 200 || (authMode === 'oauth' && status === 401);
+}
+
+export function packageConnectorReadinessEndpoint(endpoint: string): string {
+  const parsed = new URL(endpoint);
+  if (parsed.protocol !== 'http:' || parsed.hostname !== '127.0.0.1' || parsed.pathname !== '/mcp') {
+    throw new Error('FORGE_PACKAGE_CONNECTOR_ENDPOINT_INVALID');
+  }
+  parsed.pathname = '/transport-ready';
+  parsed.search = '';
+  parsed.hash = '';
+  return parsed.toString();
 }
 
 async function defaultConnectorEndpointProbe(endpoint: string): Promise<boolean> {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 1_500);
   try {
-    const response = await fetch(endpoint, { method: 'GET', redirect: 'manual', signal: controller.signal });
-    return packageConnectorEndpointStatusHealthy(response.status);
+    // GET /mcp is a protocol request, not a liveness request: in auth:none it
+    // correctly responds 400 without an MCP session. /transport-ready is the
+    // in-memory, transport-scoped readiness surface used by Recovery.
+    const response = await fetch(packageConnectorReadinessEndpoint(endpoint), { method: 'GET', redirect: 'manual', signal: controller.signal });
+    return response.status === 200;
   } catch {
     return false;
   } finally {
@@ -127,6 +143,7 @@ export async function waitForPackageConnectorEndpointReady(
   options: {
     timeoutMs?: number;
     pollIntervalMs?: number;
+    authMode?: PackageConnectorAuthMode;
     probeEndpoint?: (endpoint: string) => Promise<boolean>;
     wait?: (ms: number) => Promise<void>;
     now?: () => number;
@@ -146,7 +163,17 @@ export async function waitForPackageConnectorEndpointReady(
   return false;
 }
 
-export function packageConnectorLaunchSpec(input: { release: PackageConnectorReleaseBinding; controllerHome: string; endpoint: string; executable?: string }): { executable: string; args: string[]; environment: Record<string, string>; port: number } {
+export function packageConnectorAuthMode(controllerHome: string): PackageConnectorAuthMode {
+  // OpenAI Secure MCP Tunnels authenticate the tunnel itself. The local
+  // Connector must not advertise a loopback OAuth issuer to ChatGPT in that
+  // topology. Keep OAuth as the default for existing HTTPS Connectors, and
+  // require an explicit per-instance opt-in before disabling it.
+  return loadMcpServiceLocalConfig(controllerHome)?.auth?.mode?.trim().toLowerCase() === 'none'
+    ? 'none'
+    : 'oauth';
+}
+
+export function packageConnectorLaunchSpec(input: { release: PackageConnectorReleaseBinding; controllerHome: string; endpoint: string; executable?: string }): { executable: string; args: string[]; environment: Record<string, string>; port: number; authMode: PackageConnectorAuthMode } {
   const parsed = new URL(input.endpoint);
   const port = Number(parsed.port);
   if (parsed.protocol !== 'http:' || parsed.hostname !== '127.0.0.1' || parsed.pathname !== '/mcp' || !Number.isInteger(port) || port < 1 || port > 65_535) {
@@ -159,19 +186,29 @@ export function packageConnectorLaunchSpec(input: { release: PackageConnectorRel
   const packageRoot = resolve(input.release.packageRoot);
   const cliEntry = join(packageRoot, 'src', 'cli', 'index.ts');
   const nodeLoader = join(packageRoot, 'src', 'runtime', 'shared', 'node-ts-loader.mjs');
-  const isBun = Boolean(process.versions.bun) || /(?:^|[/\\-])bun(?:$|[/\\]|\.exe$)/i.test(basename(executable));
+  const executableName = basename(executable);
+  const executableIsCurrentProcess = resolve(executable) === resolve(process.execPath);
+  const isBun = /(?:^|[/\\-])bun(?:$|[/\\]|\.exe$)/i.test(executableName)
+    || (executableIsCurrentProcess && Boolean(process.versions.bun));
+  const instanceId = loadMcpServiceLocalConfig(input.controllerHome)?.identity?.forgeInstanceId?.trim();
+  const authMode = packageConnectorAuthMode(input.controllerHome);
   const cliArgs = [
     // The package snapshot is executable code, never an adopted repository.
     // Supplying it as --repo makes the Gateway try to register a non-Git
     // directory and fail before it can proxy the Canonical Runtime.
     'mcp', 'serve', '--controller-home', resolve(input.controllerHome),
-    '--transport', 'http', '--host', '127.0.0.1', '--port', String(port), '--profile', 'controller', '--auth', 'oauth',
+    '--transport', 'http', '--host', '127.0.0.1', '--port', String(port), '--profile', 'controller', '--auth', authMode,
   ];
   return {
     executable,
     args: isBun ? [cliEntry, ...cliArgs] : ['--loader', nodeLoader, cliEntry, ...cliArgs],
-    environment: { FORGE_CONTROLLER_HOME: resolve(input.controllerHome), FORGE_CONTROLLER_LIFECYCLE_OWNER: '1' },
+    environment: {
+      FORGE_CONTROLLER_HOME: resolve(input.controllerHome),
+      FORGE_CONTROLLER_LIFECYCLE_OWNER: '1',
+      ...(instanceId ? { FORGE_MCP_INSTANCE_ID: instanceId } : {}),
+    },
     port,
+    authMode,
   };
 }
 
@@ -182,10 +219,28 @@ export function renderPackageConnectorLaunchAgent(input: { paths: PackageConnect
   return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n  <key>Label</key>\n  <string>${xml(input.paths.label)}</string>\n  <key>ProgramArguments</key>\n  <array>\n${args.map((arg) => `    <string>${xml(arg)}</string>`).join('\n')}\n  </array>\n  <key>EnvironmentVariables</key>\n  <dict>\n${environmentXml}\n  </dict>\n  <key>RunAtLoad</key>\n  <true/>\n  <key>KeepAlive</key>\n  <dict><key>SuccessfulExit</key><false/></dict>\n  <key>ThrottleInterval</key><integer>5</integer>\n  <key>StandardOutPath</key><string>${xml(input.paths.stdoutPath)}</string>\n  <key>StandardErrorPath</key><string>${xml(input.paths.stderrPath)}</string>\n</dict>\n</plist>\n`;
 }
 
+export function packageConnectorSystemdUserUnitInput(input: { launch: ReturnType<typeof packageConnectorLaunchSpec> }): SystemdUserUnitInput {
+  const description = input.launch.authMode === 'oauth'
+    ? 'Forge ChatGPT OAuth Gateway'
+    : 'Forge ChatGPT Secure Tunnel Connector';
+  return {
+    description,
+    executable: input.launch.executable,
+    args: input.launch.args,
+    environment: input.launch.environment,
+    restart: 'on-failure',
+    restartSec: 5,
+  };
+}
+
 export function renderPackageConnectorSystemdUserUnit(input: { launch: ReturnType<typeof packageConnectorLaunchSpec> }): string {
-  const quote = (value: string) => `"${value.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
-  const env = Object.entries(input.launch.environment).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `Environment=${quote(`${k}=${v}`)}`);
-  return ['[Unit]', 'Description=Forge ChatGPT OAuth Gateway', 'After=network-online.target', '', '[Service]', 'Type=simple', `ExecStart=${[input.launch.executable, ...input.launch.args].map(quote).join(' ')}`, ...env, 'Restart=on-failure', 'RestartSec=5', '', '[Install]', 'WantedBy=default.target', ''].join('\n');
+  return createPlatformServiceManagerHost({ platform: 'linux', systemdUserAvailable: true })
+    .renderSystemdUserUnit(packageConnectorSystemdUserUnitInput(input));
+}
+
+/** A rewritten user unit needs an explicit restart; enable --now preserves an already-running old process. */
+export function packageConnectorSystemdInstallCommands(unitName: string): string[][] {
+  return [['--user', 'daemon-reload'], ['--user', 'enable', unitName], ['--user', 'restart', unitName]];
 }
 
 export function packageConnectorServiceMatchesRelease(input: {
@@ -228,35 +283,31 @@ export function packageConnectorServiceMatchesRelease(input: {
   }
 }
 
-function installSystemd(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv): string {
-  const unitName = `${paths.label}.service`;
-  const unitPath = join(env.HOME ?? homedir(), '.config', 'systemd', 'user', unitName);
-  atomicWrite(unitPath, renderPackageConnectorSystemdUserUnit({ launch }), 0o644);
-  for (const args of [['--user', 'daemon-reload'], ['--user', 'enable', '--now', unitName]]) {
-    const result = spawnSync('systemctl', args, { encoding: 'utf8', env, timeout: 30_000 });
-    if (result.status !== 0) throw new Error(`FORGE_PACKAGE_CONNECTOR_SYSTEMD_INSTALL_FAILED: ${(result.stderr || result.stdout || '').trim()}`);
-  }
-  return unitPath;
+function installSystemd(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv, host: PlatformServiceManagerHost): string {
+  return host.installSystemdUserUnit({
+    unitName: `${paths.label}.service`,
+    unit: packageConnectorSystemdUserUnitInput({ launch }),
+    env,
+    errorPrefix: 'FORGE_PACKAGE_CONNECTOR_SYSTEMD_INSTALL_FAILED',
+  });
 }
 
-function startPortable(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv): number {
-  mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
-  const stdout = openSync(paths.stdoutPath, 'a', 0o600), stderr = openSync(paths.stderrPath, 'a', 0o600);
+function startPortable(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv, host: PlatformServiceManagerHost): number {
   // A connector is not the Canonical Runtime writer. Never let a transient
-  // installer/worker write claim escape into this long-lived process; the claim
-  // would become stale as soon as its parent exits. Keep only the explicit
-  // Controller Home and lifecycle-role marker from launch.environment.
+  // installer/worker write claim escape into this long-lived process.
   const childEnv = { ...env };
   for (const key of [
     'FORGE_RUNTIME_INSTANCE_ID', 'FORGE_RUNTIME_OWNER_PID', 'FORGE_RELEASE_AUTHORITY_REVISION',
     'FORGE_RELEASE_FENCING_TOKEN', 'FORGE_RELEASE_ID', 'FORGE_ARTIFACT_IDENTITY', 'FORGE_WORKER_PROTOCOL_VERSION',
   ]) delete childEnv[key];
-  try {
-    const child = spawn(launch.executable, launch.args, { detached: true, stdio: ['ignore', stdout, stderr], env: { ...childEnv, ...launch.environment } });
-    if (!child.pid) throw new Error('FORGE_PACKAGE_CONNECTOR_START_FAILED');
-    child.unref();
-    return child.pid;
-  } finally { closeSync(stdout); closeSync(stderr); }
+  return host.startDetached({
+    executable: launch.executable,
+    args: launch.args,
+    environment: { ...childEnv, ...launch.environment },
+    stdoutPath: paths.stdoutPath,
+    stderrPath: paths.stderrPath,
+    errorCode: 'FORGE_PACKAGE_CONNECTOR_START_FAILED',
+  });
 }
 
 export async function installPackageConnectorService(input: { release: PackageConnectorReleaseBinding; controllerHome: string; endpoint: string; executable?: string; platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; forcePortable?: boolean; probeEndpoint?: (endpoint: string) => Promise<boolean> }): Promise<PackageConnectorServiceResult> {
@@ -269,33 +320,32 @@ export async function installPackageConnectorService(input: { release: PackageCo
     executable: input.executable,
   });
   const platform = input.platform ?? process.platform, env = input.env ?? process.env;
-  if (!input.forcePortable && platform === 'darwin') {
-    await retireConflictingForgeLaunchAgents({
+  const serviceHost = createPlatformServiceManagerHost({ platform, env, forcePortable: input.forcePortable });
+  const serviceManager = serviceHost.selection;
+  if (serviceManager.kind === 'launchd') {
+    await serviceHost.retireConflictingLaunchd({
       accountHome: env.HOME,
       desiredLabel: paths.label,
       labelPrefix: 'com.moretea.forge.mcp-gateway',
       port: launch.port,
-      requiredArguments: ['mcp', 'serve', '--auth', 'oauth'],
+      requiredArguments: ['mcp', 'serve', '--auth', launch.authMode],
     });
     atomicWrite(paths.sourcePlistPath, renderPackageConnectorLaunchAgent({ paths, launch }), 0o600);
-    installLaunchAgent(paths.sourcePlistPath, paths.label);
-    const result = await bootstrapLaunchAgentWithRetryV2({ label: paths.label, plistPath: paths.installedPlistPath });
+    serviceHost.installLaunchd(paths.sourcePlistPath, paths.label);
+    const result = await serviceHost.bootstrapLaunchd({ label: paths.label, plistPath: paths.installedPlistPath });
     if (!result.ok) throw new Error(`FORGE_PACKAGE_CONNECTOR_LAUNCHD_INSTALL_FAILED: ${result.diagnostics.join('; ')}`);
-    const endpointReady = await waitForPackageConnectorEndpointReady(input.endpoint, { probeEndpoint: input.probeEndpoint });
+    const endpointReady = await waitForPackageConnectorEndpointReady(input.endpoint, { authMode: launch.authMode, probeEndpoint: input.probeEndpoint });
     if (!endpointReady) throw new Error(`FORGE_PACKAGE_CONNECTOR_ENDPOINT_NOT_READY: ${input.endpoint}`);
     const installed = { endpoint: input.endpoint, mode: 'launchd' as const, persistent: true, servicePath: paths.installedPlistPath, releaseId: input.release.releaseId, releaseRoot: input.release.releaseRoot };
     writePackageConnectorServiceAuthority({ release: input.release, controllerHome: input.controllerHome, result: installed });
     return installed;
   }
-  if (!input.forcePortable && platform === 'linux') {
-    const probe = spawnSync('systemctl', ['--user', 'show-environment'], { encoding: 'utf8', env, timeout: 30_000 });
-    if (probe.status === 0) {
-      const installed = { endpoint: input.endpoint, mode: 'systemd-user' as const, persistent: true, servicePath: installSystemd(paths, launch, env), releaseId: input.release.releaseId, releaseRoot: input.release.releaseRoot };
-      writePackageConnectorServiceAuthority({ release: input.release, controllerHome: input.controllerHome, result: installed });
-      return installed;
-    }
+  if (serviceManager.kind === 'systemd-user') {
+    const installed = { endpoint: input.endpoint, mode: 'systemd-user' as const, persistent: true, servicePath: installSystemd(paths, launch, env, serviceHost), releaseId: input.release.releaseId, releaseRoot: input.release.releaseRoot };
+    writePackageConnectorServiceAuthority({ release: input.release, controllerHome: input.controllerHome, result: installed });
+    return installed;
   }
-  const portable = { endpoint: input.endpoint, mode: 'portable' as const, persistent: false, pid: startPortable(paths, launch, env), releaseId: input.release.releaseId, releaseRoot: input.release.releaseRoot };
+  const portable = { endpoint: input.endpoint, mode: 'portable' as const, persistent: false, pid: startPortable(paths, launch, env, serviceHost), releaseId: input.release.releaseId, releaseRoot: input.release.releaseRoot };
   writePackageConnectorServiceAuthority({ release: input.release, controllerHome: input.controllerHome, result: portable });
   return portable;
 }
@@ -312,15 +362,17 @@ export async function ensurePackageConnectorService(input: {
   probeEndpoint?: (endpoint: string) => Promise<boolean>;
 }): Promise<PackageConnectorServiceResult> {
   const platform = input.platform ?? process.platform;
+  const authMode = packageConnectorAuthMode(input.controllerHome);
   if (!input.refresh && !input.forcePortable && platform === 'darwin') {
     const paths = packageConnectorServicePaths(input.controllerHome, input.env?.HOME);
     const port = Number(new URL(input.endpoint).port);
-    await retireConflictingForgeLaunchAgents({
+    const serviceHost = createPlatformServiceManagerHost({ platform, env: input.env });
+    await serviceHost.retireConflictingLaunchd({
       accountHome: input.env?.HOME,
       desiredLabel: paths.label,
       labelPrefix: 'com.moretea.forge.mcp-gateway',
       port,
-      requiredArguments: ['mcp', 'serve', '--auth', 'oauth'],
+      requiredArguments: ['mcp', 'serve', '--auth', authMode],
     });
   }
   if (!input.refresh && !input.forcePortable) {

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

@@ -6,7 +6,10 @@ import { CONTROL_PLANE_SCHEMA_VERSION } from '../control-plane/persistence/sqlit
 import { packageRuntimeSourceRoot } from '../control-plane/runtime-generation';
 import { FORGE_VERSION } from '../../version';
 import { publishRuntimeRelease, type RuntimeReleaseAuthority } from './release-store';
+import { assertRuntimeReleaseExecutionSurface } from './release-manifest';
+import { assertRuntimeReleaseExecutionCanaries } from './release-execution-canary';
 import type { RuntimeReleaseManifest } from './types';
+import { assertStorageHeadroom } from '../shared/storage-capacity';
 
 export interface PackageRuntimeFileRecord {
   path: string;
@@ -28,12 +31,13 @@ export interface PackageRuntimeRelease {
   authority: RuntimeReleaseAuthority;
 }
 
-// A package Runtime is an immutable, independently launchable release.  Its
-// TypeScript entrypoints import production modules at runtime, so retaining
-// only source files creates a release that passes staging but cannot start
-// after the installed package moves or disappears.
-const PACKAGE_RUNTIME_ROOTS = ['src', 'bin', 'assets', 'scripts', 'node_modules'] as const;
+// A package Runtime is an immutable, independently launchable release. Its
+// 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_FILES = ['package.json'] as const;
+const PACKAGE_RUNTIME_STAGING_RESERVE_BYTES = 256 * 1024 * 1024;
 
 function sha256(value: Buffer | string): string {
   return createHash('sha256').update(value).digest('hex');
@@ -138,25 +142,32 @@ function packageVersion(root: string): string {
   }
 }
 
-function launcherSource(input: { packageRoot: string; indexPath: string; indexSha256: string }): string {
+function launcherSource(input: {
+  indexSha256: string;
+  entryRelativePath?: string;
+  managerSignalsProcessGroup?: boolean;
+}): string {
+  const entryRelativePath = input.entryRelativePath ?? 'src/runtime/root/entry.ts';
   return `#!${process.execPath}\n`
     + `import { createHash } from 'node:crypto';\n`
     + `import { existsSync, readFileSync } from 'node:fs';\n`
-    + `import { join } from 'node:path';\n`
+    + `import { dirname, join } from 'node:path';\n`
+    + `import { fileURLToPath } from 'node:url';\n`
     + `import { spawn } from 'node:child_process';\n`
-    + `const packageRoot=${JSON.stringify(input.packageRoot)};\n`
-    + `const indexPath=${JSON.stringify(input.indexPath)};\n`
+    + `const releaseRoot=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`
     + `const digest=(v)=>createHash('sha256').update(v).digest('hex');\n`
     + `let raw; try { raw=readFileSync(indexPath); } catch (error) { console.error('FORGE_PACKAGE_RUNTIME_INDEX_MISSING: '+error.message); process.exit(78); }\n`
     + `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 entry=join(packageRoot,'src','runtime','root','entry.ts');\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`
     + `const child=spawn(process.execPath,args,{stdio:'inherit',env:process.env});\n`
-    + `const managerSignalsProcessGroup=process.platform==='linux'&&Boolean(process.env.INVOCATION_ID);\n`
+    + `const managerSignalsProcessGroup=${input.managerSignalsProcessGroup ? "process.platform==='linux'&&Boolean(process.env.INVOCATION_ID)" : "false"};\n`
     + `for(const signal of ['SIGINT','SIGTERM','SIGHUP']){try{process.on(signal,()=>{if(!managerSignalsProcessGroup)child.kill(signal);});}catch{}}\n`
     + `child.on('error',(error)=>{console.error('FORGE_PACKAGE_RUNTIME_LAUNCH_FAILED: '+error.message);process.exit(1);});\n`
     + `child.on('exit',(code)=>process.exit(code??1));\n`;
@@ -170,21 +181,28 @@ function assertImmutablePackageRuntimeRelease(input: {
   indexJson: string;
   entrypointPath: string;
   launcher: string;
+  processRunnerPath: string;
+  processRunnerLauncher: string;
+  checkRunnerPath: string;
+  checkRunnerLauncher: string;
   manifestPath: string;
   expectedManifest: Omit<RuntimeReleaseManifest, 'createdAt'>;
 }): void {
   const rootStat = lstatSync(input.releaseRoot);
   if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error('PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: release root is not a regular directory');
   assertPackageRuntimeSnapshot(input.packageRoot, input.records);
-  const assertFile = (path: string, expected: string, label: string) => {
+  const assertFile = (path: string, expected: string, label: string, executable = false) => {
     if (!existsSync(path)) throw new Error(`PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: ${label} is missing`);
     const stat = lstatSync(path);
-    if (!stat.isFile() || stat.isSymbolicLink() || readFileSync(path, 'utf8') !== expected) {
+    if (!stat.isFile() || stat.isSymbolicLink() || readFileSync(path, 'utf8') !== expected
+      || (executable && process.platform !== 'win32' && (stat.mode & 0o111) === 0)) {
       throw new Error(`PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: ${label} changed`);
     }
   };
   assertFile(input.indexPath, input.indexJson, 'package file index');
-  assertFile(input.entrypointPath, input.launcher, 'runtime launcher');
+  assertFile(input.entrypointPath, input.launcher, 'runtime launcher', true);
+  assertFile(input.processRunnerPath, input.processRunnerLauncher, 'process runner launcher', true);
+  assertFile(input.checkRunnerPath, input.checkRunnerLauncher, 'check runner launcher', true);
   if (!existsSync(input.manifestPath)) throw new Error('PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: manifest is missing');
   const manifestStat = lstatSync(input.manifestPath);
   if (!manifestStat.isFile() || manifestStat.isSymbolicLink()) throw new Error('PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: manifest is not a regular file');
@@ -199,6 +217,11 @@ function assertImmutablePackageRuntimeRelease(input: {
     && manifest.releaseId === expected.releaseId
     && manifest.artifactIdentity === expected.artifactIdentity
     && manifest.entrypoint === expected.entrypoint
+    && manifest.executionMode === expected.executionMode
+    && manifest.processRunnerEntrypoint === expected.processRunnerEntrypoint
+    && manifest.processRunnerArtifactIdentity === expected.processRunnerArtifactIdentity
+    && manifest.checkRunnerEntrypoint === expected.checkRunnerEntrypoint
+    && manifest.checkRunnerArtifactIdentity === expected.checkRunnerArtifactIdentity
     && JSON.stringify(manifest.arguments ?? []) === JSON.stringify(expected.arguments ?? [])
     && manifest.configurationSchemaVersion === expected.configurationSchemaVersion
     && resolve(manifest.controllerHome) === resolve(expected.controllerHome)
@@ -209,6 +232,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');
+  assertRuntimeReleaseExecutionSurface(input.manifestPath, expected.controllerHome);
 }
 
 export function materializePackageRuntimeRelease(input: {
@@ -222,7 +246,7 @@ export function materializePackageRuntimeRelease(input: {
   const records = packageRuntimeFileIndex(sourcePackageRoot);
   const fingerprint = packageRuntimeFingerprint(records);
   const safeVersion = version.replace(/[^A-Za-z0-9._-]+/g, '-');
-  const launcherBinding = sha256(`${resolve(process.execPath)}\0package-launcher-v4`);
+  const launcherBinding = sha256(`${resolve(process.execPath)}\0package-launcher-v5`);
   const releaseId = `package-${safeVersion}-${fingerprint.slice(0, 16)}-${launcherBinding.slice(0, 12)}`;
   const releasesRoot = join(controllerHome, 'runtime', 'releases');
   const releaseRoot = join(releasesRoot, releaseId);
@@ -230,13 +254,32 @@ export function materializePackageRuntimeRelease(input: {
   const indexPath = join(releaseRoot, 'package-files.json');
   const indexJson = `${JSON.stringify({ schemaVersion: 1, package: '@moretea-labs/forge', version, fingerprint, files: records }, null, 2)}\n`;
   const entrypointPath = join(releaseRoot, 'forge-runtime');
-  const launcher = launcherSource({ packageRoot, indexPath, indexSha256: sha256(Buffer.from(indexJson)) });
+  const indexSha256 = sha256(Buffer.from(indexJson));
+  const launcher = launcherSource({ indexSha256, managerSignalsProcessGroup: true });
   const artifactIdentity = `sha256:${sha256(Buffer.from(launcher))}`;
+  const processRunnerEntrypoint = 'process-runner.js' as const;
+  const processRunnerPath = join(releaseRoot, processRunnerEntrypoint);
+  const processRunnerLauncher = launcherSource({
+    indexSha256,
+    entryRelativePath: 'src/runtime/execution/process-runtime/process-runner-entry.ts',
+  });
+  const processRunnerArtifactIdentity = `sha256:${sha256(Buffer.from(processRunnerLauncher))}`;
+  const checkRunnerEntrypoint = 'forge-check-runner' as const;
+  const checkRunnerPath = join(releaseRoot, checkRunnerEntrypoint);
+  const checkRunnerLauncher = launcherSource({
+    indexSha256,
+    entryRelativePath: 'src/runtime/execution/process-runtime/check-runner-sidecar.ts',
+  });
+  const checkRunnerArtifactIdentity = `sha256:${sha256(Buffer.from(checkRunnerLauncher))}`;
   const expectedManifest: Omit<RuntimeReleaseManifest, 'createdAt'> = {
     schemaVersion: 1,
     releaseId,
     artifactIdentity,
     entrypoint: 'forge-runtime',
+    processRunnerEntrypoint,
+    processRunnerArtifactIdentity,
+    checkRunnerEntrypoint,
+    checkRunnerArtifactIdentity,
     arguments: [],
     configurationSchemaVersion: 1,
     controllerHome,
@@ -246,13 +289,26 @@ export function materializePackageRuntimeRelease(input: {
     cleanWorkspace: true,
   };
   const manifestPath = join(releaseRoot, 'manifest.json');
+  const stagedBytes = records.reduce((total, record) => total + record.bytes, 0)
+    + Buffer.byteLength(indexJson)
+    + Buffer.byteLength(launcher)
+    + Buffer.byteLength(processRunnerLauncher)
+    + Buffer.byteLength(checkRunnerLauncher)
+    + Buffer.byteLength(JSON.stringify({ ...expectedManifest, createdAt: new Date(0).toISOString() }));
+  let executionCanariesValidated = false;
   const assertExisting = () => assertImmutablePackageRuntimeRelease({
-    releaseRoot, packageRoot, records, indexPath, indexJson, entrypointPath, launcher, manifestPath, expectedManifest,
+    releaseRoot, packageRoot, records, indexPath, indexJson, entrypointPath, launcher,
+    processRunnerPath, processRunnerLauncher, checkRunnerPath, checkRunnerLauncher, manifestPath, expectedManifest,
   });
 
   if (existsSync(releaseRoot)) {
     assertExisting();
   } else {
+    assertStorageHeadroom(controllerHome, {
+      operation: 'materialize_package_runtime_release',
+      requiredBytes: stagedBytes,
+      reserveBytes: PACKAGE_RUNTIME_STAGING_RESERVE_BYTES,
+    });
     mkdirSync(releasesRoot, { recursive: true, mode: 0o700 });
     const stagingRoot = join(releasesRoot, `.staging-${releaseId}-${process.pid}-${randomUUID().slice(0, 8)}`);
     try {
@@ -261,9 +317,19 @@ export function materializePackageRuntimeRelease(input: {
       atomicWrite(join(stagingRoot, 'package-files.json'), indexJson);
       atomicWrite(join(stagingRoot, 'forge-runtime'), launcher, 0o700);
       chmodSync(join(stagingRoot, 'forge-runtime'), 0o700);
+      atomicWrite(join(stagingRoot, processRunnerEntrypoint), processRunnerLauncher, 0o700);
+      chmodSync(join(stagingRoot, processRunnerEntrypoint), 0o700);
+      atomicWrite(join(stagingRoot, checkRunnerEntrypoint), checkRunnerLauncher, 0o700);
+      chmodSync(join(stagingRoot, checkRunnerEntrypoint), 0o700);
       const manifest: RuntimeReleaseManifest = { ...expectedManifest, createdAt: new Date().toISOString() };
-      atomicWrite(join(stagingRoot, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+      const stagingManifestPath = join(stagingRoot, 'manifest.json');
+      atomicWrite(stagingManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+      // A failed execution surface is still a staging failure. Do not promote an
+      // immutable release directory until both manifest-owned runners execute
+      // their bounded no-op canary successfully.
+      assertRuntimeReleaseExecutionCanaries(stagingManifestPath, controllerHome);
       renameSync(stagingRoot, releaseRoot);
+      executionCanariesValidated = true;
     } catch (error) {
       rmSync(stagingRoot, { recursive: true, force: true });
       if (!existsSync(releaseRoot)) throw error;
@@ -271,6 +337,7 @@ export function materializePackageRuntimeRelease(input: {
     }
   }
 
+  if (!executionCanariesValidated) assertRuntimeReleaseExecutionCanaries(manifestPath, controllerHome);
   const authority = publishRuntimeRelease(controllerHome, manifestPath, input.operationId ?? `package-runtime-${FORGE_VERSION}-${Date.now()}`);
   return {
     releaseId,