@moretea-labs/forge 1.5.0 → 1.6.0

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

@@ -0,0 +1,136 @@
+import { createHash } from 'crypto';
+import { closeSync, mkdirSync, openSync, renameSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { basename, dirname, join, resolve } from 'path';
+import { spawn, spawnSync } from 'child_process';
+import { bootstrapLaunchAgentWithRetryV2, installLaunchAgent, launchAgentPath } from '../../cli/controller/launch-agents';
+import type { PackageRuntimeRelease } from './package-runtime-release';
+
+export interface PackageConnectorServicePaths {
+  label: string;
+  serviceRoot: string;
+  sourcePlistPath: string;
+  installedPlistPath: string;
+  stdoutPath: string;
+  stderrPath: string;
+}
+
+export interface PackageConnectorServiceResult {
+  endpoint: string;
+  mode: 'launchd' | 'systemd-user' | 'portable';
+  persistent: boolean;
+  servicePath?: string;
+  pid?: number;
+}
+
+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 serviceRoot = join(home, 'runtime', 'connector-service');
+  return {
+    label,
+    serviceRoot,
+    sourcePlistPath: join(serviceRoot, `${label}.plist`),
+    installedPlistPath: launchAgentPath(label, accountHome),
+    stdoutPath: join(serviceRoot, 'logs', 'stdout.log'),
+    stderrPath: join(serviceRoot, 'logs', 'stderr.log'),
+  };
+}
+
+export function packageConnectorLaunchSpec(input: { release: PackageRuntimeRelease; controllerHome: string; endpoint: string; executable?: string }): { executable: string; args: string[]; environment: Record<string, string>; port: number } {
+  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.execPath);
+  const packageRoot = resolve(input.release.packageRoot);
+  const cliEntry = join(packageRoot, 'src', 'cli', 'index.ts');
+  const nodeLoader = join(packageRoot, 'src', 'runtime', 'shared', 'node-ts-loader.mjs');
+  const isBun = Boolean(process.versions.bun) || /(?:^|[/\\-])bun(?:$|[/\\]|\.exe$)/i.test(basename(executable));
+  const cliArgs = [
+    'mcp', 'serve', '--repo', packageRoot, '--controller-home', resolve(input.controllerHome),
+    '--transport', 'http', '--host', '127.0.0.1', '--port', String(port), '--profile', 'controller', '--auth', 'oauth',
+  ];
+  return {
+    executable,
+    args: isBun ? [cliEntry, ...cliArgs] : ['--loader', nodeLoader, cliEntry, ...cliArgs],
+    environment: { FORGE_CONTROLLER_HOME: resolve(input.controllerHome), FORGE_CONTROLLER_LIFECYCLE_OWNER: '1' },
+    port,
+  };
+}
+
+export function renderPackageConnectorLaunchAgent(input: { paths: PackageConnectorServicePaths; launch: ReturnType<typeof packageConnectorLaunchSpec> }): string {
+  const environmentXml = Object.entries(input.launch.environment).sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `    <key>${xml(key)}</key>\n    <string>${xml(value)}</string>`).join('\n');
+  const args = [input.launch.executable, ...input.launch.args];
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n  <key>Label</key>\n  <string>${xml(input.paths.label)}</string>\n  <key>ProgramArguments</key>\n  <array>\n${args.map((arg) => `    <string>${xml(arg)}</string>`).join('\n')}\n  </array>\n  <key>EnvironmentVariables</key>\n  <dict>\n${environmentXml}\n  </dict>\n  <key>RunAtLoad</key>\n  <true/>\n  <key>KeepAlive</key>\n  <dict><key>SuccessfulExit</key><false/></dict>\n  <key>ThrottleInterval</key><integer>5</integer>\n  <key>StandardOutPath</key><string>${xml(input.paths.stdoutPath)}</string>\n  <key>StandardErrorPath</key><string>${xml(input.paths.stderrPath)}</string>\n</dict>\n</plist>\n`;
+}
+
+export function renderPackageConnectorSystemdUserUnit(input: { launch: ReturnType<typeof packageConnectorLaunchSpec> }): string {
+  const quote = (value: string) => `"${value.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+  const env = Object.entries(input.launch.environment).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `Environment=${quote(`${k}=${v}`)}`);
+  return ['[Unit]', 'Description=Forge ChatGPT OAuth Gateway', 'After=network-online.target', '', '[Service]', 'Type=simple', `ExecStart=${[input.launch.executable, ...input.launch.args].map(quote).join(' ')}`, ...env, 'Restart=on-failure', 'RestartSec=5', '', '[Install]', 'WantedBy=default.target', ''].join('\n');
+}
+
+function installSystemd(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv): string {
+  const unitName = `${paths.label}.service`;
+  const unitPath = join(env.HOME ?? homedir(), '.config', 'systemd', 'user', unitName);
+  atomicWrite(unitPath, renderPackageConnectorSystemdUserUnit({ launch }), 0o644);
+  for (const args of [['--user', 'daemon-reload'], ['--user', 'enable', '--now', unitName]]) {
+    const result = spawnSync('systemctl', args, { encoding: 'utf8', env, timeout: 30_000 });
+    if (result.status !== 0) throw new Error(`FORGE_PACKAGE_CONNECTOR_SYSTEMD_INSTALL_FAILED: ${(result.stderr || result.stdout || '').trim()}`);
+  }
+  return unitPath;
+}
+
+function startPortable(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv): number {
+  mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
+  const stdout = openSync(paths.stdoutPath, 'a', 0o600), stderr = openSync(paths.stderrPath, 'a', 0o600);
+  // A connector is not the Canonical Runtime writer. Never let a transient
+  // installer/worker write claim escape into this long-lived process; the claim
+  // would become stale as soon as its parent exits. Keep only the explicit
+  // Controller Home and lifecycle-role marker from launch.environment.
+  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];
+  try {
+    const child = spawn(launch.executable, launch.args, { detached: true, stdio: ['ignore', stdout, stderr], env: { ...childEnv, ...launch.environment } });
+    if (!child.pid) throw new Error('FORGE_PACKAGE_CONNECTOR_START_FAILED');
+    child.unref();
+    return child.pid;
+  } finally { closeSync(stdout); closeSync(stderr); }
+}
+
+export async function installPackageConnectorService(input: { release: PackageRuntimeRelease; controllerHome: string; endpoint: string; platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; forcePortable?: boolean }): Promise<PackageConnectorServiceResult> {
+  const paths = packageConnectorServicePaths(input.controllerHome, input.env?.HOME);
+  mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
+  const launch = packageConnectorLaunchSpec({ release: input.release, controllerHome: input.controllerHome, endpoint: input.endpoint });
+  const platform = input.platform ?? process.platform, env = input.env ?? process.env;
+  if (!input.forcePortable && platform === 'darwin') {
+    atomicWrite(paths.sourcePlistPath, renderPackageConnectorLaunchAgent({ paths, launch }), 0o600);
+    installLaunchAgent(paths.sourcePlistPath, paths.label);
+    const result = await bootstrapLaunchAgentWithRetryV2({ label: paths.label, plistPath: paths.installedPlistPath });
+    if (!result.ok) throw new Error(`FORGE_PACKAGE_CONNECTOR_LAUNCHD_INSTALL_FAILED: ${result.diagnostics.join('; ')}`);
+    return { endpoint: input.endpoint, mode: 'launchd', persistent: true, servicePath: paths.installedPlistPath };
+  }
+  if (!input.forcePortable && platform === 'linux') {
+    const probe = spawnSync('systemctl', ['--user', 'show-environment'], { encoding: 'utf8', env, timeout: 30_000 });
+    if (probe.status === 0) return { endpoint: input.endpoint, mode: 'systemd-user', persistent: true, servicePath: installSystemd(paths, launch, env) };
+  }
+  return { endpoint: input.endpoint, mode: 'portable', persistent: false, pid: startPortable(paths, launch, env) };
+}

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

