@moretea-labs/forge 1.7.2 → 1.8.1

package/src/runtime/root/scheduler.ts

@@ -30,10 +30,14 @@ async function waitForSchedulerHeartbeat(
   throw new Error(`SCHEDULER_INITIALIZATION_TIMEOUT: ${timeoutMs}ms`);
 }
 
-export function startInProcessScheduler(
-  controllerHome: string,
-  readyTimeoutMs = 5_000,
-): RuntimeSchedulerHandle {
+export function startInProcessScheduler(input: {
+  controllerHome: string;
+  readyTimeoutMs?: number;
+  runtimeSourceRoot?: string;
+  workerExecutable?: string;
+  periodicCleanupExecutable?: string;
+}): RuntimeSchedulerHandle {
+  const { controllerHome, readyTimeoutMs = 5_000 } = input;
   const abort = new AbortController();
   // Old Runtime releases ignore pending activation markers entirely. A naturally
   // restarted Runtime that contains this code consumes them once, before its
@@ -42,6 +46,10 @@ export function startInProcessScheduler(
   const startedAfterMs = Date.now();
   const scheduler = new GlobalScheduler(controllerHome, {}, {
     controllerPid: process.pid,
+    runtimeSourceRoot: input.runtimeSourceRoot,
+    workerExecutable: input.workerExecutable,
+    periodicCleanupExecutable: input.periodicCleanupExecutable,
+    isolatePeriodicCleanup: true,
     fatalOnTickError: true,
   });
   const done = scheduler.run(abort.signal);

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

@@ -4,6 +4,7 @@ import { spawn, type ChildProcess } from 'child_process';
 import { loadRuntimeReleaseManifest } from './release-manifest';
 import { readRuntimeReleaseAuthority } from './release-store';
 import { readForgeRuntimeServiceConfig } from './service';
+import { runtimeAuthorityFreeEnvironment } from '../shared/process-environment';
 
 export interface ForgeRuntimeServiceCommand {
   executable: string;
@@ -25,16 +26,15 @@ export function resolveForgeRuntimeServiceCommand(controllerHome: string, config
     executable,
     args: [
       '--controller-home', home,
-      '--repo', config.repositoryRoot,
+      ...(config.repositoryRoot ? ['--repo', config.repositoryRoot] : []),
       '--release-manifest', authority.active.manifestPath,
       '--host', config.host,
       '--port', String(config.port),
       '--auth-token-file', config.authTokenFile,
       ...activeRuntimeReleaseManifest.arguments,
-      ...(config.exclusiveWorkId ? ['--exclusive-work-id', config.exclusiveWorkId] : []),
     ],
     env: {
-      ...process.env,
+      ...runtimeAuthorityFreeEnvironment(process.env),
       FORGE_CONTROLLER_HOME: home,
       FORGE_CONTROLLER_RUNTIME_SOURCE_ROOT: releaseRoot,
       FORGE_RELEASE_PATH: releaseRoot,

package/src/runtime/root/service.ts

@@ -3,21 +3,22 @@ import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync
 import { homedir } from 'os';
 import { dirname, isAbsolute, join, relative, resolve } from 'path';
 import { resolveControllerHome } from '../../cli/repositories/controller-home';
-import {
-  bootstrapLaunchAgentWithRetryV2,
-  bootoutLaunchAgentWithRetryV2,
-  installLaunchAgent,
-  retireConflictingForgeLaunchAgents,
-} from '../../cli/controller/launch-agents';
+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;
   controllerHome: string;
-  repositoryRoot: string;
+  /** Optional default repository overlay for development/embedded repository UI. */
+  repositoryRoot?: string;
   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 {
@@ -46,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,
@@ -62,50 +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 = resolve(input.repositoryRoot);
+  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 (!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 ? { 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;
-  browserAutomationHelperEntrypoint?: string;
-  browserAutomationHelperArtifactIdentity?: string;
-  browserAutomationHelperContractIdentity?: string;
-  releaseRevision?: string;
-  sourceCommit?: string;
-  cleanWorkspace?: boolean;
-}
+type RuntimeReleaseManifestRecord = RuntimeReleaseManifest;
 
 interface ActiveRuntimeReleaseRecord {
   releaseId: string;
@@ -132,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);
@@ -152,6 +152,30 @@ export function activeRuntimeEntrypoint(controllerHome: string): string | undefi
   return readActiveRuntimeRelease(controllerHome)?.entrypoint;
 }
 
+function activeRuntimeProductVersion(active: ActiveRuntimeReleaseRecord): string | undefined {
+  const packageRoot = active.manifest.packageRoot?.trim();
+  if (!packageRoot) return undefined;
+  if (!active.manifest.packageArtifactIdentity?.trim()) {
+    throw new Error('FORGE_RUNTIME_RELEASE_PACKAGE_VERSION_UNATTESTED');
+  }
+  const packageDirectory = resolve(active.releaseRoot, packageRoot);
+  if (!isInside(active.releaseRoot, packageDirectory)) {
+    throw new Error('FORGE_RUNTIME_RELEASE_PACKAGE_ROOT_OUTSIDE_RELEASE');
+  }
+  const packagePath = join(packageDirectory, 'package.json');
+  try {
+    const status = lstatSync(packagePath);
+    if (status.isSymbolicLink() || !status.isFile()) throw new Error('not a regular file');
+    const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as { version?: unknown };
+    const version = typeof parsed.version === 'string' ? parsed.version.trim() : '';
+    if (!version) throw new Error('version is missing');
+    return version;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`FORGE_RUNTIME_RELEASE_PACKAGE_VERSION_INVALID: ${detail}`);
+  }
+}
+
 function legacyBrowserAutomationLaunchAgentPaths(controllerHome: string, accountHome = process.env.HOME ?? homedir()): { label: string; installedPlistPath: string } {
   const home = resolveControllerHome(controllerHome);
   const suffix = createHash('sha256').update(home).digest('hex').slice(0, 12);
@@ -165,7 +189,7 @@ function legacyBrowserAutomationLaunchAgentPaths(controllerHome: string, account
 async function retireLegacyBrowserAutomationLaunchAgent(controllerHome: string): Promise<void> {
   const legacy = legacyBrowserAutomationLaunchAgentPaths(controllerHome);
   if (!existsSync(legacy.installedPlistPath)) return;
-  const result = await bootoutLaunchAgentWithRetryV2({ label: legacy.label, plistPath: legacy.installedPlistPath });
+  const result = await createPlatformServiceManagerHost({ platform: 'darwin' }).bootoutLaunchd({ label: legacy.label, plistPath: legacy.installedPlistPath });
   if (!result.ok) throw new Error(`FORGE_BROWSER_AUTOMATION_LEGACY_RETIRE_FAILED: ${result.diagnostics.join('; ')}`);
   rmSync(legacy.installedPlistPath, { force: true });
 }
@@ -174,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')) {
@@ -186,16 +210,18 @@ export function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLa
   if (diagnosticEntrypoint && (!isInside(active.releaseRoot, diagnosticEntrypoint) || !existsSync(diagnosticEntrypoint))) {
     throw new Error('FORGE_RUNTIME_RELEASE_DIAGNOSTIC_ENTRYPOINT_INVALID');
   }
+  const productVersion = activeRuntimeProductVersion(active);
+  const topology = normalizeRuntimeDeploymentTopology(config.topology);
   return {
     args: [
       '--controller-home', home,
-      '--repo', config.repositoryRoot,
+      ...(config.repositoryRoot ? ['--repo', config.repositoryRoot] : []),
       '--release-manifest', active.manifestPath,
       '--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,
@@ -203,6 +229,7 @@ export function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLa
       ...(diagnosticEntrypoint ? { FORGE_CLI_EXECUTABLE: diagnosticEntrypoint } : {}),
       FORGE_RELEASE_PATH: active.releaseRoot,
       FORGE_RELEASE_ID: active.releaseId,
+      ...(productVersion ? { FORGE_BUILD_VERSION: productVersion } : {}),
       FORGE_RELEASE_REVISION: active.manifest.releaseRevision ?? active.releaseId,
       ...(active.manifest.sourceCommit ? { FORGE_RELEASE_SOURCE_COMMIT: active.manifest.sourceCommit } : {}),
       FORGE_RELEASE_CLEAN_WORKSPACE: String(active.manifest.cleanWorkspace !== false),
@@ -353,14 +380,15 @@ export async function installForgeRuntimeService(input: { config: ForgeRuntimeSe
     bootstrapRunnerPath: input.runnerPath,
   });
   await retireLegacyBrowserAutomationLaunchAgent(config.controllerHome);
-  await retireConflictingForgeLaunchAgents({
+  const serviceHost = createPlatformServiceManagerHost({ platform: 'darwin' });
+  await serviceHost.retireConflictingLaunchd({
     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 });
+  serviceHost.installLaunchd(paths.sourcePlistPath, paths.label);
+  const result = await serviceHost.bootstrapLaunchd({ label: paths.label, plistPath: paths.installedPlistPath });
   if (!result.ok) throw new Error(`FORGE_RUNTIME_SERVICE_BOOTSTRAP_FAILED: ${result.diagnostics.join('; ')}`);
   return paths;
 }
@@ -368,7 +396,7 @@ export async function installForgeRuntimeService(input: { config: ForgeRuntimeSe
 export async function uninstallForgeRuntimeService(controllerHome: string): Promise<ForgeRuntimeServicePaths> {
   if (process.platform !== 'darwin') throw new Error('FORGE_RUNTIME_SERVICE_PLATFORM_UNSUPPORTED: launchd requires macOS');
   const paths = forgeRuntimeServicePaths(controllerHome);
-  const result = await bootoutLaunchAgentWithRetryV2({ label: paths.label, plistPath: paths.installedPlistPath });
+  const result = await createPlatformServiceManagerHost({ platform: 'darwin' }).bootoutLaunchd({ label: paths.label, plistPath: paths.installedPlistPath });
   if (!result.ok) throw new Error(`FORGE_RUNTIME_SERVICE_BOOTOUT_FAILED: ${result.diagnostics.join('; ')}`);
   rmSync(paths.installedPlistPath, { force: true });
 

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;
@@ -41,6 +89,7 @@ function validSnapshot(value: unknown): value is RuntimeStatusSnapshot {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
   const snapshot = value as RuntimeStatusSnapshot;
   return snapshot.schemaVersion === 1
+    && (snapshot.forgeInstanceId === undefined || (typeof snapshot.forgeInstanceId === 'string' && snapshot.forgeInstanceId.length > 0))
     && typeof snapshot.runtimeInstanceId === 'string'
     && snapshot.runtimeInstanceId.length > 0
     && Number.isInteger(snapshot.pid)

package/src/runtime/root/types.ts

@@ -28,21 +28,55 @@ 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;
   artifactIdentity: string;
   entrypoint: 'forge-runtime';
+  /** Explicit execution contract for compiled immutable releases. Absent means legacy/package launcher semantics. */
+  executionMode?: 'standalone-binary';
+  /** 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';
+  periodicCleanupArtifactIdentity?: string;
   pluginActionSidecarEntrypoint?: 'forge-plugin-action-sidecar';
   pluginActionSidecarArtifactIdentity?: string;
   externalPluginProbeEntrypoint?: 'external-unix-socket-probe.cjs';
@@ -62,12 +96,17 @@ 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;
   };
   workerProtocolVersion: number;
+  /** Repository Registry identity of the source repository that produced this immutable release. */
+  sourceRepositoryId?: string;
   sourceCommit?: string;
   releaseRevision?: string;
   cleanWorkspace?: boolean;
@@ -76,18 +115,26 @@ export interface RuntimeReleaseManifest {
 
 export interface CanonicalRuntimeConfig {
   controllerHome: string;
-  repositoryRoot: string;
+  /** Optional real repository overlay. Packaged Runtime authority is Controller Home + release, not a repository. */
+  repositoryRoot?: string;
   releaseManifestPath: string;
   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 {
   schemaVersion: 1;
+  /**
+   * Stable installed Forge identity. Legacy/transitional read-only snapshots may
+   * omit it; the canonical Runtime writer uses CanonicalRuntimeStatusSnapshot.
+   */
+  forgeInstanceId?: string;
+  /** Ephemeral Runtime process/fencing identity. */
   runtimeInstanceId: string;
   pid: number;
   releaseId: string;
@@ -100,6 +147,11 @@ export interface RuntimeStatusSnapshot {
   updatedAt: string;
 }
 
+/** Canonical Runtime publication must always carry the stable Forge identity. */
+export interface CanonicalRuntimeStatusSnapshot extends RuntimeStatusSnapshot {
+  forgeInstanceId: string;
+}
+
 export interface RuntimeStatusObservation {
   schemaVersion: 1;
   running: boolean;