@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/root/mcp-transport.ts

@@ -8,12 +8,25 @@ import type { RuntimeReadiness } from './types';
 
 interface ManagedSession {
   transport: StreamableHTTPServerTransport;
+  lastActivityAt: number;
+  activePosts: number;
+  activeStreams: number;
+}
+
+export interface RuntimeMcpSessionSnapshot {
+  active: number;
+  maximum: number;
+  initializing: number;
+  protected: number;
+  capacityAvailable: number;
+  capacityEvictions: number;
 }
 
 export interface RuntimeMcpTransportHandle {
   endpoint: string;
   host: string;
   port: number;
+  sessionSnapshot?(): RuntimeMcpSessionSnapshot;
   close(): Promise<void>;
 }
 
@@ -25,7 +38,15 @@ export interface StartRuntimeMcpTransportOptions {
   authToken: string;
   readiness: () => RuntimeReadiness;
   createServer: (principalId: string, sessionId?: string, controllerType?: ForwardedControllerType) => Server;
+  /**
+   * Called immediately before Runtime schema-observing requests are served.
+   * The Canonical Runtime uses this to keep its published status projection in
+   * sync with the live tool surface without making status.json an authority.
+   */
+  onToolSurfaceObservation?: () => void;
   onFatal?: (error: Error) => void;
+  /** Internal Runtime sessions are bounded even if a Gateway dies without DELETE. */
+  maximumSessions?: number;
 }
 
 function authorized(request: Request, configuredToken: string): boolean {
@@ -46,6 +67,15 @@ function isInitialize(body: unknown): boolean {
     && (value as Record<string, unknown>).method === 'initialize');
 }
 
