@moretea-labs/forge 1.7.2 → 1.8.0

package/src/runtime/root/runtime.ts

@@ -1,10 +1,15 @@
 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 { mkdirSync, statSync } from 'fs';
+import { writeJsonAtomic } from '../shared/json-files';
+import { ensureForgeInstanceIdentity } from '../../../packages/kernel/identity/api/index';
+import { dirname, join } from 'path';
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 import type { ControlPlaneDatabaseInspection } from '../control-plane/persistence/sqlite-store';
-import { inspectControlPlaneDatabase } from '../control-plane/persistence/sqlite-store';
+import {
+  disableControlPlaneReadConnectionReuse,
+  enableControlPlaneReadConnectionReuse,
+  inspectControlPlaneDatabase,
+} from '../control-plane/persistence/sqlite-store';
 import { activateExclusiveWorkAdmission } from '../control-plane/facade/work-admission-policy';
 import { closeCodeGraphReadProviderSessions } from '../context/codegraph-read-provider';
 import { cancelAllLightweightProcesses } from '../execution/process-runtime/lightweight-managed';
@@ -17,27 +22,36 @@ import { createRuntimeGatewayServer, runtimeGatewayToolSurfaceFingerprint } from
 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 { loadRuntimeReleaseManifest, requireCompleteCompiledRuntimeReleaseManifest } from './release-manifest';