@@ -14,6 +14,8 @@ import {
   type ForgeRuntimeServiceConfig,
 } from './service';
 import { materializePackageRuntimeRelease, type PackageRuntimeRelease } from './package-runtime-release';
+import { loadMcpServiceLocalConfig } from '../../cli/mcp/auth';
+import { installPackageConnectorService, type PackageConnectorServiceResult } from './package-connector-service';
 
 export type PackageRuntimeServiceMode = 'launchd' | 'systemd-user' | 'portable';
 
@@ -26,6 +28,7 @@ export interface PackageRuntimeServiceInstallResult {
   servicePath?: string;
   pid?: number;
   warnings: string[];
+  connector?: PackageConnectorServiceResult;
 }
 
 export interface PackageRuntimeServiceOptions {
@@ -147,26 +150,36 @@ export async function installPackageRuntimeService(options: PackageRuntimeServic
     repositoryRoot: release.packageRoot,
     host: options.host ?? '127.0.0.1',
     port: options.port ?? 8765,
-    authTokenFile: resolve(options.authTokenFile),
+    authTokenFile: options.authTokenFile,
     ...(options.exclusiveWorkId?.trim() ? { exclusiveWorkId: options.exclusiveWorkId.trim() } : {}),
   };
   writeForgeRuntimeServiceConfig(config);
   syncForgeRuntimeActiveEntrypoint(controllerHome);
   const platform = options.platform ?? process.platform;
   const env = options.env ?? process.env;
+
+  let base: PackageRuntimeServiceInstallResult;
   if (!options.forcePortable && platform === 'darwin') {
     const paths = await installForgeRuntimeService({ config, runnerPath: join(release.packageRoot, 'bin', 'forge-runtime-service.mjs'), nodeExecutable: process.execPath });
-    return { status: 'installed', mode: 'launchd', persistent: true, controllerHome, release, servicePath: paths.installedPlistPath, warnings: [] };
-  }
-  if (!options.forcePortable && platform === 'linux' && systemdUserAvailable(env)) {
+    base = { status: 'installed', mode: 'launchd', persistent: true, controllerHome, release, servicePath: paths.installedPlistPath, warnings: [] };
+  } else if (!options.forcePortable && platform === 'linux' && systemdUserAvailable(env)) {
     const unitPath = installSystemdUserService(controllerHome, env);
-    return { status: 'installed', mode: 'systemd-user', persistent: true, controllerHome, release, servicePath: unitPath, warnings: [] };
+    base = { status: 'installed', mode: 'systemd-user', persistent: true, controllerHome, release, servicePath: unitPath, warnings: [] };
+  } else {
+    const pid = startPortableRuntime(controllerHome, env);
+    base = {
+      status: 'installed', mode: 'portable', persistent: false, controllerHome, release, pid,
+      warnings: [platform === 'win32'
+        ? 'Native Windows is preview: Forge started detached Runtime and OAuth Gateway processes for this session; automatic login/reboot persistence is not yet claimed.'
+        : 'systemd --user is unavailable: Forge started detached Runtime and OAuth Gateway processes; enable a user service manager for reboot persistence.'],
+    };
   }
-  const pid = startPortableRuntime(controllerHome, env);
-  return {
-    status: 'installed', mode: 'portable', persistent: false, controllerHome, release, pid,
-    warnings: [platform === 'win32'
-      ? 'Native Windows is preview: Forge started a detached user process for this session; automatic login/reboot persistence is not yet claimed.'
-      : 'systemd --user is unavailable: Forge started a detached user process; enable a user service manager for reboot persistence.'],
-  };
+
+  const localConfig = loadMcpServiceLocalConfig(controllerHome);
+  const connectorEndpoint = localConfig?.chatgpt?.localEndpoint;
+  if (!connectorEndpoint) return base;
+  const connector = await installPackageConnectorService({
+    release, controllerHome, endpoint: connectorEndpoint, platform, env, forcePortable: options.forcePortable === true,
+  });
+  return { ...base, connector };
 }

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,19 +31,22 @@ export interface StagedRuntimeRelease {
   diagnosticArtifactIdentity?: string;
   browserNodeBridgeArtifactIdentity?: string;
   browserHandoffArtifactIdentity?: string;
-  desktopHelperArtifactIdentity?: string;
   processRunnerArtifactIdentity?: string;
   checkRunnerArtifactIdentity?: 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 };
