@moretea-labs/forge 1.7.0 → 1.7.2

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

@@ -107,7 +107,7 @@ function assertPackageRuntimeSnapshot(snapshotRoot: string, records: PackageRunt
   }
 }
 
-function stagePackageRuntimeSnapshot(sourceRoot: string, snapshotRoot: string, records: PackageRuntimeFileRecord[]): void {
+export function stagePackageRuntimeSnapshot(sourceRoot: string, snapshotRoot: string, records: PackageRuntimeFileRecord[]): void {
   mkdirSync(snapshotRoot, { recursive: false, mode: 0o700 });
   for (const record of records) {
     const source = join(sourceRoot, record.path);
@@ -156,7 +156,8 @@ function launcherSource(input: { packageRoot: string; indexPath: string; indexSh
     + `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`
-    + `for(const signal of ['SIGINT','SIGTERM','SIGHUP']){try{process.on(signal,()=>child.kill(signal));}catch{}}\n`
+    + `const managerSignalsProcessGroup=process.platform==='linux'&&Boolean(process.env.INVOCATION_ID);\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`;
 }

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

@@ -176,6 +176,20 @@ function cleanRuntimeInstallerEnvironment(env: NodeJS.ProcessEnv, releaseEnviron
   return { ...next, ...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],
+  ];
+}
+
 function installSystemdUserService(controllerHome: string, env: NodeJS.ProcessEnv): string {
   const entrypoint = activeRuntimeEntrypoint(controllerHome);
   const launch = activeRuntimeLaunchSpec(controllerHome);
@@ -184,7 +198,7 @@ function installSystemdUserService(controllerHome: string, env: NodeJS.ProcessEn
   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 [['--user', 'daemon-reload'], ['--user', 'enable', '--now', unitName]]) {
+  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()}`);
   }
@@ -357,6 +371,10 @@ async function cleanupActivationHelper(request: PackageRuntimeActivationRequest)
 async function rollbackPackageRuntimeActivation(
   request: PackageRuntimeActivationRequest,
   installDarwinService: typeof installForgeRuntimeService,
+  options: {
+    restoreConnector?: boolean;
+    ensureConnectorService?: typeof ensurePackageConnectorService;
+  } = {},
 ): Promise<string[]> {
   const errors: string[] = [];
   const servicePaths = forgeRuntimeServicePaths(request.controllerHome);
@@ -391,6 +409,29 @@ async function rollbackPackageRuntimeActivation(
       errors.push(error instanceof Error ? error.message : String(error));
     }
   }
+  if (options.restoreConnector && request.connectorEndpoint && request.priorAuthorityPresent) {
+    try {
+      const restored = readRuntimeReleaseAuthority(request.controllerHome);
+      if (!restored) throw new Error('FORGE_PACKAGE_CONNECTOR_ROLLBACK_AUTHORITY_MISSING');
+      const releaseRoot = dirname(resolve(restored.active.manifestPath));
+      const packageRoot = join(releaseRoot, 'package');
+      const ensureConnectorService = options.ensureConnectorService ?? ensurePackageConnectorService;
+      await ensureConnectorService({
+        release: {
+          releaseId: restored.active.releaseId,
+          releaseRoot,
+          packageRoot,
+        },
+        controllerHome: request.controllerHome,
+        endpoint: request.connectorEndpoint,
+        executable: request.nodeExecutable,
+        platform: 'darwin',
+        refresh: true,
+      });
+    } catch (error) {
+      errors.push(`primary Connector rollback failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
   return errors;
 }
 
@@ -421,6 +462,7 @@ export async function activateScheduledPackageRuntimeService(
         release: request.release,
         controllerHome: request.controllerHome,
         endpoint: request.connectorEndpoint,
+        executable: request.nodeExecutable,
         platform: 'darwin',
         refresh: request.refreshConnector === true,
       });
@@ -428,7 +470,10 @@ export async function activateScheduledPackageRuntimeService(
     return writeActivationReceipt(request, 'activated', { servicePath: paths.installedPlistPath });
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
-    const rollbackErrors = await rollbackPackageRuntimeActivation(request, installDarwinService);
+    const rollbackErrors = await rollbackPackageRuntimeActivation(request, installDarwinService, {
+      restoreConnector: Boolean(request.connectorEndpoint),
+      ensureConnectorService,
+    });
     writeActivationReceipt(request, 'failed+rollback', {
       error: detail,
       rollbackSucceeded: rollbackErrors.length === 0,
@@ -587,7 +632,7 @@ export async function installPackageRuntimeService(
   if (!connectorEndpoint || base.status === 'activation_scheduled') return base;
   const ensureConnectorService = dependencies.ensureConnectorService ?? ensurePackageConnectorService;
   const connector = await ensureConnectorService({
-    release, controllerHome, endpoint: connectorEndpoint, platform, env, forcePortable: options.forcePortable === true, refresh: options.refreshConnector === true,
+    release, controllerHome, endpoint: connectorEndpoint, executable: process.execPath, platform, env, forcePortable: options.forcePortable === true, refresh: options.refreshConnector === true,
   });
   return { ...base, connector };
 }

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

@@ -13,6 +13,77 @@ function canonicalExistingPathIdentity(path: string): string {
   return existsSync(resolved) ? realpathSync(resolved) : resolved;
 }
 
+function requireSha256Identity(value: unknown, field: string): string {
+  const identity = requireString(value, field);
+  if (!/^sha256:[a-f0-9]{64}$/i.test(identity)) {
+    throw new Error(`RELEASE_MANIFEST_INVALID: ${field} must be sha256:<64 hex>`);
+  }
+  return identity;
+}
+
+type RuntimeComponentPair<KEntry extends keyof RuntimeReleaseManifest, KIdentity extends keyof RuntimeReleaseManifest> = Pick<
+  RuntimeReleaseManifest,
+  KEntry | KIdentity
+>;
+
+function optionalRuntimeComponent<
+  KEntry extends keyof RuntimeReleaseManifest,
+  KIdentity extends keyof RuntimeReleaseManifest,
+>(input: {
+  value: Record<string, unknown>;
+  entryField: KEntry;
+  identityField: KIdentity;
+  canonicalEntry: RuntimeReleaseManifest[KEntry];
+}): RuntimeComponentPair<KEntry, KIdentity> | undefined {
+  const rawEntry = input.value[input.entryField as string];
+  const rawIdentity = input.value[input.identityField as string];
+  if (rawEntry === undefined && rawIdentity === undefined) return undefined;
+  const entry = requireString(rawEntry, input.entryField as string);
+  if (entry !== input.canonicalEntry) {
+    throw new Error(`RELEASE_MANIFEST_INVALID: ${String(input.entryField)} must be ${String(input.canonicalEntry)}, got ${entry}`);
+  }
+  const identity = requireSha256Identity(rawIdentity, input.identityField as string);
+  return {
+    [input.entryField]: input.canonicalEntry,
+    [input.identityField]: identity,
+  } as RuntimeComponentPair<KEntry, KIdentity>;
+}
+
+export const COMPILED_RUNTIME_RELEASE_COMPONENT_FIELDS = [
+  'diagnosticEntrypoint', 'diagnosticArtifactIdentity',
+  'browserNodeBridgeEntrypoint', 'browserNodeBridgeArtifactIdentity',
+  'browserHandoffEntrypoint', 'browserHandoffArtifactIdentity',
+  'processRunnerEntrypoint', 'processRunnerArtifactIdentity',
+  'checkRunnerEntrypoint', 'checkRunnerArtifactIdentity',
+  'pluginActionSidecarEntrypoint', 'pluginActionSidecarArtifactIdentity',
+  'externalPluginProbeEntrypoint', 'externalPluginProbeArtifactIdentity',
+  'codeGraphNodeEntrypoint', 'codeGraphNodeArtifactIdentity',
+  'codeGraphSidecarEntrypoint', 'codeGraphSidecarArtifactIdentity',
+  'codeGraphLibraryRoot', 'codeGraphLibraryArtifactIdentity',
+  'packageRoot', 'packageArtifactIdentity',
+  'controllerUiRoot', 'controllerUiArtifactIdentity',
+] as const satisfies readonly (keyof RuntimeReleaseManifest)[];
+
+/**
+ * Compiled self-host candidates have a closed execution surface. Package
+ * launcher releases are a separate source-backed release form and therefore
+ * intentionally do not satisfy this contract.
+ */
+export type CompleteCompiledRuntimeReleaseManifest = RuntimeReleaseManifest & Required<Pick<
+  RuntimeReleaseManifest,
+  typeof COMPILED_RUNTIME_RELEASE_COMPONENT_FIELDS[number]
+>>;
+
+export function requireCompleteCompiledRuntimeReleaseManifest(
+  manifest: RuntimeReleaseManifest,
+): asserts manifest is CompleteCompiledRuntimeReleaseManifest {
+  for (const field of COMPILED_RUNTIME_RELEASE_COMPONENT_FIELDS) {
+    if (manifest[field] === undefined) {
+      throw new Error(`RUNTIME_RELEASE_COMPILED_COMPONENT_MISSING: ${field}`);
+    }
+  }
+}
+
 export function loadRuntimeReleaseManifest(
   path: string,
   expectedControllerHome: string,
@@ -50,18 +121,60 @@ export function loadRuntimeReleaseManifest(
       `RELEASE_DATABASE_SCHEMA_INCOMPATIBLE: runtime=${CONTROL_PLANE_SCHEMA_VERSION} supported=${minimum}-${maximum}`,
     );
   }
-  let diagnosticEntrypoint: 'forge-cli' | undefined;
-  let diagnosticArtifactIdentity: string | undefined;
-  if (value.diagnosticEntrypoint !== undefined) {
-    const diagnosticEntry = requireString(value.diagnosticEntrypoint, 'diagnosticEntrypoint');
-    if (diagnosticEntry !== 'forge-cli') {
-      throw new Error(`RELEASE_MANIFEST_INVALID: diagnosticEntrypoint must be forge-cli, got ${diagnosticEntry}`);
-    }
-    diagnosticEntrypoint = 'forge-cli';
-    diagnosticArtifactIdentity = requireString(value.diagnosticArtifactIdentity, 'diagnosticArtifactIdentity');
-  } else if (value.diagnosticArtifactIdentity !== undefined) {
-    throw new Error('RELEASE_MANIFEST_INVALID: diagnosticArtifactIdentity requires diagnosticEntrypoint');
-  }
+  const diagnostic = optionalRuntimeComponent({
+    value,
+    entryField: 'diagnosticEntrypoint',
+    identityField: 'diagnosticArtifactIdentity',
+    canonicalEntry: 'forge-cli',
+  });
+  const browserNodeBridge = optionalRuntimeComponent({
+    value,
+    entryField: 'browserNodeBridgeEntrypoint',
+    identityField: 'browserNodeBridgeArtifactIdentity',
+    canonicalEntry: 'browser-node-bridge-host.js',
+  });
+  const browserHandoff = optionalRuntimeComponent({
+    value,
+    entryField: 'browserHandoffEntrypoint',
+    identityField: 'browserHandoffArtifactIdentity',
+    canonicalEntry: 'browser-handoff-host.js',
+  });
+  const processRunner = optionalRuntimeComponent({
+    value,
+    entryField: 'processRunnerEntrypoint',
+    identityField: 'processRunnerArtifactIdentity',
+    canonicalEntry: 'process-runner.js',
+  });
+  const checkRunner = optionalRuntimeComponent({
+    value,
+    entryField: 'checkRunnerEntrypoint',
+    identityField: 'checkRunnerArtifactIdentity',
+    canonicalEntry: 'forge-check-runner',
+  });
+  const pluginActionSidecar = optionalRuntimeComponent({
+    value,
+    entryField: 'pluginActionSidecarEntrypoint',
+    identityField: 'pluginActionSidecarArtifactIdentity',
+    canonicalEntry: 'forge-plugin-action-sidecar',
+  });
+  const externalPluginProbe = optionalRuntimeComponent({
+    value,
+    entryField: 'externalPluginProbeEntrypoint',
+    identityField: 'externalPluginProbeArtifactIdentity',
+    canonicalEntry: 'external-unix-socket-probe.cjs',
+  });
+  const packageSnapshot = optionalRuntimeComponent({
+    value,
+    entryField: 'packageRoot',
+    identityField: 'packageArtifactIdentity',
+    canonicalEntry: 'package',
+  });
+  const controllerUi = optionalRuntimeComponent({
+    value,
+    entryField: 'controllerUiRoot',
+    identityField: 'controllerUiArtifactIdentity',
+    canonicalEntry: 'ui-dist',
+  });
   const browserAutomationHelperFields = [
     value.browserAutomationHelperEntrypoint,
     value.browserAutomationHelperArtifactIdentity,
@@ -112,11 +225,11 @@ export function loadRuntimeReleaseManifest(
     }
     codeGraphRuntime = {
       codeGraphNodeEntrypoint: 'codegraph-node',
-      codeGraphNodeArtifactIdentity: requireString(value.codeGraphNodeArtifactIdentity, 'codeGraphNodeArtifactIdentity'),
+      codeGraphNodeArtifactIdentity: requireSha256Identity(value.codeGraphNodeArtifactIdentity, 'codeGraphNodeArtifactIdentity'),
       codeGraphSidecarEntrypoint: 'codegraph-sidecar.cjs',
-      codeGraphSidecarArtifactIdentity: requireString(value.codeGraphSidecarArtifactIdentity, 'codeGraphSidecarArtifactIdentity'),
+      codeGraphSidecarArtifactIdentity: requireSha256Identity(value.codeGraphSidecarArtifactIdentity, 'codeGraphSidecarArtifactIdentity'),
       codeGraphLibraryRoot: 'codegraph-lib',
-      codeGraphLibraryArtifactIdentity: requireString(value.codeGraphLibraryArtifactIdentity, 'codeGraphLibraryArtifactIdentity'),
+      codeGraphLibraryArtifactIdentity: requireSha256Identity(value.codeGraphLibraryArtifactIdentity, 'codeGraphLibraryArtifactIdentity'),
     };
   }
 
@@ -136,9 +249,17 @@ export function loadRuntimeReleaseManifest(
     releaseId: requireString(value.releaseId, 'releaseId'),
     artifactIdentity: requireString(value.artifactIdentity, 'artifactIdentity'),
     entrypoint: 'forge-runtime',
-    ...(diagnosticEntrypoint ? { diagnosticEntrypoint, diagnosticArtifactIdentity } : {}),
+    ...(diagnostic ?? {}),
+    ...(browserNodeBridge ?? {}),
+    ...(browserHandoff ?? {}),
+    ...(processRunner ?? {}),
+    ...(checkRunner ?? {}),
+    ...(pluginActionSidecar ?? {}),
+    ...(externalPluginProbe ?? {}),
     ...(browserAutomationHelper ?? {}),
     ...(codeGraphRuntime ?? {}),
+    ...(packageSnapshot ?? {}),
+    ...(controllerUi ?? {}),
     arguments: argumentsValue as string[],
     configurationSchemaVersion: 1,
     controllerHome,

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

@@ -5,6 +5,8 @@ import { dirname, join, relative, resolve } from 'path';
 import { runProcess } from '../../effects/process-runner';
 import { resolveBunExecutable } from '../shared/process-environment';
 import { CONTROL_PLANE_SCHEMA_VERSION } from '../control-plane/persistence/sqlite-store';
+import { loadRuntimeReleaseManifest, requireCompleteCompiledRuntimeReleaseManifest } from './release-manifest';
+import { packageRuntimeFileIndex, stagePackageRuntimeSnapshot } from './package-runtime-release';
 
 /**
  * Stage one immutable Forge Runtime release below Controller Home. The staged
@@ -24,6 +26,7 @@ export interface MacOSRuntimeCodeSigning {
 }
 
 export interface StagedRuntimeRelease {
+  controllerHome: string;
   releasePath: string;
   manifestPath: string;
   releaseId: string;
@@ -38,6 +41,7 @@ export interface StagedRuntimeRelease {
   codeGraphNodeArtifactIdentity?: string;
   codeGraphSidecarArtifactIdentity?: string;
   codeGraphLibraryArtifactIdentity?: string;
+  packageArtifactIdentity?: string;
   controllerUiArtifactIdentity?: string;
   macosCodeSigning?: MacOSRuntimeCodeSigning;
   manifestSha256: string;
@@ -309,6 +313,13 @@ export function stageRuntimeReleaseFromCandidateSource(input: {
   let rawManifest: Record<string, unknown>;
   try { rawManifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Record<string, unknown>; }
   catch (error) { throw new Error(`RUNTIME_RELEASE_CANDIDATE_MANIFEST_INVALID: ${error instanceof Error ? error.message : String(error)}`); }
+  const manifest = loadRuntimeReleaseManifest(manifestPath, controllerHome);
+  requireCompleteCompiledRuntimeReleaseManifest(manifest);
+  if (manifest.releaseId !== receipt.releaseId
+    || manifest.artifactIdentity !== receipt.artifactIdentity
+    || manifest.sourceCommit !== receipt.sourceCommit) {
+    throw new Error('RUNTIME_RELEASE_CANDIDATE_MANIFEST_RECEIPT_MISMATCH');
+  }
   const platform = dependencies.platform ?? process.platform;
   const macosCodeSigning = parseMacOSRuntimeCodeSigning(rawManifest.macosCodeSigning, 'RUNTIME_RELEASE_CANDIDATE_SIGNING_INVALID');
   if (platform === 'darwin') {
@@ -322,15 +333,30 @@ export function stageRuntimeReleaseFromCandidateSource(input: {
     }
   }
 
-  return {
+  const staged: StagedRuntimeRelease = {
+    controllerHome,
     releasePath,
     manifestPath,
     releaseId: receipt.releaseId,
     artifactIdentity: receipt.artifactIdentity,
+    diagnosticArtifactIdentity: manifest.diagnosticArtifactIdentity,
+    browserNodeBridgeArtifactIdentity: manifest.browserNodeBridgeArtifactIdentity,
+    browserHandoffArtifactIdentity: manifest.browserHandoffArtifactIdentity,
+    processRunnerArtifactIdentity: manifest.processRunnerArtifactIdentity,
+    checkRunnerArtifactIdentity: manifest.checkRunnerArtifactIdentity,
+    pluginActionSidecarArtifactIdentity: manifest.pluginActionSidecarArtifactIdentity,
+    externalPluginProbeArtifactIdentity: manifest.externalPluginProbeArtifactIdentity,
+    codeGraphNodeArtifactIdentity: manifest.codeGraphNodeArtifactIdentity,
+    codeGraphSidecarArtifactIdentity: manifest.codeGraphSidecarArtifactIdentity,
+    codeGraphLibraryArtifactIdentity: manifest.codeGraphLibraryArtifactIdentity,
+    packageArtifactIdentity: manifest.packageArtifactIdentity,
+    controllerUiArtifactIdentity: manifest.controllerUiArtifactIdentity,
     ...(macosCodeSigning ? { macosCodeSigning } : {}),
     manifestSha256: receipt.manifestSha256,
     sourceCommit: receipt.sourceCommit,
   };
+  assertRuntimeReleaseFiles(staged, dependencies);
+  return staged;
 }
 
 function defaultCompileBinary(input: { sourceRoot: string; outputPath: string; entryPath?: string }): { ok: boolean; stderr?: string; stdout?: string; error?: string } {
@@ -547,6 +573,16 @@ export function stageRuntimeRelease(input: {
     cpSync(sourceControllerUiPath, controllerUiPath, { recursive: true, force: false });
     const controllerUiArtifactIdentity = `sha256:${sha256Directory(controllerUiPath)}`;
 
+    // The persistent OAuth/Connector is source-backed even when the primary
+    // Runtime itself is compiled. Co-locate one immutable package snapshot in
+    // the same release so standalone Recovery can bind the Connector to the
+    // exact active release instead of retaining an older package release.
+    const packageRoot = 'package' as const;
+    const packagePath = join(staging, packageRoot);
+    const packageRecords = packageRuntimeFileIndex(sourceRoot);
+    stagePackageRuntimeSnapshot(sourceRoot, packagePath, packageRecords);
+    const packageArtifactIdentity = `sha256:${sha256Directory(packagePath)}`;
+
     const manifest = {
       schemaVersion: 1,
       releaseId,
@@ -573,6 +609,8 @@ export function stageRuntimeRelease(input: {
       codeGraphSidecarArtifactIdentity,
       codeGraphLibraryRoot,
       codeGraphLibraryArtifactIdentity,
+      packageRoot,
+      packageArtifactIdentity,
       controllerUiRoot,
       controllerUiArtifactIdentity,
       arguments: [],
@@ -592,6 +630,7 @@ export function stageRuntimeRelease(input: {
     writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
     renameSync(staging, releasePath);
     return {
+      controllerHome: resolve(input.controllerHome),
       releasePath,
       manifestPath: join(releasePath, 'manifest.json'),
       releaseId,
@@ -602,10 +641,12 @@ export function stageRuntimeRelease(input: {
       browserHandoffArtifactIdentity,
       processRunnerArtifactIdentity,
       checkRunnerArtifactIdentity,
+      pluginActionSidecarArtifactIdentity,
       externalPluginProbeArtifactIdentity,
       codeGraphNodeArtifactIdentity,
       codeGraphSidecarArtifactIdentity,
       codeGraphLibraryArtifactIdentity,
+      packageArtifactIdentity,
       controllerUiArtifactIdentity,
       manifestSha256: createHash('sha256').update(`${JSON.stringify(manifest, null, 2)}\n`).digest('hex'),
       sourceCommit,
@@ -617,13 +658,53 @@ export function stageRuntimeRelease(input: {
 }
 
 export function assertRuntimeReleaseFiles(release: StagedRuntimeRelease, dependencies: { platform?: NodeJS.Platform; inspectMacOSRuntime?: (executable: string) => MacOSRuntimeCodeSigning } = {}): void {
+  const assertRegularFile = (path: string, missingCode: string): void => {
+    if (!existsSync(path)) throw new Error(`${missingCode}: ${path}`);
+    const status = lstatSync(path);
+    if (status.isSymbolicLink() || !status.isFile()) throw new Error(`RUNTIME_RELEASE_PATH_NOT_REGULAR_FILE: ${path}`);
+  };
+  const assertExecutable = (path: string): void => {
+    if ((statSync(path).mode & 0o111) === 0) throw new Error(`RUNTIME_RELEASE_ENTRYPOINT_NOT_EXECUTABLE: ${path}`);
+  };
+  const assertFileIdentity = (path: string, expected: string): void => {
+    const actual = `sha256:${sha256(path)}`;
+    if (actual !== expected) throw new Error(`RUNTIME_RELEASE_ARTIFACT_IDENTITY_MISMATCH: ${path}`);
+  };
+  const assertDirectoryIdentity = (path: string, expected: string): void => {
+    if (!existsSync(path)) throw new Error(`RUNTIME_RELEASE_DIRECTORY_MISSING: ${path}`);
+    const status = lstatSync(path);
+    if (status.isSymbolicLink() || !status.isDirectory()) throw new Error(`RUNTIME_RELEASE_PATH_NOT_DIRECTORY: ${path}`);
+    const actual = `sha256:${sha256Directory(path)}`;
+    if (actual !== expected) throw new Error(`RUNTIME_RELEASE_ARTIFACT_IDENTITY_MISMATCH: ${path}`);
+  };
+  const assertComponentFile = (input: { path: string; identity?: string; missingCode: string; executable?: boolean }): void => {
+    if (!input.identity) return;
+    assertRegularFile(input.path, input.missingCode);
+    assertFileIdentity(input.path, input.identity);
+    if (input.executable) assertExecutable(input.path);
+  };
+
   if (!existsSync(release.releasePath) || !existsSync(release.manifestPath)) {
     throw new Error(`RUNTIME_RELEASE_FILES_MISSING: ${release.releasePath}`);
   }
-  const runtimePath = join(release.releasePath, 'forge-runtime');
-  if (!existsSync(runtimePath)) {
-    throw new Error(`RUNTIME_RELEASE_ENTRYPOINT_MISSING: ${runtimePath}`);
+  const releasesRoot = join(resolve(release.controllerHome), 'runtime', 'releases');
+  if (resolve(release.releasePath) !== join(releasesRoot, release.releaseId)
+    || resolve(release.manifestPath) !== join(release.releasePath, 'manifest.json')) {
+    throw new Error('RUNTIME_RELEASE_PATH_OUTSIDE_CONTROLLER_HOME');
+  }
+  const releaseStatus = lstatSync(release.releasePath);
+  const manifestStatus = lstatSync(release.manifestPath);
+  if (releaseStatus.isSymbolicLink() || !releaseStatus.isDirectory()
+    || manifestStatus.isSymbolicLink() || !manifestStatus.isFile()) {
+    throw new Error(`RUNTIME_RELEASE_PATH_NOT_PHYSICAL: ${release.releasePath}`);
   }
+  if (sha256(release.manifestPath) !== release.manifestSha256) {
+    throw new Error('RUNTIME_RELEASE_MANIFEST_IDENTITY_MISMATCH');
+  }
+  const runtimePath = join(release.releasePath, 'forge-runtime');
+  assertRegularFile(runtimePath, 'RUNTIME_RELEASE_ENTRYPOINT_MISSING');
+  assertExecutable(runtimePath);
+  assertFileIdentity(runtimePath, release.artifactIdentity);
   const platform = dependencies.platform ?? process.platform;
   if (platform === 'darwin' && release.macosCodeSigning) {
     const actual = (dependencies.inspectMacOSRuntime ?? inspectMacOSRuntimeCodeSigning)(runtimePath);
@@ -634,38 +715,31 @@ export function assertRuntimeReleaseFiles(release: StagedRuntimeRelease, depende
       throw new Error('RUNTIME_RELEASE_MACOS_SIGNING_MISMATCH');
     }
   }
-  if (release.diagnosticArtifactIdentity && !existsSync(join(release.releasePath, 'forge-cli'))) {
-    throw new Error(`RUNTIME_RELEASE_DIAGNOSTIC_ENTRYPOINT_MISSING: ${join(release.releasePath, 'forge-cli')}`);
-  }
-  if (release.browserNodeBridgeArtifactIdentity && !existsSync(join(release.releasePath, 'browser-node-bridge-host.js'))) {
-    throw new Error(`RUNTIME_RELEASE_BROWSER_NODE_HOST_MISSING: ${join(release.releasePath, 'browser-node-bridge-host.js')}`);
-  }
-  if (release.browserHandoffArtifactIdentity && !existsSync(join(release.releasePath, 'browser-handoff-host.js'))) {
-    throw new Error(`RUNTIME_RELEASE_BROWSER_HANDOFF_HOST_MISSING: ${join(release.releasePath, 'browser-handoff-host.js')}`);
-  }
-  if (release.processRunnerArtifactIdentity && !existsSync(join(release.releasePath, 'process-runner.js'))) {
-    throw new Error(`RUNTIME_RELEASE_PROCESS_RUNNER_MISSING: ${join(release.releasePath, 'process-runner.js')}`);
-  }
-  if (release.checkRunnerArtifactIdentity && !existsSync(join(release.releasePath, 'forge-check-runner'))) {
-    throw new Error(`RUNTIME_RELEASE_CHECK_RUNNER_MISSING: ${join(release.releasePath, 'forge-check-runner')}`);
-  }
-  if (release.pluginActionSidecarArtifactIdentity && !existsSync(join(release.releasePath, 'forge-plugin-action-sidecar'))) {
-    throw new Error(`RUNTIME_RELEASE_PLUGIN_ACTION_SIDECAR_MISSING: ${join(release.releasePath, 'forge-plugin-action-sidecar')}`);
-  }
-  if (release.externalPluginProbeArtifactIdentity && !existsSync(join(release.releasePath, 'external-unix-socket-probe.cjs'))) {
-    throw new Error(`RUNTIME_RELEASE_EXTERNAL_PLUGIN_PROBE_MISSING: ${join(release.releasePath, 'external-unix-socket-probe.cjs')}`);
-  }
-  if (release.codeGraphNodeArtifactIdentity && !existsSync(join(release.releasePath, 'codegraph-node'))) {
-    throw new Error(`RUNTIME_RELEASE_CODEGRAPH_NODE_MISSING: ${join(release.releasePath, 'codegraph-node')}`);
-  }
-  if (release.codeGraphSidecarArtifactIdentity && !existsSync(join(release.releasePath, 'codegraph-sidecar.cjs'))) {
-    throw new Error(`RUNTIME_RELEASE_CODEGRAPH_SIDECAR_MISSING: ${join(release.releasePath, 'codegraph-sidecar.cjs')}`);
+  assertComponentFile({ path: join(release.releasePath, 'forge-cli'), identity: release.diagnosticArtifactIdentity, missingCode: 'RUNTIME_RELEASE_DIAGNOSTIC_ENTRYPOINT_MISSING', executable: true });
+  assertComponentFile({ path: join(release.releasePath, 'browser-node-bridge-host.js'), identity: release.browserNodeBridgeArtifactIdentity, missingCode: 'RUNTIME_RELEASE_BROWSER_NODE_HOST_MISSING', executable: true });
+  assertComponentFile({ path: join(release.releasePath, 'browser-handoff-host.js'), identity: release.browserHandoffArtifactIdentity, missingCode: 'RUNTIME_RELEASE_BROWSER_HANDOFF_HOST_MISSING', executable: true });
+  assertComponentFile({ path: join(release.releasePath, 'process-runner.js'), identity: release.processRunnerArtifactIdentity, missingCode: 'RUNTIME_RELEASE_PROCESS_RUNNER_MISSING', executable: true });
+  assertComponentFile({ path: join(release.releasePath, 'forge-check-runner'), identity: release.checkRunnerArtifactIdentity, missingCode: 'RUNTIME_RELEASE_CHECK_RUNNER_MISSING', executable: true });
+  assertComponentFile({ path: join(release.releasePath, 'forge-plugin-action-sidecar'), identity: release.pluginActionSidecarArtifactIdentity, missingCode: 'RUNTIME_RELEASE_PLUGIN_ACTION_SIDECAR_MISSING', executable: true });
+  assertComponentFile({ path: join(release.releasePath, 'external-unix-socket-probe.cjs'), identity: release.externalPluginProbeArtifactIdentity, missingCode: 'RUNTIME_RELEASE_EXTERNAL_PLUGIN_PROBE_MISSING', executable: true });
+  assertComponentFile({ path: join(release.releasePath, 'codegraph-node'), identity: release.codeGraphNodeArtifactIdentity, missingCode: 'RUNTIME_RELEASE_CODEGRAPH_NODE_MISSING', executable: true });
+  assertComponentFile({ path: join(release.releasePath, 'codegraph-sidecar.cjs'), identity: release.codeGraphSidecarArtifactIdentity, missingCode: 'RUNTIME_RELEASE_CODEGRAPH_SIDECAR_MISSING', executable: true });
+  if (release.codeGraphLibraryArtifactIdentity) {
+    const libraryRoot = join(release.releasePath, 'codegraph-lib');
+    if (!existsSync(join(libraryRoot, 'dist', 'index.js'))) {
+      throw new Error(`RUNTIME_RELEASE_CODEGRAPH_LIBRARY_MISSING: ${join(libraryRoot, 'dist', 'index.js')}`);
+    }
+    assertDirectoryIdentity(libraryRoot, release.codeGraphLibraryArtifactIdentity);
   }
-  if (release.codeGraphLibraryArtifactIdentity && !existsSync(join(release.releasePath, 'codegraph-lib', 'dist', 'index.js'))) {
-    throw new Error(`RUNTIME_RELEASE_CODEGRAPH_LIBRARY_MISSING: ${join(release.releasePath, 'codegraph-lib', 'dist', 'index.js')}`);
+  if (release.packageArtifactIdentity) {
+    const packageRoot = join(release.releasePath, 'package');
+    assertDirectoryIdentity(packageRoot, release.packageArtifactIdentity);
   }
-  if (release.controllerUiArtifactIdentity
-    && (!existsSync(join(release.releasePath, 'ui-dist', 'app.js')) || !existsSync(join(release.releasePath, 'ui-dist', 'app.css')))) {
-    throw new Error(`RUNTIME_RELEASE_CONTROLLER_UI_MISSING: ${join(release.releasePath, 'ui-dist')}`);
+  if (release.controllerUiArtifactIdentity) {
+    const uiRoot = join(release.releasePath, 'ui-dist');
+    if (!existsSync(join(uiRoot, 'app.js')) || !existsSync(join(uiRoot, 'app.css'))) {
+      throw new Error(`RUNTIME_RELEASE_CONTROLLER_UI_MISSING: ${uiRoot}`);
+    }
+    assertDirectoryIdentity(uiRoot, release.controllerUiArtifactIdentity);
   }
 }

package/src/runtime/root/types.ts

@@ -39,8 +39,14 @@ export interface RuntimeReleaseManifest {
   browserNodeBridgeArtifactIdentity?: string;
   browserHandoffEntrypoint?: 'browser-handoff-host.js';
   browserHandoffArtifactIdentity?: string;
+  processRunnerEntrypoint?: 'process-runner.js';
+  processRunnerArtifactIdentity?: string;
+  checkRunnerEntrypoint?: 'forge-check-runner';
+  checkRunnerArtifactIdentity?: string;
   pluginActionSidecarEntrypoint?: 'forge-plugin-action-sidecar';
   pluginActionSidecarArtifactIdentity?: string;
+  externalPluginProbeEntrypoint?: 'external-unix-socket-probe.cjs';
+  externalPluginProbeArtifactIdentity?: string;
   browserAutomationHelperEntrypoint?: 'browser-automation-helper';
   browserAutomationHelperArtifactIdentity?: string;
   browserAutomationHelperContractIdentity?: string;
@@ -50,6 +56,10 @@ export interface RuntimeReleaseManifest {
   codeGraphSidecarArtifactIdentity?: string;
   codeGraphLibraryRoot?: 'codegraph-lib';
   codeGraphLibraryArtifactIdentity?: string;
+  packageRoot?: 'package';
+  packageArtifactIdentity?: string;
+  controllerUiRoot?: 'ui-dist';
+  controllerUiArtifactIdentity?: string;
   arguments: string[];
   configurationSchemaVersion: 1;
   controllerHome: string;