@moretea-labs/forge 1.5.1 → 1.7.0

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

@@ -14,6 +14,15 @@ import { CONTROL_PLANE_SCHEMA_VERSION } from '../control-plane/persistence/sqlit
  * `forge runtime service install` operation; staging alone never starts or
  * publishes anything.
  */
+export const FORGE_MACOS_RUNTIME_SIGNING_IDENTIFIER = 'com.moretea.forge.runtime';
+
+export interface MacOSRuntimeCodeSigning {
+  identifier: string;
+  teamIdentifier: string;
+  designatedRequirement: string;
+  authority: string;
+}
+
 export interface StagedRuntimeRelease {
   releasePath: string;
   manifestPath: string;
@@ -22,20 +31,23 @@ export interface StagedRuntimeRelease {
   diagnosticArtifactIdentity?: string;
   browserNodeBridgeArtifactIdentity?: string;
   browserHandoffArtifactIdentity?: string;
-  desktopHelperArtifactIdentity?: string;
   processRunnerArtifactIdentity?: string;
   checkRunnerArtifactIdentity?: string;
+  pluginActionSidecarArtifactIdentity?: string;
   externalPluginProbeArtifactIdentity?: string;
   codeGraphNodeArtifactIdentity?: string;
   codeGraphSidecarArtifactIdentity?: string;
   codeGraphLibraryArtifactIdentity?: string;
   controllerUiArtifactIdentity?: string;
+  macosCodeSigning?: MacOSRuntimeCodeSigning;
   manifestSha256: string;
   sourceCommit: string;
 }
 
 export interface RuntimeReleaseMaterializerDependencies {
   now?: () => number;
+  platform?: NodeJS.Platform;
+  signMacOSRuntime?: (input: { executable: string; controllerHome: string }) => MacOSRuntimeCodeSigning;
   uuid?: () => string;
   compileBinary?: (input: { sourceRoot: string; outputPath: string; entryPath?: 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 };
@@ -59,6 +71,8 @@ export interface CandidateRuntimeStageReceiptV1 {
 }
 
 export interface CandidateRuntimeReleaseStagerDependencies {
+  platform?: NodeJS.Platform;
+  inspectMacOSRuntime?: (executable: string) => MacOSRuntimeCodeSigning;
   runCandidateStager?: (input: {
     bunExecutable: string;
     scriptPath: string;
@@ -78,6 +92,95 @@ function sha256(path: string): string {
   return createHash('sha256').update(readFileSync(path)).digest('hex');
 }
 
+function parseMacOSRuntimeCodeSigning(value: unknown, context: string): MacOSRuntimeCodeSigning | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${context}: macosCodeSigning must be an object`);
+  const record = value as Record<string, unknown>;
+  const field = (name: keyof MacOSRuntimeCodeSigning): string => {
+    const entry = record[name];
+    if (typeof entry !== 'string' || !entry.trim()) throw new Error(`${context}: macosCodeSigning.${name} is required`);
+    return entry.trim();
+  };
+  const signing = {
+    identifier: field('identifier'),
+    teamIdentifier: field('teamIdentifier'),
+    designatedRequirement: field('designatedRequirement'),
+    authority: field('authority'),
+  };
+  if (signing.identifier !== FORGE_MACOS_RUNTIME_SIGNING_IDENTIFIER) {
+    throw new Error(`${context}: macosCodeSigning.identifier must be ${FORGE_MACOS_RUNTIME_SIGNING_IDENTIFIER}`);
+  }
+  if (!/^[A-Z0-9]{10}$/.test(signing.teamIdentifier)) throw new Error(`${context}: macosCodeSigning.teamIdentifier is invalid`);
+  if (!signing.authority.startsWith('Developer ID Application: ')) throw new Error(`${context}: macosCodeSigning.authority must be Developer ID Application`);
+  if (!signing.designatedRequirement.includes(`identifier \"${FORGE_MACOS_RUNTIME_SIGNING_IDENTIFIER}\"`)
+    || !signing.designatedRequirement.includes('anchor apple generic')
+    || !signing.designatedRequirement.includes(`certificate leaf[subject.OU] = ${signing.teamIdentifier}`)) {
+    throw new Error(`${context}: macosCodeSigning.designatedRequirement is not the stable Developer ID contract`);
+  }
+  return signing;
+}
+
+function readActiveMacOSRuntimeTeam(controllerHome: string): string | undefined {
+  const authorityPath = join(resolve(controllerHome), 'runtime', 'releases', 'authority.json');
+  if (!existsSync(authorityPath)) return undefined;
+  try {
+    const authority = JSON.parse(readFileSync(authorityPath, 'utf8')) as { active?: { manifestPath?: string } };
+    if (!authority.active?.manifestPath || !existsSync(authority.active.manifestPath)) return undefined;
+    const manifest = JSON.parse(readFileSync(authority.active.manifestPath, 'utf8')) as Record<string, unknown>;
+    return parseMacOSRuntimeCodeSigning(manifest.macosCodeSigning, 'RUNTIME_RELEASE_ACTIVE_SIGNING_INVALID')?.teamIdentifier;
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('RUNTIME_RELEASE_ACTIVE_SIGNING_INVALID')) throw error;
+    return undefined;
+  }
+}
+
+function inspectMacOSRuntimeCodeSigning(executable: string): MacOSRuntimeCodeSigning {
+  const verify = runProcess('codesign', ['--verify', '--strict', executable], { timeoutMs: 30_000, maxOutputBytes: 64 * 1024 });
+  if (!verify.ok) throw new Error(`RUNTIME_RELEASE_MACOS_SIGNATURE_INVALID: ${verify.stderr || verify.stdout || verify.error}`.slice(0, 2_000));
+  const detail = runProcess('codesign', ['-dv', '--verbose=4', executable], { timeoutMs: 30_000, maxOutputBytes: 64 * 1024 });
+  if (!detail.ok) throw new Error(`RUNTIME_RELEASE_MACOS_SIGNATURE_INSPECTION_FAILED: ${detail.stderr || detail.stdout || detail.error}`.slice(0, 2_000));
+  const detailText = `${detail.stdout}\n${detail.stderr}`;
+  const identifier = detailText.match(/^Identifier=(.+)$/m)?.[1]?.trim() ?? '';
+  const teamIdentifier = detailText.match(/^TeamIdentifier=(.+)$/m)?.[1]?.trim() ?? '';
+  const authority = detailText.match(/^Authority=(Developer ID Application:.+)$/m)?.[1]?.trim() ?? '';
+  const requirementResult = runProcess('codesign', ['-d', '-r-', executable], { timeoutMs: 30_000, maxOutputBytes: 64 * 1024 });
+  if (!requirementResult.ok) throw new Error(`RUNTIME_RELEASE_MACOS_REQUIREMENT_INSPECTION_FAILED: ${requirementResult.stderr || requirementResult.stdout || requirementResult.error}`.slice(0, 2_000));
+  const requirementText = `${requirementResult.stdout}\n${requirementResult.stderr}`;
+  const designatedRequirement = requirementText.match(/^designated => (.+)$/m)?.[1]?.trim() ?? '';
+  return parseMacOSRuntimeCodeSigning({ identifier, teamIdentifier, authority, designatedRequirement }, 'RUNTIME_RELEASE_MACOS_SIGNATURE_INVALID')!;
+}
+
+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));
+  const candidates = identities.stdout.split(/\r?\n/).flatMap((line) => {
+    const match = line.match(/^\s*\d+\)\s+([A-Fa-f0-9]{40})\s+\"(Developer ID Application: .+ \(([A-Z0-9]{10})\))\"/);
+    return match ? [{ hash: match[1]!, label: match[2]!, teamIdentifier: match[3]! }] : [];
+  });
+  const configured = process.env.FORGE_MACOS_RUNTIME_SIGNING_IDENTITY?.trim();
+  const expectedTeam = readActiveMacOSRuntimeTeam(input.controllerHome);
+  let selected = configured
+    ? candidates.find((candidate) => candidate.hash.toLowerCase() === configured.toLowerCase() || candidate.label === configured)
+    : undefined;
+  if (configured && !selected) throw new Error('RUNTIME_RELEASE_MACOS_SIGNING_IDENTITY_NOT_FOUND');
+  if (!selected) {
+    const eligible = expectedTeam ? candidates.filter((candidate) => candidate.teamIdentifier === expectedTeam) : candidates;
+    const teams = Array.from(new Set(eligible.map((candidate) => candidate.teamIdentifier)));
+    if (teams.length !== 1 || eligible.length === 0) {
+      throw new Error(expectedTeam ? 'RUNTIME_RELEASE_MACOS_SIGNING_IDENTITY_FOR_TEAM_REQUIRED' : 'RUNTIME_RELEASE_MACOS_SIGNING_IDENTITY_REQUIRED');
+    }
+    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 });
+  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');
+  return inspected;
+}
+
 function sha256Directory(root: string): string {
   const hash = createHash('sha256');
   const visit = (directory: string): void => {
@@ -203,12 +306,28 @@ export function stageRuntimeReleaseFromCandidateSource(input: {
   if (sha256(manifestPath) !== receipt.manifestSha256) {
     throw new Error('RUNTIME_RELEASE_CANDIDATE_MANIFEST_IDENTITY_MISMATCH');
   }
+  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 platform = dependencies.platform ?? process.platform;
+  const macosCodeSigning = parseMacOSRuntimeCodeSigning(rawManifest.macosCodeSigning, 'RUNTIME_RELEASE_CANDIDATE_SIGNING_INVALID');
+  if (platform === 'darwin') {
+    if (!macosCodeSigning) throw new Error('RUNTIME_RELEASE_CANDIDATE_MACOS_SIGNING_REQUIRED');
+    const actual = (dependencies.inspectMacOSRuntime ?? inspectMacOSRuntimeCodeSigning)(runtimePath);
+    if (actual.identifier !== macosCodeSigning.identifier
+      || actual.teamIdentifier !== macosCodeSigning.teamIdentifier
+      || actual.authority !== macosCodeSigning.authority
+      || actual.designatedRequirement !== macosCodeSigning.designatedRequirement) {
+      throw new Error('RUNTIME_RELEASE_CANDIDATE_MACOS_SIGNING_MISMATCH');
+    }
+  }
 
   return {
     releasePath,
     manifestPath,
     releaseId: receipt.releaseId,
     artifactIdentity: receipt.artifactIdentity,
+    ...(macosCodeSigning ? { macosCodeSigning } : {}),
     manifestSha256: receipt.manifestSha256,
     sourceCommit: receipt.sourceCommit,
   };
@@ -297,6 +416,14 @@ 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;
+    if (platform === 'darwin' && !macosCodeSigning) throw new Error('RUNTIME_RELEASE_MACOS_SIGNING_REQUIRED');
+    const normalizedMacOSCodeSigning = macosCodeSigning
+      ? parseMacOSRuntimeCodeSigning(macosCodeSigning, 'RUNTIME_RELEASE_MACOS_SIGNING_INVALID')
+      : undefined;
     const artifactIdentity = `sha256:${sha256(executable)}`;
 
     const diagnosticExecutable = join(staging, 'forge-cli');
@@ -365,6 +492,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)) {
@@ -407,32 +547,24 @@ export function stageRuntimeRelease(input: {
     cpSync(sourceControllerUiPath, controllerUiPath, { recursive: true, force: false });
     const controllerUiArtifactIdentity = `sha256:${sha256Directory(controllerUiPath)}`;
 
-    const desktopHelperEntrypoint = 'forge-desktop-helper.mjs' as const;
-    const sourceDesktopHelperPath = join(sourceRoot, 'bin', desktopHelperEntrypoint);
-    if (!existsSync(sourceDesktopHelperPath)) {
-      throw new Error(`RUNTIME_RELEASE_DESKTOP_HELPER_SOURCE_MISSING: ${sourceDesktopHelperPath}`);
-    }
-    const desktopHelperPath = join(staging, desktopHelperEntrypoint);
-    copyFileSync(sourceDesktopHelperPath, desktopHelperPath);
-    chmodSync(desktopHelperPath, 0o700);
-    const desktopHelperArtifactIdentity = `sha256:${sha256(desktopHelperPath)}`;
     const manifest = {
       schemaVersion: 1,
       releaseId,
       artifactIdentity,
       entrypoint: 'forge-runtime',
+      ...(normalizedMacOSCodeSigning ? { macosCodeSigning: normalizedMacOSCodeSigning } : {}),
       diagnosticEntrypoint: 'forge-cli',
       diagnosticArtifactIdentity,
       browserNodeBridgeEntrypoint,
       browserNodeBridgeArtifactIdentity,
       browserHandoffEntrypoint,
       browserHandoffArtifactIdentity,
-      desktopHelperEntrypoint,
-      desktopHelperArtifactIdentity,
       processRunnerEntrypoint,
       processRunnerArtifactIdentity,
       checkRunnerEntrypoint,
       checkRunnerArtifactIdentity,
+      pluginActionSidecarEntrypoint,
+      pluginActionSidecarArtifactIdentity,
       externalPluginProbeEntrypoint,
       externalPluginProbeArtifactIdentity,
       codeGraphNodeEntrypoint,
@@ -464,10 +596,10 @@ export function stageRuntimeRelease(input: {
       manifestPath: join(releasePath, 'manifest.json'),
       releaseId,
       artifactIdentity,
+      ...(normalizedMacOSCodeSigning ? { macosCodeSigning: normalizedMacOSCodeSigning } : {}),
       diagnosticArtifactIdentity,
       browserNodeBridgeArtifactIdentity,
       browserHandoffArtifactIdentity,
-      desktopHelperArtifactIdentity,
       processRunnerArtifactIdentity,
       checkRunnerArtifactIdentity,
       externalPluginProbeArtifactIdentity,
@@ -484,12 +616,23 @@ export function stageRuntimeRelease(input: {
   }
 }
 
-export function assertRuntimeReleaseFiles(release: StagedRuntimeRelease): void {
+export function assertRuntimeReleaseFiles(release: StagedRuntimeRelease, dependencies: { platform?: NodeJS.Platform; inspectMacOSRuntime?: (executable: string) => MacOSRuntimeCodeSigning } = {}): void {
   if (!existsSync(release.releasePath) || !existsSync(release.manifestPath)) {
     throw new Error(`RUNTIME_RELEASE_FILES_MISSING: ${release.releasePath}`);
   }
-  if (!existsSync(join(release.releasePath, 'forge-runtime'))) {
-    throw new Error(`RUNTIME_RELEASE_ENTRYPOINT_MISSING: ${join(release.releasePath, 'forge-runtime')}`);
+  const runtimePath = join(release.releasePath, 'forge-runtime');
+  if (!existsSync(runtimePath)) {
+    throw new Error(`RUNTIME_RELEASE_ENTRYPOINT_MISSING: ${runtimePath}`);
+  }
+  const platform = dependencies.platform ?? process.platform;
+  if (platform === 'darwin' && release.macosCodeSigning) {
+    const actual = (dependencies.inspectMacOSRuntime ?? inspectMacOSRuntimeCodeSigning)(runtimePath);
+    if (actual.identifier !== release.macosCodeSigning.identifier
+      || actual.teamIdentifier !== release.macosCodeSigning.teamIdentifier
+      || actual.authority !== release.macosCodeSigning.authority
+      || actual.designatedRequirement !== release.macosCodeSigning.designatedRequirement) {
+      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')}`);
@@ -500,15 +643,15 @@ export function assertRuntimeReleaseFiles(release: StagedRuntimeRelease): void {
   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.desktopHelperArtifactIdentity && !existsSync(join(release.releasePath, 'forge-desktop-helper.mjs'))) {
-    throw new Error(`RUNTIME_RELEASE_DESKTOP_HELPER_MISSING: ${join(release.releasePath, 'forge-desktop-helper.mjs')}`);
-  }
   if (release.processRunnerArtifactIdentity && !existsSync(join(release.releasePath, 'process-runner.js'))) {
     throw new Error(`RUNTIME_RELEASE_PROCESS_RUNNER_MISSING: ${join(release.releasePath, 'process-runner.js')}`);
   }
   if (release.checkRunnerArtifactIdentity && !existsSync(join(release.releasePath, 'forge-check-runner'))) {
     throw new Error(`RUNTIME_RELEASE_CHECK_RUNNER_MISSING: ${join(release.releasePath, 'forge-check-runner')}`);
   }
+  if (release.pluginActionSidecarArtifactIdentity && !existsSync(join(release.releasePath, 'forge-plugin-action-sidecar'))) {
+    throw new Error(`RUNTIME_RELEASE_PLUGIN_ACTION_SIDECAR_MISSING: ${join(release.releasePath, 'forge-plugin-action-sidecar')}`);
+  }
   if (release.externalPluginProbeArtifactIdentity && !existsSync(join(release.releasePath, 'external-unix-socket-probe.cjs'))) {
     throw new Error(`RUNTIME_RELEASE_EXTERNAL_PLUGIN_PROBE_MISSING: ${join(release.releasePath, 'external-unix-socket-probe.cjs')}`);
   }

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,52 +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(
+function desiredForgeRuntimeLaunchAgentContract(
   input: { controllerHome: string; bootstrapNodeExecutable?: string; bootstrapRunnerPath?: string },
-): { paths: ForgeRuntimeServicePaths; mode: 'release' | 'bootstrap'; changed: boolean } {
+): { 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 = existsSync(paths.installedPlistPath) ? readFileSync(paths.installedPlistPath, 'utf8') : undefined;
-  const changed = existingSource !== plist || existingInstalled !== plist;
-  if (existingSource !== plist) atomicWrite(paths.sourcePlistPath, plist);
-  if (existingInstalled !== plist) atomicWrite(paths.installedPlistPath, plist, 0o644);
-  return { paths, mode: useRelease ? 'release' : 'bootstrap', changed };
+    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 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 {
@@ -286,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('; ')}`);