@@ -58,6 +70,8 @@ export interface CandidateRuntimeStageReceiptV1 {
 }
 
 export interface CandidateRuntimeReleaseStagerDependencies {
+  platform?: NodeJS.Platform;
+  inspectMacOSRuntime?: (executable: string) => MacOSRuntimeCodeSigning;
   runCandidateStager?: (input: {
     bunExecutable: string;
     scriptPath: string;
@@ -77,6 +91,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 => {
@@ -202,12 +305,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,
   };
@@ -296,6 +415,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');
@@ -395,28 +522,29 @@ export function stageRuntimeRelease(input: {
     const codeGraphSidecarArtifactIdentity = `sha256:${sha256(codeGraphSidecarPath)}`;
     const codeGraphLibraryArtifactIdentity = `sha256:${sha256Directory(codeGraphLibraryPath)}`;
 
-    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 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 desktopHelperPath = join(staging, desktopHelperEntrypoint);
-    copyFileSync(sourceDesktopHelperPath, desktopHelperPath);
-    chmodSync(desktopHelperPath, 0o700);
-    const desktopHelperArtifactIdentity = `sha256:${sha256(desktopHelperPath)}`;
+    const controllerUiPath = join(staging, controllerUiRoot);
+    cpSync(sourceControllerUiPath, controllerUiPath, { recursive: true, force: false });
+    const controllerUiArtifactIdentity = `sha256:${sha256Directory(controllerUiPath)}`;
+
     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,
@@ -429,6 +557,8 @@ export function stageRuntimeRelease(input: {
       codeGraphSidecarArtifactIdentity,
       codeGraphLibraryRoot,
       codeGraphLibraryArtifactIdentity,
+      controllerUiRoot,
+      controllerUiArtifactIdentity,
       arguments: [],
       configurationSchemaVersion: 1,
       controllerHome: resolve(input.controllerHome),
@@ -450,16 +580,17 @@ export function stageRuntimeRelease(input: {
       manifestPath: join(releasePath, 'manifest.json'),
       releaseId,
       artifactIdentity,
+      ...(normalizedMacOSCodeSigning ? { macosCodeSigning: normalizedMacOSCodeSigning } : {}),
       diagnosticArtifactIdentity,
       browserNodeBridgeArtifactIdentity,
       browserHandoffArtifactIdentity,
-      desktopHelperArtifactIdentity,
       processRunnerArtifactIdentity,
       checkRunnerArtifactIdentity,
       externalPluginProbeArtifactIdentity,
       codeGraphNodeArtifactIdentity,
       codeGraphSidecarArtifactIdentity,
       codeGraphLibraryArtifactIdentity,
+      controllerUiArtifactIdentity,
       manifestSha256: createHash('sha256').update(`${JSON.stringify(manifest, null, 2)}\n`).digest('hex'),
       sourceCommit,
     };
@@ -469,12 +600,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')}`);
@@ -485,9 +627,6 @@ 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')}`);
   }
@@ -506,4 +645,8 @@ export function assertRuntimeReleaseFiles(release: StagedRuntimeRelease): void {
   if (release.codeGraphLibraryArtifactIdentity && !existsSync(join(release.releasePath, 'codegraph-lib', 'dist', 'index.js'))) {
     throw new Error(`RUNTIME_RELEASE_CODEGRAPH_LIBRARY_MISSING: ${join(release.releasePath, 'codegraph-lib', 'dist', 'index.js')}`);
   }
+  if (release.controllerUiArtifactIdentity
+    && (!existsSync(join(release.releasePath, 'ui-dist', 'app.js')) || !existsSync(join(release.releasePath, 'ui-dist', 'app.css')))) {
+    throw new Error(`RUNTIME_RELEASE_CONTROLLER_UI_MISSING: ${join(release.releasePath, 'ui-dist')}`);
+  }
 }

package/src/runtime/root/service.ts

@@ -232,7 +232,7 @@ export function syncForgeRuntimeActiveEntrypoint(controllerHome: string): { path
 }
 
 export function ensureForgeRuntimeLaunchAgentContract(
-  input: { controllerHome: string; bootstrapNodeExecutable?: string; bootstrapRunnerPath?: string },
+  input: { controllerHome: string; bootstrapNodeExecutable?: string; bootstrapRunnerPath?: string; installUserLaunchAgent?: boolean },
 ): { paths: ForgeRuntimeServicePaths; mode: 'release' | 'bootstrap'; changed: boolean } {
   const paths = forgeRuntimeServicePaths(input.controllerHome);
   const active = activeRuntimeEntrypoint(input.controllerHome);
@@ -250,10 +250,12 @@ export function ensureForgeRuntimeLaunchAgentContract(
       : { 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;
+  const existingInstalled = input.installUserLaunchAgent && existsSync(paths.installedPlistPath)
+    ? readFileSync(paths.installedPlistPath, 'utf8')
+    : undefined;
+  const changed = existingSource !== plist || (input.installUserLaunchAgent === true && existingInstalled !== plist);
   if (existingSource !== plist) atomicWrite(paths.sourcePlistPath, plist);
-  if (existingInstalled !== plist) atomicWrite(paths.installedPlistPath, plist, 0o644);
+  if (input.installUserLaunchAgent === true && existingInstalled !== plist) atomicWrite(paths.installedPlistPath, plist, 0o644);
   return { paths, mode: useRelease ? 'release' : 'bootstrap', changed };
 }
 

package/src/runtime/safe-tooling/index.ts

@@ -1,6 +1,5 @@
 export * from './types';
 export * from './plugin-summary';
-export * from './browser-safe';
 export * from './job-summary';
 export * from './external-filesystem';
 export * from './workspace-auth';

package/src/runtime/safe-tooling/types.ts

@@ -44,36 +44,6 @@ export interface SafePluginSummary {
   };
 }
 
-export interface WebTarget {
-  targetKey: string;
-  domain: string;
-  origin: string;
-  allowed: true;
-  defaultPath: '/';
-}
-
-export interface WebDomainAccessPreview {
-  ticketId: string;
-  normalizedDomain: string;
-  domainKey: string;
-  reason: string;
-  expiresAt: string;
-  alreadyAllowed: boolean;
-  currentAllowedDomainCount: number;
-  risk: 'workspace_write';
-  confirmation: 'authorization';
-  localOnly: true;
-  willChange: {
-    pluginId: 'browser';
-    configField: 'allowedDomains';
-    addDomain: string;
-  };
-  safety: {
-    arbitraryUrlAccepted: false;
-    domainOnly: true;
-    sensitiveConfigReturned: false;
-  };
-}
 
 export interface SafeJobResultSummary {
   jobId: string;

package/src/runtime/standalone-recovery/core.ts

@@ -1740,7 +1740,7 @@ export async function activateRuntimeRelease(
       return { ok: false, attempted: true, detail, serviceTarget: service.target, verify: await verifyLocal(config) } satisfies RuntimeReleaseActivationResult;
     }
     try {
-      ensureForgeRuntimeLaunchAgentContract({ controllerHome: config.controllerHome });
+      ensureForgeRuntimeLaunchAgentContract({ controllerHome: config.controllerHome, installUserLaunchAgent: true });
     } catch (error) {
       const detail = `runtime launchd stable-release contract update failed: ${error instanceof Error ? error.message : String(error)}`;
       audit(config, 'runtime_release_activation_launchd_contract_failed', { serviceTarget: service.target, operationId, detail });
@@ -1821,7 +1821,7 @@ export async function activateRuntimeRelease(
             physicalHome: storageMigration.physicalHome,
           });
         }
-        ensureForgeRuntimeLaunchAgentContract({ controllerHome: config.controllerHome });
+        ensureForgeRuntimeLaunchAgentContract({ controllerHome: config.controllerHome, installUserLaunchAgent: true });
         const previousRevision = previousActive?.releaseId ?? '';
         const previousIdentity = previousActive?.artifactIdentity;
         if (