@moretea-labs/forge 1.6.0 → 1.7.0

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;

package/src/runtime/root/service.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'crypto';
-import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'fs';
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { dirname, isAbsolute, join, relative, resolve } from 'path';
 import { resolveControllerHome } from '../../cli/repositories/controller-home';
@@ -7,6 +7,7 @@ import {
   bootstrapLaunchAgentWithRetryV2,
   bootoutLaunchAgentWithRetryV2,
   installLaunchAgent,
+  retireConflictingForgeLaunchAgents,
 } from '../../cli/controller/launch-agents';
 
 export interface ForgeRuntimeServiceConfig {
@@ -209,54 +210,118 @@ export function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLa
   };
 }
 
-function atomicSymlink(path: string, target: string): void {
+function pathEntryExists(path: string): boolean {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function stableRuntimeEntrypointMatches(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;
+  }
+}
+
+/**
+ * Keep the Runtime process at one physical path on macOS. TCC resolves symlinks
+ * before assigning the responsible process, so a stable symlink to an immutable
+ * release still creates a new permission principal for every release directory.
+ * The executable is Developer-ID signed with a stable designated requirement;
+ * atomically mirroring those exact signed bytes to this fixed service path keeps
+ * TCC identity stable while release assets/rollback remain bound by manifest/env.
+ */
+function atomicMirrorRuntimeEntrypoint(path: string, target: string): void {
   mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
-  rmSync(temporary, { force: true });
-  symlinkSync(target, temporary);
-  renameSync(temporary, path);
+  rmSync(temporary, { force: true, recursive: true });
+  try {
+    copyFileSync(target, temporary);
+    chmodSync(temporary, statSync(target).mode & 0o777);
+    try {
+      if (lstatSync(path).isDirectory()) rmSync(path, { force: true, recursive: true });
+    } catch {}
+    renameSync(temporary, path);
+  } finally {
+    rmSync(temporary, { force: true, recursive: true });
+  }
 }
 
 export function syncForgeRuntimeActiveEntrypoint(controllerHome: string): { path: string; target?: string; changed: boolean } {
   const paths = forgeRuntimeServicePaths(controllerHome);
   const target = activeRuntimeEntrypoint(controllerHome);
-  if (!target) return { path: paths.activeEntrypointPath, changed: false };
-  let current: string | undefined;
-  try {
-    if (lstatSync(paths.activeEntrypointPath).isSymbolicLink()) current = resolve(dirname(paths.activeEntrypointPath), readlinkSync(paths.activeEntrypointPath));
-  } catch {}
-  if (current === target) return { path: paths.activeEntrypointPath, target, changed: false };
-  rmSync(paths.activeEntrypointPath, { force: true, recursive: true });
-  atomicSymlink(paths.activeEntrypointPath, target);
+  if (!target) {
+    const existed = pathEntryExists(paths.activeEntrypointPath);
+    if (existed) rmSync(paths.activeEntrypointPath, { force: true, recursive: true });
+    return { path: paths.activeEntrypointPath, changed: existed };
+  }
+  if (stableRuntimeEntrypointMatches(paths.activeEntrypointPath, target)) {
+    return { path: paths.activeEntrypointPath, target, changed: false };
+  }
+  atomicMirrorRuntimeEntrypoint(paths.activeEntrypointPath, target);
+  if (!stableRuntimeEntrypointMatches(paths.activeEntrypointPath, target)) {
+    throw new Error('FORGE_RUNTIME_STABLE_ENTRYPOINT_MIRROR_FAILED');
+  }
   return { path: paths.activeEntrypointPath, target, changed: true };
 }
 
-export function ensureForgeRuntimeLaunchAgentContract(
-  input: { controllerHome: string; bootstrapNodeExecutable?: string; bootstrapRunnerPath?: string; installUserLaunchAgent?: boolean },
-): { paths: ForgeRuntimeServicePaths; mode: 'release' | 'bootstrap'; changed: boolean } {
+function desiredForgeRuntimeLaunchAgentContract(
+  input: { controllerHome: string; bootstrapNodeExecutable?: string; bootstrapRunnerPath?: string },
+): { paths: ForgeRuntimeServicePaths; mode: 'release' | 'bootstrap'; plist: string } {
   const paths = forgeRuntimeServicePaths(input.controllerHome);
   const active = activeRuntimeEntrypoint(input.controllerHome);
   const useRelease = Boolean(active);
   const releaseLaunch = useRelease ? activeRuntimeLaunchSpec(input.controllerHome) : undefined;
-  if (useRelease) syncForgeRuntimeActiveEntrypoint(input.controllerHome);
   if (!useRelease && (!input.bootstrapNodeExecutable || !input.bootstrapRunnerPath)) {
     throw new Error('FORGE_RUNTIME_BOOTSTRAP_RUNNER_REQUIRED');
   }
   if (useRelease && !releaseLaunch) throw new Error('FORGE_RUNTIME_RELEASE_LAUNCH_SPEC_UNAVAILABLE');
-  const plist = renderForgeRuntimeLaunchAgent({
+  return {
     paths,
-    ...(useRelease
-      ? { activeEntrypointPath: paths.activeEntrypointPath, runtimeArgs: releaseLaunch!.args, environment: releaseLaunch!.environment }
-      : { nodeExecutable: input.bootstrapNodeExecutable!, runnerPath: input.bootstrapRunnerPath! }),
-  });
-  const existingSource = existsSync(paths.sourcePlistPath) ? readFileSync(paths.sourcePlistPath, 'utf8') : undefined;
-  const existingInstalled = input.installUserLaunchAgent && existsSync(paths.installedPlistPath)
-    ? readFileSync(paths.installedPlistPath, 'utf8')
+    mode: useRelease ? 'release' : 'bootstrap',
+    plist: renderForgeRuntimeLaunchAgent({
+      paths,
+      ...(useRelease
+        ? { activeEntrypointPath: paths.activeEntrypointPath, runtimeArgs: releaseLaunch!.args, environment: releaseLaunch!.environment }
+        : { nodeExecutable: input.bootstrapNodeExecutable!, runnerPath: input.bootstrapRunnerPath! }),
+    }),
+  };
+}
+
+export function inspectForgeRuntimeLaunchAgentContract(
+  input: { controllerHome: string; bootstrapNodeExecutable?: string; bootstrapRunnerPath?: string; inspectUserLaunchAgent?: boolean },
+): { paths: ForgeRuntimeServicePaths; mode: 'release' | 'bootstrap'; sourceMatches: boolean; installedMatches: boolean; matches: boolean } {
+  const desired = desiredForgeRuntimeLaunchAgentContract(input);
+  const existingSource = existsSync(desired.paths.sourcePlistPath) ? readFileSync(desired.paths.sourcePlistPath, 'utf8') : undefined;
+  const existingInstalled = input.inspectUserLaunchAgent && existsSync(desired.paths.installedPlistPath)
+    ? readFileSync(desired.paths.installedPlistPath, 'utf8')
     : undefined;
-  const changed = existingSource !== plist || (input.installUserLaunchAgent === true && existingInstalled !== plist);
-  if (existingSource !== plist) atomicWrite(paths.sourcePlistPath, plist);
-  if (input.installUserLaunchAgent === true && existingInstalled !== plist) atomicWrite(paths.installedPlistPath, plist, 0o644);
-  return { paths, mode: useRelease ? 'release' : 'bootstrap', changed };
+  const sourceMatches = existingSource === desired.plist;
+  const installedMatches = input.inspectUserLaunchAgent !== true || existingInstalled === desired.plist;
+  return { paths: desired.paths, mode: desired.mode, sourceMatches, installedMatches, matches: sourceMatches && installedMatches };
+}
+
+export function ensureForgeRuntimeLaunchAgentContract(
+  input: { controllerHome: string; bootstrapNodeExecutable?: string; bootstrapRunnerPath?: string; installUserLaunchAgent?: boolean },
+): { paths: ForgeRuntimeServicePaths; mode: 'release' | 'bootstrap'; changed: boolean } {
+  const desired = desiredForgeRuntimeLaunchAgentContract(input);
+  if (desired.mode === 'release') syncForgeRuntimeActiveEntrypoint(input.controllerHome);
+  const existingSource = existsSync(desired.paths.sourcePlistPath) ? readFileSync(desired.paths.sourcePlistPath, 'utf8') : undefined;
+  const existingInstalled = input.installUserLaunchAgent && existsSync(desired.paths.installedPlistPath)
+    ? readFileSync(desired.paths.installedPlistPath, 'utf8')
+    : undefined;
+  const changed = existingSource !== desired.plist || (input.installUserLaunchAgent === true && existingInstalled !== desired.plist);
+  if (existingSource !== desired.plist) atomicWrite(desired.paths.sourcePlistPath, desired.plist);
+  if (input.installUserLaunchAgent === true && existingInstalled !== desired.plist) atomicWrite(desired.paths.installedPlistPath, desired.plist, 0o644);
+  return { paths: desired.paths, mode: desired.mode, changed };
 }
 
 export function renderForgeRuntimeLaunchAgent(input: { paths: ForgeRuntimeServicePaths; activeEntrypointPath?: string; runtimeArgs?: string[]; environment?: Record<string, string>; nodeExecutable?: string; runnerPath?: string }): string {
@@ -288,6 +353,12 @@ export async function installForgeRuntimeService(input: { config: ForgeRuntimeSe
     bootstrapRunnerPath: input.runnerPath,
   });
   await retireLegacyBrowserAutomationLaunchAgent(config.controllerHome);
+  await retireConflictingForgeLaunchAgents({
+    desiredLabel: paths.label,
+    labelPrefix: 'com.moretea.forge.runtime.',
+    port: config.port,
+    requiredArguments: ['--controller-home'],
+  });
   installLaunchAgent(paths.sourcePlistPath, paths.label);
   const result = await bootstrapLaunchAgentWithRetryV2({ label: paths.label, plistPath: paths.installedPlistPath });
   if (!result.ok) throw new Error(`FORGE_RUNTIME_SERVICE_BOOTSTRAP_FAILED: ${result.diagnostics.join('; ')}`);

package/src/runtime/root/types.ts

@@ -39,6 +39,8 @@ export interface RuntimeReleaseManifest {
   browserNodeBridgeArtifactIdentity?: string;
   browserHandoffEntrypoint?: 'browser-handoff-host.js';
   browserHandoffArtifactIdentity?: string;
+  pluginActionSidecarEntrypoint?: 'forge-plugin-action-sidecar';
+  pluginActionSidecarArtifactIdentity?: string;
   browserAutomationHelperEntrypoint?: 'browser-automation-helper';
   browserAutomationHelperArtifactIdentity?: string;
   browserAutomationHelperContractIdentity?: string;