@moretea-labs/forge 1.5.0-rc.1 → 1.5.0

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

@@ -0,0 +1,172 @@
+import { spawn, spawnSync, type SpawnSyncReturns } from 'child_process';
+import { closeSync, mkdirSync, openSync, renameSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join, resolve } from 'path';
+import { resolveControllerHome } from '../../cli/repositories/controller-home';
+import { RUNTIME_WRITE_CLAIM_ENV } from './write-fence';
+import {
+  activeRuntimeEntrypoint,
+  activeRuntimeLaunchSpec,
+  forgeRuntimeServicePaths,
+  installForgeRuntimeService,
+  syncForgeRuntimeActiveEntrypoint,
+  writeForgeRuntimeServiceConfig,
+  type ForgeRuntimeServiceConfig,
+} from './service';
+import { materializePackageRuntimeRelease, type PackageRuntimeRelease } from './package-runtime-release';
+
+export type PackageRuntimeServiceMode = 'launchd' | 'systemd-user' | 'portable';
+
+export interface PackageRuntimeServiceInstallResult {
+  status: 'installed';
+  mode: PackageRuntimeServiceMode;
+  persistent: boolean;
+  controllerHome: string;
+  release: PackageRuntimeRelease;
+  servicePath?: string;
+  pid?: number;
+  warnings: string[];
+}
+
+export interface PackageRuntimeServiceOptions {
+  controllerHome?: string;
+  packageRoot?: string;
+  host?: string;
+  port?: number;
+  authTokenFile: string;
+  exclusiveWorkId?: string;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  forcePortable?: boolean;
+}
+
+function atomicWrite(path: string, content: string, mode = 0o600): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, content, { encoding: 'utf8', mode });
+  renameSync(temporary, path);
+}
+
+function systemdEscape(value: string): string {
+  return `"${value.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+export function renderForgeRuntimeSystemdUserUnit(input: {
+  description?: string;
+  executable: string;
+  args: string[];
+  environment: Record<string, string>;
+}): string {
+  const environment = Object.entries(input.environment)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, value]) => `Environment=${systemdEscape(`${key}=${value}`)}`)
+    .join('\n');
+  return [
+    '[Unit]',
+    `Description=${input.description ?? 'Forge Runtime'}`,
+    'After=network-online.target',
+    '',
+    '[Service]',
+    'Type=simple',
+    `ExecStart=${[input.executable, ...input.args].map(systemdEscape).join(' ')}`,
+    ...(environment ? [environment] : []),
+    'Restart=on-failure',
+    'RestartSec=5',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+function commandSucceeded(command: string, args: string[], env: NodeJS.ProcessEnv): SpawnSyncReturns<string> {
+  return spawnSync(command, args, { encoding: 'utf8', env, timeout: 30_000 });
+}
+
+export function systemdUserAvailable(env: NodeJS.ProcessEnv = process.env): boolean {
+  const result = commandSucceeded('systemctl', ['--user', 'show-environment'], env);
+  return result.status === 0;
+}
+
+function cleanRuntimeInstallerEnvironment(env: NodeJS.ProcessEnv, releaseEnvironment: Record<string, string>): NodeJS.ProcessEnv {
+  const next = { ...env };
+  for (const key of Object.values(RUNTIME_WRITE_CLAIM_ENV)) delete next[key];
+  delete next.FORGE_CONTROLLER_LIFECYCLE_OWNER;
+  delete next.FORGE_RELEASE_PATH;
+  delete next.FORGE_RELEASE_REVISION;
+  delete next.FORGE_RELEASE_SOURCE_COMMIT;
+  delete next.FORGE_RELEASE_CLEAN_WORKSPACE;
+  return { ...next, ...releaseEnvironment };
+}
+
+function installSystemdUserService(controllerHome: string, env: NodeJS.ProcessEnv): string {
+  const entrypoint = activeRuntimeEntrypoint(controllerHome);
+  const launch = activeRuntimeLaunchSpec(controllerHome);
+  if (!entrypoint || !launch) throw new Error('FORGE_PACKAGE_RUNTIME_LAUNCH_SPEC_MISSING');
+  const label = forgeRuntimeServicePaths(controllerHome).label;
+  const unitName = `${label}.service`;
+  const unitPath = join(env.HOME ?? homedir(), '.config', 'systemd', 'user', unitName);
+  atomicWrite(unitPath, renderForgeRuntimeSystemdUserUnit({ executable: entrypoint, args: launch.args, environment: launch.environment }), 0o644);
+  for (const args of [['--user', 'daemon-reload'], ['--user', 'enable', '--now', unitName]]) {
+    const result = commandSucceeded('systemctl', args, env);
+    if (result.status !== 0) throw new Error(`FORGE_RUNTIME_SYSTEMD_INSTALL_FAILED: systemctl ${args.join(' ')}: ${(result.stderr || result.stdout || '').trim()}`);
+  }
+  return unitPath;
+}
+
+function startPortableRuntime(controllerHome: string, env: NodeJS.ProcessEnv): number {
+  const entrypoint = activeRuntimeEntrypoint(controllerHome);
+  const launch = activeRuntimeLaunchSpec(controllerHome);
+  if (!entrypoint || !launch) throw new Error('FORGE_PACKAGE_RUNTIME_LAUNCH_SPEC_MISSING');
+  const paths = forgeRuntimeServicePaths(controllerHome);
+  mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
+  const stdout = openSync(paths.stdoutPath, 'a', 0o600);
+  const stderr = openSync(paths.stderrPath, 'a', 0o600);
+  try {
+    const child = spawn(entrypoint, launch.args, {
+      detached: true,
+      stdio: ['ignore', stdout, stderr],
+      env: cleanRuntimeInstallerEnvironment(env, launch.environment),
+    });
+    if (!child.pid) throw new Error('FORGE_PORTABLE_RUNTIME_START_FAILED: child pid unavailable');
+    child.unref();
+    atomicWrite(join(paths.serviceRoot, 'portable.json'), `${JSON.stringify({ schemaVersion: 1, pid: child.pid, startedAt: new Date().toISOString() }, null, 2)}\n`);
+    return child.pid;
+  } finally {
+    closeSync(stdout);
+    closeSync(stderr);
+  }
+}
+
+export async function installPackageRuntimeService(options: PackageRuntimeServiceOptions): Promise<PackageRuntimeServiceInstallResult> {
+  const controllerHome = resolveControllerHome(options.controllerHome);
+  const release = materializePackageRuntimeRelease({ controllerHome, packageRoot: options.packageRoot });
+  const config: ForgeRuntimeServiceConfig = {
+    schemaVersion: 1,
+    controllerHome,
+    repositoryRoot: release.packageRoot,
+    host: options.host ?? '127.0.0.1',
+    port: options.port ?? 8765,
+    authTokenFile: resolve(options.authTokenFile),
+    ...(options.exclusiveWorkId?.trim() ? { exclusiveWorkId: options.exclusiveWorkId.trim() } : {}),
+  };
+  writeForgeRuntimeServiceConfig(config);
+  syncForgeRuntimeActiveEntrypoint(controllerHome);
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  if (!options.forcePortable && platform === 'darwin') {
+    const paths = await installForgeRuntimeService({ config, runnerPath: join(release.packageRoot, 'bin', 'forge-runtime-service.mjs'), nodeExecutable: process.execPath });
+    return { status: 'installed', mode: 'launchd', persistent: true, controllerHome, release, servicePath: paths.installedPlistPath, warnings: [] };
+  }
+  if (!options.forcePortable && platform === 'linux' && systemdUserAvailable(env)) {
+    const unitPath = installSystemdUserService(controllerHome, env);
+    return { status: 'installed', mode: 'systemd-user', persistent: true, controllerHome, release, servicePath: unitPath, warnings: [] };
+  }
+  const pid = startPortableRuntime(controllerHome, env);
+  return {
+    status: 'installed', mode: 'portable', persistent: false, controllerHome, release, pid,
+    warnings: [platform === 'win32'
+      ? 'Native Windows is preview: Forge started a detached user process for this session; automatic login/reboot persistence is not yet claimed.'
+      : 'systemd --user is unavailable: Forge started a detached user process; enable a user service manager for reboot persistence.'],
+  };
+}

package/src/runtime/root/runtime.ts

@@ -228,11 +228,12 @@ export class CanonicalForgeRuntime {
         port: this.config.port,
         authToken: this.config.authToken,
         readiness: () => this.readiness(),
-        createServer: (principalId, sessionId) => createRuntimeGatewayServer(this.controller!, principalId, {
+        createServer: (principalId, sessionId, controllerType) => createRuntimeGatewayServer(this.controller!, principalId, {
           controllerHome: this.config.controllerHome,
           runtimeInstanceId: this.runtimeInstanceId,
           runtimeSourceRoot,
           sessionId,
+          controllerType,
         }),
         onFatal: (error) => this.failCore('MCP_TRANSPORT_FAILED', error.message),
       });

package/src/runtime/root/scheduler.ts

@@ -1,4 +1,5 @@
 import { GlobalScheduler, readSchedulerHealthSnapshot } from '../control-plane/global-scheduler/scheduler';
+import { applyPendingContinuationActivations } from '../workflow/schedules/pending-activation';
 
 export interface RuntimeSchedulerHandle {
   ready: Promise<void>;
@@ -34,6 +35,10 @@ export function startInProcessScheduler(
   readyTimeoutMs = 5_000,
 ): RuntimeSchedulerHandle {
   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
+  // sole Scheduler starts, so no second scheduler or rollout hook is required.
+  applyPendingContinuationActivations(controllerHome);
   const startedAfterMs = Date.now();
   const scheduler = new GlobalScheduler(controllerHome, {}, {
     controllerPid: process.pid,

package/src/runtime/root/service.ts

@@ -97,6 +97,7 @@ interface RuntimeReleaseManifestRecord {
   controllerHome: string;
   artifactIdentity: string;
   arguments?: string[];
+  diagnosticEntrypoint?: string;
   browserAutomationHelperEntrypoint?: string;
   browserAutomationHelperArtifactIdentity?: string;
   browserAutomationHelperContractIdentity?: string;
@@ -113,7 +114,7 @@ interface ActiveRuntimeReleaseRecord {
   manifest: RuntimeReleaseManifestRecord;
 }
 
-interface ActiveRuntimeLaunchSpec {
+export interface ActiveRuntimeLaunchSpec {
   args: string[];
   environment: Record<string, string>;
 }
@@ -168,7 +169,7 @@ async function retireLegacyBrowserAutomationLaunchAgent(controllerHome: string):
   rmSync(legacy.installedPlistPath, { force: true });
 }
 
-function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLaunchSpec | undefined {
+export function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLaunchSpec | undefined {
   const home = resolveControllerHome(controllerHome);
   const active = readActiveRuntimeRelease(home);
   if (!active) return undefined;
@@ -178,6 +179,12 @@ function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLaunchSpe
   if (!Array.isArray(manifestArguments) || !manifestArguments.every((argument) => typeof argument === 'string')) {
     throw new Error('FORGE_RUNTIME_RELEASE_ARGUMENTS_INVALID');
   }
+  const diagnosticEntrypoint = typeof active.manifest.diagnosticEntrypoint === 'string' && active.manifest.diagnosticEntrypoint.trim()
+    ? resolve(active.releaseRoot, active.manifest.diagnosticEntrypoint)
+    : undefined;
+  if (diagnosticEntrypoint && (!isInside(active.releaseRoot, diagnosticEntrypoint) || !existsSync(diagnosticEntrypoint))) {
+    throw new Error('FORGE_RUNTIME_RELEASE_DIAGNOSTIC_ENTRYPOINT_INVALID');
+  }
   return {
     args: [
       '--controller-home', home,
@@ -192,6 +199,7 @@ function activeRuntimeLaunchSpec(controllerHome: string): ActiveRuntimeLaunchSpe
     environment: {
       FORGE_CONTROLLER_HOME: home,
       FORGE_CONTROLLER_RUNTIME_SOURCE_ROOT: active.releaseRoot,
+      ...(diagnosticEntrypoint ? { FORGE_CLI_EXECUTABLE: diagnosticEntrypoint } : {}),
       FORGE_RELEASE_PATH: active.releaseRoot,
       FORGE_RELEASE_ID: active.releaseId,
       FORGE_RELEASE_REVISION: active.manifest.releaseRevision ?? active.releaseId,
@@ -261,12 +269,17 @@ export function renderForgeRuntimeLaunchAgent(input: { paths: ForgeRuntimeServic
   return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n  <key>Label</key>\n  <string>${xml(input.paths.label)}</string>\n  <key>ProgramArguments</key>\n  <array>\n${args.map((arg) => `    <string>${xml(arg)}</string>`).join('\n')}\n  </array>\n${environmentXml}  <key>RunAtLoad</key>\n  <true/>\n  <key>KeepAlive</key>\n  <dict>\n    <key>SuccessfulExit</key>\n    <false/>\n  </dict>\n  <key>ThrottleInterval</key>\n  <integer>5</integer>\n  <key>ProcessType</key>\n  <string>Interactive</string>\n  <key>StandardOutPath</key>\n  <string>${xml(input.paths.stdoutPath)}</string>\n  <key>StandardErrorPath</key>\n  <string>${xml(input.paths.stderrPath)}</string>\n</dict>\n</plist>\n`;
 }
 
