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

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

@@ -1,219 +1 @@
-import {
-  getWorkContract,
-  transitionWorkContractPhase,
-  updateWorkContract,
-} from '../../control-plane/facade/work-contract-store';
-import {
-  transitionWorkHandle,
-  type WorkHandleState,
-} from '../../control-plane/execution/work-handle-store';
-import { processCheckCompletionReceipt } from '../../execution/process-runtime/check-receipt';
-import { processCheckSemanticScopeKey } from '../../execution/process-runtime/check-facade';
-import { getProcessRecord } from '../../execution/process-runtime/store';
-import { controllerCheckExecutionIdentity } from '../../../cli/controller/check-runner';
-
-export type WorkValidationOutcome =
-  | 'not_validating'
-  | 'running'
-  | 'passed'
-  | 'failed'
-  | 'infrastructure_failure';
-
-export interface WorkValidationReconciliation {
-  handle: WorkHandleState;
-  changed: boolean;
-  outcome: WorkValidationOutcome;
-  summary?: string;
-}
-
-export function hasCurrentWorkValidationAuthority(input: {
-  finalizationValidation: WorkHandleState['finalization']['validation'];
-  validatedInputFingerprint?: string;
-  evidenceState: string;
-  expectedFingerprint: string;
-}): boolean {
-  return input.finalizationValidation === 'done'
-    && input.evidenceState === 'valid'
-    && input.validatedInputFingerprint === input.expectedFingerprint;
-}
-
-/**
- * A new validation run invalidates delivery authority without deleting or
- * rewriting the prior receipts. `stale` is the only valid transition from an
- * already-valid evidence set; all other retryable states converge through
- * `partial`.
- */
-export function markWorkValidationPending(controllerHome: string, handle: WorkHandleState): void {
-  const contractId = handle.workContractId;
-  if (!contractId) return;
-  const options = { controllerHome, repoId: handle.repositoryId };
-  const contract = getWorkContract(options, contractId);
-  if (!contract || contract.completionReceipt) return;
-  const evidenceState = contract.evidenceState === 'valid' || contract.evidenceState === 'stale'
-    ? 'stale'
-    : 'partial';
-  if (contract.evidenceState !== evidenceState) updateWorkContract(options, contractId, { evidenceState });
-}
-
-/**
- * Project durable validation evidence into the Work-owned contract lifecycle.
- * Process and Check records contribute evidence only; they never become a
- * second completion or lifecycle authority.
- */
-export function projectWorkValidationOutcome(
-  controllerHome: string,
-  handle: WorkHandleState,
-  outcome: Exclude<WorkValidationOutcome, 'not_validating' | 'running'>,
-  summary?: string,
-): void {
-  const contractId = handle.workContractId;
-  if (!contractId) return;
-  const options = { controllerHome, repoId: handle.repositoryId };
-  const contract = getWorkContract(options, contractId);
-  if (!contract || contract.completionReceipt) return;
-
-  if (outcome === 'passed') {
-    transitionWorkContractPhase(options, contractId, {
-      phase: 'delivery',
-      status: 'running',
-      state: 'active',
-      summary: summary ?? 'All requested validation receipts passed; delivery is next.',
-      evidenceRefs: contract.evidenceRefs,
-    });
-    updateWorkContract(options, contractId, { evidenceState: 'valid' });
-    return;
-  }
-
-  if (outcome === 'failed') {
-    transitionWorkContractPhase(options, contractId, {
-      phase: 'cleanup',
-      status: 'failed',
-      state: 'failed',
-      summary: summary ?? 'A requested validation check failed; terminal cleanup is next.',
-      evidenceRefs: contract.evidenceRefs,
-    });
-    updateWorkContract(options, contractId, { evidenceState: 'failed' });
-    return;
-  }
-
-  transitionWorkContractPhase(options, contractId, {
-    phase: 'cleanup',
-    status: 'failed',
-    state: 'failed',
-    summary: summary ?? 'Validation infrastructure failed; terminal cleanup is required without treating this as an acceptance failure.',
-    evidenceRefs: contract.evidenceRefs,
-  });
-  updateWorkContract(options, contractId, {
-    evidenceState: contract.evidenceState === 'valid' || contract.evidenceState === 'stale' ? 'stale' : 'partial',
-  });
-}
-
-function settleInfrastructureFailure(
-  controllerHome: string,
-  handle: WorkHandleState,
-  summary: string,
-): WorkValidationReconciliation {
-  const next = transitionWorkHandle(controllerHome, handle, 'failed', {
-    finalization: { ...handle.finalization, validation: 'failed', lastError: summary },
-    validationRun: undefined,
-    failureReason: summary,
-  });
-  projectWorkValidationOutcome(controllerHome, next, 'infrastructure_failure', summary);
-  return { handle: next, changed: true, outcome: 'infrastructure_failure', summary };
-}
-
-/**
- * Converge a persisted Work validation run from durable Process receipts.
- *
- * No command is launched here. Missing/running bindings stay pending; timeout,
- * cancellation, missing process state, or malformed receipt makes the Work
- * terminally failed for cleanup without classifying it as an acceptance failure.
- */
-export function reconcileWorkValidation(
-  controllerHome: string,
-  handle: WorkHandleState,
-): WorkValidationReconciliation {
-  const run = handle.validationRun;
-  if (handle.state !== 'validating' || !run) {
-    return { handle, changed: false, outcome: 'not_validating' };
-  }
-
-  if (run.requestedChecks.length === 0) {
-    const next = transitionWorkHandle(controllerHome, handle, run.resumeState, {
-      finalization: { ...handle.finalization, validation: 'done', lastError: undefined },
-      validationRun: undefined,
-      validatedInputFingerprint: run.fingerprint,
-      failureReason: undefined,
-    });
-    projectWorkValidationOutcome(controllerHome, next, 'passed', 'No validation checks were required.');
-    return { handle: next, changed: true, outcome: 'passed' };
-  }
-
-  for (const checkId of run.requestedChecks) {
-    const binding = run.processes[checkId];
-    if (!binding) return { handle, changed: false, outcome: 'running' };
-    const record = getProcessRecord(controllerHome, handle.repositoryId, binding.processId);
-    if (!record) {
-      return settleInfrastructureFailure(
-        controllerHome,
-        handle,
-        `Validation process record is unavailable: ${binding.processId}`,
-      );
-    }
-    if (record.status === 'running' || record.status === 'starting' || record.status === 'running_recovered') {
-      return { handle, changed: false, outcome: 'running' };
-    }
-
-    try {
-      const currentIdentity = record.checkExecution
-        ? controllerCheckExecutionIdentity(handle.worktreePath, checkId, record.checkExecution.timeoutMs)
-        : undefined;
-      const receipt = processCheckCompletionReceipt(record, {
-        repoId: handle.repositoryId,
-        checkoutId: handle.checkoutId,
-        workId: handle.workId,
-        executionSessionId: handle.sessionId,
-        checkId,
-        processId: binding.processId,
-        ...(currentIdentity ? {
-          checkExecution: {
-            cacheKey: currentIdentity.cacheKey,
-            revision: currentIdentity.revision,
-            definitionDigest: currentIdentity.definitionDigest,
-            environmentFingerprint: currentIdentity.environmentFingerprint,
-            timeoutMs: currentIdentity.timeoutMs,
-            scopeKey: processCheckSemanticScopeKey({
-              checkoutId: handle.checkoutId,
-              workId: handle.workId,
-              verificationBinding: { executionSessionId: handle.sessionId },
-            }, currentIdentity.reuseScope),
-          },
-        } : {}),
-      });
-      if (!receipt.ok) {
-        if (receipt.status === 'timed_out' || receipt.status === 'cancelled') {
-          return settleInfrastructureFailure(controllerHome, handle, receipt.summary);
-        }
-        const next = transitionWorkHandle(controllerHome, handle, 'failed', {
-          finalization: { ...handle.finalization, validation: 'failed', lastError: receipt.summary },
-          validationRun: undefined,
-          failureReason: receipt.summary,
-        });
-        projectWorkValidationOutcome(controllerHome, next, 'failed', receipt.summary);
-        return { handle: next, changed: true, outcome: 'failed', summary: receipt.summary };
-      }
-    } catch (error) {
-      const summary = error instanceof Error ? error.message : String(error);
-      return settleInfrastructureFailure(controllerHome, handle, summary);
-    }
-  }
-
-  const next = transitionWorkHandle(controllerHome, handle, run.resumeState, {
-    finalization: { ...handle.finalization, validation: 'done', lastError: undefined },
-    validationRun: undefined,
-    validatedInputFingerprint: run.fingerprint,
-    failureReason: undefined,
-  });
-  projectWorkValidationOutcome(controllerHome, next, 'passed', 'All requested validation receipts passed.');
-  return { handle: next, changed: true, outcome: 'passed' };
-}
+export * from '../../control-plane/execution/work-validation-reconciler';

