@moretea-labs/forge 1.8.0 → 1.8.2

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

@@ -1,10 +1,13 @@
+import { writeAtomicTextFile } from '../shared/atomic-text-file';
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync } from 'fs';
 import { homedir } from 'os';
 import { basename, dirname, join, resolve } from 'path';
-import { loadMcpServiceLocalConfig } from '../../cli/mcp/auth';
+import { loadMcpServiceLocalConfig } from '../../../adapters/mcp/auth';
+import { runtimeAuthorityFreeEnvironment } from '../shared/process-environment';
 import type { PackageRuntimeRelease } from './package-runtime-release';
 import { createPlatformServiceManagerHost, platformLaunchdInstalledPath, type PlatformServiceManagerHost, type SystemdUserUnitInput } from '../platform/service-manager';
+import { forgeConnectorPersistentServiceLabel } from '../platform/service-inventory';
 
 export interface PackageConnectorServicePaths {
   label: string;
@@ -14,9 +17,13 @@ export interface PackageConnectorServicePaths {
   stdoutPath: string;
   stderrPath: string;
   authorityPath: string;
+  activeEntrypointPath: string;
 }
 
-export type PackageConnectorReleaseBinding = Pick<PackageRuntimeRelease, 'releaseId' | 'releaseRoot' | 'packageRoot'>;
+export type PackageConnectorReleaseBinding = Pick<PackageRuntimeRelease, 'releaseId' | 'releaseRoot' | 'packageRoot'> & {
+  connectorEntrypoint?: 'forge-mcp-gateway';
+  connectorArtifactIdentity?: string;
+};
 
 export interface PackageConnectorServiceAuthority {
   schemaVersion: 1;
@@ -27,6 +34,7 @@ export interface PackageConnectorServiceAuthority {
   mode: 'launchd' | 'systemd-user' | 'portable';
   persistent: boolean;
   servicePath?: string;
+  connectorArtifactIdentity?: string;
   installedAt: string;
 }
 
@@ -37,27 +45,30 @@ export interface PackageConnectorServiceResult {
   servicePath?: string;
   pid?: number;
   reused?: boolean;
+  rebound?: boolean;
   releaseId?: string;
   releaseRoot?: string;
 }
 
+export interface PackageConnectorCutoverDrainMarker {
+  schemaVersion: 1;
+  sessionId: string;
+  stableReleaseId: string;
+  connectorEndpoint: string;
+  connectorInstalledAt: string;
+  ownerPid: number;
+  armedAt: string;
+}
+
 export type PackageConnectorAuthMode = 'oauth' | 'none';
 
 function xml(value: string): string {
   return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
 }
 
-function atomicWrite(path: string, content: string, mode = 0o600): void {
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  const temporary = `${path}.${process.pid}.tmp`;
-  writeFileSync(temporary, content, { encoding: 'utf8', mode });
-  renameSync(temporary, path);
-}
-
 export function packageConnectorServicePaths(controllerHome: string, accountHome = process.env.HOME ?? homedir()): PackageConnectorServicePaths {
   const home = resolve(controllerHome);
-  const suffix = createHash('sha256').update(home).digest('hex').slice(0, 12);
-  const label = `com.moretea.forge.mcp-gateway.${suffix}`;
+  const label = forgeConnectorPersistentServiceLabel(home);
   const serviceRoot = join(home, 'runtime', 'connector-service');
   return {
     label,
@@ -67,9 +78,118 @@ export function packageConnectorServicePaths(controllerHome: string, accountHome
     stdoutPath: join(serviceRoot, 'logs', 'stdout.log'),
     stderrPath: join(serviceRoot, 'logs', 'stderr.log'),
     authorityPath: join(serviceRoot, 'authority.json'),
+    activeEntrypointPath: join(serviceRoot, 'active-forge-mcp-gateway'),
   };
 }
 
+const PACKAGE_CONNECTOR_CUTOVER_DRAIN_TTL_MS = 10 * 60_000;
+
+export function packageConnectorCutoverDrainMarkerPath(controllerHome: string): string {
+  return join(packageConnectorServicePaths(controllerHome).serviceRoot, 'cutover-draining.json');
+}
+
+function removePackageConnectorCutoverDrainMarker(controllerHome: string): void {
+  rmSync(packageConnectorCutoverDrainMarkerPath(controllerHome), { force: true });
+}
+
+function livePackageConnectorCutoverDrainMarker(
+  controllerHome: string,
+  now = Date.now(),
+): PackageConnectorCutoverDrainMarker | undefined {
+  const path = packageConnectorCutoverDrainMarkerPath(controllerHome);
+  if (!existsSync(path)) return undefined;
+  try {
+    const marker = JSON.parse(readFileSync(path, 'utf8')) as Partial<PackageConnectorCutoverDrainMarker>;
+    const armedAt = typeof marker.armedAt === 'string' ? Date.parse(marker.armedAt) : Number.NaN;
+    if (
+      marker.schemaVersion !== 1
+      || typeof marker.sessionId !== 'string'
+      || !marker.sessionId.trim()
+      || typeof marker.stableReleaseId !== 'string'
+      || !marker.stableReleaseId.trim()
+      || typeof marker.connectorEndpoint !== 'string'
+      || !marker.connectorEndpoint.trim()
+      || typeof marker.connectorInstalledAt !== 'string'
+      || !marker.connectorInstalledAt.trim()
+      || !Number.isInteger(marker.ownerPid)
+      || Number(marker.ownerPid) <= 0
+      || !Number.isFinite(armedAt)
+      || now - armedAt > PACKAGE_CONNECTOR_CUTOVER_DRAIN_TTL_MS
+    ) {
+      removePackageConnectorCutoverDrainMarker(controllerHome);
+      return undefined;
+    }
+    try {
+      process.kill(Number(marker.ownerPid), 0);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EPERM') {
+        removePackageConnectorCutoverDrainMarker(controllerHome);
+        return undefined;
+      }
+    }
+    return marker as PackageConnectorCutoverDrainMarker;
+  } catch {
+    removePackageConnectorCutoverDrainMarker(controllerHome);
+    return undefined;
+  }
+}
+
+export function armPackageConnectorCutoverDrain(input: {
+  controllerHome: string;
+  sessionId: string;
+  stableReleaseId: string;
+  connectorAuthority: PackageConnectorServiceAuthority;
+}): PackageConnectorCutoverDrainMarker {
+  if (input.connectorAuthority.releaseId !== input.stableReleaseId) {
+    throw new Error(`PACKAGE_CONNECTOR_CUTOVER_DRAIN_STABLE_MISMATCH: expected ${input.stableReleaseId}, observed ${input.connectorAuthority.releaseId}`);
+  }
+  const currentAuthority = readPackageConnectorServiceAuthority(input.controllerHome);
+  if (
+    !currentAuthority
+    || currentAuthority.releaseId !== input.connectorAuthority.releaseId
+    || currentAuthority.endpoint !== input.connectorAuthority.endpoint
+    || currentAuthority.installedAt !== input.connectorAuthority.installedAt
+  ) {
+    throw new Error('PACKAGE_CONNECTOR_CUTOVER_DRAIN_AUTHORITY_CHANGED');
+  }
+  const marker: PackageConnectorCutoverDrainMarker = {
+    schemaVersion: 1,
+    sessionId: input.sessionId,
+    stableReleaseId: input.stableReleaseId,
+    connectorEndpoint: input.connectorAuthority.endpoint,
+    connectorInstalledAt: input.connectorAuthority.installedAt,
+    ownerPid: process.pid,
+    armedAt: new Date().toISOString(),
+  };
+  const path = packageConnectorCutoverDrainMarkerPath(input.controllerHome);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeAtomicTextFile(path, `${JSON.stringify(marker, null, 2)}\n`, 0o600);
+  return marker;
+}
+
+export function clearPackageConnectorCutoverDrain(controllerHome: string): void {
+  removePackageConnectorCutoverDrainMarker(controllerHome);
+}
+
+export function packageConnectorCutoverDrainIsActive(
+  controllerHome: string,
+  connectorEndpoint: string,
+  now = Date.now(),
+): boolean {
+  const marker = livePackageConnectorCutoverDrainMarker(controllerHome, now);
+  if (!marker || marker.connectorEndpoint !== connectorEndpoint) return false;
+  let authority: PackageConnectorServiceAuthority | undefined;
+  try {
+    authority = readPackageConnectorServiceAuthority(controllerHome);
+  } catch {
+    return true;
+  }
+  if (!authority) return true;
+  return authority.releaseId === marker.stableReleaseId
+    && authority.endpoint === marker.connectorEndpoint
+    && authority.installedAt === marker.connectorInstalledAt;
+}
+
 export function readPackageConnectorServiceAuthority(controllerHome: string): PackageConnectorServiceAuthority | undefined {
   const path = packageConnectorServicePaths(controllerHome).authorityPath;
   if (!existsSync(path)) return undefined;
@@ -82,13 +202,15 @@ export function readPackageConnectorServiceAuthority(controllerHome: string): Pa
     || typeof parsed.packageRoot !== 'string'
     || !['launchd', 'systemd-user', 'portable'].includes(String(parsed.mode))
     || typeof parsed.persistent !== 'boolean'
+    || (parsed.connectorArtifactIdentity !== undefined && !/^sha256:[a-f0-9]{64}$/i.test(parsed.connectorArtifactIdentity))
     || typeof parsed.installedAt !== 'string'
   ) throw new Error('FORGE_PACKAGE_CONNECTOR_AUTHORITY_INVALID');
   return parsed as PackageConnectorServiceAuthority;
 }
 
-function writePackageConnectorServiceAuthority(input: { release: PackageConnectorReleaseBinding; controllerHome: string; result: PackageConnectorServiceResult }): void {
+function writePackageConnectorServiceAuthority(input: { release: PackageConnectorReleaseBinding; controllerHome: string; result: PackageConnectorServiceResult; installedAt?: string }): void {
   const paths = packageConnectorServicePaths(input.controllerHome);
+  const artifact = attestedCompiledConnector(input.release);
   const authority: PackageConnectorServiceAuthority = {
     schemaVersion: 1,
     endpoint: input.result.endpoint,
@@ -98,9 +220,10 @@ function writePackageConnectorServiceAuthority(input: { release: PackageConnecto
     mode: input.result.mode,
     persistent: input.result.persistent,
     ...(input.result.servicePath ? { servicePath: input.result.servicePath } : {}),
-    installedAt: new Date().toISOString(),
+    ...(artifact ? { connectorArtifactIdentity: artifact.identity } : {}),
+    installedAt: input.installedAt ?? new Date().toISOString(),
   };
-  atomicWrite(paths.authorityPath, `${JSON.stringify(authority, null, 2)}\n`);
+  writeAtomicTextFile(paths.authorityPath, `${JSON.stringify(authority, null, 2)}\n`);
 }
 
 export function packageConnectorEndpointStatusHealthy(status: number, authMode: PackageConnectorAuthMode = 'oauth'): boolean {
@@ -173,13 +296,73 @@ export function packageConnectorAuthMode(controllerHome: string): PackageConnect
     : 'oauth';
 }
 
+function attestedCompiledConnector(release: PackageConnectorReleaseBinding): { target: string; identity: string } | undefined {
+  const entrypoint = release.connectorEntrypoint;
+  const identity = release.connectorArtifactIdentity?.trim();
+  if (!entrypoint && !identity) return undefined;
+  if (entrypoint !== 'forge-mcp-gateway' || !identity || !/^sha256:[a-f0-9]{64}$/i.test(identity)) {
+    throw new Error('FORGE_PACKAGE_CONNECTOR_ARTIFACT_ATTESTATION_INVALID');
+  }
+  const target = resolve(release.releaseRoot, entrypoint);
+  const root = resolve(release.releaseRoot);
+  if (dirname(target) !== root || !existsSync(target)) throw new Error('FORGE_PACKAGE_CONNECTOR_ARTIFACT_MISSING');
+  const status = lstatSync(target);
+  if (!status.isFile() || status.isSymbolicLink()) throw new Error('FORGE_PACKAGE_CONNECTOR_ARTIFACT_INVALID');
+  const actual = `sha256:${createHash('sha256').update(readFileSync(target)).digest('hex')}`;
+  if (actual !== identity.toLowerCase()) throw new Error('FORGE_PACKAGE_CONNECTOR_ARTIFACT_IDENTITY_MISMATCH');
+  return { target, identity: actual };
+}
+
+function stableConnectorEntrypointMatches(path: string, target: string): boolean {
+  try {
+    const current = lstatSync(path);
+    const desired = statSync(target);
+    if (!current.isFile() || current.isSymbolicLink() || !desired.isFile()) return false;
+    if (current.size !== desired.size || (current.mode & 0o777) !== (desired.mode & 0o777)) return false;
+    return readFileSync(path).equals(readFileSync(target));
+  } catch {
+    return false;
+  }
+}
+
+export function syncPackageConnectorActiveEntrypoint(input: { release: PackageConnectorReleaseBinding; controllerHome: string; accountHome?: string }): { path: string; target?: string; artifactIdentity?: string; changed: boolean } {
+  const paths = packageConnectorServicePaths(input.controllerHome, input.accountHome);
+  const artifact = attestedCompiledConnector(input.release);
+  if (!artifact) return { path: paths.activeEntrypointPath, changed: false };
+  if (stableConnectorEntrypointMatches(paths.activeEntrypointPath, artifact.target)) {
+    return { path: paths.activeEntrypointPath, target: artifact.target, artifactIdentity: artifact.identity, changed: false };
+  }
+  mkdirSync(dirname(paths.activeEntrypointPath), { recursive: true, mode: 0o700 });
+  const temporary = `${paths.activeEntrypointPath}.${process.pid}.tmp`;
+  rmSync(temporary, { force: true, recursive: true });
+  try {
+    copyFileSync(artifact.target, temporary);
+    chmodSync(temporary, statSync(artifact.target).mode & 0o777);
+    renameSync(temporary, paths.activeEntrypointPath);
+  } finally {
+    rmSync(temporary, { force: true, recursive: true });
+  }
+  if (!stableConnectorEntrypointMatches(paths.activeEntrypointPath, artifact.target)) {
+    throw new Error('FORGE_PACKAGE_CONNECTOR_STABLE_ENTRYPOINT_MIRROR_FAILED');
+  }
+  return { path: paths.activeEntrypointPath, target: artifact.target, artifactIdentity: artifact.identity, changed: true };
+}
+
 export function packageConnectorLaunchSpec(input: { release: PackageConnectorReleaseBinding; controllerHome: string; endpoint: string; executable?: string }): { executable: string; args: string[]; environment: Record<string, string>; port: number; authMode: PackageConnectorAuthMode } {
   const parsed = new URL(input.endpoint);
   const port = Number(parsed.port);
   if (parsed.protocol !== 'http:' || parsed.hostname !== '127.0.0.1' || parsed.pathname !== '/mcp' || !Number.isInteger(port) || port < 1 || port > 65_535) {
     throw new Error('FORGE_PACKAGE_CONNECTOR_ENDPOINT_INVALID');
   }
-  const executable = resolve(input.executable ?? process.env.FORGE_CONNECTOR_EXECUTABLE ?? process.execPath);
+  const attestedConnector = attestedCompiledConnector(input.release);
+  const legacyCompiledConnector = join(resolve(input.release.releaseRoot), 'forge-mcp-gateway');
+  const hasLegacyCompiledConnector = !attestedConnector && existsSync(legacyCompiledConnector);
+  const hasCompiledConnector = Boolean(attestedConnector) || hasLegacyCompiledConnector;
+  const executable = resolve(attestedConnector
+    ? packageConnectorServicePaths(input.controllerHome).activeEntrypointPath
+    : hasLegacyCompiledConnector
+      ? legacyCompiledConnector
+      : input.executable ?? process.env.FORGE_CONNECTOR_EXECUTABLE ?? process.execPath);
   if (/^forge-recovery-(?:gateway|watchdog)$/i.test(basename(executable))) {
     throw new Error('FORGE_PACKAGE_CONNECTOR_EXECUTABLE_INVALID');
   }
@@ -201,7 +384,7 @@ export function packageConnectorLaunchSpec(input: { release: PackageConnectorRel
   ];
   return {
     executable,
-    args: isBun ? [cliEntry, ...cliArgs] : ['--loader', nodeLoader, cliEntry, ...cliArgs],
+    args: hasCompiledConnector ? cliArgs : isBun ? [cliEntry, ...cliArgs] : ['--loader', nodeLoader, cliEntry, ...cliArgs],
     environment: {
       FORGE_CONTROLLER_HOME: resolve(input.controllerHome),
       FORGE_CONTROLLER_LIFECYCLE_OWNER: '1',
@@ -253,9 +436,14 @@ export function packageConnectorServiceMatchesRelease(input: {
   executable?: string;
 }): boolean {
   try {
-    if (
-      input.authority.endpoint !== input.endpoint
-      || input.authority.releaseId !== input.release.releaseId
+    if (input.authority.endpoint !== input.endpoint) return false;
+    const artifact = attestedCompiledConnector(input.release);
+    if (artifact) {
+      const paths = packageConnectorServicePaths(input.controllerHome, input.env?.HOME);
+      if (input.authority.connectorArtifactIdentity !== artifact.identity) return false;
+      if (!stableConnectorEntrypointMatches(paths.activeEntrypointPath, artifact.target)) return false;
+    } else if (
+      input.authority.releaseId !== input.release.releaseId
       || resolve(input.authority.releaseRoot) !== resolve(input.release.releaseRoot)
       || resolve(input.authority.packageRoot) !== resolve(input.release.packageRoot)
     ) return false;
@@ -295,11 +483,7 @@ function installSystemd(paths: PackageConnectorServicePaths, launch: ReturnType<
 function startPortable(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv, host: PlatformServiceManagerHost): number {
   // A connector is not the Canonical Runtime writer. Never let a transient
   // installer/worker write claim escape into this long-lived process.
-  const childEnv = { ...env };
-  for (const key of [
-    'FORGE_RUNTIME_INSTANCE_ID', 'FORGE_RUNTIME_OWNER_PID', 'FORGE_RELEASE_AUTHORITY_REVISION',
-    'FORGE_RELEASE_FENCING_TOKEN', 'FORGE_RELEASE_ID', 'FORGE_ARTIFACT_IDENTITY', 'FORGE_WORKER_PROTOCOL_VERSION',
-  ]) delete childEnv[key];
+  const childEnv = runtimeAuthorityFreeEnvironment(env);
   return host.startDetached({
     executable: launch.executable,
     args: launch.args,
@@ -313,6 +497,7 @@ function startPortable(paths: PackageConnectorServicePaths, launch: ReturnType<t
 export async function installPackageConnectorService(input: { release: PackageConnectorReleaseBinding; controllerHome: string; endpoint: string; executable?: string; platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; forcePortable?: boolean; probeEndpoint?: (endpoint: string) => Promise<boolean> }): Promise<PackageConnectorServiceResult> {
   const paths = packageConnectorServicePaths(input.controllerHome, input.env?.HOME);
   mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
+  syncPackageConnectorActiveEntrypoint({ release: input.release, controllerHome: input.controllerHome, accountHome: input.env?.HOME });
   const launch = packageConnectorLaunchSpec({
     release: input.release,
     controllerHome: input.controllerHome,
@@ -330,7 +515,7 @@ export async function installPackageConnectorService(input: { release: PackageCo
       port: launch.port,
       requiredArguments: ['mcp', 'serve', '--auth', launch.authMode],
     });
-    atomicWrite(paths.sourcePlistPath, renderPackageConnectorLaunchAgent({ paths, launch }), 0o600);
+    writeAtomicTextFile(paths.sourcePlistPath, renderPackageConnectorLaunchAgent({ paths, launch }), 0o600);
     serviceHost.installLaunchd(paths.sourcePlistPath, paths.label);
     const result = await serviceHost.bootstrapLaunchd({ label: paths.label, plistPath: paths.installedPlistPath });
     if (!result.ok) throw new Error(`FORGE_PACKAGE_CONNECTOR_LAUNCHD_INSTALL_FAILED: ${result.diagnostics.join('; ')}`);
@@ -393,15 +578,28 @@ export async function ensurePackageConnectorService(input: {
       })
       && await (input.probeEndpoint ?? defaultConnectorEndpointProbe)(input.endpoint)
     ) {
-      return {
+      const rebound = authority.releaseId !== input.release.releaseId
+        || resolve(authority.releaseRoot) !== resolve(input.release.releaseRoot)
+        || resolve(authority.packageRoot) !== resolve(input.release.packageRoot);
+      const reused: PackageConnectorServiceResult = {
         endpoint: authority.endpoint,
         mode: authority.mode,
         persistent: true,
         ...(authority.servicePath ? { servicePath: authority.servicePath } : {}),
         reused: true,
-        releaseId: authority.releaseId,
-        releaseRoot: authority.releaseRoot,
+        ...(rebound ? { rebound: true } : {}),
+        releaseId: input.release.releaseId,
+        releaseRoot: input.release.releaseRoot,
       };
+      if (rebound) {
+        writePackageConnectorServiceAuthority({
+          release: input.release,
+          controllerHome: input.controllerHome,
+          result: reused,
+          installedAt: authority.installedAt,
+        });
+      }
+      return reused;
     }
   }
   return installPackageConnectorService(input);

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

@@ -1,3 +1,4 @@
+import { writeAtomicTextFile } from '../shared/atomic-text-file';
 import { createHash, randomUUID } from 'crypto';
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
 import { dirname, join, relative, resolve } from 'path';
@@ -35,22 +36,38 @@ export interface PackageRuntimeRelease {
 // TypeScript entrypoints import both `src/` and the top-level modular-monolith
 // roots at runtime, so retaining only `src/` creates a release that passes
 // staging but cannot start after the installed package moves or disappears.
-const PACKAGE_RUNTIME_ROOTS = ['src', 'adapters', 'packages', 'bin', 'assets', 'scripts', 'node_modules'] as const;
+const PACKAGE_RUNTIME_ROOTS = ['src', 'adapters', 'packages', 'supervisor', 'bin', 'assets', 'scripts', 'node_modules'] as const;
 const PACKAGE_RUNTIME_FILES = ['package.json'] as const;
+// Compiled releases execute only compiled/bundled artifacts. Keep a tiny package
+// projection for browser-extension installation plus two legacy Recovery
+// recognition sentinels; neither sentinel is executed when the compiled
+// Connector sidecar is present.
+const COMPILED_RUNTIME_PACKAGE_ROOTS = ['adapters/computer/chrome-extension'] as const;
+const COMPILED_RUNTIME_PACKAGE_FILES = [
+  'package.json',
+  'src/cli/index.ts',
+  'src/runtime/shared/node-ts-loader.mjs',
+] as const;
 const PACKAGE_RUNTIME_STAGING_RESERVE_BYTES = 256 * 1024 * 1024;
 
-function sha256(value: Buffer | string): string {
-  return createHash('sha256').update(value).digest('hex');
+function isNonRuntimePackageHelper(path: string): boolean {
+  if (path.startsWith('scripts/benchmark-')) return true;
+  if (path.startsWith('scripts/check-release-')) return true;
+  if (path.startsWith('scripts/public-release')) return true;
+  return path === 'scripts/route-nl-vs-ts-eval.ts'
+    || path === 'scripts/check-npm-release.sh'
+    || path === 'scripts/check-public-release-surface.sh'
+    || path === 'scripts/check-tarball-install-smoke.sh'
+    || path === 'scripts/publish-release-tarball.sh'
+    || path === 'scripts/stage-runtime-release.ts'
+    || path === 'scripts/package-source-archive.sh';
 }
 
-function atomicWrite(path: string, content: string, mode = 0o600): void {
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
-  writeFileSync(temporary, content, { encoding: 'utf8', mode });
-  renameSync(temporary, path);
+function sha256(value: Buffer | string): string {
+  return createHash('sha256').update(value).digest('hex');
 }
 
-function walkRegularFiles(root: string, current: string, output: string[]): void {
+function walkRegularFiles(root: string, current: string, output: string[], prefix = ''): void {
   if (!existsSync(current)) return;
   const stat = lstatSync(current);
   // Package managers such as Bun can materialize dependency files as
@@ -59,38 +76,89 @@ function walkRegularFiles(root: string, current: string, output: string[]): void
   // regular files beneath its own immutable package root.
   if (stat.isSymbolicLink()) {
     const target = statSync(current);
-    if (target.isFile()) output.push(relative(root, current).split('\\').join('/'));
+    if (target.isFile()) {
+      const relativePath = relative(root, current).split('\\').join('/');
+      output.push(prefix ? `${prefix}/${relativePath}` : relativePath);
+    }
     return;
   }
   if (stat.isFile()) {
-    output.push(relative(root, current).split('\\').join('/'));
+    const relativePath = relative(root, current).split('\\').join('/');
+    output.push(prefix ? `${prefix}/${relativePath}` : relativePath);
     return;
   }
   if (!stat.isDirectory()) return;
-  for (const entry of readdirSync(current).sort()) walkRegularFiles(root, join(current, entry), output);
+  for (const entry of readdirSync(current).sort()) walkRegularFiles(root, join(current, entry), output, prefix);
+}
+
+function packageSourcePath(packageRoot: string, path: string, dependencyRoot = packageRoot): string {
+  return path === 'node_modules' || path.startsWith('node_modules/')
+    ? join(resolve(dependencyRoot), path)
+    : join(resolve(packageRoot), path);
 }
 
-export function packageRuntimeFileIndex(packageRoot = packageRuntimeSourceRoot()): PackageRuntimeFileRecord[] {
+function packageFileIndex(
+  packageRoot: string,
+  roots: readonly string[],
+  files: readonly string[],
+  dependencyRoot = packageRoot,
+): PackageRuntimeFileRecord[] {
   const root = resolve(packageRoot);
+  const dependencies = resolve(dependencyRoot);
   const paths: string[] = [];
-  for (const directory of PACKAGE_RUNTIME_ROOTS) walkRegularFiles(root, join(root, directory), paths);
-  for (const file of PACKAGE_RUNTIME_FILES) walkRegularFiles(root, join(root, file), paths);
-  const unique = [...new Set(paths)].sort();
-  if (!unique.includes('package.json') || !unique.some((path) => path === 'bin/forge-runtime.mjs')) {
-    throw new Error(`PACKAGE_RUNTIME_SURFACE_INCOMPLETE: ${root}`);
+  for (const directory of roots) {
+    if (directory === 'node_modules' && dependencies !== root) {
+      const dependencyNodeModules = join(dependencies, 'node_modules');
+      walkRegularFiles(dependencyNodeModules, dependencyNodeModules, paths, 'node_modules');
+    } else {
+      walkRegularFiles(root, join(root, directory), paths);
+    }
   }
-  return unique.map((path) => {
-    const bytes = readFileSync(join(root, path));
+  for (const file of files) walkRegularFiles(root, join(root, file), paths);
+  return [...new Set(paths)].sort().map((path) => {
+    const bytes = readFileSync(packageSourcePath(root, path, dependencies));
     return { path, sha256: sha256(bytes), bytes: bytes.length };
   });
 }
 
+export function packageRuntimeFileIndex(packageRoot = packageRuntimeSourceRoot(), dependencyRoot = packageRoot): PackageRuntimeFileRecord[] {
+  const root = resolve(packageRoot);
+  const records = packageFileIndex(root, PACKAGE_RUNTIME_ROOTS, PACKAGE_RUNTIME_FILES, dependencyRoot)
+    .filter((record) => !isNonRuntimePackageHelper(record.path));
+  const paths = new Set(records.map((record) => record.path));
+  if (!paths.has('package.json') || !paths.has('bin/forge-runtime.mjs')) {
+    throw new Error(`PACKAGE_RUNTIME_SURFACE_INCOMPLETE: ${root}`);
+  }
+  return records;
+}
+
+export function compiledRuntimePackageFileIndex(packageRoot = packageRuntimeSourceRoot()): PackageRuntimeFileRecord[] {
+  const root = resolve(packageRoot);
+  const records = packageFileIndex(root, COMPILED_RUNTIME_PACKAGE_ROOTS, COMPILED_RUNTIME_PACKAGE_FILES);
+  const paths = new Set(records.map((record) => record.path));
+  for (const required of COMPILED_RUNTIME_PACKAGE_FILES) {
+    if (!paths.has(required)) throw new Error(`COMPILED_RUNTIME_PACKAGE_SURFACE_INCOMPLETE: ${required}`);
+  }
+  if (![...paths].some((path) => path.startsWith('adapters/computer/chrome-extension/'))) {
+    throw new Error('COMPILED_RUNTIME_PACKAGE_SURFACE_INCOMPLETE: adapters/computer/chrome-extension');
+  }
+  return records;
+}
+
 export function packageRuntimeFingerprint(records: PackageRuntimeFileRecord[]): string {
   const hash = createHash('sha256');
   for (const record of records) hash.update(record.path).update('\0').update(record.sha256).update('\0').update(String(record.bytes)).update('\n');
   return hash.digest('hex');
 }
 
+function packageRuntimeArtifactIdentity(root: string, records: PackageRuntimeFileRecord[]): string {
+  const hash = createHash('sha256');
+  for (const record of records) {
+    hash.update(record.path).update('\0').update(readFileSync(join(root, record.path))).update('\0');
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
 function assertPackageRuntimeSnapshot(snapshotRoot: string, records: PackageRuntimeFileRecord[]): void {
   if (!existsSync(snapshotRoot)) throw new Error('PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: package snapshot is missing');
   const rootStat = lstatSync(snapshotRoot);
@@ -111,10 +179,15 @@ function assertPackageRuntimeSnapshot(snapshotRoot: string, records: PackageRunt
   }
 }
 
-export function stagePackageRuntimeSnapshot(sourceRoot: string, snapshotRoot: string, records: PackageRuntimeFileRecord[]): void {
+export function stagePackageRuntimeSnapshot(
+  sourceRoot: string,
+  snapshotRoot: string,
+  records: PackageRuntimeFileRecord[],
+  dependencyRoot = sourceRoot,
+): void {
   mkdirSync(snapshotRoot, { recursive: false, mode: 0o700 });
   for (const record of records) {
-    const source = join(sourceRoot, record.path);
+    const source = packageSourcePath(sourceRoot, record.path, dependencyRoot);
     const link = lstatSync(source);
     const stat = link.isSymbolicLink() ? statSync(source) : link;
     if (!stat.isFile()) throw new Error(`PACKAGE_RUNTIME_SOURCE_CHANGED_DURING_STAGE: ${record.path}`);
@@ -154,7 +227,12 @@ function launcherSource(input: {
     + `import { dirname, join } from 'node:path';\n`
     + `import { fileURLToPath } from 'node:url';\n`
     + `import { spawn } from 'node:child_process';\n`
-    + `const releaseRoot=dirname(fileURLToPath(import.meta.url));\n`
+    // macOS runs a byte-for-byte mirror of this launcher from its fixed,
+    // TCC-stable service path. The mirrored file is not its immutable release
+    // directory, so use the launch contract's attested release binding when it
+    // is present. Direct execution from the immutable release still derives
+    // the same root from the entrypoint location.
+    + `const releaseRoot=process.env.FORGE_RELEASE_PATH?.trim()||dirname(fileURLToPath(import.meta.url));\n`
     + `const packageRoot=join(releaseRoot,'package');\n`
     + `const indexPath=join(releaseRoot,'package-files.json');\n`
     + `const expectedIndex=${JSON.stringify(input.indexSha256)};\n`
@@ -224,7 +302,12 @@ function assertImmutablePackageRuntimeRelease(input: {
     && manifest.checkRunnerArtifactIdentity === expected.checkRunnerArtifactIdentity
     && JSON.stringify(manifest.arguments ?? []) === JSON.stringify(expected.arguments ?? [])
     && manifest.configurationSchemaVersion === expected.configurationSchemaVersion
-    && resolve(manifest.controllerHome) === resolve(expected.controllerHome)
+    && manifest.deploymentScope === expected.deploymentScope
+    && (manifest.deploymentScope === 'portable'
+      ? expected.deploymentScope === 'portable'
+      : typeof manifest.controllerHome === 'string'
+        && typeof expected.controllerHome === 'string'
+        && resolve(manifest.controllerHome) === resolve(expected.controllerHome))
     && JSON.stringify(manifest.databaseSchemaCompatibility) === JSON.stringify(expected.databaseSchemaCompatibility)
     && manifest.workerProtocolVersion === expected.workerProtocolVersion
     && manifest.releaseRevision === expected.releaseRevision
@@ -232,6 +315,7 @@ function assertImmutablePackageRuntimeRelease(input: {
     && typeof manifest.createdAt === 'string'
     && Number.isFinite(Date.parse(manifest.createdAt));
   if (!compatible) throw new Error('PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: manifest identity changed');
+  if (!expected.controllerHome) throw new Error('PACKAGE_RUNTIME_RELEASE_IMMUTABILITY_VIOLATION: package release must remain ControllerHome-bound');
   assertRuntimeReleaseExecutionSurface(input.manifestPath, expected.controllerHome);
 }
 
@@ -245,8 +329,9 @@ export function materializePackageRuntimeRelease(input: {
   const version = packageVersion(sourcePackageRoot);
   const records = packageRuntimeFileIndex(sourcePackageRoot);
   const fingerprint = packageRuntimeFingerprint(records);
+  const packageArtifactIdentity = packageRuntimeArtifactIdentity(sourcePackageRoot, records);
   const safeVersion = version.replace(/[^A-Za-z0-9._-]+/g, '-');
-  const launcherBinding = sha256(`${resolve(process.execPath)}\0package-launcher-v5`);
+  const launcherBinding = sha256(`${resolve(process.execPath)}\0package-launcher-v9`);
   const releaseId = `package-${safeVersion}-${fingerprint.slice(0, 16)}-${launcherBinding.slice(0, 12)}`;
   const releasesRoot = join(controllerHome, 'runtime', 'releases');
   const releaseRoot = join(releasesRoot, releaseId);
@@ -280,6 +365,8 @@ export function materializePackageRuntimeRelease(input: {
     processRunnerArtifactIdentity,
     checkRunnerEntrypoint,
     checkRunnerArtifactIdentity,
+    packageRoot: 'package',
+    packageArtifactIdentity,
     arguments: [],
     configurationSchemaVersion: 1,
     controllerHome,
@@ -314,16 +401,16 @@ export function materializePackageRuntimeRelease(input: {
     try {
       mkdirSync(stagingRoot, { recursive: false, mode: 0o700 });
       stagePackageRuntimeSnapshot(sourcePackageRoot, join(stagingRoot, 'package'), records);
-      atomicWrite(join(stagingRoot, 'package-files.json'), indexJson);
-      atomicWrite(join(stagingRoot, 'forge-runtime'), launcher, 0o700);
+      writeAtomicTextFile(join(stagingRoot, 'package-files.json'), indexJson);
+      writeAtomicTextFile(join(stagingRoot, 'forge-runtime'), launcher, 0o700);
       chmodSync(join(stagingRoot, 'forge-runtime'), 0o700);
-      atomicWrite(join(stagingRoot, processRunnerEntrypoint), processRunnerLauncher, 0o700);
+      writeAtomicTextFile(join(stagingRoot, processRunnerEntrypoint), processRunnerLauncher, 0o700);
       chmodSync(join(stagingRoot, processRunnerEntrypoint), 0o700);
-      atomicWrite(join(stagingRoot, checkRunnerEntrypoint), checkRunnerLauncher, 0o700);
+      writeAtomicTextFile(join(stagingRoot, checkRunnerEntrypoint), checkRunnerLauncher, 0o700);
       chmodSync(join(stagingRoot, checkRunnerEntrypoint), 0o700);
       const manifest: RuntimeReleaseManifest = { ...expectedManifest, createdAt: new Date().toISOString() };
       const stagingManifestPath = join(stagingRoot, 'manifest.json');
-      atomicWrite(stagingManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+      writeAtomicTextFile(stagingManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
       // A failed execution surface is still a staging failure. Do not promote an
       // immutable release directory until both manifest-owned runners execute
       // their bounded no-op canary successfully.