@moretea-labs/forge 1.5.0-rc.1

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

@@ -0,0 +1,236 @@
+import { createHash, randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { ensureControllerHome } from '../../cli/repositories/controller-home';
+import {
+  backupControlPlaneDatabase,
+  restoreControlPlaneDatabase,
+  type ControlPlaneDatabaseInspection,
+} from '../control-plane/persistence/sqlite-store';
+import { loadRuntimeReleaseManifest } from './release-manifest';
+import type { RuntimeReleaseManifest } from './types';
+
+/**
+ * Local Controller Home recovery evidence. This database contains execution
+ * state and is never part of a release artifact, source checkout, package, or
+ * manifest distributed to another user or machine.
+ */
+export interface RuntimeDatabaseBackup {
+  path: string;
+  schemaVersion: number;
+  createdAt: string;
+}
+
+export interface RuntimePublishedRelease {
+  releaseId: string;
+  artifactIdentity: string;
+  manifestPath: string;
+  manifestSha256: string;
+  workerProtocolVersion: number;
+  publishedAt: string;
+  databaseBackup?: RuntimeDatabaseBackup;
+}
+
+export interface RuntimeReleaseAuthority {
+  schemaVersion: 1;
+  status: 'committed';
+  revision: number;
+  fencingToken: string;
+  active: RuntimePublishedRelease;
+  previous?: RuntimePublishedRelease;
+  operationId: string;
+  committedAt: string;
+}
+
+export interface RuntimeReleaseStoreDependencies {
+  backupDatabase(controllerHome: string, destinationPath: string): ControlPlaneDatabaseInspection;
+  restoreDatabase(controllerHome: string, backupPath: string): ControlPlaneDatabaseInspection;
+}
+
+const DEFAULT_DEPENDENCIES: RuntimeReleaseStoreDependencies = {
+  backupDatabase: backupControlPlaneDatabase,
+  restoreDatabase: restoreControlPlaneDatabase,
+};
+
+export function runtimeReleaseAuthorityPath(controllerHome: string): string {
+  return join(ensureControllerHome(controllerHome), 'runtime', 'releases', 'authority.json');
+}
+
+/** Resolve a local operational backup path under Controller Home only. */
+function backupPath(controllerHome: string, releaseId: string, operationId: string): string {
+  const safe = `${releaseId}-${operationId}`.replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 120);
+  return join(ensureControllerHome(controllerHome), 'runtime', 'releases', 'backups', `${Date.now()}-${safe}.sqlite`);
+}
+
+function atomicWrite(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+function manifestRecord(controllerHome: string, manifestPath: string, publishedAt = new Date().toISOString()): RuntimePublishedRelease {
+  const path = resolve(manifestPath);
+  const manifest = loadRuntimeReleaseManifest(path, controllerHome);
+  const bytes = readFileSync(path);
+  return {
+    releaseId: manifest.releaseId,
+    artifactIdentity: manifest.artifactIdentity,
+    manifestPath: path,
+    manifestSha256: createHash('sha256').update(bytes).digest('hex'),
+    workerProtocolVersion: manifest.workerProtocolVersion,
+    publishedAt,
+  };
+}
+
+function validRelease(controllerHome: string, release: RuntimePublishedRelease | undefined): release is RuntimePublishedRelease {
+  if (!release || !release.releaseId || !release.artifactIdentity || !release.manifestPath || !release.manifestSha256) return false;
+  if (!Number.isInteger(release.workerProtocolVersion) || release.workerProtocolVersion < 1 || !Number.isFinite(Date.parse(release.publishedAt))) return false;
+  try {
+    const observed = manifestRecord(controllerHome, release.manifestPath, release.publishedAt);
+    return observed.releaseId === release.releaseId
+      && observed.artifactIdentity === release.artifactIdentity
+      && observed.manifestSha256 === release.manifestSha256
+      && observed.workerProtocolVersion === release.workerProtocolVersion
+      && (!release.databaseBackup || (
+        resolve(release.databaseBackup.path) === release.databaseBackup.path
+        && Number.isInteger(release.databaseBackup.schemaVersion)
+        && Number.isFinite(Date.parse(release.databaseBackup.createdAt))
+      ));
+  } catch {
+    return false;
+  }
+}
+
+export function readRuntimeReleaseAuthority(controllerHome: string): RuntimeReleaseAuthority | undefined {
+  const path = runtimeReleaseAuthorityPath(controllerHome);
+  if (!existsSync(path)) return undefined;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8')) as RuntimeReleaseAuthority;
+    if (
+      value.schemaVersion !== 1
+      || value.status !== 'committed'
+      || !Number.isInteger(value.revision)
+      || value.revision < 1
+      || !value.fencingToken
+      || !value.operationId
+      || !Number.isFinite(Date.parse(value.committedAt))
+      || !validRelease(controllerHome, value.active)
+      || (value.previous !== undefined && !validRelease(controllerHome, value.previous))
+    ) return undefined;
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeRuntimeReleaseAuthority(controllerHome: string, authority: RuntimeReleaseAuthority): RuntimeReleaseAuthority {
+  if (!validRelease(controllerHome, authority.active) || (authority.previous && !validRelease(controllerHome, authority.previous))) {
+    throw new Error('RUNTIME_RELEASE_AUTHORITY_INVALID');
+  }
+  atomicWrite(runtimeReleaseAuthorityPath(controllerHome), authority);
+  return authority;
+}
+
+function sameRelease(left: RuntimePublishedRelease, right: RuntimePublishedRelease): boolean {
+  return left.releaseId === right.releaseId
+    && left.artifactIdentity === right.artifactIdentity
+    && left.manifestSha256 === right.manifestSha256
+    && left.workerProtocolVersion === right.workerProtocolVersion;
+}
+
+export function ensureActiveRuntimeRelease(
+  controllerHome: string,
+  manifestPath: string,
+  operationId = 'runtime-start',
+): RuntimeReleaseAuthority {
+  const active = manifestRecord(controllerHome, manifestPath);
+  const current = readRuntimeReleaseAuthority(controllerHome);
+  if (current) {
+    if (!sameRelease(current.active, active)) throw new Error('RUNTIME_RELEASE_AUTHORITY_MISMATCH');
+    return current;
+  }
+  return writeRuntimeReleaseAuthority(controllerHome, {
+    schemaVersion: 1,
+    status: 'committed',
+    revision: 1,
+    fencingToken: randomUUID(),
+    active,
+    operationId,
+    committedAt: new Date().toISOString(),
+  });
+}
+
+export function publishRuntimeRelease(
+  controllerHome: string,
+  manifestPath: string,
+  operationId: string,
+  dependencies: RuntimeReleaseStoreDependencies = DEFAULT_DEPENDENCIES,
+): RuntimeReleaseAuthority {
+  if (!operationId.trim()) throw new Error('RUNTIME_RELEASE_OPERATION_ID_REQUIRED');
+  const candidate = manifestRecord(controllerHome, manifestPath);
+  const current = readRuntimeReleaseAuthority(controllerHome);
+  if (!current) return ensureActiveRuntimeRelease(controllerHome, manifestPath, operationId);
+  if (sameRelease(current.active, candidate)) return current;
+  const backup = backupPath(controllerHome, current.active.releaseId, operationId);
+  const inspection = dependencies.backupDatabase(controllerHome, backup);
+  const committedAt = new Date().toISOString();
+  return writeRuntimeReleaseAuthority(controllerHome, {
+    schemaVersion: 1,
+    status: 'committed',
+    revision: current.revision + 1,
+    fencingToken: randomUUID(),
+    active: { ...candidate, publishedAt: committedAt },
+    previous: {
+      ...current.active,
+      databaseBackup: { path: resolve(backup), schemaVersion: inspection.schemaVersion, createdAt: committedAt },
+    },
+    operationId,
+    committedAt,
+  });
+}
+
+export function rollbackRuntimeRelease(
+  controllerHome: string,
+  operationId: string,
+  dependencies: RuntimeReleaseStoreDependencies = DEFAULT_DEPENDENCIES,
+): RuntimeReleaseAuthority {
+  if (!operationId.trim()) throw new Error('RUNTIME_RELEASE_OPERATION_ID_REQUIRED');
+  const current = readRuntimeReleaseAuthority(controllerHome);
+  const target = current?.previous;
+  if (!current || !target?.databaseBackup) throw new Error('RUNTIME_PREVIOUS_RELEASE_UNAVAILABLE');
+  const currentBackup = backupPath(controllerHome, current.active.releaseId, operationId);
+  const currentInspection = dependencies.backupDatabase(controllerHome, currentBackup);
+  dependencies.restoreDatabase(controllerHome, target.databaseBackup.path);
+  const committedAt = new Date().toISOString();
+  try {
+    return writeRuntimeReleaseAuthority(controllerHome, {
+      schemaVersion: 1,
+      status: 'committed',
+      revision: current.revision + 1,
+      fencingToken: randomUUID(),
+      active: {
+        releaseId: target.releaseId,
+        artifactIdentity: target.artifactIdentity,
+        manifestPath: target.manifestPath,
+        manifestSha256: target.manifestSha256,
+        workerProtocolVersion: target.workerProtocolVersion,
+        publishedAt: committedAt,
+      },
+      previous: {
+        ...current.active,
+        databaseBackup: { path: resolve(currentBackup), schemaVersion: currentInspection.schemaVersion, createdAt: committedAt },
+      },
+      operationId,
+      committedAt,
+    });
+  } catch (error) {
+    dependencies.restoreDatabase(controllerHome, currentBackup);
+    throw error;
+  }
+}
+
+export function activeRuntimeReleaseManifest(controllerHome: string): RuntimeReleaseManifest | undefined {
+  const authority = readRuntimeReleaseAuthority(controllerHome);
+  return authority ? loadRuntimeReleaseManifest(authority.active.manifestPath, controllerHome) : undefined;
+}

package/src/runtime/root/runtime.ts

@@ -0,0 +1,318 @@
+import { randomUUID } from 'crypto';
+import { statSync } from 'fs';
+import { dirname } from 'path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { ControlPlaneDatabaseInspection } from '../control-plane/persistence/sqlite-store';
+import { inspectControlPlaneDatabase } from '../control-plane/persistence/sqlite-store';
+import { activateExclusiveWorkAdmission } from '../control-plane/facade/work-admission-policy';
+import {
+  collectRuntimeSourceIdentity,
+  rotateRuntimeGeneration,
+} from '../control-plane/runtime-generation';
+import { RuntimeControllerServices } from './controller-services';
+import { createRuntimeGatewayServer, runtimeGatewayToolSurfaceFingerprint } from './gateway-adapter';
+import { startRuntimeMcpTransport, type RuntimeMcpTransportHandle } from './mcp-transport';
+import { acquireRuntimeOwnership, type RuntimeOwnershipHandle } from './ownership';
+import { RuntimeReadinessState } from './readiness';
+import { loadRuntimeReleaseManifest } from './release-manifest';
+import { ensureActiveRuntimeRelease, type RuntimeReleaseAuthority } from './release-store';
+import { bindRuntimeWriteClaim, clearRuntimeWriteClaim } from './write-fence';
+import { startInProcessScheduler, type RuntimeSchedulerHandle } from './scheduler';
+import { startConfiguredRuntimeLocalBridge, type RuntimeLocalBridgeHandle } from './local-bridge';
+import { removeRuntimeStatusSnapshot, writeRuntimeStatusSnapshot } from './status';
+import type {
+  CanonicalRuntimeConfig,
+  RuntimeExitEvidence,
+  RuntimeReadiness,
+  RuntimeReleaseManifest,
+} from './types';
+
+export interface CanonicalRuntimeDependencies {
+  loadReleaseManifest(path: string, controllerHome: string): RuntimeReleaseManifest;
+  ensureReleaseAuthority(controllerHome: string, manifestPath: string): RuntimeReleaseAuthority;
+  bindWriteClaim(input: { controllerHome: string; owner: RuntimeOwnershipHandle['record']; authority: RuntimeReleaseAuthority }): void;
+  acquireOwnership(controllerHome: string, runtimeInstanceId: string): RuntimeOwnershipHandle;
+  inspectDatabase(controllerHome: string): ControlPlaneDatabaseInspection;
+  startScheduler(controllerHome: string, timeoutMs?: number): RuntimeSchedulerHandle;
+  startLocalBridge(input: { controllerHome: string; repositoryRoot: string }): Promise<RuntimeLocalBridgeHandle | undefined>;
+  startTransport(options: Parameters<typeof startRuntimeMcpTransport>[0]): Promise<RuntimeMcpTransportHandle>;
+  runMcpProbe(endpoint: string, authToken: string): Promise<void>;
+  collectRuntimeSourceIdentity: typeof collectRuntimeSourceIdentity;
+  rotateRuntimeGeneration: typeof rotateRuntimeGeneration;
+}
+
+async function defaultMcpProbe(endpoint: string, authToken: string): Promise<void> {
+  const transport = new StreamableHTTPClientTransport(new URL(endpoint), {
+    requestInit: { headers: { Authorization: `Bearer ${authToken}` } },
+  });
+  const client = new Client({ name: 'forge-runtime-probe', version: '1.0.0' });
+  try {
+    await client.connect(transport);
+    const tools = await client.listTools();
+    if (!tools.tools.some((tool) => tool.name === 'repository_list')) {
+      throw new Error('MCP_PROBE_TOOL_MISSING: repository_list');
+    }
+    // Probe a permanent bootstrap tool that is valid before any repository is
+    // selected or registered. Database initialization has already failed closed
+    // earlier in Runtime startup; this probe owns only MCP initialize/list/call.
+    const result = await client.callTool({ name: 'repository_list', arguments: {} });
+    if (result.isError || !result.structuredContent) {
+      throw new Error('MCP_PROBE_BOOTSTRAP_CALL_FAILED');
+    }
+  } finally {
+    await client.close().catch(() => undefined);
+  }
+}
+
+const DEFAULT_DEPENDENCIES: CanonicalRuntimeDependencies = {
+  loadReleaseManifest: loadRuntimeReleaseManifest,
+  ensureReleaseAuthority: ensureActiveRuntimeRelease,
+  bindWriteClaim: (input) => { bindRuntimeWriteClaim(input); },
+  acquireOwnership: acquireRuntimeOwnership,
+  inspectDatabase: inspectControlPlaneDatabase,
+  startScheduler: startInProcessScheduler,
+  startLocalBridge: startConfiguredRuntimeLocalBridge,
+  startTransport: startRuntimeMcpTransport,
+  runMcpProbe: defaultMcpProbe,
+  collectRuntimeSourceIdentity,
+  rotateRuntimeGeneration,
+};
+
+export class CanonicalForgeRuntime {
+  readonly runtimeInstanceId: string;
+  private readonly readinessState = new RuntimeReadinessState();
+  private readonly dependencies: CanonicalRuntimeDependencies;
+  private ownership?: RuntimeOwnershipHandle;
+  private scheduler?: RuntimeSchedulerHandle;
+  private localBridge?: RuntimeLocalBridgeHandle;
+  private toolSurfaceFingerprint?: string;
+  private transport?: RuntimeMcpTransportHandle;
+  private controller?: RuntimeControllerServices;
+  private release?: RuntimeReleaseManifest;
+  private stopPromise?: Promise<void>;
+  private stoppedResolve!: () => void;
+  private readonly stopped = new Promise<void>((resolve) => { this.stoppedResolve = resolve; });
+  private started = false;
+  private stopping = false;
+  lastExit?: RuntimeExitEvidence;
+
+  constructor(
+    readonly config: CanonicalRuntimeConfig,
+    dependencies: Partial<CanonicalRuntimeDependencies> = {},
+  ) {
+    this.runtimeInstanceId = config.runtimeInstanceId?.trim() || `runtime_${randomUUID().replaceAll('-', '')}`;
+    this.dependencies = { ...DEFAULT_DEPENDENCIES, ...dependencies };
+    if (!config.controllerHome.trim()) throw new Error('RUNTIME_CONFIG_REQUIRED: controllerHome');
+    if (!config.repositoryRoot.trim()) throw new Error('RUNTIME_CONFIG_REQUIRED: repositoryRoot');
+    try {
+      if (!statSync(config.repositoryRoot).isDirectory()) throw new Error('not a directory');
+    } catch {
+      throw new Error('RUNTIME_CONFIG_INVALID: repositoryRoot must be an existing directory');
+    }
+    if (!config.releaseManifestPath.trim()) throw new Error('RUNTIME_CONFIG_REQUIRED: releaseManifestPath');
+    if (!config.host.trim()) throw new Error('RUNTIME_CONFIG_REQUIRED: host');
+    if (!Number.isInteger(config.port) || config.port < 0 || config.port > 65_535) {
+      throw new Error('RUNTIME_CONFIG_INVALID: port');
+    }
+    if (!config.authToken.trim()) throw new Error('RUNTIME_CONFIG_REQUIRED: authToken');
+  }
+
+  readiness(): RuntimeReadiness {
+    return this.readinessState.snapshot();
+  }
+
+  private publishStatus(): void {
+    if (!this.ownership || !this.release) return;
+    try {
+      writeRuntimeStatusSnapshot(this.config.controllerHome, {
+        schemaVersion: 1,
+        runtimeInstanceId: this.runtimeInstanceId,
+        pid: this.ownership.record.pid,
+        releaseId: this.release.releaseId,
+        artifactIdentity: this.release.artifactIdentity,
+        ...(this.toolSurfaceFingerprint ? { toolSurfaceFingerprint: this.toolSurfaceFingerprint } : {}),
+        ...(this.transport?.endpoint ? { endpoint: this.transport.endpoint } : {}),
+        readiness: this.readiness(),
+        startedAt: this.ownership.record.acquiredAt,
+        updatedAt: new Date().toISOString(),
+      });
+    } catch {
+      // Status is a read-only projection. Projection failure cannot become a
+      // second Runtime readiness or lifecycle authority.
+    }
+  }
+
+  endpoint(): string | undefined {
+    return this.transport?.endpoint;
+  }
+
+  async start(): Promise<void> {
+    if (this.started) throw new Error('RUNTIME_ALREADY_STARTED');
+    this.started = true;
+    this.readinessState.markNotReady();
+    let stage: 'release' | 'ownership' | 'source' | 'database' | 'scheduler' | 'localBridge' | 'transport' | 'probe' = 'release';
+    try {
+      this.release = this.dependencies.loadReleaseManifest(this.config.releaseManifestPath, this.config.controllerHome);
+
+      stage = 'ownership';
+      this.ownership = this.dependencies.acquireOwnership(this.config.controllerHome, this.runtimeInstanceId);
+
+      stage = 'release';
+      const releaseAuthority = this.dependencies.ensureReleaseAuthority(this.config.controllerHome, this.config.releaseManifestPath);
+      stage = 'source';
+      // A materialized immutable release carries its frozen source identity in
+      // the release manifest and must snapshot that release directory. Source/
+      // fixture manifests without source identity keep the historical explicit
+      // repositoryRoot behavior so development-mode Runtime drift remains live.
+      const runtimeSourceRoot = this.release.sourceCommit && this.release.releaseRevision
+        ? dirname(this.config.releaseManifestPath)
+        : this.config.repositoryRoot;
+      const runtimeSource = this.dependencies.collectRuntimeSourceIdentity(runtimeSourceRoot);
+      this.dependencies.rotateRuntimeGeneration(this.config.controllerHome, runtimeSource);
+
+      stage = 'release';
+      this.dependencies.bindWriteClaim({
+        controllerHome: this.config.controllerHome,
+        owner: this.ownership.record,
+        authority: releaseAuthority,
+      });
+      this.readinessState.setDiagnostic('releaseCoherence', 'pass');
+      this.publishStatus();
+
+      stage = 'database';
+      this.controller = new RuntimeControllerServices(
+        this.config.controllerHome,
+        this.runtimeInstanceId,
+        this.release,
+        () => this.readiness(),
+        this.dependencies.inspectDatabase,
+      );
+      this.controller.initialize();
+      this.readinessState.setDiagnostic('database', 'pass');
+      this.publishStatus();
+      if (this.config.exclusiveWorkId) {
+        activateExclusiveWorkAdmission(this.config.controllerHome, {
+          allowedWorkId: this.config.exclusiveWorkId,
+          reason: 'P0 canonical single Runtime migration isolation',
+        });
+      }
+
+      stage = 'scheduler';
+      this.scheduler = this.dependencies.startScheduler(
+        this.config.controllerHome,
+        this.config.schedulerReadyTimeoutMs,
+      );
+      await this.scheduler.ready;
+      this.readinessState.setDiagnostic('scheduler', 'pass');
+      this.publishStatus();
+      void this.scheduler.done.then(
+        () => this.failCore('SCHEDULER_STOPPED', 'Scheduler stopped while Runtime was active.'),
+        (error) => this.failCore('SCHEDULER_STALLED', error instanceof Error ? error.message : String(error)),
+      );
+
+      stage = 'localBridge';
+      this.localBridge = await this.dependencies.startLocalBridge({
+        controllerHome: this.config.controllerHome,
+        repositoryRoot: this.config.repositoryRoot,
+      });
+
+      stage = 'transport';
+      this.toolSurfaceFingerprint = runtimeGatewayToolSurfaceFingerprint({
+        controllerHome: this.config.controllerHome,
+        runtimeInstanceId: this.runtimeInstanceId,
+        runtimeSourceRoot,
+      });
+      this.transport = await this.dependencies.startTransport({
+        host: this.config.host,
+        port: this.config.port,
+        authToken: this.config.authToken,
+        readiness: () => this.readiness(),
+        createServer: (principalId, sessionId) => createRuntimeGatewayServer(this.controller!, principalId, {
+          controllerHome: this.config.controllerHome,
+          runtimeInstanceId: this.runtimeInstanceId,
+          runtimeSourceRoot,
+          sessionId,
+        }),
+        onFatal: (error) => this.failCore('MCP_TRANSPORT_FAILED', error.message),
+      });
+      this.publishStatus();
+
+      stage = 'probe';
+      await this.dependencies.runMcpProbe(this.transport.endpoint, this.config.authToken);
+      this.readinessState.setDiagnostic('mcpEndToEnd', 'pass');
+      this.readinessState.markReady();
+      this.publishStatus();
+    } catch (error) {
+      const reason = this.startupReason(stage);
+      this.markStartupFailure(stage, reason);
+      await this.stop(reason, error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+  }
+
+  private startupReason(stage: string): string {
+    if (stage === 'release') return 'RELEASE_COHERENCE_FAILED';
+    if (stage === 'ownership') return 'RUNTIME_OWNERSHIP_CONFLICT';
+    if (stage === 'source') return 'RUNTIME_SOURCE_SNAPSHOT_FAILED';
+    if (stage === 'database') return 'DATABASE_UNAVAILABLE';
+    if (stage === 'scheduler') return 'SCHEDULER_INITIALIZATION_FAILED';
+    if (stage === 'localBridge') return 'LOCAL_BRIDGE_STARTUP_FAILED';
+    if (stage === 'transport') return 'MCP_LISTENER_FAILED';
+    return 'MCP_END_TO_END_FAILED';
+  }
+
+  private markStartupFailure(stage: string, reason: string): void {
+    if (stage === 'release' || stage === 'source') {
+      this.readinessState.setDiagnostic('releaseCoherence', 'fail', reason);
+    } else if (stage === 'database') this.readinessState.setDiagnostic('database', 'fail', reason);
+    else if (stage === 'scheduler') this.readinessState.setDiagnostic('scheduler', 'fail', reason);
+    else if (stage === 'transport' || stage === 'probe') this.readinessState.setDiagnostic('mcpEndToEnd', 'fail', reason);
+    this.readinessState.addReason(reason);
+    this.publishStatus();
+  }
+
+  private failCore(reasonCode: string, message: string): void {
+    if (this.stopping || this.lastExit) return;
+    process.stderr.write(`${JSON.stringify({
+      event: 'forge_runtime_core_failure',
+      runtimeInstanceId: this.runtimeInstanceId,
+      reasonCode,
+      message,
+      observedAt: new Date().toISOString(),
+    })}\n`);
+    if (reasonCode.startsWith('SCHEDULER_')) this.readinessState.setDiagnostic('scheduler', 'fail', reasonCode);
+    if (reasonCode.startsWith('MCP_')) this.readinessState.setDiagnostic('mcpEndToEnd', 'fail', reasonCode);
+    this.readinessState.addReason(reasonCode);
+    this.publishStatus();
+    void this.stop(reasonCode, message);
+  }
+
+  async stop(reasonCode = 'RUNTIME_STOP_REQUESTED', message?: string): Promise<void> {
+    if (this.stopPromise) return this.stopPromise;
+    this.stopPromise = (async () => {
+      this.stopping = true;
+      this.readinessState.markNotReady(reasonCode);
+      this.publishStatus();
+      // Stop accepting new MCP work before quiescing Scheduler activity, then
+      // release the Controller Home claim only after all in-process services stop.
+      await this.transport?.close().catch(() => undefined);
+      await this.localBridge?.close().catch(() => undefined);
+      await this.scheduler?.stop().catch(() => undefined);
+      const ownerPid = this.ownership?.record.pid;
+      this.ownership?.release();
+      clearRuntimeWriteClaim(this.runtimeInstanceId);
+      if (ownerPid !== undefined) {
+        removeRuntimeStatusSnapshot(this.config.controllerHome, this.runtimeInstanceId, ownerPid);
+      }
+      this.lastExit = { reasonCode, observedAt: new Date().toISOString(), ...(message ? { message } : {}) };
+      this.stopping = false;
+      this.stoppedResolve();
+    })();
+    return this.stopPromise;
+  }
+
+  waitForStopped(): Promise<void> {
+    return this.stopped;
+  }
+}

package/src/runtime/root/scheduler.ts

@@ -0,0 +1,58 @@
+import { GlobalScheduler, readSchedulerHealthSnapshot } from '../control-plane/global-scheduler/scheduler';
+
+export interface RuntimeSchedulerHandle {
+  ready: Promise<void>;
+  done: Promise<void>;
+  stop(): Promise<void>;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForSchedulerHeartbeat(
+  controllerHome: string,
+  startedAfterMs: number,
+  timeoutMs: number,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const state = readSchedulerHealthSnapshot(controllerHome);
+    const loopStartedAtMs = Date.parse(state.loopStartedAt ?? '');
+    const lastHeartbeatAtMs = Date.parse(state.lastHeartbeatAt ?? '');
+    if (Number.isFinite(loopStartedAtMs)
+      && Number.isFinite(lastHeartbeatAtMs)
+      && loopStartedAtMs >= startedAfterMs
+      && lastHeartbeatAtMs >= startedAfterMs) return;
+    await delay(25);
+  }
+  throw new Error(`SCHEDULER_INITIALIZATION_TIMEOUT: ${timeoutMs}ms`);
+}
+
+export function startInProcessScheduler(
+  controllerHome: string,
+  readyTimeoutMs = 5_000,
+): RuntimeSchedulerHandle {
+  const abort = new AbortController();
+  const startedAfterMs = Date.now();
+  const scheduler = new GlobalScheduler(controllerHome, {}, {
+    controllerPid: process.pid,
+    fatalOnTickError: true,
+  });
+  const done = scheduler.run(abort.signal);
+  const unexpectedStop = done.then(() => {
+    if (!abort.signal.aborted) throw new Error('SCHEDULER_STOPPED_UNEXPECTEDLY');
+  });
+  const ready = Promise.race([
+    waitForSchedulerHeartbeat(controllerHome, startedAfterMs, readyTimeoutMs),
+    unexpectedStop,
+  ]).then(() => undefined);
+  return {
+    ready,
+    done: unexpectedStop,
+    stop: async () => {
+      abort.abort();
+      await done.catch(() => undefined);
+    },
+  };
+}

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

@@ -0,0 +1,20 @@
+import { resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { Command } from 'commander';
+import { runForgeRuntimeService } from './service-runner';
+
+export async function runForgeRuntimeServiceCli(argv = process.argv): Promise<void> {
+  const command = new Command('forge-runtime-service')
+    .requiredOption('--controller-home <path>', 'Explicit Controller Home')
+    .requiredOption('--config <path>', 'Forge Runtime service configuration');
+  command.parse(argv);
+  const options = command.opts<{ controllerHome: string; config: string }>();
+  process.exitCode = await runForgeRuntimeService(resolve(options.controllerHome), resolve(options.config));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  runForgeRuntimeServiceCli().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}