+function observesToolSurface(body: unknown): boolean {
+  const values = Array.isArray(body) ? body : [body];
+  return values.some((value) => {
+    if (!value || typeof value !== 'object') return false;
+    const method = (value as Record<string, unknown>).method;
+    return method === 'initialize' || method === 'tools/list';
+  });
+}
+
 function parseBody(body: unknown): unknown {
   if (!Buffer.isBuffer(body)) return body;
   try { return JSON.parse(body.toString('utf8')); } catch {
@@ -64,20 +94,126 @@ function authMiddleware(token: string) {
   };
 }
 
+const SESSION_CLOSE_TIMEOUT_MS = 1_000;
+const REQUEST_DRAIN_TIMEOUT_MS = 250;
+export const DEFAULT_RUNTIME_MCP_MAX_SESSIONS = 64;
+
+function boundedRuntimeMcpMaximumSessions(value: number | undefined): number {
+  if (!Number.isInteger(value) || (value ?? 0) < 1) return DEFAULT_RUNTIME_MCP_MAX_SESSIONS;
+  return Math.min(value!, DEFAULT_RUNTIME_MCP_MAX_SESSIONS);
+}
+
 function closeServer(server: NodeHttpServer): Promise<void> {
   return new Promise((resolve, reject) => {
     server.close((error) => error ? reject(error) : resolve());
+    // Stop keep-alive sockets that have no request in flight. Active requests
+    // receive a bounded graceful drain before the shutdown path forces them.
     server.closeIdleConnections?.();
   });
 }
 
+function boundedDrain(wait: Promise<void>, timeoutMs: number): Promise<void> {
+  if (timeoutMs <= 0) return Promise.resolve();
+  return Promise.race([
+    wait.catch(() => undefined),
+    new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
+  ]);
+}
+
+export async function closeRuntimeMcpTransportResources(input: {
+  closeListener: () => Promise<void>;
+  closeSessions: Array<() => Promise<void>>;
+  waitForRequestDrain?: () => Promise<void>;
+  forceCloseConnections?: () => void;
+  requestDrainTimeoutMs?: number;
+  sessionCloseTimeoutMs?: number;
+}): Promise<void> {
+  // Withdraw the TCP listener first so no new request can enter. Allow ordinary
+  // short MCP calls to finish before closing their session transport; long SSE
+  // streams remain bounded and are force-closed after the drain window.
+  const listenerClose = input.closeListener();
+  void listenerClose.catch(() => undefined);
+  await boundedDrain(
+    input.waitForRequestDrain?.() ?? Promise.resolve(),
+    Math.max(0, input.requestDrainTimeoutMs ?? REQUEST_DRAIN_TIMEOUT_MS),
+  );
+  const sessionDrain = Promise.allSettled(input.closeSessions.map(async (close) => await close()));
+  await boundedDrain(sessionDrain.then(() => undefined), Math.max(0, input.sessionCloseTimeoutMs ?? SESSION_CLOSE_TIMEOUT_MS));
+  input.forceCloseConnections?.();
+  await listenerClose;
+}
+
 export async function startRuntimeMcpTransport(
   options: StartRuntimeMcpTransportOptions,
 ): Promise<RuntimeMcpTransportHandle> {
   if (!options.authToken.trim()) throw new Error('MCP_AUTH_TOKEN_REQUIRED');
   const sessions = new Map<string, ManagedSession>();
+  const maximumSessions = boundedRuntimeMcpMaximumSessions(options.maximumSessions);
+  let initializingSessions = 0;
+  let capacityEvictions = 0;
+  let activeRequests = 0;
+
+  const sessionSnapshot = (): RuntimeMcpSessionSnapshot => ({
+    active: sessions.size,
+    maximum: maximumSessions,
+    initializing: initializingSessions,
+    protected: [...sessions.values()].filter((session) => session.activePosts > 0).length,
+    capacityAvailable: Math.max(0, maximumSessions - sessions.size - initializingSessions),
+    capacityEvictions,
+  });
+
+  const reserveInitialize = async (): Promise<boolean> => {
+    while (sessions.size + initializingSessions >= maximumSessions) {
+      const victim = [...sessions.entries()]
+        .filter(([, session]) => session.activePosts === 0)
+        .sort((left, right) => left[1].lastActivityAt - right[1].lastActivityAt)[0];
+      if (!victim) return false;
+      sessions.delete(victim[0]);
+      capacityEvictions += 1;
+      await victim[1].transport.close().catch(() => undefined);
+    }
+    initializingSessions += 1;
+    return true;
+  };
+
+  const withManagedSessionRequest = async <T>(
+    managed: ManagedSession,
+    kind: 'post' | 'stream',
+    action: () => Promise<T>,
+  ): Promise<T> => {
+    if (kind === 'post') managed.activePosts += 1;
+    else managed.activeStreams += 1;
+    managed.lastActivityAt = Date.now();
+    try {
+      return await action();
+    } finally {
+      if (kind === 'post') managed.activePosts = Math.max(0, managed.activePosts - 1);
+      else managed.activeStreams = Math.max(0, managed.activeStreams - 1);
+      managed.lastActivityAt = Date.now();
+    }
+  };
+  const requestDrainWaiters = new Set<() => void>();
   const app = express();
   app.disable('x-powered-by');
+  app.use((_req, res, next) => {
+    activeRequests += 1;
+    let settled = false;
+    const settle = (): void => {
+      if (settled) return;
+      settled = true;
+      activeRequests = Math.max(0, activeRequests - 1);
+      if (activeRequests === 0) {
+        for (const resolve of requestDrainWaiters) resolve();
+        requestDrainWaiters.clear();
+      }
+    };
+    res.once('finish', settle);
+    res.once('close', settle);
+    next();
+  });
+  const waitForRequestDrain = (): Promise<void> => activeRequests === 0
+    ? Promise.resolve()
+    : new Promise<void>((resolve) => requestDrainWaiters.add(resolve));
   app.get('/ready', (_req, res) => {
     const readiness = options.readiness();
     res.status(readiness.ready ? 200 : 503).json(readiness);
@@ -91,10 +227,16 @@ export async function startRuntimeMcpTransport(
         res.status(400).json({ error: error instanceof Error ? error.message : String(error) });
         return;
       }
+      if (observesToolSurface(body)) options.onToolSurfaceObservation?.();
       const requestedSessionId = req.headers['mcp-session-id'];
       const sessionId = typeof requestedSessionId === 'string' ? requestedSessionId : undefined;
       if (isInitialize(body)) {
+        if (!await reserveInitialize()) {
+          res.status(503).json({ error: 'mcp_session_capacity_exhausted' });
+          return;
+        }
         let transport: StreamableHTTPServerTransport;
+        let committedSessionId: string | undefined;
         const forwardedPrincipalId = typeof req.headers['x-forge-forwarded-principal-id'] === 'string'
           ? req.headers['x-forge-forwarded-principal-id'].trim().slice(0, 512)
           : '';
@@ -112,7 +254,15 @@ export async function startRuntimeMcpTransport(
         transport = new StreamableHTTPServerTransport({
           sessionIdGenerator: () => randomUUID(),
           onsessioninitialized: (createdSessionId) => {
-            sessions.set(createdSessionId, { transport });
+            committedSessionId = createdSessionId;
+            initializingSessions = Math.max(0, initializingSessions - 1);
+            sessions.set(createdSessionId, {
+              transport,
+              lastActivityAt: Date.now(),
+              // Initialize is a POST and must not be reclaimed before it settles.
+              activePosts: 1,
+              activeStreams: 0,
+            });
           },
         });
         transport.onclose = () => {
@@ -125,6 +275,16 @@ export async function startRuntimeMcpTransport(
           await transport.close().catch(() => undefined);
           if (!res.headersSent) res.status(500).json({ error: 'mcp_initialize_failed' });
           throw error;
+        } finally {
+          if (committedSessionId) {
+            const committed = sessions.get(committedSessionId);
+            if (committed) {
+              committed.activePosts = Math.max(0, committed.activePosts - 1);
+              committed.lastActivityAt = Date.now();
+            }
+          } else {
+            initializingSessions = Math.max(0, initializingSessions - 1);
+          }
         }
         return;
       }
@@ -133,7 +293,7 @@ export async function startRuntimeMcpTransport(
         res.status(404).json({ error: 'mcp_session_not_found' });
         return;
       }
-      await managed.transport.handleRequest(req, res, body);
+      await withManagedSessionRequest(managed, 'post', async () => await managed.transport.handleRequest(req, res, body));
     })().catch((error: unknown) => {
       if (!res.headersSent) res.status(500).json({ error: 'mcp_request_failed' });
       console.error('[forge-runtime mcp] request failed:', error);
@@ -148,7 +308,7 @@ export async function startRuntimeMcpTransport(
         res.status(404).json({ error: 'mcp_session_not_found' });
         return;
       }
-      await managed.transport.handleRequest(req, res);
+      await withManagedSessionRequest(managed, 'stream', async () => await managed.transport.handleRequest(req, res));
     })().catch((error: unknown) => {
       if (!res.headersSent) res.status(500).json({ error: 'mcp_request_failed' });
       console.error('[forge-runtime mcp] stream request failed:', error);
@@ -163,8 +323,10 @@ export async function startRuntimeMcpTransport(
         res.status(404).json({ error: 'mcp_session_not_found' });
         return;
       }
-      await managed.transport.handleRequest(req, res);
-      await managed.transport.close();
+      await withManagedSessionRequest(managed, 'post', async () => {
+        await managed.transport.handleRequest(req, res);
+        await managed.transport.close();
+      });
       sessions.delete(sessionId!);
     })().catch((error: unknown) => {
       if (!res.headersSent) res.status(500).json({ error: 'mcp_request_failed' });
@@ -195,12 +357,20 @@ export async function startRuntimeMcpTransport(
     endpoint,
     host: options.host,
     port: address.port,
+    sessionSnapshot,
     close: async () => {
-      await Promise.all([...sessions.values()].map(async ({ transport }) => {
-        await transport.close().catch(() => undefined);
-      }));
-      sessions.clear();
-      await closeServer(httpServer);
+      await closeRuntimeMcpTransportResources({
+        closeListener: async () => await closeServer(httpServer),
+        waitForRequestDrain,
+        // Snapshot sessions only after the request drain: an initialize request
+        // already in flight may register its session while shutdown is starting.
+        closeSessions: [async () => {
+          const activeSessions = [...sessions.values()];
+          await Promise.allSettled(activeSessions.map(async ({ transport }) => await transport.close().catch(() => undefined)));
+          sessions.clear();
+        }],
+        forceCloseConnections: () => httpServer.closeAllConnections?.(),
+      });
     },
   };
 }

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

@@ -1,9 +1,9 @@
 import { createHash } from 'crypto';
-import { closeSync, mkdirSync, openSync, renameSync, writeFileSync } from 'fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { basename, dirname, join, resolve } from 'path';
 import { spawn, spawnSync } from 'child_process';
-import { bootstrapLaunchAgentWithRetryV2, installLaunchAgent, launchAgentPath } from '../../cli/controller/launch-agents';
+import { bootstrapLaunchAgentWithRetryV2, installLaunchAgent, launchAgentPath, retireConflictingForgeLaunchAgents } from '../../cli/controller/launch-agents';
 import type { PackageRuntimeRelease } from './package-runtime-release';
 
 export interface PackageConnectorServicePaths {
@@ -13,6 +13,21 @@ export interface PackageConnectorServicePaths {
   installedPlistPath: string;
   stdoutPath: string;
   stderrPath: string;
+  authorityPath: string;
+}
+
+export type PackageConnectorReleaseBinding = Pick<PackageRuntimeRelease, 'releaseId' | 'releaseRoot' | 'packageRoot'>;
+
+export interface PackageConnectorServiceAuthority {
+  schemaVersion: 1;
+  endpoint: string;
+  releaseId: string;
+  releaseRoot: string;
+  packageRoot: string;
+  mode: 'launchd' | 'systemd-user' | 'portable';
+  persistent: boolean;
+  servicePath?: string;
+  installedAt: string;
 }
 
 export interface PackageConnectorServiceResult {
@@ -21,6 +36,9 @@ export interface PackageConnectorServiceResult {
   persistent: boolean;
   servicePath?: string;
   pid?: number;
+  reused?: boolean;
+  releaseId?: string;
+  releaseRoot?: string;
 }
 
 function xml(value: string): string {
@@ -46,22 +64,107 @@ export function packageConnectorServicePaths(controllerHome: string, accountHome
     installedPlistPath: launchAgentPath(label, accountHome),
     stdoutPath: join(serviceRoot, 'logs', 'stdout.log'),
     stderrPath: join(serviceRoot, 'logs', 'stderr.log'),
+    authorityPath: join(serviceRoot, 'authority.json'),
+  };
+}
+
+export function readPackageConnectorServiceAuthority(controllerHome: string): PackageConnectorServiceAuthority | undefined {
+  const path = packageConnectorServicePaths(controllerHome).authorityPath;
+  if (!existsSync(path)) return undefined;
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<PackageConnectorServiceAuthority>;
+  if (
+    parsed.schemaVersion !== 1
+    || typeof parsed.endpoint !== 'string'
+    || typeof parsed.releaseId !== 'string'
+    || typeof parsed.releaseRoot !== 'string'
+    || typeof parsed.packageRoot !== 'string'
+    || !['launchd', 'systemd-user', 'portable'].includes(String(parsed.mode))
+    || typeof parsed.persistent !== 'boolean'
+    || typeof parsed.installedAt !== 'string'
+  ) throw new Error('FORGE_PACKAGE_CONNECTOR_AUTHORITY_INVALID');
+  return parsed as PackageConnectorServiceAuthority;
+}
+
+function writePackageConnectorServiceAuthority(input: { release: PackageConnectorReleaseBinding; controllerHome: string; result: PackageConnectorServiceResult }): void {
+  const paths = packageConnectorServicePaths(input.controllerHome);
+  const authority: PackageConnectorServiceAuthority = {
+    schemaVersion: 1,
+    endpoint: input.result.endpoint,
+    releaseId: input.release.releaseId,
+    releaseRoot: resolve(input.release.releaseRoot),
+    packageRoot: resolve(input.release.packageRoot),
+    mode: input.result.mode,
+    persistent: input.result.persistent,
+    ...(input.result.servicePath ? { servicePath: input.result.servicePath } : {}),
+    installedAt: new Date().toISOString(),
   };
+  atomicWrite(paths.authorityPath, `${JSON.stringify(authority, null, 2)}\n`);
 }
 
-export function packageConnectorLaunchSpec(input: { release: PackageRuntimeRelease; controllerHome: string; endpoint: string; executable?: string }): { executable: string; args: string[]; environment: Record<string, string>; port: number } {
+export function packageConnectorEndpointStatusHealthy(status: number): boolean {
+  // The OAuth-protected MCP endpoint is healthy when it either answers directly
+  // or returns the expected unauthenticated Bearer challenge. Treating every
+  // received HTTP status as healthy masks upstream 5xx failures that are often
+  // surfaced remotely as 502 and prevents the persistent service from healing.
+  return status === 200 || status === 401;
+}
+
+async function defaultConnectorEndpointProbe(endpoint: string): Promise<boolean> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1_500);
+  try {
+    const response = await fetch(endpoint, { method: 'GET', redirect: 'manual', signal: controller.signal });
+    return packageConnectorEndpointStatusHealthy(response.status);
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function waitForPackageConnectorEndpointReady(
+  endpoint: string,
+  options: {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    probeEndpoint?: (endpoint: string) => Promise<boolean>;
+    wait?: (ms: number) => Promise<void>;
+    now?: () => number;
+  } = {},
+): Promise<boolean> {
+  const timeoutMs = Math.max(0, options.timeoutMs ?? 15_000);
+  const pollIntervalMs = Math.max(10, options.pollIntervalMs ?? 100);
+  const probeEndpoint = options.probeEndpoint ?? defaultConnectorEndpointProbe;
+  const wait = options.wait ?? ((ms: number) => new Promise<void>((resolveWait) => setTimeout(resolveWait, ms)));
+  const now = options.now ?? Date.now;
+  const deadline = now() + timeoutMs;
+  do {
+    if (await probeEndpoint(endpoint)) return true;
+    if (now() >= deadline) return false;
+    await wait(Math.min(pollIntervalMs, Math.max(1, deadline - now())));
+  } while (now() <= deadline);
+  return false;
+}
+
+export function packageConnectorLaunchSpec(input: { release: PackageConnectorReleaseBinding; controllerHome: string; endpoint: string; executable?: string }): { executable: string; args: string[]; environment: Record<string, string>; port: number } {
   const parsed = new URL(input.endpoint);
   const port = Number(parsed.port);
   if (parsed.protocol !== 'http:' || parsed.hostname !== '127.0.0.1' || parsed.pathname !== '/mcp' || !Number.isInteger(port) || port < 1 || port > 65_535) {
     throw new Error('FORGE_PACKAGE_CONNECTOR_ENDPOINT_INVALID');
   }
-  const executable = resolve(input.executable ?? process.execPath);
+  const executable = resolve(input.executable ?? process.env.FORGE_CONNECTOR_EXECUTABLE ?? process.execPath);
+  if (/^forge-recovery-(?:gateway|watchdog)$/i.test(basename(executable))) {
+    throw new Error('FORGE_PACKAGE_CONNECTOR_EXECUTABLE_INVALID');
+  }
   const packageRoot = resolve(input.release.packageRoot);
   const cliEntry = join(packageRoot, 'src', 'cli', 'index.ts');
   const nodeLoader = join(packageRoot, 'src', 'runtime', 'shared', 'node-ts-loader.mjs');
   const isBun = Boolean(process.versions.bun) || /(?:^|[/\\-])bun(?:$|[/\\]|\.exe$)/i.test(basename(executable));
   const cliArgs = [
-    'mcp', 'serve', '--repo', packageRoot, '--controller-home', resolve(input.controllerHome),
+    // The package snapshot is executable code, never an adopted repository.
+    // Supplying it as --repo makes the Gateway try to register a non-Git
+    // directory and fail before it can proxy the Canonical Runtime.
+    'mcp', 'serve', '--controller-home', resolve(input.controllerHome),
     '--transport', 'http', '--host', '127.0.0.1', '--port', String(port), '--profile', 'controller', '--auth', 'oauth',
   ];
   return {
@@ -85,6 +188,46 @@ export function renderPackageConnectorSystemdUserUnit(input: { launch: ReturnTyp
   return ['[Unit]', 'Description=Forge ChatGPT OAuth Gateway', 'After=network-online.target', '', '[Service]', 'Type=simple', `ExecStart=${[input.launch.executable, ...input.launch.args].map(quote).join(' ')}`, ...env, 'Restart=on-failure', 'RestartSec=5', '', '[Install]', 'WantedBy=default.target', ''].join('\n');
 }
 
+export function packageConnectorServiceMatchesRelease(input: {
+  authority: PackageConnectorServiceAuthority;
+  release: PackageConnectorReleaseBinding;
+  controllerHome: string;
+  endpoint: string;
+  platform: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  executable?: string;
+}): boolean {
+  try {
+    if (
+      input.authority.endpoint !== input.endpoint
+      || input.authority.releaseId !== input.release.releaseId
+      || resolve(input.authority.releaseRoot) !== resolve(input.release.releaseRoot)
+      || resolve(input.authority.packageRoot) !== resolve(input.release.packageRoot)
+    ) return false;
+    const launch = packageConnectorLaunchSpec({
+      release: input.release,
+      controllerHome: input.controllerHome,
+      endpoint: input.endpoint,
+      executable: input.executable,
+    });
+    if (input.platform === 'darwin') {
+      const paths = packageConnectorServicePaths(input.controllerHome, input.env?.HOME);
+      if (input.authority.mode !== 'launchd' || !input.authority.servicePath) return false;
+      const servicePath = resolve(input.authority.servicePath);
+      if (servicePath !== resolve(paths.installedPlistPath) || !existsSync(servicePath)) return false;
+      return readFileSync(servicePath, 'utf8') === renderPackageConnectorLaunchAgent({ paths, launch });
+    }
+    if (input.platform === 'linux') {
+      if (input.authority.mode !== 'systemd-user' || !input.authority.servicePath) return false;
+      const servicePath = resolve(input.authority.servicePath);
+      return existsSync(servicePath) && readFileSync(servicePath, 'utf8') === renderPackageConnectorSystemdUserUnit({ launch });
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 function installSystemd(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv): string {
   const unitName = `${paths.label}.service`;
   const unitPath = join(env.HOME ?? homedir(), '.config', 'systemd', 'user', unitName);
@@ -116,21 +259,98 @@ function startPortable(paths: PackageConnectorServicePaths, launch: ReturnType<t
   } finally { closeSync(stdout); closeSync(stderr); }
 }
 
-export async function installPackageConnectorService(input: { release: PackageRuntimeRelease; controllerHome: string; endpoint: string; platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; forcePortable?: boolean }): Promise<PackageConnectorServiceResult> {
+export async function installPackageConnectorService(input: { release: PackageConnectorReleaseBinding; controllerHome: string; endpoint: string; executable?: string; platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; forcePortable?: boolean; probeEndpoint?: (endpoint: string) => Promise<boolean> }): Promise<PackageConnectorServiceResult> {
   const paths = packageConnectorServicePaths(input.controllerHome, input.env?.HOME);
   mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
-  const launch = packageConnectorLaunchSpec({ release: input.release, controllerHome: input.controllerHome, endpoint: input.endpoint });
+  const launch = packageConnectorLaunchSpec({
+    release: input.release,
+    controllerHome: input.controllerHome,
+    endpoint: input.endpoint,
+    executable: input.executable,
+  });
   const platform = input.platform ?? process.platform, env = input.env ?? process.env;
   if (!input.forcePortable && platform === 'darwin') {
+    await retireConflictingForgeLaunchAgents({
+      accountHome: env.HOME,
+      desiredLabel: paths.label,
+      labelPrefix: 'com.moretea.forge.mcp-gateway',
+      port: launch.port,
+      requiredArguments: ['mcp', 'serve', '--auth', 'oauth'],
+    });
     atomicWrite(paths.sourcePlistPath, renderPackageConnectorLaunchAgent({ paths, launch }), 0o600);
     installLaunchAgent(paths.sourcePlistPath, paths.label);
     const result = await bootstrapLaunchAgentWithRetryV2({ label: paths.label, plistPath: paths.installedPlistPath });
     if (!result.ok) throw new Error(`FORGE_PACKAGE_CONNECTOR_LAUNCHD_INSTALL_FAILED: ${result.diagnostics.join('; ')}`);
-    return { endpoint: input.endpoint, mode: 'launchd', persistent: true, servicePath: paths.installedPlistPath };
+    const endpointReady = await waitForPackageConnectorEndpointReady(input.endpoint, { probeEndpoint: input.probeEndpoint });
+    if (!endpointReady) throw new Error(`FORGE_PACKAGE_CONNECTOR_ENDPOINT_NOT_READY: ${input.endpoint}`);
+    const installed = { endpoint: input.endpoint, mode: 'launchd' as const, persistent: true, servicePath: paths.installedPlistPath, releaseId: input.release.releaseId, releaseRoot: input.release.releaseRoot };
+    writePackageConnectorServiceAuthority({ release: input.release, controllerHome: input.controllerHome, result: installed });
+    return installed;
   }
   if (!input.forcePortable && platform === 'linux') {
     const probe = spawnSync('systemctl', ['--user', 'show-environment'], { encoding: 'utf8', env, timeout: 30_000 });
-    if (probe.status === 0) return { endpoint: input.endpoint, mode: 'systemd-user', persistent: true, servicePath: installSystemd(paths, launch, env) };
+    if (probe.status === 0) {
+      const installed = { endpoint: input.endpoint, mode: 'systemd-user' as const, persistent: true, servicePath: installSystemd(paths, launch, env), releaseId: input.release.releaseId, releaseRoot: input.release.releaseRoot };
+      writePackageConnectorServiceAuthority({ release: input.release, controllerHome: input.controllerHome, result: installed });
+      return installed;
+    }
+  }
+  const portable = { endpoint: input.endpoint, mode: 'portable' as const, persistent: false, pid: startPortable(paths, launch, env), releaseId: input.release.releaseId, releaseRoot: input.release.releaseRoot };
+  writePackageConnectorServiceAuthority({ release: input.release, controllerHome: input.controllerHome, result: portable });
+  return portable;
+}
+
+export async function ensurePackageConnectorService(input: {
+  release: PackageConnectorReleaseBinding;
+  controllerHome: string;
+  endpoint: string;
+  executable?: string;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  forcePortable?: boolean;
+  refresh?: boolean;
+  probeEndpoint?: (endpoint: string) => Promise<boolean>;
+}): Promise<PackageConnectorServiceResult> {
+  const platform = input.platform ?? process.platform;
+  if (!input.refresh && !input.forcePortable && platform === 'darwin') {
+    const paths = packageConnectorServicePaths(input.controllerHome, input.env?.HOME);
+    const port = Number(new URL(input.endpoint).port);
+    await retireConflictingForgeLaunchAgents({
+      accountHome: input.env?.HOME,
+      desiredLabel: paths.label,
+      labelPrefix: 'com.moretea.forge.mcp-gateway',
+      port,
+      requiredArguments: ['mcp', 'serve', '--auth', 'oauth'],
+    });
+  }
+  if (!input.refresh && !input.forcePortable) {
+    let authority: PackageConnectorServiceAuthority | undefined;
+    try { authority = readPackageConnectorServiceAuthority(input.controllerHome); } catch { authority = undefined; }
+    if (
+      authority?.persistent
+      && existsSync(authority.releaseRoot)
+      && existsSync(authority.packageRoot)
+      && packageConnectorServiceMatchesRelease({
+        authority,
+        release: input.release,
+        controllerHome: input.controllerHome,
+        endpoint: input.endpoint,
+        platform,
+        env: input.env,
+        executable: input.executable,
+      })
+      && await (input.probeEndpoint ?? defaultConnectorEndpointProbe)(input.endpoint)
+    ) {
+      return {
+        endpoint: authority.endpoint,
+        mode: authority.mode,
+        persistent: true,
+        ...(authority.servicePath ? { servicePath: authority.servicePath } : {}),
+        reused: true,
+        releaseId: authority.releaseId,
+        releaseRoot: authority.releaseRoot,
+      };
+    }
   }
-  return { endpoint: input.endpoint, mode: 'portable', persistent: false, pid: startPortable(paths, launch, env) };
+  return installPackageConnectorService(input);
 }