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

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

@@ -0,0 +1,161 @@
+import { createHash, randomUUID } from 'crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
+import { ensureControllerHome } from '../../cli/repositories/controller-home';
+import { CONTROL_PLANE_SCHEMA_VERSION } from '../control-plane/persistence/sqlite-store';
+import { packageRuntimeSourceRoot } from '../control-plane/runtime-generation';
+import { FORGE_VERSION } from '../../version';
+import { publishRuntimeRelease, type RuntimeReleaseAuthority } from './release-store';
+import type { RuntimeReleaseManifest } from './types';
+
+export interface PackageRuntimeFileRecord {
+  path: string;
+  sha256: string;
+  bytes: number;
+}
+
+export interface PackageRuntimeRelease {
+  releaseId: string;
+  releaseRoot: string;
+  packageRoot: string;
+  packageVersion: string;
+  packageFingerprint: string;
+  artifactIdentity: string;
+  entrypointPath: string;
+  manifestPath: string;
+  indexPath: string;
+  fileCount: number;
+  authority: RuntimeReleaseAuthority;
+}
+
+const PACKAGE_RUNTIME_ROOTS = ['src', 'bin', 'assets', 'scripts'] as const;
+const PACKAGE_RUNTIME_FILES = ['package.json'] as const;
+
+function sha256(value: Buffer | string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function atomicWrite(path: string, content: string, mode = 0o600): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  writeFileSync(temporary, content, { encoding: 'utf8', mode });
+  renameSync(temporary, path);
+}
+
+function walkRegularFiles(root: string, current: string, output: string[]): void {
+  if (!existsSync(current)) return;
+  const stat = lstatSync(current);
+  if (stat.isSymbolicLink()) return;
+  if (stat.isFile()) {
+    output.push(relative(root, current).split('\\').join('/'));
+    return;
+  }
+  if (!stat.isDirectory()) return;
+  for (const entry of readdirSync(current).sort()) walkRegularFiles(root, join(current, entry), output);
+}
+
+export function packageRuntimeFileIndex(packageRoot = packageRuntimeSourceRoot()): PackageRuntimeFileRecord[] {
+  const root = resolve(packageRoot);
+  const paths: string[] = [];
+  for (const directory of PACKAGE_RUNTIME_ROOTS) walkRegularFiles(root, join(root, directory), paths);
+  for (const file of PACKAGE_RUNTIME_FILES) walkRegularFiles(root, join(root, file), paths);
+  const unique = [...new Set(paths)].sort();
+  if (!unique.includes('package.json') || !unique.some((path) => path === 'bin/forge-runtime.mjs')) {
+    throw new Error(`PACKAGE_RUNTIME_SURFACE_INCOMPLETE: ${root}`);
+  }
+  return unique.map((path) => {
+    const bytes = readFileSync(join(root, path));
+    return { path, sha256: sha256(bytes), bytes: bytes.length };
+  });
+}
+
+export function packageRuntimeFingerprint(records: PackageRuntimeFileRecord[]): string {
+  const hash = createHash('sha256');
+  for (const record of records) hash.update(record.path).update('\0').update(record.sha256).update('\0').update(String(record.bytes)).update('\n');
+  return hash.digest('hex');
+}
+
+function packageVersion(root: string): string {
+  try {
+    const value = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { name?: unknown; version?: unknown };
+    if (value.name !== '@moretea-labs/forge') throw new Error('package name mismatch');
+    if (typeof value.version !== 'string' || !value.version.trim()) throw new Error('package version missing');
+    return value.version.trim();
+  } catch (error) {
+    throw new Error(`PACKAGE_RUNTIME_IDENTITY_INVALID: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function launcherSource(input: { packageRoot: string; indexPath: string; indexSha256: string }): string {
+  return `#!/usr/bin/env node\n`
+    + `import { createHash } from 'node:crypto';\n`
+    + `import { existsSync, readFileSync } from 'node:fs';\n`
+    + `import { join } from 'node:path';\n`
+    + `import { spawn } from 'node:child_process';\n`
+    + `const packageRoot=${JSON.stringify(input.packageRoot)};\n`
+    + `const indexPath=${JSON.stringify(input.indexPath)};\n`
+    + `const expectedIndex=${JSON.stringify(input.indexSha256)};\n`
+    + `const digest=(v)=>createHash('sha256').update(v).digest('hex');\n`
+    + `let raw; try { raw=readFileSync(indexPath); } catch (error) { console.error('FORGE_PACKAGE_RUNTIME_INDEX_MISSING: '+error.message); process.exit(78); }\n`
+    + `if(digest(raw)!==expectedIndex){console.error('FORGE_PACKAGE_RUNTIME_INDEX_CHANGED');process.exit(78);}\n`
+    + `let records; try { records=JSON.parse(raw.toString('utf8')).files; } catch { console.error('FORGE_PACKAGE_RUNTIME_INDEX_INVALID'); process.exit(78); }\n`
+    + `for(const record of records){const path=join(packageRoot,record.path);if(!existsSync(path)||digest(readFileSync(path))!==record.sha256){console.error('FORGE_PACKAGE_RUNTIME_SOURCE_CHANGED: '+record.path);process.exit(78);}}\n`
+    + `const runtime=join(packageRoot,'bin','forge-runtime.mjs');\n`
+    + `const child=spawn(process.execPath,[runtime,...process.argv.slice(2)],{stdio:'inherit',env:{...process.env,FORGE_FORCE_NODE:'1'}});\n`
+    + `for(const signal of ['SIGINT','SIGTERM','SIGHUP']){try{process.on(signal,()=>child.kill(signal));}catch{}}\n`
+    + `child.on('error',(error)=>{console.error('FORGE_PACKAGE_RUNTIME_LAUNCH_FAILED: '+error.message);process.exit(1);});\n`
+    + `child.on('exit',(code)=>process.exit(code??1));\n`;
+}
+
+export function materializePackageRuntimeRelease(input: {
+  controllerHome?: string;
+  packageRoot?: string;
+  operationId?: string;
+} = {}): PackageRuntimeRelease {
+  const controllerHome = ensureControllerHome(input.controllerHome);
+  const packageRoot = resolve(input.packageRoot ?? packageRuntimeSourceRoot());
+  const version = packageVersion(packageRoot);
+  const records = packageRuntimeFileIndex(packageRoot);
+  const fingerprint = packageRuntimeFingerprint(records);
+  const safeVersion = version.replace(/[^A-Za-z0-9._-]+/g, '-');
+  const releaseId = `package-${safeVersion}-${fingerprint.slice(0, 16)}`;
+  const releaseRoot = join(controllerHome, 'runtime', 'releases', releaseId);
+  const indexPath = join(releaseRoot, 'package-files.json');
+  const indexJson = `${JSON.stringify({ schemaVersion: 1, package: '@moretea-labs/forge', version, fingerprint, files: records }, null, 2)}\n`;
+  atomicWrite(indexPath, indexJson);
+  const entrypointPath = join(releaseRoot, 'forge-runtime');
+  const launcher = launcherSource({ packageRoot, indexPath, indexSha256: sha256(Buffer.from(indexJson)) });
+  atomicWrite(entrypointPath, launcher, 0o700);
+  chmodSync(entrypointPath, 0o700);
+  const artifactIdentity = `sha256:${sha256(Buffer.from(launcher))}`;
+  const manifest: RuntimeReleaseManifest = {
+    schemaVersion: 1,
+    releaseId,
+    artifactIdentity,
+    entrypoint: 'forge-runtime',
+    arguments: [],
+    configurationSchemaVersion: 1,
+    controllerHome,
+    databaseSchemaCompatibility: { minimum: CONTROL_PLANE_SCHEMA_VERSION, maximum: CONTROL_PLANE_SCHEMA_VERSION },
+    workerProtocolVersion: 1,
+    releaseRevision: `package:${version}:${fingerprint}`,
+    cleanWorkspace: true,
+    createdAt: new Date().toISOString(),
+  };
+  const manifestPath = join(releaseRoot, 'manifest.json');
+  atomicWrite(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  const authority = publishRuntimeRelease(controllerHome, manifestPath, input.operationId ?? `package-runtime-${FORGE_VERSION}-${Date.now()}`);
+  return {
+    releaseId,
+    releaseRoot,
+    packageRoot,
+    packageVersion: version,
+    packageFingerprint: fingerprint,
+    artifactIdentity,
+    entrypointPath,
+    manifestPath,
+    indexPath,
+    fileCount: records.length,
+    authority,
+  };
+}

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

@@ -0,0 +1,185 @@
+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';
+import { loadMcpServiceLocalConfig } from '../../cli/mcp/auth';
+import { installPackageConnectorService, type PackageConnectorServiceResult } from './package-connector-service';
+
+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[];
+  connector?: PackageConnectorServiceResult;
+}
+
+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: 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;
+
+  let base: PackageRuntimeServiceInstallResult;
+  if (!options.forcePortable && platform === 'darwin') {
+    const paths = await installForgeRuntimeService({ config, runnerPath: join(release.packageRoot, 'bin', 'forge-runtime-service.mjs'), nodeExecutable: process.execPath });
+    base = { status: 'installed', mode: 'launchd', persistent: true, controllerHome, release, servicePath: paths.installedPlistPath, warnings: [] };
+  } else if (!options.forcePortable && platform === 'linux' && systemdUserAvailable(env)) {
+    const unitPath = installSystemdUserService(controllerHome, env);
+    base = { status: 'installed', mode: 'systemd-user', persistent: true, controllerHome, release, servicePath: unitPath, warnings: [] };
+  } else {
+    const pid = startPortableRuntime(controllerHome, env);
+    base = {
+      status: 'installed', mode: 'portable', persistent: false, controllerHome, release, pid,
+      warnings: [platform === 'win32'
+        ? 'Native Windows is preview: Forge started detached Runtime and OAuth Gateway processes for this session; automatic login/reboot persistence is not yet claimed.'
+        : 'systemd --user is unavailable: Forge started detached Runtime and OAuth Gateway processes; enable a user service manager for reboot persistence.'],
+    };
+  }
+
+  const localConfig = loadMcpServiceLocalConfig(controllerHome);
+  const connectorEndpoint = localConfig?.chatgpt?.localEndpoint;
+  if (!connectorEndpoint) return base;
+  const connector = await installPackageConnectorService({
+    release, controllerHome, endpoint: connectorEndpoint, platform, env, forcePortable: options.forcePortable === true,
+  });
+  return { ...base, connector };
+}

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

@@ -29,6 +29,7 @@ export interface StagedRuntimeRelease {
   codeGraphNodeArtifactIdentity?: string;
   codeGraphSidecarArtifactIdentity?: string;
   codeGraphLibraryArtifactIdentity?: string;
+  controllerUiArtifactIdentity?: string;
   manifestSha256: string;
   sourceCommit: string;
 }
@@ -395,6 +396,17 @@ export function stageRuntimeRelease(input: {
     const codeGraphSidecarArtifactIdentity = `sha256:${sha256(codeGraphSidecarPath)}`;
     const codeGraphLibraryArtifactIdentity = `sha256:${sha256Directory(codeGraphLibraryPath)}`;
 
+    const controllerUiRoot = 'ui-dist' as const;
+    const sourceControllerUiPath = join(sourceRoot, 'src', 'cli', 'local-bridge', controllerUiRoot);
+    const sourceControllerUiJs = join(sourceControllerUiPath, 'app.js');
+    const sourceControllerUiCss = join(sourceControllerUiPath, 'app.css');
+    if (!existsSync(sourceControllerUiJs) || !existsSync(sourceControllerUiCss)) {
+      throw new Error(`RUNTIME_RELEASE_CONTROLLER_UI_SOURCE_MISSING: ${sourceControllerUiPath}`);
+    }
+    const controllerUiPath = join(staging, controllerUiRoot);
+    cpSync(sourceControllerUiPath, controllerUiPath, { recursive: true, force: false });
+    const controllerUiArtifactIdentity = `sha256:${sha256Directory(controllerUiPath)}`;
+
     const desktopHelperEntrypoint = 'forge-desktop-helper.mjs' as const;
     const sourceDesktopHelperPath = join(sourceRoot, 'bin', desktopHelperEntrypoint);
     if (!existsSync(sourceDesktopHelperPath)) {
@@ -429,6 +441,8 @@ export function stageRuntimeRelease(input: {
       codeGraphSidecarArtifactIdentity,
       codeGraphLibraryRoot,
       codeGraphLibraryArtifactIdentity,
+      controllerUiRoot,
+      controllerUiArtifactIdentity,
       arguments: [],
       configurationSchemaVersion: 1,
       controllerHome: resolve(input.controllerHome),
@@ -460,6 +474,7 @@ export function stageRuntimeRelease(input: {
       codeGraphNodeArtifactIdentity,
       codeGraphSidecarArtifactIdentity,
       codeGraphLibraryArtifactIdentity,
+      controllerUiArtifactIdentity,
       manifestSha256: createHash('sha256').update(`${JSON.stringify(manifest, null, 2)}\n`).digest('hex'),
       sourceCommit,
     };
@@ -506,4 +521,8 @@ export function assertRuntimeReleaseFiles(release: StagedRuntimeRelease): void {
   if (release.codeGraphLibraryArtifactIdentity && !existsSync(join(release.releasePath, 'codegraph-lib', 'dist', 'index.js'))) {
     throw new Error(`RUNTIME_RELEASE_CODEGRAPH_LIBRARY_MISSING: ${join(release.releasePath, 'codegraph-lib', 'dist', 'index.js')}`);
   }
+  if (release.controllerUiArtifactIdentity
+    && (!existsSync(join(release.releasePath, 'ui-dist', 'app.js')) || !existsSync(join(release.releasePath, 'ui-dist', 'app.css')))) {
+    throw new Error(`RUNTIME_RELEASE_CONTROLLER_UI_MISSING: ${join(release.releasePath, 'ui-dist')}`);
+  }
 }

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;