@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -1,11 +1,13 @@
 import { createHash, randomUUID } from 'crypto';
 import { createRequire } from 'module';
-import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
+import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
 import { dirname, join, relative, resolve } from 'path';
 import { runProcess } from '../../effects/process-runner';
 import { resolveBunExecutable } from '../shared/process-environment';
+import { assertStorageHeadroom } from '../shared/storage-capacity';
 import { CONTROL_PLANE_SCHEMA_VERSION } from '../control-plane/persistence/sqlite-store';
-import { loadRuntimeReleaseManifest, requireCompleteCompiledRuntimeReleaseManifest } from './release-manifest';
+import { assertRuntimeReleaseExecutionSurface, loadRuntimeReleaseManifest, requireCompleteCompiledRuntimeReleaseManifest } from './release-manifest';
 import { assertRuntimeReleaseExecutionCanaries, type RuntimeReleaseExecutionCanaryCommand } from './release-execution-canary';
 export { assertRuntimeReleaseExecutionCanaries, type RuntimeReleaseExecutionCanaryDependencies } from './release-execution-canary';
 import { packageRuntimeFileIndex, stagePackageRuntimeSnapshot } from './package-runtime-release';
@@ -34,11 +36,16 @@ export interface StagedRuntimeRelease {
   releaseId: string;
   artifactIdentity: string;
   runtimeBundleArtifactIdentity?: string;
+  runtimeInterpreterArtifactIdentity?: string;
   diagnosticArtifactIdentity?: string;
+  connectorArtifactIdentity?: string;
   browserNodeBridgeArtifactIdentity?: string;
   browserHandoffArtifactIdentity?: string;
+  workflowSupervisorNativeHostArtifactIdentity?: string;
   processRunnerArtifactIdentity?: string;
   checkRunnerArtifactIdentity?: string;
+  typescriptNavigationArtifactIdentity?: string;
+  contextPackArtifactIdentity?: string;
   schedulerWorkerArtifactIdentity?: string;
   periodicCleanupArtifactIdentity?: string;
   pluginActionSidecarArtifactIdentity?: string;
@@ -61,6 +68,7 @@ export interface RuntimeReleaseMaterializerDependencies {
   uuid?: () => string;
   compileBinary?: (input: { sourceRoot: string; outputPath: string; entryPath?: string }) => { ok: boolean; stderr?: string; stdout?: string; error?: string };
   bundleRuntime?: (input: { sourceRoot: string; outputPath: string; entryPath: string }) => { ok: boolean; stderr?: string; stdout?: string; error?: string };
+  materializeRuntimeInterpreter?: (input: { sourceRoot: string; outputPath: string }) => { ok: boolean; stderr?: string; stdout?: string; error?: string };
   bundleNodeHost?: (input: { sourceRoot: string; outputPath: string; entryPath: string }) => { ok: boolean; stderr?: string; stdout?: string; error?: string };
   bundleProcessRunner?: (input: { sourceRoot: string; outputPath: string; entryPath: string }) => { ok: boolean; stderr?: string; stdout?: string; error?: string };
   materializeCodeGraphRuntime?: (input: {
@@ -89,6 +97,7 @@ export interface CandidateRuntimeReleaseStagerDependencies {
     bunExecutable: string;
     scriptPath: string;
     sourceRoot: string;
+    dependencyRoot: string;
     controllerHome: string;
     expectedHead: string;
     sourceRepositoryId: string;
@@ -102,6 +111,61 @@ function gitText(root: string, args: string[]): string {
   return result.stdout.trim();
 }
 
+/**
+ * Materialize one exact tracked Git revision into a detached temporary worktree.
+ * The mutable source checkout remains only the object/dependency provider and may
+ * advance while the callback runs. Lifecycle/Runtime authority is untouched.
+ */
+export function withRuntimeReleaseSourceSnapshot<T>(input: {
+  sourceRoot: string;
+  sourceRevision: string;
+}, operation: (snapshotRoot: string) => T): T {
+  const sourceRoot = resolve(input.sourceRoot);
+  const requestedRevision = input.sourceRevision.trim();
+  if (!/^[a-f0-9]{40}$/i.test(requestedRevision)) throw new Error('RUNTIME_RELEASE_SOURCE_REVISION_INVALID');
+  const resolvedRevision = gitText(sourceRoot, ['rev-parse', '--verify', `${requestedRevision}^{commit}`]);
+  if (resolvedRevision !== requestedRevision) throw new Error('RUNTIME_RELEASE_SOURCE_REVISION_MISMATCH');
+  // Release materialization is Runtime-owned temporary state, not repository
+  // workspace state. Keeping the detached worktree outside sourceRoot prevents
+  // Forge's own immutable-source snapshot from perturbing repository status or
+  // workspace fingerprints while release validation is running.
+  const snapshotContainer = mkdtempSync(join(tmpdir(), `forge-runtime-release-source-${process.pid}-`));
+  const snapshotRoot = join(snapshotContainer, `${requestedRevision}-${randomUUID().slice(0, 8)}`);
+  const materialized = runProcess('git', ['-C', sourceRoot, 'worktree', 'add', '--detach', '--force', snapshotRoot, requestedRevision], {
+    timeoutMs: 60_000,
+    maxOutputBytes: 128 * 1024,
+  });
+  if (!materialized.ok) {
+    rmSync(snapshotContainer, { recursive: true, force: true });
+    runProcess('git', ['-C', sourceRoot, 'worktree', 'prune'], { timeoutMs: 30_000, maxOutputBytes: 64 * 1024 });
+    throw new Error(`RUNTIME_RELEASE_SOURCE_SNAPSHOT_FAILED: ${materialized.stderr || materialized.stdout || materialized.error}`.slice(0, 2_000));
+  }
+  try {
+    const sourceDependencies = join(sourceRoot, 'node_modules');
+    if (existsSync(sourceDependencies)) {
+      const snapshotDependencies = join(snapshotRoot, 'node_modules');
+      symlinkSync(realpathSync(sourceDependencies), snapshotDependencies, process.platform === 'win32' ? 'junction' : 'dir');
+    }
+    if (gitText(snapshotRoot, ['rev-parse', '--verify', 'HEAD']) !== requestedRevision) {
+      throw new Error('RUNTIME_RELEASE_SOURCE_SNAPSHOT_REVISION_MISMATCH');
+    }
+    if (gitText(snapshotRoot, ['status', '--porcelain=v1', '--untracked-files=no'])) {
+      throw new Error('RUNTIME_RELEASE_SOURCE_SNAPSHOT_DIRTY');
+    }
+    return operation(snapshotRoot);
+  } finally {
+    const removed = runProcess('git', ['-C', sourceRoot, 'worktree', 'remove', '--force', snapshotRoot], {
+      timeoutMs: 60_000,
+      maxOutputBytes: 128 * 1024,
+    });
+    if (!removed.ok) {
+      rmSync(snapshotRoot, { recursive: true, force: true });
+    }
+    runProcess('git', ['-C', sourceRoot, 'worktree', 'prune'], { timeoutMs: 30_000, maxOutputBytes: 64 * 1024 });
+    rmSync(snapshotContainer, { recursive: true, force: true });
+  }
+}
+
 function sha256(path: string): string {
   return createHash('sha256').update(readFileSync(path)).digest('hex');
 }
@@ -164,6 +228,10 @@ function inspectMacOSRuntimeCodeSigning(executable: string): MacOSRuntimeCodeSig
   return parseMacOSRuntimeCodeSigning({ identifier, teamIdentifier, authority, designatedRequirement }, 'RUNTIME_RELEASE_MACOS_SIGNATURE_INVALID')!;
 }
 
+export function macOSRuntimeSigningMayRetryWithoutTimestamp(detail: string): boolean {
+  return /(?:^|\n).*timestamp service is not available\.?\s*$/im.test(detail);
+}
+
 function defaultSignMacOSRuntime(input: { executable: string; controllerHome: string }): MacOSRuntimeCodeSigning {
   const identities = runProcess('security', ['find-identity', '-v', '-p', 'codesigning'], { timeoutMs: 30_000, maxOutputBytes: 128 * 1024 });
   if (!identities.ok) throw new Error(`RUNTIME_RELEASE_MACOS_SIGNING_IDENTITY_LOOKUP_FAILED: ${identities.stderr || identities.stdout || identities.error}`.slice(0, 2_000));
@@ -186,9 +254,16 @@ function defaultSignMacOSRuntime(input: { executable: string; controllerHome: st
     selected = eligible[0];
   }
   if (expectedTeam && selected.teamIdentifier !== expectedTeam) throw new Error('RUNTIME_RELEASE_MACOS_SIGNING_TEAM_CHANGED');
-  const signed = runProcess('codesign', [
-    '--force', '--sign', selected.hash, '--identifier', FORGE_MACOS_RUNTIME_SIGNING_IDENTIFIER, '--options', 'runtime', input.executable,
-  ], { timeoutMs: 120_000, maxOutputBytes: 128 * 1024 });
+  const signingArgs = [
+    '--force', '--sign', selected.hash, '--identifier', FORGE_MACOS_RUNTIME_SIGNING_IDENTIFIER, '--options', 'runtime',
+  ];
+  let signed = runProcess('codesign', [...signingArgs, input.executable], { timeoutMs: 120_000, maxOutputBytes: 128 * 1024 });
+  if (!signed.ok) {
+    const detail = `${signed.stderr ?? ''}\n${signed.stdout ?? ''}\n${signed.error ?? ''}`;
+    if (macOSRuntimeSigningMayRetryWithoutTimestamp(detail)) {
+      signed = runProcess('codesign', [...signingArgs, '--timestamp=none', input.executable], { timeoutMs: 120_000, maxOutputBytes: 128 * 1024 });
+    }
+  }
   if (!signed.ok) throw new Error(`RUNTIME_RELEASE_MACOS_SIGNING_FAILED: ${signed.stderr || signed.stdout || signed.error}`.slice(0, 2_000));
   const inspected = inspectMacOSRuntimeCodeSigning(input.executable);
   if (inspected.teamIdentifier !== selected.teamIdentifier) throw new Error('RUNTIME_RELEASE_MACOS_SIGNING_TEAM_MISMATCH');
@@ -258,10 +333,12 @@ function parseCandidateStageReceipt(stdout: string): CandidateRuntimeStageReceip
 export function stageRuntimeReleaseFromCandidateSource(input: {
   controllerHome: string;
   sourceRoot: string;
+  dependencyRoot?: string;
   sourceRepositoryId: string;
 }, dependencies: CandidateRuntimeReleaseStagerDependencies = {}): StagedRuntimeRelease {
   const controllerHome = resolve(input.controllerHome);
   const sourceRoot = resolve(input.sourceRoot);
+  const dependencyRoot = resolve(input.dependencyRoot ?? input.sourceRoot);
   const sourceRepositoryId = input.sourceRepositoryId.trim();
   if (!sourceRepositoryId) throw new Error('RUNTIME_RELEASE_SOURCE_REPOSITORY_ID_REQUIRED');
   const expectedHead = gitText(sourceRoot, ['rev-parse', '--verify', 'HEAD']);
@@ -279,10 +356,11 @@ export function stageRuntimeReleaseFromCandidateSource(input: {
     request.scriptPath,
     '--controller-home', request.controllerHome,
     '--source-root', request.sourceRoot,
+    '--dependency-root', request.dependencyRoot,
     '--expected-head', request.expectedHead,
     '--source-repository-id', request.sourceRepositoryId,
   ], { cwd: request.sourceRoot, timeoutMs: 600_000, maxOutputBytes: 512 * 1024 }));
-  const executed = runCandidateStager({ bunExecutable, scriptPath, sourceRoot, controllerHome, expectedHead, sourceRepositoryId });
+  const executed = runCandidateStager({ bunExecutable, scriptPath, sourceRoot, dependencyRoot, controllerHome, expectedHead, sourceRepositoryId });
   if (!executed.ok) {
     throw new Error(`RUNTIME_RELEASE_CANDIDATE_STAGE_FAILED: ${executed.stderr || executed.stdout || executed.error}`.slice(0, 2_000));
   }
@@ -360,9 +438,12 @@ export function stageRuntimeReleaseFromCandidateSource(input: {
     releaseId: receipt.releaseId,
     artifactIdentity: receipt.artifactIdentity,
     runtimeBundleArtifactIdentity: manifest.runtimeBundleArtifactIdentity,
+    runtimeInterpreterArtifactIdentity: manifest.runtimeInterpreterArtifactIdentity,
     diagnosticArtifactIdentity: manifest.diagnosticArtifactIdentity,
+    connectorArtifactIdentity: manifest.connectorArtifactIdentity,
     browserNodeBridgeArtifactIdentity: manifest.browserNodeBridgeArtifactIdentity,
     browserHandoffArtifactIdentity: manifest.browserHandoffArtifactIdentity,
+    workflowSupervisorNativeHostArtifactIdentity: manifest.workflowSupervisorNativeHostArtifactIdentity,
     processRunnerArtifactIdentity: manifest.processRunnerArtifactIdentity,
     checkRunnerArtifactIdentity: manifest.checkRunnerArtifactIdentity,
     schedulerWorkerArtifactIdentity: manifest.schedulerWorkerArtifactIdentity,
@@ -396,6 +477,31 @@ function defaultCompileBinary(input: { sourceRoot: string; outputPath: string; e
   ], { cwd: input.sourceRoot, timeoutMs: 300_000, maxOutputBytes: 512 * 1024 });
 }
 
+function defaultMaterializeRuntimeInterpreter(input: { sourceRoot: string; outputPath: string }): { ok: boolean; stderr?: string; stdout?: string; error?: string } {
+  const configured = process.env.FORGE_BUN_BIN?.trim();
+  const bun = configured || resolveBunExecutable(process.execPath, process.env);
+  const probe = runProcess(bun, ['-e', 'process.stdout.write(process.execPath)'], {
+    cwd: input.sourceRoot,
+    timeoutMs: 15_000,
+    maxOutputBytes: 16 * 1024,
+  });
+  if (!probe.ok) return probe;
+  try {
+    const reported = probe.stdout.trim();
+    if (!reported) return { ok: false, error: 'Bun did not report process.execPath' };
+    const source = realpathSync(resolve(reported));
+    const status = lstatSync(source);
+    if (status.isSymbolicLink() || !status.isFile() || (status.mode & 0o111) === 0) {
+      return { ok: false, error: `resolved Bun interpreter is not a regular executable: ${source}` };
+    }
+    copyFileSync(source, input.outputPath);
+    chmodSync(input.outputPath, 0o700);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 function defaultBundleRuntimeScript(input: { sourceRoot: string; outputPath: string; entryPath: string }): { ok: boolean; stderr?: string; stdout?: string; error?: string } {
   const configured = process.env.FORGE_BUN_BIN?.trim();
   const bun = configured || resolveBunExecutable(process.execPath, process.env);
@@ -449,9 +555,11 @@ function defaultMaterializeCodeGraphRuntime(input: {
 export function stageRuntimeRelease(input: {
   controllerHome: string;
   sourceRoot: string;
+  dependencyRoot?: string;
   sourceRepositoryId?: string;
 }, dependencies: RuntimeReleaseMaterializerDependencies = {}): StagedRuntimeRelease {
   const sourceRoot = resolve(input.sourceRoot);
+  const dependencyRoot = resolve(input.dependencyRoot ?? input.sourceRoot);
   const sourceRepositoryId = input.sourceRepositoryId?.trim();
   if (input.sourceRepositoryId !== undefined && !sourceRepositoryId) throw new Error('RUNTIME_RELEASE_SOURCE_REPOSITORY_ID_INVALID');
   const sourceCommit = gitText(sourceRoot, ['rev-parse', '--verify', 'HEAD']);
@@ -472,6 +580,7 @@ export function stageRuntimeRelease(input: {
   mkdirSync(staging, { recursive: true, mode: 0o700 });
   try {
     const compileBinary = dependencies.compileBinary ?? defaultCompileBinary;
+    const platform = dependencies.platform ?? process.platform;
     const runtimeBundleEntrypoint = 'forge-runtime-bundle.js' as const;
     const runtimeBundlePath = join(staging, runtimeBundleEntrypoint);
     const runtimeBundle = (dependencies.bundleRuntime ?? defaultBundleRuntimeScript)({
@@ -485,6 +594,20 @@ export function stageRuntimeRelease(input: {
     chmodSync(runtimeBundlePath, 0o600);
     const runtimeBundleArtifactIdentity = `sha256:${sha256(runtimeBundlePath)}`;
 
+    const runtimeInterpreterEntrypoint = platform === 'win32'
+      ? 'forge-runtime-bun.exe' as const
+      : 'forge-runtime-bun' as const;
+    const runtimeInterpreterPath = join(staging, runtimeInterpreterEntrypoint);
+    const runtimeInterpreter = (dependencies.materializeRuntimeInterpreter ?? defaultMaterializeRuntimeInterpreter)({
+      sourceRoot,
+      outputPath: runtimeInterpreterPath,
+    });
+    if (!runtimeInterpreter.ok) {
+      throw new Error(`RUNTIME_RELEASE_INTERPRETER_BUILD_FAILED: ${runtimeInterpreter.stderr || runtimeInterpreter.stdout || runtimeInterpreter.error}`.slice(0, 2_000));
+    }
+    chmodSync(runtimeInterpreterPath, 0o700);
+    const runtimeInterpreterArtifactIdentity = `sha256:${sha256(runtimeInterpreterPath)}`;
+
     const executable = join(staging, 'forge-runtime');
     const compile = compileBinary({
       sourceRoot,
@@ -495,7 +618,6 @@ export function stageRuntimeRelease(input: {
       throw new Error(`RUNTIME_RELEASE_BUILD_FAILED: ${compile.stderr || compile.stdout || compile.error}`.slice(0, 2_000));
     }
     chmodSync(executable, 0o700);
-    const platform = dependencies.platform ?? process.platform;
     const macosCodeSigning = platform === 'darwin'
       ? (dependencies.signMacOSRuntime ?? defaultSignMacOSRuntime)({ executable, controllerHome: resolve(input.controllerHome) })
       : undefined;
@@ -517,6 +639,19 @@ export function stageRuntimeRelease(input: {
     chmodSync(diagnosticExecutable, 0o700);
     const diagnosticArtifactIdentity = `sha256:${sha256(diagnosticExecutable)}`;
 
+    const connectorEntrypoint = 'forge-mcp-gateway' as const;
+    const connectorPath = join(staging, connectorEntrypoint);
+    const connectorCompile = compileBinary({
+      sourceRoot,
+      outputPath: connectorPath,
+      entryPath: join(sourceRoot, 'src/cli/index.ts'),
+    });
+    if (!connectorCompile.ok) {
+      throw new Error(`RUNTIME_RELEASE_CONNECTOR_BUILD_FAILED: ${connectorCompile.stderr || connectorCompile.stdout || connectorCompile.error}`.slice(0, 2_000));
+    }
+    chmodSync(connectorPath, 0o700);
+    const connectorArtifactIdentity = `sha256:${sha256(connectorPath)}`;
+
     const browserNodeBridgeEntrypoint = 'browser-node-bridge-host.js' as const;
     const browserNodeBridgePath = join(staging, browserNodeBridgeEntrypoint);
     const bundleNodeHost = dependencies.bundleNodeHost ?? defaultBundleNodeScript;
@@ -544,6 +679,19 @@ export function stageRuntimeRelease(input: {
     chmodSync(browserHandoffPath, 0o700);
     const browserHandoffArtifactIdentity = `sha256:${sha256(browserHandoffPath)}`;
 
+    const workflowSupervisorNativeHostEntrypoint = 'forge-workflow-supervisor-native-host' as const;
+    const workflowSupervisorNativeHostPath = join(staging, workflowSupervisorNativeHostEntrypoint);
+    const workflowSupervisorNativeHostCompile = compileBinary({
+      sourceRoot,
+      outputPath: workflowSupervisorNativeHostPath,
+      entryPath: join(sourceRoot, 'supervisor', 'native-messaging', 'host.ts'),
+    });
+    if (!workflowSupervisorNativeHostCompile.ok) {
+      throw new Error(`RUNTIME_RELEASE_WORKFLOW_SUPERVISOR_NATIVE_HOST_BUILD_FAILED: ${workflowSupervisorNativeHostCompile.stderr || workflowSupervisorNativeHostCompile.stdout || workflowSupervisorNativeHostCompile.error}`.slice(0, 2_000));
+    }
+    chmodSync(workflowSupervisorNativeHostPath, 0o700);
+    const workflowSupervisorNativeHostArtifactIdentity = `sha256:${sha256(workflowSupervisorNativeHostPath)}`;
+
     const processRunnerEntrypoint = 'process-runner.js' as const;
     const processRunnerPath = join(staging, processRunnerEntrypoint);
     // Process Runner is part of the immutable execution surface and must not
@@ -576,6 +724,32 @@ export function stageRuntimeRelease(input: {
     chmodSync(checkRunnerPath, 0o700);
     const checkRunnerArtifactIdentity = `sha256:${sha256(checkRunnerPath)}`;
 
+    const typescriptNavigationEntrypoint = 'forge-typescript-navigation' as const;
+    const typescriptNavigationPath = join(staging, typescriptNavigationEntrypoint);
+    const typescriptNavigationCompile = compileBinary({
+      sourceRoot,
+      outputPath: typescriptNavigationPath,
+      entryPath: join(sourceRoot, 'adapters/mcp/runtime-gateway/typescript-navigation-sidecar.ts'),
+    });
+    if (!typescriptNavigationCompile.ok) {
+      throw new Error(`RUNTIME_RELEASE_TYPESCRIPT_NAVIGATION_BUILD_FAILED: ${typescriptNavigationCompile.stderr || typescriptNavigationCompile.stdout || typescriptNavigationCompile.error}`.slice(0, 2_000));
+    }
+    chmodSync(typescriptNavigationPath, 0o700);
+    const typescriptNavigationArtifactIdentity = `sha256:${sha256(typescriptNavigationPath)}`;
+
+    const contextPackEntrypoint = 'forge-context-pack' as const;
+    const contextPackPath = join(staging, contextPackEntrypoint);
+    const contextPackCompile = compileBinary({
+      sourceRoot,
+      outputPath: contextPackPath,
+      entryPath: join(sourceRoot, 'adapters/mcp/runtime-gateway/context-pack-sidecar.ts'),
+    });
+    if (!contextPackCompile.ok) {
+      throw new Error(`RUNTIME_RELEASE_CONTEXT_PACK_BUILD_FAILED: ${contextPackCompile.stderr || contextPackCompile.stdout || contextPackCompile.error}`.slice(0, 2_000));
+    }
+    chmodSync(contextPackPath, 0o700);
+    const contextPackArtifactIdentity = `sha256:${sha256(contextPackPath)}`;
+
     const schedulerWorkerEntrypoint = 'forge-scheduler-worker' as const;
     const schedulerWorkerPath = join(staging, schedulerWorkerEntrypoint);
     const schedulerWorkerCompile = compileBinary({
@@ -646,25 +820,17 @@ export function stageRuntimeRelease(input: {
     const codeGraphSidecarArtifactIdentity = `sha256:${sha256(codeGraphSidecarPath)}`;
     const codeGraphLibraryArtifactIdentity = `sha256:${sha256Directory(codeGraphLibraryPath)}`;
 
-    const controllerUiRoot = 'ui-dist' as const;
-    const sourceControllerUiPath = join(sourceRoot, 'src', 'cli', 'local-bridge', controllerUiRoot);
-    const sourceControllerUiJs = join(sourceControllerUiPath, 'app.js');
-    const sourceControllerUiCss = join(sourceControllerUiPath, 'app.css');
-    if (!existsSync(sourceControllerUiJs) || !existsSync(sourceControllerUiCss)) {
-      throw new Error(`RUNTIME_RELEASE_CONTROLLER_UI_SOURCE_MISSING: ${sourceControllerUiPath}`);
-    }
-    const controllerUiPath = join(staging, controllerUiRoot);
-    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.
+    // Keep the source-backed package projection during the Recovery migration.
+    // The active standalone Recovery release can predate the compiled Connector
+    // sidecar and still rebind the primary Connector through package/src/cli.
+    // Removing that surface here makes a candidate pass isolated Runtime
+    // canaries but fail the real cutover with missing CLI command modules. Once
+    // every supported Recovery release launches forge-mcp-gateway, this
+    // compatibility projection can be removed together with the fallback.
     const packageRoot = 'package' as const;
     const packagePath = join(staging, packageRoot);
-    const packageRecords = packageRuntimeFileIndex(sourceRoot);
-    stagePackageRuntimeSnapshot(sourceRoot, packagePath, packageRecords);
+    const packageRecords = packageRuntimeFileIndex(sourceRoot, dependencyRoot);
+    stagePackageRuntimeSnapshot(sourceRoot, packagePath, packageRecords, dependencyRoot);
     const packageArtifactIdentity = `sha256:${sha256Directory(packagePath)}`;
 
     const manifest = {
@@ -675,17 +841,27 @@ export function stageRuntimeRelease(input: {
       executionMode: 'standalone-binary',
       runtimeBundleEntrypoint,
       runtimeBundleArtifactIdentity,
+      runtimeInterpreterEntrypoint,
+      runtimeInterpreterArtifactIdentity,
       ...(normalizedMacOSCodeSigning ? { macosCodeSigning: normalizedMacOSCodeSigning } : {}),
       diagnosticEntrypoint: 'forge-cli',
       diagnosticArtifactIdentity,
+      connectorEntrypoint,
+      connectorArtifactIdentity,
       browserNodeBridgeEntrypoint,
       browserNodeBridgeArtifactIdentity,
       browserHandoffEntrypoint,
       browserHandoffArtifactIdentity,
+      workflowSupervisorNativeHostEntrypoint,
+      workflowSupervisorNativeHostArtifactIdentity,
       processRunnerEntrypoint,
       processRunnerArtifactIdentity,
       checkRunnerEntrypoint,
       checkRunnerArtifactIdentity,
+      typescriptNavigationEntrypoint,
+      typescriptNavigationArtifactIdentity,
+      contextPackEntrypoint,
+      contextPackArtifactIdentity,
       schedulerWorkerEntrypoint,
       schedulerWorkerArtifactIdentity,
       periodicCleanupEntrypoint,
@@ -702,11 +878,9 @@ export function stageRuntimeRelease(input: {
       codeGraphLibraryArtifactIdentity,
       packageRoot,
       packageArtifactIdentity,
-      controllerUiRoot,
-      controllerUiArtifactIdentity,
       arguments: [],
       configurationSchemaVersion: 1,
-      controllerHome: resolve(input.controllerHome),
+      deploymentScope: 'portable',
       databaseSchemaCompatibility: {
         minimum: CONTROL_PLANE_SCHEMA_VERSION,
         maximum: CONTROL_PLANE_SCHEMA_VERSION,
@@ -728,12 +902,17 @@ export function stageRuntimeRelease(input: {
       releaseId,
       artifactIdentity,
       runtimeBundleArtifactIdentity,
+      runtimeInterpreterArtifactIdentity,
       ...(normalizedMacOSCodeSigning ? { macosCodeSigning: normalizedMacOSCodeSigning } : {}),
       diagnosticArtifactIdentity,
+      connectorArtifactIdentity,
       browserNodeBridgeArtifactIdentity,
       browserHandoffArtifactIdentity,
+      workflowSupervisorNativeHostArtifactIdentity,
       processRunnerArtifactIdentity,
       checkRunnerArtifactIdentity,
+      typescriptNavigationArtifactIdentity,
+      contextPackArtifactIdentity,
       schedulerWorkerArtifactIdentity,
       periodicCleanupArtifactIdentity,
       pluginActionSidecarArtifactIdentity,
@@ -742,7 +921,6 @@ export function stageRuntimeRelease(input: {
       codeGraphSidecarArtifactIdentity,
       codeGraphLibraryArtifactIdentity,
       packageArtifactIdentity,
-      controllerUiArtifactIdentity,
       manifestSha256: createHash('sha256').update(`${JSON.stringify(manifest, null, 2)}\n`).digest('hex'),
       sourceCommit,
       ...(sourceRepositoryId ? { sourceRepositoryId } : {}),
@@ -753,6 +931,161 @@ export function stageRuntimeRelease(input: {
   }
 }
 
+
+interface RuntimeReleaseTreeInspection {
+  sha256: string;
+  bytes: number;
+  files: number;
+}
+
+function inspectRuntimeReleaseTree(releaseRootInput: string): RuntimeReleaseTreeInspection {
+  const requestedRoot = resolve(releaseRootInput);
+  if (!existsSync(requestedRoot)) throw new Error('RUNTIME_RELEASE_TREE_MISSING');
+  const rootStat = lstatSync(requestedRoot);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error('RUNTIME_RELEASE_TREE_ROOT_INVALID');
+  const root = realpathSync(requestedRoot);
+  const records: Array<{ path: string; mode: number; bytes: number; sha256: string }> = [];
+  const visit = (directory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = join(directory, entry.name);
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink()) throw new Error(`RUNTIME_RELEASE_TREE_SYMLINK_FORBIDDEN: ${relative(root, path)}`);
+      if (stat.isDirectory()) {
+        visit(path);
+        continue;
+      }
+      if (!stat.isFile()) throw new Error(`RUNTIME_RELEASE_TREE_SPECIAL_FILE_FORBIDDEN: ${relative(root, path)}`);
+      const bytes = readFileSync(path);
+      records.push({
+        path: relative(root, path).replaceAll('\\', '/'),
+        mode: stat.mode & 0o777,
+        bytes: bytes.length,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+      });
+    }
+  };
+  visit(root);
+  const digest = createHash('sha256').update(JSON.stringify(records)).digest('hex');
+  return {
+    sha256: digest,
+    bytes: records.reduce((sum, record) => sum + record.bytes, 0),
+    files: records.length,
+  };
+}
+
+function preserveRuntimeReleaseTreeModes(sourceRootInput: string, targetRootInput: string): void {
+  const sourceRoot = resolve(sourceRootInput);
+  const targetRoot = resolve(targetRootInput);
+  const visit = (sourceDirectory: string, targetDirectory: string): void => {
+    for (const entry of readdirSync(sourceDirectory, { withFileTypes: true })) {
+      const sourcePath = join(sourceDirectory, entry.name);
+      const targetPath = join(targetDirectory, entry.name);
+      const sourceStat = lstatSync(sourcePath);
+      if (sourceStat.isDirectory()) {
+        chmodSync(targetPath, sourceStat.mode & 0o777);
+        visit(sourcePath, targetPath);
+      } else if (sourceStat.isFile()) {
+        // fs.cpSync applies the process umask to copied files. The release
+        // tree digest includes permission bits, so restore the source mode
+        // before comparing the staged tree with its immutable source.
+        chmodSync(targetPath, sourceStat.mode & 0o777);
+      }
+    }
+  };
+  chmodSync(targetRoot, lstatSync(sourceRoot).mode & 0o777);
+  visit(sourceRoot, targetRoot);
+}
+
+export function runtimeReleaseTreeSha256(releaseRoot: string): string {
+  return inspectRuntimeReleaseTree(releaseRoot).sha256;
+}
+
+export interface PromotedPortableRuntimeRelease {
+  releaseId: string;
+  artifactIdentity: string;
+  manifestPath: string;
+  manifestSha256: string;
+  treeSha256: string;
+  sourceReleaseRoot: string;
+  targetReleaseRoot: string;
+  reusedExisting: boolean;
+}
+
+export function promotePortableRuntimeRelease(input: {
+  sourceManifestPath: string;
+  targetControllerHome: string;
+  expectedTreeSha256: string;
+}): PromotedPortableRuntimeRelease {
+  const sourceManifestPath = resolve(input.sourceManifestPath);
+  const sourceReleaseRoot = dirname(sourceManifestPath);
+  const targetControllerHome = resolve(input.targetControllerHome);
+  const manifest = loadRuntimeReleaseManifest(sourceManifestPath, targetControllerHome);
+  if (manifest.deploymentScope !== 'portable') throw new Error('RUNTIME_RELEASE_PROMOTION_REQUIRES_PORTABLE_ARTIFACT');
+  requireCompleteCompiledRuntimeReleaseManifest(manifest);
+  assertRuntimeReleaseExecutionSurface(sourceManifestPath, targetControllerHome);
+
+  const sourceTree = inspectRuntimeReleaseTree(sourceReleaseRoot);
+  if (sourceTree.sha256 !== input.expectedTreeSha256) throw new Error('RUNTIME_RELEASE_PROMOTION_SOURCE_TREE_MISMATCH');
+  const sourceManifestSha256 = createHash('sha256').update(readFileSync(sourceManifestPath)).digest('hex');
+
+  const releasesRoot = join(targetControllerHome, 'runtime', 'releases');
+  mkdirSync(releasesRoot, { recursive: true, mode: 0o700 });
+  const targetReleaseRoot = join(releasesRoot, manifest.releaseId);
+  const targetManifestPath = join(targetReleaseRoot, 'manifest.json');
+
+  const verifyTarget = (reusedExisting: boolean): PromotedPortableRuntimeRelease => {
+    const targetManifest = loadRuntimeReleaseManifest(targetManifestPath, targetControllerHome);
+    if (
+      targetManifest.deploymentScope !== 'portable'
+      || targetManifest.releaseId !== manifest.releaseId
+      || targetManifest.artifactIdentity !== manifest.artifactIdentity
+    ) throw new Error('RUNTIME_RELEASE_PROMOTION_TARGET_IDENTITY_MISMATCH');
+    requireCompleteCompiledRuntimeReleaseManifest(targetManifest);
+    assertRuntimeReleaseExecutionSurface(targetManifestPath, targetControllerHome);
+    const targetManifestSha256 = createHash('sha256').update(readFileSync(targetManifestPath)).digest('hex');
+    const targetTreeSha256 = runtimeReleaseTreeSha256(targetReleaseRoot);
+    if (targetManifestSha256 !== sourceManifestSha256 || targetTreeSha256 !== sourceTree.sha256) {
+      throw new Error('RUNTIME_RELEASE_PROMOTION_NOT_BYTE_IDENTICAL');
+    }
+    return {
+      releaseId: manifest.releaseId,
+      artifactIdentity: manifest.artifactIdentity,
+      manifestPath: targetManifestPath,
+      manifestSha256: targetManifestSha256,
+      treeSha256: targetTreeSha256,
+      sourceReleaseRoot,
+      targetReleaseRoot,
+      reusedExisting,
+    };
+  };
+
+  if (existsSync(targetReleaseRoot)) return verifyTarget(true);
+
+  assertStorageHeadroom(releasesRoot, {
+    operation: 'runtime_release_promotion',
+    requiredBytes: sourceTree.bytes,
+    reserveBytes: 64 * 1024 * 1024,
+  });
+  const staging = join(releasesRoot, `.${manifest.releaseId}.promote-${process.pid}-${randomUUID().slice(0, 8)}`);
+  try {
+    cpSync(sourceReleaseRoot, staging, {
+      recursive: true,
+      force: false,
+      errorOnExist: true,
+      preserveTimestamps: false,
+      dereference: false,
+    });
+    preserveRuntimeReleaseTreeModes(sourceReleaseRoot, staging);
+    const stagedTree = inspectRuntimeReleaseTree(staging);
+    if (stagedTree.sha256 !== sourceTree.sha256) throw new Error('RUNTIME_RELEASE_PROMOTION_STAGING_TREE_MISMATCH');
+    renameSync(staging, targetReleaseRoot);
+    return verifyTarget(false);
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
 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}`);
@@ -803,6 +1136,13 @@ export function assertRuntimeReleaseFiles(release: StagedRuntimeRelease, depende
   assertFileIdentity(runtimePath, release.artifactIdentity);
   assertComponentFile({ path: join(release.releasePath, 'forge-runtime-bundle.js'), identity: release.runtimeBundleArtifactIdentity, missingCode: 'RUNTIME_RELEASE_BUNDLE_MISSING' });
   const platform = dependencies.platform ?? process.platform;
+  const runtimeInterpreterEntrypoint = platform === 'win32' ? 'forge-runtime-bun.exe' : 'forge-runtime-bun';
+  assertComponentFile({
+    path: join(release.releasePath, runtimeInterpreterEntrypoint),
+    identity: release.runtimeInterpreterArtifactIdentity,
+    missingCode: 'RUNTIME_RELEASE_INTERPRETER_MISSING',
+    executable: true,
+  });
   if (platform === 'darwin' && release.macosCodeSigning) {
     const actual = (dependencies.inspectMacOSRuntime ?? inspectMacOSRuntimeCodeSigning)(runtimePath);
     if (actual.identifier !== release.macosCodeSigning.identifier
@@ -813,10 +1153,14 @@ export function assertRuntimeReleaseFiles(release: StagedRuntimeRelease, depende
     }
   }
   assertComponentFile({ path: join(release.releasePath, 'forge-cli'), identity: release.diagnosticArtifactIdentity, missingCode: 'RUNTIME_RELEASE_DIAGNOSTIC_ENTRYPOINT_MISSING', executable: true });
+  assertComponentFile({ path: join(release.releasePath, 'forge-mcp-gateway'), identity: release.connectorArtifactIdentity, missingCode: 'RUNTIME_RELEASE_CONNECTOR_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, 'forge-workflow-supervisor-native-host'), identity: release.workflowSupervisorNativeHostArtifactIdentity, missingCode: 'RUNTIME_RELEASE_WORKFLOW_SUPERVISOR_NATIVE_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-typescript-navigation'), identity: release.typescriptNavigationArtifactIdentity, missingCode: 'RUNTIME_RELEASE_TYPESCRIPT_NAVIGATION_MISSING', executable: true });
+  assertComponentFile({ path: join(release.releasePath, 'forge-context-pack'), identity: release.contextPackArtifactIdentity, missingCode: 'RUNTIME_RELEASE_CONTEXT_PACK_MISSING', executable: true });
   assertComponentFile({ path: join(release.releasePath, 'forge-scheduler-worker'), identity: release.schedulerWorkerArtifactIdentity, missingCode: 'RUNTIME_RELEASE_SCHEDULER_WORKER_MISSING', executable: true });
   assertComponentFile({ path: join(release.releasePath, 'forge-periodic-cleanup'), identity: release.periodicCleanupArtifactIdentity, missingCode: 'RUNTIME_RELEASE_PERIODIC_CLEANUP_MISSING', executable: true });
   assertComponentFile({ path: join(release.releasePath, 'forge-plugin-action-sidecar'), identity: release.pluginActionSidecarArtifactIdentity, missingCode: 'RUNTIME_RELEASE_PLUGIN_ACTION_SIDECAR_MISSING', executable: true });