fix(desktop): localize expected errors

Raw exception text no longer reaches the UI: expected failures carry
machine-readable codes (with params where needed) that the renderer maps
through locale catalogs, and unexpected failures show a localized
fallback while redacted diagnostics go to the console.

Author: orangeCatDeveloper

apps/desktop/renderer-architecture.json

@@ -56,6 +56,7 @@
     "src/renderer/desktop-slash-command.ts",
     "src/renderer/desktop-transcript-range-store.ts",
     "src/renderer/error-boundary.tsx",
+    "src/renderer/expected-operation-error.ts",
     "src/renderer/follow-up-submit-routing.ts",
     "src/renderer/interrupted-resume.ts",
     "src/renderer/keyboard-help.tsx",
@@ -89,6 +90,7 @@
     "src/renderer/locales/settings-web-search-copy.ts",
     "src/renderer/locales/shell-copy.ts",
     "src/renderer/locales/shell-remaining-copy.ts",
+    "src/renderer/locales/workhub-copy.ts",
     "src/renderer/main.tsx",
     "src/renderer/mcp-brand-contrast.ts",
     "src/renderer/mcp-brand-marks.tsx",
@@ -278,6 +280,7 @@
     "src/renderer/features/module-hub/controller/use-scheduled-tasks-controller.ts -> src/renderer/locales/shell-remaining-copy",
     "src/renderer/features/module-hub/controller/use-skills-controller.ts -> src/renderer/locales/shell-copy",
     "src/renderer/features/module-hub/ui/module-hub-host.tsx -> src/renderer/mcp-page",
+    "src/renderer/features/session-collaboration/ui/session-collaboration-join-dialog.tsx -> src/renderer/expected-operation-error",
     "src/renderer/features/session-navigation/controller/session-row-actions.ts -> src/renderer/locales/shell-copy",
     "src/renderer/features/session-navigation/controller/use-session-navigation-controller.ts -> src/renderer/use-external-store-selector",
     "src/renderer/features/session-navigation/controller/use-session-navigation-reads.ts -> src/renderer/use-external-store-selector",
@@ -475,14 +478,14 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
           "./locales/shell-copy.js": 1,
           "@maka/core/llm-connections": 1,
-          "@maka/core/redaction": 1,
           "@maka/core/text-file-import": 1,
           "@maka/core/ui-locale": 1
         },
         "importSpecifiers": 6,
-        "nonTriviaTokens": 515
+        "nonTriviaTokens": 372
       },
       "src/renderer/app-shell-detail-panel.tsx": {
         "importDeclarations": 1,
@@ -1664,6 +1667,17 @@
           "react": 1
         }
       },
+      "src/renderer/expected-operation-error.ts": {
+        "bridgePaths": {},
+        "environmentCapabilities": {},
+        "hookCalls": {},
+        "lifecycleMethods": {},
+        "unresolvedDependencies": 0,
+        "actionFactories": [],
+        "dependencyPaths": {
+          "@maka/core/redaction": 1
+        }
+      },
       "src/renderer/follow-up-submit-routing.ts": {
         "bridgePaths": {},
         "environmentCapabilities": {},
@@ -1791,6 +1805,7 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "../../shared/work-board-ipc.js": 1,
           "@maka/core/connection-readiness": 1,
           "@maka/core/model-call-attempt": 1,
           "@maka/core/session-send-projection": 1,
@@ -2060,10 +2075,10 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "../expected-operation-error.js": 1,
           "@maka/core/goal": 1,
           "@maka/core/model-thinking": 1,
           "@maka/core/permission": 1,
-          "@maka/core/redaction": 1,
           "@maka/core/settings": 1,
           "@maka/core/slash-command-catalog": 1,
           "@maka/core/ui-locale": 1
@@ -2080,6 +2095,17 @@
           "@maka/core/ui-locale": 1
         }
       },
