@moretea-labs/forge 1.6.0 → 1.7.1

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

@@ -1,4 +1,4 @@
-import { readFileSync } from 'fs';
+import { existsSync, readFileSync, realpathSync } from 'fs';
 import { resolve } from 'path';
 import { CONTROL_PLANE_SCHEMA_VERSION } from '../control-plane/persistence/sqlite-store';
 import type { RuntimeReleaseManifest } from './types';
@@ -8,6 +8,82 @@ function requireString(value: unknown, field: string): string {
   return value.trim();
 }
 
+function canonicalExistingPathIdentity(path: string): string {
+  const resolved = resolve(path);
+  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,
@@ -31,7 +107,7 @@ export function loadRuntimeReleaseManifest(
     throw new Error('RELEASE_MANIFEST_INVALID: configurationSchemaVersion must be 1');
   }
   const controllerHome = resolve(requireString(value.controllerHome, 'controllerHome'));
-  if (controllerHome !== resolve(expectedControllerHome)) {
+  if (canonicalExistingPathIdentity(controllerHome) !== canonicalExistingPathIdentity(expectedControllerHome)) {
     throw new Error('RELEASE_MANIFEST_CONTROLLER_HOME_MISMATCH');
   }
   const compatibility = value.databaseSchemaCompatibility as Record<string, unknown> | undefined;
@@ -45,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,
@@ -107,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'),
     };
   }
 