package/src/runtime/plugins/browser-adapter.ts

@@ -383,6 +383,11 @@ function loadConfig(repoRoot: string): BrowserPluginConfig {
   return normalizeConfig(readJson<Partial<BrowserPluginConfig>>(configPath(repoRoot)) ?? {});
 }
 
+export function readBrowserPluginConfiguration(repoRoot: string): { enabled: boolean; allowedDomains: string[] } {
+  const config = loadConfig(repoRoot);
+  return { enabled: config.enabled, allowedDomains: [...(config.allowedDomains ?? [])] };
+}
+
 function saveConfig(repoRoot: string, patch: Partial<BrowserPluginConfig>): BrowserPluginConfig {
   const next = normalizeConfig({ ...loadConfig(repoRoot), ...patch });
   writeJson(configPath(repoRoot), next);

package/src/runtime/plugins/desktop-operator-registration.ts

@@ -384,7 +384,7 @@ export function createDesktopOperatorRegistrationInput(
     providerPluginId: 'desktop_operator',
     displayName: 'Forge Desktop Operator',
     provider: 'local-macos',
-    pluginVersion: options.pluginVersion ?? '0.1.0',
+    pluginVersion: options.pluginVersion ?? '0.2.1',
     protocolVersion: options.protocolVersion ?? '1.0',
     scope: 'controller',
     enabled: options.enabled !== false,

package/src/runtime/plugins/store.ts

@@ -265,13 +265,21 @@ function writeRegistry(controllerHome: string, repoId: string, manifests: Assist
   return index;
 }
 
-function mapResourceClaims(action: AssistantPluginActionDescriptor, repository: RepositoryRecord): ResourceClaimSpec[] {
+export function claimsForAssistantPluginAction(
+  action: AssistantPluginActionDescriptor,
+  repository: RepositoryRecord,
+  trustedPluginId: string,
+): ResourceClaimSpec[] {
   const controllerScoped = repository.repoId === CONTROLLER_SCOPE_REPO_ID;
+  const pluginId = trustedPluginId.trim().replace(/[^a-zA-Z0-9._-]+/g, '-');
+  if (!pluginId) throw new Error('PLUGIN_ID_REQUIRED_FOR_RESOURCE_CLAIMS');
   return action.resourceClaims.map((claim) => ({
-    resourceKey: controllerScoped
-      ? `controller-system:${claim.resource}`
-      : claim.resource === 'remote'
-        ? `remote:${repository.repoId}`
+    resourceKey: claim.resource === 'remote' || claim.resource === 'provider-state'
+      // The manifest/plugin id was resolved from the trusted registration; a
+      // provider never supplies arbitrary resource-key text.
+      ? `provider-state:${pluginId}`
+      : controllerScoped
+        ? `controller-system:${claim.resource}`
         : claim.resource === 'workspace'
           ? `workspace:${repository.activeCheckoutId}`
           : claim.resource === 'git-refs'
@@ -764,7 +772,7 @@ export async function submitAssistantPluginAction(
           mode: 'mutating',
           idempotent: action.idempotent,
           replayable: action.idempotent,
-          resourceClaims: mapResourceClaims(action, repository),
+          resourceClaims: claimsForAssistantPluginAction(action, repository, manifest.pluginId),
         },
         objective: `Execute bounded controller-local effect ${request.pluginId}/${request.actionId}`,
         mode: 'direct_control',

package/src/runtime/plugins/types.ts

@@ -4,7 +4,7 @@ export type AssistantPluginLifecycleState = 'enabled' | 'disabled' | 'degraded'
 export type AssistantPluginHealthState = 'ready' | 'disabled' | 'degraded' | 'error';
 export type AssistantPluginActionRisk = 'readonly' | 'workspace_write' | 'remote_write' | 'destructive';
 export type AssistantPluginActionConfirmation = 'none' | 'authorization' | 'strong_confirmation';
-export type AssistantPluginResource = 'repo-state' | 'workspace' | 'remote' | 'git-refs';
+export type AssistantPluginResource = 'repo-state' | 'workspace' | 'remote' | 'git-refs' | 'provider-state';
 
 export interface AssistantPluginPermissionScope {
   scope: string;

package/src/runtime/projections/materialized-view.ts

@@ -22,7 +22,6 @@ import {
   type ProjectionRefreshOwner,
 } from './invalidation';
 import { readRepositoryGitStatusSample } from './git-status-sampler';
-import { listCampaigns } from '../workflow/campaigns/store';
 import { listAssistantPluginManifests } from '../plugins/store';
 import type { ProjectionObservation, ProjectionSourceReconciliation } from '../health';
 import { RUNTIME_HEALTH_THRESHOLDS } from '../health/evaluator';
@@ -60,12 +59,6 @@ export interface RepositoryRuntimeProjection {
     degraded: number;
     error: number;
   };
-  campaigns?: {
-    active: number;
-    waitingForSupervisor: number;
-    pendingReviews: number;
-    readyForHumanAcceptance: number;
-  };
 }
 
 interface DirtyProjectionReadCacheEntry {
@@ -112,12 +105,6 @@ function emptyProjection(repoId: string, reason?: string): RepositoryRuntimeProj
       degraded: 0,
       error: 0,
     },
-    campaigns: {
-      active: 0,
-      waitingForSupervisor: 0,
-      pendingReviews: 0,
-      readyForHumanAcceptance: 0,
-    },
   };
 }
 
@@ -191,7 +178,7 @@ function projectionWithExecutionIndexOverlay(
 }
 
 function dirtyReasonImpliesActiveRisk(reason: string | undefined): boolean {
-  return Boolean(reason && /^(job:|leases-|campaign:|schedule:|worker:|process:|cleanup:)/.test(reason));
+  return Boolean(reason && /^(job:|leases-|schedule:|worker:|process:|cleanup:)/.test(reason));
 }
 
 function buildRepositoryProjection(
@@ -210,8 +197,6 @@ function buildRepositoryProjection(
   // Terminal attention records remain in history for diagnosis and audit, but only
   // active/unresolved records should influence "current readiness" decisions.
   const currentAttentionJobs = attentionJobs.filter((job) => !job.finishedAt || activeJobIds.has(job.jobId));
-  const campaigns = listCampaigns(controllerHome, repoId, 1_000);
-  const reviewableCampaigns = campaigns.filter((campaign) => ['active', 'waiting_for_supervisor'].includes(campaign.status));
   const repository = listRepositories(controllerHome).find((entry) => entry.repoId === repoId);
   const plugins = repository ? listAssistantPluginManifests(controllerHome, repository, {
     preferStored: true,
@@ -251,12 +236,6 @@ function buildRepositoryProjection(
       degraded: plugins.filter((plugin) => plugin.health.state === 'degraded').length,
       error: plugins.filter((plugin) => plugin.health.state === 'error').length,
     },
-    campaigns: {
-      active: campaigns.filter((campaign) => campaign.status === 'active').length,
-      waitingForSupervisor: campaigns.filter((campaign) => campaign.status === 'waiting_for_supervisor').length,
-      pendingReviews: reviewableCampaigns.reduce((count, campaign) => count + campaign.checkpoints.filter((checkpoint) => checkpoint.status === 'open').length, 0),
-      readyForHumanAcceptance: campaigns.filter((campaign) => campaign.status === 'ready_for_human_acceptance').length,
-    },
   };
   projection.metadata = {
     ...projection.metadata!,
@@ -270,7 +249,6 @@ function buildRepositoryProjection(
       currentAttention: projection.currentAttention,
       attention: projection.attention,
       plugins: projection.plugins,
-      campaigns: projection.campaigns,
     })).digest('hex'),
   };
   return projection;

package/src/runtime/recovery/maintenance-executor.ts

@@ -19,6 +19,7 @@ import {
   type RuntimeStorageRepairApplyResult,
   type RuntimeStorageRepairPreview,
 } from './local-jobs-repair';
+import { gcTerminalProcesses, type ProcessGcResult } from '../execution/process-runtime/gc';
 
 export type RuntimeMaintenanceActionId =
   | 'local_jobs_reconcile'
@@ -118,6 +119,8 @@ export interface RuntimeMaintenanceApplyResult extends Omit<RuntimeMaintenanceSt
   actionId: RuntimeMaintenanceActionId;
   applied: Array<RuntimeMaintenanceCandidate & { applied: boolean; result?: string; error?: string }>;
   runtimeStorageRepairApply?: RuntimeStorageRepairApplyResult;
+  /** Existing bounded terminal-process retention, run only during explicit full maintenance. */
+  processGc?: ProcessGcResult;
   projection?: unknown;
 }
 
@@ -801,6 +804,11 @@ export function applyRuntimeMaintenance(
       return { ...candidate, applied: false, error: error instanceof Error ? error.message : String(error) };
     }
   });
+  // Reuse the existing Process GC within the explicit full-maintenance cadence.
+  // No scheduler, per-tool-call cleanup, or database compaction is introduced.
+  const processGc = options.actionId === 'full_maintenance_pass'
+    ? gcTerminalProcesses({ controllerHome, repoId: repository.repoId })
+    : undefined;
 
   if (options.actionId === 'runtime_storage_finalize_relocation' || options.actionId === 'full_maintenance_pass' || applied.some((candidate) => candidate.applied) || runtimeStorageRepairApply) {
     rebuildActiveIndex(repository.canonicalRoot);
@@ -817,6 +825,7 @@ export function applyRuntimeMaintenance(
     runtimeStorageError: after.runtimeStorageError ?? storage.error,
     applied,
     runtimeStorageRepairApply,
+    processGc,
     projection,
   };
 }

package/src/runtime/resources/ownership.ts

@@ -1,7 +1,6 @@
 export type ResourceOwnerKind =
   | 'execution_job'
   | 'agent_run'
-  | 'campaign'
   | 'work_contract'
   | 'edit_session'
   | 'controller_generation'

package/src/runtime/root/gateway-adapter.ts

@@ -8,6 +8,7 @@ export interface RuntimeGatewayServerOptions {
   runtimeInstanceId: string;
   runtimeSourceRoot: string;
   sessionId?: string;
+  controllerType?: 'chatgpt' | 'codex' | 'claude' | 'grok';
 }
 
 /**
@@ -28,6 +29,7 @@ export function createRuntimeGatewayServer(
     profile: 'controller',
     principalId,
     sessionId: options.sessionId,
+    controllerType: options.controllerType,
     controllerInstanceId: options.runtimeInstanceId,
     runtimeSourceRoot: options.runtimeSourceRoot,
   });

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

@@ -17,12 +17,14 @@ export interface RuntimeMcpTransportHandle {
   close(): Promise<void>;
 }
 
+export type ForwardedControllerType = 'chatgpt' | 'codex' | 'claude' | 'grok';
+
 export interface StartRuntimeMcpTransportOptions {
   host: string;
   port: number;
   authToken: string;
   readiness: () => RuntimeReadiness;
-  createServer: (principalId: string, sessionId?: string) => Server;
+  createServer: (principalId: string, sessionId?: string, controllerType?: ForwardedControllerType) => Server;
   onFatal?: (error: Error) => void;
 }
 
@@ -99,8 +101,14 @@ export async function startRuntimeMcpTransport(
         const forwardedSessionId = typeof req.headers['x-forge-forwarded-session-id'] === 'string'
           ? req.headers['x-forge-forwarded-session-id'].trim().slice(0, 512)
           : '';
+        const forwardedControllerTypeRaw = typeof req.headers['x-forge-forwarded-controller-type'] === 'string'
+          ? req.headers['x-forge-forwarded-controller-type'].trim().toLowerCase()
+          : '';
+        const forwardedControllerType = ['chatgpt', 'codex', 'claude', 'grok'].includes(forwardedControllerTypeRaw)
+          ? forwardedControllerTypeRaw as ForwardedControllerType
+          : undefined;
         const principal = forwardedPrincipalId || principalId(options.authToken);
-        const server = options.createServer(principal, forwardedSessionId || undefined);
+        const server = options.createServer(principal, forwardedSessionId || undefined, forwardedControllerType);
         transport = new StreamableHTTPServerTransport({
           sessionIdGenerator: () => randomUUID(),
           onsessioninitialized: (createdSessionId) => {

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

@@ -0,0 +1,136 @@
+import { createHash } from 'crypto';
+import { closeSync, mkdirSync, openSync, 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 type { PackageRuntimeRelease } from './package-runtime-release';
+
+export interface PackageConnectorServicePaths {
+  label: string;
+  serviceRoot: string;
+  sourcePlistPath: string;
+  installedPlistPath: string;
+  stdoutPath: string;
+  stderrPath: string;
+}
+
+export interface PackageConnectorServiceResult {
+  endpoint: string;
+  mode: 'launchd' | 'systemd-user' | 'portable';
+  persistent: boolean;
+  servicePath?: string;
+  pid?: number;
+}
+
+function xml(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+}
+
+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);
+}
+
+export function packageConnectorServicePaths(controllerHome: string, accountHome = process.env.HOME ?? homedir()): PackageConnectorServicePaths {
+  const home = resolve(controllerHome);
+  const suffix = createHash('sha256').update(home).digest('hex').slice(0, 12);
+  const label = `com.moretea.forge.mcp-gateway.${suffix}`;
+  const serviceRoot = join(home, 'runtime', 'connector-service');
+  return {
+    label,
+    serviceRoot,
+    sourcePlistPath: join(serviceRoot, `${label}.plist`),
+    installedPlistPath: launchAgentPath(label, accountHome),
+    stdoutPath: join(serviceRoot, 'logs', 'stdout.log'),
+    stderrPath: join(serviceRoot, 'logs', 'stderr.log'),
+  };
+}
+
+export function packageConnectorLaunchSpec(input: { release: PackageRuntimeRelease; 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 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),
+    '--transport', 'http', '--host', '127.0.0.1', '--port', String(port), '--profile', 'controller', '--auth', 'oauth',
+  ];
+  return {
+    executable,
+    args: isBun ? [cliEntry, ...cliArgs] : ['--loader', nodeLoader, cliEntry, ...cliArgs],
+    environment: { FORGE_CONTROLLER_HOME: resolve(input.controllerHome), FORGE_CONTROLLER_LIFECYCLE_OWNER: '1' },
+    port,
+  };
+}
+
+export function renderPackageConnectorLaunchAgent(input: { paths: PackageConnectorServicePaths; launch: ReturnType<typeof packageConnectorLaunchSpec> }): string {
+  const environmentXml = Object.entries(input.launch.environment).sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `    <key>${xml(key)}</key>\n    <string>${xml(value)}</string>`).join('\n');
+  const args = [input.launch.executable, ...input.launch.args];
+  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  <key>EnvironmentVariables</key>\n  <dict>\n${environmentXml}\n  </dict>\n  <key>RunAtLoad</key>\n  <true/>\n  <key>KeepAlive</key>\n  <dict><key>SuccessfulExit</key><false/></dict>\n  <key>ThrottleInterval</key><integer>5</integer>\n  <key>StandardOutPath</key><string>${xml(input.paths.stdoutPath)}</string>\n  <key>StandardErrorPath</key><string>${xml(input.paths.stderrPath)}</string>\n</dict>\n</plist>\n`;
+}
+
+export function renderPackageConnectorSystemdUserUnit(input: { launch: ReturnType<typeof packageConnectorLaunchSpec> }): string {
+  const quote = (value: string) => `"${value.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+  const env = Object.entries(input.launch.environment).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `Environment=${quote(`${k}=${v}`)}`);
+  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');
+}
+
+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);
+  atomicWrite(unitPath, renderPackageConnectorSystemdUserUnit({ launch }), 0o644);
+  for (const args of [['--user', 'daemon-reload'], ['--user', 'enable', '--now', unitName]]) {
+    const result = spawnSync('systemctl', args, { encoding: 'utf8', env, timeout: 30_000 });
+    if (result.status !== 0) throw new Error(`FORGE_PACKAGE_CONNECTOR_SYSTEMD_INSTALL_FAILED: ${(result.stderr || result.stdout || '').trim()}`);
+  }
+  return unitPath;
+}
+
+function startPortable(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv): number {
+  mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
+  const stdout = openSync(paths.stdoutPath, 'a', 0o600), stderr = openSync(paths.stderrPath, 'a', 0o600);
+  // A connector is not the Canonical Runtime writer. Never let a transient
+  // installer/worker write claim escape into this long-lived process; the claim
+  // would become stale as soon as its parent exits. Keep only the explicit
+  // Controller Home and lifecycle-role marker from launch.environment.
+  const childEnv = { ...env };
+  for (const key of [
+    'FORGE_RUNTIME_INSTANCE_ID', 'FORGE_RUNTIME_OWNER_PID', 'FORGE_RELEASE_AUTHORITY_REVISION',
+    'FORGE_RELEASE_FENCING_TOKEN', 'FORGE_RELEASE_ID', 'FORGE_ARTIFACT_IDENTITY', 'FORGE_WORKER_PROTOCOL_VERSION',
+  ]) delete childEnv[key];
+  try {
+    const child = spawn(launch.executable, launch.args, { detached: true, stdio: ['ignore', stdout, stderr], env: { ...childEnv, ...launch.environment } });
+    if (!child.pid) throw new Error('FORGE_PACKAGE_CONNECTOR_START_FAILED');
+    child.unref();
+    return child.pid;
+  } 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> {
+  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 platform = input.platform ?? process.platform, env = input.env ?? process.env;
+  if (!input.forcePortable && platform === 'darwin') {
+    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 };
+  }
+  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) };
+  }
+  return { endpoint: input.endpoint, mode: 'portable', persistent: false, pid: startPortable(paths, launch, env) };
+}