@moretea-labs/forge 1.7.2 → 1.8.0

package/src/runtime/plugins/google-calendar-adapter.ts

@@ -1,6 +1,7 @@
 import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
+  AssistantPluginBuildContext,
   AssistantPluginCapability,
   AssistantPluginManifest,
   AssistantPluginPermissionScope,
@@ -9,7 +10,6 @@ import { AssistantPluginError } from './errors';
 import {
   type GoogleCalendarPluginConfig,
   googleApiRequest,
-  googleCalendarPluginConfigPath,
   googlePermission,
   loadGoogleCalendarPluginConfig,
   pluginStateFromGoogleAuth,
@@ -391,9 +391,9 @@ function calendarProvider(config: GoogleCalendarPluginConfig, repoRoot?: string)
   return config.provider === 'mock' ? mockCalendarProvider() : liveCalendarProvider(config, repoRoot);
 }
 
-export function buildGoogleCalendarPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string): AssistantPluginManifest {
+export function buildGoogleCalendarPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest {
   const root = repoRoot ?? process.cwd();
-  const config = loadGoogleCalendarPluginConfig(root);
+  const config = loadGoogleCalendarPluginConfig(root, context);
   const auth = resolveGoogleAuth('calendar', config, { repoRoot: root });
   const state = pluginStateFromGoogleAuth(config, auth);
   return {
@@ -407,7 +407,7 @@ export function buildGoogleCalendarPluginManifest(previousRevision = 0, previous
     authority: {
       strategy: 'derived',
       duplicateStateAllowed: false,
-      sourceOfTruth: [`repo-local:${googleCalendarPluginConfigPath()}`, 'env:FORGE_*_ACCESS_TOKEN'],
+      sourceOfTruth: ['controller-home:repositories/<repoId>/plugins/config/google-calendar.json', 'env:FORGE_*_ACCESS_TOKEN'],
     },
     enabled: config.enabled,
     lifecycle: {
@@ -427,11 +427,11 @@ export function buildGoogleCalendarPluginManifest(previousRevision = 0, previous
 }
 
 export async function executeGoogleCalendarPluginAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>> {
-  const current = loadGoogleCalendarPluginConfig(input.repoRoot);
+  const current = loadGoogleCalendarPluginConfig(input.repoRoot, input);
   switch (input.actionId) {
     case 'configure': {
       const args = input.args;
-      const config = saveGoogleCalendarPluginConfig(input.repoRoot, {
+      const config = saveGoogleCalendarPluginConfig(input, {
         enabled: typeof args.enabled === 'boolean' ? args.enabled : current.enabled,
         provider: args.provider === 'google-workspace' ? 'google-workspace' : args.provider === 'mock' ? 'mock' : current.provider,
         accountEmail: args.clear_account_email === true ? undefined : stringValue(args.account_email) ?? current.accountEmail,

package/src/runtime/plugins/google-shared.ts

@@ -1,6 +1,4 @@
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { dirname, join } from 'path';
 import type {
   AssistantPluginHealth,
   AssistantPluginLifecycleState,
@@ -9,6 +7,7 @@ import type {
 import { AssistantPluginError, toAssistantPluginError } from './errors';
 import { bootstrapManagedRuntimeEnv } from '../shared/managed-env';
 import { readStoredGoogleRefreshToken } from '../safe-tooling/google-credential-store';
+import { readRepositoryPluginConfig, writeRepositoryPluginConfig, type RepositoryPluginConfigContext } from './config-store';
 
 export type GoogleProviderKind = 'mock' | 'google-workspace';
 export type GoogleService = 'gmail' | 'calendar' | 'tasks';
@@ -59,7 +58,6 @@ export interface GoogleApiRequestOptions {
   timeoutMs?: number;
 }
 
-const CONFIG_ROOT = '.forge/plugins';
 const REFRESH_REQUIRED_ACCESS_TOKEN = '__forge_refresh_required__';
 
 interface CachedGoogleCredential {
@@ -144,10 +142,6 @@ export function installGoogleAccessToken(service: GoogleService, accessToken: st
   });
 }
 
-function repoPluginConfigPath(repoRoot: string, pluginId: string): string {
-  return join(repoRoot, CONFIG_ROOT, `${pluginId}.json`);
-}
-
 function stringValue(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
@@ -219,75 +213,66 @@ export function normalizeGoogleTasksPluginConfig(raw: Partial<GoogleTasksPluginC
 
 function loadPluginConfig<T extends GooglePluginConfig>(
   repoRoot: string,
+  context: Pick<RepositoryPluginConfigContext, 'controllerHome' | 'repoId'> | undefined,
   pluginId: string,
   normalize: (raw: Partial<T>) => T,
   defaults: () => T,
 ): T {
-  const path = repoPluginConfigPath(repoRoot, pluginId);
-  if (!existsSync(path)) return defaults();
-  try {
-    return normalize(JSON.parse(readFileSync(path, 'utf-8')) as Partial<T>);
-  } catch {
-    return defaults();
-  }
+  if (!context) return defaults();
+  const persisted = readRepositoryPluginConfig<Partial<T>>({ ...context, repoRoot }, pluginId);
+  return persisted ? normalize(persisted) : defaults();
 }
 
 function writePluginConfig<T extends GooglePluginConfig>(
-  repoRoot: string,
+  context: RepositoryPluginConfigContext,
   pluginId: string,
   config: T,
 ): T {
-  const path = repoPluginConfigPath(repoRoot, pluginId);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
-  return config;
-}
-
-export function gmailPluginConfigPath(): string {
-  return `${CONFIG_ROOT}/gmail.json`;
-}
-
-export function googleCalendarPluginConfigPath(): string {
-  return `${CONFIG_ROOT}/google-calendar.json`;
+  return writeRepositoryPluginConfig(context, pluginId, config);
 }
 
-export function googleTasksPluginConfigPath(): string {
-  return `${CONFIG_ROOT}/google-tasks.json`;
-}
-
-export function loadGmailPluginConfig(repoRoot: string): GmailPluginConfig {
-  return loadPluginConfig(repoRoot, 'gmail', normalizeGmailPluginConfig, defaultGmailPluginConfig);
+export function loadGmailPluginConfig(
+  repoRoot: string,
+  context?: Pick<RepositoryPluginConfigContext, 'controllerHome' | 'repoId'>,
+): GmailPluginConfig {
+  return loadPluginConfig(repoRoot, context, 'gmail', normalizeGmailPluginConfig, defaultGmailPluginConfig);
 }
 
-export function loadGoogleCalendarPluginConfig(repoRoot: string): GoogleCalendarPluginConfig {
-  return loadPluginConfig(repoRoot, 'google-calendar', normalizeGoogleCalendarPluginConfig, defaultGoogleCalendarPluginConfig);
+export function loadGoogleCalendarPluginConfig(
+  repoRoot: string,
+  context?: Pick<RepositoryPluginConfigContext, 'controllerHome' | 'repoId'>,
+): GoogleCalendarPluginConfig {
+  return loadPluginConfig(repoRoot, context, 'google-calendar', normalizeGoogleCalendarPluginConfig, defaultGoogleCalendarPluginConfig);
 }
 
-export function loadGoogleTasksPluginConfig(repoRoot: string): GoogleTasksPluginConfig {
-  return loadPluginConfig(repoRoot, 'google-tasks', normalizeGoogleTasksPluginConfig, defaultGoogleTasksPluginConfig);
+export function loadGoogleTasksPluginConfig(
+  repoRoot: string,
+  context?: Pick<RepositoryPluginConfigContext, 'controllerHome' | 'repoId'>,
+): GoogleTasksPluginConfig {
+  return loadPluginConfig(repoRoot, context, 'google-tasks', normalizeGoogleTasksPluginConfig, defaultGoogleTasksPluginConfig);
 }
 
 export type GooglePluginConfigPatch<T extends GooglePluginConfig> = Partial<Omit<T, 'schemaVersion'>>;
 
-export function saveGmailPluginConfig(repoRoot: string, patch: GooglePluginConfigPatch<GmailPluginConfig>): GmailPluginConfig {
-  const current = loadGmailPluginConfig(repoRoot);
-  return writePluginConfig(repoRoot, 'gmail', normalizeGmailPluginConfig({ ...current, ...patch }));
+export function saveGmailPluginConfig(context: RepositoryPluginConfigContext, patch: GooglePluginConfigPatch<GmailPluginConfig>): GmailPluginConfig {
+  const current = loadGmailPluginConfig(context.repoRoot, context);
+  return writePluginConfig(context, 'gmail', normalizeGmailPluginConfig({ ...current, ...patch }));
 }
 
 export function saveGoogleCalendarPluginConfig(
-  repoRoot: string,
+  context: RepositoryPluginConfigContext,
   patch: GooglePluginConfigPatch<GoogleCalendarPluginConfig>,
 ): GoogleCalendarPluginConfig {
-  const current = loadGoogleCalendarPluginConfig(repoRoot);
-  return writePluginConfig(repoRoot, 'google-calendar', normalizeGoogleCalendarPluginConfig({ ...current, ...patch }));
+  const current = loadGoogleCalendarPluginConfig(context.repoRoot, context);
+  return writePluginConfig(context, 'google-calendar', normalizeGoogleCalendarPluginConfig({ ...current, ...patch }));
 }
 
 export function saveGoogleTasksPluginConfig(
-  repoRoot: string,
+  context: RepositoryPluginConfigContext,
   patch: GooglePluginConfigPatch<GoogleTasksPluginConfig>,
 ): GoogleTasksPluginConfig {
-  const current = loadGoogleTasksPluginConfig(repoRoot);
-  return writePluginConfig(repoRoot, 'google-tasks', normalizeGoogleTasksPluginConfig({ ...current, ...patch }));
+  const current = loadGoogleTasksPluginConfig(context.repoRoot, context);
+  return writePluginConfig(context, 'google-tasks', normalizeGoogleTasksPluginConfig({ ...current, ...patch }));
 }
 
 function tokenEnvNames(service: GoogleService): string[] {

package/src/runtime/plugins/google-tasks-adapter.ts

@@ -1,6 +1,7 @@
 import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
+  AssistantPluginBuildContext,
   AssistantPluginCapability,
   AssistantPluginManifest,
   AssistantPluginPermissionScope,
@@ -10,7 +11,6 @@ import {
   type GoogleTasksPluginConfig,
   googleApiRequest,
   googlePermission,
-  googleTasksPluginConfigPath,
   loadGoogleTasksPluginConfig,
   pluginStateFromGoogleAuth,
   resolveGoogleAuth,
@@ -454,9 +454,9 @@ function tasksProvider(config: GoogleTasksPluginConfig, repoRoot?: string): Task
   return config.provider === 'mock' ? mockTasksProvider() : liveTasksProvider(config, repoRoot);
 }
 
-export function buildGoogleTasksPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string): AssistantPluginManifest {
+export function buildGoogleTasksPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest {
   const root = repoRoot ?? process.cwd();
-  const config = loadGoogleTasksPluginConfig(root);
+  const config = loadGoogleTasksPluginConfig(root, context);
   const auth = resolveGoogleAuth('tasks', config, { repoRoot: root });
   const state = pluginStateFromGoogleAuth(config, auth);
   return {
@@ -470,7 +470,7 @@ export function buildGoogleTasksPluginManifest(previousRevision = 0, previousUpd
     authority: {
       strategy: 'derived',
       duplicateStateAllowed: false,
-      sourceOfTruth: [`repo-local:${googleTasksPluginConfigPath()}`, 'env:FORGE_*_ACCESS_TOKEN'],
+      sourceOfTruth: ['controller-home:repositories/<repoId>/plugins/config/google-tasks.json', 'env:FORGE_*_ACCESS_TOKEN'],
     },
     enabled: config.enabled,
     lifecycle: {
@@ -490,11 +490,11 @@ export function buildGoogleTasksPluginManifest(previousRevision = 0, previousUpd
 }
 
 export async function executeGoogleTasksPluginAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>> {
-  const current = loadGoogleTasksPluginConfig(input.repoRoot);
+  const current = loadGoogleTasksPluginConfig(input.repoRoot, input);
   switch (input.actionId) {
     case 'configure': {
       const args = input.args;
-      const config = saveGoogleTasksPluginConfig(input.repoRoot, {
+      const config = saveGoogleTasksPluginConfig(input, {
         enabled: typeof args.enabled === 'boolean' ? args.enabled : current.enabled,
         provider: args.provider === 'google-workspace' ? 'google-workspace' : args.provider === 'mock' ? 'mock' : current.provider,
         accountEmail: args.clear_account_email === true ? undefined : stringValue(args.account_email) ?? current.accountEmail,

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

@@ -43,7 +43,6 @@ import {
 } from './ios-physical-device';
 
 const IOS_PLUGIN_ID = 'ios';
-const CONFIG_ROOT = '.forge/plugins';
 
 function now(): string {
   return new Date().toISOString();
@@ -414,7 +413,7 @@ export function buildIosPluginManifest(previousRevision = 0, previousUpdatedAt?:
     authority: {
       strategy: 'derived',
       duplicateStateAllowed: false,
-      sourceOfTruth: ['local:xcodebuild', 'local:simctl', 'local:devicectl', 'local:agent-device-capability-contract', 'process-env:DEVELOPER_DIR', 'process-env:AGENT_DEVICE_IOS_TEAM_ID', 'process-env:AGENT_DEVICE_IOS_BUNDLE_ID', `repo-local:${CONFIG_ROOT}/ios.json`],
+      sourceOfTruth: ['local:xcodebuild', 'local:simctl', 'local:devicectl', 'local:agent-device-capability-contract', 'process-env:DEVELOPER_DIR', 'process-env:AGENT_DEVICE_IOS_TEAM_ID', 'process-env:AGENT_DEVICE_IOS_BUNDLE_ID'],
     },
     enabled,
     lifecycle: {

package/src/runtime/plugins/local-system-adapter.ts

@@ -16,6 +16,9 @@ import {
 } from 'fs';
 import { dirname, extname, join, resolve } from 'path';
 import { forgeRuntimeServicePaths } from '../root/service';
+import { createRecoveryConfig, loadRecoveryConfig, repairPublicTunnel } from '../standalone-recovery/core';
+import { activateRecoveryRelease, recoverySourceIdentity, stageRecoveryRelease } from '../standalone-recovery/installer';
+import { readCurrentRecoveryRelease, type RecoveryReleaseDescriptor } from '../standalone-recovery/release';
 import {
   WorkspaceTargetGrantError,
   authorizeWorkspaceTargetGrant,
@@ -48,6 +51,7 @@ import {
   assertRepositoryCommandInputAllowed,
 } from '../../cli/repositories/command-scope';
 import { runCanonicalCommand } from '../../cli/repositories/command-executor';
+import { findRegisteredRepositoryByCheckoutRoot, listRepositories, repositoryCheckoutLifecycle } from '../../cli/repositories/registry';
 
 const PLUGIN_ID = 'local_system';
 const MAX_OUTPUT_BYTES = 64 * 1024;
@@ -73,6 +77,11 @@ export interface LocalSystemPluginHooks {
   runCommand?: (command: string, args: string[], timeoutMs?: number) => CommandResult;
   signalProcess?: (pid: number, signal: NodeJS.Signals) => void;
   scheduleLaunchAgentRestart?: (service: string) => { pid: number };
+  upgradeStandaloneRecovery?: (controllerHome: string) => Promise<Record<string, unknown>>;
+  repairPublicTunnel?: typeof repairPublicTunnel;
+  recoverySourceIdentity?: typeof recoverySourceIdentity;
+  stageRecoveryRelease?: typeof stageRecoveryRelease;
+  activateRecoveryRelease?: typeof activateRecoveryRelease;
 }
 
 let hooks: LocalSystemPluginHooks = {};
@@ -625,6 +634,171 @@ export function startVerifiedUserLaunchAgent(labelValue: unknown, expectedProgra
   return { started: true, label: identity.label, service: identity.service, plistPath: identity.plistPath, bootstrapCommand, enableCommand: enabled.command, startCommand: started.command };
 }
 
+function boundedRecoveryRelease(release: RecoveryReleaseDescriptor | undefined): Record<string, unknown> | undefined {
+  if (!release) return undefined;
+  return {
+    releaseRevision: release.releaseRevision,
+    sourceCommit: release.sourceCommit,
+    manifestSha256: release.manifestSha256,
+    legacy: release.legacy,
+  };
+}
+
+interface RecoveryUpgradeSourceRepair {
+  performed: true;
+  repositoryId: string;
+  previousSourceRoot: string;
+  currentSourceRoot: string;
+}
+
+function resolveRecoveryUpgradeSource(controllerHome: string, configuredSourceRoot: string): {
+  sourceRoot: string;
+  repositoryId: string;
+  repair?: RecoveryUpgradeSourceRepair;
+} {
+  const configured = resolve(configuredSourceRoot);
+  if (existsSync(configured)) {
+    const owner = findRegisteredRepositoryByCheckoutRoot(configured, controllerHome);
+    if (!owner) throw new Error(`RECOVERY_SOURCE_REPOSITORY_NOT_REGISTERED: ${configured}`);
+    return { sourceRoot: configured, repositoryId: owner.repoId };
+  }
+
+  const owners = listRepositories(controllerHome)
+    .filter((repository) => repository.enabled !== false)
+    .filter((repository) => repository.checkouts.some((checkout) => (
+      checkout.worktree === true
+      && repositoryCheckoutLifecycle(checkout) !== 'active'
+      && [checkout.localRoot, checkout.canonicalRoot]
+        .filter((candidate): candidate is string => Boolean(candidate?.trim()))
+        .some((candidate) => resolve(candidate) === configured)
+    )));
+  if (owners.length !== 1) {
+    throw new Error(owners.length === 0
+      ? `RECOVERY_SOURCE_REPAIR_LINEAGE_NOT_FOUND: ${configured}`
+      : `RECOVERY_SOURCE_REPAIR_LINEAGE_AMBIGUOUS: ${configured}`);
+  }
+  const owner = owners[0]!;
+  const canonical = resolve(owner.canonicalRoot);
+  if (!existsSync(canonical)) {
+    throw new Error(`RECOVERY_SOURCE_REPAIR_CANONICAL_MISSING: ${canonical}`);
+  }
+  return {
+    sourceRoot: canonical,
+    repositoryId: owner.repoId,
+    repair: {
+      performed: true,
+      repositoryId: owner.repoId,
+      previousSourceRoot: configured,
+      currentSourceRoot: canonical,
+    },
+  };
+}
+
+async function upgradeStandaloneRecovery(controllerHome: string): Promise<Record<string, unknown>> {
+  if (hooks.upgradeStandaloneRecovery) return hooks.upgradeStandaloneRecovery(controllerHome);
+  const config = loadRecoveryConfig(controllerHome);
+  const configuredSourceRoot = config.primaryRuntimeSourceRoot?.trim();
+  if (!configuredSourceRoot) {
+    throw new AssistantPluginError(
+      'LOCAL_SYSTEM_RECOVERY_SOURCE_UNCONFIGURED',
+      'Standalone Recovery upgrade requires primaryRuntimeSourceRoot in the installed Recovery configuration.',
+      { retryable: false },
+    );
+  }
+  let sourceCommit = '';
+  let candidate: RecoveryReleaseDescriptor | undefined;
+  let sourceRepair: RecoveryUpgradeSourceRepair | undefined;
+  try {
+    const resolvedSource = resolveRecoveryUpgradeSource(controllerHome, configuredSourceRoot);
+    sourceRepair = resolvedSource.repair;
+    const source = (hooks.recoverySourceIdentity ?? recoverySourceIdentity)(resolvedSource.sourceRoot);
+    sourceCommit = source.sourceCommit;
+    const current = readCurrentRecoveryRelease(controllerHome);
+    if (current && !current.legacy && current.cleanWorkspace && current.sourceCommit === source.sourceCommit) {
+      candidate = current;
+    } else {
+      const staged = (hooks.stageRecoveryRelease ?? stageRecoveryRelease)({ controllerHome, sourceRoot: source.sourceRoot });
+      candidate = staged.release;
+      if (candidate.sourceCommit !== source.sourceCommit || !candidate.cleanWorkspace) {
+        throw new Error('RECOVERY_RELEASE_SOURCE_IDENTITY_DRIFT');
+      }
+    }
+    const sourceAuthorityChanged = sourceRepair || config.primaryRuntimeSourceRepositoryId !== resolvedSource.repositoryId;
+    const activationConfig = sourceAuthorityChanged
+      ? { ...config, primaryRuntimeSourceRoot: source.sourceRoot, primaryRuntimeSourceRepositoryId: resolvedSource.repositoryId }
+      : config;
+    const activated = await (hooks.activateRecoveryRelease ?? activateRecoveryRelease)({ controllerHome, config: activationConfig, candidate });
+    if (sourceAuthorityChanged) {
+      createRecoveryConfig(controllerHome, {
+        primaryRuntimeSourceRoot: source.sourceRoot,
+        primaryRuntimeSourceRepositoryId: resolvedSource.repositoryId,
+      });
+    }
+    return {
+      upgraded: activated.noOp !== true,
+      noOp: activated.noOp === true,
+      sourceCommit,
+      sourceRepair: sourceRepair ?? { performed: false },
+      candidateRelease: boundedRecoveryRelease(candidate),
+      currentRelease: boundedRecoveryRelease(activated.release),
+      previousRelease: boundedRecoveryRelease(activated.previous),
+      migratedLegacyRelease: boundedRecoveryRelease(activated.migratedLegacy),
+      verification: {
+        ok: activated.verification.ok,
+        gatewayPid: activated.verification.gatewayPid,
+        watchdogPid: activated.verification.watchdogPid,
+      },
+      rollback: { performed: false },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const rolledBack = message.includes('RECOVERY_RELEASE_ACTIVATION_FAILED_ROLLED_BACK');
+    throw new AssistantPluginError(
+      'LOCAL_SYSTEM_RECOVERY_UPGRADE_FAILED',
+      bounded(message, 2_000).content,
+      {
+        retryable: message.includes('RECOVERY_RELEASE_BUSY'),
+        details: {
+          sourceCommit: sourceCommit || undefined,
+          sourceRepair,
+          candidateRelease: boundedRecoveryRelease(candidate),
+          rollback: { performed: rolledBack },
+        },
+      },
+    );
+  }
+}
+
+async function repairStandaloneRecoveryTunnel(controllerHome: string): Promise<Record<string, unknown>> {
+  const config = loadRecoveryConfig(controllerHome);
+  try {
+    const result = await (hooks.repairPublicTunnel ?? repairPublicTunnel)(config);
+    if (!result.ok) {
+      throw new AssistantPluginError(
+        'LOCAL_SYSTEM_RECOVERY_TUNNEL_REPAIR_FAILED',
+        bounded(result.detail, 2_000).content,
+        { retryable: result.attempted === true || result.detail.includes('cooldown') },
+      );
+    }
+    return {
+      repaired: result.attempted === true,
+      noOp: result.noOp === true,
+      detail: result.detail,
+      ...(result.serviceLabel ? { serviceLabel: result.serviceLabel } : {}),
+      ...(result.serviceTarget ? { serviceTarget: result.serviceTarget } : {}),
+      verification: { ok: result.verify.ok },
+      ...(result.localVerify ? { localVerification: { ok: result.localVerify.ok } } : {}),
+    };
+  } catch (error) {
+    if (error instanceof AssistantPluginError) throw error;
+    throw new AssistantPluginError(
+      'LOCAL_SYSTEM_RECOVERY_TUNNEL_REPAIR_FAILED',
+      bounded(error instanceof Error ? error.message : String(error), 2_000).content,
+      { retryable: false },
+    );
+  }
+}
+
 function actions(): AssistantPluginActionDescriptor[] {
   const controllerRead = [{ resource: 'repo-state' as const, mode: 'read' as const }];
   const controllerWrite = [{ resource: 'repo-state' as const, mode: 'write' as const }];
@@ -639,6 +813,8 @@ function actions(): AssistantPluginActionDescriptor[] {
     { actionId: 'restart_user_launch_agent', title: 'Restart verified user LaunchAgent', description: 'Restart one loaded user LaunchAgent by exact label only after launchctl evidence contains the expected program identity.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.process'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { label: { type: 'string' }, expected_program_contains: { type: 'string' } }, required: ['label', 'expected_program_contains'], additionalProperties: false } },
     { actionId: 'stop_user_launch_agent', title: 'Stop verified user LaunchAgent', description: 'Boot out one exact loaded user LaunchAgent only after its launchd identity matches the expected program.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: true, scopes: ['local-system.process'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { label: { type: 'string' }, expected_program_contains: { type: 'string' } }, required: ['label', 'expected_program_contains'], additionalProperties: false } },
     { actionId: 'start_user_launch_agent', title: 'Start verified user LaunchAgent', description: 'Bootstrap or start one exact current-user LaunchAgent from ~/Library/LaunchAgents only after the installed plist matches the expected program identity.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: true, scopes: ['local-system.process'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { label: { type: 'string' }, expected_program_contains: { type: 'string' } }, required: ['label', 'expected_program_contains'], additionalProperties: false } },
+    { actionId: 'upgrade_standalone_recovery', title: 'Upgrade standalone Recovery', description: 'Upgrade the installed standalone Recovery from its configured primary Runtime source using the existing immutable Recovery release authority. No caller source path or command is accepted.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 240_000, cancellable: false, idempotent: true, scopes: ['local-system.process'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { actionId: 'repair_standalone_recovery_tunnel', title: 'Repair standalone Recovery tunnel', description: 'Repair only the installed standalone Recovery public tunnel using its existing configured tunnel identity and Recovery repair authority. No caller tunnel identity, path, executable, or command is accepted.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: false, idempotent: true, scopes: ['local-system.process'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: {}, additionalProperties: false } },
     { actionId: 'open_application', title: 'Open application', description: 'Open one macOS application by name or bundle id in the background without stealing foreground focus.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.open'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { app_name: { type: 'string' }, bundle_id: { type: 'string' } }, additionalProperties: false } },
     { actionId: 'list_targets', title: 'List filesystem targets', description: 'List active expiring local filesystem grants.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 10_000, cancellable: true, idempotent: true, scopes: ['local-system.files.read'], resourceClaims: controllerRead, argumentsSchema: { type: 'object', properties: {}, additionalProperties: false } },
     { actionId: 'authorize_target', title: 'Authorize filesystem target', description: 'Authorize an expiring filesystem target. By default, a path inside a Git project authorizes the whole project/repository root; use scope=directory only when intentionally granting a narrower directory.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { target_key: { type: 'string' }, root_path: { type: 'string' }, scope: { type: 'string', enum: ['auto', 'project', 'directory'] }, expires_in_minutes: { type: 'number' }, reason: { type: 'string' }, access: { type: 'string', enum: ['read_only', 'read_write'] } }, required: ['target_key', 'root_path', 'reason'], additionalProperties: false } },
@@ -692,6 +868,8 @@ function capabilities(): AssistantPluginCapability[] {
   return [
     { capabilityId: 'local-system-diagnostics', title: 'Local diagnostics', description: 'Inspect CPU, processes, and memory with bounded typed commands.', scopes: ['local-system.read'], actions: ['system_snapshot', 'process_detail'] },
     { capabilityId: 'local-system-process-control', title: 'Verified process lifecycle', description: 'Terminate one verified PID or stop/start/restart one verified macOS user LaunchAgent without exposing arbitrary shell execution.', scopes: ['local-system.process'], actions: ['terminate_process', 'restart_user_launch_agent', 'stop_user_launch_agent', 'start_user_launch_agent'] },
+    { capabilityId: 'local-system-recovery-upgrade', title: 'Managed standalone Recovery upgrade', description: 'Upgrade standalone Recovery only from its installed configured source through the immutable Recovery release and rollback authority.', scopes: ['local-system.process'], actions: ['upgrade_standalone_recovery'] },
+    { capabilityId: 'local-system-recovery-tunnel-repair', title: 'Managed standalone Recovery tunnel repair', description: 'Repair only the installed Recovery public tunnel through the existing Recovery tunnel repair authority when the Recovery transport itself is unreachable.', scopes: ['local-system.process'], actions: ['repair_standalone_recovery_tunnel'] },
     { capabilityId: 'local-system-open', title: 'Open local applications and files', description: 'Open applications and authorized files without arbitrary shell access.', scopes: ['local-system.open'], actions: ['open_application', 'reveal_in_finder', 'open_file'] },
     { capabilityId: 'local-system-files', title: 'Authorized local files', description: 'Use expiring target grants for bounded local file operations and typed-argv commands without repository registration.', scopes: ['local-system.files.read', 'local-system.files.write'], actions: ['list_targets', 'authorize_target', 'revoke_target', 'list_directory', 'read_text', 'write_text', 'delete_file', 'delete_empty_directory', 'initialize_git', 'execute_command', 'execute_project_script', 'create_directory', 'copy_file', 'move_file', 'rename_file'] },
   ];
@@ -747,6 +925,8 @@ export async function executeLocalSystemPluginAction(input: AssistantPluginActio
     case 'restart_user_launch_agent': return restartVerifiedUserLaunchAgent(input.args.label, input.args.expected_program_contains, input.controllerHome);
     case 'stop_user_launch_agent': return stopVerifiedUserLaunchAgent(input.args.label, input.args.expected_program_contains);
     case 'start_user_launch_agent': return startVerifiedUserLaunchAgent(input.args.label, input.args.expected_program_contains);
+    case 'upgrade_standalone_recovery': return await upgradeStandaloneRecovery(input.controllerHome);
+    case 'repair_standalone_recovery_tunnel': return await repairStandaloneRecoveryTunnel(input.controllerHome);
     case 'open_application': {
       const appName = optionalString(input.args, 'app_name');
       const bundleId = optionalString(input.args, 'bundle_id');

package/src/runtime/plugins/macos-capability-broker.ts

@@ -1,111 +1,21 @@
-import { randomUUID } from 'crypto';
-import { homedir } from 'os';
-import { join, resolve } from 'path';
-import { callExternalUnixSocket } from './external-unix-socket';
-import { AssistantPluginError } from './errors';
-
-const BROKER_PLUGIN_ID = 'desktop_operator';
-const BROKER_PROTOCOL_VERSION = '1.0';
-const BROWSER_AUTOMATION_CAPABILITY = 'macos_browser_automation.v1';
-const BROWSER_AUTOMATION_PROTOCOL_VERSION = 1;
-const MAX_RESPONSE_BYTES = 4 * 1_048_576;
-let testSocketPath: string | undefined;
-
-export function macOsCapabilityBrokerSocketPath(accountHome = process.env.HOME?.trim() || homedir()): string {
-  return join(resolve(accountHome), 'Library', 'Caches', 'Forge', 'desktop-operator.sock');
-}
-
-export function setMacOsCapabilityBrokerSocketPathForTest(socketPath: string | undefined): void {
-  testSocketPath = socketPath;
-}
-
-export function resetMacOsCapabilityBrokerSocketPathForTest(): void {
-  testSocketPath = undefined;
-}
-
-function socketPath(): string {
-  return testSocketPath ?? macOsCapabilityBrokerSocketPath();
-}
-
-function unavailable(error: AssistantPluginError, path: string): AssistantPluginError {
-  if (!/^EXTERNAL_PLUGIN_(SOCKET_UNAVAILABLE|TIMEOUT|TRANSPORT_FAILED|PROTOCOL_ERROR)$/.test(error.code)) return error;
-  return new AssistantPluginError(
-    'PLUGIN_MACOS_CAPABILITY_BROKER_UNAVAILABLE',
-    `Stable Forge macOS capability broker is unavailable at ${path}. Install or restore Forge Desktop Operator instead of granting macOS permissions to Runtime or release-specific helpers.`,
-    { retryable: true, details: { socketPath: path, providerPluginId: BROKER_PLUGIN_ID, causeCode: error.code } },
-  );
-}
-
-export function validateMacOsCapabilityBrokerHandshake(
-  handshake: Record<string, unknown>,
-  requestedAction?: string,
-): void {
-  if (handshake.pluginId !== BROKER_PLUGIN_ID || handshake.protocolVersion !== BROKER_PROTOCOL_VERSION) {
-    throw new AssistantPluginError(
-      'PLUGIN_MACOS_CAPABILITY_BROKER_IDENTITY_MISMATCH',
-      'Stable macOS capability broker returned an unexpected provider identity.',
-      { retryable: false, details: { expectedPluginId: BROKER_PLUGIN_ID, expectedProtocolVersion: BROKER_PROTOCOL_VERSION } },
-    );
-  }
-  const capabilities = Array.isArray(handshake.internalCapabilities)
-    ? handshake.internalCapabilities.filter((entry): entry is string => typeof entry === 'string')
-    : [];
-  const actions = Array.isArray(handshake.browserAutomationActions)
-    ? handshake.browserAutomationActions.filter((entry): entry is string => typeof entry === 'string')
-    : [];
-  const browserProtocolVersion = handshake.browserAutomationProtocolVersion;
-  if (!capabilities.includes(BROWSER_AUTOMATION_CAPABILITY)
-    || browserProtocolVersion !== BROWSER_AUTOMATION_PROTOCOL_VERSION
-    || (requestedAction && !actions.includes(requestedAction))) {
-    throw new AssistantPluginError(
-      'PLUGIN_MACOS_CAPABILITY_BROKER_CAPABILITY_UNSUPPORTED',
-      requestedAction
-        ? `Installed Forge Desktop Operator does not declare required browser automation action ${requestedAction}.`
-        : 'Installed Forge Desktop Operator does not declare the required browser automation capability.',
-      {
-        retryable: false,
-        details: {
-          requiredCapability: BROWSER_AUTOMATION_CAPABILITY,
-          requiredBrowserAutomationProtocolVersion: BROWSER_AUTOMATION_PROTOCOL_VERSION,
-          ...(requestedAction ? { requiredAction: requestedAction } : {}),
-          declaredCapability: capabilities.includes(BROWSER_AUTOMATION_CAPABILITY),
-          declaredBrowserAutomationProtocolVersion: typeof browserProtocolVersion === 'number' ? browserProtocolVersion : null,
-          declaredActionCount: actions.length,
-        },
-      },
-    );
-  }
-}
-
-async function verifyBrokerIdentity(path: string, timeoutMs: number, requestedAction?: string): Promise<void> {
-  const handshake = await callExternalUnixSocket({
-    socketPath: path,
-    requestId: `macos-broker-handshake:${randomUUID()}`,
-    method: 'handshake',
-    timeoutMs: Math.min(timeoutMs, 2_000),
-    maxResponseBytes: 64 * 1024,
-  });
-  validateMacOsCapabilityBrokerHandshake(handshake, requestedAction);
-}
+/** @deprecated C0 compatibility shim. Browser code must consume the provider-neutral Computer boundary. */
+import type { ComputerBrowserAutomationRequest } from '../../../packages/protocols/computer/index';
+import {
+  desktopOperatorComputerSocketPath,
+  resetDesktopOperatorComputerSocketPathForTest,
+  setDesktopOperatorComputerSocketPathForTest,
+  validateDesktopOperatorComputerHandshake,
+} from '../../../adapters/computer/desktop-operator-provider';
+import { executeRuntimeComputerBrowserAutomation } from '../root/computer-composition';
+
+export const macOsCapabilityBrokerSocketPath = desktopOperatorComputerSocketPath;
+export const resetMacOsCapabilityBrokerSocketPathForTest = resetDesktopOperatorComputerSocketPathForTest;
+export const setMacOsCapabilityBrokerSocketPathForTest = setDesktopOperatorComputerSocketPathForTest;
+export const validateMacOsCapabilityBrokerHandshake = validateDesktopOperatorComputerHandshake;
 
 export async function callMacOsCapabilityBroker(
   params: Record<string, unknown>,
   timeoutMs: number,
 ): Promise<Record<string, unknown>> {
-  const path = socketPath();
-  try {
-    const requestedAction = typeof params.action === 'string' ? params.action : undefined;
-    await verifyBrokerIdentity(path, timeoutMs, requestedAction);
-    return await callExternalUnixSocket({
-      socketPath: path,
-      requestId: `macos-broker:${randomUUID()}`,
-      method: 'macos_browser_automation',
-      params,
-      timeoutMs,
-      maxResponseBytes: MAX_RESPONSE_BYTES,
-    });
-  } catch (error) {
-    if (error instanceof AssistantPluginError) throw unavailable(error, path);
-    throw error;
-  }
+  return await executeRuntimeComputerBrowserAutomation(params as unknown as ComputerBrowserAutomationRequest, timeoutMs);
 }