@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/gateway/mcp/work-validation-reconciler.ts

@@ -1 +1,2 @@
-export * from '../../control-plane/execution/work-validation-reconciler';
+/** @deprecated Kernel V2 compatibility shim. MCP gateway mapping authority lives in adapters/mcp. */
+export * from '../../../../adapters/mcp/runtime-gateway/work-validation-reconciler';

package/src/runtime/maintenance/cleanup.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from 'child_process';
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
-import { basename, dirname, join, relative, resolve } from 'path';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'path';
 import { tmpdir } from 'os';
 import type { CleanupCycleSummary } from '../control-plane/runtime-cleanup';
 import { assertRuntimeMayWrite } from '../root/write-fence';
@@ -131,6 +131,22 @@ function readJson(path: string): unknown {
   try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return undefined; }
 }
 
+function pathInside(root: string, candidate: string): boolean {
+  const rel = relative(resolve(root), resolve(candidate));
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+function relocatedRuntimeStorageRoot(repoRoot: string, name: 'local-jobs' | 'jobs'): string | undefined {
+  const repositoryPath = join(repoRoot, '.ai', 'harness', name);
+  try {
+    if (!lstatSync(repositoryPath).isSymbolicLink()) return undefined;
+    const target = realpathSync(repositoryPath);
+    return pathInside(repoRoot, target) ? undefined : target;
+  } catch {
+    return undefined;
+  }
+}
+
 function terminalStatus(status: unknown): boolean {
   return ['succeeded', 'failed', 'cancelled', 'timed_out', 'rejected'].includes(String(status));
 }
@@ -139,6 +155,7 @@ function scanTerminalLocalJobs(repoRoot: string, minAgeMinutes: number, limit: n
   const root = join(repoRoot, '.ai/harness/local-jobs');
   if (!existsSync(root)) return [];
   const at = Date.now();
+  const relocated = Boolean(relocatedRuntimeStorageRoot(repoRoot, 'local-jobs'));
   const candidates: RuntimeCleanupCandidate[] = [];
   for (const name of readdirSync(root).slice(0, limit * 3)) {
     const path = join(root, name);
@@ -147,20 +164,23 @@ function scanTerminalLocalJobs(repoRoot: string, minAgeMinutes: number, limit: n
       if (!stat.isDirectory()) continue;
       const jobJson = readJson(join(path, 'job.json')) as Record<string, unknown> | undefined;
       const ageMinutes = Math.max(0, Math.round((at - stat.mtimeMs) / 60_000));
-      const safe = ageMinutes >= minAgeMinutes && terminalStatus(jobJson?.status);
+      const safe = relocated && ageMinutes >= minAgeMinutes && terminalStatus(jobJson?.status);
       candidates.push({
         kind: 'local_job',
         path,
         id: typeof jobJson?.jobId === 'string' ? jobJson.jobId : name,
-        reason: safe ? 'Terminal local job is old enough to archive.' : 'Local job is not terminal or is too new.',
+        reason: !relocated
+          ? 'Repository-local Local Job storage must be relocated to Controller Home before cleanup.'
+          : safe ? 'Terminal Local Job is old enough to remove from Controller runtime storage.' : 'Local Job is not terminal or is too new.',
         ageMinutes,
         safe,
+        ownershipStatus: relocated ? 'explicit' : 'unknown',
       });
     } catch {
       // Ignore malformed entries.
     }
   }
-  return candidates.filter((candidate) => candidate.safe).slice(0, limit);
+  return candidates.slice(0, limit);
 }
 
 function textIncludesNoOpIntegrate(value: unknown): boolean {
@@ -190,6 +210,7 @@ function scanLegacyRuns(repoRoot: string, minAgeMinutes: number, limit: number):
   if (!existsSync(root)) return [];
   const processes = processCommands();
   const at = Date.now();
+  const relocated = Boolean(relocatedRuntimeStorageRoot(repoRoot, 'jobs'));
   const candidates: RuntimeCleanupCandidate[] = [];
   for (const name of readdirSync(root).filter((entry) => entry.startsWith('RUN-')).slice(0, limit * 3)) {
     const path = join(root, name);
@@ -200,17 +221,20 @@ function scanLegacyRuns(repoRoot: string, minAgeMinutes: number, limit: number):
       const occupied = processes.find((process) => process.command.includes(name) || process.command.includes(path));
       const status = String(state?.status ?? 'unknown');
       const ageMinutes = Math.max(0, Math.round((at - stat.mtimeMs) / 60_000));
-      const safe = !occupied && ageMinutes >= minAgeMinutes && status === 'waiting_for_user' && textIncludesNoOpIntegrate(state);
+      const safe = relocated && !occupied && ageMinutes >= minAgeMinutes && status === 'waiting_for_user' && textIncludesNoOpIntegrate(state);
       candidates.push({
         kind: 'legacy_run',
         path,
         id: typeof state?.runId === 'string' ? state.runId : name,
-        reason: safe
-          ? 'Legacy task run is waiting_for_user only because its worktree has no changes to integrate; it is safe to archive.'
-          : `Legacy task run is not a proven no-op waiting_for_user run. status=${status}`,
+        reason: !relocated
+          ? 'Repository-local legacy Run storage must be relocated to Controller Home before cleanup.'
+          : safe
+            ? 'Legacy no-op Run is old enough to remove from Controller runtime storage.'
+            : `Legacy task run is not a proven no-op waiting_for_user run. status=${status}`,
         ageMinutes,
         occupiedByPid: occupied?.pid,
         safe,
+        ownershipStatus: relocated ? 'explicit' : 'unknown',
       });
     } catch {
       candidates.push({
@@ -284,7 +308,7 @@ export function previewRuntimeCleanup(repoRoot: string, options: RuntimeCleanupO
     summary: summarize(candidates),
     warnings: [
       'Preview is non-destructive. Apply requires confirmCleanup=true.',
-      'Legacy run cleanup only archives directories proven to be old no-op waiting_for_user runs with no matching process.',
+      'Legacy runtime cleanup removes only relocated Controller Home records proven terminal/no-op and old enough; repository-local storage is never archived in the source tree.',
       'Historical attention cleanup is intentionally represented as acknowledgement guidance unless an explicit reconciler is added.',
     ],
     cycle: {
@@ -306,18 +330,6 @@ export function previewRuntimeCleanup(repoRoot: string, options: RuntimeCleanupO
   };
 }
 
-function archiveLocalJob(path: string, repoRoot: string): void {
-  const archiveRoot = join(repoRoot, '.ai/harness/local-jobs-archive');
-  mkdirSync(archiveRoot, { recursive: true });
-  renameSync(path, join(archiveRoot, basename(path)));
-}
-
-function archiveLegacyRun(path: string, repoRoot: string): void {
-  const archiveRoot = join(repoRoot, '.ai/harness/jobs-archive/legacy-noop');
-  mkdirSync(archiveRoot, { recursive: true });
-  renameSync(path, join(archiveRoot, basename(path)));
-}
-
 export function applyRuntimeCleanup(repoRoot: string, options: RuntimeCleanupOptions = {}): RuntimeCleanupApplyResult {
   // Passive / fenced runtimes must not run cleanup.
   try {
@@ -362,14 +374,16 @@ export function applyRuntimeCleanup(repoRoot: string, options: RuntimeCleanupOpt
       if (candidate.kind === 'local_job' && candidate.path) {
         const relativePath = relative(join(repoRoot, '.ai/harness/local-jobs'), candidate.path);
         if (relativePath && !relativePath.startsWith('..')) {
-          archiveLocalJob(candidate.path, repoRoot);
+          if (!relocatedRuntimeStorageRoot(repoRoot, 'local-jobs')) throw new Error('RUNTIME_CLEANUP_STORAGE_NOT_RELOCATED');
+          rmSync(candidate.path, { recursive: true, force: true });
           return { ...candidate, applied: true };
         }
       }
       if (candidate.kind === 'legacy_run' && candidate.path) {
         const relativePath = relative(join(repoRoot, '.ai/harness/jobs'), candidate.path);
         if (relativePath && !relativePath.startsWith('..') && basename(candidate.path).startsWith('RUN-')) {
-          archiveLegacyRun(candidate.path, repoRoot);
+          if (!relocatedRuntimeStorageRoot(repoRoot, 'jobs')) throw new Error('RUNTIME_CLEANUP_STORAGE_NOT_RELOCATED');
+          rmSync(candidate.path, { recursive: true, force: true });
           return { ...candidate, applied: true };
         }
       }

package/src/runtime/platform/browser-product-discovery.ts

@@ -0,0 +1,174 @@
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join, win32 as windowsPath } from 'path';
+import { discoverExecutable } from './executable-discovery';
+import type { NativeBrowserChannel } from '../../cli/chatgpt-browser/types';
+
+export type BrowserProductDiscoverySource = 'explicit' | 'path' | 'fallback';
+
+export interface NativeBrowserProduct {
+  channel: NativeBrowserChannel;
+  appName: string;
+  executable: string;
+  source: BrowserProductDiscoverySource;
+  defaultUserDataDir?: string;
+}
+
+export interface NativeBrowserProductDescriptor {
+  appName: string;
+  defaultUserDataDir?: string;
+}
+
+interface BrowserProductFallback extends NativeBrowserProductDescriptor {
+  appName: string;
+  pathNames: string[];
+  executableFallbacks: string[];
+  defaultUserDataDir?: string;
+}
+
+function channelSuffix(channel: NativeBrowserChannel): { mac: string; win: string; linux: string; profile: string } {
+  if (channel === 'chrome') return { mac: '', win: '', linux: '', profile: 'Chrome' };
+  if (channel === 'chrome-beta') return { mac: ' Beta', win: ' Beta', linux: '-beta', profile: 'Chrome Beta' };
+  if (channel === 'chrome-dev') return { mac: ' Dev', win: ' Dev', linux: '-unstable', profile: 'Chrome Dev' };
+  return { mac: ' Canary', win: ' SxS', linux: '-unstable', profile: 'Chrome Canary' };
+}
+
+function fallbackFor(channel: NativeBrowserChannel, platform: NodeJS.Platform, env: NodeJS.ProcessEnv): BrowserProductFallback | undefined {
+  const suffix = channelSuffix(channel);
+  if (platform === 'darwin') {
+    const appName = `Google Chrome${suffix.mac}`;
+    return {
+      appName,
+      pathNames: channel === 'chrome' ? ['google-chrome', 'chrome'] : [`google-chrome${suffix.linux}`],
+      executableFallbacks: [`/Applications/${appName}.app/Contents/MacOS/${appName}`],
+      defaultUserDataDir: join(env.HOME ?? homedir(), 'Library', 'Application Support', 'Google', suffix.profile),
+    };
+  }
+  if (platform === 'win32') {
+    const productRoot = channel === 'chrome-canary' ? 'Chrome SxS' : suffix.profile;
+    const relativeExecutable = windowsPath.join('Google', productRoot, 'Application', 'chrome.exe');
+    const programRoots = [env.ProgramFiles, env['ProgramFiles(x86)']].map((value) => value?.trim()).filter((value): value is string => Boolean(value));
+    const localAppData = env.LOCALAPPDATA?.trim() || windowsPath.join(env.USERPROFILE?.trim() || homedir(), 'AppData', 'Local');
+    const profileFolder = channel === 'chrome-canary' ? 'Chrome SxS' : suffix.profile;
+    return {
+      appName: channel === 'chrome' ? 'Google Chrome' : `Google Chrome${suffix.mac}`,
+      pathNames: ['chrome.exe', 'chrome'],
+      executableFallbacks: programRoots.map((root) => windowsPath.join(root, relativeExecutable)),
+      defaultUserDataDir: windowsPath.join(localAppData, 'Google', profileFolder, 'User Data'),
+    };
+  }
+  if (platform === 'linux') {
+    const command = channel === 'chrome' ? 'google-chrome' : `google-chrome${suffix.linux}`;
+    const configRoot = env.XDG_CONFIG_HOME?.trim() || join(env.HOME ?? homedir(), '.config');
+    return {
+      appName: channel === 'chrome' ? 'Google Chrome' : `Google Chrome${suffix.mac}`,
+      pathNames: channel === 'chrome' ? ['google-chrome', 'google-chrome-stable'] : [command],
+      executableFallbacks: [],
+      defaultUserDataDir: join(configRoot, command),
+    };
+  }
+  return undefined;
+}
+
+
+export function describeNativeBrowserProduct(input: {
+  channel: NativeBrowserChannel;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+}): NativeBrowserProductDescriptor | undefined {
+  const fallback = fallbackFor(input.channel, input.platform ?? process.platform, input.env ?? process.env);
+  return fallback ? { appName: fallback.appName, defaultUserDataDir: fallback.defaultUserDataDir } : undefined;
+}
+
+export function discoverNativeBrowserProduct(input: {
+  channel: NativeBrowserChannel;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  explicitExecutable?: string;
+  explicitUserDataDir?: string;
+  fileExists?: (path: string) => boolean;
+}): NativeBrowserProduct | undefined {
+  const platform = input.platform ?? process.platform;
+  const env = input.env ?? process.env;
+  const fallback = fallbackFor(input.channel, platform, env);
+  if (!fallback) return undefined;
+  const explicitExecutable = input.explicitExecutable?.trim() || env.FORGE_BROWSER_EXECUTABLE?.trim();
+  const explicitUserDataDir = input.explicitUserDataDir?.trim() || env.FORGE_BROWSER_USER_DATA_DIR?.trim();
+  const fileExists = input.fileExists ?? existsSync;
+  if (explicitExecutable) {
+    const resolution = discoverExecutable({ id: `browser:${input.channel}`, candidates: [], platform, env, explicitPath: explicitExecutable, fileExists });
+    if (resolution.status !== 'ready' || !resolution.executable) return undefined;
+    return { channel: input.channel, appName: fallback.appName, executable: resolution.executable, source: 'explicit', defaultUserDataDir: explicitUserDataDir || fallback.defaultUserDataDir };
+  }
+  const onPath = discoverExecutable({ id: `browser:${input.channel}`, candidates: fallback.pathNames, platform, env, fileExists });
+  if (onPath.status === 'ready' && onPath.executable) {
+    return { channel: input.channel, appName: fallback.appName, executable: onPath.executable, source: 'path', defaultUserDataDir: explicitUserDataDir || fallback.defaultUserDataDir };
+  }
+  const executable = fallback.executableFallbacks.find((candidate) => fileExists(candidate));
+  if (!executable) return undefined;
+  return { channel: input.channel, appName: fallback.appName, executable, source: 'fallback', defaultUserDataDir: explicitUserDataDir || fallback.defaultUserDataDir };
+}
+
+export type SupportedNativeBrowserProductId = 'chrome' | 'vivaldi';
+
+export interface SupportedNativeBrowserProduct extends NativeBrowserProduct {
+  product: SupportedNativeBrowserProductId;
+}
+
+function discoverVivaldiProduct(input: {
+  platform: NodeJS.Platform;
+  env: NodeJS.ProcessEnv;
+  fileExists: (path: string) => boolean;
+}): SupportedNativeBrowserProduct | undefined {
+  const { platform, env, fileExists } = input;
+  let pathNames: string[] = [];
+  let executableFallbacks: string[] = [];
+  let defaultUserDataDir: string | undefined;
+  if (platform === 'darwin') {
+    pathNames = ['vivaldi'];
+    executableFallbacks = ['/Applications/Vivaldi.app/Contents/MacOS/Vivaldi'];
+    defaultUserDataDir = join(env.HOME ?? homedir(), 'Library', 'Application Support', 'Vivaldi');
+  } else if (platform === 'win32') {
+    pathNames = ['vivaldi.exe', 'vivaldi'];
+    const localAppData = env.LOCALAPPDATA?.trim() || windowsPath.join(env.USERPROFILE?.trim() || homedir(), 'AppData', 'Local');
+    const roots = [localAppData, env.ProgramFiles, env['ProgramFiles(x86)']].map((value) => value?.trim()).filter((value): value is string => Boolean(value));
+    executableFallbacks = roots.map((root) => windowsPath.join(root, 'Vivaldi', 'Application', 'vivaldi.exe'));
+    defaultUserDataDir = windowsPath.join(localAppData, 'Vivaldi', 'User Data');
+  } else if (platform === 'linux') {
+    pathNames = ['vivaldi', 'vivaldi-stable'];
+    defaultUserDataDir = join(env.XDG_CONFIG_HOME?.trim() || join(env.HOME ?? homedir(), '.config'), 'vivaldi');
+  } else {
+    return undefined;
+  }
+  const onPath = discoverExecutable({ id: 'browser:vivaldi', candidates: pathNames, platform, env, fileExists });
+  if (onPath.status === 'ready' && onPath.executable) {
+    return { product: 'vivaldi', channel: 'chrome', appName: 'Vivaldi', executable: onPath.executable, source: 'path', defaultUserDataDir };
+  }
+  const executable = executableFallbacks.find((candidate) => fileExists(candidate));
+  return executable
+    ? { product: 'vivaldi', channel: 'chrome', appName: 'Vivaldi', executable, source: 'fallback', defaultUserDataDir }
+    : undefined;
+}
+
+/** Discover a usable supported Chromium-family product without binding product readiness to one developer browser. */
+export function discoverPreferredNativeBrowserProduct(input: {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  explicitExecutable?: string;
+  explicitUserDataDir?: string;
+  fileExists?: (path: string) => boolean;
+} = {}): SupportedNativeBrowserProduct | undefined {
+  const platform = input.platform ?? process.platform;
+  const env = input.env ?? process.env;
+  const fileExists = input.fileExists ?? existsSync;
+  const channels: NativeBrowserChannel[] = ['chrome', 'chrome-beta', 'chrome-dev', 'chrome-canary'];
+  for (const channel of channels) {
+    const chrome = discoverNativeBrowserProduct({
+      channel, platform, env, fileExists,
+      explicitExecutable: channel === 'chrome' ? input.explicitExecutable : undefined,
+      explicitUserDataDir: input.explicitUserDataDir,
+    });
+    if (chrome) return { ...chrome, product: 'chrome' };
+  }
+  return discoverVivaldiProduct({ platform, env, fileExists });
+}

package/src/runtime/platform/computer-platform.ts

@@ -0,0 +1,14 @@
+/**
+ * Platform resolution for Computer composition. Keeping this behind one seam
+ * makes native-provider policy deterministic in contract tests without
+ * weakening the production platform fence.
+ */
+let platformOverrideForTest: NodeJS.Platform | undefined;
+
+export function currentComputerPlatform(): NodeJS.Platform {
+  return platformOverrideForTest ?? process.platform;
+}
+
+export function setComputerPlatformForTest(platform: NodeJS.Platform | undefined): void {
+  platformOverrideForTest = platform;
+}

package/src/runtime/platform/executable-discovery.ts

@@ -0,0 +1,54 @@
+import { existsSync } from 'fs';
+import { delimiter, isAbsolute, join } from 'path';
+
+export type ExecutableDiscoveryStatus = 'ready' | 'missing' | 'unsupported';
+export interface ExecutableDiscoveryResult {
+  id: string;
+  status: ExecutableDiscoveryStatus;
+  executable?: string;
+  source?: 'explicit' | 'path';
+  recovery?: string;
+}
+
+function executableNames(name: string, platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string[] {
+  if (platform !== 'win32' || /\.[A-Za-z0-9]+$/.test(name)) return [name];
+  const extensions = (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').map((value) => value.trim()).filter(Boolean);
+  return [name, ...extensions.map((extension) => `${name}${extension.toLowerCase()}`), ...extensions.map((extension) => `${name}${extension.toUpperCase()}`)];
+}
+
+export function discoverExecutable(input: {
+  id: string;
+  candidates: readonly string[];
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  explicitPath?: string;
+  supportedPlatforms?: readonly NodeJS.Platform[];
+  fileExists?: (path: string) => boolean;
+  recovery?: string;
+}): ExecutableDiscoveryResult {
+  const platform = input.platform ?? process.platform;
+  const env = input.env ?? process.env;
+  const fileExists = input.fileExists ?? existsSync;
+  if (input.supportedPlatforms && !input.supportedPlatforms.includes(platform)) {
+    return { id: input.id, status: 'unsupported', recovery: input.recovery };
+  }
+  const explicit = input.explicitPath?.trim();
+  if (explicit) {
+    if (isAbsolute(explicit) && fileExists(explicit)) return { id: input.id, status: 'ready', executable: explicit, source: 'explicit' };
+    return { id: input.id, status: 'missing', recovery: input.recovery };
+  }
+  const pathEntries = (env.PATH ?? '').split(delimiter).map((entry) => entry.trim()).filter(Boolean);
+  for (const candidate of input.candidates) {
+    if (isAbsolute(candidate)) {
+      if (fileExists(candidate)) return { id: input.id, status: 'ready', executable: candidate, source: 'path' };
+      continue;
+    }
+    for (const directory of pathEntries) {
+      for (const name of executableNames(candidate, platform, env)) {
+        const executable = join(directory, name);
+        if (fileExists(executable)) return { id: input.id, status: 'ready', executable, source: 'path' };
+      }
+    }
+  }
+  return { id: input.id, status: 'missing', recovery: input.recovery };
+}

package/src/runtime/platform/fetch-http-server.ts

@@ -0,0 +1,90 @@
+import { createServer, type IncomingMessage, type ServerResponse } from 'http';
+
+export interface FetchHttpServer {
+  readonly port: number;
+  stop(force?: boolean): void;
+}
+
+export interface FetchHttpServerOptions {
+  hostname?: string;
+  port?: number;
+  maxRequestBytes?: number;
+  fetch(request: Request): Response | Promise<Response>;
+}
+
+async function requestBody(request: IncomingMessage, maxRequestBytes: number): Promise<ArrayBuffer | undefined> {
+  if (request.method === 'GET' || request.method === 'HEAD') return undefined;
+  const declaredLength = Number(request.headers['content-length'] ?? 0);
+  if (Number.isFinite(declaredLength) && declaredLength > maxRequestBytes) throw new Error('FETCH_HTTP_REQUEST_TOO_LARGE');
+  const chunks: Buffer[] = [];
+  let bytes = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    bytes += buffer.byteLength;
+    if (bytes > maxRequestBytes) throw new Error('FETCH_HTTP_REQUEST_TOO_LARGE');
+    chunks.push(buffer);
+  }
+  if (!chunks.length) return undefined;
+  const combined = Buffer.concat(chunks);
+  const copy = new Uint8Array(combined.byteLength);
+  copy.set(combined);
+  return copy.buffer;
+}
+
+async function toFetchRequest(request: IncomingMessage, hostname: string, maxRequestBytes: number): Promise<Request> {
+  const authority = request.headers.host?.trim() || hostname;
+  const url = new URL(request.url || '/', `http://${authority}`);
+  const headers = new Headers();
+  for (const [name, raw] of Object.entries(request.headers)) {
+    if (raw === undefined) continue;
+    if (Array.isArray(raw)) for (const value of raw) headers.append(name, value);
+    else headers.set(name, raw);
+  }
+  const requestBodyBuffer = await requestBody(request, maxRequestBytes);
+  return new Request(url, {
+    method: request.method || 'GET',
+    headers,
+    ...(requestBodyBuffer ? { body: requestBodyBuffer } : {}),
+  });
+}
+
+async function writeFetchResponse(response: Response, target: ServerResponse): Promise<void> {
+  target.statusCode = response.status;
+  response.headers.forEach((value, name) => target.setHeader(name, value));
+  if (!response.body) { target.end(); return; }
+  const body = Buffer.from(await response.arrayBuffer());
+  target.end(body);
+}
+
+export async function serveFetchHttp(input: FetchHttpServerOptions): Promise<FetchHttpServer> {
+  const hostname = input.hostname ?? '127.0.0.1';
+  const maxRequestBytes = Math.max(1_024, Math.min(input.maxRequestBytes ?? 1_048_576, 16_777_216));
+  const server = createServer(async (nodeRequest, nodeResponse) => {
+    try {
+      const request = await toFetchRequest(nodeRequest, hostname, maxRequestBytes);
+      await writeFetchResponse(await input.fetch(request), nodeResponse);
+    } catch (error) {
+      if (nodeResponse.headersSent) { nodeResponse.destroy(); return; }
+      const tooLarge = error instanceof Error && error.message === 'FETCH_HTTP_REQUEST_TOO_LARGE';
+      nodeResponse.statusCode = tooLarge ? 413 : 500;
+      nodeResponse.setHeader('content-type', 'application/json; charset=utf-8');
+      nodeResponse.end(JSON.stringify({ error: { code: tooLarge ? 'REQUEST_TOO_LARGE' : 'LOCAL_HTTP_HANDLER_FAILED' } }));
+    }
+  });
+  await new Promise<void>((resolve, reject) => {
+    const onError = (error: Error) => { server.off('listening', onListening); reject(error); };
+    const onListening = () => { server.off('error', onError); resolve(); };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(input.port ?? 0, hostname);
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') { server.close(); throw new Error('FETCH_HTTP_LISTENER_ADDRESS_UNAVAILABLE'); }
+  return {
+    port: address.port,
+    stop(force = false): void {
+      if (force && typeof server.closeAllConnections === 'function') server.closeAllConnections();
+      server.close();
+    },
+  };
+}

package/src/runtime/platform/service-manager.ts

@@ -0,0 +1,138 @@
+import { spawn, spawnSync } from 'child_process';
+import { closeSync, mkdirSync, openSync } from 'fs';
+import { dirname } from 'path';
+import {
+  bootstrapLaunchAgentWithRetryV2,
+  bootoutLaunchAgentWithRetryV2,
+  currentUserLaunchdDomain,
+  installLaunchAgent,
+  launchAgentPath,
+  retireConflictingForgeLaunchAgents,
+} from '../../cli/controller/launch-agents';
+import {
+  installSystemdUserUnit,
+  renderSystemdUserUnit,
+  systemdUserAvailable,
+  writeSystemdUserUnit,
+  systemdUserInstallCommands,
+  type SystemdUserUnitInput,
+} from '../../cli/controller/systemd-user';
+
+export type { SystemdUserUnitInput } from '../../cli/controller/systemd-user';
+
+export type PlatformServiceManagerKind = 'launchd' | 'systemd-user' | 'portable';
+
+export interface PlatformServiceManagerSelection {
+  kind: PlatformServiceManagerKind;
+  persistent: boolean;
+  reason: string;
+}
+
+export interface PlatformDetachedProcessInput {
+  executable: string;
+  args: string[];
+  environment: NodeJS.ProcessEnv;
+  stdoutPath: string;
+  stderrPath: string;
+  errorCode: string;
+}
+
+export interface PlatformServiceManagerHost {
+  selection: PlatformServiceManagerSelection;
+  renderSystemdUserUnit(input: SystemdUserUnitInput): string;
+  installSystemdUserUnit(input: { unitName: string; unit: SystemdUserUnitInput; env?: NodeJS.ProcessEnv; errorPrefix: string }): string;
+  writeSystemdUserUnit(unitName: string, unit: SystemdUserUnitInput, env?: NodeJS.ProcessEnv): string;
+  systemdUserInstallCommands(unitName: string): string[][];
+  launchdInstalledPath(label: string, accountHome?: string): string;
+  installLaunchd(sourcePath: string, label: string): void;
+  bootstrapLaunchd(input: { label: string; plistPath: string }): Promise<{ ok: boolean; diagnostics: string[] }>;
+  bootoutLaunchd(input: { label: string; plistPath: string }): Promise<{ ok: boolean; diagnostics: string[] }>;
+  retireConflictingLaunchd(input: Parameters<typeof retireConflictingForgeLaunchAgents>[0]): ReturnType<typeof retireConflictingForgeLaunchAgents>;
+  launchdDomain(): string;
+  detachLaunchdBootout(label: string): void;
+  startDetached(input: PlatformDetachedProcessInput): number;
+}
+
+/** Pure product-level selection. Platform adapters own probing/install mechanics. */
+export function resolvePlatformServiceManager(input: {
+  platform: NodeJS.Platform;
+  forcePortable?: boolean;
+  systemdUserAvailable?: boolean;
+}): PlatformServiceManagerSelection {
+  if (input.forcePortable === true) {
+    return { kind: 'portable', persistent: false, reason: 'portable_explicitly_requested' };
+  }
+  if (input.platform === 'darwin') {
+    return { kind: 'launchd', persistent: true, reason: 'macos_launchd_available' };
+  }
+  if (input.platform === 'linux' && input.systemdUserAvailable === true) {
+    return { kind: 'systemd-user', persistent: true, reason: 'linux_systemd_user_available' };
+  }
+  if (input.platform === 'linux') {
+    return { kind: 'portable', persistent: false, reason: 'linux_systemd_user_unavailable' };
+  }
+  if (input.platform === 'win32') {
+    return { kind: 'portable', persistent: false, reason: 'windows_native_persistence_preview' };
+  }
+  return { kind: 'portable', persistent: false, reason: 'platform_service_manager_unsupported' };
+}
+
+export function createPlatformServiceManagerHost(input: {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  forcePortable?: boolean;
+  systemdUserAvailable?: boolean;
+} = {}): PlatformServiceManagerHost {
+  const platform = input.platform ?? process.platform;
+  const env = input.env ?? process.env;
+  const systemdAvailable = input.systemdUserAvailable ?? (platform === 'linux' ? systemdUserAvailable(env) : false);
+  const selection = resolvePlatformServiceManager({ platform, forcePortable: input.forcePortable, systemdUserAvailable: systemdAvailable });
+  return {
+    selection,
+    renderSystemdUserUnit,
+    installSystemdUserUnit,
+    writeSystemdUserUnit,
+    systemdUserInstallCommands,
+    launchdInstalledPath: launchAgentPath,
+    installLaunchd: installLaunchAgent,
+    bootstrapLaunchd: bootstrapLaunchAgentWithRetryV2,
+    bootoutLaunchd: bootoutLaunchAgentWithRetryV2,
+    retireConflictingLaunchd: retireConflictingForgeLaunchAgents,
+    launchdDomain: currentUserLaunchdDomain,
+    detachLaunchdBootout(label: string): void {
+      if (platform !== 'darwin') return;
+      const child = spawn('/bin/launchctl', ['bootout', `${currentUserLaunchdDomain()}/${label}`], {
+        detached: true, stdio: 'ignore', env: { PATH: '/usr/bin:/bin:/usr/sbin:/sbin' },
+      });
+      child.unref();
+    },
+    startDetached(processInput: PlatformDetachedProcessInput): number {
+      mkdirSync(dirname(processInput.stdoutPath), { recursive: true, mode: 0o700 });
+      const stdout = openSync(processInput.stdoutPath, 'a', 0o600);
+      const stderr = openSync(processInput.stderrPath, 'a', 0o600);
+      try {
+        const child = spawn(processInput.executable, processInput.args, {
+          detached: true, stdio: ['ignore', stdout, stderr], env: processInput.environment,
+        });
+        if (!child.pid) throw new Error(`${processInput.errorCode}: child pid unavailable`);
+        child.unref();
+        return child.pid;
+      } finally {
+        closeSync(stdout);
+        closeSync(stderr);
+      }
+    },
+  };
+}
+
+export function platformLaunchdInstalledPath(label: string, accountHome?: string): string {
+  return launchAgentPath(label, accountHome);
+}
+
+export function probeSystemdUserAvailable(env: NodeJS.ProcessEnv = process.env): boolean {
+  return systemdUserAvailable(env);
+}
+
+export function probeSystemdUserAvailableDirect(env: NodeJS.ProcessEnv = process.env): boolean {
+  return spawnSync('systemctl', ['--user', 'show-environment'], { encoding: 'utf8', env, timeout: 30_000 }).status === 0;
+}