@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -16,6 +16,10 @@ import {
 } from 'fs';
 import { dirname, extname, join, resolve } from 'path';
 import { forgeRuntimeServicePaths } from '../root/service';
+import { installWorkflowSupervisorBrowserAdapter, inspectWorkflowSupervisorBrowserAdapter } from './computer-chatgpt-browser-adapter-installer';
+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 +52,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 +78,13 @@ 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>>;
+  installWorkflowSupervisorBrowserAdapter?: typeof installWorkflowSupervisorBrowserAdapter;
+  inspectWorkflowSupervisorBrowserAdapter?: typeof inspectWorkflowSupervisorBrowserAdapter;
+  repairPublicTunnel?: typeof repairPublicTunnel;
+  recoverySourceIdentity?: typeof recoverySourceIdentity;
+  stageRecoveryRelease?: typeof stageRecoveryRelease;
+  activateRecoveryRelease?: typeof activateRecoveryRelease;
 }
 
 let hooks: LocalSystemPluginHooks = {};
@@ -625,9 +637,175 @@ 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 }];
+  const providerWrite = [{ resource: 'provider-state' as const, mode: 'write' as const }];
   const targetProperties = {
     target_key: { type: 'string' },
     path: { type: 'string' },
@@ -639,6 +817,10 @@ 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: 'workflow_supervisor_browser_adapter_status', title: 'Workflow Supervisor browser adapter status', description: 'Inspect the Controller-owned Workflow Supervisor Chrome adapter projection and exact package-derived Native Messaging registration.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true, scopes: ['local-system.browser-adapter'], resourceClaims: [], argumentsSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { actionId: 'install_workflow_supervisor_browser_adapter', title: 'Install Workflow Supervisor browser adapter', description: 'Project the active immutable Runtime browser adapter into Controller-owned paths and register Native Messaging only for the extension package-derived stable id. No caller path, command, extension id, or browser profile is accepted.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: false, idempotent: true, scopes: ['local-system.browser-adapter'], resourceClaims: providerWrite, 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 } },
@@ -649,7 +831,7 @@ function actions(): AssistantPluginActionDescriptor[] {
     { actionId: 'delete_file', title: 'Delete file', description: 'Delete one exact regular file below an authorized read-write target. Arbitrary recursive or directory deletion is never exposed.', readOnly: false, risk: 'destructive', confirmation: 'strong_confirmation', requiredConfirmationText: 'delete-local-system-file', defaultTimeoutMs: 15_000, cancellable: true, idempotent: false, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: targetProperties, required: ['target_key', 'path'], additionalProperties: false } },
     { actionId: 'delete_empty_directory', title: 'Delete empty directory', description: 'Delete one exact empty directory below an authorized read-write target. Target roots and recursive directory deletion are never allowed.', readOnly: false, risk: 'destructive', confirmation: 'strong_confirmation', requiredConfirmationText: 'delete-local-system-empty-directory', defaultTimeoutMs: 15_000, cancellable: true, idempotent: false, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: targetProperties, required: ['target_key', 'path'], additionalProperties: false } },
     { actionId: 'initialize_git', title: 'Initialize local Git repository', description: 'Run only git init inside an authorized read-write target without registering it in Repository Registry.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: true, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { target_key: { type: 'string' }, cwd: { type: 'string' }, initial_branch: { type: 'string' } }, required: ['target_key'], additionalProperties: false } },
-    { actionId: 'execute_command', title: 'Execute target command', description: 'Execute one bounded typed-argv command inside an authorized target without repository registration. Shell strings, target escapes, destructive/remote writes, and Git mutations other than the dedicated initialize_git action are denied.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.files.read', 'local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { target_key: { type: 'string' }, command: { type: 'array', items: { type: 'string' } }, cwd: { type: 'string' }, max_output_bytes: { type: 'number' } }, required: ['target_key', 'command'], additionalProperties: false } },
+    { actionId: 'execute_command', title: 'Execute target command', description: 'Execute one bounded typed-argv command inside an authorized filesystem target. This is the narrow target-scoped alternative to broad ForgeInstance process_exec: shell strings, target escapes, destructive/remote writes, and Git mutations other than the dedicated initialize_git action are denied.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.files.read', 'local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { target_key: { type: 'string' }, command: { type: 'array', items: { type: 'string' } }, cwd: { type: 'string' }, max_output_bytes: { type: 'number' } }, required: ['target_key', 'command'], additionalProperties: false } },
     { actionId: 'execute_project_script', title: 'Execute verified project script', description: 'Execute one exact script below an authorized read-write target through a fixed interpreter after its SHA-256 digest and strong confirmation match. Eval flags and shell command strings are never accepted.', readOnly: false, risk: 'destructive', confirmation: 'strong_confirmation', requiredConfirmationText: 'execute-local-system-project-script', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.files.read', 'local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { target_key: { type: 'string' }, runtime: { type: 'string', enum: ['node', 'bun', 'python3', 'ruby', 'bash', 'sh'] }, script_path: { type: 'string' }, expected_sha256: { type: 'string' }, arguments: { type: 'array', items: { type: 'string' } }, cwd: { type: 'string' }, max_output_bytes: { type: 'number' } }, required: ['target_key', 'runtime', 'script_path', 'expected_sha256'], additionalProperties: false } },
     { actionId: 'create_directory', title: 'Create directory', description: 'Create a directory below an authorized target without leaving that root.', 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: targetProperties, required: ['target_key', 'path'], additionalProperties: false } },
     { actionId: 'copy_file', title: 'Copy file', description: 'Copy a file between authorized targets without overwriting.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { source_target_key: { type: 'string' }, source_path: { type: 'string' }, destination_target_key: { type: 'string' }, destination_path: { type: 'string' } }, required: ['source_target_key', 'source_path', 'destination_target_key', 'destination_path'], additionalProperties: false } },
@@ -683,6 +865,7 @@ function permissions(): AssistantPluginPermissionScope[] {
     { scope: 'local-system.read', mode: 'read', description: 'Read bounded local process and memory diagnostics.', granted: true, required: true },
     { scope: 'local-system.process', mode: 'write', description: 'Terminate one verified PID or control one verified current-user LaunchAgent after explicit authorization.', granted: true, required: false },
     { scope: 'local-system.open', mode: 'write', description: 'Open applications or authorized files.', granted: true, required: false },
+    { scope: 'local-system.browser-adapter', mode: 'write', description: 'Install and inspect the Controller-owned Workflow Supervisor Chrome adapter and exact Native Messaging registration.', granted: true, required: false },
     { scope: 'local-system.files.read', mode: 'read', description: 'Read files only below active target grants.', granted: true, required: false },
     { scope: 'local-system.files.write', mode: 'write', description: 'Create, copy, move, rename, or explicitly delete bounded files and empty directories below active read-write target grants.', granted: true, required: false },
   ];
@@ -692,6 +875,9 @@ 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-workflow-supervisor-browser-adapter', title: 'Workflow Supervisor browser adapter', description: 'Inspect or install the stateless Chrome adapter projection used by the Goal-level Workflow Supervisor authority.', scopes: ['local-system.browser-adapter'], actions: ['workflow_supervisor_browser_adapter_status', 'install_workflow_supervisor_browser_adapter'] },
     { 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'] },
   ];
@@ -706,7 +892,7 @@ export function buildLocalSystemPluginManifest(previousRevision = 0, previousUpd
     pluginId: PLUGIN_ID,
     provider: 'local-macos',
     displayName: 'Local System Assistant',
-    pluginVersion: '1.5.1',
+    pluginVersion: '1.5.3',
     authority: { strategy: 'derived', duplicateStateAllowed: false, sourceOfTruth: ['controllerHome:system/local-system'] },
     enabled: true,
     lifecycle: { state: currentHealth.ready ? 'enabled' : 'degraded', reason: currentHealth.ready ? 'Local system capabilities are ready.' : currentHealth.warnings[0] },
@@ -747,6 +933,10 @@ 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 'workflow_supervisor_browser_adapter_status': return (hooks.inspectWorkflowSupervisorBrowserAdapter ?? inspectWorkflowSupervisorBrowserAdapter)(input.controllerHome, { repository: { repoId: input.repoId, repoRoot: input.repoRoot } }) as unknown as Record<string, unknown>;
+    case 'install_workflow_supervisor_browser_adapter': return (hooks.installWorkflowSupervisorBrowserAdapter ?? installWorkflowSupervisorBrowserAdapter)(input.controllerHome, { repository: { repoId: input.repoId, repoRoot: input.repoRoot } }) as unknown as Record<string, unknown>;
     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);
 }

package/src/runtime/plugins/managed-process-adapter.ts

@@ -1,14 +1,14 @@
 import { spawn, spawnSync } from 'child_process';
 import { existsSync, statSync } from 'fs';
 import { dirname, isAbsolute, resolve } from 'path';
-import { AssistantPluginError } from './errors';
+import { MAX_PLUGIN_ACTION_TIMEOUT_MS } from '../../../packages/plugin-runtime/external/index';
+import { AssistantPluginError, type AssistantPluginEffectOutcome } from './errors';
 
 export const MANAGED_PLUGIN_PROTOCOL_VERSION = 1;
 const DEFAULT_MAX_REQUEST_BYTES = 1_048_576;
 const DEFAULT_MAX_RESPONSE_BYTES = 1_048_576;
 const DEFAULT_MAX_STDERR_CHARS = 8_000;
 const DEFAULT_TIMEOUT_MS = 30_000;
-const MAX_TIMEOUT_MS = 120_000;
 
 interface ManagedPluginHandshake {
   schemaVersion: 1;
@@ -60,12 +60,14 @@ export interface ManagedPluginProcessRequest {
   actionId: string;
   input: Record<string, unknown>;
   timeoutMs?: number;
+  effectOutcomeOnTimeout?: AssistantPluginEffectOutcome;
   signal?: AbortSignal;
 }
 
-function managedError(code: string, message: string, options: { retryable?: boolean; details?: Record<string, unknown> } = {}): AssistantPluginError {
+function managedError(code: string, message: string, options: { retryable?: boolean; effectOutcome?: AssistantPluginEffectOutcome; details?: Record<string, unknown> } = {}): AssistantPluginError {
   return new AssistantPluginError(code, message, {
     retryable: options.retryable ?? true,
+    effectOutcome: options.effectOutcome,
     details: options.details,
   });
 }
@@ -73,7 +75,7 @@ function managedError(code: string, message: string, options: { retryable?: bool
 function boundedTimeout(spec: ManagedPluginProcessSpec, request: ManagedPluginProcessRequest): number {
   const requested = request.timeoutMs ?? spec.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   if (!Number.isFinite(requested)) return DEFAULT_TIMEOUT_MS;
-  return Math.min(Math.max(Math.trunc(requested), 50), MAX_TIMEOUT_MS);
+  return Math.min(Math.max(Math.trunc(requested), 50), MAX_PLUGIN_ACTION_TIMEOUT_MS);
 }
 
 function minimalEnvironment(runtimeExecutable: string): NodeJS.ProcessEnv {
@@ -257,6 +259,7 @@ export async function executeManagedPluginProcess(
     let stdoutBytes = 0;
     let stderr = '';
     let handshakeReceived = false;
+    let requestDispatched = false;
     let settled = false;
     let timer: ReturnType<typeof setTimeout> | undefined;
     let killTimer: ReturnType<typeof setTimeout> | undefined;
@@ -298,6 +301,7 @@ export async function executeManagedPluginProcess(
         if (!handshakeReceived) {
           validateHandshake(parsed, spec);
           handshakeReceived = true;
+          requestDispatched = true;
           child.stdin.end(`${requestEnvelope}\n`);
           return;
         }
@@ -318,7 +322,10 @@ export async function executeManagedPluginProcess(
     };
 
     timer = setTimeout(() => {
-      fail(managedError('PLUGIN_MANAGED_PROCESS_TIMEOUT', 'Managed plugin helper timed out.', { retryable: true }));
+      fail(managedError('PLUGIN_MANAGED_PROCESS_TIMEOUT', 'Managed plugin helper timed out.', {
+        retryable: true,
+        effectOutcome: requestDispatched ? request.effectOutcomeOnTimeout : 'failed',
+      }));
     }, boundedTimeout(spec, request));
     request.signal?.addEventListener('abort', onAbort, { once: true });
 

package/src/runtime/plugins/plugin-action-sidecar.ts

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 import { createHash } from 'crypto';
-import { readFileSync, rmSync } from 'fs';
+import { readFileSync, rmSync, writeFileSync } from 'fs';
 import { getRepository } from '../../cli/repositories/registry';
 import type { AssistantPluginActionRequest } from './types';
-import { submitAssistantPluginAction } from './store';
+import { submitAssistantPluginAction, submitControllerPluginAction } from './store';
 
 interface Envelope {
   schemaVersion: 1;
   controllerHome: string;
-  repoId: string;
+  repoId?: string;
+  scope?: { kind: 'controller' } | { kind: 'repository'; repoId: string };
   request: Omit<AssistantPluginActionRequest, 'signal'>;
 }
 
@@ -30,13 +31,16 @@ export async function runPluginActionSidecar(argv = process.argv.slice(2)): Prom
     }
     const envelope = JSON.parse(bytes) as Envelope;
     if (envelope.schemaVersion !== 1) throw new Error('PLUGIN_ACTION_REQUEST_VERSION_UNSUPPORTED');
-    const repository = getRepository(envelope.repoId, envelope.controllerHome);
-    const submitted = await submitAssistantPluginAction(
-      envelope.controllerHome,
-      repository,
-      envelope.request,
-    );
-    process.stdout.write(`${JSON.stringify({
+    const controllerScoped = envelope.scope?.kind === 'controller';
+    const repoId = envelope.scope?.kind === 'repository' ? envelope.scope.repoId : envelope.repoId;
+    const submitted = controllerScoped
+      ? await submitControllerPluginAction(envelope.controllerHome, envelope.request)
+      : await submitAssistantPluginAction(
+          envelope.controllerHome,
+          getRepository(repoId ?? '', envelope.controllerHome),
+          envelope.request,
+        );
+    writeFileSync(1, `${JSON.stringify({
       ok: true,
       requestId: submitted.receipt.requestId,
       receiptId: submitted.receipt.receiptId,
@@ -51,9 +55,9 @@ export async function runPluginActionSidecar(argv = process.argv.slice(2)): Prom
 const direct = typeof process.argv[1] === 'string' && process.argv[1].includes('plugin-action-sidecar');
 if (direct) {
   void runPluginActionSidecar()
-    .then((code) => { process.exitCode = code; })
+    .then((code) => { process.exit(code); })
     .catch((error) => {
-      console.error(error instanceof Error ? error.message : String(error));
-      process.exitCode = 1;
+      writeFileSync(2, `${error instanceof Error ? error.message : String(error)}\n`);
+      process.exit(1);
     });
 }

package/src/runtime/plugins/plugin-management-adapter.ts

@@ -129,7 +129,7 @@ export function buildPluginManagementManifest(previousRevision = 0, previousUpda
   return {
     schemaVersion: 1, manifestVersion: 1, revision: Math.max(1, previousRevision || 1), pluginId: PLUGIN_ID,
     provider: 'forge-controller', displayName: 'Forge Plugin Management', pluginVersion: '1.0.0',
-    authority: { strategy: 'derived', duplicateStateAllowed: false, sourceOfTruth: ['controller-home:plugins/external/registrations', 'controller-home:system/plugin-capability-authorizations/grants.json'] },
+    authority: { strategy: 'derived', duplicateStateAllowed: false, sourceOfTruth: ['controller-home:plugins/external/registrations', 'controller-home:system/authorization-grants/grants.json'] },
     enabled: true, lifecycle: { state: 'enabled', reason: 'Canonical external plugin registration authority is available.' },
     health: { state: 'ready', checkedAt: now(), ready: true, probed: true, errors: [], warnings: [] },
     permissions: permissions(), capabilities: capabilities(), actions: actions(), updatedAt: previousUpdatedAt ?? now(),

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

@@ -3,12 +3,14 @@ import { dirname, join } from 'path';
 import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
+  AssistantPluginBuildContext,
   AssistantPluginCapability,
   AssistantPluginHealth,
   AssistantPluginManifest,
   AssistantPluginPermissionScope,
 } from './types';
 import { AssistantPluginError, toAssistantPluginError } from './errors';
+import { readRepositoryPluginConfig, writeRepositoryPluginConfig, type RepositoryPluginConfigContext } from './config-store';
 import {
   getResendOAuthAccessToken,
   prepareResendOAuthLogin,
@@ -19,7 +21,6 @@ import {
 } from '../safe-tooling/resend-oauth';
 
 const RESEND_PLUGIN_ID = 'resend';
-const CONFIG_ROOT = '.forge/plugins';
 const API_BASE_URL = 'https://api.resend.com';
 const RESEND_USER_AGENT = 'Forge-Resend-Plugin/1.0.0';
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -73,10 +74,6 @@ function boundedTimeout(value: unknown, fallback = DEFAULT_TIMEOUT_MS): number {
     : fallback;
 }
 
-function configPath(repoRoot: string): string {
-  return join(repoRoot, CONFIG_ROOT, 'resend.json');
-}
-
 function normalizeConfig(raw: Partial<ResendPluginConfig>): ResendPluginConfig {
   return {
     schemaVersion: 1,
@@ -89,22 +86,16 @@ function normalizeConfig(raw: Partial<ResendPluginConfig>): ResendPluginConfig {
   };
 }
 
-function loadConfig(repoRoot: string): ResendPluginConfig {
-  const path = configPath(repoRoot);
-  if (!existsSync(path)) return normalizeConfig({});
-  try {
-    return normalizeConfig(JSON.parse(readFileSync(path, 'utf8')) as Partial<ResendPluginConfig>);
-  } catch {
-    return normalizeConfig({});
-  }
+function loadConfig(repoRoot: string, context?: Pick<RepositoryPluginConfigContext, 'controllerHome' | 'repoId'>): ResendPluginConfig {
+  const persisted = context
+    ? readRepositoryPluginConfig<Partial<ResendPluginConfig>>({ ...context, repoRoot }, RESEND_PLUGIN_ID)
+    : undefined;
+  return normalizeConfig(persisted ?? {});
 }
 
-function saveConfig(repoRoot: string, patch: Partial<ResendPluginConfig>): ResendPluginConfig {
-  const next = normalizeConfig({ ...loadConfig(repoRoot), ...patch });
-  const path = configPath(repoRoot);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
-  return next;
+function saveConfig(input: Pick<AssistantPluginActionExecutionInput, 'controllerHome' | 'repoId' | 'repoRoot'>, patch: Partial<ResendPluginConfig>): ResendPluginConfig {
+  const next = normalizeConfig({ ...loadConfig(input.repoRoot, input), ...patch });
+  return writeRepositoryPluginConfig(input, RESEND_PLUGIN_ID, next);
 }
 
 function apiKey(): { value?: string; source?: string } {
@@ -382,14 +373,14 @@ function domainRows(payload: Record<string, unknown>): Array<Record<string, unkn
   return Array.isArray(payload.data) ? payload.data.filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object') : [];
 }
 
-export function buildResendPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string): AssistantPluginManifest {
+export function buildResendPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest {
   const root = repoRoot ?? process.cwd();
-  const config = loadConfig(root);
+  const config = loadConfig(root, context);
   const auth = resolveAuth(config);
   return {
     schemaVersion: 1, manifestVersion: 1, revision: Math.max(1, previousRevision || 1),
     pluginId: RESEND_PLUGIN_ID, provider: 'resend', displayName: 'Resend Email Plugin', pluginVersion: '1.0.0',
-    authority: { strategy: 'derived', duplicateStateAllowed: false, sourceOfTruth: ['repo-local:.forge/plugins/resend.json', 'macos-keychain:forge.resend-oauth|forge.resend-smtp', 'env:FORGE_RESEND_API_KEY|RESEND_API_KEY'] },
+    authority: { strategy: 'derived', duplicateStateAllowed: false, sourceOfTruth: ['controller-home:repositories/<repoId>/plugins/config/resend.json', 'macos-keychain:forge.resend-oauth|forge.resend-smtp', 'env:FORGE_RESEND_API_KEY|RESEND_API_KEY'] },
     enabled: config.enabled,
     lifecycle: {
       state: !config.enabled ? 'disabled' : auth.ready ? 'enabled' : 'error',
@@ -401,11 +392,11 @@ export function buildResendPluginManifest(previousRevision = 0, previousUpdatedA
 }
 
 export async function executeResendPluginAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>> {
-  const current = loadConfig(input.repoRoot);
+  const current = loadConfig(input.repoRoot, input);
   switch (input.actionId) {
     case 'configure': {
       const args = input.args;
-      const config = saveConfig(input.repoRoot, {
+      const config = saveConfig(input, {
         enabled: typeof args.enabled === 'boolean' ? args.enabled : current.enabled,
         provider: args.provider === 'resend-api' ? 'resend-api' : args.provider === 'mock' ? 'mock' : current.provider,
         sendingDomain: args.clear_sending_domain === true ? undefined : stringValue(args.sending_domain) ?? current.sendingDomain,