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",
@@ -88,6 +89,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",
@@ -276,6 +278,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",
@@ -473,14 +476,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,
@@ -1661,6 +1664,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": {},
@@ -1788,6 +1802,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,
@@ -2046,10 +2061,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
@@ -2066,6 +2081,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": {},
@@ -2359,6 +2385,7 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
           "./locales/plan-mode-copy.js": 1,
           "@astryxdesign/core/Banner": 1,
           "@astryxdesign/core/Collapsible": 1,
@@ -2399,6 +2426,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,
@@ -2467,6 +2495,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,
@@ -2604,6 +2633,7 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
           "./locales/session-collaboration-copy.js": 1,
           "@maka/runtime-host/protocol": 1,
           "@maka/ui": 1,
@@ -5213,6 +5243,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
@@ -5232,6 +5263,7 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
           "./locales/conversation-copy.js": 1,
           "./use-work-board.js": 1,
           "@astryxdesign/core": 1,
@@ -5251,6 +5283,7 @@
         "unresolvedDependencies": 0,
         "actionFactories": [],
         "dependencyPaths": {
+          "./expected-operation-error.js": 1,
           "./workhub-route-policy.js": 1,
           "@maka/runtime-host/protocol": 1
         }
@@ -5349,6 +5382,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,95 @@
+/*
+ * 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 } 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;
+    const error: unknown = new ExpectedOperationError('not_found');
+    assert.equal(
+      error instanceof ExpectedOperationError && Object.hasOwn(copy.errors, error.code)
+        ? copy.errors[error.code as keyof typeof copy.errors]
+        : copy.actionFailed,
+      copy.errors.not_found,
+    );
+  }
+});
+
+test('maps blocked session-control tokens per locale at the shared entry', () => {
+  const blocked = new Error('session_control_blocked:permission_turn_running');
+  assert.equal(
+    localizedShellErrorMessage(blocked, 'fallback', 'zh'),
+    '当前任务正在运行，等结束后再切换权限模式。',
+  );
+  assert.equal(
+    localizedShellErrorMessage(blocked, 'fallback', 'en'),
+    'A task is still running. Change the permission mode after it finishes.',
+  );
+});
+
+test('maps attachment-ingest tokens per locale at the shared entry', () => {
+  const blocked = new Error("Error invoking remote method 'attachments': Error: attachment_ingest:count_limit");
+  assert.equal(localizedShellErrorMessage(blocked, 'fallback', 'zh'), '一次最多添加 8 个附件。');
+  assert.equal(
+    localizedShellErrorMessage(blocked, 'fallback', 'en'),
+    'At most 8 attachments per message.',
+  );
+});
+
+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);