@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/root/service.ts

@@ -1,9 +1,14 @@
+import { writeAtomicTextFile } from '../shared/atomic-text-file';
 import { createHash, randomUUID } from 'crypto';
-import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync } from 'fs';
 import { homedir } from 'os';
 import { dirname, isAbsolute, join, relative, resolve } from 'path';
 import { resolveControllerHome } from '../../cli/repositories/controller-home';
 import { createPlatformServiceManagerHost } from '../platform/service-manager';
+import { forgeRuntimePersistentServiceLabel } from '../platform/service-inventory';
+import { loadRuntimeReleaseManifest } from './release-manifest';
+import { normalizeRuntimeDeploymentTopology, type RuntimeDeploymentTopology } from './deployment-topology';
+import type { RuntimeReleaseManifest } from './types';
 
 export interface ForgeRuntimeServiceConfig {
   schemaVersion: 1;
@@ -13,7 +18,8 @@ export interface ForgeRuntimeServiceConfig {
   host: string;
   port: number;
   authTokenFile: string;
-  exclusiveWorkId?: string;
+  /** Persisted product-level component composition. Missing is accepted only for legacy configs. */
+  topology?: RuntimeDeploymentTopology;
 }
 
 export interface ForgeRuntimeServicePaths {
@@ -32,18 +38,10 @@ function xml(value: string): string {
   return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
 }
 
-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);
-}
-
 export function forgeRuntimeServicePaths(controllerHome: string): ForgeRuntimeServicePaths {
   const home = resolveControllerHome(controllerHome);
   const serviceRoot = join(home, 'runtime', 'service');
-  const suffix = createHash('sha256').update(home).digest('hex').slice(0, 12);
-  const label = `com.moretea.forge.runtime.${suffix}`;
+  const label = forgeRuntimePersistentServiceLabel(home);
   const launchAgentsRoot = join(process.env.HOME ?? homedir(), 'Library', 'LaunchAgents');
   return {
     controllerHome: home,
@@ -58,52 +56,51 @@ export function forgeRuntimeServicePaths(controllerHome: string): ForgeRuntimeSe
   };
 }
 