+      "src/renderer/locales/workhub-copy.ts": {
+        "bridgePaths": {},
+        "environmentCapabilities": {},
+        "hookCalls": {},
+        "lifecycleMethods": {},
+        "unresolvedDependencies": 0,
+        "actionFactories": [],
+        "dependencyPaths": {
+          "@maka/core/ui-locale": 1
+        }
+      },
       "src/renderer/mcp-brand-contrast.ts": {
         "bridgePaths": {},
         "environmentCapabilities": {},
@@ -2373,6 +2399,7 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
           "./locales/plan-mode-copy.js": 1,
           "@astryxdesign/core/Banner": 1,
           "@astryxdesign/core/Collapsible": 1,
@@ -2413,6 +2440,7 @@
         "actionFactories": [],
         "dependencyPaths": {
           "../preload/bridge-contract.js": 1,
+          "./expected-operation-error.js": 1,
           "./locales/shell-copy.js": 1,
           "@astryxdesign/core/Button": 1,
           "@astryxdesign/core/Dialog": 1,
@@ -2481,6 +2509,7 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
           "./locales/session-collaboration-copy.js": 1,
           "./session-turn-request-composer.js": 1,
           "@astryxdesign/core": 1,
@@ -2618,6 +2647,7 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
           "./locales/session-collaboration-copy.js": 1,
           "@maka/runtime-host/protocol": 1,
           "@maka/ui": 1,
@@ -5262,6 +5292,7 @@
         "actionFactories": [],
         "dependencyPaths": {
           "../shared/work-board-ipc.js": 1,
+          "./expected-operation-error.js": 1,
           "@maka/core/work-board": 1,
           "@maka/storage/work-board-store": 1,
           "react": 1
@@ -5281,6 +5312,7 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
           "./locales/conversation-copy.js": 1,
           "./use-work-board.js": 1,
           "@astryxdesign/core": 1,
@@ -5300,6 +5332,7 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
           "./workhub-route-policy.js": 1,
           "@maka/runtime-host/protocol": 1
         }
@@ -5398,6 +5431,8 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
+          "./locales/workhub-copy.js": 2,
           "./workhub-controller.js": 1,
           "./workhub-coordination-port.js": 1,
           "./workhub-send-lease.js": 1,

apps/desktop/src/main/__tests__/expected-error-presentation.test.ts

@@ -0,0 +1,79 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { getDesktopConversationCopy } from '../../renderer/locales/conversation-copy.js';
+import { getSessionCollaborationCopy } from '../../renderer/locales/session-collaboration-copy.js';
+import {
+  ExpectedOperationError,
+  expectedOperationErrorMessage,
+} from '../../renderer/expected-operation-error.js';
+import { sessionCollaborationImportErrorMessage } from '../../renderer/features/session-collaboration/testing.js';
+import { messageReadErrorMessage } from '../../renderer/app-shell-copy.js';
+import { localizedShellErrorMessage } from '../../renderer/locales/shell-copy.js';
+
+test('routes Work Board codes through each locale catalog', () => {
+  for (const locale of ['zh', 'en'] as const) {
+    const copy = getDesktopConversationCopy(locale).workBoardPanel;
+    assert.equal(
+      expectedOperationErrorMessage(
+        new ExpectedOperationError('not_found'),
+        copy.errors,
+        copy.actionFailed,
+        'test',
+      ),
+      copy.errors.not_found,
+    );
+  }
+});
+
+test('routes structured collaboration failures through each locale catalog', () => {
+  const cases = [
+    [{ kind: 'error', reason: 'invalid_code' } as const, 'invalidCode'],
+    [{ kind: 'error', reason: 'peer_path_unavailable' } as const, 'directPathUnavailable'],
+    [{ kind: 'error', reason: 'connection_failed' } as const, 'connectionFailed'],
+  ] as const;
+  for (const locale of ['zh', 'en'] as const) {
+    const copy = getSessionCollaborationCopy(locale);
+    for (const [result, key] of cases) {
+      assert.equal(sessionCollaborationImportErrorMessage(copy, result), copy[key]);
+    }
+    assert.equal(
+      sessionCollaborationImportErrorMessage(copy, {
+        kind: 'error',
+        reason: 'mount_limit_reached',
+        params: { max: 12 },
+      }),
+      copy.mountLimit(12),
+    );
+  }
+});
+
+test('uses localized fallbacks instead of classifying raw exception text', (context) => {
+  context.mock.method(console, 'error', () => undefined);
+  const raw = new Error('timeout 401 网络失败 MAKA_SESSION_READ_MESSAGES_ERROR: 后端中文');
+  assert.equal(
+    messageReadErrorMessage(raw, 'en'),
+    'Task content is temporarily unavailable. Try again later.',
+  );
+  assert.equal(messageReadErrorMessage(raw, 'zh'), '任务内容暂时无法读取，请稍后重试。');
+  assert.equal(localizedShellErrorMessage(raw, 'English fallback', 'en'), 'English fallback');
+  assert.equal(localizedShellErrorMessage(raw, '中文兜底', 'zh'), '中文兜底');
+});

apps/desktop/src/main/__tests__/plan-mode-copy.test.ts

@@ -29,6 +29,8 @@ test('localizes Plan Mode chrome and abandon confirmation without rewriting plan
   assert.equal(en.proposal.statuses.approved, 'Approved');
   assert.equal(zh.execution.stepCount(2, 3), '2/3 步');
   assert.equal(en.execution.stepCount(1, 1), '1/1 step');
+  assert.equal(zh.operationFailed, '计划操作失败，请稍后重试。');
+  assert.equal(en.operationFailed, 'The plan action failed. Try again later.');
   assert.deepEqual(
     {
       title: en.abandonConfirmation.title,

apps/desktop/src/main/__tests__/runtime-host-guest-session-mounts.test.ts

@@ -69,11 +69,30 @@ test('removes failed activation desire instead of creating recoverable profile s
   });
 
   const result = await mounts.importInvitation(invitation('guest-two'), false, 'import-two');
-  assert.deepEqual(result.kind === 'error' ? result.reason : result.kind, 'peer_path_unavailable');
+  assert.deepEqual(result, { kind: 'error', reason: 'peer_path_unavailable' });
   assert.deepEqual(await store.read(), []);
   assert.equal(unmounted.length, 1);
 });
 
+test('logs unexpected activation failures without returning Host details', async (context) => {
+  const diagnostics: string[] = [];
+  context.mock.method(console, 'error', (...values: unknown[]) => {
+    diagnostics.push(values.map(String).join(' '));
+  });
+  const mounts = service(memoryStore(), {
+    mount: async () => {
+      throw new Error('Authorization: Bearer very-secret-token');
+    },
+  });
+
+  const result = await mounts.importInvitation(invitation('guest-failed'), false, 'import-failed');
+
+  assert.deepEqual(result, { kind: 'error', reason: 'connection_failed' });
+  assert.equal(diagnostics.length, 1);
+  assert.match(diagnostics[0]!, /session-collaboration.*import failed/u);
+  assert.doesNotMatch(diagnostics[0]!, /very-secret-token/u);
+});
+
 test('settles admitted finalization before committing unmount desire', async () => {
   const store = memoryStore();
   let started!: () => void;

apps/desktop/src/main/__tests__/work-board-ipc-main.test.ts

@@ -164,16 +164,18 @@ describe('Work Board IPC', () => {
           { title: 'stale write' },
           { expectedRevision: 1 },
         );
-        assert.equal(staleRename.ok, false);
-        if (!staleRename.ok) assert.equal(staleRename.code, 'operation_conflict');
+        assert.deepEqual(staleRename, {
+          ok: false,
+          error: { code: 'operation_conflict' },
+        });
 
       const removedBeforeArchive = await ipc.invoke<WorkBoardIpcResult<null>>(
         'workBoard:remove',
         id,
       );
       assert.equal(removedBeforeArchive.ok, false);
       if (!removedBeforeArchive.ok) {
-        assert.equal(removedBeforeArchive.code, 'must_archive_first');
+        assert.equal(removedBeforeArchive.error.code, 'must_archive_first');
       }
 
       const archived = await ipc.invoke<
@@ -194,14 +196,14 @@ describe('Work Board IPC', () => {
         { titel: 'x' },
       );
       assert.equal(invalidPatch.ok, false);
-      if (!invalidPatch.ok) assert.equal(invalidPatch.code, 'invalid_input');
+      if (!invalidPatch.ok) assert.equal(invalidPatch.error.code, 'invalid_input');
 
       const invalidCreate = await ipc.invoke<WorkBoardIpcResult<unknown>>(
         'workBoard:create',
         { ...itemInput(), notes: null },
       );
       assert.equal(invalidCreate.ok, false);
-      if (!invalidCreate.ok) assert.equal(invalidCreate.code, 'invalid_input');
+      if (!invalidCreate.ok) assert.equal(invalidCreate.error.code, 'invalid_input');
 
       await ipc.invoke('workBoard:archive', id);
       const removed = await ipc.invoke<WorkBoardIpcResult<null>>('workBoard:remove', id);

apps/desktop/src/main/__tests__/workhub-surface-flow.test.ts

@@ -43,30 +43,36 @@ import {
   type WorkHubDelegationExecutionState,
   type WorkHubSubmitInput,
 } from '../../renderer/workhub-controller.js';
+import { ExpectedOperationError } from '../../renderer/expected-operation-error.js';
+import { WorkHubCoordinationFailure } from '../../renderer/workhub-coordination-port.js';
 import { WorkHubSendLease } from '../../renderer/workhub-send-lease.js';
 import {
   createDesktopWorkHubSessionPort,
   type WorkHubDesktopSession,
 } from '../../renderer/workhub-session-port.js';
 
-test('surface turns Action Gate rejections into safe actionable failures', () => {
+test('surface turns Action Gate rejections into safe actionable failures', (context) => {
+  context.mock.method(console, 'error', () => undefined);
   assert.equal(
-    workHubSurfaceFailure(
-      new Error('WorkHub Session candidates changed; refresh before delegating'),
-    ),
+    workHubSurfaceFailure(new ExpectedOperationError('candidates_changed')),
     'candidates_changed',
   );
   assert.equal(
-    workHubSurfaceFailure(
-      new Error('WorkHub linked correction requires an active durable delegation'),
-    ),
+    workHubSurfaceFailure(new ExpectedOperationError('linked_correction_unavailable')),
     'linked_correction_unavailable',
   );
   assert.equal(
-    workHubSurfaceFailure(new Error('Target Session is waiting for user input')),
+    workHubSurfaceFailure(new WorkHubCoordinationFailure('session_busy', 'Host diagnostic')),
     'target_waiting',
   );
-  assert.equal(workHubSurfaceFailure(new Error('private transport detail')), 'delivery_failed');
+  assert.equal(
+    workHubSurfaceFailure(new WorkHubCoordinationFailure('operation_conflict', 'Host diagnostic')),
+    'action_changed',
+  );
+  assert.equal(
+    workHubSurfaceFailure(new Error('WorkHub Session candidates changed; private detail')),
+    'delivery_failed',
+  );
 });
 
 test('surface route gate rejects same-frame duplicate operations and reopens after settle', async () => {