+import { ensureActiveRuntimeRelease, readRuntimeReleaseAuthority, 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 { startActiveExecutionPowerAssertion, type RuntimePowerAssertionHandle } from './active-execution-power-assertion';
 import { removeRuntimeStatusSnapshot, writeRuntimeStatusSnapshot } from './status';
 import type {
   CanonicalRuntimeConfig,
+  CanonicalRuntimeStatusSnapshot,
   RuntimeExitEvidence,
   RuntimeReadiness,
   RuntimeReleaseManifest,
 } from './types';
 
+export interface RuntimeReleaseAuthorityMonitor {
+  stop(): void;
+}
+
 export interface CanonicalRuntimeDependencies {
   loadReleaseManifest(path: string, controllerHome: string): RuntimeReleaseManifest;
   ensureReleaseAuthority(controllerHome: string, manifestPath: string): RuntimeReleaseAuthority;
+  readReleaseAuthority(controllerHome: string): RuntimeReleaseAuthority | undefined;
+  startReleaseAuthorityMonitor(observe: () => void): RuntimeReleaseAuthorityMonitor;
   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>;
+  startScheduler(input: Parameters<typeof startInProcessScheduler>[0]): RuntimeSchedulerHandle;
+  startLocalBridge(input: { controllerHome: string; repositoryRoot?: string }): Promise<RuntimeLocalBridgeHandle | undefined>;
+  startPowerAssertion(input: { controllerHome: string; runtimePid: number }): RuntimePowerAssertionHandle;
   startTransport(options: Parameters<typeof startRuntimeMcpTransport>[0]): Promise<RuntimeMcpTransportHandle>;
   runMcpProbe(endpoint: string, authToken: string): Promise<void>;
   collectRuntimeSourceIdentity: typeof collectRuntimeSourceIdentity;
@@ -45,6 +59,8 @@ export interface CanonicalRuntimeDependencies {
   stopLightweightProcesses(controllerHome: string): Promise<number>;
   stopContextReadHelpers(): Promise<void>;
   computeToolSurfaceFingerprint: typeof runtimeGatewayToolSurfaceFingerprint;
+  ensureForgeInstanceIdentity: typeof ensureForgeInstanceIdentity;
+  startJscSamplingProfiler(directory: string): Promise<void>;
 }
 
 async function defaultMcpProbe(endpoint: string, authToken: string): Promise<void> {
@@ -70,14 +86,31 @@ async function defaultMcpProbe(endpoint: string, authToken: string): Promise<voi
   }
 }
 
+const DEFAULT_RELEASE_AUTHORITY_MONITOR_INTERVAL_MS = 1_000;
+
+function startDefaultReleaseAuthorityMonitor(observe: () => void): RuntimeReleaseAuthorityMonitor {
+  const timer = setInterval(observe, DEFAULT_RELEASE_AUTHORITY_MONITOR_INTERVAL_MS);
+  timer.unref?.();
+  return { stop: () => clearInterval(timer) };
+}
+
+async function startDefaultJscSamplingProfiler(directory: string): Promise<void> {
+  mkdirSync(directory, { recursive: true });
+  const { startSamplingProfiler } = await import('bun:jsc');
+  startSamplingProfiler(directory);
+}
+
 const DEFAULT_DEPENDENCIES: CanonicalRuntimeDependencies = {
   loadReleaseManifest: loadRuntimeReleaseManifest,
   ensureReleaseAuthority: ensureActiveRuntimeRelease,
+  readReleaseAuthority: readRuntimeReleaseAuthority,
+  startReleaseAuthorityMonitor: startDefaultReleaseAuthorityMonitor,
   bindWriteClaim: (input) => { bindRuntimeWriteClaim(input); },
   acquireOwnership: acquireRuntimeOwnership,
   inspectDatabase: inspectControlPlaneDatabase,
   startScheduler: startInProcessScheduler,
   startLocalBridge: startConfiguredRuntimeLocalBridge,
+  startPowerAssertion: startActiveExecutionPowerAssertion,
   startTransport: startRuntimeMcpTransport,
   runMcpProbe: defaultMcpProbe,
   collectRuntimeSourceIdentity,
@@ -85,24 +118,34 @@ const DEFAULT_DEPENDENCIES: CanonicalRuntimeDependencies = {
   stopLightweightProcesses: cancelAllLightweightProcesses,
   stopContextReadHelpers: closeCodeGraphReadProviderSessions,
   computeToolSurfaceFingerprint: runtimeGatewayToolSurfaceFingerprint,
+  ensureForgeInstanceIdentity,
+  startJscSamplingProfiler: startDefaultJscSamplingProfiler,
 };
 
 export class CanonicalForgeRuntime {
+  readonly forgeInstanceId: string;
   readonly runtimeInstanceId: string;
   private readonly readinessState = new RuntimeReadinessState();
   private readonly dependencies: CanonicalRuntimeDependencies;
   private ownership?: RuntimeOwnershipHandle;
   private scheduler?: RuntimeSchedulerHandle;
   private localBridge?: RuntimeLocalBridgeHandle;
+  private powerAssertion?: RuntimePowerAssertionHandle;
   private toolSurfaceFingerprint?: string;
   private transport?: RuntimeMcpTransportHandle;
   private controller?: RuntimeControllerServices;
   private release?: RuntimeReleaseManifest;
+  private releaseAuthorityMonitor?: RuntimeReleaseAuthorityMonitor;
   private stopPromise?: Promise<void>;
   private stoppedResolve!: () => void;
   private readonly stopped = new Promise<void>((resolve) => { this.stoppedResolve = resolve; });
   private started = false;
   private stopping = false;
+  private jscHeapDiagnosticsSignalHandler?: () => void;
+  private jscHeapDiagnosticsCaptureInFlight = false;
+  private jscSamplingProfilerSignalHandler?: () => void;
+  private jscSamplingProfilerStartInFlight = false;
+  private jscSamplingProfilerStarted = false;
   lastExit?: RuntimeExitEvidence;
 
   constructor(
@@ -112,11 +155,12 @@ export class CanonicalForgeRuntime {
     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.repositoryRoot?.trim()) {
+      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');
@@ -124,17 +168,112 @@ export class CanonicalForgeRuntime {
       throw new Error('RUNTIME_CONFIG_INVALID: port');
     }
     if (!config.authToken.trim()) throw new Error('RUNTIME_CONFIG_REQUIRED: authToken');
+    this.forgeInstanceId = this.dependencies.ensureForgeInstanceIdentity({
+      controllerHome: config.controllerHome,
+      preferredInstanceId: process.env.FORGE_INSTANCE_ID?.trim(),
+    }).instanceId;
   }
 
   readiness(): RuntimeReadiness {
     return this.readinessState.snapshot();
   }
 
+  private installJscHeapDiagnosticsSignal(): void {
+    if (process.platform === 'win32' || this.jscHeapDiagnosticsSignalHandler) return;
+    const handler = () => {
+      if (this.jscHeapDiagnosticsCaptureInFlight) return;
+      this.jscHeapDiagnosticsCaptureInFlight = true;
+      void import('bun:jsc').then(({ heapStats, memoryUsage }) => {
+        const heap = heapStats();
+        const topTypes = (counts: Record<string, number>, limit: number) => Object.entries(counts)
+          .sort((left, right) => right[1] - left[1])
+          .slice(0, limit)
+          .map(([type, count]) => ({ type, count }));
+        writeJsonAtomic(join(this.config.controllerHome, 'diagnostics', 'jsc-heap.json'), {
+          schemaVersion: 1,
+          capturedAt: new Date().toISOString(),
+          pid: process.pid,
+          runtimeInstanceId: this.runtimeInstanceId,
+          releaseId: this.release?.releaseId,
+          heap: {
+            heapSize: heap.heapSize,
+            heapCapacity: heap.heapCapacity,
+            extraMemorySize: heap.extraMemorySize,
+            objectCount: heap.objectCount,
+            protectedObjectCount: heap.protectedObjectCount,
+            globalObjectCount: heap.globalObjectCount,
+            protectedGlobalObjectCount: heap.protectedGlobalObjectCount,
+            objectTypeCount: Object.keys(heap.objectTypeCounts).length,
+            protectedObjectTypeCount: Object.keys(heap.protectedObjectTypeCounts).length,
+            topObjectTypes: topTypes(heap.objectTypeCounts, 100),
+            topProtectedObjectTypes: topTypes(heap.protectedObjectTypeCounts, 50),
+          },
+          memoryUsage: memoryUsage(),
+        });
+      }).catch((error) => {
+        process.stderr.write(`${JSON.stringify({
+          event: 'forge_runtime_jsc_heap_diagnostics_failed',
+          runtimeInstanceId: this.runtimeInstanceId,
+          message: error instanceof Error ? error.message : String(error),
+          observedAt: new Date().toISOString(),
+        })}\n`);
+      }).finally(() => {
+        this.jscHeapDiagnosticsCaptureInFlight = false;
+      });
+    };
+    process.on('SIGUSR2', handler);
+    this.jscHeapDiagnosticsSignalHandler = handler;
+  }
+
+  private removeJscHeapDiagnosticsSignal(): void {
+    const handler = this.jscHeapDiagnosticsSignalHandler;
+    if (!handler) return;
+    process.off('SIGUSR2', handler);
+    this.jscHeapDiagnosticsSignalHandler = undefined;
+  }
+
+  private installJscSamplingProfilerSignal(): void {
+    if (process.platform === 'win32' || this.jscSamplingProfilerSignalHandler) return;
+    const handler = () => {
+      if (this.jscSamplingProfilerStarted || this.jscSamplingProfilerStartInFlight) return;
+      this.jscSamplingProfilerStartInFlight = true;
+      const directory = join(this.config.controllerHome, 'diagnostics', 'jsc-profile');
+      void this.dependencies.startJscSamplingProfiler(directory).then(() => {
+        this.jscSamplingProfilerStarted = true;
+        process.stderr.write(`${JSON.stringify({
+          event: 'forge_runtime_jsc_sampling_profiler_started',
+          runtimeInstanceId: this.runtimeInstanceId,
+          directory,
+          observedAt: new Date().toISOString(),
+        })}\n`);
+      }).catch((error) => {
+        process.stderr.write(`${JSON.stringify({
+          event: 'forge_runtime_jsc_sampling_profiler_failed',
+          runtimeInstanceId: this.runtimeInstanceId,
+          message: error instanceof Error ? error.message : String(error),
+          observedAt: new Date().toISOString(),
+        })}\n`);
+      }).finally(() => {
+        this.jscSamplingProfilerStartInFlight = false;
+      });
+    };
+    process.on('SIGUSR1', handler);
+    this.jscSamplingProfilerSignalHandler = handler;
+  }
+
+  private removeJscSamplingProfilerSignal(): void {
+    const handler = this.jscSamplingProfilerSignalHandler;
+    if (!handler) return;
+    process.off('SIGUSR1', handler);
+    this.jscSamplingProfilerSignalHandler = undefined;
+  }
+
   private publishStatus(): void {
     if (!this.ownership || !this.release) return;
     try {
-      writeRuntimeStatusSnapshot(this.config.controllerHome, {
+      const snapshot: CanonicalRuntimeStatusSnapshot = {
         schemaVersion: 1,
+        forgeInstanceId: this.forgeInstanceId,
         runtimeInstanceId: this.runtimeInstanceId,
         pid: this.ownership.record.pid,
         releaseId: this.release.releaseId,
@@ -144,7 +283,8 @@ export class CanonicalForgeRuntime {
         readiness: this.readiness(),
         startedAt: this.ownership.record.acquiredAt,
         updatedAt: new Date().toISOString(),
-      });
+      };
+      writeRuntimeStatusSnapshot(this.config.controllerHome, snapshot);
     } catch {
       // Status is a read-only projection. Projection failure cannot become a
       // second Runtime readiness or lifecycle authority.
@@ -166,6 +306,35 @@ export class CanonicalForgeRuntime {
     return this.transport?.endpoint;
   }
 
+  private startReleaseAuthorityMonitor(): void {
+    const release = this.release;
+    if (!release || this.releaseAuthorityMonitor) return;
+    this.releaseAuthorityMonitor = this.dependencies.startReleaseAuthorityMonitor(() => {
+      if (this.stopping || this.lastExit) return;
+      let authority: RuntimeReleaseAuthority | undefined;
+      try {
+        authority = this.dependencies.readReleaseAuthority(this.config.controllerHome);
+      } catch {
+        // A read failure or ambiguous authority is not proof that this Runtime
+        // was superseded. Existing write fencing remains authoritative.
+        return;
+      }
+      if (!authority) return;
+      const active = authority.active;
+      if (
+        active.releaseId === release.releaseId
+        && active.artifactIdentity === release.artifactIdentity
+        && active.workerProtocolVersion === release.workerProtocolVersion
+      ) return;
+      const reasonCode = 'RUNTIME_RELEASE_SUPERSEDED';
+      this.readinessState.setDiagnostic('releaseCoherence', 'fail', reasonCode);
+      this.failCore(
+        reasonCode,
+        `Active Runtime release authority changed from ${release.releaseId}/${release.artifactIdentity} to ${active.releaseId}/${active.artifactIdentity}.`,
+      );
+    });
+  }
+
   async start(): Promise<void> {
     if (this.started) throw new Error('RUNTIME_ALREADY_STARTED');
     this.started = true;
@@ -180,13 +349,27 @@ export class CanonicalForgeRuntime {
       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
+      // A compiled release is a closed execution surface. Fail before Scheduler
+      // composition if a stale/corrupt manifest omits any immutable component;
+      // standalone Runtime must never regain source/import.meta.url fallback.
+      if (this.release.executionMode === 'standalone-binary') {
+        requireCompleteCompiledRuntimeReleaseManifest(this.release);
+      }
+      // A materialized immutable release carries either a source revision or a
+      // package release revision and must snapshot that release directory.
+      // Source/fixture manifests without either identity keep the historical
+      // explicit repositoryRoot behavior so development-mode Runtime drift
+      // remains live.
+      const materializedRelease = Boolean(
+        this.release.releaseRevision
+        && (this.release.sourceCommit || this.release.releaseRevision.startsWith('package:')),
+      );
+      const runtimeSourceRoot = materializedRelease
         ? dirname(this.config.releaseManifestPath)
         : this.config.repositoryRoot;
+      if (!runtimeSourceRoot) {
+        throw new Error('RUNTIME_CONFIG_REQUIRED: repositoryRoot is required only for non-materialized development Runtime');
+      }
       const runtimeSource = this.dependencies.collectRuntimeSourceIdentity(runtimeSourceRoot);
       this.dependencies.rotateRuntimeGeneration(this.config.controllerHome, runtimeSource);
 
@@ -208,6 +391,13 @@ export class CanonicalForgeRuntime {
         this.dependencies.inspectDatabase,
       );
       this.controller.initialize();
+      // The Canonical Runtime is the only process that keeps a control-plane
+      // reader alive across operations. Writers remain short-lived WAL/CAS
+      // transactions, while CLI/tests/workers keep their existing close-on-read
+      // semantics.
+      enableControlPlaneReadConnectionReuse(this.config.controllerHome);
+      this.installJscHeapDiagnosticsSignal();
+      this.installJscSamplingProfilerSignal();
       this.readinessState.setDiagnostic('database', 'pass');
       this.publishStatus();
       if (this.config.exclusiveWorkId) {
@@ -218,10 +408,20 @@ export class CanonicalForgeRuntime {
       }
 
       stage = 'scheduler';
-      this.scheduler = this.dependencies.startScheduler(
-        this.config.controllerHome,
-        this.config.schedulerReadyTimeoutMs,
-      );
+      const standaloneReleaseRoot = this.release.executionMode === 'standalone-binary'
+        ? dirname(this.config.releaseManifestPath)
+        : undefined;
+      this.scheduler = this.dependencies.startScheduler({
+        controllerHome: this.config.controllerHome,
+        readyTimeoutMs: this.config.schedulerReadyTimeoutMs,
+        runtimeSourceRoot: standaloneReleaseRoot ? undefined : runtimeSourceRoot,
+        workerExecutable: standaloneReleaseRoot && this.release.schedulerWorkerEntrypoint
+          ? join(standaloneReleaseRoot, this.release.schedulerWorkerEntrypoint)
+          : undefined,
+        periodicCleanupExecutable: standaloneReleaseRoot && this.release.periodicCleanupEntrypoint
+          ? join(standaloneReleaseRoot, this.release.periodicCleanupEntrypoint)
+          : undefined,
+      });
       await this.scheduler.ready;
       this.readinessState.setDiagnostic('scheduler', 'pass');
       this.publishStatus();
@@ -229,6 +429,10 @@ export class CanonicalForgeRuntime {
         () => this.failCore('SCHEDULER_STOPPED', 'Scheduler stopped while Runtime was active.'),
         (error) => this.failCore('SCHEDULER_STALLED', error instanceof Error ? error.message : String(error)),
       );
+      this.powerAssertion = this.dependencies.startPowerAssertion({
+        controllerHome: this.config.controllerHome,
+        runtimePid: this.ownership.record.pid,
+      });
 
       stage = 'localBridge';
       this.localBridge = await this.dependencies.startLocalBridge({
@@ -260,6 +464,8 @@ export class CanonicalForgeRuntime {
       this.readinessState.setDiagnostic('mcpEndToEnd', 'pass');
       this.readinessState.markReady();
       this.publishStatus();
+      stage = 'release';
+      this.startReleaseAuthorityMonitor();
     } catch (error) {
       const reason = this.startupReason(stage);
       this.markStartupFailure(stage, reason);
@@ -311,6 +517,12 @@ export class CanonicalForgeRuntime {
       this.stopping = true;
       this.readinessState.markNotReady(reasonCode);
       this.publishStatus();
+      // Stop the release observer before withdrawing MCP work so no second
+      // supersession callback can race the teardown sequence.
+      try { this.releaseAuthorityMonitor?.stop(); } catch { /* cleanup is best effort */ }
+      this.releaseAuthorityMonitor = undefined;
+      this.removeJscHeapDiagnosticsSignal();
+      this.removeJscSamplingProfilerSignal();
       // 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);
@@ -318,6 +530,9 @@ export class CanonicalForgeRuntime {
       await this.dependencies.stopContextReadHelpers().catch(() => undefined);
       await this.localBridge?.close().catch(() => undefined);
       await this.scheduler?.stop().catch(() => undefined);
+      try { this.powerAssertion?.stop(); } catch { /* power assertion cleanup is best effort */ }
+      this.powerAssertion = undefined;
+      disableControlPlaneReadConnectionReuse(this.config.controllerHome);
       const ownerPid = this.ownership?.record.pid;
       this.ownership?.release();
       clearRuntimeWriteClaim(this.runtimeInstanceId);

package/src/runtime/root/scheduled-controller-composition.ts

@@ -0,0 +1,51 @@
+import {
+  bindControllerSessionBinding,
+  type ControllerBinding,
+  type ControllerHost,
+  type ControllerSession,
+} from '../../../packages/kernel/controller/api/index';
+import { createChatgptControllerHost } from '../../../adapters/chatgpt/controller-host';
+import { upsertChatgptControllerBinding } from '../../../adapters/chatgpt/controller-binding-store';
+import { getChatgptWorkConversationBinding } from '../../../adapters/chatgpt/work-conversation-binding-store';
+import { createProcessControllerHost } from '../../../adapters/controller-process/controller-host';
+import { upsertProcessControllerBinding, type ProcessControllerType } from '../../../adapters/controller-process/binding-store';
+
+// Kernel V2 composition root: Scheduler selects Kernel continuation; this file wires concrete provider adapters.
+export function ensureScheduledControllerBinding(
+  options: { controllerHome: string; repoId: string },
+  input: { workId: string; session: ControllerSession; scheduleName?: string; args: Record<string, unknown> },
+): ControllerBinding {
+  let binding: ControllerBinding;
+  if (input.session.controllerType === 'chatgpt') {
+    const durable = getChatgptWorkConversationBinding(options, input.workId);
+    binding = upsertChatgptControllerBinding(options, {
+      workId: input.workId, sessionId: input.session.sessionId,
+      browserSessionId: durable?.latestBrowserSessionId ?? (typeof input.args.browser_session_id === 'string' ? input.args.browser_session_id : undefined),
+      conversationUrl: durable?.conversationUrl ?? (typeof input.args.conversation_url === 'string' ? input.args.conversation_url : undefined),
+      title: input.scheduleName,
+      model: typeof input.args.model === 'string' ? input.args.model : 'gpt-5.6',
+      reasoning: input.args.reasoning === 'medium' || input.args.reasoning === 'xhigh' ? input.args.reasoning : 'high',
+      tabPolicy: input.args.tab_policy === 'reuse' || input.args.tab_policy === 'new' ? input.args.tab_policy : 'auto',
+      timeoutMs: typeof input.args.timeout_ms === 'number' ? input.args.timeout_ms : undefined,
+    }).binding;
+  } else if (input.session.controllerType !== 'human') {
+    binding = upsertProcessControllerBinding(options, {
+      workId: input.workId, sessionId: input.session.sessionId, controllerType: input.session.controllerType as ProcessControllerType,
+      executable: typeof input.args.executable === 'string' ? input.args.executable : undefined,
+      launchArgs: Array.isArray(input.args.launch_args) ? input.args.launch_args.map(String) : [],
+      handoffId: typeof input.args.handoff_id === 'string' ? input.args.handoff_id : undefined,
+      launchReservationMs: typeof input.args.launch_reservation_ms === 'number' ? input.args.launch_reservation_ms : undefined,
+    }).binding;
+  } else {
+    throw new Error('SCHEDULE_CONTINUATION_HUMAN_HOST_UNSUPPORTED');
+  }
+  bindControllerSessionBinding(options, { workId: input.workId, sessionId: input.session.sessionId, binding });
+  return binding;
+}
+
+export function controllerHostForScheduledBinding(
+  options: { controllerHome: string; repoId: string; repoRoot: string },
+  binding: ControllerBinding,
+): ControllerHost {
+  return binding.hostKind === 'chatgpt' ? createChatgptControllerHost(options) : createProcessControllerHost(options);
+}

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

@@ -25,7 +25,7 @@ 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),

package/src/runtime/root/service.ts

@@ -3,17 +3,13 @@ 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';
 
 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;
@@ -65,16 +61,16 @@ export function forgeRuntimeServicePaths(controllerHome: string): ForgeRuntimeSe
 export function validateForgeRuntimeServiceConfig(input: ForgeRuntimeServiceConfig): 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 repositoryRoot = input.repositoryRoot?.trim() ? resolve(input.repositoryRoot) : 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 (repositoryRoot && !existsSync(repositoryRoot)) throw new Error(`FORGE_RUNTIME_SERVICE_REPOSITORY_MISSING: ${repositoryRoot}`);
   if (!existsSync(authTokenFile)) throw new Error(`FORGE_RUNTIME_SERVICE_AUTH_TOKEN_MISSING: ${authTokenFile}`);
   return {
     ...input,
     controllerHome,
-    repositoryRoot,
+    ...(repositoryRoot ? { repositoryRoot } : {}),
     host: input.host.trim(),
     authTokenFile,
     ...(input.exclusiveWorkId?.trim() ? { exclusiveWorkId: input.exclusiveWorkId.trim() } : {}),
@@ -99,6 +95,8 @@ interface RuntimeReleaseManifestRecord {
   artifactIdentity: string;
   arguments?: string[];
   diagnosticEntrypoint?: string;
+  packageRoot?: string;
+  packageArtifactIdentity?: string;
   browserAutomationHelperEntrypoint?: string;
   browserAutomationHelperArtifactIdentity?: string;
   browserAutomationHelperContractIdentity?: string;
@@ -152,6 +150,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 +187,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 });
 }
@@ -186,10 +208,11 @@ 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);
   return {
     args: [
       '--controller-home', home,
-      '--repo', config.repositoryRoot,
+      ...(config.repositoryRoot ? ['--repo', config.repositoryRoot] : []),
       '--release-manifest', active.manifestPath,
       '--host', config.host,
       '--port', String(config.port),
@@ -203,6 +226,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 +377,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 +393,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 });