-export function validateForgeRuntimeServiceConfig(input: ForgeRuntimeServiceConfig): ForgeRuntimeServiceConfig {
+export interface ForgeRuntimeServiceConfigValidationOptions {
+  /** A materialized immutable release may discard a stale development repository overlay. */
+  missingRepositoryRoot?: 'error' | 'omit';
+}
+
+export function validateForgeRuntimeServiceConfig(
+  input: ForgeRuntimeServiceConfig,
+  options: ForgeRuntimeServiceConfigValidationOptions = {},
+): ForgeRuntimeServiceConfig {
   if (input.schemaVersion !== 1) throw new Error('FORGE_RUNTIME_SERVICE_CONFIG_VERSION_UNSUPPORTED');
   const controllerHome = resolve(input.controllerHome);
-  const repositoryRoot = input.repositoryRoot?.trim() ? resolve(input.repositoryRoot) : undefined;
+  const configuredRepositoryRoot = input.repositoryRoot?.trim() ? resolve(input.repositoryRoot) : undefined;
+  const repositoryRoot = configuredRepositoryRoot && existsSync(configuredRepositoryRoot) ? configuredRepositoryRoot : undefined;
   const authTokenFile = resolve(input.authTokenFile);
   if (!input.host.trim()) throw new Error('FORGE_RUNTIME_SERVICE_HOST_REQUIRED');
   if (!Number.isInteger(input.port) || input.port < 1 || input.port > 65_535) throw new Error('FORGE_RUNTIME_SERVICE_PORT_INVALID');
-  if (repositoryRoot && !existsSync(repositoryRoot)) throw new Error(`FORGE_RUNTIME_SERVICE_REPOSITORY_MISSING: ${repositoryRoot}`);
+  if (configuredRepositoryRoot && !repositoryRoot && options.missingRepositoryRoot !== 'omit') {
+    throw new Error(`FORGE_RUNTIME_SERVICE_REPOSITORY_MISSING: ${configuredRepositoryRoot}`);
+  }
   if (!existsSync(authTokenFile)) throw new Error(`FORGE_RUNTIME_SERVICE_AUTH_TOKEN_MISSING: ${authTokenFile}`);
+  const { repositoryRoot: _configuredRepositoryRoot, ...rest } = input;
   return {
-    ...input,
+    ...rest,
     controllerHome,
     ...(repositoryRoot ? { repositoryRoot } : {}),
     host: input.host.trim(),
     authTokenFile,
-    ...(input.exclusiveWorkId?.trim() ? { exclusiveWorkId: input.exclusiveWorkId.trim() } : {}),
+    topology: normalizeRuntimeDeploymentTopology(input.topology),
   };
 }
 
-export function readForgeRuntimeServiceConfig(path: string): ForgeRuntimeServiceConfig {
-  return validateForgeRuntimeServiceConfig(JSON.parse(readFileSync(resolve(path), 'utf8')) as ForgeRuntimeServiceConfig);
+export function readForgeRuntimeServiceConfig(
+  path: string,
+  options: ForgeRuntimeServiceConfigValidationOptions = {},
+): ForgeRuntimeServiceConfig {
+  return validateForgeRuntimeServiceConfig(JSON.parse(readFileSync(resolve(path), 'utf8')) as ForgeRuntimeServiceConfig, options);
 }
 
 interface RuntimeReleaseAuthorityRecord {
-  schemaVersion: 1;
+  schemaVersion: 2;
   status: string;
   active?: { releaseId?: string; manifestPath?: string; artifactIdentity?: string };
 }
 
-interface RuntimeReleaseManifestRecord {
-  schemaVersion: 1;
-  releaseId: string;
-  entrypoint: string;
-  controllerHome: string;
-  artifactIdentity: string;
-  arguments?: string[];
-  diagnosticEntrypoint?: string;
-  packageRoot?: string;
-  packageArtifactIdentity?: string;
-  browserAutomationHelperEntrypoint?: string;
-  browserAutomationHelperArtifactIdentity?: string;
-  browserAutomationHelperContractIdentity?: string;
-  releaseRevision?: string;
-  sourceCommit?: string;
-  cleanWorkspace?: boolean;
-}
+type RuntimeReleaseManifestRecord = RuntimeReleaseManifest;
 
 interface ActiveRuntimeReleaseRecord {
   releaseId: string;
@@ -130,14 +127,13 @@ function readActiveRuntimeRelease(controllerHome: string): ActiveRuntimeReleaseR
   if (!existsSync(authorityPath)) return undefined;
   const authority = JSON.parse(readFileSync(authorityPath, 'utf8')) as RuntimeReleaseAuthorityRecord;
   const active = authority.active;
-  if (authority.schemaVersion !== 1 || authority.status !== 'committed' || !active?.manifestPath) {
+  if (authority.schemaVersion !== 2 || authority.status !== 'committed' || !active?.manifestPath) {
     throw new Error('FORGE_RUNTIME_RELEASE_AUTHORITY_INVALID');
   }
   const manifestPath = resolve(active.manifestPath);
   if (!isInside(releasesRoot, manifestPath)) throw new Error('FORGE_RUNTIME_RELEASE_MANIFEST_OUTSIDE_RELEASES');
-  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as RuntimeReleaseManifestRecord;
+  const manifest = loadRuntimeReleaseManifest(manifestPath, home);
   if (manifest.schemaVersion !== 1 || !manifest.releaseId || !manifest.entrypoint) throw new Error('FORGE_RUNTIME_RELEASE_MANIFEST_INVALID');
-  if (resolve(manifest.controllerHome) !== home) throw new Error('FORGE_RUNTIME_RELEASE_CONTROLLER_HOME_MISMATCH');
   if (active.releaseId && active.releaseId !== manifest.releaseId) throw new Error('FORGE_RUNTIME_RELEASE_ID_MISMATCH');
   const releaseRoot = dirname(manifestPath);
   const entrypoint = resolve(releaseRoot, manifest.entrypoint);
@@ -192,11 +188,96 @@ async function retireLegacyBrowserAutomationLaunchAgent(controllerHome: string):
   rmSync(legacy.installedPlistPath, { force: true });
 }
 
+/**
+ * Read the previously installed exact launchd contract only when config.json
+ * cannot be validated. Both canonical source and installed contracts must be
+ * identical and must still identify the active immutable Runtime release.
+ * A stale/mismatched plist never supplies a guessed listener port.
+ */
+function verifiedRuntimeLaunchdContract(controllerHome: string): { port: number; args: string[] } | undefined {
+  try {
+    const paths = forgeRuntimeServicePaths(controllerHome);
+    const active = readActiveRuntimeRelease(paths.controllerHome);
+    if (!active || !activeRuntimeEntrypoint(paths.controllerHome)) return undefined;
+    if (!existsSync(paths.sourcePlistPath) || !existsSync(paths.installedPlistPath)) return undefined;
+    if (statSync(paths.sourcePlistPath).size > 128 * 1024 || statSync(paths.installedPlistPath).size > 128 * 1024) return undefined;
+    const source = readFileSync(paths.sourcePlistPath, 'utf8');
+    if (source !== readFileSync(paths.installedPlistPath, 'utf8')) return undefined;
+    const parseXmlString = (raw: string): string | undefined => {
+      if (/&(?!(?:amp|lt|gt|quot|apos);)/.test(raw) || /[<>]/.test(raw)) return undefined;
+      return raw.replace(/&(amp|lt|gt|quot|apos);/g, (_, entity: string) =>
+        ({ amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" })[entity] ?? '');
+    };
+    const label = /<key>Label<\/key>\s*<string>([^<]*)<\/string>/.exec(source);
+    if (!label || parseXmlString(label[1]!) !== paths.label) return undefined;
+    const program = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(source);
+    if (!program) return undefined;
+    const args: string[] = [];
+    const text = program[1]!;
+    const itemPattern = /\s*<string>([^<]*)<\/string>\s*/g;
+    let cursor = 0;
+    for (let match = itemPattern.exec(text); match; match = itemPattern.exec(text)) {
+      if (match.index !== cursor) return undefined;
+      const value = parseXmlString(match[1]!);
+      if (value === undefined) return undefined;
+      args.push(value);
+      cursor = itemPattern.lastIndex;
+    }
+    if (cursor !== text.length || args[0] !== resolve(paths.activeEntrypointPath)) return undefined;
+    const exactValue = (flag: string): string | undefined => {
+      const indices = args.flatMap((arg, index) => arg === flag ? [index] : []);
+      return indices.length === 1 ? args[indices[0]! + 1] : undefined;
+    };
+    if (exactValue('--controller-home') !== paths.controllerHome
+      || exactValue('--release-manifest') !== resolve(active.manifestPath)) return undefined;
+    const portString = exactValue('--port');
+    if (!portString || !/^[1-9]\d{0,4}$/.test(portString)) return undefined;
+    const port = Number(portString);
+    return port <= 65_535 ? { port, args } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read-only projection of the original installed launchd contract. */
+export function verifiedRuntimePortFromLaunchdContract(controllerHome: string): number | undefined {
+  return verifiedRuntimeLaunchdContract(controllerHome)?.port;
+}
+
+/** Use the one existing config writer only after service and listener quiescence. */
+export function restoreRuntimeConfigFromVerifiedLaunchdContract(controllerHome: string): boolean {
+  const proven = verifiedRuntimeLaunchdContract(controllerHome);
+  if (!proven) return false;
+  const arg = (flag: string): string | undefined => {
+    const indices = proven.args.flatMap((value, index) => value === flag ? [index] : []);
+    return indices.length === 1 ? proven.args[indices[0]! + 1] : undefined;
+  };
+  const host = arg('--host');
+  const authTokenFile = arg('--auth-token-file');
+  if (!host || !authTokenFile) return false;
+  try {
+    const topologyString = arg('--deployment-topology');
+    const topology = topologyString ? JSON.parse(topologyString) as RuntimeDeploymentTopology : undefined;
+    writeForgeRuntimeServiceConfig({
+      schemaVersion: 1,
+      controllerHome: forgeRuntimeServicePaths(controllerHome).controllerHome,
+      host,
+      port: proven.port,
+      authTokenFile,
+      ...(arg('--repo') ? { repositoryRoot: arg('--repo') } : {}),
+      ...(topology ? { topology } : {}),
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLaunchSpec | undefined {
   const home = resolveControllerHome(controllerHome);
   const active = readActiveRuntimeRelease(home);
   if (!active) return undefined;
-  const config = readForgeRuntimeServiceConfig(forgeRuntimeServicePaths(home).configPath);
+  const config = readForgeRuntimeServiceConfig(forgeRuntimeServicePaths(home).configPath, { missingRepositoryRoot: 'omit' });
   if (config.controllerHome !== home) throw new Error('FORGE_RUNTIME_SERVICE_HOME_MISMATCH');
   const manifestArguments = active.manifest.arguments ?? [];
   if (!Array.isArray(manifestArguments) || !manifestArguments.every((argument) => typeof argument === 'string')) {
@@ -209,6 +290,7 @@ export function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLa
     throw new Error('FORGE_RUNTIME_RELEASE_DIAGNOSTIC_ENTRYPOINT_INVALID');
   }
   const productVersion = activeRuntimeProductVersion(active);
+  const topology = normalizeRuntimeDeploymentTopology(config.topology);
   return {
     args: [
       '--controller-home', home,
@@ -217,8 +299,8 @@ export function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLa
       '--host', config.host,
       '--port', String(config.port),
       '--auth-token-file', config.authTokenFile,
+      '--deployment-topology', JSON.stringify(topology),
       ...manifestArguments,
-      ...(config.exclusiveWorkId ? ['--exclusive-work-id', config.exclusiveWorkId] : []),
     ],
     environment: {
       FORGE_CONTROLLER_HOME: home,
@@ -343,8 +425,8 @@ export function ensureForgeRuntimeLaunchAgentContract(
     ? 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);
+  if (existingSource !== desired.plist) writeAtomicTextFile(desired.paths.sourcePlistPath, desired.plist);
+  if (input.installUserLaunchAgent === true && existingInstalled !== desired.plist) writeAtomicTextFile(desired.paths.installedPlistPath, desired.plist, 0o644);
   return { paths: desired.paths, mode: desired.mode, changed };
 }
 
@@ -364,7 +446,7 @@ export function writeForgeRuntimeServiceConfig(input: ForgeRuntimeServiceConfig)
   const config = validateForgeRuntimeServiceConfig(input);
   const paths = forgeRuntimeServicePaths(config.controllerHome);
   mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
-  atomicWrite(paths.configPath, `${JSON.stringify(config, null, 2)}\n`);
+  writeAtomicTextFile(paths.configPath, `${JSON.stringify(config, null, 2)}\n`);
   return { config, paths };
 }
 

package/src/runtime/root/status.ts

@@ -7,6 +7,7 @@ import { readRuntimeOwner } from './ownership';
 import type {
   RuntimeDiagnosticEvidence,
   RuntimeReadiness,
+  RuntimeStartupFailureEvidence,
   RuntimeStatusObservation,
   RuntimeStatusSnapshot,
 } from './types';
@@ -15,6 +16,53 @@ export function runtimeStatusPath(controllerHome: string): string {
   return join(resolveControllerHome(controllerHome), 'runtime', 'status.json');
 }
 
+export function runtimeStartupFailurePath(controllerHome: string): string {
+  return join(resolveControllerHome(controllerHome), 'runtime', 'startup-failure.json');
+}
+
+function validStartupFailure(value: unknown): value is RuntimeStartupFailureEvidence {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const evidence = value as RuntimeStartupFailureEvidence;
+  return evidence.schemaVersion === 1
+    && typeof evidence.runtimeInstanceId === 'string'
+    && evidence.runtimeInstanceId.length > 0
+    && typeof evidence.stage === 'string'
+    && evidence.stage.length > 0
+    && typeof evidence.reasonCode === 'string'
+    && evidence.reasonCode.length > 0
+    && (evidence.message === undefined || typeof evidence.message === 'string')
+    && (evidence.releaseId === undefined || typeof evidence.releaseId === 'string')
+    && (evidence.artifactIdentity === undefined || typeof evidence.artifactIdentity === 'string')
+    && Number.isFinite(Date.parse(evidence.observedAt));
+}
+
+export function writeRuntimeStartupFailureEvidence(
+  controllerHome: string,
+  evidence: RuntimeStartupFailureEvidence,
+): void {
+  if (!validStartupFailure(evidence)) throw new Error('RUNTIME_STARTUP_FAILURE_EVIDENCE_INVALID');
+  const path = runtimeStartupFailurePath(controllerHome);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(evidence, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+export function readRuntimeStartupFailureEvidence(controllerHome: string): RuntimeStartupFailureEvidence | undefined {
+  const path = runtimeStartupFailurePath(controllerHome);
+  if (!existsSync(path)) return undefined;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+    return validStartupFailure(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function removeRuntimeStartupFailureEvidence(controllerHome: string): void {
+  try { unlinkSync(runtimeStartupFailurePath(controllerHome)); } catch { /* already absent */ }
+}
+
 function validDiagnostic(value: unknown): value is RuntimeDiagnosticEvidence {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
   const diagnostic = value as RuntimeDiagnosticEvidence;

package/src/runtime/root/types.ts

@@ -28,6 +28,18 @@ export interface RuntimeExitEvidence {
   message?: string;
 }
 
+/** Latest failed startup attempt only. Diagnostic evidence, never lifecycle authority. */
+export interface RuntimeStartupFailureEvidence {
+  schemaVersion: 1;
+  runtimeInstanceId: string;
+  stage: string;
+  reasonCode: string;
+  message?: string;
+  releaseId?: string;
+  artifactIdentity?: string;
+  observedAt: string;
+}
+
 export interface RuntimeReleaseManifest {
   schemaVersion: 1;
   releaseId: string;
@@ -35,19 +47,32 @@ export interface RuntimeReleaseManifest {
   entrypoint: 'forge-runtime';
   /** Explicit execution contract for compiled immutable releases. Absent means legacy/package launcher semantics. */
   executionMode?: 'standalone-binary';
-  /** Immutable Runtime payload loaded by the small signed compiled entrypoint. */
+  /** Immutable Runtime payload executed by the release-owned Bun interpreter. */
   runtimeBundleEntrypoint?: 'forge-runtime-bundle.js';
   runtimeBundleArtifactIdentity?: string;
+  /** Release-owned interpreter used only for the long-lived Runtime bundle. */
+  runtimeInterpreterEntrypoint?: 'forge-runtime-bun' | 'forge-runtime-bun.exe';
+  runtimeInterpreterArtifactIdentity?: string;
   diagnosticEntrypoint?: 'forge-cli';
   diagnosticArtifactIdentity?: string;
+  connectorEntrypoint?: 'forge-mcp-gateway';
+  connectorArtifactIdentity?: string;
   browserNodeBridgeEntrypoint?: 'browser-node-bridge-host.js';
   browserNodeBridgeArtifactIdentity?: string;
   browserHandoffEntrypoint?: 'browser-handoff-host.js';
   browserHandoffArtifactIdentity?: string;
+  workflowSupervisorNativeHostEntrypoint?: 'forge-workflow-supervisor-native-host';
+  workflowSupervisorNativeHostArtifactIdentity?: string;
   processRunnerEntrypoint?: 'process-runner.js';
   processRunnerArtifactIdentity?: string;
   checkRunnerEntrypoint?: 'forge-check-runner';
   checkRunnerArtifactIdentity?: string;
+  /** Disposable TypeScript LanguageService process; never retained by the canonical Runtime. */
+  typescriptNavigationEntrypoint?: 'forge-typescript-navigation';
+  typescriptNavigationArtifactIdentity?: string;
+  /** Disposable Context Plane materialization process; keeps allocator-heavy retrieval out of the canonical Runtime. */
+  contextPackEntrypoint?: 'forge-context-pack';
+  contextPackArtifactIdentity?: string;
   schedulerWorkerEntrypoint?: 'forge-scheduler-worker';
   schedulerWorkerArtifactIdentity?: string;
   periodicCleanupEntrypoint?: 'forge-periodic-cleanup';
@@ -59,19 +84,16 @@ export interface RuntimeReleaseManifest {
   browserAutomationHelperEntrypoint?: 'browser-automation-helper';
   browserAutomationHelperArtifactIdentity?: string;
   browserAutomationHelperContractIdentity?: string;
-  codeGraphNodeEntrypoint?: 'codegraph-node';
-  codeGraphNodeArtifactIdentity?: string;
-  codeGraphSidecarEntrypoint?: 'codegraph-sidecar.cjs';
-  codeGraphSidecarArtifactIdentity?: string;
-  codeGraphLibraryRoot?: 'codegraph-lib';
-  codeGraphLibraryArtifactIdentity?: string;
   packageRoot?: 'package';
   packageArtifactIdentity?: string;
   controllerUiRoot?: 'ui-dist';
   controllerUiArtifactIdentity?: string;
   arguments: string[];
   configurationSchemaVersion: 1;
-  controllerHome: string;
+  /** Compiled releases are portable artifacts. Legacy package releases bind through controllerHome. */
+  deploymentScope?: 'portable';
+  /** Legacy/package deployment binding only. Portable compiled artifacts omit this field. */
+  controllerHome?: string;
   databaseSchemaCompatibility: {
     minimum: number;
     maximum: number;
@@ -93,9 +115,10 @@ export interface CanonicalRuntimeConfig {
   host: string;
   port: number;
   authToken: string;
-  exclusiveWorkId?: string;
   runtimeInstanceId?: string;
   schedulerReadyTimeoutMs?: number;
+  /** Product-level component composition; missing means a legacy ChatGPT-capable installation. */
+  topology?: import('./deployment-topology').RuntimeDeploymentTopology;
 }
 
 export interface RuntimeStatusSnapshot {