@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/root/service.ts

@@ -4,6 +4,10 @@ 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 +17,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 {
@@ -42,8 +47,7 @@ function atomicWrite(path: string, content: string, mode = 0o600): void {
 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 +62,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 +133,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);
@@ -196,7 +198,7 @@ export function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLa
   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 +211,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 +220,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,

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';
@@ -71,7 +96,10 @@ export interface RuntimeReleaseManifest {
   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 +121,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 {