@@ -131,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;
@@ -33,10 +36,12 @@ export interface StagedRuntimeRelease {
   browserHandoffArtifactIdentity?: string;
   processRunnerArtifactIdentity?: string;
   checkRunnerArtifactIdentity?: string;
+  pluginActionSidecarArtifactIdentity?: string;
   externalPluginProbeArtifactIdentity?: string;
   codeGraphNodeArtifactIdentity?: string;
   codeGraphSidecarArtifactIdentity?: string;
   codeGraphLibraryArtifactIdentity?: string;
+  packageArtifactIdentity?: string;
   controllerUiArtifactIdentity?: string;
   macosCodeSigning?: MacOSRuntimeCodeSigning;
   manifestSha256: string;
@@ -308,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') {
@@ -321,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 } {
@@ -491,6 +518,19 @@ export function stageRuntimeRelease(input: {
     chmodSync(checkRunnerPath, 0o700);
     const checkRunnerArtifactIdentity = `sha256:${sha256(checkRunnerPath)}`;
 
+    const pluginActionSidecarEntrypoint = 'forge-plugin-action-sidecar' as const;
+    const pluginActionSidecarPath = join(staging, pluginActionSidecarEntrypoint);
+    const pluginActionSidecarCompile = compileBinary({
+      sourceRoot,
+      outputPath: pluginActionSidecarPath,
+      entryPath: join(sourceRoot, 'src/runtime/plugins/plugin-action-sidecar.ts'),
+    });
+    if (!pluginActionSidecarCompile.ok) {
+      throw new Error(`RUNTIME_RELEASE_PLUGIN_ACTION_SIDECAR_BUILD_FAILED: ${pluginActionSidecarCompile.stderr || pluginActionSidecarCompile.stdout || pluginActionSidecarCompile.error}`.slice(0, 2_000));
+    }
+    chmodSync(pluginActionSidecarPath, 0o700);
+    const pluginActionSidecarArtifactIdentity = `sha256:${sha256(pluginActionSidecarPath)}`;
+
     const externalPluginProbeEntrypoint = 'external-unix-socket-probe.cjs' as const;
     const sourceExternalPluginProbePath = join(sourceRoot, 'src', 'runtime', 'plugins', externalPluginProbeEntrypoint);
     if (!existsSync(sourceExternalPluginProbePath)) {
@@ -533,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,
@@ -549,6 +599,8 @@ export function stageRuntimeRelease(input: {
       processRunnerArtifactIdentity,
       checkRunnerEntrypoint,
       checkRunnerArtifactIdentity,
+      pluginActionSidecarEntrypoint,
+      pluginActionSidecarArtifactIdentity,
       externalPluginProbeEntrypoint,
       externalPluginProbeArtifactIdentity,
       codeGraphNodeEntrypoint,
@@ -557,6 +609,8 @@ export function stageRuntimeRelease(input: {
       codeGraphSidecarArtifactIdentity,
       codeGraphLibraryRoot,
       codeGraphLibraryArtifactIdentity,
+      packageRoot,
+      packageArtifactIdentity,
       controllerUiRoot,
       controllerUiArtifactIdentity,
       arguments: [],
@@ -576,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,
@@ -586,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,
@@ -601,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);
@@ -618,35 +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.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/release-store.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { ensureControllerHome } from '../../cli/repositories/controller-home';
 import {
@@ -102,9 +102,14 @@ function validRelease(controllerHome: string, release: RuntimePublishedRelease |
   }
 }
 
-export function readRuntimeReleaseAuthority(controllerHome: string): RuntimeReleaseAuthority | undefined {
+type RuntimeReleaseAuthorityRead =
+  | { state: 'missing' }
+  | { state: 'valid'; authority: RuntimeReleaseAuthority }
+  | { state: 'invalid'; reason: string };
+
+function inspectRuntimeReleaseAuthority(controllerHome: string): RuntimeReleaseAuthorityRead {
   const path = runtimeReleaseAuthorityPath(controllerHome);
-  if (!existsSync(path)) return undefined;
+  if (!existsSync(path)) return { state: 'missing' };
   try {
     const value = JSON.parse(readFileSync(path, 'utf8')) as RuntimeReleaseAuthority;
     if (
@@ -117,11 +122,24 @@ export function readRuntimeReleaseAuthority(controllerHome: string): RuntimeRele
       || !Number.isFinite(Date.parse(value.committedAt))
       || !validRelease(controllerHome, value.active)
       || (value.previous !== undefined && !validRelease(controllerHome, value.previous))
-    ) return undefined;
-    return value;
-  } catch {
-    return undefined;
+    ) return { state: 'invalid', reason: 'authority fields or referenced release evidence are invalid' };
+    return { state: 'valid', authority: value };
+  } catch (error) {
+    return { state: 'invalid', reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function mutableRuntimeReleaseAuthority(controllerHome: string): RuntimeReleaseAuthority | undefined {
+  const observed = inspectRuntimeReleaseAuthority(controllerHome);
+  if (observed.state === 'invalid') {
+    throw new Error(`RUNTIME_RELEASE_AUTHORITY_INVALID_EXISTING: ${observed.reason}`);
   }
+  return observed.state === 'valid' ? observed.authority : undefined;
+}
+
+export function readRuntimeReleaseAuthority(controllerHome: string): RuntimeReleaseAuthority | undefined {
+  const observed = inspectRuntimeReleaseAuthority(controllerHome);
+  return observed.state === 'valid' ? observed.authority : undefined;
 }
 
 function writeRuntimeReleaseAuthority(controllerHome: string, authority: RuntimeReleaseAuthority): RuntimeReleaseAuthority {
@@ -145,7 +163,7 @@ export function ensureActiveRuntimeRelease(
   operationId = 'runtime-start',
 ): RuntimeReleaseAuthority {
   const active = manifestRecord(controllerHome, manifestPath);
-  const current = readRuntimeReleaseAuthority(controllerHome);
+  const current = mutableRuntimeReleaseAuthority(controllerHome);
   if (current) {
     if (!sameRelease(current.active, active)) throw new Error('RUNTIME_RELEASE_AUTHORITY_MISMATCH');
     return current;
@@ -169,8 +187,18 @@ export function publishRuntimeRelease(
 ): RuntimeReleaseAuthority {
   if (!operationId.trim()) throw new Error('RUNTIME_RELEASE_OPERATION_ID_REQUIRED');
   const candidate = manifestRecord(controllerHome, manifestPath);
-  const current = readRuntimeReleaseAuthority(controllerHome);
-  if (!current) return ensureActiveRuntimeRelease(controllerHome, manifestPath, operationId);
+  const current = mutableRuntimeReleaseAuthority(controllerHome);
+  if (!current) {
+    return writeRuntimeReleaseAuthority(controllerHome, {
+      schemaVersion: 1,
+      status: 'committed',
+      revision: 1,
+      fencingToken: randomUUID(),
+      active: candidate,
+      operationId,
+      committedAt: new Date().toISOString(),
+    });
+  }
   if (sameRelease(current.active, candidate)) return current;
   const backup = backupPath(controllerHome, current.active.releaseId, operationId);
   const inspection = dependencies.backupDatabase(controllerHome, backup);
@@ -190,13 +218,22 @@ export function publishRuntimeRelease(
   });
 }
 
+export function revertInitialRuntimeReleasePublication(controllerHome: string, operationId: string): void {
+  const current = mutableRuntimeReleaseAuthority(controllerHome);
+  if (!current) return;
+  if (current.revision !== 1 || current.previous !== undefined || current.operationId !== operationId) {
+    throw new Error('RUNTIME_RELEASE_INITIAL_PUBLICATION_REVERT_MISMATCH');
+  }
+  rmSync(runtimeReleaseAuthorityPath(controllerHome), { force: true });
+}
+
 export function rollbackRuntimeRelease(
   controllerHome: string,
   operationId: string,
   dependencies: RuntimeReleaseStoreDependencies = DEFAULT_DEPENDENCIES,
 ): RuntimeReleaseAuthority {
   if (!operationId.trim()) throw new Error('RUNTIME_RELEASE_OPERATION_ID_REQUIRED');
-  const current = readRuntimeReleaseAuthority(controllerHome);
+  const current = mutableRuntimeReleaseAuthority(controllerHome);
   const target = current?.previous;
   if (!current || !target?.databaseBackup) throw new Error('RUNTIME_PREVIOUS_RELEASE_UNAVAILABLE');
   const currentBackup = backupPath(controllerHome, current.active.releaseId, operationId);

package/src/runtime/root/runtime.ts

@@ -6,6 +6,8 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import type { ControlPlaneDatabaseInspection } from '../control-plane/persistence/sqlite-store';
 import { inspectControlPlaneDatabase } from '../control-plane/persistence/sqlite-store';
 import { activateExclusiveWorkAdmission } from '../control-plane/facade/work-admission-policy';
+import { closeCodeGraphReadProviderSessions } from '../context/codegraph-read-provider';
+import { cancelAllLightweightProcesses } from '../execution/process-runtime/lightweight-managed';
 import {
   collectRuntimeSourceIdentity,
   rotateRuntimeGeneration,
@@ -40,6 +42,9 @@ export interface CanonicalRuntimeDependencies {
   runMcpProbe(endpoint: string, authToken: string): Promise<void>;
   collectRuntimeSourceIdentity: typeof collectRuntimeSourceIdentity;
   rotateRuntimeGeneration: typeof rotateRuntimeGeneration;
+  stopLightweightProcesses(controllerHome: string): Promise<number>;
+  stopContextReadHelpers(): Promise<void>;
+  computeToolSurfaceFingerprint: typeof runtimeGatewayToolSurfaceFingerprint;
 }
 
 async function defaultMcpProbe(endpoint: string, authToken: string): Promise<void> {
@@ -77,6 +82,9 @@ const DEFAULT_DEPENDENCIES: CanonicalRuntimeDependencies = {
   runMcpProbe: defaultMcpProbe,
   collectRuntimeSourceIdentity,
   rotateRuntimeGeneration,
+  stopLightweightProcesses: cancelAllLightweightProcesses,
+  stopContextReadHelpers: closeCodeGraphReadProviderSessions,
+  computeToolSurfaceFingerprint: runtimeGatewayToolSurfaceFingerprint,
 };
 
 export class CanonicalForgeRuntime {
@@ -143,6 +151,17 @@ export class CanonicalForgeRuntime {
     }
   }
 
+  private refreshToolSurfaceFingerprint(runtimeSourceRoot: string): void {
+    const next = this.dependencies.computeToolSurfaceFingerprint({
+      controllerHome: this.config.controllerHome,
+      runtimeInstanceId: this.runtimeInstanceId,
+      runtimeSourceRoot,
+    });
+    if (next === this.toolSurfaceFingerprint) return;
+    this.toolSurfaceFingerprint = next;
+    this.publishStatus();
+  }
+
   endpoint(): string | undefined {
     return this.transport?.endpoint;
   }
@@ -218,11 +237,7 @@ export class CanonicalForgeRuntime {
       });
 
       stage = 'transport';
-      this.toolSurfaceFingerprint = runtimeGatewayToolSurfaceFingerprint({
-        controllerHome: this.config.controllerHome,
-        runtimeInstanceId: this.runtimeInstanceId,
-        runtimeSourceRoot,
-      });
+      this.refreshToolSurfaceFingerprint(runtimeSourceRoot);
       this.transport = await this.dependencies.startTransport({
         host: this.config.host,
         port: this.config.port,
@@ -235,6 +250,7 @@ export class CanonicalForgeRuntime {
           sessionId,
           controllerType,
         }),
+        onToolSurfaceObservation: () => this.refreshToolSurfaceFingerprint(runtimeSourceRoot),
         onFatal: (error) => this.failCore('MCP_TRANSPORT_FAILED', error.message),
       });
       this.publishStatus();
@@ -298,6 +314,8 @@ export class CanonicalForgeRuntime {
       // Stop accepting new MCP work before quiescing Scheduler activity, then
       // release the Controller Home claim only after all in-process services stop.
       await this.transport?.close().catch(() => undefined);
+      await this.dependencies.stopLightweightProcesses(this.config.controllerHome).catch(() => undefined);
+      await this.dependencies.stopContextReadHelpers().catch(() => undefined);
       await this.localBridge?.close().catch(() => undefined);
       await this.scheduler?.stop().catch(() => undefined);
       const ownerPid = this.ownership?.record.pid;