@moretea-labs/forge 1.8.1 → 1.8.2

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

@@ -11,6 +11,7 @@ import {
   listGitHubWorkflowRuns,
   listGitHubWorkflows,
 } from '../../cli/github/github';
+import { syncGitHubSemanticRelease } from '../../cli/github/semantic-projection';
 import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
@@ -72,7 +73,7 @@ function githubCapabilities(): AssistantPluginCapability[] {
       title: 'Issue Sync',
       description: 'Mirror controller issues and task metadata into GitHub issues.',
       scopes: ['github:issues:write', 'controller:issues:write'],
-      actions: ['configure', 'publish_issue', 'refresh_issue', 'close_issue'],
+      actions: ['configure', 'publish_issue', 'refresh_issue', 'close_issue', 'sync_semantic_release'],
     },
     {
       capabilityId: 'project-sync',
@@ -91,7 +92,7 @@ function githubCapabilities(): AssistantPluginCapability[] {
   ];
 }
 
-function githubActions(): AssistantPluginActionDescriptor[] {
+function githubActions(projectConfigured: boolean): AssistantPluginActionDescriptor[] {
   return [
     {
       actionId: 'configure',
@@ -145,6 +146,22 @@ function githubActions(): AssistantPluginActionDescriptor[] {
         additionalProperties: false,
       },
     },
+    {
+      actionId: 'sync_semantic_release',
+      title: 'Sync semantic release to GitHub',
+      description: 'Idempotently project one root semantic release Work and explicitly linked child Works from Forge into GitHub Issues without changing Forge semantics.',
+      readOnly: false,
+      risk: 'remote_write',
+      confirmation: 'authorization',
+      defaultTimeoutMs: 120_000,
+      cancellable: true,
+      idempotent: true,
+      scopes: projectConfigured ? ['github:issues:write', 'github:projects:write'] : ['github:issues:write'],
+      resourceClaims: [{ resource: 'remote', mode: 'exclusive' }],
+      argumentsSchema: { type: 'object', required: ['release_work_id'], properties: {
+        release_work_id: { type: 'string', minLength: 1, maxLength: 200 },
+      }, additionalProperties: false },
+    },
     {
       actionId: 'refresh_issue',
       title: 'Refresh linked GitHub issue',
@@ -321,7 +338,7 @@ export function buildGitHubPluginManifest(previousRevision = 0, previousUpdatedA
     },
     permissions: githubPermissions(status.ready, projectConfigured),
     capabilities: githubCapabilities(),
-    actions: githubActions(),
+    actions: githubActions(projectConfigured),
     updatedAt: previousUpdatedAt ?? now(),
   };
 }
@@ -343,6 +360,16 @@ export async function executeGitHubPluginAction(input: AssistantPluginActionExec
     }
     case 'publish_issue':
       return { issue: publishIssueWithGitHubPlugin(input.repoRoot, String(input.args.issue_id ?? '').trim()) };
+    case 'sync_semantic_release': {
+      const config = loadGitHubPluginConfig(input.repoRoot);
+      if (!config.enabled || !getGitHubPluginStatus(input.repoRoot).ready) throw new Error('GITHUB_SEMANTIC_PLUGIN_NOT_READY');
+      return { ...syncGitHubSemanticRelease(input.repoRoot, {
+        releaseWorkId: String(input.args.release_work_id ?? '').trim(),
+        repository: config.repository,
+        projectOwner: config.projectOwner,
+        projectNumber: config.projectNumber,
+      }) };
+    }
     case 'refresh_issue':
       return refreshIssueWithGitHubPlugin(input.repoRoot, String(input.args.issue_id ?? '').trim()) as Record<string, unknown>;
     case 'list_workflows': {

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

@@ -20,7 +20,18 @@ import {
   stableMockId,
 } from './google-shared';
 
-const GMAIL_PLUGIN_ID = 'gmail';
+export const GMAIL_PLUGIN_ID = 'gmail';
+export const GMAIL_AUTOMATION_CAPABILITY_ID = 'scheduled-gmail-automation';
+export const GMAIL_OWNER_NOTIFICATION_CAPABILITY_ID = 'owner-notification';
+const GMAIL_AUTOMATION_GRANT_MINUTES = 90 * 24 * 60;
+
+function gmailAutomationMailbox(config: GmailPluginConfig): string {
+  const mailbox = stringValue(config.accountEmail)?.toLowerCase();
+  if (!mailbox) {
+    throw new AssistantPluginError('GMAIL_AUTOMATION_MAILBOX_NOT_CONFIGURED', 'Set the Gmail plugin accountEmail to the connected mailbox before using scheduled Gmail automation.', { retryable: false });
+  }
+  return mailbox;
+}
 
 interface GmailProvider {
   listMessages(args: Record<string, unknown>, config: GmailPluginConfig): Promise<Record<string, unknown>>;
@@ -97,6 +108,20 @@ function gmailCapabilities(): AssistantPluginCapability[] {
       scopes: ['gmail.modify'],
       actions: ['modify_message_labels', 'archive_message', 'mark_message_read', 'mark_message_unread', 'trash_message'],
     },
+    {
+      capabilityId: GMAIL_AUTOMATION_CAPABILITY_ID,
+      title: 'Scheduled Gmail Automation',
+      description: 'After an explicit reusable grant, archive selected messages in the profile-verified mailbox. This does not authorize sending mail, replies or trash.',
+      scopes: ['gmail.modify'],
+      actions: ['authorize_scheduled_gmail_automation', 'archive_scheduled_message'],
+    },
+    {
+      capabilityId: GMAIL_OWNER_NOTIFICATION_CAPABILITY_ID,
+      title: 'Owner Authorization Email',
+      description: 'Send Forge authorization/approval notices exclusively to the configured, Google-profile-verified owner mailbox. Does not authorize archive, replies, trash or arbitrary recipients.',
+      scopes: ['gmail.send'],
+      actions: ['authorize_owner_notifications', 'send_owner_notification'],
+    },
   ];
 }
 
@@ -295,6 +320,79 @@ function gmailActions(): AssistantPluginActionDescriptor[] {
         additionalProperties: false,
       },
     },
+    {
+      actionId: 'authorize_scheduled_gmail_automation',
+      title: 'Authorize scheduled Gmail automation',
+      description: 'Explicitly grant Forge up to 90 days to archive selected messages in the configured, profile-verified Gmail mailbox. It does not authorize sending messages or trash.',
+      readOnly: false,
+      risk: 'remote_write',
+      confirmation: 'authorization',
+      requiredConfirmationText: 'authorize-scheduled-gmail-automation',
+      defaultTimeoutMs: 30_000,
+      cancellable: false,
+      idempotent: true,
+      scopes: ['gmail.modify'],
+      resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+      actionId: 'archive_scheduled_message',
+      title: 'Archive selected Gmail message for scheduled automation',
+      description: 'Archive one explicitly selected message in the fixed owner mailbox. Requires the dedicated scheduled Gmail automation grant.',
+      readOnly: false,
+      risk: 'remote_write',
+      confirmation: 'authorization',
+      requiresExplicitCapabilityGrant: true,
+      defaultTimeoutMs: 30_000,
+      cancellable: false,
+      idempotent: true,
+      scopes: ['gmail.modify'],
+      resourceClaims: [{ resource: 'remote', mode: 'exclusive' }],
+      argumentsSchema: {
+        type: 'object',
+        properties: { message_id: { type: 'string', minLength: 1, maxLength: 512 } },
+        required: ['message_id'],
+        additionalProperties: false,
+      },
+    },
+    {
+      actionId: 'authorize_owner_notifications',
+      title: 'Authorize owner notification emails',
+      description: 'Explicitly allow Forge to send future authorization requests to this verified Gmail account, with links to affected ChatGPT conversations. Does not grant archiving, replies or arbitrary recipients.',
+      readOnly: false,
+      risk: 'remote_write',
+      confirmation: 'authorization',
+      requiredConfirmationText: 'authorize-owner-notifications',
+      defaultTimeoutMs: 30_000,
+      cancellable: false,
+      idempotent: true,
+      scopes: ['gmail.send'],
+      resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+      actionId: 'send_owner_notification',
+      title: 'Send Forge notification to owner mailbox',
+      description: 'Send a plain-text Forge/Gmail automation notification only to the configured, profile-verified Gmail mailbox. No recipient, CC, BCC, or attachments can be supplied. Requires the dedicated scheduled Gmail automation grant.',
+      readOnly: false,
+      risk: 'remote_write',
+      confirmation: 'authorization',
+      requiresExplicitCapabilityGrant: true,
+      defaultTimeoutMs: 45_000,
+      cancellable: false,
+      idempotent: false,
+      scopes: ['gmail.send'],
+      resourceClaims: [{ resource: 'remote', mode: 'exclusive' }],
+      argumentsSchema: {
+        type: 'object',
+        properties: {
+          subject: { type: 'string', minLength: 1, maxLength: 180 },
+          body_text: { type: 'string', minLength: 1, maxLength: 12000 },
+        },
+        required: ['subject', 'body_text'],
+        additionalProperties: false,
+      },
+    },
     {
       actionId: 'modify_message_labels',
       title: 'Modify Gmail message labels',
@@ -752,6 +850,40 @@ export async function executeGmailPluginAction(input: AssistantPluginActionExecu
       return gmailProvider(current, input.repoRoot).createDraft(input.args, current);
     case 'send_message':
       return gmailProvider(current, input.repoRoot).sendMessage(input.args, current);
+    case 'authorize_owner_notifications':
+      return {
+        authorizedMailbox: gmailAutomationMailbox(current),
+        capabilityId: GMAIL_OWNER_NOTIFICATION_CAPABILITY_ID,
+        scopes: ['gmail.send'],
+        grantLifetimeDays: 90,
+        sent: false,
+      };
+    case 'authorize_scheduled_gmail_automation':
+      return {
+        authorizedMailbox: gmailAutomationMailbox(current),
+        capabilityId: GMAIL_AUTOMATION_CAPABILITY_ID,
+        scopes: ['gmail.modify'],
+        grantLifetimeDays: 90,
+        sent: false,
+        note: 'The plugin action store records the reusable grant after this explicit authorization action succeeds.',
+      };
+    case 'archive_scheduled_message':
+      return gmailProvider(current, input.repoRoot).archiveMessage(input.args, current);
+    case 'send_owner_notification': {
+      const subject = stringValue(input.args.subject);
+      const bodyText = stringValue(input.args.body_text);
+      if (!subject || !/^\[(Forge|Gmail)\]/.test(subject)) {
+        throw new AssistantPluginError('GMAIL_OWNER_NOTIFICATION_SUBJECT_INVALID', 'Owner notifications must start with [Forge] or [Gmail].', { retryable: false });
+      }
+      if (!bodyText) {
+        throw new AssistantPluginError('GMAIL_OWNER_NOTIFICATION_BODY_REQUIRED', 'Owner notifications require plain-text body_text.', { retryable: false });
+      }
+      return gmailProvider(current, input.repoRoot).sendMessage({
+        to: [gmailAutomationMailbox(current)],
+        subject,
+        body_text: bodyText,
+      }, current);
+    }
     case 'modify_message_labels':
       return gmailProvider(current, input.repoRoot).modifyMessageLabels(input.args, current);
     case 'archive_message':
@@ -769,8 +901,41 @@ export async function executeGmailPluginAction(input: AssistantPluginActionExecu
   }
 }
 
+async function resolveGmailAutomationAuthorizationContext(input: AssistantPluginActionExecutionInput) {
+  if (![
+    'authorize_scheduled_gmail_automation',
+    'archive_scheduled_message',
+    'authorize_owner_notifications',
+    'send_owner_notification',
+  ].includes(input.actionId)) return undefined;
+
+  const current = loadGmailPluginConfig(input.repoRoot, input);
+  if (!current.enabled) {
+    throw new AssistantPluginError('GMAIL_AUTOMATION_DISABLED', 'Enable the Gmail plugin before authorizing scheduled Gmail automation.', { retryable: false });
+  }
+  const configuredEmail = gmailAutomationMailbox(current);
+  const profile = await gmailProvider(current, input.repoRoot).getProfile({}, current);
+  const actualEmail = stringValue(profile.emailAddress)?.toLowerCase();
+  if (actualEmail !== configuredEmail) {
+    throw new AssistantPluginError(
+      'GMAIL_AUTOMATION_MAILBOX_MISMATCH',
+      'The connected Gmail profile does not match the configured Gmail accountEmail.',
+      { retryable: false },
+    );
+  }
+  return {
+    target: {
+      kind: 'gmail-mailbox' as const,
+      id: configuredEmail,
+      identityFingerprint: `gmail-profile:${configuredEmail}`,
+    },
+    expiresInMinutes: GMAIL_AUTOMATION_GRANT_MINUTES,
+  };
+}
+
 export const gmailPluginAdapter = {
   pluginId: GMAIL_PLUGIN_ID,
   buildManifest: buildGmailPluginManifest,
   executeAction: executeGmailPluginAction,
+  resolveAuthorizationContext: resolveGmailAutomationAuthorizationContext,
 };

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

@@ -331,7 +331,7 @@ export function resolveGoogleAuth(
       credentialSource: refresh?.name,
       accessToken: REFRESH_REQUIRED_ACCESS_TOKEN,
       errors: [],
-      warnings: ['A stored refresh credential is available; the next provider request will refresh and verify an access token.'],
+      warnings: ['A refresh token is stored, but Google has not verified it. A matching OAuth client secret may also be required by the provider.'],
     };
   }
   return {
@@ -351,7 +351,7 @@ export type GoogleReadinessMode =
 export function resolveGoogleReadinessMode(config: GooglePluginConfig, auth: GoogleAuthState): GoogleReadinessMode {
   if (!config.enabled) return 'disabled';
   if (config.provider === 'mock' && auth.ready) return 'mock_provider_ready';
-  if (config.provider === 'google-workspace' && auth.ready) return 'live_provider_ready';
+  if (config.provider === 'google-workspace' && auth.ready && auth.probed) return 'live_provider_ready';
   if (config.provider === 'google-workspace' && auth.authenticated) return 'live_token_unverified';
   return 'missing_token';
 }
@@ -379,10 +379,10 @@ export function pluginStateFromGoogleAuth(config: GooglePluginConfig, auth: Goog
       checkedAt: new Date().toISOString(),
       ready: config.enabled && ready,
       probed: config.enabled ? auth.probed : false,
-      errors: [],
+      errors: !config.enabled || auth.authenticated ? [] : auth.errors,
       warnings: !config.enabled
         ? ['Plugin is disabled. Enable it before using Google provider actions.']
-        : [...auth.warnings, ...(!auth.authenticated ? auth.errors : [])],
+        : auth.warnings,
       details: {
         provider: config.provider,
         accountEmail: config.accountEmail,
@@ -457,7 +457,12 @@ async function refreshGoogleAccessToken(service: GoogleService, timeoutMs: numbe
     try { parsed = raw ? JSON.parse(raw) as Record<string, unknown> : {}; } catch { parsed = { raw }; }
     const accessToken = typeof parsed.access_token === 'string' ? parsed.access_token.trim() : '';
     if (!response.ok || !accessToken) {
-      throw new AssistantPluginError('PLUGIN_AUTH_FAILED', 'Google refresh token exchange failed.', {
+      const missingSecret = parsed.error === 'invalid_request'
+        && typeof parsed.error_description === 'string'
+        && /client_secret is missing/i.test(parsed.error_description);
+      throw new AssistantPluginError('PLUGIN_AUTH_FAILED', missingSecret
+        ? 'Google OAuth client secret is missing for the configured client. Restore its matching secret in macOS Keychain, or reauthorize with a new OAuth client.'
+        : 'Google refresh token exchange failed.', {
         retryable: false,
         details: { service, status: response.status, providerError: parsed },
       });

package/src/runtime/plugins/ios/remote-xpc-hid.ts

@@ -6,15 +6,16 @@ import { createInterface } from 'readline';
 import { performance } from 'perf_hooks';
 import { AssistantPluginError } from '../errors';
 
-const TOOLCHAIN_VERSION = '10.2.1';
+export const IOS_HID_TOOLCHAIN_VERSION = '11.24.0';
 const WORKER_IDLE_MS = 15 * 60_000;
 const WORKER_STARTUP_MS = 12_000;
-const MUTATION_READY_BUDGET_MS = 2_500;
 const REQUEST_TIMEOUT_MS = 12_000;
 const RSD_ENDPOINT_CACHE_TTL_MS = 30_000;
 const RSD_ENDPOINT_PERSISTED_TTL_MS = 10 * 60_000;
 const MAX_TEXT_LENGTH = 2048;
 const MAX_STDERR = 8 * 1024;
+const TOOLCHAIN_PROBE_TTL_MS = 60_000;
+const TOOLCHAIN_PROBE_TIMEOUT_MS = 5_000;
 
 export interface RemoteXpcHidInput {
   controllerHome: string;
@@ -99,6 +100,7 @@ const warmups = new Map<string, Promise<void>>();
 const workerGenerations = new Map<string, number>();
 const warmupFailures = new Map<string, WarmupFailure>();
 const endpointCache = new Map<string, EndpointCacheEntry>();
+const toolchainProbeCache = new Map<string, { checkedAt: number; installedVersion?: string; available: boolean; reason?: string }>();
 
 export function setRemoteXpcHidExecutorForTest(executor: TestExecutor | undefined): void {
   testExecutor = executor;
@@ -112,26 +114,71 @@ export function resetRemoteXpcHidForTest(): void {
   workerGenerations.clear();
   warmupFailures.clear();
   endpointCache.clear();
+  toolchainProbeCache.clear();
 }
 
-export function remoteXpcHidStatus(controllerHome: string, env: NodeJS.ProcessEnv = process.env): Record<string, unknown> {
+const TOOLCHAIN_PROBE_SCRIPT = [
+  'from importlib.metadata import version',
+  'from pymobiledevice3.remote.remote_service_discovery import RemoteServiceDiscoveryService',
+  'from pymobiledevice3.remote.core_device.pasteboard_service import PasteboardService',
+  'from pymobiledevice3.remote.core_device.hid_service import UniversalHIDServiceService, touch_session',
+  "print(version('pymobiledevice3'))",
+].join('; ');
+
+function probeHidToolchain(python: string): { installedVersion?: string; available: boolean; reason?: string } {
+  const cached = toolchainProbeCache.get(python);
+  if (cached && Date.now() - cached.checkedAt <= TOOLCHAIN_PROBE_TTL_MS) return cached;
+  const result = spawnSync(python, ['-c', TOOLCHAIN_PROBE_SCRIPT], {
+    encoding: 'utf8', timeout: TOOLCHAIN_PROBE_TIMEOUT_MS, maxBuffer: 8 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const installedVersion = typeof result.stdout === 'string' ? result.stdout.trim() : undefined;
+  const available = result.status === 0 && installedVersion === IOS_HID_TOOLCHAIN_VERSION && !result.error;
+  const reason = available ? undefined : result.error?.message ?? (result.status === 0
+    ? `Expected pymobiledevice3 ${IOS_HID_TOOLCHAIN_VERSION}, found ${installedVersion || 'unknown'}.`
+    : `pymobiledevice3 import/version probe failed (exit ${result.status ?? 'unknown'}).`);
+  const probe = { checkedAt: Date.now(), installedVersion, available, reason };
+  // A failed probe is not durable: an explicitly authorized installer may
+  // finish immediately afterward without requiring a Runtime restart.
+  if (available) toolchainProbeCache.set(python, probe);
+  else toolchainProbeCache.delete(python);
+  return probe;
+}
+
+function hidToolchainStatus(controllerHome: string, env: NodeJS.ProcessEnv, allowProbe: boolean): Record<string, unknown> {
   const python = resolvePython(controllerHome, env);
+  const cached = python ? toolchainProbeCache.get(python) : undefined;
+  const validCached = cached?.available === true && Date.now() - cached.checkedAt <= TOOLCHAIN_PROBE_TTL_MS
+    ? cached : undefined;
+  const probe = python ? (allowProbe ? probeHidToolchain(python) : validCached) : undefined;
   return {
     backend: 'remote-xpc-hid',
-    available: Boolean(python),
+    available: probe?.available === true,
     python,
-    toolchainVersion: TOOLCHAIN_VERSION,
+    toolchainVersion: IOS_HID_TOOLCHAIN_VERSION,
+    ...(probe?.installedVersion ? { installedVersion: probe.installedVersion } : {}),
+    ...(probe?.reason ? { reason: probe.reason } : {}),
     transport: 'macos-trusted-coredevice-rsd',
     runnerOwned: false,
   };
 }
 
+// Manifest reads are passive: only an explicit HID action may start Python.
+// This is a view of the same short-lived successful probe cache, not a second
+// readiness authority or a durable grant.
+export function remoteXpcHidCachedStatus(controllerHome: string, env: NodeJS.ProcessEnv = process.env): Record<string, unknown> {
+  return hidToolchainStatus(controllerHome, env, false);
+}
+
+export function remoteXpcHidStatus(controllerHome: string, env: NodeJS.ProcessEnv = process.env): Record<string, unknown> {
+  return hidToolchainStatus(controllerHome, env, true);
+}
+
 function resolvePython(controllerHome: string, env: NodeJS.ProcessEnv): string | undefined {
   const explicit = env.FORGE_IOS_HID_PYTHON?.trim();
   const candidates = [
     explicit,
-    join(controllerHome, 'toolchains', `pymobiledevice3-${TOOLCHAIN_VERSION}-py39`, 'bin', 'python'),
-    join(controllerHome, 'toolchains', `pymobiledevice3-${TOOLCHAIN_VERSION}`, 'bin', 'python'),
+    join(controllerHome, 'toolchains', `pymobiledevice3-${IOS_HID_TOOLCHAIN_VERSION}`, 'bin', 'python'),
   ].filter((value): value is string => Boolean(value));
   return candidates.find((candidate) => existsSync(candidate));
 }
@@ -143,6 +190,7 @@ import asyncio
 import json
 import sys
 import time
+from importlib.metadata import version as package_version
 
 from pymobiledevice3.remote.remote_service_discovery import RemoteServiceDiscoveryService
 from pymobiledevice3.remote.core_device.pasteboard_service import PasteboardService
@@ -222,7 +270,11 @@ async def main():
     parser = argparse.ArgumentParser()
     parser.add_argument('--host', required=True)
     parser.add_argument('--port', required=True, type=int)
+    parser.add_argument('--expected-version', required=True)
     args = parser.parse_args()
+    actual_version = package_version('pymobiledevice3')
+    if actual_version != args.expected_version:
+        raise RuntimeError(f'RemoteXPC HID pymobiledevice3 version mismatch: {actual_version} != {args.expected_version}')
     async with RemoteServiceDiscoveryService((args.host, args.port)) as rsd:
         async with touch_session(rsd) as hid:
             connected = await hid.list_connected_services()
@@ -743,11 +795,12 @@ export function stopRemoteXpcHidForDevice(deviceIdentifier: string): Record<stri
 }
 
 function startWorker(input: Pick<RemoteXpcHidInput, 'controllerHome' | 'deviceIdentifier'>, endpoint: RsdEndpoint): WorkerRecord {
-  const python = resolvePython(input.controllerHome, process.env);
+  const status = remoteXpcHidStatus(input.controllerHome);
+  const python = status.available === true && typeof status.python === 'string' ? status.python : undefined;
   if (!python) {
-    throw new AssistantPluginError('IOS_HID_TOOLCHAIN_MISSING', `The Controller-owned pymobiledevice3 ${TOOLCHAIN_VERSION} toolchain is unavailable.`, {
+    throw new AssistantPluginError('IOS_HID_TOOLCHAIN_MISSING', `The Controller-owned pymobiledevice3 ${IOS_HID_TOOLCHAIN_VERSION} toolchain is unavailable or incompatible.`, {
       retryable: false,
-      details: { expected: join(input.controllerHome, 'toolchains', `pymobiledevice3-${TOOLCHAIN_VERSION}-py39`, 'bin', 'python') },
+      details: { expected: join(input.controllerHome, 'toolchains', `pymobiledevice3-${IOS_HID_TOOLCHAIN_VERSION}`, 'bin', 'python'), reason: status.reason },
     });
   }
   const script = materializeWorker(input.controllerHome);
@@ -756,6 +809,7 @@ function startWorker(input: Pick<RemoteXpcHidInput, 'controllerHome' | 'deviceId
     '-u', script,
     '--host', endpoint.host,
     '--port', String(endpoint.port),
+    '--expected-version', IOS_HID_TOOLCHAIN_VERSION,
   ], {
     stdio: ['pipe', 'pipe', 'pipe'],
     env: {
@@ -1089,23 +1143,11 @@ async function waitForMutationWorker(
   }
   const current = workers.get(input.deviceIdentifier);
   const warmup = warmups.get(input.deviceIdentifier);
-  const readiness = current
-    ? current.ready.then(() => undefined).catch(() => undefined)
-    : warmup;
-  if (readiness) {
-    let timer: NodeJS.Timeout | undefined;
-    try {
-      await Promise.race([
-        readiness,
-        new Promise<void>((resolve) => {
-          timer = setTimeout(resolve, MUTATION_READY_BUDGET_MS);
-          timer.unref?.();
-        }),
-      ]);
-    } finally {
-      if (timer) clearTimeout(timer);
-    }
-  }
+  // Plugin actions use separate managed processes. A detached prewarm cannot
+  // survive its owning action, so the first real mutation must finish its own
+  // endpoint discovery and worker startup rather than time out and retry cold.
+  const readiness = warmup ?? current?.ready.then(() => undefined).catch(() => undefined);
+  if (readiness) await readiness;
   const waitMs = Math.round((performance.now() - startedAt) * 100) / 100;
   const worker = workers.get(input.deviceIdentifier);
   if (!worker || worker.readyState !== 'ready') {
@@ -1115,15 +1157,13 @@ async function waitForMutationWorker(
     }
     throw new AssistantPluginError(
       'IOS_HID_INPUT_NOT_READY',
-      `RemoteXPC HID is still warming after the ${MUTATION_READY_BUDGET_MS}ms mutation readiness budget. No input was sent; retry the same action after prewarm completes.`,
+      'RemoteXPC HID worker did not reach ready state in this action. No input was sent.',
       {
         retryable: true,
         details: {
           deviceIdentifier: input.deviceIdentifier,
           mutationDispatched: false,
           workerReadyWaitMs: waitMs,
-          readinessBudgetMs: MUTATION_READY_BUDGET_MS,
-          prewarmContinues: warmups.has(input.deviceIdentifier) || worker?.readyState === 'starting',
         },
       },
     );