@moretea-labs/forge 1.7.2 → 1.8.1

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-inventory.ts

@@ -0,0 +1,130 @@
+import { createHash } from 'crypto';
+import { resolve } from 'path';
+import type { PlatformServiceManagerHost } from './service-manager';
+
+export type ForgePersistentServiceOwner = 'forge-core' | 'provider';
+export type ForgePersistentServiceState = 'current' | 'retired';
+
+export interface ForgePersistentServiceIdentity {
+  id: string;
+  owner: ForgePersistentServiceOwner;
+  state: ForgePersistentServiceState;
+  launchdLabel: string;
+  systemdUnitName: string;
+}
+
+export const FORGE_RECOVERY_DAEMON_LABEL = 'com.moretea.forge-recovery';
+export const FORGE_RECOVERY_GATEWAY_LABEL = 'com.moretea.forge-recovery-gateway';
+export const FORGE_RECOVERY_WATCHDOG_LABEL = 'com.moretea.forge-recovery-watchdog';
+
+const RETIRED_CORE_LABELS = [
+  ['legacy-runtime', 'com.moretea.forge.runtime'],
+  ['legacy-mcp-gateway', 'com.moretea.forge.mcp-gateway'],
+  ['bootstrap-supervisor', 'com.moretea.forge-bootstrap-supervisor'],
+  ['evolution-supervisor', 'com.moretea.forge-evolution-supervisor'],
+  ['legacy-recovery-gateway', FORGE_RECOVERY_GATEWAY_LABEL],
+  ['legacy-recovery-watchdog', FORGE_RECOVERY_WATCHDOG_LABEL],
+] as const;
+
+/**
+ * These identities are intentionally outside Forge core lifecycle authority.
+ * They are listed to make the negative ownership boundary machine-visible,
+ * not to authorize any retirement action.
+ */
+export const FORGE_PROVIDER_OWNED_PERSISTENT_SERVICES = [
+  'com.moretea.forge.desktop-operator',
+  'com.moretea.desktop-operator',
+] as const;
+
+function controllerHomeSuffix(controllerHome: string): string {
+  return createHash('sha256').update(resolve(controllerHome)).digest('hex').slice(0, 12);
+}
+
+export function forgeRuntimePersistentServiceLabel(controllerHome: string): string {
+  return `com.moretea.forge.runtime.${controllerHomeSuffix(controllerHome)}`;
+}
+
+export function forgeConnectorPersistentServiceLabel(controllerHome: string): string {
+  return `com.moretea.forge.mcp-gateway.${controllerHomeSuffix(controllerHome)}`;
+}
+
+function identity(
+  id: string,
+  label: string,
+  state: ForgePersistentServiceState,
+): ForgePersistentServiceIdentity {
+  return {
+    id,
+    owner: 'forge-core',
+    state,
+    launchdLabel: label,
+    systemdUnitName: `${label}.service`,
+  };
+}
+
+export const FORGE_RETIRED_PERSISTENT_SERVICES: readonly ForgePersistentServiceIdentity[] =
+  RETIRED_CORE_LABELS.map(([id, label]) => identity(id, label, 'retired'));
+
+export function forgeOwnedPersistentServiceInventory(controllerHome: string): {
+  current: ForgePersistentServiceIdentity[];
+  retired: readonly ForgePersistentServiceIdentity[];
+  providerOwnedExcludedLabels: readonly string[];
+} {
+  return {
+    current: [
+      identity('runtime', forgeRuntimePersistentServiceLabel(controllerHome), 'current'),
+      identity('mcp-gateway', forgeConnectorPersistentServiceLabel(controllerHome), 'current'),
+      identity('recovery', FORGE_RECOVERY_DAEMON_LABEL, 'current'),
+    ],
+    retired: FORGE_RETIRED_PERSISTENT_SERVICES,
+    providerOwnedExcludedLabels: FORGE_PROVIDER_OWNED_PERSISTENT_SERVICES,
+  };
+}
+
+export interface ForgeRetiredServiceReconciliation {
+  id: string;
+  label: string;
+  platform: 'launchd' | 'systemd-user';
+  serviceWasPresent: boolean;
+  artifactWasPresent: boolean;
+  retired: boolean;
+}
+
+export async function reconcileRetiredForgePersistentServices(input: {
+  host: PlatformServiceManagerHost;
+  env?: NodeJS.ProcessEnv;
+  accountHome?: string;
+}): Promise<ForgeRetiredServiceReconciliation[]> {
+  if (!input.host.selection.persistent || input.host.selection.kind === 'portable') return [];
+  const results: ForgeRetiredServiceReconciliation[] = [];
+  for (const service of FORGE_RETIRED_PERSISTENT_SERVICES) {
+    if (input.host.selection.kind === 'launchd') {
+      const result = await input.host.retireLaunchdExact({
+        label: service.launchdLabel,
+        accountHome: input.accountHome,
+      });
+      results.push({
+        id: service.id,
+        label: service.launchdLabel,
+        platform: 'launchd',
+        serviceWasPresent: result.serviceWasPresent,
+        artifactWasPresent: result.plistWasPresent,
+        retired: result.absentAfter,
+      });
+    } else {
+      const result = input.host.retireSystemdUserExact({
+        unitName: service.systemdUnitName,
+        env: input.env,
+      });
+      results.push({
+        id: service.id,
+        label: service.systemdUnitName,
+        platform: 'systemd-user',
+        serviceWasPresent: result.serviceWasPresent,
+        artifactWasPresent: result.unitFileWasPresent,
+        retired: result.absentAfter,
+      });
+    }
+  }
+  return results;
+}