-export async function installForgeRuntimeService(input: { config: ForgeRuntimeServiceConfig; runnerPath: string; nodeExecutable?: string }): Promise<ForgeRuntimeServicePaths> {
-  if (process.platform !== 'darwin') throw new Error('FORGE_RUNTIME_SERVICE_PLATFORM_UNSUPPORTED: launchd requires macOS');
-  const config = validateForgeRuntimeServiceConfig(input.config);
+export function writeForgeRuntimeServiceConfig(input: ForgeRuntimeServiceConfig): { config: ForgeRuntimeServiceConfig; paths: ForgeRuntimeServicePaths } {
+  const config = validateForgeRuntimeServiceConfig(input);
   const paths = forgeRuntimeServicePaths(config.controllerHome);
   mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
   atomicWrite(paths.configPath, `${JSON.stringify(config, null, 2)}\n`);
+  return { config, paths };
+}
+
+export async function installForgeRuntimeService(input: { config: ForgeRuntimeServiceConfig; runnerPath: string; nodeExecutable?: string }): Promise<ForgeRuntimeServicePaths> {
+  if (process.platform !== 'darwin') throw new Error('FORGE_RUNTIME_SERVICE_PLATFORM_UNSUPPORTED: launchd requires macOS');
+  const { config, paths } = writeForgeRuntimeServiceConfig(input.config);
   ensureForgeRuntimeLaunchAgentContract({
     controllerHome: config.controllerHome,
     bootstrapNodeExecutable: input.nodeExecutable ?? process.execPath,

package/src/runtime/standalone-recovery/core.ts

@@ -16,6 +16,12 @@ import {
 } from '../root/release-store';
 import type { RuntimeReleaseManifest } from '../root/types';
 import { createRecoveryHttpTransport, type RecoveryHttpTransport } from './http-transport';
+import {
+  migrateStoppedRepoLocalControllerHomeStorage,
+  repoLocalControllerHomeStorageNeedsMigration,
+  rollbackStoppedRepoLocalControllerHomeStorage,
+  type ControllerHomeStorageMigration,
+} from '../../cli/repositories/controller-home';
 
 /** Standalone recovery reads only canonical Runtime observation and whole-release authority. */
 export interface PublicTunnelServiceConfig {
@@ -1590,7 +1596,8 @@ export async function activateRuntimeRelease(
     audit(config, 'runtime_release_activation_candidate_invalid', { detail, ...(guard.requestId ? { requestId: guard.requestId } : {}) });
     return { ok: false, attempted: false, noOp: true, detail };
   }
-  if ((dependencies.platform ?? process.platform) !== 'darwin') {
+  const platform = dependencies.platform ?? process.platform;
+  if (platform !== 'darwin') {
     return { ok: false, attempted: false, noOp: true, detail: 'Runtime release activation currently requires the configured macOS launchd service' };
   }
   const uid = await (dependencies.currentUid ?? currentUid)();
@@ -1638,7 +1645,19 @@ export async function activateRuntimeRelease(
       });
       return { ok: false, attempted: false, noOp: true, detail, operationId } satisfies RuntimeReleaseActivationResult;
     }
+    let storageMigrationRequired = false;
+    try {
+      storageMigrationRequired = repoLocalControllerHomeStorageNeedsMigration(config.controllerHome, platform);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : 'Controller Home storage migration preflight failed';
+      audit(config, 'runtime_release_activation_storage_preflight_failed', { operationId, requestId: lockRequestId, detail });
+      return { ok: false, attempted: false, noOp: true, detail, operationId } satisfies RuntimeReleaseActivationResult;
+    }
     if (current && current.active.releaseId === candidate.manifest.releaseId) {
+      if (storageMigrationRequired) {
+        const detail = 'CONTROLLER_HOME_STORAGE_MIGRATION_REQUIRES_STAGED_RELEASE: stage a fresh immutable Runtime release so Recovery can migrate storage inside the activation transaction';
+        return { ok: false, attempted: false, noOp: true, detail, operationId } satisfies RuntimeReleaseActivationResult;
+      }
       return {
         ok: true,
         attempted: false,
@@ -1649,7 +1668,7 @@ export async function activateRuntimeRelease(
       } satisfies RuntimeReleaseActivationResult;
     }
     if (current) {
-      if (runtimeBehaviorEquivalent(current.active.manifestPath, candidate.manifestPath)) {
+      if (runtimeBehaviorEquivalent(current.active.manifestPath, candidate.manifestPath) && !storageMigrationRequired) {
         const verify = await verifyLocal(config);
         audit(config, 'runtime_release_activation_behavior_identical', {
           operationId,
@@ -1727,24 +1746,44 @@ export async function activateRuntimeRelease(
       audit(config, 'runtime_release_activation_launchd_contract_failed', { serviceTarget: service.target, operationId, detail });
       return { ok: false, attempted: true, detail, serviceTarget: service.target, verify: await verifyLocal(config) } satisfies RuntimeReleaseActivationResult;
     }
-    const started = await ensureLaunchdServiceStarted(service, runCommand);
+    let storageMigration: ControllerHomeStorageMigration | undefined;
     let after: VerifyResult;
     let activationFailureDetail: string | undefined;
-    if (!started.ok) {
-      activationFailureDetail = started.detail;
-      audit(config, 'runtime_release_activation_start_failed', { serviceTarget: service.target, operationId, detail: started.detail });
+    try {
+      storageMigration = migrateStoppedRepoLocalControllerHomeStorage(config.controllerHome, platform);
+      if (storageMigration.migrated) {
+        audit(config, 'runtime_controller_home_noindex_migrated', {
+          serviceTarget: service.target,
+          operationId,
+          logicalHome: storageMigration.logicalHome,
+          physicalHome: storageMigration.physicalHome,
+        });
+      }
+    } catch (error) {
+      activationFailureDetail = `Controller Home .noindex migration failed: ${error instanceof Error ? error.message : String(error)}`;
+      audit(config, 'runtime_controller_home_noindex_migration_failed', { serviceTarget: service.target, operationId, detail: activationFailureDetail });
+    }
+
+    if (activationFailureDetail) {
       after = await verifyLocal(config);
     } else {
-      after = await verifyPrimaryRuntimeAfterStart({
-        config,
-        timeoutMs: configuredPrimaryRuntimeService(config).postRestartVerifyTimeoutMs ?? 60_000,
-        now,
-        wait,
-        verifyLocal,
-      });
-      if (after.ok && after.releases.active?.revision === candidate.manifest.releaseId) {
-        audit(config, 'runtime_release_activation_succeeded', { serviceTarget: service.target, operationId, requestId: lockRequestId, activeRevision: after.releases.active?.revision, expectedAuthorityRevision: guard.expectedAuthorityRevision, expectedActiveReleaseId: guard.expectedActiveReleaseId });
-        return { ok: true, attempted: true, detail: 'requested Runtime release activated and passed whole-Runtime verification', serviceTarget: service.target, operationId, verify: after } satisfies RuntimeReleaseActivationResult;
+      const started = await ensureLaunchdServiceStarted(service, runCommand);
+      if (!started.ok) {
+        activationFailureDetail = started.detail;
+        audit(config, 'runtime_release_activation_start_failed', { serviceTarget: service.target, operationId, detail: started.detail });
+        after = await verifyLocal(config);
+      } else {
+        after = await verifyPrimaryRuntimeAfterStart({
+          config,
+          timeoutMs: configuredPrimaryRuntimeService(config).postRestartVerifyTimeoutMs ?? 60_000,
+          now,
+          wait,
+          verifyLocal,
+        });
+        if (after.ok && after.releases.active?.revision === candidate.manifest.releaseId) {
+          audit(config, 'runtime_release_activation_succeeded', { serviceTarget: service.target, operationId, requestId: lockRequestId, activeRevision: after.releases.active?.revision, expectedAuthorityRevision: guard.expectedAuthorityRevision, expectedActiveReleaseId: guard.expectedActiveReleaseId, controllerHomeStorageMigrated: storageMigration?.migrated === true });
+          return { ok: true, attempted: true, detail: storageMigration?.migrated ? 'requested Runtime release activated, Controller Home migrated to .noindex storage, and whole-Runtime verification passed' : 'requested Runtime release activated and passed whole-Runtime verification', serviceTarget: service.target, operationId, verify: after } satisfies RuntimeReleaseActivationResult;
+        }
       }
     }
 
@@ -1772,6 +1811,16 @@ export async function activateRuntimeRelease(
       try {
         const rollbackOperationId = `recovery-activate-runtime-rollback-${Date.now()}-${randomUUID().slice(0, 8)}`;
         const restored = rollbackRuntimeRelease(config.controllerHome, rollbackOperationId);
+        if (storageMigration?.migrated) {
+          rollbackStoppedRepoLocalControllerHomeStorage(storageMigration);
+          audit(config, 'runtime_controller_home_noindex_migration_rolled_back', {
+            serviceTarget: service.target,
+            operationId,
+            rollbackOperationId,
+            logicalHome: storageMigration.logicalHome,
+            physicalHome: storageMigration.physicalHome,
+          });
+        }
         ensureForgeRuntimeLaunchAgentContract({ controllerHome: config.controllerHome });
         const previousRevision = previousActive?.releaseId ?? '';
         const previousIdentity = previousActive?.artifactIdentity;