From e66072743fbc7aae05f4cc11723dcc20eb4b9273 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Mon, 3 Aug 2026 23:34:09 -0700
Subject: [PATCH] Clarify remote file mutation version mismatch messages

- Update error messages to explicitly state whether the client or remote
  server is out of date, removing ambiguous phrasing like "newer Orca"
- Add actionable guidance directing users to Settings > General > Updates
  > Remote Orca Servers to resolve version mismatches
- Consolidate and improve test descriptions to match the clearer messaging
---
 src/main/runtime/orca-runtime-files.test.ts       |  4 ++--
 src/main/runtime/orca-runtime-files.ts            |  2 +-
 .../src/web/web-file-mutation-methods.test.ts     | 15 ++++++++++++---
 src/shared/protocol-version.ts                    |  2 +-
 4 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/src/main/runtime/orca-runtime-files.test.ts b/src/main/runtime/orca-runtime-files.test.ts
index 379372dd0ac..15bfc3baa20 100644
--- a/src/main/runtime/orca-runtime-files.test.ts
+++ b/src/main/runtime/orca-runtime-files.test.ts
@@ -389,7 +389,7 @@ describe('RuntimeFileCommands', () => {
     const { commands } = createRuntimeFileCommands()
 
     await expect(commands.renameFileExplorerPath('id:wt-1', 'old.ts', 'new.ts')).rejects.toThrow(
-      'newer Orca client'
+      'Orca client paired with this server is out of date'
     )
 
     expect(getSshFilesystemProvider).not.toHaveBeenCalled()
@@ -402,7 +402,7 @@ describe('RuntimeFileCommands', () => {
 
     await expect(
       commands.renameFileExplorerPath('id:wt-1', 'old.ts', 'new.ts', 0, 'ssh-1')
-    ).rejects.toThrow('newer Orca client')
+    ).rejects.toThrow('Orca client paired with this server is out of date')
 
     expect(getSshFilesystemProvider).not.toHaveBeenCalled()
     expect(renameMock).not.toHaveBeenCalled()
diff --git a/src/main/runtime/orca-runtime-files.ts b/src/main/runtime/orca-runtime-files.ts
index adbae1adf7e..126c3843172 100644
--- a/src/main/runtime/orca-runtime-files.ts
+++ b/src/main/runtime/orca-runtime-files.ts
@@ -101,7 +101,7 @@ export const WINDOWS_RUNTIME_FILE_WATCH_CLOSE_DEADLINE_MS = 10_000
 const TERMINAL_FILE_GRANT_TTL_MS = 10 * 60 * 1000
 const OPEN_NOFOLLOW = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0
 const RUNTIME_FILE_MUTATION_UPDATE_REQUIRED =
-  'Remote file changes require a newer Orca client. Update the paired client and try again.'
+  'Remote file changes are unavailable because the Orca client paired with this server is out of date. Update the client, reconnect, and try again.'
 
 function assertRuntimeFileMutationExpectation(
   connectionId: string | undefined,
diff --git a/src/renderer/src/web/web-file-mutation-methods.test.ts b/src/renderer/src/web/web-file-mutation-methods.test.ts
index 7a996e24805..6e659debdb6 100644
--- a/src/renderer/src/web/web-file-mutation-methods.test.ts
+++ b/src/renderer/src/web/web-file-mutation-methods.test.ts
@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { FILE_MUTATION_OWNERSHIP_UPDATE_REQUIRED_MESSAGE } from '../../../shared/protocol-version'
 import type { SshConnectionState } from '../../../shared/ssh-types'
 import type { Worktree } from '../../../shared/types'
 import { createWebFileMutationMethods } from './web-file-mutation-methods'
@@ -271,13 +272,21 @@ describe('paired web file mutation methods', () => {
     expect(getSshState).not.toHaveBeenCalled()
   })
 
-  it('rejects an old HUB before reading SSH state or sending a mutation', async () => {
-    assertMutationSupported.mockRejectedValueOnce(new Error('Update the HUB'))
+  it('rejects an outdated remote Orca server before reading SSH state or mutating', async () => {
+    expect(FILE_MUTATION_OWNERSHIP_UPDATE_REQUIRED_MESSAGE).toContain(
+      "remote Orca server is out of date, so Orca can't upload or change files"
+    )
+    expect(FILE_MUTATION_OWNERSHIP_UPDATE_REQUIRED_MESSAGE).toContain(
+      'Settings > General > Updates > Remote Orca Servers'
+    )
+    assertMutationSupported.mockRejectedValueOnce(
+      new Error(FILE_MUTATION_OWNERSHIP_UPDATE_REQUIRED_MESSAGE)
+    )
     const methods = createWebFileMutationMethods({ captureSession })
 
     await expect(
       methods.deletePath({ targetPath: '/ssh/repo/dir', recursive: true })
-    ).rejects.toThrow('Update the HUB')
+    ).rejects.toThrow(FILE_MUTATION_OWNERSHIP_UPDATE_REQUIRED_MESSAGE)
     expect(getSshState).not.toHaveBeenCalled()
     expect(callRuntimeResult).not.toHaveBeenCalled()
   })
diff --git a/src/shared/protocol-version.ts b/src/shared/protocol-version.ts
index b254d45dca4..084b7ee36f4 100644
--- a/src/shared/protocol-version.ts
+++ b/src/shared/protocol-version.ts
@@ -72,7 +72,7 @@ export const AGENT_SESSION_OMP_RESUME_PATH_RUNTIME_CAPABILITY =
 // Why: older runtimes strip mutation owner fields, so clients must fence writes before RPC.
 export const FILE_MUTATION_OWNERSHIP_RUNTIME_CAPABILITY = 'files.mutation-ownership.v1' as const
 export const FILE_MUTATION_OWNERSHIP_UPDATE_REQUIRED_MESSAGE =
-  'Remote file changes require a newer Orca server. Update the HUB and try again.'
+  "This workspace's remote Orca server is out of date, so Orca can't upload or change files there. To update it, open Settings > General > Updates > Remote Orca Servers. Reconnect, then try again."
 
 export const RUNTIME_CAPABILITIES = [
   'runtime.status.compat.v1',