From 30713c8de9a3755c8e9ca65ffc5e2d48b9a875b6 Mon Sep 17 00:00:00 2001
From: xuzhiqin1990 <xuzhiqin1990@qq.com>
Date: Sat, 19 Sep 2026 19:52:54 +0800
Subject: [PATCH 01/85] fix(providers): raise default model call timeout to
 300s

The OpenAI-compatible provider defaulted to a 120s request timeout,
which caused frequent timeouts during evaluation runs where model
responses legitimately take longer. Raise the default to 300s.

The MEMMY_AGENT_OPENAI_COMPAT_TIMEOUT_S env override is unchanged;
only the fallback default changes. Update the two default-timeout
assertions accordingly.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 App/memmy-agent/src/providers/openai-compat-provider.ts       | 2 +-
 App/memmy-agent/tests/providers/openai-compat-timeout.test.ts | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/App/memmy-agent/src/providers/openai-compat-provider.ts b/App/memmy-agent/src/providers/openai-compat-provider.ts
index 26ee43559..f940cbb1e 100644
--- a/App/memmy-agent/src/providers/openai-compat-provider.ts
+++ b/App/memmy-agent/src/providers/openai-compat-provider.ts
@@ -51,7 +51,7 @@ const THINKING_STYLE_MAP: Record<string, (on: boolean) => Record<string, any>> =
 const GATEWAY_REASONING_STYLE_MAP: Record<string, (effort: string) => Record<string, any>> = {
   reasoning_effort: (effort) => ({ reasoning: { effort } }),
 };
-const OPENAI_COMPAT_REQUEST_TIMEOUT_S = 120.0;
+const OPENAI_COMPAT_REQUEST_TIMEOUT_S = 300.0;
 
 export const RESPONSES_FAILURE_THRESHOLD = 3;
 export const RESPONSES_PROBE_INTERVAL_S = 300;
diff --git a/App/memmy-agent/tests/providers/openai-compat-timeout.test.ts b/App/memmy-agent/tests/providers/openai-compat-timeout.test.ts
index 03d2bd9aa..ca8d940e6 100644
--- a/App/memmy-agent/tests/providers/openai-compat-timeout.test.ts
+++ b/App/memmy-agent/tests/providers/openai-compat-timeout.test.ts
@@ -28,7 +28,7 @@ describe("OpenAI-compatible local timeout hints", () => {
     expect((provider as any).client).toBeNull();
     const client = await provider.ensureClient();
 
-    expect(client.timeout).toBe(120_000);
+    expect(client.timeout).toBe(300_000);
     expect(client.fetchOptions).toBeUndefined();
   });
 
@@ -37,7 +37,7 @@ describe("OpenAI-compatible local timeout hints", () => {
 
     const client = await provider.ensureClient();
 
-    expect(client.timeout).toBe(120_000);
+    expect(client.timeout).toBe(300_000);
     expect(client.fetchOptions.keepalive).toBe(false);
   });
 

From a88abc5816273086a9d071b55c8f87963f66da54 Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Mon, 14 Sep 2026 19:38:18 +0800
Subject: [PATCH 02/85] feat(models): add Custom protocols, thinking budget,
 and image declarations

Expose OpenAI Completions/Responses and Custom providers in the model workspace, persist thinking/image capability on Custom presets, and send thinking fields through the chat turn so the backend can map them onto reasoningEffort.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 App/backend/local-api-contracts/package.json  |   2 +-
 App/backend/local-api-contracts/src/index.ts  |  30 ++-
 .../src/model-catalog-resolver.ts             |  25 +-
 .../src/model-thinking-levels.ts              | 249 ++++++++++++++++++
 .../tests/model-catalog-resolver.test.ts      |  43 +++
 .../tests/model-thinking-levels.test.ts       |  36 +++
 .../memmy-config/model-config-catalog.ts      |  29 +-
 App/frontend/desktop/src/api/config-client.ts |  37 ++-
 .../desktop/src/api/memmy-agent-client.ts     |   8 +-
 .../src/components/agent-model-selector.tsx   |  13 +-
 .../src/components/agent-thinking-control.tsx | 117 ++++++++
 .../src/components/model-provider-logo.tsx    |   4 +-
 App/frontend/desktop/src/i18n/messages.ts     |  54 ++++
 App/frontend/desktop/src/pages/home-page.tsx  |  33 ++-
 .../desktop/src/pages/model-config.ts         |  48 +++-
 .../src/pages/model-workspace-section.tsx     | 228 ++++++++++++++--
 .../desktop/src/pages/settings-page.tsx       |   4 +-
 .../src/pages/tests/home-page.test.tsx        |  37 +++
 .../src/pages/tests/model-config.test.ts      |  29 +-
 ...del-workspace-section.interaction.test.tsx |   2 +-
 ...odel-workspace-task-picker-layout.test.tsx |   2 +-
 .../src/pages/tests/settings-page.test.tsx    |  19 +-
 .../desktop/src/state/agent-chat-slice.ts     |  45 ++++
 App/frontend/desktop/src/state/app-actions.ts |   8 +
 .../desktop/src/state/model-workspace.ts      |  93 ++++++-
 .../src/state/tests/agent-chat-slice.test.ts  |  37 +++
 .../src/state/tests/model-workspace.test.ts   |  57 +++-
 App/frontend/desktop/src/styles.css           | 166 ++++++++++++
 App/memmy-agent/src/config/schema.ts          |  18 +-
 .../src/core/agent-runtime/loop.ts            |  30 ++-
 .../src/core/agent-runtime/runner.ts          |   9 +-
 App/memmy-agent/src/core/session/manager.ts   |   6 +
 .../src/integrations/channels/websocket.ts    |  68 ++---
 App/memmy-agent/src/providers/factory.ts      |   7 +-
 .../src/providers/model-catalog.ts            |   3 +
 .../src/providers/model-input-capabilities.ts |   8 +
 .../runner-byok-image-input.test.ts           |  30 +++
 .../agent-runtime/thinking-effort.test.ts     |  21 ++
 .../channels/webui-message-digest.test.ts     |  41 +++
 .../tests/providers/bedrock-provider.test.ts  |  35 +++
 .../model-input-capabilities.test.ts          |   8 +
 41 files changed, 1617 insertions(+), 122 deletions(-)
 create mode 100644 App/backend/local-api-contracts/src/model-thinking-levels.ts
 create mode 100644 App/backend/local-api-contracts/tests/model-thinking-levels.test.ts
 create mode 100644 App/frontend/desktop/src/components/agent-thinking-control.tsx
 create mode 100644 App/memmy-agent/tests/core/agent-runtime/thinking-effort.test.ts
 create mode 100644 App/memmy-agent/tests/integrations/channels/webui-message-digest.test.ts

diff --git a/App/backend/local-api-contracts/package.json b/App/backend/local-api-contracts/package.json
index 17a8c8cf8..d33a62b9f 100644
--- a/App/backend/local-api-contracts/package.json
+++ b/App/backend/local-api-contracts/package.json
@@ -14,7 +14,7 @@
   },
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
-    "test": "npm run typecheck && vitest run tests/desktop-runtime-manifest.test.ts tests/language.test.ts",
+    "test": "npm run typecheck && vitest run tests/desktop-runtime-manifest.test.ts tests/language.test.ts tests/model-catalog-resolver.test.ts tests/model-thinking-levels.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
diff --git a/App/backend/local-api-contracts/src/index.ts b/App/backend/local-api-contracts/src/index.ts
index 69bf78250..999adcb3b 100644
--- a/App/backend/local-api-contracts/src/index.ts
+++ b/App/backend/local-api-contracts/src/index.ts
@@ -1,7 +1,9 @@
 /** Memmy local API contract. */
 import { z } from "zod";
+import { ModelThinkingConfigSchema } from "./model-thinking-levels.js";
 
 export * from "./model-catalog-resolver.js";
+export * from "./model-thinking-levels.js";
 
 export * from "./memory-runtime.js";
 export * from "./memory-canonical-json.js";
@@ -742,7 +744,8 @@ export const CatalogProviderIdSchema = z.enum([
     "volcengine",
     "stepfun",
     "xiaomi_mimo",
-    "memmy_account"
+    "memmy_account",
+    "bedrock"
 ]);
 export type CatalogProviderId = z.infer<typeof CatalogProviderIdSchema>;
 
@@ -784,7 +787,8 @@ export const ModelEndpointProtocolSchema = z.enum([
     "dashscope-input-audio-chat",
     "openai-images",
     "dashscope-multimodal-generation",
-    "memmy-account"
+    "memmy-account",
+    "bedrock-converse"
 ]);
 export type ModelEndpointProtocol = z.infer<typeof ModelEndpointProtocolSchema>;
 
@@ -905,19 +909,26 @@ export const CatalogEndpointInputSchema = z.object({
     protocol: ModelEndpointProtocolSchema,
     apiKey: z.string().optional(),
     extraHeaders: z.record(z.string(), z.string()).optional(),
-    extraBody: z.record(z.string(), z.unknown()).optional()
+    extraBody: z.record(z.string(), z.unknown()).optional(),
+    region: z.string().trim().min(1).optional()
 });
 export type CatalogEndpointInput = z.infer<typeof CatalogEndpointInputSchema>;
 
 export const MODEL_NAME_MAX_LENGTH = 128;
 
+export const ModelInputModalitySchema = z.enum(["text", "image", "video"]);
+export type ModelInputModality = z.infer<typeof ModelInputModalitySchema>;
+
 export const TextModelItemInputSchema = z.object({
     presetId: z.string().trim().min(1).optional(),
     endpointId: z.string().trim().min(1),
     model: z.string().trim().min(1).max(MODEL_NAME_MAX_LENGTH),
     source: ModelSourceSchema,
     ownerAccountId: z.string().trim().min(1).optional(),
-    capabilities: z.array(ModelCapabilitySchema).min(1)
+    capabilities: z.array(ModelCapabilitySchema).min(1),
+    thinking: ModelThinkingConfigSchema.optional(),
+    custom: z.boolean().optional(),
+    inputModalities: z.array(ModelInputModalitySchema).optional()
 });
 export type TextModelItemInput = z.infer<typeof TextModelItemInputSchema>;
 
@@ -972,7 +983,8 @@ export const ModelConfigTestInputSchema = z.object({
     modelId: z.string().min(1),
     apiKey: z.string().min(1).optional(),
     capability: ModelConfigTestCapabilitySchema.optional(),
-    secretTarget: ModelConfigTestSecretTargetSchema.optional()
+    secretTarget: ModelConfigTestSecretTargetSchema.optional(),
+    region: z.string().trim().min(1).optional()
 });
 export type ModelConfigTestInput = z.infer<typeof ModelConfigTestInputSchema>;
 
@@ -1078,7 +1090,8 @@ export const CatalogEndpointViewSchema = z.object({
     protocol: ModelEndpointProtocolSchema,
     hasApiKey: z.boolean(),
     apiKeyMasked: z.string(),
-    apiKey: z.string().default("")
+    apiKey: z.string().default(""),
+    region: z.string().min(1).optional()
 });
 export type CatalogEndpointView = z.infer<typeof CatalogEndpointViewSchema>;
 
@@ -1091,7 +1104,10 @@ export const TextModelItemViewSchema = z.object({
     source: ModelSourceSchema,
     ownerAccountId: z.string().min(1).optional(),
     capabilities: z.array(ModelCapabilitySchema).min(1),
-    available: z.boolean()
+    available: z.boolean(),
+    thinking: ModelThinkingConfigSchema.optional(),
+    custom: z.boolean().optional(),
+    inputModalities: z.array(ModelInputModalitySchema).optional()
 });
 export type TextModelItemView = z.infer<typeof TextModelItemViewSchema>;
 
diff --git a/App/backend/local-api-contracts/src/model-catalog-resolver.ts b/App/backend/local-api-contracts/src/model-catalog-resolver.ts
index 289eadfad..b813c3ace 100644
--- a/App/backend/local-api-contracts/src/model-catalog-resolver.ts
+++ b/App/backend/local-api-contracts/src/model-catalog-resolver.ts
@@ -11,6 +11,7 @@ export interface RuntimeCatalogEndpoint {
     apiKey?: string;
     extraHeaders?: Record<string, string>;
     extraBody?: Record<string, unknown>;
+    region?: string;
 }
 
 export const BUILTIN_LOCAL_EMBEDDING_ASSIGNMENT_ID = "memmy-builtin-local-embedding";
@@ -30,6 +31,7 @@ export interface RuntimeCatalogPreset {
     source: ModelSource;
     ownerAccountId?: string;
     capabilities: ModelCapability[];
+    inputModalities?: readonly ("text" | "image" | "video")[];
 }
 
 export interface RuntimeModelAssignment {
@@ -74,6 +76,7 @@ export interface ActualModelContext {
     ownerAccountId: string | null;
     capability: ModelCapability;
     capabilities: readonly ModelCapability[];
+    inputModalities?: readonly ("text" | "image" | "video")[];
 }
 
 export interface ResolvedProviderSnapshot {
@@ -118,7 +121,8 @@ const CAPABILITIES = new Set<ModelCapability>([
 const PROTOCOLS = new Set<ModelEndpointProtocol>([
     "openai-chat-completions", "openai-responses", "anthropic-messages",
     "gemini-generate-content", "openai-embeddings", "dashscope-input-audio-chat",
-    "openai-images", "dashscope-multimodal-generation", "memmy-account"
+    "openai-images", "dashscope-multimodal-generation", "memmy-account",
+    "bedrock-converse"
 ]);
 
 /** Resolves one immutable current-catalog model assignment without guessing another preset or endpoint. */
@@ -171,7 +175,8 @@ export function resolveAssignedModel(input: ResolveAssignedModelInput): ModelSel
         source: preset.source,
         ownerAccountId: preset.ownerAccountId ?? null,
         capability: input.capability,
-        capabilities
+        capabilities,
+        ...(preset.inputModalities ? { inputModalities: Object.freeze([...preset.inputModalities]) } : {})
     });
     const providerSnapshot = Object.freeze({
         provider: preset.provider,
@@ -301,7 +306,12 @@ function isRuntimePreset(value: unknown): value is RuntimeCatalogPreset {
         && value.capabilities.length > 0
         && value.capabilities.every((capability): capability is ModelCapability => (
             typeof capability === "string" && CAPABILITIES.has(capability as ModelCapability)
-        ));
+        ))
+        && (value.inputModalities === undefined
+            || (Array.isArray(value.inputModalities)
+                && value.inputModalities.every((modality) => (
+                    modality === "text" || modality === "image" || modality === "video"
+                ))));
 }
 
 function isRuntimeProvider(value: unknown): value is RuntimeCatalogProvider {
@@ -320,7 +330,8 @@ function isRuntimeEndpoint(value: unknown): value is RuntimeCatalogEndpoint {
         && PROTOCOLS.has(value.protocol as ModelEndpointProtocol)
         && (value.apiKey === undefined || typeof value.apiKey === "string")
         && validStringRecord(value.extraHeaders)
-        && validUnknownRecord(value.extraBody);
+        && validUnknownRecord(value.extraBody)
+        && (value.region === undefined || typeof value.region === "string");
 }
 
 function protocolSupportsCapability(
@@ -332,12 +343,14 @@ function protocolSupportsCapability(
         return protocol === "openai-chat-completions"
             || protocol === "openai-responses"
             || protocol === "anthropic-messages"
-            || protocol === "gemini-generate-content";
+            || protocol === "gemini-generate-content"
+            || protocol === "bedrock-converse";
     }
     if (capability === "memory_summary" || capability === "memory_evolution") {
         return protocol === "openai-chat-completions"
             || protocol === "anthropic-messages"
-            || protocol === "gemini-generate-content";
+            || protocol === "gemini-generate-content"
+            || protocol === "bedrock-converse";
     }
     if (capability === "embedding") return protocol === "openai-embeddings";
     if (capability === "asr") return protocol === "dashscope-input-audio-chat";
diff --git a/App/backend/local-api-contracts/src/model-thinking-levels.ts b/App/backend/local-api-contracts/src/model-thinking-levels.ts
new file mode 100644
index 000000000..3df8208b2
--- /dev/null
+++ b/App/backend/local-api-contracts/src/model-thinking-levels.ts
@@ -0,0 +1,249 @@
+/**
+ * 模型思考强度配置表。Reviewed: 2026-09-10
+ *
+ * 三个字段决定前端渲染与新 session 默认状态：
+ * - switchable: true  → 渲染思考开关（用户可关闭思考）
+ *                false → 不渲染开关（thinking always-on）
+ * - defaultEnabled: 新 session 默认开关状态（仅 switchable:true 时有意义，当前恒为 true）
+ * - levels: 强度档位列表（不含表示关闭的 "off"）。空数组 = 无档位选择器。
+ *
+ * 档位命名（统一 i18n key）：low=低, medium=中, high=高, xhigh=超高, max=最强
+ */
+import { z } from "zod";
+
+/** 思考强度档位。前端 i18n key 由 `home.thinking.levelValue.${level}` 拼出，须为字面量联合。 */
+export const THINKING_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export interface ModelThinkingConfig {
+  switchable: boolean;
+  defaultEnabled: boolean;
+  levels: readonly ThinkingLevel[];
+  defaultLevel?: ThinkingLevel;
+}
+
+export const ModelThinkingConfigSchema = z.object({
+  switchable: z.boolean(),
+  defaultEnabled: z.boolean(),
+  levels: z.array(z.enum(THINKING_LEVELS)),
+  defaultLevel: z.enum(THINKING_LEVELS).optional()
+});
+export type ModelThinkingConfigDto = z.infer<typeof ModelThinkingConfigSchema>;
+
+export const MODEL_THINKING_REVIEWED_AT = "2026-09-10";
+
+const ALWAYS_ON_FIVE: ModelThinkingConfig = {
+  switchable: false,
+  defaultEnabled: true,
+  levels: ["low", "medium", "high", "xhigh", "max"],
+  defaultLevel: "high"
+};
+
+const SWITCHABLE_FIVE: ModelThinkingConfig = {
+  switchable: true,
+  defaultEnabled: true,
+  levels: ["low", "medium", "high", "xhigh", "max"],
+  defaultLevel: "high"
+};
+
+const SWITCHABLE_FOUR: ModelThinkingConfig = {
+  switchable: true,
+  defaultEnabled: true,
+  levels: ["low", "medium", "high", "xhigh"],
+  defaultLevel: "medium"
+};
+
+const SWITCHABLE_THREE: ModelThinkingConfig = {
+  switchable: true,
+  defaultEnabled: true,
+  levels: ["low", "medium", "high"],
+  defaultLevel: "medium"
+};
+
+const SWITCHABLE_LOW_HIGH_MAX: ModelThinkingConfig = {
+  switchable: true,
+  defaultEnabled: true,
+  levels: ["low", "high", "max"],
+  defaultLevel: "high"
+};
+
+const SWITCHABLE_LOW_HIGH: ModelThinkingConfig = {
+  switchable: true,
+  defaultEnabled: true,
+  levels: ["low", "high"],
+  defaultLevel: "high"
+};
+
+const TOGGLE_ONLY: ModelThinkingConfig = {
+  switchable: true,
+  defaultEnabled: true,
+  levels: []
+};
+
+export const MODEL_THINKING_CONFIGS: Readonly<Record<string, ModelThinkingConfig>> = Object.freeze({
+  // Anthropic. Reviewed 2026-09-10.
+  "claude-fable-5-1": ALWAYS_ON_FIVE,
+  "claude-fable-5": ALWAYS_ON_FIVE,
+  "claude-mythos-5-1": ALWAYS_ON_FIVE,
+  "claude-mythos-5": ALWAYS_ON_FIVE,
+  "claude-mythos-preview": ALWAYS_ON_FIVE,
+  "claude-opus-5": SWITCHABLE_FIVE,
+  "claude-sonnet-5": SWITCHABLE_FIVE,
+  "claude-opus-4-8": SWITCHABLE_FIVE,
+  "claude-opus-4-7": SWITCHABLE_FIVE,
+  "claude-opus-4-6": SWITCHABLE_FIVE,
+  "claude-sonnet-4-6": SWITCHABLE_FIVE,
+  "claude-opus-4-5-20251101": {
+    switchable: true,
+    defaultEnabled: true,
+    levels: ["low", "medium", "high", "max"],
+    defaultLevel: "high"
+  },
+  "claude-haiku-4-5": TOGGLE_ONLY,
+  "claude-haiku-4-5-20251001": TOGGLE_ONLY,
+  "anthropic.claude-opus-5": SWITCHABLE_FIVE,
+  "anthropic.claude-sonnet-5": SWITCHABLE_FIVE,
+  "anthropic.claude-opus-4-8": SWITCHABLE_FIVE,
+  "anthropic.claude-opus-4-7": SWITCHABLE_FIVE,
+  "anthropic.claude-haiku-4-5": TOGGLE_ONLY,
+
+  // OpenAI. Reviewed 2026-09-10.
+  "gpt-5.6": SWITCHABLE_FIVE,
+  "gpt-5.6-sol": SWITCHABLE_FIVE,
+  "gpt-5.6-terra": SWITCHABLE_FIVE,
+  "gpt-5.6-luna": SWITCHABLE_FIVE,
+  "gpt-5.5": SWITCHABLE_FOUR,
+  "gpt-5.5-pro": SWITCHABLE_FOUR,
+  "gpt-5.4": SWITCHABLE_THREE,
+  "gpt-5.4-pro": SWITCHABLE_THREE,
+  "gpt-5.4-mini": SWITCHABLE_THREE,
+  "gpt-5.4-nano": SWITCHABLE_THREE,
+  "gpt-5.3-codex": SWITCHABLE_THREE,
+  "gpt-5.2": SWITCHABLE_THREE,
+  "gpt-5.2-pro": SWITCHABLE_THREE,
+  "gpt-5.2-codex": SWITCHABLE_THREE,
+  "gpt-5.1": SWITCHABLE_THREE,
+  "gpt-5.1-codex": SWITCHABLE_THREE,
+
+  // Gemini. Reviewed 2026-09-10.
+  "gemini-2.5-flash": TOGGLE_ONLY,
+  "gemini-2.5-flash-lite": TOGGLE_ONLY,
+
+  // DeepSeek. Reviewed 2026-09-10.
+  "deepseek-v4-pro": SWITCHABLE_LOW_HIGH_MAX,
+  "deepseek-v4-flash": SWITCHABLE_LOW_HIGH_MAX,
+  "deepseek-v4-flash-0731": SWITCHABLE_LOW_HIGH_MAX,
+  "deepseek-v4-flash-vision-exp": SWITCHABLE_LOW_HIGH_MAX,
+  "deepseek-v3.2": TOGGLE_ONLY,
+
+  // Zhipu GLM. Reviewed 2026-09-10.
+  "glm-5.3": {
+    switchable: false,
+    defaultEnabled: true,
+    levels: ["low", "high", "max"],
+    defaultLevel: "high"
+  },
+  "glm-5.2": TOGGLE_ONLY,
+  "glm-5.1": TOGGLE_ONLY,
+  "glm-5": TOGGLE_ONLY,
+  "glm-5-turbo": TOGGLE_ONLY,
+  "glm-4.7": TOGGLE_ONLY,
+
+  // Kimi / Moonshot. Reviewed 2026-09-10.
+  "kimi-k3": SWITCHABLE_LOW_HIGH_MAX,
+  "k3": SWITCHABLE_LOW_HIGH_MAX,
+  "k3-256k": SWITCHABLE_LOW_HIGH_MAX,
+  "kimi-k2.6": TOGGLE_ONLY,
+  "kimi-k2.5": TOGGLE_ONLY,
+
+  // MiniMax. Reviewed 2026-09-10.
+  "MiniMax-M3": TOGGLE_ONLY,
+
+  // Qwen. Reviewed 2026-09-10.
+  "qwen3.8-max": TOGGLE_ONLY,
+  "qwen3.8-max-preview": TOGGLE_ONLY,
+  "qwen3.7-max": TOGGLE_ONLY,
+  "qwen3.7-max-2026-05-20": TOGGLE_ONLY,
+  "qwen3.7-max-2026-06-08": TOGGLE_ONLY,
+  "qwen3.7-plus": TOGGLE_ONLY,
+  "qwen3.7-plus-2026-05-26": TOGGLE_ONLY,
+  "qwen3.7-flash": TOGGLE_ONLY,
+  "qwen3.7-flash-2026-07-15": TOGGLE_ONLY,
+  "qwen3.6-max-preview": TOGGLE_ONLY,
+  "qwen3.6-plus": TOGGLE_ONLY,
+  "qwen3.6-plus-2026-04-02": TOGGLE_ONLY,
+  "qwen3.6-flash": TOGGLE_ONLY,
+  "qwen3.6-flash-2026-04-16": TOGGLE_ONLY,
+  "qwen3.5-plus": TOGGLE_ONLY,
+  "qwen3.5-plus-2026-02-15": TOGGLE_ONLY,
+  "qwen3.5-flash": TOGGLE_ONLY,
+  "qwen3.5-flash-2026-02-23": TOGGLE_ONLY,
+  "qwen3-coder-plus": TOGGLE_ONLY,
+  "qwen3-coder-flash": TOGGLE_ONLY,
+
+  // Doubao. Reviewed 2026-09-10.
+  "doubao-seed-evolving": TOGGLE_ONLY,
+  "doubao-seed-2-1-pro": TOGGLE_ONLY,
+  "doubao-seed-2-1-turbo": TOGGLE_ONLY,
+  "doubao-seed-2-0-pro-260215": TOGGLE_ONLY,
+  "doubao-seed-2-0-lite-260215": TOGGLE_ONLY,
+  "doubao-seed-2-0-mini-260215": TOGGLE_ONLY,
+
+  // Xiaomi MiMo. Reviewed 2026-09-10.
+  "mimo-v2.5-pro": TOGGLE_ONLY,
+  "mimo-v2.5-pro-ultraspeed": TOGGLE_ONLY,
+  "mimo-v2.5": TOGGLE_ONLY,
+
+  // StepFun. Reviewed 2026-09-10.
+  "step-3.7-flash": SWITCHABLE_THREE,
+  "step-3.5-flash": SWITCHABLE_LOW_HIGH,
+  "step-3.5-flash-2603": SWITCHABLE_LOW_HIGH,
+
+  // Baidu ERNIE. Reviewed 2026-09-10.
+  "ernie-5.1": TOGGLE_ONLY,
+  "ernie-5.0": TOGGLE_ONLY,
+  "ernie-5.0-thinking-preview": TOGGLE_ONLY,
+  "ernie-5.0-thinking-latest": TOGGLE_ONLY,
+  "ernie-x1.1": TOGGLE_ONLY,
+  "ernie-x1.1-preview": TOGGLE_ONLY
+});
+
+export function getModelThinkingConfig(model: string | null | undefined): ModelThinkingConfig | null {
+  if (typeof model !== "string") return null;
+  return MODEL_THINKING_CONFIGS[model] ?? null;
+}
+
+/** 是否只有开关无档位（情况2）：可开关且无强度档位。 */
+export function isThinkingToggleOnly(config: ModelThinkingConfig | null): boolean {
+  if (!config) return false;
+  return config.switchable && config.levels.length === 0;
+}
+
+/** 解析当前生效的思考档位：会话选择优先，否则回退表中默认档，再退首个档位。 */
+export function resolveThinkingLevel(
+  config: ModelThinkingConfig,
+  sessionLevel: string | null | undefined
+): ThinkingLevel | null {
+  if (sessionLevel && config.levels.includes(sessionLevel as ThinkingLevel)) {
+    return sessionLevel as ThinkingLevel;
+  }
+  return config.defaultLevel ?? config.levels[0] ?? null;
+}
+
+/** 解析当前生效的开关状态：always-on 恒 true，其余用会话选择，缺省取 defaultEnabled。 */
+export function resolveThinkingEnabled(
+  config: ModelThinkingConfig,
+  sessionEnabled: boolean | undefined
+): boolean {
+  if (!config.switchable) return true;
+  return sessionEnabled ?? config.defaultEnabled;
+}
+
+/**
+ * 从档位列表取默认档（"中档"）：优先 medium，否则取中间项（偶数个时偏下，避免默认落到最高档）。
+ */
+export function defaultThinkingLevel(levels: readonly ThinkingLevel[]): ThinkingLevel | undefined {
+  if (levels.length === 0) return undefined;
+  if (levels.includes("medium")) return "medium";
+  return levels[Math.floor((levels.length - 1) / 2)];
+}
diff --git a/App/backend/local-api-contracts/tests/model-catalog-resolver.test.ts b/App/backend/local-api-contracts/tests/model-catalog-resolver.test.ts
index 7bc025940..09ea02778 100644
--- a/App/backend/local-api-contracts/tests/model-catalog-resolver.test.ts
+++ b/App/backend/local-api-contracts/tests/model-catalog-resolver.test.ts
@@ -228,4 +228,47 @@ describe("resolveAssignedModel", () => {
       capability: "memory_summary"
     })).toEqual({ ok: false, code: "model_selection_unavailable" });
   });
+
+  it("resolves bedrock-converse and declared input modalities", () => {
+    const current: RuntimeModelCatalog = {
+      providers: {
+        bedrock: {
+          endpoints: {
+            chat: {
+              apiBase: "https://bedrock-runtime.us-west-2.amazonaws.com",
+              protocol: "bedrock-converse",
+              region: "us-west-2"
+            }
+          }
+        }
+      },
+      modelPresets: {
+        custom: {
+          provider: "bedrock",
+          endpoint: "chat",
+          model: "anthropic.claude-sonnet-5",
+          source: "byok",
+          capabilities: ["agent"],
+          inputModalities: ["text", "image"]
+        }
+      },
+      modelAssignments: {
+        byok: {
+          agent: { candidates: ["custom"], default: "custom" }
+        }
+      }
+    };
+    const resolved = resolveAssignedModel({
+      catalog: current,
+      mode: "byok",
+      capability: "agent"
+    });
+
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok) return;
+    expect(resolved.context.protocol).toBe("bedrock-converse");
+    expect(resolved.context.provider).toBe("bedrock");
+    expect(resolved.context.inputModalities).toEqual(["text", "image"]);
+    expect(resolved.provider.apiBase).toBe("https://bedrock-runtime.us-west-2.amazonaws.com");
+  });
 });
diff --git a/App/backend/local-api-contracts/tests/model-thinking-levels.test.ts b/App/backend/local-api-contracts/tests/model-thinking-levels.test.ts
new file mode 100644
index 000000000..d67d416aa
--- /dev/null
+++ b/App/backend/local-api-contracts/tests/model-thinking-levels.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import {
+  defaultThinkingLevel,
+  getModelThinkingConfig,
+  isThinkingToggleOnly,
+  resolveThinkingEnabled,
+  resolveThinkingLevel,
+} from "../src/model-thinking-levels.js";
+
+describe("model thinking levels", () => {
+  it("returns table config, toggle-only, and default middle level", () => {
+    const gpt = getModelThinkingConfig("gpt-5.4");
+    expect(gpt).toMatchObject({
+      switchable: true,
+      defaultEnabled: true,
+      defaultLevel: "medium",
+    });
+    expect(isThinkingToggleOnly(getModelThinkingConfig("claude-haiku-4-5"))).toBe(true);
+    expect(getModelThinkingConfig("unlisted-model")).toBeNull();
+    expect(defaultThinkingLevel(["low", "medium", "high"])).toBe("medium");
+    expect(defaultThinkingLevel(["low", "high"])).toBe("low");
+    expect(defaultThinkingLevel([])).toBeUndefined();
+  });
+
+  it("resolves session override against table defaults", () => {
+    const gpt = getModelThinkingConfig("gpt-5.4")!;
+    expect(resolveThinkingEnabled(gpt, undefined)).toBe(true);
+    expect(resolveThinkingEnabled(gpt, false)).toBe(false);
+    expect(resolveThinkingLevel(gpt, undefined)).toBe("medium");
+    expect(resolveThinkingLevel(gpt, "high")).toBe("high");
+    expect(resolveThinkingLevel(gpt, "not-a-level")).toBe("medium");
+
+    const alwaysOn = getModelThinkingConfig("claude-fable-5")!;
+    expect(resolveThinkingEnabled(alwaysOn, false)).toBe(true);
+  });
+});
diff --git a/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts b/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
index c1d25dc37..7f6d2dae3 100644
--- a/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
+++ b/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
@@ -27,9 +27,9 @@ const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 type ConfigRecord = Record<string, unknown>;
 
 const CAPABILITY_PROTOCOLS: Readonly<Record<ModelCapability, ReadonlySet<ModelEndpointProtocol>>> = {
-  agent: new Set(["openai-chat-completions", "openai-responses", "anthropic-messages", "gemini-generate-content", "memmy-account"]),
-  memory_summary: new Set(["openai-chat-completions", "anthropic-messages", "gemini-generate-content", "memmy-account"]),
-  memory_evolution: new Set(["openai-chat-completions", "anthropic-messages", "gemini-generate-content", "memmy-account"]),
+  agent: new Set(["openai-chat-completions", "openai-responses", "anthropic-messages", "gemini-generate-content", "memmy-account", "bedrock-converse"]),
+  memory_summary: new Set(["openai-chat-completions", "anthropic-messages", "gemini-generate-content", "memmy-account", "bedrock-converse"]),
+  memory_evolution: new Set(["openai-chat-completions", "anthropic-messages", "gemini-generate-content", "memmy-account", "bedrock-converse"]),
   embedding: new Set(["openai-embeddings", "memmy-account"]),
   asr: new Set(["dashscope-input-audio-chat", "memmy-account"]),
   image_generation: new Set(["openai-images", "dashscope-multimodal-generation", "memmy-account"])
@@ -145,7 +145,7 @@ function mergeModelConfig(config: ConfigRecord, input: ModelConfigInput): Config
       validatePresetEndpoint(providerInput.provider, modelInput, endpoint);
       const presetId = resolvePresetId(modelInput.presetId, existingByokPresets, usedPresetIds);
       const previousPreset = record(existingByokPresets[presetId]);
-      nextPresets[presetId] = {
+      const nextPreset: ConfigRecord = {
         ...previousPreset,
         provider: providerInput.provider,
         endpoint: modelInput.endpointId,
@@ -153,8 +153,15 @@ function mergeModelConfig(config: ConfigRecord, input: ModelConfigInput): Config
         source: "byok",
         capabilities: [...new Set(modelInput.capabilities)]
       };
-      delete record(nextPresets[presetId]).label;
-      delete record(nextPresets[presetId]).ownerAccountId;
+      delete record(nextPreset).label;
+      delete record(nextPreset).ownerAccountId;
+      if (modelInput.thinking) nextPreset.thinking = modelInput.thinking;
+      else delete nextPreset.thinking;
+      if (modelInput.custom) nextPreset.custom = true;
+      else delete nextPreset.custom;
+      if (modelInput.inputModalities) nextPreset.inputModalities = [...modelInput.inputModalities];
+      else delete nextPreset.inputModalities;
+      nextPresets[presetId] = nextPreset;
     }
   }
 
@@ -443,6 +450,8 @@ function mergeEndpoint(previous: ConfigRecord, input: CatalogEndpointInput): Con
   setOptionalSecret(next, "apiKey", input.apiKey, previous.apiKey);
   setOptionalRecord(next, "extraHeaders", input.extraHeaders, previous.extraHeaders);
   setOptionalRecord(next, "extraBody", input.extraBody, previous.extraBody);
+  if (input.region) next.region = input.region;
+  else delete next.region;
   return next;
 }
 
@@ -651,7 +660,8 @@ function providerView(
       protocol,
       hasApiKey: Boolean(endpointApiKey),
       apiKeyMasked: maskSecret(endpointApiKey),
-      apiKey: ""
+      apiKey: "",
+      ...(stringValue(endpoint.region) ? { region: stringValue(endpoint.region)! } : {})
     }];
   });
   return {
@@ -692,7 +702,10 @@ function presetView(
     source,
     ...(stringValue(preset.ownerAccountId) ? { ownerAccountId: stringValue(preset.ownerAccountId)! } : {}),
     capabilities: arrayValue(preset.capabilities).filter(isModelCapability),
-    available: Boolean((hasCredential || API_KEY_OPTIONAL_PROVIDERS.has(providerId)) && ownerMatches)
+    available: Boolean((hasCredential || API_KEY_OPTIONAL_PROVIDERS.has(providerId)) && ownerMatches),
+    ...(preset.thinking && typeof preset.thinking === "object" ? { thinking: preset.thinking as TextModelItemView["thinking"] } : {}),
+    ...(preset.custom === true ? { custom: true } : {}),
+    ...(Array.isArray(preset.inputModalities) ? { inputModalities: preset.inputModalities as TextModelItemView["inputModalities"] } : {})
   };
 }
 
diff --git a/App/frontend/desktop/src/api/config-client.ts b/App/frontend/desktop/src/api/config-client.ts
index 00c147c71..c643a54f6 100644
--- a/App/frontend/desktop/src/api/config-client.ts
+++ b/App/frontend/desktop/src/api/config-client.ts
@@ -55,6 +55,7 @@ export interface ModelProviderConfig {
   provider: string;
   endpointId?: string;
   protocol?: ModelEndpointProtocol;
+  region?: string;
   endpoint: string;
   model: string;
   apiKey: string;
@@ -270,7 +271,8 @@ export function createHttpConfigClient(config: RuntimeConfig): ConfigClient {
           modelId: modelConfig.model,
           apiKey: modelConfig.apiKey || undefined,
           capability,
-          secretTarget
+          secretTarget,
+          ...(modelConfig.region ? { region: modelConfig.region } : {})
         })
       });
     },
@@ -821,11 +823,32 @@ function fromOptionalPreset(view: ModelConfigView, preset: ModelConfigView["prov
 }
 
 function toModelProvider(provider: string): ModelProvider {
-  if (provider === "openai") {
+  if (provider === "openai" || provider === "openai_responses") {
     return "openai_compatible";
   }
+  if (provider === "bedrock") {
+    return "anthropic";
+  }
+  if (provider === "gemini") {
+    return "google";
+  }
+  if (provider === "moonshot") {
+    return "kimi";
+  }
+  if (provider === "dashscope") {
+    return "qwen";
+  }
+  if (provider === "qianfan") {
+    return "baidu";
+  }
+  if (provider === "volcengine") {
+    return "doubao";
+  }
+  if (provider === "xiaomi_mimo") {
+    return "xiaomi";
+  }
 
-  return provider === "gemini" ? "google" : (provider as ModelProvider);
+  return provider as ModelProvider;
 }
 function toCatalogInput(config: ModelConfigInput | ModelConfigView): ModelConfigInput {
   if (!("configured" in config)) {
@@ -841,7 +864,8 @@ function toCatalogInput(config: ModelConfigInput | ModelConfigView): ModelConfig
         endpointId: endpoint.endpointId,
         apiBase: endpoint.apiBase,
         protocol: endpoint.protocol,
-        ...(endpoint.apiKey ? { apiKey: endpoint.apiKey } : {})
+        ...(endpoint.apiKey ? { apiKey: endpoint.apiKey } : {}),
+        ...(endpoint.region ? { region: endpoint.region } : {})
       })),
       models: provider.models.map((model) => ({
         ...(model.presetId ? { presetId: model.presetId } : {}),
@@ -849,7 +873,10 @@ function toCatalogInput(config: ModelConfigInput | ModelConfigView): ModelConfig
         model: model.model,
         source: model.source,
         ...(model.ownerAccountId ? { ownerAccountId: model.ownerAccountId } : {}),
-        capabilities: [...model.capabilities]
+        capabilities: [...model.capabilities],
+        ...(model.thinking ? { thinking: model.thinking } : {}),
+        ...(model.custom ? { custom: true } : {}),
+        ...(model.inputModalities ? { inputModalities: [...model.inputModalities] } : {})
       }))
     })),
     modelAssignments: structuredClone(config.modelAssignments)
diff --git a/App/frontend/desktop/src/api/memmy-agent-client.ts b/App/frontend/desktop/src/api/memmy-agent-client.ts
index 97ccbd236..27c6c80b3 100644
--- a/App/frontend/desktop/src/api/memmy-agent-client.ts
+++ b/App/frontend/desktop/src/api/memmy-agent-client.ts
@@ -225,7 +225,9 @@ const SessionSummarySchema = z.object({
   projectId: z.string().nullable(),
   cwd: z.string(),
   model_preset: z.string().nullable().optional(),
-  model_selection: ModelSelectionSchema.nullable().optional()
+  model_selection: ModelSelectionSchema.nullable().optional(),
+  thinking_enabled: z.boolean().nullable().optional(),
+  thinking_level: z.string().nullable().optional()
 }).passthrough();
 
 const ProjectSchema = z.object({
@@ -636,6 +638,8 @@ export type MemmyAgentSendMessageInput = {
   language?: MemmyAgentUiLanguage;
   media?: MemmyAgentMediaInput[];
   modelPreset?: string | null;
+  thinkingEnabled?: boolean;
+  thinkingLevel?: string | null;
 };
 
 export interface MemmyAgentNewChatResult {
@@ -2324,6 +2328,8 @@ class MemmyAgentWebSocketSession implements MemmyAgentWebSocketConnection {
       ...(input.target ? { target: input.target } : {}),
       ...(input.language ? { language: input.language } : {}),
       ...(input.modelPreset !== undefined ? { model_preset: input.modelPreset } : {}),
+      ...(input.thinkingEnabled !== undefined ? { thinking_enabled: input.thinkingEnabled } : {}),
+      ...(input.thinkingLevel ? { thinking_level: input.thinkingLevel } : {}),
       ...(input.media?.length ? { media_paths: input.media.map((item) => item.path) } : {})
     }, expectedGeneration);
     this.knownChats.add(input.chatId);
diff --git a/App/frontend/desktop/src/components/agent-model-selector.tsx b/App/frontend/desktop/src/components/agent-model-selector.tsx
index 85528e583..f81d63ffa 100644
--- a/App/frontend/desktop/src/components/agent-model-selector.tsx
+++ b/App/frontend/desktop/src/components/agent-model-selector.tsx
@@ -4,14 +4,16 @@ import { useTranslation } from "../i18n/use-translation.js";
 import { agentActions, appActions } from "../state/app-actions.js";
 import { useAppState } from "../state/app-state.js";
 import {
-  getTaskModelCandidates,
   createModelWorkspace,
+  getTaskModelCandidates,
   resolveModelSelection,
+  resolveThinkingConfigForModel,
   type ModelWorkspaceMode
 } from "../state/model-workspace.js";
 import {
   settingsTabHash
 } from "../pages/settings-nav.js";
+import { AgentThinkingControl } from "./agent-thinking-control.js";
 import { ModelProviderLogo } from "./model-provider-logo.js";
 import { Select, type SelectOption } from "./Select.js";
 
@@ -97,7 +99,15 @@ export function AgentModelSelector(props: AgentModelSelectorProps) {
     dispatch(appActions.navigate("/settings"));
   }
 
+  const thinkingConfig = resolveThinkingConfigForModel(workspace, resolved.candidate);
+
   return (
+    <div className="agent-model-selector-with-thinking">
+      <AgentThinkingControl
+        scopeKey={props.scopeKey}
+        thinkingConfig={thinkingConfig}
+        disabled={props.disabled}
+      />
     <div className="agent-model-selector" data-model-selector-scope={props.scopeKey}>
       <Select
         label={t("home.modelSelector.label")}
@@ -129,6 +139,7 @@ export function AgentModelSelector(props: AgentModelSelectorProps) {
         )}
       />
     </div>
+    </div>
   );
 }
 
diff --git a/App/frontend/desktop/src/components/agent-thinking-control.tsx b/App/frontend/desktop/src/components/agent-thinking-control.tsx
new file mode 100644
index 000000000..0ec32faf1
--- /dev/null
+++ b/App/frontend/desktop/src/components/agent-thinking-control.tsx
@@ -0,0 +1,117 @@
+import { Brain, ChevronDown } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import {
+  resolveThinkingEnabled,
+  resolveThinkingLevel,
+  type ModelThinkingConfig,
+  type ThinkingLevel
+} from "@memmy/local-api-contracts";
+import { useTranslation } from "../i18n/use-translation.js";
+import { agentActions } from "../state/app-actions.js";
+import { useAppState } from "../state/app-state.js";
+
+export interface AgentThinkingControlProps {
+  scopeKey: string;
+  thinkingConfig: ModelThinkingConfig | null;
+  disabled: boolean;
+}
+
+export function AgentThinkingControl(props: AgentThinkingControlProps) {
+  const { t } = useTranslation();
+  const { state, dispatch } = useAppState();
+  const [pickerOpen, setPickerOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const config = props.thinkingConfig;
+
+  const thinkingState = state.agent.thinkingStateByScope[props.scopeKey];
+  const enabled = config
+    ? resolveThinkingEnabled(config, thinkingState?.enabled)
+    : false;
+  const currentLevel = config
+    ? resolveThinkingLevel(config, thinkingState?.level)
+    : null;
+
+  useEffect(() => {
+    if (!pickerOpen) return;
+    const handleClickOutside = (event: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
+        setPickerOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, [pickerOpen]);
+
+  if (!config) {
+    return null;
+  }
+
+  const hasLevels = config.levels.length > 0;
+  const showLevels = hasLevels && enabled && currentLevel !== null;
+  const level: ThinkingLevel | null = showLevels ? currentLevel : null;
+
+  function toggleThinking() {
+    dispatch(agentActions.thinkingToggled(props.scopeKey, !enabled));
+  }
+
+  function selectLevel(next: string) {
+    dispatch(agentActions.thinkingLevelChanged(props.scopeKey, next));
+    setPickerOpen(false);
+  }
+
+  return (
+    <div ref={containerRef} className="agent-thinking-control">
+      {config.switchable && (
+        <button
+          type="button"
+          onClick={toggleThinking}
+          disabled={props.disabled}
+          aria-pressed={enabled}
+          className={`thinking-toggle ${enabled ? "thinking-toggle--on" : ""}`}
+          aria-label={t("home.thinking.toggle")}
+        >
+          <Brain size={16} className="thinking-toggle__icon" />
+          <span className="thinking-toggle__label">{t("home.thinking.label")}</span>
+          <div className={`thinking-toggle__switch ${enabled ? "thinking-toggle__switch--on" : ""}`}>
+            <div className="thinking-toggle__switch-thumb" />
+          </div>
+        </button>
+      )}
+
+      {level !== null && (
+        <div className="thinking-level-trigger-container">
+          <button
+            type="button"
+            onClick={() => setPickerOpen(!pickerOpen)}
+            disabled={props.disabled}
+            className="thinking-level-trigger"
+            aria-label={t("home.thinking.selectLevel")}
+          >
+            <span className="thinking-level-trigger__label">
+              {t("home.thinking.level")}: {t(`home.thinking.levelValue.${level}`)}
+            </span>
+            <ChevronDown size={14} className="thinking-level-trigger__icon" />
+          </button>
+
+          {pickerOpen && (
+            <div className="thinking-level-picker">
+              <div className="thinking-level-picker__header">
+                {t("home.thinking.levelHeader")}
+              </div>
+              {config.levels.map((option) => (
+                <button
+                  key={option}
+                  type="button"
+                  onClick={() => selectLevel(option)}
+                  className={`thinking-level-option ${level === option ? "thinking-level-option--selected" : ""}`}
+                >
+                  {t(`home.thinking.levelValue.${option}`)}
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/App/frontend/desktop/src/components/model-provider-logo.tsx b/App/frontend/desktop/src/components/model-provider-logo.tsx
index 7cfea1439..a00e0e748 100644
--- a/App/frontend/desktop/src/components/model-provider-logo.tsx
+++ b/App/frontend/desktop/src/components/model-provider-logo.tsx
@@ -17,6 +17,7 @@ export { memmyCoverLogoUrl };
 
 const PROTOCOL_LOGO_URLS: Record<Protocol, string> = {
   openai: openaiLogoUrl,
+  openai_responses: openaiLogoUrl,
   anthropic: anthropicLogoUrl,
   gemini: geminiLogoUrl,
   deepseek: deepseekLogoUrl,
@@ -27,7 +28,8 @@ const PROTOCOL_LOGO_URLS: Record<Protocol, string> = {
   baidu: baiduLogoUrl,
   doubao: doubaoLogoUrl,
   stepfun: stepfunLogoUrl,
-  xiaomi: xiaomiLogoUrl
+  xiaomi: xiaomiLogoUrl,
+  custom: openaiLogoUrl
 };
 
 /** Resolve a logo URL for a protocol or free-form provider string. */
diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index 9e79ffc53..dc21ce1be 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -305,6 +305,8 @@ export const zhCNMessages = {
   "apiKey.group.international": "国际",
   "apiKey.group.domestic": "国产",
   "apiKey.provider.openai": "OpenAI 兼容",
+  "apiKey.provider.openaiCompletions": "OpenAI Completions",
+  "apiKey.provider.openaiResponses": "OpenAI Responses",
   "apiKey.provider.anthropic": "Anthropic",
   "apiKey.provider.gemini": "Google Gemini",
   "apiKey.provider.deepseek": "DeepSeek",
@@ -317,6 +319,11 @@ export const zhCNMessages = {
   "apiKey.provider.stepfun": "阶跃星辰",
   "apiKey.provider.xiaomi": "小米 MiMo",
   "apiKey.provider.memmy": "Memmy",
+  "apiKey.provider.custom": "Custom",
+  "apiKey.customProtocol.openaiCompletions": "OpenAI Chat Completions",
+  "apiKey.customProtocol.openaiResponses": "OpenAI Responses",
+  "apiKey.customProtocol.anthropicMessages": "Anthropic Messages",
+  "apiKey.customProtocol.awsBedrock": "AWS Bedrock",
   "apiKey.localEmbedding": "内嵌本地模型（默认 / 推荐）",
   "apiKey.customEmbedding": "使用自定义 API",
   "apiKey.testMissingFields": "请先填写 API 地址、模型 ID 和 API Key",
@@ -496,6 +503,16 @@ export const zhCNMessages = {
   "home.modelSelector.emptyHint": "当前模型空间没有可用模型，请先前往设置添加。",
   "home.modelSelector.saveFailed": "模型选择保存失败，请重试。",
   "home.modelSelector.configureCustom": "管理自定义模型",
+  "home.thinking.toggle": "切换思考模式",
+  "home.thinking.label": "思考模式",
+  "home.thinking.level": "思考强度",
+  "home.thinking.selectLevel": "选择思考强度",
+  "home.thinking.levelHeader": "思考强度",
+  "home.thinking.levelValue.low": "低",
+  "home.thinking.levelValue.medium": "中",
+  "home.thinking.levelValue.high": "高",
+  "home.thinking.levelValue.xhigh": "超高",
+  "home.thinking.levelValue.max": "最强",
   "home.scrollToLatest": "回到最新",
   "home.commandPalette.commands": "指令",
   "home.command.newTitle": "新对话",
@@ -1531,6 +1548,16 @@ export const zhCNMessages = {
   "settings.modelWorkspace.incompatibleModelCapabilities": "所选模型类型与当前连接协议不匹配，请选择与连接一致的模型类型。",
   "settings.modelWorkspace.connectionMissing": "配置已不存在，请刷新后重试。",
   "settings.modelWorkspace.invalidConnection": "请完整填写 Provider、Endpoint、API Key 和模型名称。",
+  "settings.modelWorkspace.customProtocol": "协议",
+  "settings.modelWorkspace.region": "区域",
+  "settings.modelWorkspace.regionPlaceholder": "例如：us-east-1",
+  "settings.modelWorkspace.customThinkingEnabled": "支持思考",
+  "settings.modelWorkspace.customThinkingSwitchable": "可关闭思考",
+  "settings.modelWorkspace.customThinkingDefaultEnabled": "默认开启思考",
+  "settings.modelWorkspace.customThinkingLevels": "思考档位",
+  "settings.modelWorkspace.customThinkingLevelsPlaceholder": "例如：low,medium,high",
+  "settings.modelWorkspace.customThinkingLevelsHint": "用逗号分隔多个档位名称，留空表示无档位",
+  "settings.modelWorkspace.customImageInput": "支持图片输入",
   "settings.token.detail": "Token 用量详情",
   "settings.token.agentTask": "Agent 任务",
   "settings.token.memorySummary": "记忆摘要",
@@ -2045,6 +2072,8 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "apiKey.group.international": "International",
   "apiKey.group.domestic": "Domestic",
   "apiKey.provider.openai": "OpenAI compatible",
+  "apiKey.provider.openaiCompletions": "OpenAI Completions",
+  "apiKey.provider.openaiResponses": "OpenAI Responses",
   "apiKey.provider.anthropic": "Anthropic",
   "apiKey.provider.gemini": "Google Gemini",
   "apiKey.provider.deepseek": "DeepSeek",
@@ -2057,6 +2086,11 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "apiKey.provider.stepfun": "StepFun",
   "apiKey.provider.xiaomi": "Xiaomi MiMo",
   "apiKey.provider.memmy": "Memmy",
+  "apiKey.provider.custom": "Custom",
+  "apiKey.customProtocol.openaiCompletions": "OpenAI Chat Completions",
+  "apiKey.customProtocol.openaiResponses": "OpenAI Responses",
+  "apiKey.customProtocol.anthropicMessages": "Anthropic Messages",
+  "apiKey.customProtocol.awsBedrock": "AWS Bedrock",
   "apiKey.localEmbedding": "Built-in local model (default / recommended)",
   "apiKey.customEmbedding": "Use a custom API",
   "apiKey.testMissingFields": "Fill in API URL, model ID, and API key first",
@@ -2236,6 +2270,16 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "home.modelSelector.emptyHint": "This model space has no available models. Add one in Settings first.",
   "home.modelSelector.saveFailed": "Could not save the model selection. Try again.",
   "home.modelSelector.configureCustom": "Manage custom models",
+  "home.thinking.toggle": "Toggle thinking",
+  "home.thinking.label": "Thinking",
+  "home.thinking.level": "Thinking effort",
+  "home.thinking.selectLevel": "Select thinking effort",
+  "home.thinking.levelHeader": "Thinking effort",
+  "home.thinking.levelValue.low": "Low",
+  "home.thinking.levelValue.medium": "Medium",
+  "home.thinking.levelValue.high": "High",
+  "home.thinking.levelValue.xhigh": "Extra high",
+  "home.thinking.levelValue.max": "Max",
   "home.scrollToLatest": "Jump to latest",
   "home.commandPalette.commands": "Commands",
   "home.command.newTitle": "New chat",
@@ -3271,6 +3315,16 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "settings.modelWorkspace.incompatibleModelCapabilities": "The selected model type does not match this connection protocol. Choose the same model type as the connection.",
   "settings.modelWorkspace.connectionMissing": "This configuration no longer exists. Refresh and try again.",
   "settings.modelWorkspace.invalidConnection": "Complete the provider, endpoint, API key, and model name.",
+  "settings.modelWorkspace.customProtocol": "Protocol",
+  "settings.modelWorkspace.region": "Region",
+  "settings.modelWorkspace.regionPlaceholder": "For example: us-east-1",
+  "settings.modelWorkspace.customThinkingEnabled": "Supports thinking",
+  "settings.modelWorkspace.customThinkingSwitchable": "Thinking can be turned off",
+  "settings.modelWorkspace.customThinkingDefaultEnabled": "Thinking on by default",
+  "settings.modelWorkspace.customThinkingLevels": "Thinking levels",
+  "settings.modelWorkspace.customThinkingLevelsPlaceholder": "For example: low,medium,high",
+  "settings.modelWorkspace.customThinkingLevelsHint": "Comma-separated level names. Leave empty for no levels.",
+  "settings.modelWorkspace.customImageInput": "Supports image input",
   "settings.token.detail": "Token usage details",
   "settings.token.agentTask": "Agent tasks",
   "settings.token.memorySummary": "Memory summary",
diff --git a/App/frontend/desktop/src/pages/home-page.tsx b/App/frontend/desktop/src/pages/home-page.tsx
index d823d2eae..0c001b4d2 100644
--- a/App/frontend/desktop/src/pages/home-page.tsx
+++ b/App/frontend/desktop/src/pages/home-page.tsx
@@ -1,6 +1,6 @@
 /** Home page module. */
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ChangeEvent, type ClipboardEvent, type DragEvent, type KeyboardEvent, type PointerEvent as ReactPointerEvent, type SetStateAction, type UIEvent } from "react";
-import type { AgentGatewayStartupIssue } from "@memmy/local-api-contracts";
+import { resolveThinkingEnabled, resolveThinkingLevel, type AgentGatewayStartupIssue } from "@memmy/local-api-contracts";
 import { hydrateAgentThreadInBackground, refreshAgentTaskList, useAgentRuntimeBridge, type AgentTaskStateCoordinator } from "../app/agent-runtime-bridge.js";
 import { useApiClients } from "../app/providers.js";
 import { FOCUSED_AGENT_CHAT_STORAGE_KEY, clearFocusedAgentTarget, isAccountTokenQuotaExhausted, normalizeAgentChatId, readLaunchAgentChatId, removeLaunchAgentChatIdFromUrl } from "../app/routes.js";
@@ -40,7 +40,7 @@ import { ImChannelTitleIcon, imChannelTitleDisplay } from "../integrations/integ
 import { useTaskBus, type TaskBusAgentMessage } from "../lib/task-bus.js";
 import type { AppAction } from "../state/app-actions.js";
 import { agentActions, appActions, createAgentOperationError } from "../state/app-actions.js";
-import { type AgentChatMessage, type AgentState } from "../state/agent-chat-slice.js";
+import { NEW_TASK_MODEL_SCOPE_KEY, type AgentChatMessage, type AgentState, type AgentThinkingState } from "../state/agent-chat-slice.js";
 import { useAppState } from "../state/app-state.js";
 import { isComposingKeyboardEvent } from "../utils/keyboard.js";
 import {
@@ -51,7 +51,7 @@ import {
   type PendingFileAttachment,
   type PendingImage
 } from "../state/agent-composer-state.js";
-import { createModelWorkspace, defaultModelSelectionInput, resolveModelSelection } from "../state/model-workspace.js";
+import { createModelWorkspace, defaultModelSelectionInput, resolveModelSelection, resolveThinkingConfigForModel, type ModelCandidate, type ModelWorkspace } from "../state/model-workspace.js";
 import {
   AgentCommandPalette,
   buildVisibleSlashCommands,
@@ -99,8 +99,6 @@ export { hydrateAgentThreadInBackground };
 export { isComposingKeyboardEvent } from "../utils/keyboard.js";
 export type { PendingAttachment, PendingAttachmentBase, PendingFileAttachment, PendingImage };
 
-const NEW_TASK_MODEL_SCOPE_KEY = "draft-new-task";
-
 const AGENT_WS_SAFE_FRAME_BYTES = 1024 * 1024;
 const COMPOSER_HEIGHT_EPSILON = 2;
 
@@ -310,6 +308,8 @@ export interface SubmitAgentComposerMessageInput {
   getChatSelectionEpoch?: () => number;
   scopeKey?: string;
   modelPreset?: string | null;
+  thinkingEnabled?: boolean;
+  thinkingLevel?: string | null;
 }
 
 export interface RequestAgentStopInput {
@@ -651,6 +651,20 @@ export function requestNewSessionReset(input: RequestNewSessionResetInput): bool
   return true;
 }
 
+export function thinkingPayloadForSend(
+  workspace: ModelWorkspace,
+  candidate: ModelCandidate | null | undefined,
+  sessionThinking: AgentThinkingState | undefined
+): { thinkingEnabled?: boolean; thinkingLevel?: string | null } {
+  const config = resolveThinkingConfigForModel(workspace, candidate);
+  if (!config) return {};
+  const thinkingEnabled = resolveThinkingEnabled(config, sessionThinking?.enabled);
+  const thinkingLevel = thinkingEnabled
+    ? resolveThinkingLevel(config, sessionThinking?.level)
+    : null;
+  return { thinkingEnabled, thinkingLevel };
+}
+
 export async function submitAgentComposerMessage(input: SubmitAgentComposerMessageInput): Promise<boolean> {
   const text = input.content.trim();
   const trimmedDisplayContent = input.displayContent?.trim();
@@ -745,6 +759,8 @@ export async function submitAgentComposerMessage(input: SubmitAgentComposerMessa
     ...(capturedTarget ? { target: capturedTarget } : {}),
     ...(input.language ? { language: input.language } : {}),
     ...(confirmedModelPreset !== undefined ? { model_preset: confirmedModelPreset } : {}),
+    ...(input.thinkingEnabled !== undefined ? { thinking_enabled: input.thinkingEnabled } : {}),
+    ...(input.thinkingLevel ? { thinking_level: input.thinkingLevel } : {}),
     ...(uploadedAttachments.length ? { media_paths: uploadedAttachments.map((item) => item.path) } : {})
   };
   if (encodedPayloadBytes(payload) > AGENT_WS_SAFE_FRAME_BYTES) {
@@ -768,6 +784,8 @@ export async function submitAgentComposerMessage(input: SubmitAgentComposerMessa
       ...(capturedTarget ? { target: capturedTarget } : {}),
       ...(input.language ? { language: input.language } : {}),
       ...(confirmedModelPreset !== undefined ? { modelPreset: confirmedModelPreset } : {}),
+      ...(input.thinkingEnabled !== undefined ? { thinkingEnabled: input.thinkingEnabled } : {}),
+      ...(input.thinkingLevel !== undefined ? { thinkingLevel: input.thinkingLevel } : {}),
       media: uploadedAttachments
     }, expectedGeneration);
   } catch (error) {
@@ -1773,6 +1791,11 @@ export function HomePage() {
         getChatSelectionEpoch: () => chatSelectionEpochRef.current,
         scopeKey: sendScopeKey,
         modelPreset: resolvedConversationModel.candidateId ?? undefined,
+        ...thinkingPayloadForSend(
+          modelWorkspace,
+          resolvedConversationModel.candidate,
+          state.agent.thinkingStateByScope[modelSelectionScopeKey]
+        ),
         onChatResolved: (chatId) => dispatch(agentActions.modelSelectionRequestStarted(
           sendScopeKey,
           chatId,
diff --git a/App/frontend/desktop/src/pages/model-config.ts b/App/frontend/desktop/src/pages/model-config.ts
index 130097964..f124143ef 100644
--- a/App/frontend/desktop/src/pages/model-config.ts
+++ b/App/frontend/desktop/src/pages/model-config.ts
@@ -20,7 +20,7 @@ import {
 } from "./model-config-validation.js";
 
 /** Type definition for protocol. */
-export type Protocol = "openai" | "anthropic" | "gemini" | "deepseek" | "zhipu" | "qwen" | "moonshot" | "minimax" | "baidu" | "doubao" | "stepfun" | "xiaomi";
+export type Protocol = "openai" | "openai_responses" | "anthropic" | "gemini" | "deepseek" | "zhipu" | "qwen" | "moonshot" | "minimax" | "baidu" | "doubao" | "stepfun" | "xiaomi" | "custom";
 
 /** Contract for model config. */
 export interface ModelConfig {
@@ -33,6 +33,7 @@ export interface ModelConfig {
   configured: boolean;
   showKey: boolean;
   validation: ModelConfigValidationState;
+  customProtocol?: CustomProtocol;
 }
 
 /** Contract for protocol option. */
@@ -108,7 +109,8 @@ export interface TestModelConnectionMessages {
 }
 
 export const PROTOCOL_OPTIONS: ProtocolOption[] = [
-  { value: "openai", labelKey: "apiKey.provider.openai" },
+  { value: "openai", labelKey: "apiKey.provider.openaiCompletions" },
+  { value: "openai_responses", labelKey: "apiKey.provider.openaiResponses" },
   { value: "anthropic", labelKey: "apiKey.provider.anthropic" },
   { value: "gemini", labelKey: "apiKey.provider.gemini" },
   { value: "deepseek", labelKey: "apiKey.provider.deepseek" },
@@ -119,13 +121,15 @@ export const PROTOCOL_OPTIONS: ProtocolOption[] = [
   { value: "baidu", labelKey: "apiKey.provider.baidu" },
   { value: "doubao", labelKey: "apiKey.provider.doubao" },
   { value: "stepfun", labelKey: "apiKey.provider.stepfun" },
-  { value: "xiaomi", labelKey: "apiKey.provider.xiaomi" }
+  { value: "xiaomi", labelKey: "apiKey.provider.xiaomi" },
+  { value: "custom", labelKey: "apiKey.provider.custom" }
 ];
 
 const MEMMY_ACCOUNT_PROVIDER = "memmy_account";
 
 export const DEFAULT_ENDPOINTS: Record<Protocol, string> = {
   openai: "https://api.openai.com/v1",
+  openai_responses: "https://api.openai.com/v1",
   anthropic: "https://api.anthropic.com",
   gemini: "https://generativelanguage.googleapis.com",
   deepseek: "https://api.deepseek.com/v1",
@@ -136,11 +140,13 @@ export const DEFAULT_ENDPOINTS: Record<Protocol, string> = {
   baidu: "https://qianfan.baidubce.com/v2",
   doubao: "https://ark.cn-beijing.volces.com/api/v3",
   stepfun: "https://api.stepfun.com/v1",
-  xiaomi: "https://api.xiaomimimo.com/v1"
+  xiaomi: "https://api.xiaomimimo.com/v1",
+  custom: ""
 };
 
 export const DEFAULT_MODEL_IDS: Record<Protocol, string> = {
   openai: "gpt-4o",
+  openai_responses: "gpt-4o",
   anthropic: "claude-sonnet-4",
   gemini: "gemini-2.5-pro",
   deepseek: "deepseek-chat",
@@ -151,7 +157,8 @@ export const DEFAULT_MODEL_IDS: Record<Protocol, string> = {
   baidu: "ernie-x1.1",
   doubao: "doubao-pro-256k",
   stepfun: "step-3.5-flash",
-  xiaomi: "mimo-v2.5-pro"
+  xiaomi: "mimo-v2.5-pro",
+  custom: ""
 };
 
 export const ASR_MODEL_ID = QWEN_ASR_MODEL_ID;
@@ -633,6 +640,14 @@ export function toProtocol(provider: string): Protocol {
     return "moonshot";
   }
 
+  if (provider === "openai_responses") {
+    return "openai_responses";
+  }
+
+  if (provider === "custom") {
+    return "custom";
+  }
+
   return PROTOCOL_OPTIONS.some((option) => option.value === provider) ? (provider as Protocol) : "openai";
 }
 
@@ -692,5 +707,26 @@ export function textProviderDisplayName(
 
 /** Handles from protocol. */
 export function fromProtocol(protocol: Protocol): string {
-  return protocol === "moonshot" ? "kimi" : protocol;
+  if (protocol === "moonshot") return "kimi";
+  if (protocol === "openai_responses") return "openai_responses";
+  if (protocol === "custom") return "custom";
+  return protocol;
 }
+
+export type CustomProtocol =
+  | "openai-chat-completions"
+  | "openai-responses"
+  | "anthropic-messages"
+  | "bedrock-converse";
+
+export interface CustomProtocolOption {
+  value: CustomProtocol;
+  labelKey: MessageKey;
+}
+
+export const CUSTOM_PROTOCOL_OPTIONS: CustomProtocolOption[] = [
+  { value: "openai-chat-completions", labelKey: "apiKey.customProtocol.openaiCompletions" },
+  { value: "openai-responses", labelKey: "apiKey.customProtocol.openaiResponses" },
+  { value: "anthropic-messages", labelKey: "apiKey.customProtocol.anthropicMessages" },
+  { value: "bedrock-converse", labelKey: "apiKey.customProtocol.awsBedrock" }
+];
diff --git a/App/frontend/desktop/src/pages/model-workspace-section.tsx b/App/frontend/desktop/src/pages/model-workspace-section.tsx
index f6a81a738..d6140102a 100644
--- a/App/frontend/desktop/src/pages/model-workspace-section.tsx
+++ b/App/frontend/desktop/src/pages/model-workspace-section.tsx
@@ -2,7 +2,12 @@ import { AlertTriangle, Check, CheckCircle2, ChevronDown, ChevronUp, Database, I
 import {
   BUILTIN_LOCAL_EMBEDDING_ASSIGNMENT_ID,
   MODEL_NAME_MAX_LENGTH,
-  type ModelEndpointProtocol
+  THINKING_LEVELS,
+  defaultThinkingLevel,
+  type ModelEndpointProtocol,
+  type ModelThinkingConfig,
+  type ModelThinkingConfigDto,
+  type ThinkingLevel
 } from "@memmy/local-api-contracts";
 import { useCallback, useEffect, useRef, useState } from "react";
 import type { ConfigClient, ModelProviderConfig } from "../api/config-client.js";
@@ -25,8 +30,10 @@ import {
   setDefaultTaskModel,
   setTaskModelCandidates,
   upsertModelConnection,
+  isCustomModelEntry,
   type ModelCapability,
   type ModelAssignmentKind,
+  type ModelCandidate,
   type ModelConnection,
   type ModelWorkspaceMode,
   type ModelWorkspaceMutationError
@@ -36,7 +43,7 @@ import {
   PasswordConfigField,
   TestButton as ApiKeyTestButton
 } from "./api-key-form-fields.js";
-import { DEFAULT_ENDPOINTS, DEFAULT_MODEL_IDS, PROTOCOL_OPTIONS, fromProtocol, type Protocol } from "./model-config.js";
+import { DEFAULT_ENDPOINTS, DEFAULT_MODEL_IDS, PROTOCOL_OPTIONS, CUSTOM_PROTOCOL_OPTIONS, fromProtocol, type CustomProtocol, type Protocol } from "./model-config.js";
 import {
   SETTINGS_ADD_MODEL_EVENT,
   SETTINGS_ADD_MODEL_RETURN_STORAGE_KEY,
@@ -77,6 +84,13 @@ interface ConnectionEditorState {
   provider: Protocol;
   endpoint: string;
   apiKey: string;
+  customProtocol: CustomProtocol | null;
+  region: string;
+  customThinkingEnabled: boolean;
+  customThinkingSwitchable: boolean;
+  customThinkingDefaultEnabled: boolean;
+  customThinkingLevels: string;
+  customImageInput: boolean;
   models: Array<{
     presetId?: string;
     name: string;
@@ -223,6 +237,13 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       provider,
       endpoint: DEFAULT_ENDPOINTS[provider],
       apiKey: "",
+      customProtocol: provider === "custom" ? "openai-chat-completions" : null,
+      region: "",
+      customThinkingEnabled: false,
+      customThinkingSwitchable: true,
+      customThinkingDefaultEnabled: true,
+      customThinkingLevels: "",
+      customImageInput: false,
       models: [],
       modelDraft: DEFAULT_MODEL_IDS[provider],
       capabilityDrafts: [...DEFAULT_TEXT_CAPABILITIES],
@@ -269,7 +290,13 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
   }, [openAddConnection, props.autoOpenAddConnection]);
 
   function openEditConnection(connection: ModelConnection) {
-    const provider = protocolFromConnection(connection.provider);
+    const isCustom = connection.modelEntries[0]?.custom === true;
+    const provider: Protocol = isCustom
+      ? "custom"
+      : connection.protocol === "openai-responses"
+        ? "openai_responses"
+        : protocolFromConnection(connection.provider);
+    const thinking = connection.modelEntries[0]?.thinking;
     const savedTest = connectionTestState(connection, testStates);
     setFormError(null);
     setEditorTest(savedTest
@@ -281,6 +308,13 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       provider,
       endpoint: connection.endpoint,
       apiKey: "",
+      customProtocol: isCustom ? connection.protocol as CustomProtocol : null,
+      region: connection.region ?? "",
+      customThinkingEnabled: Boolean(thinking),
+      customThinkingSwitchable: thinking?.switchable ?? true,
+      customThinkingDefaultEnabled: thinking?.defaultEnabled ?? true,
+      customThinkingLevels: thinking?.levels.join(",") ?? "",
+      customImageInput: connection.modelEntries[0]?.inputModalities?.includes("image") === true,
       models: connection.modelEntries.map((entry) => ({
         presetId: entry.presetId,
         name: entry.model,
@@ -337,18 +371,40 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       ? space.connections.find((connection) => connection.id === editor.connectionId)
       : undefined;
     const providerChanged = Boolean(
-      existing && protocolFromConnection(existing.provider) !== editor.provider
+      existing && editorIdentity(existing) !== editor.provider
     );
     const capabilities = resolved.models.flatMap((model) => model.capabilities);
-    const result = upsertModelConnection(workspace, props.mode, {
-      id: editor.connectionId ?? undefined,
-      provider: editor.provider,
-      endpoint: editor.endpoint,
-      protocol: editorProtocolForCapabilities(
+    const catalogProvider = catalogProviderForEditor(editor.provider, editor.customProtocol);
+    const protocol = editor.provider === "custom" && editor.customProtocol
+      ? editor.customProtocol
+      : editorProtocolForCapabilities(
         editor.provider,
         capabilities,
         providerChanged ? undefined : existing?.protocol
-      ),
+      );
+    const levels = editor.customThinkingLevels
+      .split(",")
+      .map((level) => level.trim())
+      .filter((level): level is ThinkingLevel => THINKING_LEVELS.includes(level as ThinkingLevel));
+    const customThinkingConfig: ModelThinkingConfigDto | null = editor.provider === "custom" && editor.customThinkingEnabled
+      ? {
+          switchable: editor.customThinkingSwitchable,
+          defaultEnabled: editor.customThinkingSwitchable
+            ? editor.customThinkingDefaultEnabled
+            : true,
+          levels: [...levels],
+          defaultLevel: defaultThinkingLevel(levels)
+        }
+      : null;
+    const inputModalities = editor.provider === "custom"
+      ? (editor.customImageInput ? ["text", "image"] as const : ["text"] as const)
+      : undefined;
+    const result = upsertModelConnection(workspace, props.mode, {
+      id: editor.connectionId ?? undefined,
+      provider: catalogProvider,
+      endpoint: editor.endpoint,
+      protocol,
+      region: editor.customProtocol === "bedrock-converse" ? editor.region : undefined,
       apiKey: editor.apiKey || undefined,
       apiKeyMasked: providerChanged ? undefined : existing?.apiKeyMasked,
       models: resolved.models.map((model) => model.name),
@@ -356,7 +412,12 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
         ...(model.presetId ? { presetId: model.presetId } : {}),
         model: model.name,
         capability: model.capabilities[0]!,
-        capabilities: model.capabilities
+        capabilities: model.capabilities,
+        ...(editor.provider === "custom" ? {
+          custom: true,
+          thinking: customThinkingConfig,
+          inputModalities: [...inputModalities!]
+        } : {})
       })),
       modelCapabilities: Object.fromEntries(
         resolved.models.map((model) => [model.name, model.capabilities[0]!])
@@ -370,7 +431,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       connection.id === editor.connectionId
       || (
         editor.connectionId === null
-        && protocolFromConnection(connection.provider) === editor.provider
+        && connection.provider === catalogProvider
         && connection.endpoint === editor.endpoint.trim().replace(/\/+$/, "")
         && resolved.models.every((model) => connection.modelEntries.some((entry) => (
           entry.model === model.name
@@ -555,7 +616,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       ? space.connections.find((connection) => connection.id === editor.connectionId)
       : undefined;
     const providerChanged = Boolean(
-      existing && protocolFromConnection(existing.provider) !== editor.provider
+      existing && editorIdentity(existing) !== editor.provider
     );
     if (!editor.apiKey.trim() && (!existing?.apiKeyMasked || providerChanged)) {
       setEditorTest({ status: "error", message: t("settings.modelWorkspace.testKeyRequired") });
@@ -565,9 +626,11 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
     try {
       const result = props.configClient
         ? await props.configClient.testModelConfig({
-          provider: fromProtocol(editor.provider),
+          provider: catalogProviderForEditor(editor.provider, editor.customProtocol),
           endpointId: existing?.endpointId ?? editor.connectionId ?? "connection-test-new",
-          protocol: editorProtocolForCapabilities(
+          protocol: editor.provider === "custom" && editor.customProtocol
+            ? editor.customProtocol
+            : editorProtocolForCapabilities(
             editor.provider,
             selectedModel.capabilities,
             providerChanged ? undefined : existing?.protocol
@@ -576,7 +639,8 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
             model: selectedModel.name,
             apiKey: editor.apiKey,
             apiKeyMasked: providerChanged ? "" : existing?.apiKeyMasked ?? "",
-            configured: true
+            configured: true,
+            ...(editor.customProtocol === "bedrock-converse" && editor.region ? { region: editor.region } : {})
           }, testCapability(selectedModel.capabilities[0]!), testSecretTarget(selectedModel.capabilities[0]!))
         : await simulateConnectionTest();
       setEditorTest({
@@ -608,7 +672,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
 
   const memorySummaryOptions = memorySummaryCandidates.map((candidate) => candidateOption(
     candidate.id,
-    candidate.source === "platform" ? t("settings.modelWorkspace.platformName") : connectionProtocolLabel(candidate.provider, t),
+    candidate.source === "platform" ? t("settings.modelWorkspace.platformName") : connectionProtocolLabel(candidate.provider, t, identityForCandidate(workspace, candidate)),
     candidate.source === "platform" ? platformModelName(candidate.capability, t) : candidate.model,
     candidate.source === "platform" ? t("settings.modelWorkspace.platformModels") : t("settings.modelWorkspace.byokConnections"),
     candidate.source,
@@ -616,7 +680,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
   ));
   const memoryEvolutionOptions = memoryEvolutionCandidates.map((candidate) => candidateOption(
     candidate.id,
-    candidate.source === "platform" ? t("settings.modelWorkspace.platformName") : connectionProtocolLabel(candidate.provider, t),
+    candidate.source === "platform" ? t("settings.modelWorkspace.platformName") : connectionProtocolLabel(candidate.provider, t, identityForCandidate(workspace, candidate)),
     candidate.source === "platform" ? platformModelName(candidate.capability, t) : candidate.model,
     candidate.source === "platform" ? t("settings.modelWorkspace.platformModels") : t("settings.modelWorkspace.byokConnections"),
     candidate.source,
@@ -626,7 +690,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
     .filter((candidate) => candidate.source === "byok")
     .map((candidate) => candidateOption(
       candidate.id,
-      connectionProtocolLabel(candidate.provider, t),
+      connectionProtocolLabel(candidate.provider, t, identityForCandidate(workspace, candidate)),
       candidate.model,
       t("settings.modelWorkspace.byokConnections"),
       candidate.source,
@@ -647,7 +711,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
     candidate.id,
     candidate.source === "platform"
       ? t("settings.modelWorkspace.platformName")
-      : connectionProtocolLabel(candidate.provider, t),
+      : connectionProtocolLabel(candidate.provider, t, identityForCandidate(workspace, candidate)),
     candidate.source === "platform" ? platformModelName(candidate.capability, t) : candidate.model,
     candidate.source === "platform"
       ? t("settings.modelWorkspace.platformModels")
@@ -659,7 +723,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
     candidate.id,
     candidate.source === "platform"
       ? t("settings.modelWorkspace.platformName")
-      : connectionProtocolLabel(candidate.provider, t),
+      : connectionProtocolLabel(candidate.provider, t, identityForCandidate(workspace, candidate)),
     candidate.source === "platform" ? platformModelName(candidate.capability, t) : candidate.model,
     candidate.source === "platform"
       ? t("settings.modelWorkspace.platformModels")
@@ -684,7 +748,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
     ? space.connections.find((connection) => connection.id === editor.connectionId)
     : undefined;
   const editorOriginalProvider = editorExistingConnection
-    ? protocolFromConnection(editorExistingConnection.provider)
+    ? editorIdentity(editorExistingConnection)
     : null;
   const editorProviderChanged = Boolean(
     editor && editorOriginalProvider && editor.provider !== editorOriginalProvider
@@ -798,7 +862,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
                   <div className="min-w-0">
                     <h4 className="flex min-w-0 items-center gap-2 text-sm font-semibold text-text-ink/80">
                       <ModelProviderLogo provider={connection.provider} size={16} />
-                      <span className="truncate">{connectionProtocolLabel(connection.provider, t)}</span>
+                      <span className="truncate">{connectionProtocolLabel(connection.provider, t, editorIdentity(connection))}</span>
                     </h4>
                   </div>
                   <div className="flex shrink-0 items-center gap-1">
@@ -833,7 +897,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
                       />
                 ) : (
                   <p className="mt-2 text-xs text-text-ink/45">
-                    {connectionProtocolLabel(connection.provider, t)} · {t("settings.modelWorkspace.modelCount", {
+                    {connectionProtocolLabel(connection.provider, t, editorIdentity(connection))} · {t("settings.modelWorkspace.modelCount", {
                       count: connection.models.length
                     })}
                   </p>
@@ -934,7 +998,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
                           <span className="shrink-0 text-[10px] text-text-ink/40">
                             {candidate.source === "platform"
                               ? t("settings.modelWorkspace.platformName")
-                              : connectionProtocolLabel(candidate.provider, t)}
+                              : connectionProtocolLabel(candidate.provider, t, identityForCandidate(workspace, candidate))}
                           </span>
                           </button>
                           {selected && (
@@ -1063,6 +1127,8 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
                 provider,
                 endpoint: DEFAULT_ENDPOINTS[provider],
                 apiKey: "",
+                customProtocol: provider === "custom" ? current.customProtocol ?? "openai-chat-completions" : null,
+                region: provider === "custom" ? current.region : "",
                 ...(current.connectionId
                   ? {}
                   : {
@@ -1086,6 +1152,83 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
             className="select-control--subtle model-connection-select"
             labelClassName="model-connection-select__label"
           />
+          {editor.provider === "custom" && (
+            <>
+              <Select
+                label={t("settings.modelWorkspace.customProtocol")}
+                value={editor.customProtocol ?? "openai-chat-completions"}
+                onValueChange={(value) => setEditor((prev) => prev ? { ...prev, customProtocol: value as CustomProtocol } : null)}
+                className="select-control--subtle"
+                options={CUSTOM_PROTOCOL_OPTIONS.map((option) => ({
+                  value: option.value,
+                  label: t(option.labelKey)
+                }))}
+              />
+              {editor.customProtocol === "bedrock-converse" && (
+                <ConfigField
+                  label={t("settings.modelWorkspace.region")}
+                  value={editor.region}
+                  onChange={(region) => setEditor((prev) => prev ? { ...prev, region } : prev)}
+                  placeholder={t("settings.modelWorkspace.regionPlaceholder")}
+                />
+              )}
+              <div className="custom-thinking-config">
+                <label className="custom-thinking-config__label">
+                  <input
+                    type="checkbox"
+                    checked={editor.customThinkingEnabled}
+                    onChange={(event) => setEditor((prev) => prev ? { ...prev, customThinkingEnabled: event.target.checked } : null)}
+                  />
+                  {t("settings.modelWorkspace.customThinkingEnabled")}
+                </label>
+                {editor.customThinkingEnabled && (
+                  <>
+                    <label className="custom-thinking-config__label">
+                      <input
+                        type="checkbox"
+                        checked={editor.customThinkingSwitchable}
+                        onChange={(event) => setEditor((prev) => prev ? { ...prev, customThinkingSwitchable: event.target.checked } : null)}
+                      />
+                      {t("settings.modelWorkspace.customThinkingSwitchable")}
+                    </label>
+                    {editor.customThinkingSwitchable && (
+                      <label className="custom-thinking-config__label">
+                        <input
+                          type="checkbox"
+                          checked={editor.customThinkingDefaultEnabled}
+                          onChange={(event) => setEditor((prev) => prev ? { ...prev, customThinkingDefaultEnabled: event.target.checked } : null)}
+                        />
+                        {t("settings.modelWorkspace.customThinkingDefaultEnabled")}
+                      </label>
+                    )}
+                    <div className="custom-thinking-levels">
+                      <label className="custom-thinking-levels__label">
+                        {t("settings.modelWorkspace.customThinkingLevels")}
+                      </label>
+                      <input
+                        type="text"
+                        placeholder={t("settings.modelWorkspace.customThinkingLevelsPlaceholder")}
+                        value={editor.customThinkingLevels}
+                        onChange={(event) => setEditor((prev) => prev ? { ...prev, customThinkingLevels: event.target.value } : null)}
+                        className="custom-thinking-levels__input"
+                      />
+                      <p className="custom-thinking-levels__hint">
+                        {t("settings.modelWorkspace.customThinkingLevelsHint")}
+                      </p>
+                    </div>
+                  </>
+                )}
+                <label className="custom-thinking-config__label">
+                  <input
+                    type="checkbox"
+                    checked={editor.customImageInput}
+                    onChange={(event) => setEditor((prev) => prev ? { ...prev, customImageInput: event.target.checked } : null)}
+                  />
+                  {t("settings.modelWorkspace.customImageInput")}
+                </label>
+              </div>
+            </>
+          )}
           <ConfigField
             label={t("apiKey.endpoint")}
             value={editor.endpoint}
@@ -1231,7 +1374,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
         open={Boolean(deleteTarget)}
         title={t("settings.modelWorkspace.deleteTitle")}
         message={t("settings.modelWorkspace.deleteConfirm", {
-          provider: deleteTarget ? connectionProtocolLabel(deleteTarget.provider, t) : ""
+          provider: deleteTarget ? connectionProtocolLabel(deleteTarget.provider, t, editorIdentity(deleteTarget)) : ""
         })}
         cancelLabel={t("common.cancel")}
         closeLabel={t("common.close")}
@@ -1449,13 +1592,25 @@ function candidateOption(
 
 function connectionProtocolLabel(
   provider: string,
-  t: ReturnType<typeof useTranslation>["t"]
+  t: ReturnType<typeof useTranslation>["t"],
+  identity?: Protocol
 ): string {
-  const protocol = protocolFromConnection(provider);
+  const protocol = identity ?? protocolFromConnection(provider);
   const option = PROTOCOL_OPTIONS.find((item) => item.value === protocol);
   return option ? t(option.labelKey) : provider;
 }
 
+function identityForCandidate(
+  workspace: ReturnType<typeof createModelWorkspace>,
+  candidate: ModelCandidate
+): Protocol | undefined {
+  if (candidate.source !== "byok" || !candidate.connectionId) return undefined;
+  const connection = workspace.spaces.byok.connections.find((item) => item.id === candidate.connectionId)
+    ?? workspace.spaces.account.connections.find((item) => item.id === candidate.connectionId);
+  if (!connection) return isCustomModelEntry(workspace, candidate) ? "custom" : undefined;
+  return editorIdentity(connection);
+}
+
 export function protocolFromConnection(provider: string): Protocol {
   if (provider === "moonshot" || provider === "kimi") return "moonshot";
   if (provider === "dashscope") return "qwen";
@@ -1466,10 +1621,27 @@ export function protocolFromConnection(provider: string): Protocol {
   return "openai";
 }
 
+export function catalogProviderForEditor(provider: Protocol, customProtocol: CustomProtocol | null): string {
+  if (provider === "custom") {
+    if (customProtocol === "anthropic-messages") return "anthropic";
+    if (customProtocol === "bedrock-converse") return "bedrock";
+    return "openai";
+  }
+  if (provider === "openai_responses") return "openai";
+  return fromProtocol(provider) === "kimi" ? "moonshot" : fromProtocol(provider);
+}
+
+function editorIdentity(connection: ModelConnection): Protocol {
+  if (connection.modelEntries[0]?.custom === true) return "custom";
+  if (connection.protocol === "openai-responses") return "openai_responses";
+  return protocolFromConnection(connection.provider);
+}
+
 function protocolForEditor(provider: Protocol, capability: ModelCapability): ModelEndpointProtocol {
   if (capability === "embedding") return "openai-embeddings";
   if (capability === "asr") return "dashscope-input-audio-chat";
   if (capability === "image") return provider === "qwen" ? "dashscope-multimodal-generation" : "openai-images";
+  if (provider === "openai_responses") return "openai-responses";
   if (provider === "anthropic") return "anthropic-messages";
   if (provider === "gemini") return "gemini-generate-content";
   return "openai-chat-completions";
diff --git a/App/frontend/desktop/src/pages/settings-page.tsx b/App/frontend/desktop/src/pages/settings-page.tsx
index 152fcd5b5..f9bcd51e9 100644
--- a/App/frontend/desktop/src/pages/settings-page.tsx
+++ b/App/frontend/desktop/src/pages/settings-page.tsx
@@ -2858,7 +2858,9 @@ function ProtocolSelect(props: ProtocolSelectProps) {
       value={props.value}
       onValueChange={(value) => props.onChange(value as Protocol)}
       className="select-control--paper"
-      options={PROTOCOL_OPTIONS.map((option) => ({
+      options={PROTOCOL_OPTIONS
+        .filter((option) => option.value !== "openai_responses" && option.value !== "custom")
+        .map((option) => ({
         value: option.value,
         label: t(option.labelKey)
       }))}
diff --git a/App/frontend/desktop/src/pages/tests/home-page.test.tsx b/App/frontend/desktop/src/pages/tests/home-page.test.tsx
index d2393cb6a..152e84858 100644
--- a/App/frontend/desktop/src/pages/tests/home-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/home-page.test.tsx
@@ -5,6 +5,7 @@ import { Window } from "happy-dom";
 import { renderToString } from "react-dom/server";
 import { describe, expect, it, vi } from "vitest";
 import { MemmyAgentMessageRejectedError } from "../../api/memmy-agent-client.js";
+import { createModelWorkspace, type ModelCandidate } from "../../state/model-workspace.js";
 import { AgentRuntimeBridge } from "../../app/agent-runtime-bridge.js";
 import { AppProviders } from "../../app/providers.js";
 import { FOCUSED_AGENT_CHAT_STORAGE_KEY } from "../../app/routes.js";
@@ -41,6 +42,7 @@ import {
   resolveComposerCommandDraft,
   shouldAcceptAgentStatusResult,
   submitAgentComposerMessage,
+  thinkingPayloadForSend,
   updateAgentComposerOverlayHeight,
   updateComposerDraftForScope,
   fileToPendingAttachment,
@@ -191,11 +193,16 @@ describe("HomePage", () => {
     expect(source).toContain("state.agent.committedModelSelectionByScope[modelSelectionScopeKey]");
     expect(source).toContain("allowUnassignedSelected: pendingModelPreset == null && Boolean(committedModelSelection)");
     expect(source).toContain("modelPreset: resolvedConversationModel.candidateId ?? undefined");
+    expect(source).toContain("thinkingPayloadForSend(");
     expect(source).not.toContain("copyScopedModelSelection");
     expect(selectorSource).toContain("agentActions.pendingModelPresetUpdated");
+    expect(selectorSource).toContain("AgentThinkingControl");
+    expect(selectorSource).toContain("resolveThinkingConfigForModel");
     expect(selectorSource).not.toContain("localStorage");
     expect(source).not.toContain('sendMessage({ chatId: state.agent.currentChatId, content: "/model');
     expect(styles).toContain(".agent-model-selector .agent-model-selector__menu");
+    expect(styles).toContain(".agent-model-selector-with-thinking");
+    expect(styles).toContain(".agent-thinking-control");
     expect(styles).toContain("top: calc(100% + 6px)");
     expect(styles).toContain(".agent-model-selector__configure");
     expect(source).not.toContain("modelSwitchNotice");
@@ -209,6 +216,36 @@ describe("HomePage", () => {
     expect(source).not.toContain("agent-conversation-model-error");
   });
 
+  it("组帧时按模型思考表解析开关与默认档位", () => {
+    const workspace = createModelWorkspace(null);
+    const candidate: ModelCandidate = {
+      id: "gpt-54",
+      source: "byok",
+      provider: "openai",
+      model: "gpt-5.4",
+      displayName: "gpt-5.4",
+      connectionId: null,
+      endpointId: "chat",
+      capability: "chat",
+      capabilities: ["agent"],
+      available: true
+    };
+
+    expect(thinkingPayloadForSend(workspace, candidate, undefined)).toEqual({
+      thinkingEnabled: true,
+      thinkingLevel: "medium"
+    });
+    expect(thinkingPayloadForSend(workspace, candidate, { enabled: false })).toEqual({
+      thinkingEnabled: false,
+      thinkingLevel: null
+    });
+    expect(thinkingPayloadForSend(workspace, candidate, { enabled: true, level: "high" })).toEqual({
+      thinkingEnabled: true,
+      thinkingLevel: "high"
+    });
+    expect(thinkingPayloadForSend(workspace, { ...candidate, model: "unlisted-model" }, undefined)).toEqual({});
+  });
+
   it("hides the agent status line after the websocket is connected", () => {
     expect(agentStatusText("connected", "agent_chat", (key, values) => `${key}:${values?.model ?? ""}`)).toBeNull();
     expect(agentStatusText("connecting", null, (key) => key)).toBe("home.agent.connecting");
diff --git a/App/frontend/desktop/src/pages/tests/model-config.test.ts b/App/frontend/desktop/src/pages/tests/model-config.test.ts
index c4f6df998..7df7ea6cd 100644
--- a/App/frontend/desktop/src/pages/tests/model-config.test.ts
+++ b/App/frontend/desktop/src/pages/tests/model-config.test.ts
@@ -30,7 +30,7 @@ import {
 import type { TextModelProviderConfig } from "../../api/config-client.js";
 import { modelProviderLogoUrl } from "../../components/model-provider-logo.js";
 import { canSaveModelConfig, createModelConfigValidationKey, type ModelConfigValidationState } from "../model-config-validation.js";
-import { zhCNMessages } from "../../i18n/messages.js";
+import { zhCNMessages, enUSMessages } from "../../i18n/messages.js";
 
 describe("model config helpers", () => {
   it("严格映射并过滤桌面不支持或没有模型的 Provider", () => {
@@ -530,6 +530,33 @@ describe("model config helpers", () => {
     expect(zhCNMessages["apiKey.provider.xiaomi"]).toBe("小米 MiMo");
   });
 
+  it("OpenAI Completions/Responses 与 Custom 作为文本 Provider 可选且默认值完整", () => {
+    const options = PROTOCOL_OPTIONS.map((option) => option.value);
+    expect(options).toContain("openai");
+    expect(options).toContain("openai_responses");
+    expect(options).toContain("custom");
+    expect(PROTOCOL_OPTIONS.find((option) => option.value === "openai")?.labelKey)
+      .toBe("apiKey.provider.openaiCompletions");
+    expect(IMAGE_PROTOCOL_OPTIONS.find((option) => option.value === "openai")?.labelKey)
+      .toBe("apiKey.provider.openai");
+
+    expect(DEFAULT_ENDPOINTS.openai_responses).toBe("https://api.openai.com/v1");
+    expect(DEFAULT_ENDPOINTS.custom).toBe("");
+    expect(DEFAULT_MODEL_IDS.openai_responses).toBe("gpt-4o");
+    expect(DEFAULT_MODEL_IDS.custom).toBe("");
+    expect(toProtocol("openai_responses")).toBe("openai_responses");
+    expect(fromProtocol("openai_responses")).toBe("openai_responses");
+    expect(toProtocol("custom")).toBe("custom");
+    expect(fromProtocol("custom")).toBe("custom");
+    expect(zhCNMessages["apiKey.provider.openaiCompletions"]).toBe("OpenAI Completions");
+    expect(zhCNMessages["apiKey.provider.openaiResponses"]).toBe("OpenAI Responses");
+    expect(zhCNMessages["apiKey.provider.custom"]).toBe("Custom");
+  });
+
+  it("中英文字典键集合一致", () => {
+    expect(Object.keys(enUSMessages).sort()).toEqual(Object.keys(zhCNMessages).sort());
+  });
+
   it("为阶跃星辰和小米 MiMo 解析出品牌 logo", () => {
     expect(modelProviderLogoUrl("stepfun")).toMatch(/^data:image\/svg\+xml/);
     expect(modelProviderLogoUrl("xiaomi")).toMatch(/^data:image\/svg\+xml/);
diff --git a/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx
index d201bb161..12f735264 100644
--- a/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx
@@ -157,7 +157,7 @@ describe("ModelWorkspaceSection BYOK connection deletion", () => {
       .toEqual([
         "Memmy Platform 本地 Embedding",
         "Memmy Platform 云端 Embedding",
-        "OpenAI 兼容 · text-embedding-3-small"
+        "OpenAI Completions · text-embedding-3-small"
       ]);
   });
 
diff --git a/App/frontend/desktop/src/pages/tests/model-workspace-task-picker-layout.test.tsx b/App/frontend/desktop/src/pages/tests/model-workspace-task-picker-layout.test.tsx
index 0fc9fda7f..5739e1517 100644
--- a/App/frontend/desktop/src/pages/tests/model-workspace-task-picker-layout.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/model-workspace-task-picker-layout.test.tsx
@@ -38,7 +38,7 @@ describe("model workspace task picker layout", () => {
 
     const row = [...container.querySelectorAll<HTMLElement>(".task-model-picker__option")]
       .find((option) => option.textContent?.includes("gpt-5.4")
-        && option.textContent.includes("OpenAI 兼容")
+        && option.textContent.includes("OpenAI Completions")
         && option.textContent.includes("默认"));
     if (!row) throw new Error("Missing default custom-model row");
     const choiceButton = row.querySelector<HTMLButtonElement>('button[role="checkbox"]');
diff --git a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
index efd7be2da..191982184 100644
--- a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
@@ -28,6 +28,7 @@ import {
 import { formatMessage, zhCNMessages } from "../../i18n/messages.js";
 import {
   availableConnectionProtocols,
+  catalogProviderForEditor,
   editorProtocolForCapabilities,
   modelCapabilitiesForKind,
   normalizeEditorCapabilities,
@@ -75,6 +76,7 @@ describe("多 BYOK endpoint 入口", () => {
         endpointId: "openai-chat",
         endpoint: "https://api.openai.com/v1",
         protocol: "openai-chat-completions",
+        region: "",
         apiKeyMasked: "••••1234",
         models: ["gpt-4o"],
         modelEntries: [{ presetId: "preset-openai", model: "gpt-4o", capability: "chat", capabilities: ["agent"] }],
@@ -89,6 +91,7 @@ describe("多 BYOK endpoint 入口", () => {
         endpointId: "anthropic-chat",
         endpoint: "https://api.anthropic.com",
         protocol: "anthropic-messages",
+        region: "",
         apiKeyMasked: "••••5678",
         models: ["claude-sonnet-4"],
         modelEntries: [{ presetId: "preset-anthropic", model: "claude-sonnet-4", capability: "chat", capabilities: ["agent"] }],
@@ -100,11 +103,24 @@ describe("多 BYOK endpoint 入口", () => {
     ]);
 
     expect(available).toContain("openai");
+    expect(available).toContain("openai_responses");
+    expect(available).toContain("custom");
     expect(available).toContain("anthropic");
     expect(available[0]).toBe("openai");
   });
 });
 
+describe("Custom 与 OpenAI Responses 的 catalog provider 推导", () => {
+  it("Custom 按底层协议落到 openai/anthropic/bedrock，而不是 custom", () => {
+    expect(catalogProviderForEditor("custom", "openai-chat-completions")).toBe("openai");
+    expect(catalogProviderForEditor("custom", "openai-responses")).toBe("openai");
+    expect(catalogProviderForEditor("custom", "anthropic-messages")).toBe("anthropic");
+    expect(catalogProviderForEditor("custom", "bedrock-converse")).toBe("bedrock");
+    expect(catalogProviderForEditor("openai_responses", null)).toBe("openai");
+    expect(catalogProviderForEditor("moonshot", null)).toBe("moonshot");
+  });
+});
+
 describe("自定义模型能力选择", () => {
   it("四种单选类型映射为对应的底层能力", () => {
     expect(modelCapabilitiesForKind("text")).toEqual(["chat", "memorySummary", "memoryEvolution"]);
@@ -196,7 +212,8 @@ describe("自定义模型能力选择", () => {
     expect(source).toContain('className="select-control--subtle model-capability-select"');
     expect(source.match(/t\("settings\.modelWorkspace\.modelCapability"\)/g)).toHaveLength(1);
     expect(source).toContain("normalizeEditorCapabilities(entry.capabilities.map(fromCatalogCapability))");
-    expect(source).not.toContain('type="checkbox"');
+    expect(source).toContain("checked={editor.customThinkingEnabled}");
+    expect(source).toContain("checked={editor.customImageInput}");
     expect(source).not.toContain('t("settings.modelWorkspace.textRoles")');
     expect(source).not.toContain('t("settings.modelWorkspace.capability.agent")');
   });
diff --git a/App/frontend/desktop/src/state/agent-chat-slice.ts b/App/frontend/desktop/src/state/agent-chat-slice.ts
index 2666ef9be..f41ac0a70 100644
--- a/App/frontend/desktop/src/state/agent-chat-slice.ts
+++ b/App/frontend/desktop/src/state/agent-chat-slice.ts
@@ -42,6 +42,13 @@ import {
   type AgentToolProgressEvent
 } from "./agent-tool-traces.js";
 
+export interface AgentThinkingState {
+  enabled?: boolean;
+  level?: string;
+}
+
+export const NEW_TASK_MODEL_SCOPE_KEY = "draft-new-task";
+
 export type AgentConnectionStatus = "idle" | "bootstrapping" | "connecting" | "connected" | "reconnecting" | "error";
 export type AgentOperationSurface = "chat" | "sidebar";
 export type AgentOperationErrorSource = "sessions" | "sidebar" | "history" | "new-chat" | "send" | "gateway-command" | "recovery" | "queue";
@@ -191,6 +198,7 @@ export interface AgentState {
     chatId: string | null;
     presetId: string | null;
   }>;
+  thinkingStateByScope: Record<string, AgentThinkingState>;
   chatViewVisible: boolean;
   currentChatId: string | null;
   currentSessionKey: string | null;
@@ -264,6 +272,8 @@ export type AgentAction =
   | { type: "agent/pendingModelPresetCleared"; scopeKey: string }
   | { type: "agent/modelSelectionRequestStarted"; scopeKey: string; chatId: string | null; clientRequestId: string; presetId: string | null }
   | { type: "agent/modelSelectionRequestCancelled"; clientRequestId: string }
+  | { type: "agent/thinkingToggled"; scopeKey: string; enabled: boolean }
+  | { type: "agent/thinkingLevelChanged"; scopeKey: string; level: string }
   | { type: "agent/connectionConnecting" }
   | { type: "agent/connectionFailed"; message: string }
   | { type: "agent/connectionDisposed" }
@@ -353,6 +363,7 @@ export const initialAgentState: AgentState = {
   committedModelSelectionByScope: {},
   pendingPresetByScope: {},
   pendingModelCommitByRequestId: {},
+  thinkingStateByScope: {},
   chatViewVisible: false,
   currentChatId: null,
   currentSessionKey: null,
@@ -458,6 +469,28 @@ export function agentReducer(state: AgentState, action: AgentAction): AgentState
           action.clientRequestId
         )
       };
+    case "agent/thinkingToggled":
+      return {
+        ...state,
+        thinkingStateByScope: {
+          ...state.thinkingStateByScope,
+          [action.scopeKey]: {
+            ...state.thinkingStateByScope[action.scopeKey],
+            enabled: action.enabled
+          }
+        }
+      };
+    case "agent/thinkingLevelChanged":
+      return {
+        ...state,
+        thinkingStateByScope: {
+          ...state.thinkingStateByScope,
+          [action.scopeKey]: {
+            ...state.thinkingStateByScope[action.scopeKey],
+            level: action.level
+          }
+        }
+      };
     case "agent/connectionConnecting":
       return { ...state, connectionStatus: "connecting", connectionError: null };
     case "agent/connectionFailed":
@@ -1562,9 +1595,17 @@ function completeSessionsLoad(state: AgentState, sessions: MemmyAgentSessionSumm
 
   const canonicalChatIds = new Set(sessions.map((session) => sessionKeyToChatId(session.key)));
   const committedModelSelectionByScope = { ...state.committedModelSelectionByScope };
+  const thinkingStateByScope = { ...state.thinkingStateByScope };
   for (const session of sessions) {
     const chatId = sessionKeyToChatId(session.key);
     committedModelSelectionByScope[chatId] = session.model_selection ?? null;
+    const restored: AgentThinkingState = {
+      ...(typeof session.thinking_enabled === "boolean" ? { enabled: session.thinking_enabled } : {}),
+      ...(typeof session.thinking_level === "string" ? { level: session.thinking_level } : {})
+    };
+    if (Object.keys(restored).length) {
+      thinkingStateByScope[chatId] = { ...thinkingStateByScope[chatId], ...restored };
+    }
   }
   const optimisticTasksByChatId = pruneOptimisticTasks(state.optimisticTasksByChatId, canonicalChatIds);
   const queuedMessagesByChatId = pruneChatMap(
@@ -1599,6 +1640,10 @@ function completeSessionsLoad(state: AgentState, sessions: MemmyAgentSessionSumm
     ...state,
     sessions,
     committedModelSelectionByScope,
+    thinkingStateByScope: pruneChatMap(
+      thinkingStateByScope,
+      new Set([...canonicalChatIds, NEW_TASK_MODEL_SCOPE_KEY])
+    ),
     optimisticTasksByChatId,
     queuedMessagesByChatId,
     queueRevisionByChatId,
diff --git a/App/frontend/desktop/src/state/app-actions.ts b/App/frontend/desktop/src/state/app-actions.ts
index 3de3f5dcd..4d63d178c 100644
--- a/App/frontend/desktop/src/state/app-actions.ts
+++ b/App/frontend/desktop/src/state/app-actions.ts
@@ -262,6 +262,14 @@ export const agentActions = {
     return { type: "agent/pendingModelPresetCleared", scopeKey };
   },
 
+  thinkingToggled(scopeKey: string, enabled: boolean): AppAction {
+    return { type: "agent/thinkingToggled", scopeKey, enabled };
+  },
+
+  thinkingLevelChanged(scopeKey: string, level: string): AppAction {
+    return { type: "agent/thinkingLevelChanged", scopeKey, level };
+  },
+
   modelSelectionRequestStarted(
     scopeKey: string,
     chatId: string | null,
diff --git a/App/frontend/desktop/src/state/model-workspace.ts b/App/frontend/desktop/src/state/model-workspace.ts
index 6b39d8a12..a3558bc77 100644
--- a/App/frontend/desktop/src/state/model-workspace.ts
+++ b/App/frontend/desktop/src/state/model-workspace.ts
@@ -1,6 +1,7 @@
 /** Pure view-model helpers for the canonical model catalog returned by the local API. */
 import {
   BUILTIN_LOCAL_EMBEDDING_ASSIGNMENT_ID,
+  getModelThinkingConfig,
   type CatalogEndpointInput,
   type CatalogProviderId,
   type ModelAssignment,
@@ -8,6 +9,9 @@ import {
   type ModelConfigInput,
   type ModelConfigView,
   type ModelEndpointProtocol,
+  type ModelInputModality,
+  type ModelThinkingConfig,
+  type ModelThinkingConfigDto,
   type TextModelItemView
 } from "@memmy/local-api-contracts";
 import { CLIENT_PRESET_ID_PREFIX, type ModelProviderConfig } from "../api/config-client.js";
@@ -31,6 +35,7 @@ export interface ModelConnection {
   endpointId: string;
   endpoint: string;
   protocol: ModelEndpointProtocol;
+  region: string;
   apiKeyMasked: string;
   models: string[];
   modelEntries: ModelConnectionModel[];
@@ -45,6 +50,9 @@ export interface ModelConnectionModel {
   model: string;
   capability: ModelCapability;
   capabilities: CatalogCapability[];
+  thinking?: ModelThinkingConfigDto;
+  custom?: boolean;
+  inputModalities?: ModelInputModality[];
 }
 
 export interface ModelWorkspaceSpace {
@@ -78,6 +86,7 @@ export interface ModelConnectionInput {
   endpointId?: string;
   endpoint: string;
   protocol?: ModelEndpointProtocol;
+  region?: string;
   apiKey?: string;
   apiKeyMasked?: string;
   models: string[];
@@ -86,6 +95,9 @@ export interface ModelConnectionInput {
     model: string;
     capability: ModelCapability;
     capabilities?: ModelCapability[];
+    thinking?: ModelThinkingConfigDto | null;
+    custom?: boolean;
+    inputModalities?: ModelInputModality[];
   }>;
   modelCapabilities?: Record<string, ModelCapability>;
 }
@@ -183,7 +195,10 @@ export function modelConfigInputFromView(view: ModelConfigView): ModelConfigInpu
         model: model.model,
         source: model.source,
         ...(model.ownerAccountId ? { ownerAccountId: model.ownerAccountId } : {}),
-        capabilities: [...model.capabilities]
+        capabilities: [...model.capabilities],
+        ...(model.thinking ? { thinking: model.thinking } : {}),
+        ...(model.custom ? { custom: true } : {}),
+        ...(model.inputModalities ? { inputModalities: [...model.inputModalities] } : {})
       }))
     })),
     modelAssignments: cloneAssignments(view.modelAssignments)
@@ -379,12 +394,23 @@ export function upsertModelConnection(
 ): ModelWorkspaceMutationResult {
   const providerId = normalizeProvider(input.provider);
   const endpoint = input.endpoint.trim().replace(/\/+$/, "");
-  const entries: Array<{ presetId?: string; model: string; capabilities: ModelCapability[]; capabilitiesExplicit: boolean }> = input.modelEntries?.length
+  const entries: Array<{
+    presetId?: string;
+    model: string;
+    capabilities: ModelCapability[];
+    capabilitiesExplicit: boolean;
+    thinking?: ModelThinkingConfigDto | null;
+    custom?: boolean;
+    inputModalities?: ModelInputModality[];
+  }> = input.modelEntries?.length
     ? input.modelEntries.map((entry) => ({
         ...(entry.presetId ? { presetId: entry.presetId } : {}),
         model: entry.model.trim(),
         capabilities: unique(entry.capabilities?.length ? entry.capabilities : [entry.capability]),
         capabilitiesExplicit: Boolean(entry.capabilities?.length),
+        ...(entry.thinking !== undefined ? { thinking: entry.thinking } : {}),
+        ...(entry.custom ? { custom: true } : {}),
+        ...(entry.inputModalities ? { inputModalities: entry.inputModalities } : {})
       })).filter((entry) => Boolean(entry.model))
     : input.models.map((model) => ({
         model: model.trim(),
@@ -453,7 +479,8 @@ export function upsertModelConnection(
     protocol,
     hasApiKey: Boolean(input.apiKey || input.apiKeyMasked),
     apiKeyMasked: input.apiKey ? maskApiKey(input.apiKey) : input.apiKeyMasked ?? "",
-    apiKey: input.apiKey ?? ""
+    apiKey: input.apiKey ?? "",
+    ...(input.region ? { region: input.region } : {})
   });
   provider.models.push(...entries.map((entry, index) => {
     const model = entry.model;
@@ -476,7 +503,10 @@ export function upsertModelConnection(
       model,
       source: "byok" as const,
       capabilities,
-      available: true
+      available: true,
+      ...(entry.thinking ? { thinking: entry.thinking } : {}),
+      ...(entry.custom ? { custom: true } : {}),
+      ...(entry.inputModalities ? { inputModalities: [...entry.inputModalities] } : {})
     };
   }));
 
@@ -658,13 +688,17 @@ function createSpace(catalog: ModelConfigView, mode: ModelWorkspaceMode): ModelW
       endpointId: endpoint.endpointId,
       endpoint: endpoint.apiBase,
       protocol: endpoint.protocol,
+      region: endpoint.region ?? "",
       apiKeyMasked: endpoint.apiKeyMasked || provider.apiKeyMasked,
       models: models.map((model) => model.model),
       modelEntries: models.map((model) => ({
         presetId: model.presetId,
         model: model.model,
         capability: fromCapabilities(model.capabilities),
-        capabilities: [...model.capabilities]
+        capabilities: [...model.capabilities],
+        ...(model.thinking ? { thinking: model.thinking } : {}),
+        ...(model.custom ? { custom: true } : {}),
+        ...(model.inputModalities ? { inputModalities: [...model.inputModalities] } : {})
       })),
       modelCapabilities: Object.fromEntries(models.map((model) => [model.model, fromCapabilities(model.capabilities)])),
       presetIds: Object.fromEntries(models.map((model) => [model.model, model.presetId])),
@@ -708,7 +742,8 @@ function endpointInput(endpoint: ModelConfigView["providers"][number]["endpoints
     endpointId: endpoint.endpointId,
     apiBase: endpoint.apiBase,
     protocol: endpoint.protocol,
-    ...(endpoint.apiKey ? { apiKey: endpoint.apiKey } : {})
+    ...(endpoint.apiKey ? { apiKey: endpoint.apiKey } : {}),
+    ...(endpoint.region ? { region: endpoint.region } : {})
   };
 }
 
@@ -741,9 +776,16 @@ function cloneAssignment<T extends Omit<ModelAssignment, "ownerAccountId"> | Mod
 
 function normalizeProvider(provider: string): CatalogProviderId | null {
   const normalized = provider.trim().toLowerCase();
-  const aliases: Record<string, CatalogProviderId> = { qwen: "dashscope", kimi: "moonshot", baidu: "qianfan", doubao: "volcengine", xiaomi: "xiaomi_mimo" };
+  const aliases: Record<string, CatalogProviderId> = {
+    qwen: "dashscope",
+    kimi: "moonshot",
+    baidu: "qianfan",
+    doubao: "volcengine",
+    xiaomi: "xiaomi_mimo",
+    openai_responses: "openai"
+  };
   const candidate = aliases[normalized] ?? normalized;
-  return ["openai", "anthropic", "gemini", "deepseek", "zhipu", "dashscope", "moonshot", "minimax", "qianfan", "volcengine", "stepfun", "xiaomi_mimo", "memmy_account"].includes(candidate)
+  return ["openai", "anthropic", "gemini", "deepseek", "zhipu", "dashscope", "moonshot", "minimax", "qianfan", "volcengine", "stepfun", "xiaomi_mimo", "memmy_account", "bedrock"].includes(candidate)
     ? candidate as CatalogProviderId
     : null;
 }
@@ -755,6 +797,7 @@ function protocolFor(provider: CatalogProviderId, capability: ModelCapability):
   if (provider === "anthropic") return "anthropic-messages";
   if (provider === "gemini") return "gemini-generate-content";
   if (provider === "memmy_account") return "memmy-account";
+  if (provider === "bedrock") return "bedrock-converse";
   return "openai-chat-completions";
 }
 
@@ -906,3 +949,37 @@ function newClientPresetId(): string {
   const suffix = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`;
   return `${CLIENT_PRESET_ID_PREFIX}${suffix}`;
 }
+
+function modelEntryFor(
+  workspace: ModelWorkspace,
+  candidate: ModelCandidate | null | undefined
+) {
+  if (!candidate || candidate.source !== "byok") return undefined;
+  const connection = workspace.spaces.byok.connections
+    .find((item) => item.id === candidate.connectionId);
+  return connection?.modelEntries.find((item) => item.model === candidate.model);
+}
+
+export function isCustomModelEntry(
+  workspace: ModelWorkspace,
+  candidate: ModelCandidate | null | undefined
+): boolean {
+  return modelEntryFor(workspace, candidate)?.custom === true;
+}
+
+export function customThinkingConfigFor(
+  workspace: ModelWorkspace,
+  candidate: ModelCandidate | null | undefined
+): ModelThinkingConfig | null {
+  return modelEntryFor(workspace, candidate)?.thinking ?? null;
+}
+
+export function resolveThinkingConfigForModel(
+  workspace: ModelWorkspace,
+  candidate: ModelCandidate | null | undefined
+): ModelThinkingConfig | null {
+  if (isCustomModelEntry(workspace, candidate)) {
+    return customThinkingConfigFor(workspace, candidate);
+  }
+  return getModelThinkingConfig(candidate?.model);
+}
diff --git a/App/frontend/desktop/src/state/tests/agent-chat-slice.test.ts b/App/frontend/desktop/src/state/tests/agent-chat-slice.test.ts
index 65bbe4eb3..ac3b43210 100644
--- a/App/frontend/desktop/src/state/tests/agent-chat-slice.test.ts
+++ b/App/frontend/desktop/src/state/tests/agent-chat-slice.test.ts
@@ -7,6 +7,7 @@ import {
   buildAgentTasks,
   defaultAgentSidebarState,
   initialAgentState,
+  NEW_TASK_MODEL_SCOPE_KEY,
   selectedModelPresetForScope,
   type AgentState,
   updateSidebarStateForTask
@@ -5628,6 +5629,42 @@ describe("agent chat slice", () => {
     expect(state.activeTurnIdByChatId["chat-1"]).toBe("turn-new");
     expect(state.isSending).toBe(true);
   });
+
+  it("思考开关与档位按 session scope 写入，并在 sessions 加载时恢复", () => {
+    let state = agentReducer(initialAgentState, {
+      type: "agent/thinkingToggled",
+      scopeKey: "chat-1",
+      enabled: false
+    });
+    state = agentReducer(state, {
+      type: "agent/thinkingLevelChanged",
+      scopeKey: "chat-1",
+      level: "low"
+    });
+    state = agentReducer(state, {
+      type: "agent/thinkingToggled",
+      scopeKey: NEW_TASK_MODEL_SCOPE_KEY,
+      enabled: true
+    });
+
+    expect(state.thinkingStateByScope["chat-1"]).toEqual({ enabled: false, level: "low" });
+    expect(state.thinkingStateByScope[NEW_TASK_MODEL_SCOPE_KEY]).toEqual({ enabled: true });
+
+    state = agentReducer(state, {
+      type: "agent/sessionsLoaded",
+      sessions: [
+        {
+          ...sessions[0]!,
+          thinking_enabled: true,
+          thinking_level: "high"
+        }
+      ]
+    });
+
+    expect(state.thinkingStateByScope["chat-1"]).toEqual({ enabled: true, level: "high" });
+    expect(state.thinkingStateByScope[NEW_TASK_MODEL_SCOPE_KEY]).toEqual({ enabled: true });
+    expect(state.thinkingStateByScope["chat-2"]).toBeUndefined();
+  });
 });
 
 function recoveryStateWithPendingMessage(content: string): AgentState {
diff --git a/App/frontend/desktop/src/state/tests/model-workspace.test.ts b/App/frontend/desktop/src/state/tests/model-workspace.test.ts
index 0e455923e..37a93ada8 100644
--- a/App/frontend/desktop/src/state/tests/model-workspace.test.ts
+++ b/App/frontend/desktop/src/state/tests/model-workspace.test.ts
@@ -29,7 +29,9 @@ import {
   setModelAssignment,
   setTaskModelCandidates,
   upsertByokPreset,
-  upsertModelConnection
+  upsertModelConnection,
+  isCustomModelEntry,
+  resolveThinkingConfigForModel
 } from "../model-workspace.js";
 
 const fixtureRoots: string[] = [];
@@ -1085,4 +1087,57 @@ describe("canonical model workspace adapter", () => {
     expect(serialized).not.toContain("maxTokens");
     expect(serialized).not.toContain("dailyTokenLimit");
   });
+
+  it("Custom 连接保存思考配置、图片声明与 region，重开后仍在", async () => {
+    const file = catalogFixture();
+    const empty = await readModelConfigCatalog(file);
+    const created = upsertModelConnection(createModelWorkspace(empty), "byok", {
+      provider: "bedrock",
+      endpoint: "https://bedrock-runtime.us-west-2.amazonaws.com",
+      protocol: "bedrock-converse",
+      region: "us-west-2",
+      apiKey: "sk-bedrock",
+      models: ["anthropic.claude-sonnet-5"],
+      modelEntries: [{
+        model: "anthropic.claude-sonnet-5",
+        capability: "chat",
+        capabilities: ["chat", "memorySummary", "memoryEvolution"],
+        custom: true,
+        thinking: {
+          switchable: true,
+          defaultEnabled: true,
+          levels: ["low", "medium", "high"],
+          defaultLevel: "medium"
+        },
+        inputModalities: ["text", "image"]
+      }]
+    });
+    expect(created.error).toBeNull();
+
+    const saved = await persistModelCatalogMutation(modelConfigInput(created.workspace), {
+      read: () => readModelConfigCatalog(file),
+      write: (input) => writeModelConfigCatalog(file, input)
+    });
+    const reloaded = createModelWorkspace(saved);
+    const connection = reloaded.spaces.byok.connections.find((item) => item.provider === "bedrock")!;
+    const entry = connection.modelEntries[0]!;
+    const candidate = getTaskModelCandidates(reloaded, "byok").find((item) => item.model === "anthropic.claude-sonnet-5")!;
+
+    expect(connection.protocol).toBe("bedrock-converse");
+    expect(connection.region).toBe("us-west-2");
+    expect(entry.custom).toBe(true);
+    expect(entry.thinking).toEqual({
+      switchable: true,
+      defaultEnabled: true,
+      levels: ["low", "medium", "high"],
+      defaultLevel: "medium"
+    });
+    expect(entry.inputModalities).toEqual(["text", "image"]);
+    expect(isCustomModelEntry(reloaded, candidate)).toBe(true);
+    expect(resolveThinkingConfigForModel(reloaded, candidate)).toEqual(entry.thinking);
+    expect(saved.providers.find((provider) => provider.provider === "bedrock")?.models[0]).toMatchObject({
+      custom: true,
+      inputModalities: ["text", "image"]
+    });
+  });
 });
diff --git a/App/frontend/desktop/src/styles.css b/App/frontend/desktop/src/styles.css
index 375ca9c0f..6ec3764ec 100644
--- a/App/frontend/desktop/src/styles.css
+++ b/App/frontend/desktop/src/styles.css
@@ -861,6 +861,172 @@ body.memmy-window-fullscreen {
   transition: background var(--duration-fast), color var(--duration-fast);
 }
 
+.agent-model-selector-with-thinking {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.agent-thinking-control {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.thinking-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  height: 32px;
+  padding: 0 8px;
+  border: 0;
+  border-radius: 9px;
+  background: transparent;
+  color: color-mix(in srgb, var(--color-text-ink) 48%, transparent);
+  cursor: pointer;
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.thinking-toggle:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--color-canvas-oat) 64%, transparent);
+  color: color-mix(in srgb, var(--color-text-ink) 78%, transparent);
+}
+
+.thinking-toggle:disabled {
+  cursor: not-allowed;
+  opacity: 0.4;
+}
+
+.thinking-toggle--on {
+  color: var(--color-action-sky);
+}
+
+.thinking-toggle__switch {
+  position: relative;
+  width: 28px;
+  height: 16px;
+  background: color-mix(in srgb, var(--color-text-ink) 18%, transparent);
+  border-radius: 999px;
+}
+
+.thinking-toggle__switch--on {
+  background: var(--color-action-sky);
+}
+
+.thinking-toggle__switch-thumb {
+  position: absolute;
+  top: 2px;
+  left: 2px;
+  width: 12px;
+  height: 12px;
+  background: white;
+  border-radius: 50%;
+  transition: transform var(--duration-fast);
+}
+
+.thinking-toggle__switch--on .thinking-toggle__switch-thumb {
+  transform: translateX(12px);
+}
+
+.thinking-level-trigger-container {
+  position: relative;
+}
+
+.thinking-level-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  height: 32px;
+  padding: 0 8px;
+  border: 0;
+  border-radius: 9px;
+  background: transparent;
+  color: color-mix(in srgb, var(--color-text-ink) 48%, transparent);
+  cursor: pointer;
+  font-size: 13px;
+}
+
+.thinking-level-trigger:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--color-canvas-oat) 64%, transparent);
+  color: color-mix(in srgb, var(--color-text-ink) 78%, transparent);
+}
+
+.thinking-level-picker {
+  position: absolute;
+  right: 0;
+  bottom: calc(100% + 6px);
+  z-index: 130;
+  min-width: 160px;
+  background: var(--color-background-paper, #fff);
+  border: 1px solid color-mix(in srgb, var(--color-text-ink) 12%, transparent);
+  border-radius: 8px;
+  box-shadow: 0 8px 24px color-mix(in srgb, var(--color-text-ink) 12%, transparent);
+}
+
+.thinking-level-picker__header {
+  padding: 8px 12px;
+  font-size: 12px;
+  font-weight: 600;
+  color: color-mix(in srgb, var(--color-text-ink) 55%, transparent);
+  border-bottom: 1px solid color-mix(in srgb, var(--color-text-ink) 10%, transparent);
+}
+
+.thinking-level-option {
+  display: block;
+  width: 100%;
+  padding: 8px 12px;
+  border: 0;
+  background: none;
+  text-align: left;
+  cursor: pointer;
+  font-size: 13px;
+}
+
+.thinking-level-option:hover {
+  background: color-mix(in srgb, var(--color-canvas-oat) 64%, transparent);
+}
+
+.thinking-level-option--selected {
+  color: var(--color-action-sky);
+  font-weight: 500;
+}
+
+.custom-thinking-config {
+  display: grid;
+  gap: 10px;
+  margin-top: 4px;
+  padding: 12px;
+  border: 1px solid color-mix(in srgb, var(--color-text-ink) 12%, transparent);
+  border-radius: 8px;
+}
+
+.custom-thinking-config__label {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 13px;
+}
+
+.custom-thinking-levels {
+  display: grid;
+  gap: 6px;
+}
+
+.custom-thinking-levels__input {
+  width: 100%;
+  padding: 8px 12px;
+  border: 1px solid color-mix(in srgb, var(--color-text-ink) 12%, transparent);
+  border-radius: 6px;
+  font-size: 13px;
+}
+
+.custom-thinking-levels__hint {
+  margin: 0;
+  font-size: 12px;
+  color: color-mix(in srgb, var(--color-text-ink) 55%, transparent);
+}
+
 .agent-model-selector {
   position: relative;
   z-index: 50;
diff --git a/App/memmy-agent/src/config/schema.ts b/App/memmy-agent/src/config/schema.ts
index 9820534b8..8e85c5f18 100644
--- a/App/memmy-agent/src/config/schema.ts
+++ b/App/memmy-agent/src/config/schema.ts
@@ -97,7 +97,8 @@ export type ModelEndpointProtocol =
   | "dashscope-input-audio-chat"
   | "openai-images"
   | "dashscope-multimodal-generation"
-  | "memmy-account";
+  | "memmy-account"
+  | "bedrock-converse";
 
 const MODEL_CAPABILITIES = ["agent", "memory_summary", "memory_evolution", "embedding", "asr", "image_generation"] as const;
 const TEXT_GENERATION_CAPABILITIES: ReadonlySet<ModelCapability> = new Set([
@@ -106,7 +107,7 @@ const TEXT_GENERATION_CAPABILITIES: ReadonlySet<ModelCapability> = new Set([
 const ENDPOINT_PROTOCOLS = [
   "openai-chat-completions", "openai-responses", "anthropic-messages", "gemini-generate-content",
   "openai-embeddings", "dashscope-input-audio-chat", "openai-images",
-  "dashscope-multimodal-generation", "memmy-account",
+  "dashscope-multimodal-generation", "memmy-account", "bedrock-converse",
 ] as const;
 
 export class Base {
@@ -234,6 +235,7 @@ export class ModelPresetConfig extends Base {
   contextWindowTokens = DEFAULT_CONTEXT_WINDOW_TOKENS;
   temperature = 0.7;
   reasoningEffort: string | null = null;
+  inputModalities: readonly string[] | null = null;
 
   constructor(init: Dict) {
     super(init);
@@ -262,6 +264,9 @@ export class ModelPresetConfig extends Base {
     );
     this.temperature = pick(init, ["temperature"], 0.7);
     this.reasoningEffort = pick(init, ["reasoningEffort"], null);
+    this.inputModalities = Array.isArray(init.inputModalities)
+      ? Object.freeze([...init.inputModalities.filter((item: unknown) => typeof item === "string")])
+      : null;
     if (this.source === "account" && !optionalString(this.ownerAccountId)) {
       throw new ValueError("account modelPreset ownerAccountId is required");
     }
@@ -282,6 +287,7 @@ export class ModelPresetConfig extends Base {
     return omitUndefined({
       ...this,
       ownerAccountId: this.ownerAccountId ?? undefined,
+      inputModalities: this.inputModalities ?? undefined,
     });
   }
 }
@@ -591,6 +597,7 @@ export class ProviderConfig extends Base {
   private chatEndpoint(): ModelEndpointConfig | null {
     return Object.values(this.endpoints).find((endpoint) => [
       "openai-chat-completions", "openai-responses", "anthropic-messages", "gemini-generate-content", "memmy-account",
+      "bedrock-converse",
     ].includes(endpoint.protocol)) ?? null;
   }
 
@@ -612,6 +619,8 @@ export class ModelEndpointConfig extends Base {
   apiKey: string | null;
   extraHeaders: Dict<string> | null;
   extraBody: Dict | null;
+  region: string | null;
+  profile: string | null;
 
   constructor(init: Dict = {}) {
     for (const legacy of ["api_key", "api_base", "api_type", "extra_headers", "extra_body"]) {
@@ -625,6 +634,8 @@ export class ModelEndpointConfig extends Base {
     this.apiKey = pick(init, ["apiKey"], null);
     this.extraHeaders = pick(init, ["extraHeaders"], null);
     this.extraBody = pick(init, ["extraBody"], null);
+    this.region = pick(init, ["region"], null);
+    this.profile = pick(init, ["profile"], null);
   }
 
   override toObject(): Dict {
@@ -633,6 +644,8 @@ export class ModelEndpointConfig extends Base {
       apiKey: this.apiKey ?? undefined,
       extraHeaders: this.extraHeaders ?? undefined,
       extraBody: this.extraBody ?? undefined,
+      region: this.region ?? undefined,
+      profile: this.profile ?? undefined,
     });
   }
 }
@@ -1298,6 +1311,7 @@ export class Config extends Base {
   private validateModelCatalog(): void {
     const textProtocols = new Set<ModelEndpointProtocol>([
       "openai-chat-completions", "openai-responses", "anthropic-messages", "gemini-generate-content", "memmy-account",
+      "bedrock-converse",
     ]);
     const protocolsByCapability: Readonly<Record<ModelCapability, ReadonlySet<ModelEndpointProtocol>>> = {
       agent: textProtocols,
diff --git a/App/memmy-agent/src/core/agent-runtime/loop.ts b/App/memmy-agent/src/core/agent-runtime/loop.ts
index 9b379fc5d..7863308c6 100644
--- a/App/memmy-agent/src/core/agent-runtime/loop.ts
+++ b/App/memmy-agent/src/core/agent-runtime/loop.ts
@@ -25,6 +25,7 @@ import {
   type ModelSelectionInput,
   type ResolvedModelSelection,
 } from "../../providers/model-catalog.js";
+import { getModelThinkingConfig } from "@memmy/local-api-contracts";
 import type { ProviderErrorCategory } from "../../providers/provider-error-classifier.js";
 
 type UserFacingModelErrorCategory = ProviderErrorCategory | "model_failed";
@@ -694,6 +695,27 @@ export class SessionWorkspaceError extends Error {
   }
 }
 
+function thinkingFieldsFromMetadata(metadata: Record<string, unknown> | null | undefined): Record<string, unknown> {
+  return {
+    ...(typeof metadata?.thinking_enabled === "boolean" ? { thinking_enabled: metadata.thinking_enabled } : {}),
+    ...(typeof metadata?.thinking_level === "string" ? { thinking_level: metadata.thinking_level } : {}),
+  };
+}
+
+export function reasoningEffortFromTurnMetadata(
+  metadata: Record<string, unknown> | null | undefined,
+  model: string | null | undefined,
+): string | undefined {
+  if (typeof metadata?.thinking_enabled !== "boolean") return undefined;
+  const config = getModelThinkingConfig(model);
+  const enabled = config && !config.switchable ? true : metadata.thinking_enabled;
+  if (!enabled) return "none";
+  if (typeof metadata.thinking_level === "string" && metadata.thinking_level.trim()) {
+    return metadata.thinking_level;
+  }
+  return "medium";
+}
+
 export class AgentLoop {
   bus: MessageBus;
   config: Config;
@@ -3554,7 +3576,9 @@ export class AgentLoop {
         maxIterationsFinalPrompt: renderTemplate("agent/max-iterations-final-response.md", { strip: true }),
         maxTokens: activeProvider?.generation?.maxTokens ?? this.config.agents.defaults.maxTokens,
         temperature: activeProvider?.generation?.temperature ?? this.config.agents.defaults.temperature,
-        reasoningEffort: activeProvider?.generation?.reasoningEffort ?? this.config.agents.defaults.reasoningEffort,
+        reasoningEffort: reasoningEffortFromTurnMetadata(metadata, activeModel)
+          ?? activeProvider?.generation?.reasoningEffort
+          ?? this.config.agents.defaults.reasoningEffort,
         maxToolResultChars: this.maxToolResultChars,
         toolResultMaxCharsByName: SESSION_TOOL_RESULT_MAX_CHARS_BY_NAME,
         workspace: sessionWorkspace,
@@ -3714,6 +3738,7 @@ export class AgentLoop {
             model_provider: modelSelection.provider,
             model: modelSelection.model,
             model_selection: modelSelectionWire(modelSelection),
+            ...thinkingFieldsFromMetadata(msg.metadata),
           }
         : { ...(msg.metadata ?? {}) },
       sessionKey: ctx.sessionKey,
@@ -3738,6 +3763,7 @@ export class AgentLoop {
     }
     ctx.session.metadata.modelPreset = modelSelection.preset;
     ctx.session.metadata.modelSelection = persistedModelSelection(modelSelection);
+    Object.assign(ctx.session.metadata, thinkingFieldsFromMetadata(msg.metadata));
     const projectedBinding = this.guiTranscriptMirror?.prepareSession(
       msg,
       ctx.session,
@@ -4306,6 +4332,7 @@ export class AgentLoop {
             model_provider: modelSelection.provider,
             model: modelSelection.model,
             model_selection: modelSelectionWire(modelSelection),
+            ...thinkingFieldsFromMetadata(msg.metadata),
           }
         : { ...(msg.metadata ?? {}) },
       sessionKey: key,
@@ -4319,6 +4346,7 @@ export class AgentLoop {
     let session = existingSession ?? await this.getOrCreateSession(key);
     session.metadata.modelPreset = modelSelection.preset;
     session.metadata.modelSelection = persistedModelSelection(modelSelection);
+    Object.assign(session.metadata, thinkingFieldsFromMetadata(msg.metadata));
     const sessionBinding = this.resolveSessionWorkspace(
       msg,
       session,
diff --git a/App/memmy-agent/src/core/agent-runtime/runner.ts b/App/memmy-agent/src/core/agent-runtime/runner.ts
index 7a28486c0..2233ded12 100644
--- a/App/memmy-agent/src/core/agent-runtime/runner.ts
+++ b/App/memmy-agent/src/core/agent-runtime/runner.ts
@@ -3,9 +3,9 @@ import path from "node:path";
 import { LLMProvider, LLMResponse, ToolCallRequest } from "../../providers/base.js";
 import {
   coversInputModalities,
-  getModelInputModalities,
   hasDeclaredInputModalities,
   requiredInputModalities,
+  resolveModelInputModalities,
 } from "../../providers/model-input-capabilities.js";
 import type { ActualModelContext } from "@memmy/local-api-contracts";
 import { CONTEXT_SAFETY_BUFFER_TOKENS } from "../../token-budget.js";
@@ -671,15 +671,18 @@ export class AgentRunner {
     const messagesForModel = this.prepareImageMessages(messages, imageTextState);
     const model = spec.actualModelContext?.model ?? spec.model;
     const required = requiredInputModalities(messagesForModel);
-    const supported = getModelInputModalities(model);
+    const declared = spec.actualModelContext?.inputModalities;
+    const supported = resolveModelInputModalities(model, declared);
     const missing = required.filter((modality) => !supported.includes(modality));
     const canUseAccountFallback = missing.length === 1
       && missing[0] === "image"
       && this.canRunAccountImageTextFallback(spec, null);
     // A BYOK model ID we have never reviewed may well be multimodal, and BYOK has no
     // image2text fallback to fall back on, so let the user's own endpoint answer rather
-    // than refusing the request here.
+    // than refusing the request here. Custom models always declare modalities, so a
+    // declaration is authoritative and must not defer.
     const deferToProvider = spec.actualModelContext?.source === "byok"
+      && !declared
       && !hasDeclaredInputModalities(model);
 
     let initialResponse: LLMResponse | null = null;
diff --git a/App/memmy-agent/src/core/session/manager.ts b/App/memmy-agent/src/core/session/manager.ts
index cbcc32dd1..715790d7c 100644
--- a/App/memmy-agent/src/core/session/manager.ts
+++ b/App/memmy-agent/src/core/session/manager.ts
@@ -106,6 +106,12 @@ function sessionSummary(session: Session, filePath: string, options: { repairPre
       ? session.metadata.modelPreset
       : null,
     model_selection: modelSelectionWire(session.metadata?.modelSelection),
+    thinking_enabled: typeof session.metadata?.thinking_enabled === "boolean"
+      ? session.metadata.thinking_enabled
+      : null,
+    thinking_level: typeof session.metadata?.thinking_level === "string"
+      ? session.metadata.thinking_level
+      : null,
   };
   if (session.metadata?.[WEBUI_SESSION_METADATA_KEY] === true) {
     const binding = readWebuiSessionBinding(session);
diff --git a/App/memmy-agent/src/integrations/channels/websocket.ts b/App/memmy-agent/src/integrations/channels/websocket.ts
index efc4236f7..142c3a79b 100644
--- a/App/memmy-agent/src/integrations/channels/websocket.ts
+++ b/App/memmy-agent/src/integrations/channels/websocket.ts
@@ -227,6 +227,36 @@ type SessionDeletionServices = {
 };
 export type WebuiLanguage = "zh-CN" | "en-US";
 
+export type WebuiMessageDigestInput = {
+  chatId: string;
+  content: string;
+  mediaPaths: string[];
+  language: WebuiLanguage | null;
+  target: WebuiSessionTarget | null;
+  modelPreset: string | null | undefined;
+  queueSurface: "chat_composer" | null;
+  turnAdmission: "queue" | "steer";
+  expectedTurnId: string | null;
+  thinkingEnabled?: boolean;
+  thinkingLevel?: string | null;
+};
+
+export function computeWebuiMessageDigest(input: WebuiMessageDigestInput): string {
+  return crypto.createHash("sha256").update(JSON.stringify({
+    chat_id: input.chatId,
+    content: input.content,
+    media_paths: input.mediaPaths,
+    language: input.language,
+    target: input.target,
+    model_preset: input.modelPreset,
+    queue_surface: input.queueSurface,
+    turn_admission: input.turnAdmission,
+    expected_turn_id: input.expectedTurnId,
+    thinking_enabled: input.thinkingEnabled ?? null,
+    thinking_level: input.thinkingLevel ?? null,
+  })).digest("hex");
+}
+
 const CHAT_ID_RE = /^[A-Za-z0-9_:-]{1,64}$/;
 const API_KEY_RE = /^[A-Za-z0-9_:.-]{1,128}$/;
 const WEBUI_LANGUAGE_VALUES = new Set<WebuiLanguage>(["zh-CN", "en-US"]);
@@ -912,38 +942,8 @@ export class WebSocketChannel extends BaseChannel {
     return null;
   }
 
-  private webuiMessageDigest({
-    chatId,
-    content,
-    mediaPaths,
-    language,
-    target,
-    modelPreset,
-    queueSurface,
-    turnAdmission,
-    expectedTurnId,
-  }: {
-    chatId: string;
-    content: string;
-    mediaPaths: string[];
-    language: WebuiLanguage | null;
-    target: WebuiSessionTarget | null;
-    modelPreset: string | null | undefined;
-    queueSurface: "chat_composer" | null;
-    turnAdmission: "queue" | "steer";
-    expectedTurnId: string | null;
-  }): string {
-    return crypto.createHash("sha256").update(JSON.stringify({
-      chat_id: chatId,
-      content,
-      media_paths: mediaPaths,
-      language,
-      target,
-      model_preset: modelPreset,
-      queue_surface: queueSurface,
-      turn_admission: turnAdmission,
-      expected_turn_id: expectedTurnId,
-    })).digest("hex");
+  private webuiMessageDigest(input: WebuiMessageDigestInput): string {
+    return computeWebuiMessageDigest(input);
   }
 
   private resolveMessageModel(
@@ -3341,6 +3341,8 @@ export class WebSocketChannel extends BaseChannel {
           queueSurface,
           turnAdmission,
           expectedTurnId,
+          thinkingEnabled: typeof envelope.thinking_enabled === "boolean" ? envelope.thinking_enabled : undefined,
+          thinkingLevel: typeof envelope.thinking_level === "string" ? envelope.thinking_level : undefined,
         })
       : null;
     if (existing && clientRequestId) {
@@ -3449,6 +3451,8 @@ export class WebSocketChannel extends BaseChannel {
       model: modelSelection.model,
       model_selection: modelSelectionWire(modelSelection),
     };
+    if (typeof envelope.thinking_enabled === "boolean") metadata.thinking_enabled = envelope.thinking_enabled;
+    if (typeof envelope.thinking_level === "string") metadata.thinking_level = envelope.thinking_level;
     if (clientRequestId && digest) {
       metadata.client_request_id = clientRequestId;
       metadata.webui_request_digest = digest;
diff --git a/App/memmy-agent/src/providers/factory.ts b/App/memmy-agent/src/providers/factory.ts
index 6946c32a2..85518bc39 100644
--- a/App/memmy-agent/src/providers/factory.ts
+++ b/App/memmy-agent/src/providers/factory.ts
@@ -98,6 +98,7 @@ function makeProviderCore(
   const model = opts.model ?? resolved.model;
   const providerName = config.getProviderName(model, { preset: resolved });
   const providerConfig = config.getProvider(model, { preset: resolved });
+  const endpoint = exactEndpoint(config, providerConfig, resolved);
   const spec = providerName ? findByName(providerName) : null;
   const backend = spec?.backend ?? "openai_compat";
   const init = providerInit(config, providerConfig, spec, model, resolved);
@@ -118,7 +119,11 @@ function makeProviderCore(
   else if (backend === "azure_openai") provider = new AzureOpenAIProvider(init);
   else if (backend === "github_copilot") provider = new GitHubCopilotProvider(init);
   else if (backend === "anthropic") provider = new AnthropicProvider(init);
-  else if (backend === "bedrock") provider = new BedrockProvider({ ...init, region: (providerConfig as any)?.region ?? null, profile: (providerConfig as any)?.profile ?? null });
+  else if (backend === "bedrock") provider = new BedrockProvider({
+    ...init,
+    region: endpoint?.region ?? (providerConfig as { region?: string | null })?.region ?? null,
+    profile: endpoint?.profile ?? (providerConfig as { profile?: string | null })?.profile ?? null,
+  });
   else provider = new OpenAICompatProvider(init);
 
   provider.generation = resolved.toGenerationSettings();
diff --git a/App/memmy-agent/src/providers/model-catalog.ts b/App/memmy-agent/src/providers/model-catalog.ts
index b34427479..82116cad2 100644
--- a/App/memmy-agent/src/providers/model-catalog.ts
+++ b/App/memmy-agent/src/providers/model-catalog.ts
@@ -165,6 +165,7 @@ export function persistedModelSelection(
     ownerAccountId: selection.ownerAccountId ?? null,
     capability: selection.capability,
     capabilities: Object.freeze([...selection.capabilities]),
+    ...(selection.inputModalities ? { inputModalities: Object.freeze([...selection.inputModalities]) } : {}),
   });
 }
 
@@ -244,6 +245,7 @@ function runtimeCatalog(config: Config): RuntimeModelCatalog {
             apiKey: endpoint.apiKey,
             extraHeaders: endpoint.extraHeaders,
             extraBody: endpoint.extraBody,
+            region: endpoint.region,
           }),
         ])),
       })];
@@ -257,6 +259,7 @@ function runtimeCatalog(config: Config): RuntimeModelCatalog {
         source: preset.source,
         ownerAccountId: preset.ownerAccountId,
         capabilities: [...preset.capabilities],
+        inputModalities: preset.inputModalities ?? undefined,
       }),
     ])),
     modelAssignments: {
diff --git a/App/memmy-agent/src/providers/model-input-capabilities.ts b/App/memmy-agent/src/providers/model-input-capabilities.ts
index 83e49587a..37075add1 100644
--- a/App/memmy-agent/src/providers/model-input-capabilities.ts
+++ b/App/memmy-agent/src/providers/model-input-capabilities.ts
@@ -367,6 +367,14 @@ export function hasDeclaredInputModalities(model: string | null | undefined): bo
     && Object.prototype.hasOwnProperty.call(MODEL_INPUT_CAPABILITIES, model);
 }
 
+/** 声明优先于静态表：有声明用声明，无声明查表。 */
+export function resolveModelInputModalities(
+  model: string | null | undefined,
+  declared: readonly ModelInputModality[] | null | undefined,
+): readonly ModelInputModality[] {
+  return declared ?? getModelInputModalities(model);
+}
+
 export function requiredInputModalities(
   messages: readonly Record<string, any>[],
 ): readonly ModelInputModality[] {
diff --git a/App/memmy-agent/tests/core/agent-runtime/runner-byok-image-input.test.ts b/App/memmy-agent/tests/core/agent-runtime/runner-byok-image-input.test.ts
index 7ca833d47..5880c2820 100644
--- a/App/memmy-agent/tests/core/agent-runtime/runner-byok-image-input.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/runner-byok-image-input.test.ts
@@ -118,4 +118,34 @@ describe("BYOK custom model image input", () => {
     expect(provider.calls).toHaveLength(0);
     expect(result.finalContent).toBe("Current model does not support image input.");
   });
+
+  it("blocks images when a Custom model declares text-only input", async () => {
+    const provider = new ByokProvider();
+
+    const result = await new AgentRunner(provider).run(new AgentRunSpec({
+      initialMessages: [imageMessage()],
+      provider,
+      model: "Qwen3-27B",
+      actualModelContext: { ...byokContext("Qwen3-27B"), inputModalities: ["text"] },
+    }));
+
+    expect(provider.calls).toHaveLength(0);
+    expect(result.finalContent).toBe("Current model does not support image input.");
+    expect(result.response.errorCategory).toBe("image_input_unsupported");
+  });
+
+  it("allows images when a Custom declaration includes image even if the catalog is text-only", async () => {
+    const provider = new ByokProvider();
+
+    const result = await new AgentRunner(provider).run(new AgentRunSpec({
+      initialMessages: [imageMessage()],
+      provider,
+      model: "deepseek-v4-pro",
+      actualModelContext: { ...byokContext("deepseek-v4-pro"), inputModalities: ["text", "image"] },
+    }));
+
+    expect(result.finalContent).toBe("described the image");
+    expect(provider.calls).toHaveLength(1);
+    expect(JSON.stringify(provider.calls[0].messages)).toContain('"type":"image_url"');
+  });
 });
diff --git a/App/memmy-agent/tests/core/agent-runtime/thinking-effort.test.ts b/App/memmy-agent/tests/core/agent-runtime/thinking-effort.test.ts
new file mode 100644
index 000000000..1052542be
--- /dev/null
+++ b/App/memmy-agent/tests/core/agent-runtime/thinking-effort.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { reasoningEffortFromTurnMetadata } from "../../../src/core/agent-runtime/loop.js";
+
+describe("reasoningEffortFromTurnMetadata", () => {
+  it("maps disabled thinking to none and missing level to medium", () => {
+    expect(reasoningEffortFromTurnMetadata({ thinking_enabled: false }, "gpt-5.4")).toBe("none");
+    expect(reasoningEffortFromTurnMetadata({ thinking_enabled: true }, "gpt-5.4")).toBe("medium");
+    expect(reasoningEffortFromTurnMetadata({
+      thinking_enabled: true,
+      thinking_level: "high",
+    }, "gpt-5.4")).toBe("high");
+    expect(reasoningEffortFromTurnMetadata({}, "gpt-5.4")).toBeUndefined();
+  });
+
+  it("keeps always-on table models enabled even if the frame asked to disable", () => {
+    expect(reasoningEffortFromTurnMetadata({
+      thinking_enabled: false,
+      thinking_level: "low",
+    }, "claude-fable-5")).toBe("low");
+  });
+});
diff --git a/App/memmy-agent/tests/integrations/channels/webui-message-digest.test.ts b/App/memmy-agent/tests/integrations/channels/webui-message-digest.test.ts
new file mode 100644
index 000000000..8dcd3a0d6
--- /dev/null
+++ b/App/memmy-agent/tests/integrations/channels/webui-message-digest.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { computeWebuiMessageDigest } from "../../../src/integrations/channels/websocket.js";
+
+const base = {
+  chatId: "chat-1",
+  content: "hello",
+  mediaPaths: [] as string[],
+  language: null,
+  target: null,
+  modelPreset: "fast",
+  queueSurface: "chat_composer" as const,
+  turnAdmission: "queue" as const,
+  expectedTurnId: null,
+};
+
+describe("webui message digest", () => {
+  it("changes when thinking fields differ for the same text", () => {
+    const none = computeWebuiMessageDigest({
+      ...base,
+      thinkingEnabled: false,
+    });
+    const medium = computeWebuiMessageDigest({
+      ...base,
+      thinkingEnabled: true,
+      thinkingLevel: "medium",
+    });
+    const high = computeWebuiMessageDigest({
+      ...base,
+      thinkingEnabled: true,
+      thinkingLevel: "high",
+    });
+
+    expect(none).not.toBe(medium);
+    expect(medium).not.toBe(high);
+    expect(computeWebuiMessageDigest({
+      ...base,
+      thinkingEnabled: true,
+      thinkingLevel: "medium",
+    })).toBe(medium);
+  });
+});
diff --git a/App/memmy-agent/tests/providers/bedrock-provider.test.ts b/App/memmy-agent/tests/providers/bedrock-provider.test.ts
index 6771a6b0e..c35e2c91b 100644
--- a/App/memmy-agent/tests/providers/bedrock-provider.test.ts
+++ b/App/memmy-agent/tests/providers/bedrock-provider.test.ts
@@ -36,6 +36,41 @@ describe("Bedrock provider", () => {
     expect(findByName("bedrock")?.backend).toBe("bedrock");
   });
 
+  it("lifts endpoint region and profile into the Bedrock provider", () => {
+    const provider = makeProvider(
+      new Config({
+        agents: { defaults: { modelPreset: "custom-bedrock" } },
+        providers: {
+          bedrock: {
+            region: "us-east-1",
+            profile: "legacy",
+            endpoints: {
+              chat: {
+                apiBase: "https://bedrock-runtime.us-west-2.amazonaws.com",
+                protocol: "bedrock-converse",
+                region: "us-west-2",
+                profile: "work",
+              },
+            },
+          },
+        },
+        modelPresets: {
+          "custom-bedrock": {
+            endpoint: "chat",
+            model: "anthropic.claude-3-5-sonnet",
+            provider: "bedrock",
+            source: "byok",
+            capabilities: ["agent"],
+          },
+        },
+      }),
+    ) as BedrockProvider;
+
+    expect(provider).toBeInstanceOf(BedrockProvider);
+    expect(provider.region).toBe("us-west-2");
+    expect(provider.profile).toBe("work");
+  });
+
   it("maps configured AWS profiles to SDK credential providers", async () => {
     const provider = new BedrockProvider({ region: "us-east-1", profile: "dev" });
     const client = await provider.makeClient();
diff --git a/App/memmy-agent/tests/providers/model-input-capabilities.test.ts b/App/memmy-agent/tests/providers/model-input-capabilities.test.ts
index 072e99ed7..063c12926 100644
--- a/App/memmy-agent/tests/providers/model-input-capabilities.test.ts
+++ b/App/memmy-agent/tests/providers/model-input-capabilities.test.ts
@@ -7,6 +7,7 @@ import {
   MODEL_INPUT_CAPABILITIES,
   MODEL_INPUT_CAPABILITIES_REVIEWED_AT,
   requiredInputModalities,
+  resolveModelInputModalities,
   type ModelInputModality,
 } from "../../src/providers/model-input-capabilities.js";
 
@@ -82,4 +83,11 @@ describe("model input capabilities", () => {
     expect(coversInputModalities(["text", "image"], imageRequired)).toBe(true);
     expect(coversInputModalities(["text"], imageRequired)).toBe(false);
   });
+
+  it("prefers an explicit modality declaration over the static catalog", () => {
+    expect(resolveModelInputModalities("deepseek-v4-pro", ["text", "image"])).toEqual(["text", "image"]);
+    expect(resolveModelInputModalities("gpt-5.6", ["text"])).toEqual(["text"]);
+    expect(resolveModelInputModalities("Qwen3-27B", undefined)).toEqual(["text"]);
+    expect(resolveModelInputModalities("gpt-5.6", null)).toEqual(["text", "image"]);
+  });
 });

From 35c53cb25a3b638b8fc032a848c14d2adadddc8b Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Tue, 29 Sep 2026 15:57:56 +0800
Subject: [PATCH 03/85] Let memory summary and evolution call Bedrock Converse
 and OpenAI Responses.

Settings can save those protocols for both memory roles, and the memory runtime now sends the matching request instead of rejecting the assignment or falling through to chat completions.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../src/model-catalog-resolver.ts             |   1 +
 .../tests/model-catalog-resolver.test.ts      |  11 +-
 .../memmy-config/model-config-catalog.ts      |  10 +-
 .../tests/model-config-catalog.test.ts        |  44 ++++-
 Memory/src/config/index.ts                    |  15 +-
 Memory/src/contracts/index.ts                 |   3 +-
 .../src/contracts/model-catalog-resolver.ts   |  10 +-
 Memory/src/model/llm.ts                       |  58 +++++++
 Memory/tests/llm-protocol-adapters.test.ts    | 155 ++++++++++++++++++
 9 files changed, 288 insertions(+), 19 deletions(-)
 create mode 100644 Memory/tests/llm-protocol-adapters.test.ts

diff --git a/App/backend/local-api-contracts/src/model-catalog-resolver.ts b/App/backend/local-api-contracts/src/model-catalog-resolver.ts
index b813c3ace..af108ff8c 100644
--- a/App/backend/local-api-contracts/src/model-catalog-resolver.ts
+++ b/App/backend/local-api-contracts/src/model-catalog-resolver.ts
@@ -348,6 +348,7 @@ function protocolSupportsCapability(
     }
     if (capability === "memory_summary" || capability === "memory_evolution") {
         return protocol === "openai-chat-completions"
+            || protocol === "openai-responses"
             || protocol === "anthropic-messages"
             || protocol === "gemini-generate-content"
             || protocol === "bedrock-converse";
diff --git a/App/backend/local-api-contracts/tests/model-catalog-resolver.test.ts b/App/backend/local-api-contracts/tests/model-catalog-resolver.test.ts
index 09ea02778..2a4dc0c13 100644
--- a/App/backend/local-api-contracts/tests/model-catalog-resolver.test.ts
+++ b/App/backend/local-api-contracts/tests/model-catalog-resolver.test.ts
@@ -216,17 +216,22 @@ describe("resolveAssignedModel", () => {
     })).toEqual({ ok: false, code: "model_selection_unavailable" });
   });
 
-  it("rejects Responses presets for Memory capabilities until a Responses adapter exists", () => {
+  it("resolves Responses presets for memory capabilities", () => {
     const current = catalog() as any;
     current.providers.dashscope.endpoints.asr.protocol = "openai-responses";
     current.modelPresets["byok-asr"].capabilities = ["memory_summary"];
     current.modelAssignments.byok = { memorySummary: "byok-asr" };
 
-    expect(resolveAssignedModel({
+    const resolved = resolveAssignedModel({
       catalog: current,
       mode: "byok",
       capability: "memory_summary"
-    })).toEqual({ ok: false, code: "model_selection_unavailable" });
+    });
+
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok) return;
+    expect(resolved.context.protocol).toBe("openai-responses");
+    expect(resolved.context.capability).toBe("memory_summary");
   });
 
   it("resolves bedrock-converse and declared input modalities", () => {
diff --git a/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts b/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
index 7f6d2dae3..0baa81d1f 100644
--- a/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
+++ b/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
@@ -28,8 +28,8 @@ type ConfigRecord = Record<string, unknown>;
 
 const CAPABILITY_PROTOCOLS: Readonly<Record<ModelCapability, ReadonlySet<ModelEndpointProtocol>>> = {
   agent: new Set(["openai-chat-completions", "openai-responses", "anthropic-messages", "gemini-generate-content", "memmy-account", "bedrock-converse"]),
-  memory_summary: new Set(["openai-chat-completions", "anthropic-messages", "gemini-generate-content", "memmy-account", "bedrock-converse"]),
-  memory_evolution: new Set(["openai-chat-completions", "anthropic-messages", "gemini-generate-content", "memmy-account", "bedrock-converse"]),
+  memory_summary: new Set(["openai-chat-completions", "openai-responses", "anthropic-messages", "gemini-generate-content", "memmy-account", "bedrock-converse"]),
+  memory_evolution: new Set(["openai-chat-completions", "openai-responses", "anthropic-messages", "gemini-generate-content", "memmy-account", "bedrock-converse"]),
   embedding: new Set(["openai-embeddings", "memmy-account"]),
   asr: new Set(["dashscope-input-audio-chat", "memmy-account"]),
   image_generation: new Set(["openai-images", "dashscope-multimodal-generation", "memmy-account"])
@@ -309,7 +309,7 @@ function memoryConnection(config: ConfigRecord, presetId: string): ConfigRecord
   const extraHeaders = { ...record(provider.extraHeaders), ...record(endpoint.extraHeaders) };
   const extraBody = { ...record(provider.extraBody), ...record(endpoint.extraBody) };
   return {
-    provider: memoryProvider(providerId),
+    provider: memoryProvider(providerId, stringValue(endpoint.protocol)),
     sourceProvider: providerId,
     endpoint: apiBase,
     model,
@@ -319,7 +319,9 @@ function memoryConnection(config: ConfigRecord, presetId: string): ConfigRecord
   };
 }
 
-function memoryProvider(providerId: string): string {
+function memoryProvider(providerId: string, protocol: string | undefined): string {
+  if (protocol === "bedrock-converse") return "bedrock";
+  if (protocol === "openai-responses") return "openai_responses";
   if (providerId === "anthropic") return "anthropic";
   if (providerId === "gemini") return "gemini";
   return "openai_compatible";
diff --git a/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts b/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
index 4515c5ab6..1ed55ca8a 100644
--- a/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
+++ b/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
@@ -516,13 +516,43 @@ describe("model config catalog", () => {
     wrongProtocol.providers[0]!.models[0]!.capabilities = ["embedding"];
     await expect(writeModelConfigCatalog(file, wrongProtocol)).rejects.toThrow(/does not support capability embedding/);
 
-    const unsupportedMemoryResponses = openAiInput(revision);
-    unsupportedMemoryResponses.providers[0]!.endpoints[0]!.protocol = "openai-responses";
-    unsupportedMemoryResponses.providers[0]!.models[0]!.capabilities = ["memory_summary"];
-    await expect(writeModelConfigCatalog(file, unsupportedMemoryResponses))
-      .rejects.toThrow(/does not support capability memory_summary/);
-
-    const duplicateModel = openAiInput(revision);
+    const responsesMemory = openAiInput(revision);
+    responsesMemory.providers[0]!.endpoints[0]!.protocol = "openai-responses";
+    responsesMemory.providers[0]!.models[0]!.capabilities = ["agent", "memory_summary", "memory_evolution"];
+    const savedResponses = await writeModelConfigCatalog(file, responsesMemory);
+    const responsesPresetId = savedResponses.providers[0]!.models[0]!.presetId!;
+    const assignedResponses = openAiInput(savedResponses.configRevision, responsesPresetId);
+    assignedResponses.providers[0]!.endpoints[0]!.protocol = "openai-responses";
+    assignedResponses.providers[0]!.models[0]!.capabilities = ["agent", "memory_summary", "memory_evolution"];
+    assignedResponses.modelAssignments.byok.memoryEvolution = responsesPresetId;
+    await writeModelConfigCatalog(file, assignedResponses);
+    expect((YAML.parse(readFileSync(file, "utf8")) as any).memmyMemory.evolution.provider).toBe("openai_responses");
+
+    const bedrockMemory = openAiInput((await readModelConfigCatalog(file)).configRevision);
+    bedrockMemory.providers = [{
+      provider: "bedrock",
+      endpoints: [{
+        endpointId: "chat",
+        apiBase: "https://bedrock-runtime.us-west-2.amazonaws.com",
+        protocol: "bedrock-converse",
+        region: "us-west-2"
+      }],
+      models: [{
+        endpointId: "chat",
+        model: "anthropic.claude-sonnet-5",
+        source: "byok",
+        capabilities: ["agent", "memory_summary", "memory_evolution"]
+      }]
+    }];
+    const savedBedrock = await writeModelConfigCatalog(file, bedrockMemory);
+    const bedrockPresetId = savedBedrock.providers[0]!.models[0]!.presetId!;
+    bedrockMemory.configRevision = savedBedrock.configRevision;
+    bedrockMemory.providers[0]!.models[0]!.presetId = bedrockPresetId;
+    bedrockMemory.modelAssignments.byok.memorySummary = bedrockPresetId;
+    await writeModelConfigCatalog(file, bedrockMemory);
+    expect((YAML.parse(readFileSync(file, "utf8")) as any).memmyMemory.summary.provider).toBe("bedrock");
+
+    const duplicateModel = openAiInput((await readModelConfigCatalog(file)).configRevision);
     duplicateModel.providers[0]!.models.push({
       endpointId: "chat",
       model: "gpt-5",
diff --git a/Memory/src/config/index.ts b/Memory/src/config/index.ts
index 85a96a4f2..6e9a98627 100644
--- a/Memory/src/config/index.ts
+++ b/Memory/src/config/index.ts
@@ -17,6 +17,7 @@ export type LlmProviderName =
   | ""
   | "local_only"
   | "openai_compatible"
+  | "openai_responses"
   | "gemini"
   | "anthropic"
   | "bedrock"
@@ -841,7 +842,7 @@ function resolveAssignedLlm(
   if (!resolved.ok || !llmProtocolSupported(resolved.context.protocol)) {
     return unavailableLlm(defaults);
   }
-  const runtimeProvider = memoryLlmProvider(resolved.context.provider);
+  const runtimeProvider = memoryRuntimeProvider(resolved.context.provider, resolved.context.protocol);
   return {
     ...defaults,
     provider: runtimeProvider,
@@ -887,6 +888,15 @@ function unavailableLlm(defaults: LlmConfig): Record<string, unknown> {
   };
 }
 
+function memoryRuntimeProvider(
+  provider: string,
+  protocol: ActualModelContext["protocol"]
+): LlmProviderName {
+  if (protocol === "bedrock-converse") return "bedrock";
+  if (protocol === "openai-responses") return "openai_responses";
+  return memoryLlmProvider(provider);
+}
+
 function memoryLlmProvider(provider: string): LlmProviderName {
   switch (provider) {
     case "anthropic":
@@ -1094,8 +1104,10 @@ function runtimeAssignmentMode(rootConfig: Record<string, unknown>): "account" |
 
 function llmProtocolSupported(protocol: ActualModelContext["protocol"]): boolean {
   return protocol === "openai-chat-completions"
+    || protocol === "openai-responses"
     || protocol === "anthropic-messages"
     || protocol === "gemini-generate-content"
+    || protocol === "bedrock-converse"
     || protocol === "memmy-account";
 }
 
@@ -1354,6 +1366,7 @@ function llmProvider(value: unknown, fallback: LlmProviderName): LlmProviderName
     provider === "" ||
     provider === "local_only" ||
     provider === "openai_compatible" ||
+    provider === "openai_responses" ||
     provider === "gemini" ||
     provider === "anthropic" ||
     provider === "bedrock" ||
diff --git a/Memory/src/contracts/index.ts b/Memory/src/contracts/index.ts
index 766bea1b0..bf9475c4f 100644
--- a/Memory/src/contracts/index.ts
+++ b/Memory/src/contracts/index.ts
@@ -16,7 +16,8 @@ export type ModelEndpointProtocol =
   | "dashscope-input-audio-chat"
   | "openai-images"
   | "dashscope-multimodal-generation"
-  | "memmy-account";
+  | "memmy-account"
+  | "bedrock-converse";
 
 export * from "./memory-canonical-json.js";
 export * from "./memory-workspace-identity.js";
diff --git a/Memory/src/contracts/model-catalog-resolver.ts b/Memory/src/contracts/model-catalog-resolver.ts
index 289eadfad..d32efb5fb 100644
--- a/Memory/src/contracts/model-catalog-resolver.ts
+++ b/Memory/src/contracts/model-catalog-resolver.ts
@@ -118,7 +118,8 @@ const CAPABILITIES = new Set<ModelCapability>([
 const PROTOCOLS = new Set<ModelEndpointProtocol>([
     "openai-chat-completions", "openai-responses", "anthropic-messages",
     "gemini-generate-content", "openai-embeddings", "dashscope-input-audio-chat",
-    "openai-images", "dashscope-multimodal-generation", "memmy-account"
+    "openai-images", "dashscope-multimodal-generation", "memmy-account",
+    "bedrock-converse"
 ]);
 
 /** Resolves one immutable current-catalog model assignment without guessing another preset or endpoint. */
@@ -332,12 +333,15 @@ function protocolSupportsCapability(
         return protocol === "openai-chat-completions"
             || protocol === "openai-responses"
             || protocol === "anthropic-messages"
-            || protocol === "gemini-generate-content";
+            || protocol === "gemini-generate-content"
+            || protocol === "bedrock-converse";
     }
     if (capability === "memory_summary" || capability === "memory_evolution") {
         return protocol === "openai-chat-completions"
+            || protocol === "openai-responses"
             || protocol === "anthropic-messages"
-            || protocol === "gemini-generate-content";
+            || protocol === "gemini-generate-content"
+            || protocol === "bedrock-converse";
     }
     if (capability === "embedding") return protocol === "openai-embeddings";
     if (capability === "asr") return protocol === "dashscope-input-audio-chat";
diff --git a/Memory/src/model/llm.ts b/Memory/src/model/llm.ts
index 19f046bd7..a2cc03f21 100644
--- a/Memory/src/model/llm.ts
+++ b/Memory/src/model/llm.ts
@@ -14,6 +14,15 @@ import type { LlmClient, LlmCompletionOptions, LlmMessage, ModelStatus } from ".
 
 const logger = createMemoryLogger("llm");
 
+interface OpenAiResponsesResponse {
+  status?: string;
+  output?: Array<{
+    type?: string;
+    content?: Array<{ type?: string; text?: string }>;
+  }>;
+  usage?: Record<string, unknown>;
+}
+
 interface OpenAiChatResponse {
   choices?: Array<{
     message?: {
@@ -299,6 +308,8 @@ class HttpLlmClient implements LlmClient {
     switch (this.config.provider) {
       case "openai_compatible":
         return this.completeOpenAiCompatible(messages, options);
+      case "openai_responses":
+        return this.completeOpenAiResponses(messages, options);
       case "gemini":
         return this.completeGemini(messages, options);
       case "anthropic":
@@ -374,6 +385,46 @@ class HttpLlmClient implements LlmClient {
     return { text, finishReason: normalizeFinishReason(choice?.finish_reason) };
   }
 
+  private async completeOpenAiResponses(messages: LlmMessage[], options: LlmCompletionOptions): Promise<LlmCallResult> {
+    const base = trimTrailingSlash(this.config.endpoint || "https://api.openai.com/v1");
+    const url = base.endsWith("/responses") ? base : `${base}/responses`;
+    const maxOutputTokens = Math.max(1, options.maxTokens ?? this.config.maxTokens ?? 1);
+    const response = await postJsonWithRetry<OpenAiResponsesResponse>({
+      actualModelContext: this.config.actualModelContext,
+      provider: "openai_responses",
+      operation: options.operation,
+      model: this.config.model,
+      url,
+      headers: {
+        ...bearer(this.config.apiKey),
+        ...(this.config.extraHeaders ?? {})
+      },
+      timeoutMs: options.timeoutMs ?? this.config.timeoutMs,
+      maxRetries: options.maxRetries ?? this.config.maxRetries,
+      body: {
+        model: this.config.model,
+        input: messages.map((message) => ({ role: message.role, content: message.content })),
+        max_output_tokens: maxOutputTokens,
+        store: false,
+        stream: false,
+        temperature: options.temperature ?? this.config.temperature,
+        ...(options.jsonMode ? { text: { format: { type: "json_object" } } } : {}),
+        ...(this.config.extraBody ?? {})
+      }
+    });
+    const text = (response.output ?? [])
+      .filter((item) => item.type === "message")
+      .flatMap((item) => item.content ?? [])
+      .filter((part) => part.type === "output_text" || typeof part.text === "string")
+      .map((part) => part.text ?? "")
+      .join("");
+    if (!text.trim()) {
+      throw new Error("openai_responses response missing output text");
+    }
+    this.recordTokenUsage(response, options);
+    return { text, finishReason: responsesFinishReason(response.status) };
+  }
+
   private async completeGemini(messages: LlmMessage[], options: LlmCompletionOptions): Promise<LlmCallResult> {
     if (!this.config.apiKey) {
       throw new Error("gemini provider requires apiKey");
@@ -1048,6 +1099,13 @@ function doubleMaxTokens(value: number | undefined, limit = Number.MAX_SAFE_INTE
   return expanded > value ? expanded : undefined;
 }
 
+function responsesFinishReason(status: string | undefined): LlmCallResult["finishReason"] {
+  if (status === "completed") return "stop";
+  if (status === "incomplete") return "length";
+  if (status === "failed" || status === "cancelled") return "other";
+  return normalizeFinishReason(status);
+}
+
 function normalizeFinishReason(value: string | undefined): LlmCallResult["finishReason"] {
   if (!value) return undefined;
   switch (value.trim().toLowerCase()) {
diff --git a/Memory/tests/llm-protocol-adapters.test.ts b/Memory/tests/llm-protocol-adapters.test.ts
new file mode 100644
index 000000000..6661bde5b
--- /dev/null
+++ b/Memory/tests/llm-protocol-adapters.test.ts
@@ -0,0 +1,155 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveAssignedModel, type RuntimeModelCatalog } from "../src/contracts/index.js";
+import type { LlmConfig } from "../src/config/index.js";
+import { createLlmClient } from "../src/model/llm.js";
+import type { LlmMessage } from "../src/model/types.js";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("memory protocol adapters", () => {
+  it("resolves openai-responses and bedrock-converse for memory roles", () => {
+    const responses = resolveAssignedModel({
+      catalog: catalog("openai-responses"),
+      mode: "byok",
+      capability: "memory_summary"
+    });
+    const bedrock = resolveAssignedModel({
+      catalog: catalog("bedrock-converse"),
+      mode: "byok",
+      capability: "memory_evolution"
+    });
+
+    expect(responses.ok && responses.context.protocol).toBe("openai-responses");
+    expect(bedrock.ok && bedrock.context.protocol).toBe("bedrock-converse");
+  });
+
+  it("posts memory summary turns to the Responses API", async () => {
+    const fetchMock = stubFetch(responsesBody("{\"summary\":\"ok\"}"));
+    vi.stubGlobal("fetch", fetchMock);
+    const messages: LlmMessage[] = [
+      { role: "system", content: "Return JSON." },
+      { role: "user", content: "Summarize this." }
+    ];
+
+    const text = await createLlmClient(llmConfig({ provider: "openai_responses" }), {
+      modelRole: "memory_summary"
+    }).complete(messages, { operation: "capture.summarize", jsonMode: true, maxTokens: 512 });
+
+    expect(text).toBe("{\"summary\":\"ok\"}");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://api.example.test/v1/responses",
+      expect.objectContaining({ method: "POST" })
+    );
+    expect(requestBody(fetchMock)).toMatchObject({
+      model: "memory-model",
+      input: messages,
+      max_output_tokens: 512,
+      store: false,
+      stream: false,
+      text: { format: { type: "json_object" } }
+    });
+  });
+
+  it("posts memory evolution turns to Bedrock Converse", async () => {
+    const fetchMock = stubFetch(bedrockBody("evolved"));
+    vi.stubGlobal("fetch", fetchMock);
+    const messages: LlmMessage[] = [
+      { role: "system", content: "Evolve the memory." },
+      { role: "user", content: "New evidence." }
+    ];
+
+    const text = await createLlmClient(llmConfig({
+      provider: "bedrock",
+      endpoint: "https://bedrock-runtime.us-west-2.amazonaws.com",
+      model: "anthropic.claude-sonnet-5"
+    }), {
+      modelRole: "memory_evolution"
+    }).complete(messages, { operation: "skill.crystallize", maxTokens: 700 });
+
+    expect(text).toBe("evolved");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://bedrock-runtime.us-west-2.amazonaws.com/model/anthropic.claude-sonnet-5/converse",
+      expect.objectContaining({ method: "POST" })
+    );
+    expect(requestBody(fetchMock)).toMatchObject({
+      system: [{ text: "Evolve the memory." }],
+      messages: [{ role: "user", content: [{ text: "New evidence." }] }],
+      inferenceConfig: { maxTokens: 700 }
+    });
+  });
+});
+
+function catalog(protocol: "openai-responses" | "bedrock-converse"): RuntimeModelCatalog {
+  return {
+    providers: {
+      custom: {
+        apiKey: "secret",
+        endpoints: {
+          chat: {
+            apiBase: protocol === "bedrock-converse"
+              ? "https://bedrock-runtime.us-west-2.amazonaws.com"
+              : "https://api.example.test/v1",
+            protocol
+          }
+        }
+      }
+    },
+    modelPresets: {
+      "memory-model": {
+        provider: "custom",
+        endpoint: "chat",
+        model: "memory-model",
+        source: "byok",
+        capabilities: ["agent", "memory_summary", "memory_evolution"]
+      }
+    },
+    modelAssignments: {
+      byok: protocol === "bedrock-converse"
+        ? { memoryEvolution: "memory-model" }
+        : { memorySummary: "memory-model" }
+    }
+  };
+}
+
+function llmConfig(overrides: Partial<LlmConfig>): LlmConfig {
+  return {
+    provider: "openai_responses",
+    endpoint: "https://api.example.test/v1",
+    model: "memory-model",
+    apiKey: "sk-test",
+    enableThinking: false,
+    temperature: 0,
+    maxTokens: 4096,
+    timeoutMs: 60_000,
+    maxRetries: 0,
+    malformedRetries: 0,
+    ...overrides
+  };
+}
+
+function responsesBody(text: string): Response {
+  return new Response(JSON.stringify({
+    status: "completed",
+    output: [{ type: "message", content: [{ type: "output_text", text }] }],
+    usage: { input_tokens: 3, output_tokens: 2, total_tokens: 5 }
+  }), { status: 200, headers: { "content-type": "application/json" } });
+}
+
+function bedrockBody(text: string): Response {
+  return new Response(JSON.stringify({
+    output: { message: { content: [{ text }] } },
+    stopReason: "end_turn",
+    usage: { inputTokens: 3, outputTokens: 2 }
+  }), { status: 200, headers: { "content-type": "application/json" } });
+}
+
+function stubFetch(response: Response): ReturnType<typeof vi.fn<typeof fetch>> {
+  return vi.fn<typeof fetch>(async () => response);
+}
+
+function requestBody(fetchMock: ReturnType<typeof vi.fn<typeof fetch>>): Record<string, unknown> {
+  return JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body)) as Record<string, unknown>;
+}

From 284639b34dcd25dcffd765a66fa5c18f91e114ab Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Tue, 29 Sep 2026 16:21:32 +0800
Subject: [PATCH 04/85] Add official thinking levels for the September model
 releases.

GPT-6, Claude Opus 5.5, Gemini 3.8 Flash, and DeepSeek V4.1 Flash were missing from the picker table, so the composer had no effort control for those model ids.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../src/model-thinking-levels.ts              | 44 ++++++++++++++++---
 .../tests/model-thinking-levels.test.ts       | 36 +++++++++++++++
 2 files changed, 75 insertions(+), 5 deletions(-)

diff --git a/App/backend/local-api-contracts/src/model-thinking-levels.ts b/App/backend/local-api-contracts/src/model-thinking-levels.ts
index 3df8208b2..667f2f045 100644
--- a/App/backend/local-api-contracts/src/model-thinking-levels.ts
+++ b/App/backend/local-api-contracts/src/model-thinking-levels.ts
@@ -1,5 +1,5 @@
 /**
- * 模型思考强度配置表。Reviewed: 2026-09-10
+ * 模型思考强度配置表。Reviewed: 2026-09-29
  *
  * 三个字段决定前端渲染与新 session 默认状态：
  * - switchable: true  → 渲染思考开关（用户可关闭思考）
@@ -30,7 +30,7 @@ export const ModelThinkingConfigSchema = z.object({
 });
 export type ModelThinkingConfigDto = z.infer<typeof ModelThinkingConfigSchema>;
 
-export const MODEL_THINKING_REVIEWED_AT = "2026-09-10";
+export const MODEL_THINKING_REVIEWED_AT = "2026-09-29";
 
 const ALWAYS_ON_FIVE: ModelThinkingConfig = {
   switchable: false,
@@ -46,6 +46,27 @@ const SWITCHABLE_FIVE: ModelThinkingConfig = {
   defaultLevel: "high"
 };
 
+/** GPT-6 Sol / Luna: `none` turns reasoning off; omitted effort is `medium`. */
+const SWITCHABLE_FIVE_MEDIUM: ModelThinkingConfig = {
+  switchable: true,
+  defaultEnabled: true,
+  levels: ["low", "medium", "high", "xhigh", "max"],
+  defaultLevel: "medium"
+};
+
+/**
+ * Thinking cannot be disabled. Five effort levels, default `medium`.
+ * GPT-6 Astra rejects `none`. Claude Opus 5.5 documents `medium` as its API default.
+ * OpenAI's reasoning guide does not publish a separate omit-effort default for Astra;
+ * `medium` is the default it documents for the other GPT-6 models and for most workloads.
+ */
+const ALWAYS_ON_FIVE_MEDIUM: ModelThinkingConfig = {
+  switchable: false,
+  defaultEnabled: true,
+  levels: ["low", "medium", "high", "xhigh", "max"],
+  defaultLevel: "medium"
+};
+
 const SWITCHABLE_FOUR: ModelThinkingConfig = {
   switchable: true,
   defaultEnabled: true,
@@ -87,6 +108,7 @@ export const MODEL_THINKING_CONFIGS: Readonly<Record<string, ModelThinkingConfig
   "claude-mythos-5-1": ALWAYS_ON_FIVE,
   "claude-mythos-5": ALWAYS_ON_FIVE,
   "claude-mythos-preview": ALWAYS_ON_FIVE,
+  "claude-opus-5-5": ALWAYS_ON_FIVE_MEDIUM,
   "claude-opus-5": SWITCHABLE_FIVE,
   "claude-sonnet-5": SWITCHABLE_FIVE,
   "claude-opus-4-8": SWITCHABLE_FIVE,
@@ -101,13 +123,17 @@ export const MODEL_THINKING_CONFIGS: Readonly<Record<string, ModelThinkingConfig
   },
   "claude-haiku-4-5": TOGGLE_ONLY,
   "claude-haiku-4-5-20251001": TOGGLE_ONLY,
+  "anthropic.claude-opus-5-5": ALWAYS_ON_FIVE_MEDIUM,
   "anthropic.claude-opus-5": SWITCHABLE_FIVE,
   "anthropic.claude-sonnet-5": SWITCHABLE_FIVE,
   "anthropic.claude-opus-4-8": SWITCHABLE_FIVE,
   "anthropic.claude-opus-4-7": SWITCHABLE_FIVE,
   "anthropic.claude-haiku-4-5": TOGGLE_ONLY,
 
-  // OpenAI. Reviewed 2026-09-10.
+  // OpenAI. GPT-6 reviewed 2026-09-29; GPT-5.6 and earlier reviewed 2026-09-10.
+  "gpt-6-astra": ALWAYS_ON_FIVE_MEDIUM,
+  "gpt-6-sol": SWITCHABLE_FIVE_MEDIUM,
+  "gpt-6-luna": SWITCHABLE_FIVE_MEDIUM,
   "gpt-5.6": SWITCHABLE_FIVE,
   "gpt-5.6-sol": SWITCHABLE_FIVE,
   "gpt-5.6-terra": SWITCHABLE_FIVE,
@@ -125,11 +151,19 @@ export const MODEL_THINKING_CONFIGS: Readonly<Record<string, ModelThinkingConfig
   "gpt-5.1": SWITCHABLE_THREE,
   "gpt-5.1-codex": SWITCHABLE_THREE,
 
-  // Gemini. Reviewed 2026-09-10.
+  // Gemini. 3.8 Flash reviewed 2026-09-29; 2.5 reviewed 2026-09-10.
+  "gemini-3.8-flash": {
+    switchable: false,
+    defaultEnabled: true,
+    levels: ["low", "medium", "high"],
+    defaultLevel: "medium"
+  },
   "gemini-2.5-flash": TOGGLE_ONLY,
   "gemini-2.5-flash-lite": TOGGLE_ONLY,
 
-  // DeepSeek. Reviewed 2026-09-10.
+  // DeepSeek. V4.1 Flash reviewed 2026-09-29; earlier V4 ids reviewed 2026-09-10.
+  "deepseek-flash": SWITCHABLE_LOW_HIGH_MAX,
+  "deepseek-v4.1-flash": SWITCHABLE_LOW_HIGH_MAX,
   "deepseek-v4-pro": SWITCHABLE_LOW_HIGH_MAX,
   "deepseek-v4-flash": SWITCHABLE_LOW_HIGH_MAX,
   "deepseek-v4-flash-0731": SWITCHABLE_LOW_HIGH_MAX,
diff --git a/App/backend/local-api-contracts/tests/model-thinking-levels.test.ts b/App/backend/local-api-contracts/tests/model-thinking-levels.test.ts
index d67d416aa..650d6722e 100644
--- a/App/backend/local-api-contracts/tests/model-thinking-levels.test.ts
+++ b/App/backend/local-api-contracts/tests/model-thinking-levels.test.ts
@@ -33,4 +33,40 @@ describe("model thinking levels", () => {
     const alwaysOn = getModelThinkingConfig("claude-fable-5")!;
     expect(resolveThinkingEnabled(alwaysOn, false)).toBe(true);
   });
+
+  it("matches vendor docs for models added on 2026-09-29", () => {
+    expect(getModelThinkingConfig("gpt-6-sol")).toEqual({
+      switchable: true,
+      defaultEnabled: true,
+      levels: ["low", "medium", "high", "xhigh", "max"],
+      defaultLevel: "medium"
+    });
+    expect(getModelThinkingConfig("gpt-6-luna")).toEqual(getModelThinkingConfig("gpt-6-sol"));
+    expect(getModelThinkingConfig("gpt-6-astra")).toEqual({
+      switchable: false,
+      defaultEnabled: true,
+      levels: ["low", "medium", "high", "xhigh", "max"],
+      defaultLevel: "medium"
+    });
+    expect(resolveThinkingEnabled(getModelThinkingConfig("gpt-6-astra")!, false)).toBe(true);
+
+    expect(getModelThinkingConfig("claude-opus-5-5")).toEqual(getModelThinkingConfig("gpt-6-astra"));
+    expect(getModelThinkingConfig("anthropic.claude-opus-5-5")).toEqual(getModelThinkingConfig("claude-opus-5-5"));
+
+    expect(getModelThinkingConfig("gemini-3.8-flash")).toEqual({
+      switchable: false,
+      defaultEnabled: true,
+      levels: ["low", "medium", "high"],
+      defaultLevel: "medium"
+    });
+
+    const deepseek = {
+      switchable: true,
+      defaultEnabled: true,
+      levels: ["low", "high", "max"],
+      defaultLevel: "high"
+    };
+    expect(getModelThinkingConfig("deepseek-flash")).toEqual(deepseek);
+    expect(getModelThinkingConfig("deepseek-v4.1-flash")).toEqual(deepseek);
+  });
 });

From cddc65b5aeb1e6d005ccc271f0ac909162a9803b Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Tue, 29 Sep 2026 16:28:13 +0800
Subject: [PATCH 05/85] Remove the brain icon from the thinking mode toggle.

The label and switch already identify the control, and the icon crowded the composer action bar.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 App/frontend/desktop/src/components/agent-thinking-control.tsx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/App/frontend/desktop/src/components/agent-thinking-control.tsx b/App/frontend/desktop/src/components/agent-thinking-control.tsx
index 0ec32faf1..88c885ad4 100644
--- a/App/frontend/desktop/src/components/agent-thinking-control.tsx
+++ b/App/frontend/desktop/src/components/agent-thinking-control.tsx
@@ -1,4 +1,4 @@
-import { Brain, ChevronDown } from "lucide-react";
+import { ChevronDown } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 import {
   resolveThinkingEnabled,
@@ -70,7 +70,6 @@ export function AgentThinkingControl(props: AgentThinkingControlProps) {
           className={`thinking-toggle ${enabled ? "thinking-toggle--on" : ""}`}
           aria-label={t("home.thinking.toggle")}
         >
-          <Brain size={16} className="thinking-toggle__icon" />
           <span className="thinking-toggle__label">{t("home.thinking.label")}</span>
           <div className={`thinking-toggle__switch ${enabled ? "thinking-toggle__switch--on" : ""}`}>
             <div className="thinking-toggle__switch-thumb" />

From cb4832612aeaef99fe53245f69aa6e981e392777 Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Tue, 29 Sep 2026 17:01:17 +0800
Subject: [PATCH 06/85] Explain custom model capability options on hover.

The thinking and image checkboxes did not say what they change, and the checkbox itself did not show a pointer.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 App/frontend/desktop/src/i18n/messages.ts     |  8 ++
 .../src/pages/model-workspace-section.tsx     | 77 +++++++++++--------
 .../src/pages/tests/settings-page.test.tsx    |  8 ++
 App/frontend/desktop/src/styles.css           |  4 +
 4 files changed, 65 insertions(+), 32 deletions(-)

diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index dc21ce1be..aa4178b4c 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -1552,12 +1552,16 @@ export const zhCNMessages = {
   "settings.modelWorkspace.region": "区域",
   "settings.modelWorkspace.regionPlaceholder": "例如：us-east-1",
   "settings.modelWorkspace.customThinkingEnabled": "支持思考",
+  "settings.modelWorkspace.customThinkingEnabledHint": "勾选后，输入框可以设置思考。不勾选则不传思考参数，由模型接口按默认行为处理。",
   "settings.modelWorkspace.customThinkingSwitchable": "可关闭思考",
+  "settings.modelWorkspace.customThinkingSwitchableHint": "勾选后，对话里可以临时关闭思考。不勾选则思考始终开启，输入框不显示思考开关。",
   "settings.modelWorkspace.customThinkingDefaultEnabled": "默认开启思考",
+  "settings.modelWorkspace.customThinkingDefaultEnabledHint": "决定新对话一开始是否开启思考。之后仍可在输入框里更改。",
   "settings.modelWorkspace.customThinkingLevels": "思考档位",
   "settings.modelWorkspace.customThinkingLevelsPlaceholder": "例如：low,medium,high",
   "settings.modelWorkspace.customThinkingLevelsHint": "用逗号分隔多个档位名称，留空表示无档位",
   "settings.modelWorkspace.customImageInput": "支持图片输入",
+  "settings.modelWorkspace.customImageInputHint": "勾选后可以在消息里发送图片。不勾选时，带图片的消息会被拒绝。",
   "settings.token.detail": "Token 用量详情",
   "settings.token.agentTask": "Agent 任务",
   "settings.token.memorySummary": "记忆摘要",
@@ -3319,12 +3323,16 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "settings.modelWorkspace.region": "Region",
   "settings.modelWorkspace.regionPlaceholder": "For example: us-east-1",
   "settings.modelWorkspace.customThinkingEnabled": "Supports thinking",
+  "settings.modelWorkspace.customThinkingEnabledHint": "When checked, the composer can set thinking. When unchecked, no thinking parameters are sent and the model endpoint uses its default behavior.",
   "settings.modelWorkspace.customThinkingSwitchable": "Thinking can be turned off",
+  "settings.modelWorkspace.customThinkingSwitchableHint": "When checked, a conversation can turn thinking off. When unchecked, thinking stays on and the composer hides the thinking switch.",
   "settings.modelWorkspace.customThinkingDefaultEnabled": "Thinking on by default",
+  "settings.modelWorkspace.customThinkingDefaultEnabledHint": "Sets whether a new conversation starts with thinking on. You can still change it in the composer.",
   "settings.modelWorkspace.customThinkingLevels": "Thinking levels",
   "settings.modelWorkspace.customThinkingLevelsPlaceholder": "For example: low,medium,high",
   "settings.modelWorkspace.customThinkingLevelsHint": "Comma-separated level names. Leave empty for no levels.",
   "settings.modelWorkspace.customImageInput": "Supports image input",
+  "settings.modelWorkspace.customImageInputHint": "When checked, messages can include images. When unchecked, messages with images are rejected.",
   "settings.token.detail": "Token usage details",
   "settings.token.agentTask": "Agent tasks",
   "settings.token.memorySummary": "Memory summary",
diff --git a/App/frontend/desktop/src/pages/model-workspace-section.tsx b/App/frontend/desktop/src/pages/model-workspace-section.tsx
index d6140102a..916328ae4 100644
--- a/App/frontend/desktop/src/pages/model-workspace-section.tsx
+++ b/App/frontend/desktop/src/pages/model-workspace-section.tsx
@@ -1173,33 +1173,27 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
                 />
               )}
               <div className="custom-thinking-config">
-                <label className="custom-thinking-config__label">
-                  <input
-                    type="checkbox"
-                    checked={editor.customThinkingEnabled}
-                    onChange={(event) => setEditor((prev) => prev ? { ...prev, customThinkingEnabled: event.target.checked } : null)}
-                  />
-                  {t("settings.modelWorkspace.customThinkingEnabled")}
-                </label>
+                <CustomCapabilityOption
+                  checked={editor.customThinkingEnabled}
+                  label={t("settings.modelWorkspace.customThinkingEnabled")}
+                  hint={t("settings.modelWorkspace.customThinkingEnabledHint")}
+                  onChange={(customThinkingEnabled) => setEditor((prev) => prev ? { ...prev, customThinkingEnabled } : null)}
+                />
                 {editor.customThinkingEnabled && (
                   <>
-                    <label className="custom-thinking-config__label">
-                      <input
-                        type="checkbox"
-                        checked={editor.customThinkingSwitchable}
-                        onChange={(event) => setEditor((prev) => prev ? { ...prev, customThinkingSwitchable: event.target.checked } : null)}
-                      />
-                      {t("settings.modelWorkspace.customThinkingSwitchable")}
-                    </label>
+                    <CustomCapabilityOption
+                      checked={editor.customThinkingSwitchable}
+                      label={t("settings.modelWorkspace.customThinkingSwitchable")}
+                      hint={t("settings.modelWorkspace.customThinkingSwitchableHint")}
+                      onChange={(customThinkingSwitchable) => setEditor((prev) => prev ? { ...prev, customThinkingSwitchable } : null)}
+                    />
                     {editor.customThinkingSwitchable && (
-                      <label className="custom-thinking-config__label">
-                        <input
-                          type="checkbox"
-                          checked={editor.customThinkingDefaultEnabled}
-                          onChange={(event) => setEditor((prev) => prev ? { ...prev, customThinkingDefaultEnabled: event.target.checked } : null)}
-                        />
-                        {t("settings.modelWorkspace.customThinkingDefaultEnabled")}
-                      </label>
+                      <CustomCapabilityOption
+                        checked={editor.customThinkingDefaultEnabled}
+                        label={t("settings.modelWorkspace.customThinkingDefaultEnabled")}
+                        hint={t("settings.modelWorkspace.customThinkingDefaultEnabledHint")}
+                        onChange={(customThinkingDefaultEnabled) => setEditor((prev) => prev ? { ...prev, customThinkingDefaultEnabled } : null)}
+                      />
                     )}
                     <div className="custom-thinking-levels">
                       <label className="custom-thinking-levels__label">
@@ -1218,14 +1212,12 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
                     </div>
                   </>
                 )}
-                <label className="custom-thinking-config__label">
-                  <input
-                    type="checkbox"
-                    checked={editor.customImageInput}
-                    onChange={(event) => setEditor((prev) => prev ? { ...prev, customImageInput: event.target.checked } : null)}
-                  />
-                  {t("settings.modelWorkspace.customImageInput")}
-                </label>
+                <CustomCapabilityOption
+                  checked={editor.customImageInput}
+                  label={t("settings.modelWorkspace.customImageInput")}
+                  hint={t("settings.modelWorkspace.customImageInputHint")}
+                  onChange={(customImageInput) => setEditor((prev) => prev ? { ...prev, customImageInput } : null)}
+                />
               </div>
             </>
           )}
@@ -1777,3 +1769,24 @@ async function simulateConnectionTest(): Promise<{ ok: boolean }> {
   await new Promise((resolve) => window.setTimeout(resolve, 450));
   return { ok: true };
 }
+
+function CustomCapabilityOption(props: {
+  checked: boolean;
+  label: string;
+  hint: string;
+  onChange: (checked: boolean) => void;
+}) {
+  return (
+    <label className="custom-thinking-config__label">
+      <input
+        type="checkbox"
+        className="custom-thinking-config__checkbox"
+        checked={props.checked}
+        onChange={(event) => props.onChange(event.target.checked)}
+      />
+      <Tooltip content={props.hint} variant="description">
+        <span>{props.label}</span>
+      </Tooltip>
+    </label>
+  );
+}
diff --git a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
index 191982184..1c9a6f7da 100644
--- a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
@@ -204,6 +204,7 @@ describe("自定义模型能力选择", () => {
 
   it("模型能力沿用标准 Select 四选一，不再拆分文本用途", () => {
     const source = readFileSync(modelWorkspaceSourcePath, "utf8");
+    const styles = readFileSync(fileURLToPath(new URL("../../styles.css", import.meta.url)), "utf8");
 
     expect(source).toContain('const MODEL_KIND_OPTIONS = ["text", "embedding", "asr", "image"] as const;');
     expect(source).toContain("value={kind}");
@@ -214,6 +215,13 @@ describe("自定义模型能力选择", () => {
     expect(source).toContain("normalizeEditorCapabilities(entry.capabilities.map(fromCatalogCapability))");
     expect(source).toContain("checked={editor.customThinkingEnabled}");
     expect(source).toContain("checked={editor.customImageInput}");
+    expect(source).toContain('t("settings.modelWorkspace.customThinkingEnabledHint")');
+    expect(source).toContain('t("settings.modelWorkspace.customThinkingSwitchableHint")');
+    expect(source).toContain('t("settings.modelWorkspace.customThinkingDefaultEnabledHint")');
+    expect(source).toContain('t("settings.modelWorkspace.customImageInputHint")');
+    expect(source).toContain('className="custom-thinking-config__checkbox"');
+    expect(styles).toContain(".custom-thinking-config__checkbox");
+    expect(styles).toContain("cursor: pointer");
     expect(source).not.toContain('t("settings.modelWorkspace.textRoles")');
     expect(source).not.toContain('t("settings.modelWorkspace.capability.agent")');
   });
diff --git a/App/frontend/desktop/src/styles.css b/App/frontend/desktop/src/styles.css
index 6ec3764ec..eff8f6dd0 100644
--- a/App/frontend/desktop/src/styles.css
+++ b/App/frontend/desktop/src/styles.css
@@ -1008,6 +1008,10 @@ body.memmy-window-fullscreen {
   font-size: 13px;
 }
 
+.custom-thinking-config__checkbox {
+  cursor: pointer;
+}
+
 .custom-thinking-levels {
   display: grid;
   gap: 6px;

From 2560b36a677322ca430dc057c3f02971ca8f4b31 Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Tue, 29 Sep 2026 19:31:04 +0800
Subject: [PATCH 07/85] Save Custom as its own provider and route each protocol
 to the matching client.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 App/backend/local-api-contracts/src/index.ts  |   3 +-
 .../memmy-config/model-config-catalog.ts      | 127 +++++++++++++++-
 .../tests/model-config-catalog.test.ts        | 137 ++++++++++++++++++
 .../src/pages/model-workspace-section.tsx     |   8 +-
 .../src/pages/tests/settings-page.test.tsx    |  10 +-
 .../desktop/src/state/model-workspace.ts      |   2 +-
 .../src/state/tests/model-workspace.test.ts   |   6 +-
 App/memmy-agent/src/providers/factory.ts      |  10 +-
 .../src/providers/openai-compat-provider.ts   |   3 +-
 .../tests/providers/custom-provider.test.ts   |  42 ++++++
 Memory/src/config/index.ts                    |   2 +
 Memory/src/config/model-catalog.ts            |   3 +-
 Memory/tests/llm-protocol-adapters.test.ts    |  51 ++++++-
 13 files changed, 381 insertions(+), 23 deletions(-)

diff --git a/App/backend/local-api-contracts/src/index.ts b/App/backend/local-api-contracts/src/index.ts
index 999adcb3b..66d746787 100644
--- a/App/backend/local-api-contracts/src/index.ts
+++ b/App/backend/local-api-contracts/src/index.ts
@@ -745,7 +745,8 @@ export const CatalogProviderIdSchema = z.enum([
     "stepfun",
     "xiaomi_mimo",
     "memmy_account",
-    "bedrock"
+    "bedrock",
+    "custom"
 ]);
 export type CatalogProviderId = z.infer<typeof CatalogProviderIdSchema>;
 
diff --git a/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts b/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
index 0baa81d1f..94fbfb1e7 100644
--- a/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
+++ b/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
@@ -64,7 +64,23 @@ export class InvalidModelConfigError extends Error {
 export async function readModelConfigCatalog(configPath: string): Promise<ModelConfigView> {
   const target = resolve(configPath);
   const { content, config } = await readConfig(target);
-  return buildModelConfigView(config, revisionFor(config), await updatedAt(target, content));
+  if (!relocateCustomPresets(config)) {
+    return buildModelConfigView(config, revisionFor(config), await updatedAt(target, content));
+  }
+  try {
+    const result = await mutateRuntimeConfig(target, (current) => {
+      relocateCustomPresets(current);
+      return current;
+    });
+    return buildModelConfigView(result.value, revisionFor(result.value), new Date().toISOString());
+  } catch (error) {
+    if (isErrorCode(error, "migration_lock_timeout")) {
+      throw Object.assign(new Error("Model configuration is busy; try again"), {
+        code: "config_write_busy" as const
+      });
+    }
+    throw error;
+  }
 }
 
 export async function writeModelConfigCatalog(
@@ -165,6 +181,7 @@ function mergeModelConfig(config: ConfigRecord, input: ModelConfigInput): Config
     }
   }
 
+  relocateCustomPresets({ providers: nextProviders, modelPresets: nextPresets });
   validateUniqueModels(nextPresets);
   const modelAssignments = cloneAssignments(input.modelAssignments);
   validateAssignments(modelAssignments, nextPresets, existingAssignments);
@@ -322,11 +339,115 @@ function memoryConnection(config: ConfigRecord, presetId: string): ConfigRecord
 function memoryProvider(providerId: string, protocol: string | undefined): string {
   if (protocol === "bedrock-converse") return "bedrock";
   if (protocol === "openai-responses") return "openai_responses";
-  if (providerId === "anthropic") return "anthropic";
-  if (providerId === "gemini") return "gemini";
+  if (protocol === "anthropic-messages" || providerId === "anthropic") return "anthropic";
+  if (protocol === "gemini-generate-content" || providerId === "gemini") return "gemini";
   return "openai_compatible";
 }
 
+const CUSTOM_PROVIDER_ID = "custom";
+const PROVIDER_CONNECTION_KEYS = new Set([
+  "apiKey", "extraHeaders", "extraBody", "region", "profile", "endpoints", "apiBase", "apiType"
+]);
+
+function relocateCustomPresets(config: ConfigRecord): boolean {
+  const providers = record(config.providers);
+  const presets = record(config.modelPresets);
+  const customProvider = record(providers[CUSTOM_PROVIDER_ID]);
+  const customEndpoints = record(customProvider.endpoints);
+  let changed = false;
+
+  for (const presetValue of Object.values(presets)) {
+    const preset = record(presetValue);
+    if (preset.custom !== true) continue;
+    const providerId = stringValue(preset.provider);
+    const endpointId = stringValue(preset.endpoint);
+    if (!providerId || !endpointId || providerId === CUSTOM_PROVIDER_ID) continue;
+    const sourceProvider = record(providers[providerId]);
+    const sourceEndpoint = record(record(sourceProvider.endpoints)[endpointId]);
+    if (!stringValue(sourceEndpoint.apiBase)) continue;
+    const targetId = placeCustomEndpoint(customEndpoints, endpointId, movedEndpoint(sourceProvider, sourceEndpoint));
+    preset.provider = CUSTOM_PROVIDER_ID;
+    preset.endpoint = targetId;
+    changed = true;
+  }
+  if (!changed) return false;
+
+  customProvider.endpoints = customEndpoints;
+  providers[CUSTOM_PROVIDER_ID] = customProvider;
+  for (const [providerId, providerValue] of Object.entries(providers)) {
+    if (providerId === CUSTOM_PROVIDER_ID) continue;
+    const provider = record(providerValue);
+    const endpoints = record(provider.endpoints);
+    for (const endpointId of Object.keys(endpoints)) {
+      const referenced = Object.values(presets).some((presetValue) => {
+        const preset = record(presetValue);
+        return preset.provider === providerId && preset.endpoint === endpointId;
+      });
+      if (!referenced) delete endpoints[endpointId];
+    }
+    const stillReferenced = Object.values(presets).some((presetValue) => record(presetValue).provider === providerId);
+    const onlyConnectionFields = Object.keys(provider).every((key) => PROVIDER_CONNECTION_KEYS.has(key));
+    if (!stillReferenced && !Object.keys(endpoints).length && onlyConnectionFields) {
+      delete providers[providerId];
+    }
+  }
+  config.providers = providers;
+  config.modelPresets = presets;
+  return true;
+}
+
+function movedEndpoint(provider: ConfigRecord, endpoint: ConfigRecord): ConfigRecord {
+  const next: ConfigRecord = { ...endpoint };
+  const apiKey = stringValue(endpoint.apiKey) ?? stringValue(provider.apiKey);
+  if (apiKey) next.apiKey = apiKey;
+  const extraHeaders = { ...record(provider.extraHeaders), ...record(endpoint.extraHeaders) };
+  if (Object.keys(extraHeaders).length) next.extraHeaders = extraHeaders;
+  const extraBody = { ...record(provider.extraBody), ...record(endpoint.extraBody) };
+  if (Object.keys(extraBody).length) next.extraBody = extraBody;
+  const region = stringValue(endpoint.region) ?? stringValue(provider.region);
+  if (region) next.region = region;
+  const profile = stringValue(endpoint.profile) ?? stringValue(provider.profile);
+  if (profile) next.profile = profile;
+  return next;
+}
+
+function placeCustomEndpoint(endpoints: ConfigRecord, preferredId: string, endpoint: ConfigRecord): string {
+  const existing = record(endpoints[preferredId]);
+  if (!Object.keys(existing).length) {
+    endpoints[preferredId] = endpoint;
+    return preferredId;
+  }
+  if (sameStoredEndpoint(existing, endpoint)) return preferredId;
+  let suffix = 2;
+  let id = `${preferredId}-custom`;
+  while (Object.keys(record(endpoints[id])).length && !sameStoredEndpoint(record(endpoints[id]), endpoint)) {
+    id = `${preferredId}-custom-${suffix}`;
+    suffix += 1;
+  }
+  endpoints[id] = endpoint;
+  return id;
+}
+
+function sameStoredEndpoint(left: ConfigRecord, right: ConfigRecord): boolean {
+  return stableJson({
+    protocol: left.protocol ?? null,
+    apiBase: normalizeApiBase(stringValue(left.apiBase) ?? ""),
+    apiKey: stringValue(left.apiKey) ?? null,
+    region: stringValue(left.region) ?? null,
+    profile: stringValue(left.profile) ?? null,
+    extraHeaders: left.extraHeaders ?? null,
+    extraBody: left.extraBody ?? null
+  }) === stableJson({
+    protocol: right.protocol ?? null,
+    apiBase: normalizeApiBase(stringValue(right.apiBase) ?? ""),
+    apiKey: stringValue(right.apiKey) ?? null,
+    region: stringValue(right.region) ?? null,
+    profile: stringValue(right.profile) ?? null,
+    extraHeaders: right.extraHeaders ?? null,
+    extraBody: right.extraBody ?? null
+  });
+}
+
 function mergeMemoryConnection(previous: ConfigRecord, connection: ConfigRecord): ConfigRecord {
   return {
     ...withoutMemoryConnection(previous),
diff --git a/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts b/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
index 1ed55ca8a..7c9f4d93b 100644
--- a/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
+++ b/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
@@ -69,6 +69,143 @@ function openAiInput(revision: string, presetId?: string): ModelConfigInput {
 }
 
 describe("model config catalog", () => {
+  it("stores Custom beside OpenAI and moves an existing custom preset onto provider custom", async () => {
+    const file = fixture({
+      providers: {
+        openai: {
+          apiKey: "sk-shared",
+          endpoints: {
+            chat: {
+              apiBase: "https://api.openai.com/v1",
+              protocol: "openai-chat-completions"
+            }
+          }
+        }
+      },
+      modelPresets: {
+        "legacy-custom": {
+          provider: "openai",
+          endpoint: "chat",
+          model: "legacy-model",
+          source: "byok",
+          capabilities: ["agent", "memory_summary", "memory_evolution"],
+          custom: true
+        }
+      },
+      modelAssignments: emptyAssignments()
+    });
+
+    const read = await readModelConfigCatalog(file);
+    const migrated = YAML.parse(readFileSync(file, "utf8")) as any;
+    expect(migrated.modelPresets["legacy-custom"]).toMatchObject({
+      provider: "custom",
+      endpoint: "chat",
+      custom: true
+    });
+    expect(migrated.providers.custom.endpoints.chat).toMatchObject({
+      apiBase: "https://api.openai.com/v1",
+      protocol: "openai-chat-completions",
+      apiKey: "sk-shared"
+    });
+    expect(migrated.providers.openai).toBeUndefined();
+    expect(read.providers.map((provider) => provider.provider)).toEqual(["custom"]);
+
+    const legacy = read.providers[0]!.models[0]!;
+    const saved = await writeModelConfigCatalog(file, {
+      configRevision: read.configRevision,
+      providers: [
+        {
+          provider: "custom",
+          endpoints: [{
+            endpointId: legacy.endpointId,
+            apiBase: "https://api.openai.com/v1",
+            protocol: "openai-chat-completions",
+            apiKey: "sk-shared"
+          }, {
+            endpointId: "anthropic",
+            apiBase: "https://api.anthropic.com/v1",
+            protocol: "anthropic-messages",
+            apiKey: "sk-anthropic"
+          }],
+          models: [
+            {
+              presetId: legacy.presetId,
+              endpointId: legacy.endpointId,
+              model: "legacy-model",
+              source: "byok",
+              capabilities: ["agent", "memory_summary", "memory_evolution"],
+              custom: true
+            },
+            {
+              endpointId: "anthropic",
+              model: "claude-sonnet",
+              source: "byok",
+              capabilities: ["memory_summary", "memory_evolution"],
+              custom: true
+            }
+          ]
+        },
+        {
+          provider: "openai",
+          endpoints: [{
+            endpointId: "chat",
+            apiBase: "https://api.openai.com/v1",
+            protocol: "openai-chat-completions",
+            apiKey: "sk-shared"
+          }],
+          models: [{
+            endpointId: "chat",
+            model: "gpt-official",
+            source: "byok",
+            capabilities: ["agent"]
+          }]
+        }
+      ],
+      modelAssignments: emptyAssignments()
+    });
+    expect(saved.providers.map((provider) => provider.provider).sort()).toEqual(["custom", "openai"]);
+
+    const anthropicId = saved.providers
+      .find((provider) => provider.provider === "custom")!
+      .models.find((model) => model.model === "claude-sonnet")!
+      .presetId;
+    const officialId = saved.providers
+      .find((provider) => provider.provider === "openai")!
+      .models[0]!.presetId;
+    const assigned = await writeModelConfigCatalog(file, {
+      configRevision: saved.configRevision,
+      providers: saved.providers.map((provider) => ({
+        provider: provider.provider,
+        endpoints: provider.endpoints.map((endpoint) => ({
+          endpointId: endpoint.endpointId,
+          apiBase: endpoint.apiBase,
+          protocol: endpoint.protocol,
+          ...(provider.provider === "custom" && endpoint.protocol === "openai-chat-completions" ? { apiKey: "sk-shared" } : {}),
+          ...(endpoint.protocol === "anthropic-messages" ? { apiKey: "sk-anthropic" } : {}),
+          ...(provider.provider === "openai" ? { apiKey: "sk-shared" } : {})
+        })),
+        models: provider.models.map((model) => ({
+          presetId: model.presetId,
+          endpointId: model.endpointId,
+          model: model.model,
+          source: model.source,
+          capabilities: [...model.capabilities],
+          ...(model.custom ? { custom: true } : {})
+        }))
+      })),
+      modelAssignments: {
+        ...emptyAssignments(),
+        byok: {
+          ...emptyAssignment(),
+          agent: { candidates: [officialId], default: officialId },
+          memoryEvolution: anthropicId
+        }
+      }
+    });
+    expect(assigned.providers.find((provider) => provider.provider === "custom")?.models).toHaveLength(2);
+    expect((YAML.parse(readFileSync(file, "utf8")) as any).memmyMemory.evolution.provider).toBe("anthropic");
+  });
+
   it("round-trips StepFun and Xiaomi MiMo connections back into the view", async () => {
     const file = fixture({ modelAssignments: emptyAssignments() });
     const current = await readModelConfigCatalog(file);
diff --git a/App/frontend/desktop/src/pages/model-workspace-section.tsx b/App/frontend/desktop/src/pages/model-workspace-section.tsx
index 916328ae4..a80115715 100644
--- a/App/frontend/desktop/src/pages/model-workspace-section.tsx
+++ b/App/frontend/desktop/src/pages/model-workspace-section.tsx
@@ -1613,12 +1613,8 @@ export function protocolFromConnection(provider: string): Protocol {
   return "openai";
 }
 
-export function catalogProviderForEditor(provider: Protocol, customProtocol: CustomProtocol | null): string {
-  if (provider === "custom") {
-    if (customProtocol === "anthropic-messages") return "anthropic";
-    if (customProtocol === "bedrock-converse") return "bedrock";
-    return "openai";
-  }
+export function catalogProviderForEditor(provider: Protocol, _customProtocol: CustomProtocol | null): string {
+  if (provider === "custom") return "custom";
   if (provider === "openai_responses") return "openai";
   return fromProtocol(provider) === "kimi" ? "moonshot" : fromProtocol(provider);
 }
diff --git a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
index 1c9a6f7da..543fb1de4 100644
--- a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
@@ -111,11 +111,11 @@ describe("多 BYOK endpoint 入口", () => {
 });
 
 describe("Custom 与 OpenAI Responses 的 catalog provider 推导", () => {
-  it("Custom 按底层协议落到 openai/anthropic/bedrock，而不是 custom", () => {
-    expect(catalogProviderForEditor("custom", "openai-chat-completions")).toBe("openai");
-    expect(catalogProviderForEditor("custom", "openai-responses")).toBe("openai");
-    expect(catalogProviderForEditor("custom", "anthropic-messages")).toBe("anthropic");
-    expect(catalogProviderForEditor("custom", "bedrock-converse")).toBe("bedrock");
+  it("Custom 按供应商 custom 保存，协议留在端点上", () => {
+    expect(catalogProviderForEditor("custom", "openai-chat-completions")).toBe("custom");
+    expect(catalogProviderForEditor("custom", "openai-responses")).toBe("custom");
+    expect(catalogProviderForEditor("custom", "anthropic-messages")).toBe("custom");
+    expect(catalogProviderForEditor("custom", "bedrock-converse")).toBe("custom");
     expect(catalogProviderForEditor("openai_responses", null)).toBe("openai");
     expect(catalogProviderForEditor("moonshot", null)).toBe("moonshot");
   });
diff --git a/App/frontend/desktop/src/state/model-workspace.ts b/App/frontend/desktop/src/state/model-workspace.ts
index a3558bc77..162b93697 100644
--- a/App/frontend/desktop/src/state/model-workspace.ts
+++ b/App/frontend/desktop/src/state/model-workspace.ts
@@ -785,7 +785,7 @@ function normalizeProvider(provider: string): CatalogProviderId | null {
     openai_responses: "openai"
   };
   const candidate = aliases[normalized] ?? normalized;
-  return ["openai", "anthropic", "gemini", "deepseek", "zhipu", "dashscope", "moonshot", "minimax", "qianfan", "volcengine", "stepfun", "xiaomi_mimo", "memmy_account", "bedrock"].includes(candidate)
+  return ["openai", "anthropic", "gemini", "deepseek", "zhipu", "dashscope", "moonshot", "minimax", "qianfan", "volcengine", "stepfun", "xiaomi_mimo", "memmy_account", "bedrock", "custom"].includes(candidate)
     ? candidate as CatalogProviderId
     : null;
 }
diff --git a/App/frontend/desktop/src/state/tests/model-workspace.test.ts b/App/frontend/desktop/src/state/tests/model-workspace.test.ts
index 37a93ada8..ebf1f7fd2 100644
--- a/App/frontend/desktop/src/state/tests/model-workspace.test.ts
+++ b/App/frontend/desktop/src/state/tests/model-workspace.test.ts
@@ -1092,7 +1092,7 @@ describe("canonical model workspace adapter", () => {
     const file = catalogFixture();
     const empty = await readModelConfigCatalog(file);
     const created = upsertModelConnection(createModelWorkspace(empty), "byok", {
-      provider: "bedrock",
+      provider: "custom",
       endpoint: "https://bedrock-runtime.us-west-2.amazonaws.com",
       protocol: "bedrock-converse",
       region: "us-west-2",
@@ -1119,7 +1119,7 @@ describe("canonical model workspace adapter", () => {
       write: (input) => writeModelConfigCatalog(file, input)
     });
     const reloaded = createModelWorkspace(saved);
-    const connection = reloaded.spaces.byok.connections.find((item) => item.provider === "bedrock")!;
+    const connection = reloaded.spaces.byok.connections.find((item) => item.provider === "custom")!;
     const entry = connection.modelEntries[0]!;
     const candidate = getTaskModelCandidates(reloaded, "byok").find((item) => item.model === "anthropic.claude-sonnet-5")!;
 
@@ -1135,7 +1135,7 @@ describe("canonical model workspace adapter", () => {
     expect(entry.inputModalities).toEqual(["text", "image"]);
     expect(isCustomModelEntry(reloaded, candidate)).toBe(true);
     expect(resolveThinkingConfigForModel(reloaded, candidate)).toEqual(entry.thinking);
-    expect(saved.providers.find((provider) => provider.provider === "bedrock")?.models[0]).toMatchObject({
+    expect(saved.providers.find((provider) => provider.provider === "custom")?.models[0]).toMatchObject({
       custom: true,
       inputModalities: ["text", "image"]
     });
diff --git a/App/memmy-agent/src/providers/factory.ts b/App/memmy-agent/src/providers/factory.ts
index 85518bc39..cc6ac81b3 100644
--- a/App/memmy-agent/src/providers/factory.ts
+++ b/App/memmy-agent/src/providers/factory.ts
@@ -72,6 +72,12 @@ function mergedRecord(
   return { ...(defaults ?? {}), ...(overrides ?? {}) };
 }
 
+function backendForCustomProtocol(protocol: string | undefined): ProviderSpec["backend"] {
+  if (protocol === "anthropic-messages") return "anthropic";
+  if (protocol === "bedrock-converse") return "bedrock";
+  return "openai_compat";
+}
+
 function exactEndpoint(
   config: Config,
   providerConfig: ProviderConfig | null,
@@ -100,7 +106,9 @@ function makeProviderCore(
   const providerConfig = config.getProvider(model, { preset: resolved });
   const endpoint = exactEndpoint(config, providerConfig, resolved);
   const spec = providerName ? findByName(providerName) : null;
-  const backend = spec?.backend ?? "openai_compat";
+  const backend = providerName === "custom"
+    ? backendForCustomProtocol(endpoint?.protocol)
+    : spec?.backend ?? "openai_compat";
   const init = providerInit(config, providerConfig, spec, model, resolved);
 
   if (opts.validateCredentials !== false && backend === "azure_openai") {
diff --git a/App/memmy-agent/src/providers/openai-compat-provider.ts b/App/memmy-agent/src/providers/openai-compat-provider.ts
index 7b9b72d9b..5865f98a0 100644
--- a/App/memmy-agent/src/providers/openai-compat-provider.ts
+++ b/App/memmy-agent/src/providers/openai-compat-provider.ts
@@ -135,7 +135,8 @@ export class OpenAICompatProvider extends LLMProvider {
     }
 
     this.defaultModel = this.model ?? "gpt-4o";
-    if (this.apiType !== "auto" && specName(this.spec) !== "openai") {
+    const name = specName(this.spec);
+    if (this.apiType !== "auto" && name !== "openai" && name !== "custom") {
       this.apiType = "auto";
     }
     if (this.apiKey && this.spec?.envKey) this.setupEnv(this.apiKey, this.apiBase);
diff --git a/App/memmy-agent/tests/providers/custom-provider.test.ts b/App/memmy-agent/tests/providers/custom-provider.test.ts
index 3e58c2a76..bfe025447 100644
--- a/App/memmy-agent/tests/providers/custom-provider.test.ts
+++ b/App/memmy-agent/tests/providers/custom-provider.test.ts
@@ -1,5 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { Config } from "../../src/config/schema.js";
+import { AnthropicProvider } from "../../src/providers/anthropic-provider.js";
+import { BedrockProvider } from "../../src/providers/bedrock-provider.js";
 import { makeProvider } from "../../src/providers/factory.js";
 import { OpenAICompatProvider } from "../../src/providers/openai-compat-provider.js";
 import { findByName } from "../../src/providers/registry.js";
@@ -47,6 +49,17 @@ describe("custom provider", () => {
     } } } })).toThrow();
   });
 
+  it("selects the client from the custom endpoint protocol", () => {
+    const responses = makeProvider(customPresetConfig("openai-responses", "gpt-4o-mini")) as OpenAICompatProvider;
+    const anthropic = makeProvider(customPresetConfig("anthropic-messages", "claude-sonnet"));
+    const bedrock = makeProvider(customPresetConfig("bedrock-converse", "anthropic.claude-sonnet"));
+
+    expect(responses).toBeInstanceOf(OpenAICompatProvider);
+    expect(responses.apiType).toBe("responses");
+    expect(anthropic).toBeInstanceOf(AnthropicProvider);
+    expect(bedrock).toBeInstanceOf(BedrockProvider);
+  });
+
   it("parses empty choices as an error response", () => {
     const provider = new OpenAICompatProvider();
 
@@ -140,3 +153,32 @@ describe("custom provider", () => {
     expect(result.content).toContain("proxy/tunnel");
   });
 });
+
+function customPresetConfig(protocol: string, model: string): Config {
+  return new Config({
+    agents: { defaults: { provider: "custom", model, modelPreset: "chosen" } },
+    providers: {
+      custom: {
+        apiKey: "test-key",
+        endpoints: {
+          chat: {
+            apiBase: protocol === "bedrock-converse"
+              ? "https://bedrock-runtime.us-west-2.amazonaws.com"
+              : "https://example.com/v1",
+            protocol,
+            ...(protocol === "bedrock-converse" ? { region: "us-west-2" } : {})
+          }
+        }
+      }
+    },
+    modelPresets: {
+      chosen: {
+        provider: "custom",
+        endpoint: "chat",
+        model,
+        source: "byok",
+        capabilities: ["agent"]
+      }
+    }
+  });
+}
diff --git a/Memory/src/config/index.ts b/Memory/src/config/index.ts
index 6e9a98627..602f6ef21 100644
--- a/Memory/src/config/index.ts
+++ b/Memory/src/config/index.ts
@@ -894,6 +894,8 @@ function memoryRuntimeProvider(
 ): LlmProviderName {
   if (protocol === "bedrock-converse") return "bedrock";
   if (protocol === "openai-responses") return "openai_responses";
+  if (protocol === "anthropic-messages") return "anthropic";
+  if (protocol === "gemini-generate-content") return "gemini";
   return memoryLlmProvider(provider);
 }
 
diff --git a/Memory/src/config/model-catalog.ts b/Memory/src/config/model-catalog.ts
index 5c92097e2..ee4a959a8 100644
--- a/Memory/src/config/model-catalog.ts
+++ b/Memory/src/config/model-catalog.ts
@@ -150,7 +150,8 @@ function catalogProviderId(connection: Record<string, unknown>): string {
   const provider = aliases[source] ?? source;
   return [
     "openai", "anthropic", "gemini", "deepseek", "zhipu", "dashscope",
-    "moonshot", "minimax", "qianfan", "volcengine", "stepfun", "xiaomi_mimo"
+    "moonshot", "minimax", "qianfan", "volcengine", "stepfun", "xiaomi_mimo",
+    "custom"
   ].includes(provider) ? provider : "openai";
 }
 
diff --git a/Memory/tests/llm-protocol-adapters.test.ts b/Memory/tests/llm-protocol-adapters.test.ts
index 6661bde5b..0de0a1a19 100644
--- a/Memory/tests/llm-protocol-adapters.test.ts
+++ b/Memory/tests/llm-protocol-adapters.test.ts
@@ -1,6 +1,10 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import YAML from "yaml";
 import { resolveAssignedModel, type RuntimeModelCatalog } from "../src/contracts/index.js";
-import type { LlmConfig } from "../src/config/index.js";
+import { loadMemmyConfig, type LlmConfig } from "../src/config/index.js";
 import { createLlmClient } from "../src/model/llm.js";
 import type { LlmMessage } from "../src/model/types.js";
 
@@ -80,6 +84,51 @@ describe("memory protocol adapters", () => {
       inferenceConfig: { maxTokens: 700 }
     });
   });
+
+  it("runs a custom Anthropic Messages preset through the Anthropic memory runtime", () => {
+    const root = mkdtempSync(join(tmpdir(), "memmy-custom-anthropic-"));
+    const file = join(root, "config.yaml");
+    writeFileSync(file, YAML.stringify({
+      app: { userMode: "byok" },
+      providers: {
+        custom: {
+          endpoints: {
+            chat: {
+              apiBase: "https://api.anthropic.com/v1",
+              protocol: "anthropic-messages",
+              apiKey: "sk-anthropic"
+            }
+          }
+        }
+      },
+      modelPresets: {
+        "memory-model": {
+          provider: "custom",
+          endpoint: "chat",
+          model: "claude-sonnet",
+          source: "byok",
+          capabilities: ["agent", "memory_summary", "memory_evolution"]
+        }
+      },
+      modelAssignments: {
+        byok: {
+          agent: { candidates: ["memory-model"], default: "memory-model" }
+        }
+      },
+      memmyMemory: {
+        roleRouting: { summary: "follow", evolution: "follow" }
+      }
+    }), "utf8");
+
+    try {
+      const { config } = loadMemmyConfig(file);
+      expect(config.evolution.provider).toBe("anthropic");
+      expect(config.evolution.model).toBe("claude-sonnet");
+      expect(config.evolution.endpoint).toBe("https://api.anthropic.com/v1");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
 });
 
 function catalog(protocol: "openai-responses" | "bedrock-converse"): RuntimeModelCatalog {

From 776753b500be656e67b51ae7036300130c1ac4c5 Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Tue, 29 Sep 2026 20:27:45 +0800
Subject: [PATCH 08/85] Let Custom connection tests follow the selected
 protocol.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 App/backend/local-api-contracts/src/index.ts  |   9 +-
 .../src/services/model-config-tester.ts       |  27 +++--
 .../tests/model-config-tester.test.ts         | 105 ++++++++++++++++++
 .../src/tests/local-app-contracts.test.ts     |   8 ++
 App/frontend/desktop/src/api/config-client.ts |   2 +-
 .../src/api/tests/config-client.test.ts       |  43 +++++++
 6 files changed, 182 insertions(+), 12 deletions(-)

diff --git a/App/backend/local-api-contracts/src/index.ts b/App/backend/local-api-contracts/src/index.ts
index 66d746787..09ade9431 100644
--- a/App/backend/local-api-contracts/src/index.ts
+++ b/App/backend/local-api-contracts/src/index.ts
@@ -731,6 +731,13 @@ export const ModelProviderSchema = z.enum([
 ]);
 export type ModelProvider = z.infer<typeof ModelProviderSchema>;
 
+/** Connection tests accept the catalog provider custom. Role model config stays on ModelProviderSchema. */
+export const ModelConfigTestProviderSchema = z.union([
+    ModelProviderSchema,
+    z.literal("custom")
+]);
+export type ModelConfigTestProvider = z.infer<typeof ModelConfigTestProviderSchema>;
+
 export const CatalogProviderIdSchema = z.enum([
     "openai",
     "anthropic",
@@ -977,7 +984,7 @@ export type ModelConfigInput = z.infer<typeof ModelConfigInputSchema>;
 
 /** Definition for model config test input. */
 export const ModelConfigTestInputSchema = z.object({
-    provider: ModelProviderSchema,
+    provider: ModelConfigTestProviderSchema,
     endpointId: z.string().trim().min(1),
     protocol: ModelEndpointProtocolSchema,
     apiBase: z.string().url(),
diff --git a/App/backend/src/services/model-config-tester.ts b/App/backend/src/services/model-config-tester.ts
index 84aaf87f2..064522b23 100644
--- a/App/backend/src/services/model-config-tester.ts
+++ b/App/backend/src/services/model-config-tester.ts
@@ -2,8 +2,7 @@
 import type {
   ModelConfigTestInput,
   ModelConfigTestResult,
-  ModelEndpointProtocol,
-  ModelProvider
+  ModelEndpointProtocol
 } from "@memmy/local-api-contracts";
 
 type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
@@ -56,7 +55,7 @@ export function createHttpModelConfigTester(options: CreateHttpModelConfigTester
           return result(
             false,
             response.status === 404
-              ? appendBaseUrlGuidance(errorMessage, input.provider)
+              ? appendBaseUrlGuidance(errorMessage, input.protocol)
               : errorMessage,
             now
           );
@@ -68,7 +67,7 @@ export function createHttpModelConfigTester(options: CreateHttpModelConfigTester
           return result(false, redactSecret(providerError, input.apiKey), now);
         }
         if (!probe.isValidBody(body)) {
-          return result(false, appendBaseUrlGuidance(INVALID_SUCCESS_BODY_MESSAGE, input.provider), now);
+          return result(false, appendBaseUrlGuidance(INVALID_SUCCESS_BODY_MESSAGE, input.protocol), now);
         }
 
         const modelListed = probe.listedModels(body).some((model) => model === input.modelId);
@@ -156,16 +155,24 @@ function resourceUrl(apiBase: string, resource: string): string {
   return `${apiBase.replace(/\/+$/u, "")}/${resource}`;
 }
 
-function baseUrlGuidance(provider: ModelProvider): string {
-  if (provider === "anthropic") {
+function baseUrlGuidance(protocol: ModelEndpointProtocol): string {
+  if (protocol === "anthropic-messages") {
     return "Anthropic API 地址通常不包含 /v1，例如 https://api.anthropic.com";
   }
-  if (provider === "google") return "";
-  return "OpenAI 兼容 API 地址通常以 /v1 结尾，例如 https://api.openai.com/v1";
+  if (protocol === "gemini-generate-content") return "";
+  if (
+    protocol === "openai-chat-completions"
+    || protocol === "openai-responses"
+    || protocol === "openai-embeddings"
+    || protocol === "openai-images"
+  ) {
+    return "OpenAI 兼容 API 地址通常以 /v1 结尾，例如 https://api.openai.com/v1";
+  }
+  return "";
 }
 
-function appendBaseUrlGuidance(message: string, provider: ModelProvider): string {
-  const hint = baseUrlGuidance(provider);
+function appendBaseUrlGuidance(message: string, protocol: ModelEndpointProtocol): string {
+  const hint = baseUrlGuidance(protocol);
   if (!hint) return message;
   return `${message.replace(/[。\.\s]+$/u, "")}。${hint}`;
 }
diff --git a/App/backend/src/services/tests/model-config-tester.test.ts b/App/backend/src/services/tests/model-config-tester.test.ts
index dcd087bf8..d4c0029bd 100644
--- a/App/backend/src/services/tests/model-config-tester.test.ts
+++ b/App/backend/src/services/tests/model-config-tester.test.ts
@@ -177,6 +177,111 @@ describe("model config tester", () => {
     expect(JSON.stringify(response)).not.toContain("sk-secret");
   });
 
+  it.each([
+    ["openai-chat-completions", "https://api.example.test/v1/models", { Authorization: "Bearer sk-secret" }],
+    ["openai-responses", "https://api.example.test/v1/models", { Authorization: "Bearer sk-secret" }]
+  ] as Array<[ModelEndpointProtocol, string, Record<string, string>]>)(
+    "probes custom %s with the OpenAI model list",
+    async (protocol, url, headers) => {
+      const calls: Array<{ url: string; init: RequestInit }> = [];
+      const tester = createHttpModelConfigTester({
+        fetch: async (request, init) => {
+          calls.push({ url: request.toString(), init: init ?? {} });
+          return json({ data: [{ id: "model-a" }] });
+        }
+      });
+
+      await tester.test(input({
+        provider: "custom",
+        protocol,
+        apiBase: "https://api.example.test/v1"
+      }));
+
+      expect(calls[0]).toMatchObject({ url, init: { method: "GET", headers } });
+    }
+  );
+
+  it("probes custom Anthropic Messages with the Anthropic model list", async () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const tester = createHttpModelConfigTester({
+      fetch: async (request, init) => {
+        calls.push({ url: request.toString(), init: init ?? {} });
+        return json({ data: [{ id: "model-a" }] });
+      }
+    });
+
+    await tester.test(input({
+      provider: "custom",
+      protocol: "anthropic-messages",
+      apiBase: "https://api.anthropic.com"
+    }));
+
+    expect(calls[0]).toMatchObject({
+      url: "https://api.anthropic.com/v1/models",
+      init: {
+        method: "GET",
+        headers: {
+          "x-api-key": "sk-secret",
+          "anthropic-version": "2023-06-01"
+        }
+      }
+    });
+  });
+
+  it("probes custom Gemini with the Gemini model list", async () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const tester = createHttpModelConfigTester({
+      fetch: async (request, init) => {
+        calls.push({ url: request.toString(), init: init ?? {} });
+        return json({ models: [{ name: "models/model-a" }] });
+      }
+    });
+
+    await tester.test(input({
+      provider: "custom",
+      protocol: "gemini-generate-content",
+      apiBase: "https://generativelanguage.googleapis.com/v1beta"
+    }));
+
+    expect(calls[0]).toMatchObject({
+      url: "https://generativelanguage.googleapis.com/v1beta/models",
+      init: { method: "GET", headers: { "x-goog-api-key": "sk-secret" } }
+    });
+  });
+
+  it("does not probe custom Bedrock Converse", async () => {
+    const fetch = vi.fn();
+    const tester = createHttpModelConfigTester({ now: () => checkedAt, fetch });
+
+    await expect(tester.test(input({
+      provider: "custom",
+      protocol: "bedrock-converse",
+      apiBase: "https://bedrock-runtime.us-west-2.amazonaws.com"
+    }))).resolves.toEqual({
+      ok: false,
+      message: "当前 endpoint 协议不支持模型列表连接测试",
+      checkedAt
+    });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("uses the selected protocol for custom failure hints", async () => {
+    const tester = createHttpModelConfigTester({
+      now: () => checkedAt,
+      fetch: async () => json({ error: { message: "not found" } }, 404)
+    });
+
+    const openai = await tester.test(input({ provider: "custom", protocol: "openai-chat-completions" }));
+    const anthropic = await tester.test(input({
+      provider: "custom",
+      protocol: "anthropic-messages",
+      apiBase: "https://api.anthropic.com"
+    }));
+
+    expect(openai.message).toContain("OpenAI 兼容 API 地址通常以 /v1 结尾");
+    expect(anthropic.message).toContain("Anthropic API 地址通常不包含 /v1");
+  });
+
   it("keeps actionable Base URL guidance on 404", async () => {
     const tester = createHttpModelConfigTester({
       now: () => checkedAt,
diff --git a/App/backend/src/tests/local-app-contracts.test.ts b/App/backend/src/tests/local-app-contracts.test.ts
index 6a0623f62..69d779506 100644
--- a/App/backend/src/tests/local-app-contracts.test.ts
+++ b/App/backend/src/tests/local-app-contracts.test.ts
@@ -52,6 +52,7 @@ describe("local app contracts", () => {
   it("accepts StepFun and Xiaomi as text providers and canonicalises their catalog ids", () => {
     expect(ModelProviderSchema.safeParse("stepfun").success).toBe(true);
     expect(ModelProviderSchema.safeParse("xiaomi").success).toBe(true);
+    expect(ModelProviderSchema.safeParse("custom").success).toBe(false);
 
     expect(canonicalCatalogProviderId("stepfun")).toBe("stepfun");
     expect(canonicalCatalogProviderId("xiaomi")).toBe("xiaomi_mimo");
@@ -409,6 +410,13 @@ describe("local app contracts", () => {
 
     expect(input.modelId).toBe("gpt-5.5");
     expect(asrInput.capability).toBe("asr");
+    expect(ModelConfigTestInputSchema.safeParse({
+      provider: "custom",
+      endpointId: "chat",
+      protocol: "openai-chat-completions",
+      apiBase: "https://api.example.test/v1",
+      modelId: "gpt-6-sol"
+    }).success).toBe(true);
 
     const result = ModelConfigTestResultSchema.parse({
       ok: false,
diff --git a/App/frontend/desktop/src/api/config-client.ts b/App/frontend/desktop/src/api/config-client.ts
index c643a54f6..95d05a157 100644
--- a/App/frontend/desktop/src/api/config-client.ts
+++ b/App/frontend/desktop/src/api/config-client.ts
@@ -264,7 +264,7 @@ export function createHttpConfigClient(config: RuntimeConfig): ConfigClient {
         path: "/api/app/model-config/test",
         schema: ModelConfigTestResultSchema,
         body: ModelConfigTestInputSchema.parse({
-          provider: toModelProvider(modelConfig.provider),
+          provider: modelConfig.provider === "custom" ? "custom" : toModelProvider(modelConfig.provider),
           endpointId: modelConfig.endpointId ?? `connection-test-${secretTarget ?? capability}`,
           protocol: modelConfig.protocol ?? testProtocolFor(modelConfig.provider, capability),
           apiBase: modelConfig.endpoint,
diff --git a/App/frontend/desktop/src/api/tests/config-client.test.ts b/App/frontend/desktop/src/api/tests/config-client.test.ts
index eae3aa81a..dd157227b 100644
--- a/App/frontend/desktop/src/api/tests/config-client.test.ts
+++ b/App/frontend/desktop/src/api/tests/config-client.test.ts
@@ -249,6 +249,49 @@ describe("config-client canonical model catalog", () => {
     });
     expect(result.ok).toBe(true);
   });
+
+  it("keeps custom as the test provider and probes by the selected protocol", async () => {
+    const bodies: any[] = [];
+    vi.stubGlobal("fetch", vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
+      bodies.push(JSON.parse(String(init?.body)));
+      return jsonResponse({ ok: true, message: "ok", checkedAt: "2026-08-11T00:00:00.000Z" });
+    }));
+    const client = createHttpConfigClient(config);
+
+    await client.testModelConfig({
+      provider: "custom",
+      endpointId: "chat",
+      protocol: "openai-chat-completions",
+      endpoint: "https://api.example.test/v1",
+      model: "gpt-6-sol",
+      apiKey: "sk-live",
+      apiKeyMasked: "",
+      configured: true
+    });
+    await client.testModelConfig({
+      provider: "custom",
+      endpointId: "messages",
+      protocol: "anthropic-messages",
+      endpoint: "https://api.anthropic.com",
+      model: "claude-sonnet",
+      apiKey: "sk-live",
+      apiKeyMasked: "",
+      configured: true
+    });
+
+    expect(bodies[0]).toMatchObject({
+      provider: "custom",
+      protocol: "openai-chat-completions",
+      apiBase: "https://api.example.test/v1",
+      modelId: "gpt-6-sol"
+    });
+    expect(bodies[1]).toMatchObject({
+      provider: "custom",
+      protocol: "anthropic-messages",
+      apiBase: "https://api.anthropic.com",
+      modelId: "claude-sonnet"
+    });
+  });
 });
 
 function catalog(configRevision: string): ModelConfigView {

From a1fae2a421c16567c3db1e004efb22772b460593 Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Tue, 29 Sep 2026 20:59:15 +0800
Subject: [PATCH 09/85] Send max_completion_tokens for newer OpenAI model names
 on Custom Chat Completions.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../src/providers/custom-provider.ts          |  6 ++++
 .../src/providers/openai-compat-provider.ts   |  5 ++-
 .../tests/providers/custom-provider.test.ts   | 31 +++++++++++++++++++
 3 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 App/memmy-agent/src/providers/custom-provider.ts

diff --git a/App/memmy-agent/src/providers/custom-provider.ts b/App/memmy-agent/src/providers/custom-provider.ts
new file mode 100644
index 000000000..ad6ceb00b
--- /dev/null
+++ b/App/memmy-agent/src/providers/custom-provider.ts
@@ -0,0 +1,6 @@
+const MAX_COMPLETION_TOKEN_MARKERS = ["gpt-5", "gpt-6", "o1", "o3", "o4"] as const;
+
+export function customModelUsesMaxCompletionTokens(modelName: string): boolean {
+  const name = modelName.toLowerCase();
+  return MAX_COMPLETION_TOKEN_MARKERS.some((marker) => name.includes(marker));
+}
diff --git a/App/memmy-agent/src/providers/openai-compat-provider.ts b/App/memmy-agent/src/providers/openai-compat-provider.ts
index 5865f98a0..b62c6b5a4 100644
--- a/App/memmy-agent/src/providers/openai-compat-provider.ts
+++ b/App/memmy-agent/src/providers/openai-compat-provider.ts
@@ -15,6 +15,7 @@ import {
   convertTools,
   parseResponseOutput,
 } from "./openai-responses/index.js";
+import { customModelUsesMaxCompletionTokens } from "./custom-provider.js";
 import { memmyAccountNoneThinkingStyle } from "./memmy-account.js";
 import { getModelInputModalities } from "./model-input-capabilities.js";
 import { OPENROUTER_ATTRIBUTION_HEADERS } from "./openrouter-attribution.js";
@@ -608,7 +609,9 @@ export class OpenAICompatProvider extends LLMProvider {
 
     if (OpenAICompatProvider.supportsTemperature(modelName, reasoningEffort))
       kwargs.temperature = temperature;
-    if (this.spec?.supportsMaxCompletionTokens) kwargs.max_completion_tokens = maxTokens;
+    const useMaxCompletionTokens = Boolean(this.spec?.supportsMaxCompletionTokens)
+      || (specName(this.spec) === "custom" && customModelUsesMaxCompletionTokens(modelName));
+    if (useMaxCompletionTokens) kwargs.max_completion_tokens = maxTokens;
     else kwargs.max_tokens = maxTokens;
 
     for (const [pattern, overrides] of this.spec?.modelOverrides ?? []) {
diff --git a/App/memmy-agent/tests/providers/custom-provider.test.ts b/App/memmy-agent/tests/providers/custom-provider.test.ts
index bfe025447..02e783daa 100644
--- a/App/memmy-agent/tests/providers/custom-provider.test.ts
+++ b/App/memmy-agent/tests/providers/custom-provider.test.ts
@@ -3,6 +3,7 @@ import { Config } from "../../src/config/schema.js";
 import { AnthropicProvider } from "../../src/providers/anthropic-provider.js";
 import { BedrockProvider } from "../../src/providers/bedrock-provider.js";
 import { makeProvider } from "../../src/providers/factory.js";
+import { customModelUsesMaxCompletionTokens } from "../../src/providers/custom-provider.js";
 import { OpenAICompatProvider } from "../../src/providers/openai-compat-provider.js";
 import { findByName } from "../../src/providers/registry.js";
 
@@ -49,6 +50,23 @@ describe("custom provider", () => {
     } } } })).toThrow();
   });
 
+  it("uses max_completion_tokens for newer OpenAI model names", () => {
+    expect(customModelUsesMaxCompletionTokens("gpt-6-sol")).toBe(true);
+    expect(customModelUsesMaxCompletionTokens("gpt-5.4")).toBe(true);
+    expect(customModelUsesMaxCompletionTokens("deepseek-v4")).toBe(false);
+    expect(customModelUsesMaxCompletionTokens("qwen-max")).toBe(false);
+  });
+
+  it("sends max_completion_tokens only for matching custom chat models", () => {
+    const gpt = chatKwargs("gpt-6-sol");
+    const qwen = chatKwargs("qwen-max");
+
+    expect(gpt.max_completion_tokens).toBe(1024);
+    expect(gpt).not.toHaveProperty("max_tokens");
+    expect(qwen.max_tokens).toBe(1024);
+    expect(qwen).not.toHaveProperty("max_completion_tokens");
+  });
+
   it("selects the client from the custom endpoint protocol", () => {
     const responses = makeProvider(customPresetConfig("openai-responses", "gpt-4o-mini")) as OpenAICompatProvider;
     const anthropic = makeProvider(customPresetConfig("anthropic-messages", "claude-sonnet"));
@@ -154,6 +172,19 @@ describe("custom provider", () => {
   });
 });
 
+function chatKwargs(model: string): Record<string, unknown> {
+  const provider = new OpenAICompatProvider("test-key", "https://example.com/v1", model, findByName("custom"));
+  return provider.buildKwargs({
+    messages: [{ role: "user", content: "hi" }],
+    tools: null,
+    model,
+    maxTokens: 1024,
+    temperature: 0.7,
+    reasoningEffort: null,
+    toolChoice: null,
+  });
+}
+
 function customPresetConfig(protocol: string, model: string): Config {
   return new Config({
     agents: { defaults: { provider: "custom", model, modelPreset: "chosen" } },

From f37f21fc2e4e56b8b64f57b0cb08e487c17f72c4 Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Wed, 30 Sep 2026 11:03:34 +0800
Subject: [PATCH 10/85] Hide thinking for OpenAI Chat Completions on newer
 reasoning models, and warn Custom users to turn it off.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 App/frontend/desktop/src/i18n/messages.ts     |  4 +-
 .../src/pages/tests/settings-page.test.tsx    | 11 ++++-
 .../desktop/src/state/model-workspace.ts      | 25 +++++++++++
 .../src/state/tests/model-workspace.test.ts   | 29 ++++++++++++-
 .../src/providers/openai-compat-provider.ts   |  7 ++-
 .../tests/providers/custom-provider.test.ts   | 18 ++++++--
 .../tests/providers/openai-responses.test.ts  | 43 +++++++++++++++++++
 7 files changed, 129 insertions(+), 8 deletions(-)

diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index aa4178b4c..a0b30b16c 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -1552,7 +1552,7 @@ export const zhCNMessages = {
   "settings.modelWorkspace.region": "区域",
   "settings.modelWorkspace.regionPlaceholder": "例如：us-east-1",
   "settings.modelWorkspace.customThinkingEnabled": "支持思考",
-  "settings.modelWorkspace.customThinkingEnabledHint": "勾选后，输入框可以设置思考。不勾选则不传思考参数，由模型接口按默认行为处理。",
+  "settings.modelWorkspace.customThinkingEnabledHint": "勾选后，输入框可以设置思考。不勾选则不传思考参数，由模型接口按默认行为处理。使用 Chat Completions 并且使用 gpt 模型时，请关闭支持思考，否则可能导致错误。",
   "settings.modelWorkspace.customThinkingSwitchable": "可关闭思考",
   "settings.modelWorkspace.customThinkingSwitchableHint": "勾选后，对话里可以临时关闭思考。不勾选则思考始终开启，输入框不显示思考开关。",
   "settings.modelWorkspace.customThinkingDefaultEnabled": "默认开启思考",
@@ -3323,7 +3323,7 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "settings.modelWorkspace.region": "Region",
   "settings.modelWorkspace.regionPlaceholder": "For example: us-east-1",
   "settings.modelWorkspace.customThinkingEnabled": "Supports thinking",
-  "settings.modelWorkspace.customThinkingEnabledHint": "When checked, the composer can set thinking. When unchecked, no thinking parameters are sent and the model endpoint uses its default behavior.",
+  "settings.modelWorkspace.customThinkingEnabledHint": "When checked, the composer can set thinking. When unchecked, no thinking parameters are sent and the model endpoint uses its default behavior. When using Chat Completions with a GPT model, turn off Supports thinking, or the request may fail.",
   "settings.modelWorkspace.customThinkingSwitchable": "Thinking can be turned off",
   "settings.modelWorkspace.customThinkingSwitchableHint": "When checked, a conversation can turn thinking off. When unchecked, thinking stays on and the composer hides the thinking switch.",
   "settings.modelWorkspace.customThinkingDefaultEnabled": "Thinking on by default",
diff --git a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
index 543fb1de4..f22e844f5 100644
--- a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
@@ -25,7 +25,7 @@ import {
   shouldSaveAccountNicknameOnKeyDown,
   writeLogLevel
 } from "../settings-page.js";
-import { formatMessage, zhCNMessages } from "../../i18n/messages.js";
+import { enUSMessages, formatMessage, zhCNMessages } from "../../i18n/messages.js";
 import {
   availableConnectionProtocols,
   catalogProviderForEditor,
@@ -225,6 +225,15 @@ describe("自定义模型能力选择", () => {
     expect(source).not.toContain('t("settings.modelWorkspace.textRoles")');
     expect(source).not.toContain('t("settings.modelWorkspace.capability.agent")');
   });
+
+  it("支持思考的说明提醒 Chat Completions 的 gpt 模型关掉思考", () => {
+    expect(zhCNMessages["settings.modelWorkspace.customThinkingEnabledHint"]).toContain(
+      "使用 Chat Completions 并且使用 gpt 模型时，请关闭支持思考，否则可能导致错误。"
+    );
+    expect(enUSMessages["settings.modelWorkspace.customThinkingEnabledHint"]).toContain(
+      "When using Chat Completions with a GPT model, turn off Supports thinking, or the request may fail."
+    );
+  });
 });
 
 describe("日志级别本地持久化", () => {
diff --git a/App/frontend/desktop/src/state/model-workspace.ts b/App/frontend/desktop/src/state/model-workspace.ts
index 162b93697..442d97aad 100644
--- a/App/frontend/desktop/src/state/model-workspace.ts
+++ b/App/frontend/desktop/src/state/model-workspace.ts
@@ -974,6 +974,24 @@ export function customThinkingConfigFor(
   return modelEntryFor(workspace, candidate)?.thinking ?? null;
 }
 
+const CHAT_COMPLETIONS_THINKING_MARKERS = ["gpt-5", "gpt-6", "o1", "o3", "o4"] as const;
+
+function endpointProtocolFor(
+  workspace: ModelWorkspace,
+  candidate: ModelCandidate
+): ModelEndpointProtocol | undefined {
+  for (const space of Object.values(workspace.spaces)) {
+    const connection = space.connections.find((item) => item.id === candidate.connectionId);
+    if (connection) return connection.protocol;
+  }
+  return undefined;
+}
+
+function chatCompletionsHidesCatalogThinking(modelName: string): boolean {
+  const name = modelName.toLowerCase();
+  return CHAT_COMPLETIONS_THINKING_MARKERS.some((marker) => name.includes(marker));
+}
+
 export function resolveThinkingConfigForModel(
   workspace: ModelWorkspace,
   candidate: ModelCandidate | null | undefined
@@ -981,5 +999,12 @@ export function resolveThinkingConfigForModel(
   if (isCustomModelEntry(workspace, candidate)) {
     return customThinkingConfigFor(workspace, candidate);
   }
+  if (
+    candidate
+    && endpointProtocolFor(workspace, candidate) === "openai-chat-completions"
+    && chatCompletionsHidesCatalogThinking(candidate.model)
+  ) {
+    return null;
+  }
   return getModelThinkingConfig(candidate?.model);
 }
diff --git a/App/frontend/desktop/src/state/tests/model-workspace.test.ts b/App/frontend/desktop/src/state/tests/model-workspace.test.ts
index ebf1f7fd2..bf59a1ca1 100644
--- a/App/frontend/desktop/src/state/tests/model-workspace.test.ts
+++ b/App/frontend/desktop/src/state/tests/model-workspace.test.ts
@@ -3,8 +3,10 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   BUILTIN_LOCAL_EMBEDDING_ASSIGNMENT_ID,
+  getModelThinkingConfig,
   type ModelConfigInput,
-  type ModelConfigView
+  type ModelConfigView,
+  type ModelEndpointProtocol
 } from "@memmy/local-api-contracts";
 import YAML from "yaml";
 import { afterEach, describe, expect, it } from "vitest";
@@ -1140,4 +1142,29 @@ describe("canonical model workspace adapter", () => {
       inputModalities: ["text", "image"]
     });
   });
+
+  it("OpenAI Chat Completions 的 gpt-6 不提供目录思考，Responses 仍提供", () => {
+    const chat = openaiThinkingWorkspace("openai-chat-completions");
+    const responses = openaiThinkingWorkspace("openai-responses");
+    const chatCandidate = getTaskModelCandidates(chat, "byok").find((item) => item.model === "gpt-6-sol")!;
+    const responsesCandidate = getTaskModelCandidates(responses, "byok").find((item) => item.model === "gpt-6-sol")!;
+
+    expect(resolveThinkingConfigForModel(chat, chatCandidate)).toBeNull();
+    expect(resolveThinkingConfigForModel(responses, responsesCandidate)).toEqual(getModelThinkingConfig("gpt-6-sol"));
+  });
 });
+
+function openaiThinkingWorkspace(protocol: ModelEndpointProtocol) {
+  return upsertModelConnection(createModelWorkspace(null), "byok", {
+    provider: "openai",
+    endpoint: "https://api.openai.com/v1",
+    protocol,
+    apiKey: "sk-test",
+    models: ["gpt-6-sol"],
+    modelEntries: [{
+      model: "gpt-6-sol",
+      capability: "chat",
+      capabilities: ["chat", "memorySummary", "memoryEvolution"]
+    }]
+  }).workspace;
+}
diff --git a/App/memmy-agent/src/providers/openai-compat-provider.ts b/App/memmy-agent/src/providers/openai-compat-provider.ts
index b62c6b5a4..d7eb7fc0f 100644
--- a/App/memmy-agent/src/providers/openai-compat-provider.ts
+++ b/App/memmy-agent/src/providers/openai-compat-provider.ts
@@ -621,7 +621,12 @@ export class OpenAICompatProvider extends LLMProvider {
       }
     }
 
-    if (wireEffort && semanticEffort !== "none") kwargs.reasoning_effort = wireEffort;
+    const omitReasoningEffortForTools = specName(this.spec) === "openai"
+      && Boolean(tools?.length)
+      && customModelUsesMaxCompletionTokens(modelName);
+    if (wireEffort && semanticEffort !== "none" && !omitReasoningEffortForTools) {
+      kwargs.reasoning_effort = wireEffort;
+    }
     if (reasoningEffort !== null) {
       const thinkingEnabled = semanticEffort !== "none" && semanticEffort !== "minimal";
       const styles = thinkingStylesFor(this.spec, modelName);
diff --git a/App/memmy-agent/tests/providers/custom-provider.test.ts b/App/memmy-agent/tests/providers/custom-provider.test.ts
index 02e783daa..aae3e0cb3 100644
--- a/App/memmy-agent/tests/providers/custom-provider.test.ts
+++ b/App/memmy-agent/tests/providers/custom-provider.test.ts
@@ -67,6 +67,15 @@ describe("custom provider", () => {
     expect(qwen).not.toHaveProperty("max_completion_tokens");
   });
 
+  it("keeps reasoning_effort when custom thinking is on", () => {
+    const kwargs = chatKwargs("gpt-6-sol", {
+      reasoningEffort: "medium",
+      tools: [{ type: "function", function: { name: "read_file" } }],
+    });
+
+    expect(kwargs.reasoning_effort).toBe("medium");
+  });
+
   it("selects the client from the custom endpoint protocol", () => {
     const responses = makeProvider(customPresetConfig("openai-responses", "gpt-4o-mini")) as OpenAICompatProvider;
     const anthropic = makeProvider(customPresetConfig("anthropic-messages", "claude-sonnet"));
@@ -172,15 +181,18 @@ describe("custom provider", () => {
   });
 });
 
-function chatKwargs(model: string): Record<string, unknown> {
+function chatKwargs(
+  model: string,
+  overrides: { reasoningEffort?: string | null; tools?: Record<string, unknown>[] | null } = {},
+): Record<string, unknown> {
   const provider = new OpenAICompatProvider("test-key", "https://example.com/v1", model, findByName("custom"));
   return provider.buildKwargs({
     messages: [{ role: "user", content: "hi" }],
-    tools: null,
+    tools: overrides.tools ?? null,
     model,
     maxTokens: 1024,
     temperature: 0.7,
-    reasoningEffort: null,
+    reasoningEffort: overrides.reasoningEffort ?? null,
     toolChoice: null,
   });
 }
diff --git a/App/memmy-agent/tests/providers/openai-responses.test.ts b/App/memmy-agent/tests/providers/openai-responses.test.ts
index 37fc97cab..d2443c1f1 100644
--- a/App/memmy-agent/tests/providers/openai-responses.test.ts
+++ b/App/memmy-agent/tests/providers/openai-responses.test.ts
@@ -569,3 +569,46 @@ describe("OpenAI Responses consumeSdkStream", () => {
     expect(toolCalls[0].arguments).toEqual({ bad: null });
   });
 });
+
+describe("OpenAI chat completions reasoning effort", () => {
+  const tool = [{ type: "function", function: { name: "read_file" } }];
+
+  it("omits reasoning_effort when gpt-6-sol is called with tools", () => {
+    const kwargs = chatKwargs("gpt-6-sol", tool);
+
+    expect(kwargs).not.toHaveProperty("reasoning_effort");
+    expect(kwargs.tools).toEqual(tool);
+  });
+
+  it("keeps reasoning_effort when gpt-6-sol is called without tools", () => {
+    expect(chatKwargs("gpt-6-sol", null).reasoning_effort).toBe("medium");
+  });
+
+  it("keeps reasoning effort on the responses body", () => {
+    const provider = new OpenAICompatProvider("test-key", "https://api.openai.com/v1", "gpt-6-sol", findByName("openai"));
+    const body = provider.buildResponsesBody({
+      messages: [{ role: "user", content: "hi" }],
+      tools: tool,
+      model: "gpt-6-sol",
+      maxTokens: 1024,
+      temperature: 0.7,
+      reasoningEffort: "medium",
+      toolChoice: null,
+    });
+
+    expect(body.reasoning).toEqual({ effort: "medium" });
+  });
+});
+
+function chatKwargs(model: string, tools: Record<string, unknown>[] | null): Record<string, unknown> {
+  const provider = new OpenAICompatProvider("test-key", "https://api.openai.com/v1", model, findByName("openai"));
+  return provider.buildKwargs({
+    messages: [{ role: "user", content: "hi" }],
+    tools,
+    model,
+    maxTokens: 1024,
+    temperature: 0.7,
+    reasoningEffort: "medium",
+    toolChoice: null,
+  });
+}

From 407cf0298240a6292ffbe680f53aba4351a6c4f1 Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Wed, 30 Sep 2026 11:27:29 +0800
Subject: [PATCH 11/85] Send reasoning_effort none for OpenAI Chat Completions
 when newer reasoning models are called with tools.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../src/providers/openai-compat-provider.ts   |  7 +++----
 .../tests/providers/openai-responses.test.ts  | 20 +++++++++++++------
 2 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/App/memmy-agent/src/providers/openai-compat-provider.ts b/App/memmy-agent/src/providers/openai-compat-provider.ts
index d7eb7fc0f..103d85f40 100644
--- a/App/memmy-agent/src/providers/openai-compat-provider.ts
+++ b/App/memmy-agent/src/providers/openai-compat-provider.ts
@@ -621,12 +621,11 @@ export class OpenAICompatProvider extends LLMProvider {
       }
     }
 
-    const omitReasoningEffortForTools = specName(this.spec) === "openai"
+    const forceNoneReasoningEffort = specName(this.spec) === "openai"
       && Boolean(tools?.length)
       && customModelUsesMaxCompletionTokens(modelName);
-    if (wireEffort && semanticEffort !== "none" && !omitReasoningEffortForTools) {
-      kwargs.reasoning_effort = wireEffort;
-    }
+    if (forceNoneReasoningEffort) kwargs.reasoning_effort = "none";
+    else if (wireEffort && semanticEffort !== "none") kwargs.reasoning_effort = wireEffort;
     if (reasoningEffort !== null) {
       const thinkingEnabled = semanticEffort !== "none" && semanticEffort !== "minimal";
       const styles = thinkingStylesFor(this.spec, modelName);
diff --git a/App/memmy-agent/tests/providers/openai-responses.test.ts b/App/memmy-agent/tests/providers/openai-responses.test.ts
index d2443c1f1..c4db8394d 100644
--- a/App/memmy-agent/tests/providers/openai-responses.test.ts
+++ b/App/memmy-agent/tests/providers/openai-responses.test.ts
@@ -573,15 +573,19 @@ describe("OpenAI Responses consumeSdkStream", () => {
 describe("OpenAI chat completions reasoning effort", () => {
   const tool = [{ type: "function", function: { name: "read_file" } }];
 
-  it("omits reasoning_effort when gpt-6-sol is called with tools", () => {
-    const kwargs = chatKwargs("gpt-6-sol", tool);
+  it("sends reasoning_effort none when gpt-6-sol is called with tools", () => {
+    const kwargs = chatKwargs("gpt-6-sol", tool, "medium");
 
-    expect(kwargs).not.toHaveProperty("reasoning_effort");
+    expect(kwargs.reasoning_effort).toBe("none");
     expect(kwargs.tools).toEqual(tool);
   });
 
+  it("sends reasoning_effort none when tools are present and no effort was requested", () => {
+    expect(chatKwargs("gpt-6-astra", tool, null).reasoning_effort).toBe("none");
+  });
+
   it("keeps reasoning_effort when gpt-6-sol is called without tools", () => {
-    expect(chatKwargs("gpt-6-sol", null).reasoning_effort).toBe("medium");
+    expect(chatKwargs("gpt-6-sol", null, "medium").reasoning_effort).toBe("medium");
   });
 
   it("keeps reasoning effort on the responses body", () => {
@@ -600,7 +604,11 @@ describe("OpenAI chat completions reasoning effort", () => {
   });
 });
 
-function chatKwargs(model: string, tools: Record<string, unknown>[] | null): Record<string, unknown> {
+function chatKwargs(
+  model: string,
+  tools: Record<string, unknown>[] | null,
+  reasoningEffort: string | null,
+): Record<string, unknown> {
   const provider = new OpenAICompatProvider("test-key", "https://api.openai.com/v1", model, findByName("openai"));
   return provider.buildKwargs({
     messages: [{ role: "user", content: "hi" }],
@@ -608,7 +616,7 @@ function chatKwargs(model: string, tools: Record<string, unknown>[] | null): Rec
     model,
     maxTokens: 1024,
     temperature: 0.7,
-    reasoningEffort: "medium",
+    reasoningEffort,
     toolChoice: null,
   });
 }

From 85893b7956eab10b69ada399750d7958ea9e448b Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Wed, 30 Sep 2026 11:52:40 +0800
Subject: [PATCH 12/85] Send reasoning_effort none on Chat Completions for any
 GPT or o-series model with tools, including Custom when thinking is off.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../desktop/src/state/model-workspace.ts      |  5 ++-
 .../src/state/tests/model-workspace.test.ts   | 20 ++++++---
 .../src/core/agent-runtime/loop.ts            |  2 +-
 .../src/providers/custom-provider.ts          |  6 +++
 .../src/providers/openai-compat-provider.ts   | 14 +++++--
 .../agent-runtime/thinking-effort.test.ts     |  8 ++++
 .../tests/providers/custom-provider.test.ts   | 41 ++++++++++++++++++-
 .../tests/providers/openai-responses.test.ts  |  1 +
 8 files changed, 85 insertions(+), 12 deletions(-)

diff --git a/App/frontend/desktop/src/state/model-workspace.ts b/App/frontend/desktop/src/state/model-workspace.ts
index 442d97aad..41a3e7dd5 100644
--- a/App/frontend/desktop/src/state/model-workspace.ts
+++ b/App/frontend/desktop/src/state/model-workspace.ts
@@ -974,7 +974,7 @@ export function customThinkingConfigFor(
   return modelEntryFor(workspace, candidate)?.thinking ?? null;
 }
 
-const CHAT_COMPLETIONS_THINKING_MARKERS = ["gpt-5", "gpt-6", "o1", "o3", "o4"] as const;
+const CHAT_COMPLETIONS_O_SERIES_MARKERS = ["o1", "o3", "o4"] as const;
 
 function endpointProtocolFor(
   workspace: ModelWorkspace,
@@ -989,7 +989,8 @@ function endpointProtocolFor(
 
 function chatCompletionsHidesCatalogThinking(modelName: string): boolean {
   const name = modelName.toLowerCase();
-  return CHAT_COMPLETIONS_THINKING_MARKERS.some((marker) => name.includes(marker));
+  return name.includes("gpt-")
+    || CHAT_COMPLETIONS_O_SERIES_MARKERS.some((marker) => name.includes(marker));
 }
 
 export function resolveThinkingConfigForModel(
diff --git a/App/frontend/desktop/src/state/tests/model-workspace.test.ts b/App/frontend/desktop/src/state/tests/model-workspace.test.ts
index bf59a1ca1..2ca7ab61b 100644
--- a/App/frontend/desktop/src/state/tests/model-workspace.test.ts
+++ b/App/frontend/desktop/src/state/tests/model-workspace.test.ts
@@ -1144,25 +1144,35 @@ describe("canonical model workspace adapter", () => {
   });
 
   it("OpenAI Chat Completions 的 gpt-6 不提供目录思考，Responses 仍提供", () => {
-    const chat = openaiThinkingWorkspace("openai-chat-completions");
-    const responses = openaiThinkingWorkspace("openai-responses");
+    const chat = openaiThinkingWorkspace("openai-chat-completions", "gpt-6-sol");
+    const responses = openaiThinkingWorkspace("openai-responses", "gpt-6-sol");
     const chatCandidate = getTaskModelCandidates(chat, "byok").find((item) => item.model === "gpt-6-sol")!;
     const responsesCandidate = getTaskModelCandidates(responses, "byok").find((item) => item.model === "gpt-6-sol")!;
 
     expect(resolveThinkingConfigForModel(chat, chatCandidate)).toBeNull();
     expect(resolveThinkingConfigForModel(responses, responsesCandidate)).toEqual(getModelThinkingConfig("gpt-6-sol"));
   });
+
+  it("OpenAI Chat Completions 的 gpt-4o 不提供目录思考，Responses 仍按目录", () => {
+    const chat = openaiThinkingWorkspace("openai-chat-completions", "gpt-4o");
+    const responses = openaiThinkingWorkspace("openai-responses", "gpt-4o");
+    const chatCandidate = getTaskModelCandidates(chat, "byok").find((item) => item.model === "gpt-4o")!;
+    const responsesCandidate = getTaskModelCandidates(responses, "byok").find((item) => item.model === "gpt-4o")!;
+
+    expect(resolveThinkingConfigForModel(chat, chatCandidate)).toBeNull();
+    expect(resolveThinkingConfigForModel(responses, responsesCandidate)).toEqual(getModelThinkingConfig("gpt-4o"));
+  });
 });
 
-function openaiThinkingWorkspace(protocol: ModelEndpointProtocol) {
+function openaiThinkingWorkspace(protocol: ModelEndpointProtocol, model: string) {
   return upsertModelConnection(createModelWorkspace(null), "byok", {
     provider: "openai",
     endpoint: "https://api.openai.com/v1",
     protocol,
     apiKey: "sk-test",
-    models: ["gpt-6-sol"],
+    models: [model],
     modelEntries: [{
-      model: "gpt-6-sol",
+      model,
       capability: "chat",
       capabilities: ["chat", "memorySummary", "memoryEvolution"]
     }]
diff --git a/App/memmy-agent/src/core/agent-runtime/loop.ts b/App/memmy-agent/src/core/agent-runtime/loop.ts
index 7863308c6..eab9fcbc6 100644
--- a/App/memmy-agent/src/core/agent-runtime/loop.ts
+++ b/App/memmy-agent/src/core/agent-runtime/loop.ts
@@ -707,7 +707,7 @@ export function reasoningEffortFromTurnMetadata(
   model: string | null | undefined,
 ): string | undefined {
   if (typeof metadata?.thinking_enabled !== "boolean") return undefined;
-  const config = getModelThinkingConfig(model);
+  const config = metadata.model_provider === "custom" ? null : getModelThinkingConfig(model);
   const enabled = config && !config.switchable ? true : metadata.thinking_enabled;
   if (!enabled) return "none";
   if (typeof metadata.thinking_level === "string" && metadata.thinking_level.trim()) {
diff --git a/App/memmy-agent/src/providers/custom-provider.ts b/App/memmy-agent/src/providers/custom-provider.ts
index ad6ceb00b..0bccc0023 100644
--- a/App/memmy-agent/src/providers/custom-provider.ts
+++ b/App/memmy-agent/src/providers/custom-provider.ts
@@ -1,6 +1,12 @@
 const MAX_COMPLETION_TOKEN_MARKERS = ["gpt-5", "gpt-6", "o1", "o3", "o4"] as const;
+const O_SERIES_MARKERS = ["o1", "o3", "o4"] as const;
 
 export function customModelUsesMaxCompletionTokens(modelName: string): boolean {
   const name = modelName.toLowerCase();
   return MAX_COMPLETION_TOKEN_MARKERS.some((marker) => name.includes(marker));
 }
+
+export function chatCompletionsModelForcesNoneReasoning(modelName: string): boolean {
+  const name = modelName.toLowerCase();
+  return name.includes("gpt-") || O_SERIES_MARKERS.some((marker) => name.includes(marker));
+}
diff --git a/App/memmy-agent/src/providers/openai-compat-provider.ts b/App/memmy-agent/src/providers/openai-compat-provider.ts
index 103d85f40..72a252ac8 100644
--- a/App/memmy-agent/src/providers/openai-compat-provider.ts
+++ b/App/memmy-agent/src/providers/openai-compat-provider.ts
@@ -15,7 +15,10 @@ import {
   convertTools,
   parseResponseOutput,
 } from "./openai-responses/index.js";
-import { customModelUsesMaxCompletionTokens } from "./custom-provider.js";
+import {
+  chatCompletionsModelForcesNoneReasoning,
+  customModelUsesMaxCompletionTokens,
+} from "./custom-provider.js";
 import { memmyAccountNoneThinkingStyle } from "./memmy-account.js";
 import { getModelInputModalities } from "./model-input-capabilities.js";
 import { OPENROUTER_ATTRIBUTION_HEADERS } from "./openrouter-attribution.js";
@@ -621,9 +624,14 @@ export class OpenAICompatProvider extends LLMProvider {
       }
     }
 
-    const forceNoneReasoningEffort = specName(this.spec) === "openai"
+    const chatCompletionsGptWithTools = this.apiType === "chatCompletions"
       && Boolean(tools?.length)
-      && customModelUsesMaxCompletionTokens(modelName);
+      && chatCompletionsModelForcesNoneReasoning(modelName);
+    const providerName = specName(this.spec);
+    const thinkingOff = !wireEffort || semanticEffort === "none";
+    const forceNoneReasoningEffort = chatCompletionsGptWithTools && (
+      providerName === "openai" || (providerName === "custom" && thinkingOff)
+    );
     if (forceNoneReasoningEffort) kwargs.reasoning_effort = "none";
     else if (wireEffort && semanticEffort !== "none") kwargs.reasoning_effort = wireEffort;
     if (reasoningEffort !== null) {
diff --git a/App/memmy-agent/tests/core/agent-runtime/thinking-effort.test.ts b/App/memmy-agent/tests/core/agent-runtime/thinking-effort.test.ts
index 1052542be..3750aa897 100644
--- a/App/memmy-agent/tests/core/agent-runtime/thinking-effort.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/thinking-effort.test.ts
@@ -18,4 +18,12 @@ describe("reasoningEffortFromTurnMetadata", () => {
       thinking_level: "low",
     }, "claude-fable-5")).toBe("low");
   });
+
+  it("lets a custom model turn thinking off even when the catalog model is always on", () => {
+    expect(reasoningEffortFromTurnMetadata({
+      model_provider: "custom",
+      thinking_enabled: false,
+      thinking_level: "low",
+    }, "gpt-6-astra")).toBe("none");
+  });
 });
diff --git a/App/memmy-agent/tests/providers/custom-provider.test.ts b/App/memmy-agent/tests/providers/custom-provider.test.ts
index aae3e0cb3..f80b528a9 100644
--- a/App/memmy-agent/tests/providers/custom-provider.test.ts
+++ b/App/memmy-agent/tests/providers/custom-provider.test.ts
@@ -3,7 +3,10 @@ import { Config } from "../../src/config/schema.js";
 import { AnthropicProvider } from "../../src/providers/anthropic-provider.js";
 import { BedrockProvider } from "../../src/providers/bedrock-provider.js";
 import { makeProvider } from "../../src/providers/factory.js";
-import { customModelUsesMaxCompletionTokens } from "../../src/providers/custom-provider.js";
+import {
+  chatCompletionsModelForcesNoneReasoning,
+  customModelUsesMaxCompletionTokens,
+} from "../../src/providers/custom-provider.js";
 import { OpenAICompatProvider } from "../../src/providers/openai-compat-provider.js";
 import { findByName } from "../../src/providers/registry.js";
 
@@ -55,6 +58,14 @@ describe("custom provider", () => {
     expect(customModelUsesMaxCompletionTokens("gpt-5.4")).toBe(true);
     expect(customModelUsesMaxCompletionTokens("deepseek-v4")).toBe(false);
     expect(customModelUsesMaxCompletionTokens("qwen-max")).toBe(false);
+    expect(customModelUsesMaxCompletionTokens("gpt-4o")).toBe(false);
+  });
+
+  it("treats gpt- names and o-series names as chat completions reasoning models", () => {
+    expect(chatCompletionsModelForcesNoneReasoning("gpt-4o")).toBe(true);
+    expect(chatCompletionsModelForcesNoneReasoning("gpt-6-sol")).toBe(true);
+    expect(chatCompletionsModelForcesNoneReasoning("o3-mini")).toBe(true);
+    expect(chatCompletionsModelForcesNoneReasoning("qwen-max")).toBe(false);
   });
 
   it("sends max_completion_tokens only for matching custom chat models", () => {
@@ -76,6 +87,33 @@ describe("custom provider", () => {
     expect(kwargs.reasoning_effort).toBe("medium");
   });
 
+  it("sends reasoning_effort none for custom chat completions gpt models when thinking is off", () => {
+    const tools = [{ type: "function", function: { name: "read_file" } }];
+
+    expect(chatKwargs("gpt-6-sol", { tools }).reasoning_effort).toBe("none");
+    expect(chatKwargs("gpt-6-sol", { reasoningEffort: "none", tools }).reasoning_effort).toBe("none");
+    expect(chatKwargs("gpt-4o", { tools }).reasoning_effort).toBe("none");
+    expect(chatKwargs("gpt-4o", { tools }).max_tokens).toBe(1024);
+    expect(chatKwargs("gpt-4o", { tools })).not.toHaveProperty("max_completion_tokens");
+    expect(chatKwargs("qwen-max", { tools })).not.toHaveProperty("reasoning_effort");
+  });
+
+  it("does not force reasoning_effort none for custom responses", () => {
+    const provider = new OpenAICompatProvider("test-key", "https://example.com/v1", "gpt-6-sol", findByName("custom"));
+    provider.apiType = "responses";
+    const kwargs = provider.buildKwargs({
+      messages: [{ role: "user", content: "hi" }],
+      tools: [{ type: "function", function: { name: "read_file" } }],
+      model: "gpt-6-sol",
+      maxTokens: 1024,
+      temperature: 0.7,
+      reasoningEffort: null,
+      toolChoice: null,
+    });
+
+    expect(kwargs).not.toHaveProperty("reasoning_effort");
+  });
+
   it("selects the client from the custom endpoint protocol", () => {
     const responses = makeProvider(customPresetConfig("openai-responses", "gpt-4o-mini")) as OpenAICompatProvider;
     const anthropic = makeProvider(customPresetConfig("anthropic-messages", "claude-sonnet"));
@@ -186,6 +224,7 @@ function chatKwargs(
   overrides: { reasoningEffort?: string | null; tools?: Record<string, unknown>[] | null } = {},
 ): Record<string, unknown> {
   const provider = new OpenAICompatProvider("test-key", "https://example.com/v1", model, findByName("custom"));
+  provider.apiType = "chatCompletions";
   return provider.buildKwargs({
     messages: [{ role: "user", content: "hi" }],
     tools: overrides.tools ?? null,
diff --git a/App/memmy-agent/tests/providers/openai-responses.test.ts b/App/memmy-agent/tests/providers/openai-responses.test.ts
index c4db8394d..ef49beff1 100644
--- a/App/memmy-agent/tests/providers/openai-responses.test.ts
+++ b/App/memmy-agent/tests/providers/openai-responses.test.ts
@@ -610,6 +610,7 @@ function chatKwargs(
   reasoningEffort: string | null,
 ): Record<string, unknown> {
   const provider = new OpenAICompatProvider("test-key", "https://api.openai.com/v1", model, findByName("openai"));
+  provider.apiType = "chatCompletions";
   return provider.buildKwargs({
     messages: [{ role: "user", content: "hi" }],
     tools,

From 1785fafa8bdb13f76ae9f514a46491065d768735 Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Wed, 30 Sep 2026 11:57:58 +0800
Subject: [PATCH 13/85] =?UTF-8?q?Recommend=20the=20Responses=20API=20for?=
 =?UTF-8?q?=20GPT=20models=20in=20the=20Custom=20thinking=20hint,=20and=20?=
 =?UTF-8?q?show=20=E8=87=AA=E5=AE=9A=E4=B9=89=20for=20that=20provider=20in?=
 =?UTF-8?q?=20Chinese.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 App/frontend/desktop/src/i18n/messages.ts                   | 6 +++---
 App/frontend/desktop/src/pages/tests/model-config.test.ts   | 3 ++-
 App/frontend/desktop/src/pages/tests/settings-page.test.tsx | 6 ++++++
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index a0b30b16c..f62fcdedf 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -319,7 +319,7 @@ export const zhCNMessages = {
   "apiKey.provider.stepfun": "阶跃星辰",
   "apiKey.provider.xiaomi": "小米 MiMo",
   "apiKey.provider.memmy": "Memmy",
-  "apiKey.provider.custom": "Custom",
+  "apiKey.provider.custom": "自定义",
   "apiKey.customProtocol.openaiCompletions": "OpenAI Chat Completions",
   "apiKey.customProtocol.openaiResponses": "OpenAI Responses",
   "apiKey.customProtocol.anthropicMessages": "Anthropic Messages",
@@ -1552,7 +1552,7 @@ export const zhCNMessages = {
   "settings.modelWorkspace.region": "区域",
   "settings.modelWorkspace.regionPlaceholder": "例如：us-east-1",
   "settings.modelWorkspace.customThinkingEnabled": "支持思考",
-  "settings.modelWorkspace.customThinkingEnabledHint": "勾选后，输入框可以设置思考。不勾选则不传思考参数，由模型接口按默认行为处理。使用 Chat Completions 并且使用 gpt 模型时，请关闭支持思考，否则可能导致错误。",
+  "settings.modelWorkspace.customThinkingEnabledHint": "勾选后，输入框可以设置思考。不勾选则不传思考参数，由模型接口按默认行为处理。使用 Chat Completions 并且使用 gpt 模型时，请关闭支持思考，否则可能导致错误。gpt 模型建议使用 Responses 接口获得最佳体验。",
   "settings.modelWorkspace.customThinkingSwitchable": "可关闭思考",
   "settings.modelWorkspace.customThinkingSwitchableHint": "勾选后，对话里可以临时关闭思考。不勾选则思考始终开启，输入框不显示思考开关。",
   "settings.modelWorkspace.customThinkingDefaultEnabled": "默认开启思考",
@@ -3323,7 +3323,7 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "settings.modelWorkspace.region": "Region",
   "settings.modelWorkspace.regionPlaceholder": "For example: us-east-1",
   "settings.modelWorkspace.customThinkingEnabled": "Supports thinking",
-  "settings.modelWorkspace.customThinkingEnabledHint": "When checked, the composer can set thinking. When unchecked, no thinking parameters are sent and the model endpoint uses its default behavior. When using Chat Completions with a GPT model, turn off Supports thinking, or the request may fail.",
+  "settings.modelWorkspace.customThinkingEnabledHint": "When checked, the composer can set thinking. When unchecked, no thinking parameters are sent and the model endpoint uses its default behavior. When using Chat Completions with a GPT model, turn off Supports thinking, or the request may fail. GPT models should use the Responses API for the best experience.",
   "settings.modelWorkspace.customThinkingSwitchable": "Thinking can be turned off",
   "settings.modelWorkspace.customThinkingSwitchableHint": "When checked, a conversation can turn thinking off. When unchecked, thinking stays on and the composer hides the thinking switch.",
   "settings.modelWorkspace.customThinkingDefaultEnabled": "Thinking on by default",
diff --git a/App/frontend/desktop/src/pages/tests/model-config.test.ts b/App/frontend/desktop/src/pages/tests/model-config.test.ts
index 7df7ea6cd..052e84bfd 100644
--- a/App/frontend/desktop/src/pages/tests/model-config.test.ts
+++ b/App/frontend/desktop/src/pages/tests/model-config.test.ts
@@ -550,7 +550,8 @@ describe("model config helpers", () => {
     expect(fromProtocol("custom")).toBe("custom");
     expect(zhCNMessages["apiKey.provider.openaiCompletions"]).toBe("OpenAI Completions");
     expect(zhCNMessages["apiKey.provider.openaiResponses"]).toBe("OpenAI Responses");
-    expect(zhCNMessages["apiKey.provider.custom"]).toBe("Custom");
+    expect(zhCNMessages["apiKey.provider.custom"]).toBe("自定义");
+    expect(enUSMessages["apiKey.provider.custom"]).toBe("Custom");
   });
 
   it("中英文字典键集合一致", () => {
diff --git a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
index f22e844f5..0fb79f27f 100644
--- a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
@@ -230,9 +230,15 @@ describe("自定义模型能力选择", () => {
     expect(zhCNMessages["settings.modelWorkspace.customThinkingEnabledHint"]).toContain(
       "使用 Chat Completions 并且使用 gpt 模型时，请关闭支持思考，否则可能导致错误。"
     );
+    expect(zhCNMessages["settings.modelWorkspace.customThinkingEnabledHint"]).toContain(
+      "gpt 模型建议使用 Responses 接口获得最佳体验。"
+    );
     expect(enUSMessages["settings.modelWorkspace.customThinkingEnabledHint"]).toContain(
       "When using Chat Completions with a GPT model, turn off Supports thinking, or the request may fail."
     );
+    expect(enUSMessages["settings.modelWorkspace.customThinkingEnabledHint"]).toContain(
+      "GPT models should use the Responses API for the best experience."
+    );
   });
 });
 

From 69cfa4c83f91249c6ead34a6d8fcea4acd3a3de9 Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Wed, 30 Sep 2026 15:22:37 +0800
Subject: [PATCH 14/85] Give the Custom provider its own puzzle mark so it is
 no longer shown with the OpenAI logo.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 App/frontend/desktop/src/assets/model-logos/custom.svg      | 1 +
 App/frontend/desktop/src/components/model-provider-logo.tsx | 3 ++-
 App/frontend/desktop/src/pages/tests/model-config.test.ts   | 6 ++++++
 3 files changed, 9 insertions(+), 1 deletion(-)
 create mode 100644 App/frontend/desktop/src/assets/model-logos/custom.svg

diff --git a/App/frontend/desktop/src/assets/model-logos/custom.svg b/App/frontend/desktop/src/assets/model-logos/custom.svg
new file mode 100644
index 000000000..5773776b0
--- /dev/null
+++ b/App/frontend/desktop/src/assets/model-logos/custom.svg
@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Custom</title><path d="M15.39 4.39a1 1 0 0 0 1.68-.474 2.5 2.5 0 1 1 3.014 3.015 1 1 0 0 0-.474 1.68l1.683 1.682a2.414 2.414 0 0 1 0 3.414L19.61 15.39a1 1 0 0 1-1.68-.474 2.5 2.5 0 1 0-3.014 3.015 1 1 0 0 1 .474 1.68l-1.683 1.682a2.414 2.414 0 0 1-3.414 0L8.61 19.61a1 1 0 0 0-1.68.474 2.5 2.5 0 1 1-3.014-3.015 1 1 0 0 0 .474-1.68l-1.683-1.682a2.414 2.414 0 0 1 0-3.414L4.39 8.61a1 1 0 0 1 1.68.474 2.5 2.5 0 1 0 3.014-3.015 1 1 0 0 1-.474-1.68l1.683-1.682a2.414 2.414 0 0 1 3.414 0z"></path></svg>
diff --git a/App/frontend/desktop/src/components/model-provider-logo.tsx b/App/frontend/desktop/src/components/model-provider-logo.tsx
index a00e0e748..143c9069f 100644
--- a/App/frontend/desktop/src/components/model-provider-logo.tsx
+++ b/App/frontend/desktop/src/components/model-provider-logo.tsx
@@ -1,6 +1,7 @@
 import memmyCoverLogoUrl from "../assets/brand/memmy-cover.png";
 import anthropicLogoUrl from "../assets/model-logos/anthropic.svg";
 import baiduLogoUrl from "../assets/model-logos/baidu.svg";
+import customLogoUrl from "../assets/model-logos/custom.svg";
 import deepseekLogoUrl from "../assets/model-logos/deepseek.svg";
 import doubaoLogoUrl from "../assets/model-logos/doubao.svg";
 import geminiLogoUrl from "../assets/model-logos/gemini.svg";
@@ -29,7 +30,7 @@ const PROTOCOL_LOGO_URLS: Record<Protocol, string> = {
   doubao: doubaoLogoUrl,
   stepfun: stepfunLogoUrl,
   xiaomi: xiaomiLogoUrl,
-  custom: openaiLogoUrl
+  custom: customLogoUrl
 };
 
 /** Resolve a logo URL for a protocol or free-form provider string. */
diff --git a/App/frontend/desktop/src/pages/tests/model-config.test.ts b/App/frontend/desktop/src/pages/tests/model-config.test.ts
index 052e84bfd..290b9a3fa 100644
--- a/App/frontend/desktop/src/pages/tests/model-config.test.ts
+++ b/App/frontend/desktop/src/pages/tests/model-config.test.ts
@@ -558,6 +558,12 @@ describe("model config helpers", () => {
     expect(Object.keys(enUSMessages).sort()).toEqual(Object.keys(zhCNMessages).sort());
   });
 
+  it("自定义供应商使用独立的拼图图标", () => {
+    expect(modelProviderLogoUrl("custom")).toMatch(/^data:image\/svg\+xml/);
+    expect(modelProviderLogoUrl("custom")).not.toBe(modelProviderLogoUrl("openai"));
+    expect(modelProviderLogoUrl("openai_responses")).toBe(modelProviderLogoUrl("openai"));
+  });
+
   it("为阶跃星辰和小米 MiMo 解析出品牌 logo", () => {
     expect(modelProviderLogoUrl("stepfun")).toMatch(/^data:image\/svg\+xml/);
     expect(modelProviderLogoUrl("xiaomi")).toMatch(/^data:image\/svg\+xml/);

From 4e4c5fc0d199f714676c08d0e274758b8759ae3e Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Fri, 9 Oct 2026 12:21:19 +0800
Subject: [PATCH 15/85] feat: package agent runtime for npm

---
 .gitignore                                    |  1 +
 App/memmy-agent/package.json                  |  3 +
 App/memmy-agent/scripts/build-npm-package.mjs | 96 +++++++++++++++++++
 package.json                                  |  2 +
 4 files changed, 102 insertions(+)
 create mode 100644 App/memmy-agent/scripts/build-npm-package.mjs

diff --git a/.gitignore b/.gitignore
index fec3c3dd1..34416d4da 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 node_modules/
 dist/
+App/memmy-agent/.npm-package/
 release/
 App/shell/desktop/release/
 Mac软件打包/
diff --git a/App/memmy-agent/package.json b/App/memmy-agent/package.json
index 78ec3cfaf..9be992733 100644
--- a/App/memmy-agent/package.json
+++ b/App/memmy-agent/package.json
@@ -15,6 +15,9 @@
     "pretest": "npm --prefix ../../Knowledge run build && npm run version:sync && npm --prefix ../../Migrations run build && npm --prefix ../backend/local-api-contracts run build",
     "pretest:tui-cursor": "npm run version:sync",
     "build": "tsc -p tsconfig.build.json && node scripts/copy-build-assets.mjs",
+    "prepackage:npm": "npm run build",
+    "package:npm": "node scripts/build-npm-package.mjs",
+    "pack:npm": "npm run package:npm && npm pack ./.npm-package",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:tui-cursor": "vitest run tests/entrypoints/cli/tui-cursor.test.ts",
diff --git a/App/memmy-agent/scripts/build-npm-package.mjs b/App/memmy-agent/scripts/build-npm-package.mjs
new file mode 100644
index 000000000..0eff8b995
--- /dev/null
+++ b/App/memmy-agent/scripts/build-npm-package.mjs
@@ -0,0 +1,96 @@
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const scriptRoot = dirname(fileURLToPath(import.meta.url));
+const agentRoot = resolve(scriptRoot, "..");
+const repoRoot = resolve(agentRoot, "../..");
+const outputRoot = join(agentRoot, ".npm-package");
+const vendorRoot = join(outputRoot, "vendor");
+const sourceManifest = JSON.parse(await readFile(join(agentRoot, "package.json"), "utf8"));
+const packageName = "@memtensor/memmy-agent";
+
+const localDependencies = new Map([
+  ["@memmy/local-api-contracts", "App/backend/local-api-contracts"],
+  ["@memmy/migrations", "Migrations"],
+  ["@memmy/knowledge", "Knowledge"],
+]);
+
+await rm(outputRoot, { recursive: true, force: true });
+await rm(join(agentRoot, "dist", "memmy-agent-npm"), { recursive: true, force: true });
+await mkdir(vendorRoot, { recursive: true });
+
+const vendorPackages = {};
+for (const [dependencyName, packagePath] of localDependencies) {
+  const packageRoot = join(repoRoot, packagePath);
+  const tarball = await pack(packageRoot, vendorRoot);
+  vendorPackages[dependencyName] = `file:vendor/${tarball}`;
+}
+
+const packageManifest = {
+  name: packageName,
+  version: sourceManifest.version,
+  description: sourceManifest.description,
+  type: "module",
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js",
+      default: "./dist/index.js",
+    },
+  },
+  bin: { memmy: "./dist/main.js" },
+  publishConfig: { access: "public" },
+  files: ["dist/**/*", ".env.example", "README.md", "vendor/*.tgz"],
+  engines: sourceManifest.engines,
+  dependencies: {
+    ...sourceManifest.dependencies,
+    ...vendorPackages,
+  },
+};
+
+await writeFile(join(outputRoot, "package.json"), `${JSON.stringify(packageManifest, null, 2)}\n`);
+await cp(join(agentRoot, "dist"), join(outputRoot, "dist"), { recursive: true });
+await cp(join(agentRoot, ".env.example"), join(outputRoot, ".env.example"));
+await cp(join(agentRoot, "README.md"), join(outputRoot, "README.md"));
+
+for (const file of ["dist/main.js", "dist/index.js", ".env.example", "README.md"]) {
+  if (!(await exists(join(outputRoot, file)))) throw new Error(`npm package is missing ${file}`);
+}
+if (Object.values(packageManifest.dependencies).some((value) => value.startsWith("file:../") || value.startsWith("file:../../"))) {
+  throw new Error("npm package contains a dependency outside its own archive");
+}
+
+console.log(`Prepared ${packageName}@${sourceManifest.version} at ${outputRoot}`);
+
+async function pack(packageRoot, destination) {
+  const result = await run("npm", ["pack", packageRoot, "--pack-destination", destination, "--ignore-scripts", "--json"], repoRoot);
+  const metadata = JSON.parse(result.stdout).at(-1);
+  if (!metadata?.filename) throw new Error(`npm pack did not return a filename for ${packageRoot}`);
+  return metadata.filename;
+}
+
+async function exists(path) {
+  try {
+    await readFile(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function run(command, args, cwd) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "inherit"] });
+    let stdout = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      if (code === 0) resolvePromise({ stdout });
+      else reject(new Error(`${command} ${args.join(" ")} exited with ${code}`));
+    });
+  });
+}
diff --git a/package.json b/package.json
index 6a7814a8e..f5158cf4b 100644
--- a/package.json
+++ b/package.json
@@ -55,6 +55,8 @@
     "memory:pack": "npm run pack:npm -w @memmy/memory",
     "memory:binary": "npm run binary -w @memmy/memory",
     "memory:runtime:package": "npm run runtime:package -w @memmy/memory",
+    "agent:package": "npm --prefix App/memmy-agent run package:npm",
+    "agent:pack": "npm --prefix App/memmy-agent run pack:npm",
     "memory:dev": "npm run dev -w @memmy/memory",
     "memory:serve": "npm run serve -w @memmy/memory",
     "memory:serve:local": "npm run serve:local -w @memmy/memory",

From 2f934f522283cfa72bf5a1af7c11bb43623fa26d Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Fri, 9 Oct 2026 14:16:50 +0800
Subject: [PATCH 16/85] chore: relocate agent npm package output

---
 .gitignore                                    | 2 +-
 App/memmy-agent/package.json                  | 2 +-
 App/memmy-agent/scripts/build-npm-package.mjs | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index 34416d4da..b390d647b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,6 @@
 node_modules/
 dist/
-App/memmy-agent/.npm-package/
+App/memmy-agent/npm-packages/
 release/
 App/shell/desktop/release/
 Mac软件打包/
diff --git a/App/memmy-agent/package.json b/App/memmy-agent/package.json
index 9be992733..b6979b934 100644
--- a/App/memmy-agent/package.json
+++ b/App/memmy-agent/package.json
@@ -17,7 +17,7 @@
     "build": "tsc -p tsconfig.build.json && node scripts/copy-build-assets.mjs",
     "prepackage:npm": "npm run build",
     "package:npm": "node scripts/build-npm-package.mjs",
-    "pack:npm": "npm run package:npm && npm pack ./.npm-package",
+    "pack:npm": "npm run package:npm && npm pack ./npm-packages/memmy-agent --pack-destination ./npm-packages",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:tui-cursor": "vitest run tests/entrypoints/cli/tui-cursor.test.ts",
diff --git a/App/memmy-agent/scripts/build-npm-package.mjs b/App/memmy-agent/scripts/build-npm-package.mjs
index 0eff8b995..ef6432e0d 100644
--- a/App/memmy-agent/scripts/build-npm-package.mjs
+++ b/App/memmy-agent/scripts/build-npm-package.mjs
@@ -6,7 +6,7 @@ import { spawn } from "node:child_process";
 const scriptRoot = dirname(fileURLToPath(import.meta.url));
 const agentRoot = resolve(scriptRoot, "..");
 const repoRoot = resolve(agentRoot, "../..");
-const outputRoot = join(agentRoot, ".npm-package");
+const outputRoot = join(agentRoot, "npm-packages", "memmy-agent");
 const vendorRoot = join(outputRoot, "vendor");
 const sourceManifest = JSON.parse(await readFile(join(agentRoot, "package.json"), "utf8"));
 const packageName = "@memtensor/memmy-agent";

From 019cce2867ee012c3f82993a4844f11dcb1c8982 Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Fri, 9 Oct 2026 14:22:39 +0800
Subject: [PATCH 17/85] fix: sync generated agent npm package version

---
 scripts/sync-project-version.mjs | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/scripts/sync-project-version.mjs b/scripts/sync-project-version.mjs
index 336d8e7e4..37f932be8 100644
--- a/scripts/sync-project-version.mjs
+++ b/scripts/sync-project-version.mjs
@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { access, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -16,6 +16,9 @@ const derivedManifests = [
   "App/memmy-agent/package.json",
   "App/shell/desktop/package.json",
 ];
+const optionalDerivedManifests = [
+  "App/memmy-agent/npm-packages/memmy-agent/package.json",
+];
 
 const staleFiles = [];
 for (const relativePath of derivedManifests) {
@@ -23,6 +26,13 @@ for (const relativePath of derivedManifests) {
     json.version = version;
   });
 }
+for (const relativePath of optionalDerivedManifests) {
+  if (await exists(relativePath)) {
+    await updateJson(relativePath, (json) => {
+      json.version = version;
+    });
+  }
+}
 
 await updateText(
   "App/backend/src/project-version.ts",
@@ -74,3 +84,12 @@ async function updateText(relativePath, nextText) {
 async function readJson(path) {
   return JSON.parse(await readFile(path, "utf8"));
 }
+
+async function exists(relativePath) {
+  try {
+    await access(join(root, relativePath));
+    return true;
+  } catch {
+    return false;
+  }
+}

From 8f9c428b2e14a10ed51587dbc52ca753c7b900d9 Mon Sep 17 00:00:00 2001
From: xrzhu <xrzhu@xrzhudeMacBook-Pro-3.local>
Date: Fri, 9 Oct 2026 17:18:01 +0800
Subject: [PATCH 18/85] fix(chat): keep copy actions on completed historical
 replies

---
 .../src/pages/agent-thread-messages.tsx       |  22 ++--
 .../agent-thread-copy.interaction.test.tsx    | 100 ++++++++++++++++++
 2 files changed, 115 insertions(+), 7 deletions(-)
 create mode 100644 App/frontend/desktop/src/pages/tests/agent-thread-copy.interaction.test.tsx

diff --git a/App/frontend/desktop/src/pages/agent-thread-messages.tsx b/App/frontend/desktop/src/pages/agent-thread-messages.tsx
index 29588a66c..d5da86ea4 100644
--- a/App/frontend/desktop/src/pages/agent-thread-messages.tsx
+++ b/App/frontend/desktop/src/pages/agent-thread-messages.tsx
@@ -136,7 +136,7 @@ export const AgentThreadMessages = memo(function AgentThreadMessages(props: Agen
     () => buildAgentDisplayUnits(props.messages, { chatScopeKey: props.chatScopeKey, retryWaitStatus: props.retryWaitStatus ?? null }),
     [props.chatScopeKey, props.messages, props.retryWaitStatus]
   );
-  const finalAssistantAnswerIndex = useMemo(() => findFinalAssistantAnswerUnitIndex(units, { isSending: props.isSending }), [props.isSending, units]);
+  const finalAssistantAnswerIndices = useMemo(() => findFinalAssistantAnswerUnitIndices(units, { isSending: props.isSending }), [props.isSending, units]);
   const recallEvidenceAnchors = useMemo(
     () => findRecallEvidenceUserAnchors(units, { isSending: props.isSending }),
     [props.isSending, units]
@@ -217,7 +217,7 @@ export const AgentThreadMessages = memo(function AgentThreadMessages(props: Agen
               artifactClient={props.artifactClient}
               chatScopeKey={props.chatScopeKey}
               unitIndex={index}
-              isFinalAssistantAnswer={index === finalAssistantAnswerIndex}
+              isFinalAssistantAnswer={finalAssistantAnswerIndices.has(index)}
               forceMessageActions={unit.message.id === (props.forceMessageActionsForMessageId ?? props.afterMessageId)}
               deferContentRender={shouldDeferAgentMessageContent(unit, index, units.length)}
               deferredRevealDelayMs={deferredAgentMessageRevealDelay(index, units.length)}
@@ -361,16 +361,23 @@ function isActivityAutoOpenRunning(unit: Extract<AgentDisplayUnit, { type: "acti
 }
 
 /**
- * Locate the index of the last "single" unit that is a finalized assistant
- * answer. While the current turn is still sending, assistant text after the
+ * Locate the last finalized assistant answer in each user-delimited turn.
+ * While the current turn is still sending, assistant text after the
  * latest user message is treated as continuation text, because the agent may
  * still alternate body → tool → reasoning → tool before the actual final answer.
  */
-function findFinalAssistantAnswerUnitIndex(units: AgentDisplayUnit[], options: { isSending?: boolean } = {}): number {
+function findFinalAssistantAnswerUnitIndices(units: AgentDisplayUnit[], options: { isSending?: boolean } = {}): Set<number> {
+  const indices = new Set<number>();
   const lastUserUnitIndex = findLastUserUnitIndex(units);
+  let foundAnswerInTurn = false;
   for (let index = units.length - 1; index >= 0; index -= 1) {
     const unit = units[index];
     if (unit?.type !== "single") continue;
+    if (unit.message.role === "user") {
+      foundAnswerInTurn = false;
+      continue;
+    }
+    if (foundAnswerInTurn) continue;
     if (options.isSending && index > lastUserUnitIndex) continue;
     const message = unit.message;
     if (message.role === "assistant"
@@ -378,10 +385,11 @@ function findFinalAssistantAnswerUnitIndex(units: AgentDisplayUnit[], options: {
       && message.kind !== "narration"
       && message.kind !== "context_compaction"
       && message.content.trim().length > 0) {
-      return index;
+      indices.add(index);
+      foundAnswerInTurn = true;
     }
   }
-  return -1;
+  return indices;
 }
 
 function findLastUserUnitIndex(units: AgentDisplayUnit[]): number {
diff --git a/App/frontend/desktop/src/pages/tests/agent-thread-copy.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/agent-thread-copy.interaction.test.tsx
new file mode 100644
index 000000000..87dad7cf4
--- /dev/null
+++ b/App/frontend/desktop/src/pages/tests/agent-thread-copy.interaction.test.tsx
@@ -0,0 +1,100 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { I18nProvider } from "../../i18n/i18n-provider.js";
+import type { AgentChatMessage } from "../../state/agent-chat-slice.js";
+import { AgentThreadMessages } from "../agent-thread-messages.js";
+
+describe("AgentThreadMessages copy actions across turns", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  const completedMessages: AgentChatMessage[] = [
+    { id: "question-1", role: "user", content: "First question" },
+    { id: "answer-1", role: "assistant", content: "First **answer**" },
+    { id: "question-2", role: "user", content: "Second question" },
+    { id: "answer-2", role: "assistant", content: "Second `answer`" },
+  ];
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  async function render(messages: AgentChatMessage[], isSending = false) {
+    await act(async () => {
+      root.render(
+        <I18nProvider language="en-US">
+          <AgentThreadMessages chatScopeKey="copy-history" messages={messages} isSending={isSending} />
+        </I18nProvider>
+      );
+    });
+  }
+
+  function copyButtons() {
+    return [...container.querySelectorAll<HTMLButtonElement>(".agent-message-copy-button--left")];
+  }
+
+  it("keeps the first answer copyable after a second turn and copies each answer's raw text", async () => {
+    const writeText = vi.spyOn(navigator.clipboard, "writeText").mockResolvedValue();
+    await render(completedMessages.slice(0, 2));
+    expect(copyButtons()).toHaveLength(1);
+
+    await render(completedMessages);
+    const buttons = copyButtons();
+    expect(buttons).toHaveLength(2);
+    await act(async () => buttons[0]!.click());
+    await act(async () => buttons[1]!.click());
+    expect(writeText.mock.calls).toEqual([["First **answer**"], ["Second `answer`"]]);
+  });
+
+  it.each(["waiting", "streaming", "reasoning", "tools"] as const)(
+    "keeps both completed turns copyable while the third turn is %s",
+    async (phase) => {
+      const messages: AgentChatMessage[] = [
+        ...completedMessages,
+        { id: "question-3", role: "user", content: "Third question" },
+      ];
+      if (phase !== "waiting") {
+        messages.push({
+          id: "answer-3", role: "assistant", content: "Third draft",
+          isStreaming: phase === "streaming",
+          reasoningStreaming: phase === "reasoning",
+        });
+      }
+      if (phase === "tools") {
+        messages.push({ id: "tool-3", role: "tool", kind: "trace", content: "read_file()", isStreaming: true });
+      }
+      await render(messages, true);
+      expect(copyButtons()).toHaveLength(2);
+      expect(copyButtons().map((button) => button.closest(".agent-chat-bubble-frame")?.textContent))
+        .toEqual([expect.stringContaining("First answer"), expect.stringContaining("Second answer")]);
+    },
+  );
+
+  it("only exposes the final answer within each completed turn", async () => {
+    await render([
+      { id: "question-1", role: "user", content: "First question" },
+      { id: "continuation-1", role: "assistant", content: "Checking first" },
+      { id: "tool-1", role: "tool", kind: "trace", content: "read_file()" },
+      { id: "answer-1", role: "assistant", content: "First final" },
+      { id: "question-2", role: "user", content: "Second question" },
+      { id: "continuation-2", role: "assistant", content: "Checking second" },
+      { id: "narration-2", role: "assistant", kind: "narration", content: "Still checking" },
+      { id: "answer-2", role: "assistant", content: "Second final", stoppedByUser: true },
+      { id: "empty-2", role: "assistant", content: " " },
+    ]);
+    expect(copyButtons()).toHaveLength(2);
+    expect(copyButtons().map((button) => button.closest(".agent-chat-bubble-frame")?.textContent))
+      .toEqual([expect.stringContaining("First final"), expect.stringContaining("Second final")]);
+  });
+});

From a69fe874ffbfdf7212e4f1d0e69a37ffddf2f421 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Fri, 9 Oct 2026 19:04:12 +0800
Subject: [PATCH 19/85] fix: reuse degraded development memory service

---
 .../desktop/src/main/runtime-services.ts      |  6 ++-
 .../desktop/tests/runtime-services.test.ts    | 46 +++++++++++++++++++
 2 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/App/shell/desktop/src/main/runtime-services.ts b/App/shell/desktop/src/main/runtime-services.ts
index 332a672ec..da14738a6 100644
--- a/App/shell/desktop/src/main/runtime-services.ts
+++ b/App/shell/desktop/src/main/runtime-services.ts
@@ -1891,8 +1891,10 @@ async function probeMemoryService(url: string, headers: Record<string, string> =
       signal: AbortSignal.timeout(HTTP_TIMEOUT_MS)
     });
     if (!response.ok) return "unexpected";
-    const body = await response.json() as { ok?: unknown; protocolVersion?: unknown };
-    if (body.ok !== true) return "unexpected";
+    const body: unknown = await response.json();
+    if (!isRecord(body) || typeof body.ok !== "boolean") return "unexpected";
+    // `ok` also reflects model health. A degraded dev-start service still owns
+    // this endpoint and must be reused instead of starting a second listener.
     return body.protocolVersion === SUPPORTED_MEMORY_PROTOCOL_VERSION ? "ready" : "incompatible";
   } catch {
     return "unreachable";
diff --git a/App/shell/desktop/tests/runtime-services.test.ts b/App/shell/desktop/tests/runtime-services.test.ts
index eb1d6b370..c292a6d90 100644
--- a/App/shell/desktop/tests/runtime-services.test.ts
+++ b/App/shell/desktop/tests/runtime-services.test.ts
@@ -554,6 +554,52 @@ describe("packaged desktop runtime config", () => {
     expect(children).toHaveLength(0);
   });
 
+  it("reuses a compatible degraded Memory service started by dev-start", async () => {
+    const root = await makeTempRoot();
+    const databasePath = join(root, "memory.sqlite");
+    const server = createServer((_request, response) => {
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(JSON.stringify({
+        ok: false,
+        protocolVersion: 1,
+        serviceVersion: "2.1.3",
+        models: { summary: { lastError: "model unavailable" } }
+      }));
+    });
+    testServers.push(server);
+    await new Promise<void>((resolveListen) => server.listen(0, "127.0.0.1", resolveListen));
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("expected TCP address");
+    const children: ManagedChild[] = [];
+
+    await ensureMemoryService(
+      { memoryEntry: join(root, "missing-memory.js"), agentEntry: join(root, "missing-agent.js") },
+      {
+        configPath: join(root, "config.yaml"),
+        agentWorkspace: join(root, "workspace"),
+        memoryDatabasePath: databasePath,
+        memoryBaseUrl: `http://127.0.0.1:${address.port}`,
+        memoryToken: "",
+        memoryListenHost: "127.0.0.1",
+        memoryListenPort: address.port,
+        agentGatewayBaseUrl: "http://127.0.0.1:18980",
+        agentGatewayHealthHost: "127.0.0.1",
+        agentGatewayHealthPort: 18970,
+        agentGatewayBootstrapSecret: "secret"
+      },
+      children,
+      {
+        appPath: root,
+        appDatabaseFile: join(root, "app.sqlite"),
+        resourcesPath: root,
+        logDirectory: root,
+        logLevel: "info"
+      }
+    );
+
+    expect(children).toHaveLength(0);
+  });
+
   it("rereads the migrated workspace instead of pinning the pre-migration legacy value", async () => {
     const memmyHome = await makeTempRoot();
     const configPath = join(memmyHome, "config.yaml");

From 37598d50a737a163996037ed454ab635b8fb17a7 Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Sun, 11 Oct 2026 15:21:30 +0800
Subject: [PATCH 20/85] fix: forward native progress events over SSE

---
 .../src/entrypoints/openai-like-api/server.ts | 72 +++++++++++++++++++
 .../openai-like-api/api-stream.test.ts        | 37 +++++++++-
 2 files changed, 108 insertions(+), 1 deletion(-)

diff --git a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
index 0ff0484a9..4de00a531 100644
--- a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
+++ b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
@@ -4,6 +4,7 @@ import { Config } from "../../config/schema.js";
 import { getMediaDir } from "../../config/paths.js";
 import { InboundMessage } from "../../core/runtime-messages/events.js";
 import { FileSizeExceeded, saveBase64DataUrl } from "../../utils/media-decode.js";
+import { withProgressCapabilities } from "../../utils/progress-events.js";
 import { EMPTY_FINAL_RESPONSE_MESSAGE } from "../../utils/runtime.js";
 
 export const API_SESSION_KEY = "api:default";
@@ -107,6 +108,17 @@ export function sseChunk(delta: string, model: string, chunkId: string, finishRe
   return `data: ${JSON.stringify(payload)}\n\n`;
 }
 
+export function sseMemmyEvent(type: string, payload: Record<string, any>, model: string, chunkId: string): string {
+  return `data: ${JSON.stringify({
+    id: chunkId,
+    object: "chat.completion.chunk",
+    created: Math.floor(Date.now() / 1000),
+    model,
+    choices: [],
+    memmy_event: { type, ...payload },
+  })}\n\n`;
+}
+
 export const SSE_DONE = "data: [DONE]\n\n";
 
 function safeFilename(name: string): string {
@@ -315,6 +327,30 @@ export async function handleChatCompletions(request: Request, ctx?: ApiContext):
             if (token) emitted = true;
             write(sseChunk(token, context.modelName, chunkId));
           };
+          const onProgress = withProgressCapabilities(async (content: string, options: Record<string, any> = {}) => {
+            if (options.reasoning && content) write(sseMemmyEvent("thinking_delta", { text: content }, context.modelName, chunkId));
+            if (options.reasoningEnd) write(sseMemmyEvent("thinking_end", {}, context.modelName, chunkId));
+            for (const event of options.toolEvents ?? []) {
+              const phase = String(event?.phase ?? "");
+              if (phase === "start") {
+                write(sseMemmyEvent("tool_call", {
+                  callId: String(event.call_id ?? event.ui_tool_call_id ?? "call"),
+                  name: String(event.name ?? "tool"),
+                  input: event.arguments ?? {},
+                }, context.modelName, chunkId));
+              } else if (phase === "end" || phase === "error") {
+                write(sseMemmyEvent("tool_result", {
+                  callId: String(event.call_id ?? event.ui_tool_call_id ?? "call"),
+                  name: String(event.name ?? "tool"),
+                  output: phase === "error" ? event.error ?? "Tool execution failed" : event.result ?? null,
+                  ok: phase === "end",
+                }, context.modelName, chunkId));
+                for (const media of mediaFromToolEvent(event)) {
+                  write(sseMemmyEvent("media", { media: [media] }, context.modelName, chunkId));
+                }
+              }
+            }
+          }, { reasoning: true, toolEvents: true });
           const onStreamEnd = async () => undefined;
           try {
             await withSessionLock(context, sessionKey, async () => {
@@ -322,6 +358,7 @@ export async function handleChatCompletions(request: Request, ctx?: ApiContext):
                 Promise.resolve(
                   callAgent(context, {
                     ...baseArgs,
+                    onProgress,
                     onStream,
                     onStreamEnd,
                   }),
@@ -379,6 +416,41 @@ export async function handleChatCompletions(request: Request, ctx?: ApiContext):
   }
 }
 
+function mediaFromToolEvent(event: Record<string, any>): Array<Record<string, string>> {
+  const media: Array<Record<string, string>> = [];
+  const seen = new Set<string>();
+  const push = (item: Record<string, string>): void => {
+    const key = `${item.kind}:${item.url ?? item.path ?? ""}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    media.push(item);
+  };
+  const add = (value: any): void => {
+    if (Array.isArray(value)) {
+      for (const item of value) add(item);
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    if (value.type === "resource_link" && typeof value.uri === "string" && value.uri.trim()) {
+      const mime = typeof value.mimeType === "string" ? value.mimeType : "";
+      const kind = mime.startsWith("image/") || /\.(?:png|jpe?g|gif|webp|svg)$/iu.test(value.uri) ? "image" : "file";
+      push({ kind, ...(value.uri.startsWith("http") || value.uri.startsWith("data:") ? { url: value.uri } : { path: value.uri }), ...(typeof value.name === "string" && value.name ? { name: value.name } : {}) });
+      return;
+    }
+    if (value.type === "image_url" && typeof value.image_url?.url === "string" && value.image_url.url.trim()) {
+      push({ kind: "image", url: value.image_url.url });
+      return;
+    }
+    for (const child of [value.files, value.embeds, value.content, value.result]) add(child);
+  };
+  for (const file of event.files ?? []) {
+    if (typeof file === "string" && file.trim()) add({ type: "resource_link", uri: file });
+  }
+  add(event.embeds);
+  add(event.result);
+  return media;
+}
+
 export async function handleModels(request?: Request, ctx?: Pick<ApiContext, "modelName">): Promise<Response> {
   void request;
   const model = ctx?.modelName ?? "memmy";
diff --git a/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts b/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
index 19a84b06b..f547178a6 100644
--- a/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
+++ b/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { SSE_DONE, sseChunk, createApp } from "../../../src/entrypoints/openai-like-api/server.js";
+import { SSE_DONE, sseChunk, sseMemmyEvent, createApp } from "../../../src/entrypoints/openai-like-api/server.js";
 
 function request(body: unknown): Request {
   return new Request("http://localhost/v1/chat/completions", {
@@ -47,6 +47,14 @@ describe("SSE response helpers", () => {
   it("uses the OpenAI [DONE] SSE terminator", () => {
     expect(SSE_DONE).toBe("data: [DONE]\n\n");
   });
+
+  it("encodes Memmy progress events without changing the OpenAI chunk shape", () => {
+    const payload = JSON.parse(sseMemmyEvent("thinking_delta", { text: "先分析" }, "m", "id1").slice(6));
+
+    expect(payload.choices).toEqual([]);
+    expect(payload.memmy_event).toEqual({ type: "thinking_delta", text: "先分析" });
+    expect(payload.object).toBe("chat.completion.chunk");
+  });
 });
 
 describe("SSE chat completions", () => {
@@ -168,6 +176,33 @@ describe("SSE chat completions", () => {
     expect(captured.onStreamEnd).toBeTypeOf("function");
   });
 
+  it("streams reasoning, tool lifecycle and generated files through Memmy events", async () => {
+    const app = createApp({
+      processDirect: async (args: any) => {
+        await args.onProgress("先分析", { reasoning: true });
+        await args.onProgress("", { reasoningEnd: true });
+        await args.onProgress("", {
+          toolEvents: [{ phase: "start", call_id: "call-1", name: "write_file", arguments: { path: "a.txt" } }],
+        });
+        await args.onProgress("", {
+          toolEvents: [{ phase: "end", call_id: "call-1", name: "write_file", result: [{ type: "resource_link", uri: "/tmp/a.txt", mimeType: "text/plain" }], files: ["/tmp/a.txt"] }],
+        });
+        await args.onStream("完成");
+        return "完成";
+      },
+    }, "m");
+
+    const payloads = ssePayloads(await (await app.fetch(request({ messages: [{ role: "user", content: "go" }], stream: true }))).text())
+      .filter((line) => line !== "[DONE]")
+      .map((line) => JSON.parse(line));
+    expect(payloads.map((item) => item.memmy_event?.type).filter(Boolean)).toEqual([
+      "thinking_delta", "thinking_end", "tool_call", "tool_result", "media",
+    ]);
+    expect(payloads.filter((item) => item.memmy_event?.type === "media").map((item) => item.memmy_event.media[0])).toEqual([
+      { kind: "file", path: "/tmp/a.txt" },
+    ]);
+  });
+
   it("does not close the SSE response on intermediate stream-end callbacks", async () => {
     const app = createApp(
       {

From c3b8162057cfb84673f824991b78aa1580fe519a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Mon, 12 Oct 2026 15:50:46 +0800
Subject: [PATCH 21/85] =?UTF-8?q?fix:=20=E6=94=AF=E6=8C=81=20apply=5Fpatch?=
 =?UTF-8?q?=20=E5=B7=A5=E4=BD=9C=E5=8C=BA=E5=86=85=E7=BB=9D=E5=AF=B9?=
 =?UTF-8?q?=E8=B7=AF=E5=BE=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../core/agent-runtime/tools/apply-patch.ts   |  34 +++-
 .../agent-runtime/tools/patch-envelope.ts     |  28 ++--
 .../tools/apply-patch-tool.test.ts            |   6 +-
 .../agent-runtime/tools/bug-671-repro.test.ts | 146 ++++++++++++++++++
 .../tools/patch-envelope.test.ts              |  12 +-
 .../tools/tool-descriptions.test.ts           |   2 +-
 6 files changed, 203 insertions(+), 25 deletions(-)
 create mode 100644 App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts

diff --git a/App/memmy-agent/src/core/agent-runtime/tools/apply-patch.ts b/App/memmy-agent/src/core/agent-runtime/tools/apply-patch.ts
index cea810679..d8b015b1f 100644
--- a/App/memmy-agent/src/core/agent-runtime/tools/apply-patch.ts
+++ b/App/memmy-agent/src/core/agent-runtime/tools/apply-patch.ts
@@ -7,6 +7,7 @@ import {
   PatchError,
   normalizePatchPath,
   parsePatchEnvelope,
+  validatePatchPathConflicts,
   type PatchFileOperation,
   type PatchHunk,
 } from "./patch-envelope.js";
@@ -284,7 +285,7 @@ export class ApplyPatchTool extends Tool {
   }
 
   get description(): string {
-    return "Apply a patch to add, update, delete, or move one or more workspace-relative files.";
+    return "Apply a patch to add, update, delete, or move one or more files inside the workspace.";
   }
 
   get parameters() {
@@ -316,7 +317,7 @@ To move or rename a file, use:
 Start each update hunk with @@. If needed, add an exact line from the file after @@ to help locate the change, for example: @@ function calculate().
 Prefix added lines with +, removed lines with -, and unchanged context lines with a space.
 Use *** End of File for an append or a hunk that must end at EOF.
-Paths must be workspace-relative. Use at most 20 file operations in one patch.`,
+Paths may be workspace-relative or absolute paths inside the workspace. Use at most 20 file operations in one patch.`,
         },
       },
       required: ["input"],
@@ -327,15 +328,18 @@ Paths must be workspace-relative. Use at most 20 file operations in one patch.`,
     return params;
   }
 
-  resolve(relativePath: string): string {
-    const normalized = normalizePatchPath(relativePath);
-    const target = path.resolve(this.workspace, ...normalized.split("/"));
+  resolve(requestedPath: string): string {
+    const normalized = normalizePatchPath(requestedPath);
+    const target = path.isAbsolute(normalized)
+      ? path.resolve(normalized)
+      : path.resolve(this.workspace, ...normalized.split("/"));
     const relative = path.relative(this.workspace, target);
     if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-      throw new PatchError(`patch path escapes workspace: ${relativePath}`);
+      throw new PatchError(`patch path escapes workspace: ${requestedPath}`);
     }
+    if (!relative) throw new PatchError(`patch path must name a file inside the workspace: ${requestedPath}`);
 
-    const segments = normalized.split("/");
+    const segments = relative.split(path.sep);
     let current = this.workspace;
     for (let index = 0; index < segments.length; index += 1) {
       current = path.join(current, segments[index]);
@@ -354,6 +358,20 @@ Paths must be workspace-relative. Use at most 20 file operations in one patch.`,
     return target;
   }
 
+  private normalizeOperations(operations: PatchFileOperation[]): PatchFileOperation[] {
+    const relativePath = (requestedPath: string): string =>
+      path.relative(this.workspace, this.resolve(requestedPath)).split(path.sep).join("/");
+    const normalized = operations.map((operation): PatchFileOperation => {
+      const operationPath = relativePath(operation.path);
+      if (operation.kind !== "update" || !operation.moveTo) {
+        return { ...operation, path: operationPath };
+      }
+      return { ...operation, path: operationPath, moveTo: relativePath(operation.moveTo) };
+    });
+    validatePatchPathConflicts(normalized);
+    return normalized;
+  }
+
   private async readSnapshot(target: string, signal?: AbortSignal | null): Promise<FileSnapshot> {
     throwIfAborted(signal);
     let stat: fsSync.Stats;
@@ -610,7 +628,7 @@ Paths must be workspace-relative. Use at most 20 file operations in one patch.`,
     let plan: PatchPlan;
     try {
       throwIfAborted(signal);
-      const operations = parsePatchEnvelope(params.input);
+      const operations = this.normalizeOperations(parsePatchEnvelope(params.input));
       plan = await this.planOperations(operations, signal);
       throwIfAborted(signal);
     } catch (error) {
diff --git a/App/memmy-agent/src/core/agent-runtime/tools/patch-envelope.ts b/App/memmy-agent/src/core/agent-runtime/tools/patch-envelope.ts
index a2b65f5ae..cc7f0a10a 100644
--- a/App/memmy-agent/src/core/agent-runtime/tools/patch-envelope.ts
+++ b/App/memmy-agent/src/core/agent-runtime/tools/patch-envelope.ts
@@ -1,3 +1,5 @@
+import path from "node:path";
+
 const BEGIN_PATCH = "*** Begin Patch";
 const END_PATCH = "*** End Patch";
 const END_OF_FILE = "*** End of File";
@@ -99,25 +101,27 @@ export function normalizePatchPath(raw: string): string {
   const value = raw.trim();
   if (!value) throw new PatchError("patch path cannot be empty");
   if (value.includes("\0")) throw new PatchError(`patch path contains a null byte: ${raw}`);
-  if (
-    value.startsWith("~") ||
-    value.startsWith("/") ||
-    value.startsWith("\\") ||
-    /^[A-Za-z]:/.test(value)
-  ) {
-    throw new PatchError(`patch path must be relative: ${raw}`);
+  if (value.startsWith("~")) throw new PatchError(`patch path must not use '~': ${raw}`);
+  if (/^[A-Za-z]:/.test(value) && !path.isAbsolute(value)) {
+    throw new PatchError(`patch path has an unsupported drive prefix: ${raw}`);
+  }
+  if (value.startsWith("\\") && !path.isAbsolute(value)) {
+    throw new PatchError(`patch path has an unsupported absolute form: ${raw}`);
   }
 
-  const segments = value.replace(/\\/g, "/").split("/");
-  if (segments.some((segment) => segment === "..")) {
+  const absolute = path.isAbsolute(value);
+  const slashPath = value.replace(/\\/g, "/");
+  if (!absolute && slashPath.split("/").some((segment) => segment === "..")) {
     throw new PatchError(`patch path must not contain '..': ${raw}`);
   }
-  const normalized = segments.filter((segment) => segment && segment !== ".").join("/");
+  const normalized = absolute
+    ? path.normalize(value).replace(/\\/g, "/")
+    : path.posix.normalize(slashPath);
   if (!normalized) throw new PatchError("patch path cannot be empty");
   return normalized;
 }
 
-function validatePathConflicts(operations: PatchFileOperation[]): void {
+export function validatePatchPathConflicts(operations: PatchFileOperation[]): void {
   const sources = new Map<string, PatchFileOperation>();
   const moveTargets = new Map<string, PatchUpdate>();
   const finalTargets: Array<{ key: string; path: string; line: number }> = [];
@@ -266,7 +270,7 @@ export function parsePatchEnvelope(input: string): PatchFileOperation[] {
   }
 
   if (operations.length === 0) fail(2, "a patch must contain at least one file operation");
-  validatePathConflicts(operations);
+  validatePatchPathConflicts(operations);
   return operations;
 }
 
diff --git a/App/memmy-agent/tests/core/agent-runtime/tools/apply-patch-tool.test.ts b/App/memmy-agent/tests/core/agent-runtime/tools/apply-patch-tool.test.ts
index 547cb136f..adcce77ca 100644
--- a/App/memmy-agent/tests/core/agent-runtime/tools/apply-patch-tool.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/tools/apply-patch-tool.test.ts
@@ -29,7 +29,7 @@ describe("ApplyPatchTool contract", () => {
     const tool = new ApplyPatchTool({ workspace: workspace() });
 
     expect(tool.description).toBe(
-      "Apply a patch to add, update, delete, or move one or more workspace-relative files.",
+      "Apply a patch to add, update, delete, or move one or more files inside the workspace.",
     );
     expect(tool.parameters).toMatchObject({
       type: "object",
@@ -45,7 +45,9 @@ describe("ApplyPatchTool contract", () => {
     expect(tool.parameters.properties.input.description).toContain("*** Move to:");
     expect(tool.parameters.properties.input.description).toContain("@@");
     expect(tool.parameters.properties.input.description).toContain("*** End of File");
-    expect(tool.parameters.properties.input.description).toContain("workspace-relative");
+    expect(tool.parameters.properties.input.description).toContain(
+      "workspace-relative or absolute paths inside the workspace",
+    );
     expect(tool.parameters.properties.input.description).toContain("at most 20");
   });
 
diff --git a/App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts b/App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts
new file mode 100644
index 000000000..2f56d057c
--- /dev/null
+++ b/App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts
@@ -0,0 +1,146 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ApplyPatchTool } from "../../../../src/core/agent-runtime/tools/apply-patch.js";
+import { EditFileTool, WriteFileTool } from "../../../../src/core/agent-runtime/tools/filesystem.js";
+
+const roots: string[] = [];
+
+function workspace(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "memmy-bug671-"));
+  roots.push(root);
+  return root;
+}
+
+function input(...lines: string[]): { input: string } {
+  return { input: ["*** Begin Patch", ...lines, "*** End Patch"].join("\n") };
+}
+
+afterEach(() => {
+  for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe("Bug 671 reproduction", () => {
+  it("accepts an in-workspace absolute path when adding", async () => {
+    const root = workspace();
+    const target = path.join(root, "added.txt");
+    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
+      `*** Add File: ${target}`,
+      "+added",
+    ));
+
+    expect(result).toContain("Patch applied:");
+    expect(fs.readFileSync(target, "utf8")).toBe("added\n");
+  });
+
+  it("accepts an in-workspace absolute path when updating", async () => {
+    const root = workspace();
+    const target = path.join(root, "updated.txt");
+    fs.writeFileSync(target, "before\n");
+    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
+      `*** Update File: ${target}`,
+      "@@",
+      "-before",
+      "+after",
+    ));
+
+    expect(result).toContain("Patch applied:");
+    expect(fs.readFileSync(target, "utf8")).toBe("after\n");
+  });
+
+  it("accepts an in-workspace absolute path when deleting", async () => {
+    const root = workspace();
+    const target = path.join(root, "deleted.txt");
+    fs.writeFileSync(target, "delete\n");
+    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
+      `*** Delete File: ${target}`,
+    ));
+
+    expect(result).toContain("Patch applied:");
+    expect(fs.existsSync(target)).toBe(false);
+  });
+
+  it("accepts an in-workspace absolute move source", async () => {
+    const root = workspace();
+    const source = path.join(root, "source.txt");
+    fs.writeFileSync(source, "move\n");
+    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
+      `*** Update File: ${source}`,
+      "*** Move to: moved.txt",
+    ));
+
+    expect(result).toContain("Patch applied:");
+    expect(fs.readFileSync(path.join(root, "moved.txt"), "utf8")).toBe("move\n");
+  });
+
+  it("accepts an in-workspace absolute move target", async () => {
+    const root = workspace();
+    const source = path.join(root, "source.txt");
+    const target = path.join(root, "moved.txt");
+    fs.writeFileSync(source, "move\n");
+    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
+      "*** Update File: source.txt",
+      `*** Move to: ${target}`,
+    ));
+
+    expect(result).toContain("Patch applied:");
+    expect(fs.readFileSync(target, "utf8")).toBe("move\n");
+  });
+
+  it("continues accepting relative apply_patch paths", async () => {
+    const root = workspace();
+    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
+      "*** Add File: relative.txt",
+      "+relative",
+    ));
+
+    expect(result).toContain("Patch applied:");
+    expect(fs.readFileSync(path.join(root, "relative.txt"), "utf8")).toBe("relative\n");
+  });
+
+  it("matches write_file and edit_file absolute-path behavior", async () => {
+    const root = workspace();
+    const target = path.join(root, "other-tools.txt");
+    const options = { workspace: root, allowedDir: root, postWriteValidation: false } as any;
+
+    expect(await new WriteFileTool(options).execute({ path: target, content: "before\n" }))
+      .toContain("Successfully wrote");
+    expect(await new EditFileTool(options).execute({
+      path: target,
+      old_text: "before",
+      new_text: "after",
+    })).toContain("Successfully edited file");
+    expect(fs.readFileSync(target, "utf8")).toBe("after\n");
+  });
+
+  it("still rejects traversal and symbolic links", async () => {
+    const root = workspace();
+    const outside = workspace();
+    const outsideFile = path.join(outside, "outside.txt");
+    fs.writeFileSync(outsideFile, "outside\n");
+    fs.symlinkSync(outsideFile, path.join(root, "outside-link.txt"));
+    const tool = new ApplyPatchTool({ workspace: root });
+
+    expect(await tool.execute(input("*** Add File: ../escaped.txt", "+escaped")))
+      .toContain("must not contain '..'");
+    expect(await tool.execute(input(`*** Delete File: ${outsideFile}`)))
+      .toContain("patch path escapes workspace");
+    expect(await tool.execute(input("*** Delete File: outside-link.txt")))
+      .toContain("symbolic links");
+    expect(fs.readFileSync(outsideFile, "utf8")).toBe("outside\n");
+  });
+
+  it("detects conflicts after absolute and relative paths are canonicalized", async () => {
+    const root = workspace();
+    const absolute = path.join(root, "same.txt");
+    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
+      `*** Add File: ${absolute}`,
+      "+first",
+      "*** Delete File: same.txt",
+    ));
+
+    expect(result).toContain("duplicate file operation path: same.txt");
+    expect(fs.existsSync(absolute)).toBe(false);
+  });
+});
diff --git a/App/memmy-agent/tests/core/agent-runtime/tools/patch-envelope.test.ts b/App/memmy-agent/tests/core/agent-runtime/tools/patch-envelope.test.ts
index 851ed76ce..fa25d76a7 100644
--- a/App/memmy-agent/tests/core/agent-runtime/tools/patch-envelope.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/tools/patch-envelope.test.ts
@@ -1,3 +1,4 @@
+import path from "node:path";
 import { describe, expect, it } from "vitest";
 import {
   PatchError,
@@ -121,12 +122,19 @@ describe("patch envelope parser", () => {
     );
   });
 
-  it.each(["~/a", "/a", "\\a", "C:a", "C:\\a", "../a", "a/../b", "a\0b"])(
+  it.each(["~/a", "C:a", "../a", "a/../b", "a\0b"])(
     "rejects unsafe path %s",
     (unsafe) => expect(() => normalizePatchPath(unsafe)).toThrow(PatchError),
   );
 
-  it("normalizes separators, empty segments, and dot segments", () => {
+  it.runIf(process.platform !== "win32")("rejects absolute paths for another platform", () => {
+    expect(() => normalizePatchPath("\\a")).toThrow(PatchError);
+    expect(() => normalizePatchPath("C:\\a")).toThrow(PatchError);
+  });
+
+  it("accepts absolute paths and normalizes separators and dot segments", () => {
+    const absolute = path.resolve("workspace", "src", "..", "file.ts");
+    expect(path.isAbsolute(normalizePatchPath(` ${absolute} `))).toBe(true);
     expect(normalizePatchPath(" ./src\\nested//./file.ts ")).toBe("src/nested/file.ts");
   });
 });
diff --git a/App/memmy-agent/tests/core/agent-runtime/tools/tool-descriptions.test.ts b/App/memmy-agent/tests/core/agent-runtime/tools/tool-descriptions.test.ts
index b0f662368..cd7e01a81 100644
--- a/App/memmy-agent/tests/core/agent-runtime/tools/tool-descriptions.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/tools/tool-descriptions.test.ts
@@ -12,7 +12,7 @@ describe("coding tool descriptions", () => {
     const writeFile = new WriteFileTool().description.toLowerCase();
 
     expect(applyPatch).toBe(
-      "apply a patch to add, update, delete, or move one or more workspace-relative files.",
+      "apply a patch to add, update, delete, or move one or more files inside the workspace.",
     );
 
     expect(editFile).toContain("small, exact replacement");

From 22f542f8a138d25f3b5d4f20590ee0392923aa8f Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Mon, 12 Oct 2026 17:55:23 +0800
Subject: [PATCH 22/85] fix: add correlated API and model latency diagnostics

---
 .../src/core/agent-runtime/loop.ts            | 10 ++++
 .../src/core/agent-runtime/runner.ts          |  2 +
 .../src/entrypoints/openai-like-api/server.ts | 10 ++++
 .../src/providers/openai-compat-provider.ts   |  4 ++
 App/memmy-agent/src/utils/request-timing.ts   | 24 +++++++++
 .../tests/utils/request-timing.test.ts        | 49 +++++++++++++++++++
 6 files changed, 99 insertions(+)
 create mode 100644 App/memmy-agent/src/utils/request-timing.ts
 create mode 100644 App/memmy-agent/tests/utils/request-timing.test.ts

diff --git a/App/memmy-agent/src/core/agent-runtime/loop.ts b/App/memmy-agent/src/core/agent-runtime/loop.ts
index 9b379fc5d..12e6738b4 100644
--- a/App/memmy-agent/src/core/agent-runtime/loop.ts
+++ b/App/memmy-agent/src/core/agent-runtime/loop.ts
@@ -1,3 +1,4 @@
+import { requestTiming } from "../../utils/request-timing.js";
 import { initializeDesktopScreenCapture } from '../../tools/computer-use/desktop-screen-capture.js';
 import fs from "node:fs";
 import path from "node:path";
@@ -3866,6 +3867,7 @@ export class AgentLoop {
         ctx.userPersistedEarly = Boolean(persisted.entry || ctx.msg.content.trim() || ctx.msg.media.length);
       } else {
         ctx.userPersistedEarly = this.persistUserMessageEarly(ctx.msg, ctx.session!);
+        requestTiming("agent.user_persisted");
       }
     }
     if (ctx.userPersistedEarly && !internalGoal) {
@@ -3888,6 +3890,7 @@ export class AgentLoop {
     if (revalidated.cwd !== sessionWorkspace || revalidated.projectId !== ctx.sessionProjectId) {
       throw new SessionWorkspaceError("workspace_conflict");
     }
+    requestTiming("agent.prompt_hooks_start");
     await this.lifecycleHook().beforeBuildSystemPrompt(new AgentHookContext({
       session: ctx.session,
       sessionKey: ctx.sessionKey,
@@ -3895,6 +3898,7 @@ export class AgentLoop {
       spec: { hostProjectId: ctx.sessionProjectId, workspace: sessionWorkspace },
       metadata: { lifecycle: "system_prompt" },
     }));
+    requestTiming("agent.prompt_hooks_end");
     const compactionOptions: {
       replayMaxMessages: number | null;
       notifyOnLockWait?: boolean;
@@ -3920,11 +3924,14 @@ export class AgentLoop {
       };
       compactionOptions.onCompactionEvent = ctx.onTokenCompactionEvent;
     }
+    requestTiming("agent.compaction_start");
     await (ctx.consolidator ?? this.consolidator).maybeConsolidateByTokens(
       ctx.session!,
       compactionOptions,
     );
+    requestTiming("agent.compaction_end");
     await initializeDesktopScreenCapture();
+    requestTiming("agent.screen_capture_ready");
     ctx.tools = this.createToolRegistry("turn", sessionWorkspace, {
       includeConnectedMcp: true,
       messageSendCallback: ctx.messageSendCallback,
@@ -4035,6 +4042,7 @@ export class AgentLoop {
   }
 
   async stateRun(ctx: TurnContext): Promise<string> {
+    requestTiming("agent.prepared");
     if (ctx.slot?.state === "running") ctx.slot.acceptingSteer = true;
     const settleSlot = (): void => {
       if (!ctx.slot || ctx.slot.state === "closed") return;
@@ -5477,7 +5485,9 @@ export class AgentLoop {
     const pendingMarker = new AsyncQueue<InboundMessage>();
     this.pendingQueues.set(key, pendingMarker);
     try {
+      requestTiming("agent.tools_start");
       await this.initializeRuntimeTools();
+      requestTiming("agent.tools_ready");
       const msg = new InboundMessage({
         channel,
         chatId,
diff --git a/App/memmy-agent/src/core/agent-runtime/runner.ts b/App/memmy-agent/src/core/agent-runtime/runner.ts
index 7a28486c0..8691a5a3c 100644
--- a/App/memmy-agent/src/core/agent-runtime/runner.ts
+++ b/App/memmy-agent/src/core/agent-runtime/runner.ts
@@ -1,3 +1,4 @@
+import { requestTiming } from "../../utils/request-timing.js";
 import crypto from "node:crypto";
 import path from "node:path";
 import { LLMProvider, LLMResponse, ToolCallRequest } from "../../providers/base.js";
@@ -784,6 +785,7 @@ export class AgentRunner {
   }
 
   private async callProvider(provider: any, args: any, stream = false): Promise<LLMResponse> {
+    requestTiming("model.call_start");
     if (stream) {
       if (typeof provider.chatStreamWithRetry === "function") return provider.chatStreamWithRetry(args);
       if (typeof provider.chatStream === "function") return provider.chatStream(args);
diff --git a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
index 4de00a531..9217d0262 100644
--- a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
+++ b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
@@ -1,3 +1,4 @@
+import { requestTiming, withRequestTiming } from "../../utils/request-timing.js";
 import fs from "node:fs";
 import path from "node:path";
 import { Config } from "../../config/schema.js";
@@ -249,6 +250,10 @@ async function callAgent(ctx: ApiContext, args: Record<string, any>): Promise<an
 }
 
 export async function handleChatCompletions(request: Request, ctx?: ApiContext): Promise<Response> {
+  return withRequestTiming(request.headers.get("x-memmy-trace-id"), () => handleTimedChatCompletions(request, ctx));
+}
+
+async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): Promise<Response> {
   const context = ctx ?? {
     agentLoop: null,
     modelName: "memmy",
@@ -324,10 +329,12 @@ export async function handleChatCompletions(request: Request, ctx?: ApiContext):
         void (async () => {
           let failed = false;
           const onStream = async (token: string) => {
+            if (token) requestTiming("api.first_content", true);
             if (token) emitted = true;
             write(sseChunk(token, context.modelName, chunkId));
           };
           const onProgress = withProgressCapabilities(async (content: string, options: Record<string, any> = {}) => {
+            if (options.reasoning && content) requestTiming("api.first_reasoning", true);
             if (options.reasoning && content) write(sseMemmyEvent("thinking_delta", { text: content }, context.modelName, chunkId));
             if (options.reasoningEnd) write(sseMemmyEvent("thinking_end", {}, context.modelName, chunkId));
             for (const event of options.toolEvents ?? []) {
@@ -354,6 +361,7 @@ export async function handleChatCompletions(request: Request, ctx?: ApiContext):
           const onStreamEnd = async () => undefined;
           try {
             await withSessionLock(context, sessionKey, async () => {
+              requestTiming("api.session_lock_acquired");
               const response = await withTimeout(
                 Promise.resolve(
                   callAgent(context, {
@@ -371,12 +379,14 @@ export async function handleChatCompletions(request: Request, ctx?: ApiContext):
               }
             });
           } catch {
+            requestTiming("api.error");
             failed = true;
           } finally {
             if (!failed) {
               write(sseChunk("", context.modelName, chunkId, "stop"));
               write(SSE_DONE);
             }
+            requestTiming("api.finished");
             close();
           }
         })();
diff --git a/App/memmy-agent/src/providers/openai-compat-provider.ts b/App/memmy-agent/src/providers/openai-compat-provider.ts
index 7b9b72d9b..3efa5f5f3 100644
--- a/App/memmy-agent/src/providers/openai-compat-provider.ts
+++ b/App/memmy-agent/src/providers/openai-compat-provider.ts
@@ -1,3 +1,4 @@
+import { requestTiming } from "../utils/request-timing.js";
 import crypto from "crypto";
 import OpenAI from "openai";
 import {
@@ -1172,11 +1173,14 @@ export class OpenAICompatProvider extends LLMProvider {
       }
       if (args.signal?.aborted) throw createProviderAbortError();
       const options = providerAbortOptions(args.signal);
+      requestTiming("model.http_start");
       const stream = options
         ? await this.client.chat.completions.create(kwargs as any, options as any)
         : await this.client.chat.completions.create(kwargs as any);
+      requestTiming("model.http_headers");
       const chunks: any[] = [];
       for await (const chunk of timedAsyncIterable(stream, idleTimeoutS)) {
+        requestTiming("model.first_chunk", true);
         if (args.signal?.aborted) throw createProviderAbortError();
         chunks.push(chunk);
         const choice =
diff --git a/App/memmy-agent/src/utils/request-timing.ts b/App/memmy-agent/src/utils/request-timing.ts
new file mode 100644
index 000000000..2b4a80713
--- /dev/null
+++ b/App/memmy-agent/src/utils/request-timing.ts
@@ -0,0 +1,24 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+
+const timing = new AsyncLocalStorage<{ traceId: string; started: number; seen: Set<string> }>();
+
+/** Timing fields only: never serialize prompts, credentials, URLs or errors. */
+export function requestTiming(stage: string, once = false): void {
+  const context = timing.getStore();
+  if (!context || (once && context.seen.has(stage))) return;
+  context.seen.add(stage);
+  process.stderr.write(`[memmy-timing] ${JSON.stringify({
+    traceId: context.traceId, stage, elapsedMs: Math.round(performance.now() - context.started),
+    at: new Date().toISOString(), pid: process.pid,
+  })}\n`);
+}
+
+export function withRequestTiming<T>(traceId: string | null, fn: () => T): T {
+  if (process.env.MEMMY_TIMING_LOG !== "1") return fn();
+  const safeId = traceId && /^[a-zA-Z0-9_-]{1,96}$/.test(traceId) ? traceId : randomUUID();
+  return timing.run({ traceId: safeId, started: performance.now(), seen: new Set() }, () => {
+    requestTiming("api.received");
+    return fn();
+  });
+}
diff --git a/App/memmy-agent/tests/utils/request-timing.test.ts b/App/memmy-agent/tests/utils/request-timing.test.ts
new file mode 100644
index 000000000..86ab5952a
--- /dev/null
+++ b/App/memmy-agent/tests/utils/request-timing.test.ts
@@ -0,0 +1,49 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { requestTiming, withRequestTiming } from "../../src/utils/request-timing.js";
+import { createApp } from "../../src/entrypoints/openai-like-api/server.js";
+
+afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); });
+
+it("keeps concurrent request timings separate and excludes prompt and invalid trace input", async () => {
+  vi.stubEnv("MEMMY_TIMING_LOG", "1");
+  const lines: string[] = [];
+  vi.spyOn(process.stderr, "write").mockImplementation((chunk: any) => { lines.push(String(chunk)); return true; });
+  await Promise.all(["trace-a", "trace-b"].map((id) => withRequestTiming(id, async () => {
+    await Promise.resolve();
+    requestTiming("model.first_chunk", true);
+    requestTiming("model.first_chunk", true);
+  })));
+  const records = lines.map((line) => JSON.parse(line.slice(15)));
+  for (const id of ["trace-a", "trace-b"]) {
+    expect(records.filter((row) => row.traceId === id).map((row) => row.stage)).toEqual(["api.received", "model.first_chunk"]);
+  }
+  withRequestTiming("Bearer secret\nprompt", () => requestTiming("api.finished"));
+  expect(lines.join("")).not.toMatch(/secret|prompt/);
+  vi.stubEnv("MEMMY_TIMING_LOG", "0");
+  const count = lines.length;
+  withRequestTiming("disabled", () => requestTiming("api.finished"));
+  expect(lines).toHaveLength(count);
+});
+
+it("retains the trace through an SSE response without logging its content", async () => {
+  vi.stubEnv("MEMMY_TIMING_LOG", "1");
+  const lines: string[] = [];
+  vi.spyOn(process.stderr, "write").mockImplementation((chunk: any) => { lines.push(String(chunk)); return true; });
+  const app = createApp({ processDirect: async (args: any) => {
+    await Promise.resolve();
+    requestTiming("model.http_start");
+    await args.onStream("private reply");
+    return "private reply";
+  } }, "test");
+  const response = await app.fetch(new Request("http://localhost/v1/chat/completions", {
+    method: "POST", headers: { "content-type": "application/json", "x-memmy-trace-id": "trace-sse" },
+    body: JSON.stringify({ stream: true, messages: [{ role: "user", content: "private prompt" }] }),
+  }));
+  expect(await response.text()).toContain("private reply");
+  const records = lines.map((line) => JSON.parse(line.slice(15)));
+  expect(records.map((row) => row.stage)).toEqual([
+    "api.received", "api.session_lock_acquired", "model.http_start", "api.first_content", "api.finished",
+  ]);
+  expect(records.every((row) => row.traceId === "trace-sse" && row.elapsedMs >= 0)).toBe(true);
+  expect(lines.join("")).not.toContain("private");
+});

From 27e0418fb285dca877ead6239323406c7d29cbd1 Mon Sep 17 00:00:00 2001
From: mikotosuki123 <yxyy99923@gmail.com>
Date: Mon, 12 Oct 2026 20:09:17 +0800
Subject: [PATCH 23/85] fix: wake exec waits on process completion and buffered
 output

---
 .../core/agent-runtime/tools/exec-session.ts  | 103 +++++--
 .../tools/exec-session-wait.test.ts           | 276 ++++++++++++++++++
 2 files changed, 358 insertions(+), 21 deletions(-)
 create mode 100644 App/memmy-agent/tests/core/agent-runtime/tools/exec-session-wait.test.ts

diff --git a/App/memmy-agent/src/core/agent-runtime/tools/exec-session.ts b/App/memmy-agent/src/core/agent-runtime/tools/exec-session.ts
index 96724ad3c..acfb887e1 100644
--- a/App/memmy-agent/src/core/agent-runtime/tools/exec-session.ts
+++ b/App/memmy-agent/src/core/agent-runtime/tools/exec-session.ts
@@ -11,6 +11,8 @@ export const DEFAULT_MAX_OUTPUT_CHARS = 10_000;
 export const MAX_OUTPUT_CHARS = 50_000;
 const STDIO_DRAIN_GRACE_MS = 1000;
 const PROCESS_TERMINATE_GRACE_MS = 1000;
+// Batch progress output without turning every stream chunk into a tool return.
+const OUTPUT_COALESCE_MS = 1000;
 export const EXEC_LIFECYCLE_ERROR =
   "Error: Command process exited but descendants kept stdout/stderr open; the managed process tree was terminated.";
 
@@ -41,10 +43,6 @@ export type ExecSessionInfo = {
   returncode: number | null;
 };
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 function processExited(child: ChildProcess): boolean {
   return child.exitCode != null || child.signalCode != null;
 }
@@ -169,18 +167,17 @@ export async function drainExitedProcessStreams({
   streamsClosed,
   forceCloseStreams,
   options,
+  abortSignal,
 }: {
   child: ChildProcess;
   closePromise: Promise<void>;
   streamsClosed: () => boolean;
   forceCloseStreams: () => void;
   options?: ManagedProcessOptions;
+  abortSignal?: AbortSignal | null;
 }): Promise<string | null> {
   if (streamsClosed()) return null;
-  const closedDuringDrain = await Promise.race([
-    closePromise.then(() => true),
-    sleep(STDIO_DRAIN_GRACE_MS).then(() => streamsClosed()),
-  ]);
+  const closedDuringDrain = await waitForDrain(closePromise, streamsClosed, abortSignal);
   if (closedDuringDrain || streamsClosed()) return null;
   await terminateManagedProcessTree(child, options);
   if (!streamsClosed()) forceCloseStreams();
@@ -201,20 +198,27 @@ function throwIfAborted(signal?: AbortSignal | null): void {
   if (signal?.aborted) throw createToolAbortError();
 }
 
-function abortableSleep(ms: number, signal?: AbortSignal | null): Promise<void> {
-  if (ms <= 0) return Promise.resolve();
+function waitForDrain(
+  closePromise: Promise<void>,
+  streamsClosed: () => boolean,
+  signal?: AbortSignal | null,
+): Promise<boolean> {
   throwIfAborted(signal);
-  if (!signal) return sleep(ms);
   return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      signal.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = () => {
+    let settled = false;
+    const finish = (closed: boolean, error?: Error) => {
+      if (settled) return;
+      settled = true;
       clearTimeout(timer);
-      reject(createToolAbortError());
+      signal?.removeEventListener("abort", onAbort);
+      if (error) reject(error);
+      else resolve(closed);
     };
-    signal.addEventListener("abort", onAbort, { once: true });
+    const onAbort = () => finish(false, createToolAbortError());
+    const timer = setTimeout(() => finish(streamsClosed()), STDIO_DRAIN_GRACE_MS);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    void closePromise.then(() => finish(true));
+    if (signal?.aborted) onAbort();
   });
 }
 
@@ -241,6 +245,7 @@ export class ExecSession {
   deadlineMs: number;
   lastAccess = Date.now();
   private chunks: string[] = [];
+  private outputStartedAt: number | null = null;
   private timedOut = false;
   private stderrStarted = false;
   private readonly stdoutDecoder: CommandOutputDecoder;
@@ -251,6 +256,7 @@ export class ExecSession {
   private lifecycleError: string | null = null;
   private readonly closePromise: Promise<void>;
   private resolveClose!: () => void;
+  private readonly outputWaiters = new Set<() => void>();
 
   constructor({
     command,
@@ -296,7 +302,7 @@ export class ExecSession {
       args.push("-c", command);
       this.process = spawnProcess(resolvedShell, args, { cwd, env, detached: true });
     }
-    this.process.on("error", (error) => this.chunks.push(`Error executing command: ${error.message}`));
+    this.process.on("error", (error) => this.appendStdout(`Error executing command: ${error.message}`));
     this.process.stdout.on("data", (chunk: Buffer) => {
       this.stdoutDecoder.push(chunk);
       this.appendStdout(this.stdoutDecoder.read());
@@ -348,7 +354,7 @@ export class ExecSession {
   ): Promise<SessionPoll> {
     this.lastAccess = Date.now();
     throwIfAborted(abortSignal);
-    if (yieldTimeMs > 0 && !this.isDone()) await abortableSleep(Math.min(yieldTimeMs, MAX_YIELD_MS), abortSignal);
+    if (yieldTimeMs > 0) await this.waitForActivity(Math.min(yieldTimeMs, MAX_YIELD_MS), abortSignal);
     throwIfAborted(abortSignal);
     if (!this.isDone() && Date.now() >= this.deadlineMs) {
       this.timedOut = true;
@@ -360,11 +366,13 @@ export class ExecSession {
         closePromise: this.closePromise,
         streamsClosed: () => this.streamsClosed,
         forceCloseStreams: () => this.forceCloseStreams(),
+        abortSignal,
       });
     }
     throwIfAborted(abortSignal);
     const raw = this.chunks.join("");
     this.chunks = [];
+    this.outputStartedAt = null;
     const [output, truncated] = truncateOutput(raw, maxOutputChars);
     const elapsed = Math.max(0, (Date.now() - this.startedAt) / 1000);
     const done = this.streamsClosed;
@@ -381,14 +389,66 @@ export class ExecSession {
     };
   }
 
+  private waitForActivity(ms: number, signal?: AbortSignal | null): Promise<void> {
+    throwIfAborted(signal);
+    if (this.isDone() || this.streamsClosed) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let outputTimer: ReturnType<typeof setTimeout> | undefined;
+      const finish = (error?: Error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(waitTimer);
+        clearTimeout(outputTimer);
+        this.outputWaiters.delete(onOutput);
+        this.process.removeListener("exit", onDone);
+        this.process.removeListener("close", onDone);
+        signal?.removeEventListener("abort", onAbort);
+        if (error) reject(error);
+        else resolve();
+      };
+      const onDone = () => finish();
+      const onAbort = () => finish(createToolAbortError());
+      const onOutput = () => {
+        if (this.isDone() || this.streamsClosed) {
+          finish();
+        } else if (this.chunks.length > 0 && outputTimer === undefined) {
+          // Anchor at the first readable output, never debounce continuous logs.
+          const remaining = Math.max(0, (this.outputStartedAt ?? Date.now()) + OUTPUT_COALESCE_MS - Date.now());
+          if (remaining === 0) finish();
+          else outputTimer = setTimeout(onDone, remaining);
+        }
+      };
+      const waitMs = Math.max(0, Math.min(ms, this.deadlineMs - Date.now()));
+      const waitTimer = setTimeout(onDone, waitMs);
+      this.process.once("exit", onDone);
+      this.process.once("close", onDone);
+      this.outputWaiters.add(onOutput);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      // Recheck after subscribing so completion, cancellation and buffered
+      // output cannot fall between checking state and installing listeners.
+      if (signal?.aborted) onAbort();
+      else onOutput();
+    });
+  }
+
+  private notifyOutputWaiters(): void {
+    for (const wake of this.outputWaiters) wake();
+  }
+
   private appendStdout(text: string): void {
-    if (text) this.chunks.push(text);
+    if (!text) return;
+    this.chunks.push(text);
+    this.outputStartedAt ??= Date.now();
+    this.notifyOutputWaiters();
   }
 
   private appendStderr(text: string): void {
     if (!text) return;
     this.chunks.push(this.stderrStarted ? text : `STDERR:\n${text}`);
+    this.outputStartedAt ??= Date.now();
     this.stderrStarted = true;
+    this.notifyOutputWaiters();
   }
 
   private finishStdoutOnce(): void {
@@ -412,6 +472,7 @@ export class ExecSession {
     if (this.streamsClosed) return;
     this.streamsClosed = true;
     this.resolveClose();
+    this.notifyOutputWaiters();
   }
 }
 
diff --git a/App/memmy-agent/tests/core/agent-runtime/tools/exec-session-wait.test.ts b/App/memmy-agent/tests/core/agent-runtime/tools/exec-session-wait.test.ts
new file mode 100644
index 000000000..620a9bb65
--- /dev/null
+++ b/App/memmy-agent/tests/core/agent-runtime/tools/exec-session-wait.test.ts
@@ -0,0 +1,276 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ExecSession, type SessionPoll } from "../../../../src/core/agent-runtime/tools/exec-session.js";
+
+const children: any[] = [];
+
+function childProcess() {
+  const child = new EventEmitter() as any;
+  child.stdin = new PassThrough();
+  child.stdout = new PassThrough();
+  child.stderr = new PassThrough();
+  child.exitCode = null;
+  child.signalCode = null;
+  child.kill = vi.fn(() => {
+    child.signalCode = "SIGTERM";
+    child.stdout.destroy();
+    child.stderr.destroy();
+    child.emit("exit", null, "SIGTERM");
+    close(child);
+    return true;
+  });
+  children.push(child);
+  return child;
+}
+
+function close(child: any) {
+  child.stdout.end();
+  child.stderr.end();
+  child.emit("close", child.exitCode, child.signalCode);
+}
+
+function exit(child: any, code = 0) {
+  child.exitCode = code;
+  child.emit("exit", code, null);
+  close(child);
+}
+
+function sessionFor(child: any, timeoutS?: number) {
+  return new ExecSession({ command: "controlled child", timeoutS, spawnProcess: (() => child) as any });
+}
+
+function observe(pending: Promise<SessionPoll>) {
+  const state: { settled: boolean; poll?: SessionPoll; error?: Error } = { settled: false };
+  void pending.then((poll) => { state.settled = true; state.poll = poll; }, (error) => { state.settled = true; state.error = error; });
+  return state;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(0);
+});
+
+afterEach(async () => {
+  for (const child of children.splice(0)) exit(child);
+  await vi.runOnlyPendingTimersAsync();
+  vi.clearAllTimers();
+  vi.useRealTimers();
+});
+
+describe("exec session waiting", () => {
+  it("returns when a silent process completes instead of waiting 30 seconds", async () => {
+    const child = childProcess();
+    const state = observe(sessionFor(child).poll(30_000, 10_000));
+    await vi.advanceTimersByTimeAsync(100);
+    exit(child);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(state.poll).toMatchObject({ done: true, exitCode: 0, output: "", elapsedS: 0.1 });
+    expect(vi.getTimerCount()).toBe(0);
+    expect(child.listenerCount("exit")).toBe(0);
+  });
+
+  it("wakes on signal exit with a null exit code", async () => {
+    const child = childProcess();
+    const state = observe(sessionFor(child).poll(30_000, 10_000));
+    await vi.advanceTimersByTimeAsync(50);
+    child.kill();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(state.poll).toMatchObject({ done: true, exitCode: null, elapsedS: 0.05 });
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("returns immediately if the process has already completed", async () => {
+    const child = childProcess();
+    const session = sessionFor(child);
+    child.stdout.write("finished\n");
+    exit(child);
+    expect(await session.poll(30_000, 10_000)).toMatchObject({ done: true, output: "finished\n", elapsedS: 0 });
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("coalesces stdout and stderr for one second from the first readable output", async () => {
+    const child = childProcess();
+    const session = sessionFor(child);
+    const state = observe(session.poll(30_000, 10_000));
+    await vi.advanceTimersByTimeAsync(100);
+    child.stdout.write("first\n");
+    await vi.advanceTimersByTimeAsync(500);
+    child.stderr.write("second\n");
+    await vi.advanceTimersByTimeAsync(499);
+    expect(state.settled).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(state.poll).toMatchObject({ done: false, output: "first\nSTDERR:\nsecond\n", elapsedS: 1.1 });
+    expect(vi.getTimerCount()).toBe(0);
+    expect(child.listenerCount("exit")).toBe(0);
+    expect(child.listenerCount("close")).toBe(1);
+    child.stdout.write("third\n");
+    expect((await session.poll(0, 10_000)).output).toBe("third\n");
+    expect((await session.poll(0, 10_000)).output).toBe("");
+  });
+
+  it("also coalesces output that was buffered before polling", async () => {
+    const child = childProcess();
+    const session = sessionFor(child);
+    child.stdout.write("buffered\n");
+    const state = observe(session.poll(30_000, 10_000));
+    await vi.advanceTimersByTimeAsync(999);
+    expect(state.settled).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(state.poll).toMatchObject({ done: false, output: "buffered\n", elapsedS: 1 });
+  });
+
+  it("returns stderr-only output without waiting the full yield", async () => {
+    const child = childProcess();
+    const session = sessionFor(child);
+    const state = observe(session.poll(30_000, 10_000));
+    child.stderr.write("diagnostic\n");
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(state.poll).toMatchObject({ done: false, output: "STDERR:\ndiagnostic\n" });
+  });
+
+  it("does not restart an expired output window when a later poll begins", async () => {
+    const child = childProcess();
+    const session = sessionFor(child);
+    child.stdout.write("ready-before-poll\n");
+    await vi.advanceTimersByTimeAsync(1200);
+    expect(await session.poll(30_000, 10_000)).toMatchObject({ done: false, output: "ready-before-poll\n", elapsedS: 1.2 });
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("does not restart the coalescing window for continuous small chunks", async () => {
+    const child = childProcess();
+    const state = observe(sessionFor(child).poll(30_000, 10_000));
+    for (let i = 1; i <= 80; i++) {
+      await vi.advanceTimersByTimeAsync(10);
+      child.stdout.write(`chunk-${i}\n`);
+      expect(state.settled).toBe(false);
+    }
+    await vi.advanceTimersByTimeAsync(209);
+    expect(state.settled).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(state.poll?.output).toBe(Array.from({ length: 80 }, (_, i) => `chunk-${i + 1}\n`).join(""));
+    expect(state.poll?.elapsedS).toBe(1.01);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("respects a shorter yield instead of extending it for coalescing", async () => {
+    const child = childProcess();
+    const state = observe(sessionFor(child).poll(200, 10_000));
+    await vi.advanceTimersByTimeAsync(100);
+    child.stdout.write("progress\n");
+    await vi.advanceTimersByTimeAsync(100);
+    expect(state.poll).toMatchObject({ done: false, output: "progress\n", elapsedS: 0.2 });
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("returns at the yield deadline when no output arrives", async () => {
+    const state = observe(sessionFor(childProcess()).poll(1000, 10_000));
+    await vi.advanceTimersByTimeAsync(999);
+    expect(state.settled).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(state.poll).toMatchObject({ done: false, output: "", elapsedS: 1 });
+  });
+
+  it("keeps zero-yield reads immediate and preserves the output limit", async () => {
+    const child = childProcess();
+    const session = sessionFor(child);
+    child.stdout.write("a".repeat(2000));
+    expect(await session.poll(0, 1000)).toMatchObject({ done: false, truncatedChars: 1000, elapsedS: 0 });
+    expect((await session.poll(0, 1000)).output).toBe("");
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("bypasses coalescing on completion and waits for the last stream bytes", async () => {
+    const child = childProcess();
+    const session = sessionFor(child);
+    const state = observe(session.poll(30_000, 10_000));
+    child.stdout.write("head|");
+    await vi.advanceTimersByTimeAsync(100);
+    child.exitCode = 0;
+    child.emit("exit", 0, null);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(state.settled).toBe(false);
+    await vi.advanceTimersByTimeAsync(50);
+    child.stdout.write("tail\n");
+    child.stderr.write("final-error\n");
+    close(child);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(state.poll).toMatchObject({ done: true, output: "head|tail\nSTDERR:\nfinal-error\n", elapsedS: 0.15 });
+    expect((await session.poll(0, 10_000)).output).toBe("");
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("cancels during coalescing and preserves unread output for a subsequent poll", async () => {
+    const child = childProcess();
+    const session = sessionFor(child);
+    const controller = new AbortController();
+    const state = observe(session.poll(30_000, 10_000, {}, controller.signal));
+    child.stdout.write("keep-this\n");
+    await vi.advanceTimersByTimeAsync(50);
+    controller.abort();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(state.error?.name).toBe("AbortError");
+    expect(child.kill).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+    expect(child.listenerCount("exit")).toBe(0);
+    expect((await session.poll(0, 10_000)).output).toBe("keep-this\n");
+  });
+
+  it("cancels while draining an exited process without consuming its final output", async () => {
+    const child = childProcess();
+    const session = sessionFor(child);
+    const controller = new AbortController();
+    child.exitCode = 0;
+    child.emit("exit", 0, null);
+    const state = observe(session.poll(30_000, 10_000, {}, controller.signal));
+    await vi.advanceTimersByTimeAsync(50);
+    controller.abort();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(state.error?.name).toBe("AbortError");
+    expect(vi.getTimerCount()).toBe(0);
+    child.stdout.write("late-tail\n");
+    close(child);
+    expect(await session.poll(0, 10_000)).toMatchObject({ done: true, output: "late-tail\n" });
+  });
+
+  it("rejects an already-cancelled poll without installing wait listeners", async () => {
+    const child = childProcess();
+    const controller = new AbortController();
+    controller.abort();
+    await expect(sessionFor(child).poll(30_000, 10_000, {}, controller.signal)).rejects.toMatchObject({ name: "AbortError" });
+    expect(vi.getTimerCount()).toBe(0);
+    expect(child.listenerCount("exit")).toBe(0);
+  });
+
+  it("honors the command timeout before a longer yield expires", async () => {
+    const child = childProcess();
+    const state = observe(sessionFor(child, 0.1).poll(30_000, 10_000));
+    await vi.advanceTimersByTimeAsync(100);
+    expect(state.poll).toMatchObject({ done: true, timedOut: true, elapsedS: 0.1 });
+    expect(child.kill).toHaveBeenCalledTimes(1);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("wakes when a spawn failure closes streams even without an exit code", async () => {
+    const child = childProcess();
+    const state = observe(sessionFor(child).poll(30_000, 10_000));
+    child.emit("error", new Error("spawn failed"));
+    close(child);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(state.poll).toMatchObject({ done: true, exitCode: null, output: "Error executing command: spawn failed" });
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("settles once when completion and the yield deadline coincide", async () => {
+    const child = childProcess();
+    const session = sessionFor(child);
+    setTimeout(() => exit(child), 1000);
+    const settled = vi.fn();
+    const pending = session.poll(1000, 10_000).then((poll) => { settled(); return poll; });
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(await pending).toMatchObject({ done: true, exitCode: 0 });
+    expect(settled).toHaveBeenCalledTimes(1);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

From ca38419ff1741bc649ddcc10a61fedc1f371363c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Sat, 10 Oct 2026 13:24:37 +0800
Subject: [PATCH 24/85] fix: locate bundled Codex CLI for hook trust
 installation

---
 .../outbound/skill-writer/codex/hook-trust.ts      | 14 ++++++++++++--
 .../agent-source/integration/codex/hook-trust.ts   | 14 ++++++++++++--
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/App/backend/src/adapters/outbound/skill-writer/codex/hook-trust.ts b/App/backend/src/adapters/outbound/skill-writer/codex/hook-trust.ts
index a46425ca0..27edba3f5 100644
--- a/App/backend/src/adapters/outbound/skill-writer/codex/hook-trust.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/codex/hook-trust.ts
@@ -1,6 +1,7 @@
 /** Codex hook trust persistence through the Codex app-server protocol. */
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { accessSync, constants, statSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, join, normalize } from "node:path";
 
 const APP_SERVER_REQUEST_TIMEOUT_MS = 10_000;
@@ -283,8 +284,17 @@ function handleResponseLine(line: string, pending: Map<number, PendingRequest>):
 
 function resolveCodexExecutable(codexHomeDirectory: string): string {
   const executableName = process.platform === "win32" ? "codex.exe" : "codex";
-  const bundledExecutable = join(codexHomeDirectory, "plugins", ".plugin-appserver", executableName);
-  return isExecutableFile(bundledExecutable) ? bundledExecutable : executableName;
+  const candidates = [join(codexHomeDirectory, "plugins", ".plugin-appserver", executableName)];
+  if (process.platform === "darwin") {
+    // The desktop process may not inherit the shell PATH where ChatGPT exposes Codex CLI.
+    const codexCliPath = join("Contents", "Resources", "codex-cli", "CodexCLI.app", "Contents", "MacOS", "codex");
+    candidates.push(
+      join("/Applications", "ChatGPT.app", codexCliPath),
+      join(homedir(), "Applications", "ChatGPT.app", codexCliPath)
+    );
+  }
+
+  return candidates.find(isExecutableFile) ?? executableName;
 }
 
 function isExecutableFile(filePath: string): boolean {
diff --git a/Memory/src/agent-source/integration/codex/hook-trust.ts b/Memory/src/agent-source/integration/codex/hook-trust.ts
index a46425ca0..27edba3f5 100644
--- a/Memory/src/agent-source/integration/codex/hook-trust.ts
+++ b/Memory/src/agent-source/integration/codex/hook-trust.ts
@@ -1,6 +1,7 @@
 /** Codex hook trust persistence through the Codex app-server protocol. */
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { accessSync, constants, statSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, join, normalize } from "node:path";
 
 const APP_SERVER_REQUEST_TIMEOUT_MS = 10_000;
@@ -283,8 +284,17 @@ function handleResponseLine(line: string, pending: Map<number, PendingRequest>):
 
 function resolveCodexExecutable(codexHomeDirectory: string): string {
   const executableName = process.platform === "win32" ? "codex.exe" : "codex";
-  const bundledExecutable = join(codexHomeDirectory, "plugins", ".plugin-appserver", executableName);
-  return isExecutableFile(bundledExecutable) ? bundledExecutable : executableName;
+  const candidates = [join(codexHomeDirectory, "plugins", ".plugin-appserver", executableName)];
+  if (process.platform === "darwin") {
+    // The desktop process may not inherit the shell PATH where ChatGPT exposes Codex CLI.
+    const codexCliPath = join("Contents", "Resources", "codex-cli", "CodexCLI.app", "Contents", "MacOS", "codex");
+    candidates.push(
+      join("/Applications", "ChatGPT.app", codexCliPath),
+      join(homedir(), "Applications", "ChatGPT.app", codexCliPath)
+    );
+  }
+
+  return candidates.find(isExecutableFile) ?? executableName;
 }
 
 function isExecutableFile(filePath: string): boolean {

From f0bd53b9da7d2af343464d1c856a11c38da48e85 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Mon, 12 Oct 2026 11:15:05 +0800
Subject: [PATCH 25/85] fix: preserve hook removals and roll back failed Codex
 trust

---
 .../outbound/skill-writer/codex/target.ts     | 105 ++++++++++++++----
 .../skill-writer/codex/tests/target.test.ts   |  43 ++++++-
 .../agent-source-store/repository.ts          |  21 ++++
 .../tests/repository.test.ts                  |  19 ++++
 ...0-agent-source-auto-inject-suppression.sql |   3 +
 .../app-state-store/tests/index.test.ts       |   4 +-
 .../agent-source-auto-inject-service.ts       |  23 +++-
 .../src/services/agent-source-service.ts      |  21 +++-
 App/backend/src/services/index.ts             |   1 +
 .../agent-source-auto-inject-service.test.ts  |  54 +++++++++
 .../tests/agent-source-service.test.ts        |   5 +
 .../agent-source/integration/codex/target.ts  | 105 ++++++++++++++----
 Memory/src/agent-source/runtime.ts            |  30 ++++-
 Memory/tests/agent-source-runtime.test.ts     |  62 ++++++++++-
 14 files changed, 436 insertions(+), 60 deletions(-)
 create mode 100644 App/backend/src/infrastructure/app-state-store/migrations/0030-agent-source-auto-inject-suppression.sql

diff --git a/App/backend/src/adapters/outbound/skill-writer/codex/target.ts b/App/backend/src/adapters/outbound/skill-writer/codex/target.ts
index a292d4d33..2c0c65ab5 100644
--- a/App/backend/src/adapters/outbound/skill-writer/codex/target.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/codex/target.ts
@@ -1,5 +1,5 @@
 /** Target module. */
-import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, readlink, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { resolveCodexHomeDirectory } from "../../agent-paths.js";
@@ -118,18 +118,26 @@ export function createCodexSkillTarget(deps: CreateCodexSkillTargetDeps = {}): S
         memmy_config_path: memmyConfigPath,
         ...(await readMemmyMemoryServiceConfig(memmyConfigPath))
       };
-      await mkdir(hookDirectory, { recursive: true });
-      await writeFileAtomically(hookConfigPath, `${JSON.stringify(hookConfig, null, 2)}\n`);
-      await writeFileAtomically(hookScriptPath, renderMemmyResumeHookScript({ source: CODEX_TARGET_ID, mode: "codex" }));
-      await writeFileAtomically(
-        join(hookDirectory, WORKSPACE_BRIDGE_FILE_NAME),
-        await loadMemmyWorkspaceBridgeRuntimeAsset()
-      );
       const hooksFilePath = join(root, HOOKS_FILE_NAME);
+      const bridgePath = join(hookDirectory, WORKSPACE_BRIDGE_FILE_NAME);
       const hookCommand = createNodeHookCommand(hookScriptPath);
-      await upsertCodexHookConfig(hooksFilePath, hookCommand);
-      await rm(join(root, HOOK_DIRECTORY_NAME, LEGACY_HOOK_SCRIPT_FILE_NAME), { force: true });
+      await withCodexHookFileRollback(
+        [hookConfigPath, hookScriptPath, bridgePath, hooksFilePath],
+        async () => {
+          await mkdir(hookDirectory, { recursive: true });
+          await writeFileAtomically(hookConfigPath, `${JSON.stringify(hookConfig, null, 2)}\n`);
+          await writeFileAtomically(hookScriptPath, renderMemmyResumeHookScript({ source: CODEX_TARGET_ID, mode: "codex" }));
+          await writeFileAtomically(bridgePath, await loadMemmyWorkspaceBridgeRuntimeAsset());
+          await upsertCodexHookConfig(hooksFilePath, hookCommand);
+          await trustHooks({ codexHomeDirectory: root, hooksFilePath, hookCommand });
+          await writeFileAtomically(
+            hookConfigPath,
+            `${JSON.stringify({ ...hookConfig, ...(await memmyHookRevisionField(CODEX_TARGET_ID, "codex")) }, null, 2)}\n`
+          );
+        }
+      );
 
+      await rm(join(hookDirectory, LEGACY_HOOK_SCRIPT_FILE_NAME), { force: true });
       const manifest = renderMemmyPluginSkillManifest(_targetId);
       const filePath = join(root, TARGET_FILE_NAME);
       await writeFileAtomically(
@@ -138,15 +146,6 @@ export function createCodexSkillTarget(deps: CreateCodexSkillTargetDeps = {}): S
       );
       await replaceMemmySkillDirectory(root, manifest);
       await replaceMemmyResumeSkillDirectory(root, CODEX_TARGET_ID);
-      await trustHooks({
-        codexHomeDirectory: root,
-        hooksFilePath,
-        hookCommand
-      });
-      await writeFileAtomically(
-        hookConfigPath,
-        `${JSON.stringify({ ...hookConfig, ...(await memmyHookRevisionField(CODEX_TARGET_ID, "codex")) }, null, 2)}\n`
-      );
     },
 
     async uninstallPlugin(_targetId) {
@@ -335,11 +334,73 @@ function createMarkerBlockPattern(startMarker: string, endMarker = END_MARKER):
   return new RegExp(`${escapeRegExp(startMarker)}\\n[\\s\\S]*?${escapeRegExp(endMarker)}\\n?`, "m");
 }
 
-async function writeFileAtomically(filePath: string, content: string): Promise<void> {
+async function writeFileAtomically(filePath: string, content: string | Buffer, mode?: number): Promise<void> {
   await mkdir(dirname(filePath), { recursive: true });
   const tempPath = join(dirname(filePath), `.${basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
-  await writeFile(tempPath, content, "utf8");
-  await rename(tempPath, filePath);
+  try {
+    await writeFile(tempPath, content, { encoding: "utf8", ...(mode === undefined ? {} : { mode }) });
+    await rename(tempPath, filePath);
+  } finally {
+    await rm(tempPath, { force: true });
+  }
+}
+
+type CodexHookFileSnapshot =
+  | { path: string; kind: "missing" }
+  | { path: string; kind: "file"; content: Buffer; mode: number }
+  | { path: string; kind: "symlink"; target: string };
+
+async function withCodexHookFileRollback<T>(paths: string[], operation: () => Promise<T>): Promise<T> {
+  const snapshots = await Promise.all(paths.map(snapshotCodexHookFile));
+  try {
+    return await operation();
+  } catch (error) {
+    const rollbackResults = await Promise.allSettled(snapshots.map(restoreCodexHookFile));
+    const rollbackErrors = rollbackResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [error, ...rollbackErrors],
+        "Codex hook installation failed and its files could not be fully rolled back"
+      );
+    }
+
+    throw error;
+  }
+}
+
+async function snapshotCodexHookFile(filePath: string): Promise<CodexHookFileSnapshot> {
+  try {
+    const metadata = await lstat(filePath);
+    if (metadata.isSymbolicLink()) {
+      return { path: filePath, kind: "symlink", target: await readlink(filePath) };
+    }
+    if (!metadata.isFile()) {
+      throw new Error(`Codex hook path is not a regular file: ${filePath}`);
+    }
+
+    return { path: filePath, kind: "file", content: await readFile(filePath), mode: metadata.mode & 0o777 };
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return { path: filePath, kind: "missing" };
+    }
+
+    throw error;
+  }
+}
+
+async function restoreCodexHookFile(snapshot: CodexHookFileSnapshot): Promise<void> {
+  if (snapshot.kind === "missing") {
+    await rm(snapshot.path, { force: true });
+    return;
+  }
+
+  if (snapshot.kind === "symlink") {
+    await rm(snapshot.path, { force: true });
+    await symlink(snapshot.target, snapshot.path);
+    return;
+  }
+
+  await writeFileAtomically(snapshot.path, snapshot.content, snapshot.mode);
 }
 
 function escapeRegExp(input: string): string {
diff --git a/App/backend/src/adapters/outbound/skill-writer/codex/tests/target.test.ts b/App/backend/src/adapters/outbound/skill-writer/codex/tests/target.test.ts
index 5a3e6855e..3db0efef8 100644
--- a/App/backend/src/adapters/outbound/skill-writer/codex/tests/target.test.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/codex/tests/target.test.ts
@@ -1,5 +1,5 @@
 /** Target tests. */
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import type { AddressInfo } from "node:net";
@@ -184,6 +184,47 @@ describe("codex skill target", () => {
     });
 
     await expect(target.installPlugin?.("codex")).rejects.toThrow("trust failed");
+    expect(existsSync(join(rootDirectory, "hooks.json"))).toBe(false);
+    expect(existsSync(join(rootDirectory, "hooks", "memmy-resume-hook.mjs"))).toBe(false);
+    expect(existsSync(join(rootDirectory, "hooks", "memmy-memory-config.json"))).toBe(false);
+    expect(existsSync(join(rootDirectory, "hooks", "memmy-workspace-bridge.mjs"))).toBe(false);
+    expect(existsSync(join(rootDirectory, "AGENTS.md"))).toBe(false);
+    expect(existsSync(join(rootDirectory, "skills", "memmy-memory"))).toBe(false);
+  });
+
+  it("restores existing hook files and links when Codex cannot persist hook trust", async () => {
+    const { rootDirectory, memmyConfigPath } = createFixture();
+    const hookDirectory = join(rootDirectory, "hooks");
+    mkdirSync(hookDirectory);
+    const hooksFilePath = join(rootDirectory, "hooks.json");
+    const hookConfigPath = join(hookDirectory, "memmy-memory-config.json");
+    const hookScriptPath = join(hookDirectory, "memmy-resume-hook.mjs");
+    const bridgePath = join(hookDirectory, "memmy-workspace-bridge.mjs");
+    const bridgeTargetPath = join(rootDirectory, "previous-workspace-bridge.mjs");
+    const originalHooks = '{"hooks":{"Stop":[]}}\n';
+    writeFileSync(hooksFilePath, originalHooks);
+    writeFileSync(hookConfigPath, "previous hook config\n");
+    writeFileSync(hookScriptPath, "previous hook script\n");
+    writeFileSync(bridgeTargetPath, "previous bridge\n");
+    symlinkSync(bridgeTargetPath, bridgePath);
+    const target = createCodexSkillTarget({
+      rootDirectory,
+      memmyConfigPath,
+      trustHooks: async () => {
+        throw new Error("trust failed");
+      }
+    });
+
+    await expect(target.installPlugin?.("codex")).rejects.toThrow("trust failed");
+
+    expect(readFileSync(hooksFilePath, "utf8")).toBe(originalHooks);
+    expect(readFileSync(hookConfigPath, "utf8")).toBe("previous hook config\n");
+    expect(readFileSync(hookScriptPath, "utf8")).toBe("previous hook script\n");
+    expect(lstatSync(bridgePath).isSymbolicLink()).toBe(true);
+    expect(readlinkSync(bridgePath)).toBe(bridgeTargetPath);
+    expect(readFileSync(bridgePath, "utf8")).toBe("previous bridge\n");
+    expect(existsSync(join(rootDirectory, "AGENTS.md"))).toBe(false);
+    expect(existsSync(join(rootDirectory, "skills", "memmy-memory"))).toBe(false);
   });
 
   it("installs a UserPromptSubmit hook that blocks resume commands with top L1 candidates", async () => {
diff --git a/App/backend/src/infrastructure/agent-source-store/repository.ts b/App/backend/src/infrastructure/agent-source-store/repository.ts
index 12a4fcf58..be0dbf7c0 100644
--- a/App/backend/src/infrastructure/agent-source-store/repository.ts
+++ b/App/backend/src/infrastructure/agent-source-store/repository.ts
@@ -60,6 +60,8 @@ export interface AgentSourceRepository {
   upsertSource(input: UpsertAgentSourceInput): void;
   removeSource(sourceId: string): void;
   setStatus(sourceId: string, status: AgentSourceStatus): void;
+  setConnectionState(sourceId: string, status: AgentSourceStatus, autoInjectSuppressed: boolean): void;
+  isAutoInjectSuppressed(sourceId: string): boolean;
   setLastScannedAt(sourceId: string, scannedAt: string): void;
   getScanWatermark(sourceId: string): AgentSourceScanWatermark | null;
   upsertScanWatermark(input: UpsertAgentSourceScanWatermarkInput): void;
@@ -167,6 +169,25 @@ export function createAgentSourceRepository(
       );
     },
 
+    setConnectionState(sourceId, status, autoInjectSuppressed) {
+      db.prepare(
+        "UPDATE account_agent_sources SET status = ?, auto_inject_suppressed = ?, updated_at = ? WHERE uuid = ? AND source_id = ?"
+      ).run(
+        status,
+        autoInjectSuppressed ? 1 : 0,
+        new Date().toISOString(),
+        INSTALLATION_SCAN_SCOPE_UUID,
+        sourceId
+      );
+    },
+
+    isAutoInjectSuppressed(sourceId) {
+      const row = db.prepare(
+        "SELECT auto_inject_suppressed FROM account_agent_sources WHERE uuid = ? AND source_id = ?"
+      ).get(INSTALLATION_SCAN_SCOPE_UUID, sourceId) as { auto_inject_suppressed: 0 | 1 } | undefined;
+      return row?.auto_inject_suppressed === 1;
+    },
+
     setLastScannedAt(sourceId, scannedAt) {
       db.prepare("UPDATE account_agent_sources SET last_scanned_at = ?, updated_at = ? WHERE uuid = ? AND source_id = ?").run(
         scannedAt,
diff --git a/App/backend/src/infrastructure/agent-source-store/tests/repository.test.ts b/App/backend/src/infrastructure/agent-source-store/tests/repository.test.ts
index 159ff5e98..7469b68c8 100644
--- a/App/backend/src/infrastructure/agent-source-store/tests/repository.test.ts
+++ b/App/backend/src/infrastructure/agent-source-store/tests/repository.test.ts
@@ -90,6 +90,24 @@ describe("agent source repository", () => {
     expect(repository.listSources()).toEqual([]);
   });
 
+  it("persists auto-inject suppression across status-only updates", () => {
+    const repository = createRepository();
+    repository.upsertSource({
+      sourceId: "cursor",
+      displayName: "Cursor",
+      dataPath: "/Users/test/Cursor",
+      builtin: true
+    });
+
+    repository.setConnectionState("cursor", "not_connected", true);
+    expect(repository.isAutoInjectSuppressed("cursor")).toBe(true);
+    repository.setStatus("cursor", "plugin_installed");
+    expect(repository.isAutoInjectSuppressed("cursor")).toBe(true);
+
+    repository.setConnectionState("cursor", "plugin_installed", false);
+    expect(repository.isAutoInjectSuppressed("cursor")).toBe(false);
+  });
+
   it("tracks ingestion dedupe keys without double-counting repeated marks", () => {
     const repository = createRepository();
     repository.upsertSource({
@@ -184,6 +202,7 @@ function createRepository(): AgentSourceRepository {
       data_path       TEXT NOT NULL,
       builtin         INTEGER NOT NULL CHECK(builtin IN (0,1)),
       status          TEXT NOT NULL DEFAULT 'not_connected',
+      auto_inject_suppressed INTEGER NOT NULL DEFAULT 0 CHECK(auto_inject_suppressed IN (0,1)),
       last_scanned_at TEXT,
       sync_recipe_json TEXT,
       created_at      TEXT NOT NULL DEFAULT (datetime('now')),
diff --git a/App/backend/src/infrastructure/app-state-store/migrations/0030-agent-source-auto-inject-suppression.sql b/App/backend/src/infrastructure/app-state-store/migrations/0030-agent-source-auto-inject-suppression.sql
new file mode 100644
index 000000000..55412239c
--- /dev/null
+++ b/App/backend/src/infrastructure/app-state-store/migrations/0030-agent-source-auto-inject-suppression.sql
@@ -0,0 +1,3 @@
+ALTER TABLE account_agent_sources
+  ADD COLUMN auto_inject_suppressed INTEGER NOT NULL DEFAULT 0
+    CHECK(auto_inject_suppressed IN (0,1));
diff --git a/App/backend/src/infrastructure/app-state-store/tests/index.test.ts b/App/backend/src/infrastructure/app-state-store/tests/index.test.ts
index 9ffebda22..c46ac36c9 100644
--- a/App/backend/src/infrastructure/app-state-store/tests/index.test.ts
+++ b/App/backend/src/infrastructure/app-state-store/tests/index.test.ts
@@ -131,8 +131,8 @@ describe("app state store migrations", () => {
     expect(settings.menuBarIconEnabled).toBe(true);
     expect(settings.stopMemoryServiceOnExit).toBe(false);
     expect(agentSources).toEqual([]);
-    expect(firstMigrationCount).toBe(34);
-    expect(secondMigrationCount).toBe(34);
+    expect(firstMigrationCount).toBe(35);
+    expect(secondMigrationCount).toBe(35);
   });
 
   it("preserves the authenticated account when upgrading the legacy 0007 database", () => {
diff --git a/App/backend/src/services/agent-source-auto-inject-service.ts b/App/backend/src/services/agent-source-auto-inject-service.ts
index c97eed893..a5ddd7dfe 100644
--- a/App/backend/src/services/agent-source-auto-inject-service.ts
+++ b/App/backend/src/services/agent-source-auto-inject-service.ts
@@ -23,9 +23,11 @@ export interface AgentSourceAutoInjectService {
 }
 
 export interface CreateAgentSourceAutoInjectServiceOptions {
-  agentSources: Pick<AgentSourceService, "list" | "installSkill" | "installPlugin" | "isInstalledHookCurrent">;
+  agentSources: Pick<AgentSourceService, "list" | "installSkill" | "installPlugin" | "isInstalledHookCurrent">
+    & Partial<Pick<AgentSourceService, "uninstallSkill" | "uninstallPlugin">>;
   permissionManager: Pick<PermissionManager, "canWriteAgentSkill">;
   getScanPreferences: () => ScanPreferences;
+  isAutoInjectSuppressed?: (sourceId: string) => boolean;
 }
 
 /** Creates create agent source auto inject service. */
@@ -54,6 +56,7 @@ export function createAgentSourceAutoInjectService(
 
         for (const source of sources) {
           if (!isUpdatableInstalledHook(source)) continue;
+          if (options.isAutoInjectSuppressed?.(source.sourceId)) continue;
           if (!(await options.permissionManager.canWriteAgentSkill({ agentSourceId: source.sourceId }))) {
             continue;
           }
@@ -61,6 +64,11 @@ export function createAgentSourceAutoInjectService(
           try {
             if (await options.agentSources.isInstalledHookCurrent(source.sourceId)) continue;
             await options.agentSources.installPlugin(source.sourceId, { installType: "auto_inject" });
+            if (options.isAutoInjectSuppressed?.(source.sourceId)) {
+              if (!options.agentSources.uninstallPlugin) throw new Error("Cannot clean up an auto-updated source removed during installation");
+              await options.agentSources.uninstallPlugin(source.sourceId, { installType: "auto_inject" });
+              continue;
+            }
             installed.push(source.sourceId);
           } catch (error) {
             failed.push({
@@ -85,6 +93,7 @@ export function createAgentSourceAutoInjectService(
           if (!AUTO_INJECT_AGENT_SOURCE_IDS.has(source.sourceId) || !source.builtin || !source.available || source.status !== "not_connected") {
             continue;
           }
+          if (options.isAutoInjectSuppressed?.(source.sourceId)) continue;
 
           if (!(await options.permissionManager.canWriteAgentSkill({ agentSourceId: source.sourceId }))) {
             continue;
@@ -94,7 +103,17 @@ export function createAgentSourceAutoInjectService(
             if (HOOK_OR_PLUGIN_AGENT_SOURCE_IDS.has(source.sourceId)) {
               await options.agentSources.installPlugin(source.sourceId, { installType: "auto_inject" });
             } else {
-              await options.agentSources.installSkill(source.sourceId);
+              await options.agentSources.installSkill(source.sourceId, { installType: "auto_inject" });
+            }
+            if (options.isAutoInjectSuppressed?.(source.sourceId)) {
+              if (HOOK_OR_PLUGIN_AGENT_SOURCE_IDS.has(source.sourceId)) {
+                if (!options.agentSources.uninstallPlugin) throw new Error("Cannot clean up an auto-injected source removed during installation");
+                await options.agentSources.uninstallPlugin(source.sourceId, { installType: "auto_inject" });
+              } else {
+                if (!options.agentSources.uninstallSkill) throw new Error("Cannot clean up an auto-injected source removed during installation");
+                await options.agentSources.uninstallSkill(source.sourceId);
+              }
+              continue;
             }
             installed.push(source.sourceId);
           } catch (error) {
diff --git a/App/backend/src/services/agent-source-service.ts b/App/backend/src/services/agent-source-service.ts
index cbecc0dfe..2c7355553 100644
--- a/App/backend/src/services/agent-source-service.ts
+++ b/App/backend/src/services/agent-source-service.ts
@@ -99,7 +99,7 @@ export interface AgentSourceService {
   syncManaged(sourceId: string): Promise<ManagedAgentSourceImportResult>;
   updateManaged(sourceId: string, input: ManagedAgentSourceUpdateInput): Promise<AgentSourceView>;
   remove(sourceId: string): Promise<void>;
-  installSkill(sourceId: string): Promise<void>;
+  installSkill(sourceId: string, action?: Pick<AgentSourcePluginActionInput, "installType">): Promise<void>;
   uninstallSkill(sourceId: string): Promise<void>;
   installPlugin(sourceId: string, action?: AgentSourcePluginActionInput): Promise<void>;
   uninstallPlugin(sourceId: string, action?: AgentSourcePluginActionInput): Promise<void>;
@@ -352,8 +352,9 @@ export function createAgentSourceService(options: CreateAgentSourceServiceOption
       options.agentSourceRepository.removeSource(sourceId);
     },
 
-    async installSkill(sourceId) {
+    async installSkill(sourceId, action = {}) {
       const startedAt = Date.now();
+      const installType = normalizePluginInstallType(action.installType);
       const statusBefore = readSourceStatus(options, sourceId);
       const permission = await readScanPermission(options);
       const builtin = readSourceBuiltin(options, sourceId);
@@ -361,7 +362,11 @@ export function createAgentSourceService(options: CreateAgentSourceServiceOption
         await ensureSourceAvailable(options, sourceId);
         await options.skillDistributionService.install(sourceId);
         ensureSourceExists(options, sourceId);
-        options.agentSourceRepository.setStatus(sourceId, "skill_installed");
+        if (installType === "auto_inject") {
+          options.agentSourceRepository.setStatus(sourceId, "skill_installed");
+        } else {
+          options.agentSourceRepository.setConnectionState(sourceId, "skill_installed", false);
+        }
         agentSourceAnalytics.trackSkillInstalled({
           sourceId,
           builtin,
@@ -394,7 +399,7 @@ export function createAgentSourceService(options: CreateAgentSourceServiceOption
       try {
         await options.skillDistributionService.uninstall(sourceId);
         ensureSourceExists(options, sourceId);
-        options.agentSourceRepository.setStatus(sourceId, "not_connected");
+        options.agentSourceRepository.setConnectionState(sourceId, "not_connected", true);
         agentSourceAnalytics.trackSkillUninstalled({
           sourceId,
           builtin,
@@ -428,7 +433,11 @@ export function createAgentSourceService(options: CreateAgentSourceServiceOption
         await ensureSourceAvailable(options, sourceId);
         await options.skillDistributionService.installPlugin(sourceId);
         ensureSourceExists(options, sourceId);
-        options.agentSourceRepository.setStatus(sourceId, "plugin_installed");
+        if (installType === "auto_inject") {
+          options.agentSourceRepository.setStatus(sourceId, "plugin_installed");
+        } else {
+          options.agentSourceRepository.setConnectionState(sourceId, "plugin_installed", false);
+        }
         agentSourceAnalytics.trackPluginInstalled({
           sourceId,
           permission,
@@ -465,7 +474,7 @@ export function createAgentSourceService(options: CreateAgentSourceServiceOption
       try {
         await options.skillDistributionService.uninstallPlugin(sourceId);
         ensureSourceExists(options, sourceId);
-        options.agentSourceRepository.setStatus(sourceId, "not_connected");
+        options.agentSourceRepository.setConnectionState(sourceId, "not_connected", true);
         agentSourceAnalytics.trackPluginUninstalled({
           sourceId,
           permission,
diff --git a/App/backend/src/services/index.ts b/App/backend/src/services/index.ts
index 606e1ce35..65f47e091 100644
--- a/App/backend/src/services/index.ts
+++ b/App/backend/src/services/index.ts
@@ -216,6 +216,7 @@ export function createBackendServices(options: CreateBackendServicesOptions): Ba
     agentSourceAutoInject: createAgentSourceAutoInjectService({
       agentSources,
       permissionManager: options.permissionManager,
+      isAutoInjectSuppressed: (sourceId) => options.appStateStore.repositories.agentSources.isAutoInjectSuppressed(sourceId),
       getScanPreferences: () => options.scanPreferencesStore?.getScanPreferences()
         ?? options.appStateStore.repositories.bootstrap.getScanPreferences()
     }),
diff --git a/App/backend/src/services/tests/agent-source-auto-inject-service.test.ts b/App/backend/src/services/tests/agent-source-auto-inject-service.test.ts
index a79b18a5b..6d9a80016 100644
--- a/App/backend/src/services/tests/agent-source-auto-inject-service.test.ts
+++ b/App/backend/src/services/tests/agent-source-auto-inject-service.test.ts
@@ -53,6 +53,60 @@ describe("agent source auto inject service", () => {
     ]);
   });
 
+  it("does not reinstall manually uninstalled sources", async () => {
+    const calls: string[] = [];
+    const service = createAgentSourceAutoInjectService({
+      agentSources: {
+        ...createAgentSources(calls),
+        async list() {
+          return [source("cursor", "not_connected", true)];
+        }
+      },
+      permissionManager: { async canWriteAgentSkill() { return true; } },
+      getScanPreferences: () => enabledPreferences,
+      isAutoInjectSuppressed: (sourceId) => sourceId === "cursor"
+    });
+
+    await expect(service.runOnce()).resolves.toMatchObject({
+      ok: true,
+      skipped: false,
+      installed: [],
+      failed: []
+    });
+    expect(calls).toEqual([]);
+  });
+
+  it("removes an auto-injected hook when manual uninstallation races with installation", async () => {
+    const calls: string[] = [];
+    let suppressed = false;
+    const service = createAgentSourceAutoInjectService({
+      agentSources: {
+        ...createAgentSources(calls),
+        async list() {
+          return [source("cursor", "not_connected", true)];
+        },
+        async installPlugin(sourceId) {
+          calls.push(`plugin:${sourceId}:auto_inject`);
+          suppressed = true;
+        },
+        async uninstallPlugin(sourceId, action) {
+          calls.push(`uninstall:${sourceId}:${action?.installType ?? "manual"}`);
+        }
+      },
+      permissionManager: { async canWriteAgentSkill() { return true; } },
+      getScanPreferences: () => enabledPreferences,
+      isAutoInjectSuppressed: () => suppressed
+    });
+
+    await expect(service.runOnce()).resolves.toMatchObject({
+      ok: true,
+      skipped: false,
+      installed: [],
+      failed: []
+    });
+    expect(calls).toEqual(["plugin:cursor:auto_inject", "uninstall:cursor:auto_inject"]);
+  });
+
   it("skips unavailable builtin agents", async () => {
     const calls: string[] = [];
     const service = createAgentSourceAutoInjectService({
diff --git a/App/backend/src/services/tests/agent-source-service.test.ts b/App/backend/src/services/tests/agent-source-service.test.ts
index 42a22ed6c..b068771e4 100644
--- a/App/backend/src/services/tests/agent-source-service.test.ts
+++ b/App/backend/src/services/tests/agent-source-service.test.ts
@@ -1312,10 +1312,12 @@ describe("agent source service", () => {
     });
 
     await service.installSkill("cursor");
+    expect(repository.isAutoInjectSuppressed("cursor")).toBe(false);
     await service.uninstallSkill("cursor");
 
     expect(calls).toEqual(["install:cursor", "uninstall:cursor"]);
     expect(repository.listSources()[0]?.status).toBe("not_connected");
+    expect(repository.isAutoInjectSuppressed("cursor")).toBe(true);
   });
 
   it("delegates native plugin install then updates source status", async () => {
@@ -1347,10 +1349,12 @@ describe("agent source service", () => {
     });
 
     await service.installPlugin("openclaw");
+    expect(repository.isAutoInjectSuppressed("openclaw")).toBe(false);
     await service.uninstallPlugin("openclaw");
 
     expect(calls).toEqual(["plugin:openclaw", "unplugin:openclaw"]);
     expect(repository.listSources()[0]?.status).toBe("not_connected");
+    expect(repository.isAutoInjectSuppressed("openclaw")).toBe(true);
   });
 
   it("delegates memory plugin conflict detection to the skill distribution service", async () => {
@@ -1785,6 +1789,7 @@ function createRepository(): AgentSourceRepository {
       data_path       TEXT NOT NULL,
       builtin         INTEGER NOT NULL CHECK(builtin IN (0,1)),
       status          TEXT NOT NULL DEFAULT 'not_connected',
+      auto_inject_suppressed INTEGER NOT NULL DEFAULT 0 CHECK(auto_inject_suppressed IN (0,1)),
       last_scanned_at TEXT,
       sync_recipe_json TEXT,
       created_at      TEXT NOT NULL DEFAULT (datetime('now')),
diff --git a/Memory/src/agent-source/integration/codex/target.ts b/Memory/src/agent-source/integration/codex/target.ts
index 54e75627c..46501dec6 100644
--- a/Memory/src/agent-source/integration/codex/target.ts
+++ b/Memory/src/agent-source/integration/codex/target.ts
@@ -1,5 +1,5 @@
 /** Target module. */
-import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, readlink, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { resolveCodexHomeDirectory } from "../../agent-paths.js";
@@ -99,21 +99,27 @@ export function createCodexSkillTarget(deps: CreateCodexSkillTargetDeps = {}): S
 
       const hookDirectory = join(root, HOOK_DIRECTORY_NAME);
       const hookScriptPath = join(hookDirectory, HOOK_SCRIPT_FILE_NAME);
-      await mkdir(hookDirectory, { recursive: true });
-      await writeFileAtomically(
-        join(hookDirectory, HOOK_CONFIG_FILE_NAME),
-        `${JSON.stringify({ memmy_config_path: memmyConfigPath, ...(await readMemmyMemoryServiceConfig(memmyConfigPath)) }, null, 2)}\n`
-      );
-      await writeFileAtomically(hookScriptPath, renderMemmyResumeHookScript({ source: CODEX_TARGET_ID, mode: "codex" }));
-      await writeFileAtomically(
-        join(hookDirectory, WORKSPACE_BRIDGE_FILE_NAME),
-        await loadMemmyWorkspaceBridgeRuntimeAsset()
-      );
+      const hookConfigPath = join(hookDirectory, HOOK_CONFIG_FILE_NAME);
+      const bridgePath = join(hookDirectory, WORKSPACE_BRIDGE_FILE_NAME);
       const hooksFilePath = join(root, HOOKS_FILE_NAME);
       const hookCommand = createNodeHookCommand(hookScriptPath);
-      await upsertCodexHookConfig(hooksFilePath, hookCommand);
-      await rm(join(root, HOOK_DIRECTORY_NAME, LEGACY_HOOK_SCRIPT_FILE_NAME), { force: true });
+      const hookConfig = {
+        memmy_config_path: memmyConfigPath,
+        ...(await readMemmyMemoryServiceConfig(memmyConfigPath))
+      };
+      await withCodexHookFileRollback(
+        [hookConfigPath, hookScriptPath, bridgePath, hooksFilePath],
+        async () => {
+          await mkdir(hookDirectory, { recursive: true });
+          await writeFileAtomically(hookConfigPath, `${JSON.stringify(hookConfig, null, 2)}\n`);
+          await writeFileAtomically(hookScriptPath, renderMemmyResumeHookScript({ source: CODEX_TARGET_ID, mode: "codex" }));
+          await writeFileAtomically(bridgePath, await loadMemmyWorkspaceBridgeRuntimeAsset());
+          await upsertCodexHookConfig(hooksFilePath, hookCommand);
+          await trustHooks({ codexHomeDirectory: root, hooksFilePath, hookCommand });
+        }
+      );
 
+      await rm(join(hookDirectory, LEGACY_HOOK_SCRIPT_FILE_NAME), { force: true });
       const manifest = renderMemmyPluginSkillManifest(_targetId);
       const filePath = join(root, TARGET_FILE_NAME);
       await writeFileAtomically(
@@ -122,11 +128,6 @@ export function createCodexSkillTarget(deps: CreateCodexSkillTargetDeps = {}): S
       );
       await replaceMemmySkillDirectory(root, manifest);
       await replaceMemmyResumeSkillDirectory(root, CODEX_TARGET_ID);
-      await trustHooks({
-        codexHomeDirectory: root,
-        hooksFilePath,
-        hookCommand
-      });
     },
 
     async uninstallPlugin(_targetId) {
@@ -315,11 +316,73 @@ function createMarkerBlockPattern(startMarker: string, endMarker = END_MARKER):
   return new RegExp(`${escapeRegExp(startMarker)}\\n[\\s\\S]*?${escapeRegExp(endMarker)}\\n?`, "m");
 }
 
-async function writeFileAtomically(filePath: string, content: string): Promise<void> {
+async function writeFileAtomically(filePath: string, content: string | Buffer, mode?: number): Promise<void> {
   await mkdir(dirname(filePath), { recursive: true });
   const tempPath = join(dirname(filePath), `.${basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
-  await writeFile(tempPath, content, "utf8");
-  await rename(tempPath, filePath);
+  try {
+    await writeFile(tempPath, content, { encoding: "utf8", ...(mode === undefined ? {} : { mode }) });
+    await rename(tempPath, filePath);
+  } finally {
+    await rm(tempPath, { force: true });
+  }
+}
+
+type CodexHookFileSnapshot =
+  | { path: string; kind: "missing" }
+  | { path: string; kind: "file"; content: Buffer; mode: number }
+  | { path: string; kind: "symlink"; target: string };
+
+async function withCodexHookFileRollback<T>(paths: string[], operation: () => Promise<T>): Promise<T> {
+  const snapshots = await Promise.all(paths.map(snapshotCodexHookFile));
+  try {
+    return await operation();
+  } catch (error) {
+    const rollbackResults = await Promise.allSettled(snapshots.map(restoreCodexHookFile));
+    const rollbackErrors = rollbackResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [error, ...rollbackErrors],
+        "Codex hook installation failed and its files could not be fully rolled back"
+      );
+    }
+
+    throw error;
+  }
+}
+
+async function snapshotCodexHookFile(filePath: string): Promise<CodexHookFileSnapshot> {
+  try {
+    const metadata = await lstat(filePath);
+    if (metadata.isSymbolicLink()) {
+      return { path: filePath, kind: "symlink", target: await readlink(filePath) };
+    }
+    if (!metadata.isFile()) {
+      throw new Error(`Codex hook path is not a regular file: ${filePath}`);
+    }
+
+    return { path: filePath, kind: "file", content: await readFile(filePath), mode: metadata.mode & 0o777 };
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return { path: filePath, kind: "missing" };
+    }
+
+    throw error;
+  }
+}
+
+async function restoreCodexHookFile(snapshot: CodexHookFileSnapshot): Promise<void> {
+  if (snapshot.kind === "missing") {
+    await rm(snapshot.path, { force: true });
+    return;
+  }
+
+  if (snapshot.kind === "symlink") {
+    await rm(snapshot.path, { force: true });
+    await symlink(snapshot.target, snapshot.path);
+    return;
+  }
+
+  await writeFileAtomically(snapshot.path, snapshot.content, snapshot.mode);
 }
 
 function escapeRegExp(input: string): string {
diff --git a/Memory/src/agent-source/runtime.ts b/Memory/src/agent-source/runtime.ts
index 755f27014..863404f00 100644
--- a/Memory/src/agent-source/runtime.ts
+++ b/Memory/src/agent-source/runtime.ts
@@ -105,13 +105,19 @@ export interface AgentSourceExecutor {
   pauseScan(): Promise<{ ok: true }>;
   cancelScan(): Promise<{ ok: true }>;
   scanResults?(jobId: string, cursor?: string, limit?: number): Promise<{ items: Array<{ sourceId: string; conversationId: string; memoryId?: string; error?: string }>; nextCursor: string | null }>;
-  mutateConnection(sourceId: string, kind: "plugin" | "skill", method: "POST" | "DELETE"): Promise<unknown>;
+  mutateConnection(
+    sourceId: string,
+    kind: "plugin" | "skill",
+    method: "POST" | "DELETE",
+    installType?: "manual" | "auto_inject"
+  ): Promise<unknown>;
   startAutomation(): void;
   dispose(): void | Promise<void>;
 }
 
 interface PersistedSourceState {
   status: AgentConnectionStatus;
+  autoInjectSuppressed?: boolean;
   messageCount: number;
   lastScannedAt: string | null;
   latestSeenAt: string | null;
@@ -489,7 +495,8 @@ export function createAgentSourceExecutor(options: CreateAgentSourceExecutorOpti
   async function mutateConnection(
     sourceId: string,
     kind: "plugin" | "skill",
-    method: "POST" | "DELETE"
+    method: "POST" | "DELETE",
+    installType: "manual" | "auto_inject" = "manual"
   ): Promise<unknown> {
     const adapter = registry.require(sourceId);
     if (!(await adapter.detect())) {
@@ -515,10 +522,16 @@ export function createAgentSourceExecutor(options: CreateAgentSourceExecutorOpti
     }
     const state = await readState();
     const stored = state.sources[sourceId] ?? emptySourceState();
-    state.sources[sourceId] = {
+    const nextState: PersistedSourceState = {
       ...stored,
       status: method === "POST" ? connectionStatus(sourceId) : "not_connected"
     };
+    if (method === "DELETE") {
+      nextState.autoInjectSuppressed = true;
+    } else if (installType === "manual") {
+      delete nextState.autoInjectSuppressed;
+    }
+    state.sources[sourceId] = nextState;
     await persist(state);
     logger.info(method === "POST" ? "connection.installed" : "connection.removed", { sourceId, kind });
     return { ok: true, sourceId, status: state.sources[sourceId].status };
@@ -542,12 +555,18 @@ export function createAgentSourceExecutor(options: CreateAgentSourceExecutorOpti
     if (disposed || scan.running) return;
     const config = loadMemmyConfig(configPath).config.agentAccess;
     if (config.autoInjectSkill) {
+      const state = await readState();
       const discovered = await list();
       for (const source of discovered.sources) {
         if (disposed) return;
-        if (!source.available || source.status !== "not_connected") continue;
+        if (!source.available || source.status !== "not_connected" || state.sources[source.sourceId]?.autoInjectSuppressed === true) continue;
         try {
-          await mutateConnection(source.sourceId, agentConnectionKind(source.sourceId), "POST");
+          const kind = agentConnectionKind(source.sourceId);
+          await mutateConnection(source.sourceId, kind, "POST", "auto_inject");
+          const currentState = await readState();
+          if (currentState.sources[source.sourceId]?.autoInjectSuppressed === true) {
+            await mutateConnection(source.sourceId, kind, "DELETE", "auto_inject");
+          }
         } catch (error) {
           logger.warn("connection.auto_install_failed", { sourceId: source.sourceId, ...memoryErrorFields(error) });
         }
@@ -1286,6 +1305,7 @@ async function loadState(path: string): Promise<PersistedState> {
       const status = source.status === "skill_installed" || source.status === "plugin_installed" ? source.status : "not_connected";
       return [sourceId, {
         status,
+        ...(source.autoInjectSuppressed === true ? { autoInjectSuppressed: true } : {}),
         messageCount: typeof source.messageCount === "number" && Number.isFinite(source.messageCount) ? Math.max(0, Math.floor(source.messageCount)) : 0,
         lastScannedAt: typeof source.lastScannedAt === "string" ? source.lastScannedAt : null,
         latestSeenAt: typeof source.latestSeenAt === "string" ? source.latestSeenAt : null,
diff --git a/Memory/tests/agent-source-runtime.test.ts b/Memory/tests/agent-source-runtime.test.ts
index 4474711f7..1c87afb6d 100644
--- a/Memory/tests/agent-source-runtime.test.ts
+++ b/Memory/tests/agent-source-runtime.test.ts
@@ -10,6 +10,7 @@ import type { SourceAdapter } from "../src/agent-source/adapters/types.js";
 import { createSourceRegistry } from "../src/agent-source/adapters/source-registry.js";
 import { createCursorSkillTarget } from "../src/agent-source/integration/cursor/index.js";
 import { createSkillTargetRegistry } from "../src/agent-source/integration/target-registry.js";
+import type { SkillTarget } from "../src/agent-source/integration/types.js";
 import type { MemoryService } from "../src/service/memory-service.js";
 
 const roots: string[] = [];
@@ -671,6 +672,7 @@ describe("standalone Agent source executor", () => {
     const cursorRoot = join(root, ".cursor");
     mkdirSync(cursorRoot, { recursive: true });
     const configPath = join(root, "config.yaml");
+    const statePath = join(root, "agent-sources.json");
     writeFileSync(configPath, "memmyMemory:\n  storage:\n    endpoint: http://127.0.0.1:18960\n");
     const adapter: SourceAdapter = {
       descriptor: { sourceId: "cursor", displayName: "Cursor", builtin: true, dataPath: cursorRoot },
@@ -684,7 +686,7 @@ describe("standalone Agent source executor", () => {
     const executor = createAgentSourceExecutor({
       service,
       configPath,
-      statePath: join(root, "agent-sources.json"),
+      statePath,
       sourceRegistry: createSourceRegistry([adapter]),
       integrationRegistry: createSkillTargetRegistry([
         createCursorSkillTarget({ rootDirectory: cursorRoot, memmyConfigPath: configPath })
@@ -699,6 +701,64 @@ describe("standalone Agent source executor", () => {
     await executor.mutateConnection("cursor", "plugin", "DELETE");
     expect(readFileSync(join(cursorRoot, "hooks.json"), "utf8")).not.toContain("memmy-resume-hook.mjs");
     expect((await executor.list()).sources[0]?.status).toBe("not_connected");
+    expect(JSON.parse(readFileSync(statePath, "utf8")).sources.cursor.autoInjectSuppressed).toBe(true);
+
+    await executor.mutateConnection("cursor", "plugin", "POST", "auto_inject");
+    expect(JSON.parse(readFileSync(statePath, "utf8")).sources.cursor.autoInjectSuppressed).toBe(true);
+    await executor.mutateConnection("cursor", "plugin", "DELETE");
+    await executor.mutateConnection("cursor", "plugin", "POST", "manual");
+    expect(JSON.parse(readFileSync(statePath, "utf8")).sources.cursor.autoInjectSuppressed).toBeUndefined();
+  });
+
+  it("removes a hook when manual uninstall races with standalone auto injection", async () => {
+    const root = tempRoot();
+    const codexRoot = join(root, ".codex");
+    mkdirSync(codexRoot, { recursive: true });
+    const configPath = join(root, "config.yaml");
+    const statePath = join(root, "agent-sources.json");
+    writeFileSync(configPath, JSON.stringify({ memmyMemory: {
+      agentAccess: { autoScanKnownAgents: true, watchFileChanges: false, autoInjectSkill: true },
+    } }));
+    let executor!: ReturnType<typeof createAgentSourceExecutor>;
+    let autoInstallFinished = false;
+    let hookPresent = false;
+    const target: SkillTarget = {
+      targetId: "codex",
+      displayName: "Codex",
+      async resolveRootDirectory() { return codexRoot; },
+      async install() {},
+      async uninstall() {},
+      async isInstalled() { return hookPresent; },
+      async installPlugin() {
+        await executor.mutateConnection("codex", "plugin", "DELETE");
+        hookPresent = true;
+        autoInstallFinished = true;
+      },
+      async uninstallPlugin() { hookPresent = false; },
+    };
+    const adapter: SourceAdapter = {
+      descriptor: { sourceId: "codex", displayName: "Codex", builtin: true, dataPath: codexRoot },
+      detect: async () => true,
+      async *scan() {},
+    };
+    executor = createAgentSourceExecutor({
+      service: {} as MemoryService,
+      configPath,
+      statePath,
+      initialScanDelayMs: 0,
+      sourceRegistry: createSourceRegistry([adapter]),
+      integrationRegistry: createSkillTargetRegistry([target]),
+    });
+
+    try {
+      executor.startAutomation();
+      await vi.waitFor(() => expect(autoInstallFinished).toBe(true));
+      await vi.waitFor(() => expect(hookPresent).toBe(false));
+      expect((await executor.list()).sources[0]?.status).toBe("not_connected");
+      expect(JSON.parse(readFileSync(statePath, "utf8")).sources.codex.autoInjectSuppressed).toBe(true);
+    } finally {
+      await executor.dispose();
+    }
   });
 });
 

From 516ba152d91bcfb6e3d8d4cc219b54680a99620b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Mon, 12 Oct 2026 13:57:58 +0800
Subject: [PATCH 26/85] fix: allow models to share identical endpoints

---
 .../memmy-config/model-config-catalog.ts      | 25 ++++--
 .../tests/model-config-catalog.test.ts        | 83 +++++++++++++++++--
 App/frontend/desktop/src/api/config-client.ts | 65 +++++++++++++--
 .../src/api/tests/config-client.test.ts       | 59 +++++++++++++
 4 files changed, 211 insertions(+), 21 deletions(-)

diff --git a/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts b/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
index c1d25dc37..e7e360e77 100644
--- a/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
+++ b/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
@@ -134,10 +134,10 @@ function mergeModelConfig(config: ConfigRecord, input: ModelConfigInput): Config
     if (providerInput.provider === ACCOUNT_PROVIDER) continue;
     const previousProvider = record(existingProviders[providerInput.provider]);
     const provider = mergeProvider(previousProvider, providerInput);
+    const modelInputs = canonicalizeEndpointDefinitions(providerInput, provider);
     nextProviders[providerInput.provider] = provider;
-    validateEndpointDefinitions(providerInput, provider);
 
-    for (const modelInput of providerInput.models) {
+    for (const modelInput of modelInputs) {
       if (modelInput.source !== "byok" || modelInput.ownerAccountId) {
         throw new InvalidModelConfigError("Desktop model settings may only create ownerless BYOK presets");
       }
@@ -446,10 +446,12 @@ function mergeEndpoint(previous: ConfigRecord, input: CatalogEndpointInput): Con
   return next;
 }
 
-function validateEndpointDefinitions(input: TextModelProviderInput, provider: ConfigRecord): void {
-  const signatures = new Set<string>();
+function canonicalizeEndpointDefinitions(input: TextModelProviderInput, provider: ConfigRecord): TextModelItemInput[] {
+  const canonicalIds = new Map<string, string>();
+  const redirects = new Map<string, string>();
+  const endpoints = record(provider.endpoints);
   for (const endpoint of input.endpoints) {
-    const merged = record(record(provider.endpoints)[endpoint.endpointId]);
+    const merged = record(endpoints[endpoint.endpointId]);
     const signature = stableJson({
       provider: input.provider,
       protocol: merged.protocol,
@@ -458,11 +460,18 @@ function validateEndpointDefinitions(input: TextModelProviderInput, provider: Co
       extraHeaders: merged.extraHeaders ?? provider.extraHeaders ?? null,
       extraBody: merged.extraBody ?? provider.extraBody ?? null
     });
-    if (signatures.has(signature)) {
-      throw new InvalidModelConfigError(`Duplicate endpoint definition for Provider ${input.provider}`);
+    const canonicalId = canonicalIds.get(signature);
+    if (canonicalId) {
+      redirects.set(endpoint.endpointId, canonicalId);
+      delete endpoints[endpoint.endpointId];
+    } else {
+      canonicalIds.set(signature, endpoint.endpointId);
     }
-    signatures.add(signature);
   }
+  return input.models.map((model) => {
+    const endpointId = redirects.get(model.endpointId);
+    return endpointId ? { ...model, endpointId } : model;
+  });
 }
 
 function validatePresetEndpoint(providerId: CatalogProviderId, model: TextModelItemInput, endpoint: ConfigRecord): void {
diff --git a/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts b/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
index 4515c5ab6..a52b1d8d6 100644
--- a/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
+++ b/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
@@ -501,17 +501,90 @@ describe("model config catalog", () => {
     expect((YAML.parse(readFileSync(file, "utf8")) as any).memmyMemory.roleRouting.summary).toBe("follow");
   });
 
-  it("rejects duplicate endpoint definitions, invalid protocol capabilities, and duplicate models", async () => {
+  it("coalesces identical endpoint definitions and redirects their model references", async () => {
     const file = fixture();
-    const revision = (await readModelConfigCatalog(file)).configRevision;
-    const duplicateEndpoint = openAiInput(revision);
-    duplicateEndpoint.providers[0]!.endpoints.push({
+    const input = openAiInput((await readModelConfigCatalog(file)).configRevision);
+    input.providers[0]!.endpoints.push({
       endpointId: "chat-copy",
       apiBase: "https://api.example.test/v1",
       protocol: "openai-chat-completions"
     });
-    await expect(writeModelConfigCatalog(file, duplicateEndpoint)).rejects.toThrow(/Duplicate endpoint definition/);
+    input.providers[0]!.models.push({
+      endpointId: "chat-copy",
+      model: "gpt-5-alias",
+      source: "byok",
+      capabilities: ["agent"]
+    });
+
+    const saved = await writeModelConfigCatalog(file, input);
+    const raw = YAML.parse(readFileSync(file, "utf8")) as any;
+    expect(Object.keys(raw.providers.openai.endpoints)).toEqual(["chat"]);
+    expect(Object.values(raw.modelPresets).map((preset: any) => preset.endpoint)).toEqual(["chat", "chat"]);
+    expect(saved.providers[0]?.endpoints).toHaveLength(1);
+  });
+
+  it("coalesces duplicate embedding endpoints created while adding models", async () => {
+    const file = fixture();
+    const input = openAiInput((await readModelConfigCatalog(file)).configRevision);
+    input.providers[0]!.endpoints = [
+      {
+        endpointId: "embedding",
+        apiBase: "https://api.example.test/v1/",
+        protocol: "openai-embeddings"
+      },
+      {
+        endpointId: "embedding-copy",
+        apiBase: "https://api.example.test/v1",
+        protocol: "openai-embeddings"
+      }
+    ];
+    input.providers[0]!.models = [
+      {
+        endpointId: "embedding",
+        model: "embedding-a",
+        source: "byok",
+        capabilities: ["embedding"]
+      },
+      {
+        endpointId: "embedding-copy",
+        model: "embedding-b",
+        source: "byok",
+        capabilities: ["embedding"]
+      }
+    ];
+
+    const saved = await writeModelConfigCatalog(file, input);
+    const raw = YAML.parse(readFileSync(file, "utf8")) as any;
+    expect(Object.keys(raw.providers.openai.endpoints)).toEqual(["embedding"]);
+    expect(Object.values(raw.modelPresets).map((preset: any) => preset.endpoint)).toEqual(["embedding", "embedding"]);
+    expect(saved.providers[0]?.models.map((model) => model.model)).toEqual(["embedding-a", "embedding-b"]);
+  });
+
+  it("keeps endpoints with different credentials even when their route is the same", async () => {
+    const file = fixture();
+    const input = openAiInput((await readModelConfigCatalog(file)).configRevision);
+    input.providers[0]!.endpoints.push({
+      endpointId: "chat-other-key",
+      apiBase: "https://api.example.test/v1",
+      protocol: "openai-chat-completions",
+      apiKey: "sk-another-secret"
+    });
+    input.providers[0]!.models.push({
+      endpointId: "chat-other-key",
+      model: "gpt-5-alias",
+      source: "byok",
+      capabilities: ["agent"]
+    });
 
+    await writeModelConfigCatalog(file, input);
+    const raw = YAML.parse(readFileSync(file, "utf8")) as any;
+    expect(Object.keys(raw.providers.openai.endpoints)).toEqual(["chat", "chat-other-key"]);
+    expect(raw.providers.openai.endpoints["chat-other-key"].apiKey).toBe("sk-another-secret");
+  });
+
+  it("rejects invalid protocol capabilities and duplicate models", async () => {
+    const file = fixture();
+    const revision = (await readModelConfigCatalog(file)).configRevision;
     const wrongProtocol = openAiInput(revision);
     wrongProtocol.providers[0]!.models[0]!.capabilities = ["embedding"];
     await expect(writeModelConfigCatalog(file, wrongProtocol)).rejects.toThrow(/does not support capability embedding/);
diff --git a/App/frontend/desktop/src/api/config-client.ts b/App/frontend/desktop/src/api/config-client.ts
index 00c147c71..2446bf2aa 100644
--- a/App/frontend/desktop/src/api/config-client.ts
+++ b/App/frontend/desktop/src/api/config-client.ts
@@ -604,24 +604,33 @@ interface PendingPreset {
   clientId: string;
   provider: string;
   endpointId: string;
+  endpointApiBase: string | null;
+  endpointProtocol: ModelEndpointProtocol | null;
+  endpointApiKey: string;
+  providerApiKey: string;
   model: string;
   source: "account" | "byok";
   capabilities: ModelCapability[];
 }
 
 function pendingPresets(input: ModelConfigInput): PendingPreset[] {
-  return input.providers.flatMap((provider) => provider.models.flatMap((model) => (
-    model.presetId?.startsWith(CLIENT_PRESET_ID_PREFIX)
+  return input.providers.flatMap((provider) => provider.models.flatMap((model) => {
+    const endpoint = provider.endpoints.find((item) => item.endpointId === model.endpointId);
+    return model.presetId?.startsWith(CLIENT_PRESET_ID_PREFIX)
       ? [{
           clientId: model.presetId,
           provider: provider.provider,
           endpointId: model.endpointId,
+          endpointApiBase: endpoint?.apiBase ?? null,
+          endpointProtocol: endpoint?.protocol ?? null,
+          endpointApiKey: endpoint?.apiKey ?? "",
+          providerApiKey: provider.apiKey ?? "",
           model: model.model,
           source: model.source,
           capabilities: [...model.capabilities]
         }]
-      : []
-  )));
+      : [];
+  }));
 }
 
 function withoutPendingPresetAssignments(input: ModelConfigInput, pendingIds: ReadonlySet<string>): ModelConfigInput {
@@ -646,13 +655,22 @@ function withoutPendingPresetAssignments(input: ModelConfigInput, pendingIds: Re
 function resolvePendingPresetIds(pending: PendingPreset[], view: ModelConfigView): Map<string, string> {
   const mapping = new Map<string, string>();
   for (const item of pending) {
-    const matches = view.providers.flatMap((provider) => provider.models).filter((model) => (
+    const provider = view.providers.find((candidate) => candidate.provider === item.provider);
+    const matchesModel = (model: ModelConfigView["providers"][number]["models"][number]) => (
       model.provider === item.provider
-      && model.endpointId === item.endpointId
       && model.model === item.model
       && model.source === item.source
       && sameStringSet(model.capabilities, item.capabilities)
-    ));
+    );
+    const exactMatches = provider?.models.filter((model) => (
+      matchesModel(model) && model.endpointId === item.endpointId
+    )) ?? [];
+    const canonicalizedMatches = exactMatches.length === 0 && provider
+      ? provider.models.filter((model) => (
+        matchesModel(model) && pendingEndpointMatches(item, provider, model.endpointId)
+      ))
+      : [];
+    const matches = exactMatches.length > 0 ? exactMatches : canonicalizedMatches;
     if (matches.length !== 1) {
       throw new Error(`Unable to resolve server preset for ${item.provider}/${item.endpointId}/${item.model}`);
     }
@@ -661,6 +679,35 @@ function resolvePendingPresetIds(pending: PendingPreset[], view: ModelConfigView
   return mapping;
 }
 
+function pendingEndpointMatches(
+  item: PendingPreset,
+  provider: ModelConfigView["providers"][number],
+  endpointId: string
+): boolean {
+  if (!item.endpointApiBase || !item.endpointProtocol) return false;
+  const endpoint = provider.endpoints.find((candidate) => candidate.endpointId === endpointId);
+  if (
+    !endpoint
+    || normalizeApiBase(endpoint.apiBase) !== normalizeApiBase(item.endpointApiBase)
+    || endpoint.protocol !== item.endpointProtocol
+  ) {
+    return false;
+  }
+  const expectedApiKey = maskSecret(item.endpointApiKey || item.providerApiKey);
+  const actualApiKey = endpoint.hasApiKey ? endpoint.apiKeyMasked : provider.apiKeyMasked;
+  return !expectedApiKey || expectedApiKey === actualApiKey;
+}
+
+function normalizeApiBase(value: string): string {
+  return value.trim().replace(/\/+$/u, "");
+}
+
+function maskSecret(value: string): string {
+  if (!value) return "";
+  if (value.length <= 8) return "••••••••";
+  return `${value.slice(0, 3)}••••${value.slice(-4)}`;
+}
+
 function assignmentPhaseInput(
   base: ModelConfigView,
   requested: ModelConfigInput,
@@ -704,10 +751,12 @@ function assertResolvedPresetsStillExist(
   const byId = new Map(view.providers.flatMap((provider) => provider.models).map((model) => [model.presetId, model]));
   for (const item of pending) {
     const preset = byId.get(mapping.get(item.clientId) ?? "");
+    const provider = view.providers.find((candidate) => candidate.provider === item.provider);
     if (
       !preset
       || preset.provider !== item.provider
-      || preset.endpointId !== item.endpointId
+      || !provider
+      || (preset.endpointId !== item.endpointId && !pendingEndpointMatches(item, provider, preset.endpointId))
       || preset.model !== item.model
       || preset.source !== item.source
       || !sameStringSet(preset.capabilities, item.capabilities)
diff --git a/App/frontend/desktop/src/api/tests/config-client.test.ts b/App/frontend/desktop/src/api/tests/config-client.test.ts
index eae3aa81a..4940a39ba 100644
--- a/App/frontend/desktop/src/api/tests/config-client.test.ts
+++ b/App/frontend/desktop/src/api/tests/config-client.test.ts
@@ -209,6 +209,65 @@ describe("config-client canonical model catalog", () => {
     expect(saved.catalog?.modelAssignments.byok.agent.default).toBe(serverPresetId);
   });
 
+  it("后端合并相同 endpoint 定义后仍能解析新模型并完成 assignment", async () => {
+    const bodies: any[] = [];
+    const serverPresetId = "5c8872cf-28c8-4cf3-bf51-9a3a2a0fb42a";
+    vi.stubGlobal("fetch", vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
+      const body = JSON.parse(String(init?.body));
+      bodies.push(body);
+      const response = catalog(bodies.length === 1 ? "revision-2" : "revision-3");
+      response.providers[0]!.models.push({
+        presetId: serverPresetId,
+        provider: "openai",
+        endpointId: "chat",
+        protocol: "openai-chat-completions",
+        model: "gpt-new",
+        source: "byok",
+        capabilities: ["agent"],
+        available: true
+      });
+      if (bodies.length > 1) {
+        response.modelAssignments.byok.agent = {
+          candidates: ["byok-agent", serverPresetId],
+          default: serverPresetId
+        };
+      }
+      return jsonResponse(response);
+    }));
+    const input = inputFromCatalog(catalog("revision-1"));
+    const clientPresetId = `${CLIENT_PRESET_ID_PREFIX}canonicalized-endpoint`;
+    input.providers[0]!.endpoints.push({
+      endpointId: "chat-duplicate",
+      apiBase: "https://api.openai.com/v1/",
+      protocol: "openai-chat-completions"
+    });
+    input.providers[0]!.models.push({
+      presetId: clientPresetId,
+      endpointId: "chat-duplicate",
+      model: "gpt-new",
+      source: "byok",
+      capabilities: ["agent"]
+    });
+    input.modelAssignments.byok.agent = {
+      candidates: ["byok-agent", clientPresetId],
+      default: clientPresetId
+    };
+
+    const saved = await createHttpConfigClient(config).saveModelCatalog(input);
+
+    expect(bodies).toHaveLength(2);
+    expect(bodies[0].providers[0].endpoints.some((endpoint: any) => endpoint.endpointId === "chat-duplicate")).toBe(true);
+    expect(bodies[1].providers[0].models.find((model: any) => model.model === "gpt-new")).toMatchObject({
+      presetId: serverPresetId,
+      endpointId: "chat"
+    });
+    expect(bodies[1].modelAssignments.byok.agent).toEqual({
+      candidates: ["byok-agent", serverPresetId],
+      default: serverPresetId
+    });
+    expect(saved.catalog?.modelAssignments.byok.agent.default).toBe(serverPresetId);
+  });
+
   it("首次成功 GET 后只清理旧 workspace cache", async () => {
     const removeItem = vi.fn();
     vi.stubGlobal("window", { localStorage: { removeItem } });

From b5ac0666e1153f01d5827107be91287be8246023 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Tue, 13 Oct 2026 12:12:28 +0800
Subject: [PATCH 27/85] fix: reuse saved BYOK endpoint in setup connection
 tests

---
 .../src/pages/api-key-optional-page.tsx       | 20 +++-
 .../desktop/src/pages/api-key-page.tsx        |  8 +-
 App/frontend/desktop/src/pages/model-page.tsx | 17 +++-
 ...k-setup-save-feedback.interaction.test.tsx | 99 +++++++++++++++++++
 4 files changed, 135 insertions(+), 9 deletions(-)

diff --git a/App/frontend/desktop/src/pages/api-key-optional-page.tsx b/App/frontend/desktop/src/pages/api-key-optional-page.tsx
index c8dda7386..c0c56cb01 100644
--- a/App/frontend/desktop/src/pages/api-key-optional-page.tsx
+++ b/App/frontend/desktop/src/pages/api-key-optional-page.tsx
@@ -61,6 +61,9 @@ export function ApiKeyOptionalPage() {
   const { t } = useTranslation();
   const { track } = useAnalytics();
   const initialModelForm = hydrateModelConfigForm(state.modelConfig, "local");
+  const initialWorkspace = createModelWorkspace(state.modelConfig);
+  const initialAsrEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "asr");
+  const initialImageEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "image_generation");
   const initialAsrModel = initialModelForm.asrModelId;
   const initialAsrEndpoint = initialModelForm.asrEndpoint || ASR_DEFAULT_ENDPOINT;
   const [asrModel, setAsrModel] = useState(initialAsrModel);
@@ -70,7 +73,10 @@ export function ApiKeyOptionalPage() {
   const [asrValidation, setAsrValidation] = useState<ModelConfigValidationState>(initialModelForm.asrValidation);
   const [asrWarningAcknowledged, setAsrWarningAcknowledged] = useState(false);
   const [asrApiKeyMasked] = useState(initialModelForm.asrApiKeyMasked);
-  const asrFormValues = createAsrModelFormValues(asrModel, asrEndpoint, asrApiKey, asrApiKeyMasked);
+  const asrFormValues = {
+    ...createAsrModelFormValues(asrModel, asrEndpoint, asrApiKey, asrApiKeyMasked),
+    endpointId: !asrApiKey.trim() && asrApiKeyMasked ? initialAsrEndpointId : undefined
+  };
   const isAsrUsable = canSaveModelConfig(asrFormValues, asrValidation);
   const asrTestKey = createModelConfigValidationKey(asrFormValues);
   const isAsrTestStale = Boolean(asrValidation.testedKey && asrValidation.testedKey !== asrTestKey);
@@ -82,7 +88,14 @@ export function ApiKeyOptionalPage() {
   const [imageGenValidation, setImageGenValidation] = useState<ModelConfigValidationState>(initialModelForm.imageGenValidation);
   const [imageGenWarningAcknowledged, setImageGenWarningAcknowledged] = useState(false);
   const [imageGenApiKeyMasked] = useState(initialModelForm.imageGenApiKeyMasked);
-  const imageGenFormValues = createImageGenModelFormValues(imageGenProtocol, imageGenModel, imageGenEndpoint, imageGenApiKey, imageGenApiKeyMasked);
+  const imageGenFormValues = {
+    ...createImageGenModelFormValues(imageGenProtocol, imageGenModel, imageGenEndpoint, imageGenApiKey, imageGenApiKeyMasked),
+    endpointId: !imageGenApiKey.trim()
+      && imageGenApiKeyMasked
+      && imageGenProtocol === initialModelForm.imageGenProtocol
+      ? initialImageEndpointId
+      : undefined
+  };
   const isImageGenUsable = canSaveModelConfig(imageGenFormValues, imageGenValidation);
   const imageGenTestKey = createModelConfigValidationKey(imageGenFormValues);
   const isImageGenTestStale = Boolean(imageGenValidation.testedKey && imageGenValidation.testedKey !== imageGenTestKey);
@@ -108,9 +121,6 @@ export function ApiKeyOptionalPage() {
     imageGeneration: isImageGenUsable ? imageGenTestKey : null
   });
   const savedCatalogSignatureRef = useRef<string | null>(null);
-  const initialWorkspace = createModelWorkspace(state.modelConfig);
-  const initialAsrEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "asr");
-  const initialImageEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "image_generation");
   const savedEndpointIdentitiesRef = useRef<Partial<Record<"asr" | "imageGeneration", SavedEndpointIdentity>>>({
     ...(initialAsrEndpointId
       ? { asr: { endpointId: initialAsrEndpointId, credentialSignature: asrCredentialSignature } }
diff --git a/App/frontend/desktop/src/pages/api-key-page.tsx b/App/frontend/desktop/src/pages/api-key-page.tsx
index 40f6fb6ed..6e917ad2d 100644
--- a/App/frontend/desktop/src/pages/api-key-page.tsx
+++ b/App/frontend/desktop/src/pages/api-key-page.tsx
@@ -83,6 +83,9 @@ export function ApiKeyPage() {
   const { t } = useTranslation();
   const { track } = useAnalytics();
   const initialModelForm = hydrateModelConfigForm(state.modelConfig, "local");
+  const initialWorkspace = createModelWorkspace(state.modelConfig);
+  const initialAgentEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "agent");
+  const initialEmbeddingEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "embedding");
   const initialProvider = fromProtocol(initialModelForm.protocol);
   const [provider, setProvider] = useState(initialProvider);
   const selectedProvider = providerOptions.find((option) => option.value === provider) ?? defaultProvider;
@@ -93,6 +96,7 @@ export function ApiKeyPage() {
   const [showApiKey, setShowApiKey] = useState(false);
   const modelFormValues = {
     provider,
+    endpointId: !apiKey.trim() && apiKeyMasked ? initialAgentEndpointId : undefined,
     endpoint,
     model,
     apiKey,
@@ -100,7 +104,6 @@ export function ApiKeyPage() {
     hasExistingApiKey: Boolean(apiKeyMasked)
   };
   const [llmValidation, setLlmValidation] = useState<ModelConfigValidationState>(initialModelForm.llmValidation);
-  const initialWorkspace = createModelWorkspace(state.modelConfig);
   const initialEmbeddingMode: EmbeddingMode = initialWorkspace.catalog.modelAssignments.byok.embedding
     ? "custom"
     : "local";
@@ -114,6 +117,7 @@ export function ApiKeyPage() {
   const [showEmbeddingApiKey, setShowEmbeddingApiKey] = useState(false);
   const embeddingFormValues = {
     provider: "openai",
+    endpointId: !embeddingConfig.apiKey.trim() && embeddingConfig.apiKeyMasked ? initialEmbeddingEndpointId : undefined,
     endpoint: embeddingConfig.endpoint,
     model: embeddingConfig.model,
     apiKey: embeddingConfig.apiKey,
@@ -145,8 +149,6 @@ export function ApiKeyPage() {
   );
   const saveSignature = `${embeddingMode}\n${testedKey}\n${embeddingTestKey}`;
   const savedCatalogSignatureRef = useRef<string | null>(null);
-  const initialAgentEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "agent");
-  const initialEmbeddingEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "embedding");
   const savedEndpointIdentitiesRef = useRef<Partial<Record<"agent" | "embedding", SavedEndpointIdentity>>>({
     ...(initialAgentEndpointId
       ? { agent: { endpointId: initialAgentEndpointId, credentialSignature: agentCredentialSignature } }
diff --git a/App/frontend/desktop/src/pages/model-page.tsx b/App/frontend/desktop/src/pages/model-page.tsx
index aef50d6a9..b541878d7 100644
--- a/App/frontend/desktop/src/pages/model-page.tsx
+++ b/App/frontend/desktop/src/pages/model-page.tsx
@@ -84,6 +84,8 @@ export function ModelPage() {
   const { t } = useTranslation();
   const { track } = useAnalytics();
   const initialModelForm = hydrateModelConfigForm(state.modelConfig, "local");
+  const initialWorkspace = createModelWorkspace(state.modelConfig);
+  const primaryEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "agent");
   const [primaryModel] = useState<PrimaryModelValues>(() => ({
     protocol: initialModelForm.protocol,
     modelId: initialModelForm.modelId,
@@ -99,6 +101,14 @@ export function ModelPage() {
   const skillValues = createModelFormValues(skill, primaryModel);
   const evolutionModel = modelFormValuesAsPrimary(skillValues);
   const memoryValues = createModelFormValues(mem, evolutionModel);
+  const skillEndpointId = skill.reuse
+    ? primaryEndpointId
+    : assignedCatalogEndpointId(initialWorkspace, "byok", "memory_evolution")
+      ?? (skillValues.apiKeyMasked ? primaryEndpointId : undefined);
+  const memoryEndpointId = mem.reuse
+    ? skillEndpointId
+    : assignedCatalogEndpointId(initialWorkspace, "byok", "memory_summary")
+      ?? (memoryValues.apiKeyMasked ? skillEndpointId : undefined);
   const canContinue = canUseModelConfig(mem, memoryValues) && canUseModelConfig(skill, skillValues);
 
   /** Handles patch mem. */
@@ -121,7 +131,12 @@ export function ModelPage() {
     const values = createModelFormValues(config, inheritedModel);
     testModelConnection({
       configClient: clients?.config,
-      values,
+      values: {
+        ...values,
+        endpointId: values.apiKeyMasked
+          ? secretTarget === "skill" ? skillEndpointId : memoryEndpointId
+          : undefined
+      },
       setValidation: (validation) => patch({ validation }),
       secretTarget,
       messages: createTestModelConnectionMessages(t)
diff --git a/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx
index f6cd72a99..2011fb782 100644
--- a/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx
@@ -77,6 +77,42 @@ describe("BYOK setup save feedback", () => {
     expect(container.querySelector('[role="alert"]')).toBeNull();
   });
 
+  it("retests masked first-step keys through their saved endpoints", async () => {
+    const catalog = configuredCatalog();
+    const workspace = createModelWorkspace(catalog);
+    const agentEndpointId = assignedCatalogEndpointId(workspace, "byok", "agent");
+    const embeddingEndpointId = assignedCatalogEndpointId(workspace, "byok", "embedding");
+    const testModelConfig = vi.fn(async () => ({
+      ok: true,
+      message: "ok",
+      checkedAt: "2026-10-13T00:00:00.000Z"
+    }));
+    mocks.state = { ...createInitialAppState(), modelConfig: maskedSavedModelConfig(catalog) };
+    mocks.clients = createClients(vi.fn(async () => maskedSavedModelConfig(catalog)), { testModelConfig });
+    await render(<ApiKeyPage />);
+
+    const primaryInput = [...container.querySelectorAll("label")]
+      .find((candidate) => candidate.textContent === "apiKey.key")
+      ?.parentElement?.querySelector("input");
+    expect(primaryInput?.placeholder).toBe(maskApiKey("sk-primary"));
+
+    await click(testButton());
+    await vi.waitFor(() => expect(testModelConfig).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ endpointId: agentEndpointId, apiKey: "" }),
+      "chat",
+      "primary"
+    ));
+
+    await click(testButton(1));
+    await vi.waitFor(() => expect(testModelConfig).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ endpointId: embeddingEndpointId, apiKey: "" }),
+      "embedding",
+      "embedding"
+    ));
+  });
+
   it("defaults a genuinely absent BYOK embedding assignment to the local model", async () => {
     const catalog = configuredCatalog(false);
     catalog.modelAssignments.byok.embedding = null;
@@ -438,6 +474,69 @@ describe("BYOK setup save feedback", () => {
       .toBe(initialImageEndpointId);
   });
 
+  it("retests masked optional keys through their saved endpoints", async () => {
+    const catalog = configuredCatalog();
+    const workspace = createModelWorkspace(catalog);
+    const asrEndpointId = assignedCatalogEndpointId(workspace, "byok", "asr");
+    const imageEndpointId = assignedCatalogEndpointId(workspace, "byok", "image_generation");
+    const testModelConfig = vi.fn(async () => ({
+      ok: true,
+      message: "ok",
+      checkedAt: "2026-10-13T00:00:00.000Z"
+    }));
+    mocks.state = { ...createInitialAppState(), modelConfig: maskedSavedModelConfig(catalog) };
+    mocks.clients = createClients(vi.fn(async () => maskedSavedModelConfig(catalog)), { testModelConfig });
+    await render(<ApiKeyOptionalPage />);
+
+    await click(testButton());
+    await vi.waitFor(() => expect(testModelConfig).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ endpointId: asrEndpointId, apiKey: "" }),
+      "asr",
+      "asr"
+    ));
+
+    await click(testButton(1));
+    await vi.waitFor(() => expect(testModelConfig).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ endpointId: imageEndpointId, apiKey: "" }),
+      "image",
+      "image"
+    ));
+  });
+
+  it("retests masked inherited middle-step keys through the saved agent endpoint", async () => {
+    const catalog = configuredCatalog(false);
+    const agentEndpointId = assignedCatalogEndpointId(createModelWorkspace(catalog), "byok", "agent");
+    const testModelConfig = vi.fn(async () => ({
+      ok: true,
+      message: "ok",
+      checkedAt: "2026-10-13T00:00:00.000Z"
+    }));
+    mocks.state = { ...createInitialAppState(), modelConfig: maskedSavedModelConfig(catalog) };
+    mocks.clients = createClients(vi.fn(async () => maskedSavedModelConfig(catalog)), { testModelConfig });
+    await render(<ModelPage />);
+
+    const reuseButtons = () => [...container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')];
+    await click(reuseButtons()[1]!);
+    await click(testButton());
+    await vi.waitFor(() => expect(testModelConfig).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ endpointId: agentEndpointId, apiKey: "" }),
+      "chat",
+      "skill"
+    ));
+
+    await click(reuseButtons()[0]!);
+    await click(testButton());
+    await vi.waitFor(() => expect(testModelConfig).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ endpointId: agentEndpointId, apiKey: "" }),
+      "chat",
+      "memory"
+    ));
+  });
+
   it("keeps the middle step pending and retryable when its catalog save fails", async () => {
     const firstSave = deferred<ModelProviderConfig>();
     const saveModelCatalog = vi.fn()

From b433ef36b37c4a20ea98506f3c6a90106ad9cb43 Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Tue, 13 Oct 2026 14:33:31 +0800
Subject: [PATCH 28/85] fix: apply explicit API model selection to resumed
 sessions

---
 .../src/entrypoints/openai-like-api/server.ts | 12 ++++++++++-
 .../openai-like-api/api-stream.test.ts        | 12 +++++++++++
 .../openai-like-api/openai-api.test.ts        | 20 +++++++++++++++++++
 3 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
index 9217d0262..5abfd2dd1 100644
--- a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
+++ b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
@@ -225,6 +225,7 @@ async function callAgent(ctx: ApiContext, args: Record<string, any>): Promise<an
     sessionKey: args.sessionKey ?? args.session_key,
     channel: args.channel,
     chatId: args.chatId ?? args.chat_id,
+    metadata: args.metadata,
     onProgress: args.onProgress,
     onStream: args.onStream,
     onStreamEnd: args.onStreamEnd,
@@ -241,6 +242,7 @@ async function callAgent(ctx: ApiContext, args: Record<string, any>): Promise<an
         senderId: "api",
         content: args.content,
         media: args.media ?? [],
+        metadata: args.metadata,
         sessionKey: args.session_key ?? args.sessionKey,
       }),
     );
@@ -300,6 +302,9 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
     channel: "api",
     chat_id: API_CHAT_ID,
     chatId: API_CHAT_ID,
+    // An explicit API model selects this server's configured default, overriding a stale session binding.
+    ...(requestedModel && typeof context.agentLoop?.modelPreset === "string"
+      ? { metadata: { model_preset: context.agentLoop.modelPreset } } : {}),
   };
 
   if (stream) {
@@ -378,9 +383,14 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
                 if (finalText.trim()) write(sseChunk(finalText, context.modelName, chunkId));
               }
             });
-          } catch {
+          } catch (error) {
             requestTiming("api.error");
             failed = true;
+            const selectionUnavailable = error instanceof Error && error.message === "model_selection_unavailable";
+            write(`data: ${JSON.stringify({ error: {
+              code: selectionUnavailable ? "model_selection_unavailable" : "server_error",
+              message: selectionUnavailable ? "会话绑定的模型已不可用，请重新选择模型。" : "Memmy runtime failed while processing the request.",
+            } })}\n\n`);
           } finally {
             if (!failed) {
               write(sseChunk("", context.modelName, chunkId, "stop"));
diff --git a/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts b/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
index f547178a6..e0d19056b 100644
--- a/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
+++ b/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
@@ -293,5 +293,17 @@ describe("SSE chat completions", () => {
     expect(response.status).toBe(200);
     expect(body).not.toContain('"finish_reason":"stop"');
     expect(body).not.toContain("[DONE]");
+    expect(JSON.parse(ssePayloads(body)[0]).error.code).toBe("server_error");
+    expect(body).not.toContain("backend blew up");
+  });
+
+  it("reports an unavailable session model instead of silently closing the stream", async () => {
+    const app = createApp({ processDirect: async () => {
+      throw new Error("model_selection_unavailable");
+    } }, "m");
+    const response = await app.fetch(request({ messages: [{ role: "user", content: "hi" }], stream: true }));
+    const body = await response.text();
+    expect(JSON.parse(ssePayloads(body)[0]).error).toMatchObject({ code: "model_selection_unavailable" });
+    expect(body).not.toContain("[DONE]");
   });
 });
diff --git a/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts b/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts
index c81b232d8..fe01a530e 100644
--- a/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts
+++ b/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts
@@ -70,6 +70,26 @@ describe("OpenAI-compatible API response helpers", () => {
 });
 
 describe("OpenAI-compatible API request validation", () => {
+  it("overrides a persisted model binding only when the request explicitly selects the configured model", async () => {
+    const calls: any[] = [];
+    const app = createApp({
+      modelPreset: "glm-preset",
+      processMessageInternal() {},
+      processDirect: async (_content: string, options: any) => {
+        calls.push(options);
+        return "ok";
+      },
+    }, "glm-5.2");
+    for (const stream of [false, true]) {
+      const response = await app.fetch(request({ model: "glm-5.2", session_id: "existing",
+        messages: [{ role: "user", content: "hello" }], stream }));
+      await response.text();
+      expect(calls.at(-1)).toMatchObject({ sessionKey: "api:existing", metadata: { model_preset: "glm-preset" } });
+    }
+    await app.fetch(request({ session_id: "existing", messages: [{ role: "user", content: "hello" }] }));
+    expect(calls.at(-1).metadata).toBeUndefined();
+  });
+
   it("returns 400 when messages are missing", async () => {
     const app = createApp({ processDirect: async () => "unused" }, "test-model");
 

From 1d09b69a05e28955c0eab611df773d168025b0d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Tue, 13 Oct 2026 15:30:45 +0800
Subject: [PATCH 29/85] =?UTF-8?q?fix:=20=E6=8B=92=E7=BB=9D=E7=BB=9D?=
 =?UTF-8?q?=E5=AF=B9=E8=B7=AF=E5=BE=84=E4=B8=AD=E7=9A=84=E7=88=B6=E7=BA=A7?=
 =?UTF-8?q?=E8=B7=B3=E8=BD=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/core/agent-runtime/tools/patch-envelope.ts         | 2 +-
 .../tests/core/agent-runtime/tools/bug-671-repro.test.ts   | 4 ++++
 .../tests/core/agent-runtime/tools/patch-envelope.test.ts  | 7 ++++++-
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/App/memmy-agent/src/core/agent-runtime/tools/patch-envelope.ts b/App/memmy-agent/src/core/agent-runtime/tools/patch-envelope.ts
index cc7f0a10a..09b78f8b6 100644
--- a/App/memmy-agent/src/core/agent-runtime/tools/patch-envelope.ts
+++ b/App/memmy-agent/src/core/agent-runtime/tools/patch-envelope.ts
@@ -111,7 +111,7 @@ export function normalizePatchPath(raw: string): string {
 
   const absolute = path.isAbsolute(value);
   const slashPath = value.replace(/\\/g, "/");
-  if (!absolute && slashPath.split("/").some((segment) => segment === "..")) {
+  if (slashPath.split("/").some((segment) => segment === "..")) {
     throw new PatchError(`patch path must not contain '..': ${raw}`);
   }
   const normalized = absolute
diff --git a/App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts b/App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts
index 2f56d057c..88ebbac3d 100644
--- a/App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts
@@ -118,12 +118,16 @@ describe("Bug 671 reproduction", () => {
     const root = workspace();
     const outside = workspace();
     const outsideFile = path.join(outside, "outside.txt");
+    const absoluteTraversal = `${root}${path.sep}nested${path.sep}..${path.sep}escaped.txt`;
     fs.writeFileSync(outsideFile, "outside\n");
     fs.symlinkSync(outsideFile, path.join(root, "outside-link.txt"));
     const tool = new ApplyPatchTool({ workspace: root });
 
     expect(await tool.execute(input("*** Add File: ../escaped.txt", "+escaped")))
       .toContain("must not contain '..'");
+    expect(await tool.execute(input(`*** Add File: ${absoluteTraversal}`, "+escaped")))
+      .toContain("must not contain '..'");
+    expect(fs.existsSync(path.join(root, "escaped.txt"))).toBe(false);
     expect(await tool.execute(input(`*** Delete File: ${outsideFile}`)))
       .toContain("patch path escapes workspace");
     expect(await tool.execute(input("*** Delete File: outside-link.txt")))
diff --git a/App/memmy-agent/tests/core/agent-runtime/tools/patch-envelope.test.ts b/App/memmy-agent/tests/core/agent-runtime/tools/patch-envelope.test.ts
index fa25d76a7..2897ca56a 100644
--- a/App/memmy-agent/tests/core/agent-runtime/tools/patch-envelope.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/tools/patch-envelope.test.ts
@@ -133,10 +133,15 @@ describe("patch envelope parser", () => {
   });
 
   it("accepts absolute paths and normalizes separators and dot segments", () => {
-    const absolute = path.resolve("workspace", "src", "..", "file.ts");
+    const absolute = path.resolve("workspace", "file.ts");
     expect(path.isAbsolute(normalizePatchPath(` ${absolute} `))).toBe(true);
     expect(normalizePatchPath(" ./src\\nested//./file.ts ")).toBe("src/nested/file.ts");
   });
+
+  it("rejects parent traversal in absolute paths before normalization", () => {
+    const absolute = `${path.resolve("workspace")}${path.sep}nested${path.sep}..${path.sep}file.ts`;
+    expect(() => normalizePatchPath(absolute)).toThrow("must not contain '..'");
+  });
 });
 
 describe("patch envelope prefix scanner", () => {

From 94e3eb9889b0b623575a58598ac14c0a5ca40ec0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Sat, 10 Oct 2026 19:22:58 +0800
Subject: [PATCH 30/85] =?UTF-8?q?fix:=20=E6=81=A2=E5=A4=8D=E7=99=BB?=
 =?UTF-8?q?=E5=BD=95=E8=B4=A6=E5=8F=B7=E7=9A=84=E5=86=85=E7=BD=AE=E6=A8=A1?=
 =?UTF-8?q?=E5=9E=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/infrastructure/memmy-config/index.ts  | 14 +++++
 .../services/runtime-config-sync-service.ts   | 32 ++++++++++++
 .../tests/runtime-config-sync-service.test.ts | 51 +++++++++++++++++++
 3 files changed, 97 insertions(+)

diff --git a/App/backend/src/infrastructure/memmy-config/index.ts b/App/backend/src/infrastructure/memmy-config/index.ts
index 050475886..27f640778 100644
--- a/App/backend/src/infrastructure/memmy-config/index.ts
+++ b/App/backend/src/infrastructure/memmy-config/index.ts
@@ -334,6 +334,20 @@ export async function readRuntimeMemmyConfigState(
   return deriveRuntimeMemmyConfigState(parsed, configPath, mode);
 }
 
+/** Reads the persisted runtime user mode without deriving a model selection. */
+export async function readRuntimeMemmyConfigUserMode(
+  configPath = resolveDefaultMemmyConfigPath()
+): Promise<UserMode | undefined> {
+  const content = await readMemmyConfigContent(configPath);
+  if (!content?.trim()) return undefined;
+  const parsed = YAML.parse(content) as unknown;
+  if (!isRecord(parsed)) return undefined;
+  const userMode = existingString(asRecord(parsed.app)?.userMode);
+  return userMode === "account" || userMode === "byok" || userMode === "unset"
+    ? userMode
+    : undefined;
+}
+
 /** Reads agents.defaults.timezone without inventing a configured value. */
 export async function readConfiguredAgentTimeZone(
   configPath = resolveDefaultMemmyConfigPath()
diff --git a/App/backend/src/services/runtime-config-sync-service.ts b/App/backend/src/services/runtime-config-sync-service.ts
index a5a80473d..ab510e37e 100644
--- a/App/backend/src/services/runtime-config-sync-service.ts
+++ b/App/backend/src/services/runtime-config-sync-service.ts
@@ -6,6 +6,7 @@ import {
 } from "../infrastructure/app-state-store/index.js";
 import {
   clearAccountModelProjectionFromMemmyConfig,
+  readRuntimeMemmyConfigUserMode,
   readRuntimeMemmyConfigState,
   writeAccountModelProjectionToMemmyConfig,
   type RuntimeMemmyConfigState
@@ -90,6 +91,7 @@ export async function syncRuntimeConfigWithAppState(
     }
     return accountChannelMismatchResult(options.appStateStore, wroteConfig);
   }
+  state = await restoreMissingActiveAccountProjection(options, state);
   switch (state.status) {
     case "valid_byok": {
       const clearedDormantProjection = await clearUntrustedAccountProjection(options, state.accountProjection);
@@ -135,6 +137,36 @@ export async function syncRuntimeConfigWithAppState(
   }
 }
 
+async function restoreMissingActiveAccountProjection(
+  options: SyncRuntimeConfigWithAppStateOptions,
+  state: RuntimeMemmyConfigState
+): Promise<RuntimeMemmyConfigState> {
+  if (state.status === "valid_account" || state.status === "invalid_yaml" || state.status === "conflict") {
+    return state;
+  }
+
+  const session = options.appStateStore.repositories.accountSession.get();
+  if (!session.authenticated) return state;
+  if (options.appStateStore.repositories.bootstrap.getAppSettings().userMode !== "account") {
+    return state;
+  }
+
+  // An explicit BYOK selection remains authoritative even while the user is signed in.
+  // The repair is only for an account-mode database paired with an unset/incomplete runtime projection.
+  if (await readRuntimeMemmyConfigUserMode(options.memmyConfigPath) === "byok") {
+    return state;
+  }
+
+  const cloudUuid = options.appStateStore.repositories.accountSession.getCloudUuid();
+  if (!cloudUuid) return state;
+  await writeAccountModelProjectionToMemmyConfig({
+    cloudUuid,
+    userId: session.profile.userId,
+    preserveAccountByokSelection: true
+  }, options.memmyConfigPath);
+  return readRuntimeMemmyConfigState(options.memmyConfigPath);
+}
+
 /** Handles sync runtime config for startup. */
 export async function syncRuntimeConfigForStartup(
   options: SyncRuntimeConfigForStartupOptions
diff --git a/App/backend/src/services/tests/runtime-config-sync-service.test.ts b/App/backend/src/services/tests/runtime-config-sync-service.test.ts
index 2bc3c5828..e7000923a 100644
--- a/App/backend/src/services/tests/runtime-config-sync-service.test.ts
+++ b/App/backend/src/services/tests/runtime-config-sync-service.test.ts
@@ -51,6 +51,57 @@ describe("syncRuntimeConfigWithAppState", () => {
     expect(context.store.db.prepare("SELECT * FROM account_model_config ORDER BY uuid").all()).toEqual(legacyBefore);
   });
 
+  it("restores built-in models when an authenticated account has an unset runtime projection", async () => {
+    const context = createContext();
+    seedAccountSession(context, "phone");
+    const config = currentByokCatalog() as any;
+    config.app.userMode = "unset";
+    config.modelAssignments.account = {
+      ownerAccountId: "owner-a",
+      agent: { candidates: ["missing-account-preset"], default: "missing-account-preset" }
+    };
+    context.writeConfig(config);
+
+    await expect(syncRuntimeConfigWithAppState({
+      ...context,
+      accountChannel: "phone"
+    })).resolves.toMatchObject({
+      source: "runtime_config",
+      mode: "account",
+      provider: "memmy_account",
+      model: "agent_chat",
+      hydratedAppState: true
+    });
+
+    const saved = YAML.parse(readFileSync(context.memmyConfigPath, "utf8"));
+    expect(saved.providers.memmy_account).toMatchObject({
+      ownerAccountId: "owner-a",
+      apiKey: "cloud-token-a"
+    });
+    expect(saved.modelAssignments.account.agent.candidates).toContainEqual(
+      expect.stringMatching(/^memmy-account-.+-agent$/)
+    );
+  });
+
+  it("keeps an explicit BYOK runtime selection while the account remains authenticated", async () => {
+    const context = createContext();
+    seedAccountSession(context);
+    context.writeConfig(currentByokCatalog());
+
+    await expect(syncRuntimeConfigWithAppState({
+      ...context,
+      accountChannel: "email"
+    })).resolves.toMatchObject({
+      source: "runtime_config",
+      mode: "byok",
+      provider: "openai",
+      model: "gpt-5"
+    });
+
+    const saved = YAML.parse(readFileSync(context.memmyConfigPath, "utf8"));
+    expect(saved.providers.memmy_account).toBeUndefined();
+  });
+
   it("hydrates account mode only from a current owner-bound projection", async () => {
     const context = createContext();
     context.store.repositories.accountSession.upsert({

From 3ba189ac058f0883addcf75be0d9897273381870 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Tue, 13 Oct 2026 22:10:42 +0800
Subject: [PATCH 31/85] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8D=E7=99=BB?=
 =?UTF-8?q?=E5=BD=95=E8=B4=A6=E5=8F=B7=E5=86=85=E7=BD=AE=E6=A8=A1=E5=9E=8B?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=E6=81=A2=E5=A4=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/infrastructure/memmy-config/index.ts  |  1 +
 .../tests/account-model-projection.test.ts    |  1 +
 .../services/runtime-config-sync-service.ts   | 56 ++++++++++++-------
 .../tests/runtime-config-sync-service.test.ts |  5 +-
 4 files changed, 41 insertions(+), 22 deletions(-)

diff --git a/App/backend/src/infrastructure/memmy-config/index.ts b/App/backend/src/infrastructure/memmy-config/index.ts
index 27f640778..d04c1f30d 100644
--- a/App/backend/src/infrastructure/memmy-config/index.ts
+++ b/App/backend/src/infrastructure/memmy-config/index.ts
@@ -585,6 +585,7 @@ export async function writeAccountModelProjectionToMemmyConfig(
       appConfig,
       LEGACY_ACCOUNT_BYOK_LOCAL_SELECTION_BASELINE
     );
+    appConfig.userMode = "account";
     if (normalizedCloudUuid) appConfig.cloudUuid = normalizedCloudUuid;
     if (normalizedUserId) appConfig.userId = normalizedUserId;
     delete appConfig[LEGACY_ACCOUNT_BYOK_LOCAL_SELECTION_BASELINE];
diff --git a/App/backend/src/infrastructure/memmy-config/tests/account-model-projection.test.ts b/App/backend/src/infrastructure/memmy-config/tests/account-model-projection.test.ts
index 15e43fde3..61031302e 100644
--- a/App/backend/src/infrastructure/memmy-config/tests/account-model-projection.test.ts
+++ b/App/backend/src/infrastructure/memmy-config/tests/account-model-projection.test.ts
@@ -97,6 +97,7 @@ describe("account model projection current catalog", () => {
 
     expect(result).toEqual({ changed: true, memoryConfigAffected: true });
     const saved = await readConfig(file);
+    expect(saved.app.userMode).toBe("account");
     expect(saved.providers.memmy_account).toMatchObject({
       ownerAccountId: "owner-a",
       apiKey: "cloud-token",
diff --git a/App/backend/src/services/runtime-config-sync-service.ts b/App/backend/src/services/runtime-config-sync-service.ts
index ab510e37e..80f32bc5d 100644
--- a/App/backend/src/services/runtime-config-sync-service.ts
+++ b/App/backend/src/services/runtime-config-sync-service.ts
@@ -9,7 +9,8 @@ import {
   readRuntimeMemmyConfigUserMode,
   readRuntimeMemmyConfigState,
   writeAccountModelProjectionToMemmyConfig,
-  type RuntimeMemmyConfigState
+  type RuntimeMemmyConfigState,
+  type RuntimeProjectionResult
 } from "../infrastructure/memmy-config/index.js";
 
 export interface RuntimeConfigMigrationConsistency {
@@ -91,7 +92,8 @@ export async function syncRuntimeConfigWithAppState(
     }
     return accountChannelMismatchResult(options.appStateStore, wroteConfig);
   }
-  state = await restoreMissingActiveAccountProjection(options, state);
+  const restored = await restoreMissingActiveAccountProjection(options, state);
+  state = restored.state;
   switch (state.status) {
     case "valid_byok": {
       const clearedDormantProjection = await clearUntrustedAccountProjection(options, state.accountProjection);
@@ -101,7 +103,7 @@ export async function syncRuntimeConfigWithAppState(
         : hydrated;
     }
     case "valid_account":
-      return hydrateAccountRuntimeConfig(options, state);
+      return hydrateAccountRuntimeConfig(options, state, restored.projection);
     case "missing":
     case "empty":
       return {
@@ -140,31 +142,37 @@ export async function syncRuntimeConfigWithAppState(
 async function restoreMissingActiveAccountProjection(
   options: SyncRuntimeConfigWithAppStateOptions,
   state: RuntimeMemmyConfigState
-): Promise<RuntimeMemmyConfigState> {
+): Promise<{
+  state: RuntimeMemmyConfigState;
+  projection?: RuntimeProjectionResult;
+}> {
   if (state.status === "valid_account" || state.status === "invalid_yaml" || state.status === "conflict") {
-    return state;
+    return { state };
   }
 
   const session = options.appStateStore.repositories.accountSession.get();
-  if (!session.authenticated) return state;
+  if (!session.authenticated) return { state };
   if (options.appStateStore.repositories.bootstrap.getAppSettings().userMode !== "account") {
-    return state;
+    return { state };
   }
 
   // An explicit BYOK selection remains authoritative even while the user is signed in.
   // The repair is only for an account-mode database paired with an unset/incomplete runtime projection.
   if (await readRuntimeMemmyConfigUserMode(options.memmyConfigPath) === "byok") {
-    return state;
+    return { state };
   }
 
   const cloudUuid = options.appStateStore.repositories.accountSession.getCloudUuid();
-  if (!cloudUuid) return state;
-  await writeAccountModelProjectionToMemmyConfig({
+  if (!cloudUuid) return { state };
+  const projection = await writeAccountModelProjectionToMemmyConfig({
     cloudUuid,
     userId: session.profile.userId,
     preserveAccountByokSelection: true
   }, options.memmyConfigPath);
-  return readRuntimeMemmyConfigState(options.memmyConfigPath);
+  return {
+    state: await readRuntimeMemmyConfigState(options.memmyConfigPath),
+    projection
+  };
 }
 
 /** Handles sync runtime config for startup. */
@@ -279,7 +287,8 @@ function hydrateByokRuntimeConfig(
 
 async function hydrateAccountRuntimeConfig(
   options: SyncRuntimeConfigWithAppStateOptions,
-  state: Extract<RuntimeMemmyConfigState, { status: "valid_account" }>
+  state: Extract<RuntimeMemmyConfigState, { status: "valid_account" }>,
+  restoredProjection?: RuntimeProjectionResult
 ): Promise<RuntimeConfigSyncResult> {
   const { appStateStore } = options;
   const activated = appStateStore.repositories.accountSession.activateByCloudUuid(
@@ -303,15 +312,18 @@ async function hydrateAccountRuntimeConfig(
       source: "none",
       mode: appStateStore.repositories.bootstrap.getAppSettings().userMode,
       hydratedAppState: false,
-      wroteConfig: projection.changed,
+      wroteConfig: projection.changed || restoredProjection?.changed === true,
       reason: "account_projection_has_no_matching_local_session"
     };
   }
-  const projection = await writeAccountModelProjectionToMemmyConfig({
-    cloudUuid: state.cloudUuid,
-    userId: session.profile.userId,
-    preserveAccountByokSelection: true
-  }, options.memmyConfigPath);
+  const projection = restoredProjection ?? await writeAccountModelProjectionToMemmyConfig(
+    {
+      cloudUuid: state.cloudUuid,
+      userId: session.profile.userId,
+      preserveAccountByokSelection: true
+    },
+    options.memmyConfigPath
+  );
   appStateStore.repositories.bootstrap.updateAppSettings({ userMode: "account" });
   return {
     source: "runtime_config",
@@ -320,9 +332,11 @@ async function hydrateAccountRuntimeConfig(
     model: "agent_chat",
     hydratedAppState: true,
     wroteConfig: projection.changed,
-    reason: projection.changed
-      ? "refreshed_account_projection_and_hydrated_account"
-      : "hydrated_account_from_runtime_config"
+    reason: restoredProjection?.changed
+      ? "restored_account_projection_and_hydrated_account"
+      : projection.changed
+        ? "refreshed_account_projection_and_hydrated_account"
+        : "hydrated_account_from_runtime_config"
   };
 }
 
diff --git a/App/backend/src/services/tests/runtime-config-sync-service.test.ts b/App/backend/src/services/tests/runtime-config-sync-service.test.ts
index e7000923a..3eb7bec58 100644
--- a/App/backend/src/services/tests/runtime-config-sync-service.test.ts
+++ b/App/backend/src/services/tests/runtime-config-sync-service.test.ts
@@ -70,10 +70,13 @@ describe("syncRuntimeConfigWithAppState", () => {
       mode: "account",
       provider: "memmy_account",
       model: "agent_chat",
-      hydratedAppState: true
+      hydratedAppState: true,
+      wroteConfig: true,
+      reason: "restored_account_projection_and_hydrated_account"
     });
 
     const saved = YAML.parse(readFileSync(context.memmyConfigPath, "utf8"));
+    expect(saved.app.userMode).toBe("account");
     expect(saved.providers.memmy_account).toMatchObject({
       ownerAccountId: "owner-a",
       apiKey: "cloud-token-a"

From 516e2df02cb0dde37cdcda15053a613ec263169a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Wed, 14 Oct 2026 09:20:49 +0800
Subject: [PATCH 32/85] =?UTF-8?q?fix:=20=E4=BF=9D=E7=95=99=E8=B4=A6?=
 =?UTF-8?q?=E5=8F=B7=E6=A8=A1=E5=9E=8B=E6=81=A2=E5=A4=8D=E7=BB=93=E6=9E=9C?=
 =?UTF-8?q?=E5=B9=B6=E6=A0=A1=E9=AA=8C=E8=B4=A6=E5=8F=B7=E4=B8=80=E8=87=B4?=
 =?UTF-8?q?=E6=80=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../services/runtime-config-sync-service.ts   | 23 +++--
 .../tests/runtime-config-sync-service.test.ts | 91 ++++++++++++++++++-
 2 files changed, 106 insertions(+), 8 deletions(-)

diff --git a/App/backend/src/services/runtime-config-sync-service.ts b/App/backend/src/services/runtime-config-sync-service.ts
index 80f32bc5d..d58357bb5 100644
--- a/App/backend/src/services/runtime-config-sync-service.ts
+++ b/App/backend/src/services/runtime-config-sync-service.ts
@@ -54,6 +54,12 @@ type RuntimeConfigSyncErrorState = {
   reason: string;
 };
 
+interface RestoredAccountProjection {
+  cloudUuid: string;
+  userId: string;
+  result: RuntimeProjectionResult;
+}
+
 /**
  * Hydrate current AppState from config.yaml. Missing runtime config is left untouched:
  * importing SQLite model rows into YAML belongs exclusively to startup migrations.
@@ -144,7 +150,7 @@ async function restoreMissingActiveAccountProjection(
   state: RuntimeMemmyConfigState
 ): Promise<{
   state: RuntimeMemmyConfigState;
-  projection?: RuntimeProjectionResult;
+  projection?: RestoredAccountProjection;
 }> {
   if (state.status === "valid_account" || state.status === "invalid_yaml" || state.status === "conflict") {
     return { state };
@@ -171,7 +177,7 @@ async function restoreMissingActiveAccountProjection(
   }, options.memmyConfigPath);
   return {
     state: await readRuntimeMemmyConfigState(options.memmyConfigPath),
-    projection
+    projection: { cloudUuid, userId: session.profile.userId, result: projection }
   };
 }
 
@@ -288,7 +294,7 @@ function hydrateByokRuntimeConfig(
 async function hydrateAccountRuntimeConfig(
   options: SyncRuntimeConfigWithAppStateOptions,
   state: Extract<RuntimeMemmyConfigState, { status: "valid_account" }>,
-  restoredProjection?: RuntimeProjectionResult
+  restoredProjection?: RestoredAccountProjection
 ): Promise<RuntimeConfigSyncResult> {
   const { appStateStore } = options;
   const activated = appStateStore.repositories.accountSession.activateByCloudUuid(
@@ -312,11 +318,14 @@ async function hydrateAccountRuntimeConfig(
       source: "none",
       mode: appStateStore.repositories.bootstrap.getAppSettings().userMode,
       hydratedAppState: false,
-      wroteConfig: projection.changed || restoredProjection?.changed === true,
+      wroteConfig: projection.changed || restoredProjection?.result.changed === true,
       reason: "account_projection_has_no_matching_local_session"
     };
   }
-  const projection = restoredProjection ?? await writeAccountModelProjectionToMemmyConfig(
+  // Reuse a completed repair only after validating the session and its account identity.
+  const restoredForCurrentAccount = restoredProjection?.cloudUuid === state.cloudUuid
+    && restoredProjection.userId === session.profile.userId;
+  const projection = restoredForCurrentAccount ? restoredProjection.result : await writeAccountModelProjectionToMemmyConfig(
     {
       cloudUuid: state.cloudUuid,
       userId: session.profile.userId,
@@ -331,8 +340,8 @@ async function hydrateAccountRuntimeConfig(
     provider: "memmy_account",
     model: "agent_chat",
     hydratedAppState: true,
-    wroteConfig: projection.changed,
-    reason: restoredProjection?.changed
+    wroteConfig: projection.changed || restoredProjection?.result.changed === true,
+    reason: restoredForCurrentAccount && restoredProjection.result.changed
       ? "restored_account_projection_and_hydrated_account"
       : projection.changed
         ? "refreshed_account_projection_and_hydrated_account"
diff --git a/App/backend/src/services/tests/runtime-config-sync-service.test.ts b/App/backend/src/services/tests/runtime-config-sync-service.test.ts
index 3eb7bec58..1c941259b 100644
--- a/App/backend/src/services/tests/runtime-config-sync-service.test.ts
+++ b/App/backend/src/services/tests/runtime-config-sync-service.test.ts
@@ -3,8 +3,9 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import YAML from "yaml";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createAppStateStore, type AppStateStore } from "../../infrastructure/app-state-store/index.js";
+import * as memmyConfig from "../../infrastructure/memmy-config/index.js";
 import {
   createMemmyConfigWriter,
   writeAccountModelProjectionToMemmyConfig
@@ -21,6 +22,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  vi.restoreAllMocks();
   store?.close();
   store = undefined;
   if (tempDir) rmSync(tempDir, { recursive: true, force: true });
@@ -62,6 +64,10 @@ describe("syncRuntimeConfigWithAppState", () => {
     };
     context.writeConfig(config);
 
+    const writeProjection = vi.spyOn(memmyConfig, "writeAccountModelProjectionToMemmyConfig");
+    const activateSession = vi.spyOn(context.store.repositories.accountSession, "activateByCloudUuid");
+    const updateSettings = vi.spyOn(context.store.repositories.bootstrap, "updateAppSettings");
+
     await expect(syncRuntimeConfigWithAppState({
       ...context,
       accountChannel: "phone"
@@ -74,6 +80,9 @@ describe("syncRuntimeConfigWithAppState", () => {
       wroteConfig: true,
       reason: "restored_account_projection_and_hydrated_account"
     });
+    expect(writeProjection).toHaveBeenCalledTimes(1);
+    expect(activateSession).toHaveBeenCalledWith("cloud-token-a", "phone");
+    expect(updateSettings).toHaveBeenCalledWith({ userMode: "account" });
 
     const saved = YAML.parse(readFileSync(context.memmyConfigPath, "utf8"));
     expect(saved.app.userMode).toBe("account");
@@ -84,6 +93,86 @@ describe("syncRuntimeConfigWithAppState", () => {
     expect(saved.modelAssignments.account.agent.candidates).toContainEqual(
       expect.stringMatching(/^memmy-account-.+-agent$/)
     );
+
+    const repairedConfig = readFileSync(context.memmyConfigPath, "utf8");
+    await expect(syncRuntimeConfigWithAppState({
+      ...context,
+      accountChannel: "phone"
+    })).resolves.toMatchObject({
+      mode: "account",
+      hydratedAppState: true,
+      wroteConfig: false,
+      reason: "hydrated_account_from_runtime_config"
+    });
+    // A normal restart still refreshes the projection, but makes no redundant changes.
+    expect(writeProjection).toHaveBeenCalledTimes(2);
+    expect(readFileSync(context.memmyConfigPath, "utf8")).toBe(repairedConfig);
+  });
+
+  it("validates the session after repairing a missing account projection", async () => {
+    const context = createContext();
+    seedAccountSession(context);
+    const config = currentByokCatalog() as any;
+    config.app.userMode = "unset";
+    context.writeConfig(config);
+    const writeProjection = vi.spyOn(memmyConfig, "writeAccountModelProjectionToMemmyConfig");
+    vi.spyOn(context.store.repositories.accountSession, "activateByCloudUuid").mockReturnValue(false);
+    const updateSettings = vi.spyOn(context.store.repositories.bootstrap, "updateAppSettings");
+
+    await expect(syncRuntimeConfigWithAppState({ ...context, accountChannel: "email" }))
+      .resolves.toMatchObject({
+        source: "none",
+        hydratedAppState: false,
+        wroteConfig: true,
+        reason: "account_projection_has_no_matching_local_session"
+      });
+    expect(writeProjection).toHaveBeenCalledTimes(1);
+    expect(updateSettings).not.toHaveBeenCalled();
+    const saved = YAML.parse(readFileSync(context.memmyConfigPath, "utf8"));
+    expect(saved.providers.memmy_account).toBeUndefined();
+  });
+
+  it("refreshes a different account if its projection replaces the repaired config before hydration", async () => {
+    const context = createContext();
+    seedAccountSession(context);
+    const session = context.store.repositories.accountSession.get();
+    if (!session.authenticated) throw new Error("Expected the seeded account session");
+    context.store.repositories.accountSession.upsert({
+      profile: { ...session.profile, userId: "owner-b" },
+      uuid: "account-b",
+      cloudUuid: "cloud-token-b",
+      authChannel: "email"
+    });
+    context.store.repositories.accountSession.activateByCloudUuid("cloud-token-a", "email");
+    const config = currentByokCatalog() as any;
+    config.app.userMode = "unset";
+    context.writeConfig(config);
+    const originalWrite = memmyConfig.writeAccountModelProjectionToMemmyConfig;
+    const writeProjection = vi.spyOn(memmyConfig, "writeAccountModelProjectionToMemmyConfig")
+      .mockImplementationOnce(async (...args) => {
+        const result = await originalWrite(...args);
+        // Model a concurrent account switch while the repaired config is being re-read.
+        context.writeRaw(YAML.stringify(currentAccountCatalog())
+          .replaceAll("owner-a", "owner-b")
+          .replaceAll("cloud-token-a", "cloud-token-b"));
+        return result;
+      });
+
+    await expect(syncRuntimeConfigWithAppState({ ...context, accountChannel: "email" }))
+      .resolves.toMatchObject({ mode: "account", hydratedAppState: true, wroteConfig: true });
+    expect(writeProjection).toHaveBeenCalledTimes(2);
+    expect(writeProjection).toHaveBeenLastCalledWith({
+      cloudUuid: "cloud-token-b", userId: "owner-b", preserveAccountByokSelection: true
+    }, context.memmyConfigPath);
+    expect(context.store.repositories.accountSession.get()).toMatchObject({
+      authenticated: true, profile: { userId: "owner-b" }
+    });
+    const saved = YAML.parse(readFileSync(context.memmyConfigPath, "utf8"));
+    expect(saved.providers.memmy_account.ownerAccountId).toBe("owner-b");
+    expect(saved.modelAssignments.account.ownerAccountId).toBe("owner-b");
+    expect(saved.modelPresets[saved.modelAssignments.account.memorySummary]).toMatchObject({
+      source: "account", ownerAccountId: "owner-b", capabilities: ["memory_summary"]
+    });
   });
 
   it("keeps an explicit BYOK runtime selection while the account remains authenticated", async () => {

From 679b0ec530d18fdf79ab4450f056a514e046c3ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Wed, 14 Oct 2026 10:32:31 +0800
Subject: [PATCH 33/85] =?UTF-8?q?fix:=20=E4=BF=9D=E7=95=99=E8=A1=A5?=
 =?UTF-8?q?=E4=B8=81=E8=A7=84=E8=8C=83=E5=8C=96=E8=B7=AF=E5=BE=84=E4=B8=AD?=
 =?UTF-8?q?=E7=9A=84=E6=96=87=E4=BB=B6=E5=90=8D=E7=A9=BA=E6=A0=BC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../core/agent-runtime/tools/apply-patch.ts   |  11 +-
 .../tools/apply-patch-tool.test.ts            |  58 ++++++-
 .../agent-runtime/tools/bug-671-repro.test.ts | 150 ------------------
 3 files changed, 63 insertions(+), 156 deletions(-)
 delete mode 100644 App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts

diff --git a/App/memmy-agent/src/core/agent-runtime/tools/apply-patch.ts b/App/memmy-agent/src/core/agent-runtime/tools/apply-patch.ts
index d8b015b1f..c9d671e45 100644
--- a/App/memmy-agent/src/core/agent-runtime/tools/apply-patch.ts
+++ b/App/memmy-agent/src/core/agent-runtime/tools/apply-patch.ts
@@ -328,8 +328,7 @@ Paths may be workspace-relative or absolute paths inside the workspace. Use at m
     return params;
   }
 
-  resolve(requestedPath: string): string {
-    const normalized = normalizePatchPath(requestedPath);
+  private resolveNormalizedPath(normalized: string, requestedPath = normalized): string {
     const target = path.isAbsolute(normalized)
       ? path.resolve(normalized)
       : path.resolve(this.workspace, ...normalized.split("/"));
@@ -358,6 +357,10 @@ Paths may be workspace-relative or absolute paths inside the workspace. Use at m
     return target;
   }
 
+  resolve(requestedPath: string): string {
+    return this.resolveNormalizedPath(normalizePatchPath(requestedPath), requestedPath);
+  }
+
   private normalizeOperations(operations: PatchFileOperation[]): PatchFileOperation[] {
     const relativePath = (requestedPath: string): string =>
       path.relative(this.workspace, this.resolve(requestedPath)).split(path.sep).join("/");
@@ -395,9 +398,9 @@ Paths may be workspace-relative or absolute paths inside the workspace. Use at m
     const resolved = new Map<string, string>();
     for (const operation of operations) {
       throwIfAborted(signal);
-      resolved.set(operation.path, this.resolve(operation.path));
+      resolved.set(operation.path, this.resolveNormalizedPath(operation.path));
       if (operation.kind === "update" && operation.moveTo) {
-        resolved.set(operation.moveTo, this.resolve(operation.moveTo));
+        resolved.set(operation.moveTo, this.resolveNormalizedPath(operation.moveTo));
       }
     }
 
diff --git a/App/memmy-agent/tests/core/agent-runtime/tools/apply-patch-tool.test.ts b/App/memmy-agent/tests/core/agent-runtime/tools/apply-patch-tool.test.ts
index adcce77ca..1e234b010 100644
--- a/App/memmy-agent/tests/core/agent-runtime/tools/apply-patch-tool.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/tools/apply-patch-tool.test.ts
@@ -127,6 +127,53 @@ describe("ApplyPatchTool operations", () => {
     expect(fs.readFileSync(path.join(root, "moved.txt"), "utf8")).toBe("after\n");
   });
 
+  it("supports absolute paths for every operation and preserves filename spaces", async () => {
+    const root = workspace();
+    const added = path.join(root, " added.txt");
+    const updated = path.join(root, " updated.txt");
+    const deleted = path.join(root, " deleted.txt");
+    const moveSource = path.join(root, " move-source.txt");
+    const moveTarget = path.join(root, " moved-target.txt");
+    fs.writeFileSync(updated, "before\n");
+    fs.writeFileSync(deleted, "delete\n");
+    fs.writeFileSync(moveSource, "move\n");
+
+    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
+      `*** Add File: ${added}`,
+      "+added",
+      `*** Update File: ${updated}`,
+      "@@",
+      "-before",
+      "+after",
+      `*** Delete File: ${deleted}`,
+      `*** Update File: ${moveSource}`,
+      `*** Move to: ${moveTarget}`,
+    ));
+
+    expect(result).toContain("Patch applied:");
+    expect(fs.readFileSync(added, "utf8")).toBe("added\n");
+    expect(fs.existsSync(path.join(root, "added.txt"))).toBe(false);
+    expect(fs.readFileSync(updated, "utf8")).toBe("after\n");
+    expect(fs.existsSync(path.join(root, "updated.txt"))).toBe(false);
+    expect(fs.existsSync(deleted)).toBe(false);
+    expect(fs.existsSync(moveSource)).toBe(false);
+    expect(fs.readFileSync(moveTarget, "utf8")).toBe("move\n");
+    expect(fs.existsSync(path.join(root, "moved-target.txt"))).toBe(false);
+  });
+
+  it("detects conflicts after absolute and relative paths are canonicalized", async () => {
+    const root = workspace();
+    const target = path.join(root, "same.txt");
+    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
+      `*** Add File: ${target}`,
+      "+first",
+      "*** Delete File: same.txt",
+    ));
+
+    expect(result).toContain("duplicate file operation path: same.txt");
+    expect(fs.existsSync(target)).toBe(false);
+  });
+
   it("creates an empty file and preserves extra blank lines", async () => {
     const root = workspace();
     const result = await new ApplyPatchTool({ workspace: root }).execute(input(
@@ -184,16 +231,23 @@ describe("ApplyPatchTool operations", () => {
   it("rejects symlink paths and non-directory parents before reading content", async () => {
     const root = workspace();
     const outside = workspace();
-    fs.writeFileSync(path.join(outside, "outside.txt"), "outside\n");
-    fs.symlinkSync(path.join(outside, "outside.txt"), path.join(root, "link.txt"));
+    const outsideFile = path.join(outside, "outside.txt");
+    const absoluteTraversal = `${root}${path.sep}nested${path.sep}..${path.sep}escaped.txt`;
+    fs.writeFileSync(outsideFile, "outside\n");
+    fs.symlinkSync(outsideFile, path.join(root, "link.txt"));
     fs.writeFileSync(path.join(root, "parent"), "file\n");
     const tool = new ApplyPatchTool({ workspace: root });
 
+    expect(await tool.execute(input(`*** Add File: ${absoluteTraversal}`, "+escaped")))
+      .toContain("must not contain '..'");
+    expect(await tool.execute(input(`*** Delete File: ${outsideFile}`)))
+      .toContain("patch path escapes workspace");
     expect(await tool.execute(input("*** Delete File: link.txt"))).toContain("symbolic links");
     expect(await tool.execute(input("*** Add File: parent/child.txt", "+x"))).toContain(
       "parent is not a directory",
     );
     expect(fs.readFileSync(path.join(outside, "outside.txt"), "utf8")).toBe("outside\n");
+    expect(fs.existsSync(path.join(root, "escaped.txt"))).toBe(false);
   });
 
   it("plans every operation before the first write", async () => {
diff --git a/App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts b/App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts
deleted file mode 100644
index 88ebbac3d..000000000
--- a/App/memmy-agent/tests/core/agent-runtime/tools/bug-671-repro.test.ts
+++ /dev/null
@@ -1,150 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { ApplyPatchTool } from "../../../../src/core/agent-runtime/tools/apply-patch.js";
-import { EditFileTool, WriteFileTool } from "../../../../src/core/agent-runtime/tools/filesystem.js";
-
-const roots: string[] = [];
-
-function workspace(): string {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "memmy-bug671-"));
-  roots.push(root);
-  return root;
-}
-
-function input(...lines: string[]): { input: string } {
-  return { input: ["*** Begin Patch", ...lines, "*** End Patch"].join("\n") };
-}
-
-afterEach(() => {
-  for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
-});
-
-describe("Bug 671 reproduction", () => {
-  it("accepts an in-workspace absolute path when adding", async () => {
-    const root = workspace();
-    const target = path.join(root, "added.txt");
-    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
-      `*** Add File: ${target}`,
-      "+added",
-    ));
-
-    expect(result).toContain("Patch applied:");
-    expect(fs.readFileSync(target, "utf8")).toBe("added\n");
-  });
-
-  it("accepts an in-workspace absolute path when updating", async () => {
-    const root = workspace();
-    const target = path.join(root, "updated.txt");
-    fs.writeFileSync(target, "before\n");
-    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
-      `*** Update File: ${target}`,
-      "@@",
-      "-before",
-      "+after",
-    ));
-
-    expect(result).toContain("Patch applied:");
-    expect(fs.readFileSync(target, "utf8")).toBe("after\n");
-  });
-
-  it("accepts an in-workspace absolute path when deleting", async () => {
-    const root = workspace();
-    const target = path.join(root, "deleted.txt");
-    fs.writeFileSync(target, "delete\n");
-    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
-      `*** Delete File: ${target}`,
-    ));
-
-    expect(result).toContain("Patch applied:");
-    expect(fs.existsSync(target)).toBe(false);
-  });
-
-  it("accepts an in-workspace absolute move source", async () => {
-    const root = workspace();
-    const source = path.join(root, "source.txt");
-    fs.writeFileSync(source, "move\n");
-    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
-      `*** Update File: ${source}`,
-      "*** Move to: moved.txt",
-    ));
-
-    expect(result).toContain("Patch applied:");
-    expect(fs.readFileSync(path.join(root, "moved.txt"), "utf8")).toBe("move\n");
-  });
-
-  it("accepts an in-workspace absolute move target", async () => {
-    const root = workspace();
-    const source = path.join(root, "source.txt");
-    const target = path.join(root, "moved.txt");
-    fs.writeFileSync(source, "move\n");
-    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
-      "*** Update File: source.txt",
-      `*** Move to: ${target}`,
-    ));
-
-    expect(result).toContain("Patch applied:");
-    expect(fs.readFileSync(target, "utf8")).toBe("move\n");
-  });
-
-  it("continues accepting relative apply_patch paths", async () => {
-    const root = workspace();
-    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
-      "*** Add File: relative.txt",
-      "+relative",
-    ));
-
-    expect(result).toContain("Patch applied:");
-    expect(fs.readFileSync(path.join(root, "relative.txt"), "utf8")).toBe("relative\n");
-  });
-
-  it("matches write_file and edit_file absolute-path behavior", async () => {
-    const root = workspace();
-    const target = path.join(root, "other-tools.txt");
-    const options = { workspace: root, allowedDir: root, postWriteValidation: false } as any;
-
-    expect(await new WriteFileTool(options).execute({ path: target, content: "before\n" }))
-      .toContain("Successfully wrote");
-    expect(await new EditFileTool(options).execute({
-      path: target,
-      old_text: "before",
-      new_text: "after",
-    })).toContain("Successfully edited file");
-    expect(fs.readFileSync(target, "utf8")).toBe("after\n");
-  });
-
-  it("still rejects traversal and symbolic links", async () => {
-    const root = workspace();
-    const outside = workspace();
-    const outsideFile = path.join(outside, "outside.txt");
-    const absoluteTraversal = `${root}${path.sep}nested${path.sep}..${path.sep}escaped.txt`;
-    fs.writeFileSync(outsideFile, "outside\n");
-    fs.symlinkSync(outsideFile, path.join(root, "outside-link.txt"));
-    const tool = new ApplyPatchTool({ workspace: root });
-
-    expect(await tool.execute(input("*** Add File: ../escaped.txt", "+escaped")))
-      .toContain("must not contain '..'");
-    expect(await tool.execute(input(`*** Add File: ${absoluteTraversal}`, "+escaped")))
-      .toContain("must not contain '..'");
-    expect(fs.existsSync(path.join(root, "escaped.txt"))).toBe(false);
-    expect(await tool.execute(input(`*** Delete File: ${outsideFile}`)))
-      .toContain("patch path escapes workspace");
-    expect(await tool.execute(input("*** Delete File: outside-link.txt")))
-      .toContain("symbolic links");
-    expect(fs.readFileSync(outsideFile, "utf8")).toBe("outside\n");
-  });
-
-  it("detects conflicts after absolute and relative paths are canonicalized", async () => {
-    const root = workspace();
-    const absolute = path.join(root, "same.txt");
-    const result = await new ApplyPatchTool({ workspace: root }).execute(input(
-      `*** Add File: ${absolute}`,
-      "+first",
-      "*** Delete File: same.txt",
-    ));
-
-    expect(result).toContain("duplicate file operation path: same.txt");
-    expect(fs.existsSync(absolute)).toBe(false);
-  });
-});

From 43ead001ef22dafe92a58542b6aad17393af4637 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Wed, 14 Oct 2026 12:05:24 +0800
Subject: [PATCH 34/85] fix: trim API keys when matching pending presets

---
 App/frontend/desktop/src/api/config-client.ts |  28 +++--
 .../src/api/tests/config-client.test.ts       | 111 ++++++++++--------
 2 files changed, 77 insertions(+), 62 deletions(-)

diff --git a/App/frontend/desktop/src/api/config-client.ts b/App/frontend/desktop/src/api/config-client.ts
index 2446bf2aa..8ad8e5242 100644
--- a/App/frontend/desktop/src/api/config-client.ts
+++ b/App/frontend/desktop/src/api/config-client.ts
@@ -606,8 +606,8 @@ interface PendingPreset {
   endpointId: string;
   endpointApiBase: string | null;
   endpointProtocol: ModelEndpointProtocol | null;
-  endpointApiKey: string;
-  providerApiKey: string;
+  endpointApiKey?: string;
+  providerApiKey?: string;
   model: string;
   source: "account" | "byok";
   capabilities: ModelCapability[];
@@ -616,6 +616,8 @@ interface PendingPreset {
 function pendingPresets(input: ModelConfigInput): PendingPreset[] {
   return input.providers.flatMap((provider) => provider.models.flatMap((model) => {
     const endpoint = provider.endpoints.find((item) => item.endpointId === model.endpointId);
+    const endpointApiKey = trimNonEmpty(endpoint?.apiKey);
+    const providerApiKey = trimNonEmpty(provider.apiKey);
     return model.presetId?.startsWith(CLIENT_PRESET_ID_PREFIX)
       ? [{
           clientId: model.presetId,
@@ -623,8 +625,8 @@ function pendingPresets(input: ModelConfigInput): PendingPreset[] {
           endpointId: model.endpointId,
           endpointApiBase: endpoint?.apiBase ?? null,
           endpointProtocol: endpoint?.protocol ?? null,
-          endpointApiKey: endpoint?.apiKey ?? "",
-          providerApiKey: provider.apiKey ?? "",
+          ...(endpointApiKey ? { endpointApiKey } : {}),
+          ...(providerApiKey ? { providerApiKey } : {}),
           model: model.model,
           source: model.source,
           capabilities: [...model.capabilities]
@@ -693,8 +695,8 @@ function pendingEndpointMatches(
   ) {
     return false;
   }
-  const expectedApiKey = maskSecret(item.endpointApiKey || item.providerApiKey);
-  const actualApiKey = endpoint.hasApiKey ? endpoint.apiKeyMasked : provider.apiKeyMasked;
+  const expectedApiKey = maskSecret(item.endpointApiKey ?? item.providerApiKey);
+  const actualApiKey = trimNonEmpty(endpoint.hasApiKey ? endpoint.apiKeyMasked : provider.apiKeyMasked);
   return !expectedApiKey || expectedApiKey === actualApiKey;
 }
 
@@ -702,10 +704,16 @@ function normalizeApiBase(value: string): string {
   return value.trim().replace(/\/+$/u, "");
 }
 
-function maskSecret(value: string): string {
-  if (!value) return "";
-  if (value.length <= 8) return "••••••••";
-  return `${value.slice(0, 3)}••••${value.slice(-4)}`;
+function trimNonEmpty(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed || undefined;
+}
+
+function maskSecret(value: string | undefined): string | undefined {
+  const secret = trimNonEmpty(value);
+  if (!secret) return undefined;
+  if (secret.length <= 8) return "••••••••";
+  return `${secret.slice(0, 3)}••••${secret.slice(-4)}`;
 }
 
 function assignmentPhaseInput(
diff --git a/App/frontend/desktop/src/api/tests/config-client.test.ts b/App/frontend/desktop/src/api/tests/config-client.test.ts
index 4940a39ba..76d1efb9e 100644
--- a/App/frontend/desktop/src/api/tests/config-client.test.ts
+++ b/App/frontend/desktop/src/api/tests/config-client.test.ts
@@ -209,64 +209,71 @@ describe("config-client canonical model catalog", () => {
     expect(saved.catalog?.modelAssignments.byok.agent.default).toBe(serverPresetId);
   });
 
-  it("后端合并相同 endpoint 定义后仍能解析新模型并完成 assignment", async () => {
-    const bodies: any[] = [];
-    const serverPresetId = "5c8872cf-28c8-4cf3-bf51-9a3a2a0fb42a";
-    vi.stubGlobal("fetch", vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
-      const body = JSON.parse(String(init?.body));
-      bodies.push(body);
-      const response = catalog(bodies.length === 1 ? "revision-2" : "revision-3");
-      response.providers[0]!.models.push({
-        presetId: serverPresetId,
-        provider: "openai",
-        endpointId: "chat",
+  it.each(["endpoint apiKey", "provider apiKey", "missing apiKey"] as const)(
+    "后端合并相同 endpoint 定义后可用 %s 解析新模型并完成 assignment",
+    async (keyLocation) => {
+      const bodies: any[] = [];
+      const serverPresetId = "5c8872cf-28c8-4cf3-bf51-9a3a2a0fb42a";
+      vi.stubGlobal("fetch", vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
+        const body = JSON.parse(String(init?.body));
+        bodies.push(body);
+        const response = catalog(bodies.length === 1 ? "revision-2" : "revision-3");
+        response.providers[0]!.apiKeyMasked = "sk-••••1234";
+        for (const endpoint of response.providers[0]!.endpoints) endpoint.apiKeyMasked = "sk-••••1234";
+        response.providers[0]!.models.push({
+          presetId: serverPresetId,
+          provider: "openai",
+          endpointId: "chat",
+          protocol: "openai-chat-completions",
+          model: "gpt-new",
+          source: "byok",
+          capabilities: ["agent"],
+          available: true
+        });
+        if (bodies.length > 1) {
+          response.modelAssignments.byok.agent = {
+            candidates: ["byok-agent", serverPresetId],
+            default: serverPresetId
+          };
+        }
+        return jsonResponse(response);
+      }));
+      const input = inputFromCatalog(catalog("revision-1"));
+      const clientPresetId = `${CLIENT_PRESET_ID_PREFIX}canonicalized-endpoint`;
+      input.providers[0]!.endpoints.push({
+        endpointId: "chat-duplicate",
+        apiBase: "https://api.openai.com/v1/",
         protocol: "openai-chat-completions",
+        ...(keyLocation === "endpoint apiKey" ? { apiKey: "  sk-live1234  " } : {})
+      });
+      if (keyLocation === "provider apiKey") input.providers[0]!.apiKey = "  sk-live1234  ";
+      input.providers[0]!.models.push({
+        presetId: clientPresetId,
+        endpointId: "chat-duplicate",
         model: "gpt-new",
         source: "byok",
-        capabilities: ["agent"],
-        available: true
+        capabilities: ["agent"]
       });
-      if (bodies.length > 1) {
-        response.modelAssignments.byok.agent = {
-          candidates: ["byok-agent", serverPresetId],
-          default: serverPresetId
-        };
-      }
-      return jsonResponse(response);
-    }));
-    const input = inputFromCatalog(catalog("revision-1"));
-    const clientPresetId = `${CLIENT_PRESET_ID_PREFIX}canonicalized-endpoint`;
-    input.providers[0]!.endpoints.push({
-      endpointId: "chat-duplicate",
-      apiBase: "https://api.openai.com/v1/",
-      protocol: "openai-chat-completions"
-    });
-    input.providers[0]!.models.push({
-      presetId: clientPresetId,
-      endpointId: "chat-duplicate",
-      model: "gpt-new",
-      source: "byok",
-      capabilities: ["agent"]
-    });
-    input.modelAssignments.byok.agent = {
-      candidates: ["byok-agent", clientPresetId],
-      default: clientPresetId
-    };
+      input.modelAssignments.byok.agent = {
+        candidates: ["byok-agent", clientPresetId],
+        default: clientPresetId
+      };
 
-    const saved = await createHttpConfigClient(config).saveModelCatalog(input);
+      const saved = await createHttpConfigClient(config).saveModelCatalog(input);
 
-    expect(bodies).toHaveLength(2);
-    expect(bodies[0].providers[0].endpoints.some((endpoint: any) => endpoint.endpointId === "chat-duplicate")).toBe(true);
-    expect(bodies[1].providers[0].models.find((model: any) => model.model === "gpt-new")).toMatchObject({
-      presetId: serverPresetId,
-      endpointId: "chat"
-    });
-    expect(bodies[1].modelAssignments.byok.agent).toEqual({
-      candidates: ["byok-agent", serverPresetId],
-      default: serverPresetId
-    });
-    expect(saved.catalog?.modelAssignments.byok.agent.default).toBe(serverPresetId);
-  });
+      expect(bodies).toHaveLength(2);
+      expect(bodies[0].providers[0].endpoints.some((endpoint: any) => endpoint.endpointId === "chat-duplicate")).toBe(true);
+      expect(bodies[1].providers[0].models.find((model: any) => model.model === "gpt-new")).toMatchObject({
+        presetId: serverPresetId,
+        endpointId: "chat"
+      });
+      expect(bodies[1].modelAssignments.byok.agent).toEqual({
+        candidates: ["byok-agent", serverPresetId],
+        default: serverPresetId
+      });
+      expect(saved.catalog?.modelAssignments.byok.agent.default).toBe(serverPresetId);
+    }
+  );
 
   it("首次成功 GET 后只清理旧 workspace cache", async () => {
     const removeItem = vi.fn();

From f83cdf1283e369237726b44cf5b2bc9244247775 Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Wed, 14 Oct 2026 12:16:46 +0800
Subject: [PATCH 35/85] fix: build bundled agent and memory runtimes in Memmy

---
 App/memmy-agent/scripts/build-npm-package.mjs |   2 +
 App/memmy-agent/scripts/build-runtime.mjs     |  64 ++++++
 App/memmy-agent/src/runtime-main.ts           |  39 ++++
 Memory/src/cli/scripts/build-runtime.mjs      |  13 +-
 package-lock.json                             |   1 +
 package.json                                  |   4 +-
 scripts/internal/shared/bundle-runtime.mjs    | 183 ++++++++++++++++++
 scripts/internal/shared/npm-invocation.mjs    |  15 ++
 scripts/internal/shared/runtime-payload.mjs   |  85 ++++++++
 tests/runtime-bundle.test.ts                  | 124 ++++++++++++
 10 files changed, 527 insertions(+), 3 deletions(-)
 create mode 100644 App/memmy-agent/scripts/build-runtime.mjs
 create mode 100644 App/memmy-agent/src/runtime-main.ts
 create mode 100644 scripts/internal/shared/bundle-runtime.mjs
 create mode 100644 scripts/internal/shared/npm-invocation.mjs
 create mode 100644 scripts/internal/shared/runtime-payload.mjs
 create mode 100644 tests/runtime-bundle.test.ts

diff --git a/App/memmy-agent/scripts/build-npm-package.mjs b/App/memmy-agent/scripts/build-npm-package.mjs
index ef6432e0d..6ff720a20 100644
--- a/App/memmy-agent/scripts/build-npm-package.mjs
+++ b/App/memmy-agent/scripts/build-npm-package.mjs
@@ -1,4 +1,5 @@
 import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { npmInvocation } from "../../../scripts/internal/shared/npm-invocation.mjs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
@@ -83,6 +84,7 @@ async function exists(path) {
 }
 
 function run(command, args, cwd) {
+  if (command === "npm") ({ command, args } = npmInvocation(args));
   return new Promise((resolvePromise, reject) => {
     const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "inherit"] });
     let stdout = "";
diff --git a/App/memmy-agent/scripts/build-runtime.mjs b/App/memmy-agent/scripts/build-runtime.mjs
new file mode 100644
index 000000000..4ca5bd08e
--- /dev/null
+++ b/App/memmy-agent/scripts/build-runtime.mjs
@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { npmInvocation } from "../../../scripts/internal/shared/npm-invocation.mjs";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { cp, mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { spawnSync } from "node:child_process";
+import { bundleRuntime } from "../../../scripts/internal/shared/bundle-runtime.mjs";
+
+if (Number(process.versions.node.split(".")[0]) < 22) throw new Error("Agent runtime requires Node 22 or newer.");
+
+const agentRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const { values } = parseArgs({ options: {
+  target: { type: "string" }, output: { type: "string" }, "skip-build": { type: "boolean" }
+} });
+const hostTarget = `${process.platform === "win32" ? "windows" : process.platform}-${process.arch}`;
+const target = values.target ?? hostTarget;
+// Native modules must be installed on the release runner for the target OS/architecture.
+if (!/^(darwin|linux|windows)-(arm64|x64)$/.test(target) || target !== hostTarget) {
+  throw new Error(`Build ${target} on a matching runner (current: ${hostTarget}).`);
+}
+const outputRoot = resolve(values.output ?? join(agentRoot, "dist", "releases"));
+const temporaryRoot = await mkdtemp(join(tmpdir(), "memmy-agent-runtime-"));
+try {
+  if (!values["skip-build"]) run("npm", ["run", "build"], agentRoot);
+  run(process.execPath, [join(agentRoot, "scripts", "build-npm-package.mjs")], agentRoot);
+  const source = join(temporaryRoot, "staged");
+  const packageRoot = join(source, "package");
+  await mkdir(source, { recursive: true });
+  await cp(join(agentRoot, "npm-packages", "memmy-agent"), packageRoot, { recursive: true });
+  run("npm", ["install", "--omit=dev", "--no-audit", "--no-fund"], packageRoot);
+  const destination = join(temporaryRoot, "bundled");
+  await bundleRuntime({ source, destination, packageDirectory: "package", kind: "agent", target: { platform: process.platform, arch: process.arch } });
+  const manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+  await writeJson(join(destination, "package", "agent-runtime.json"), {
+    name: "memmy-agent-runtime", version: manifest.version, formatVersion: 1, target,
+    entrypoint: "dist/main.js", nodeAbi: process.versions.modules
+  });
+  await mkdir(outputRoot, { recursive: true });
+  const name = `memmy-agent-runtime-${manifest.version}-${target}.tgz`;
+  const archive = join(outputRoot, name);
+  run("tar", ["-czf", archive, "-C", destination, "package"], agentRoot);
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(archive)) hash.update(chunk);
+  await writeJson(join(outputRoot, `agent-release-${target}.json`), {
+    version: manifest.version, assets: { [target]: { name, sha256: hash.digest("hex"), size: (await stat(archive)).size } }
+  });
+  console.log(archive);
+} finally {
+  await rm(temporaryRoot, { recursive: true, force: true });
+}
+
+function run(command, args, cwd) {
+  if (command === "npm") ({ command, args } = npmInvocation(args));
+  const result = spawnSync(command, args, { cwd, stdio: "inherit", env: { ...process.env, PATH: `${dirname(process.execPath)}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}` } });
+  if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} failed`);
+}
+
+async function writeJson(file, value) {
+  await writeFile(file, `${JSON.stringify(value, null, 2)}\n`);
+}
diff --git a/App/memmy-agent/src/runtime-main.ts b/App/memmy-agent/src/runtime-main.ts
new file mode 100644
index 000000000..5fc531d58
--- /dev/null
+++ b/App/memmy-agent/src/runtime-main.ts
@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import "./load-env.js";
+import { serve, runInternalCommand } from "./entrypoints/cli/commands.js";
+import { prepareStartupMigrations } from "./entrypoints/cli/startup-migrations.js";
+import { ConfigError } from "./config/loader.js";
+import { VERSION } from "./version.js";
+import { parseArgs } from "node:util";
+if (await runInternalCommand(process.argv)) {
+  // Preserve internal browser preparation without bringing in gateway/onboarding.
+} else if (["-V", "--version"].includes(process.argv[2])) console.log(VERSION);
+else {
+  const args = process.argv.slice(2);
+  if (args[0] === "serve") args.shift();
+  const { values } = parseArgs({
+    args,
+    options: {
+      port: { type: "string", short: "p" },
+      host: { type: "string", short: "H" },
+      timeout: { type: "string", short: "t" },
+      workspace: { type: "string", short: "w" },
+      config: { type: "string", short: "c" },
+      verbose: { type: "boolean", short: "v" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+  if (values.help)
+    console.log(
+      "Usage: memmy serve [--host HOST] [--port PORT] [--config FILE] [--workspace DIR] [--timeout SECONDS] [--verbose]",
+    );
+  else
+    try {
+      await prepareStartupMigrations(values);
+      await serve(values);
+    } catch (error) {
+      if (!(error instanceof ConfigError)) throw error;
+      console.error("memmy: " + error.message);
+      process.exitCode = 1;
+    }
+}
diff --git a/Memory/src/cli/scripts/build-runtime.mjs b/Memory/src/cli/scripts/build-runtime.mjs
index cafdede24..0aa3f607d 100755
--- a/Memory/src/cli/scripts/build-runtime.mjs
+++ b/Memory/src/cli/scripts/build-runtime.mjs
@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { npmInvocation } from "../../../../scripts/internal/shared/npm-invocation.mjs";
 import { createHash } from "node:crypto";
 import { createReadStream, existsSync } from "node:fs";
 import { cp, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
@@ -7,6 +8,7 @@ import { basename, dirname, join, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
+import { bundleRuntime } from "../../../../scripts/internal/shared/bundle-runtime.mjs";
 
 const require = createRequire(import.meta.url);
 const scriptDir = dirname(fileURLToPath(import.meta.url));
@@ -65,9 +67,15 @@ try {
     builtAt: new Date().toISOString()
   });
 
+  const bundledRoot = join(temporaryRoot, "bundled");
+  await bundleRuntime({ source: runtimeRoot, destination: bundledRoot, packageDirectory: ".", kind: "memory", target: { platform, arch } });
+  // Workspace code is in the bundle now; native libraries and model files remain external.
+  await verifyRuntimeDependencies(bundledRoot, target, platform, arch, []);
+  if (process.env.MEMMY_MEMORY_SKIP_EMBEDDING_MODEL !== "1") await verifyEmbeddingModel(bundledRoot);
+
   await mkdir(outputRoot, { recursive: true });
   const assetPath = join(outputRoot, assetName);
-  run("tar", ["-czf", assetPath, "-C", runtimeRoot, "."], repositoryRoot);
+  run("tar", ["-czf", assetPath, "-C", bundledRoot, "."], repositoryRoot);
   const descriptor = { name: assetName, sha256: await sha256File(assetPath), size: (await stat(assetPath)).size };
   await updateReleaseManifest(outputRoot, version, target, descriptor);
   process.stdout.write(`${assetPath}\n`);
@@ -113,7 +121,8 @@ function npmPlatformFlags(platform, arch) {
 }
 
 function run(command, args, cwd) {
-  const result = spawnSync(command, args, { cwd, stdio: "inherit", env: process.env, shell: process.platform === "win32" });
+  if (command === "npm") ({ command, args } = npmInvocation(args));
+  const result = spawnSync(command, args, { cwd, stdio: "inherit", env: process.env });
   if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} failed`);
 }
 
diff --git a/package-lock.json b/package-lock.json
index b7319fd43..97cebb149 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -25,6 +25,7 @@
         "@vitest/coverage-v8": "^4.1.7",
         "concurrently": "^9.2.1",
         "dotenv": "^16.6.1",
+        "esbuild": "0.28.2",
         "eslint": "^9.39.4",
         "eslint-import-resolver-typescript": "^4.4.4",
         "eslint-plugin-import": "^2.32.0",
diff --git a/package.json b/package.json
index 84acc6884..0075fd2ed 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,7 @@
     "typecheck": "npm run memory:lint && npm run workspace:typecheck",
     "test": "npm run test:release-workflow && npm run test:packaging-guards && npm run test:contracts && npm run memory:test && npm run workspace:test && npm run agent:test:tui-cursor",
     "test:release-workflow": "vitest run tests/release-workflow.test.ts tests/oss-crc64.test.mjs tests/windows-memory-workflow.test.ts",
-    "test:packaging-guards": "vitest run tests/package-version-guard.test.mjs tests/packaged-runtime-config.test.mjs tests/open-computer-use-packaging.test.mjs tests/computer-history-packaging.test.mjs tests/prune-packaged-runtime.test.mjs tests/package-logging.test.mjs",
+    "test:packaging-guards": "vitest run tests/package-version-guard.test.mjs tests/packaged-runtime-config.test.mjs tests/open-computer-use-packaging.test.mjs tests/computer-history-packaging.test.mjs tests/prune-packaged-runtime.test.mjs tests/package-logging.test.mjs tests/runtime-bundle.test.ts",
     "test:linux-cli": "vitest run tests/linux-cli-packaging.test.mjs tests/linux-open-computer-use-bundle.test.mjs tests/linux-computer-use-deps.test.mjs && npm --prefix App/memmy-agent exec vitest run tests/entrypoints/cli/linux-systemd-gateway.test.ts tests/entrypoints/cli/gateway-lifecycle.test.ts tests/entrypoints/cli/root-terminal-options.test.ts tests/entrypoints/cli/terminal-target.test.ts tests/tools/computer-use/mac-permission-settings.test.ts tests/tools/computer-use/mac-permission-preflight.test.ts && npm --prefix Memory test -- tests/cli-setup.test.ts",
     "serve": "npm run memory:serve",
     "serve:local": "npm run memory:serve:local",
@@ -57,6 +57,7 @@
     "memory:runtime:package": "npm run runtime:package -w @memmy/memory",
     "agent:package": "npm --prefix App/memmy-agent run package:npm",
     "agent:pack": "npm --prefix App/memmy-agent run pack:npm",
+    "agent:runtime:package": "node App/memmy-agent/scripts/build-runtime.mjs",
     "memory:dev": "npm run dev -w @memmy/memory",
     "memory:serve": "npm run serve -w @memmy/memory",
     "memory:serve:local": "npm run serve:local -w @memmy/memory",
@@ -89,6 +90,7 @@
     "@vitest/coverage-v8": "^4.1.7",
     "concurrently": "^9.2.1",
     "dotenv": "^16.6.1",
+    "esbuild": "0.28.2",
     "eslint": "^9.39.4",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
diff --git a/scripts/internal/shared/bundle-runtime.mjs b/scripts/internal/shared/bundle-runtime.mjs
new file mode 100644
index 000000000..ff63bac8a
--- /dev/null
+++ b/scripts/internal/shared/bundle-runtime.mjs
@@ -0,0 +1,183 @@
+import { builtinModules } from "node:module";
+import { existsSync } from "node:fs";
+import { copyFile, cp, mkdir, readFile, readdir, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { build, transform } from "esbuild";
+import { includeRuntimePath } from "./runtime-payload.mjs";
+
+// These packages load native binaries, workers, or assets relative to their own files.
+const EXTERNAL_PACKAGES = new Set([
+  "better-sqlite3", "tiktoken", "sqlite-vec", "@huggingface/transformers",
+  "playwright", "playwright-core", "@playwright/mcp", "open-computer-use",
+  "pdfjs-dist", "typescript", "html-validate", "@tencent-connect/openclaw-qqbot",
+  "ink", "@mistralai/mistralai", "isomorphic-git", "commander", "nunjucks",
+  "iconv-lite", "glob", "@discordjs/ws", "thread-stream", "pino",
+  "@larksuiteoapi/node-sdk", "@matrix-org/matrix-sdk-crypto-wasm", "open", "botbuilder", "jsonc-parser"
+]);
+const BUILTINS = new Set(builtinModules.flatMap((name) => [name, `node:${name}`]));
+const packageName = (specifier) => specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
+const posix = (value) => value.split(path.sep).join("/");
+
+
+function inside(root, file) {
+  const relative = path.relative(root, file);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Runtime file escapes its staging directory: ${file}`);
+  }
+  return relative;
+}
+
+function findPackage(name, directory, root) {
+  for (let current = directory; ; current = path.dirname(current)) {
+    const candidate = path.join(current, "node_modules", ...name.split("/"));
+    if (existsSync(path.join(candidate, "package.json"))) return candidate;
+    if (current === root || path.dirname(current) === current) return undefined;
+  }
+}
+
+// Keep entry paths for subprocesses and dynamic imports, but share bundled dependencies.
+export async function bundleRuntime({ source, destination, packageDirectory, kind, target = {} }) {
+  source = await realpath(source);
+  destination = path.resolve(destination);
+  const separation = path.relative(source, destination);
+  if (!separation || (!separation.startsWith(`..${path.sep}`) && separation !== ".." && !path.isAbsolute(separation))) {
+    throw new Error("Runtime destination must be outside the staging directory.");
+  }
+  const packageRoot = path.join(source, packageDirectory);
+  inside(source, packageRoot);
+  const manifest = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+  const codeRoot = path.join(packageRoot, "dist");
+  const outputRoot = path.join(destination, packageDirectory, "dist");
+  const entryPoints = [];
+  const assets = [];
+  const externalRoots = new Set();
+  const moduleUrls = new Map();
+  const externalPaths = new Map();
+  const copyOptions = { ...target, prune: true };
+
+  const collect = async (directory) => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const file = path.join(directory, entry.name);
+      const relative = posix(path.relative(packageRoot, file));
+      if (!includeRuntimePath(relative, copyOptions) || entry.name === "node_modules" || entry.name === "vendor" || entry.name === "package-lock.json") continue;
+      if (entry.isDirectory()) await collect(file);
+      else if (entry.isFile()) {
+        const code = path.relative(codeRoot, file);
+        // Skills and integration templates contain programs emitted as data, not server modules.
+        if (file.endsWith(".js") && !code.startsWith("..") && !/(?:^|\/)(?:skills|viewer|templates)(?:\/|$)/u.test(posix(code))) {
+          const entry = posix(code);
+          if (kind === "agent" ? entry === "runtime-main.js" || /^tools\/(?:computer-history\/mac\/(?:record-human-history|summarize-history)|computer-use\/extract-workflow-candidate)\.js$/u.test(entry)
+            : ["src/server/index.js", "src/cli/index.js"].includes(entry)) entryPoints.push({ in: file, out: kind === "agent" && entry === "runtime-main.js" ? "main" : entry.slice(0, -3) });
+        }
+        else if (!file.endsWith(".map") && !/\.d\.[cm]?ts$/u.test(file)) assets.push(file);
+      }
+    }
+  };
+  // Runtime assets live here; src, vendor tarballs and build projects are not shipped.
+  for (const directory of ["dist", ...(kind === "memory" ? ["embedding-models", "adapters"] : [])]) {
+    const directoryPath = path.join(packageRoot, directory);
+    if (existsSync(directoryPath)) await collect(directoryPath);
+  }
+  if (!entryPoints.length) throw new Error(`No compiled ${kind} runtime entrypoints in ${codeRoot}.`);
+
+  // These modules are resolved by strings passed to workers or child processes.
+  const dynamicPackages = kind === "agent" ? ["isomorphic-git", "@playwright/mcp", "open-computer-use"] : [];
+  for (const name of dynamicPackages) {
+    const directory = findPackage(name, packageRoot, source);
+    if (!directory) throw new Error(`Missing dynamic runtime dependency: ${name}`);
+    externalRoots.add(directory);
+  }
+
+  const result = await build({
+    entryPoints, outdir: outputRoot, outbase: codeRoot, entryNames: "[dir]/[name]",
+    chunkNames: "_chunks/[name]-[hash]", bundle: true, splitting: true,
+    platform: "node", target: "node22", format: "esm", keepNames: true,
+    write: false, metafile: true, logLevel: "silent", charset: "utf8",
+    banner: { js: 'import { createRequire as __memmyCreateRequire } from "node:module"; import { fileURLToPath as __memmyFileURLToPath } from "node:url"; const require = __memmyCreateRequire(import.meta.url);' },
+    plugins: [{ name: "runtime-layout", setup(builder) {
+      builder.onResolve({ filter: /^[^./]|^@/ }, async (args) => {
+        if (args.pluginData?.runtimeResolved || BUILTINS.has(args.path) || !EXTERNAL_PACKAGES.has(packageName(args.path))) return;
+        const resolved = await builder.resolve(args.path, { resolveDir: args.resolveDir, kind: args.kind, pluginData: { runtimeResolved: true } });
+        if (resolved.errors.length) return { errors: resolved.errors };
+        const directory = findPackage(packageName(args.path), args.resolveDir, source);
+        if (!directory) throw new Error(`Cannot locate external runtime dependency: ${args.path}`);
+        inside(source, resolved.path);
+        externalPaths.set(resolved.path, { directory, relocated: path.join(destination, path.relative(source, resolved.path)) });
+        return { path: resolved.path, external: true };
+      });
+      builder.onLoad({ filter: /\.[cm]?js$/ }, async (args) => {
+        if (!args.path.startsWith(`${packageRoot}${path.sep}`) || path.relative(packageRoot, args.path).split(path.sep).includes("node_modules")) return;
+        const contents = await readFile(args.path, "utf8");
+        if (!contents.includes("import.meta.url")) return { contents, loader: "js", resolveDir: path.dirname(args.path) };
+        const marker = `memmy-module:${posix(path.relative(source, args.path))}`;
+        moduleUrls.set(marker, path.join(destination, path.relative(source, args.path)));
+        const transformed = await transform(contents, { loader: "js", target: "node22", define: { "import.meta.url": JSON.stringify(marker) } });
+        return { contents: transformed.code, loader: "js", resolveDir: path.dirname(args.path) };
+      });
+    } }]
+  });
+
+  for (const file of result.outputFiles) {
+    let contents = file.text;
+    for (const [marker, original] of moduleUrls) {
+      const relative = posix(path.relative(path.dirname(file.path), original)).split("/").map(encodeURIComponent).join("/");
+      contents = contents.replaceAll(JSON.stringify(marker), `new URL(${JSON.stringify(relative)}, import.meta.url).href`);
+    }
+    for (const [original, { relocated }] of externalPaths) {
+      let relative = posix(path.relative(path.dirname(file.path), relocated));
+      if (!relative.startsWith(".")) relative = `./${relative}`;
+      relative = relative.split("/").map(encodeURIComponent).join("/");
+      // esbuild shares its CJS require helper between chunks; resolve from the caller.
+      contents = contents.replaceAll(`__require(${JSON.stringify(original)})`, `__require(__memmyFileURLToPath(new URL(${JSON.stringify(relative)}, import.meta.url)))`);
+      contents = contents.replaceAll(JSON.stringify(original), JSON.stringify(relative));
+    }
+    await mkdir(path.dirname(file.path), { recursive: true });
+    await writeFile(file.path, contents);
+  }
+  if (kind === "memory" && existsSync(path.join(packageRoot, "memory-runtime.json"))) assets.push(path.join(packageRoot, "memory-runtime.json"));
+  for (const file of assets) {
+    const output = path.join(destination, inside(source, file));
+    await mkdir(path.dirname(output), { recursive: true });
+    await copyFile(file, output);
+  }
+  // This is a launchable runtime, not the original SDK/development npm package.
+  const runtimeManifest = Object.fromEntries(["name", "version", "type", "bin", "engines", "license"].filter((key) => manifest[key] !== undefined).map((key) => [key, manifest[key]]));
+  await writeFile(path.join(destination, packageDirectory, "package.json"), `${JSON.stringify({ ...runtimeManifest, private: true }, null, 2)}\n`);
+
+  const copied = new Set();
+  const copyPackage = async (directory) => {
+    inside(source, await realpath(directory));
+    if (copied.has(directory)) return;
+    copied.add(directory);
+    const manifest = JSON.parse(await readFile(path.join(directory, "package.json"), "utf8"));
+    await cp(directory, path.join(destination, inside(source, directory)), {
+      recursive: true, dereference: true,
+      filter: (file) => {
+        const relative = path.relative(directory, file);
+        return !relative.split(path.sep).includes("node_modules") && includeRuntimePath(path.relative(source, file), copyOptions);
+      }
+    });
+    const optional = { ...manifest.optionalDependencies, ...manifest.peerDependencies };
+    for (const name of new Set([...Object.keys(manifest.dependencies ?? {}), ...Object.keys(optional)])) {
+      const dependency = findPackage(name, directory, source);
+      if (dependency) await copyPackage(dependency);
+      else if (!Object.hasOwn(optional, name)) throw new Error(`Missing runtime dependency ${name} required by ${manifest.name}.`);
+    }
+  };
+  for (const output of Object.values(result.metafile.outputs)) {
+    for (const imported of output.imports) {
+      const external = externalPaths.get(imported.path);
+      if (external) externalRoots.add(external.directory);
+    }
+  }
+  for (const directory of externalRoots) await copyPackage(directory);
+  // Keep installed optional modules referenced from bundled code (e.g. ws native accelerators).
+  for (const output of Object.values(result.metafile.outputs)) {
+    for (const imported of output.imports) {
+      if (!imported.external || BUILTINS.has(imported.path) || path.isAbsolute(imported.path)) continue;
+      const directory = findPackage(packageName(imported.path), packageRoot, source);
+      if (directory) await copyPackage(directory);
+    }
+  }
+  return { modules: Object.keys(result.metafile.inputs).length, bundles: result.outputFiles.length, externalPackages: copied.size };
+}
diff --git a/scripts/internal/shared/npm-invocation.mjs b/scripts/internal/shared/npm-invocation.mjs
new file mode 100644
index 000000000..cb38c0c88
--- /dev/null
+++ b/scripts/internal/shared/npm-invocation.mjs
@@ -0,0 +1,15 @@
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+// Invoke npm through Node so Windows never passes package paths through cmd.exe.
+export function npmInvocation(args, { execPath = process.execPath, env = process.env, platform = process.platform } = {}) {
+  const candidates = [
+    env.npm_execpath && basename(env.npm_execpath) === "npm-cli.js" ? env.npm_execpath : undefined,
+    join(dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js"),
+    resolve(dirname(execPath), "../lib/node_modules/npm/bin/npm-cli.js")
+  ];
+  const cli = candidates.find((file) => file && existsSync(file));
+  if (cli) return { command: execPath, args: [cli, ...args] };
+  if (platform === "win32") throw new Error("Cannot locate npm-cli.js; run packaging with a Node installation that includes npm.");
+  return { command: "npm", args };
+}
diff --git a/scripts/internal/shared/runtime-payload.mjs b/scripts/internal/shared/runtime-payload.mjs
new file mode 100644
index 000000000..77bbe6161
--- /dev/null
+++ b/scripts/internal/shared/runtime-payload.mjs
@@ -0,0 +1,85 @@
+import path from "node:path";
+
+// `doc` and `docs` are not skipped: the yaml package loads dist/doc/*.js at runtime.
+const NON_RUNTIME_DIR = /^(?:test|tests|__tests__|__mocks__|example|examples|\.github|coverage|benchmark|benchmarks)$/i;
+const NON_RUNTIME_DOC = /^(?:readme|changelog|history|contributing|code_of_conduct|security)(?:\.[a-z0-9]+)?$/i;
+const NON_RUNTIME_FILE = /\.(?:map|d\.ts|d\.mts|d\.cts|ts|tsx|mts|cts|scss|sass|less|flow|tsbuildinfo|c|cc|cpp|h|hpp)$/i;
+const NATIVE_PACKAGE = /(?:^|[-.])(darwin|linux|win32|windows|android|freebsd|openbsd)[-.](x64|arm64|ia32|arm|armv7l|universal|x86|mips64el|ppc64|s390x)(?:[-.](?:gnu|musl|msvc|eabi))?$/i;
+
+const packageTarget = (options = {}) => {
+  const raw = options.platform ?? process.platform;
+  const platform = raw === "mas" || raw === "darwin" ? "darwin" : raw === "windows" ? "win32" : raw;
+  return { platform, arch: options.arch ?? process.arch };
+};
+
+const isForeignNativeName = (name, target) => {
+  const matched = NATIVE_PACKAGE.exec(name);
+  if (!matched) return false;
+  const platform = matched[1].toLowerCase() === "windows" ? "win32" : matched[1].toLowerCase();
+  return platform !== target.platform || matched[2].toLowerCase() !== target.arch;
+};
+
+const shouldOmitPackagedDirectory = (relative, target) => {
+  if (omitPackagedPayload(relative)) return true;
+  const parts = String(relative).replaceAll("\\", "/").split("/").filter(Boolean);
+  if (parts.some((part) => NON_RUNTIME_DIR.test(part) || isForeignNativeName(part, target))) return true;
+  const napi = parts.indexOf("napi-v3");
+  if (napi < 0 || !parts[napi + 1]) return false;
+  const platform = parts[napi + 1].toLowerCase();
+  const arch = (parts[napi + 2] ?? "").toLowerCase();
+  if (["darwin", "linux", "win32"].includes(platform) && platform !== target.platform) return true;
+  return ["x64", "arm64", "ia32"].includes(arch) && arch !== target.arch;
+};
+
+const omitNonRuntimePackagedRelative = (relative, options = {}) => {
+  const target = packageTarget(options);
+  const normalized = String(relative).replaceAll("\\", "/");
+  if (shouldOmitPackagedDirectory(normalized, target)) return true;
+  const name = path.posix.basename(normalized);
+  if (NON_RUNTIME_DOC.test(name) || NON_RUNTIME_FILE.test(name)) return true;
+  if (shouldOmitPackagedDirectory(path.posix.dirname(normalized), target)) return true;
+  const extension = path.posix.extname(name).toLowerCase();
+  if (target.platform === "win32" && (extension === ".dylib" || extension === ".so")) return true;
+  if (target.platform === "darwin" && (extension === ".dll" || extension === ".exe")) return true;
+  if (target.platform === "linux" && (extension === ".dylib" || extension === ".dll" || extension === ".exe")) return true;
+  return false;
+};
+
+// Installer payload that the Node runtime does not load.
+function omitPackagedPayload(relative) {
+  const parts = String(relative ?? "").replaceAll("\\", "/").split("/").filter(Boolean);
+  if (parts.length === 0) return false;
+  const web = parts.indexOf("onnxruntime-web");
+  if (web > 0 && parts[web - 1] === "node_modules") return true;
+  const openclaw = parts.indexOf("openclaw");
+  // yaml loads dist/doc/*.js. Only the OpenClaw documentation tree is unused.
+  if (openclaw >= 0 && parts[openclaw + 1] === "docs") return true;
+  const sqlite = parts.lastIndexOf("better-sqlite3");
+  if (sqlite > 0 && parts[sqlite - 1] === "node_modules") {
+    const rest = parts.slice(sqlite + 1).join("/");
+    if (rest === "" || rest === "package.json" || rest === "lib" || rest.startsWith("lib/")) return false;
+    if (rest === "build" || rest === "build/Release" || rest === "build/Release/better_sqlite3.node") return false;
+    if (rest === "deps" || rest.startsWith("deps/") || rest === "src" || rest.startsWith("src/") || rest.startsWith("build/")) return true;
+  }
+  const tiktoken = parts.lastIndexOf("tiktoken");
+  if (tiktoken > 0 && parts[tiktoken - 1] === "node_modules") {
+    const child = parts[tiktoken + 1];
+    // get_encoding() reads ranks from tiktoken_bg.wasm, not encoders/ or lite/.
+    if (child === "encoders" || child === "lite") return true;
+  }
+  if (parts.at(-2) === "dist" && parts.at(-3) === "transformers" && parts.at(-4) === "@huggingface" && parts.at(-5) === "node_modules") {
+    const file = parts.at(-1);
+    if (file.endsWith(".map") || file.endsWith(".wasm")) return true;
+    // Node resolves transformers.node.*; the browser bundles and their wasm are unused.
+    if (/^transformers(?!\.node\.)/u.test(file)) return true;
+  }
+  return false;
+}
+
+export function includeRuntimePath(relative, options = {}) {
+  const normalized = String(relative).replaceAll("\\", "/");
+  const parts = normalized.split("/");
+  if (parts.some((part) => part === ".git" || part === ".DS_Store" || part === "__MACOSX" || part.startsWith("._"))) return false;
+  if (["package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml"].includes(parts.at(-1))) return false;
+  return !omitNonRuntimePackagedRelative(normalized, options);
+}
diff --git a/tests/runtime-bundle.test.ts b/tests/runtime-bundle.test.ts
new file mode 100644
index 000000000..fac9ddf4a
--- /dev/null
+++ b/tests/runtime-bundle.test.ts
@@ -0,0 +1,124 @@
+import { execFileSync } from "node:child_process";
+import { mkdtemp, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { bundleRuntime } from "../scripts/internal/shared/bundle-runtime.mjs";
+
+const roots: string[] = [];
+afterEach(async () => { for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }); });
+async function fixture() {
+  const root = await mkdtemp(path.join(os.tmpdir(), "runtime bundle #"));
+  roots.push(root);
+  const source = path.join(root, "source");
+  const put = async (file: string, contents: string) => {
+    const target = path.join(source, file);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, contents);
+  };
+  return { root, source, put, destination: path.join(root, "output") };
+}
+
+it("runs relocated Memory entries without staging, retaining resources and exact external dependency versions", async () => {
+  const { root, source, destination, put } = await fixture();
+  await put("package/package.json", JSON.stringify({ type: "module" }));
+  await put("package/dist/src/server/index.js", `import { readFileSync } from 'node:fs';
+    import value from 'demo'; import sqlite from 'better-sqlite3';
+    console.log(JSON.stringify([value, sqlite, readFileSync(new URL('./message%20%231.txt', import.meta.url), 'utf8')]));`);
+  await put("package/dist/src/server/message #1.txt", "asset");
+  await put("package/dist/src/cli/index.js", `import value from 'demo'; console.log(value);`);
+  await put("package/node_modules/demo/package.json", JSON.stringify({ name: "demo", main: "index.cjs" }));
+  await put("package/node_modules/demo/index.cjs", `module.exports = require('glob');`);
+  await put("package/node_modules/demo/node_modules/glob/package.json", JSON.stringify({ name: "glob", main: "index.cjs" }));
+  await put("package/node_modules/demo/node_modules/glob/index.cjs", `module.exports = 'nested-version';`);
+  await put("package/node_modules/glob/package.json", JSON.stringify({ name: "glob", main: "index.cjs" }));
+  await put("package/node_modules/glob/index.cjs", `module.exports = 'wrong-version';`);
+  await put("package/node_modules/better-sqlite3/package.json", JSON.stringify({ name: "better-sqlite3", main: "lib/index.cjs", dependencies: { helper: "1" } }));
+  await put("package/node_modules/better-sqlite3/lib/index.cjs", `module.exports = require('helper');`);
+  await put("package/node_modules/helper/package.json", JSON.stringify({ name: "helper", main: "index.cjs" }));
+  await put("package/node_modules/helper/index.cjs", `module.exports = 'external-dependency';`);
+  await put("package/node_modules/better-sqlite3/build/Release/better_sqlite3.node", "native-fixture");
+  await put("package/node_modules/unused/index.js", "unused");
+  await put("package/src/server.ts", "source-only");
+  await put("package/dist/src/server/index.js.map", "{}");
+  await bundleRuntime({ source, destination, packageDirectory: "package", kind: "memory" });
+  const relocated = path.join(root, "relocated # runtime");
+  await rename(destination, relocated);
+  await rm(source, { recursive: true });
+  const run = (entry: string) => execFileSync(process.execPath, [path.join(relocated, "package/dist/src", entry)], { encoding: "utf8" }).trim();
+  expect(JSON.parse(run("server/index.js"))).toEqual(["nested-version", "external-dependency", "asset"]);
+  expect(run("cli/index.js")).toBe("nested-version");
+  await expect(readFile(path.join(relocated, "package/node_modules/better-sqlite3/build/Release/better_sqlite3.node"), "utf8")).resolves.toBe("native-fixture");
+  for (const file of ["src/server.ts", "node_modules/unused/index.js", "node_modules/demo/index.cjs", "dist/src/server/index.js.map"]) {
+    await expect(readFile(path.join(relocated, "package", file))).rejects.toThrow();
+  }
+});
+
+it("packages the Agent serve entry and its dynamic tools without the standalone gateway", async () => {
+  const { source, destination, put } = await fixture();
+  const pkg = "node_modules/@memtensor/memmy-agent";
+  await put(`${pkg}/package.json`, JSON.stringify({ type: "module", bin: { memmy: "dist/main.js" } }));
+  await put(`${pkg}/dist/runtime-main.js`, await readFile(new URL("../App/memmy-agent/src/runtime-main.ts", import.meta.url), "utf8"));
+  await put(`${pkg}/dist/main.js`, `throw new Error('standalone CLI must not run');`);
+  await put(`${pkg}/dist/load-env.js`, "export {};");
+  await put(`${pkg}/dist/config/loader.js`, "export class ConfigError extends Error {}");
+  await put(`${pkg}/dist/version.js`, `export const VERSION = '1.2.1';`);
+  await put(`${pkg}/dist/entrypoints/cli/startup-migrations.js`, `export async function prepareStartupMigrations() { globalThis.migrationsReady = true; }`);
+  await put(`${pkg}/dist/entrypoints/cli/commands.js`, `export async function serve(options) { if (!globalThis.migrationsReady) throw new Error('Migrations skipped'); console.log(JSON.stringify(options)); }
+    export async function runInternalCommand(argv) { if (argv[2] === 'internal') { console.log('browser-prepare'); return true; } return false; }
+    export async function gateway() { return import('unused-gateway'); }`);
+  await put(`${pkg}/node_modules/unused-gateway/package.json`, JSON.stringify({ main: "index.js" }));
+  await put(`${pkg}/node_modules/unused-gateway/index.js`, `throw new Error('unused gateway');`);
+  for (const name of ["isomorphic-git", "@playwright/mcp", "open-computer-use"]) {
+    await put(`${pkg}/node_modules/${name}/package.json`, JSON.stringify({ name, main: "index.js" }));
+    await put(`${pkg}/node_modules/${name}/index.js`, `module.exports = ${JSON.stringify(name)};`);
+  }
+  await bundleRuntime({ source, destination, packageDirectory: pkg, kind: "agent" });
+  await rm(source, { recursive: true });
+  const output = execFileSync(process.execPath, [path.join(destination, pkg, "dist/main.js"), "serve", "--config", "config.json", "-t", "30"], { encoding: "utf8" });
+  expect(JSON.parse(output)).toEqual({ config: "config.json", timeout: "30" });
+  expect(execFileSync(process.execPath, [path.join(destination, pkg, "dist/main.js"), "internal", "browser-prepare"], { encoding: "utf8" }).trim()).toBe("browser-prepare");
+  expect(execFileSync(process.execPath, [path.join(destination, pkg, "dist/main.js"), "--version"], { encoding: "utf8" }).trim()).toBe("1.2.1");
+  await expect(readFile(path.join(destination, pkg, "node_modules/@playwright/mcp/index.js"), "utf8")).resolves.toContain("@playwright/mcp");
+  await expect(readFile(path.join(destination, pkg, "node_modules/unused-gateway/index.js"))).rejects.toThrow();
+});
+
+it("fails packaging when an external package's required dependency is missing", async () => {
+  const { source, destination, put } = await fixture();
+  await put("package/package.json", JSON.stringify({ type: "module" }));
+  await put("package/dist/src/server/index.js", `import sqlite from 'better-sqlite3'; console.log(sqlite);`);
+  await put("package/node_modules/better-sqlite3/package.json", JSON.stringify({ main: "lib/index.js", dependencies: { missing: "1" } }));
+  await put("package/node_modules/better-sqlite3/lib/index.js", `module.exports = require('missing');`);
+  await expect(bundleRuntime({ source, destination, packageDirectory: "package", kind: "memory" })).rejects.toThrow("Missing runtime dependency missing");
+});
+
+it("keeps native runtime assets for Windows while excluding build material", async () => {
+  const { includeRuntimePath } = await import("../scripts/internal/shared/runtime-payload.mjs");
+  const target = { platform: "windows", arch: "x64" };
+  for (const file of [
+    "node_modules/yaml/dist/doc/Document.js",
+    "node_modules/better-sqlite3/build/Release/better_sqlite3.node",
+    "node_modules/onnxruntime-node/bin/napi-v3/win32/x64/onnxruntime.dll",
+    "node_modules/tiktoken/tiktoken_bg.wasm",
+    "dist/skills/computer-history/SKILL.md"
+  ]) expect(includeRuntimePath(file, target), file).toBe(true);
+  for (const file of [
+    "node_modules/better-sqlite3/build/Release/obj/better_sqlite3.o",
+    "node_modules/onnxruntime-node/bin/napi-v3/darwin/arm64/onnxruntime_binding.node",
+    "node_modules/sqlite-vec-windows-arm64/vec0.dll",
+    "node_modules/demo/tests/test.js",
+    "dist/main.js.map", "dist/main.d.ts", "package-lock.json"
+  ]) expect(includeRuntimePath(file, target), file).toBe(false);
+});
+
+
+it("invokes Windows npm with Node and preserves paths containing spaces", async () => {
+  const { root } = await fixture();
+  const { npmInvocation } = await import("../scripts/internal/shared/npm-invocation.mjs");
+  const executable = path.join(root, "Program Files", "node.exe");
+  const cli = path.join(root, "Program Files", "node_modules/npm/bin/npm-cli.js");
+  await mkdir(path.dirname(cli), { recursive: true });
+  await writeFile(cli, "");
+  const args = ["pack", "C:\\Users\\Name With Spaces\\package"];
+  expect(npmInvocation(args, { execPath: executable, env: {}, platform: "win32" })).toEqual({ command: executable, args: [cli, ...args] });
+});

From 248bbafab8e147790e940903a1a158490e56c103 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Sat, 10 Oct 2026 10:52:11 +0800
Subject: [PATCH 36/85] fix: deduplicate native source captures across account
 changes

---
 .../service/session/session-turn-service.ts   | 16 +++-
 Memory/src/storage/polardb.ts                 |  8 ++
 Memory/src/storage/repositories.ts            | 15 ++--
 Memory/src/storage/schema.ts                  |  8 ++
 .../tests/contract/source-turn-http.test.ts   | 24 +++---
 Memory/tests/native-scanner-lifecycle.test.ts |  8 +-
 .../repository/source-turn-schema.test.ts     | 21 +++++-
 .../session/source-turn-capture.test.ts       | 75 ++++++++++++++++++-
 8 files changed, 147 insertions(+), 28 deletions(-)

diff --git a/Memory/src/service/session/session-turn-service.ts b/Memory/src/service/session/session-turn-service.ts
index 181d12d5d..811771711 100644
--- a/Memory/src/service/session/session-turn-service.ts
+++ b/Memory/src/service/session/session-turn-service.ts
@@ -1261,8 +1261,8 @@ export class SessionTurnService {
       toolCalls: normalizeCompleteTurnToolCalls(normalized), toolResults: normalizeCompleteTurnToolResults(normalized)
     });
     return this.deps.repos.transaction(() => {
-      // A durable source identity is checked before touching an open Session. Deleted memories
-      // and closed Sessions therefore cannot turn a retry into a second capture.
+      // Native captures belong to the local source conversation, not the cloud account
+      // currently sending them. Check before opening a Session or scheduling any work.
       const existing = this.deps.repos.runtime.getSourceTurnCapture(scope, identity.turnId);
       if (existing) {
         if (existing.contentHash !== contentHash) {
@@ -1310,6 +1310,12 @@ export class SessionTurnService {
       const adoptedImport = this.adoptLegacyImport(request, namespace, normalized, scope, contentHash);
       if (adoptedImport) return adoptedImport;
       const previous = this.deps.repos.runtime.latestSourceTurnCapture(scope);
+      if (previous) {
+        namespace.userId = previous.userId;
+        scope.userId = previous.userId;
+      }
+      normalized.namespace = namespace;
+      request = { ...request, namespace };
       let gapEpisode: EpisodeRecord | undefined;
       let targetSessionId = previous?.sessionId;
       const legacyBackfill = allowsLegacyHistoryCapture(request);
@@ -1347,6 +1353,10 @@ export class SessionTurnService {
           : resolved;
       }
       const session = resolved as SessionRecord;
+      // A scan may be the first completion of a Hook Session opened by another account.
+      // Keep the Session owner and all persisted capture references consistent.
+      namespace.userId = session.userId;
+      scope.userId = session.userId;
       const observed = this.deps.repos.runtime.getRawTurnBySessionTurn(session.id, identity.turnId);
       if (observed && this.deps.repos.runtime.getEpisode(observed.episodeId)?.status !== "open") {
         return detachLegacyHistory("source_episode_closed");
@@ -1581,7 +1591,7 @@ export class SessionTurnService {
   ): SessionRecord | { status: "pending"; reason: string } {
     const namespace = normalizeNamespace(request.namespace);
     const inScope = (candidate: SessionRecord): boolean =>
-      candidate.userId === namespace.userId && candidate.source === identity.source && candidate.profileId === identity.profileId &&
+      candidate.source === identity.source && candidate.profileId === identity.profileId &&
       (!candidate.conversationId || candidate.conversationId === identity.conversationId) &&
       (candidate.hostSessionKey === identity.conversationId || candidate.conversationId === identity.conversationId ||
         candidate.hostSessionKey === `${identity.source}-memory-${identity.conversationId}`) &&
diff --git a/Memory/src/storage/polardb.ts b/Memory/src/storage/polardb.ts
index be44cd7e0..123e23918 100644
--- a/Memory/src/storage/polardb.ts
+++ b/Memory/src/storage/polardb.ts
@@ -336,6 +336,14 @@ export function polardbMigrationSql(): string[] {
   )`,
   `CREATE INDEX IF NOT EXISTS idx_source_turn_captures_conversation
     ON source_turn_captures (user_id, source, profile_id, namespace_key, conversation_id, completed_at DESC)`,
+  `CREATE INDEX IF NOT EXISTS idx_source_turn_captures_native_turn
+    ON source_turn_captures (source, profile_id, namespace_key, conversation_id, turn_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_source_turn_captures_native_conversation
+    ON source_turn_captures (source, profile_id, namespace_key, conversation_id, completed_at DESC)`,
+  `CREATE INDEX IF NOT EXISTS idx_source_sessions_native_conversation
+    ON sessions (source, profile_id, conversation_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_source_sessions_native_host_key
+    ON sessions (source, profile_id, host_session_key)`,
 
     `CREATE TABLE IF NOT EXISTS runtime_kv (
       key TEXT PRIMARY KEY,
diff --git a/Memory/src/storage/repositories.ts b/Memory/src/storage/repositories.ts
index dee1bb81f..d76fcd38b 100644
--- a/Memory/src/storage/repositories.ts
+++ b/Memory/src/storage/repositories.ts
@@ -1847,17 +1847,20 @@ export class RuntimeRepository {
     }));
   }
 
+  // userId is capture provenance. It must not partition the same local native turn
+  // when an installed Hook and the desktop scanner submit under different accounts.
   getSourceTurnCapture(scope: SourceTurnCaptureScope, turnId: string): SourceTurnCaptureRecord | undefined {
     const row = this.db.prepare(`SELECT * FROM source_turn_captures
-      WHERE user_id = @userId AND source = @source AND profile_id = @profileId
-        AND namespace_key = @namespaceKey AND conversation_id = @conversationId AND turn_id = @turnId`
+      WHERE source = @source AND profile_id = @profileId
+        AND namespace_key = @namespaceKey AND conversation_id = @conversationId AND turn_id = @turnId
+      ORDER BY created_at ASC, user_id ASC LIMIT 1`
     ).get({ ...scope, turnId }) as Record<string, unknown> | undefined;
     return row ? sourceTurnCaptureFromSql(row) : undefined;
   }
 
   latestSourceTurnCapture(scope: SourceTurnCaptureScope): SourceTurnCaptureRecord | undefined {
     const row = this.db.prepare(`SELECT * FROM source_turn_captures
-      WHERE user_id = @userId AND source = @source AND profile_id = @profileId
+      WHERE source = @source AND profile_id = @profileId
         AND namespace_key = @namespaceKey AND conversation_id = @conversationId AND session_id IS NOT NULL
       ORDER BY completed_at DESC, source_sequence DESC LIMIT 1`
     ).get(scope) as Record<string, unknown> | undefined;
@@ -1869,7 +1872,7 @@ export class RuntimeRepository {
     after?: SourceTurnCaptureRecord;
   } {
     const prefix = `SELECT * FROM source_turn_captures
-      WHERE user_id = @userId AND source = @source AND profile_id = @profileId
+      WHERE source = @source AND profile_id = @profileId
         AND namespace_key = @namespaceKey AND conversation_id = @conversationId AND session_id IS NOT NULL`;
     const before = this.db.prepare(`${prefix} AND started_at < @startedAt ORDER BY started_at DESC LIMIT 1`)
       .get({ ...scope, startedAt }) as Record<string, unknown> | undefined;
@@ -1906,8 +1909,8 @@ export class RuntimeRepository {
       .run(toJson(rawTurnIds), toJson(l1MemoryIds), episodeId);
   }
 
-  sourceConversationSessions(input: { userId: string; source: string; profileId: string; conversationId: string }): SessionRecord[] {
-    return (this.db.prepare(`SELECT * FROM sessions WHERE user_id = @userId AND source = @source
+  sourceConversationSessions(input: { userId?: string; source: string; profileId: string; conversationId: string }): SessionRecord[] {
+    return (this.db.prepare(`SELECT * FROM sessions WHERE source = @source
       AND profile_id = @profileId AND (host_session_key = @conversationId OR conversation_id = @conversationId
         OR host_session_key = @source || '-memory-' || @conversationId)
       ORDER BY opened_at DESC`).all(input) as SqlSessionRow[]).map(sessionFromSql);
diff --git a/Memory/src/storage/schema.ts b/Memory/src/storage/schema.ts
index 9755c4b92..3cb76e0c4 100644
--- a/Memory/src/storage/schema.ts
+++ b/Memory/src/storage/schema.ts
@@ -529,6 +529,14 @@ const statements = [
   )`,
   `CREATE INDEX IF NOT EXISTS idx_source_turn_captures_conversation
     ON source_turn_captures (user_id, source, profile_id, namespace_key, conversation_id, completed_at DESC)`,
+  `CREATE INDEX IF NOT EXISTS idx_source_turn_captures_native_turn
+    ON source_turn_captures (source, profile_id, namespace_key, conversation_id, turn_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_source_turn_captures_native_conversation
+    ON source_turn_captures (source, profile_id, namespace_key, conversation_id, completed_at DESC)`,
+  `CREATE INDEX IF NOT EXISTS idx_source_sessions_native_conversation
+    ON sessions (source, profile_id, conversation_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_source_sessions_native_host_key
+    ON sessions (source, profile_id, host_session_key)`,
 
   `CREATE TABLE IF NOT EXISTS memory_capture_claims (
     user_id TEXT NOT NULL,
diff --git a/Memory/tests/contract/source-turn-http.test.ts b/Memory/tests/contract/source-turn-http.test.ts
index 34f070f86..1ab9d8088 100644
--- a/Memory/tests/contract/source-turn-http.test.ts
+++ b/Memory/tests/contract/source-turn-http.test.ts
@@ -40,10 +40,10 @@ describe("source turn HTTP contract", () => {
     } finally { await new Promise<void>((resolve) => server.close(() => resolve())); }
   });
 
-  it.each(["hook", "agent_source_scan"] as const)("uses the configured local owner and existing Hook Session when %s arrives first", async (channel) => {
+  it.each(["hook", "agent_source_scan", "concurrent"] as const)("reuses the installed Hook owner after account switch when %s arrives first", async (channel) => {
     const { service, db } = createTestService({ config: { ...DEFAULT_MEMMY_CONFIG, userId: "configured-owner" } });
     const opened = service.openSession({
-      source: "codex", namespace: { source: "codex", profileId: "default", userId: "configured-owner", sessionKey: "codex-memory-local-conversation" },
+      source: "codex", namespace: { source: "codex", profileId: "default", userId: "installed-owner", sessionKey: "codex-memory-local-conversation" },
       l3WorldModelProtocolVersion: 2, l3WorldModelTransition: "allow_legacy_rollover",
       workspaceUri: "file:///fixture-project", workspaceHostId: "a".repeat(64)
     });
@@ -55,26 +55,30 @@ describe("source turn HTTP contract", () => {
       startedAt: "2099-01-01T10:00:00.000Z", completedAt: "2099-01-01T10:01:00.000Z", sequence: 1,
       completionEvidence: "final_answer:local-turn", query: "Fix the source capture user and Session identity.",
       answer: "The source capture reuses the existing user and Session identity.", status: "succeeded", toolCalls: [], toolResults: []
-    }, channel);
+    }, channel === "concurrent" ? "hook" : channel);
     const submit = async (source: "hook" | "agent_source_scan") => {
       const response = await fetch(`http://127.0.0.1:${address.port}/api/v1/source-turns/complete`, {
         method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ ...payload, channel: source,
-          ...(source === "hook" ? { sessionId: opened.sessionId, namespace: { userId: "configured-owner" } } : {}) })
+          ...(source === "hook" ? { sessionId: opened.sessionId, namespace: { userId: "installed-owner" } } : {}) })
       });
       expect(response.status).toBe(200);
       return response.json() as Promise<{ status: string; result: { sessionId: string; l1MemoryId: string } }>;
     };
     try {
-      const first = await submit(channel);
-      const second = await submit(channel === "hook" ? "agent_source_scan" : "hook");
-      expect(first.status).toBe("stored");
-      expect(second.status).toBe("existing");
+      const [first, second] = channel === "concurrent"
+        ? await Promise.all([submit("hook"), submit("agent_source_scan")])
+        : [await submit(channel), await submit(channel === "hook" ? "agent_source_scan" : "hook")];
+      expect([first.status, second.status].sort()).toEqual(["existing", "stored"]);
       expect(first.result.sessionId).toBe(opened.sessionId);
       expect(second.result.l1MemoryId).toBe(first.result.l1MemoryId);
       const repos = new Repositories(db.db);
-      expect(repos.memories.get(first.result.l1MemoryId)).toMatchObject({ userId: "configured-owner", sessionId: opened.sessionId,
+      expect(repos.memories.get(first.result.l1MemoryId)).toMatchObject({ userId: "installed-owner", sessionId: opened.sessionId,
         info: { project_id: repos.runtime.getSession(opened.sessionId)!.projectId } });
-      expect(db.db.prepare("SELECT COUNT(*) AS n FROM sessions").get()).toEqual({ n: 1 });
+      for (const table of ["sessions", "episodes", "raw_turns", "source_turn_captures"]) {
+        expect(db.db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get()).toEqual({ n: 1 });
+      }
+      expect(db.db.prepare("SELECT COUNT(*) AS n FROM memories WHERE memory_layer = 'L1'").get()).toEqual({ n: 1 });
+      expect(db.db.prepare("SELECT COUNT(*) AS n FROM evolution_jobs WHERE job_type = 'trace_summary'").get()).toEqual({ n: 1 });
     } finally { await new Promise<void>(resolve => server.close(() => resolve())); }
   });
 
diff --git a/Memory/tests/native-scanner-lifecycle.test.ts b/Memory/tests/native-scanner-lifecycle.test.ts
index e47fbaa18..b3a3a5a25 100644
--- a/Memory/tests/native-scanner-lifecycle.test.ts
+++ b/Memory/tests/native-scanner-lifecycle.test.ts
@@ -31,7 +31,7 @@ describe("Codex scan and Hook share the actual Memory lifecycle", () => {
     writeFileSync(path, records(true).map(record => JSON.stringify(record)).join("\n") + "\n");
     const messages: RawCodexMessage[] = []; for await (const value of readCodexRollout(path)) messages.push(value);
     const turn = sourceTurnFromMessages(messages)!;
-    const hook = () => service.completeSourceTurn({ ...buildSourceTurnRequest(turn, "hook"), namespace: { source: "codex", profileId: "default", userId: "scan-owner" } });
+    const hook = () => service.completeSourceTurn({ ...buildSourceTurnRequest(turn, "hook"), namespace: { source: "codex", profileId: "default", userId: "hook-owner" } });
     const add = vi.spyOn(service, "addMemory");
     const executor = createAgentSourceExecutor({ service, configPath: join(root, "config.yaml"),
       resolveAgentSkillRoot: () => null,
@@ -43,12 +43,12 @@ describe("Codex scan and Hook share the actual Memory lifecycle", () => {
       expect(executor.scanStatus().error).toBeNull();
       expect(hook().status).toBe("existing");
       expect(add).not.toHaveBeenCalled();
-      for (const table of ["raw_turns", "source_turn_captures"]) expect(db.db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get()).toEqual({ n: 1 });
+      for (const table of ["sessions", "episodes", "raw_turns", "source_turn_captures"]) expect(db.db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get()).toEqual({ n: 1 });
       expect(db.db.prepare("SELECT COUNT(*) AS n FROM memories WHERE memory_layer = 'L1'").get()).toEqual({ n: 1 });
       const captured = hook().result!;
       const repos = new Repositories(db.db);
-      expect(repos.runtime.getSession(captured.sessionId)?.userId).toBe("scan-owner");
-      expect(repos.memories.get(captured.l1MemoryId)?.userId).toBe("scan-owner");
+      expect(repos.runtime.getSession(captured.sessionId)?.userId).toBe(first === "hook" ? "hook-owner" : "scan-owner");
+      expect(repos.memories.get(captured.l1MemoryId)?.userId).toBe(first === "hook" ? "hook-owner" : "scan-owner");
       expect(repos.runtime.getEpisode(captured.episodeId)?.l1MemoryIds).toEqual([captured.l1MemoryId]);
       expect(repos.runtime.getRawTurn(captured.rawTurnId)?.toolCalls[0]).toMatchObject({ id: "read", input: { path: "src/main.ts" }, output: expect.stringContaining("source contents") });
       expect(db.db.prepare("SELECT COUNT(*) AS n FROM evolution_jobs WHERE job_type = 'import_summary'").get()).toEqual({ n: 0 });
diff --git a/Memory/tests/repository/source-turn-schema.test.ts b/Memory/tests/repository/source-turn-schema.test.ts
index febdf1edd..0e38bc630 100644
--- a/Memory/tests/repository/source-turn-schema.test.ts
+++ b/Memory/tests/repository/source-turn-schema.test.ts
@@ -33,6 +33,25 @@ describe("source turn schema upgrade", () => {
     finally { reopened.close(); }
   });
 
+  it("adds account-independent lookup indexes on an existing database without rewriting captures", () => {
+    const { db, root } = createTestService();
+    const runtime = new Repositories(db.db).runtime;
+    runtime.insertSourceTurnCapture({ userId: "installed-owner", source: "codex", profileId: "default", namespaceKey: "scope",
+      conversationId: "conversation", turnId: "turn", contentHash: "hash", startedAt: "2099-01-01T10:00:00Z",
+      completedAt: "2099-01-01T10:01:00Z", createdAt: "2099-01-01T10:01:00Z", response: { status: "rejected", reason: "capture_policy" } });
+    const before = db.db.prepare("SELECT * FROM source_turn_captures").all();
+    db.db.exec("DROP INDEX idx_source_turn_captures_native_turn; DROP INDEX idx_source_turn_captures_native_conversation");
+    db.close();
+    const reopened = new MemoryDb({ path: join(root, "memory.sqlite") });
+    try {
+      expect(reopened.db.prepare("SELECT * FROM source_turn_captures").all()).toEqual(before);
+      const plan = reopened.db.prepare(`EXPLAIN QUERY PLAN SELECT * FROM source_turn_captures
+        WHERE source = ? AND profile_id = ? AND namespace_key = ? AND conversation_id = ? AND turn_id = ?`)
+        .all("codex", "default", "scope", "conversation", "turn") as Array<{ detail: string }>;
+      expect(plan.some(row => row.detail.includes("idx_source_turn_captures_native_turn"))).toBe(true);
+    } finally { reopened.close(); }
+  });
+
   it("enforces source uniqueness across separate database connections", () => {
     const { db, root } = createTestService();
     const second = new MemoryDb({ path: join(root, "memory.sqlite") });
@@ -45,7 +64,7 @@ describe("source turn schema upgrade", () => {
     try {
       new Repositories(db.db).runtime.insertSourceTurnCapture(capture);
       expect(() => new Repositories(second.db).runtime.insertSourceTurnCapture(capture)).toThrow(/UNIQUE constraint/);
-      expect(new Repositories(second.db).runtime.getSourceTurnCapture(capture, capture.turnId)?.response).toEqual(capture.response);
+      expect(new Repositories(second.db).runtime.getSourceTurnCapture({ ...capture, userId: "switched-user" }, capture.turnId)?.response).toEqual(capture.response);
     } finally { second.close(); }
   });
 });
diff --git a/Memory/tests/service/session/source-turn-capture.test.ts b/Memory/tests/service/session/source-turn-capture.test.ts
index 88f279f80..71c474a4e 100644
--- a/Memory/tests/service/session/source-turn-capture.test.ts
+++ b/Memory/tests/service/session/source-turn-capture.test.ts
@@ -153,7 +153,8 @@ describe("native source turn submission", () => {
     const reopened = new MemoryDb({ path: join(root, "memory.sqlite") });
     try {
       const restarted = createTestMemoryService({ db: reopened });
-      const second = restarted.completeSourceTurn(request({ channel: channel === "hook" ? "agent_source_scan" : "hook", sessionId: "late-hook-session" }));
+      const second = restarted.completeSourceTurn(request({ channel: channel === "hook" ? "agent_source_scan" : "hook", sessionId: "late-hook-session",
+        namespace: { ...request().namespace!, userId: "switched-after-restart" } }));
       expect(second).toMatchObject({ status: "existing", result: { rawTurnId: result.rawTurnId, l1MemoryId: result.l1MemoryId, duplicate: true, jobs: [] } });
       expect(counts(reopened)).toEqual(before);
     } finally { reopened.close(); }
@@ -202,7 +203,6 @@ describe("native source turn submission", () => {
   });
 
   it.each([
-    { label: "another user with the same native conversation", namespace: { userId: "other-user" } },
     { label: "another project", namespace: { projectId: "project-b" } },
     { label: "another workspace", namespace: { workspaceId: "workspace-b" } },
     { label: "an unproven tenant", namespace: { tenantId: "tenant-b" } },
@@ -310,12 +310,79 @@ describe("native source turn submission", () => {
     expect(counts(db)).toEqual(before);
   });
 
-  it("does not merge equal QA belonging to different turns or scopes", () => {
+  it("keeps different native turns but reuses the same turn across accounts", () => {
     const { service } = createTestService();
     const first = service.completeSourceTurn(request());
     const second = service.completeSourceTurn(request({ sourceTurn: { ...request().sourceTurn, turnId: "native-turn-2", sequence: 2, startedAt: "2099-01-01T10:02:00.000Z", completedAt: "2099-01-01T10:03:00.000Z" } }));
     const otherUser = service.completeSourceTurn(request({ namespace: { ...request().namespace!, userId: "other-user" } }));
-    expect(new Set([first.result?.l1MemoryId, second.result?.l1MemoryId, otherUser.result?.l1MemoryId]).size).toBe(3);
+    expect(otherUser).toMatchObject({ status: "existing", result: { l1MemoryId: first.result!.l1MemoryId, jobs: [] } });
+    expect(second.result?.l1MemoryId).not.toBe(first.result?.l1MemoryId);
+  });
+
+  it.each(["codex", "claude_code", "cursor", "opencode"])(
+    "keeps one %s conversation across accounts and capture channels",
+    async (source) => {
+      for (const firstChannel of ["hook", "agent_source_scan"] as const) {
+        const { db, service } = createTestService();
+        const input = request({ source, channel: firstChannel,
+          namespace: { source, profileId: "default", userId: "installed-owner" },
+          sourceTurn: { ...request().sourceTurn, source } });
+        const opened = service.openSession({ namespace: { ...input.namespace!,
+          sessionKey: `${source}-memory-${input.sourceTurn.conversationId}` } });
+        const first = service.completeSourceTurn(input);
+        expect(first).toMatchObject({ status: "stored", result: { sessionId: opened.sessionId } });
+        const before = counts(db);
+        const switched = { ...input, channel: firstChannel === "hook" ? "agent_source_scan" as const : "hook" as const,
+          namespace: { ...input.namespace!, userId: "current-owner" } };
+        expect(service.completeSourceTurn(switched)).toMatchObject({ status: "existing", result: {
+          sessionId: first.result!.sessionId, episodeId: first.result!.episodeId,
+          rawTurnId: first.result!.rawTurnId, l1MemoryIds: first.result!.l1MemoryIds, jobs: []
+        } });
+        expect(counts(db)).toEqual(before);
+        const secondInput = { ...switched, sourceTurn: { ...input.sourceTurn, turnId: "native-turn-2", sequence: 2,
+          startedAt: "2099-01-01T10:02:00.000Z", completedAt: "2099-01-01T10:03:00.000Z" } };
+        const second = service.completeSourceTurn(secondInput);
+        expect(second).toMatchObject({ status: "stored", result: {
+          sessionId: opened.sessionId, episodeId: first.result!.episodeId
+        } });
+        expect(second.result!.l1MemoryId).not.toBe(first.result!.l1MemoryId);
+        expect(db.db.prepare("SELECT DISTINCT user_id FROM source_turn_captures").all()).toEqual([{ user_id: "installed-owner" }]);
+        expect(counts(db)).toMatchObject({ sessions: 1, episodes: 1, raw_turns: 2, source_turn_captures: 2 });
+        await runWorkerRounds(service, 4);
+        const recall = await service.search({ query: input.query, layers: ["L1"], limit: 10 });
+        expect(recall.hits.filter(hit => hit.id === first.result!.l1MemoryId)).toHaveLength(1);
+        const afterWorker = counts(db);
+        service.completeSourceTurn(switched);
+        service.completeSourceTurn(secondInput);
+        expect(counts(db)).toEqual(afterWorker);
+      }
+    }
+  );
+
+  it("lets the first scanner completion reuse a Hook Session from the installed account", () => {
+    const { service, db } = createTestService();
+    const input = request();
+    const opened = service.openSession({ namespace: { ...input.namespace!,
+      sessionKey: `codex-memory-${input.sourceTurn.conversationId}` } });
+    const scanned = service.completeSourceTurn({ ...input, channel: "agent_source_scan",
+      namespace: { ...input.namespace!, userId: "new-account" } });
+    expect(scanned).toMatchObject({ status: "stored", result: { sessionId: opened.sessionId } });
+    expect(service.completeSourceTurn(input).status).toBe("existing");
+    expect(counts(db)).toMatchObject({ sessions: 1, episodes: 1, raw_turns: 1, source_turn_captures: 1 });
+    expect(new Repositories(db.db).memories.get(scanned.result!.l1MemoryId)?.userId).toBe(input.namespace!.userId);
+  });
+
+  it("retains cross-account conflicts and tombstones after the Episode closes", () => {
+    const { service, db } = createTestService();
+    const first = service.completeSourceTurn(request());
+    service.closeSession(first.result!.sessionId);
+    const switched = request({ namespace: { ...request().namespace!, userId: "switched-owner" }, channel: "agent_source_scan" });
+    const before = counts(db);
+    expect(service.completeSourceTurn(switched)).toMatchObject({ status: "existing", result: { jobs: [] } });
+    expect(service.completeSourceTurn({ ...switched, answer: "A different answer" })).toMatchObject({ status: "conflict", reason: "source_turn_content_conflict" });
+    db.db.prepare("UPDATE memories SET status = 'deleted', deleted_at = ? WHERE id = ?").run("2099-01-02", first.result!.l1MemoryId);
+    expect(service.completeSourceTurn(switched)).toMatchObject({ status: "rejected", reason: "capture_deleted" });
+    expect(counts(db)).toEqual(before);
   });
 
   it("reports conflicting content and keeps deleted capture identities", () => {

From 4d38f0186fc1cab092c7001c300a834ca4174241 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Sat, 10 Oct 2026 11:05:04 +0800
Subject: [PATCH 37/85] test: clarify native conversation scope regression name

---
 Memory/tests/service/session/source-turn-capture.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Memory/tests/service/session/source-turn-capture.test.ts b/Memory/tests/service/session/source-turn-capture.test.ts
index 71c474a4e..c0cacdb32 100644
--- a/Memory/tests/service/session/source-turn-capture.test.ts
+++ b/Memory/tests/service/session/source-turn-capture.test.ts
@@ -1076,7 +1076,7 @@ describe("native source turn submission", () => {
     expect(runtime.getEpisode(completed.result!.episodeId)?.openedAt).toBe("2099-01-01T10:02:00.000Z");
   });
 
-  it("rejects a supplied Session from another account or native conversation", () => {
+  it("rejects a supplied Session from another native conversation", () => {
     const { service } = createTestService();
     const foreign = service.openSession({ namespace: { source: "codex", profileId: "default", userId: "other-user", sessionKey: "other-conversation" } });
     expect(() => service.completeSourceTurn(request({ sessionId: foreign.sessionId }))).toThrow("source_session_scope_conflict");

From 0e48c982e0460f08b2f031a085f92992a20ced2b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Wed, 14 Oct 2026 14:59:08 +0800
Subject: [PATCH 38/85] fix: collapse duplicate cross-account L1 recall
 candidates

---
 .../cross-account-candidate-dedup.ts          | 151 ++++++++++++++++++
 .../retrieval/indexed-candidate-pool.ts       |  12 +-
 .../service/retrieval/retrieval-service.ts    |  12 +-
 .../service/session/session-turn-service.ts   |   8 +-
 4 files changed, 176 insertions(+), 7 deletions(-)
 create mode 100644 Memory/src/service/retrieval/cross-account-candidate-dedup.ts

diff --git a/Memory/src/service/retrieval/cross-account-candidate-dedup.ts b/Memory/src/service/retrieval/cross-account-candidate-dedup.ts
new file mode 100644
index 000000000..aab41318a
--- /dev/null
+++ b/Memory/src/service/retrieval/cross-account-candidate-dedup.ts
@@ -0,0 +1,151 @@
+import type { SeededChannelScores } from "../../algorithm/plugin-algorithms.js";
+import type { Repositories } from "../../storage/repositories.js";
+import { attachMemoryVector, memoryVector, memoryVectorEntries } from "../../storage/memory-vector-state.js";
+import type { MemoryRow } from "../../types.js";
+import { stableHash } from "../../utils/id.js";
+import { isRecord } from "../../utils/json.js";
+
+export interface CrossAccountCandidateDedupResult {
+  memories: MemoryRow[];
+  channelScoresByMemory: ReadonlyMap<string, SeededChannelScores>;
+  memoryIdByMemoryId: ReadonlyMap<string, string>;
+}
+
+/**
+ * Collapse copies of the same locally sourced memory before ranking. Account IDs
+ * identify the write owner, but the same native source turn can have been written
+ * under more than one account before cross-account capture deduplication existed.
+ */
+export function deduplicateCrossAccountMemoryCandidates(input: {
+  memories: readonly MemoryRow[];
+  repos: Repositories;
+  preferredUserId: string;
+  channelScoresByMemory?: ReadonlyMap<string, SeededChannelScores>;
+}): CrossAccountCandidateDedupResult {
+  const groups = new Map<string, { firstIndex: number; memories: MemoryRow[] }>();
+  const nativeConversationBySessionId = new Map<string, string | undefined>();
+  input.memories.forEach((memory, index) => {
+    const key = duplicateKey(memory, input.repos, nativeConversationBySessionId);
+    if (!key) {
+      groups.set(`unique:${index}:${memory.id}`, { firstIndex: index, memories: [memory] });
+      return;
+    }
+    const group = groups.get(key);
+    if (group) group.memories.push(memory);
+    else groups.set(key, { firstIndex: index, memories: [memory] });
+  });
+
+  const selected = [...groups.values()]
+    .sort((left, right) => left.firstIndex - right.firstIndex)
+    .map((group) => {
+      const representative = [...group.memories].sort((left, right) =>
+        Number(right.userId === input.preferredUserId) - Number(left.userId === input.preferredUserId) ||
+        candidateScore(right, input.channelScoresByMemory) - candidateScore(left, input.channelScoresByMemory) ||
+        left.createdAt.localeCompare(right.createdAt) ||
+        left.id.localeCompare(right.id)
+      )[0]!;
+      return { representative, members: group.memories };
+    });
+
+  const channelScoresByMemory = new Map<string, SeededChannelScores>();
+  const memoryIdByMemoryId = new Map<string, string>();
+  for (const group of selected) {
+    if (group.members.length === 1) {
+      const memory = group.representative;
+      memoryIdByMemoryId.set(memory.id, memory.id);
+      const scores = input.channelScoresByMemory?.get(memory.id);
+      if (scores) channelScoresByMemory.set(memory.id, scores);
+      continue;
+    }
+
+    const merged: SeededChannelScores = {};
+    for (const memory of group.members) {
+      memoryIdByMemoryId.set(memory.id, group.representative.id);
+      for (const vector of memoryVectorEntries(memory)) {
+        if (!memoryVector(group.representative, vector.vectorField)) {
+          attachMemoryVector(group.representative, vector);
+        }
+      }
+      for (const [channel, score] of Object.entries(input.channelScoresByMemory?.get(memory.id) ?? {})) {
+        const key = channel as keyof SeededChannelScores;
+        const current = merged[key];
+        if (typeof score === "number" && (current === undefined || score > current)) {
+          merged[key] = score;
+        }
+      }
+    }
+    if (Object.keys(merged).length > 0) channelScoresByMemory.set(group.representative.id, merged);
+  }
+
+  return {
+    memories: selected.map((group) => group.representative),
+    channelScoresByMemory,
+    memoryIdByMemoryId
+  };
+}
+
+function duplicateKey(
+  memory: MemoryRow,
+  repos: Repositories,
+  nativeConversationBySessionId: Map<string, string | undefined>
+): string | undefined {
+  if (memory.memoryLayer !== "L1" || memory.properties.internal_info.memory_kind === "work_memory") {
+    return undefined;
+  }
+  const nativeConversation = nativeConversationKey(memory, repos, nativeConversationBySessionId);
+  if (!nativeConversation) return undefined;
+  const internal = memory.properties.internal_info;
+  const trace = isRecord(internal.trace)
+    ? internal.trace
+    : isRecord(memory.info.trace)
+      ? memory.info.trace
+      : undefined;
+  const turnId = text(memory.info.turn_id) ?? text(trace?.turn_id);
+  if (!turnId) return undefined;
+  const stepIndex = typeof trace?.step_index === "number" && Number.isFinite(trace.step_index)
+    ? trace.step_index
+    : memory.contentHash ?? stableHash(memory.memoryValue);
+  return `native-turn:${stableHash({ nativeConversation, turnId, stepIndex })}`;
+}
+
+function nativeConversationKey(
+  memory: MemoryRow,
+  repos: Repositories,
+  cache: Map<string, string | undefined>
+): string | undefined {
+  if (!memory.sessionId) return undefined;
+  if (cache.has(memory.sessionId)) return cache.get(memory.sessionId);
+  const session = repos.runtime.getSession(memory.sessionId);
+  if (!session) {
+    cache.set(memory.sessionId, undefined);
+    return undefined;
+  }
+  const conversationId = session.conversationId?.trim() || memory.conversationId?.trim();
+  const source = session.source.trim();
+  const profileId = session.profileId.trim();
+  if (!conversationId || !source || !profileId) {
+    cache.set(memory.sessionId, undefined);
+    return undefined;
+  }
+
+  const storedNamespaceKey = text(session.meta.source_namespace_key);
+  const tenantId = text(session.meta.tenant_id) ?? text(session.meta.tenantId) ?? null;
+  const namespaceKey = storedNamespaceKey ?? stableHash({
+    tenantId,
+    projectId: session.projectId ?? null,
+    workspaceId: session.workspaceId ?? null
+  });
+  const key = stableHash({ source, profileId, namespaceKey, conversationId });
+  cache.set(memory.sessionId, key);
+  return key;
+}
+
+function candidateScore(memory: MemoryRow, scores?: ReadonlyMap<string, SeededChannelScores>): number {
+  return Math.max(0, ...Object.values(scores?.get(memory.id) ?? {}).filter((value): value is number =>
+    typeof value === "number" && Number.isFinite(value)
+  ));
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
diff --git a/Memory/src/service/retrieval/indexed-candidate-pool.ts b/Memory/src/service/retrieval/indexed-candidate-pool.ts
index f907e2d4d..e177b97ec 100644
--- a/Memory/src/service/retrieval/indexed-candidate-pool.ts
+++ b/Memory/src/service/retrieval/indexed-candidate-pool.ts
@@ -14,6 +14,7 @@ import type {
   MemoryLayer,
   MemoryRow
 } from "../../types.js";
+import { deduplicateCrossAccountMemoryCandidates } from "./cross-account-candidate-dedup.js";
 
 export function dedupeStrings(values: readonly string[]): string[] {
   const out: string[] = [];
@@ -147,13 +148,16 @@ export class IndexedCandidatePool {
       scores[hit.channel] = Math.max(scores[hit.channel] ?? -Infinity, hit.score);
       channelScoresByMemory.set(hit.id, scores);
     }
-    return {
-      memories: this.deps.repos.memories.getMany(candidateIds).filter((memory) =>
+    const readyMemories = this.deps.repos.memories.getMany(candidateIds).filter((memory) =>
         this.isMemoryReadyForRetrieval(memory) &&
         this.isSkillVisibleToAgent(memory, input.currentAgentId)
-      ),
+      );
+    return deduplicateCrossAccountMemoryCandidates({
+      memories: readyMemories,
+      repos: this.deps.repos,
+      preferredUserId: input.userId,
       channelScoresByMemory
-    };
+    });
   }
 
   private isSkillVisibleToAgent(memory: MemoryRow, currentAgentId?: string): boolean {
diff --git a/Memory/src/service/retrieval/retrieval-service.ts b/Memory/src/service/retrieval/retrieval-service.ts
index 17e6ebf0d..ca7a6baed 100644
--- a/Memory/src/service/retrieval/retrieval-service.ts
+++ b/Memory/src/service/retrieval/retrieval-service.ts
@@ -69,6 +69,7 @@ import {
   normalizeRetrievalExtractKeywords
 } from "../turn/turn-normalization.js";
 import { IndexedCandidatePool } from "./indexed-candidate-pool.js";
+import { deduplicateCrossAccountMemoryCandidates } from "./cross-account-candidate-dedup.js";
 import { filterL1TraceSpanRecallHits } from "./l1-trace-span-filter.js";
 
 type InternalMemorySearchRequest = MemorySearchRequest & {
@@ -1941,7 +1942,8 @@ export class RetrievalService {
       ? this.retrieveTimeFilteredTraceMemories({
           timeFilter,
           tags: request.tags,
-          limit: retrievalLimit
+          limit: retrievalLimit,
+          preferredUserId: context.userId
         })
       : await this.retrieveSearchMemories({
           userId: context.userId,
@@ -2165,6 +2167,7 @@ export class RetrievalService {
     timeFilter: RetrievalTimeFilter;
     tags?: string[];
     limit: number;
+    preferredUserId: string;
   }): { retrieval: RetrievalResult; memories: MemoryRow[] } {
     const filter: MemoryFilter = {
       memoryLayer: "L1",
@@ -2174,10 +2177,15 @@ export class RetrievalService {
       ...(input.tags?.length ? { tags: input.tags } : {})
     };
     const candidateCount = this.deps.repos.memories.count(filter);
-    const candidates = this.deps.repos.memories
+    const loadedCandidates = this.deps.repos.memories
       .list(filter, candidateCount)
       .filter((memory) => this.isMemoryReadyForRetrieval(memory))
       .filter((memory) => Boolean(traceMetaFromMemory(memory)?.summary.trim()));
+    const candidates = deduplicateCrossAccountMemoryCandidates({
+      memories: loadedCandidates,
+      repos: this.deps.repos,
+      preferredUserId: input.preferredUserId
+    }).memories;
     const selected = [...candidates]
       .sort(compareTimeFilteredTraceRecency)
       .slice(0, Math.max(0, input.limit))
diff --git a/Memory/src/service/session/session-turn-service.ts b/Memory/src/service/session/session-turn-service.ts
index 811771711..1132952c1 100644
--- a/Memory/src/service/session/session-turn-service.ts
+++ b/Memory/src/service/session/session-turn-service.ts
@@ -71,6 +71,7 @@ import type {
   SynthesizeDecisionRepairDraft
 } from "../feedback/feedback-experience.js";
 import { recordApiLog } from "../model-audit/model-call-audit.js";
+import { deduplicateCrossAccountMemoryCandidates } from "../retrieval/cross-account-candidate-dedup.js";
 import {
   namespaceForRawTurn,
   namespaceForSession,
@@ -2937,13 +2938,18 @@ export class SessionTurnService {
       : undefined;
     const query = buildRepairSuggestionQuery(input);
     const repairLayers = retrievalLayersForMode("decision_repair");
-    const candidates = this.deps.repos.memories.list(
+    const loadedCandidates = this.deps.repos.memories.list(
       {
         memoryLayer: repairLayers,
         status: ["activated", "resolving"]
       },
       500
     ).filter((memory) => this.deps.isMemoryReadyForRetrieval(memory));
+    const candidates = deduplicateCrossAccountMemoryCandidates({
+      memories: loadedCandidates,
+      repos: this.deps.repos,
+      preferredUserId: session.userId
+    }).memories;
     const retrieval = retrievePluginMemories({
       query,
       queryVector: await this.deps.queryVector(query),

From 15164f98c4da4d2dca1823d85185dda50db719c1 Mon Sep 17 00:00:00 2001
From: dolnna <99724206+dolnna@users.noreply.github.com>
Date: Wed, 14 Oct 2026 15:41:59 +0800
Subject: [PATCH 39/85] style(desktop): place social sign-in below email login

---
 .../src/components/social-login-buttons.tsx   | 11 ++-
 App/frontend/desktop/src/i18n/messages.ts     |  2 +
 App/frontend/desktop/src/pages/login-page.tsx |  3 +-
 .../desktop/src/pages/welcome-page.tsx        | 17 ++--
 App/frontend/desktop/src/styles.css           | 82 +++++++++++++++++++
 5 files changed, 103 insertions(+), 12 deletions(-)

diff --git a/App/frontend/desktop/src/components/social-login-buttons.tsx b/App/frontend/desktop/src/components/social-login-buttons.tsx
index 078f7074f..45bdd7e46 100644
--- a/App/frontend/desktop/src/components/social-login-buttons.tsx
+++ b/App/frontend/desktop/src/components/social-login-buttons.tsx
@@ -10,6 +10,7 @@ const SOCIAL_LOGIN_BUTTONS_ENABLED = false;
 export interface SocialLoginButtonsProps {
   pendingProvider: SocialLoginProvider | null;
   disabled?: boolean;
+  showDivider?: boolean;
   feedback?: { text: string; tone: "error" | "success" } | null;
   onLogin: (provider: SocialLoginProvider) => void;
 }
@@ -19,15 +20,18 @@ export function SocialLoginButtons(props: SocialLoginButtonsProps) {
   if (!SOCIAL_LOGIN_BUTTONS_ENABLED) return null;
 
   return (
-    <div className="mt-4 space-y-2.5">
-      <div className="flex flex-col gap-3">
+    <div className="social-login-actions">
+      {props.showDivider ? <div className="social-login-divider">{t("login.social.orSocial")}</div> : null}
+      <div className="social-login-actions__buttons">
         <SocialLoginButton
+          provider="google"
           label={props.pendingProvider === "google" ? t("login.social.opening") : t("login.social.google")}
           icon={<GoogleMark />}
           disabled={props.disabled || Boolean(props.pendingProvider)}
           onClick={() => props.onLogin("google")}
         />
         <SocialLoginButton
+          provider="github"
           label={props.pendingProvider === "github" ? t("login.social.opening") : t("login.social.github")}
           icon={<GitHubMark />}
           disabled={props.disabled || Boolean(props.pendingProvider)}
@@ -48,6 +52,7 @@ export function SocialLoginButtons(props: SocialLoginButtonsProps) {
 }
 
 function SocialLoginButton(props: {
+  provider: SocialLoginProvider;
   label: string;
   icon: ReactNode;
   disabled?: boolean;
@@ -58,7 +63,7 @@ function SocialLoginButton(props: {
       type="button"
       disabled={props.disabled}
       onClick={props.onClick}
-      className="flex min-w-0 items-center justify-center gap-2 rounded-btn border border-border-stone/80 bg-white px-3 py-3 text-sm font-semibold text-text-ink shadow-sm transition-colors hover:bg-canvas-oat/60 disabled:cursor-not-allowed disabled:opacity-45"
+      className={`social-login-button social-login-button--${props.provider}`}
     >
       {props.icon}
       <span className="truncate">{props.label}</span>
diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index 9e79ffc53..a7ddec3d2 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -215,6 +215,7 @@ export const zhCNMessages = {
   "login.continue": "登录 / 注册",
   "login.social.google": "使用 Google 登录",
   "login.social.github": "使用 GitHub 登录",
+  "login.social.orSocial": "或",
   "login.social.opening": "正在打开…",
   "login.social.waiting": "请在浏览器中完成登录…",
   "login.social.expired": "登录已超时，请重试",
@@ -1955,6 +1956,7 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "login.continue": "Log in / Sign up",
   "login.social.google": "Continue with Google",
   "login.social.github": "Continue with GitHub",
+  "login.social.orSocial": "or",
   "login.social.opening": "Opening…",
   "login.social.waiting": "Complete sign-in in your browser…",
   "login.social.expired": "Sign-in timed out. Please try again.",
diff --git a/App/frontend/desktop/src/pages/login-page.tsx b/App/frontend/desktop/src/pages/login-page.tsx
index c20db5726..2b37c8213 100644
--- a/App/frontend/desktop/src/pages/login-page.tsx
+++ b/App/frontend/desktop/src/pages/login-page.tsx
@@ -171,7 +171,7 @@ export function LoginPage() {
           <p className="text-sm font-semibold text-text-ink/60">{t("nav.login")}</p>
           <h1 className="text-2xl font-extrabold text-text-ink mt-1">{t("login.title")}</h1>
         </div>
-        <div className="px-6 pb-6 space-y-3.5">
+        <div className="login-page__body px-6 pb-6 space-y-3.5">
           <AuthCodeForm
             identifier={identifier}
             identifierType={channel}
@@ -193,6 +193,7 @@ export function LoginPage() {
             <SocialLoginButtons
               pendingProvider={socialLogin.pendingProvider}
               disabled={verificationCodeAuth.loginPending || modePersistencePending}
+              showDivider
               feedback={socialLogin.feedback}
               onLogin={(provider) => void startSocialLogin(provider)}
             />
diff --git a/App/frontend/desktop/src/pages/welcome-page.tsx b/App/frontend/desktop/src/pages/welcome-page.tsx
index 666092d42..324f84e91 100644
--- a/App/frontend/desktop/src/pages/welcome-page.tsx
+++ b/App/frontend/desktop/src/pages/welcome-page.tsx
@@ -252,6 +252,15 @@ export function WelcomePage() {
                 onOpenTerms={() => void openExternalUrl(getLegalLinkUrl("terms", language, state.bootstrap?.legal))}
                 onOpenDataAgreement={() => void openExternalUrl(getLegalLinkUrl("data", language, state.bootstrap?.legal))}
               />
+              {channel === "email" ? (
+                <SocialLoginButtons
+                  pendingProvider={socialLogin.pendingProvider}
+                  disabled={verificationCodeAuth.loginPending || modePersistencePending}
+                  showDivider
+                  feedback={socialLogin.feedback}
+                  onLogin={(provider) => void startSocialLogin(provider)}
+                />
+              ) : null}
             </div>
           </div>
 
@@ -270,14 +279,6 @@ export function WelcomePage() {
             <Key size={15} />
             {t("welcome.byok.quickAction")}
           </button>
-          {channel === "email" ? (
-            <SocialLoginButtons
-              pendingProvider={socialLogin.pendingProvider}
-              disabled={verificationCodeAuth.loginPending || modePersistencePending}
-              feedback={socialLogin.feedback}
-              onLogin={(provider) => void startSocialLogin(provider)}
-            />
-          ) : null}
           </div>
         </div>
       </div>
diff --git a/App/frontend/desktop/src/styles.css b/App/frontend/desktop/src/styles.css
index 375ca9c0f..911eeef22 100644
--- a/App/frontend/desktop/src/styles.css
+++ b/App/frontend/desktop/src/styles.css
@@ -11070,6 +11070,88 @@ body.memmy-platform-windows:not(.memmy-window-fullscreen) .memmy-notification-st
   color: color-mix(in srgb, var(--color-text-ink) 24%, transparent);
 }
 
+.login-page__body {
+  padding-bottom: 24px;
+}
+
+.login-page__body .auth-code-form-input.flex-1,
+.welcome-login-card__body .auth-code-form-input.flex-1 {
+  min-width: 0;
+}
+
+.social-login-actions {
+  display: grid;
+  gap: 18px;
+}
+
+.social-login-actions__buttons {
+  display: grid;
+  gap: 10px;
+}
+
+.social-login-button {
+  display: flex;
+  width: 100%;
+  min-height: 48px;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  padding: 10px 16px;
+  border: 1px solid color-mix(in srgb, var(--color-border-stone) 85%, var(--color-text-ink));
+  border-radius: 11px;
+  background: var(--color-background-paper);
+  color: var(--color-text-ink);
+  font-size: 14px;
+  font-weight: 700;
+  line-height: 1.25;
+  cursor: pointer;
+  transition: border-color 150ms ease, background 150ms ease, box-shadow 150ms ease;
+}
+
+.social-login-button--google {
+  border-color: color-mix(in srgb, var(--color-action-sky) 53%, var(--color-border-stone));
+  background: color-mix(in srgb, var(--color-canvas-oat) 42%, white);
+  box-shadow: 0 2px 9px rgb(29 93 76 / 7%);
+}
+
+.social-login-button:hover:not(:disabled) {
+  border-color: var(--color-action-sky-hover);
+  background: color-mix(in srgb, var(--color-canvas-oat) 68%, white);
+}
+
+.social-login-button:focus-visible {
+  outline: 3px solid color-mix(in srgb, var(--color-action-sky) 65%, transparent);
+  outline-offset: 2px;
+}
+
+.social-login-button:disabled {
+  cursor: not-allowed;
+  opacity: .55;
+}
+
+.social-login-divider {
+  display: flex;
+  align-items: center;
+  gap: 13px;
+  color: color-mix(in srgb, var(--color-text-ink) 55%, transparent);
+  font-size: 12px;
+  line-height: 1;
+  white-space: nowrap;
+}
+
+.social-login-divider::before,
+.social-login-divider::after {
+  content: "";
+  flex: 1;
+  height: 1px;
+  background: var(--color-border-stone);
+}
+
+.login-page__body .social-login-actions,
+.welcome-login-card__body .social-login-actions {
+  margin-top: 22px;
+}
+
 /* Optional invite field: muted so it reads as secondary / non-required. */
 .auth-code-form-input--optional {
   border-color: color-mix(in srgb, var(--color-border-stone) 42%, white);

From b041201417fd3791151d8c9e74e55ea2e53fa8ad Mon Sep 17 00:00:00 2001
From: dolnna <99724206+dolnna@users.noreply.github.com>
Date: Wed, 14 Oct 2026 15:52:28 +0800
Subject: [PATCH 40/85] feat(desktop): refine model thinking controls and
 custom capabilities

---
 .../desktop/src/components/Select.tsx         |  91 +++--
 .../src/components/agent-model-selector.tsx   |  16 +-
 .../src/components/agent-thinking-control.tsx | 114 ++----
 .../agent-thinking-menu.interaction.test.tsx  | 103 ++++++
 App/frontend/desktop/src/i18n/messages.ts     |  26 +-
 .../src/pages/model-workspace-section.tsx     | 324 ++++++++++++------
 .../src/pages/tests/home-page.test.tsx        |   5 +-
 ...del-workspace-section.interaction.test.tsx | 127 +++++++
 .../src/pages/tests/settings-page.test.tsx    |  39 +--
 App/frontend/desktop/src/styles.css           | 254 +++++++++-----
 10 files changed, 756 insertions(+), 343 deletions(-)
 create mode 100644 App/frontend/desktop/src/components/tests/agent-thinking-menu.interaction.test.tsx

diff --git a/App/frontend/desktop/src/components/Select.tsx b/App/frontend/desktop/src/components/Select.tsx
index 89cbc0dcf..92995123d 100644
--- a/App/frontend/desktop/src/components/Select.tsx
+++ b/App/frontend/desktop/src/components/Select.tsx
@@ -31,6 +31,8 @@ export interface SelectProps {
   placement?: "top" | "bottom";
   /** Optional footer rendered below options; receives a close helper. */
   menuFooter?: (api: { close: () => void }) => ReactNode;
+  /** Optional panel shown beside the menu while an option is hovered or focused. */
+  optionAside?: (option: SelectOption) => ReactNode;
 }
 
 /** Handles select. */
@@ -40,15 +42,23 @@ export function Select(props: SelectProps) {
   const listboxId = `${controlId}-listbox`;
   const labelId = `${controlId}-label`;
   const rootRef = useRef<HTMLDivElement | null>(null);
+  const menuRef = useRef<HTMLDivElement | null>(null);
   const [open, setOpen] = useState(false);
   const [activeValue, setActiveValue] = useState(props.value);
+  const [hoveredValue, setHoveredValue] = useState<string | null>(null);
+  const [hoveredTop, setHoveredTop] = useState(0);
 
   const enabledOptions = useMemo(() => props.options.filter((option) => !option.disabled), [props.options]);
   const selectedOption = props.options.find((option) => option.value === props.value);
   const activeOption = props.options.find((option) => option.value === activeValue && !option.disabled);
+  const hoveredOption = props.options.find((option) => option.value === hoveredValue && !option.disabled);
+  const aside = hoveredOption ? props.optionAside?.(hoveredOption) : null;
 
   useEffect(() => {
-    if (!open) return;
+    if (!open) {
+      setHoveredValue(null);
+      return;
+    }
 
     setActiveValue(props.value || enabledOptions[0]?.value || "");
 
@@ -62,6 +72,12 @@ export function Select(props: SelectProps) {
     return () => document.removeEventListener("mousedown", closeOnOutsideClick);
   }, [enabledOptions, open, props.value]);
 
+  function showOptionAside(option: SelectOption, element: HTMLButtonElement) {
+    const menuTop = menuRef.current?.getBoundingClientRect().top ?? 0;
+    setHoveredTop(element.getBoundingClientRect().top - menuTop);
+    setHoveredValue(option.value);
+  }
+
   function moveActive(step: 1 | -1) {
     if (!enabledOptions.length) return;
 
@@ -158,38 +174,51 @@ export function Select(props: SelectProps) {
         <ChevronDown size={16} strokeWidth={2.2} className="select-control__icon" aria-hidden="true" />
       </button>
       {open && (
-        <div id={listboxId} className={`select-control__menu ${props.menuClassName ?? ""}`} role="listbox" aria-labelledby={props.label ? labelId : undefined}>
-          {props.options.map((option) => {
-            const showGroupLabel = Boolean(option.groupLabel && option.groupLabel !== previousGroupLabel);
-            previousGroupLabel = option.groupLabel;
-
-            return (
-              <div key={option.value}>
-                {showGroupLabel && <div className="select-control__group-label">{option.groupLabel}</div>}
-                <button
-                  type="button"
-                  role="option"
-                  aria-selected={option.value === props.value}
-                  disabled={option.disabled}
-                  className={`select-control__option ${
-                    option.value === props.value ? "select-control__option--selected" : ""
-                  } ${option.value === activeValue ? "select-control__option--active" : ""}`}
-                  onClick={() => selectValue(option.value)}
-                >
-                  <span className="select-control__option-content">
-                    {option.icon && (
-                      <span className="select-control__option-icon" aria-hidden="true">{option.icon}</span>
+        <div
+          ref={menuRef}
+          className={`select-control__menu ${props.menuClassName ?? ""}`}
+          onMouseLeave={() => setHoveredValue(null)}
+        >
+          <div id={listboxId} className="select-control__options" role="listbox" aria-labelledby={props.label ? labelId : undefined}>
+            {props.options.map((option) => {
+              const showGroupLabel = Boolean(option.groupLabel && option.groupLabel !== previousGroupLabel);
+              previousGroupLabel = option.groupLabel;
+
+              return (
+                <div key={option.value}>
+                  {showGroupLabel && <div className="select-control__group-label">{option.groupLabel}</div>}
+                  <button
+                    type="button"
+                    role="option"
+                    aria-selected={option.value === props.value}
+                    disabled={option.disabled}
+                    className={`select-control__option ${
+                      option.value === props.value ? "select-control__option--selected" : ""
+                    } ${option.value === activeValue ? "select-control__option--active" : ""}`}
+                    onMouseEnter={(event) => showOptionAside(option, event.currentTarget)}
+                    onFocus={(event) => showOptionAside(option, event.currentTarget)}
+                    onClick={() => selectValue(option.value)}
+                  >
+                    <span className="select-control__option-content">
+                      {option.icon && (
+                        <span className="select-control__option-icon" aria-hidden="true">{option.icon}</span>
+                      )}
+                      <span className="select-control__option-label">{option.label}</span>
+                    </span>
+                    {option.value === props.value && !option.disabled && (
+                      <Check size={14} strokeWidth={2.6} className="select-control__option-check" aria-hidden="true" />
                     )}
-                    <span className="select-control__option-label">{option.label}</span>
-                  </span>
-                  {option.value === props.value && !option.disabled && (
-                    <Check size={14} strokeWidth={2.6} className="select-control__option-check" aria-hidden="true" />
-                  )}
-                </button>
-              </div>
-            );
-          })}
+                  </button>
+                </div>
+              );
+            })}
+          </div>
           {props.menuFooter?.({ close: () => setOpen(false) })}
+          {aside && (
+            <div className="select-control__aside" style={{ top: hoveredTop }}>
+              {aside}
+            </div>
+          )}
         </div>
       )}
     </div>
diff --git a/App/frontend/desktop/src/components/agent-model-selector.tsx b/App/frontend/desktop/src/components/agent-model-selector.tsx
index f81d63ffa..7158bcbb1 100644
--- a/App/frontend/desktop/src/components/agent-model-selector.tsx
+++ b/App/frontend/desktop/src/components/agent-model-selector.tsx
@@ -102,12 +102,6 @@ export function AgentModelSelector(props: AgentModelSelectorProps) {
   const thinkingConfig = resolveThinkingConfigForModel(workspace, resolved.candidate);
 
   return (
-    <div className="agent-model-selector-with-thinking">
-      <AgentThinkingControl
-        scopeKey={props.scopeKey}
-        thinkingConfig={thinkingConfig}
-        disabled={props.disabled}
-      />
     <div className="agent-model-selector" data-model-selector-scope={props.scopeKey}>
       <Select
         label={t("home.modelSelector.label")}
@@ -122,6 +116,15 @@ export function AgentModelSelector(props: AgentModelSelectorProps) {
         className="select-control--compact select-control--subtle agent-model-selector__control"
         buttonClassName="agent-model-selector__button"
         menuClassName="agent-model-selector__menu"
+        optionAside={(option) => (
+          option.value === resolved.candidateId && thinkingConfig
+            ? <AgentThinkingControl
+                scopeKey={props.scopeKey}
+                thinkingConfig={thinkingConfig}
+                disabled={props.disabled}
+              />
+            : null
+        )}
         menuFooter={({ close }) => (
           <div className="agent-model-selector__footer">
             <button
@@ -139,7 +142,6 @@ export function AgentModelSelector(props: AgentModelSelectorProps) {
         )}
       />
     </div>
-    </div>
   );
 }
 
diff --git a/App/frontend/desktop/src/components/agent-thinking-control.tsx b/App/frontend/desktop/src/components/agent-thinking-control.tsx
index 88c885ad4..9d0380176 100644
--- a/App/frontend/desktop/src/components/agent-thinking-control.tsx
+++ b/App/frontend/desktop/src/components/agent-thinking-control.tsx
@@ -1,10 +1,8 @@
-import { ChevronDown } from "lucide-react";
-import { useEffect, useRef, useState } from "react";
+import { Check } from "lucide-react";
 import {
   resolveThinkingEnabled,
   resolveThinkingLevel,
-  type ModelThinkingConfig,
-  type ThinkingLevel
+  type ModelThinkingConfig
 } from "@memmy/local-api-contracts";
 import { useTranslation } from "../i18n/use-translation.js";
 import { agentActions } from "../state/app-actions.js";
@@ -16,99 +14,53 @@ export interface AgentThinkingControlProps {
   disabled: boolean;
 }
 
+/** Thinking settings shown inside the open model menu. */
 export function AgentThinkingControl(props: AgentThinkingControlProps) {
   const { t } = useTranslation();
   const { state, dispatch } = useAppState();
-  const [pickerOpen, setPickerOpen] = useState(false);
-  const containerRef = useRef<HTMLDivElement>(null);
   const config = props.thinkingConfig;
 
-  const thinkingState = state.agent.thinkingStateByScope[props.scopeKey];
-  const enabled = config
-    ? resolveThinkingEnabled(config, thinkingState?.enabled)
-    : false;
-  const currentLevel = config
-    ? resolveThinkingLevel(config, thinkingState?.level)
-    : null;
-
-  useEffect(() => {
-    if (!pickerOpen) return;
-    const handleClickOutside = (event: MouseEvent) => {
-      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
-        setPickerOpen(false);
-      }
-    };
-    document.addEventListener("mousedown", handleClickOutside);
-    return () => document.removeEventListener("mousedown", handleClickOutside);
-  }, [pickerOpen]);
-
-  if (!config) {
-    return null;
-  }
-
-  const hasLevels = config.levels.length > 0;
-  const showLevels = hasLevels && enabled && currentLevel !== null;
-  const level: ThinkingLevel | null = showLevels ? currentLevel : null;
+  if (!config) return null;
 
-  function toggleThinking() {
-    dispatch(agentActions.thinkingToggled(props.scopeKey, !enabled));
-  }
-
-  function selectLevel(next: string) {
-    dispatch(agentActions.thinkingLevelChanged(props.scopeKey, next));
-    setPickerOpen(false);
-  }
+  const thinkingState = state.agent.thinkingStateByScope[props.scopeKey];
+  const enabled = resolveThinkingEnabled(config, thinkingState?.enabled);
+  const currentLevel = resolveThinkingLevel(config, thinkingState?.level);
+  const showLevels = enabled && config.levels.length > 0;
 
   return (
-    <div ref={containerRef} className="agent-thinking-control">
+    <div className="agent-thinking-control" aria-label={t("home.thinking.label")}>
       {config.switchable && (
         <button
           type="button"
-          onClick={toggleThinking}
+          role="switch"
+          aria-checked={enabled}
+          onClick={() => dispatch(agentActions.thinkingToggled(props.scopeKey, !enabled))}
           disabled={props.disabled}
-          aria-pressed={enabled}
-          className={`thinking-toggle ${enabled ? "thinking-toggle--on" : ""}`}
-          aria-label={t("home.thinking.toggle")}
+          className="thinking-toggle"
         >
-          <span className="thinking-toggle__label">{t("home.thinking.label")}</span>
-          <div className={`thinking-toggle__switch ${enabled ? "thinking-toggle__switch--on" : ""}`}>
-            <div className="thinking-toggle__switch-thumb" />
-          </div>
+          <span>{t("home.thinking.label")}</span>
+          <span className={`thinking-toggle__switch ${enabled ? "thinking-toggle__switch--on" : ""}`} aria-hidden="true">
+            <span className="thinking-toggle__switch-thumb" />
+          </span>
         </button>
       )}
 
-      {level !== null && (
-        <div className="thinking-level-trigger-container">
-          <button
-            type="button"
-            onClick={() => setPickerOpen(!pickerOpen)}
-            disabled={props.disabled}
-            className="thinking-level-trigger"
-            aria-label={t("home.thinking.selectLevel")}
-          >
-            <span className="thinking-level-trigger__label">
-              {t("home.thinking.level")}: {t(`home.thinking.levelValue.${level}`)}
-            </span>
-            <ChevronDown size={14} className="thinking-level-trigger__icon" />
-          </button>
-
-          {pickerOpen && (
-            <div className="thinking-level-picker">
-              <div className="thinking-level-picker__header">
-                {t("home.thinking.levelHeader")}
-              </div>
-              {config.levels.map((option) => (
-                <button
-                  key={option}
-                  type="button"
-                  onClick={() => selectLevel(option)}
-                  className={`thinking-level-option ${level === option ? "thinking-level-option--selected" : ""}`}
-                >
-                  {t(`home.thinking.levelValue.${option}`)}
-                </button>
-              ))}
-            </div>
-          )}
+      {showLevels && (
+        <div className="thinking-level-picker" role="group" aria-label={t("home.thinking.levelHeader")}>
+          <div className="thinking-level-picker__header">{t("home.thinking.levelHeader")}</div>
+          {config.levels.map((option) => (
+            <button
+              key={option}
+              type="button"
+              aria-pressed={currentLevel === option}
+              onClick={() => dispatch(agentActions.thinkingLevelChanged(props.scopeKey, option))}
+              disabled={props.disabled}
+              className={`thinking-level-option ${currentLevel === option ? "thinking-level-option--selected" : ""}`}
+            >
+              <span>{t(`home.thinking.levelValue.${option}`)}</span>
+              {currentLevel === option && <Check size={15} strokeWidth={2.4} aria-hidden="true" />}
+            </button>
+          ))}
         </div>
       )}
     </div>
diff --git a/App/frontend/desktop/src/components/tests/agent-thinking-menu.interaction.test.tsx b/App/frontend/desktop/src/components/tests/agent-thinking-menu.interaction.test.tsx
new file mode 100644
index 000000000..533e9f19b
--- /dev/null
+++ b/App/frontend/desktop/src/components/tests/agent-thinking-menu.interaction.test.tsx
@@ -0,0 +1,103 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AgentModelSelector } from "../agent-model-selector.js";
+
+const mocks = vi.hoisted(() => ({
+  dispatch: vi.fn(),
+  state: {
+    modelConfig: null,
+    agent: {
+      committedModelSelectionByScope: {},
+      pendingPresetByScope: {},
+      thinkingStateByScope: {}
+    }
+  }
+}));
+
+vi.mock("../../state/app-state.js", () => ({ useAppState: () => mocks }));
+vi.mock("../../i18n/use-translation.js", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const labels: Record<string, string> = {
+        "home.modelSelector.label": "会话模型",
+        "home.modelSelector.byokGroup": "自定义模型",
+        "home.thinking.label": "思考模式",
+        "home.thinking.levelHeader": "思考强度",
+        "home.thinking.levelValue.low": "低",
+        "home.thinking.levelValue.medium": "中",
+        "home.thinking.levelValue.high": "高"
+      };
+      return labels[key] ?? key;
+    }
+  })
+}));
+vi.mock("../../state/model-workspace.js", () => ({
+  createModelWorkspace: () => ({}),
+  getTaskModelCandidates: () => [
+    { id: "openai-1", source: "byok", provider: "openai", model: "local-review-model" },
+    { id: "custom-1", source: "byok", provider: "custom", model: "local-review-model" }
+  ],
+  resolveModelSelection: () => ({
+    candidateId: "custom-1",
+    candidate: { id: "custom-1", source: "byok", provider: "custom", model: "local-review-model" }
+  }),
+  resolveThinkingConfigForModel: () => ({
+    switchable: true,
+    defaultEnabled: true,
+    levels: ["low", "medium", "high"],
+    defaultLevel: "medium"
+  })
+}));
+
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("AgentModelSelector thinking popover", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    mocks.dispatch.mockClear();
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    document.body.replaceChildren();
+  });
+
+  it("shows thinking settings beside the selected model row only after that row is hovered", () => {
+    act(() => root.render(
+      <AgentModelSelector mode="byok" scopeKey="draft-new-task" disabled={false} />
+    ));
+    const trigger = container.querySelector<HTMLButtonElement>('[role="combobox"]');
+    expect(container.querySelector(".select-control__aside")).toBeNull();
+
+    act(() => trigger?.click());
+    expect(container.querySelector('[role="listbox"]')).not.toBeNull();
+    expect(container.querySelector(".select-control__aside")).toBeNull();
+
+    const options = container.querySelectorAll<HTMLButtonElement>('[role="option"]');
+    act(() => options[0]?.dispatchEvent(new MouseEvent("mouseover", { bubbles: true })));
+    expect(container.querySelector(".select-control__aside")).toBeNull();
+
+    act(() => options[1]?.dispatchEvent(new MouseEvent("mouseover", { bubbles: true })));
+    expect(container.querySelector(".select-control__aside")).not.toBeNull();
+    expect(container.querySelectorAll(".thinking-level-option")).toHaveLength(3);
+
+    act(() => container.querySelector<HTMLButtonElement>('[role="switch"]')?.click());
+    expect(mocks.dispatch).toHaveBeenLastCalledWith({
+      type: "agent/thinkingToggled", scopeKey: "draft-new-task", enabled: false
+    });
+
+    expect(container.querySelector('[role="listbox"]')).not.toBeNull();
+    expect(container.querySelector(".select-control__aside")).not.toBeNull();
+
+    act(() => trigger?.click());
+    expect(container.querySelector(".select-control__aside")).toBeNull();
+  });
+});
diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index f62fcdedf..22baf2181 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -1536,8 +1536,7 @@ export const zhCNMessages = {
   "settings.modelWorkspace.endpoint": "Endpoint",
   "settings.modelWorkspace.initialModel": "首个模型名称",
   "settings.modelWorkspace.apiKey": "API Key",
-  "settings.modelWorkspace.replaceKey": "替换 API Key（留空则保留）",
-  "settings.modelWorkspace.replaceKeyPlaceholder": "留空以保留当前 Key",
+  "settings.modelWorkspace.apiKeyPlaceholder": "输入你的 API Key",
   "settings.modelWorkspace.deleteTitle": "删除配置？",
   "settings.modelWorkspace.deleteConfirm": "删除 {provider} 配置后，其下模型会从当前空间和候选列表中移除。此操作需要重新添加才能恢复。",
   "settings.modelWorkspace.chooseFor": "为{feature}选择模型",
@@ -1551,6 +1550,14 @@ export const zhCNMessages = {
   "settings.modelWorkspace.customProtocol": "协议",
   "settings.modelWorkspace.region": "区域",
   "settings.modelWorkspace.regionPlaceholder": "例如：us-east-1",
+  "settings.modelWorkspace.modelAbilities": "输入与思考",
+  "settings.modelWorkspace.thinkingMode": "思考模式",
+  "settings.modelWorkspace.thinkingModeToggleHint": "不勾选时，Memmy 不显示思考设置，由模型接口按默认行为处理。",
+  "settings.modelWorkspace.allowThinkingOff": "允许关闭思考模式",
+  "settings.modelWorkspace.allowThinkingOffHint": "仅当模型接口支持关闭思考时勾选。不勾选则思考始终开启。",
+  "settings.modelWorkspace.supportedThinkingLevels": "可选思考强度",
+  "settings.modelWorkspace.supportedThinkingLevelsHint": "至少选择一个，只勾选模型接口实际支持的档位。",
+  "settings.modelWorkspace.defaultThinkingLevel": "新会话默认强度",
   "settings.modelWorkspace.customThinkingEnabled": "支持思考",
   "settings.modelWorkspace.customThinkingEnabledHint": "勾选后，输入框可以设置思考。不勾选则不传思考参数，由模型接口按默认行为处理。使用 Chat Completions 并且使用 gpt 模型时，请关闭支持思考，否则可能导致错误。gpt 模型建议使用 Responses 接口获得最佳体验。",
   "settings.modelWorkspace.customThinkingSwitchable": "可关闭思考",
@@ -1561,7 +1568,7 @@ export const zhCNMessages = {
   "settings.modelWorkspace.customThinkingLevelsPlaceholder": "例如：low,medium,high",
   "settings.modelWorkspace.customThinkingLevelsHint": "用逗号分隔多个档位名称，留空表示无档位",
   "settings.modelWorkspace.customImageInput": "支持图片输入",
-  "settings.modelWorkspace.customImageInputHint": "勾选后可以在消息里发送图片。不勾选时，带图片的消息会被拒绝。",
+  "settings.modelWorkspace.customImageInputHint": "仅在模型能理解图片时开启。此设置决定 Memmy 是否放行图片，不会自动验证模型能力。",
   "settings.token.detail": "Token 用量详情",
   "settings.token.agentTask": "Agent 任务",
   "settings.token.memorySummary": "记忆摘要",
@@ -3307,8 +3314,7 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "settings.modelWorkspace.endpoint": "Endpoint",
   "settings.modelWorkspace.initialModel": "First model name",
   "settings.modelWorkspace.apiKey": "API key",
-  "settings.modelWorkspace.replaceKey": "Replace API key (leave blank to keep it)",
-  "settings.modelWorkspace.replaceKeyPlaceholder": "Leave blank to keep the current key",
+  "settings.modelWorkspace.apiKeyPlaceholder": "Enter your API key",
   "settings.modelWorkspace.deleteTitle": "Delete configuration?",
   "settings.modelWorkspace.deleteConfirm": "Deleting the {provider} configuration removes all of its models from this space and its candidate lists. Re-add the configuration to restore them.",
   "settings.modelWorkspace.chooseFor": "Choose a model for {feature}",
@@ -3322,6 +3328,14 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "settings.modelWorkspace.customProtocol": "Protocol",
   "settings.modelWorkspace.region": "Region",
   "settings.modelWorkspace.regionPlaceholder": "For example: us-east-1",
+  "settings.modelWorkspace.modelAbilities": "Input and thinking",
+  "settings.modelWorkspace.thinkingMode": "Thinking mode",
+  "settings.modelWorkspace.thinkingModeToggleHint": "When unchecked, Memmy hides thinking controls and leaves the endpoint's default behavior in place.",
+  "settings.modelWorkspace.allowThinkingOff": "Allow turning thinking off",
+  "settings.modelWorkspace.allowThinkingOffHint": "Select only if the endpoint supports disabling thinking. Otherwise thinking stays on.",
+  "settings.modelWorkspace.supportedThinkingLevels": "Available thinking levels",
+  "settings.modelWorkspace.supportedThinkingLevelsHint": "Select at least one level, and only levels the model endpoint actually supports.",
+  "settings.modelWorkspace.defaultThinkingLevel": "Default level for new chats",
   "settings.modelWorkspace.customThinkingEnabled": "Supports thinking",
   "settings.modelWorkspace.customThinkingEnabledHint": "When checked, the composer can set thinking. When unchecked, no thinking parameters are sent and the model endpoint uses its default behavior. When using Chat Completions with a GPT model, turn off Supports thinking, or the request may fail. GPT models should use the Responses API for the best experience.",
   "settings.modelWorkspace.customThinkingSwitchable": "Thinking can be turned off",
@@ -3332,7 +3346,7 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "settings.modelWorkspace.customThinkingLevelsPlaceholder": "For example: low,medium,high",
   "settings.modelWorkspace.customThinkingLevelsHint": "Comma-separated level names. Leave empty for no levels.",
   "settings.modelWorkspace.customImageInput": "Supports image input",
-  "settings.modelWorkspace.customImageInputHint": "When checked, messages can include images. When unchecked, messages with images are rejected.",
+  "settings.modelWorkspace.customImageInputHint": "Turn on only if the model can understand images. This controls whether Memmy permits images; it does not verify the model's capability.",
   "settings.token.detail": "Token usage details",
   "settings.token.agentTask": "Agent tasks",
   "settings.token.memorySummary": "Memory summary",
diff --git a/App/frontend/desktop/src/pages/model-workspace-section.tsx b/App/frontend/desktop/src/pages/model-workspace-section.tsx
index a80115715..a8dbabce1 100644
--- a/App/frontend/desktop/src/pages/model-workspace-section.tsx
+++ b/App/frontend/desktop/src/pages/model-workspace-section.tsx
@@ -5,7 +5,6 @@ import {
   THINKING_LEVELS,
   defaultThinkingLevel,
   type ModelEndpointProtocol,
-  type ModelThinkingConfig,
   type ModelThinkingConfigDto,
   type ThinkingLevel
 } from "@memmy/local-api-contracts";
@@ -79,6 +78,59 @@ interface ConnectionTestState {
   message: string | null;
 }
 
+type CustomThinkingMode = "interface-default" | "switchable" | "always-on";
+
+interface CustomModelOptions {
+  thinkingMode: CustomThinkingMode;
+  defaultEnabled: boolean;
+  levels: ThinkingLevel[];
+  defaultLevel: ThinkingLevel;
+  imageInput: boolean;
+}
+
+interface ConnectionEditorModel {
+  presetId?: string;
+  name: string;
+  capabilities: ModelCapability[];
+  customOptions?: CustomModelOptions;
+}
+
+function defaultCustomModelOptions(): CustomModelOptions {
+  return {
+    thinkingMode: "interface-default",
+    defaultEnabled: true,
+    levels: ["medium"],
+    defaultLevel: "medium",
+    imageInput: false
+  };
+}
+
+function customOptionsFromModel(entry: ModelConnection["modelEntries"][number]): CustomModelOptions {
+  const thinking = entry.thinking;
+  const levels = thinking?.levels.length ? [...thinking.levels] : ["medium" as ThinkingLevel];
+  return {
+    thinkingMode: !thinking
+      ? "interface-default"
+      : thinking.switchable ? "switchable" : "always-on",
+    defaultEnabled: thinking?.defaultEnabled ?? true,
+    levels,
+    defaultLevel: thinking?.defaultLevel && levels.includes(thinking.defaultLevel)
+      ? thinking.defaultLevel
+      : defaultThinkingLevel(levels) ?? "medium",
+    imageInput: entry.inputModalities?.includes("image") === true
+  };
+}
+
+function thinkingConfigFromOptions(options: CustomModelOptions | undefined): ModelThinkingConfigDto | undefined {
+  if (!options || options.thinkingMode === "interface-default") return undefined;
+  return {
+    switchable: options.thinkingMode === "switchable",
+    defaultEnabled: options.thinkingMode === "switchable" ? options.defaultEnabled : true,
+    levels: [...options.levels],
+    defaultLevel: options.defaultLevel
+  };
+}
+
 interface ConnectionEditorState {
   connectionId: string | null;
   provider: Protocol;
@@ -86,18 +138,10 @@ interface ConnectionEditorState {
   apiKey: string;
   customProtocol: CustomProtocol | null;
   region: string;
-  customThinkingEnabled: boolean;
-  customThinkingSwitchable: boolean;
-  customThinkingDefaultEnabled: boolean;
-  customThinkingLevels: string;
-  customImageInput: boolean;
-  models: Array<{
-    presetId?: string;
-    name: string;
-    capabilities: ModelCapability[];
-  }>;
+  models: ConnectionEditorModel[];
   modelDraft: string;
   capabilityDrafts: ModelCapability[];
+  modelDraftOptions: CustomModelOptions;
   addingModel: boolean;
   editingModelIndex: number | null;
 }
@@ -239,14 +283,10 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       apiKey: "",
       customProtocol: provider === "custom" ? "openai-chat-completions" : null,
       region: "",
-      customThinkingEnabled: false,
-      customThinkingSwitchable: true,
-      customThinkingDefaultEnabled: true,
-      customThinkingLevels: "",
-      customImageInput: false,
       models: [],
       modelDraft: DEFAULT_MODEL_IDS[provider],
       capabilityDrafts: [...DEFAULT_TEXT_CAPABILITIES],
+      modelDraftOptions: defaultCustomModelOptions(),
       addingModel: true,
       editingModelIndex: null
     });
@@ -296,7 +336,6 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       : connection.protocol === "openai-responses"
         ? "openai_responses"
         : protocolFromConnection(connection.provider);
-    const thinking = connection.modelEntries[0]?.thinking;
     const savedTest = connectionTestState(connection, testStates);
     setFormError(null);
     setEditorTest(savedTest
@@ -310,26 +349,28 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       apiKey: "",
       customProtocol: isCustom ? connection.protocol as CustomProtocol : null,
       region: connection.region ?? "",
-      customThinkingEnabled: Boolean(thinking),
-      customThinkingSwitchable: thinking?.switchable ?? true,
-      customThinkingDefaultEnabled: thinking?.defaultEnabled ?? true,
-      customThinkingLevels: thinking?.levels.join(",") ?? "",
-      customImageInput: connection.modelEntries[0]?.inputModalities?.includes("image") === true,
       models: connection.modelEntries.map((entry) => ({
         presetId: entry.presetId,
         name: entry.model,
-        capabilities: normalizeEditorCapabilities(entry.capabilities.map(fromCatalogCapability))
+        capabilities: normalizeEditorCapabilities(entry.capabilities.map(fromCatalogCapability)),
+        ...(isCustom ? { customOptions: customOptionsFromModel(entry) } : {})
       })),
       modelDraft: "",
       capabilityDrafts: [...DEFAULT_TEXT_CAPABILITIES],
+      modelDraftOptions: defaultCustomModelOptions(),
       addingModel: false,
       editingModelIndex: null
     });
   }
 
+  function updateDraftCustomOptions(next: CustomModelOptions) {
+    setEditor((current) => current ? { ...current, modelDraftOptions: next } : null);
+    setEditorTest({ status: "idle", message: null });
+  }
+
   function resolveEditorModels() {
     if (!editor) {
-      return { models: [] as Array<{ presetId?: string; name: string; capabilities: ModelCapability[] }>, error: null as string | null };
+      return { models: [] as ConnectionEditorModel[], error: null as string | null };
     }
     const draftName = editor.modelDraft.trim();
     if (!editor.addingModel || !draftName) {
@@ -350,7 +391,8 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
     const nextModel = {
       ...(editedModel?.presetId ? { presetId: editedModel.presetId } : {}),
       name: draftName,
-      capabilities: editor.capabilityDrafts
+      capabilities: editor.capabilityDrafts,
+      ...(editor.provider === "custom" ? { customOptions: editor.modelDraftOptions } : {})
     };
     return {
       models: editor.editingModelIndex !== null
@@ -382,23 +424,6 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
         capabilities,
         providerChanged ? undefined : existing?.protocol
       );
-    const levels = editor.customThinkingLevels
-      .split(",")
-      .map((level) => level.trim())
-      .filter((level): level is ThinkingLevel => THINKING_LEVELS.includes(level as ThinkingLevel));
-    const customThinkingConfig: ModelThinkingConfigDto | null = editor.provider === "custom" && editor.customThinkingEnabled
-      ? {
-          switchable: editor.customThinkingSwitchable,
-          defaultEnabled: editor.customThinkingSwitchable
-            ? editor.customThinkingDefaultEnabled
-            : true,
-          levels: [...levels],
-          defaultLevel: defaultThinkingLevel(levels)
-        }
-      : null;
-    const inputModalities = editor.provider === "custom"
-      ? (editor.customImageInput ? ["text", "image"] as const : ["text"] as const)
-      : undefined;
     const result = upsertModelConnection(workspace, props.mode, {
       id: editor.connectionId ?? undefined,
       provider: catalogProvider,
@@ -408,17 +433,20 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       apiKey: editor.apiKey || undefined,
       apiKeyMasked: providerChanged ? undefined : existing?.apiKeyMasked,
       models: resolved.models.map((model) => model.name),
-      modelEntries: resolved.models.map((model) => ({
-        ...(model.presetId ? { presetId: model.presetId } : {}),
-        model: model.name,
-        capability: model.capabilities[0]!,
-        capabilities: model.capabilities,
-        ...(editor.provider === "custom" ? {
-          custom: true,
-          thinking: customThinkingConfig,
-          inputModalities: [...inputModalities!]
-        } : {})
-      })),
+      modelEntries: resolved.models.map((model) => {
+        const thinking = thinkingConfigFromOptions(model.customOptions);
+        return {
+          ...(model.presetId ? { presetId: model.presetId } : {}),
+          model: model.name,
+          capability: model.capabilities[0]!,
+          capabilities: model.capabilities,
+          ...(editor.provider === "custom" ? {
+            custom: true,
+            ...(thinking ? { thinking } : {}),
+            inputModalities: model.customOptions?.imageInput ? ["text", "image"] : ["text"]
+          } : {})
+        };
+      }),
       modelCapabilities: Object.fromEntries(
         resolved.models.map((model) => [model.name, model.capabilities[0]!])
       )
@@ -514,7 +542,8 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
     const nextModel = {
       ...(editedModel?.presetId ? { presetId: editedModel.presetId } : {}),
       name,
-      capabilities: editor.capabilityDrafts
+      capabilities: editor.capabilityDrafts,
+      ...(editor.provider === "custom" ? { customOptions: editor.modelDraftOptions } : {})
     };
     const models = editor.editingModelIndex !== null
       ? editor.models.map((model, index) => index === editor.editingModelIndex ? nextModel : model)
@@ -524,6 +553,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       models,
       modelDraft: "",
       capabilityDrafts: [...DEFAULT_TEXT_CAPABILITIES],
+      modelDraftOptions: defaultCustomModelOptions(),
       addingModel: false,
       editingModelIndex: null
     });
@@ -539,6 +569,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       ...editor,
       modelDraft: model.name,
       capabilityDrafts: model.capabilities,
+      modelDraftOptions: model.customOptions ?? defaultCustomModelOptions(),
       addingModel: true,
       editingModelIndex: modelIndex
     });
@@ -551,6 +582,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       ...editor,
       modelDraft: "",
       capabilityDrafts: [...DEFAULT_TEXT_CAPABILITIES],
+      modelDraftOptions: defaultCustomModelOptions(),
       addingModel: false,
       editingModelIndex: null
     });
@@ -569,6 +601,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
         ? {
             modelDraft: "",
             capabilityDrafts: [...DEFAULT_TEXT_CAPABILITIES],
+            modelDraftOptions: defaultCustomModelOptions(),
             addingModel: false,
             editingModelIndex: null
           }
@@ -1135,6 +1168,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
                       models: [],
                       modelDraft: DEFAULT_MODEL_IDS[provider],
                       capabilityDrafts: [...DEFAULT_TEXT_CAPABILITIES],
+                      modelDraftOptions: defaultCustomModelOptions(),
                       addingModel: true,
                       editingModelIndex: null
                     })
@@ -1157,7 +1191,10 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
               <Select
                 label={t("settings.modelWorkspace.customProtocol")}
                 value={editor.customProtocol ?? "openai-chat-completions"}
-                onValueChange={(value) => setEditor((prev) => prev ? { ...prev, customProtocol: value as CustomProtocol } : null)}
+                onValueChange={(value) => {
+                  setEditor((prev) => prev ? { ...prev, customProtocol: value as CustomProtocol } : null);
+                  setEditorTest({ status: "idle", message: null });
+                }}
                 className="select-control--subtle"
                 options={CUSTOM_PROTOCOL_OPTIONS.map((option) => ({
                   value: option.value,
@@ -1168,57 +1205,13 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
                 <ConfigField
                   label={t("settings.modelWorkspace.region")}
                   value={editor.region}
-                  onChange={(region) => setEditor((prev) => prev ? { ...prev, region } : prev)}
+                  onChange={(region) => {
+                    setEditor((prev) => prev ? { ...prev, region } : prev);
+                    setEditorTest({ status: "idle", message: null });
+                  }}
                   placeholder={t("settings.modelWorkspace.regionPlaceholder")}
                 />
               )}
-              <div className="custom-thinking-config">
-                <CustomCapabilityOption
-                  checked={editor.customThinkingEnabled}
-                  label={t("settings.modelWorkspace.customThinkingEnabled")}
-                  hint={t("settings.modelWorkspace.customThinkingEnabledHint")}
-                  onChange={(customThinkingEnabled) => setEditor((prev) => prev ? { ...prev, customThinkingEnabled } : null)}
-                />
-                {editor.customThinkingEnabled && (
-                  <>
-                    <CustomCapabilityOption
-                      checked={editor.customThinkingSwitchable}
-                      label={t("settings.modelWorkspace.customThinkingSwitchable")}
-                      hint={t("settings.modelWorkspace.customThinkingSwitchableHint")}
-                      onChange={(customThinkingSwitchable) => setEditor((prev) => prev ? { ...prev, customThinkingSwitchable } : null)}
-                    />
-                    {editor.customThinkingSwitchable && (
-                      <CustomCapabilityOption
-                        checked={editor.customThinkingDefaultEnabled}
-                        label={t("settings.modelWorkspace.customThinkingDefaultEnabled")}
-                        hint={t("settings.modelWorkspace.customThinkingDefaultEnabledHint")}
-                        onChange={(customThinkingDefaultEnabled) => setEditor((prev) => prev ? { ...prev, customThinkingDefaultEnabled } : null)}
-                      />
-                    )}
-                    <div className="custom-thinking-levels">
-                      <label className="custom-thinking-levels__label">
-                        {t("settings.modelWorkspace.customThinkingLevels")}
-                      </label>
-                      <input
-                        type="text"
-                        placeholder={t("settings.modelWorkspace.customThinkingLevelsPlaceholder")}
-                        value={editor.customThinkingLevels}
-                        onChange={(event) => setEditor((prev) => prev ? { ...prev, customThinkingLevels: event.target.value } : null)}
-                        className="custom-thinking-levels__input"
-                      />
-                      <p className="custom-thinking-levels__hint">
-                        {t("settings.modelWorkspace.customThinkingLevelsHint")}
-                      </p>
-                    </div>
-                  </>
-                )}
-                <CustomCapabilityOption
-                  checked={editor.customImageInput}
-                  label={t("settings.modelWorkspace.customImageInput")}
-                  hint={t("settings.modelWorkspace.customImageInputHint")}
-                  onChange={(customImageInput) => setEditor((prev) => prev ? { ...prev, customImageInput } : null)}
-                />
-              </div>
             </>
           )}
           <ConfigField
@@ -1231,9 +1224,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
             placeholder={DEFAULT_ENDPOINTS[editor.provider]}
           />
           <PasswordConfigField
-            label={editor.connectionId && !editorProviderChanged
-              ? t("settings.modelWorkspace.replaceKey")
-              : t("apiKey.key")}
+            label={t("apiKey.key")}
             value={editor.apiKey}
             onChange={(value) => {
               setEditor((current) => current ? { ...current, apiKey: value } : current);
@@ -1242,9 +1233,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
             maskedValue={editor.connectionId && !editorProviderChanged
               ? editorExistingConnection?.apiKeyMasked
               : undefined}
-            placeholder={editor.connectionId && !editorProviderChanged
-              ? t("settings.modelWorkspace.replaceKeyPlaceholder")
-              : "sk-..."}
+            placeholder={t("settings.modelWorkspace.apiKeyPlaceholder")}
             showPassword={showEditorApiKey}
             onTogglePassword={() => setShowEditorApiKey((show) => !show)}
           />
@@ -1262,6 +1251,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
                     capabilityDrafts: editorExistingConnection
                       ? editorCapabilitiesForProtocol(editorExistingConnection.protocol)
                       : [...DEFAULT_TEXT_CAPABILITIES],
+                    modelDraftOptions: defaultCustomModelOptions(),
                     addingModel: true,
                     editingModelIndex: null
                   })}
@@ -1309,9 +1299,18 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
                 />
                 <ModelCapabilityPicker
                   capabilities={editor.capabilityDrafts}
-                  onChange={(capabilityDrafts) => setEditor({ ...editor, capabilityDrafts })}
+                  onChange={(capabilityDrafts) => {
+                    setEditor({ ...editor, capabilityDrafts });
+                    setEditorTest({ status: "idle", message: null });
+                  }}
                 />
               </div>
+              {editor.provider === "custom" && editor.capabilityDrafts.includes("chat") && (
+                <CustomModelSettings
+                  options={editor.modelDraftOptions}
+                  onChange={updateDraftCustomOptions}
+                />
+              )}
               <div className="model-editor-actions">
                 <button
                   type="button"
@@ -1411,9 +1410,7 @@ function ProviderModelList(props: {
             index > 0 ? "border-t border-border-stone/30" : ""
           }`}
         >
-          <span className="min-w-0 flex-1 truncate text-sm text-text-ink/70" title={item.model}>
-            {item.model}
-          </span>
+          <span className="min-w-0 flex-1 truncate text-sm text-text-ink/70" title={item.model}>{item.model}</span>
           <div className="flex shrink-0 items-center gap-1.5">
             <span className="rounded-tag bg-canvas-oat px-2 py-0.5 text-[10px] text-text-ink/50">
               {t(modelKindMessageKey(modelKindForCapabilities(item.capabilities)))}
@@ -1776,7 +1773,7 @@ function CustomCapabilityOption(props: {
     <label className="custom-thinking-config__label">
       <input
         type="checkbox"
-        className="custom-thinking-config__checkbox"
+        className="custom-thinking-config__checkbox check-sky"
         checked={props.checked}
         onChange={(event) => props.onChange(event.target.checked)}
       />
@@ -1786,3 +1783,102 @@ function CustomCapabilityOption(props: {
     </label>
   );
 }
+
+function CustomModelSettings(props: {
+  options: CustomModelOptions;
+  onChange: (next: CustomModelOptions) => void;
+}) {
+  const { t } = useTranslation();
+  const thinkingConfigured = props.options.thinkingMode !== "interface-default";
+
+  function toggleLevel(level: ThinkingLevel) {
+    const levels = props.options.levels.includes(level)
+      ? props.options.levels.filter((item) => item !== level)
+      : THINKING_LEVELS.filter((item) => item === level || props.options.levels.includes(item));
+    if (levels.length === 0) return;
+    props.onChange({
+      ...props.options,
+      levels,
+      defaultLevel: levels.includes(props.options.defaultLevel)
+        ? props.options.defaultLevel
+        : defaultThinkingLevel(levels) ?? levels[0]!
+    });
+  }
+
+  return (
+    <fieldset className="custom-thinking-config">
+      <legend className="custom-thinking-config__title">{t("settings.modelWorkspace.modelAbilities")}</legend>
+      <div className="custom-thinking-config__capabilities">
+        <CustomCapabilityOption
+          checked={props.options.imageInput}
+          label={t("settings.modelWorkspace.customImageInput")}
+          hint={t("settings.modelWorkspace.customImageInputHint")}
+          onChange={(imageInput) => props.onChange({ ...props.options, imageInput })}
+        />
+        <CustomCapabilityOption
+          checked={thinkingConfigured}
+          label={t("settings.modelWorkspace.thinkingMode")}
+          hint={t("settings.modelWorkspace.thinkingModeToggleHint")}
+          onChange={(checked) => props.onChange({
+            ...props.options,
+            thinkingMode: checked ? "always-on" : "interface-default"
+          })}
+        />
+      </div>
+      {thinkingConfigured && (
+        <>
+          <div className="custom-thinking-config__capabilities">
+            <CustomCapabilityOption
+              checked={props.options.thinkingMode === "switchable"}
+              label={t("settings.modelWorkspace.allowThinkingOff")}
+              hint={t("settings.modelWorkspace.allowThinkingOffHint")}
+              onChange={(allowed) => props.onChange({
+                ...props.options,
+                thinkingMode: allowed ? "switchable" : "always-on"
+              })}
+            />
+            {props.options.thinkingMode === "switchable" && (
+              <CustomCapabilityOption
+                checked={props.options.defaultEnabled}
+                label={t("settings.modelWorkspace.customThinkingDefaultEnabled")}
+                hint={t("settings.modelWorkspace.customThinkingDefaultEnabledHint")}
+                onChange={(defaultEnabled) => props.onChange({ ...props.options, defaultEnabled })}
+              />
+            )}
+          </div>
+          <div className="custom-thinking-config__section">
+            <div className="custom-thinking-config__section-title">{t("settings.modelWorkspace.supportedThinkingLevels")}</div>
+            <div className="custom-thinking-level-options">
+              {THINKING_LEVELS.map((level) => (
+                <label key={level} className="custom-thinking-level-option">
+                  <input
+                    type="checkbox"
+                    className="check-sky"
+                    checked={props.options.levels.includes(level)}
+                    disabled={props.options.levels.length === 1 && props.options.levels[0] === level}
+                    onChange={() => toggleLevel(level)}
+                  />
+                  <span>{t(`home.thinking.levelValue.${level}`)}</span>
+                </label>
+              ))}
+            </div>
+            <p className="custom-thinking-config__hint">{t("settings.modelWorkspace.supportedThinkingLevelsHint")}</p>
+          </div>
+          <Select
+            label={t("settings.modelWorkspace.defaultThinkingLevel")}
+            value={props.options.defaultLevel}
+            options={props.options.levels.map((level) => ({
+              value: level,
+              label: t(`home.thinking.levelValue.${level}`)
+            }))}
+            onValueChange={(value) => props.onChange({
+              ...props.options,
+              defaultLevel: value as ThinkingLevel
+            })}
+            className="select-control--subtle"
+          />
+        </>
+      )}
+    </fieldset>
+  );
+}
diff --git a/App/frontend/desktop/src/pages/tests/home-page.test.tsx b/App/frontend/desktop/src/pages/tests/home-page.test.tsx
index 152e84858..fb15403d8 100644
--- a/App/frontend/desktop/src/pages/tests/home-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/home-page.test.tsx
@@ -198,10 +198,13 @@ describe("HomePage", () => {
     expect(selectorSource).toContain("agentActions.pendingModelPresetUpdated");
     expect(selectorSource).toContain("AgentThinkingControl");
     expect(selectorSource).toContain("resolveThinkingConfigForModel");
+    expect(selectorSource).toContain("optionAside={(option) => (");
+    expect(selectorSource).toContain("option.value === resolved.candidateId && thinkingConfig");
     expect(selectorSource).not.toContain("localStorage");
     expect(source).not.toContain('sendMessage({ chatId: state.agent.currentChatId, content: "/model');
     expect(styles).toContain(".agent-model-selector .agent-model-selector__menu");
-    expect(styles).toContain(".agent-model-selector-with-thinking");
+    expect(styles).toContain(".agent-model-selector__menu .select-control__aside");
+    expect(styles).not.toContain(".agent-model-selector-with-thinking");
     expect(styles).toContain(".agent-thinking-control");
     expect(styles).toContain("top: calc(100% + 6px)");
     expect(styles).toContain(".agent-model-selector__configure");
diff --git a/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx
index 12f735264..3e8c75076 100644
--- a/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx
@@ -55,6 +55,95 @@ describe("ModelWorkspaceSection BYOK connection deletion", () => {
     expect(dialog?.textContent).toContain("删除配置？");
   });
 
+  it("shows the saved API Key as a masked hint when a connection is reopened", () => {
+    renderWorkspace(createSeedConfig(1));
+
+    const editButton = container.querySelector<HTMLButtonElement>('button[aria-label="编辑 openai 配置"]')!;
+    act(() => editButton.click());
+    const firstInput = container.querySelector<HTMLInputElement>('[role="dialog"] input[type="password"]')!;
+    expect(firstInput.placeholder).toBe("••••test");
+    expect(firstInput.value).toBe("");
+
+    act(() => container.querySelector<HTMLButtonElement>('[role="dialog"] button[aria-label="保存"]')!.click());
+    act(() => editButton.click());
+    const reopenedInput = container.querySelector<HTMLInputElement>('[role="dialog"] input[type="password"]')!;
+    expect(reopenedInput.placeholder).toBe("••••test");
+    expect(reopenedInput.value).toBe("");
+  });
+
+  it("edits Custom thinking and image declarations for each model independently", () => {
+    renderWorkspace(createCustomSeedConfig());
+
+    act(() => container.querySelector<HTMLButtonElement>('button[aria-label="编辑 custom 配置"]')!.click());
+    const dialog = container.querySelector<HTMLElement>('[role="dialog"]')!;
+    expect(dialog.querySelector(".custom-thinking-config")).toBeNull();
+    const modelRows = dialog.querySelectorAll(".provider-model-list__row");
+    expect(modelRows).toHaveLength(2);
+    expect(modelRows[0]?.textContent).toContain("model-a");
+    expect(modelRows[1]?.textContent).toContain("model-b");
+    expect(modelRows[0]?.textContent).not.toContain("思考");
+    expect(modelRows[1]?.textContent).not.toContain("思考");
+
+    act(() => dialog.querySelector<HTMLButtonElement>('button[aria-label="编辑模型 model-a"]')!.click());
+    expect(dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[0]?.checked).toBe(true);
+    expect(dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[1]?.checked).toBe(true);
+    expect(dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[2]?.checked).toBe(true);
+    expect(dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[3]?.checked).toBe(true);
+    expect(dialog.querySelectorAll(".custom-thinking-level-option")).toHaveLength(5);
+    act(() => dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[2]!.click());
+    expect(dialog.querySelectorAll('.custom-thinking-config__checkbox')).toHaveLength(3);
+    expect(dialog.textContent).not.toContain("默认开启思考");
+    act(() => dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[2]!.click());
+    expect(dialog.querySelectorAll('.custom-thinking-config__checkbox')).toHaveLength(4);
+    act(() => dialog.querySelector<HTMLButtonElement>(".model-editor-actions button")!.click());
+
+    act(() => dialog.querySelector<HTMLButtonElement>('button[aria-label="编辑模型 model-b"]')!.click());
+    expect(dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[0]?.checked).toBe(false);
+    expect(dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[1]?.checked).toBe(false);
+    expect(dialog.querySelectorAll('.custom-thinking-config__checkbox')).toHaveLength(2);
+    expect(dialog.querySelector(".custom-thinking-level-options")).toBeNull();
+    act(() => dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[1]!.click());
+    expect(dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[2]?.checked).toBe(false);
+    expect(dialog.textContent).not.toContain("默认开启思考");
+    act(() => dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[0]!.click());
+    act(() => dialog.querySelector<HTMLButtonElement>('button[aria-label="保存模型"]')!.click());
+
+    act(() => dialog.querySelector<HTMLButtonElement>('button[aria-label="保存"]')!.click());
+    act(() => container.querySelector<HTMLButtonElement>('button[aria-label="编辑 custom 配置"]')!.click());
+    const reopened = container.querySelector<HTMLElement>('[role="dialog"]')!;
+    act(() => reopened.querySelector<HTMLButtonElement>('button[aria-label="编辑模型 model-a"]')!.click());
+    expect(reopened.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[0]?.checked).toBe(true);
+    expect(reopened.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[2]?.checked).toBe(true);
+    act(() => reopened.querySelector<HTMLButtonElement>(".model-editor-actions button")!.click());
+    act(() => reopened.querySelector<HTMLButtonElement>('button[aria-label="编辑模型 model-b"]')!.click());
+    expect(reopened.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[0]?.checked).toBe(true);
+    expect(reopened.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[1]?.checked).toBe(true);
+    expect(reopened.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[2]?.checked).toBe(false);
+    expect(reopened.textContent).not.toContain("默认开启思考");
+  });
+
+  it("hides thinking choices when the model's thinking mode is unchecked", () => {
+    renderWorkspace(createCustomSeedConfig());
+
+    act(() => container.querySelector<HTMLButtonElement>('button[aria-label="编辑 custom 配置"]')!.click());
+    const dialog = container.querySelector<HTMLElement>('[role="dialog"]')!;
+    act(() => dialog.querySelector<HTMLButtonElement>('button[aria-label="编辑模型 model-a"]')!.click());
+    const thinkingToggle = dialog.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[1]!;
+    expect(thinkingToggle.checked).toBe(true);
+
+    act(() => thinkingToggle.click());
+    expect(dialog.querySelectorAll('.custom-thinking-config__checkbox')).toHaveLength(2);
+    expect(dialog.querySelector(".custom-thinking-level-options")).toBeNull();
+    expect(dialog.textContent).not.toContain("新会话默认强度");
+    act(() => dialog.querySelector<HTMLButtonElement>('button[aria-label="保存模型"]')!.click());
+    act(() => dialog.querySelector<HTMLButtonElement>('button[aria-label="保存"]')!.click());
+    act(() => container.querySelector<HTMLButtonElement>('button[aria-label="编辑 custom 配置"]')!.click());
+    const reopened = container.querySelector<HTMLElement>('[role="dialog"]')!;
+    act(() => reopened.querySelector<HTMLButtonElement>('button[aria-label="编辑模型 model-a"]')!.click());
+    expect(reopened.querySelectorAll<HTMLInputElement>('.custom-thinking-config__checkbox')[1]?.checked).toBe(false);
+    expect(reopened.querySelector(".custom-thinking-level-options")).toBeNull();
+  });
+
   it("shows an actionable save error above the model assignment title", async () => {
     const seedConfig = createSeedConfig(1);
     const configClient = {
@@ -267,6 +356,44 @@ function createEmbeddingSeedConfig(): ModelProviderConfig {
   return seed;
 }
 
+function createCustomSeedConfig(): ModelProviderConfig {
+  const seed = createSeedConfig(1);
+  const provider = seed.catalog.providers[0]!;
+  const endpoint = provider.endpoints[0]!;
+  provider.provider = "custom";
+  endpoint.protocol = "openai-responses";
+  const first = {
+    ...provider.models[0]!,
+    provider: "custom" as const,
+    protocol: "openai-responses" as const,
+    model: "model-a",
+    custom: true,
+    thinking: {
+      switchable: true,
+      defaultEnabled: true,
+      levels: ["low", "medium", "high"] as Array<"low" | "medium" | "high">,
+      defaultLevel: "medium" as const
+    },
+    inputModalities: ["text", "image"] as Array<"text" | "image">
+  };
+  const second = {
+    ...first,
+    presetId: "preset-2",
+    model: "model-b",
+    thinking: undefined,
+    inputModalities: ["text"] as Array<"text" | "image">
+  };
+  provider.models = [first, second];
+  seed.catalog.modelAssignments.byok.agent = {
+    candidates: [first.presetId, second.presetId],
+    default: first.presetId
+  };
+  seed.catalog.effectiveCandidates.byok = [first, second];
+  seed.provider = "custom";
+  seed.model = first.model;
+  return seed;
+}
+
 function createAccountSeedConfig(): ModelProviderConfig {
   const seed = createEmbeddingSeedConfig();
   const customProvider = seed.catalog.providers[0]!;
diff --git a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
index 0fb79f27f..23763d62c 100644
--- a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
@@ -213,32 +213,23 @@ describe("自定义模型能力选择", () => {
     expect(source).toContain('className="select-control--subtle model-capability-select"');
     expect(source.match(/t\("settings\.modelWorkspace\.modelCapability"\)/g)).toHaveLength(1);
     expect(source).toContain("normalizeEditorCapabilities(entry.capabilities.map(fromCatalogCapability))");
-    expect(source).toContain("checked={editor.customThinkingEnabled}");
-    expect(source).toContain("checked={editor.customImageInput}");
-    expect(source).toContain('t("settings.modelWorkspace.customThinkingEnabledHint")');
-    expect(source).toContain('t("settings.modelWorkspace.customThinkingSwitchableHint")');
+    expect(source).toContain("checked={thinkingConfigured}");
+    expect(source).toContain('t("settings.modelWorkspace.allowThinkingOff")');
     expect(source).toContain('t("settings.modelWorkspace.customThinkingDefaultEnabledHint")');
     expect(source).toContain('t("settings.modelWorkspace.customImageInputHint")');
-    expect(source).toContain('className="custom-thinking-config__checkbox"');
+    expect(source).toContain('className="custom-thinking-config__checkbox check-sky"');
+    expect(source).toContain('className="check-sky"');
     expect(styles).toContain(".custom-thinking-config__checkbox");
-    expect(styles).toContain("cursor: pointer");
+    expect(styles).toContain('.custom-thinking-config input[type="checkbox"].check-sky:checked');
     expect(source).not.toContain('t("settings.modelWorkspace.textRoles")');
     expect(source).not.toContain('t("settings.modelWorkspace.capability.agent")');
   });
 
-  it("支持思考的说明提醒 Chat Completions 的 gpt 模型关掉思考", () => {
-    expect(zhCNMessages["settings.modelWorkspace.customThinkingEnabledHint"]).toContain(
-      "使用 Chat Completions 并且使用 gpt 模型时，请关闭支持思考，否则可能导致错误。"
-    );
-    expect(zhCNMessages["settings.modelWorkspace.customThinkingEnabledHint"]).toContain(
-      "gpt 模型建议使用 Responses 接口获得最佳体验。"
-    );
-    expect(enUSMessages["settings.modelWorkspace.customThinkingEnabledHint"]).toContain(
-      "When using Chat Completions with a GPT model, turn off Supports thinking, or the request may fail."
-    );
-    expect(enUSMessages["settings.modelWorkspace.customThinkingEnabledHint"]).toContain(
-      "GPT models should use the Responses API for the best experience."
-    );
+  it("思考模式说明区分接口默认行为与允许关闭", () => {
+    expect(zhCNMessages["settings.modelWorkspace.thinkingModeToggleHint"]).toContain("模型接口按默认行为处理");
+    expect(zhCNMessages["settings.modelWorkspace.allowThinkingOffHint"]).toContain("不勾选则思考始终开启");
+    expect(enUSMessages["settings.modelWorkspace.thinkingModeToggleHint"]).toContain("endpoint's default behavior");
+    expect(enUSMessages["settings.modelWorkspace.allowThinkingOffHint"]).toContain("thinking stays on");
   });
 });
 
@@ -943,16 +934,14 @@ describe("SettingsPageView", () => {
     expect(source).toContain("setWorkspace(createModelWorkspace(saved));");
   });
 
-  it("模型工作区连接编辑展示已保存脱敏 key，且保存不回传脱敏值", () => {
+  it("模型工作区新建时提示输入 API Key，编辑时显示已配置密钥的脱敏值", () => {
     const workspaceSource = readFileSync(fileURLToPath(new URL("../model-workspace-section.tsx", import.meta.url)), "utf8");
-    const fieldsSource = readFileSync(fileURLToPath(new URL("../api-key-form-fields.tsx", import.meta.url)), "utf8");
 
+    expect(workspaceSource).toContain('label={t("apiKey.key")}');
+    expect(workspaceSource).toContain('placeholder={t("settings.modelWorkspace.apiKeyPlaceholder")}');
     expect(workspaceSource).toContain("maskedValue={editor.connectionId && !editorProviderChanged");
     expect(workspaceSource).toContain("apiKey: editor.apiKey || undefined");
-    expect(workspaceSource).toContain("apiKeyMasked:");
-    expect(fieldsSource).toContain("const placeholder = !props.value.trim() && props.maskedValue ? props.maskedValue : props.placeholder;");
-    expect(fieldsSource).toContain("placeholder={placeholder}");
-    expect(fieldsSource).not.toContain("const showSavedSecret = !props.value.trim() && Boolean(props.maskedValue)");
+    expect(workspaceSource).toContain("apiKeyMasked: providerChanged ? undefined : existing?.apiKeyMasked");
   });
   it("设置页已移除旧内联模型保存链路，模型工作区只走 catalog API", () => {
     const source = readFileSync(settingsPageSourcePath, "utf8");
diff --git a/App/frontend/desktop/src/styles.css b/App/frontend/desktop/src/styles.css
index eff8f6dd0..f8a3bf9f4 100644
--- a/App/frontend/desktop/src/styles.css
+++ b/App/frontend/desktop/src/styles.css
@@ -861,36 +861,36 @@ body.memmy-window-fullscreen {
   transition: background var(--duration-fast), color var(--duration-fast);
 }
 
-.agent-model-selector-with-thinking {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-}
-
 .agent-thinking-control {
-  display: flex;
-  align-items: center;
-  gap: 6px;
+  max-height: min(360px, 70vh);
+  overflow-y: auto;
+  padding: 8px;
+  border: 1px solid color-mix(in srgb, var(--color-border-stone) 72%, transparent);
+  border-radius: 14px;
+  background: var(--color-background-paper);
+  box-shadow: var(--shadow-popover);
 }
 
 .thinking-toggle {
-  display: inline-flex;
+  display: flex;
+  width: 100%;
+  min-height: 38px;
   align-items: center;
-  gap: 6px;
-  height: 32px;
-  padding: 0 8px;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 8px 10px;
   border: 0;
-  border-radius: 9px;
+  border-radius: 7px;
   background: transparent;
-  color: color-mix(in srgb, var(--color-text-ink) 48%, transparent);
+  color: var(--color-text-ink);
   cursor: pointer;
   font-size: 13px;
   font-weight: 500;
+  text-align: left;
 }
 
 .thinking-toggle:hover:not(:disabled) {
-  background: color-mix(in srgb, var(--color-canvas-oat) 64%, transparent);
-  color: color-mix(in srgb, var(--color-text-ink) 78%, transparent);
+  background: color-mix(in srgb, var(--color-canvas-oat) 72%, transparent);
 }
 
 .thinking-toggle:disabled {
@@ -898,14 +898,11 @@ body.memmy-window-fullscreen {
   opacity: 0.4;
 }
 
-.thinking-toggle--on {
-  color: var(--color-action-sky);
-}
-
 .thinking-toggle__switch {
   position: relative;
-  width: 28px;
-  height: 16px;
+  width: 32px;
+  height: 18px;
+  flex: 0 0 32px;
   background: color-mix(in srgb, var(--color-text-ink) 18%, transparent);
   border-radius: 999px;
 }
@@ -918,89 +915,76 @@ body.memmy-window-fullscreen {
   position: absolute;
   top: 2px;
   left: 2px;
-  width: 12px;
-  height: 12px;
+  width: 14px;
+  height: 14px;
   background: white;
   border-radius: 50%;
   transition: transform var(--duration-fast);
 }
 
 .thinking-toggle__switch--on .thinking-toggle__switch-thumb {
-  transform: translateX(12px);
-}
-
-.thinking-level-trigger-container {
-  position: relative;
-}
-
-.thinking-level-trigger {
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-  height: 32px;
-  padding: 0 8px;
-  border: 0;
-  border-radius: 9px;
-  background: transparent;
-  color: color-mix(in srgb, var(--color-text-ink) 48%, transparent);
-  cursor: pointer;
-  font-size: 13px;
-}
-
-.thinking-level-trigger:hover:not(:disabled) {
-  background: color-mix(in srgb, var(--color-canvas-oat) 64%, transparent);
-  color: color-mix(in srgb, var(--color-text-ink) 78%, transparent);
+  transform: translateX(14px);
 }
 
 .thinking-level-picker {
-  position: absolute;
-  right: 0;
-  bottom: calc(100% + 6px);
-  z-index: 130;
-  min-width: 160px;
-  background: var(--color-background-paper, #fff);
-  border: 1px solid color-mix(in srgb, var(--color-text-ink) 12%, transparent);
-  border-radius: 8px;
-  box-shadow: 0 8px 24px color-mix(in srgb, var(--color-text-ink) 12%, transparent);
+  margin-top: 4px;
+  padding-top: 6px;
+  border-top: 1px solid color-mix(in srgb, var(--color-border-stone) 36%, transparent);
 }
 
 .thinking-level-picker__header {
-  padding: 8px 12px;
+  padding: 7px 10px;
   font-size: 12px;
   font-weight: 600;
   color: color-mix(in srgb, var(--color-text-ink) 55%, transparent);
-  border-bottom: 1px solid color-mix(in srgb, var(--color-text-ink) 10%, transparent);
 }
 
 .thinking-level-option {
-  display: block;
+  display: flex;
   width: 100%;
-  padding: 8px 12px;
+  min-height: 34px;
+  align-items: center;
+  justify-content: space-between;
+  padding: 8px 10px;
   border: 0;
-  background: none;
+  border-radius: 7px;
+  background: transparent;
+  color: var(--color-text-ink);
   text-align: left;
   cursor: pointer;
   font-size: 13px;
 }
 
-.thinking-level-option:hover {
-  background: color-mix(in srgb, var(--color-canvas-oat) 64%, transparent);
+.thinking-level-option:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--color-canvas-oat) 72%, transparent);
 }
 
 .thinking-level-option--selected {
+  background: color-mix(in srgb, var(--color-canvas-oat) 72%, transparent);
   color: var(--color-action-sky);
-  font-weight: 500;
+}
+
+.thinking-level-option:disabled {
+  cursor: not-allowed;
+  opacity: 0.4;
 }
 
 .custom-thinking-config {
   display: grid;
-  gap: 10px;
-  margin-top: 4px;
-  padding: 12px;
+  gap: 14px;
+  margin-top: 8px;
+  padding: 14px;
   border: 1px solid color-mix(in srgb, var(--color-text-ink) 12%, transparent);
   border-radius: 8px;
 }
 
+.custom-thinking-config__title {
+  padding: 0 4px;
+  color: var(--color-text-ink);
+  font-size: 13px;
+  font-weight: 600;
+}
+
 .custom-thinking-config__label {
   display: flex;
   align-items: center;
@@ -1008,29 +992,83 @@ body.memmy-window-fullscreen {
   font-size: 13px;
 }
 
+.custom-thinking-config__capabilities {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px 24px;
+}
+
 .custom-thinking-config__checkbox {
   cursor: pointer;
 }
 
-.custom-thinking-levels {
+.custom-thinking-config input[type="checkbox"].check-sky:checked {
+  background: color-mix(in srgb, var(--color-action-sky-hover) 75%, var(--color-text-ink));
+  border-color: color-mix(in srgb, var(--color-action-sky-hover) 75%, var(--color-text-ink));
+}
+
+.custom-thinking-config input[type="checkbox"].check-sky:focus-visible {
+  outline: 2px solid var(--color-action-sky-hover);
+  outline-offset: 2px;
+}
+
+.custom-thinking-config__section {
   display: grid;
-  gap: 6px;
+  gap: 8px;
 }
 
-.custom-thinking-levels__input {
-  width: 100%;
-  padding: 8px 12px;
-  border: 1px solid color-mix(in srgb, var(--color-text-ink) 12%, transparent);
-  border-radius: 6px;
+.custom-thinking-config__section-title {
+  color: var(--color-text-ink);
   font-size: 13px;
+  font-weight: 500;
 }
 
-.custom-thinking-levels__hint {
+.custom-thinking-config__hint {
   margin: 0;
   font-size: 12px;
+  line-height: 1.5;
   color: color-mix(in srgb, var(--color-text-ink) 55%, transparent);
 }
 
+.custom-thinking-level-options {
+  display: grid;
+  grid-template-columns: repeat(5, minmax(0, 1fr));
+  gap: 7px;
+}
+
+.custom-thinking-level-option {
+  display: flex;
+  min-height: 36px;
+  align-items: center;
+  gap: 6px;
+  padding: 7px 9px;
+  border: 1px solid color-mix(in srgb, var(--color-text-ink) 12%, transparent);
+  border-radius: 7px;
+  cursor: pointer;
+  font-size: 12px;
+}
+
+.custom-thinking-level-option:has(input:checked) {
+  border-color: color-mix(in srgb, var(--color-action-sky) 50%, transparent);
+  background: color-mix(in srgb, var(--color-action-sky) 8%, transparent);
+}
+
+.custom-thinking-level-option input {
+  flex: 0 0 auto;
+  margin: 0;
+}
+
+.custom-thinking-level-option:has(input:disabled) {
+  cursor: default;
+}
+
+@media (max-width: 640px) {
+  .custom-thinking-level-options {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
 .agent-model-selector {
   position: relative;
   z-index: 50;
@@ -1096,7 +1134,67 @@ body.memmy-window-fullscreen {
   width: max-content;
   min-width: 240px;
   max-width: min(320px, calc(100vw - 48px));
-  max-height: min(280px, 42vh);
+  max-height: none;
+  overflow: visible;
+}
+
+.agent-model-selector__menu .select-control__options {
+  max-height: min(224px, 42vh);
+  overflow-y: auto;
+}
+
+.agent-model-selector__menu .select-control__aside {
+  position: absolute;
+  right: 100%;
+  z-index: 130;
+  width: min(260px, calc(100vw - 48px));
+  padding-right: 8px;
+}
+
+/* Let the model's side panel cross the main pane boundary above the sidebar. */
+.sidebar-shell:has(.select-control__aside) > .app-frame-main {
+  z-index: 31;
+  overflow: visible;
+}
+
+.app-frame-main:has(.select-control__aside) > div:has(.agent-workspace-layout),
+.app-frame-main:has(.select-control__aside) .agent-workspace-layout {
+  overflow: visible;
+}
+
+@media (max-width: 880px) {
+  .agent-model-selector__menu .agent-thinking-control {
+    max-height: min(190px, 32vh);
+    padding: 6px;
+  }
+
+  .agent-model-selector__menu .thinking-toggle {
+    min-height: 34px;
+    padding: 6px 8px;
+  }
+
+  .agent-model-selector__menu .thinking-level-picker {
+    margin-top: 2px;
+    padding-top: 4px;
+  }
+
+  .agent-model-selector__menu .thinking-level-picker__header {
+    padding: 4px 8px;
+  }
+
+  .agent-model-selector__menu .thinking-level-option {
+    min-height: 30px;
+    padding: 6px 8px;
+  }
+}
+
+@media (max-width: 680px) {
+  .agent-model-selector .agent-model-selector__menu {
+    right: auto;
+    left: 0;
+    width: min(260px, calc(100vw - 32px));
+    min-width: min(240px, calc(100vw - 32px));
+  }
 }
 
 .model-provider-logo {

From f2e4f07c48b192193a4e6bbe9dbac55606838419 Mon Sep 17 00:00:00 2001
From: OpenClaw Agent <agent@openclaw.ai>
Date: Wed, 14 Oct 2026 16:02:55 +0800
Subject: [PATCH 41/85] Let external plugins participate in the agent lifecycle

Memmy needs a host-owned integration point so third-party plugins can contribute temporary model context, inspect buffered responses, and block an unverified final answer without controlling agent startup.

Load configured hook factories once per runtime, compose them with native hooks, keep iteration and finalization feedback request-only, and isolate plugin failures so the original agent flow continues.

Constraint: External plugins must not own or interrupt Memmy startup and injected context must not enter user session history
Rejected: Launch Memmy through a plugin wrapper | reverses host/plugin ownership and couples execution to one plugin
Confidence: high
Scope-risk: moderate
Directive: Keep external hook loading host-owned, fail-open, and restart-bound; preserve request-only injection isolation
Tested: npm run build; 5 focused Vitest files with 58 passing tests; git diff --check
Not-tested: Full typecheck is blocked by missing optional dependency typings; full suite has 48 unrelated environment/baseline failures with 5606 tests passing
---
 App/memmy-agent/src/config/schema.ts          |   3 +
 .../agent-runtime/external-hook-loader.ts     |  50 +++++
 .../src/core/agent-runtime/hook.ts            | 195 +++++++++++++++-
 .../src/core/agent-runtime/loop.ts            |  50 ++++-
 .../src/core/agent-runtime/runner.ts          | 128 ++++++++---
 .../tests/config/agent-hooks-config.test.ts   |  21 ++
 .../external-hook-loader.test.ts              | 123 +++++++++++
 .../core/agent-runtime/hook-composite.test.ts | 114 ++++++++++
 .../core/agent-runtime/runner-hooks.test.ts   | 208 +++++++++++++++++-
 .../runner-progress-deltas.test.ts            |  35 +++
 10 files changed, 879 insertions(+), 48 deletions(-)
 create mode 100644 App/memmy-agent/src/core/agent-runtime/external-hook-loader.ts
 create mode 100644 App/memmy-agent/tests/config/agent-hooks-config.test.ts
 create mode 100644 App/memmy-agent/tests/core/agent-runtime/external-hook-loader.test.ts

diff --git a/App/memmy-agent/src/config/schema.ts b/App/memmy-agent/src/config/schema.ts
index 9820534b8..66bed95bc 100644
--- a/App/memmy-agent/src/config/schema.ts
+++ b/App/memmy-agent/src/config/schema.ts
@@ -1168,6 +1168,7 @@ export class FileMemoryConfig extends Base {
 
 export class Config extends Base {
   app: Dict;
+  agentHooks: string[];
   agents: AgentsConfig;
   providers: ProvidersConfig;
   channels: ChannelsConfig;
@@ -1208,6 +1209,7 @@ export class Config extends Base {
     if (appUserId) {
       this.app.userId = appUserId;
     }
+    this.agentHooks = assertStringArray("agentHooks", pick(init, ["agentHooks"], []));
     this.agents =
       init.agents instanceof AgentsConfig ? init.agents : new AgentsConfig(init.agents ?? {});
     this.providers =
@@ -1456,6 +1458,7 @@ export class Config extends Base {
     delete this.app.user_id;
     this.memmyMemory.userId = appUserId ?? this.memmyMemory.userId ?? "local-user";
     const data: Dict = {
+      agentHooks: this.agentHooks,
       agents: this.agents,
       providers: this.providers,
       channels: this.channels,
diff --git a/App/memmy-agent/src/core/agent-runtime/external-hook-loader.ts b/App/memmy-agent/src/core/agent-runtime/external-hook-loader.ts
new file mode 100644
index 000000000..0c24704ac
--- /dev/null
+++ b/App/memmy-agent/src/core/agent-runtime/external-hook-loader.ts
@@ -0,0 +1,50 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  AGENT_HOOK_TIMEOUT_MS,
+  withAgentHookTimeout,
+  type AgentHook,
+} from "./hook.js";
+
+type HookFactory = () => AgentHook | Promise<AgentHook>;
+
+export async function loadExternalAgentHooks(specifiers: string[]): Promise<AgentHook[]> {
+  const hooks: AgentHook[] = [];
+  for (const specifier of specifiers) {
+    try {
+      const hook = await withAgentHookTimeout(async () => {
+        const module = await import(moduleTarget(specifier));
+        if (typeof module.default !== "function") {
+          throw new Error(`agent hook module '${specifier}' must default-export a hook factory`);
+        }
+        return (module.default as HookFactory)();
+      }, AGENT_HOOK_TIMEOUT_MS, `external agent hook '${specifier}' initialization`);
+      if (!hook || typeof hook !== "object") {
+        throw new Error(`agent hook module '${specifier}' did not return a hook`);
+      }
+      hook.reraise = false;
+      Object.defineProperty(hook, "externalHookSpecifier", {
+        configurable: false,
+        enumerable: false,
+        value: specifier,
+        writable: false,
+      });
+      hooks.push(hook);
+    } catch (error) {
+      console.error(`Unable to load external agent hook '${specifier}':`, error);
+    }
+  }
+  return hooks;
+}
+
+function moduleTarget(specifier: string): string {
+  if (specifier.startsWith("file:")) return new URL(specifier).href;
+  if (path.isAbsolute(specifier)) return pathToFileURL(specifier).href;
+  if (specifier === "~" || specifier.startsWith("~/") || specifier.startsWith("./") || specifier.startsWith("../")) {
+    throw new Error(`agent hook specifier '${specifier}' must be a package, absolute path, or file URL`);
+  }
+  if (/^[a-z][a-z\d+.-]*:/iu.test(specifier)) {
+    throw new Error(`agent hook specifier '${specifier}' must use the file URL protocol`);
+  }
+  return specifier;
+}
diff --git a/App/memmy-agent/src/core/agent-runtime/hook.ts b/App/memmy-agent/src/core/agent-runtime/hook.ts
index 375e3f5a4..ee2d82298 100644
--- a/App/memmy-agent/src/core/agent-runtime/hook.ts
+++ b/App/memmy-agent/src/core/agent-runtime/hook.ts
@@ -79,8 +79,51 @@ export type AgentToolRegistrationContext = {
   metadata: Record<string, any>;
 };
 
+export type AgentHookMessage = {
+  role: "user";
+  content: string;
+};
+
+export type LlmContentRewrite =
+  | string
+  | null
+  | {
+      content: string | null;
+      continue: true;
+    };
+
+export const AGENT_HOOK_TIMEOUT_MS = 600_000;
+export const AGENT_HOOK_SHUTDOWN_TIMEOUT_MS = 3_000;
+
+export async function withAgentHookTimeout<T>(
+  run: () => T | Promise<T>,
+  timeoutMs: number,
+  label: string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(run),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${label} timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function hookLabel(hook: AgentHook): string {
+  return String((hook as any).externalHookSpecifier ?? hook.constructor.name);
+}
+
 export class AgentHookContext {
   spec?: any;
+  workspace: string | null;
   sessionKey?: string | null;
   session?: any;
   reason?: string | null;
@@ -101,6 +144,7 @@ export class AgentHookContext {
   metadata: Record<string, any>;
   constructor(init: Partial<AgentHookContext> = {}) {
     Object.assign(this, init);
+    this.workspace = init.workspace ?? init.spec?.workspace ?? null;
     this.sessionKey = init.sessionKey ?? null;
     this.session = init.session ?? null;
     this.reason = init.reason ?? null;
@@ -133,7 +177,11 @@ export class AgentHook {
     return false;
   }
 
-  async beforeIteration(ctx: AgentHookContext): Promise<void> { void ctx; }
+  requiresBufferedLlmContent(): boolean {
+    return false;
+  }
+
+  async beforeIteration(ctx: AgentHookContext): Promise<AgentHookMessage[] | void> { void ctx; }
   async onStream(ctx: AgentHookContext, delta: string): Promise<void> { void ctx; void delta; }
   async onStreamEnd(ctx: AgentHookContext, opts: { resuming?: boolean } = {}): Promise<void> { void ctx; void opts; }
   async beforeExecuteTools(ctx: AgentHookContext): Promise<void> { void ctx; }
@@ -142,6 +190,17 @@ export class AgentHook {
   finalizeContent(ctx: AgentHookContext, content: string | null): string | null {
     return content;
   }
+  async beforeFinalize(
+    ctx: AgentHookContext,
+    candidate: string,
+  ): Promise<AgentHookMessage[] | void> {
+    void ctx;
+    void candidate;
+  }
+  async rewriteLlmContent(ctx: AgentHookContext, content: string | null): Promise<LlmContentRewrite> {
+    void ctx;
+    return content;
+  }
   onRegisterTools(ctx: AgentToolRegistrationContext): void { void ctx; }
   onBuildSystemPrompt(ctx: SystemPromptBuildContext): void { void ctx; }
   async beforeBuildSystemPrompt(ctx: AgentHookContext): Promise<void> { void ctx; }
@@ -156,6 +215,7 @@ export class AgentHook {
   async afterCompaction(ctx: AgentHookContext): Promise<void> { void ctx; }
   async subagentStart(ctx: AgentHookContext): Promise<void> { void ctx; }
   async subagentStop(ctx: AgentHookContext): Promise<void> { void ctx; }
+  async shutdown(): Promise<void> {}
 }
 
 export class CompositeHook extends AgentHook {
@@ -167,18 +227,49 @@ export class CompositeHook extends AgentHook {
   }
 
   override wantsStreaming(): boolean {
-    return this.hooks.some((hook) => hook.wantsStreaming());
+    for (const hook of this.hooks) {
+      try {
+        if (hook.wantsStreaming?.()) return true;
+      } catch (error) {
+        if (hook.reraise) throw error;
+        console.error(`AgentHook.wantsStreaming error in ${hookLabel(hook)}:`, error);
+      }
+    }
+    return false;
+  }
+
+  override requiresBufferedLlmContent(): boolean {
+    for (const hook of this.hooks) {
+      try {
+        if (hook.requiresBufferedLlmContent?.()) return true;
+      } catch (error) {
+        if (hook.reraise) throw error;
+        console.error(`AgentHook.requiresBufferedLlmContent error in ${hookLabel(hook)}:`, error);
+      }
+    }
+    return false;
+  }
+
+  private async invokeHook<T>(hook: AgentHook, methodName: string, ...args: any[]): Promise<T> {
+    const fn = (hook as any)[methodName];
+    if (typeof fn !== "function") return undefined as T;
+    const timeoutMs = methodName === "shutdown"
+      ? AGENT_HOOK_SHUTDOWN_TIMEOUT_MS
+      : AGENT_HOOK_TIMEOUT_MS;
+    return withAgentHookTimeout(
+      () => fn.apply(hook, args),
+      timeoutMs,
+      `AgentHook.${methodName}`,
+    );
   }
 
   async forEachHookSafe(methodName: string, ...args: any[]): Promise<void> {
     for (const hook of this.hooks) {
       try {
-        const fn = (hook as any)[methodName];
-        if (typeof fn !== "function") continue;
-        await fn.apply(hook, args);
+        await this.invokeHook(hook, methodName, ...args);
       } catch (error) {
         if (hook.reraise) throw error;
-        console.error(`AgentHook.${methodName} error in ${hook.constructor.name}:`, error);
+        console.error(`AgentHook.${methodName} error in ${hookLabel(hook)}:`, error);
       }
     }
   }
@@ -191,7 +282,7 @@ export class CompositeHook extends AgentHook {
         fn.apply(hook, args);
       } catch (error) {
         if (hook.reraise) throw error;
-        console.error(`AgentHook.${methodName} error in ${hook.constructor.name}:`, error);
+        console.error(`AgentHook.${methodName} error in ${hookLabel(hook)}:`, error);
       }
     }
   }
@@ -199,8 +290,24 @@ export class CompositeHook extends AgentHook {
   override async beforeRun(ctx: AgentHookContext): Promise<void> {
     await this.forEachHookSafe("beforeRun", ctx);
   }
-  override async beforeIteration(ctx: AgentHookContext): Promise<void> {
-    await this.forEachHookSafe("beforeIteration", ctx);
+  override async beforeIteration(ctx: AgentHookContext): Promise<AgentHookMessage[]> {
+    const messages: AgentHookMessage[] = [];
+    for (const hook of this.hooks) {
+      try {
+        const result = await this.invokeHook<AgentHookMessage[] | void>(hook, "beforeIteration", ctx);
+        if (result == null) continue;
+        if (!Array.isArray(result) || result.some((item) => (
+          !item || item.role !== "user" || typeof item.content !== "string"
+        ))) {
+          throw new TypeError("beforeIteration must return user messages");
+        }
+        messages.push(...result);
+      } catch (error) {
+        if (hook.reraise) throw error;
+        console.error(`AgentHook.beforeIteration error in ${hookLabel(hook)}:`, error);
+      }
+    }
+    return messages;
   }
   override async onStream(ctx: AgentHookContext, delta: string): Promise<void> {
     await this.forEachHookSafe("onStream", ctx, delta);
@@ -219,9 +326,74 @@ export class CompositeHook extends AgentHook {
   }
   override finalizeContent(ctx: AgentHookContext, content: string | null): string | null {
     let next = content;
-    for (const hook of this.hooks) next = hook.finalizeContent(ctx, next);
+    for (const hook of this.hooks) {
+      try {
+        if (typeof hook.finalizeContent === "function") {
+          next = hook.finalizeContent(ctx, next);
+        }
+      } catch (error) {
+        if (hook.reraise) throw error;
+        console.error(`AgentHook.finalizeContent error in ${hookLabel(hook)}:`, error);
+      }
+    }
     return next;
   }
+  override async beforeFinalize(
+    ctx: AgentHookContext,
+    candidate: string,
+  ): Promise<AgentHookMessage[]> {
+    const messages: AgentHookMessage[] = [];
+    for (const hook of this.hooks) {
+      try {
+        const result = await this.invokeHook<AgentHookMessage[] | void>(
+          hook,
+          "beforeFinalize",
+          ctx,
+          candidate,
+        );
+        if (result == null) continue;
+        if (!Array.isArray(result) || result.some((item) => (
+          !item || item.role !== "user" || typeof item.content !== "string"
+        ))) {
+          throw new TypeError("beforeFinalize must return user messages");
+        }
+        messages.push(...result.filter((item) => item.content.trim()));
+      } catch (error) {
+        console.error(`AgentHook.beforeFinalize error in ${hookLabel(hook)}:`, error);
+      }
+    }
+    return messages;
+  }
+  override async rewriteLlmContent(
+    ctx: AgentHookContext,
+    content: string | null,
+  ): Promise<LlmContentRewrite> {
+    let next = content;
+    let shouldContinue = false;
+    for (const hook of this.hooks) {
+      try {
+        const result = await this.invokeHook<LlmContentRewrite>(hook, "rewriteLlmContent", ctx, next);
+        if (result === undefined) continue;
+        if (
+          result !== null
+          && typeof result !== "string"
+          && (!result || result.continue !== true || (result.content !== null && typeof result.content !== "string"))
+        ) {
+          throw new TypeError("rewriteLlmContent returned an invalid result");
+        }
+        if (typeof result === "object" && result !== null) {
+          next = result.content;
+          shouldContinue = true;
+        } else {
+          next = result;
+        }
+      } catch (error) {
+        if (hook.reraise) throw error;
+        console.error(`AgentHook.rewriteLlmContent error in ${hookLabel(hook)}:`, error);
+      }
+    }
+    return shouldContinue ? { content: next, continue: true } : next;
+  }
   override onRegisterTools(ctx: AgentToolRegistrationContext): void {
     this.forEachHookSyncSafe("onRegisterTools", ctx);
   }
@@ -261,6 +433,9 @@ export class CompositeHook extends AgentHook {
   override async subagentStop(ctx: AgentHookContext): Promise<void> {
     await this.forEachHookSafe("subagentStop", ctx);
   }
+  override async shutdown(): Promise<void> {
+    await this.forEachHookSafe("shutdown");
+  }
 }
 
 export class CompositeAgentHook extends CompositeHook {}
diff --git a/App/memmy-agent/src/core/agent-runtime/loop.ts b/App/memmy-agent/src/core/agent-runtime/loop.ts
index 750a149c8..b46c226b2 100644
--- a/App/memmy-agent/src/core/agent-runtime/loop.ts
+++ b/App/memmy-agent/src/core/agent-runtime/loop.ts
@@ -119,6 +119,7 @@ import {
   type TokenCompactionStatus,
 } from "./memory.js";
 import { AgentHook, AgentHookContext, CompositeAgentHook } from "./hook.js";
+import { loadExternalAgentHooks } from "./external-hook-loader.js";
 import { SubagentManager } from "./subagent.js";
 import { AutoCompact } from "./autocompact.js";
 import { configuredModelPresets, defaultSelectionSignature, makePresetSnapshotLoader, normalizePresetName } from "./model-presets.js";
@@ -734,6 +735,9 @@ export class AgentLoop {
   unifiedSession: boolean;
   backgroundTasks: Array<Promise<any>> = [];
   extraHooks: AgentHook[] = [];
+  private externalHooks: AgentHook[] = [];
+  private externalHooksLoadPromise: Promise<void> | null = null;
+  private externalHooksShutdownPromise: Promise<void> | null = null;
   startTime: number;
   lastUsageBySession: Map<string, Record<string, number>>;
   goalRuntime: GoalRuntime;
@@ -1133,6 +1137,7 @@ export class AgentLoop {
   }
 
   async initializeRuntimeTools(): Promise<void> {
+    await this.ensureExternalHooksLoaded();
     await initializeDesktopScreenCapture();
     await this.connectMcp();
     await this.browserSessionManager.initialize();
@@ -1145,9 +1150,34 @@ export class AgentLoop {
   }
 
   async closeRuntimeTools(): Promise<void> {
-    await this.browserSessionManager.close();
-    await this.closeMcp();
-    await this.memmyMemoryIntegration.dispose?.();
+    try {
+      await this.browserSessionManager.close();
+      await this.closeMcp();
+      await this.memmyMemoryIntegration.dispose?.();
+    } finally {
+      await this.shutdownExternalHooks();
+    }
+  }
+
+  private ensureExternalHooksLoaded(): Promise<void> {
+    this.externalHooksLoadPromise ??= loadExternalAgentHooks(this.config.agentHooks)
+      .then((hooks) => {
+        this.externalHooks = hooks;
+        this.extraHooks.push(...hooks);
+      })
+      .catch((error) => {
+        console.error("Unable to initialize external agent hooks:", error);
+      });
+    return this.externalHooksLoadPromise;
+  }
+
+  private shutdownExternalHooks(): Promise<void> {
+    this.externalHooksShutdownPromise ??= new CompositeAgentHook(this.externalHooks)
+      .shutdown()
+      .catch((error) => {
+        console.error("Unable to shut down external agent hooks:", error);
+      });
+    return this.externalHooksShutdownPromise;
   }
 
   async closeBrowserSession(
@@ -1311,11 +1341,15 @@ export class AgentLoop {
     });
   }
 
-  registerHookTools(toolCtx: ToolContext, phase: string, registry: ToolRegistryInstance = this.tools): void {
+  registerHookTools(
+    toolCtx: ToolContext,
+    phase: string,
+    registry: ToolRegistryInstance = this.tools,
+  ): void {
     this.lifecycleHook().onRegisterTools({
       registry,
       toolContext: toolCtx,
-      workspace: this.workspace,
+      workspace: toolCtx.workspace ?? this.workspace,
       metadata: { phase },
     });
   }
@@ -1326,6 +1360,9 @@ export class AgentLoop {
         session,
         sessionKey,
         reason,
+        workspace: typeof session.metadata?.[WEBUI_WORKSPACE_CWD_METADATA_KEY] === "string"
+          ? session.metadata[WEBUI_WORKSPACE_CWD_METADATA_KEY]
+          : this.workspace,
         metadata: { lifecycle: "session" },
       }),
     );
@@ -1337,6 +1374,9 @@ export class AgentLoop {
         session,
         sessionKey,
         reason,
+        workspace: typeof session?.metadata?.[WEBUI_WORKSPACE_CWD_METADATA_KEY] === "string"
+          ? session.metadata[WEBUI_WORKSPACE_CWD_METADATA_KEY]
+          : this.workspace,
         metadata: { lifecycle: "session" },
       }),
     );
diff --git a/App/memmy-agent/src/core/agent-runtime/runner.ts b/App/memmy-agent/src/core/agent-runtime/runner.ts
index bfe6ef224..bb7eef3ae 100644
--- a/App/memmy-agent/src/core/agent-runtime/runner.ts
+++ b/App/memmy-agent/src/core/agent-runtime/runner.ts
@@ -11,7 +11,7 @@ import type { ActualModelContext } from "@memmy/local-api-contracts";
 import { CONTEXT_SAFETY_BUFFER_TOKENS } from "../../token-budget.js";
 import { ToolRegistry } from "./tools/registry.js";
 import type { FileMutationOutcome, ToolExecutionContext } from "./tools/base.js";
-import { AgentHook, AgentHookContext } from "./hook.js";
+import { AgentHook, AgentHookContext, type AgentHookMessage } from "./hook.js";
 import {
   buildFinalizationRetryMessage,
   buildLengthRecoveryMessage,
@@ -808,10 +808,11 @@ export class AgentRunner {
     const tools = options.toolsOverride === undefined
       ? spec.tools?.getDefinitions?.() ?? []
       : options.toolsOverride;
-    const wantsStreaming = options.forceNonStreaming ? false : hook.wantsStreaming();
+    const forceNonStreaming = options.forceNonStreaming || hook.requiresBufferedLlmContent();
+    const wantsStreaming = forceNonStreaming ? false : hook.wantsStreaming();
     const providerRuntime = provider as any;
     const wantsProgressStreaming =
-      !options.forceNonStreaming &&
+      !forceNonStreaming &&
       !wantsStreaming &&
       spec.streamProgressDeltas &&
       spec.progressCallback &&
@@ -820,7 +821,7 @@ export class AgentRunner {
         (provider.constructor as any)?.supportsProgressDeltas === true
       );
     const args = this.buildRequestArgs(spec, messages, tools);
-    const liveFileEdits = !options.forceNonStreaming && spec.progressCallback && onProgressAcceptsFileEditEvents(spec.progressCallback)
+    const liveFileEdits = !forceNonStreaming && spec.progressCallback && onProgressAcceptsFileEditEvents(spec.progressCallback)
       ? new StreamingFileEditTracker({
         workspace: spec.workspace ?? null,
         tools: spec.tools,
@@ -1495,6 +1496,8 @@ export class AgentRunner {
     spec.provider ??= this.provider;
     if (!spec.provider) throw new Error("AgentRunSpec.provider is required");
     const hook = spec.hook ?? new AgentHook();
+    const requiresBufferedLlmContent = hook.requiresBufferedLlmContent();
+    const streamsHookContent = hook.wantsStreaming() && !requiresBufferedLlmContent;
     const messages = [...spec.initialMessages];
     const toolCalls: any[] = [];
     const toolEvents: Record<string, any>[] = [];
@@ -1511,6 +1514,8 @@ export class AgentRunner {
     let lengthRecoveries = 0;
     let injectionCycles = 0;
     let hadInjections = false;
+    let pendingHookInjections: AgentHookMessage[] = [];
+    let hookContinuationExhausted = false;
     const imageTextState: TurnImageTextState = {
       nextImageNumber: 1,
       nextBatchId: 1,
@@ -1549,21 +1554,30 @@ export class AgentRunner {
           break;
         }
       }
-      let messagesForModel = this.modelContextMessages(messages, modelContextProjection);
+      const context = new AgentHookContext({ spec, messages, iteration, usage });
+      const beforeIterationInjections = await hook.beforeIteration(context) ?? [];
+      const requestOnlyInjections = [...pendingHookInjections, ...beforeIterationInjections];
+      pendingHookInjections = [];
+      let requestMessages = messages;
+      if (requestOnlyInjections.length) {
+        requestMessages = messages.map((message) => ({ ...message }));
+        AgentRunner.appendInjectedMessages(requestMessages, requestOnlyInjections);
+        console.info("AgentHook.beforeIteration injected request-only content:", requestOnlyInjections);
+      }
+      let messagesForModel = this.modelContextMessages(requestMessages, modelContextProjection);
       messagesForModel = this.prepareMessagesForModel(spec, messagesForModel, {
         toolsForRequest,
         reservedPromptTokens: 0,
       });
       messagesForModel = this.prepareImageMessages(messagesForModel, imageTextState);
 
-      const context = new AgentHookContext({ spec, messages, iteration, usage });
-      await hook.beforeIteration(context);
       response = await this.requestModelWithImagePolicy(
         spec,
         messagesForModel,
         hook,
         context,
         imageTextState,
+        { forceNonStreaming: requiresBufferedLlmContent },
       );
       const iterationUsage = this.usageDict(response.usage);
       this.accumulateUsage(usage, iterationUsage);
@@ -1600,8 +1614,25 @@ export class AgentRunner {
         context.streamedReasoning = true;
       }
 
+      const rewritten = await hook.rewriteLlmContent(context, response.content);
+      const shouldContinueFromHook = rewritten !== null && typeof rewritten === "object";
+      const rewrittenContent = shouldContinueFromHook ? (rewritten as { content: string | null }).content : rewritten;
+      response.content = rewrittenContent;
+      if (shouldContinueFromHook) {
+        if (typeof rewrittenContent === "string" && !isBlankText(rewrittenContent)) {
+          pendingHookInjections = [{ role: "user", content: rewrittenContent }];
+        }
+        if (streamsHookContent) {
+          await hook.onStreamEnd(context, { resuming: iteration + 1 < spec.maxIterations });
+        }
+        await hook.afterIteration(context);
+        if (iteration + 1 < spec.maxIterations) continue;
+        hookContinuationExhausted = true;
+        break;
+      }
+
       if (response.shouldExecuteTools && spec.tools && response.toolCalls.length) {
-        if (hook.wantsStreaming()) {
+        if (streamsHookContent) {
           await hook.onStreamEnd(context, { resuming: true });
         }
         const assistant = this.assistantMessage(response);
@@ -1702,13 +1733,13 @@ export class AgentRunner {
       if (response.finishReason !== "error" && isBlankText(clean)) {
         emptyContentRetries += 1;
         if (emptyContentRetries < MAX_EMPTY_RETRIES) {
-          if (hook.wantsStreaming()) {
+          if (streamsHookContent) {
             await hook.onStreamEnd(context, { resuming: false });
           }
           await hook.afterIteration(context);
           continue;
         }
-        if (hook.wantsStreaming()) {
+        if (streamsHookContent) {
           await hook.onStreamEnd(context, { resuming: false });
         }
         response = await this.requestFinalizationRetry(
@@ -1756,15 +1787,18 @@ export class AgentRunner {
         injectionCycles = cycles;
         if (shouldContinue) hadInjections = true;
       }
-      if (hook.wantsStreaming()) {
-        await hook.onStreamEnd(context, { resuming: shouldContinue });
-      }
       if (shouldContinue) {
+        if (streamsHookContent) {
+          await hook.onStreamEnd(context, { resuming: true });
+        }
         await hook.afterIteration(context);
         continue;
       }
 
       if (response.finishReason === "error") {
+        if (streamsHookContent) {
+          await hook.onStreamEnd(context, { resuming: false });
+        }
         finalContent = clean || spec.errorMessage || DEFAULT_ERROR_MESSAGE;
         stopReason = "error";
         error = finalContent;
@@ -1784,6 +1818,9 @@ export class AgentRunner {
       }
 
       if (isBlankText(clean)) {
+        if (streamsHookContent) {
+          await hook.onStreamEnd(context, { resuming: false });
+        }
         finalContent = EMPTY_FINAL_RESPONSE_MESSAGE;
         stopReason = "emptyFinalResponse";
         error = finalContent;
@@ -1801,6 +1838,24 @@ export class AgentRunner {
         break;
       }
 
+      const finalizeInjections = await hook.beforeFinalize?.(context, clean as string);
+      if (finalizeInjections?.length) {
+        const canContinue = iteration + 1 < spec.maxIterations;
+        if (streamsHookContent) {
+          await hook.onStreamEnd(context, { resuming: canContinue });
+        }
+        await hook.afterIteration(context);
+        if (canContinue) {
+          pendingHookInjections = finalizeInjections;
+          continue;
+        }
+        hookContinuationExhausted = true;
+        break;
+      }
+      if (streamsHookContent) {
+        await hook.onStreamEnd(context, { resuming: false });
+      }
+
       messages.push(assistant ?? buildAssistantMessage(clean));
       await this.emitCheckpoint(spec, {
         phase: "finalResponse",
@@ -1826,7 +1881,7 @@ export class AgentRunner {
           strip: true,
           maxIterations: spec.maxIterations,
         });
-      if (spec.maxIterationsFinalPrompt) {
+      if (spec.maxIterationsFinalPrompt && !hookContinuationExhausted) {
         spec.onMaxFinalizationStarting?.();
         const reservedPromptTokens = estimateMessageTokens({
           role: "user",
@@ -1884,19 +1939,6 @@ export class AgentRunner {
               finalContent = "Error: task cancelled";
               stopReason = "cancelled";
               error = finalContent;
-            } else if (response.finishReason === "error" && AgentRunner.terminalImageError(response)) {
-              const [, cleanedContent] = extractReasoning(
-                response.reasoningContent,
-                response.thinkingBlocks,
-                response.content,
-              );
-              response.content = cleanedContent;
-              finalContent = hook.finalizeContent(context, response.content)
-                || spec.errorMessage
-                || DEFAULT_ERROR_MESSAGE;
-              stopReason = "error";
-              error = finalContent;
-              AgentRunner.appendModelErrorPlaceholder(messages);
             } else {
               const [, cleanedContent] = extractReasoning(
                 response.reasoningContent,
@@ -1904,11 +1946,33 @@ export class AgentRunner {
                 response.content,
               );
               response.content = cleanedContent;
-              const clean = hook.finalizeContent(context, response.content);
-              finalContent = response.finishReason !== "error" && !isBlankText(clean)
-                ? clean
-                : fallback;
-              AgentRunner.appendFinalMessage(messages, finalContent);
+              context.response = response;
+              context.toolCalls = [...response.toolCalls];
+              const finalRewrite = await hook.rewriteLlmContent(context, response.content);
+              const continueFromFinalization = finalRewrite !== null && typeof finalRewrite === "object";
+              response.content = continueFromFinalization
+                ? (finalRewrite as { content: string | null }).content
+                : finalRewrite;
+              if (continueFromFinalization) {
+                finalContent = fallback;
+                AgentRunner.appendFinalMessage(messages, finalContent);
+              } else if (response.finishReason === "error" && AgentRunner.terminalImageError(response)) {
+                finalContent = hook.finalizeContent(context, response.content)
+                  || spec.errorMessage
+                  || DEFAULT_ERROR_MESSAGE;
+                stopReason = "error";
+                error = finalContent;
+                AgentRunner.appendModelErrorPlaceholder(messages);
+              } else {
+                const clean = hook.finalizeContent(context, response.content);
+                const finalizeInjections = response.finishReason !== "error" && !isBlankText(clean)
+                  ? await hook.beforeFinalize?.(context, clean as string)
+                  : [];
+                finalContent = finalizeInjections?.length || response.finishReason === "error" || isBlankText(clean)
+                  ? fallback
+                  : clean;
+                AgentRunner.appendFinalMessage(messages, finalContent);
+              }
             }
           } catch (requestError) {
             if (isAbortError(requestError) || spec.abortSignal?.aborted) {
diff --git a/App/memmy-agent/tests/config/agent-hooks-config.test.ts b/App/memmy-agent/tests/config/agent-hooks-config.test.ts
new file mode 100644
index 000000000..2b77b1f57
--- /dev/null
+++ b/App/memmy-agent/tests/config/agent-hooks-config.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { Config, ValueError } from "../../src/config/schema.js";
+
+describe("agentHooks config", () => {
+  it("defaults to an empty list and round-trips configured specifiers", () => {
+    expect(new Config().agentHooks).toEqual([]);
+
+    const config = new Config({
+      agentHooks: ["@memmy/example-hook", "file:///opt/memmy/example-hook.js"],
+    });
+
+    expect(config.toObject().agentHooks).toEqual([
+      "@memmy/example-hook",
+      "file:///opt/memmy/example-hook.js",
+    ]);
+  });
+
+  it("rejects non-string entries", () => {
+    expect(() => new Config({ agentHooks: ["valid", 42] })).toThrow(ValueError);
+  });
+});
diff --git a/App/memmy-agent/tests/core/agent-runtime/external-hook-loader.test.ts b/App/memmy-agent/tests/core/agent-runtime/external-hook-loader.test.ts
new file mode 100644
index 000000000..fc655fd5d
--- /dev/null
+++ b/App/memmy-agent/tests/core/agent-runtime/external-hook-loader.test.ts
@@ -0,0 +1,123 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Config } from "../../../src/config/schema.js";
+import { AgentLoop } from "../../../src/core/agent-runtime/loop.js";
+import { loadExternalAgentHooks } from "../../../src/core/agent-runtime/external-hook-loader.js";
+
+const roots: string[] = [];
+
+afterEach(() => {
+  vi.useRealTimers();
+  for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe("external agent hook loader", () => {
+  it("loads configured hook factories without host arguments", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "memmy-agent-hook-"));
+    roots.push(root);
+    const pluginPath = path.join(root, "plugin.mjs");
+    fs.writeFileSync(pluginPath, [
+      "export default async (...args) => ({",
+      "  argsLength: args.length,",
+      "  reraise: true,",
+      "  async beforeIteration() {},",
+      "});",
+    ].join("\n"));
+
+    const hooks = await loadExternalAgentHooks([pathToFileURL(pluginPath).href]);
+
+    expect(hooks).toHaveLength(1);
+    expect((hooks[0] as unknown as { argsLength: number }).argsLength).toBe(0);
+    expect(hooks[0]?.reraise).toBe(false);
+  });
+
+  it("skips modules without a default hook factory", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "memmy-agent-hook-"));
+    roots.push(root);
+    const pluginPath = path.join(root, "plugin.mjs");
+    fs.writeFileSync(pluginPath, "export const value = 1;\n");
+    await expect(loadExternalAgentHooks([pathToFileURL(pluginPath).href])).resolves.toEqual([]);
+  });
+
+  it("continues loading after a module fails", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "memmy-agent-hook-"));
+    roots.push(root);
+    const firstPluginPath = path.join(root, "first-plugin.mjs");
+    const invalidPluginPath = path.join(root, "invalid-plugin.mjs");
+    const lastPluginPath = path.join(root, "last-plugin.mjs");
+    fs.writeFileSync(firstPluginPath, [
+      "export default () => ({",
+      '  id: "first",',
+      "});",
+    ].join("\n"));
+    fs.writeFileSync(invalidPluginPath, "export const value = 1;\n");
+    fs.writeFileSync(lastPluginPath, 'export default () => ({ id: "last" });\n');
+
+    const hooks = await loadExternalAgentHooks([
+      pathToFileURL(firstPluginPath).href,
+      pathToFileURL(invalidPluginPath).href,
+      lastPluginPath,
+    ]);
+
+    expect(hooks.map((hook) => (hook as unknown as { id: string }).id)).toEqual(["first", "last"]);
+  });
+
+  it("rejects relative and home-relative specifiers without failing the batch", async () => {
+    await expect(loadExternalAgentHooks(["./plugin.mjs", "../plugin.mjs", "~/plugin.mjs"]))
+      .resolves.toEqual([]);
+  });
+
+  it("rejects URL protocols other than file", async () => {
+    await expect(loadExternalAgentHooks([
+      "data:text/javascript,export default () => ({})",
+      "node:fs",
+    ])).resolves.toEqual([]);
+  });
+
+  it("times out hook initialization without blocking the batch", async () => {
+    vi.useFakeTimers();
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "memmy-agent-hook-"));
+    roots.push(root);
+    const pluginPath = path.join(root, "plugin.mjs");
+    fs.writeFileSync(pluginPath, "export default () => new Promise(() => {});\n");
+
+    const loading = loadExternalAgentHooks([pathToFileURL(pluginPath).href]);
+    await vi.advanceTimersByTimeAsync(600_000);
+
+    await expect(loading).resolves.toEqual([]);
+  });
+
+  it("loads once and shuts down once through AgentLoop runtime lifecycle", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "memmy-agent-hook-"));
+    roots.push(root);
+    const pluginPath = path.join(root, "plugin.mjs");
+    const counterKey = `__memmyHookShutdown_${Date.now()}_${Math.random()}`;
+    (globalThis as any)[counterKey] = 0;
+    fs.writeFileSync(pluginPath, [
+      "export default () => ({",
+      '  id: "external",',
+      `  async shutdown() { globalThis[${JSON.stringify(counterKey)}] += 1; },`,
+      "});",
+    ].join("\n"));
+    const loop = new AgentLoop({
+      config: new Config({
+        agentHooks: [pathToFileURL(pluginPath).href],
+        agents: { defaults: { workspace: root } },
+      }),
+      workspace: root,
+      provider: { getDefaultModel: () => "test", generation: { maxTokens: 1024 } } as any,
+    });
+
+    await (loop as any).ensureExternalHooksLoaded();
+    await (loop as any).ensureExternalHooksLoaded();
+    expect(loop.extraHooks.filter((hook: any) => hook.id === "external")).toHaveLength(1);
+
+    await (loop as any).shutdownExternalHooks();
+    await (loop as any).shutdownExternalHooks();
+    expect((globalThis as any)[counterKey]).toBe(1);
+    delete (globalThis as any)[counterKey];
+  });
+});
diff --git a/App/memmy-agent/tests/core/agent-runtime/hook-composite.test.ts b/App/memmy-agent/tests/core/agent-runtime/hook-composite.test.ts
index a6891727e..d5709e749 100644
--- a/App/memmy-agent/tests/core/agent-runtime/hook-composite.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/hook-composite.test.ts
@@ -45,6 +45,7 @@ class StaticTool extends Tool {
 }
 
 afterEach(() => {
+  vi.useRealTimers();
   vi.restoreAllMocks();
   for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
 });
@@ -72,6 +73,109 @@ describe("CompositeHook", () => {
     expect(calls).toEqual(["A:0", "B:0"]);
   });
 
+  it("collects beforeIteration messages in hook order", async () => {
+    class H extends AgentHook {
+      override async beforeIteration() {
+        return [{ role: "user" as const, content: "first" }];
+      }
+    }
+    class H2 extends AgentHook {
+      override async beforeIteration() {
+        return [{ role: "user" as const, content: "second" }];
+      }
+    }
+
+    await expect(new CompositeHook([new H(), new H2()]).beforeIteration(ctx())).resolves.toEqual([
+      { role: "user", content: "first" },
+      { role: "user", content: "second" },
+    ]);
+  });
+
+  it("collects beforeFinalize messages in hook order", async () => {
+    class H extends AgentHook {
+      override async beforeFinalize() {
+        return [{ role: "user" as const, content: "first review" }];
+      }
+    }
+    class H2 extends AgentHook {
+      override async beforeFinalize() {
+        return [{ role: "user" as const, content: "second review" }];
+      }
+    }
+
+    await expect(new CompositeHook([new H(), new H2()]).beforeFinalize(ctx(), "draft"))
+      .resolves.toEqual([
+        { role: "user", content: "first review" },
+        { role: "user", content: "second review" },
+      ]);
+  });
+
+  it("isolates beforeFinalize failures and keeps later feedback", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    class BadHook extends AgentHook {
+      override async beforeFinalize(): Promise<any> {
+        throw new Error("review failed");
+      }
+    }
+    class GoodHook extends AgentHook {
+      override async beforeFinalize() {
+        return [{ role: "user" as const, content: "retry safely" }];
+      }
+    }
+
+    await expect(new CompositeHook([new BadHook(), new GoodHook()]).beforeFinalize(ctx(), "draft"))
+      .resolves.toEqual([{ role: "user", content: "retry safely" }]);
+  });
+
+  it("pipes rewritten content and keeps continuation sticky", async () => {
+    class ContinueHook extends AgentHook {
+      override async rewriteLlmContent() {
+        return { content: "review", continue: true as const };
+      }
+    }
+    class SuffixHook extends AgentHook {
+      override async rewriteLlmContent(context: AgentHookContext, content: string | null) {
+        return `${content}!`;
+      }
+    }
+
+    await expect(new CompositeHook([new ContinueHook(), new SuffixHook()])
+      .rewriteLlmContent(ctx(), "draft"))
+      .resolves.toEqual({ content: "review!", continue: true });
+  });
+
+  it("isolates synchronous failures from fail-open hooks", () => {
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    class BadHook extends AgentHook {
+      override wantsStreaming(): boolean {
+        throw new Error("broken streaming check");
+      }
+      override finalizeContent(): string | null {
+        throw new Error("broken finalizer");
+      }
+    }
+
+    const hook = new CompositeHook([new BadHook(), new AgentHook()]);
+
+    expect(hook.wantsStreaming()).toBe(false);
+    expect(hook.finalizeContent(ctx(), "answer")).toBe("answer");
+  });
+
+  it("stops waiting for a fail-open asynchronous hook after the fixed timeout", async () => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    class HangingHook extends AgentHook {
+      override async beforeRun(): Promise<void> {
+        await new Promise(() => undefined);
+      }
+    }
+    const call = new CompositeHook([new HangingHook()]).beforeRun(ctx());
+
+    await vi.advanceTimersByTimeAsync(600_000);
+
+    await expect(call).resolves.toBeUndefined();
+  });
+
   it("fans out all async methods to every hook", async () => {
     const events: string[] = [];
     class RecordingHook extends AgentHook {
@@ -308,6 +412,16 @@ describe("CompositeHook", () => {
     expect(new CompositeHook([new AgentHook()]).finalizeContent(ctx(), null)).toBeNull();
   });
 
+  it("preserves null returned by finalizeContent", () => {
+    class RemoveContent extends AgentHook {
+      override finalizeContent(): null {
+        return null;
+      }
+    }
+
+    expect(new CompositeHook([new RemoveContent()]).finalizeContent(ctx(), "answer")).toBeNull();
+  });
+
   it("orders finalizeContent as a pipeline", () => {
     const steps: string[] = [];
     class H1 extends AgentHook {
diff --git a/App/memmy-agent/tests/core/agent-runtime/runner-hooks.test.ts b/App/memmy-agent/tests/core/agent-runtime/runner-hooks.test.ts
index 8a96a8ca3..2b59555db 100644
--- a/App/memmy-agent/tests/core/agent-runtime/runner-hooks.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/runner-hooks.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { AgentHook, AgentHookContext } from "../../../src/core/agent-runtime/hook.js";
 import { AgentRunner, AgentRunSpec } from "../../../src/core/agent-runtime/runner.js";
 import { LLMResponse, ToolCallRequest } from "../../../src/providers/base.js";
@@ -10,6 +10,208 @@ class FinalHook extends AgentHook {
 }
 
 describe("AgentRunner hooks", () => {
+  it("adds beforeIteration messages only to the current model request", async () => {
+    const requests: any[][] = [];
+    const provider = {
+      chatWithRetry: async ({ messages }: any) => {
+        requests.push(messages);
+        return new LLMResponse({ content: "done" });
+      },
+    };
+    class InjectionHook extends AgentHook {
+      override async beforeIteration() {
+        return [{ role: "user" as const, content: "request-only memory" }];
+      }
+    }
+    const initial = [{ role: "user", content: "question" }];
+
+    const result = await new AgentRunner(provider as any).run(new AgentRunSpec({
+      messages: initial,
+      hook: new InjectionHook(),
+      maxIterations: 1,
+    }));
+
+    expect(requests[0]?.at(-1)?.content).toContain("request-only memory");
+    expect(initial).toEqual([{ role: "user", content: "question" }]);
+    expect(result.messages.some((message) => String(message.content).includes("request-only memory"))).toBe(false);
+    expect(result.hadInjections).toBe(false);
+  });
+
+  it("continues before executing rejected tool calls", async () => {
+    const requests: any[][] = [];
+    let call = 0;
+    const provider = {
+      chatWithRetry: async ({ messages }: any) => {
+        requests.push(messages);
+        call += 1;
+        if (call === 1) {
+          return new LLMResponse({
+            content: "draft",
+            toolCalls: [new ToolCallRequest({ id: "call_1", name: "dangerous", arguments: {} })],
+          });
+        }
+        return new LLMResponse({ content: "verified" });
+      },
+    };
+    const execute = vi.fn(async () => "should not run");
+    const tools = {
+      getDefinitions: () => [],
+      get: () => null,
+      execute,
+    };
+    class VerificationHook extends AgentHook {
+      rewrites = 0;
+      override async rewriteLlmContent(context: AgentHookContext, content: string | null) {
+        this.rewrites += 1;
+        return this.rewrites === 1
+          ? { content: "revise this answer", continue: true as const }
+          : content;
+      }
+    }
+
+    const result = await new AgentRunner(provider as any).run(new AgentRunSpec({
+      messages: [{ role: "user", content: "question" }],
+      tools,
+      hook: new VerificationHook(),
+      maxIterations: 2,
+    }));
+
+    expect(result.finalContent).toBe("verified");
+    expect(execute).not.toHaveBeenCalled();
+    expect(requests[1]?.at(-1)?.content).toContain("revise this answer");
+    expect(result.messages.some((message) => String(message.content).includes("revise this answer"))).toBe(false);
+  });
+
+  it("does not run an unverified finalization request after continuation exhausts iterations", async () => {
+    const provider = {
+      chatWithRetry: vi.fn(async () => new LLMResponse({ content: "unverified draft" })),
+    };
+    class RejectingHook extends AgentHook {
+      override async rewriteLlmContent() {
+        return { content: "try again", continue: true as const };
+      }
+    }
+
+    const result = await new AgentRunner(provider as any).run(new AgentRunSpec({
+      messages: [{ role: "user", content: "question" }],
+      hook: new RejectingHook(),
+      maxIterations: 1,
+      maxIterationsFinalPrompt: "Summarize completed work.",
+    }));
+
+    expect(provider.chatWithRetry).toHaveBeenCalledTimes(1);
+    expect(result.stopReason).toBe("maxIterations");
+    expect(result.messages.some((message) => message.content === "unverified draft")).toBe(false);
+  });
+
+  it("continues from beforeFinalize with request-only feedback", async () => {
+    const requests: any[][] = [];
+    const checkpoints: string[] = [];
+    let calls = 0;
+    let afterRuns = 0;
+    const provider = {
+      chatWithRetry: async ({ messages }: any) => {
+        requests.push(structuredClone(messages));
+        calls += 1;
+        return new LLMResponse({ content: calls === 1 ? "unverified draft" : "verified answer" });
+      },
+    };
+    class StopHook extends AgentHook {
+      override requiresBufferedLlmContent(): boolean {
+        return true;
+      }
+      override async beforeFinalize(_context: AgentHookContext, candidate: string) {
+        return candidate === "unverified draft"
+          ? [{ role: "user" as const, content: "verify the page count before answering" }]
+          : [];
+      }
+      override async afterRun(): Promise<void> {
+        afterRuns += 1;
+      }
+    }
+
+    const result = await new AgentRunner(provider as any).run(new AgentRunSpec({
+      messages: [{ role: "user", content: "question" }],
+      hook: new StopHook(),
+      maxIterations: 2,
+      checkpointCallback: ({ phase }) => {
+        checkpoints.push(phase);
+      },
+    }));
+
+    expect(result.finalContent).toBe("verified answer");
+    expect(requests).toHaveLength(2);
+    expect(requests[1]?.at(-1)?.content).toContain("verify the page count before answering");
+    expect(result.messages.some((message) => String(message.content).includes("unverified draft"))).toBe(false);
+    expect(result.messages.some((message) => String(message.content).includes("verify the page count"))).toBe(false);
+    expect(checkpoints).toEqual(["finalResponse"]);
+    expect(afterRuns).toBe(1);
+  });
+
+  it("does not submit a candidate rejected by beforeFinalize when iterations are exhausted", async () => {
+    const provider = {
+      chatWithRetry: vi.fn(async () => new LLMResponse({ content: "unverified draft" })),
+    };
+    class StopHook extends AgentHook {
+      override async beforeFinalize() {
+        return [{ role: "user" as const, content: "verification failed" }];
+      }
+    }
+
+    const result = await new AgentRunner(provider as any).run(new AgentRunSpec({
+      messages: [{ role: "user", content: "question" }],
+      hook: new StopHook(),
+      maxIterations: 1,
+      maxIterationsFinalPrompt: "Summarize completed work.",
+    }));
+
+    expect(provider.chatWithRetry).toHaveBeenCalledTimes(1);
+    expect(result.stopReason).toBe("maxIterations");
+    expect(result.messages.some((message) => message.content === "unverified draft")).toBe(false);
+  });
+
+  it("checks a max-iteration finalization candidate before submitting it", async () => {
+    let calls = 0;
+    const candidates: string[] = [];
+    const provider = {
+      chatWithRetry: vi.fn(async () => {
+        calls += 1;
+        if (calls === 1) {
+          return new LLMResponse({
+            content: "working",
+            toolCalls: [new ToolCallRequest({ id: "call_1", name: "read_file", arguments: {} })],
+          });
+        }
+        return new LLMResponse({ content: "unverified summary" });
+      }),
+    };
+    const tools = {
+      getDefinitions: () => [],
+      get: () => null,
+      execute: async () => "tool result",
+    };
+    class StopHook extends AgentHook {
+      override async beforeFinalize(_context: AgentHookContext, candidate: string) {
+        candidates.push(candidate);
+        return [{ role: "user" as const, content: "verification failed" }];
+      }
+    }
+
+    const result = await new AgentRunner(provider as any).run(new AgentRunSpec({
+      messages: [{ role: "user", content: "question" }],
+      tools,
+      hook: new StopHook(),
+      maxIterations: 1,
+      maxIterationsMessage: "iteration limit reached",
+      maxIterationsFinalPrompt: "Summarize completed work.",
+    }));
+
+    expect(provider.chatWithRetry).toHaveBeenCalledTimes(2);
+    expect(candidates).toEqual(["unverified summary"]);
+    expect(result.finalContent).toBe("iteration limit reached");
+    expect(result.messages.some((message) => message.content === "unverified summary")).toBe(false);
+  });
+
   it("lets hooks finalize assistant content", async () => {
     const provider = { chatWithRetry: async () => new LLMResponse({ content: "done" }) };
     const result = await new AgentRunner(provider as any).run(new AgentRunSpec({ messages: [], hook: new FinalHook() }));
@@ -58,6 +260,9 @@ describe("AgentRunner hooks", () => {
         events.push(["finalizeContent", context.iteration, content]);
         return content?.toUpperCase() ?? content;
       }
+      override async beforeFinalize(context: AgentHookContext, candidate: string) {
+        events.push(["beforeFinalize", context.iteration, candidate]);
+      }
     }
 
     const result = await new AgentRunner(provider as any).run(new AgentRunSpec({
@@ -75,6 +280,7 @@ describe("AgentRunner hooks", () => {
       ["afterIteration", 0, null, ["tool result"], [{ name: "list_dir", status: "ok", detail: "tool result" }], null],
       ["beforeIteration", 1],
       ["finalizeContent", 1, "done"],
+      ["beforeFinalize", 1, "DONE"],
       ["afterIteration", 1, "DONE", [], [], "completed"],
     ]);
   });
diff --git a/App/memmy-agent/tests/core/agent-runtime/runner-progress-deltas.test.ts b/App/memmy-agent/tests/core/agent-runtime/runner-progress-deltas.test.ts
index a8e3abe0e..5e8311209 100644
--- a/App/memmy-agent/tests/core/agent-runtime/runner-progress-deltas.test.ts
+++ b/App/memmy-agent/tests/core/agent-runtime/runner-progress-deltas.test.ts
@@ -42,6 +42,41 @@ afterEach(() => {
 });
 
 describe("AgentRunner progress deltas", () => {
+  it("buffers provider output when a hook requires complete content", async () => {
+    const provider = {
+      supportsProgressDeltas: true,
+      chatStreamWithRetry: vi.fn(),
+      chatWithRetry: vi.fn(async () => new LLMResponse({ content: "done", toolCalls: [], usage: {} })),
+    };
+    const progress = withProgressCapabilities(vi.fn(), { reasoning: true });
+    const hook = {
+      requiresBufferedLlmContent: vi.fn(() => true),
+      wantsStreaming: () => true,
+      beforeRun: vi.fn(),
+      beforeIteration: vi.fn(),
+      rewriteLlmContent: vi.fn(async (_context: AgentHookContext, content: string | null) => content),
+      finalizeContent: (_context: AgentHookContext, content: string | null) => content,
+      afterIteration: vi.fn(),
+      afterRun: vi.fn(),
+    } as any;
+
+    const result = await new AgentRunner(provider as any).run(new AgentRunSpec({
+      messages: [{ role: "user", content: "question" }],
+      provider: provider as any,
+      tools: toolRegistry([], async () => "ok"),
+      model: "test-model",
+      maxIterations: 1,
+      progressCallback: progress,
+      hook,
+    }));
+
+    expect(result.finalContent).toBe("done");
+    expect(provider.chatWithRetry).toHaveBeenCalledTimes(1);
+    expect(provider.chatStreamWithRetry).not.toHaveBeenCalled();
+    expect(progress).not.toHaveBeenCalled();
+    expect(hook.requiresBufferedLlmContent).toHaveBeenCalledOnce();
+  });
+
   it("streams only visible incremental content after stripping thinking blocks", async () => {
     const deltas: string[] = [];
     const hook = new AgentProgressHook(null, (delta) => {

From 4753a6bb8032f7318247e7ac4480c586f702fdbf Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Wed, 14 Oct 2026 16:29:26 +0800
Subject: [PATCH 42/85] feat: build and verify runtime artifacts for all
 platforms

---
 .github/workflows/runtime-artifacts.yml       | 93 +++++++++++++++++++
 .../shared/collect-runtime-artifacts.mjs      | 39 ++++++++
 .../shared/verify-runtime-artifacts.mjs       | 78 ++++++++++++++++
 tests/runtime-artifacts.test.mjs              | 43 +++++++++
 4 files changed, 253 insertions(+)
 create mode 100644 .github/workflows/runtime-artifacts.yml
 create mode 100644 scripts/internal/shared/collect-runtime-artifacts.mjs
 create mode 100644 scripts/internal/shared/verify-runtime-artifacts.mjs
 create mode 100644 tests/runtime-artifacts.test.mjs

diff --git a/.github/workflows/runtime-artifacts.yml b/.github/workflows/runtime-artifacts.yml
new file mode 100644
index 000000000..8129087cb
--- /dev/null
+++ b/.github/workflows/runtime-artifacts.yml
@@ -0,0 +1,93 @@
+name: Agent and Memory runtime artifacts
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [zy_runtime_artifacts]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: darwin-arm64
+            runner: macos-14
+            arch: arm64
+          - target: darwin-x64
+            runner: macos-15-intel
+            arch: x64
+          - target: linux-arm64
+            runner: ubuntu-24.04-arm
+            arch: arm64
+          - target: linux-x64
+            runner: ubuntu-24.04
+            arch: x64
+          - target: windows-arm64
+            runner: windows-11-arm
+            arch: arm64
+          - target: windows-x64
+            runner: windows-2025
+            arch: x64
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 45
+    defaults:
+      run:
+        shell: bash
+    env:
+      COPYFILE_DISABLE: '1'
+      PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '1'
+      ELECTRON_SKIP_BINARY_DOWNLOAD: '1'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 26.0.0
+          architecture: ${{ matrix.arch }}
+          cache: npm
+      - name: Install build dependencies
+        run: |
+          npm ci --no-audit --no-fund
+          npm --prefix App/memmy-agent install --ignore-scripts --no-audit --no-fund
+      - name: Build Agent runtime
+        run: npm run agent:runtime:package -- --target "${{ matrix.target }}" --output "$RUNNER_TEMP/runtime-artifacts"
+      - name: Build Memory runtime
+        run: npm run runtime:package -w @memmy/memory -- --target "${{ matrix.target }}" --output "$RUNNER_TEMP/runtime-artifacts"
+      - name: Verify unpacked runtimes and native dependencies
+        run: node scripts/internal/shared/verify-runtime-artifacts.mjs "$RUNNER_TEMP/runtime-artifacts" "${{ matrix.target }}"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: runtimes-${{ matrix.target }}
+          path: ${{ runner.temp }}/runtime-artifacts/*
+          if-no-files-found: error
+          compression-level: 0
+          retention-days: 14
+
+  collect:
+    needs: build
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 26.0.0
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: runtimes-*
+          path: runtime-input
+      - name: Collect all twelve archives with checksums
+        run: node scripts/internal/shared/collect-runtime-artifacts.mjs runtime-input runtime-output
+      - uses: actions/upload-artifact@v4
+        with:
+          name: all-platform-runtimes
+          path: runtime-output/*
+          if-no-files-found: error
+          compression-level: 0
+          retention-days: 14
diff --git a/scripts/internal/shared/collect-runtime-artifacts.mjs b/scripts/internal/shared/collect-runtime-artifacts.mjs
new file mode 100644
index 000000000..6bf5e513f
--- /dev/null
+++ b/scripts/internal/shared/collect-runtime-artifacts.mjs
@@ -0,0 +1,39 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const [input, output] = process.argv.slice(2).map((value) => resolve(value));
+if (!input || !output || input === output) throw new Error("Usage: collect-runtime-artifacts.mjs <input-directory> <output-directory>");
+const targets = ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "windows-arm64", "windows-x64"];
+const manifest = { sourceCommit: process.env.GITHUB_SHA ?? null, nodeVersion: process.versions.node, nodeAbi: process.versions.modules, runtimes: {} };
+const checksums = [];
+await mkdir(output, { recursive: true });
+for (const kind of ["agent", "memory"]) {
+  const packageFile = kind === "agent" ? "App/memmy-agent/package.json" : "Memory/package.json";
+  const version = JSON.parse(await readFile(join(repo, packageFile))).version;
+  const assets = {};
+  for (const target of targets) {
+    const root = join(input, `runtimes-${target}`);
+    const metadataFile = kind === "agent" ? `agent-release-${target}.json` : "memory-release.json";
+    const metadata = JSON.parse(await readFile(join(root, metadataFile)));
+    const asset = metadata.assets?.[target];
+    const name = `memmy-${kind}-runtime-${version}-${target}.${kind === "agent" ? "tgz" : "tar.gz"}`;
+    if (metadata.version !== version || asset?.name !== name) throw new Error(`Invalid ${kind} release metadata for ${target}`);
+    const file = join(root, name);
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(file)) hash.update(chunk);
+    const sha256 = hash.digest("hex");
+    const size = (await stat(file)).size;
+    if (asset.sha256 !== sha256 || asset.size !== size) throw new Error(`Checksum or size mismatch: ${name}`);
+    await cp(file, join(output, name));
+    assets[target] = { name, sha256, size };
+    checksums.push(`${sha256}  ${name}`);
+  }
+  manifest.runtimes[kind] = { version, assets };
+}
+await writeFile(join(output, "runtime-artifacts.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+await writeFile(join(output, "SHA256SUMS"), `${checksums.sort().join("\n")}\n`);
+console.log(`Collected ${checksums.length} verified runtime archives at ${output}`);
diff --git a/scripts/internal/shared/verify-runtime-artifacts.mjs b/scripts/internal/shared/verify-runtime-artifacts.mjs
new file mode 100644
index 000000000..80cedf5e3
--- /dev/null
+++ b/scripts/internal/shared/verify-runtime-artifacts.mjs
@@ -0,0 +1,78 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const directory = resolve(process.argv[2]);
+const target = process.argv[3];
+const hostTarget = `${process.platform === "win32" ? "windows" : process.platform}-${process.arch}`;
+if (target !== hostTarget) throw new Error(`Expected ${target}, running on ${hostTarget}`);
+const agentVersion = JSON.parse(await readFile(join(repo, "App/memmy-agent/package.json"))).version;
+const memoryVersion = JSON.parse(await readFile(join(repo, "Memory/package.json"))).version;
+const root = await mkdtemp(join(tmpdir(), "runtime-artifact-check-"));
+let service;
+let serviceExit;
+let logs = "";
+try {
+  for (const [kind, version, extension] of [["agent", agentVersion, "tgz"], ["memory", memoryVersion, "tar.gz"]]) {
+    await mkdir(join(root, kind));
+    run("tar", ["-xzf", join(directory, `memmy-${kind}-runtime-${version}-${target}.${extension}`), "-C", join(root, kind)]);
+  }
+  const agentRoot = join(root, "agent/package");
+  const agent = JSON.parse(await readFile(join(agentRoot, "agent-runtime.json")));
+  if (agent.target !== target || agent.version !== agentVersion || agent.nodeAbi !== process.versions.modules) {
+    throw new Error("Agent runtime metadata does not match the runner");
+  }
+  if (run(process.execPath, [join(agentRoot, "dist/main.js"), "--version"]).trim() !== agentVersion) {
+    throw new Error("Agent runtime version check failed");
+  }
+  for (const packageRoot of [agentRoot, join(root, "memory")]) {
+    const require = createRequire(join(packageRoot, "package.json"));
+    const Database = require("better-sqlite3");
+    const database = new Database(":memory:");
+    if (packageRoot.endsWith("memory")) require("sqlite-vec").load(database);
+    database.prepare("SELECT 1").get();
+    database.close();
+  }
+  const socket = createServer();
+  await new Promise((resolvePort, reject) => { socket.once("error", reject); socket.listen(0, "127.0.0.1", resolvePort); });
+  const port = socket.address().port;
+  await new Promise((done) => socket.close(done));
+  const config = join(root, "config.json");
+  await writeFile(config, JSON.stringify({ storage: { mode: "local", backend: "sqlite", sqlitePath: join(root, "memory.sqlite") }, agentAccess: { autoScanKnownAgents: false, watchFileChanges: false, autoInjectSkill: false } }));
+  service = spawn(process.execPath, [join(root, "memory/dist/src/server/index.js"), "--config", config, "--port", String(port)], {
+    cwd: root, env: { ...process.env, MEMMY_MEMORY_HOME: join(root, "home"), MEMORY_SERVICE_HOME: join(root, "home") }, stdio: ["ignore", "pipe", "pipe"]
+  });
+  serviceExit = new Promise((done) => service.once("close", done));
+  service.on("error", (error) => { logs += String(error); });
+  for (const stream of [service.stdout, service.stderr]) stream.on("data", (chunk) => { logs = (logs + chunk).slice(-8000); });
+  let healthy = false;
+  for (let attempt = 0; attempt < 100; attempt++) {
+    if (service.exitCode !== null) break;
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/v1/health`, { signal: AbortSignal.timeout(1000) });
+      if (response.ok) { healthy = true; break; }
+    } catch {}
+    await delay(200);
+  }
+  if (!healthy) throw new Error(`Memory runtime failed health check: ${logs}`);
+  console.log(`Verified Agent ${agentVersion}, Memory ${memoryVersion}, target ${target}, Node ABI ${process.versions.modules}`);
+} finally {
+  if (service) {
+    service.kill();
+    await Promise.race([serviceExit, delay(3000)]);
+    if (service.exitCode === null) { service.kill("SIGKILL"); await serviceExit; }
+  }
+  await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, { encoding: "utf8", timeout: 60_000, env: { ...process.env, COPYFILE_DISABLE: "1" } });
+  if (result.status !== 0) throw new Error(`${command} failed: ${result.error ?? result.stderr}`);
+  return result.stdout;
+}
diff --git a/tests/runtime-artifacts.test.mjs b/tests/runtime-artifacts.test.mjs
new file mode 100644
index 000000000..634b9d219
--- /dev/null
+++ b/tests/runtime-artifacts.test.mjs
@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach, expect, it } from "vitest";
+import YAML from "yaml";
+
+const root = resolve(import.meta.dirname, "..");
+const collector = join(root, "scripts/internal/shared/collect-runtime-artifacts.mjs");
+const workflow = YAML.parse(await readFile(join(root, ".github/workflows/runtime-artifacts.yml"), "utf8"));
+const roots = [];
+afterEach(async () => { for (const directory of roots.splice(0)) await rm(directory, { recursive: true, force: true }); });
+
+it("collects all target artifacts and rejects corrupted downloads", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "runtime-artifact-test-"));
+  roots.push(directory);
+  const targets = workflow.jobs.build.strategy.matrix.include.map((entry) => entry.target);
+  expect(new Set(targets)).toEqual(new Set(["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "windows-arm64", "windows-x64"]));
+  let corrupted;
+  for (const target of targets) {
+    const input = join(directory, "input", `runtimes-${target}`);
+    await mkdir(input, { recursive: true });
+    for (const kind of ["agent", "memory"]) {
+      const manifestPath = kind === "agent" ? "App/memmy-agent/package.json" : "Memory/package.json";
+      const version = JSON.parse(await readFile(join(root, manifestPath))).version;
+      const name = `memmy-${kind}-runtime-${version}-${target}.${kind === "agent" ? "tgz" : "tar.gz"}`;
+      const bytes = Buffer.from(`${kind}:${target}`);
+      corrupted = join(input, name);
+      await writeFile(corrupted, bytes);
+      const metadata = { version, assets: { [target]: { name, size: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") } } };
+      await writeFile(join(input, kind === "agent" ? `agent-release-${target}.json` : "memory-release.json"), JSON.stringify(metadata));
+    }
+  }
+  const args = [collector, join(directory, "input"), join(directory, "output")];
+  execFileSync(process.execPath, args);
+  expect((await readdir(join(directory, "output"))).length).toBe(14);
+  const manifest = JSON.parse(await readFile(join(directory, "output/runtime-artifacts.json")));
+  expect(Object.keys(manifest.runtimes.agent.assets)).toHaveLength(6);
+  expect(Object.keys(manifest.runtimes.memory.assets)).toHaveLength(6);
+  await writeFile(corrupted, "corrupted");
+  expect(() => execFileSync(process.execPath, args, { stdio: "pipe" })).toThrow();
+});

From 7ec2e5ec56ea590ea47028c4f50cdd614466fd13 Mon Sep 17 00:00:00 2001
From: OpenClaw Agent <agent@openclaw.ai>
Date: Wed, 14 Oct 2026 17:37:32 +0800
Subject: [PATCH 43/85] Keep installed Memmy CLI directly executable

The npm package assembly copies the compiled distribution into a staging directory where the entrypoint mode is not guaranteed to remain executable. Explicitly restore mode 0755 after the copy so global npm bin links can invoke Memmy without a wrapper.

Constraint: The npm bin target must be executable after package staging on Linux
Rejected: Rely on source file mode preservation | recursive copy does not make the packaging invariant explicit
Confidence: high
Scope-risk: narrow
Directive: Keep the executable-bit assertion in packaging verification when changing the CLI entrypoint
Tested: npm run package:npm; packaged dist/main.js mode is 755; packaged CLI --version succeeds; git diff --check
Not-tested: Cross-platform npm installation outside Linux
---
 App/memmy-agent/scripts/build-npm-package.mjs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/App/memmy-agent/scripts/build-npm-package.mjs b/App/memmy-agent/scripts/build-npm-package.mjs
index ef6432e0d..1436f6659 100644
--- a/App/memmy-agent/scripts/build-npm-package.mjs
+++ b/App/memmy-agent/scripts/build-npm-package.mjs
@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
@@ -54,6 +54,7 @@ const packageManifest = {
 
 await writeFile(join(outputRoot, "package.json"), `${JSON.stringify(packageManifest, null, 2)}\n`);
 await cp(join(agentRoot, "dist"), join(outputRoot, "dist"), { recursive: true });
+await chmod(join(outputRoot, "dist", "main.js"), 0o755);
 await cp(join(agentRoot, ".env.example"), join(outputRoot, ".env.example"));
 await cp(join(agentRoot, "README.md"), join(outputRoot, "README.md"));
 

From f030dbabdad5be0121d9db7d68af7707a057898a Mon Sep 17 00:00:00 2001
From: antalike <>
Date: Wed, 14 Oct 2026 17:42:29 +0800
Subject: [PATCH 44/85] feat(auth): enable Google and GitHub social login

Render the social sign-in choices again and give the cloud oauth
start/status calls a 20s floor so a slow provider redirect does not
trip the 5s default timeout.
---
 .../cloud-client/http-cloud-client.ts         |  9 +++--
 .../cloud-client/tests/cloud-client.test.ts   | 33 +++++++++++++++++++
 .../src/components/social-login-buttons.tsx   |  4 +--
 .../tests/social-login-buttons.test.tsx       |  7 ++--
 4 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/App/backend/src/adapters/outbound/cloud-client/http-cloud-client.ts b/App/backend/src/adapters/outbound/cloud-client/http-cloud-client.ts
index 6eb1c4e66..f9e5d0aed 100644
--- a/App/backend/src/adapters/outbound/cloud-client/http-cloud-client.ts
+++ b/App/backend/src/adapters/outbound/cloud-client/http-cloud-client.ts
@@ -68,6 +68,7 @@ import type {
 } from "./types.js";
 
 const DEFAULT_TIMEOUT_MS = 5_000;
+const CLOUD_SOCIAL_LOGIN_TIMEOUT_MS = 20_000;
 const CLOUD_COMPOSIO_ROUTER_TIMEOUT_MS = 60_000;
 const CLOUD_COMPOSIO_UNAVAILABLE_MESSAGE = "工具连接服务暂时不可用";
 const CLOUD_COMPOSIO_SERVICE_UNAVAILABLE_CODE = 60020;
@@ -147,7 +148,7 @@ export function createHttpCloudClient(options: CreateHttpCloudClientOptions = {}
       const data = await requestCloudData<Record<string, unknown>>(
         fetchImpl,
         baseUrl,
-        timeoutMs,
+        socialLoginTimeoutMs(timeoutMs),
         "/api/agentUser/oauth/start",
         {
           body: {
@@ -169,7 +170,7 @@ export function createHttpCloudClient(options: CreateHttpCloudClientOptions = {}
       const data = await requestCloudData<Record<string, unknown>>(
         fetchImpl,
         baseUrl,
-        timeoutMs,
+        socialLoginTimeoutMs(timeoutMs),
         "/api/agentUser/oauth/status",
         {
           body: { flowId: input.flowId, pollToken: input.pollToken },
@@ -532,6 +533,10 @@ async function requestCloudData<T>(
   return envelope.data as T;
 }
 
+function socialLoginTimeoutMs(timeoutMs: number): number {
+  return Math.max(timeoutMs, CLOUD_SOCIAL_LOGIN_TIMEOUT_MS);
+}
+
 function normalizeAgentRegion(value: string | undefined): "cn" | "intl" {
   return value?.trim().toLowerCase() === "intl" ? "intl" : "cn";
 }
diff --git a/App/backend/src/adapters/outbound/cloud-client/tests/cloud-client.test.ts b/App/backend/src/adapters/outbound/cloud-client/tests/cloud-client.test.ts
index 498655008..ffea27e3f 100644
--- a/App/backend/src/adapters/outbound/cloud-client/tests/cloud-client.test.ts
+++ b/App/backend/src/adapters/outbound/cloud-client/tests/cloud-client.test.ts
@@ -222,6 +222,39 @@ describe("cloud client", () => {
     ]);
   });
 
+  it("keeps waiting for Google login after the default cloud timeout", async () => {
+    server = createServer((_request, response) => {
+      setTimeout(() => {
+        sendJson(response, {
+          code: 0,
+          message: "ok",
+          data: {
+            flowId: "social-flow-id-0001",
+            pollToken: "social-poll-token-0000000000000001",
+            authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth?state=opaque-state",
+            expiresInSec: 600,
+            pollIntervalSec: 2
+          }
+        });
+      }, 1_500);
+    });
+    await listen(server);
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Mock cloud server did not bind");
+    const client = createHttpCloudClient({
+      baseUrl: `http://127.0.0.1:${address.port}`,
+      timeoutMs: 200
+    });
+
+    const start = await client.startSocialLogin({
+      provider: "google",
+      locale: "en",
+      loginSource: "Memmy"
+    });
+
+    expect(start.authorizationUrl).toContain("https://accounts.google.com/");
+  });
+
   it("rejects a social-login authorization URL outside the provider allowlist", async () => {
     server = createServer((_request, response) => {
       sendJson(response, {
diff --git a/App/frontend/desktop/src/components/social-login-buttons.tsx b/App/frontend/desktop/src/components/social-login-buttons.tsx
index 45bdd7e46..5b3ce1acc 100644
--- a/App/frontend/desktop/src/components/social-login-buttons.tsx
+++ b/App/frontend/desktop/src/components/social-login-buttons.tsx
@@ -3,9 +3,7 @@ import type { SocialLoginProvider } from "@memmy/local-api-contracts";
 import type { ReactNode } from "react";
 import { useTranslation } from "../i18n/use-translation.js";
 
-// Keep the integration code available, but do not render social login until the
-// production providers are ready to be exposed again.
-const SOCIAL_LOGIN_BUTTONS_ENABLED = false;
+const SOCIAL_LOGIN_BUTTONS_ENABLED = true;
 
 export interface SocialLoginButtonsProps {
   pendingProvider: SocialLoginProvider | null;
diff --git a/App/frontend/desktop/src/components/tests/social-login-buttons.test.tsx b/App/frontend/desktop/src/components/tests/social-login-buttons.test.tsx
index 909a562a0..6cd8aef10 100644
--- a/App/frontend/desktop/src/components/tests/social-login-buttons.test.tsx
+++ b/App/frontend/desktop/src/components/tests/social-login-buttons.test.tsx
@@ -4,7 +4,7 @@ import { I18nProvider } from "../../i18n/i18n-provider.js";
 import { SocialLoginButtons } from "../social-login-buttons.js";
 
 describe("SocialLoginButtons", () => {
-  it("does not render social login choices while the feature is disabled", () => {
+  it("renders Google and GitHub sign-in choices", () => {
     const onLogin = vi.fn();
     const html = renderToString(
       <I18nProvider language="en-US">
@@ -12,9 +12,8 @@ describe("SocialLoginButtons", () => {
       </I18nProvider>
     );
 
-    expect(html).toBe("");
-    expect(html).not.toContain("Continue with Google");
-    expect(html).not.toContain("Continue with GitHub");
+    expect(html).toContain("Continue with Google");
+    expect(html).toContain("Continue with GitHub");
     expect(onLogin).not.toHaveBeenCalled();
   });
 });

From 374a4e5c9f119559a88674a3892563405791364c Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Wed, 14 Oct 2026 17:55:40 +0800
Subject: [PATCH 45/85] feat: build all Memory runtime platforms with one
 command

---
 .github/workflows/runtime-artifacts.yml       | 24 ++++---
 Memory/package.json                           |  1 +
 package.json                                  |  1 +
 scripts/internal/shared/build-memory-all.mjs  | 69 +++++++++++++++++++
 .../shared/collect-runtime-artifacts.mjs      |  8 ++-
 .../shared/verify-runtime-artifacts.mjs       | 24 ++++---
 tests/runtime-artifacts.test.mjs              | 62 ++++++++++++++++-
 7 files changed, 169 insertions(+), 20 deletions(-)
 create mode 100644 scripts/internal/shared/build-memory-all.mjs

diff --git a/.github/workflows/runtime-artifacts.yml b/.github/workflows/runtime-artifacts.yml
index 8129087cb..7854d5629 100644
--- a/.github/workflows/runtime-artifacts.yml
+++ b/.github/workflows/runtime-artifacts.yml
@@ -1,10 +1,16 @@
 name: Agent and Memory runtime artifacts
+run-name: runtime-artifacts-${{ github.ref_name }}
 
 on:
   workflow_dispatch:
+    inputs:
+      runtime:
+        description: Runtime packages to build
+        type: choice
+        options: [both, memory]
+        default: both
   push:
-    branches: [zy_runtime_artifacts]
-
+    branches: [zy_memory_runtime_*]
 permissions:
   contents: read
 
@@ -51,15 +57,17 @@ jobs:
           architecture: ${{ matrix.arch }}
           cache: npm
       - name: Install build dependencies
-        run: |
-          npm ci --no-audit --no-fund
-          npm --prefix App/memmy-agent install --ignore-scripts --no-audit --no-fund
+        run: npm ci --no-audit --no-fund
+      - name: Install Agent build dependencies
+        if: github.event_name == 'workflow_dispatch' && inputs.runtime != 'memory'
+        run: npm --prefix App/memmy-agent install --ignore-scripts --no-audit --no-fund
       - name: Build Agent runtime
+        if: github.event_name == 'workflow_dispatch' && inputs.runtime != 'memory'
         run: npm run agent:runtime:package -- --target "${{ matrix.target }}" --output "$RUNNER_TEMP/runtime-artifacts"
       - name: Build Memory runtime
         run: npm run runtime:package -w @memmy/memory -- --target "${{ matrix.target }}" --output "$RUNNER_TEMP/runtime-artifacts"
       - name: Verify unpacked runtimes and native dependencies
-        run: node scripts/internal/shared/verify-runtime-artifacts.mjs "$RUNNER_TEMP/runtime-artifacts" "${{ matrix.target }}"
+        run: node scripts/internal/shared/verify-runtime-artifacts.mjs "$RUNNER_TEMP/runtime-artifacts" "${{ matrix.target }}" "${{ inputs.runtime || 'memory' }}"
       - uses: actions/upload-artifact@v4
         with:
           name: runtimes-${{ matrix.target }}
@@ -82,8 +90,8 @@ jobs:
         with:
           pattern: runtimes-*
           path: runtime-input
-      - name: Collect all twelve archives with checksums
-        run: node scripts/internal/shared/collect-runtime-artifacts.mjs runtime-input runtime-output
+      - name: Collect runtime archives with checksums
+        run: node scripts/internal/shared/collect-runtime-artifacts.mjs runtime-input runtime-output "${{ inputs.runtime || 'memory' }}"
       - uses: actions/upload-artifact@v4
         with:
           name: all-platform-runtimes
diff --git a/Memory/package.json b/Memory/package.json
index d6d7845ad..a9760f538 100644
--- a/Memory/package.json
+++ b/Memory/package.json
@@ -29,6 +29,7 @@
     "pack:npm": "npm run package:npm && npm pack ./dist/memmy-memory-npm",
     "binary": "bash src/cli/scripts/build-binary.sh",
     "runtime:package": "node src/cli/scripts/build-runtime.mjs",
+    "runtime:package:all": "node ../scripts/internal/shared/build-memory-all.mjs",
     "release:assemble": "node src/cli/scripts/assemble-release.mjs",
     "standalone:package": "node src/cli/scripts/build-standalone.mjs"
   },
diff --git a/package.json b/package.json
index 9b0cfb045..383e21434 100644
--- a/package.json
+++ b/package.json
@@ -55,6 +55,7 @@
     "memory:pack": "npm run pack:npm -w @memmy/memory",
     "memory:binary": "npm run binary -w @memmy/memory",
     "memory:runtime:package": "npm run runtime:package -w @memmy/memory",
+    "memory:runtime:package:all": "node scripts/internal/shared/build-memory-all.mjs",
     "agent:package": "npm --prefix App/memmy-agent run package:npm",
     "agent:pack": "npm --prefix App/memmy-agent run pack:npm",
     "agent:runtime:package": "node App/memmy-agent/scripts/build-runtime.mjs",
diff --git a/scripts/internal/shared/build-memory-all.mjs b/scripts/internal/shared/build-memory-all.mjs
new file mode 100644
index 000000000..a7a7af4be
--- /dev/null
+++ b/scripts/internal/shared/build-memory-all.mjs
@@ -0,0 +1,69 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, readFile, stat } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const workflow = "runtime-artifacts.yml";
+const targets = ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "windows-arm64", "windows-x64"];
+
+function command(executable, args, live = false) {
+  const result = spawnSync(executable, args, { cwd: repoRoot, encoding: "utf8", stdio: live ? "inherit" : "pipe" });
+  if (result.status !== 0) throw new Error(`${executable} ${args.join(" ")} failed: ${result.error?.message ?? result.stderr ?? "see output above"}`);
+  return result.stdout?.trim() ?? "";
+}
+
+export async function buildMemoryAll({ run = command, wait = delay } = {}) {
+  if (run("git", ["status", "--porcelain"])) throw new Error("Commit your local changes before building all platforms.");
+  const sha = run("git", ["rev-parse", "HEAD"]);
+  const remote = run("git", ["remote", "get-url", "origin"]);
+  const repository = run("gh", ["repo", "view", remote, "--json", "nameWithOwner", "--jq", ".nameWithOwner"]);
+  const branch = `zy_memory_runtime_${randomUUID()}`;
+  console.log(`Uploading committed source ${sha} to ${repository} (${branch})`);
+  run("git", ["push", "origin", `${sha}:refs/heads/${branch}`], true);
+  let build;
+  for (let attempt = 0; attempt < 24; attempt++) {
+    const runs = JSON.parse(run("gh", ["run", "list", "--repo", repository, "--workflow", workflow, "--branch", branch, "--event", "push", "--limit", "50", "--json", "databaseId,displayTitle,headSha,url"]));
+    build = runs.find((entry) => entry.headSha === sha);
+    if (build) break;
+    await wait(5000);
+  }
+  if (!build) throw new Error(`Build was pushed but was not found yet. Check Actions in ${repository}, branch ${branch}.`);
+  console.log(`Building six Memory runtimes: ${build.url}`);
+  run("gh", ["run", "watch", String(build.databaseId), "--repo", repository, "--exit-status", "--interval", "15"], true);
+  const output = join(repoRoot, "Memory/dist/releases", `all-${build.databaseId}`);
+  await mkdir(output, { recursive: true });
+  run("gh", ["run", "download", String(build.databaseId), "--repo", repository, "--name", "all-platform-runtimes", "--dir", output], true);
+  await verifyMemoryDownload(output, sha);
+  try { run("git", ["push", "origin", "--delete", branch], true); }
+  catch (error) { console.warn(`Artifacts are complete; temporary branch cleanup failed: ${error.message}`); }
+  console.log(`Six Memory runtime archives verified: ${output}`);
+  return output;
+}
+
+export async function verifyMemoryDownload(output, sha) {
+  const manifest = JSON.parse(await readFile(join(output, "runtime-artifacts.json"), "utf8"));
+  const memory = manifest.runtimes?.memory;
+  if (manifest.sourceCommit !== sha || Object.keys(manifest.runtimes ?? {}).join() !== "memory" ||
+      Object.keys(memory?.assets ?? {}).sort().join() !== [...targets].sort().join()) {
+    throw new Error("Downloaded manifest does not match the requested commit and six Memory targets.");
+  }
+  for (const target of targets) {
+    const asset = memory.assets[target];
+    if (asset.name !== `memmy-memory-runtime-${memory.version}-${target}.tar.gz` || !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(memory.version)) {
+      throw new Error(`Invalid Memory artifact name: ${target}`);
+    }
+    const file = join(output, asset.name);
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(file)) hash.update(chunk);
+    if (hash.digest("hex") !== asset.sha256 || (await stat(file)).size !== asset.size) throw new Error(`Checksum or size mismatch: ${asset.name}`);
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { await buildMemoryAll(); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}
diff --git a/scripts/internal/shared/collect-runtime-artifacts.mjs b/scripts/internal/shared/collect-runtime-artifacts.mjs
index 6bf5e513f..390ca422d 100644
--- a/scripts/internal/shared/collect-runtime-artifacts.mjs
+++ b/scripts/internal/shared/collect-runtime-artifacts.mjs
@@ -5,13 +5,17 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const repo = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
-const [input, output] = process.argv.slice(2).map((value) => resolve(value));
+const [inputPath, outputPath, selection = "both"] = process.argv.slice(2);
+if (!inputPath || !outputPath || !["both", "memory"].includes(selection)) {
+  throw new Error("Usage: collect-runtime-artifacts.mjs <input-directory> <output-directory> [both|memory]");
+}
+const [input, output] = [inputPath, outputPath].map((value) => resolve(value));
 if (!input || !output || input === output) throw new Error("Usage: collect-runtime-artifacts.mjs <input-directory> <output-directory>");
 const targets = ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "windows-arm64", "windows-x64"];
 const manifest = { sourceCommit: process.env.GITHUB_SHA ?? null, nodeVersion: process.versions.node, nodeAbi: process.versions.modules, runtimes: {} };
 const checksums = [];
 await mkdir(output, { recursive: true });
-for (const kind of ["agent", "memory"]) {
+for (const kind of selection === "memory" ? ["memory"] : ["agent", "memory"]) {
   const packageFile = kind === "agent" ? "App/memmy-agent/package.json" : "Memory/package.json";
   const version = JSON.parse(await readFile(join(repo, packageFile))).version;
   const assets = {};
diff --git a/scripts/internal/shared/verify-runtime-artifacts.mjs b/scripts/internal/shared/verify-runtime-artifacts.mjs
index 80cedf5e3..a5bbd37b7 100644
--- a/scripts/internal/shared/verify-runtime-artifacts.mjs
+++ b/scripts/internal/shared/verify-runtime-artifacts.mjs
@@ -10,6 +10,8 @@ import { setTimeout as delay } from "node:timers/promises";
 const repo = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
 const directory = resolve(process.argv[2]);
 const target = process.argv[3];
+const selection = process.argv[4] ?? "both";
+if (!["both", "memory"].includes(selection)) throw new Error("Expected runtime selection: both or memory");
 const hostTarget = `${process.platform === "win32" ? "windows" : process.platform}-${process.arch}`;
 if (target !== hostTarget) throw new Error(`Expected ${target}, running on ${hostTarget}`);
 const agentVersion = JSON.parse(await readFile(join(repo, "App/memmy-agent/package.json"))).version;
@@ -19,19 +21,23 @@ let service;
 let serviceExit;
 let logs = "";
 try {
-  for (const [kind, version, extension] of [["agent", agentVersion, "tgz"], ["memory", memoryVersion, "tar.gz"]]) {
+  const runtimes = [["memory", memoryVersion, "tar.gz"]];
+  if (selection === "both") runtimes.unshift(["agent", agentVersion, "tgz"]);
+  for (const [kind, version, extension] of runtimes) {
     await mkdir(join(root, kind));
     run("tar", ["-xzf", join(directory, `memmy-${kind}-runtime-${version}-${target}.${extension}`), "-C", join(root, kind)]);
   }
   const agentRoot = join(root, "agent/package");
-  const agent = JSON.parse(await readFile(join(agentRoot, "agent-runtime.json")));
-  if (agent.target !== target || agent.version !== agentVersion || agent.nodeAbi !== process.versions.modules) {
-    throw new Error("Agent runtime metadata does not match the runner");
+  if (selection === "both") {
+    const agent = JSON.parse(await readFile(join(agentRoot, "agent-runtime.json")));
+    if (agent.target !== target || agent.version !== agentVersion || agent.nodeAbi !== process.versions.modules) {
+      throw new Error("Agent runtime metadata does not match the runner");
+    }
+    if (run(process.execPath, [join(agentRoot, "dist/main.js"), "--version"]).trim() !== agentVersion) {
+      throw new Error("Agent runtime version check failed");
+    }
   }
-  if (run(process.execPath, [join(agentRoot, "dist/main.js"), "--version"]).trim() !== agentVersion) {
-    throw new Error("Agent runtime version check failed");
-  }
-  for (const packageRoot of [agentRoot, join(root, "memory")]) {
+  for (const packageRoot of selection === "memory" ? [join(root, "memory")] : [agentRoot, join(root, "memory")]) {
     const require = createRequire(join(packageRoot, "package.json"));
     const Database = require("better-sqlite3");
     const database = new Database(":memory:");
@@ -61,7 +67,7 @@ try {
     await delay(200);
   }
   if (!healthy) throw new Error(`Memory runtime failed health check: ${logs}`);
-  console.log(`Verified Agent ${agentVersion}, Memory ${memoryVersion}, target ${target}, Node ABI ${process.versions.modules}`);
+  console.log(`Verified ${selection === "both" ? `Agent ${agentVersion}, ` : ""}Memory ${memoryVersion}, target ${target}, Node ABI ${process.versions.modules}`);
 } finally {
   if (service) {
     service.kill();
diff --git a/tests/runtime-artifacts.test.mjs b/tests/runtime-artifacts.test.mjs
index 634b9d219..6e8379d76 100644
--- a/tests/runtime-artifacts.test.mjs
+++ b/tests/runtime-artifacts.test.mjs
@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { afterEach, expect, it } from "vitest";
 import YAML from "yaml";
+import { buildMemoryAll, verifyMemoryDownload } from "../scripts/internal/shared/build-memory-all.mjs";
 
 const root = resolve(import.meta.dirname, "..");
 const collector = join(root, "scripts/internal/shared/collect-runtime-artifacts.mjs");
@@ -38,6 +39,65 @@ it("collects all target artifacts and rejects corrupted downloads", async () =>
   const manifest = JSON.parse(await readFile(join(directory, "output/runtime-artifacts.json")));
   expect(Object.keys(manifest.runtimes.agent.assets)).toHaveLength(6);
   expect(Object.keys(manifest.runtimes.memory.assets)).toHaveLength(6);
+  for (const target of targets) {
+    const input = join(directory, "input", `runtimes-${target}`);
+    for (const name of await readdir(input)) if (name.includes("agent")) await rm(join(input, name));
+  }
+  const memoryOutput = join(directory, "memory-output");
+  const memoryArgs = [collector, join(directory, "input"), memoryOutput, "memory"];
+  execFileSync(process.execPath, memoryArgs, { env: { ...process.env, GITHUB_SHA: "test-commit" } });
+  expect(await readdir(memoryOutput)).toHaveLength(8);
+  await verifyMemoryDownload(memoryOutput, "test-commit");
+  await expect(verifyMemoryDownload(memoryOutput, "other-commit")).rejects.toThrow("requested commit");
+  await writeFile(join(memoryOutput, (await readdir(memoryOutput)).find((name) => name.endsWith("tar.gz"))), "corrupt download");
+  await expect(verifyMemoryDownload(memoryOutput, "test-commit")).rejects.toThrow("Checksum");
   await writeFile(corrupted, "corrupted");
-  expect(() => execFileSync(process.execPath, args, { stdio: "pipe" })).toThrow();
+  expect(() => execFileSync(process.execPath, memoryArgs, { stdio: "pipe" })).toThrow();
+});
+
+it("rejects local changes before uploading source", async () => {
+  await expect(buildMemoryAll({ run: () => " M package.json" })).rejects.toThrow("Commit your local changes");
+});
+
+it("tracks the pushed build and propagates failure before downloading", async () => {
+  let branch;
+  let watched = false;
+  const calls = [];
+  await expect(buildMemoryAll({
+    wait: async () => {},
+    run: (command, args) => {
+      calls.push([command, ...args]);
+      if (command === "git") {
+        if (args[0] === "status") return "";
+        if (args[0] === "rev-parse") return "sha";
+        if (args[0] === "remote") return "https://github.com/owner/repo.git";
+        if (args[0] === "push") {
+          expect(args[1]).toBe("origin");
+          expect(args[2]).toMatch(/^sha:refs\/heads\/zy_memory_runtime_/);
+          branch = args[2].split("/").at(-1);
+          return "";
+        }
+      }
+      if (args[0] === "repo") {
+        expect(args[2]).toBe("https://github.com/owner/repo.git");
+        return "owner/repo";
+      }
+      if (args[1] === "list") {
+        expect(args).toContain(branch);
+        expect(args).toContain("push");
+        return JSON.stringify([
+          { databaseId: 10, headSha: "other-sha" },
+          { databaseId: 11, headSha: "sha", url: "https://example.test/run/11" },
+        ]);
+      }
+      if (args[1] === "watch") {
+        expect(args[2]).toBe("11");
+        watched = true;
+        throw new Error("Windows build failed");
+      }
+      throw new Error("Unexpected command");
+    },
+  })).rejects.toThrow("Windows build failed");
+  expect(watched).toBe(true);
+  expect(calls.some((args) => args.includes("download"))).toBe(false);
 });

From 7db6ad6c4a8f259b93d223b73378fd2bcf652aec Mon Sep 17 00:00:00 2001
From: lee <leason1874@qq.com>
Date: Wed, 14 Oct 2026 18:28:29 +0800
Subject: [PATCH 46/85] fix(runtime): skip third-party install scripts when
 packaging the agent runtime

@tencent-connect/openclaw-qqbot's postinstall (node scripts/postinstall-link-sdk.js 2>/dev/null || true) is POSIX-only. Under Windows cmd.exe it fails unless a 'true' binary is on PATH, which aborts 'npm run agent:runtime:package -- --target windows-x64'.

Install the staged package with --ignore-scripts and rebuild only better-sqlite3, the native module the runtime loads. Also retry removal of the temporary staging directory so transient Windows file locks do not mask the real error.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 App/memmy-agent/scripts/build-runtime.mjs | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/App/memmy-agent/scripts/build-runtime.mjs b/App/memmy-agent/scripts/build-runtime.mjs
index 4ca5bd08e..3b430807a 100644
--- a/App/memmy-agent/scripts/build-runtime.mjs
+++ b/App/memmy-agent/scripts/build-runtime.mjs
@@ -31,7 +31,12 @@ try {
   const packageRoot = join(source, "package");
   await mkdir(source, { recursive: true });
   await cp(join(agentRoot, "npm-packages", "memmy-agent"), packageRoot, { recursive: true });
-  run("npm", ["install", "--omit=dev", "--no-audit", "--no-fund"], packageRoot);
+  // Third-party lifecycle scripts are not needed to ship the runtime and some are POSIX-only
+  // (e.g. @tencent-connect/openclaw-qqbot runs `... 2>/dev/null || true`, which fails under
+  // Windows cmd.exe unless a `true` binary happens to be on PATH). Install without scripts,
+  // then run only the install script of the native module the runtime actually loads.
+  run("npm", ["install", "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund"], packageRoot);
+  run("npm", ["rebuild", "better-sqlite3", "--no-audit", "--no-fund"], packageRoot);
   const destination = join(temporaryRoot, "bundled");
   await bundleRuntime({ source, destination, packageDirectory: "package", kind: "agent", target: { platform: process.platform, arch: process.arch } });
   const manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
@@ -50,7 +55,8 @@ try {
   });
   console.log(archive);
 } finally {
-  await rm(temporaryRoot, { recursive: true, force: true });
+  // Windows may briefly lock freshly installed files (antivirus/indexer), so retry on EBUSY/EPERM.
+  await rm(temporaryRoot, { recursive: true, force: true, maxRetries: 10, retryDelay: 300 });
 }
 
 function run(command, args, cwd) {

From 195a8fad1a7e3f247ce426ef9ebf7fd32931e5ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Thu, 15 Oct 2026 10:41:38 +0800
Subject: [PATCH 47/85] =?UTF-8?q?fix:=20=E4=BF=9D=E7=95=99=E8=BF=81?=
 =?UTF-8?q?=E7=A7=BB=E5=90=8E=E7=9A=84=E6=A8=A1=E5=9E=8B=E6=A8=A1=E5=BC=8F?=
 =?UTF-8?q?=E5=B9=B6=E5=88=B7=E6=96=B0=E8=AE=B0=E5=BF=86=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/infrastructure/memmy-config/index.ts  |  6 +-
 .../tests/account-model-projection.test.ts    | 24 ++++++
 .../src/services/app-config-service.ts        |  8 ++
 .../services/tests/app-config-service.test.ts | 75 ++++++++++++++++++-
 .../tests/runtime-config-sync-service.test.ts | 30 ++++++++
 5 files changed, 140 insertions(+), 3 deletions(-)

diff --git a/App/backend/src/infrastructure/memmy-config/index.ts b/App/backend/src/infrastructure/memmy-config/index.ts
index d04c1f30d..7abfc6407 100644
--- a/App/backend/src/infrastructure/memmy-config/index.ts
+++ b/App/backend/src/infrastructure/memmy-config/index.ts
@@ -585,7 +585,11 @@ export async function writeAccountModelProjectionToMemmyConfig(
       appConfig,
       LEGACY_ACCOUNT_BYOK_LOCAL_SELECTION_BASELINE
     );
-    appConfig.userMode = "account";
+    // Projection repair also runs during migration; preserve an explicit BYOK choice.
+    const userMode = existingString(appConfig.userMode);
+    if (!userMode || userMode === "unset") {
+      appConfig.userMode = "account";
+    }
     if (normalizedCloudUuid) appConfig.cloudUuid = normalizedCloudUuid;
     if (normalizedUserId) appConfig.userId = normalizedUserId;
     delete appConfig[LEGACY_ACCOUNT_BYOK_LOCAL_SELECTION_BASELINE];
diff --git a/App/backend/src/infrastructure/memmy-config/tests/account-model-projection.test.ts b/App/backend/src/infrastructure/memmy-config/tests/account-model-projection.test.ts
index 61031302e..ac3ae2914 100644
--- a/App/backend/src/infrastructure/memmy-config/tests/account-model-projection.test.ts
+++ b/App/backend/src/infrastructure/memmy-config/tests/account-model-projection.test.ts
@@ -86,6 +86,30 @@ function currentByokCatalog(): Record<string, unknown> {
 }
 
 describe("account model projection current catalog", () => {
+  it.each([
+    [undefined, "account"],
+    ["", "account"],
+    ["unset", "account"],
+    ["account", "account"],
+    ["byok", "byok"]
+  ])("preserves an explicit user mode when repairing the projection (%s -> %s)", async (userMode, expectedMode) => {
+    const initial = currentByokCatalog();
+    const file = await configFile({ ...initial, app: { userMode } });
+    await writeAccountModelProjectionToMemmyConfig({ cloudUuid: "cloud-token", userId: "owner-a" }, file);
+
+    const saved = await readConfig(file);
+    expect(saved.app.userMode).toBe(expectedMode);
+    expect(saved.providers.openai).toEqual((initial.providers as any).openai);
+    expect(saved.modelAssignments.byok).toEqual((initial.modelAssignments as any).byok);
+    expect(saved.providers.memmy_account.ownerAccountId).toBe("owner-a");
+    expect(saved.modelAssignments.account.agent.candidates).toContain(accountId("owner-a", "agent"));
+    const snapshot = await readFile(file, "utf8");
+    await expect(writeAccountModelProjectionToMemmyConfig({
+      cloudUuid: "cloud-token", userId: "owner-a"
+    }, file)).resolves.toMatchObject({ changed: false });
+    expect(await readFile(file, "utf8")).toBe(snapshot);
+  });
+
   it("creates an owner-scoped Provider, endpoint, six presets, and isolated assignment", async () => {
     const file = await configFile(currentByokCatalog());
     const beforeByok = (await readConfig(file)).modelAssignments.byok;
diff --git a/App/backend/src/services/app-config-service.ts b/App/backend/src/services/app-config-service.ts
index c69a03335..ec2330727 100644
--- a/App/backend/src/services/app-config-service.ts
+++ b/App/backend/src/services/app-config-service.ts
@@ -115,6 +115,14 @@ export function createAppConfigService(options: CreateAppConfigServiceOptions):
         });
         await options.memoryClient?.reloadConfig({ reason: "memory_token_budget_saved" });
       }
+      if (input.userMode) {
+        try {
+          await options.memoryClient?.reloadConfig({ reason: "user_mode_saved" });
+        } catch {
+          // Settings are saved; saving the mode again or restarting Memory can retry the reload.
+          console.warn("Memory config reload failed after user mode was saved");
+        }
+      }
       preserveCompletedGuideWhenSwitchingToByok(previousOnboarding, options);
       return settings;
     },
diff --git a/App/backend/src/services/tests/app-config-service.test.ts b/App/backend/src/services/tests/app-config-service.test.ts
index caf963eff..6b811adbf 100644
--- a/App/backend/src/services/tests/app-config-service.test.ts
+++ b/App/backend/src/services/tests/app-config-service.test.ts
@@ -1,9 +1,9 @@
 /** App config service tests. */
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import YAML from "yaml";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { createAppConfigService } from "../app-config-service.js";
 import { createAppStateStore } from "../../infrastructure/app-state-store/index.js";
 import { createMemmyConfigWriter } from "../../infrastructure/memmy-config/index.js";
@@ -16,6 +16,77 @@ import type {
 } from "@memmy/local-api-contracts";
 
 describe("AppConfigService", () => {
+  it.each(["byok", "account"] as const)("reloads Memory after persisting %s mode to YAML and SQLite", async (userMode) => {
+    const root = mkdtempSync(join(tmpdir(), "memmy-mode-reload-"));
+    const configPath = join(root, "config.yaml");
+    const store = createAppStateStore({ databasePath: join(root, "app.sqlite") });
+    try {
+      const observations: unknown[] = [];
+      const reloadConfig = vi.fn(async (input) => {
+        observations.push({
+          input,
+          yamlMode: YAML.parse(readFileSync(configPath, "utf8")).app.userMode,
+          databaseMode: store.repositories.bootstrap.getAppSettings().userMode
+        });
+      });
+      const service = createAppConfigService({
+        bootstrapRepository: store.repositories.bootstrap,
+        memmyConfigWriter: createMemmyConfigWriter({ configPath }),
+        memoryClient: { reloadConfig }
+      });
+      await expect(service.updateSettings({ userMode })).resolves.toMatchObject({ userMode });
+      expect(observations).toEqual([{
+        input: { reason: "user_mode_saved" }, yamlMode: userMode, databaseMode: userMode
+      }]);
+
+      const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        reloadConfig.mockRejectedValueOnce(new Error("Memory unavailable"));
+        await expect(service.updateSettings({ userMode })).resolves.toMatchObject({ userMode });
+        expect(warning).toHaveBeenCalledWith("Memory config reload failed after user mode was saved");
+        expect(YAML.parse(readFileSync(configPath, "utf8")).app.userMode).toBe(userMode);
+        expect(store.repositories.bootstrap.getAppSettings().userMode).toBe(userMode);
+        // Saving the same mode again must retry the failed reload.
+        await service.updateSettings({ userMode });
+        expect(reloadConfig).toHaveBeenCalledTimes(3);
+        expect(observations).toHaveLength(2);
+      } finally {
+        warning.mockRestore();
+      }
+    } finally {
+      store.close();
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("does not reload Memory when only appearance settings change", async () => {
+    const reloadConfig = vi.fn();
+    const service = createAppConfigService({
+      bootstrapRepository: {
+        ...createBootstrapRepositoryStub(),
+        updateAppSettings: (patch) => appSettings(patch)
+      },
+      memoryClient: { reloadConfig }
+    });
+    await service.updateSettings({ theme: "dark" });
+    expect(reloadConfig).not.toHaveBeenCalled();
+  });
+
+  it("does not update the database or reload Memory if saving the runtime mode fails", async () => {
+    const updateAppSettings = vi.fn();
+    const reloadConfig = vi.fn();
+    const writer = createMemmyConfigWriter();
+    vi.spyOn(writer, "writeUserMode").mockRejectedValueOnce(new Error("Config not writable"));
+    const service = createAppConfigService({
+      bootstrapRepository: { ...createBootstrapRepositoryStub(), updateAppSettings },
+      memmyConfigWriter: writer,
+      memoryClient: { reloadConfig }
+    });
+    await expect(service.updateSettings({ userMode: "account" })).rejects.toThrow("Config not writable");
+    expect(updateAppSettings).not.toHaveBeenCalled();
+    expect(reloadConfig).not.toHaveBeenCalled();
+  });
+
   it("updates app settings through the bootstrap repository", async () => {
     const calls: unknown[] = [];
     const service = createAppConfigService({
diff --git a/App/backend/src/services/tests/runtime-config-sync-service.test.ts b/App/backend/src/services/tests/runtime-config-sync-service.test.ts
index 1c941259b..f9d52f602 100644
--- a/App/backend/src/services/tests/runtime-config-sync-service.test.ts
+++ b/App/backend/src/services/tests/runtime-config-sync-service.test.ts
@@ -612,6 +612,36 @@ describe("syncRuntimeConfigWithAppState", () => {
     expect(saved.modelAssignments.account.ownerAccountId).toBe("owner-a");
   });
 
+  it.each([false, true])("preserves explicit BYOK while repairing a migrated account projection (runtime migrated: %s)", async (runtimeSourceWasMigrated) => {
+    const context = createContext();
+    seedAccountSession(context);
+    const byok = currentByokCatalog() as any;
+    context.writeConfig({ ...byok, app: { ...byok.app, userMode: "byok" } });
+
+    const options = {
+      ...context,
+      accountChannel: "email" as const,
+      migrationConsistency: {
+        accountSourceIsAuthoritative: true,
+        runtimeSourceWasMigrated,
+        categorySourcesShareGeneration: false
+      }
+    };
+    await expect(syncRuntimeConfigWithAppState(options)).resolves.toMatchObject({
+      mode: "byok", provider: "openai", model: "gpt-5", hydratedAppState: true
+    });
+    const saved = YAML.parse(readFileSync(context.memmyConfigPath, "utf8"));
+    expect(saved.app.userMode).toBe("byok");
+    expect(saved.providers.openai).toEqual(byok.providers.openai);
+    expect(saved.modelAssignments.byok).toEqual(byok.modelAssignments.byok);
+    expect(saved.providers.memmy_account).toMatchObject({ ownerAccountId: "owner-a", apiKey: "cloud-token-a" });
+    expect(context.store.repositories.bootstrap.getAppSettings().userMode).toBe("byok");
+    expect(context.store.repositories.accountSession.get()).toMatchObject({ authenticated: true });
+    const snapshot = readFileSync(context.memmyConfigPath, "utf8");
+    await expect(syncRuntimeConfigWithAppState(options)).resolves.toMatchObject({ mode: "byok", wroteConfig: false });
+    expect(readFileSync(context.memmyConfigPath, "utf8")).toBe(snapshot);
+  });
+
   it("restores the active account after an upgrade left active_uuid empty", async () => {
     const context = createContext();
     seedAccountSession(context);

From 0192ab8ceda2389a21fb4ae626e09e7d068152b4 Mon Sep 17 00:00:00 2001
From: whqf1123 <333792770+whqf1123@users.noreply.github.com>
Date: Sat, 10 Oct 2026 14:29:28 +0800
Subject: [PATCH 48/85] fix: guard embedding inputs and isolate rejected
 batches (MEMMY-488)

---
 Memory/readme.md                              | 24 ++++-
 Memory/src/cli/legacy-migration.ts            |  1 +
 Memory/src/config/index.ts                    |  3 +
 Memory/src/model/embedder.ts                  |  2 +-
 Memory/src/model/openai-embedding-inputs.ts   | 67 ++++++++++---
 Memory/src/service/worker/job-handlers.ts     |  4 +
 Memory/src/service/worker/worker-runner.ts    | 16 ++-
 Memory/tests/config.test.ts                   |  6 +-
 Memory/tests/embedding-input-guard.test.ts    | 50 ++++++++++
 Memory/tests/memmy-488-reproduction.test.ts   | 98 +++++++++++++++++++
 .../embedding/embedding-processing.test.ts    | 44 +++++++--
 11 files changed, 282 insertions(+), 33 deletions(-)
 create mode 100644 Memory/tests/embedding-input-guard.test.ts
 create mode 100644 Memory/tests/memmy-488-reproduction.test.ts

diff --git a/Memory/readme.md b/Memory/readme.md
index 624f19346..8a5279407 100644
--- a/Memory/readme.md
+++ b/Memory/readme.md
@@ -72,11 +72,25 @@ The `MEMMY_MEMORY_HOST`, `MEMMY_MEMORY_PORT`, and `MEMMY_MEMORY_DB`
 environment variables override the corresponding server settings. The
 `MEMORY_SERVICE_*` aliases are also accepted.
 
-OpenAI-compatible embedding inputs are tokenized and split automatically with
-a conservative 7,500-token per-input budget. Set
-`memmyMemory.embedding.maxInputTokens` or
-`MEMMY_EMBEDDING_MAX_INPUT_TOKENS` to use a smaller budget for a provider with
-a shorter context window.
+OpenAI-compatible embedding inputs are split without truncating the source text.
+Known OpenAI embedding models use a 7,500-token per-input budget. Opaque aliases
+(such as BGE deployments) use a 4,000-token estimate plus an independent 12,000-byte
+UTF-8 cap, because the provider may use a different tokenizer. Splits preserve
+Unicode characters; chunk vectors are length-weighted and combined into one
+vector per original input. Set `memmyMemory.embedding.maxInputTokens` /
+`MEMMY_EMBEDDING_MAX_INPUT_TOKENS`, or for opaque aliases
+`memmyMemory.embedding.maxInputBytes` / `MEMMY_EMBEDDING_MAX_INPUT_BYTES`, to lower
+these limits. Defaults are conservative guards, not guarantees of an unknown
+provider's context window. Budgets too small for a complete character fail
+locally without retrying or dropping text.
+
+Embedding workers isolate a rejected batch by trying each original item once
+for input-related HTTP 400/413/422 failures, including generic parameter errors.
+Successful siblings are saved; a still-invalid item stops automatic retries.
+Authentication/configuration, quota, rate-limit and server errors do not trigger
+this fan-out. This applies to both new jobs and the embedding retry queue.
+Previously failed records require an explicit retry/reindex; updating the code
+does not automatically reset their failed state.
 
 All remote summary-model calls (capture, reflection, long-turn splitting,
 reward scoring, retrieval filtering, and turn routing) are clipped before
diff --git a/Memory/src/cli/legacy-migration.ts b/Memory/src/cli/legacy-migration.ts
index 42b936bde..f38c93d0e 100644
--- a/Memory/src/cli/legacy-migration.ts
+++ b/Memory/src/cli/legacy-migration.ts
@@ -214,6 +214,7 @@ function mapEmbedding(value: Row): Row {
     model: string(value.model),
     apiKey: string(value.apiKey),
     maxInputTokens: finite(value.maxInputTokens) ?? undefined,
+    maxInputBytes: finite(value.maxInputBytes) ?? undefined,
     batchSize: finite(value.batchSize) ?? undefined,
     cache: typeof cache.enabled === "boolean" ? cache.enabled : undefined
   });
diff --git a/Memory/src/config/index.ts b/Memory/src/config/index.ts
index a1e0af3f9..8809b20de 100644
--- a/Memory/src/config/index.ts
+++ b/Memory/src/config/index.ts
@@ -92,6 +92,7 @@ export interface EmbeddingConfig {
   actualModelContext?: ActualModelContext;
   selectionError?: "model_selection_unavailable";
   maxInputTokens?: number;
+  maxInputBytes?: number;
   batchSize: number;
   timeoutMs: number;
   maxRetries: number;
@@ -626,6 +627,7 @@ function configFromEnv(): Record<string, unknown> {
       model: process.env.MEMMY_EMBEDDING_MODEL,
       apiKey: process.env.MEMMY_EMBEDDING_API_KEY,
       maxInputTokens: numberEnv("MEMMY_EMBEDDING_MAX_INPUT_TOKENS"),
+      maxInputBytes: numberEnv("MEMMY_EMBEDDING_MAX_INPUT_BYTES"),
       batchSize: numberEnv("MEMMY_EMBEDDING_BATCH_SIZE"),
       timeoutMs: numberEnv("MEMMY_EMBEDDING_TIMEOUT_MS"),
       maxRetries: numberEnv("MEMMY_EMBEDDING_MAX_RETRIES")
@@ -797,6 +799,7 @@ function normalizeEmbedding(input: Record<string, unknown>): EmbeddingConfig {
       ? input.selectionError
       : undefined,
     maxInputTokens: positiveInteger(input.maxInputTokens),
+    maxInputBytes: positiveInteger(input.maxInputBytes),
     batchSize: numberValue(input.batchSize, DEFAULT_MEMMY_CONFIG.embedding.batchSize),
     timeoutMs: numberValue(input.timeoutMs, DEFAULT_MEMMY_CONFIG.embedding.timeoutMs),
     maxRetries: numberValue(input.maxRetries, DEFAULT_MEMMY_CONFIG.embedding.maxRetries),
diff --git a/Memory/src/model/embedder.ts b/Memory/src/model/embedder.ts
index 70abd20dd..b07468d43 100644
--- a/Memory/src/model/embedder.ts
+++ b/Memory/src/model/embedder.ts
@@ -237,7 +237,7 @@ class HttpEmbedder implements Embedder {
       throw new Error(`${provider} embedding provider requires apiKey or endpoint`);
     }
     const plan = provider === "openai_compatible"
-      ? planOpenAiEmbeddingInputs(texts, this.config.model, this.config.maxInputTokens)
+      ? planOpenAiEmbeddingInputs(texts, this.config.model, this.config.maxInputTokens, this.config.maxInputBytes)
       : null;
     if (!plan) return this.requestOpenAiShape(texts, provider, url, role);
 
diff --git a/Memory/src/model/openai-embedding-inputs.ts b/Memory/src/model/openai-embedding-inputs.ts
index 1954b66a7..1aac54d74 100644
--- a/Memory/src/model/openai-embedding-inputs.ts
+++ b/Memory/src/model/openai-embedding-inputs.ts
@@ -2,6 +2,13 @@ import { get_encoding } from "tiktoken";
 
 const OPENAI_EMBEDDING_INPUT_TOKEN_BUDGET = 7_500;
 const OPAQUE_EMBEDDING_INPUT_TOKEN_BUDGET = 4_000;
+// An alias may use a different tokenizer. Bound bytes independently of our
+// token estimate; this is a conservative default, not a provider context limit.
+const OPAQUE_EMBEDDING_INPUT_BYTE_BUDGET = 12_000;
+
+export class EmbeddingInputLimitError extends Error {
+  override readonly name = "EmbeddingInputLimitError";
+}
 const OPENAI_EMBEDDING_BATCH_TOKEN_BUDGET = 290_000;
 
 export interface OpenAiEmbeddingChunk {
@@ -22,7 +29,8 @@ let opaqueModelEncoder: ReturnType<typeof get_encoding> | undefined;
 export function planOpenAiEmbeddingInputs(
   texts: string[],
   model?: string,
-  configuredMaxInputTokens?: number
+  configuredMaxInputTokens?: number,
+  configuredMaxInputBytes?: number
 ): OpenAiEmbeddingPlan | null {
   const knownOpenAiModel = isKnownOpenAiEmbeddingModel(model);
   const inputTokenBudget = resolveInputTokenBudget(model, configuredMaxInputTokens);
@@ -30,15 +38,21 @@ export function planOpenAiEmbeddingInputs(
   // use a different tokenizer (for example BGE-M3), so keep their chunks as
   // text and let the provider apply its native tokenizer.
   const useTokenIds = knownOpenAiModel;
+  const inputByteBudget = knownOpenAiModel ? Infinity :
+    Math.min(positiveBudget(configuredMaxInputBytes) ?? OPAQUE_EMBEDDING_INPUT_BYTE_BUDGET,
+      OPAQUE_EMBEDDING_INPUT_BYTE_BUDGET);
   const encoder = knownOpenAiModel
     ? (openAiEncoder ??= get_encoding("cl100k_base"))
     : (opaqueModelEncoder ??= get_encoding("o200k_base"));
-  const encoded = texts.map((text) => Array.from(encoder.encode(text, [], [])));
-  const totalTokens = encoded.reduce((sum, tokens) => sum + tokens.length, 0);
-  if (totalTokens <= OPENAI_EMBEDDING_BATCH_TOKEN_BUDGET &&
-    encoded.every((tokens) => tokens.length <= inputTokenBudget)) return null;
+  const inputs = texts.flatMap((text, originalIndex) =>
+    (useTokenIds ? [text] : splitUtf8Input(text, inputByteBudget))
+      .map((part) => ({ originalIndex, tokens: Array.from(encoder.encode(part, [], [])) }))
+  );
+  const totalTokens = inputs.reduce((sum, item) => sum + item.tokens.length, 0);
+  if (inputs.length === texts.length && totalTokens <= OPENAI_EMBEDDING_BATCH_TOKEN_BUDGET &&
+    inputs.every((item) => item.tokens.length <= inputTokenBudget)) return null;
 
-  const chunks = encoded.flatMap((tokens, originalIndex) => {
+  const chunks = inputs.flatMap(({ tokens, originalIndex }) => {
     if (tokens.length === 0) return [{ originalIndex, tokens, input: useTokenIds ? tokens : "" }];
     const tokenBytes = useTokenIds
       ? undefined
@@ -46,11 +60,13 @@ export function planOpenAiEmbeddingInputs(
     const items: OpenAiEmbeddingChunk[] = [];
     for (let offset = 0; offset < tokens.length;) {
       let end = Math.min(tokens.length, offset + inputTokenBudget);
-      if (!useTokenIds && end < tokens.length) {
-        while (end > offset && startsWithContinuationByte(tokenBytes?.[end])) {
-          end -= 1;
+      if (!useTokenIds) {
+        // Never cut through a UTF-8 character, including when one character
+        // occupies several tokens. If it cannot fit, fail without sending it.
+        while (end > offset && end < tokens.length && startsWithContinuationByte(tokenBytes![end])) end -= 1;
+        if (end === offset) {
+          throw new EmbeddingInputLimitError("Embedding token budget is too small for one complete character; increase maxInputTokens.");
         }
-        if (end === offset) end = Math.min(tokens.length, offset + inputTokenBudget);
       }
       const chunkTokens = tokens.slice(offset, end);
       items.push({
@@ -96,10 +112,12 @@ function isKnownOpenAiEmbeddingModel(model?: string): boolean {
   return /(?:^|[/.:])text-embedding-(?:3-(?:small|large)|ada-002)(?:$|[/.:])/i.test(model?.trim() ?? "");
 }
 
+function positiveBudget(value?: number): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.floor(value) : undefined;
+}
+
 function resolveInputTokenBudget(model?: string, configured?: number): number {
-  const explicit = typeof configured === "number" && Number.isFinite(configured) && configured > 0
-    ? Math.floor(configured)
-    : undefined;
+  const explicit = positiveBudget(configured);
   const defaultBudget = isKnownOpenAiEmbeddingModel(model)
     ? OPENAI_EMBEDDING_INPUT_TOKEN_BUDGET
     : OPAQUE_EMBEDDING_INPUT_TOKEN_BUDGET;
@@ -132,3 +150,26 @@ function batchChunks(chunks: OpenAiEmbeddingChunk[]): OpenAiEmbeddingChunk[][] {
   if (current.length > 0) batches.push(current);
   return batches;
 }
+
+function splitUtf8Input(text: string, budget: number): string[] {
+  if (Buffer.byteLength(text, "utf8") <= budget) return [text];
+  const parts: string[] = [];
+  let offset = 0;
+  let start = 0;
+  let bytes = 0;
+  for (const character of text) {
+    const size = Buffer.byteLength(character, "utf8");
+    if (size > budget) {
+      throw new EmbeddingInputLimitError("Embedding byte budget is too small for one complete character; increase maxInputBytes.");
+    }
+    if (bytes + size > budget) {
+      parts.push(text.slice(start, offset));
+      start = offset;
+      bytes = 0;
+    }
+    offset += character.length;
+    bytes += size;
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
diff --git a/Memory/src/service/worker/job-handlers.ts b/Memory/src/service/worker/job-handlers.ts
index 8eb2d8bc2..121dac284 100644
--- a/Memory/src/service/worker/job-handlers.ts
+++ b/Memory/src/service/worker/job-handlers.ts
@@ -1,3 +1,4 @@
+import { EmbeddingInputLimitError } from "../../model/openai-embedding-inputs.js";
 /**
  * Worker job routing and durable write-back helpers.
  *
@@ -583,6 +584,9 @@ export function classifyProcessingError(error: unknown): {
   code: string;
   retryAction: "retry" | "open_settings" | "none";
 } {
+  if (error instanceof EmbeddingInputLimitError) {
+    return { code: "model_input_too_long", retryAction: "none" };
+  }
   if (error instanceof ModelHttpError && error.errorCode === "40309") {
     return { code: "40309", retryAction: "open_settings" };
   }
diff --git a/Memory/src/service/worker/worker-runner.ts b/Memory/src/service/worker/worker-runner.ts
index 20455e650..8aa5ebc6c 100644
--- a/Memory/src/service/worker/worker-runner.ts
+++ b/Memory/src/service/worker/worker-runner.ts
@@ -1,3 +1,4 @@
+import { ModelHttpError } from "../../model/http.js";
 /**
  * Worker scheduling and execution domain.
  *
@@ -545,8 +546,7 @@ export class WorkerRunner {
           }
         }
       } catch (error) {
-        const classification = classifyProcessingError(error);
-        if (classification.code === "model_input_too_long" && batch.length > 1) {
+        if (batch.length > 1 && shouldIsolateEmbeddingBatch(error)) {
           for (const item of batch) results.push(await this.runLeasedEmbeddingItem(item));
           continue;
         }
@@ -733,8 +733,7 @@ export class WorkerRunner {
           }
         }
       } catch (error) {
-        const classification = classifyProcessingError(error);
-        if (classification.code === "model_input_too_long" && batch.length > 1) {
+        if (batch.length > 1 && shouldIsolateEmbeddingBatch(error)) {
           for (const item of batch) {
             results.push(await this.runClaimedEmbeddingRetryItem(item.retry, item.claim, item.attemptNo));
           }
@@ -933,3 +932,12 @@ function embeddingRetryLogFields(retry: EmbeddingRetryRecord): Record<string, un
     nextAttemptAt: retry.nextAttemptAt
   };
 }
+
+// A rejected input can poison a whole provider request. Probe each original
+// item once; do not split authentication, quota, rate-limit or server failures.
+function shouldIsolateEmbeddingBatch(error: unknown): boolean {
+  const classification = classifyProcessingError(error);
+  return classification.code === "model_input_too_long" ||
+    (classification.code === "invalid_model_request" && error instanceof ModelHttpError &&
+      [400, 413, 422].includes(error.httpStatus));
+}
diff --git a/Memory/tests/config.test.ts b/Memory/tests/config.test.ts
index be064876e..28315065f 100644
--- a/Memory/tests/config.test.ts
+++ b/Memory/tests/config.test.ts
@@ -147,12 +147,16 @@ describe("memmy memory config", () => {
           provider: "openai_compatible",
           endpoint: "https://embedding.example/v1",
           model: "deployment-alias",
-          maxInputTokens: 1_200
+          maxInputTokens: 1_200,
+          maxInputBytes: 8_000
         }
       }
     }));
 
     expect(loadMemmyConfig(configPath).config.embedding.maxInputTokens).toBe(1_200);
+    expect(loadMemmyConfig(configPath).config.embedding.maxInputBytes).toBe(8_000);
+    setEnv("MEMMY_EMBEDDING_MAX_INPUT_BYTES", "2048");
+    expect(loadMemmyConfig(configPath).config.embedding.maxInputBytes).toBe(2048);
     setEnv("MEMMY_EMBEDDING_MAX_INPUT_TOKENS", "640");
     expect(loadMemmyConfig(configPath).config.embedding.maxInputTokens).toBe(640);
   });
diff --git a/Memory/tests/embedding-input-guard.test.ts b/Memory/tests/embedding-input-guard.test.ts
new file mode 100644
index 000000000..8e1f0453d
--- /dev/null
+++ b/Memory/tests/embedding-input-guard.test.ts
@@ -0,0 +1,50 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { DEFAULT_MEMMY_CONFIG } from "../src/config/index.js";
+import { createEmbedder } from "../src/model/embedder.js";
+
+afterEach(() => vi.unstubAllGlobals());
+
+it.each([
+  ["ASCII boundary", "a".repeat(27_447)],
+  ["mixed Unicode", "中文🙂 café\n".repeat(5_000)]
+])("guards opaque-model %s inputs by bytes without truncation", async (_name, text) => {
+  const sent: string[] = [];
+  vi.stubGlobal("fetch", vi.fn(async (_url, init) => {
+    const { input } = JSON.parse(String(init?.body));
+    sent.push(...input);
+    if (input.some((part: string) => Buffer.byteLength(part, "utf8") > 12_000)) {
+      return new Response(JSON.stringify({ code: 20015, message: "The parameter is invalid." }), { status: 400 });
+    }
+    return new Response(JSON.stringify({ data: input.map(() => ({ embedding: [1, 0] })) }), { status: 200 });
+  }));
+  const embedder = createEmbedder({ ...DEFAULT_MEMMY_CONFIG.embedding, provider: "openai_compatible",
+    model: "Pro/BAAI/bge-m3", endpoint: "https://example.test/v1", cache: false, maxRetries: 0 },
+    { usageRecorder: { record() { return "skipped"; } } });
+  await expect(embedder.embedOne(text)).resolves.toEqual([1, 0]);
+  expect(sent.length).toBeGreaterThan(1);
+  expect(sent.every(part => Buffer.byteLength(part, "utf8") <= 12_000)).toBe(true);
+  expect(sent.join("")).toBe(text);
+});
+
+it("honors a smaller byte budget and keeps multi-byte characters intact", async () => {
+  const sent: string[] = [];
+  vi.stubGlobal("fetch", vi.fn(async (_url, init) => {
+    const { input } = JSON.parse(String(init?.body)); sent.push(...input);
+    return new Response(JSON.stringify({ data: input.map(() => ({ embedding: [1, 0] })) }), { status: 200 });
+  }));
+  const text = "a中🙂é".repeat(100);
+  const embedder = createEmbedder({ ...DEFAULT_MEMMY_CONFIG.embedding, provider: "openai_compatible",
+    model: "custom-alias", endpoint: "https://example.test/v1", maxInputBytes: 7, cache: false },
+    { usageRecorder: { record() { return "skipped"; } } });
+  await embedder.embedOne(text);
+  expect(sent.every(part => Buffer.byteLength(part) <= 7)).toBe(true);
+  expect(sent.join("")).toBe(text);
+});
+
+it("rejects an impossible character budget before making any HTTP request", async () => {
+  const fetchMock = vi.fn(); vi.stubGlobal("fetch", fetchMock);
+  const embedder = createEmbedder({ ...DEFAULT_MEMMY_CONFIG.embedding, provider: "openai_compatible",
+    model: "custom-alias", endpoint: "https://example.test/v1", maxInputBytes: 1, cache: false });
+  await expect(embedder.embedOne("🙂")).rejects.toThrow("one complete character");
+  expect(fetchMock).not.toHaveBeenCalled();
+});
diff --git a/Memory/tests/memmy-488-reproduction.test.ts b/Memory/tests/memmy-488-reproduction.test.ts
new file mode 100644
index 000000000..0dde1e782
--- /dev/null
+++ b/Memory/tests/memmy-488-reproduction.test.ts
@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { DEFAULT_MEMMY_CONFIG, type MemoryRow } from '../src/index.js';
+import { createEmbedder } from '../src/model/embedder.js';
+import { Repositories } from '../src/storage/repositories.js';
+import { embeddingTextForMemory } from '../src/service/embedding/embedding-pipeline.js';
+import { createMemoryServiceFixture, createBatchReflectionLlm } from './fixtures/memory-service-fixture.js';
+
+const fixture = createMemoryServiceFixture();
+afterEach(() => { fixture.cleanup(); vi.unstubAllGlobals(); });
+
+function setup(explicit: boolean) {
+  const requests: Array<{ sizes: number[]; rejected: boolean }> = [];
+  vi.stubGlobal('fetch', vi.fn(async (_url: unknown, init: RequestInit) => {
+    const { input } = JSON.parse(String(init.body)) as { input: string[] };
+    const rejected = input.some(text => text.includes('BAD_EMBEDDING_ITEM'));
+    requests.push({ sizes: input.map(text => text.length), rejected });
+    return new Response(JSON.stringify(rejected
+      ? { code: explicit ? 'context_length_exceeded' : 20015, message: explicit ? 'maximum context length exceeded' : 'The parameter is invalid.' }
+      : { data: input.map(() => ({ embedding: [1, 0, 0] })) }),
+      { status: rejected ? 400 : 200, headers: { 'content-type': 'application/json' } });
+  }));
+  const embedder = createEmbedder({ ...DEFAULT_MEMMY_CONFIG.embedding,
+    provider: 'openai_compatible', model: 'Pro/BAAI/bge-m3',
+    endpoint: 'https://embedding-reproduction.invalid/v1', apiKey: 'synthetic-test-key',
+    cache: false, maxRetries: 3 }, { usageRecorder: { record() { return "skipped"; } } });
+  return { embedder, requests };
+}
+function skill(id: string, content: string): MemoryRow {
+  const at = new Date().toISOString();
+  return { id, timeline: at, userId: 'memmy488-test', memoryType: 'SkillMemory',
+    status: 'activated', visibility: 'private', memoryKey: id, memoryValue: content,
+    tags: [], info: {}, properties: { internal_info: { memory_layer: 'Skill', memory_kind: 'skill',
+      skill: { name: id, status: 'active', invocation_guide: content } } },
+    memoryLayer: 'Skill', version: 1, createdAt: at, updatedAt: at };
+}
+
+describe('MEMMY-488 regression (valid siblings must survive)', () => {
+  for (const explicit of [true, false]) {
+    it(`fresh worker batch: ${explicit ? 'explicit length error' : 'screenshot error 20015'}`, async () => {
+      const { embedder, requests } = setup(explicit);
+      const { db, service } = fixture.createTestService({ embedder, llm: createBatchReflectionLlm([], 'Synthetic summary.') });
+      const session = service.openSession({ namespace: { source: 'codex', profileId: 'memmy488', userId: 'memmy488-test' } });
+      const ids = ['GOOD_A', 'GOOD_B', 'GOOD_C', 'BAD_EMBEDDING_ITEM'].map((answer, i) =>
+        service.completeTurn(`turn-${i}`, { sessionId: session.sessionId, query: 'Remember this synthetic test.', answer }).l1MemoryId);
+      await service.runWorkerOnce(20, { priorityCohortOnly: true });
+      await service.runWorkerOnce(20, { priorityCohortOnly: true });
+      const repos = new Repositories(db.db);
+      const states = ids.map(id => ({ id, state: repos.processing.get(id)?.state, error: repos.processing.get(id)?.errorCode }));
+      expect(states.map(s => s.state)).toEqual(['ready', 'ready', 'ready', explicit ? 'ready_text_only' : 'failed']);
+      const vectorRows = db.db.prepare('SELECT memory_id, vector_field FROM memory_vector_entries').all();
+      expect(vectorRows.length).toBe(3);
+      const before = requests.length;
+      await service.runWorkerOnce(20, { priorityCohortOnly: true });
+      expect(requests.length).toBe(before);
+    });
+
+    it(`legacy retry batch and separate replay: ${explicit ? 'explicit length error' : 'screenshot error 20015'}`, async () => {
+      const { embedder, requests } = setup(explicit);
+      const { db, service } = fixture.createTestService({ embedder });
+      const repos = new Repositories(db.db);
+      const memories = ['GOOD_A', 'GOOD_B', 'GOOD_C', 'BAD_EMBEDDING_ITEM'].map((text, i) => skill(`skill-488-${i}`, text));
+      const retries = memories.map(memory => {
+        repos.memories.insert(memory);
+        return repos.runtime.enqueueEmbeddingRetry({ targetKind: 'skill', targetId: memory.id, vectorField: 'vec',
+          sourceText: embeddingTextForMemory(memory), embedRole: 'query', now: Date.now() - 1 });
+      });
+      await service.runWorkerOnce(10);
+      const states = retries.map(retry => { const row = repos.runtime.getEmbeddingRetry(retry.id)!; return { status: row.status, attempts: row.attempts }; });
+      expect(states.map(s => s.status)).toEqual(['succeeded', 'succeeded', 'succeeded', 'failed']);
+      const vectorRows = db.db.prepare('SELECT memory_id, vector_field FROM memory_vector_entries').all();
+      expect(vectorRows.length).toBe(3);
+      const before = requests.length;
+      await service.runWorkerOnce(10);
+      expect(requests.length).toBe(before);
+      const replay: string[] = [];
+      for (const memory of memories) {
+        try { await embedder.embedOne(embeddingTextForMemory(memory), 'query'); replay.push('succeeded'); }
+        catch { replay.push('failed'); }
+      }
+      expect(replay).toEqual(['succeeded', 'succeeded', 'succeeded', 'failed']);
+    });
+  }
+
+  it('long BGE alias text is chunked and preserves the complete input', async () => {
+    const sent: string[] = [];
+    vi.stubGlobal('fetch', vi.fn(async (_url: unknown, init: RequestInit) => {
+      const { input } = JSON.parse(String(init.body)); sent.push(...input);
+      return new Response(JSON.stringify({ data: input.map(() => ({ embedding: [1, 0, 0] })) }), { status: 200 });
+    }));
+    const embedder = createEmbedder({ ...DEFAULT_MEMMY_CONFIG.embedding, provider: 'openai_compatible',
+      model: 'Pro/BAAI/bge-m3', endpoint: 'https://embedding-reproduction.invalid/v1', apiKey: 'synthetic-test-key', cache: false },
+      { usageRecorder: { record() { return "skipped"; } } });
+    const text = '# Synthetic long document\n' + ' memory'.repeat(16000) + '\nEND_MARKER';
+    await embedder.embedOne(text);
+    expect(sent.length).toBeGreaterThan(1);
+    expect(sent.join('')).toBe(text);
+  });
+});
diff --git a/Memory/tests/service/embedding/embedding-processing.test.ts b/Memory/tests/service/embedding/embedding-processing.test.ts
index a0cdb8266..c5d7f5339 100644
--- a/Memory/tests/service/embedding/embedding-processing.test.ts
+++ b/Memory/tests/service/embedding/embedding-processing.test.ts
@@ -203,12 +203,17 @@ describe("MemoryService / embedding / processing", () => {
     db.close();
   });
 
-  it("isolates a deterministic embedding failure and keeps the valid sibling", async () => {
+  it.each([
+    [400, "context_length_exceeded", "maximum context length exceeded"],
+    [400, "20015", "The parameter is invalid."],
+    [413, "payload_too_large", "Request too large"],
+    [422, "invalid_input", "Invalid input"]
+  ])("isolates a deterministic embedding failure and keeps the valid sibling (%s / %s)", async (status, code, message) => {
     const llmCalls: Array<{
       messages: Array<{ role: string; content: string }>;
       options: { operation: string };
     }> = [];
-    const embedder = createSelectiveFailureEmbedder();
+    const embedder = createSelectiveFailureEmbedder(undefined, new ModelHttpError(message, "openai_compatible", status as number, code as string, message as string));
     const { db, service } = createTestService({
       llm: createBatchReflectionLlm(llmCalls, "Imported memory summary."),
       embedder
@@ -237,10 +242,10 @@ describe("MemoryService / embedding / processing", () => {
     ]));
     expect(repositories.processing.get(good.l1MemoryId)?.state).toBe("ready");
     expect(repositories.processing.get(bad.l1MemoryId)).toMatchObject({
-      state: "ready_text_only",
-      stage: null,
+      state: code === "context_length_exceeded" ? "ready_text_only" : "failed",
+      stage: code === "context_length_exceeded" ? null : "embedding",
       retryAction: "none",
-      errorCode: "model_input_too_long"
+      errorCode: code === "context_length_exceeded" ? "model_input_too_long" : "invalid_model_request"
     });
     db.close();
   });
@@ -338,8 +343,13 @@ describe("MemoryService / embedding / processing", () => {
     db.close();
   });
 
-  it("isolates a deterministic legacy retry failure and keeps the valid sibling", async () => {
-    const { db, service } = createTestService({ embedder: createSelectiveFailureEmbedder() });
+  it.each([
+    [400, "context_length_exceeded", "maximum context length exceeded"],
+    [400, "20015", "The parameter is invalid."],
+    [413, "payload_too_large", "Request too large"],
+    [422, "invalid_input", "Invalid input"]
+  ])("isolates a deterministic legacy retry failure and keeps the valid sibling (%s / %s)", async (status, code, message) => {
+    const { db, service } = createTestService({ embedder: createSelectiveFailureEmbedder(undefined, new ModelHttpError(message, "openai_compatible", status as number, code as string, message as string)) });
     const repositories = new Repositories(db.db);
     const good = skillMemory(undefined, {
       id: "skill_legacy_retry_good",
@@ -380,6 +390,22 @@ describe("MemoryService / embedding / processing", () => {
     db.close();
   });
 
+  it.each([401, 403, 429, 500])("does not fan out a shared HTTP %s failure", async (status) => {
+    const calls = { batch: 0, single: 0 };
+    const failure = new ModelHttpError("Provider unavailable", "openai_compatible", status, undefined, "Provider unavailable");
+    const { db, service } = createTestService({ embedder: createSelectiveFailureEmbedder(calls, failure) });
+    const repositories = new Repositories(db.db);
+    for (let index = 0; index < 2; index += 1) {
+      const memory = skillMemory(undefined, { id: `shared-failure-${index}`, content: "VALID_EMBEDDING_ITEM" });
+      repositories.memories.insert(memory);
+      repositories.runtime.enqueueEmbeddingRetry({ targetKind: "skill", targetId: memory.id, vectorField: "vec",
+        sourceText: embeddingTextForMemory(memory), embedRole: "query", now: Date.now() - 1 });
+    }
+    await service.runWorkerOnce(10);
+    expect(calls).toEqual({ batch: 1, single: 0 });
+    db.close();
+  });
+
   it("embeds L1 summary together with bounded user and assistant text", async () => {
     const root = createTestRoot("mindock-memory-dual-embedding-");
     const db = new MemoryDb({
@@ -747,8 +773,8 @@ function createFlakyEmbedder(): Embedder {
   };
 }
 
-function createSelectiveFailureEmbedder(calls?: { batch: number; single: number }): Embedder {
-  const inputTooLong = () => new ModelHttpError(
+function createSelectiveFailureEmbedder(calls?: { batch: number; single: number }, failure?: ModelHttpError): Embedder {
+  const inputTooLong = () => failure ?? new ModelHttpError(
     "openai_compatible HTTP 400: maximum context length exceeded",
     "openai_compatible",
     400,

From b972ec15c08c627af579356dd35e41ca1b295f7a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Thu, 15 Oct 2026 15:01:00 +0800
Subject: [PATCH 49/85] fix: delete generated spans with task memory

---
 Memory/src/service/memory-service.ts              | 15 +++++++++++++++
 .../tests/service/evolution/span-big-turn.test.ts | 11 ++++++++++-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/Memory/src/service/memory-service.ts b/Memory/src/service/memory-service.ts
index bb44dab52..273557f9a 100644
--- a/Memory/src/service/memory-service.ts
+++ b/Memory/src/service/memory-service.ts
@@ -2009,6 +2009,21 @@ export class MemoryService {
     const deletedMemoryIds: string[] = [];
 
     this.repos.transaction(() => {
+      const spanIds = new Set<string>();
+      for (const memoryId of episode.l1MemoryIds) {
+        const memory = this.repos.memories.get(memoryId);
+        const trace = memory?.properties.internal_info.trace;
+        if (!isRecord(trace) || !Array.isArray(trace.span_ids)) continue;
+        for (const spanId of trace.span_ids) {
+          if (typeof spanId === "string") spanIds.add(spanId);
+        }
+      }
+      for (const spanId of spanIds) {
+        const span = this.repos.memories.get(spanId);
+        if (!span || kindFromMemory(span) !== "span") continue;
+        this.deleteMemory(spanId, request);
+        deletedMemoryIds.push(spanId);
+      }
       for (const memoryId of episode.l1MemoryIds) {
         if (!this.repos.memories.get(memoryId)) continue;
         this.deleteMemory(memoryId, request);
diff --git a/Memory/tests/service/evolution/span-big-turn.test.ts b/Memory/tests/service/evolution/span-big-turn.test.ts
index 64110bc41..7b59a5a28 100644
--- a/Memory/tests/service/evolution/span-big-turn.test.ts
+++ b/Memory/tests/service/evolution/span-big-turn.test.ts
@@ -117,7 +117,7 @@ function createSpanBigTurnLlm(
 }
 
 describe("MemoryService / evolution / span big turn", () => {
-  it("stores and recalls subtask spans for a positively rewarded complex turn", async () => {
+  it("stores, recalls, and deletes subtask spans with their task", async () => {
     const calls: Array<{ messages: LlmMessage[]; options: LlmCompletionOptions }> = [];
     const embeddedTexts: string[] = [];
     const embeddedRoles: Array<"query" | "document" | undefined> = [];
@@ -321,6 +321,15 @@ describe("MemoryService / evolution / span big turn", () => {
       toolCalls: toolCalls.slice(0, 4).map(({ id, name, input }) => ({ id, name, input }))
     });
     expect(completed.l1MemoryIds).toHaveLength(1);
+
+    const deleted = service.deletePanelTask(completed.episodeId, { namespace });
+    expect(new Set(deleted.deletedMemoryIds)).toEqual(new Set([
+      completed.l1MemoryId,
+      ...storedSpanIds
+    ]));
+    expect(service.panelTasks({ namespace, page: 1 }).tasks).toHaveLength(0);
+    expect(service.panelItems({ namespace, layer: "L1" }).items).toHaveLength(0);
+    expect(() => service.getMemory(firstSpanId!, { namespace })).toThrow(/not found/i);
     db.close();
   });
 

From 2b8f186edc81ac4c837ef394ef29cce78d4b1584 Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Thu, 15 Oct 2026 15:16:08 +0800
Subject: [PATCH 50/85] fix: emit SHA-256 checksum files for Agent runtime
 packages

---
 App/memmy-agent/scripts/build-runtime.mjs     | 12 +++-----
 .../scripts/write-runtime-release.mjs         | 16 ++++++++++
 tests/runtime-artifacts.test.mjs              | 29 ++++++++++++++++++-
 3 files changed, 48 insertions(+), 9 deletions(-)
 create mode 100644 App/memmy-agent/scripts/write-runtime-release.mjs

diff --git a/App/memmy-agent/scripts/build-runtime.mjs b/App/memmy-agent/scripts/build-runtime.mjs
index 4ca5bd08e..e87216ab4 100644
--- a/App/memmy-agent/scripts/build-runtime.mjs
+++ b/App/memmy-agent/scripts/build-runtime.mjs
@@ -1,14 +1,13 @@
 #!/usr/bin/env node
 import { npmInvocation } from "../../../scripts/internal/shared/npm-invocation.mjs";
-import { createHash } from "node:crypto";
-import { createReadStream } from "node:fs";
-import { cp, mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
 import { bundleRuntime } from "../../../scripts/internal/shared/bundle-runtime.mjs";
+import { writeAgentRuntimeRelease } from "./write-runtime-release.mjs";
 
 if (Number(process.versions.node.split(".")[0]) < 22) throw new Error("Agent runtime requires Node 22 or newer.");
 
@@ -43,12 +42,9 @@ try {
   const name = `memmy-agent-runtime-${manifest.version}-${target}.tgz`;
   const archive = join(outputRoot, name);
   run("tar", ["-czf", archive, "-C", destination, "package"], agentRoot);
-  const hash = createHash("sha256");
-  for await (const chunk of createReadStream(archive)) hash.update(chunk);
-  await writeJson(join(outputRoot, `agent-release-${target}.json`), {
-    version: manifest.version, assets: { [target]: { name, sha256: hash.digest("hex"), size: (await stat(archive)).size } }
-  });
+  const asset = await writeAgentRuntimeRelease(archive, manifest.version, target);
   console.log(archive);
+  console.log(`SHA-256: ${asset.sha256}\nChecksum file: ${archive}.sha256`);
 } finally {
   await rm(temporaryRoot, { recursive: true, force: true });
 }
diff --git a/App/memmy-agent/scripts/write-runtime-release.mjs b/App/memmy-agent/scripts/write-runtime-release.mjs
new file mode 100644
index 000000000..048a461f0
--- /dev/null
+++ b/App/memmy-agent/scripts/write-runtime-release.mjs
@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+export async function writeAgentRuntimeRelease(archive, version, target) {
+  // Hash the finished archive, including native dependencies, rather than its version or source files.
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(archive)) hash.update(chunk);
+  const asset = { name: basename(archive), sha256: hash.digest("hex"), size: (await stat(archive)).size };
+  await writeFile(`${archive}.sha256`, `${asset.sha256}  ${asset.name}\n`);
+  await writeFile(join(dirname(archive), `agent-release-${target}.json`), `${JSON.stringify({
+    version, assets: { [target]: asset }
+  }, null, 2)}\n`);
+  return asset;
+}
diff --git a/tests/runtime-artifacts.test.mjs b/tests/runtime-artifacts.test.mjs
index 6e8379d76..c345d8b57 100644
--- a/tests/runtime-artifacts.test.mjs
+++ b/tests/runtime-artifacts.test.mjs
@@ -6,6 +6,7 @@ import { join, resolve } from "node:path";
 import { afterEach, expect, it } from "vitest";
 import YAML from "yaml";
 import { buildMemoryAll, verifyMemoryDownload } from "../scripts/internal/shared/build-memory-all.mjs";
+import { writeAgentRuntimeRelease } from "../App/memmy-agent/scripts/write-runtime-release.mjs";
 
 const root = resolve(import.meta.dirname, "..");
 const collector = join(root, "scripts/internal/shared/collect-runtime-artifacts.mjs");
@@ -30,7 +31,8 @@ it("collects all target artifacts and rejects corrupted downloads", async () =>
       corrupted = join(input, name);
       await writeFile(corrupted, bytes);
       const metadata = { version, assets: { [target]: { name, size: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") } } };
-      await writeFile(join(input, kind === "agent" ? `agent-release-${target}.json` : "memory-release.json"), JSON.stringify(metadata));
+      if (kind === "agent") await writeAgentRuntimeRelease(corrupted, version, target);
+      else await writeFile(join(input, "memory-release.json"), JSON.stringify(metadata));
     }
   }
   const args = [collector, join(directory, "input"), join(directory, "output")];
@@ -55,6 +57,31 @@ it("collects all target artifacts and rejects corrupted downloads", async () =>
   expect(() => execFileSync(process.execPath, memoryArgs, { stdio: "pipe" })).toThrow();
 });
 
+it("writes the finished Agent archive checksum and replaces it when same-version content changes", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "agent-release-sha-"));
+  roots.push(directory);
+  await mkdir(join(directory, "package"));
+  const version = "1.2.3";
+  const target = "darwin-arm64";
+  const name = `memmy-agent-runtime-${version}-${target}.tgz`;
+  const archive = join(directory, name);
+  let previous;
+  for (const content of ["first build", "changed content at the same version"]) {
+    await writeFile(join(directory, "package/main.js"), content);
+    execFileSync("tar", ["-czf", archive, "-C", directory, "package"], { env: { ...process.env, COPYFILE_DISABLE: "1" } });
+    const asset = await writeAgentRuntimeRelease(archive, version, target);
+    const bytes = await readFile(archive);
+    const expected = createHash("sha256").update(bytes).digest("hex");
+    expect(asset).toEqual({ name, sha256: expected, size: bytes.length });
+    expect(await readFile(`${archive}.sha256`, "utf8")).toBe(`${expected}  ${name}\n`);
+    expect(JSON.parse(await readFile(join(directory, `agent-release-${target}.json`)))).toEqual({
+      version, assets: { [target]: asset }
+    });
+    if (previous) expect(expected).not.toBe(previous);
+    previous = expected;
+  }
+});
+
 it("rejects local changes before uploading source", async () => {
   await expect(buildMemoryAll({ run: () => " M package.json" })).rejects.toThrow("Commit your local changes");
 });

From d698dd4747f5a3c75ae2be9c28c3a153dce28a7a Mon Sep 17 00:00:00 2001
From: Yicheng <yicheng@yichengs-MacBook-Pro-297.local>
Date: Thu, 15 Oct 2026 16:40:30 +0800
Subject: [PATCH 51/85] fix: clarify missing ASR model error

---
 App/frontend/desktop/src/i18n/messages.ts         |  2 ++
 App/frontend/desktop/src/pages/home-page.tsx      | 15 ++++++++++++++-
 .../desktop/src/pages/tests/home-page.test.tsx    |  7 +++++++
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index a7ddec3d2..1a667ab29 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -546,6 +546,7 @@ export const zhCNMessages = {
   "home.media.addPhotoFile": "添加图片和文件",
   "home.voiceInput": "语音输入",
   "home.asrEmptyAudio": "没有录到有效音频，请稍微说久一点再发送",
+  "home.asrNotConfigured": "未配置 ASR 模型，请先配置后再使用语音输入",
   "home.asrFailedWithMessage": "语音识别失败：{message}",
   "home.asrFailed": "语音识别失败，请重试",
   "home.suggestion.one": "整理最近的 Agent 任务",
@@ -2287,6 +2288,7 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "home.media.addPhotoFile": "Add images and files",
   "home.voiceInput": "Voice input",
   "home.asrEmptyAudio": "No valid audio was recorded. Please speak a little longer and try again.",
+  "home.asrNotConfigured": "No ASR model is configured. Configure one before using voice input.",
   "home.asrFailedWithMessage": "Speech recognition failed: {message}",
   "home.asrFailed": "Speech recognition failed. Please try again.",
   "home.suggestion.one": "Organize recent Agent tasks",
diff --git a/App/frontend/desktop/src/pages/home-page.tsx b/App/frontend/desktop/src/pages/home-page.tsx
index d823d2eae..55ee911f5 100644
--- a/App/frontend/desktop/src/pages/home-page.tsx
+++ b/App/frontend/desktop/src/pages/home-page.tsx
@@ -187,6 +187,7 @@ const TRANSLATABLE_AGENT_ERROR_KEYS = new Set<MessageKey>([
   "home.media.error.sendReadFailed",
   "home.media.error.sendFailed",
   "home.media.error.messageTooBig",
+  "home.asrNotConfigured",
   "home.agent.messageNotRecorded",
   "home.agent.executionInterrupted",
   "home.agent.recoveryTimeout",
@@ -3457,6 +3458,9 @@ export function agentErrorText(error: string | null, t: HomeTranslate = defaultH
   if (TRANSLATABLE_AGENT_ERROR_KEYS.has(error as MessageKey)) {
     return t(error as MessageKey);
   }
+  if (isAsrModelNotConfiguredError(error)) {
+    return t("home.asrNotConfigured");
+  }
   const stableCode = error.includes(":") ? error.slice(error.lastIndexOf(":") + 1) : error;
   const mapped = AGENT_OPERATION_ERROR_MESSAGE_KEYS[stableCode];
   if (mapped) return t(mapped);
@@ -3593,15 +3597,24 @@ function browserStorage(): SlashCommandStorageLike | null {
  * @param error An unknown exception.
  * @returns Error text or a MessageKey that can be shown to the user.
  */
-function toReadableAsrError(error: unknown, t: HomeTranslate = defaultHomeTranslate): string {
+export function toReadableAsrError(error: unknown, t: HomeTranslate = defaultHomeTranslate): string {
   if (error instanceof MicrophonePermissionError) {
     return microphonePermissionDeniedMessageKey();
   }
+  if (isAsrModelNotConfiguredError(error)) {
+    return "home.asrNotConfigured";
+  }
   return error instanceof Error && error.message
     ? t("home.asrFailedWithMessage", { message: error.message })
     : t("home.asrFailed");
 }
 
+/** Detects backend ASR configuration errors that should not fall through to the generic operation error. */
+function isAsrModelNotConfiguredError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /ASR (?:model catalog|model|client) is not configured|Assigned ASR model is unavailable|ASR requires account or BYOK mode/i.test(message);
+}
+
 function readableError(error: unknown): string {
   return error instanceof Error && error.message ? error.message : String(error);
 }
diff --git a/App/frontend/desktop/src/pages/tests/home-page.test.tsx b/App/frontend/desktop/src/pages/tests/home-page.test.tsx
index d2393cb6a..b6b836fdc 100644
--- a/App/frontend/desktop/src/pages/tests/home-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/home-page.test.tsx
@@ -41,6 +41,7 @@ import {
   resolveComposerCommandDraft,
   shouldAcceptAgentStatusResult,
   submitAgentComposerMessage,
+  toReadableAsrError,
   updateAgentComposerOverlayHeight,
   updateComposerDraftForScope,
   fileToPendingAttachment,
@@ -1163,6 +1164,12 @@ describe("HomePage", () => {
     expect(agentErrorText(null)).toBeNull();
   });
 
+  it("shows a dedicated message when voice input has no ASR model configured", () => {
+    expect(toReadableAsrError(new Error("Assigned ASR model is unavailable"))).toBe("home.asrNotConfigured");
+    expect(agentErrorText("home.asrNotConfigured")).toBe("未配置 ASR 模型，请先配置后再使用语音输入");
+    expect(agentErrorText("语音识别失败：ASR model catalog is not configured")).toBe("未配置 ASR 模型，请先配置后再使用语音输入");
+  });
+
   it("keeps the model unavailable reason when a tombstone blocks new-chat creation", async () => {
     const dispatch = vi.fn();
 

From bb21412ac179f0eb5eb11dbecce02a482629e731 Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Thu, 15 Oct 2026 17:15:26 +0800
Subject: [PATCH 52/85] fix: remove whole-turn deadlines from Memmy API

---
 App/memmy-agent/src/config/schema.ts          |  3 --
 .../src/entrypoints/cli/commands.ts           |  4 +-
 .../src/entrypoints/openai-like-api/server.ts | 49 ++++++-------------
 .../tests/entrypoints/cli/commands.test.ts    |  6 +--
 .../openai-like-api/api-stream.test.ts        | 32 +++++++++++-
 .../openai-like-api/openai-api.test.ts        |  1 -
 6 files changed, 50 insertions(+), 45 deletions(-)

diff --git a/App/memmy-agent/src/config/schema.ts b/App/memmy-agent/src/config/schema.ts
index 9820534b8..317950ec4 100644
--- a/App/memmy-agent/src/config/schema.ts
+++ b/App/memmy-agent/src/config/schema.ts
@@ -1028,14 +1028,12 @@ export class HeartbeatConfig extends Base {
 export class ApiConfig extends Base {
   host = "127.0.0.1";
   port = 18990;
-  timeout = 120;
   apiKey: string | null = null;
 
   constructor(init: Dict = {}) {
     super();
     this.host = pick(init, ["host"], this.host);
     this.port = pick(init, ["port"], this.port);
-    this.timeout = pick(init, ["timeout"], this.timeout);
     this.apiKey = pick(init, ["apiKey"], null);
   }
 
@@ -1043,7 +1041,6 @@ export class ApiConfig extends Base {
     return {
       host: this.host,
       port: this.port,
-      timeout: this.timeout,
       apiKey: this.apiKey,
     };
   }
diff --git a/App/memmy-agent/src/entrypoints/cli/commands.ts b/App/memmy-agent/src/entrypoints/cli/commands.ts
index 87c72cd63..1d5aca651 100644
--- a/App/memmy-agent/src/entrypoints/cli/commands.ts
+++ b/App/memmy-agent/src/entrypoints/cli/commands.ts
@@ -597,7 +597,7 @@ export async function main(argv: string[] = process.argv): Promise<void> {
     .description("Start the OpenAI-compatible API server.")
     .option("-p, --port <port>", "API server port")
     .option("-H, --host <host>", "Bind address")
-    .option("-t, --timeout <seconds>", "Per-request timeout")
+    .option("-t, --timeout <seconds>", "Deprecated; agent turns have no total time limit")
     .option("-w, --workspace <dir>", "Workspace directory")
     .option("-c, --config <path>", "Path to config file")
     .option("-v, --verbose", "Enable verbose runtime logs", false)
@@ -923,7 +923,7 @@ export async function serve({
   const appServer = createApp(
     loop,
     resolved.model,
-    timeout == null ? loaded.api.timeout : Number(timeout),
+
   );
   const bindHost = host ?? loaded.api.host;
   const bindPort = port == null ? loaded.api.port : Number(port);
diff --git a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
index 5abfd2dd1..4a4c41a92 100644
--- a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
+++ b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
@@ -24,7 +24,6 @@ export class RequestBodyTooLarge extends Error {
 type ApiContext = {
   agentLoop: any;
   modelName: string;
-  requestTimeout: number;
   sessionLocks: Map<string, Promise<void>>;
 };
 
@@ -188,33 +187,20 @@ async function parseMultipart(request: Request): Promise<[string, string[], stri
   return [text, mediaPaths, sessionId, model];
 }
 
-async function withTimeout<T>(promise: Promise<T>, timeoutS: number): Promise<T> {
-  let timer: NodeJS.Timeout | undefined;
-  const timeout = new Promise<never>((resolve, reject) => {
-    void resolve;
-    timer = setTimeout(() => reject(new Error(`Request timed out after ${timeoutS}s`)), timeoutS * 1000);
-    timer.unref?.();
-  });
-  try {
-    return await Promise.race([promise, timeout]);
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
-}
-
 async function withSessionLock<T>(ctx: ApiContext, sessionKey: string, fn: () => Promise<T>): Promise<T> {
   const previous = ctx.sessionLocks.get(sessionKey) ?? Promise.resolve();
   let release!: () => void;
   const current = new Promise<void>((resolve) => {
     release = resolve;
   });
-  ctx.sessionLocks.set(sessionKey, previous.then(() => current, () => current));
+  const queued = previous.then(() => current, () => current);
+  ctx.sessionLocks.set(sessionKey, queued);
   await previous.catch(() => undefined);
   try {
     return await fn();
   } finally {
     release();
-    if (ctx.sessionLocks.get(sessionKey) === current) ctx.sessionLocks.delete(sessionKey);
+    if (ctx.sessionLocks.get(sessionKey) === queued) ctx.sessionLocks.delete(sessionKey);
   }
 }
 
@@ -259,7 +245,6 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
   const context = ctx ?? {
     agentLoop: null,
     modelName: "memmy",
-    requestTimeout: 120,
     sessionLocks: new Map<string, Promise<void>>(),
   };
   const contentType = request.headers.get("content-type") ?? "";
@@ -367,17 +352,13 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
           try {
             await withSessionLock(context, sessionKey, async () => {
               requestTiming("api.session_lock_acquired");
-              const response = await withTimeout(
-                Promise.resolve(
-                  callAgent(context, {
-                    ...baseArgs,
-                    onProgress,
-                    onStream,
-                    onStreamEnd,
-                  }),
-                ),
-                context.requestTimeout,
-              );
+              // Model and tool calls own their deadlines; a whole turn has none.
+              const response = await callAgent(context, {
+                ...baseArgs,
+                onProgress,
+                onStream,
+                onStreamEnd,
+              });
               if (!emitted) {
                 const finalText = responseText(response);
                 if (finalText.trim()) write(sseChunk(finalText, context.modelName, chunkId));
@@ -417,11 +398,11 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
 
   try {
     const reply = await withSessionLock(context, sessionKey, async () => {
-      const first = await withTimeout(Promise.resolve(callAgent(context, baseArgs)), context.requestTimeout);
+      const first = await callAgent(context, baseArgs);
       let textResponse = responseText(first);
       let usage = responseUsage(first);
       if (!textResponse.trim()) {
-        const retry = await withTimeout(Promise.resolve(callAgent(context, baseArgs)), context.requestTimeout);
+        const retry = await callAgent(context, baseArgs);
         textResponse = responseText(retry);
         usage = mergeUsageRecords(usage, responseUsage(retry));
         if (!textResponse.trim()) textResponse = EMPTY_FINAL_RESPONSE_MESSAGE;
@@ -430,8 +411,6 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
     });
     return Response.json(chatCompletionResponse(reply.text, context.modelName, reply.usage));
   } catch (err) {
-    const message = (err as Error).message ?? "";
-    if (message.startsWith("Request timed out")) return errorJson(504, message);
     return errorJson(500, "Internal server error", "server_error");
   }
 }
@@ -487,13 +466,13 @@ export async function handleHealth(): Promise<Response> {
 export function createApp(
   agentLoopOrConfig: any = null,
   modelName = "memmy",
-  requestTimeout = 120,
+  // Accepted for callers built against older runtimes; never limits a turn.
+  _legacyRequestTimeout?: number,
 ): { fetch: (request: Request) => Promise<Response>; context: ApiContext } {
   const agentLoop = agentLoopOrConfig instanceof Config || agentLoopOrConfig == null ? null : agentLoopOrConfig;
   const ctx: ApiContext = {
     agentLoop,
     modelName,
-    requestTimeout,
     sessionLocks: new Map<string, Promise<void>>(),
   };
   return {
diff --git a/App/memmy-agent/tests/entrypoints/cli/commands.test.ts b/App/memmy-agent/tests/entrypoints/cli/commands.test.ts
index 361b34048..eb1e1e3b1 100644
--- a/App/memmy-agent/tests/entrypoints/cli/commands.test.ts
+++ b/App/memmy-agent/tests/entrypoints/cli/commands.test.ts
@@ -531,7 +531,7 @@ describe("CLI command helpers", () => {
       .toThrow("unsupported config key");
   });
 
-  it("serve uses api.timeout from config when no CLI timeout override is supplied", async () => {
+  it("serve ignores legacy api.timeout while a task is still executing", async () => {
     const root = tempRoot("memmy-serve-timeout-");
     const workspace = path.join(root, "workspace");
     const configPath = writeConfig(root, {
@@ -561,8 +561,8 @@ describe("CLI command helpers", () => {
       });
       const body = await response.json() as any;
 
-      expect(response.status).toBe(504);
-      expect(body.error.message).toContain("Request timed out after 0.01s");
+      expect(response.status).toBe(200);
+      expect(body.choices[0].message.content).toBe("late");
       expect(fs.existsSync(path.join(workspace, "AGENTS.md"))).toBe(true);
     } finally {
       await closeServer(server);
diff --git a/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts b/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
index e0d19056b..6f3ca300a 100644
--- a/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
+++ b/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { SSE_DONE, sseChunk, sseMemmyEvent, createApp } from "../../../src/entrypoints/openai-like-api/server.js";
 
 function request(body: unknown): Request {
@@ -307,3 +307,33 @@ describe("SSE chat completions", () => {
     expect(body).not.toContain("[DONE]");
   });
 });
+
+for (const stream of [true, false]) {
+  it(`keeps a silent long-running task alive (stream=${stream})`, async () => {
+    vi.useFakeTimers();
+    let release!: () => void;
+    let started!: () => void;
+    const entered = new Promise<void>((resolve) => { started = resolve; });
+    const gate = new Promise<void>((resolve) => { release = resolve; });
+    try {
+      const app = createApp({ processDirect: async () => {
+        started();
+        await gate;
+        return "long tool finished";
+      } }, "m", 600);
+      let settled = false;
+      const result = app.fetch(request({ messages: [{ role: "user", content: "long tool" }], stream }))
+        .then((response) => response.text());
+      void result.then(() => { settled = true; });
+      await entered;
+      await vi.advanceTimersByTimeAsync(2 * 60 * 60 * 1000);
+      expect(settled).toBe(false);
+      release();
+      expect(await result).toContain("long tool finished");
+      expect(app.context.sessionLocks.size).toBe(0);
+    } finally {
+      release?.();
+      vi.useRealTimers();
+    }
+  });
+}
diff --git a/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts b/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts
index fe01a530e..dbcdb9508 100644
--- a/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts
+++ b/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts
@@ -122,7 +122,6 @@ describe("OpenAI-compatible API request validation", () => {
       {
         agentLoop: { processDirect: async () => "unused" },
         modelName: "test-model",
-        requestTimeout: 10,
         sessionLocks: new Map(),
       },
     );

From b596123f37156763bb4f31c0d9565ad56c510387 Mon Sep 17 00:00:00 2001
From: ZongYue <zongyue99@163.com>
Date: Thu, 15 Oct 2026 17:20:33 +0800
Subject: [PATCH 53/85] fix: cancel Memmy turns only through explicit stop
 requests

---
 .../src/entrypoints/cli/commands.ts           |  4 +
 .../src/entrypoints/openai-like-api/server.ts | 65 +++++++++++++++--
 .../tests/entrypoints/cli/commands.test.ts    | 50 +++++++++++++
 .../openai-like-api/api-stream.test.ts        | 73 +++++++++++++++++++
 .../openai-like-api/openai-api.test.ts        |  1 +
 5 files changed, 188 insertions(+), 5 deletions(-)

diff --git a/App/memmy-agent/src/entrypoints/cli/commands.ts b/App/memmy-agent/src/entrypoints/cli/commands.ts
index 1d5aca651..98ec75e89 100644
--- a/App/memmy-agent/src/entrypoints/cli/commands.ts
+++ b/App/memmy-agent/src/entrypoints/cli/commands.ts
@@ -896,6 +896,10 @@ async function writeNodeResponse(res: http.ServerResponse, response: Response):
     return;
   }
   const nodeStream = Readable.fromWeb(response.body as any);
+  // A silent tool may run for a long time. Expose admission before the first delta.
+  res.flushHeaders();
+  nodeStream.on("error", () => res.destroy());
+  res.once("close", () => nodeStream.destroy());
   nodeStream.pipe(res);
 }
 
diff --git a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
index 4a4c41a92..325100c0e 100644
--- a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
+++ b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
@@ -25,6 +25,7 @@ type ApiContext = {
   agentLoop: any;
   modelName: string;
   sessionLocks: Map<string, Promise<void>>;
+  activeRequests: Map<string, { controller: AbortController; done: Promise<void> }>;
 };
 
 type ChatCompletionUsage = {
@@ -215,6 +216,7 @@ async function callAgent(ctx: ApiContext, args: Record<string, any>): Promise<an
     onProgress: args.onProgress,
     onStream: args.onStream,
     onStreamEnd: args.onStreamEnd,
+    abortSignal: args.abortSignal,
   };
   const isAgentLoopStyle = typeof loop?.processMessageInternal === "function";
   if (typeof loop?.processDirect === "function") {
@@ -231,6 +233,8 @@ async function callAgent(ctx: ApiContext, args: Record<string, any>): Promise<an
         metadata: args.metadata,
         sessionKey: args.session_key ?? args.sessionKey,
       }),
+      args.session_key ?? args.sessionKey,
+      { abortSignal: args.abortSignal },
     );
   }
   if (typeof loop === "function") return loop(args);
@@ -246,6 +250,7 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
     agentLoop: null,
     modelName: "memmy",
     sessionLocks: new Map<string, Promise<void>>(),
+    activeRequests: new Map(),
   };
   const contentType = request.headers.get("content-type") ?? "";
   let text = "";
@@ -253,6 +258,7 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
   let sessionId: string | null | undefined;
   let requestedModel: string | null | undefined;
   let stream = false;
+  let requestId: string = crypto.randomUUID();
 
   try {
     if (contentType.startsWith("multipart/")) {
@@ -268,6 +274,12 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
       requestedModel = body.model;
       [text, mediaPaths] = parseJsonContent(body);
       sessionId = body.session_id;
+      if (body.request_id !== undefined) {
+        if (typeof body.request_id !== "string" || !body.request_id.trim() || body.request_id.length > 4096) {
+          return errorJson(400, "Invalid request_id");
+        }
+        requestId = body.request_id;
+      }
     }
   } catch (err) {
     if (err instanceof FileSizeExceeded) return errorJson(413, err.message);
@@ -279,7 +291,18 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
   }
 
   const sessionKey = sessionId ? `api:${sessionId}` : API_SESSION_KEY;
+  const requestKey = JSON.stringify([sessionKey, requestId]);
+  if (context.activeRequests.has(requestKey)) return errorJson(409, "Request is already running");
+  const controller = new AbortController();
+  let finish!: () => void;
+  const done = new Promise<void>((resolve) => { finish = resolve; });
+  context.activeRequests.set(requestKey, { controller, done });
+  const finishRequest = (): void => {
+    context.activeRequests.delete(requestKey);
+    finish();
+  };
   const baseArgs = {
+    abortSignal: controller.signal,
     content: text,
     media: mediaPaths.length ? mediaPaths : null,
     session_key: sessionKey,
@@ -297,12 +320,12 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
     const encoder = new TextEncoder();
     let closed = false;
     const body = new ReadableStream<Uint8Array>({
-      start(controller) {
+      start(streamController) {
         let emitted = false;
         const write = (chunk: string): void => {
           if (closed) return;
           try {
-            controller.enqueue(encoder.encode(chunk));
+            streamController.enqueue(encoder.encode(chunk));
           } catch {
             closed = true;
           }
@@ -311,7 +334,7 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
           if (closed) return;
           closed = true;
           try {
-            controller.close();
+            streamController.close();
           } catch {
             // The client may have already disconnected.
           }
@@ -319,11 +342,13 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
         void (async () => {
           let failed = false;
           const onStream = async (token: string) => {
+            if (controller.signal.aborted) return;
             if (token) requestTiming("api.first_content", true);
             if (token) emitted = true;
             write(sseChunk(token, context.modelName, chunkId));
           };
           const onProgress = withProgressCapabilities(async (content: string, options: Record<string, any> = {}) => {
+            if (controller.signal.aborted) return;
             if (options.reasoning && content) requestTiming("api.first_reasoning", true);
             if (options.reasoning && content) write(sseMemmyEvent("thinking_delta", { text: content }, context.modelName, chunkId));
             if (options.reasoningEnd) write(sseMemmyEvent("thinking_end", {}, context.modelName, chunkId));
@@ -351,6 +376,7 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
           const onStreamEnd = async () => undefined;
           try {
             await withSessionLock(context, sessionKey, async () => {
+              controller.signal.throwIfAborted();
               requestTiming("api.session_lock_acquired");
               // Model and tool calls own their deadlines; a whole turn has none.
               const response = await callAgent(context, {
@@ -359,6 +385,7 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
                 onStream,
                 onStreamEnd,
               });
+              controller.signal.throwIfAborted();
               if (!emitted) {
                 const finalText = responseText(response);
                 if (finalText.trim()) write(sseChunk(finalText, context.modelName, chunkId));
@@ -369,8 +396,8 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
             failed = true;
             const selectionUnavailable = error instanceof Error && error.message === "model_selection_unavailable";
             write(`data: ${JSON.stringify({ error: {
-              code: selectionUnavailable ? "model_selection_unavailable" : "server_error",
-              message: selectionUnavailable ? "会话绑定的模型已不可用，请重新选择模型。" : "Memmy runtime failed while processing the request.",
+              code: controller.signal.aborted ? "cancelled" : selectionUnavailable ? "model_selection_unavailable" : "server_error",
+              message: controller.signal.aborted ? "Task cancelled by user." : selectionUnavailable ? "会话绑定的模型已不可用，请重新选择模型。" : "Memmy runtime failed while processing the request.",
             } })}\n\n`);
           } finally {
             if (!failed) {
@@ -379,6 +406,7 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
             }
             requestTiming("api.finished");
             close();
+            finishRequest();
           }
         })();
       },
@@ -398,11 +426,14 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
 
   try {
     const reply = await withSessionLock(context, sessionKey, async () => {
+      controller.signal.throwIfAborted();
       const first = await callAgent(context, baseArgs);
+      controller.signal.throwIfAborted();
       let textResponse = responseText(first);
       let usage = responseUsage(first);
       if (!textResponse.trim()) {
         const retry = await callAgent(context, baseArgs);
+        controller.signal.throwIfAborted();
         textResponse = responseText(retry);
         usage = mergeUsageRecords(usage, responseUsage(retry));
         if (!textResponse.trim()) textResponse = EMPTY_FINAL_RESPONSE_MESSAGE;
@@ -411,8 +442,30 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
     });
     return Response.json(chatCompletionResponse(reply.text, context.modelName, reply.usage));
   } catch (err) {
+    if (controller.signal.aborted) return errorJson(409, "Task cancelled by user.", "cancelled");
     return errorJson(500, "Internal server error", "server_error");
+  } finally {
+    finishRequest();
+  }
+}
+
+async function handleCancel(request: Request, ctx: ApiContext): Promise<Response> {
+  let body: any;
+  try {
+    body = await request.json();
+  } catch {
+    return errorJson(400, "Invalid JSON body");
+  }
+  if (typeof body?.session_id !== "string" || !body.session_id.trim()
+    || typeof body?.request_id !== "string" || !body.request_id.trim()) {
+    return errorJson(400, "session_id and request_id are required");
   }
+  const key = JSON.stringify([`api:${body.session_id}`, body.request_id]);
+  const active = ctx.activeRequests.get(key);
+  if (!active) return errorJson(404, "Running request not found");
+  active.controller.abort();
+  await active.done;
+  return Response.json({ status: "cancelled" });
 }
 
 function mediaFromToolEvent(event: Record<string, any>): Array<Record<string, string>> {
@@ -474,6 +527,7 @@ export function createApp(
     agentLoop,
     modelName,
     sessionLocks: new Map<string, Promise<void>>(),
+    activeRequests: new Map(),
   };
   return {
     context: ctx,
@@ -481,6 +535,7 @@ export function createApp(
       const url = new URL(request.url);
       if (url.pathname === "/health" && request.method === "GET") return handleHealth();
       if (url.pathname === "/v1/models" && request.method === "GET") return handleModels(request, ctx);
+      if (url.pathname === "/v1/chat/cancel" && request.method === "POST") return handleCancel(request, ctx);
       if (url.pathname === "/v1/chat/completions" && request.method === "POST") return handleChatCompletions(request, ctx);
       return errorJson(404, "not found");
     },
diff --git a/App/memmy-agent/tests/entrypoints/cli/commands.test.ts b/App/memmy-agent/tests/entrypoints/cli/commands.test.ts
index eb1e1e3b1..580a5d4f8 100644
--- a/App/memmy-agent/tests/entrypoints/cli/commands.test.ts
+++ b/App/memmy-agent/tests/entrypoints/cli/commands.test.ts
@@ -2099,3 +2099,53 @@ describe("CLI command parity with memmy test_commands", () => {
     expect(fs.existsSync(path.join(customWorkspace, "cron", "jobs.json"))).toBe(false);
   });
 });
+
+it("serve admits silent tasks immediately and reserves cancellation for explicit stop", async () => {
+  const root = tempRoot("memmy-serve-stop-");
+  const configPath = writeConfig(root, {
+    agents: { defaults: { workspace: path.join(root, "workspace"), model: "openai/test-model" } },
+    api: { host: "127.0.0.1", port: 0 },
+  });
+  let signal!: AbortSignal;
+  let release!: () => void;
+  vi.spyOn(AgentLoop, "fromConfig").mockReturnValue({
+    processMessageInternal() {},
+    async processDirect(_text: string, opts: any) {
+      signal = opts.abortSignal;
+      await new Promise<void>((resolve) => {
+        release = resolve;
+        signal.addEventListener("abort", () => resolve(), { once: true });
+      });
+      return { content: "finished" };
+    },
+    connectMcp: vi.fn(async () => undefined),
+    closeMcp: vi.fn(async () => undefined),
+  } as any);
+  vi.spyOn(console, "log").mockImplementation(() => undefined);
+  const server = await serve({ config: configPath });
+  try {
+    const port = (server.address() as any).port;
+    const base = `http://127.0.0.1:${port}`;
+    const response = await fetch(`${base}/v1/chat/completions`, {
+      method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ messages: [{ role: "user", content: "go" }], stream: true, session_id: "s", request_id: "r" }),
+      signal: AbortSignal.timeout(2000),
+    });
+    expect(response.status).toBe(200);
+    expect(signal.aborted).toBe(false);
+    await response.body!.cancel();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(signal.aborted).toBe(false);
+    const stopped = await fetch(`${base}/v1/chat/cancel`, {
+      method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ session_id: "s", request_id: "r" }),
+      signal: AbortSignal.timeout(2000),
+    });
+    expect(await stopped.json()).toEqual({ status: "cancelled" });
+    expect(signal.aborted).toBe(true);
+    expect((await fetch(`${base}/health`)).status).toBe(200);
+  } finally {
+    release?.();
+    await closeServer(server);
+  }
+});
diff --git a/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts b/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
index 6f3ca300a..1d83d4eb1 100644
--- a/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
+++ b/App/memmy-agent/tests/entrypoints/openai-like-api/api-stream.test.ts
@@ -337,3 +337,76 @@ for (const stream of [true, false]) {
     }
   });
 }
+
+function cancelRequest(sessionId: string, requestId: string): Request {
+  return new Request("http://localhost/v1/chat/cancel", {
+    method: "POST", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ session_id: sessionId, request_id: requestId }),
+  });
+}
+
+it("only an explicit stop cancels its matching request, including after disconnect", async () => {
+  const signals = new Map<string, AbortSignal>();
+  const releases = new Map<string, () => void>();
+  const app = createApp({
+    processMessageInternal() {},
+    async processDirect(_content: string, options: any) {
+      const signal: AbortSignal = options.abortSignal;
+      signals.set(options.sessionKey, signal);
+      await new Promise<void>((resolve) => {
+        releases.set(options.sessionKey, resolve);
+        signal.addEventListener("abort", () => resolve(), { once: true });
+      });
+      return "finished";
+    },
+  }, "m");
+  const start = (session_id: string, request_id: string) => app.fetch(request({
+    messages: [{ role: "user", content: "long tool" }], stream: true, session_id, request_id,
+  }));
+  const first = await start("a", "run-a");
+  const second = await start("b", "run-b");
+  await first.body!.cancel();
+  expect(signals.get("api:a")!.aborted).toBe(false);
+  expect(app.context.activeRequests.size).toBe(2);
+  expect((await start("a", "run-a")).status).toBe(409);
+  expect((await app.fetch(cancelRequest("a", "run-b"))).status).toBe(404);
+  expect(signals.get("api:b")!.aborted).toBe(false);
+  expect((await app.fetch(cancelRequest("a", "run-a"))).status).toBe(200);
+  expect(signals.get("api:a")!.aborted).toBe(true);
+  expect(signals.get("api:b")!.aborted).toBe(false);
+  releases.get("api:b")!();
+  expect(await second.text()).toContain("[DONE]");
+  expect(app.context.activeRequests.size).toBe(0);
+  expect(app.context.sessionLocks.size).toBe(0);
+  const next = await start("a", "run-next");
+  expect((await app.fetch(cancelRequest("a", "run-a"))).status).toBe(404);
+  expect(signals.get("api:a")!.aborted).toBe(false);
+  releases.get("api:a")!();
+  expect(await next.text()).toContain("[DONE]");
+});
+
+it("explicit cancellation ends SSE as cancelled, never as successful completion", async () => {
+  const app = createApp({ processDirect: async (args: any) => {
+    await new Promise<void>((resolve) => args.abortSignal.addEventListener("abort", () => resolve(), { once: true }));
+    return "must not become a successful reply";
+  } }, "m");
+  const response = await app.fetch(request({ messages: [{ role: "user", content: "go" }], stream: true, session_id: "s", request_id: "r" }));
+  const output = response.text();
+  await app.fetch(cancelRequest("s", "r"));
+  const text = await output;
+  expect(text).toContain('"code":"cancelled"');
+  expect(text).not.toContain("[DONE]");
+  expect(text).not.toContain("successful reply");
+});
+
+it("a model or tool error remains a failure, not user cancellation", async () => {
+  let signal!: AbortSignal;
+  const app = createApp({ processDirect: async (args: any) => {
+    signal = args.abortSignal;
+    throw new Error("tool timed out");
+  } }, "m");
+  const response = await app.fetch(request({ messages: [{ role: "user", content: "go" }], stream: true }));
+  expect(await response.text()).toContain('"code":"server_error"');
+  expect(signal.aborted).toBe(false);
+  expect(app.context.activeRequests.size).toBe(0);
+});
diff --git a/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts b/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts
index dbcdb9508..5bc6ad651 100644
--- a/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts
+++ b/App/memmy-agent/tests/entrypoints/openai-like-api/openai-api.test.ts
@@ -123,6 +123,7 @@ describe("OpenAI-compatible API request validation", () => {
         agentLoop: { processDirect: async () => "unused" },
         modelName: "test-model",
         sessionLocks: new Map(),
+        activeRequests: new Map(),
       },
     );
     const body = (await response.json()) as any;

From 30a11991819b75548776a08229577f9396e35839 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=BA=AA=E5=B9=BF=E5=B8=9D?=
 <jiguangdi@jiguangdideMacBook-Pro.local>
Date: Thu, 15 Oct 2026 19:21:23 +0800
Subject: [PATCH 54/85] fix(desktop): render skill markdown and restore slash
 command suggestions

---
 .../desktop/src/api/memmy-agent-client.ts     | 13 -------
 .../src/api/tests/memmy-agent-client.test.ts  | 13 ++++++-
 .../src/pages/agent-command-palette.tsx       | 12 +++++-
 .../src/pages/memory/skills-sub-page.tsx      |  6 ++-
 ...agent-command-palette.interaction.test.tsx | 39 +++++++++++++++++++
 .../tests/agent-command-palette.test.tsx      | 13 ++++++-
 App/frontend/desktop/src/styles.css           |  8 ++++
 7 files changed, 84 insertions(+), 20 deletions(-)
 create mode 100644 App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx

diff --git a/App/frontend/desktop/src/api/memmy-agent-client.ts b/App/frontend/desktop/src/api/memmy-agent-client.ts
index 97ccbd236..2f8d87931 100644
--- a/App/frontend/desktop/src/api/memmy-agent-client.ts
+++ b/App/frontend/desktop/src/api/memmy-agent-client.ts
@@ -350,18 +350,6 @@ const SlashCommandsResponseSchema = z.object({
   commands: z.array(SlashCommandSchema)
 });
 
-const WEBUI_HIDDEN_SLASH_COMMANDS = new Set([
-  "/stop",
-  "/restart",
-  "/dream",
-  "/dream-log",
-  "/dream-restore",
-  "/history",
-  "/pairing",
-  "/help",
-  "/model"
-]);
-
 const SidebarStateSchema = z.object({
   schema_version: z.literal(1),
   pinned_keys: z.array(z.string()),
@@ -1186,7 +1174,6 @@ class HttpMemmyAgentClient implements MemmyAgentClient {
   async listSlashCommands(): Promise<MemmyAgentSlashCommand[]> {
     const response = await this.request("/api/commands", SlashCommandsResponseSchema);
     return response.commands
-      .filter((command) => !WEBUI_HIDDEN_SLASH_COMMANDS.has(command.command))
       .map((command) => ({
         command: command.command,
         title: command.title,
diff --git a/App/frontend/desktop/src/api/tests/memmy-agent-client.test.ts b/App/frontend/desktop/src/api/tests/memmy-agent-client.test.ts
index 63f775c70..d815bd030 100644
--- a/App/frontend/desktop/src/api/tests/memmy-agent-client.test.ts
+++ b/App/frontend/desktop/src/api/tests/memmy-agent-client.test.ts
@@ -397,7 +397,7 @@ describe("memmy-agent client", () => {
     expect(paths).toEqual(["/webui/bootstrap"]);
   });
 
-  it("lists slash commands with bearer token, camelCase mapping, goal exposure, and control-command filtering", async () => {
+  it("lists all server-supported slash commands with bearer token and camelCase mapping", async () => {
     const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
       const url = new URL(String(input));
       if (url.pathname === "/webui/bootstrap") {
@@ -427,9 +427,18 @@ describe("memmy-agent client", () => {
     const client = createMemmyAgentClient({ baseUrl: "http://127.0.0.1:18980", clientId: "frontend-test", fetchFn: fetchMock as typeof fetch });
 
     await expect(client.listSlashCommands()).resolves.toEqual([
+      { command: "/stop", title: "Stop", description: "Stop turn", icon: "square", argHint: "" },
+      { command: "/restart", title: "Restart", description: "Restart agent", icon: "rotate-cw", argHint: "" },
+      { command: "/dream", title: "Dream", description: "Run Dream", icon: "sparkles", argHint: "" },
+      { command: "/dream-log", title: "Dream log", description: "Show Dream log", icon: "book-open", argHint: "" },
+      { command: "/dream-restore", title: "Dream restore", description: "Restore Dream", icon: "undo-2", argHint: "" },
+      { command: "/history", title: "History", description: "Show history", icon: "history", argHint: "[n]" },
       { command: "/goal", title: "Goal", description: "Start goal", icon: "activity", argHint: "<goal>" },
+      { command: "/pairing", title: "Pairing", description: "Manage pairing", icon: "shield", argHint: "" },
+      { command: "/help", title: "Help", description: "Show help", icon: "circle-help", argHint: "" },
       { command: "/status", title: "Status", description: "Show status", icon: "activity", argHint: "" },
-      { command: "/new", title: "New", description: "New chat", icon: "square-pen", argHint: "" }
+      { command: "/new", title: "New", description: "New chat", icon: "square-pen", argHint: "" },
+      { command: "/model", title: "Model", description: "Switch model", icon: "brain", argHint: "[preset]" }
     ]);
   });
 
diff --git a/App/frontend/desktop/src/pages/agent-command-palette.tsx b/App/frontend/desktop/src/pages/agent-command-palette.tsx
index d73271218..64cd18972 100644
--- a/App/frontend/desktop/src/pages/agent-command-palette.tsx
+++ b/App/frontend/desktop/src/pages/agent-command-palette.tsx
@@ -1,3 +1,4 @@
+import { useEffect, useRef } from "react";
 import {
   Activity,
   BookOpen,
@@ -17,7 +18,6 @@ import type { MemmyAgentSlashCommand } from "../api/memmy-agent-client.js";
 import type { MessageKey, ResolvedLanguage } from "../i18n/messages.js";
 
 export const RECENT_SLASH_COMMANDS_STORAGE_KEY = "memmy-agent-recent-slash-commands";
-export const MAX_VISIBLE_SLASH_COMMANDS = 8;
 export const MAX_RECENT_SLASH_COMMANDS = 5;
 
 export type SlashCommandPaletteItem = MemmyAgentSlashCommand & {
@@ -132,6 +132,13 @@ export function localizeSlashCommands(
 }
 
 export function AgentCommandPalette(props: AgentCommandPaletteProps) {
+  const selectedOptionRef = useRef<HTMLButtonElement>(null);
+  const selectedCommand = props.commands[props.selectedIndex]?.command;
+
+  useEffect(() => {
+    selectedOptionRef.current?.scrollIntoView({ block: "nearest" });
+  }, [props.selectedIndex, selectedCommand]);
+
   if (!props.commands.length) {
     return null;
   }
@@ -156,6 +163,7 @@ export function AgentCommandPalette(props: AgentCommandPaletteProps) {
               type="button"
               role="option"
               aria-selected={selected}
+              ref={selected ? selectedOptionRef : undefined}
               onClick={() => props.onSelect(command)}
               className={`w-full rounded-btn px-2.5 py-2 text-left cursor-pointer transition-colors flex items-start gap-2.5 ${selected ? "bg-canvas-oat/80" : "hover:bg-canvas-oat/50"}`}
             >
@@ -203,7 +211,7 @@ export function filterSlashCommands(
   const matched = normalizedQuery
     ? commands.filter((command) => commandMatchesQuery(command, normalizedQuery))
     : sortByRecent(commands, recentCommands);
-  return matched.slice(0, MAX_VISIBLE_SLASH_COMMANDS);
+  return matched;
 }
 
 export function readRecentSlashCommands(storage: SlashCommandStorageLike | null = browserStorage()): string[] {
diff --git a/App/frontend/desktop/src/pages/memory/skills-sub-page.tsx b/App/frontend/desktop/src/pages/memory/skills-sub-page.tsx
index a244761c6..620f85a50 100644
--- a/App/frontend/desktop/src/pages/memory/skills-sub-page.tsx
+++ b/App/frontend/desktop/src/pages/memory/skills-sub-page.tsx
@@ -16,6 +16,7 @@ import { MemoryDrawerDeleteAction } from "./memory-delete-action.js";
 import { toMemoryDetailErrorMessage } from "./memory-detail-error.js";
 import { cleanMemoryBody, cleanMemoryText, drawerEyebrow } from "./memory-display.js";
 import { displayMemoryId } from "./memory-id.js";
+import { MemoryMarkdown } from "./memory-markdown.js";
 import {
   MemoryReferenceTags,
   type MemoryReferenceOpenRequest,
@@ -482,7 +483,10 @@ function SkillDetail(props: {
 
       <SkillTimelineSection entries={props.timeline} />
       {skill.usageGuide && <DetailTextSection title={t("memory.skills.invocationGuide")} body={skill.usageGuide} />}
-      <DetailTextSection title={t("memory.skills.body")} body={skill.body} />
+      <section className="memory-detail-card">
+        <h5 className="memory-detail-card__label">{t("memory.skills.body")}</h5>
+        <MemoryMarkdown text={skill.body || "-"} />
+      </section>
 
       {hasDecisionGuidance && (
         <section className="memory-detail-card">
diff --git a/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx
new file mode 100644
index 000000000..1157fd9bf
--- /dev/null
+++ b/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx
@@ -0,0 +1,39 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import { AgentCommandPalette, filterSlashCommands } from "../agent-command-palette.js";
+
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+it("scrolls to and selects commands beyond the initial visible rows", () => {
+  const names = ["/new", "/restart", "/status", "/model", "/history", "/history-dag", "/goal", "/help", "/pairing"];
+  const commands = filterSlashCommands(names.map((command) => ({
+    command, title: command, description: "", icon: "activity", argHint: ""
+  })), "", []);
+  const scrollIntoView = vi.fn();
+  const originalScroll = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "scrollIntoView");
+  Object.defineProperty(HTMLElement.prototype, "scrollIntoView", { configurable: true, value: scrollIntoView });
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  const onSelect = vi.fn();
+  try {
+    act(() => root.render(<AgentCommandPalette commands={commands} heading="Commands" selectedIndex={0} onSelect={onSelect} />));
+    expect(container.querySelectorAll('[role="option"]')).toHaveLength(names.length);
+    scrollIntoView.mockClear();
+    act(() => root.render(<AgentCommandPalette commands={commands} heading="Commands" selectedIndex={8} onSelect={onSelect} />));
+    const selected = container.querySelector<HTMLButtonElement>('[aria-selected="true"]')!;
+    expect(selected.textContent).toContain("/pairing");
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest" });
+    expect(scrollIntoView.mock.contexts[0]).toBe(selected);
+    act(() => selected.click());
+    expect(onSelect).toHaveBeenCalledWith(commands[8]);
+  } finally {
+    act(() => root.unmount());
+    container.remove();
+    if (originalScroll) Object.defineProperty(HTMLElement.prototype, "scrollIntoView", originalScroll);
+    else Reflect.deleteProperty(HTMLElement.prototype, "scrollIntoView");
+  }
+});
diff --git a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
index 09128ee84..8d61354f7 100644
--- a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
@@ -29,10 +29,19 @@ describe("AgentCommandPalette", () => {
     expect(slashQueryFromInput("show /history")).toBeNull();
   });
 
-  it("filters by command metadata and caps visible results", () => {
+  it("filters by command metadata", () => {
     expect(filterSlashCommands(commands, "his", []).map((command) => command.command)).toEqual(["/history"]);
     expect(filterSlashCommands(commands, "preset", []).map((command) => command.command)).toEqual(["/model"]);
-    expect(filterSlashCommands([...commands, ...commands, ...commands], "", [])).toHaveLength(8);
+  });
+
+  it("keeps every available command reachable beyond the first eight results", () => {
+    const available = ["/new", "/restart", "/status", "/model", "/history", "/history-dag", "/goal", "/help", "/pairing", "/last-compaction"]
+      .map((command) => ({ command, title: command, description: "Available command", icon: "activity", argHint: "" }));
+    expect(filterSlashCommands(available, "", [])).toEqual(available);
+    expect(filterSlashCommands(available, "available", [])).toEqual(available);
+    for (const command of available) {
+      expect(filterSlashCommands(available, slashQueryFromInput(command.command)!, [])).toContainEqual(command);
+    }
   });
 
   it("orders empty-query results by recent commands without storing /stop", () => {
diff --git a/App/frontend/desktop/src/styles.css b/App/frontend/desktop/src/styles.css
index 375ca9c0f..c60c44ba3 100644
--- a/App/frontend/desktop/src/styles.css
+++ b/App/frontend/desktop/src/styles.css
@@ -5781,6 +5781,14 @@ body.memmy-platform-windows .memory-drawer {
   margin-top: 3px;
 }
 
+ul.memory-markdown__list {
+  list-style-type: disc;
+}
+
+ol.memory-markdown__list {
+  list-style-type: decimal;
+}
+
 .memory-markdown__quote,
 .memory-log-markdown blockquote {
   margin: 0 0 8px;

From 16920de1374b0d28440168e8dda37bacec9e49fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=BA=AA=E5=B9=BF=E5=B8=9D?=
 <jiguangdi@jiguangdideMacBook-Pro.local>
Date: Thu, 15 Oct 2026 19:37:52 +0800
Subject: [PATCH 55/85] fix(desktop): limit command palette height and surface
 stop in search

---
 .../src/pages/agent-command-palette.tsx       | 11 +++-
 App/frontend/desktop/src/pages/home-page.tsx  |  2 +-
 .../tests/agent-command-palette.test.tsx      | 12 +++-
 .../src/pages/tests/home-page.test.tsx        |  2 +-
 docs/cn/reference/meta.json                   |  2 +-
 docs/cn/reference/slash-commands.mdx          | 65 +++++++++++++++++++
 6 files changed, 86 insertions(+), 8 deletions(-)
 create mode 100644 docs/cn/reference/slash-commands.mdx

diff --git a/App/frontend/desktop/src/pages/agent-command-palette.tsx b/App/frontend/desktop/src/pages/agent-command-palette.tsx
index 64cd18972..acce36bfa 100644
--- a/App/frontend/desktop/src/pages/agent-command-palette.tsx
+++ b/App/frontend/desktop/src/pages/agent-command-palette.tsx
@@ -19,6 +19,9 @@ import type { MessageKey, ResolvedLanguage } from "../i18n/messages.js";
 
 export const RECENT_SLASH_COMMANDS_STORAGE_KEY = "memmy-agent-recent-slash-commands";
 export const MAX_RECENT_SLASH_COMMANDS = 5;
+const DEFAULT_VISIBLE_COMMAND_ROWS = 5;
+const COMMAND_ROW_HEIGHT = 56;
+const COMMAND_LIST_BOTTOM_PADDING = 6;
 
 export type SlashCommandPaletteItem = MemmyAgentSlashCommand & {
   synthetic?: boolean;
@@ -152,7 +155,7 @@ export function AgentCommandPalette(props: AgentCommandPaletteProps) {
         role="listbox"
         aria-labelledby="agent-command-palette-heading"
         className="px-1.5 pb-1.5 overflow-y-auto"
-        style={{ maxHeight: "min(432px, calc(100vh - 260px))" }}
+        style={{ maxHeight: `min(${DEFAULT_VISIBLE_COMMAND_ROWS * COMMAND_ROW_HEIGHT + COMMAND_LIST_BOTTOM_PADDING}px, calc(100vh - 260px))` }}
       >
         {props.commands.map((command, index) => {
           const Icon = iconByName[command.icon] ?? Activity;
@@ -164,6 +167,7 @@ export function AgentCommandPalette(props: AgentCommandPaletteProps) {
               role="option"
               aria-selected={selected}
               ref={selected ? selectedOptionRef : undefined}
+              style={{ height: COMMAND_ROW_HEIGHT, boxSizing: "border-box" }}
               onClick={() => props.onSelect(command)}
               className={`w-full rounded-btn px-2.5 py-2 text-left cursor-pointer transition-colors flex items-start gap-2.5 ${selected ? "bg-canvas-oat/80" : "hover:bg-canvas-oat/50"}`}
             >
@@ -196,10 +200,11 @@ export function slashQueryFromInput(input: string): string | null {
 export function buildVisibleSlashCommands(
   commands: MemmyAgentSlashCommand[],
   isSending: boolean,
-  stopCommand: SlashCommandPaletteItem
+  stopCommand: SlashCommandPaletteItem,
+  query = ""
 ): SlashCommandPaletteItem[] {
   const filtered = commands.filter((command) => command.command !== "/stop");
-  return isSending ? [stopCommand, ...filtered] : filtered;
+  return isSending || query.length > 0 ? [stopCommand, ...filtered] : filtered;
 }
 
 export function filterSlashCommands(
diff --git a/App/frontend/desktop/src/pages/home-page.tsx b/App/frontend/desktop/src/pages/home-page.tsx
index d823d2eae..6f069d929 100644
--- a/App/frontend/desktop/src/pages/home-page.tsx
+++ b/App/frontend/desktop/src/pages/home-page.tsx
@@ -1539,7 +1539,7 @@ export function HomePage() {
     lastCompactionSlashCommand,
     ...localizedSlashCommands.filter((command) => command.command !== "/last-compaction")
   ];
-  const visibleSlashCommands = buildVisibleSlashCommands(slashCommandsWithLocal, state.agent.isSending, stopSlashCommand);
+  const visibleSlashCommands = buildVisibleSlashCommands(slashCommandsWithLocal, state.agent.isSending, stopSlashCommand, slashQuery ?? "");
   const modeVisibleSlashCommands = selectedComposerCommand
     ? filterGoalModeSlashCommands(visibleSlashCommands, Boolean(state.agent.currentChatId))
     : visibleSlashCommands;
diff --git a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
index 8d61354f7..2a8f53e78 100644
--- a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
@@ -58,11 +58,18 @@ describe("AgentCommandPalette", () => {
     expect(readRecentSlashCommands(storage)).toEqual(["/history", "/model"]);
   });
 
-  it("prepends a synthetic /stop command only while streaming", () => {
+  it("shows /stop while streaming or searching, but not in idle default suggestions", () => {
     const stopCommand: SlashCommandPaletteItem = { command: "/stop", title: "Stop", description: "Cancel turn", icon: "square", argHint: "", synthetic: true };
 
     expect(buildVisibleSlashCommands(commands, false, stopCommand).map((command) => command.command)).not.toContain("/stop");
     expect(buildVisibleSlashCommands([{ ...stopCommand, synthetic: false }, ...commands], true, stopCommand).map((command) => command.command).slice(0, 2)).toEqual(["/stop", "/status"]);
+    for (const input of ["/s", "/stop"]) {
+      const query = slashQueryFromInput(input)!;
+      const visible = buildVisibleSlashCommands([stopCommand, ...commands], false, stopCommand, query);
+      const matches = filterSlashCommands(visible, query, []);
+      expect(matches.filter((command) => command.command === "/stop")).toEqual([stopCommand]);
+    }
+    expect(filterSlashCommands(buildVisibleSlashCommands(commands, false, stopCommand, "model"), "model", [])).not.toContainEqual(stopCommand);
   });
 
   it("localizes builtin command titles and descriptions for Chinese UI", () => {
@@ -110,7 +117,8 @@ describe("AgentCommandPalette", () => {
     expect(html).toContain('aria-selected="true"');
     expect(html).toContain("w-full");
     expect(html).toContain('aria-labelledby="agent-command-palette-heading"');
-    expect(html).toContain("max-height:min(432px, calc(100vh - 260px))");
+    expect(html).toContain("max-height:min(286px, calc(100vh - 260px))");
+    expect(html).toContain("height:56px;box-sizing:border-box");
     expect(html).toContain("rounded-card");
     expect(html).toContain("rounded-btn px-2.5 py-2");
     expect(html).toContain("shrink-0 whitespace-nowrap font-mono");
diff --git a/App/frontend/desktop/src/pages/tests/home-page.test.tsx b/App/frontend/desktop/src/pages/tests/home-page.test.tsx
index d2393cb6a..fc55e1bee 100644
--- a/App/frontend/desktop/src/pages/tests/home-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/home-page.test.tsx
@@ -270,7 +270,7 @@ describe("HomePage", () => {
     expect(source).toContain("const slashCommandsWithLocal = [");
     expect(source).toContain("lastCompactionSlashCommand,");
     expect(source).toContain('...localizedSlashCommands.filter((command) => command.command !== "/last-compaction")');
-    expect(source).toContain("buildVisibleSlashCommands(slashCommandsWithLocal, state.agent.isSending, stopSlashCommand)");
+    expect(source).toContain('buildVisibleSlashCommands(slashCommandsWithLocal, state.agent.isSending, stopSlashCommand, slashQuery ?? "")');
     expect(source).toContain("{statusPanel.open && !slashMenuOpen && (");
     expect(source).toContain("{lastCompactionPanel.open && !slashMenuOpen && (");
     expect(source).toContain("{lastCompactionPanel.open && !statusPanel.open && !slashMenuOpen && (");
diff --git a/docs/cn/reference/meta.json b/docs/cn/reference/meta.json
index 839fef3da..710a84cef 100644
--- a/docs/cn/reference/meta.json
+++ b/docs/cn/reference/meta.json
@@ -1,5 +1,5 @@
 {
   "title": "参考",
   "icon": "Library",
-  "pages": ["openai-api", "memory-api", "local-api", "ports"]
+  "pages": ["slash-commands", "openai-api", "memory-api", "local-api", "ports"]
 }
diff --git a/docs/cn/reference/slash-commands.mdx b/docs/cn/reference/slash-commands.mdx
new file mode 100644
index 000000000..2b3609fde
--- /dev/null
+++ b/docs/cn/reference/slash-commands.mdx
@@ -0,0 +1,65 @@
+---
+title: 斜杠命令一览
+icon: Terminal
+---
+
+本文整理聊天输入框中的全部 14 个斜杠命令，包括 13 个 Agent 内置命令和桌面专用的 `/last-compaction`，不包含终端里的 `memmy` CLI 子命令。
+
+## 输入与提示
+
+- 输入 `/` 后，面板默认显示最多 5 行，其余命令可滚动查看。较小窗口下可见行数会进一步减少。
+- 继续输入名称可筛选命令，例如 `/s`、`/model`、`/history`。筛选不会截断结果。
+- 使用上下方向键选择，Enter 或 Tab 选中，Escape 关闭提示。带参数的命令可继续填写参数后发送。
+- 空闲时，默认列表不显示 `/stop`；输入 `/s` 或 `/stop` 时仍会显示匹配提示。任务运行时，默认列表也会显示 `/stop`。
+- 最近使用的命令优先排列，`/stop` 不计入最近使用记录。
+
+## 完整命令表
+
+方括号表示可选参数，尖括号表示需要替换为实际内容的参数。
+
+| 命令 | 用途 | 参数与可用条件 |
+| --- | --- | --- |
+| `/new` | 停止当前任务并开始全新对话。 | 无参数。桌面中选择后直接执行新会话操作。 |
+| `/stop` | 停止当前任务；后端也支持暂停当前活跃 Goal。 | 无参数。桌面提示项在有任务运行时执行停止，空闲时选中不会创建任务。 |
+| `/restart` | 重启 Agent 进程。 | 无参数。桌面托管运行时由桌面管理器处理重启。 |
+| `/status` | 查看运行时、模型供应商及频道状态。 | 无参数。桌面中打开状态面板。 |
+| `/model [list\|preset]` | 查看当前模型预设、列出预设或切换模型预设。 | 无参数查看当前配置；`/model list` 列出预设；`/model <preset>` 切换至已配置的预设。 |
+| `/history [n]` | 查看已保存的对话消息。 | 默认 10 条，最多 50 条；例如 `/history 5`。不包含命令消息及内部 Goal 续跑上下文。 |
+| `/history-dag` | 查看当前会话的任务状态 DAG。 | 需要启用 `sessionDag.enabled`；关闭时不会出现在后端提供的命令列表中。桌面中打开 DAG 面板。 |
+| `/goal [子命令或目标]` | 创建、查询、暂停、恢复或调整长期目标。 | 完整子命令见下表。桌面中从提示选中 `/goal` 后，会进入目标输入模式。 |
+| `/dream` | 手动触发文件记忆整合。 | 仅在 `fileMemory.enabled=true` 时提供。 |
+| `/dream-log [sha]` | 查看最近一次 Dream 修改，或指定版本的修改。 | 需要启用文件记忆，并已有可用的记忆版本记录。 |
+| `/dream-restore [sha]` | 列出最近 10 个记忆版本，或撤销指定 Dream 修改。 | 需要启用文件记忆及版本记录；指定 `sha` 后恢复到该次修改之前的状态，并创建新的安全提交。 |
+| `/help` | 列出 Agent 内置斜杠命令及说明。 | 不包含桌面本地命令 `/last-compaction`。Dream 命令随文件记忆配置显示。 |
+| `/pairing [子命令]` | 管理频道接入配对请求与授权。 | 支持列出、批准、拒绝及撤销，完整子命令见下表。 |
+| `/last-compaction` | 查看当前会话最近一次文本压缩或 DAG 上下文摘要。 | 桌面专用，打开本地面板；内容取决于当前会话是否已有压缩快照。 |
+
+## Goal 子命令
+
+| 写法 | 行为 |
+| --- | --- |
+| `/goal` 或 `/goal status` | 查看当前 Goal 状态。 |
+| `/goal help` | 查看 Goal 使用说明。 |
+| `/goal <objective>` 或 `/goal create <objective>` | 创建长期目标。 |
+| `/goal pause` | 暂停 Goal，并停止当前 Goal 回合。 |
+| `/goal resume` | 恢复可续跑的 Goal。达到用量限制时需先恢复供应商容量；达到预算限制时需先提高或移除预算。 |
+| `/goal edit <objective>` | 修改非运行状态的 Goal 目标。 |
+| `/goal budget <正整数>` | 设置累计 token 预算。 |
+| `/goal budget none` | 移除累计 token 预算。 |
+| `/goal clear` | 取消并移除当前 Goal。 |
+
+桌面中从提示选中 `/goal` 会将其显示为目标标签，后续输入作为目标内容。若需要执行管理子命令，可直接输入完整命令及参数后发送。目标标签模式只提供状态、DAG 和压缩摘要等辅助命令。
+
+## Pairing 子命令
+
+| 写法 | 行为 |
+| --- | --- |
+| `/pairing` 或 `/pairing list` | 列出待处理配对请求。 |
+| `/pairing approve <code>` | 批准指定配对码。 |
+| `/pairing deny <code>` | 拒绝指定配对码。 |
+| `/pairing revoke <user_id>` | 撤销当前频道中该用户的授权。 |
+| `/pairing revoke <channel> <user_id>` | 撤销指定频道中该用户的授权。 |
+
+## 维护来源
+
+命令定义和执行逻辑位于 `App/memmy-agent/src/command/builtin.ts`，配对子命令位于 `App/memmy-agent/src/integrations/channel-auth/store.ts`。桌面本地命令及交互位于 `App/frontend/desktop/src/pages/home-page.tsx`，提示过滤和展示位于 `App/frontend/desktop/src/pages/agent-command-palette.tsx`。

From 1755344ad368d3f6099097ceb531d4dd17107f9d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=BA=AA=E5=B9=BF=E5=B8=9D?=
 <jiguangdi@jiguangdideMacBook-Pro.local>
Date: Thu, 15 Oct 2026 19:40:01 +0800
Subject: [PATCH 56/85] fix(desktop): match slash suggestions by command name
 prefix

---
 .../src/pages/agent-command-palette.tsx       |  3 +--
 .../tests/agent-command-palette.test.tsx      | 22 ++++++++++++++++---
 docs/cn/reference/slash-commands.mdx          |  2 +-
 3 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/App/frontend/desktop/src/pages/agent-command-palette.tsx b/App/frontend/desktop/src/pages/agent-command-palette.tsx
index acce36bfa..307c14898 100644
--- a/App/frontend/desktop/src/pages/agent-command-palette.tsx
+++ b/App/frontend/desktop/src/pages/agent-command-palette.tsx
@@ -248,8 +248,7 @@ export function updateRecentSlashCommands(command: string, previous: string[]):
 }
 
 function commandMatchesQuery(command: SlashCommandPaletteItem, query: string): boolean {
-  return [command.command, command.title, command.description, command.argHint]
-    .some((value) => value.toLowerCase().includes(query));
+  return command.command.toLowerCase().startsWith(`/${query}`);
 }
 
 function sortByRecent(commands: SlashCommandPaletteItem[], recentCommands: string[]): SlashCommandPaletteItem[] {
diff --git a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
index 2a8f53e78..daeae09d5 100644
--- a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
@@ -29,16 +29,17 @@ describe("AgentCommandPalette", () => {
     expect(slashQueryFromInput("show /history")).toBeNull();
   });
 
-  it("filters by command metadata", () => {
+  it("filters only by command-name prefix, case-insensitively", () => {
     expect(filterSlashCommands(commands, "his", []).map((command) => command.command)).toEqual(["/history"]);
-    expect(filterSlashCommands(commands, "preset", []).map((command) => command.command)).toEqual(["/model"]);
+    expect(filterSlashCommands(commands, "MoD", []).map((command) => command.command)).toEqual(["/model"]);
+    expect(filterSlashCommands(commands, "preset", [])).toEqual([]);
+    expect(filterSlashCommands(commands, "istory", [])).toEqual([]);
   });
 
   it("keeps every available command reachable beyond the first eight results", () => {
     const available = ["/new", "/restart", "/status", "/model", "/history", "/history-dag", "/goal", "/help", "/pairing", "/last-compaction"]
       .map((command) => ({ command, title: command, description: "Available command", icon: "activity", argHint: "" }));
     expect(filterSlashCommands(available, "", [])).toEqual(available);
-    expect(filterSlashCommands(available, "available", [])).toEqual(available);
     for (const command of available) {
       expect(filterSlashCommands(available, slashQueryFromInput(command.command)!, [])).toContainEqual(command);
     }
@@ -72,6 +73,21 @@ describe("AgentCommandPalette", () => {
     expect(filterSlashCommands(buildVisibleSlashCommands(commands, false, stopCommand, "model"), "model", [])).not.toContainEqual(stopCommand);
   });
 
+  it("does not suggest /new when its description contains Stop", () => {
+    const stopCommand: SlashCommandPaletteItem = { command: "/stop", title: "Stop", description: "Cancel turn", icon: "square", argHint: "", synthetic: true };
+    const available = [
+      ...commands,
+      { command: "/new", title: "New chat", description: "Stop the current task and start a fresh conversation.", icon: "square-pen", argHint: "" }
+    ];
+    for (const isSending of [false, true]) {
+      for (const [input, expected] of [["/s", ["/stop", "/status"]], ["/stop", ["/stop"]]] as const) {
+        const query = slashQueryFromInput(input)!;
+        const visible = buildVisibleSlashCommands(available, isSending, stopCommand, query);
+        expect(filterSlashCommands(visible, query, []).map((command) => command.command)).toEqual(expected);
+      }
+    }
+  });
+
   it("localizes builtin command titles and descriptions for Chinese UI", () => {
     const localized = localizeSlashCommands(
       [
diff --git a/docs/cn/reference/slash-commands.mdx b/docs/cn/reference/slash-commands.mdx
index 2b3609fde..48e92f94e 100644
--- a/docs/cn/reference/slash-commands.mdx
+++ b/docs/cn/reference/slash-commands.mdx
@@ -8,7 +8,7 @@ icon: Terminal
 ## 输入与提示
 
 - 输入 `/` 后，面板默认显示最多 5 行，其余命令可滚动查看。较小窗口下可见行数会进一步减少。
-- 继续输入名称可筛选命令，例如 `/s`、`/model`、`/history`。筛选不会截断结果。
+- 继续输入名称可按命令名前缀筛选，不匹配说明文字。例如 `/s` 匹配 `/stop` 和 `/status`，`/stop` 只匹配 `/stop`。筛选不会截断结果。
 - 使用上下方向键选择，Enter 或 Tab 选中，Escape 关闭提示。带参数的命令可继续填写参数后发送。
 - 空闲时，默认列表不显示 `/stop`；输入 `/s` 或 `/stop` 时仍会显示匹配提示。任务运行时，默认列表也会显示 `/stop`。
 - 最近使用的命令优先排列，`/stop` 不计入最近使用记录。

From 7de08d598a5667dbaf21e05612c59ee8e5e245fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=BA=AA=E5=B9=BF=E5=B8=9D?=
 <jiguangdi@jiguangdideMacBook-Pro.local>
Date: Thu, 15 Oct 2026 19:47:15 +0800
Subject: [PATCH 57/85] feat(desktop): complete slash subcommands and model
 presets

---
 .../src/pages/agent-command-palette.tsx       | 42 +++++++++++++++---
 App/frontend/desktop/src/pages/home-page.tsx  |  2 +-
 .../tests/agent-command-palette.test.tsx      | 44 ++++++++++++++++++-
 docs/cn/reference/slash-commands.mdx          |  2 +
 4 files changed, 83 insertions(+), 7 deletions(-)

diff --git a/App/frontend/desktop/src/pages/agent-command-palette.tsx b/App/frontend/desktop/src/pages/agent-command-palette.tsx
index 307c14898..959ff4565 100644
--- a/App/frontend/desktop/src/pages/agent-command-palette.tsx
+++ b/App/frontend/desktop/src/pages/agent-command-palette.tsx
@@ -23,6 +23,20 @@ const DEFAULT_VISIBLE_COMMAND_ROWS = 5;
 const COMMAND_ROW_HEIGHT = 56;
 const COMMAND_LIST_BOTTOM_PADDING = 6;
 
+// Literal subcommands only; free-form arguments are displayed as hints.
+const SUBCOMMANDS: Record<string, ReadonlyArray<readonly [string, string]>> = {
+  "/goal": [
+    ["status", ""], ["help", ""], ["create", "<objective>"],
+    ["pause", ""], ["resume", ""], ["edit", "<objective>"],
+    ["budget", "<positive-int|none>"], ["budget none", ""], ["clear", ""]
+  ],
+  "/pairing": [
+    ["list", ""], ["approve", "<code>"], ["deny", "<code>"],
+    ["revoke", "[channel] <user_id>"]
+  ],
+  "/model": [["list", ""]]
+};
+
 export type SlashCommandPaletteItem = MemmyAgentSlashCommand & {
   synthetic?: boolean;
 };
@@ -190,11 +204,10 @@ export function AgentCommandPalette(props: AgentCommandPaletteProps) {
 }
 
 export function slashQueryFromInput(input: string): string | null {
-  if (!input.startsWith("/")) {
+  if (!/^\/(?:[^\s/]+(?:[\t ][^\r\n]*)?)?$/.test(input)) {
     return null;
   }
-  const token = input.slice(1);
-  return /\s/.test(token) ? null : token.toLowerCase();
+  return input.slice(1).replace(/[\t ]+/g, " ").toLowerCase();
 }
 
 export function buildVisibleSlashCommands(
@@ -210,9 +223,28 @@ export function buildVisibleSlashCommands(
 export function filterSlashCommands(
   commands: SlashCommandPaletteItem[],
   query: string,
-  recentCommands: string[]
+  recentCommands: string[],
+  modelPresets: ReadonlyArray<{ name: string; available: boolean }> = []
 ): SlashCommandPaletteItem[] {
-  const normalizedQuery = query.toLowerCase();
+  const normalizedQuery = query.toLowerCase().replace(/[\t ]+/g, " ");
+  if (normalizedQuery.includes(" ")) {
+    const [root] = normalizedQuery.split(" ");
+    const parent = commands.find((command) => command.command.toLowerCase() === `/${root}`);
+    if (!parent) return [];
+    const suffixes = [...(SUBCOMMANDS[parent.command.toLowerCase()] ?? [])];
+    if (parent.command === "/model") {
+      for (const preset of modelPresets) {
+        if (preset.available && !/\s/.test(preset.name) && preset.name.toLowerCase() !== "list") {
+          suffixes.push([preset.name, ""]);
+        }
+      }
+    }
+    const depth = normalizedQuery.split(" ").length - 1;
+    return suffixes
+      .filter(([suffix]) => suffix.split(" ").length === depth)
+      .map(([suffix, argHint]) => ({ ...parent, command: `${parent.command} ${suffix}`, argHint }))
+      .filter((command) => commandMatchesQuery(command, normalizedQuery));
+  }
   const matched = normalizedQuery
     ? commands.filter((command) => commandMatchesQuery(command, normalizedQuery))
     : sortByRecent(commands, recentCommands);
diff --git a/App/frontend/desktop/src/pages/home-page.tsx b/App/frontend/desktop/src/pages/home-page.tsx
index 6f069d929..ff74512f9 100644
--- a/App/frontend/desktop/src/pages/home-page.tsx
+++ b/App/frontend/desktop/src/pages/home-page.tsx
@@ -1543,7 +1543,7 @@ export function HomePage() {
   const modeVisibleSlashCommands = selectedComposerCommand
     ? filterGoalModeSlashCommands(visibleSlashCommands, Boolean(state.agent.currentChatId))
     : visibleSlashCommands;
-  const filteredSlashCommands = slashQuery == null ? [] : filterSlashCommands(modeVisibleSlashCommands, slashQuery, recentSlashCommands);
+  const filteredSlashCommands = slashQuery == null ? [] : filterSlashCommands(modeVisibleSlashCommands, slashQuery, recentSlashCommands, state.agent.modelPresets);
   const slashMenuOpen = filteredSlashCommands.length > 0;
   const displayConnectionStatus = state.agent.recoveryKind === "initial"
     ? "connecting"
diff --git a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
index daeae09d5..d46204039 100644
--- a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
@@ -25,7 +25,10 @@ describe("AgentCommandPalette", () => {
   it("detects slash query mode only for a leading command token", () => {
     expect(slashQueryFromInput("/")).toBe("");
     expect(slashQueryFromInput("/his")).toBe("his");
-    expect(slashQueryFromInput("/history 5")).toBeNull();
+    expect(slashQueryFromInput("/history 5")).toBe("history 5");
+    expect(slashQueryFromInput("/GOAL  p")).toBe("goal p");
+    expect(slashQueryFromInput("/goal ")).toBe("goal ");
+    expect(slashQueryFromInput("/goal\npause")).toBeNull();
     expect(slashQueryFromInput("show /history")).toBeNull();
   });
 
@@ -45,6 +48,45 @@ describe("AgentCommandPalette", () => {
     }
   });
 
+  it("matches every literal subcommand at its current depth", () => {
+    const available = ["/goal", "/pairing", "/model", "/history", "/dream-log"].map((command) => ({
+      command, title: command, description: "", icon: "activity", argHint: ""
+    }));
+    const match = (input: string) => filterSlashCommands(available, slashQueryFromInput(input)!, []);
+    const expected = {
+      "/goal ": ["status", "help", "create", "pause", "resume", "edit", "budget", "clear"],
+      "/pairing ": ["list", "approve", "deny", "revoke"],
+      "/model ": ["list"],
+      "/goal budget ": ["none"]
+    };
+    for (const [prefix, suffixes] of Object.entries(expected)) {
+      expect(match(prefix).map((item) => item.command)).toEqual(suffixes.map((suffix) => prefix + suffix));
+      for (const suffix of suffixes) {
+        expect(match(prefix + suffix).map((item) => item.command)).toEqual([prefix + suffix]);
+        expect(match(prefix + suffix[0]).map((item) => item.command)).toContain(prefix + suffix);
+      }
+    }
+    expect(match("/GOAL   P").map((item) => item.command)).toEqual(["/goal pause"]);
+    expect(match("/pairing a")[0]).toMatchObject({ command: "/pairing approve", argHint: "<code>" });
+    expect(match("/goal c").map((item) => item.command)).toEqual(["/goal create", "/goal clear"]);
+    expect(match("/goal create")[0]?.argHint).toBe("<objective>");
+    for (const input of ["/history 5", "/dream-log abc", "/pairing approve abc", "/goal create write tests", "/goal budget 1000", "/goal status ", "/goal my objective"]) {
+      expect(match(input)).toEqual([]);
+    }
+    expect(filterSlashCommands([], "goal p", [])).toEqual([]);
+  });
+
+  it("matches available model preset names without changing their case", () => {
+    const presets = [
+      { name: "FastModel", available: true },
+      { name: "unavailable", available: false }
+    ];
+    expect(filterSlashCommands(commands, "model ", [], presets).map((item) => item.command)).toEqual(["/model list", "/model FastModel"]);
+    expect(filterSlashCommands(commands, "model fa", [], presets)[0]).toMatchObject({ command: "/model FastModel", argHint: "" });
+    expect(filterSlashCommands(commands, "model un", [], presets)).toEqual([]);
+    expect(filterSlashCommands(commands, "model FastModel ", [], presets)).toEqual([]);
+  });
+
   it("orders empty-query results by recent commands without storing /stop", () => {
     const recent = updateRecentSlashCommands("/history", updateRecentSlashCommands("/stop", ["/model"]));
     expect(recent).toEqual(["/history", "/model"]);
diff --git a/docs/cn/reference/slash-commands.mdx b/docs/cn/reference/slash-commands.mdx
index 48e92f94e..742b03681 100644
--- a/docs/cn/reference/slash-commands.mdx
+++ b/docs/cn/reference/slash-commands.mdx
@@ -9,6 +9,8 @@ icon: Terminal
 
 - 输入 `/` 后，面板默认显示最多 5 行，其余命令可滚动查看。较小窗口下可见行数会进一步减少。
 - 继续输入名称可按命令名前缀筛选，不匹配说明文字。例如 `/s` 匹配 `/stop` 和 `/status`，`/stop` 只匹配 `/stop`。筛选不会截断结果。
+- 主命令后输入空格可查看子命令，继续输入则按子命令前缀筛选。例如 `/goal p` 匹配 `/goal pause`，`/pairing a` 匹配 `/pairing approve`，`/goal budget n` 匹配 `/goal budget none`。`/model ` 还会显示当前可用的模型预设，支持按预设名前缀筛选。
+- 选中子命令后会填入完整命令；需要参数时保留空格供继续填写。目标内容、数字、配对码、用户 ID 和版本 SHA 是自由参数，不会被替换成子命令。填写完成后发送执行。
 - 使用上下方向键选择，Enter 或 Tab 选中，Escape 关闭提示。带参数的命令可继续填写参数后发送。
 - 空闲时，默认列表不显示 `/stop`；输入 `/s` 或 `/stop` 时仍会显示匹配提示。任务运行时，默认列表也会显示 `/stop`。
 - 最近使用的命令优先排列，`/stop` 不计入最近使用记录。

From 117f7b2b6b5d359d29d1cb259f6586512bee6fff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=BA=AA=E5=B9=BF=E5=B8=9D?=
 <jiguangdi@jiguangdideMacBook-Pro.local>
Date: Thu, 15 Oct 2026 19:54:27 +0800
Subject: [PATCH 58/85] fix(desktop): expand exact commands and place closest
 suggestions last

---
 .../src/pages/agent-command-palette.tsx       | 49 ++++++++++++-------
 App/frontend/desktop/src/pages/home-page.tsx  |  8 ++-
 ...agent-command-palette.interaction.test.tsx | 15 +++++-
 .../tests/agent-command-palette.test.tsx      | 38 ++++++++++++--
 docs/cn/reference/slash-commands.mdx          |  4 +-
 5 files changed, 84 insertions(+), 30 deletions(-)

diff --git a/App/frontend/desktop/src/pages/agent-command-palette.tsx b/App/frontend/desktop/src/pages/agent-command-palette.tsx
index 959ff4565..82d5a6ee3 100644
--- a/App/frontend/desktop/src/pages/agent-command-palette.tsx
+++ b/App/frontend/desktop/src/pages/agent-command-palette.tsx
@@ -227,28 +227,39 @@ export function filterSlashCommands(
   modelPresets: ReadonlyArray<{ name: string; available: boolean }> = []
 ): SlashCommandPaletteItem[] {
   const normalizedQuery = query.toLowerCase().replace(/[\t ]+/g, " ");
-  if (normalizedQuery.includes(" ")) {
-    const [root] = normalizedQuery.split(" ");
-    const parent = commands.find((command) => command.command.toLowerCase() === `/${root}`);
-    if (!parent) return [];
-    const suffixes = [...(SUBCOMMANDS[parent.command.toLowerCase()] ?? [])];
-    if (parent.command === "/model") {
-      for (const preset of modelPresets) {
-        if (preset.available && !/\s/.test(preset.name) && preset.name.toLowerCase() !== "list") {
-          suffixes.push([preset.name, ""]);
-        }
+  if (!normalizedQuery) return sortByRecent(commands, recentCommands);
+
+  const [root] = normalizedQuery.split(" ");
+  const parent = commands.find((command) => command.command.toLowerCase() === `/${root}`);
+  const suffixes = [...(SUBCOMMANDS[parent?.command.toLowerCase() ?? ""] ?? [])];
+  if (parent?.command === "/model") {
+    for (const preset of modelPresets) {
+      if (preset.available && !/\s/.test(preset.name) && preset.name.toLowerCase() !== "list") {
+        suffixes.push([preset.name, ""]);
       }
     }
-    const depth = normalizedQuery.split(" ").length - 1;
-    return suffixes
-      .filter(([suffix]) => suffix.split(" ").length === depth)
-      .map(([suffix, argHint]) => ({ ...parent, command: `${parent.command} ${suffix}`, argHint }))
-      .filter((command) => commandMatchesQuery(command, normalizedQuery));
   }
-  const matched = normalizedQuery
-    ? commands.filter((command) => commandMatchesQuery(command, normalizedQuery))
-    : sortByRecent(commands, recentCommands);
-  return matched;
+  const descendants = parent ? suffixes.map(([suffix, argHint]) => ({
+    ...parent, command: `${parent.command} ${suffix}`, argHint
+  })) : [];
+  const depth = normalizedQuery.split(" ").length;
+  const candidates = depth === 1 ? commands : descendants.filter((command) => command.command.split(" ").length === depth);
+  const matched = candidates.filter((command) => commandMatchesQuery(command, normalizedQuery));
+
+  // Expand a complete command immediately, without requiring a trailing space.
+  if (matched.some((command) => command.command.toLowerCase() === `/${normalizedQuery}`)) {
+    matched.push(...descendants.filter((command) =>
+      command.command.split(" ").length === depth + 1
+      && command.command.toLowerCase().startsWith(`/${normalizedQuery} `)
+    ));
+  }
+
+  // Suggestions open above the input: the shortest remaining completion is closest.
+  return matched.sort((left, right) => right.command.length - left.command.length);
+}
+
+export function defaultSlashCommandIndex(query: string | null, count: number): number {
+  return query ? Math.max(0, count - 1) : 0;
 }
 
 export function readRecentSlashCommands(storage: SlashCommandStorageLike | null = browserStorage()): string[] {
diff --git a/App/frontend/desktop/src/pages/home-page.tsx b/App/frontend/desktop/src/pages/home-page.tsx
index ff74512f9..b078950e0 100644
--- a/App/frontend/desktop/src/pages/home-page.tsx
+++ b/App/frontend/desktop/src/pages/home-page.tsx
@@ -55,6 +55,7 @@ import { createModelWorkspace, defaultModelSelectionInput, resolveModelSelection
 import {
   AgentCommandPalette,
   buildVisibleSlashCommands,
+  defaultSlashCommandIndex,
   filterSlashCommands,
   localizeSlashCommands,
   readRecentSlashCommands,
@@ -1587,10 +1588,8 @@ export function HomePage() {
   const composerSubmitDisabled = composerPrimaryAction === "stop" ? composerStopDisabled : composerSendDisabled;
 
   useEffect(() => {
-    if (selectedCommandIndex >= filteredSlashCommands.length) {
-      setSelectedCommandIndex(0);
-    }
-  }, [filteredSlashCommands.length, selectedCommandIndex]);
+    setSelectedCommandIndex(defaultSlashCommandIndex(slashQuery, filteredSlashCommands.length));
+  }, [slashQuery, filteredSlashCommands.length]);
 
   useEffect(() => {
     composerDraftsRef.current = composerDrafts;
@@ -2122,7 +2121,6 @@ export function HomePage() {
   function updateComposerInput(value: string) {
     setCurrentComposerDraft(buildComposerCommandDraft(selectedComposerCommand, value));
     setSlashMenuDismissed(false);
-    setSelectedCommandIndex(0);
     if (
       slashQueryFromInput(value) != null &&
       clients?.memmyAgent &&
diff --git a/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx
index 1157fd9bf..0447d6bb6 100644
--- a/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx
@@ -3,7 +3,7 @@
 import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { expect, it, vi } from "vitest";
-import { AgentCommandPalette, filterSlashCommands } from "../agent-command-palette.js";
+import { AgentCommandPalette, defaultSlashCommandIndex, filterSlashCommands } from "../agent-command-palette.js";
 
 (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -30,6 +30,19 @@ it("scrolls to and selects commands beyond the initial visible rows", () => {
     expect(scrollIntoView.mock.contexts[0]).toBe(selected);
     act(() => selected.click());
     expect(onSelect).toHaveBeenCalledWith(commands[8]);
+
+    const goalMatches = filterSlashCommands(commands, "goal", []);
+    scrollIntoView.mockClear();
+    act(() => root.render(<AgentCommandPalette commands={goalMatches} heading="Commands" selectedIndex={defaultSlashCommandIndex("goal", goalMatches.length)} onSelect={onSelect} />));
+    const goalOptions = container.querySelectorAll<HTMLButtonElement>('[role="option"]');
+    const closest = goalOptions[goalOptions.length - 1]!;
+    expect(goalOptions).toHaveLength(9);
+    expect(closest.getAttribute("aria-selected")).toBe("true");
+    expect(closest.querySelector(".font-mono")?.textContent).toBe("/goal");
+    expect(scrollIntoView.mock.contexts[0]).toBe(closest);
+    expect(container.textContent).toContain("/goal pause");
+    act(() => closest.click());
+    expect(onSelect).toHaveBeenLastCalledWith(expect.objectContaining({ command: "/goal" }));
   } finally {
     act(() => root.unmount());
     container.remove();
diff --git a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
index d46204039..a8a68c207 100644
--- a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
@@ -4,6 +4,7 @@ import { enUSMessages, zhCNMessages } from "../../i18n/messages.js";
 import {
   AgentCommandPalette,
   buildVisibleSlashCommands,
+  defaultSlashCommandIndex,
   filterSlashCommands,
   localizeSlashCommands,
   readRecentSlashCommands,
@@ -60,9 +61,9 @@ describe("AgentCommandPalette", () => {
       "/goal budget ": ["none"]
     };
     for (const [prefix, suffixes] of Object.entries(expected)) {
-      expect(match(prefix).map((item) => item.command)).toEqual(suffixes.map((suffix) => prefix + suffix));
+      expect(match(prefix).map((item) => item.command)).toEqual(suffixes.map((suffix) => prefix + suffix).sort((a, b) => b.length - a.length));
       for (const suffix of suffixes) {
-        expect(match(prefix + suffix).map((item) => item.command)).toEqual([prefix + suffix]);
+        expect(match(prefix + suffix).at(-1)?.command).toBe(prefix + suffix);
         expect(match(prefix + suffix[0]).map((item) => item.command)).toContain(prefix + suffix);
       }
     }
@@ -76,12 +77,41 @@ describe("AgentCommandPalette", () => {
     expect(filterSlashCommands([], "goal p", [])).toEqual([]);
   });
 
+  it("expands exact parent commands without a space and places exact matches last", () => {
+    const available = ["/goal", "/pairing", "/model"].map((command) => ({
+      command, title: command, description: "", icon: "activity", argHint: ""
+    }));
+    const match = (query: string) => filterSlashCommands(available, query, []).map((item) => item.command);
+    expect(match("goal")).toEqual([
+      "/goal status", "/goal create", "/goal resume", "/goal budget",
+      "/goal pause", "/goal clear", "/goal help", "/goal edit", "/goal"
+    ]);
+    expect(match("goal ")).not.toContain("/goal");
+    expect(match("goal budget")).toEqual(["/goal budget none", "/goal budget"]);
+    expect(match("goal budget ")).toEqual(["/goal budget none"]);
+    expect(match("pairing")).toEqual(["/pairing approve", "/pairing revoke", "/pairing list", "/pairing deny", "/pairing"]);
+    expect(match("model")).toEqual(["/model list", "/model"]);
+  });
+
+  it("places closer prefix matches nearest the input and selects the bottom result", () => {
+    const available = ["/history", "/history-dag"].map((command) => ({
+      command, title: command, description: "", icon: "activity", argHint: ""
+    }));
+    for (const query of ["h", "history"]) {
+      const matches = filterSlashCommands(available, query, []);
+      expect(matches.map((item) => item.command)).toEqual(["/history-dag", "/history"]);
+      expect(matches[defaultSlashCommandIndex(query, matches.length)]?.command).toBe("/history");
+    }
+    expect(defaultSlashCommandIndex("", 5)).toBe(0);
+    expect(defaultSlashCommandIndex("missing", 0)).toBe(0);
+  });
+
   it("matches available model preset names without changing their case", () => {
     const presets = [
       { name: "FastModel", available: true },
       { name: "unavailable", available: false }
     ];
-    expect(filterSlashCommands(commands, "model ", [], presets).map((item) => item.command)).toEqual(["/model list", "/model FastModel"]);
+    expect(filterSlashCommands(commands, "model ", [], presets).map((item) => item.command)).toEqual(["/model FastModel", "/model list"]);
     expect(filterSlashCommands(commands, "model fa", [], presets)[0]).toMatchObject({ command: "/model FastModel", argHint: "" });
     expect(filterSlashCommands(commands, "model un", [], presets)).toEqual([]);
     expect(filterSlashCommands(commands, "model FastModel ", [], presets)).toEqual([]);
@@ -122,7 +152,7 @@ describe("AgentCommandPalette", () => {
       { command: "/new", title: "New chat", description: "Stop the current task and start a fresh conversation.", icon: "square-pen", argHint: "" }
     ];
     for (const isSending of [false, true]) {
-      for (const [input, expected] of [["/s", ["/stop", "/status"]], ["/stop", ["/stop"]]] as const) {
+      for (const [input, expected] of [["/s", ["/status", "/stop"]], ["/stop", ["/stop"]]] as const) {
         const query = slashQueryFromInput(input)!;
         const visible = buildVisibleSlashCommands(available, isSending, stopCommand, query);
         expect(filterSlashCommands(visible, query, []).map((command) => command.command)).toEqual(expected);
diff --git a/docs/cn/reference/slash-commands.mdx b/docs/cn/reference/slash-commands.mdx
index 742b03681..f77adfc49 100644
--- a/docs/cn/reference/slash-commands.mdx
+++ b/docs/cn/reference/slash-commands.mdx
@@ -9,7 +9,9 @@ icon: Terminal
 
 - 输入 `/` 后，面板默认显示最多 5 行，其余命令可滚动查看。较小窗口下可见行数会进一步减少。
 - 继续输入名称可按命令名前缀筛选，不匹配说明文字。例如 `/s` 匹配 `/stop` 和 `/status`，`/stop` 只匹配 `/stop`。筛选不会截断结果。
-- 主命令后输入空格可查看子命令，继续输入则按子命令前缀筛选。例如 `/goal p` 匹配 `/goal pause`，`/pairing a` 匹配 `/pairing approve`，`/goal budget n` 匹配 `/goal budget none`。`/model ` 还会显示当前可用的模型预设，支持按预设名前缀筛选。
+- 输入完整主命令即展开子命令，无需等待空格，例如 `/goal` 同时展示它的子命令及主命令自身；输入 `/goal ` 后只保留子命令。完整的 `/goal budget` 同样会展开 `none` 选项。
+- 查询时按剩余补全文字的长度排列：完全匹配或更接近输入的候选放在底部，靠近输入框，并默认选中底部候选；只输入 `/` 时仍按最近使用记录排列。
+- 继续输入可按子命令前缀筛选。例如 `/goal p` 匹配 `/goal pause`，`/pairing a` 匹配 `/pairing approve`，`/goal budget n` 匹配 `/goal budget none`。`/model` 还会展示当前可用的模型预设，支持按预设名前缀筛选。
 - 选中子命令后会填入完整命令；需要参数时保留空格供继续填写。目标内容、数字、配对码、用户 ID 和版本 SHA 是自由参数，不会被替换成子命令。填写完成后发送执行。
 - 使用上下方向键选择，Enter 或 Tab 选中，Escape 关闭提示。带参数的命令可继续填写参数后发送。
 - 空闲时，默认列表不显示 `/stop`；输入 `/s` 或 `/stop` 时仍会显示匹配提示。任务运行时，默认列表也会显示 `/stop`。

From 1cebfe06c26721e85e7d189685bb74c0b96dbb3c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=BA=AA=E5=B9=BF=E5=B8=9D?=
 <jiguangdi@jiguangdideMacBook-Pro.local>
Date: Thu, 15 Oct 2026 19:58:35 +0800
Subject: [PATCH 59/85] fix(desktop): match commands and subcommands as flat
 candidates

---
 .../src/pages/agent-command-palette.tsx       | 36 +++++++------------
 ...agent-command-palette.interaction.test.tsx |  9 ++---
 .../tests/agent-command-palette.test.tsx      | 18 ++++++----
 docs/cn/reference/slash-commands.mdx          |  2 +-
 4 files changed, 31 insertions(+), 34 deletions(-)

diff --git a/App/frontend/desktop/src/pages/agent-command-palette.tsx b/App/frontend/desktop/src/pages/agent-command-palette.tsx
index 82d5a6ee3..56001db96 100644
--- a/App/frontend/desktop/src/pages/agent-command-palette.tsx
+++ b/App/frontend/desktop/src/pages/agent-command-palette.tsx
@@ -227,33 +227,23 @@ export function filterSlashCommands(
   modelPresets: ReadonlyArray<{ name: string; available: boolean }> = []
 ): SlashCommandPaletteItem[] {
   const normalizedQuery = query.toLowerCase().replace(/[\t ]+/g, " ");
-  if (!normalizedQuery) return sortByRecent(commands, recentCommands);
-
-  const [root] = normalizedQuery.split(" ");
-  const parent = commands.find((command) => command.command.toLowerCase() === `/${root}`);
-  const suffixes = [...(SUBCOMMANDS[parent?.command.toLowerCase() ?? ""] ?? [])];
-  if (parent?.command === "/model") {
-    for (const preset of modelPresets) {
-      if (preset.available && !/\s/.test(preset.name) && preset.name.toLowerCase() !== "list") {
-        suffixes.push([preset.name, ""]);
+  const descendants = commands.flatMap((parent) => {
+    const suffixes = [...(SUBCOMMANDS[parent.command.toLowerCase()] ?? [])];
+    if (parent.command.toLowerCase() === "/model") {
+      for (const preset of modelPresets) {
+        if (preset.available && !/\s/.test(preset.name) && preset.name.toLowerCase() !== "list") {
+          suffixes.push([preset.name, ""]);
+        }
       }
     }
-  }
-  const descendants = parent ? suffixes.map(([suffix, argHint]) => ({
-    ...parent, command: `${parent.command} ${suffix}`, argHint
-  })) : [];
-  const depth = normalizedQuery.split(" ").length;
-  const candidates = depth === 1 ? commands : descendants.filter((command) => command.command.split(" ").length === depth);
+    return suffixes.map(([suffix, argHint]) => ({
+      ...parent, command: `${parent.command} ${suffix}`, argHint
+    }));
+  });
+  const candidates = [...commands, ...descendants];
+  if (!normalizedQuery) return sortByRecent(candidates, recentCommands);
   const matched = candidates.filter((command) => commandMatchesQuery(command, normalizedQuery));
 
-  // Expand a complete command immediately, without requiring a trailing space.
-  if (matched.some((command) => command.command.toLowerCase() === `/${normalizedQuery}`)) {
-    matched.push(...descendants.filter((command) =>
-      command.command.split(" ").length === depth + 1
-      && command.command.toLowerCase().startsWith(`/${normalizedQuery} `)
-    ));
-  }
-
   // Suggestions open above the input: the shortest remaining completion is closest.
   return matched.sort((left, right) => right.command.length - left.command.length);
 }
diff --git a/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx
index 0447d6bb6..8f9df00de 100644
--- a/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/agent-command-palette.interaction.test.tsx
@@ -21,7 +21,7 @@ it("scrolls to and selects commands beyond the initial visible rows", () => {
   const onSelect = vi.fn();
   try {
     act(() => root.render(<AgentCommandPalette commands={commands} heading="Commands" selectedIndex={0} onSelect={onSelect} />));
-    expect(container.querySelectorAll('[role="option"]')).toHaveLength(names.length);
+    expect(container.querySelectorAll('[role="option"]')).toHaveLength(commands.length);
     scrollIntoView.mockClear();
     act(() => root.render(<AgentCommandPalette commands={commands} heading="Commands" selectedIndex={8} onSelect={onSelect} />));
     const selected = container.querySelector<HTMLButtonElement>('[aria-selected="true"]')!;
@@ -31,16 +31,17 @@ it("scrolls to and selects commands beyond the initial visible rows", () => {
     act(() => selected.click());
     expect(onSelect).toHaveBeenCalledWith(commands[8]);
 
-    const goalMatches = filterSlashCommands(commands, "goal", []);
+    const goalMatches = filterSlashCommands(commands.filter((command) => !command.command.includes(" ")), "g", []);
     scrollIntoView.mockClear();
-    act(() => root.render(<AgentCommandPalette commands={goalMatches} heading="Commands" selectedIndex={defaultSlashCommandIndex("goal", goalMatches.length)} onSelect={onSelect} />));
+    act(() => root.render(<AgentCommandPalette commands={goalMatches} heading="Commands" selectedIndex={defaultSlashCommandIndex("g", goalMatches.length)} onSelect={onSelect} />));
     const goalOptions = container.querySelectorAll<HTMLButtonElement>('[role="option"]');
     const closest = goalOptions[goalOptions.length - 1]!;
-    expect(goalOptions).toHaveLength(9);
+    expect(goalOptions).toHaveLength(10);
     expect(closest.getAttribute("aria-selected")).toBe("true");
     expect(closest.querySelector(".font-mono")?.textContent).toBe("/goal");
     expect(scrollIntoView.mock.contexts[0]).toBe(closest);
     expect(container.textContent).toContain("/goal pause");
+    expect(container.textContent).toContain("/goal budget none");
     act(() => closest.click());
     expect(onSelect).toHaveBeenLastCalledWith(expect.objectContaining({ command: "/goal" }));
   } finally {
diff --git a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
index a8a68c207..3e1639e12 100644
--- a/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/agent-command-palette.test.tsx
@@ -35,7 +35,7 @@ describe("AgentCommandPalette", () => {
 
   it("filters only by command-name prefix, case-insensitively", () => {
     expect(filterSlashCommands(commands, "his", []).map((command) => command.command)).toEqual(["/history"]);
-    expect(filterSlashCommands(commands, "MoD", []).map((command) => command.command)).toEqual(["/model"]);
+    expect(filterSlashCommands(commands, "MoD", []).map((command) => command.command)).toEqual(["/model list", "/model"]);
     expect(filterSlashCommands(commands, "preset", [])).toEqual([]);
     expect(filterSlashCommands(commands, "istory", [])).toEqual([]);
   });
@@ -43,19 +43,20 @@ describe("AgentCommandPalette", () => {
   it("keeps every available command reachable beyond the first eight results", () => {
     const available = ["/new", "/restart", "/status", "/model", "/history", "/history-dag", "/goal", "/help", "/pairing", "/last-compaction"]
       .map((command) => ({ command, title: command, description: "Available command", icon: "activity", argHint: "" }));
-    expect(filterSlashCommands(available, "", [])).toEqual(available);
+    expect(filterSlashCommands(available, "", []).slice(0, available.length)).toEqual(available);
+    expect(filterSlashCommands(available, "", []).map((item) => item.command)).toContain("/goal budget none");
     for (const command of available) {
       expect(filterSlashCommands(available, slashQueryFromInput(command.command)!, [])).toContainEqual(command);
     }
   });
 
-  it("matches every literal subcommand at its current depth", () => {
+  it("matches every literal subcommand in the same flat candidate list", () => {
     const available = ["/goal", "/pairing", "/model", "/history", "/dream-log"].map((command) => ({
       command, title: command, description: "", icon: "activity", argHint: ""
     }));
     const match = (input: string) => filterSlashCommands(available, slashQueryFromInput(input)!, []);
     const expected = {
-      "/goal ": ["status", "help", "create", "pause", "resume", "edit", "budget", "clear"],
+      "/goal ": ["status", "help", "create", "pause", "resume", "edit", "budget", "budget none", "clear"],
       "/pairing ": ["list", "approve", "deny", "revoke"],
       "/model ": ["list"],
       "/goal budget ": ["none"]
@@ -77,15 +78,19 @@ describe("AgentCommandPalette", () => {
     expect(filterSlashCommands([], "goal p", [])).toEqual([]);
   });
 
-  it("expands exact parent commands without a space and places exact matches last", () => {
+  it("matches parent and descendant commands together and places exact matches last", () => {
     const available = ["/goal", "/pairing", "/model"].map((command) => ({
       command, title: command, description: "", icon: "activity", argHint: ""
     }));
     const match = (query: string) => filterSlashCommands(available, query, []).map((item) => item.command);
     expect(match("goal")).toEqual([
-      "/goal status", "/goal create", "/goal resume", "/goal budget",
+      "/goal budget none", "/goal status", "/goal create", "/goal resume", "/goal budget",
       "/goal pause", "/goal clear", "/goal help", "/goal edit", "/goal"
     ]);
+    expect(match("g")).toEqual(match("goal"));
+    expect(match("goal b")).toEqual(["/goal budget none", "/goal budget"]);
+    expect(match("p")).toEqual(match("pairing"));
+    expect(match("m")).toEqual(match("model"));
     expect(match("goal ")).not.toContain("/goal");
     expect(match("goal budget")).toEqual(["/goal budget none", "/goal budget"]);
     expect(match("goal budget ")).toEqual(["/goal budget none"]);
@@ -112,6 +117,7 @@ describe("AgentCommandPalette", () => {
       { name: "unavailable", available: false }
     ];
     expect(filterSlashCommands(commands, "model ", [], presets).map((item) => item.command)).toEqual(["/model FastModel", "/model list"]);
+    expect(filterSlashCommands(commands, "m", [], presets).map((item) => item.command)).toEqual(["/model FastModel", "/model list", "/model"]);
     expect(filterSlashCommands(commands, "model fa", [], presets)[0]).toMatchObject({ command: "/model FastModel", argHint: "" });
     expect(filterSlashCommands(commands, "model un", [], presets)).toEqual([]);
     expect(filterSlashCommands(commands, "model FastModel ", [], presets)).toEqual([]);
diff --git a/docs/cn/reference/slash-commands.mdx b/docs/cn/reference/slash-commands.mdx
index f77adfc49..fba044273 100644
--- a/docs/cn/reference/slash-commands.mdx
+++ b/docs/cn/reference/slash-commands.mdx
@@ -9,7 +9,7 @@ icon: Terminal
 
 - 输入 `/` 后，面板默认显示最多 5 行，其余命令可滚动查看。较小窗口下可见行数会进一步减少。
 - 继续输入名称可按命令名前缀筛选，不匹配说明文字。例如 `/s` 匹配 `/stop` 和 `/status`，`/stop` 只匹配 `/stop`。筛选不会截断结果。
-- 输入完整主命令即展开子命令，无需等待空格，例如 `/goal` 同时展示它的子命令及主命令自身；输入 `/goal ` 后只保留子命令。完整的 `/goal budget` 同样会展开 `none` 选项。
+- 主命令、完整子命令和可用模型预设处于同一候选列表，统一按完整输入做前缀匹配，不限制层级。例如 `/g` 同时匹配 `/goal`、`/goal pause`、`/goal budget none` 等所有相关项；`/goal ` 只匹配带空格的子命令；`/goal b` 同时匹配 `/goal budget` 和 `/goal budget none`。
 - 查询时按剩余补全文字的长度排列：完全匹配或更接近输入的候选放在底部，靠近输入框，并默认选中底部候选；只输入 `/` 时仍按最近使用记录排列。
 - 继续输入可按子命令前缀筛选。例如 `/goal p` 匹配 `/goal pause`，`/pairing a` 匹配 `/pairing approve`，`/goal budget n` 匹配 `/goal budget none`。`/model` 还会展示当前可用的模型预设，支持按预设名前缀筛选。
 - 选中子命令后会填入完整命令；需要参数时保留空格供继续填写。目标内容、数字、配对码、用户 ID 和版本 SHA 是自由参数，不会被替换成子命令。填写完成后发送执行。

From 4d3228f490ef22ece8f51d4d9c8d96f987f5f18d Mon Sep 17 00:00:00 2001
From: jiachengzhen <jiacz@memtensor.cn>
Date: Thu, 15 Oct 2026 22:53:01 +0800
Subject: [PATCH 60/85] test: distinguish unexpected memory endpoint fixtures

---
 App/shell/desktop/tests/runtime-memory-upgrade.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/App/shell/desktop/tests/runtime-memory-upgrade.test.ts b/App/shell/desktop/tests/runtime-memory-upgrade.test.ts
index dc7d28e53..9ea1fa861 100644
--- a/App/shell/desktop/tests/runtime-memory-upgrade.test.ts
+++ b/App/shell/desktop/tests/runtime-memory-upgrade.test.ts
@@ -70,7 +70,7 @@ async function fixture(options: {
     "const lock = db + '.server.lock'; const version = process.env.FIXTURE_VERSION || '2.1.1';",
     "fs.writeFileSync(lock, JSON.stringify({ pid: process.pid, sqlitePath: db, host: '127.0.0.1', port }));",
     "const server = http.createServer((request, response) => {",
-    "  if (request.url === '/api/v1/health') { response.setHeader('content-type', 'application/json'); response.end(JSON.stringify({ ok: process.env.FIXTURE_IDENTITY !== 'false' && !fs.existsSync(path.join(serviceHome, 'unexpected-service')), protocolVersion: 1, serviceVersion: version })); return; }",
+    "  if (request.url === '/api/v1/health') { response.setHeader('content-type', 'application/json'); const ownsMemory = process.env.FIXTURE_IDENTITY !== 'false' && !fs.existsSync(path.join(serviceHome, 'unexpected-service')); const health = ownsMemory ? { ok: true, protocolVersion: 1, serviceVersion: version } : { serviceVersion: version }; response.end(JSON.stringify(health)); return; }",
     "  if (request.url === '/api/v1/admin/shutdown') { response.end('{}'); setImmediate(shutdown); return; }",
     "  response.writeHead(404); response.end();",
     "});",

From 896ca85d77ee1726fd682ee716781104bd7c158c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Fri, 16 Oct 2026 10:20:39 +0800
Subject: [PATCH 61/85] test(windows): model non-Memory health responses

---
 App/shell/desktop/tests/runtime-memory-upgrade.test.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/App/shell/desktop/tests/runtime-memory-upgrade.test.ts b/App/shell/desktop/tests/runtime-memory-upgrade.test.ts
index dc7d28e53..c112cc514 100644
--- a/App/shell/desktop/tests/runtime-memory-upgrade.test.ts
+++ b/App/shell/desktop/tests/runtime-memory-upgrade.test.ts
@@ -70,7 +70,12 @@ async function fixture(options: {
     "const lock = db + '.server.lock'; const version = process.env.FIXTURE_VERSION || '2.1.1';",
     "fs.writeFileSync(lock, JSON.stringify({ pid: process.pid, sqlitePath: db, host: '127.0.0.1', port }));",
     "const server = http.createServer((request, response) => {",
-    "  if (request.url === '/api/v1/health') { response.setHeader('content-type', 'application/json'); response.end(JSON.stringify({ ok: process.env.FIXTURE_IDENTITY !== 'false' && !fs.existsSync(path.join(serviceHome, 'unexpected-service')), protocolVersion: 1, serviceVersion: version })); return; }",
+    "  if (request.url === '/api/v1/health') {",
+    "    const hasMemoryIdentity = process.env.FIXTURE_IDENTITY !== 'false' && !fs.existsSync(path.join(serviceHome, 'unexpected-service'));",
+    // A non-Memory endpoint lacks the health contract; `ok: false` is valid for a degraded Memory service.
+    "    const health = hasMemoryIdentity ? { ok: true, protocolVersion: 1, serviceVersion: version } : { serviceVersion: version };",
+    "    response.setHeader('content-type', 'application/json'); response.end(JSON.stringify(health)); return;",
+    "  }",
     "  if (request.url === '/api/v1/admin/shutdown') { response.end('{}'); setImmediate(shutdown); return; }",
     "  response.writeHead(404); response.end();",
     "});",

From 083e5e1079efde624f59fa84f546356bae6ca92b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Fri, 16 Oct 2026 11:00:45 +0800
Subject: [PATCH 62/85] =?UTF-8?q?fix:=20=E7=BB=9F=E4=B8=80=20BYOK=20?=
 =?UTF-8?q?=E6=98=BE=E7=A4=BA=E3=80=81=E6=B5=8B=E8=AF=95=E4=B8=8E=E4=BF=9D?=
 =?UTF-8?q?=E5=AD=98=E7=9A=84=E5=87=AD=E6=8D=AE=E6=9D=A5=E6=BA=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

统一已保存凭据的复用条件，绑定角色表单与 endpoint 来源，覆盖返回配置页、复用切换和凭据变更。

纳入 516ba152、43ead001 的 endpoint 去重依赖思路，并使用后端返回的 endpointAliases 替代掩码匹配；补齐相同模型去重和完整保存回归。
---
 App/backend/local-api-contracts/src/index.ts  |   2 +
 .../memmy-config/model-config-catalog.ts      |  60 ++-
 .../tests/model-config-catalog.test.ts        | 108 +++++-
 App/frontend/desktop/src/api/config-client.ts |  10 +-
 .../src/api/tests/config-client.test.ts       |  67 ++++
 App/frontend/desktop/src/i18n/messages.ts     |   2 +
 .../desktop/src/pages/api-key-form-fields.tsx |   7 +-
 .../src/pages/api-key-optional-page.tsx       |  94 ++---
 .../desktop/src/pages/api-key-page.tsx        |  95 ++---
 .../src/pages/model-config-validation.ts      |   6 +-
 .../desktop/src/pages/model-config.ts         |  56 ++-
 .../desktop/src/pages/model-credentials.ts    |  61 +++
 App/frontend/desktop/src/pages/model-page.tsx |  93 ++---
 .../api-key-optional-page-source.test.ts      |   5 -
 .../pages/tests/api-key-page-source.test.ts   |  14 +-
 ...redential-consistency.interaction.test.tsx | 351 ++++++++++++++++++
 ...k-setup-save-feedback.interaction.test.tsx |  50 ---
 .../src/pages/tests/model-config.test.ts      |   2 +-
 .../src/pages/tests/model-page-source.test.ts |  12 +-
 19 files changed, 789 insertions(+), 306 deletions(-)
 create mode 100644 App/frontend/desktop/src/pages/model-credentials.ts
 create mode 100644 App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx

diff --git a/App/backend/local-api-contracts/src/index.ts b/App/backend/local-api-contracts/src/index.ts
index 69bf78250..5fac3e6e5 100644
--- a/App/backend/local-api-contracts/src/index.ts
+++ b/App/backend/local-api-contracts/src/index.ts
@@ -1127,6 +1127,8 @@ export type MemoryRuntimeModelSettings = z.infer<typeof MemoryRuntimeModelSettin
 
 /** Schema for model config view. */
 export const ModelConfigViewSchema = z.object({
+    /** Write-response-only aliases, resolved by the server using real credentials. */
+    endpointAliases: z.record(z.string(), z.record(z.string(), z.string())).optional(),
     configRevision: z.string().min(1),
     providers: z.array(TextModelProviderViewSchema),
     modelAssignments: ModelAssignmentsSchema,
diff --git a/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts b/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
index c1d25dc37..f2518ab4f 100644
--- a/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
+++ b/App/backend/src/infrastructure/memmy-config/model-config-catalog.ts
@@ -72,15 +72,19 @@ export async function writeModelConfigCatalog(
   input: ModelConfigInput
 ): Promise<ModelConfigView> {
   const target = resolve(configPath);
+  const endpointAliases: NonNullable<ModelConfigView["endpointAliases"]> = {};
   try {
     const result = await mutateRuntimeConfig(target, (current) => {
       if (input.configRevision !== revisionFor(current)) throw new ModelConfigChangedError();
-      const next = mergeModelConfig(current, input);
+      const next = mergeModelConfig(current, input, endpointAliases);
       for (const key of Object.keys(current)) delete current[key];
       Object.assign(current, next);
       return next;
     });
-    return buildModelConfigView(result.value, revisionFor(result.value), new Date().toISOString());
+    return {
+      ...buildModelConfigView(result.value, revisionFor(result.value), new Date().toISOString()),
+      ...(Object.keys(endpointAliases).length ? { endpointAliases } : {})
+    };
   } catch (error) {
     if (isErrorCode(error, "migration_lock_timeout")) {
       throw Object.assign(new Error("Model configuration is busy; try again"), {
@@ -97,7 +101,9 @@ export function generateDesktopPresetName(provider: string, model: string): stri
   return `desktop-${readableIdPart(provider, 24) || "provider"}-${readableIdPart(model, 48) || "model"}-${hash}`;
 }
 
-function mergeModelConfig(config: ConfigRecord, input: ModelConfigInput): ConfigRecord {
+function mergeModelConfig(
+  config: ConfigRecord, input: ModelConfigInput, endpointAliases: NonNullable<ModelConfigView["endpointAliases"]>
+): ConfigRecord {
   const existingProviders = record(config.providers);
   const existingPresets = record(config.modelPresets);
   const existingAssignments = normalizeStoredAssignments(config.modelAssignments);
@@ -134,10 +140,10 @@ function mergeModelConfig(config: ConfigRecord, input: ModelConfigInput): Config
     if (providerInput.provider === ACCOUNT_PROVIDER) continue;
     const previousProvider = record(existingProviders[providerInput.provider]);
     const provider = mergeProvider(previousProvider, providerInput);
+    const modelInputs = canonicalizeEndpointDefinitions(providerInput, provider, previousProvider, endpointAliases);
     nextProviders[providerInput.provider] = provider;
-    validateEndpointDefinitions(providerInput, provider);
 
-    for (const modelInput of providerInput.models) {
+    for (const modelInput of modelInputs) {
       if (modelInput.source !== "byok" || modelInput.ownerAccountId) {
         throw new InvalidModelConfigError("Desktop model settings may only create ownerless BYOK presets");
       }
@@ -446,10 +452,19 @@ function mergeEndpoint(previous: ConfigRecord, input: CatalogEndpointInput): Con
   return next;
 }
 
-function validateEndpointDefinitions(input: TextModelProviderInput, provider: ConfigRecord): void {
-  const signatures = new Set<string>();
-  for (const endpoint of input.endpoints) {
-    const merged = record(record(provider.endpoints)[endpoint.endpointId]);
+function canonicalizeEndpointDefinitions(
+  input: TextModelProviderInput, provider: ConfigRecord, previous: ConfigRecord,
+  aliases: NonNullable<ModelConfigView["endpointAliases"]>
+): TextModelItemInput[] {
+  const canonicalIds = new Map<string, string>();
+  const redirects = new Map<string, string>();
+  const endpoints = record(provider.endpoints);
+  const previousEndpoints = record(previous.endpoints);
+  // Keep persisted connection identities even if a new duplicate is submitted first.
+  const ordered = [...input.endpoints].sort((left, right) =>
+    Number(right.endpointId in previousEndpoints) - Number(left.endpointId in previousEndpoints));
+  for (const endpoint of ordered) {
+    const merged = record(endpoints[endpoint.endpointId]);
     const signature = stableJson({
       provider: input.provider,
       protocol: merged.protocol,
@@ -458,11 +473,32 @@ function validateEndpointDefinitions(input: TextModelProviderInput, provider: Co
       extraHeaders: merged.extraHeaders ?? provider.extraHeaders ?? null,
       extraBody: merged.extraBody ?? provider.extraBody ?? null
     });
-    if (signatures.has(signature)) {
-      throw new InvalidModelConfigError(`Duplicate endpoint definition for Provider ${input.provider}`);
+    const canonicalId = canonicalIds.get(signature);
+    if (canonicalId) {
+      redirects.set(endpoint.endpointId, canonicalId);
+      delete endpoints[endpoint.endpointId];
+    } else {
+      canonicalIds.set(signature, endpoint.endpointId);
     }
-    signatures.add(signature);
   }
+  if (redirects.size) aliases[input.provider] = Object.fromEntries(redirects);
+  const models = input.models.map((model) => ({
+    ...model, endpointId: redirects.get(model.endpointId) ?? model.endpointId
+  }));
+  // Only coalesce a new model made redundant by credential-based endpoint merging.
+  // Existing preset IDs and ordinary duplicate-model validation remain intact.
+  const removed = new Set<number>();
+  for (const [index, original] of input.models.entries()) {
+    if (original.presetId || original.ownerAccountId || original.source !== "byok" || !redirects.has(original.endpointId)) continue;
+    const duplicate = models.findIndex((model, candidate) => candidate !== index
+      && !removed.has(candidate)
+      && model.endpointId === models[index]!.endpointId
+      && model.model === original.model && model.source === original.source);
+    if (duplicate < 0) continue;
+    models[duplicate]!.capabilities = [...new Set([...models[duplicate]!.capabilities, ...models[index]!.capabilities])];
+    removed.add(index);
+  }
+  return models.filter((_, index) => !removed.has(index));
 }
 
 function validatePresetEndpoint(providerId: CatalogProviderId, model: TextModelItemInput, endpoint: ConfigRecord): void {
diff --git a/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts b/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
index 4515c5ab6..25c85eddc 100644
--- a/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
+++ b/App/backend/src/infrastructure/memmy-config/tests/model-config-catalog.test.ts
@@ -501,17 +501,115 @@ describe("model config catalog", () => {
     expect((YAML.parse(readFileSync(file, "utf8")) as any).memmyMemory.roleRouting.summary).toBe("follow");
   });
 
-  it("rejects duplicate endpoint definitions, invalid protocol capabilities, and duplicate models", async () => {
+  it("coalesces identical endpoint definitions and redirects their model references", async () => {
     const file = fixture();
-    const revision = (await readModelConfigCatalog(file)).configRevision;
-    const duplicateEndpoint = openAiInput(revision);
-    duplicateEndpoint.providers[0]!.endpoints.push({
+    const input = openAiInput((await readModelConfigCatalog(file)).configRevision);
+    input.providers[0]!.endpoints.push({
       endpointId: "chat-copy",
       apiBase: "https://api.example.test/v1",
       protocol: "openai-chat-completions"
     });
-    await expect(writeModelConfigCatalog(file, duplicateEndpoint)).rejects.toThrow(/Duplicate endpoint definition/);
+    input.providers[0]!.models.push({
+      endpointId: "chat-copy",
+      model: "gpt-5-alias",
+      source: "byok",
+      capabilities: ["agent"]
+    });
+
+    const saved = await writeModelConfigCatalog(file, input);
+    const raw = YAML.parse(readFileSync(file, "utf8")) as any;
+    expect(Object.keys(raw.providers.openai.endpoints)).toEqual(["chat"]);
+    expect(Object.values(raw.modelPresets).map((preset: any) => preset.endpoint)).toEqual(["chat", "chat"]);
+    expect(saved.providers[0]?.endpoints).toHaveLength(1);
+  });
+
+  it("coalesces duplicate embedding endpoints created while adding models", async () => {
+    const file = fixture();
+    const input = openAiInput((await readModelConfigCatalog(file)).configRevision);
+    input.providers[0]!.endpoints = [
+      {
+        endpointId: "embedding",
+        apiBase: "https://api.example.test/v1/",
+        protocol: "openai-embeddings"
+      },
+      {
+        endpointId: "embedding-copy",
+        apiBase: "https://api.example.test/v1",
+        protocol: "openai-embeddings"
+      }
+    ];
+    input.providers[0]!.models = [
+      {
+        endpointId: "embedding",
+        model: "embedding-a",
+        source: "byok",
+        capabilities: ["embedding"]
+      },
+      {
+        endpointId: "embedding-copy",
+        model: "embedding-b",
+        source: "byok",
+        capabilities: ["embedding"]
+      }
+    ];
+
+    const saved = await writeModelConfigCatalog(file, input);
+    const raw = YAML.parse(readFileSync(file, "utf8")) as any;
+    expect(Object.keys(raw.providers.openai.endpoints)).toEqual(["embedding"]);
+    expect(Object.values(raw.modelPresets).map((preset: any) => preset.endpoint)).toEqual(["embedding", "embedding"]);
+    expect(saved.providers[0]?.models.map((model) => model.model)).toEqual(["embedding-a", "embedding-b"]);
+  });
+
+  it.each([false, true])("coalesces a reentered key and identical model while retaining the saved preset (new endpoint first: %s)", async (newFirst) => {
+    const file = fixture();
+    const first = await writeModelConfigCatalog(file, openAiInput((await readModelConfigCatalog(file)).configRevision));
+    const originalId = first.providers[0]!.models[0]!.presetId;
+    const input = openAiInput(first.configRevision);
+    input.providers[0]!.models[0]!.presetId = originalId;
+    input.providers[0]!.models[0]!.capabilities = ["agent"];
+    input.providers[0]!.endpoints.push({ ...input.providers[0]!.endpoints[0]!, endpointId: "chat-copy" });
+    input.providers[0]!.models.push({
+      ...input.providers[0]!.models[0]!, presetId: undefined, endpointId: "chat-copy", capabilities: ["memory_evolution"]
+    });
+    if (newFirst) {
+      input.providers[0]!.endpoints.reverse();
+      input.providers[0]!.models.reverse();
+    }
+    const saved = await writeModelConfigCatalog(file, input);
+    expect(saved.endpointAliases).toEqual({ openai: { "chat-copy": "chat" } });
+    expect(saved.providers[0]!.models).toHaveLength(1);
+    expect(saved.providers[0]!.models[0]).toMatchObject({
+      presetId: originalId, endpointId: "chat", capabilities: ["agent", "memory_evolution"]
+    });
+    // Aliases describe this write only; neither transient metadata nor plaintext is added to GET views.
+    expect((await readModelConfigCatalog(file)).endpointAliases).toBeUndefined();
+  });
 
+  it("keeps endpoints with different credentials even when their route is the same", async () => {
+    const file = fixture();
+    const input = openAiInput((await readModelConfigCatalog(file)).configRevision);
+    input.providers[0]!.endpoints.push({
+      endpointId: "chat-other-key",
+      apiBase: "https://api.example.test/v1",
+      protocol: "openai-chat-completions",
+      apiKey: "sk-another-secret"
+    });
+    input.providers[0]!.models.push({
+      endpointId: "chat-other-key",
+      model: "gpt-5-alias",
+      source: "byok",
+      capabilities: ["agent"]
+    });
+
+    await writeModelConfigCatalog(file, input);
+    const raw = YAML.parse(readFileSync(file, "utf8")) as any;
+    expect(Object.keys(raw.providers.openai.endpoints)).toEqual(["chat", "chat-other-key"]);
+    expect(raw.providers.openai.endpoints["chat-other-key"].apiKey).toBe("sk-another-secret");
+  });
+
+  it("rejects invalid protocol capabilities and duplicate models", async () => {
+    const file = fixture();
+    const revision = (await readModelConfigCatalog(file)).configRevision;
     const wrongProtocol = openAiInput(revision);
     wrongProtocol.providers[0]!.models[0]!.capabilities = ["embedding"];
     await expect(writeModelConfigCatalog(file, wrongProtocol)).rejects.toThrow(/does not support capability embedding/);
diff --git a/App/frontend/desktop/src/api/config-client.ts b/App/frontend/desktop/src/api/config-client.ts
index 00c147c71..d89c85597 100644
--- a/App/frontend/desktop/src/api/config-client.ts
+++ b/App/frontend/desktop/src/api/config-client.ts
@@ -646,12 +646,14 @@ function withoutPendingPresetAssignments(input: ModelConfigInput, pendingIds: Re
 function resolvePendingPresetIds(pending: PendingPreset[], view: ModelConfigView): Map<string, string> {
   const mapping = new Map<string, string>();
   for (const item of pending) {
+    // Never infer credential equality from a mask. Only the backend can resolve aliases.
+    item.endpointId = view.endpointAliases?.[item.provider]?.[item.endpointId] ?? item.endpointId;
     const matches = view.providers.flatMap((provider) => provider.models).filter((model) => (
       model.provider === item.provider
       && model.endpointId === item.endpointId
       && model.model === item.model
       && model.source === item.source
-      && sameStringSet(model.capabilities, item.capabilities)
+      && item.capabilities.every((capability) => model.capabilities.includes(capability))
     ));
     if (matches.length !== 1) {
       throw new Error(`Unable to resolve server preset for ${item.provider}/${item.endpointId}/${item.model}`);
@@ -710,17 +712,13 @@ function assertResolvedPresetsStillExist(
       || preset.endpointId !== item.endpointId
       || preset.model !== item.model
       || preset.source !== item.source
-      || !sameStringSet(preset.capabilities, item.capabilities)
+      || !item.capabilities.every((capability) => preset.capabilities.includes(capability))
     ) {
       throw new Error(`Created model preset changed before assignment: ${item.provider}/${item.endpointId}/${item.model}`);
     }
   }
 }
 
-function sameStringSet(left: readonly string[], right: readonly string[]): boolean {
-  return left.length === right.length && left.every((value) => right.includes(value));
-}
-
 function isModelConfigChanged(error: unknown): boolean {
   return Boolean(error && typeof error === "object" && "code" in error && error.code === "model_config_changed");
 }
diff --git a/App/frontend/desktop/src/api/tests/config-client.test.ts b/App/frontend/desktop/src/api/tests/config-client.test.ts
index eae3aa81a..29f2ee110 100644
--- a/App/frontend/desktop/src/api/tests/config-client.test.ts
+++ b/App/frontend/desktop/src/api/tests/config-client.test.ts
@@ -209,6 +209,73 @@ describe("config-client canonical model catalog", () => {
     expect(saved.catalog?.modelAssignments.byok.agent.default).toBe(serverPresetId);
   });
 
+  it.each(["endpoint apiKey", "provider apiKey", "missing apiKey"] as const)(
+    "后端合并相同 endpoint 定义后可用 %s 解析新模型并完成 assignment",
+    async (keyLocation) => {
+      const bodies: any[] = [];
+      const serverPresetId = "5c8872cf-28c8-4cf3-bf51-9a3a2a0fb42a";
+      vi.stubGlobal("fetch", vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
+        const body = JSON.parse(String(init?.body));
+        bodies.push(body);
+        const response = catalog(bodies.length === 1 ? "revision-2" : "revision-3");
+        response.endpointAliases = { openai: { "chat-duplicate": "chat" } };
+        response.providers[0]!.apiKeyMasked = "sk-••••1234";
+        for (const endpoint of response.providers[0]!.endpoints) endpoint.apiKeyMasked = "sk-••••1234";
+        response.providers[0]!.models.push({
+          presetId: serverPresetId,
+          provider: "openai",
+          endpointId: "chat",
+          protocol: "openai-chat-completions",
+          model: "gpt-new",
+          source: "byok",
+          capabilities: ["agent"],
+          available: true
+        });
+        if (bodies.length > 1) {
+          response.modelAssignments.byok.agent = {
+            candidates: ["byok-agent", serverPresetId],
+            default: serverPresetId
+          };
+        }
+        return jsonResponse(response);
+      }));
+      const input = inputFromCatalog(catalog("revision-1"));
+      const clientPresetId = `${CLIENT_PRESET_ID_PREFIX}canonicalized-endpoint`;
+      input.providers[0]!.endpoints.push({
+        endpointId: "chat-duplicate",
+        apiBase: "https://api.openai.com/v1/",
+        protocol: "openai-chat-completions",
+        ...(keyLocation === "endpoint apiKey" ? { apiKey: "  sk-live1234  " } : {})
+      });
+      if (keyLocation === "provider apiKey") input.providers[0]!.apiKey = "  sk-live1234  ";
+      input.providers[0]!.models.push({
+        presetId: clientPresetId,
+        endpointId: "chat-duplicate",
+        model: "gpt-new",
+        source: "byok",
+        capabilities: ["agent"]
+      });
+      input.modelAssignments.byok.agent = {
+        candidates: ["byok-agent", clientPresetId],
+        default: clientPresetId
+      };
+
+      const saved = await createHttpConfigClient(config).saveModelCatalog(input);
+
+      expect(bodies).toHaveLength(2);
+      expect(bodies[0].providers[0].endpoints.some((endpoint: any) => endpoint.endpointId === "chat-duplicate")).toBe(true);
+      expect(bodies[1].providers[0].models.find((model: any) => model.model === "gpt-new")).toMatchObject({
+        presetId: serverPresetId,
+        endpointId: "chat"
+      });
+      expect(bodies[1].modelAssignments.byok.agent).toEqual({
+        candidates: ["byok-agent", serverPresetId],
+        default: serverPresetId
+      });
+      expect(saved.catalog?.modelAssignments.byok.agent.default).toBe(serverPresetId);
+    }
+  );
+
   it("首次成功 GET 后只清理旧 workspace cache", async () => {
     const removeItem = vi.fn();
     vi.stubGlobal("window", { localStorage: { removeItem } });
diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index 9e79ffc53..2acbe6900 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -327,6 +327,7 @@ export const zhCNMessages = {
   "apiKey.testInvalidConfig": "连接失败，请检查 API Key、模型 ID 或 API 地址",
   "apiKey.testRequestFailed": "连接测试失败，请检查本地 API 或网络",
   "apiKey.testSaveFailed": "连接成功，但配置保存失败，请点击保存重试",
+  "apiKey.credentialsChanged": "连接地址或服务商已更改，请重新填写 API Key",
   "apiKey.testStale": "配置已变更，请重新测试",
   "apiKey.showKey": "显示 API Key",
   "apiKey.hideKey": "隐藏 API Key",
@@ -2067,6 +2068,7 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "apiKey.testInvalidConfig": "Connection failed. Check API key, model ID, or API URL.",
   "apiKey.testRequestFailed": "Connection test failed. Check local API or network.",
   "apiKey.testSaveFailed": "Connected, but saving the config failed. Click Save to retry.",
+  "apiKey.credentialsChanged": "Connection URL or provider changed. Enter the API key again.",
   "apiKey.testStale": "Configuration changed. Test again.",
   "apiKey.showKey": "Show API key",
   "apiKey.hideKey": "Hide API key",
diff --git a/App/frontend/desktop/src/pages/api-key-form-fields.tsx b/App/frontend/desktop/src/pages/api-key-form-fields.tsx
index 1abe4951a..c76409c26 100644
--- a/App/frontend/desktop/src/pages/api-key-form-fields.tsx
+++ b/App/frontend/desktop/src/pages/api-key-form-fields.tsx
@@ -55,6 +55,7 @@ interface TestButtonProps {
 interface ValidationMessageProps {
   validation: ModelConfigValidationState;
   stale: boolean;
+  credentialRequired?: boolean;
 }
 
 /** Handles config field. */
@@ -152,12 +153,12 @@ export function TestButton(props: TestButtonProps) {
 export function ValidationMessage(props: ValidationMessageProps) {
   const { t } = useTranslation();
 
-  if (props.validation.status === "idle" && !props.stale) {
+  if (props.validation.status === "idle" && !props.stale && !props.credentialRequired) {
     return null;
   }
 
-  const isSuccess = props.validation.status === "success" && !props.stale;
-  const message = props.stale ? t("apiKey.testStale") : props.validation.message;
+  const isSuccess = props.validation.status === "success" && !props.stale && !props.credentialRequired;
+  const message = props.credentialRequired ? t("apiKey.credentialsChanged") : props.stale ? t("apiKey.testStale") : props.validation.message;
 
   return (
     <OverflowTooltipText
diff --git a/App/frontend/desktop/src/pages/api-key-optional-page.tsx b/App/frontend/desktop/src/pages/api-key-optional-page.tsx
index c0c56cb01..bb5164e66 100644
--- a/App/frontend/desktop/src/pages/api-key-optional-page.tsx
+++ b/App/frontend/desktop/src/pages/api-key-optional-page.tsx
@@ -1,3 +1,4 @@
+import { bindSavedValidation, endpointCredentialSignature, resolveModelCredentials, type SavedEndpointIdentity } from "./model-credentials.js";
 import { useRef, useState } from "react";
 import { ChevronLeft, Image as ImageIcon, Mic } from "lucide-react";
 import { useAnalytics } from "../analytics/use-analytics.js";
@@ -50,33 +51,37 @@ import {
   type ImageProtocol
 } from "./model-config.js";
 
-interface SavedEndpointIdentity {
-  endpointId: string;
-  credentialSignature: string;
-}
 
 export function ApiKeyOptionalPage() {
   const { state, dispatch } = useAppState();
   const { clients } = useApiClients();
   const { t } = useTranslation();
   const { track } = useAnalytics();
-  const initialModelForm = hydrateModelConfigForm(state.modelConfig, "local");
-  const initialWorkspace = createModelWorkspace(state.modelConfig);
+  const [initialModelForm] = useState(() => hydrateModelConfigForm(state.modelConfig, "local"));
+  const [initialWorkspace] = useState(() => createModelWorkspace(state.modelConfig));
   const initialAsrEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "asr");
   const initialImageEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "image_generation");
+  const savedEndpointIdentitiesRef = useRef<Partial<Record<"asr" | "imageGeneration", SavedEndpointIdentity>>>({
+    ...(initialAsrEndpointId
+      ? { asr: { endpointId: initialAsrEndpointId, credentialSignature: endpointCredentialSignature("qwen", "dashscope-input-audio-chat", initialModelForm.asrEndpoint, initialModelForm.asrApiKey, initialModelForm.asrApiKeyMasked) } }
+      : {}),
+    ...(initialImageEndpointId
+      ? { imageGeneration: { endpointId: initialImageEndpointId, credentialSignature: endpointCredentialSignature(initialModelForm.imageGenProtocol, initialModelForm.imageGenProtocol === "qwen" ? "dashscope-multimodal-generation" : "openai-images", initialModelForm.imageGenEndpoint, initialModelForm.imageGenApiKey, initialModelForm.imageGenApiKeyMasked) } }
+      : {})
+  });
   const initialAsrModel = initialModelForm.asrModelId;
   const initialAsrEndpoint = initialModelForm.asrEndpoint || ASR_DEFAULT_ENDPOINT;
   const [asrModel, setAsrModel] = useState(initialAsrModel);
   const [asrEndpoint, setAsrEndpoint] = useState(initialAsrEndpoint);
   const [asrApiKey, setAsrApiKey] = useState(initialModelForm.asrApiKey);
   const [showAsrApiKey, setShowAsrApiKey] = useState(false);
-  const [asrValidation, setAsrValidation] = useState<ModelConfigValidationState>(initialModelForm.asrValidation);
   const [asrWarningAcknowledged, setAsrWarningAcknowledged] = useState(false);
   const [asrApiKeyMasked] = useState(initialModelForm.asrApiKeyMasked);
-  const asrFormValues = {
+  const asrFormValues = resolveModelCredentials({
     ...createAsrModelFormValues(asrModel, asrEndpoint, asrApiKey, asrApiKeyMasked),
-    endpointId: !asrApiKey.trim() && asrApiKeyMasked ? initialAsrEndpointId : undefined
-  };
+    protocol: "dashscope-input-audio-chat"
+  }, savedEndpointIdentitiesRef.current.asr);
+  const [asrValidation, setAsrValidation] = useState<ModelConfigValidationState>(() => bindSavedValidation(initialModelForm.asrValidation, asrFormValues));
   const isAsrUsable = canSaveModelConfig(asrFormValues, asrValidation);
   const asrTestKey = createModelConfigValidationKey(asrFormValues);
   const isAsrTestStale = Boolean(asrValidation.testedKey && asrValidation.testedKey !== asrTestKey);
@@ -85,17 +90,13 @@ export function ApiKeyOptionalPage() {
   const [imageGenEndpoint, setImageGenEndpoint] = useState(initialModelForm.imageGenEndpoint);
   const [imageGenApiKey, setImageGenApiKey] = useState(initialModelForm.imageGenApiKey);
   const [showImageGenApiKey, setShowImageGenApiKey] = useState(false);
-  const [imageGenValidation, setImageGenValidation] = useState<ModelConfigValidationState>(initialModelForm.imageGenValidation);
   const [imageGenWarningAcknowledged, setImageGenWarningAcknowledged] = useState(false);
   const [imageGenApiKeyMasked] = useState(initialModelForm.imageGenApiKeyMasked);
-  const imageGenFormValues = {
+  const imageGenFormValues = resolveModelCredentials({
     ...createImageGenModelFormValues(imageGenProtocol, imageGenModel, imageGenEndpoint, imageGenApiKey, imageGenApiKeyMasked),
-    endpointId: !imageGenApiKey.trim()
-      && imageGenApiKeyMasked
-      && imageGenProtocol === initialModelForm.imageGenProtocol
-      ? initialImageEndpointId
-      : undefined
-  };
+    protocol: imageGenProtocol === "qwen" ? "dashscope-multimodal-generation" : "openai-images"
+  }, savedEndpointIdentitiesRef.current.imageGeneration);
+  const [imageGenValidation, setImageGenValidation] = useState<ModelConfigValidationState>(() => bindSavedValidation(initialModelForm.imageGenValidation, imageGenFormValues));
   const isImageGenUsable = canSaveModelConfig(imageGenFormValues, imageGenValidation);
   const imageGenTestKey = createModelConfigValidationKey(imageGenFormValues);
   const isImageGenTestStale = Boolean(imageGenValidation.testedKey && imageGenValidation.testedKey !== imageGenTestKey);
@@ -121,14 +122,7 @@ export function ApiKeyOptionalPage() {
     imageGeneration: isImageGenUsable ? imageGenTestKey : null
   });
   const savedCatalogSignatureRef = useRef<string | null>(null);
-  const savedEndpointIdentitiesRef = useRef<Partial<Record<"asr" | "imageGeneration", SavedEndpointIdentity>>>({
-    ...(initialAsrEndpointId
-      ? { asr: { endpointId: initialAsrEndpointId, credentialSignature: asrCredentialSignature } }
-      : {}),
-    ...(initialImageEndpointId
-      ? { imageGeneration: { endpointId: initialImageEndpointId, credentialSignature: imageGenCredentialSignature } }
-      : {})
-  });
+
   const [optionalModelMissingWarning, setOptionalModelMissingWarning] = useState<OptionalModelMissingWarningKind | null>(null);
   const [modePersistencePending, setModePersistencePending] = useState(false);
   const [nextValidationError, setNextValidationError] = useState<"noInput" | "testRequired" | null>(null);
@@ -190,34 +184,26 @@ export function ApiKeyOptionalPage() {
         const latest = await clients.config.getModelConfig();
         let workspace = createModelWorkspace(latest);
         if (isAsrUsable) {
-          const savedAsrIdentity = savedEndpointIdentitiesRef.current.asr;
-          const asrEndpointId = savedAsrIdentity?.credentialSignature === asrCredentialSignature
-            ? savedAsrIdentity.endpointId
-            : undefined;
           const asr = upsertByokPreset(workspace, {
             provider: "qwen",
-            ...(asrEndpointId ? { endpointId: asrEndpointId } : {}),
+            ...(asrFormValues.endpointId ? { endpointId: asrFormValues.endpointId } : {}),
             endpoint: asrEndpoint,
             protocol: "dashscope-input-audio-chat",
             ...(asrApiKey.trim() ? { apiKey: asrApiKey.trim() } : {}),
-            ...(asrApiKeyMasked ? { apiKeyMasked: asrApiKeyMasked } : {}),
+            ...(asrFormValues.apiKeyMasked ? { apiKeyMasked: asrFormValues.apiKeyMasked } : {}),
             model: asrModel || ASR_MODEL_ID,
             capabilities: ["asr"]
           });
           workspace = assignCatalogPreset(asr.workspace, "byok", "asr", asr.presetId);
         }
         if (isImageGenUsable) {
-          const savedImageIdentity = savedEndpointIdentitiesRef.current.imageGeneration;
-          const imageEndpointId = savedImageIdentity?.credentialSignature === imageGenCredentialSignature
-            ? savedImageIdentity.endpointId
-            : undefined;
           const image = upsertByokPreset(workspace, {
             provider: imageGenProtocol,
-            ...(imageEndpointId ? { endpointId: imageEndpointId } : {}),
+            ...(imageGenFormValues.endpointId ? { endpointId: imageGenFormValues.endpointId } : {}),
             endpoint: imageGenEndpoint,
             protocol: imageGenEndpointProtocol,
             ...(imageGenApiKey.trim() ? { apiKey: imageGenApiKey.trim() } : {}),
-            ...(imageGenApiKeyMasked ? { apiKeyMasked: imageGenApiKeyMasked } : {}),
+            ...(imageGenFormValues.apiKeyMasked ? { apiKeyMasked: imageGenFormValues.apiKeyMasked } : {}),
             model: imageGenModel,
             capabilities: ["image_generation"]
           });
@@ -289,8 +275,8 @@ export function ApiKeyOptionalPage() {
     setSaveError(null);
     setNextValidationError(null);
 
-    const asrHasInput = Boolean(asrApiKey.trim());
-    const imageGenHasInput = Boolean(imageGenApiKey.trim());
+    const asrHasInput = Boolean(asrApiKey.trim() || asrApiKeyMasked);
+    const imageGenHasInput = Boolean(imageGenApiKey.trim() || imageGenApiKeyMasked);
 
     if (!asrHasInput && !imageGenHasInput) {
       setNextValidationError("noInput");
@@ -357,12 +343,12 @@ export function ApiKeyOptionalPage() {
                 setAsrWarningAcknowledged(false);
               }}
               showPassword={showAsrApiKey}
-              maskedValue={asrApiKeyMasked}
+              maskedValue={asrFormValues.apiKeyMasked}
               onTogglePassword={() => setShowAsrApiKey((value) => !value)}
             />
             <div className="flex min-h-9 items-center justify-end gap-3">
-              <ValidationMessage validation={asrValidation} stale={isAsrTestStale} />
-              <TestButton status={asrValidation.status} onClick={testAsrConnection} label={t("apiKey.test")} />
+              <ValidationMessage validation={asrValidation} stale={isAsrTestStale} credentialRequired={asrFormValues.requiresApiKey} />
+              <TestButton status={isAsrTestStale || asrFormValues.requiresApiKey ? "idle" : asrValidation.status} onClick={testAsrConnection} label={t("apiKey.test")} />
             </div>
           </div>
         </div>
@@ -408,12 +394,12 @@ export function ApiKeyOptionalPage() {
                 setImageGenWarningAcknowledged(false);
               }}
               showPassword={showImageGenApiKey}
-              maskedValue={imageGenApiKeyMasked}
+              maskedValue={imageGenFormValues.apiKeyMasked}
               onTogglePassword={() => setShowImageGenApiKey((value) => !value)}
             />
             <div className="flex min-h-9 items-center justify-end gap-3">
-              <ValidationMessage validation={imageGenValidation} stale={isImageGenTestStale} />
-              <TestButton status={imageGenValidation.status} onClick={testImageGenConnection} label={t("apiKey.test")} />
+              <ValidationMessage validation={imageGenValidation} stale={isImageGenTestStale} credentialRequired={imageGenFormValues.requiresApiKey} />
+              <TestButton status={isImageGenTestStale || imageGenFormValues.requiresApiKey ? "idle" : imageGenValidation.status} onClick={testImageGenConnection} label={t("apiKey.test")} />
             </div>
           </div>
         </div>
@@ -463,22 +449,6 @@ export function ApiKeyOptionalPage() {
   );
 }
 
-function endpointCredentialSignature(
-  provider: string,
-  protocol: string,
-  endpoint: string,
-  apiKey: string,
-  apiKeyMasked: string
-): string {
-  const normalizedApiKey = apiKey.trim();
-  const normalizedMaskedApiKey = apiKeyMasked.trim();
-  return JSON.stringify({
-    provider: provider.trim().toLowerCase(),
-    protocol,
-    endpoint: endpoint.trim().replace(/\/+$/, ""),
-    credential: normalizedMaskedApiKey ? `masked:${normalizedMaskedApiKey}` : `raw:${normalizedApiKey}`
-  });
-}
 
 function optionalStepSaveErrorText(
   error: unknown,
diff --git a/App/frontend/desktop/src/pages/api-key-page.tsx b/App/frontend/desktop/src/pages/api-key-page.tsx
index 6e917ad2d..7d32b640d 100644
--- a/App/frontend/desktop/src/pages/api-key-page.tsx
+++ b/App/frontend/desktop/src/pages/api-key-page.tsx
@@ -1,3 +1,4 @@
+import { bindSavedValidation, endpointCredentialSignature, resolveModelCredentials, type SavedEndpointIdentity, chatProtocol } from "./model-credentials.js";
 import { useRef, useState } from "react";
 import { Brain, ChevronLeft, Search } from "lucide-react";
 import { useAnalytics } from "../analytics/use-analytics.js";
@@ -55,10 +56,7 @@ interface ProviderOption {
   defaultModelId: string;
 }
 
-interface SavedEndpointIdentity {
-  endpointId: string;
-  credentialSignature: string;
-}
+
 
 const providerOptions: ProviderOption[] = [
   { value: "openai", labelKey: "apiKey.provider.openai", endpoint: "https://api.openai.com/v1", defaultModelId: "gpt-4o" },
@@ -82,28 +80,36 @@ export function ApiKeyPage() {
   const { clients } = useApiClients();
   const { t } = useTranslation();
   const { track } = useAnalytics();
-  const initialModelForm = hydrateModelConfigForm(state.modelConfig, "local");
-  const initialWorkspace = createModelWorkspace(state.modelConfig);
+  const [initialModelForm] = useState(() => hydrateModelConfigForm(state.modelConfig, "local"));
+  const [initialWorkspace] = useState(() => createModelWorkspace(state.modelConfig));
   const initialAgentEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "agent");
   const initialEmbeddingEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "embedding");
   const initialProvider = fromProtocol(initialModelForm.protocol);
+  const savedEndpointIdentitiesRef = useRef<Partial<Record<"agent" | "embedding", SavedEndpointIdentity>>>({
+    ...(initialAgentEndpointId
+      ? { agent: { endpointId: initialAgentEndpointId, credentialSignature: endpointCredentialSignature(initialProvider, chatProtocol(initialProvider), initialModelForm.endpoint, initialModelForm.apiKey, initialModelForm.apiKeyMasked) } }
+      : {}),
+    ...(initialEmbeddingEndpointId
+      ? { embedding: { endpointId: initialEmbeddingEndpointId, credentialSignature: endpointCredentialSignature("openai", "openai-embeddings", initialModelForm.embEndpoint, initialModelForm.embApiKey, initialModelForm.embApiKeyMasked) } }
+      : {})
+  });
   const [provider, setProvider] = useState(initialProvider);
   const selectedProvider = providerOptions.find((option) => option.value === provider) ?? defaultProvider;
   const [endpoint, setEndpoint] = useState(initialModelForm.endpoint || selectedProvider.endpoint);
   const [model, setModel] = useState(initialModelForm.modelId);
   const [apiKey, setApiKey] = useState(initialModelForm.apiKey);
-  const [apiKeyMasked, setApiKeyMasked] = useState(initialModelForm.apiKeyMasked);
+  const [apiKeyMasked] = useState(initialModelForm.apiKeyMasked);
   const [showApiKey, setShowApiKey] = useState(false);
-  const modelFormValues = {
+  const modelFormValues = resolveModelCredentials({
+    protocol: chatProtocol(provider),
     provider,
-    endpointId: !apiKey.trim() && apiKeyMasked ? initialAgentEndpointId : undefined,
     endpoint,
     model,
     apiKey,
     apiKeyMasked,
     hasExistingApiKey: Boolean(apiKeyMasked)
-  };
-  const [llmValidation, setLlmValidation] = useState<ModelConfigValidationState>(initialModelForm.llmValidation);
+  }, savedEndpointIdentitiesRef.current.agent);
+  const [llmValidation, setLlmValidation] = useState<ModelConfigValidationState>(() => bindSavedValidation(initialModelForm.llmValidation, modelFormValues));
   const initialEmbeddingMode: EmbeddingMode = initialWorkspace.catalog.modelAssignments.byok.embedding
     ? "custom"
     : "local";
@@ -115,16 +121,16 @@ export function ApiKeyPage() {
     apiKeyMasked: initialModelForm.embApiKeyMasked
   });
   const [showEmbeddingApiKey, setShowEmbeddingApiKey] = useState(false);
-  const embeddingFormValues = {
+  const embeddingFormValues = resolveModelCredentials({
+    protocol: "openai-embeddings",
     provider: "openai",
-    endpointId: !embeddingConfig.apiKey.trim() && embeddingConfig.apiKeyMasked ? initialEmbeddingEndpointId : undefined,
     endpoint: embeddingConfig.endpoint,
     model: embeddingConfig.model,
     apiKey: embeddingConfig.apiKey,
     apiKeyMasked: embeddingConfig.apiKeyMasked,
     hasExistingApiKey: Boolean(embeddingConfig.apiKeyMasked)
-  };
-  const [embeddingValidation, setEmbeddingValidation] = useState<ModelConfigValidationState>(initialModelForm.embValidation);
+  }, savedEndpointIdentitiesRef.current.embedding);
+  const [embeddingValidation, setEmbeddingValidation] = useState<ModelConfigValidationState>(() => bindSavedValidation(initialModelForm.embValidation, embeddingFormValues));
   const canSave = canSaveModelConfig(modelFormValues, llmValidation)
     && canSaveOptionalModelConfig(embeddingMode === "custom", embeddingFormValues, embeddingValidation);
   const [savePending, setSavePending] = useState(false);
@@ -149,14 +155,7 @@ export function ApiKeyPage() {
   );
   const saveSignature = `${embeddingMode}\n${testedKey}\n${embeddingTestKey}`;
   const savedCatalogSignatureRef = useRef<string | null>(null);
-  const savedEndpointIdentitiesRef = useRef<Partial<Record<"agent" | "embedding", SavedEndpointIdentity>>>({
-    ...(initialAgentEndpointId
-      ? { agent: { endpointId: initialAgentEndpointId, credentialSignature: agentCredentialSignature } }
-      : {}),
-    ...(initialEmbeddingEndpointId
-      ? { embedding: { endpointId: initialEmbeddingEndpointId, credentialSignature: embeddingCredentialSignature } }
-      : {})
-  });
+
 
   function changeProvider(nextProvider: string) {
     const next = providerOptions.find((option) => option.value === nextProvider) ?? defaultProvider;
@@ -164,7 +163,6 @@ export function ApiKeyPage() {
     setEndpoint(next.endpoint);
     setModel("");
     setApiKey("");
-    setApiKeyMasked("");
   }
 
   function testLlmConnection() {
@@ -202,33 +200,26 @@ export function ApiKeyPage() {
       if (savedCatalogSignatureRef.current !== saveSignature) {
         const latest = await clients.config.getModelConfig();
         let workspace = createModelWorkspace(latest);
-        const savedAgentIdentity = savedEndpointIdentitiesRef.current.agent;
-        const agentEndpointId = savedAgentIdentity?.credentialSignature === agentCredentialSignature
-          ? savedAgentIdentity.endpointId
-          : undefined;
         const agent = upsertByokPreset(workspace, {
           provider,
-          ...(agentEndpointId ? { endpointId: agentEndpointId } : {}),
+          ...(modelFormValues.endpointId ? { endpointId: modelFormValues.endpointId } : {}),
           endpoint,
           protocol: chatProtocol(provider),
           ...(apiKey.trim() ? { apiKey: apiKey.trim() } : {}),
-          ...(apiKeyMasked ? { apiKeyMasked } : {}),
+          ...(modelFormValues.apiKeyMasked ? { apiKeyMasked: modelFormValues.apiKeyMasked } : {}),
           model,
           capabilities: ["agent"]
         });
         workspace = assignCatalogPreset(agent.workspace, "byok", "agent", agent.presetId);
         const savedEmbeddingIdentity = savedEndpointIdentitiesRef.current.embedding;
         if (embeddingMode === "custom") {
-          const embeddingEndpointId = savedEmbeddingIdentity?.credentialSignature === embeddingCredentialSignature
-            ? savedEmbeddingIdentity.endpointId
-            : undefined;
           const embedding = upsertByokPreset(workspace, {
             provider: "openai",
-            ...(embeddingEndpointId ? { endpointId: embeddingEndpointId } : {}),
+            ...(embeddingFormValues.endpointId ? { endpointId: embeddingFormValues.endpointId } : {}),
             endpoint: embeddingConfig.endpoint,
             protocol: "openai-embeddings",
             ...(embeddingConfig.apiKey.trim() ? { apiKey: embeddingConfig.apiKey.trim() } : {}),
-            ...(embeddingConfig.apiKeyMasked ? { apiKeyMasked: embeddingConfig.apiKeyMasked } : {}),
+            ...(embeddingFormValues.apiKeyMasked ? { apiKeyMasked: embeddingFormValues.apiKeyMasked } : {}),
             model: embeddingConfig.model,
             capabilities: ["embedding"]
           });
@@ -317,14 +308,14 @@ export function ApiKeyPage() {
               placeholder="sk-..."
               value={apiKey}
               onChange={setApiKey}
-              maskedValue={apiKeyMasked}
+              maskedValue={modelFormValues.apiKeyMasked}
               showPassword={showApiKey}
               onTogglePassword={() => setShowApiKey((value) => !value)}
             />
 
             <div className="flex min-h-9 items-center justify-end gap-3">
-              <ValidationMessage validation={llmValidation} stale={isTestStale} />
-              <TestButton status={llmValidation.status} onClick={testLlmConnection} label={t("apiKey.test")} />
+              <ValidationMessage validation={llmValidation} stale={isTestStale} credentialRequired={modelFormValues.requiresApiKey} />
+              <TestButton status={isTestStale || modelFormValues.requiresApiKey ? "idle" : llmValidation.status} onClick={testLlmConnection} label={t("apiKey.test")} />
             </div>
           </div>
         </div>
@@ -366,13 +357,13 @@ export function ApiKeyPage() {
                   placeholder="sk-..."
                   value={embeddingConfig.apiKey}
                   onChange={(value) => updateEmbeddingConfig("apiKey", value)}
-                  maskedValue={embeddingConfig.apiKeyMasked}
+                  maskedValue={embeddingFormValues.apiKeyMasked}
                   showPassword={showEmbeddingApiKey}
                   onTogglePassword={() => setShowEmbeddingApiKey((value) => !value)}
                 />
                 <div className="flex min-h-9 items-center justify-end gap-3">
-                  <ValidationMessage validation={embeddingValidation} stale={isEmbeddingTestStale} />
-                  <TestButton status={embeddingValidation.status} onClick={testEmbeddingConnection} label={t("apiKey.test")} />
+                  <ValidationMessage validation={embeddingValidation} stale={isEmbeddingTestStale} credentialRequired={embeddingFormValues.requiresApiKey} />
+                  <TestButton status={isEmbeddingTestStale || embeddingFormValues.requiresApiKey ? "idle" : embeddingValidation.status} onClick={testEmbeddingConnection} label={t("apiKey.test")} />
                 </div>
               </>
             ) : null}
@@ -393,22 +384,6 @@ export function ApiKeyPage() {
   );
 }
 
-function endpointCredentialSignature(
-  provider: string,
-  protocol: string,
-  endpoint: string,
-  apiKey: string,
-  apiKeyMasked: string
-): string {
-  const normalizedApiKey = apiKey.trim();
-  const normalizedMaskedApiKey = apiKeyMasked.trim();
-  return JSON.stringify({
-    provider: provider.trim().toLowerCase(),
-    protocol,
-    endpoint: endpoint.trim().replace(/\/+$/, ""),
-    credential: normalizedMaskedApiKey ? `masked:${normalizedMaskedApiKey}` : `raw:${normalizedApiKey}`
-  });
-}
 
 function firstStepSaveErrorText(
   error: unknown,
@@ -421,9 +396,3 @@ function firstStepSaveErrorText(
     ? error.message
     : t("settings.modelWorkspace.saveFailed");
 }
-
-function chatProtocol(provider: string) {
-  if (provider === "anthropic") return "anthropic-messages" as const;
-  if (provider === "gemini") return "gemini-generate-content" as const;
-  return "openai-chat-completions" as const;
-}
diff --git a/App/frontend/desktop/src/pages/model-config-validation.ts b/App/frontend/desktop/src/pages/model-config-validation.ts
index 5c6280e5e..d5a56d78d 100644
--- a/App/frontend/desktop/src/pages/model-config-validation.ts
+++ b/App/frontend/desktop/src/pages/model-config-validation.ts
@@ -10,6 +10,8 @@ export interface ModelConfigFormValues {
   apiKey: string;
   apiKeyMasked?: string;
   hasExistingApiKey?: boolean;
+  credentialSource?: import("./model-credentials.js").SavedEndpointIdentity | null;
+  requiresApiKey?: boolean;
 }
 
 /** Type definition for model config validation status. */
@@ -26,7 +28,9 @@ export interface ModelConfigValidationState {
 export function createModelConfigValidationKey(values: ModelConfigFormValues): string {
   return JSON.stringify({
     provider: values.provider.trim(),
-    endpoint: values.endpoint.trim(),
+    endpoint: values.endpoint.trim().replace(/\/+$/, ""),
+    protocol: values.protocol,
+    endpointId: values.apiKey.trim() ? undefined : values.endpointId,
     model: values.model.trim(),
     apiKey: values.apiKey.trim() || existingSecretKey(values)
   });
diff --git a/App/frontend/desktop/src/pages/model-config.ts b/App/frontend/desktop/src/pages/model-config.ts
index 130097964..e8bcf5a70 100644
--- a/App/frontend/desktop/src/pages/model-config.ts
+++ b/App/frontend/desktop/src/pages/model-config.ts
@@ -1,4 +1,5 @@
 /** Model config module. */
+import { resolveModelCredentials, type SavedEndpointIdentity } from "./model-credentials.js";
 import { ASR_DEFAULT_BASE_URL, ASR_PROVIDER, QWEN_ASR_MODEL_ID, type ModelConfigTestSecretTarget } from "@memmy/local-api-contracts";
 import type {
   AsrProviderConfig,
@@ -24,6 +25,7 @@ export type Protocol = "openai" | "anthropic" | "gemini" | "deepseek" | "zhipu"
 
 /** Contract for model config. */
 export interface ModelConfig {
+  credentialSource?: SavedEndpointIdentity | null;
   reuse: boolean;
   protocol: Protocol;
   modelId: string;
@@ -48,6 +50,7 @@ export interface TextProviderOption {
 
 /** Contract for primary model values. */
 export interface PrimaryModelValues {
+  credentialSource?: SavedEndpointIdentity | null;
   protocol: Protocol;
   modelId: string;
   endpoint: string;
@@ -100,6 +103,7 @@ export interface TestModelConnectionInput {
 /** Contract for test model connection messages. */
 export interface TestModelConnectionMessages {
   missingFields: string;
+  credentialsChanged?: string;
   localApiUnavailable: string;
   testing: string;
   success: string;
@@ -195,6 +199,7 @@ export const IMAGE_DEFAULT_MODEL_IDS: Record<ImageProtocol, string> = {
 export function createTestModelConnectionMessages(t: (key: MessageKey) => string): TestModelConnectionMessages {
   return {
     missingFields: t("apiKey.testMissingFields"),
+    credentialsChanged: t("apiKey.credentialsChanged"),
     localApiUnavailable: t("apiKey.testLocalApiUnavailable"),
     testing: t("apiKey.testConnecting"),
     success: t("apiKey.testSuccess"),
@@ -236,30 +241,24 @@ export function createModelProtocolPatch(protocol: Protocol): Pick<ModelConfig,
 
 /** Creates create model form values. */
 export function createModelFormValues(config: ModelConfig, primary: PrimaryModelValues): ModelConfigFormValues {
-  if (config.reuse) {
-    return {
-      provider: fromProtocol(primary.protocol),
-      endpoint: primary.endpoint,
-      model: primary.modelId,
-      apiKey: primary.apiKey,
-      apiKeyMasked: primary.apiKeyMasked,
-      hasExistingApiKey: Boolean(primary.configured || primary.apiKeyMasked)
-    };
-  }
-
-  return {
-    provider: fromProtocol(config.protocol),
-    endpoint: config.endpoint,
-    model: config.modelId,
-    apiKey: config.apiKey,
-    apiKeyMasked: config.apiKeyMasked,
-    hasExistingApiKey: Boolean(config.configured || config.apiKeyMasked)
+  const selected = config.reuse ? primary : config;
+  const values: ModelConfigFormValues = {
+    provider: fromProtocol(selected.protocol),
+    endpoint: selected.endpoint,
+    model: selected.modelId,
+    apiKey: selected.apiKey,
+    apiKeyMasked: selected.apiKeyMasked,
+    hasExistingApiKey: Boolean(selected.configured || selected.apiKeyMasked)
   };
+  return selected.credentialSource === undefined
+    ? values
+    : resolveModelCredentials(values, selected.credentialSource);
 }
 
 /** Converts resolved form values into the inheritance source for a weaker model role. */
 export function modelFormValuesAsPrimary(values: ModelConfigFormValues): PrimaryModelValues {
   return {
+    ...(values.credentialSource !== undefined ? { credentialSource: values.credentialSource } : {}),
     protocol: toProtocol(values.provider),
     modelId: values.model,
     endpoint: values.endpoint,
@@ -491,19 +490,10 @@ function toRoleModelProviderConfig(values: ModelConfigFormValues): RoleModelProv
 }
 
 function hydrateRoleModelConfig(role: RoleModelProviderConfig | undefined, primary: PrimaryModelValues): ModelConfig {
-  if (!role || role.mode === "follow" || (!role.configured && !role.apiKeyMasked)) {
+  if (!role || role.mode === "follow" || (role.mode !== "fixed" && !role.configured && !role.apiKeyMasked && !role.apiKey.trim())) {
     return createModelConfig(primary.protocol);
   }
 
-  if (isReusingPrimaryModel(role, primary)) {
-    return {
-      ...createModelConfig(primary.protocol),
-      configured: true,
-      apiKeyMasked: primary.apiKeyMasked ?? "",
-      validation: createSavedValidation(createModelFormValues(createModelConfig(primary.protocol), primary))
-    };
-  }
-
   const protocol = toProtocol(role.provider);
   const config: ModelConfig = {
     reuse: false,
@@ -520,12 +510,6 @@ function hydrateRoleModelConfig(role: RoleModelProviderConfig | undefined, prima
   return config;
 }
 
-function isReusingPrimaryModel(role: RoleModelProviderConfig, primary: PrimaryModelValues): boolean {
-  return role.provider === fromProtocol(primary.protocol)
-    && role.endpoint === primary.endpoint
-    && role.model === primary.modelId;
-}
-
 function resolveEmbeddingMode(
   embedding: EmbeddingProviderConfig | null,
   defaultEmbeddingMode: ModelConfigEmbeddingMode
@@ -573,7 +557,9 @@ export function testModelConnection(input: TestModelConnectionInput): void {
   if (!hasRequiredModelConfigValues(input.values)) {
     input.setValidation({
       status: "error",
-      message: input.messages.missingFields,
+      message: input.values.requiresApiKey
+        ? input.messages.credentialsChanged ?? input.messages.missingFields
+        : input.messages.missingFields,
       testedKey: null
     });
     return;
diff --git a/App/frontend/desktop/src/pages/model-credentials.ts b/App/frontend/desktop/src/pages/model-credentials.ts
new file mode 100644
index 000000000..34c0e26db
--- /dev/null
+++ b/App/frontend/desktop/src/pages/model-credentials.ts
@@ -0,0 +1,61 @@
+import { canonicalCatalogProviderId } from "@memmy/local-api-contracts";
+import type { ModelConfigFormValues, ModelConfigValidationState } from "./model-config-validation.js";
+import { createModelConfigValidationKey, hasRequiredModelConfigValues } from "./model-config-validation.js";
+
+/** Binds a displayed credential to the saved connection that owns it. */
+export interface SavedEndpointIdentity {
+  endpointId: string;
+  credentialSignature: string;
+}
+
+export function chatProtocol(provider: string) {
+  if (provider === "anthropic") return "anthropic-messages" as const;
+  if (provider === "gemini" || provider === "google") return "gemini-generate-content" as const;
+  return "openai-chat-completions" as const;
+}
+
+export function endpointCredentialSignature(
+  provider: string, protocol: string, endpoint: string, apiKey: string, apiKeyMasked: string
+): string {
+  const raw = apiKey.trim();
+  return JSON.stringify({
+    provider: canonicalCatalogProviderId(provider) ?? provider.trim().toLowerCase(),
+    protocol,
+    endpoint: endpoint.trim().replace(/\/+$/, ""),
+    credential: raw ? `raw:${raw}` : `masked:${apiKeyMasked.trim()}`
+  });
+}
+
+/** Tests, display and persistence must all consume these same resolved values. */
+export function resolveModelCredentials(
+  values: ModelConfigFormValues,
+  source: SavedEndpointIdentity | null | undefined
+): ModelConfigFormValues {
+  const protocol = values.protocol ?? chatProtocol(values.provider);
+  const raw = values.apiKey.trim();
+  const signature = endpointCredentialSignature(values.provider, protocol, values.endpoint, raw, values.apiKeyMasked ?? "");
+  const matches = Boolean(source && source.credentialSignature === signature);
+  const hasExistingApiKey = !raw && matches && Boolean(values.apiKeyMasked);
+  return {
+    ...values,
+    protocol,
+    endpoint: values.endpoint.trim().replace(/\/+$/, ""),
+    apiKey: raw,
+    endpointId: matches ? source!.endpointId : undefined,
+    apiKeyMasked: hasExistingApiKey ? values.apiKeyMasked : "",
+    hasExistingApiKey,
+    credentialSource: source ?? null,
+    requiresApiKey: !raw && !hasExistingApiKey && Boolean(source || values.apiKeyMasked)
+  };
+}
+
+/** Rebind the initial saved validation to its credential identity, never to later edits. */
+export function bindSavedValidation(
+  validation: ModelConfigValidationState, values: ModelConfigFormValues
+): ModelConfigValidationState {
+  return {
+    ...validation,
+    testedKey: validation.testedKey && hasRequiredModelConfigValues(values)
+      ? createModelConfigValidationKey(values) : null
+  };
+}
diff --git a/App/frontend/desktop/src/pages/model-page.tsx b/App/frontend/desktop/src/pages/model-page.tsx
index b541878d7..2d4caa53b 100644
--- a/App/frontend/desktop/src/pages/model-page.tsx
+++ b/App/frontend/desktop/src/pages/model-page.tsx
@@ -1,4 +1,5 @@
 /** Model page module. */
+import { bindSavedValidation, chatProtocol, endpointCredentialSignature } from "./model-credentials.js";
 import { useState, type ReactNode } from "react";
 import { Brain, Check, CheckCircle2, ChevronLeft, Cog, Eye, EyeOff, Lightbulb, Loader2, XCircle } from "lucide-react";
 import { useApiClients } from "../app/providers.js";
@@ -75,6 +76,7 @@ interface TestButtonProps {
 interface ValidationMessageProps {
   validation: ModelConfigValidationState;
   stale: boolean;
+  credentialRequired?: boolean;
 }
 
 /** Handles model page. */
@@ -83,8 +85,8 @@ export function ModelPage() {
   const { clients } = useApiClients();
   const { t } = useTranslation();
   const { track } = useAnalytics();
-  const initialModelForm = hydrateModelConfigForm(state.modelConfig, "local");
-  const initialWorkspace = createModelWorkspace(state.modelConfig);
+  const [initialModelForm] = useState(() => hydrateModelConfigForm(state.modelConfig, "local"));
+  const [initialWorkspace] = useState(() => createModelWorkspace(state.modelConfig));
   const primaryEndpointId = assignedCatalogEndpointId(initialWorkspace, "byok", "agent");
   const [primaryModel] = useState<PrimaryModelValues>(() => ({
     protocol: initialModelForm.protocol,
@@ -92,33 +94,34 @@ export function ModelPage() {
     endpoint: initialModelForm.endpoint,
     apiKey: initialModelForm.apiKey,
     apiKeyMasked: state.modelConfig.apiKeyMasked,
-    configured: state.modelConfig.configured
+    configured: state.modelConfig.configured,
+    credentialSource: primaryEndpointId ? {
+      endpointId: primaryEndpointId,
+      credentialSignature: endpointCredentialSignature(initialModelForm.protocol, chatProtocol(initialModelForm.protocol), initialModelForm.endpoint, initialModelForm.apiKey, initialModelForm.apiKeyMasked)
+    } : null
   }));
-  const [mem, setMem] = useState<ModelConfig>(() => initialModelForm.memoryModel);
-  const [skill, setSkill] = useState<ModelConfig>(() => initialModelForm.skillModel);
+  const [skill, setSkill] = useState<ModelConfig>(() => bindRoleCredential(
+    initialModelForm.skillModel, primaryModel, assignedCatalogEndpointId(initialWorkspace, "byok", "memory_evolution")
+  ));
+  const [mem, setMem] = useState<ModelConfig>(() => bindRoleCredential(
+    initialModelForm.memoryModel, modelFormValuesAsPrimary(createModelFormValues(skill, primaryModel)),
+    assignedCatalogEndpointId(initialWorkspace, "byok", "memory_summary")
+  ));
   const [savePending, setSavePending] = useState(false);
   const [saveFeedback, setSaveFeedback] = useState<{ text: string; tone: "error" | "success" } | null>(null);
   const skillValues = createModelFormValues(skill, primaryModel);
   const evolutionModel = modelFormValuesAsPrimary(skillValues);
   const memoryValues = createModelFormValues(mem, evolutionModel);
-  const skillEndpointId = skill.reuse
-    ? primaryEndpointId
-    : assignedCatalogEndpointId(initialWorkspace, "byok", "memory_evolution")
-      ?? (skillValues.apiKeyMasked ? primaryEndpointId : undefined);
-  const memoryEndpointId = mem.reuse
-    ? skillEndpointId
-    : assignedCatalogEndpointId(initialWorkspace, "byok", "memory_summary")
-      ?? (memoryValues.apiKeyMasked ? skillEndpointId : undefined);
   const canContinue = canUseModelConfig(mem, memoryValues) && canUseModelConfig(skill, skillValues);
 
   /** Handles patch mem. */
   function patchMem(patch: Partial<ModelConfig>) {
-    setMem((current) => ({ ...current, ...patch }));
+    setMem((current) => patchModelConfig(current, patch));
   }
 
   /** Handles patch skill. */
   function patchSkill(patch: Partial<ModelConfig>) {
-    setSkill((current) => ({ ...current, ...patch }));
+    setSkill((current) => patchModelConfig(current, patch));
   }
 
   /** Handles test model config connection. */
@@ -131,12 +134,7 @@ export function ModelPage() {
     const values = createModelFormValues(config, inheritedModel);
     testModelConnection({
       configClient: clients?.config,
-      values: {
-        ...values,
-        endpointId: values.apiKeyMasked
-          ? secretTarget === "skill" ? skillEndpointId : memoryEndpointId
-          : undefined
-      },
+      values,
       setValidation: (validation) => patch({ validation }),
       secretTarget,
       messages: createTestModelConnectionMessages(t)
@@ -157,15 +155,9 @@ export function ModelPage() {
       let workspace = createModelWorkspace(latest);
       const evolutionValues = createModelFormValues(skill, primaryModel);
       const memoryValues = createModelFormValues(mem, modelFormValuesAsPrimary(evolutionValues));
-      const assignedEvolutionEndpointId = skill.reuse
-        ? assignedCatalogEndpointId(workspace, "byok", "agent")
-        : assignedCatalogEndpointId(workspace, "byok", "memory_evolution")
-          ?? (!evolutionValues.apiKey.trim() && evolutionValues.apiKeyMasked
-            ? assignedCatalogEndpointId(workspace, "byok", "agent")
-            : undefined);
       const evolution = upsertByokPreset(workspace, {
         provider: evolutionValues.provider,
-        ...(evolutionValues.apiKeyMasked && assignedEvolutionEndpointId ? { endpointId: assignedEvolutionEndpointId } : {}),
+        ...(evolutionValues.endpointId ? { endpointId: evolutionValues.endpointId } : {}),
         endpoint: evolutionValues.endpoint,
         protocol: chatProtocol(evolutionValues.provider),
         ...(evolutionValues.apiKey.trim() ? { apiKey: evolutionValues.apiKey.trim() } : {}),
@@ -174,15 +166,9 @@ export function ModelPage() {
         capabilities: ["memory_evolution"]
       });
       workspace = assignCatalogPreset(evolution.workspace, "byok", "memory_evolution", evolution.presetId);
-      const assignedMemoryEndpointId = mem.reuse
-        ? evolution.endpointId
-        : assignedCatalogEndpointId(workspace, "byok", "memory_summary")
-          ?? (!memoryValues.apiKey.trim() && memoryValues.apiKeyMasked
-            ? evolution.endpointId
-            : undefined);
       const memory = upsertByokPreset(workspace, {
         provider: memoryValues.provider,
-        ...(memoryValues.apiKeyMasked && assignedMemoryEndpointId ? { endpointId: assignedMemoryEndpointId } : {}),
+        ...(memoryValues.endpointId ? { endpointId: memoryValues.endpointId } : {}),
         endpoint: memoryValues.endpoint,
         protocol: chatProtocol(memoryValues.provider),
         ...(memoryValues.apiKey.trim() ? { apiKey: memoryValues.apiKey.trim() } : {}),
@@ -277,10 +263,26 @@ function modelPageSaveErrorText(
   return message || t("settings.modelWorkspace.saveFailed");
 }
 
-function chatProtocol(provider: string) {
-  if (provider === "anthropic") return "anthropic-messages" as const;
-  if (provider === "gemini" || provider === "google") return "gemini-generate-content" as const;
-  return "openai-chat-completions" as const;
+function patchModelConfig(current: ModelConfig, patch: Partial<ModelConfig>): ModelConfig {
+  return {
+    ...current,
+    ...patch,
+    ...(patch.reuse !== undefined
+      ? { validation: { status: "idle" as const, message: null, testedKey: null } }
+      : {})
+  };
+}
+
+function bindRoleCredential(config: ModelConfig, primary: PrimaryModelValues, endpointId: string | undefined): ModelConfig {
+  const next: ModelConfig = {
+    ...config,
+    credentialSource: endpointId ? {
+      endpointId,
+      credentialSignature: endpointCredentialSignature(config.protocol, chatProtocol(config.protocol), config.endpoint, config.apiKey, config.apiKeyMasked)
+    } : null
+  };
+  next.validation = bindSavedValidation(config.validation, createModelFormValues(next, primary));
+  return next;
 }
 
 /**
@@ -305,6 +307,7 @@ function ModelCard(props: ModelCardProps) {
         endpoint: props.primary.endpoint,
         apiKey: props.primary.apiKey,
         apiKeyMasked: props.primary.apiKeyMasked ?? "",
+        credentialSource: props.primary.credentialSource,
         configured: Boolean(props.primary.configured || props.primary.apiKeyMasked)
       });
       return;
@@ -385,12 +388,12 @@ function ModelCard(props: ModelCardProps) {
             value={props.cfg.apiKey}
             onChange={(value) => props.onPatch({ apiKey: value })}
             show={props.cfg.showKey}
-            maskedValue={props.cfg.apiKeyMasked}
+            maskedValue={formValues.apiKeyMasked}
             onToggle={() => props.onPatch({ showKey: !props.cfg.showKey })}
           />
           <div className="flex min-h-9 items-center justify-end gap-3">
-            <ValidationMessage validation={props.cfg.validation} stale={isTestStale} />
-            <TestButton status={props.cfg.validation.status} onClick={props.onTest} disabled={false} />
+            <ValidationMessage validation={props.cfg.validation} stale={isTestStale} credentialRequired={formValues.requiresApiKey} />
+            <TestButton status={isTestStale || formValues.requiresApiKey ? "idle" : props.cfg.validation.status} onClick={props.onTest} disabled={false} />
           </div>
         </div>
       )}
@@ -499,12 +502,12 @@ function TestButton(props: TestButtonProps) {
 function ValidationMessage(props: ValidationMessageProps) {
   const { t } = useTranslation();
 
-  if (props.validation.status === "idle" && !props.stale) {
+  if (props.validation.status === "idle" && !props.stale && !props.credentialRequired) {
     return null;
   }
 
-  const isSuccess = props.validation.status === "success" && !props.stale;
-  const message = props.stale ? t("apiKey.testStale") : props.validation.message;
+  const isSuccess = props.validation.status === "success" && !props.stale && !props.credentialRequired;
+  const message = props.credentialRequired ? t("apiKey.credentialsChanged") : props.stale ? t("apiKey.testStale") : props.validation.message;
 
   return (
     <span className={`min-w-0 flex-1 truncate text-right text-xs ${isSuccess ? "text-status-success" : "text-status-error"}`}>
diff --git a/App/frontend/desktop/src/pages/tests/api-key-optional-page-source.test.ts b/App/frontend/desktop/src/pages/tests/api-key-optional-page-source.test.ts
index b092e1cff..7db7df8a2 100644
--- a/App/frontend/desktop/src/pages/tests/api-key-optional-page-source.test.ts
+++ b/App/frontend/desktop/src/pages/tests/api-key-optional-page-source.test.ts
@@ -35,12 +35,7 @@ describe("ApiKeyOptionalPage catalog source", () => {
     expect(source).toContain("savedCatalogSignatureRef.current !== saveSignature");
     expect(source).toContain("savedCatalogSignatureRef.current = saveSignature");
     expect(source).toContain("const savedEndpointIdentitiesRef = useRef");
-    expect(source).toContain("savedAsrIdentity?.credentialSignature === asrCredentialSignature");
-    expect(source).toContain("savedImageIdentity?.credentialSignature === imageGenCredentialSignature");
     expect(source).toContain("endpointCredentialSignature(");
-    expect(source).toContain("provider: provider.trim().toLowerCase()");
-    expect(source).toContain('endpoint: endpoint.trim().replace(/\\/+$/, "")');
-    expect(source).toContain("credential: normalizedMaskedApiKey ?");
     expect(source).toContain('role="alert"');
     expect(source).toContain("disabled={modePersistencePending}");
   });
diff --git a/App/frontend/desktop/src/pages/tests/api-key-page-source.test.ts b/App/frontend/desktop/src/pages/tests/api-key-page-source.test.ts
index 581753311..13adc501b 100644
--- a/App/frontend/desktop/src/pages/tests/api-key-page-source.test.ts
+++ b/App/frontend/desktop/src/pages/tests/api-key-page-source.test.ts
@@ -10,8 +10,8 @@ describe("ApiKeyPage source", () => {
   it("第一步仅保留大模型与 Embedding，测试连接按钮布局固定", () => {
     const source = readFileSync(apiKeyPageSourcePath, "utf8");
     const fieldsSource = readFileSync(fileURLToPath(new URL("../api-key-form-fields.tsx", import.meta.url)), "utf8");
-    const messageIndex = source.indexOf("<ValidationMessage validation={llmValidation} stale={isTestStale} />");
-    const buttonIndex = source.indexOf("<TestButton status={llmValidation.status} onClick={testLlmConnection} label={t(\"apiKey.test\")} />");
+    const messageIndex = source.indexOf("<ValidationMessage validation={llmValidation} stale={isTestStale}");
+    const buttonIndex = source.indexOf("<TestButton status=");
 
     expect(source).toContain('Brain, ChevronLeft, Search');
     expect(source).not.toContain("Mic");
@@ -80,12 +80,7 @@ describe("ApiKeyPage source", () => {
     expect(source).toContain("savedCatalogSignatureRef.current !== saveSignature");
     expect(source).toContain("savedCatalogSignatureRef.current = saveSignature");
     expect(source).toContain("const savedEndpointIdentitiesRef = useRef");
-    expect(source).toContain("savedAgentIdentity?.credentialSignature === agentCredentialSignature");
-    expect(source).toContain("savedEmbeddingIdentity?.credentialSignature === embeddingCredentialSignature");
     expect(source).toContain("endpointCredentialSignature(");
-    expect(source).toContain("provider: provider.trim().toLowerCase()");
-    expect(source).toContain('endpoint: endpoint.trim().replace(/\\/+$/, "")');
-    expect(source).toContain("credential: normalizedMaskedApiKey ?");
     expect(source).toContain('role="alert"');
     expect(source).toContain("} finally {");
   });
@@ -95,7 +90,7 @@ describe("ApiKeyPage source", () => {
 
     expect(source).toContain('hydrateModelConfigForm(state.modelConfig, "local")');
     expect(source).toContain("fromProtocol(initialModelForm.protocol)");
-    expect(source).toContain("const [apiKeyMasked, setApiKeyMasked] = useState(initialModelForm.apiKeyMasked)");
+    expect(source).toContain("const [apiKeyMasked] = useState(initialModelForm.apiKeyMasked)");
     expect(source).toContain("hasExistingApiKey: Boolean(apiKeyMasked)");
     expect(source).toContain("const [embeddingMode, setEmbeddingMode] = useState<EmbeddingMode>(initialEmbeddingMode)");
     expect(source).toContain("apiKeyMasked: embeddingConfig.apiKeyMasked");
@@ -110,7 +105,7 @@ describe("ApiKeyPage source", () => {
 
     expect(source).not.toContain("showSavedSecret");
     expect(source).not.toContain('savedLabel={t("apiKey.savedKey")}');
-    expect(source).toContain("maskedValue={apiKeyMasked}");
+    expect(source).toContain("maskedValue={modelFormValues.apiKeyMasked}");
     expect(fieldsSource).toContain("const placeholder = !props.value.trim() && props.maskedValue ? props.maskedValue : props.placeholder;");
     expect(fieldsSource).toContain("placeholder={placeholder}");
   });
@@ -140,7 +135,6 @@ describe("ApiKeyPage source", () => {
     expect(source).toContain("setEndpoint(next.endpoint)");
     expect(source).toContain('setModel("")');
     expect(source).toContain('setApiKey("");');
-    expect(source).toContain('setApiKeyMasked("");');
     expect(source).toContain('placeholder={`${t("apiKey.examplePrefix")} ${selectedProvider.defaultModelId}`}');
     expect(source).not.toContain("modelPlaceholder");
   });
diff --git a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
new file mode 100644
index 000000000..39619a7ad
--- /dev/null
+++ b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
@@ -0,0 +1,351 @@
+// @vitest-environment happy-dom
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { act, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ModelCapability, ModelConfigInput, ModelConfigTestInput } from "@memmy/local-api-contracts";
+import { createMemmyConfigWriter } from "../../../../../backend/src/infrastructure/memmy-config/index.js";
+import { createAppConfigService, type CreateAppConfigServiceOptions } from "../../../../../backend/src/services/app-config-service.js";
+import { createHttpConfigClient } from "../../api/config-client.js";
+import type { AppClients } from "../../api/client-types.js";
+import { createInitialAppState, type AppState } from "../../state/app-reducer.js";
+import { assignedCatalogEndpointId, assignCatalogPreset, createModelWorkspace, modelConfigInput, upsertByokPreset } from "../../state/model-workspace.js";
+import { ApiKeyPage } from "../api-key-page.js";
+import { ApiKeyOptionalPage } from "../api-key-optional-page.js";
+import { ModelPage } from "../model-page.js";
+
+const mocks = vi.hoisted(() => ({ clients: null as AppClients | null, state: null as AppState | null, dispatch: vi.fn() }));
+vi.mock("../../app/providers.js", () => ({ useApiClients: () => ({ clients: mocks.clients }) }));
+vi.mock("../../state/app-state.js", () => ({ useAppState: () => ({ state: mocks.state, dispatch: mocks.dispatch }) }));
+vi.mock("../../analytics/use-analytics.js", () => ({ useAnalytics: () => ({ track: vi.fn() }) }));
+vi.mock("../../i18n/use-translation.js", () => ({ useTranslation: () => ({ t: (key: string) => key, language: "zh-CN" }) }));
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+// Use the real HTTP client conversion, backend secret resolution and catalog file writer.
+// Only transport and the external model provider are replaced; no real keys or network calls.
+async function createServer(directory: string, independent = true) {
+  const writer = createMemmyConfigWriter({ configPath: join(directory, "config.yaml") });
+  const probe = vi.fn(async (_input: ModelConfigTestInput & { apiKey: string }) => ({
+    ok: true, message: "ok", checkedAt: "2026-10-16T00:00:00.000Z"
+  }));
+  const service = createAppConfigService({
+    bootstrapRepository: {} as CreateAppConfigServiceOptions["bootstrapRepository"],
+    memmyConfigWriter: writer,
+    modelConfigTester: { test: probe }
+  });
+  const write = vi.spyOn(service, "setModelConfig");
+  vi.stubGlobal("fetch", vi.fn(async (url: URL, init: RequestInit) => {
+    const path = new URL(url).pathname;
+    let data: unknown;
+    if (path.endsWith("/test")) data = await service.testModelConfig(JSON.parse(String(init.body)));
+    else if (path === "/api/app/model-config") data = init.method === "GET"
+      ? await service.getModelConfig() : await service.setModelConfig(JSON.parse(String(init.body)) as ModelConfigInput);
+    else throw new Error(`Unexpected request: ${path}`);
+    return new Response(JSON.stringify(data), { headers: { "content-type": "application/json" } });
+  }));
+  const client = createHttpConfigClient({ baseUrl: "http://test.invalid", localToken: "test-only" });
+  client.updateSettings = vi.fn(async (input) => input) as typeof client.updateSettings;
+  client.updateOnboarding = vi.fn(async (input) => input) as typeof client.updateOnboarding;
+  let workspace = createModelWorkspace(await service.getModelConfig());
+  for (const [capability, provider, protocol, model, key] of [
+    ["agent", "openai", "openai-chat-completions", "same-model", "sk-personal-1111"],
+    ["embedding", "openai", "openai-embeddings", "embed-model", "sk-embedding-2222"],
+    ["asr", "qwen", "dashscope-input-audio-chat", "qwen3-asr-flash", "sk-asr-3333"],
+    ["image_generation", "openai", "openai-images", "image-model", "sk-image-4444"],
+    ...(independent ? [
+      ["memory_evolution", "openai", "openai-chat-completions", "same-model", "sk-team-1111"],
+      ["memory_summary", "openai", "openai-chat-completions", "same-model", "sk-summary-1111"]
+    ] : [])
+  ] as const) {
+    const preset = upsertByokPreset(workspace, {
+      provider, protocol, model, apiKey: key, endpoint: "https://provider.example/v1", capabilities: [capability]
+    });
+    workspace = assignCatalogPreset(preset.workspace, "byok", capability, preset.presetId);
+  }
+  // Same route/model/capabilities and same displayed mask, but a different secret.
+  // Saving the primary key must never resolve to this unassigned alternative.
+  workspace = upsertByokPreset(workspace, {
+    provider: "openai", protocol: "openai-chat-completions", model: "same-model",
+    apiKey: "sk-alternative-1111", endpoint: "https://provider.example/v1", capabilities: ["agent"]
+  }).workspace;
+  await client.saveModelCatalog(modelConfigInput(workspace));
+  write.mockClear();
+  return {
+    client, probe, write, writer,
+    read: () => client.getModelConfig(),
+    async key(capability: ModelCapability) {
+      const config = await client.getModelConfig();
+      const workspace = createModelWorkspace(config);
+      const id = assignedCatalogEndpointId(workspace, "byok", capability)!;
+      const provider = config.catalog!.providers.find((provider) => provider.endpoints.some((endpoint) => endpoint.endpointId === id))!;
+      return writer.readEndpointApiKey!(provider.provider, id);
+    }
+  };
+}
+
+type Scenario = { role: ModelCapability; page: () => ReactNode; endpoint: string; model: string; key: string; expected: string; index: number; fieldIndex?: number };
+const scenarios: Scenario[] = [
+  { role: "agent", page: () => <ApiKeyPage />, endpoint: "apiKey.endpoint", model: "apiKey.model", key: "apiKey.key", expected: "sk-personal-1111", index: 0 },
+  { role: "embedding", page: () => <ApiKeyPage />, endpoint: "apiKey.embeddingEndpoint", model: "apiKey.embeddingModel", key: "apiKey.embeddingKey", expected: "sk-embedding-2222", index: 1 },
+  { role: "asr", page: () => <ApiKeyOptionalPage />, endpoint: "apiKey.asrEndpoint", model: "apiKey.asrModel", key: "apiKey.asrKey", expected: "sk-asr-3333", index: 0 },
+  { role: "image_generation", page: () => <ApiKeyOptionalPage />, endpoint: "apiKey.imageGenEndpoint", model: "apiKey.imageGenModel", key: "apiKey.imageGenKey", expected: "sk-image-4444", index: 1 },
+  { role: "memory_evolution", page: () => <ModelPage />, endpoint: "apiKey.endpoint", model: "apiKey.model", key: "API Key", expected: "sk-team-1111", index: 1, fieldIndex: 1 },
+  { role: "memory_summary", page: () => <ModelPage />, endpoint: "apiKey.endpoint", model: "apiKey.model", key: "API Key", expected: "sk-summary-1111", index: 0, fieldIndex: 0 }
+];
+
+describe("BYOK displayed, tested and saved credentials", () => {
+  let directory: string;
+  let container: HTMLDivElement;
+  let root: Root;
+  let server: Awaited<ReturnType<typeof createServer>>;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    directory = await mkdtemp(join(tmpdir(), "memmy-byok-review-"));
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    server = await createServer(directory);
+    mocks.state = { ...createInitialAppState(), modelConfig: await server.read() };
+    mocks.clients = { config: server.client } as AppClients;
+  });
+  afterEach(async () => {
+    act(() => root.unmount());
+    document.body.replaceChildren();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    await rm(directory, { recursive: true, force: true });
+  });
+
+  async function render(page: ReactNode) { await act(async () => root.render(page)); }
+  async function click(button: HTMLButtonElement) { await act(async () => button.click()); }
+  function next() { return [...container.querySelectorAll("button")].find((button) => button.textContent === "apiKey.next")!; }
+  function test(index: number) { return [...container.querySelectorAll("button")].filter((button) => button.textContent?.startsWith("apiKey.test"))[index]!; }
+  function field(label: string, index = 0) {
+    return [...container.querySelectorAll("label")].filter((node) => node.textContent === label)[index]!.parentElement!.querySelector("input")!;
+  }
+  async function change(input: HTMLInputElement, value: string) {
+    await act(async () => {
+      Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!.call(input, value);
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+  }
+  async function testAndSave(scenario: Scenario) {
+    const count = server.probe.mock.calls.length;
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(count + 1));
+    await vi.waitFor(() => expect(test(scenario.index).textContent).toBe("apiKey.testSuccess"));
+    const tested = server.probe.mock.calls.at(-1)![0];
+    const writes = server.write.mock.calls.length;
+    await click(next());
+    await vi.waitFor(() => expect(server.write.mock.calls.length).toBeGreaterThan(writes));
+    await vi.waitFor(() => expect(mocks.dispatch).toHaveBeenCalledWith(expect.objectContaining({ type: "navigation/changed" })));
+    expect(await server.key(scenario.role)).toBe(tested.apiKey);
+    return tested;
+  }
+
+  it.each(scenarios)("$role: unchanged masked credential resolves and persists the same real key", async (scenario) => {
+    await render(scenario.page());
+    expect(field(scenario.key, scenario.fieldIndex).value).toBe("");
+    expect(field(scenario.key, scenario.fieldIndex).placeholder).toContain(scenario.expected.slice(-4));
+    expect((await testAndSave(scenario)).apiKey).toBe(scenario.expected);
+  });
+
+  it.each(scenarios)("$role: changed URL blocks old credentials; explicit key tests and saves a separate connection", async (scenario) => {
+    const original = await server.read();
+    const oldId = assignedCatalogEndpointId(createModelWorkspace(original), "byok", scenario.role)!;
+    const oldProvider = original.catalog!.providers.find((provider) => provider.endpoints.some((endpoint) => endpoint.endpointId === oldId))!.provider;
+    await render(scenario.page());
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(test(scenario.index).textContent).toBe("apiKey.testSuccess"));
+    await change(field(scenario.endpoint, scenario.fieldIndex), "https://changed.example/v1");
+    expect(field(scenario.key, scenario.fieldIndex).placeholder).toBe("sk-...");
+    expect(container.textContent).toContain("apiKey.credentialsChanged");
+    expect(test(scenario.index).textContent).not.toBe("apiKey.testSuccess");
+    const calls = server.probe.mock.calls.length;
+    await click(test(scenario.index));
+    expect(server.probe).toHaveBeenCalledTimes(calls);
+    await click(next());
+    expect(server.write).not.toHaveBeenCalled();
+    // The same key may be entered again; no new provider credential is required.
+    await change(field(scenario.key, scenario.fieldIndex), scenario.expected);
+    const result = await testAndSave(scenario);
+    expect(result.apiBase).toBe("https://changed.example/v1");
+    expect(result.apiKey).toBe(scenario.expected);
+    const saved = await server.read();
+    expect(assignedCatalogEndpointId(createModelWorkspace(saved), "byok", scenario.role)).not.toBe(oldId);
+    expect(await server.writer.readEndpointApiKey!(oldProvider, oldId)).toBe(scenario.expected);
+    expect(saved.catalog!.providers.find((provider) => provider.provider === oldProvider)!.endpoints.find((endpoint) => endpoint.endpointId === oldId)!.apiBase).toBe("https://provider.example/v1");
+  });
+
+  it.each(scenarios.filter((scenario) => scenario.role !== "asr"))("$role: model-only edits retain the key but invalidate the test", async (scenario) => {
+    const oldId = assignedCatalogEndpointId(createModelWorkspace(await server.read()), "byok", scenario.role);
+    await render(scenario.page());
+    await change(field(scenario.model, scenario.fieldIndex), "changed-model");
+    expect(container.textContent).toContain("apiKey.testStale");
+    expect(field(scenario.key, scenario.fieldIndex).placeholder).toContain(scenario.expected.slice(-4));
+    const tested = await testAndSave(scenario);
+    expect(tested.apiKey).toBe(scenario.expected);
+    expect(tested.modelId).toBe("changed-model");
+    expect(assignedCatalogEndpointId(createModelWorkspace(await server.read()), "byok", scenario.role)).toBe(oldId);
+  });
+
+  it.each(scenarios)("$role: URL whitespace and trailing slash keep the saved credential usable", async (scenario) => {
+    await render(scenario.page());
+    await change(field(scenario.endpoint, scenario.fieldIndex), "  https://provider.example/v1///  ");
+    expect(container.textContent).not.toContain("apiKey.credentialsChanged");
+    expect((await testAndSave(scenario)).apiKey).toBe(scenario.expected);
+  });
+
+  it.each([0, 1])("role %i: same URL/model and identical masks do not imply reuse; toggling restores the independent key", async (index) => {
+    await render(<ModelPage />);
+    const checkbox = () => [...container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')][index]!;
+    expect(checkbox().getAttribute("aria-checked")).toBe("false");
+    const scenario = scenarios[index === 0 ? 5 : 4]!;
+    await click(test(index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    expect(server.probe.mock.calls[0]![0].apiKey).toBe(scenario.expected);
+    await click(checkbox());
+    await click(checkbox());
+    expect(checkbox().getAttribute("aria-checked")).toBe("false");
+    expect(test(index).textContent).not.toBe("apiKey.testSuccess");
+    expect((await testAndSave(scenario)).apiKey).toBe(scenario.expected);
+  });
+  // Deduplication is verified against the real file writer, not a catalog stub.
+  it.each(scenarios)("$role: reentering the same trimmed key reuses the canonical saved endpoint", async (scenario) => {
+    const before = await server.read();
+    const oldId = assignedCatalogEndpointId(createModelWorkspace(before), "byok", scenario.role);
+    await render(scenario.page());
+    await change(field(scenario.key, scenario.fieldIndex), `  ${scenario.expected}  `);
+    expect((await testAndSave(scenario)).apiKey).toBe(scenario.expected);
+    const saved = await server.read();
+    expect(assignedCatalogEndpointId(createModelWorkspace(saved), "byok", scenario.role)).toBe(oldId);
+    expect(saved.catalog!.providers.flatMap((provider) => provider.endpoints)).toHaveLength(
+      before.catalog!.providers.flatMap((provider) => provider.endpoints).length
+    );
+  });
+
+  it.each(scenarios)("$role: replacing a key with an identical mask tests and saves the new key without overwriting the old one", async (scenario) => {
+    const before = await server.read();
+    const oldId = assignedCatalogEndpointId(createModelWorkspace(before), "byok", scenario.role)!;
+    const provider = before.catalog!.providers.find((item) => item.endpoints.some((endpoint) => endpoint.endpointId === oldId))!.provider;
+    const replacement = `sk-replacement-${scenario.expected.slice(-4)}`;
+    await render(scenario.page());
+    await change(field(scenario.key, scenario.fieldIndex), replacement);
+    expect((await testAndSave(scenario)).apiKey).toBe(replacement);
+    expect(assignedCatalogEndpointId(createModelWorkspace(await server.read()), "byok", scenario.role)).not.toBe(oldId);
+    expect(await server.writer.readEndpointApiKey!(provider, oldId)).toBe(scenario.expected);
+  });
+
+  it.each([0, 1])("role %i: enabling reuse saves the inherited credential instead of the independent credential", async (index) => {
+    await render(<ModelPage />);
+    await click([...container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')][index]!);
+    await click(next());
+    await vi.waitFor(() => expect(mocks.dispatch).toHaveBeenCalledWith(expect.objectContaining({ type: "navigation/changed" })));
+    expect(await server.key(index === 0 ? "memory_summary" : "memory_evolution")).toBe(index === 0 ? "sk-team-1111" : "sk-personal-1111");
+  });
+
+  it.each([0, 1])("role %i: disabling explicit follow copies the displayed inherited key and its actual source", async (index) => {
+    server = await createServer(join(directory, "follow"), false);
+    mocks.state = { ...createInitialAppState(), modelConfig: await server.read() };
+    mocks.clients = { config: server.client } as AppClients;
+    await render(<ModelPage />);
+    const checkbox = [...container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')][index]!;
+    expect(checkbox.getAttribute("aria-checked")).toBe("true");
+    await click(checkbox);
+    const scenario = { ...scenarios[index === 0 ? 5 : 4]!, index: 0, fieldIndex: 0 };
+    expect(field("API Key").placeholder).toContain("1111");
+    expect((await testAndSave(scenario)).apiKey).toBe("sk-personal-1111");
+  });
+
+  it.each(scenarios.filter((scenario) => ["agent", "image_generation", "memory_evolution", "memory_summary"].includes(scenario.role)))(
+    "$role: changing provider and protocol requires an explicit key before testing and saving", async (scenario) => {
+      await render(scenario.page());
+      const comboIndex = scenario.fieldIndex ?? 0;
+      await click([...container.querySelectorAll<HTMLButtonElement>('button[role="combobox"]')][comboIndex]!);
+      // Select an actual different provider through the rendered control.
+      const option = [...container.querySelectorAll<HTMLButtonElement>('button[role="option"]')].find((item) => item.getAttribute("aria-selected") === "false")!;
+      await click(option);
+      await change(field(scenario.model, scenario.fieldIndex), "changed-provider-model");
+      // Same URL does not make credentials interchangeable across providers/protocols.
+      await change(field(scenario.endpoint, scenario.fieldIndex), "https://provider.example/v1");
+      expect(field(scenario.key, scenario.fieldIndex).placeholder).toBe("sk-...");
+      expect(container.textContent).toContain("apiKey.credentialsChanged");
+      await click(test(scenario.index));
+      expect(server.probe).not.toHaveBeenCalled();
+      await click(next());
+      expect(server.write).not.toHaveBeenCalled();
+      await change(field(scenario.key, scenario.fieldIndex), scenario.expected);
+      expect((await testAndSave(scenario)).apiKey).toBe(scenario.expected);
+    }
+  );
+
+  it("an explicitly fixed incomplete role is not silently changed to follow", async () => {
+    mocks.state!.modelConfig.memmyMemory!.evolution = {
+      mode: "fixed", provider: "openai", endpoint: "https://provider.example/v1",
+      model: "", apiKey: "", apiKeyMasked: "", configured: false
+    };
+    await render(<ModelPage />);
+    expect([...container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')][1]!.getAttribute("aria-checked")).toBe("false");
+    expect(next().disabled).toBe(true);
+  });
+
+  it("a rejected independent key cannot fall back to the valid primary key or be saved", async () => {
+    await render(<ModelPage />);
+    server.probe.mockResolvedValueOnce({ ok: false, message: "rejected team key", checkedAt: "2026-10-16T00:00:00.000Z" });
+    await click(test(1));
+    await vi.waitFor(() => expect(container.textContent).toContain("rejected team key"));
+    expect(server.probe.mock.calls[0]![0].apiKey).toBe("sk-team-1111");
+    expect(next().disabled).toBe(true);
+    expect(server.write).not.toHaveBeenCalled();
+  });
+
+  it("returning after Next hydrates the saved mask and tests the same persisted key", async () => {
+    await render(<ApiKeyPage />);
+    await change(field("apiKey.key"), "sk-new-onboarding-1111");
+    await testAndSave(scenarios[0]!);
+    await render(null);
+    mocks.state = { ...createInitialAppState(), modelConfig: await server.read() };
+    mocks.dispatch.mockClear();
+    await render(<ApiKeyPage />);
+    expect(field("apiKey.key").value).toBe("");
+    expect(field("apiKey.key").placeholder).toContain("1111");
+    expect((await testAndSave(scenarios[0]!)).apiKey).toBe("sk-new-onboarding-1111");
+  });
+
+  it("an old in-flight success cannot validate a changed connection", async () => {
+    let finish!: (result: Awaited<ReturnType<typeof server.probe>>) => void;
+    server.probe.mockImplementationOnce(() => new Promise((resolve) => { finish = resolve; }));
+    await render(<ApiKeyPage />);
+    await click(test(0));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    await change(field("apiKey.endpoint"), "https://changed.example/v1");
+    await act(async () => finish({ ok: true, message: "ok", checkedAt: "2026-10-16T00:00:00.000Z" }));
+    expect(container.textContent).toContain("apiKey.credentialsChanged");
+    expect(test(0).textContent).not.toBe("apiKey.testSuccess");
+    expect(next().disabled).toBe(true);
+    expect(server.write).not.toHaveBeenCalled();
+  });
+
+  it("retry after assignment-write failure reuses the newly saved key without duplicate connections", async () => {
+    await render(<ApiKeyPage />);
+    await change(field("apiKey.key"), "sk-retry-1111");
+    await click(test(0));
+    await vi.waitFor(() => expect(test(0).textContent).toBe("apiKey.testSuccess"));
+    const persist = server.write.getMockImplementation()!;
+    server.write.mockImplementationOnce(persist).mockRejectedValueOnce(new Error("assignment-write-failed"));
+    await click(next());
+    await vi.waitFor(() => expect(container.textContent).toContain("assignment-write-failed"));
+    expect(mocks.dispatch).not.toHaveBeenCalled();
+    const endpointsAfterCreate = (await server.read()).catalog!.providers.flatMap((provider) => provider.endpoints).length;
+    await click(next());
+    await vi.waitFor(() => expect(mocks.dispatch).toHaveBeenCalledWith(expect.objectContaining({ type: "navigation/changed" })));
+    expect(await server.key("agent")).toBe("sk-retry-1111");
+    expect((await server.read()).catalog!.providers.flatMap((provider) => provider.endpoints)).toHaveLength(endpointsAfterCreate);
+  });
+
+});
diff --git a/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx
index 2011fb782..4c2f5123e 100644
--- a/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx
@@ -299,31 +299,6 @@ describe("BYOK setup save feedback", () => {
     expect(mocks.dispatch).toHaveBeenCalledWith(appActions.navigate("/api-key-models"));
   });
 
-  it("reuses existing first-step endpoints when saved keys are entered again", async () => {
-    const server = createCatalogServer(configuredCatalog(false));
-    const initialAgentEndpointId = assignedCatalogEndpointId(createModelWorkspace(server.catalog()), "byok", "agent");
-    const initialEmbeddingEndpointId = assignedCatalogEndpointId(createModelWorkspace(server.catalog()), "byok", "embedding");
-    mocks.state = { ...createInitialAppState(), modelConfig: maskedSavedModelConfig(server.catalog()) };
-    mocks.clients = createClients(server.saveModelCatalog, {
-      getModelConfig: vi.fn(async () => maskedSavedModelConfig(server.catalog()))
-    });
-    await render(<ApiKeyPage />);
-
-    await changeField("apiKey.key", "sk-primary");
-    await click(testButton());
-    await changeField("apiKey.embeddingKey", "sk-embedding");
-    await click(testButton(1));
-    await vi.waitFor(() => expect(button("apiKey.next").disabled).toBe(false));
-    await click(button("apiKey.next"));
-
-    const savedCatalog = server.catalog();
-    expect(endpointCount(savedCatalog)).toBe(2);
-    expect(assignedCatalogEndpointId(createModelWorkspace(savedCatalog), "byok", "agent"))
-      .toBe(initialAgentEndpointId);
-    expect(assignedCatalogEndpointId(createModelWorkspace(savedCatalog), "byok", "embedding"))
-      .toBe(initialEmbeddingEndpointId);
-  });
-
   it("invalidates only the changed first-step credential identity", async () => {
     const server = createCatalogServer(configuredCatalog(false));
     const updateSettings = vi.fn(async (settings: unknown) => settings)
@@ -449,31 +424,6 @@ describe("BYOK setup save feedback", () => {
     expect(mocks.dispatch).toHaveBeenCalledWith(appActions.navigate("/onboarding"));
   });
 
-  it("reuses existing optional endpoints when saved keys are entered again", async () => {
-    const server = createCatalogServer(configuredCatalog());
-    const initialAsrEndpointId = assignedCatalogEndpointId(createModelWorkspace(server.catalog()), "byok", "asr");
-    const initialImageEndpointId = assignedCatalogEndpointId(createModelWorkspace(server.catalog()), "byok", "image_generation");
-    mocks.state = { ...createInitialAppState(), modelConfig: maskedSavedModelConfig(server.catalog()) };
-    mocks.clients = createClients(server.saveModelCatalog, {
-      getModelConfig: vi.fn(async () => maskedSavedModelConfig(server.catalog()))
-    });
-    await render(<ApiKeyOptionalPage />);
-
-    await changeField("apiKey.asrKey", "sk-asr");
-    await click(testButton());
-    await changeField("apiKey.imageGenKey", "sk-image");
-    await click(testButton(1));
-    await vi.waitFor(() => expect(button("apiKey.next").disabled).toBe(false));
-    await click(button("apiKey.next"));
-
-    const savedCatalog = server.catalog();
-    expect(endpointCount(savedCatalog)).toBe(4);
-    expect(assignedCatalogEndpointId(createModelWorkspace(savedCatalog), "byok", "asr"))
-      .toBe(initialAsrEndpointId);
-    expect(assignedCatalogEndpointId(createModelWorkspace(savedCatalog), "byok", "image_generation"))
-      .toBe(initialImageEndpointId);
-  });
-
   it("retests masked optional keys through their saved endpoints", async () => {
     const catalog = configuredCatalog();
     const workspace = createModelWorkspace(catalog);
diff --git a/App/frontend/desktop/src/pages/tests/model-config.test.ts b/App/frontend/desktop/src/pages/tests/model-config.test.ts
index c4f6df998..553c3335a 100644
--- a/App/frontend/desktop/src/pages/tests/model-config.test.ts
+++ b/App/frontend/desktop/src/pages/tests/model-config.test.ts
@@ -338,7 +338,7 @@ describe("model config helpers", () => {
         apiKeyMasked: "sk-m••••mory"
       },
       skillModel: {
-        reuse: true,
+        reuse: false,
         apiKeyMasked: "sk-m••••main"
       }
     });
diff --git a/App/frontend/desktop/src/pages/tests/model-page-source.test.ts b/App/frontend/desktop/src/pages/tests/model-page-source.test.ts
index e03408d33..3218c9649 100644
--- a/App/frontend/desktop/src/pages/tests/model-page-source.test.ts
+++ b/App/frontend/desktop/src/pages/tests/model-page-source.test.ts
@@ -37,11 +37,7 @@ describe("ModelPage source", () => {
     expect(pageSource).toContain('capabilities: ["memory_evolution"]');
     expect(pageSource).toContain('assignCatalogPreset(memory.workspace, "byok", "memory_summary"');
     expect(pageSource).toContain('assignCatalogPreset(evolution.workspace, "byok", "memory_evolution"');
-    expect(pageSource).toContain('assignedCatalogEndpointId(workspace, "byok", "agent")');
-    expect(pageSource).toContain("const assignedMemoryEndpointId = mem.reuse");
-    expect(pageSource).toContain("const assignedEvolutionEndpointId = skill.reuse");
-    expect(pageSource).toContain("!memoryValues.apiKey.trim() && memoryValues.apiKeyMasked");
-    expect(pageSource).toContain("!evolutionValues.apiKey.trim() && evolutionValues.apiKeyMasked");
+    expect(pageSource).toContain('assignedCatalogEndpointId(initialWorkspace, "byok", "agent")');
     expect(pageSource).toContain("createModelFormValues");
     expect(pageSource).toContain("createModelProtocolPatch");
     expect(pageSource).toContain("testModelConnection");
@@ -53,7 +49,7 @@ describe("ModelPage source", () => {
     expect(pageSource).not.toContain('dispatch(appActions.navigate("/onboarding"))');
     expect(pageSource).not.toContain('track({ name: "byok_completed"');
     expect(pageSource).toContain("DEFAULT_MODEL_IDS[props.cfg.protocol]");
-    expect(pageSource).toContain("<ValidationMessage validation={props.cfg.validation} stale={isTestStale} />");
+    expect(pageSource).toContain("<ValidationMessage validation={props.cfg.validation} stale={isTestStale}");
     expect(pageSource).not.toContain("shouldContinueOnboarding");
     expect(pageSource).not.toContain("MOCK_PRIMARY_LLM");
     expect(pageSource).not.toContain("useNavigate");
@@ -83,8 +79,8 @@ describe("ModelPage source", () => {
     const pageSource = readSource(resolve(pagesDir, "model-page.tsx"));
 
     expect(pageSource).toContain('hydrateModelConfigForm(state.modelConfig, "local")');
-    expect(pageSource).toContain("const [mem, setMem] = useState<ModelConfig>(() => initialModelForm.memoryModel)");
-    expect(pageSource).toContain("const [skill, setSkill] = useState<ModelConfig>(() => initialModelForm.skillModel)");
+    expect(pageSource).toContain("const [mem, setMem] = useState<ModelConfig>(() => bindRoleCredential(");
+    expect(pageSource).toContain("const [skill, setSkill] = useState<ModelConfig>(() => bindRoleCredential(");
     expect(pageSource).toContain("apiKeyMasked: state.modelConfig.apiKeyMasked");
     expect(pageSource).toContain("configured: state.modelConfig.configured");
   });

From 3a0d9a4fad8446129e03c9321ebf8b17e617531a Mon Sep 17 00:00:00 2001
From: whqf1123 <333792770+whqf1123@users.noreply.github.com>
Date: Fri, 16 Oct 2026 11:58:31 +0800
Subject: [PATCH 63/85] fix: refine embedding failure isolation and empty chunk
 handling (MEMMY-488)

---
 Memory/readme.md                              |   6 +
 Memory/src/model/openai-embedding-inputs.ts   |  25 ++--
 Memory/src/service/worker/job-handlers.ts     |  12 ++
 Memory/tests/embedding-input-guard.test.ts    |  28 +++++
 Memory/tests/memmy-488-reproduction.test.ts   |  98 ----------------
 .../embedding/embedding-processing.test.ts    | 107 +++++++++++++++++-
 6 files changed, 168 insertions(+), 108 deletions(-)
 delete mode 100644 Memory/tests/memmy-488-reproduction.test.ts

diff --git a/Memory/readme.md b/Memory/readme.md
index 8a5279407..9ecedc690 100644
--- a/Memory/readme.md
+++ b/Memory/readme.md
@@ -89,6 +89,12 @@ for input-related HTTP 400/413/422 failures, including generic parameter errors.
 Successful siblings are saved; a still-invalid item stops automatic retries.
 Authentication/configuration, quota, rate-limit and server errors do not trigger
 this fan-out. This applies to both new jobs and the embedding retry queue.
+Provider codes and messages for unsupported operations, insufficient quota/balance,
+and rate limits are classified before generic HTTP 400 errors. Rate limits retain
+delayed retry behavior; model/account configuration failures require intervention.
+Decoded empty chunks are removed from the embedding plan before requests and
+aggregation. If an original has no usable chunks, `(empty)` is embedded under the
+same input budgets so output vectors remain aligned with the originals.
 Previously failed records require an explicit retry/reindex; updating the code
 does not automatically reset their failed state.
 
diff --git a/Memory/src/model/openai-embedding-inputs.ts b/Memory/src/model/openai-embedding-inputs.ts
index 1aac54d74..9be342fe1 100644
--- a/Memory/src/model/openai-embedding-inputs.ts
+++ b/Memory/src/model/openai-embedding-inputs.ts
@@ -50,10 +50,9 @@ export function planOpenAiEmbeddingInputs(
   );
   const totalTokens = inputs.reduce((sum, item) => sum + item.tokens.length, 0);
   if (inputs.length === texts.length && totalTokens <= OPENAI_EMBEDDING_BATCH_TOKEN_BUDGET &&
-    inputs.every((item) => item.tokens.length <= inputTokenBudget)) return null;
+    inputs.every((item) => item.tokens.length > 0 && item.tokens.length <= inputTokenBudget)) return null;
 
-  const chunks = inputs.flatMap(({ tokens, originalIndex }) => {
-    if (tokens.length === 0) return [{ originalIndex, tokens, input: useTokenIds ? tokens : "" }];
+  const chunkTokensForInput = (tokens: number[], originalIndex: number): OpenAiEmbeddingChunk[] => {
     const tokenBytes = useTokenIds
       ? undefined
       : tokens.map((token) => encoder.decode_single_token_bytes(token));
@@ -69,14 +68,24 @@ export function planOpenAiEmbeddingInputs(
         }
       }
       const chunkTokens = tokens.slice(offset, end);
-      items.push({
-        originalIndex,
-        tokens: chunkTokens,
-        input: useTokenIds ? chunkTokens : decodeTokenBytes(tokenBytes!.slice(offset, end))
-      });
+      const input = useTokenIds ? chunkTokens : decodeTokenBytes(tokenBytes!.slice(offset, end));
+      // A standalone BOM can decode to an empty string. Filter in the plan,
+      // so the request and vector aggregation retain the same chunk order.
+      if (input.length > 0) items.push({ originalIndex, tokens: chunkTokens, input });
       offset = end;
     }
     return items;
+  };
+  const chunksByOriginal: OpenAiEmbeddingChunk[][] = texts.map(() => []);
+  for (const { tokens, originalIndex } of inputs) {
+    chunksByOriginal[originalIndex]!.push(...chunkTokensForInput(tokens, originalIndex));
+  }
+  const chunks = chunksByOriginal.flatMap((items, originalIndex) => {
+    if (items.length > 0) return items;
+    // Keep one output vector per original, respecting even a small configured
+    // budget when the placeholder itself needs multiple chunks.
+    const parts = useTokenIds ? ["(empty)"] : splitUtf8Input("(empty)", inputByteBudget);
+    return parts.flatMap(part => chunkTokensForInput(Array.from(encoder.encode(part, [], [])), originalIndex));
   });
   return {
     batches: batchChunks(chunks),
diff --git a/Memory/src/service/worker/job-handlers.ts b/Memory/src/service/worker/job-handlers.ts
index 121dac284..589344a6e 100644
--- a/Memory/src/service/worker/job-handlers.ts
+++ b/Memory/src/service/worker/job-handlers.ts
@@ -598,6 +598,18 @@ export function classifyProcessingError(error: unknown): {
   if (!hasStructuredCode && /\b40309\b/.test(normalized)) {
     return { code: "40309", retryAction: "open_settings" };
   }
+  // Providers can report shared model/account failures as HTTP 400. Classify
+  // their reason before generic 4xx handling, which permits item isolation.
+  if (error instanceof ModelHttpError) {
+    const providerCode = error.errorCode?.toLowerCase().replace(/[\s_-]/g, "");
+    if (providerCode === "operationnotsupported" || providerCode === "insufficientquota" ||
+      /operation.{0,80}(?:does not work|not supported)|insufficient[\s_-]+(?:quota|balance)/.test(normalized)) {
+      return { code: "model_configuration", retryAction: "open_settings" };
+    }
+    if (providerCode === "ratelimitexceeded" || /rate[\s_-]*limit/.test(normalized)) {
+      return { code: "transient_provider_error", retryAction: "retry" };
+    }
+  }
   if (/api.?key|unauthorized|forbidden|\b401\b|\b403\b|\b404\b|model.+not configured|missing.+model|expected json|html instead of json|configured model endpoint/.test(normalized)) {
     return { code: "model_configuration", retryAction: "open_settings" };
   }
diff --git a/Memory/tests/embedding-input-guard.test.ts b/Memory/tests/embedding-input-guard.test.ts
index 8e1f0453d..941e61aa7 100644
--- a/Memory/tests/embedding-input-guard.test.ts
+++ b/Memory/tests/embedding-input-guard.test.ts
@@ -4,6 +4,34 @@ import { createEmbedder } from "../src/model/embedder.js";
 
 afterEach(() => vi.unstubAllGlobals());
 
+it.each([
+  { name: "trailing decoded empty chunk", texts: ["a".repeat(12_000) + "\uFEFF", "xyz"], budget: undefined,
+    expected: ["a".repeat(12_000), "xyz"] },
+  { name: "middle decoded empty chunk", texts: ["aaa\uFEFFbbb", "xyz"], budget: 3,
+    expected: ["aaa", "bbb", "xyz"] },
+  { name: "all chunks of one original decode empty", texts: ["\uFEFF\uFEFF", "xyz"], budget: 3,
+    expected: ["(em", "pty", ")", "xyz"] },
+  { name: "empty original", texts: ["", "xyz"], budget: undefined,
+    expected: ["(empty)", "xyz"] },
+  { name: "meaningful whitespace", texts: ["   aaa", "xyz"], budget: 3,
+    expected: ["   ", "aaa", "xyz"] }
+])("keeps vectors aligned after handling $name", async ({ texts, budget, expected }) => {
+  const sent: string[] = [];
+  vi.stubGlobal("fetch", vi.fn(async (_url, init) => {
+    const { input } = JSON.parse(String(init?.body)) as { input: string[] };
+    sent.push(...input);
+    return new Response(JSON.stringify({ data: input.map(part => ({
+      embedding: part === "xyz" ? [0, 1] : [1, 0]
+    })) }), { status: 200 });
+  }));
+  const embedder = createEmbedder({ ...DEFAULT_MEMMY_CONFIG.embedding, provider: "openai_compatible",
+    model: "custom-alias", endpoint: "https://example.test/v1", maxInputBytes: budget, cache: false, maxRetries: 0 },
+    { usageRecorder: { record() { return "skipped"; } } });
+  await expect(embedder.embed(texts)).resolves.toEqual([[1, 0], [0, 1]]);
+  expect(sent).toEqual(expected);
+  expect(sent.every(part => part.length > 0 && Buffer.byteLength(part) <= (budget ?? 12_000))).toBe(true);
+});
+
 it.each([
   ["ASCII boundary", "a".repeat(27_447)],
   ["mixed Unicode", "中文🙂 café\n".repeat(5_000)]
diff --git a/Memory/tests/memmy-488-reproduction.test.ts b/Memory/tests/memmy-488-reproduction.test.ts
deleted file mode 100644
index 0dde1e782..000000000
--- a/Memory/tests/memmy-488-reproduction.test.ts
+++ /dev/null
@@ -1,98 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { DEFAULT_MEMMY_CONFIG, type MemoryRow } from '../src/index.js';
-import { createEmbedder } from '../src/model/embedder.js';
-import { Repositories } from '../src/storage/repositories.js';
-import { embeddingTextForMemory } from '../src/service/embedding/embedding-pipeline.js';
-import { createMemoryServiceFixture, createBatchReflectionLlm } from './fixtures/memory-service-fixture.js';
-
-const fixture = createMemoryServiceFixture();
-afterEach(() => { fixture.cleanup(); vi.unstubAllGlobals(); });
-
-function setup(explicit: boolean) {
-  const requests: Array<{ sizes: number[]; rejected: boolean }> = [];
-  vi.stubGlobal('fetch', vi.fn(async (_url: unknown, init: RequestInit) => {
-    const { input } = JSON.parse(String(init.body)) as { input: string[] };
-    const rejected = input.some(text => text.includes('BAD_EMBEDDING_ITEM'));
-    requests.push({ sizes: input.map(text => text.length), rejected });
-    return new Response(JSON.stringify(rejected
-      ? { code: explicit ? 'context_length_exceeded' : 20015, message: explicit ? 'maximum context length exceeded' : 'The parameter is invalid.' }
-      : { data: input.map(() => ({ embedding: [1, 0, 0] })) }),
-      { status: rejected ? 400 : 200, headers: { 'content-type': 'application/json' } });
-  }));
-  const embedder = createEmbedder({ ...DEFAULT_MEMMY_CONFIG.embedding,
-    provider: 'openai_compatible', model: 'Pro/BAAI/bge-m3',
-    endpoint: 'https://embedding-reproduction.invalid/v1', apiKey: 'synthetic-test-key',
-    cache: false, maxRetries: 3 }, { usageRecorder: { record() { return "skipped"; } } });
-  return { embedder, requests };
-}
-function skill(id: string, content: string): MemoryRow {
-  const at = new Date().toISOString();
-  return { id, timeline: at, userId: 'memmy488-test', memoryType: 'SkillMemory',
-    status: 'activated', visibility: 'private', memoryKey: id, memoryValue: content,
-    tags: [], info: {}, properties: { internal_info: { memory_layer: 'Skill', memory_kind: 'skill',
-      skill: { name: id, status: 'active', invocation_guide: content } } },
-    memoryLayer: 'Skill', version: 1, createdAt: at, updatedAt: at };
-}
-
-describe('MEMMY-488 regression (valid siblings must survive)', () => {
-  for (const explicit of [true, false]) {
-    it(`fresh worker batch: ${explicit ? 'explicit length error' : 'screenshot error 20015'}`, async () => {
-      const { embedder, requests } = setup(explicit);
-      const { db, service } = fixture.createTestService({ embedder, llm: createBatchReflectionLlm([], 'Synthetic summary.') });
-      const session = service.openSession({ namespace: { source: 'codex', profileId: 'memmy488', userId: 'memmy488-test' } });
-      const ids = ['GOOD_A', 'GOOD_B', 'GOOD_C', 'BAD_EMBEDDING_ITEM'].map((answer, i) =>
-        service.completeTurn(`turn-${i}`, { sessionId: session.sessionId, query: 'Remember this synthetic test.', answer }).l1MemoryId);
-      await service.runWorkerOnce(20, { priorityCohortOnly: true });
-      await service.runWorkerOnce(20, { priorityCohortOnly: true });
-      const repos = new Repositories(db.db);
-      const states = ids.map(id => ({ id, state: repos.processing.get(id)?.state, error: repos.processing.get(id)?.errorCode }));
-      expect(states.map(s => s.state)).toEqual(['ready', 'ready', 'ready', explicit ? 'ready_text_only' : 'failed']);
-      const vectorRows = db.db.prepare('SELECT memory_id, vector_field FROM memory_vector_entries').all();
-      expect(vectorRows.length).toBe(3);
-      const before = requests.length;
-      await service.runWorkerOnce(20, { priorityCohortOnly: true });
-      expect(requests.length).toBe(before);
-    });
-
-    it(`legacy retry batch and separate replay: ${explicit ? 'explicit length error' : 'screenshot error 20015'}`, async () => {
-      const { embedder, requests } = setup(explicit);
-      const { db, service } = fixture.createTestService({ embedder });
-      const repos = new Repositories(db.db);
-      const memories = ['GOOD_A', 'GOOD_B', 'GOOD_C', 'BAD_EMBEDDING_ITEM'].map((text, i) => skill(`skill-488-${i}`, text));
-      const retries = memories.map(memory => {
-        repos.memories.insert(memory);
-        return repos.runtime.enqueueEmbeddingRetry({ targetKind: 'skill', targetId: memory.id, vectorField: 'vec',
-          sourceText: embeddingTextForMemory(memory), embedRole: 'query', now: Date.now() - 1 });
-      });
-      await service.runWorkerOnce(10);
-      const states = retries.map(retry => { const row = repos.runtime.getEmbeddingRetry(retry.id)!; return { status: row.status, attempts: row.attempts }; });
-      expect(states.map(s => s.status)).toEqual(['succeeded', 'succeeded', 'succeeded', 'failed']);
-      const vectorRows = db.db.prepare('SELECT memory_id, vector_field FROM memory_vector_entries').all();
-      expect(vectorRows.length).toBe(3);
-      const before = requests.length;
-      await service.runWorkerOnce(10);
-      expect(requests.length).toBe(before);
-      const replay: string[] = [];
-      for (const memory of memories) {
-        try { await embedder.embedOne(embeddingTextForMemory(memory), 'query'); replay.push('succeeded'); }
-        catch { replay.push('failed'); }
-      }
-      expect(replay).toEqual(['succeeded', 'succeeded', 'succeeded', 'failed']);
-    });
-  }
-
-  it('long BGE alias text is chunked and preserves the complete input', async () => {
-    const sent: string[] = [];
-    vi.stubGlobal('fetch', vi.fn(async (_url: unknown, init: RequestInit) => {
-      const { input } = JSON.parse(String(init.body)); sent.push(...input);
-      return new Response(JSON.stringify({ data: input.map(() => ({ embedding: [1, 0, 0] })) }), { status: 200 });
-    }));
-    const embedder = createEmbedder({ ...DEFAULT_MEMMY_CONFIG.embedding, provider: 'openai_compatible',
-      model: 'Pro/BAAI/bge-m3', endpoint: 'https://embedding-reproduction.invalid/v1', apiKey: 'synthetic-test-key', cache: false },
-      { usageRecorder: { record() { return "skipped"; } } });
-    const text = '# Synthetic long document\n' + ' memory'.repeat(16000) + '\nEND_MARKER';
-    await embedder.embedOne(text);
-    expect(sent.length).toBeGreaterThan(1);
-    expect(sent.join('')).toBe(text);
-  });
-});
diff --git a/Memory/tests/service/embedding/embedding-processing.test.ts b/Memory/tests/service/embedding/embedding-processing.test.ts
index c5d7f5339..f603c81c7 100644
--- a/Memory/tests/service/embedding/embedding-processing.test.ts
+++ b/Memory/tests/service/embedding/embedding-processing.test.ts
@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   DEFAULT_MEMMY_CONFIG,
   MemoryDb,
@@ -16,6 +16,7 @@ import {
   updateMemoryVectorField
 } from "../../../src/service/embedding/embedding-pipeline.js";
 import { ModelHttpError } from "../../../src/model/http.js";
+import { createEmbedder } from "../../../src/model/embedder.js";
 import { Repositories } from "../../../src/storage/repositories.js";
 import {
   addAgentSourceImport,
@@ -32,9 +33,105 @@ const {
   createTestService
 } = createMemoryServiceFixture();
 
-afterEach(cleanup);
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
 
 describe("MemoryService / embedding / processing", () => {
+  for (const queue of ["fresh", "retry"] as const) {
+    for (const format of ["code", "message"] as const) {
+      it.each([
+        ["OperationNotSupported", "The embeddings operation does not work with the specified model.", false],
+        ["insufficient_quota", "Insufficient balance.", false],
+        ["rate_limit_exceeded", "Rate limit exceeded.", true]
+      ] as const)(`${queue} queue does not fan out shared HTTP 400 %s (${format})`, async (code, message, transient) => {
+        const fetchMock = vi.fn(async () => new Response(JSON.stringify({ error: {
+          code: format === "code" ? code : undefined,
+          message: format === "message" ? message : "Request rejected"
+        } }), { status: 400 }));
+        vi.stubGlobal("fetch", fetchMock);
+        const { db, service } = createTestService({
+          embedder: createHttpTestEmbedder(),
+          llm: createBatchReflectionLlm([], "Synthetic summary.")
+        });
+        const repos = new Repositories(db.db);
+        if (queue === "fresh") {
+          const session = service.openSession({ namespace: { source: "codex", profileId: "shared-error", userId: "test" } });
+          const ids = ["GOOD_A", "GOOD_B", "GOOD_C"].map((answer, i) => service.completeTurn(`turn-${i}`, {
+            sessionId: session.sessionId, query: "Remember this.", answer
+          }).l1MemoryId);
+          await service.runWorkerOnce(20, { priorityCohortOnly: true });
+          await service.runWorkerOnce(20, { priorityCohortOnly: true });
+          for (const id of ids) expect(repos.processing.get(id)).toMatchObject({
+            state: transient ? "embedding_pending" : "failed",
+            errorCode: transient ? "transient_provider_error" : "model_configuration",
+            retryAction: transient ? "retry" : "open_settings"
+          });
+        } else {
+          const retries = ["GOOD_A", "GOOD_B", "GOOD_C"].map((content, i) => {
+            const memory = skillMemory(undefined, { id: `shared-${i}`, content });
+            repos.memories.insert(memory);
+            return repos.runtime.enqueueEmbeddingRetry({ targetKind: "skill", targetId: memory.id,
+              vectorField: "vec", sourceText: embeddingTextForMemory(memory), embedRole: "query", now: Date.now() - 1 });
+          });
+          await service.runWorkerOnce(10);
+          for (const retry of retries) {
+            const stored = repos.runtime.getEmbeddingRetry(retry.id)!;
+            expect(stored).toMatchObject({ status: transient ? "pending" : "failed", attempts: 1 });
+            if (transient) expect(stored.nextAttemptAt).toBeGreaterThan(Date.now());
+          }
+        }
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(db.db.prepare("SELECT count(*) AS n FROM memory_vector_entries").get()).toEqual({ n: 0 });
+      });
+    }
+
+    it.each([
+      ["context_length_exceeded", "maximum context length exceeded"],
+      ["20015", "The parameter is invalid."]
+    ])(`${queue} queue preserves valid siblings through the HTTP adapter (%s)`, async (code, message) => {
+      const fetchMock = vi.fn(async (_url, init) => {
+        const { input } = JSON.parse(String(init?.body)) as { input: string[] };
+        const bad = input.some(text => text.includes("BAD_EMBEDDING_ITEM"));
+        return new Response(JSON.stringify(bad ? { code, message } : {
+          data: input.map(() => ({ embedding: [1, 0, 0] }))
+        }), { status: bad ? 400 : 200 });
+      });
+      vi.stubGlobal("fetch", fetchMock);
+      const { db, service } = createTestService({ embedder: createHttpTestEmbedder(),
+        llm: createBatchReflectionLlm([], "Synthetic summary.") });
+      const repos = new Repositories(db.db);
+      const texts = ["GOOD_A", "GOOD_B", "GOOD_C", "BAD_EMBEDDING_ITEM"];
+      if (queue === "fresh") {
+        const session = service.openSession({ namespace: { source: "codex", profileId: "isolation", userId: "test" } });
+        const ids = texts.map((answer, i) => service.completeTurn(`turn-${i}`, {
+          sessionId: session.sessionId, query: "Remember this.", answer
+        }).l1MemoryId);
+        await service.runWorkerOnce(20, { priorityCohortOnly: true });
+        await service.runWorkerOnce(20, { priorityCohortOnly: true });
+        expect(ids.map(id => repos.processing.get(id)?.state)).toEqual([
+          "ready", "ready", "ready", code === "context_length_exceeded" ? "ready_text_only" : "failed"
+        ]);
+      } else {
+        const retries = texts.map((content, i) => {
+          const memory = skillMemory(undefined, { id: `isolated-${i}`, content });
+          repos.memories.insert(memory);
+          return repos.runtime.enqueueEmbeddingRetry({ targetKind: "skill", targetId: memory.id,
+            vectorField: "vec", sourceText: embeddingTextForMemory(memory), embedRole: "query", now: Date.now() - 1 });
+        });
+        await service.runWorkerOnce(10);
+        expect(retries.map(retry => repos.runtime.getEmbeddingRetry(retry.id)?.status)).toEqual([
+          "succeeded", "succeeded", "succeeded", "failed"
+        ]);
+      }
+      expect(db.db.prepare("SELECT count(*) AS n FROM memory_vector_entries").get()).toEqual({ n: 3 });
+      expect(fetchMock).toHaveBeenCalledTimes(5);
+      await service.runWorkerOnce(20, { priorityCohortOnly: true });
+      expect(fetchMock).toHaveBeenCalledTimes(5);
+    });
+  }
+
   it("embeds Skill retrieval metadata instead of the full SKILL.md when short metadata exists", () => {
     const text = embeddingTextForMemory(skillMemory({
       retrievalBlurb: "Use for safe SQLite schema migrations.",
@@ -741,6 +838,12 @@ function worldModelMemory(): MemoryRow {
   };
 }
 
+function createHttpTestEmbedder(): Embedder {
+  return createEmbedder({ ...DEFAULT_MEMMY_CONFIG.embedding, provider: "openai_compatible",
+    model: "custom-alias", endpoint: "https://embedding.test/v1", cache: false, maxRetries: 0 },
+    { usageRecorder: { record() { return "skipped"; } } });
+}
+
 function createFlakyEmbedder(): Embedder {
   let batchCalls = 0;
   return {

From 2184ff42214bf33d6c2e53a5bd3d842ab2255c30 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Fri, 16 Oct 2026 14:07:02 +0800
Subject: [PATCH 64/85] =?UTF-8?q?fix:=20=E7=BB=9F=E4=B8=80=E8=AE=BE?=
 =?UTF-8?q?=E7=BD=AE=E9=A1=B5=E5=87=AD=E6=8D=AE=E6=A0=A1=E9=AA=8C=E5=B9=B6?=
 =?UTF-8?q?=E4=BF=9D=E7=95=99=E8=BF=9E=E7=BB=AD=E5=A4=8D=E7=94=A8=E5=85=B3?=
 =?UTF-8?q?=E7=B3=BB?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../desktop/src/pages/api-key-page.tsx        |   9 +-
 App/frontend/desktop/src/pages/model-page.tsx |  10 +-
 .../src/pages/model-workspace-section.tsx     | 135 ++++++-----
 .../pages/tests/api-key-page-source.test.ts   |   1 -
 ...redential-consistency.interaction.test.tsx | 219 +++++++++++++++++-
 ...del-workspace-section.interaction.test.tsx |   4 +
 .../src/pages/tests/settings-page.test.tsx    |   6 +-
 7 files changed, 311 insertions(+), 73 deletions(-)

diff --git a/App/frontend/desktop/src/pages/api-key-page.tsx b/App/frontend/desktop/src/pages/api-key-page.tsx
index 7d32b640d..646ddd12a 100644
--- a/App/frontend/desktop/src/pages/api-key-page.tsx
+++ b/App/frontend/desktop/src/pages/api-key-page.tsx
@@ -200,6 +200,10 @@ export function ApiKeyPage() {
       if (savedCatalogSignatureRef.current !== saveSignature) {
         const latest = await clients.config.getModelConfig();
         let workspace = createModelWorkspace(latest);
+        // Preserve explicit follow routing when rotating the primary credential.
+        // Independent role assignments must keep their existing endpoint and key.
+        const evolutionFollows = latest.memmyMemory?.evolution?.mode === "follow";
+        const summaryFollowsPrimary = evolutionFollows && latest.memmyMemory?.summary?.mode === "follow";
         const agent = upsertByokPreset(workspace, {
           provider,
           ...(modelFormValues.endpointId ? { endpointId: modelFormValues.endpointId } : {}),
@@ -208,9 +212,12 @@ export function ApiKeyPage() {
           ...(apiKey.trim() ? { apiKey: apiKey.trim() } : {}),
           ...(modelFormValues.apiKeyMasked ? { apiKeyMasked: modelFormValues.apiKeyMasked } : {}),
           model,
-          capabilities: ["agent"]
+          capabilities: ["agent", ...(evolutionFollows ? ["memory_evolution" as const] : []),
+            ...(summaryFollowsPrimary ? ["memory_summary" as const] : [])]
         });
         workspace = assignCatalogPreset(agent.workspace, "byok", "agent", agent.presetId);
+        if (evolutionFollows) workspace = assignCatalogPreset(workspace, "byok", "memory_evolution", agent.presetId);
+        if (summaryFollowsPrimary) workspace = assignCatalogPreset(workspace, "byok", "memory_summary", agent.presetId);
         const savedEmbeddingIdentity = savedEndpointIdentitiesRef.current.embedding;
         if (embeddingMode === "custom") {
           const embedding = upsertByokPreset(workspace, {
diff --git a/App/frontend/desktop/src/pages/model-page.tsx b/App/frontend/desktop/src/pages/model-page.tsx
index 2d4caa53b..a6e0ec67e 100644
--- a/App/frontend/desktop/src/pages/model-page.tsx
+++ b/App/frontend/desktop/src/pages/model-page.tsx
@@ -1,6 +1,6 @@
 /** Model page module. */
 import { bindSavedValidation, chatProtocol, endpointCredentialSignature } from "./model-credentials.js";
-import { useState, type ReactNode } from "react";
+import { useRef, useState, type ReactNode } from "react";
 import { Brain, Check, CheckCircle2, ChevronLeft, Cog, Eye, EyeOff, Lightbulb, Loader2, XCircle } from "lucide-react";
 import { useApiClients } from "../app/providers.js";
 import { useAnalytics } from "../analytics/use-analytics.js";
@@ -109,6 +109,7 @@ export function ModelPage() {
   ));
   const [savePending, setSavePending] = useState(false);
   const [saveFeedback, setSaveFeedback] = useState<{ text: string; tone: "error" | "success" } | null>(null);
+  const credentialRevision = useRef(0);
   const skillValues = createModelFormValues(skill, primaryModel);
   const evolutionModel = modelFormValuesAsPrimary(skillValues);
   const memoryValues = createModelFormValues(mem, evolutionModel);
@@ -116,11 +117,13 @@ export function ModelPage() {
 
   /** Handles patch mem. */
   function patchMem(patch: Partial<ModelConfig>) {
+    if (!patch.validation) credentialRevision.current += 1;
     setMem((current) => patchModelConfig(current, patch));
   }
 
   /** Handles patch skill. */
   function patchSkill(patch: Partial<ModelConfig>) {
+    if (!patch.validation) credentialRevision.current += 1;
     setSkill((current) => patchModelConfig(current, patch));
   }
 
@@ -132,10 +135,13 @@ export function ModelPage() {
     secretTarget: "memory" | "skill"
   ) {
     const values = createModelFormValues(config, inheritedModel);
+    const revision = credentialRevision.current;
     testModelConnection({
       configClient: clients?.config,
       values,
-      setValidation: (validation) => patch({ validation }),
+      setValidation: (validation) => {
+        if (credentialRevision.current === revision) patch({ validation });
+      },
       secretTarget,
       messages: createTestModelConnectionMessages(t)
     });
diff --git a/App/frontend/desktop/src/pages/model-workspace-section.tsx b/App/frontend/desktop/src/pages/model-workspace-section.tsx
index f6a81a738..964245ee2 100644
--- a/App/frontend/desktop/src/pages/model-workspace-section.tsx
+++ b/App/frontend/desktop/src/pages/model-workspace-section.tsx
@@ -4,7 +4,7 @@ import {
   MODEL_NAME_MAX_LENGTH,
   type ModelEndpointProtocol
 } from "@memmy/local-api-contracts";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState, type Dispatch, type SetStateAction } from "react";
 import type { ConfigClient, ModelProviderConfig } from "../api/config-client.js";
 import { Button } from "../components/button.js";
 import { ConfirmDialog } from "../components/confirm-dialog.js";
@@ -52,6 +52,8 @@ import {
   type StoredConnectionTestStatus
 } from "./model-workspace-connection-test-state.js";
 
+import { endpointCredentialSignature, resolveModelCredentials } from "./model-credentials.js";
+
 type TestStatus = "idle" | "testing" | "success" | "error";
 export type ModelKind = "text" | "embedding" | "asr" | "image";
 
@@ -113,8 +115,17 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
   const [workspace, setWorkspace] = useState(() => createModelWorkspace(props.seedConfig));
   const [modelsExpanded, setModelsExpanded] = useState(true);
   const [taskPickerOpen, setTaskPickerOpen] = useState(false);
-  const [editor, setEditor] = useState<ConnectionEditorState | null>(null);
+  const [editor, setEditorState] = useState<ConnectionEditorState | null>(null);
+  const editorRevision = useRef(0);
+  const editorRequest = useRef(0);
   const [editorTest, setEditorTest] = useState<ConnectionTestState>({ status: "idle", message: null });
+  // Every edit (including closing/reopening) invalidates pending responses, even
+  // when the user later restores the same field values.
+  const setEditor: Dispatch<SetStateAction<ConnectionEditorState | null>> = useCallback((update) => {
+    editorRevision.current += 1;
+    setEditorState(update);
+    setEditorTest({ status: "idle", message: null });
+  }, []);
   const [showEditorApiKey, setShowEditorApiKey] = useState(false);
   const [deleteTarget, setDeleteTarget] = useState<ModelConnection | null>(null);
   const [formError, setFormError] = useState<string | null>(null);
@@ -272,9 +283,6 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
     const provider = protocolFromConnection(connection.provider);
     const savedTest = connectionTestState(connection, testStates);
     setFormError(null);
-    setEditorTest(savedTest
-      ? { status: savedTest, message: connectionTestMessage(savedTest, t) }
-      : { status: "idle", message: null });
     setShowEditorApiKey(false);
     setEditor({
       connectionId: connection.id,
@@ -291,6 +299,9 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       addingModel: false,
       editingModelIndex: null
     });
+    setEditorTest(savedTest
+      ? { status: savedTest, message: connectionTestMessage(savedTest, t) }
+      : { status: "idle", message: null });
   }
 
   function resolveEditorModels() {
@@ -333,24 +344,15 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       setFormError(resolved.error);
       return;
     }
-    const existing = editor.connectionId
-      ? space.connections.find((connection) => connection.id === editor.connectionId)
-      : undefined;
-    const providerChanged = Boolean(
-      existing && protocolFromConnection(existing.provider) !== editor.provider
-    );
-    const capabilities = resolved.models.flatMap((model) => model.capabilities);
+    const credentials = editorCredentials;
+    if (!canSaveConnection || !credentials) return;
     const result = upsertModelConnection(workspace, props.mode, {
       id: editor.connectionId ?? undefined,
-      provider: editor.provider,
-      endpoint: editor.endpoint,
-      protocol: editorProtocolForCapabilities(
-        editor.provider,
-        capabilities,
-        providerChanged ? undefined : existing?.protocol
-      ),
-      apiKey: editor.apiKey || undefined,
-      apiKeyMasked: providerChanged ? undefined : existing?.apiKeyMasked,
+      provider: credentials.provider,
+      endpoint: credentials.endpoint,
+      protocol: credentials.protocol,
+      apiKey: credentials.apiKey || undefined,
+      apiKeyMasked: credentials.apiKeyMasked || undefined,
       models: resolved.models.map((model) => model.name),
       modelEntries: resolved.models.map((model) => ({
         ...(model.presetId ? { presetId: model.presetId } : {}),
@@ -551,39 +553,31 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
       setEditorTest({ status: "error", message: t("settings.modelWorkspace.testNoModel") });
       return;
     }
-    const existing = editor.connectionId
-      ? space.connections.find((connection) => connection.id === editor.connectionId)
-      : undefined;
-    const providerChanged = Boolean(
-      existing && protocolFromConnection(existing.provider) !== editor.provider
-    );
-    if (!editor.apiKey.trim() && (!existing?.apiKeyMasked || providerChanged)) {
-      setEditorTest({ status: "error", message: t("settings.modelWorkspace.testKeyRequired") });
+    const credentials = editorCredentials;
+    if (!credentials || (!credentials.apiKey && !credentials.hasExistingApiKey)) {
+      setEditorTest({ status: "error", message: t(credentials?.requiresApiKey
+        ? "apiKey.credentialsChanged" : "settings.modelWorkspace.testKeyRequired") });
       return;
     }
+    const revision = editorRevision.current;
+    const request = ++editorRequest.current;
+    const isCurrent = () => revision === editorRevision.current && request === editorRequest.current;
     setEditorTest({ status: "testing", message: t("settings.modelWorkspace.testing") });
     try {
       const result = props.configClient
         ? await props.configClient.testModelConfig({
-          provider: fromProtocol(editor.provider),
-          endpointId: existing?.endpointId ?? editor.connectionId ?? "connection-test-new",
-          protocol: editorProtocolForCapabilities(
-            editor.provider,
-            selectedModel.capabilities,
-            providerChanged ? undefined : existing?.protocol
-          ),
-          endpoint: editor.endpoint,
-            model: selectedModel.name,
-            apiKey: editor.apiKey,
-            apiKeyMasked: providerChanged ? "" : existing?.apiKeyMasked ?? "",
-            configured: true
-          }, testCapability(selectedModel.capabilities[0]!), testSecretTarget(selectedModel.capabilities[0]!))
+          ...credentials,
+          apiKeyMasked: credentials.apiKeyMasked ?? "",
+          configured: true
+        }, testCapability(selectedModel.capabilities[0]!), testSecretTarget(selectedModel.capabilities[0]!))
         : await simulateConnectionTest();
+      if (!isCurrent()) return;
       setEditorTest({
         status: result.ok ? "success" : "error",
         message: result.ok ? t("settings.modelWorkspace.testSuccess") : t("settings.modelWorkspace.testFailed")
       });
     } catch {
+      if (!isCurrent()) return;
       setEditorTest({ status: "error", message: t("settings.modelWorkspace.testFailed") });
     }
   }
@@ -683,21 +677,36 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
   const editorExistingConnection = editor?.connectionId
     ? space.connections.find((connection) => connection.id === editor.connectionId)
     : undefined;
-  const editorOriginalProvider = editorExistingConnection
-    ? protocolFromConnection(editorExistingConnection.provider)
-    : null;
-  const editorProviderChanged = Boolean(
-    editor && editorOriginalProvider && editor.provider !== editorOriginalProvider
-  );
-  const editorHasUsableKey = Boolean(
-    editor?.apiKey.trim()
-    || (editorExistingConnection?.apiKeyMasked && !editorProviderChanged)
-  );
+  const editorModels = resolveEditorModels().models;
+  const editorSelectedModel = editorModels.find((model) => model.capabilities.includes("chat")) ?? editorModels[0];
+  const editorProviderChanged = Boolean(editorExistingConnection && editor
+    && protocolFromConnection(editorExistingConnection.provider) !== editor.provider);
+  const editorCredentials = editor ? resolveModelCredentials({
+    provider: fromProtocol(editor.provider),
+    protocol: editorProtocolForCapabilities(editor.provider,
+      editorModels.flatMap((model) => model.capabilities),
+      editorProviderChanged ? undefined : editorExistingConnection?.protocol),
+    endpoint: editor.endpoint,
+    model: editorSelectedModel?.name ?? "",
+    apiKey: editor.apiKey,
+    apiKeyMasked: editorExistingConnection?.apiKeyMasked ?? ""
+  }, editorExistingConnection ? {
+    endpointId: editorExistingConnection.endpointId,
+    credentialSignature: endpointCredentialSignature(editorExistingConnection.provider,
+      editorExistingConnection.protocol, editorExistingConnection.endpoint, "", editorExistingConnection.apiKeyMasked)
+  } : null) : null;
+  const editorHasUsableKey = Boolean(editorCredentials?.apiKey || editorCredentials?.hasExistingApiKey);
+  const editorDetailsChanged = Boolean(editorExistingConnection && editorCredentials && (
+    editorCredentials.apiKey || !editorCredentials.hasExistingApiKey
+    || JSON.stringify(editorModels.map((model) => [model.name, [...model.capabilities].sort()])) !==
+       JSON.stringify(editorExistingConnection.modelEntries.map((model) => [model.model,
+         normalizeEditorCapabilities(model.capabilities.map(fromCatalogCapability)).sort()]))
+  ));
   const canSaveConnection = Boolean(
-    editor
-    && editor.endpoint.trim()
-    && editorHasUsableKey
-    && (editor.models.length > 0 || (editor.addingModel && editor.modelDraft.trim()))
+    editor && editorCredentials?.endpoint && editorHasUsableKey
+    && editorModels.length && !resolveEditorModels().error
+    && editorTest.status !== "error"
+    && (!editorDetailsChanged || editorTest.status === "success")
   );
   const selectedTaskModelsText = taskCandidates.length > 0
     ? taskCandidates.map((candidate) => candidate.model).join("、")
@@ -1096,7 +1105,7 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
             placeholder={DEFAULT_ENDPOINTS[editor.provider]}
           />
           <PasswordConfigField
-            label={editor.connectionId && !editorProviderChanged
+            label={editorCredentials?.hasExistingApiKey
               ? t("settings.modelWorkspace.replaceKey")
               : t("apiKey.key")}
             value={editor.apiKey}
@@ -1104,15 +1113,19 @@ export function ModelWorkspaceSection(props: ModelWorkspaceSectionProps) {
               setEditor((current) => current ? { ...current, apiKey: value } : current);
               setEditorTest({ status: "idle", message: null });
             }}
-            maskedValue={editor.connectionId && !editorProviderChanged
-              ? editorExistingConnection?.apiKeyMasked
-              : undefined}
-            placeholder={editor.connectionId && !editorProviderChanged
+            maskedValue={editorCredentials?.apiKeyMasked}
+            placeholder={editorCredentials?.hasExistingApiKey
               ? t("settings.modelWorkspace.replaceKeyPlaceholder")
               : "sk-..."}
             showPassword={showEditorApiKey}
             onTogglePassword={() => setShowEditorApiKey((show) => !show)}
           />
+          {editorCredentials?.requiresApiKey && (
+            <p className="text-xs text-status-error" role="alert">{t("apiKey.credentialsChanged")}</p>
+          )}
+          {editorDetailsChanged && editorHasUsableKey && editorTest.status === "idle" && (
+            <p className="text-xs text-text-ink/65" role="status">{t("apiKey.testStale")}</p>
+          )}
           <div className="grid gap-1.5">
             <div className="flex items-center justify-between gap-3">
               <div className="text-xs text-text-ink/65">
diff --git a/App/frontend/desktop/src/pages/tests/api-key-page-source.test.ts b/App/frontend/desktop/src/pages/tests/api-key-page-source.test.ts
index 13adc501b..52eab39bc 100644
--- a/App/frontend/desktop/src/pages/tests/api-key-page-source.test.ts
+++ b/App/frontend/desktop/src/pages/tests/api-key-page-source.test.ts
@@ -46,7 +46,6 @@ describe("ApiKeyPage source", () => {
     expect(source).not.toContain('t("apiKey.dailyLimit")');
     expect(source).toContain('dispatch(appActions.navigate("/api-key-models"))');
     expect(source).toContain("clients.config.getModelConfig()");
-    expect(source).toContain('capabilities: ["agent"]');
     expect(source).toContain('protocol: "openai-embeddings"');
     expect(source).toContain('capabilities: ["embedding"]');
     expect(source).toContain('assignCatalogPreset(agent.workspace, "byok", "agent"');
diff --git a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
index 39619a7ad..ec8264535 100644
--- a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
@@ -15,6 +15,7 @@ import { createInitialAppState, type AppState } from "../../state/app-reducer.js
 import { assignedCatalogEndpointId, assignCatalogPreset, createModelWorkspace, modelConfigInput, upsertByokPreset } from "../../state/model-workspace.js";
 import { ApiKeyPage } from "../api-key-page.js";
 import { ApiKeyOptionalPage } from "../api-key-optional-page.js";
+import { ModelWorkspaceSection } from "../model-workspace-section.js";
 import { ModelPage } from "../model-page.js";
 
 const mocks = vi.hoisted(() => ({ clients: null as AppClients | null, state: null as AppState | null, dispatch: vi.fn() }));
@@ -28,9 +29,10 @@ vi.mock("../../i18n/use-translation.js", () => ({ useTranslation: () => ({ t: (k
 // Only transport and the external model provider are replaced; no real keys or network calls.
 async function createServer(directory: string, independent = true) {
   const writer = createMemmyConfigWriter({ configPath: join(directory, "config.yaml") });
-  const probe = vi.fn(async (_input: ModelConfigTestInput & { apiKey: string }) => ({
-    ok: true, message: "ok", checkedAt: "2026-10-16T00:00:00.000Z"
-  }));
+  const probe = vi.fn(async (input: ModelConfigTestInput & { apiKey: string }) => {
+    void input;
+    return { ok: true, message: "ok", checkedAt: "2026-10-16T00:00:00.000Z" };
+  });
   const service = createAppConfigService({
     bootstrapRepository: {} as CreateAppConfigServiceOptions["bootstrapRepository"],
     memmyConfigWriter: writer,
@@ -73,8 +75,9 @@ async function createServer(directory: string, independent = true) {
   }).workspace;
   await client.saveModelCatalog(modelConfigInput(workspace));
   write.mockClear();
+  const saveCatalog = vi.spyOn(client, "saveModelCatalog");
   return {
-    client, probe, write, writer,
+    client, probe, write, writer, saveCatalog,
     read: () => client.getModelConfig(),
     async key(capability: ModelCapability) {
       const config = await client.getModelConfig();
@@ -114,6 +117,9 @@ describe("BYOK displayed, tested and saved credentials", () => {
     mocks.clients = { config: server.client } as AppClients;
   });
   afterEach(async () => {
+    await act(async () => {
+      await Promise.allSettled(server.saveCatalog.mock.results.map((result) => result.value));
+    });
     act(() => root.unmount());
     document.body.replaceChildren();
     vi.unstubAllGlobals();
@@ -348,4 +354,209 @@ describe("BYOK displayed, tested and saved credentials", () => {
     expect((await server.read()).catalog!.providers.flatMap((provider) => provider.endpoints)).toHaveLength(endpointsAfterCreate);
   });
 
+  async function openSettings(role: ModelCapability) {
+    const config = await server.read();
+    const workspace = createModelWorkspace(config);
+    const id = assignedCatalogEndpointId(workspace, "byok", role);
+    const index = workspace.spaces.byok.connections.findIndex((connection) => connection.endpointId === id);
+    await render(<ModelWorkspaceSection mode="byok" seedConfig={config} configClient={server.client} />);
+    await click(container.querySelectorAll<HTMLButtonElement>('[aria-label="settings.modelWorkspace.editConnection"]')[index]!);
+  }
+  function settingsSave() { return document.querySelector<HTMLButtonElement>('[aria-label="common.save"]')!; }
+  function settingsTest() { return [...document.querySelectorAll<HTMLButtonElement>("button")].find((button) =>
+    button.textContent === "settings.modelWorkspace.test" || button.textContent === "apiKey.testSuccess" || button.textContent === "apiKey.testRetry")!; }
+  function modalField(label: string) {
+    return [...document.querySelectorAll("label")].find((node) => node.textContent === label)!.parentElement!.querySelector("input")!;
+  }
+
+  it.each(scenarios.slice(0, 4))("settings $role: URL edit blocks the saved key; retest and save preserve other connections", async (scenario) => {
+    const before = await server.read();
+    const oldId = assignedCatalogEndpointId(createModelWorkspace(before), "byok", scenario.role)!;
+    const others = before.catalog!.providers.flatMap((p) => p.endpoints).filter((e) => e.endpointId !== oldId);
+    await openSettings(scenario.role);
+    const beforeTest1 = server.probe.mock.calls.length;
+    await click(settingsTest());
+    await vi.waitFor(() => expect(server.probe.mock.calls.length).toBeGreaterThan(beforeTest1));
+    await vi.waitFor(() => expect(document.body.textContent).toContain("settings.modelWorkspace.testSuccess"));
+    expect(server.probe.mock.calls.at(-1)![0].apiKey).toBe(scenario.expected);
+    await change(modalField("apiKey.endpoint"), "https://changed.example/v2");
+    expect(document.body.textContent).toContain("apiKey.credentialsChanged");
+    expect(modalField("apiKey.key").placeholder).toBe("sk-...");
+    expect(settingsSave().disabled).toBe(true);
+    const calls = server.probe.mock.calls.length;
+    await click(settingsTest());
+    await click(settingsSave());
+    expect(server.probe).toHaveBeenCalledTimes(calls);
+    expect(server.write).not.toHaveBeenCalled();
+    await change(modalField("apiKey.key"), `  ${scenario.expected}  `);
+    expect(settingsSave().disabled).toBe(true);
+    const beforeTest2 = server.probe.mock.calls.length;
+    await click(settingsTest());
+    await vi.waitFor(() => expect(server.probe.mock.calls.length).toBeGreaterThan(beforeTest2));
+    await vi.waitFor(() => expect(document.body.textContent).toContain("settings.modelWorkspace.testSuccess"));
+    expect(server.probe.mock.calls.at(-1)![0]).toMatchObject({ apiKey: scenario.expected, apiBase: "https://changed.example/v2" });
+    expect(settingsSave().disabled).toBe(false);
+    await click(settingsSave());
+    await vi.waitFor(() => expect(server.write).toHaveBeenCalled());
+    await vi.waitFor(async () => {
+      const config = await server.read();
+      expect(config.catalog!.providers.flatMap((p) => p.endpoints).find((e) => e.endpointId === oldId)?.apiBase).toBe("https://changed.example/v2");
+    });
+    expect(await server.key(scenario.role)).toBe(scenario.expected);
+    const saved = await server.read();
+    expect(saved.catalog!.providers.flatMap((p) => p.endpoints).filter((e) => e.endpointId !== oldId)).toEqual(others);
+    await render(null);
+    await openSettings(scenario.role);
+    expect(modalField("settings.modelWorkspace.replaceKey").value).toBe("");
+    const beforeTest3 = server.probe.mock.calls.length;
+    await click(settingsTest());
+    await vi.waitFor(() => expect(server.probe.mock.calls.length).toBeGreaterThan(beforeTest3));
+    await vi.waitFor(() => expect(document.body.textContent).toContain("settings.modelWorkspace.testSuccess"));
+    expect(server.probe.mock.calls.at(-1)![0]).toMatchObject({ apiKey: scenario.expected, apiBase: "https://changed.example/v2" });
+  });
+
+  it("settings: normalized URL retains the key; a model-only edit requires retesting", async () => {
+    await openSettings("agent");
+    await click(settingsTest());
+    await change(modalField("apiKey.endpoint"), "  https://provider.example/v1///  ");
+    expect(modalField("settings.modelWorkspace.replaceKey").placeholder).toContain("1111");
+    await click(document.querySelector<HTMLButtonElement>('[aria-label="settings.modelWorkspace.editModel"]')!);
+    await change(modalField("apiKey.model"), "changed-model");
+    expect(settingsSave().disabled).toBe(true);
+    expect(document.body.textContent).toContain("apiKey.testStale");
+    const beforeTest4 = server.probe.mock.calls.length;
+    await click(settingsTest());
+    await vi.waitFor(() => expect(server.probe.mock.calls.length).toBeGreaterThan(beforeTest4));
+    await vi.waitFor(() => expect(document.body.textContent).toContain("settings.modelWorkspace.testSuccess"));
+    expect(server.probe.mock.calls.at(-1)![0]).toMatchObject({ apiKey: "sk-personal-1111", modelId: "changed-model", apiBase: "https://provider.example/v1" });
+    await click(settingsSave());
+    await vi.waitFor(() => expect(server.write).toHaveBeenCalled());
+    expect(await server.key("agent")).toBe("sk-personal-1111");
+  });
+
+  it.each(["address", "key", "model", "close"])("settings: a late success after %s changes cannot validate the editor", async (edit) => {
+    await openSettings("agent");
+    let finish!: (result: Awaited<ReturnType<typeof server.probe>>) => void;
+    server.probe.mockImplementationOnce(() => new Promise((resolve) => { finish = resolve; }));
+    await click(settingsTest());
+    await vi.waitFor(() => expect(finish).toBeTypeOf("function"));
+    if (edit === "address") await change(modalField("apiKey.endpoint"), "https://changed.example/v2");
+    if (edit === "key") await change(modalField("settings.modelWorkspace.replaceKey"), "sk-new-1111");
+    if (edit === "model") {
+      await click(document.querySelector<HTMLButtonElement>('[aria-label="settings.modelWorkspace.editModel"]')!);
+      await change(modalField("apiKey.model"), "changed-model");
+    }
+    if (edit === "close") {
+      await click(document.querySelector<HTMLButtonElement>('[aria-label="common.close"]')!);
+      await openSettings("agent");
+    }
+    await act(async () => finish({ ok: true, message: "ok", checkedAt: "2026-10-16T00:00:00.000Z" }));
+    expect(document.body.textContent).not.toContain("settings.modelWorkspace.testSuccess");
+    if (edit !== "close") expect(settingsSave().disabled).toBe(true);
+    expect(server.write).not.toHaveBeenCalled();
+  });
+
+  it.each(["model", "key", "reuse"])("roles: a late success after %s changes cannot validate the current credential", async (edit) => {
+    let finish!: (result: Awaited<ReturnType<typeof server.probe>>) => void;
+    server.probe.mockImplementationOnce(() => new Promise((resolve) => { finish = resolve; }));
+    await render(<ModelPage />);
+    await click(test(1));
+    await vi.waitFor(() => expect(finish).toBeTypeOf("function"));
+    if (edit === "model") await change(field("apiKey.model", 1), "changed-model");
+    if (edit === "key") await change(field("API Key", 1), "sk-new-team-1111");
+    if (edit === "reuse") {
+      const checkbox = () => container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')[1]!;
+      await click(checkbox());
+      await click(checkbox());
+    }
+    await act(async () => finish({ ok: true, message: "ok", checkedAt: "2026-10-16T00:00:00.000Z" }));
+    expect(test(1).textContent).not.toBe("apiKey.testSuccess");
+    expect(next().disabled).toBe(true);
+    expect(server.write).not.toHaveBeenCalled();
+  });
+
+  it("follow chain: primary rotation flows through evolution and summary, while a fixed role keeps its own key", async () => {
+    await render(<ModelPage />);
+    await click(container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')[0]!);
+    await click(container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')[1]!);
+    await click(next());
+    await vi.waitFor(() => expect(mocks.dispatch).toHaveBeenCalledWith(expect.objectContaining({ type: "navigation/changed" })));
+    expect(await server.key("memory_evolution")).toBe("sk-personal-1111");
+    expect(await server.key("memory_summary")).toBe("sk-personal-1111");
+    await render(null);
+    mocks.state!.modelConfig = await server.read();
+    mocks.dispatch.mockClear();
+    await render(<ApiKeyPage />);
+    await change(field("apiKey.key"), "sk-rotated-9999");
+    await testAndSave(scenarios[0]!);
+    await render(null);
+    mocks.state!.modelConfig = await server.read();
+    await render(<ModelPage />);
+    const boxes = () => container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]');
+    expect([...boxes()].map((b) => b.getAttribute("aria-checked"))).toEqual(["true", "true"]);
+    await click(boxes()[1]!); // Copy the new primary into an independent evolution configuration.
+    expect(field("API Key").placeholder).toContain("9999");
+    await change(field("API Key"), "sk-chain-team-7777");
+    expect(next().disabled).toBe(true);
+    await testAndSave({ ...scenarios[4]!, index: 0, fieldIndex: 0 });
+    expect(await server.key("agent")).toBe("sk-rotated-9999");
+    expect(await server.key("memory_evolution")).toBe("sk-chain-team-7777");
+    expect(await server.key("memory_summary")).toBe("sk-chain-team-7777");
+    await render(null);
+    mocks.state!.modelConfig = await server.read();
+    await render(<ModelPage />);
+    expect([...boxes()].map((b) => b.getAttribute("aria-checked"))).toEqual(["true", "false"]);
+    await click(boxes()[0]!);
+    expect(field("API Key").placeholder).toContain("7777");
+    expect((await testAndSave(scenarios[5]!)).apiKey).toBe("sk-chain-team-7777");
+    expect(await server.key("agent")).toBe("sk-rotated-9999");
+  });
+
+  it("settings: changing provider cannot reuse a masked key", async () => {
+    await openSettings("agent");
+    await click(document.querySelector<HTMLButtonElement>('.model-connection-modal [role="combobox"]')!);
+    await click([...document.querySelectorAll<HTMLButtonElement>('[role="option"]')].find((b) => b.getAttribute("aria-selected") === "false")!);
+    await change(modalField("apiKey.endpoint"), "https://provider.example/v1");
+    expect(modalField("apiKey.key").placeholder).toBe("sk-...");
+    await click(settingsTest());
+    expect(server.probe).not.toHaveBeenCalled();
+    expect(settingsSave().disabled).toBe(true);
+  });
+
+  it("shared endpoint: rotating the primary leaves fixed evolution and summary on their old saved key", async () => {
+    const before = await server.read();
+    const oldId = assignedCatalogEndpointId(createModelWorkspace(before), "byok", "agent")!;
+    let workspace = createModelWorkspace(before);
+    const shared = upsertByokPreset(workspace, { provider: before.provider, endpointId: oldId,
+      endpoint: before.endpoint, protocol: "openai-chat-completions", model: "fixed-role-model",
+      apiKeyMasked: before.apiKeyMasked, capabilities: ["memory_evolution", "memory_summary"] });
+    workspace = assignCatalogPreset(shared.workspace, "byok", "memory_evolution", shared.presetId);
+    workspace = assignCatalogPreset(workspace, "byok", "memory_summary", shared.presetId);
+    await server.client.saveModelCatalog(modelConfigInput(workspace));
+    mocks.state!.modelConfig = await server.read();
+    await render(<ApiKeyPage />);
+    await change(field("apiKey.key"), "sk-new-primary-8888");
+    await testAndSave(scenarios[0]!);
+    expect(await server.key("agent")).toBe("sk-new-primary-8888");
+    expect(await server.key("memory_evolution")).toBe("sk-personal-1111");
+    expect(await server.key("memory_summary")).toBe("sk-personal-1111");
+    await render(null);
+    mocks.state!.modelConfig = await server.read();
+    await render(<ModelPage />);
+    await click(test(0));
+    await vi.waitFor(() => expect(server.probe.mock.calls.at(-1)![0].apiKey).toBe("sk-personal-1111"));
+    expect(assignedCatalogEndpointId(createModelWorkspace(await server.read()), "byok", "memory_evolution")).toBe(oldId);
+  });
+
+  it("settings: protocol-only change on the same provider and address requires a key", async () => {
+    await openSettings("agent");
+    await click(document.querySelector<HTMLButtonElement>('[aria-label="settings.modelWorkspace.editModel"]')!);
+    await click(document.querySelector<HTMLButtonElement>('.model-capability-select [role="combobox"], button.model-capability-select')!);
+    await click([...document.querySelectorAll<HTMLButtonElement>('[role="option"]')].find((b) => b.textContent?.includes("capability.embedding"))!);
+    expect(modalField("apiKey.key").placeholder).toBe("sk-...");
+    await click(settingsTest());
+    expect(server.probe).not.toHaveBeenCalled();
+    expect(settingsSave().disabled).toBe(true);
+  });
+
 });
diff --git a/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx
index d201bb161..f6fa13e09 100644
--- a/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/model-workspace-section.interaction.test.tsx
@@ -121,6 +121,10 @@ describe("ModelWorkspaceSection BYOK connection deletion", () => {
     expect(container.querySelector(".model-capability-select")?.textContent).toContain("Embedding");
 
     act(() => container.querySelector<HTMLButtonElement>('button[aria-label="添加模型"]')!.click());
+    expect(container.querySelector<HTMLButtonElement>('button[aria-label="保存"]')!.disabled).toBe(true);
+    await act(async () => {
+      [...container.querySelectorAll<HTMLButtonElement>("button")].find((button) => button.textContent === "测试")!.click();
+    });
     act(() => container.querySelector<HTMLButtonElement>('button[aria-label="保存"]')!.click());
 
     await vi.waitFor(() => expect(configClient.saveModelCatalog).toHaveBeenCalledTimes(1));
diff --git a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
index efd7be2da..afea23194 100644
--- a/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/settings-page.test.tsx
@@ -904,12 +904,10 @@ describe("SettingsPageView", () => {
   });
 
   it("模型工作区连接编辑展示已保存脱敏 key，且保存不回传脱敏值", () => {
-    const workspaceSource = readFileSync(fileURLToPath(new URL("../model-workspace-section.tsx", import.meta.url)), "utf8");
     const fieldsSource = readFileSync(fileURLToPath(new URL("../api-key-form-fields.tsx", import.meta.url)), "utf8");
 
-    expect(workspaceSource).toContain("maskedValue={editor.connectionId && !editorProviderChanged");
-    expect(workspaceSource).toContain("apiKey: editor.apiKey || undefined");
-    expect(workspaceSource).toContain("apiKeyMasked:");
+    // Credential display/test/save behavior is covered with the real catalog
+    // writer in byok-credential-consistency.interaction.test.tsx.
     expect(fieldsSource).toContain("const placeholder = !props.value.trim() && props.maskedValue ? props.maskedValue : props.placeholder;");
     expect(fieldsSource).toContain("placeholder={placeholder}");
     expect(fieldsSource).not.toContain("const showSavedSecret = !props.value.trim() && Boolean(props.maskedValue)");

From 356a779f1a73330127cf2bd7f2ae2fc004c958ad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Fri, 16 Oct 2026 16:24:17 +0800
Subject: [PATCH 65/85] fix: find task spans by their own ownership links

---
 Memory/src/service/memory-service.ts          |  14 +--
 Memory/src/storage/repositories.ts            |  16 +++
 .../service/evolution/span-big-turn.test.ts   | 119 ++++++++++++++++++
 3 files changed, 138 insertions(+), 11 deletions(-)

diff --git a/Memory/src/service/memory-service.ts b/Memory/src/service/memory-service.ts
index 273557f9a..7e389f70e 100644
--- a/Memory/src/service/memory-service.ts
+++ b/Memory/src/service/memory-service.ts
@@ -2009,18 +2009,10 @@ export class MemoryService {
     const deletedMemoryIds: string[] = [];
 
     this.repos.transaction(() => {
-      const spanIds = new Set<string>();
-      for (const memoryId of episode.l1MemoryIds) {
-        const memory = this.repos.memories.get(memoryId);
-        const trace = memory?.properties.internal_info.trace;
-        if (!isRecord(trace) || !Array.isArray(trace.span_ids)) continue;
-        for (const spanId of trace.span_ids) {
-          if (typeof spanId === "string") spanIds.add(spanId);
-        }
-      }
+      const spanIds = new Set(this.repos.memories.listTaskSpanIds(
+        episode.userId, episode.id, episode.l1MemoryIds
+      ));
       for (const spanId of spanIds) {
-        const span = this.repos.memories.get(spanId);
-        if (!span || kindFromMemory(span) !== "span") continue;
         this.deleteMemory(spanId, request);
         deletedMemoryIds.push(spanId);
       }
diff --git a/Memory/src/storage/repositories.ts b/Memory/src/storage/repositories.ts
index dee1bb81f..c973256cf 100644
--- a/Memory/src/storage/repositories.ts
+++ b/Memory/src/storage/repositories.ts
@@ -694,6 +694,22 @@ export class MemoryRepository {
     return row ? this.hydrate(memoryFromSql(row)) : undefined;
   }
 
+  listTaskSpanIds(userId: string, episodeId: string, sourceTraceIds: string[]): string[] {
+    // Parent traces may already be soft-deleted, and their span_ids only describe
+    // the latest split. Use the spans' own ownership links for task deletion.
+    const rows = this.db.prepare(
+      `SELECT id FROM memories
+       WHERE user_id = ? AND memory_layer = 'L1'
+         AND deleted_at IS NULL AND status != 'deleted'
+         AND json_extract(properties_json, '$.internal_info.memory_kind') = 'span'
+         AND json_extract(properties_json, '$.internal_info.span.episode_id') = ?
+         AND json_extract(properties_json, '$.internal_info.span.source_trace_id')
+           IN (SELECT value FROM json_each(?))
+       ORDER BY id`
+    ).all(userId, episodeId, JSON.stringify(sourceTraceIds)) as Array<{ id: string }>;
+    return rows.map((row) => row.id);
+  }
+
   getByKey(memoryLayer: MemoryLayer, key: string): MemoryRow | undefined {
     const row = this.db
       .prepare(
diff --git a/Memory/tests/service/evolution/span-big-turn.test.ts b/Memory/tests/service/evolution/span-big-turn.test.ts
index 7b59a5a28..270669764 100644
--- a/Memory/tests/service/evolution/span-big-turn.test.ts
+++ b/Memory/tests/service/evolution/span-big-turn.test.ts
@@ -333,6 +333,125 @@ describe("MemoryService / evolution / span big turn", () => {
     db.close();
   });
 
+  it.each([
+    { name: "after the parent trace was deleted", deleteParent: true, splitAgain: false },
+    { name: "after a second successful split with different ranges", deleteParent: false, splitAgain: true },
+    { name: "after both re-splitting and deleting the parent", deleteParent: true, splitAgain: true }
+  ])("deletes all task spans $name", async ({ deleteParent, splitAgain }) => {
+    const calls: Array<{ messages: LlmMessage[]; options: LlmCompletionOptions }> = [];
+    const firstSplit = {
+      spans: [
+        { start: 0, end: 3, spanGoal: "分析构建问题", summary: "检查构建日志" },
+        { start: 4, end: 7, spanGoal: "修改构建配置", summary: "修复依赖冲突" },
+        { start: 8, end: 10, spanGoal: "验证构建结果", summary: "执行测试验证" }
+      ]
+    };
+    const secondSplit = {
+      spans: [
+        { start: 0, end: 6, spanGoal: "分析并修改构建配置", summary: "定位并修复问题" },
+        { start: 7, end: 10, spanGoal: "重新验证构建结果", summary: "完成测试验证" }
+      ]
+    };
+    const llm = createSpanBigTurnLlm(calls, [firstSplit, secondSplit, firstSplit]);
+    const config = {
+      ...DEFAULT_MEMMY_CONFIG,
+      algorithm: {
+        ...DEFAULT_MEMMY_CONFIG.algorithm,
+        retrieval: {
+          ...DEFAULT_MEMMY_CONFIG.algorithm.retrieval,
+          relativeThresholdFloor: 0,
+          smartSeed: false,
+          llmFilterEnabled: false
+        }
+      }
+    };
+    const { db, service } = createTestService({ config, llm, skillLlm: llm });
+    const namespace = { source: "codex", profileId: "cascade", userId: "cascade-review" };
+    function createTask(requestId: string) {
+      const session = service.openSession({ namespace });
+      const toolCalls = Array.from({ length: 11 }, (_, index) => ({
+        id: `${requestId}-${index}`, name: "task_step", input: { index }
+      }));
+      const completed = service.completeTurn(requestId, {
+        namespace, sessionId: session.sessionId,
+        query: "分析构建问题、修改配置并验证结果",
+        answer: "已完成分析、修复和验证。",
+        toolCalls,
+        toolResults: toolCalls.map((call) => ({
+          toolCallId: call.id, name: call.name, output: { ok: true }
+        }))
+      });
+      service.closeSession(session.sessionId);
+      return { ...completed, sessionId: session.sessionId };
+    }
+    async function reward(task: ReturnType<typeof createTask>) {
+      await service.feedback({
+        namespace, sessionId: task.sessionId, episodeId: task.episodeId,
+        l1MemoryId: task.l1MemoryId, channel: "explicit", polarity: "positive",
+        magnitude: 1, rationale: "构建修复正确"
+      });
+      await runWorkerRounds(service, 8);
+    }
+    function spanIds(episodeId: string): string[] {
+      return (db.db.prepare(`SELECT id FROM memories
+        WHERE json_extract(properties_json, '$.internal_info.memory_kind') = 'span'
+          AND json_extract(properties_json, '$.internal_info.span.episode_id') = ?
+          AND deleted_at IS NULL`).all(episodeId) as Array<{ id: string }>).map((row) => row.id);
+    }
+    const task = createTask("cascade-target");
+    await reward(task);
+    const originalSpans = spanIds(task.episodeId);
+    expect(originalSpans).toHaveLength(3);
+    if (splitAgain) {
+      await reward(task);
+      expect(calls.filter((call) => call.options.operation === "span.big_turn.v1")).toHaveLength(2);
+      const parent = db.db.prepare("SELECT properties_json FROM memories WHERE id = ?")
+        .get(task.l1MemoryId) as { properties_json: string };
+      const latestIds = JSON.parse(parent.properties_json).internal_info.trace.span_ids as string[];
+      expect(latestIds).toHaveLength(2);
+      expect(latestIds.every((id) => !originalSpans.includes(id))).toBe(true);
+    }
+    const targetIds = spanIds(task.episodeId);
+    expect(targetIds).toHaveLength(splitAgain ? 5 : 3);
+    const control = createTask("cascade-control");
+    await reward(control);
+    const controlIds = spanIds(control.episodeId);
+    expect(controlIds.length).toBeGreaterThan(0);
+    const controlBefore = db.db.prepare("SELECT * FROM memories WHERE id IN (SELECT value FROM json_each(?))")
+      .all(JSON.stringify(controlIds));
+    const countVectors = (ids: string[]) => (db.db.prepare(
+      "SELECT count(*) AS count FROM memory_vector_entries WHERE memory_id IN (SELECT value FROM json_each(?))"
+    ).get(JSON.stringify(ids)) as { count: number }).count;
+    expect(countVectors(targetIds)).toBeGreaterThan(0);
+    const controlVectorCount = countVectors(controlIds);
+    if (deleteParent) service.deleteMemory(task.l1MemoryId!, { namespace });
+
+    const deleted = service.deletePanelTask(task.episodeId, { namespace });
+    expect(new Set(deleted.deletedMemoryIds)).toEqual(new Set([
+      ...targetIds, ...(deleteParent ? [] : [task.l1MemoryId])
+    ]));
+    expect(db.db.prepare("SELECT id FROM episodes WHERE id = ?").get(task.episodeId)).toBeUndefined();
+    expect(db.db.prepare("SELECT id FROM raw_turns WHERE id = ?").get(task.rawTurnId)).toBeUndefined();
+    for (const id of [...targetIds, task.l1MemoryId!]) {
+      expect(db.db.prepare("SELECT status, deleted_at FROM memories WHERE id = ?").get(id))
+        .toEqual({ status: "deleted", deleted_at: expect.any(String) });
+      expect(() => service.getMemory(id, { namespace })).toThrow(/not found/i);
+      expect(db.db.prepare("SELECT count(*) AS count FROM audit_logs WHERE action = 'delete' AND target_id = ?").get(id))
+        .toEqual({ count: 1 });
+    }
+    expect(countVectors(targetIds)).toBe(0);
+    const remaining = service.panelItems({ namespace, layer: "L1" }).items.map((item) => item.id);
+    expect(targetIds.every((id) => !remaining.includes(id))).toBe(true);
+    const recalled = await service.search({ namespace, query: "分析构建问题 修改配置 验证结果", layers: ["L1"] });
+    expect(recalled.hits.some((hit) => targetIds.includes(hit.id) || hit.id === task.l1MemoryId)).toBe(false);
+    expect(db.db.prepare("SELECT * FROM memories WHERE id IN (SELECT value FROM json_each(?))")
+      .all(JSON.stringify(controlIds))).toEqual(controlBefore);
+    expect(countVectors(controlIds)).toBe(controlVectorCount);
+    for (const id of controlIds) expect(() => service.getMemory(id, { namespace })).not.toThrow();
+    expect(service.panelTasks({ namespace, page: 1 }).tasks.map((item) => item.id)).toContain(control.episodeId);
+    db.close();
+  });
+
   it("keeps the parent trace only when the complex turn has one coherent goal", async () => {
     const calls: Array<{ messages: LlmMessage[]; options: LlmCompletionOptions }> = [];
     const llm = createSpanBigTurnLlm(calls, {

From 5a0951fa17a38445165c539072fc13a81246e32a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Sat, 17 Oct 2026 16:22:17 +0800
Subject: [PATCH 66/85] =?UTF-8?q?fix:=20=E6=81=A2=E5=A4=8D=E8=AE=B0?=
 =?UTF-8?q?=E5=BF=86=E6=A8=A1=E5=9E=8B=E7=BC=96=E8=BE=91=E5=90=8E=E7=9A=84?=
 =?UTF-8?q?=E8=BF=9E=E6=8E=A5=E9=87=8D=E6=B5=8B=E5=B9=B6=E9=9A=94=E7=A6=BB?=
 =?UTF-8?q?=E5=8D=A1=E7=89=87=E8=AF=B7=E6=B1=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 App/frontend/desktop/src/pages/model-page.tsx |  40 +++++--
 ...redential-consistency.interaction.test.tsx | 100 ++++++++++++++++++
 2 files changed, 129 insertions(+), 11 deletions(-)

diff --git a/App/frontend/desktop/src/pages/model-page.tsx b/App/frontend/desktop/src/pages/model-page.tsx
index a6e0ec67e..508e2020d 100644
--- a/App/frontend/desktop/src/pages/model-page.tsx
+++ b/App/frontend/desktop/src/pages/model-page.tsx
@@ -109,7 +109,7 @@ export function ModelPage() {
   ));
   const [savePending, setSavePending] = useState(false);
   const [saveFeedback, setSaveFeedback] = useState<{ text: string; tone: "error" | "success" } | null>(null);
-  const credentialRevision = useRef(0);
+  const testRevisions = useRef({ skill: 0, memory: 0 });
   const skillValues = createModelFormValues(skill, primaryModel);
   const evolutionModel = modelFormValuesAsPrimary(skillValues);
   const memoryValues = createModelFormValues(mem, evolutionModel);
@@ -117,14 +117,24 @@ export function ModelPage() {
 
   /** Handles patch mem. */
   function patchMem(patch: Partial<ModelConfig>) {
-    if (!patch.validation) credentialRevision.current += 1;
-    setMem((current) => patchModelConfig(current, patch));
+    const changed = modelConnectionChanged(mem, patch, evolutionModel);
+    if (changed) testRevisions.current.memory += 1;
+    setMem((current) => patchModelConfig(current, patch, changed ? t("apiKey.testStale") : null));
   }
 
   /** Handles patch skill. */
   function patchSkill(patch: Partial<ModelConfig>) {
-    if (!patch.validation) credentialRevision.current += 1;
-    setSkill((current) => patchModelConfig(current, patch));
+    const changed = modelConnectionChanged(skill, patch, primaryModel);
+    if (changed) {
+      testRevisions.current.skill += 1;
+      const nextEvolution = modelFormValuesAsPrimary(createModelFormValues({ ...skill, ...patch }, primaryModel));
+      if (mem.reuse && createModelConfigValidationKey(memoryValues)
+        !== createModelConfigValidationKey(createModelFormValues(mem, nextEvolution))) {
+        testRevisions.current.memory += 1;
+        setMem((current) => patchModelConfig(current, {}, t("apiKey.testStale")));
+      }
+    }
+    setSkill((current) => patchModelConfig(current, patch, changed ? t("apiKey.testStale") : null));
   }
 
   /** Handles test model config connection. */
@@ -135,12 +145,14 @@ export function ModelPage() {
     secretTarget: "memory" | "skill"
   ) {
     const values = createModelFormValues(config, inheritedModel);
-    const revision = credentialRevision.current;
+    // Each card owns its request. A newer request also invalidates an older one
+    // when the user edits a value and then returns to the original configuration.
+    const revision = ++testRevisions.current[secretTarget];
     testModelConnection({
       configClient: clients?.config,
       values,
       setValidation: (validation) => {
-        if (credentialRevision.current === revision) patch({ validation });
+        if (testRevisions.current[secretTarget] === revision) patch({ validation });
       },
       secretTarget,
       messages: createTestModelConnectionMessages(t)
@@ -269,12 +281,18 @@ function modelPageSaveErrorText(
   return message || t("settings.modelWorkspace.saveFailed");
 }
 
-function patchModelConfig(current: ModelConfig, patch: Partial<ModelConfig>): ModelConfig {
+function modelConnectionChanged(current: ModelConfig, patch: Partial<ModelConfig>, primary: PrimaryModelValues): boolean {
+  return (patch.reuse !== undefined && patch.reuse !== current.reuse)
+    || createModelConfigValidationKey(createModelFormValues(current, primary))
+      !== createModelConfigValidationKey(createModelFormValues({ ...current, ...patch }, primary));
+}
+
+function patchModelConfig(current: ModelConfig, patch: Partial<ModelConfig>, staleMessage: string | null): ModelConfig {
   return {
     ...current,
     ...patch,
-    ...(patch.reuse !== undefined
-      ? { validation: { status: "idle" as const, message: null, testedKey: null } }
+    ...(staleMessage
+      ? { validation: { status: "idle" as const, message: staleMessage, testedKey: null } }
       : {})
   };
 }
@@ -508,7 +526,7 @@ function TestButton(props: TestButtonProps) {
 function ValidationMessage(props: ValidationMessageProps) {
   const { t } = useTranslation();
 
-  if (props.validation.status === "idle" && !props.stale && !props.credentialRequired) {
+  if (props.validation.status === "idle" && !props.validation.message && !props.stale && !props.credentialRequired) {
     return null;
   }
 
diff --git a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
index ec8264535..42079a4d0 100644
--- a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
@@ -473,6 +473,106 @@ describe("BYOK displayed, tested and saved credentials", () => {
     expect(test(1).textContent).not.toBe("apiKey.testSuccess");
     expect(next().disabled).toBe(true);
     expect(server.write).not.toHaveBeenCalled();
+    await testAndSave(scenarios[4]!);
+  });
+
+  function deferProbe() {
+    let finish!: (result: Awaited<ReturnType<typeof server.probe>>) => void;
+    server.probe.mockImplementationOnce(() => new Promise((resolve) => { finish = resolve; }));
+    return async (ok = true) => {
+      await act(async () => finish({ ok, message: ok ? "ok" : "old request failed", checkedAt: "2026-10-17T00:00:00.000Z" }));
+    };
+  }
+
+  it.each([0, 1].flatMap((index) => ["model", "key"].map((edit) => ({ index, edit }))))(
+    "role $index: editing $edit during a test unlocks retry and allows saving the new configuration",
+    async ({ index, edit }) => {
+      const finishOld = deferProbe();
+      await render(<ModelPage />);
+      await click(test(index));
+      await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+      expect(test(index).disabled).toBe(true);
+      await change(field(edit === "model" ? "apiKey.model" : "API Key", index), edit === "model" ? "corrected-model" : "sk-corrected-9999");
+      expect(test(index).disabled).toBe(false);
+      expect(test(index).textContent).toBe("apiKey.test");
+      expect(next().disabled).toBe(true);
+      await finishOld();
+      expect(test(index).disabled).toBe(false);
+      expect(test(index).textContent).toBe("apiKey.test");
+      const scenario = scenarios[index === 0 ? 5 : 4]!;
+      const tested = await testAndSave(scenario);
+      expect(tested).toMatchObject(edit === "model" ? { modelId: "corrected-model" } : { apiKey: "sk-corrected-9999" });
+    }
+  );
+
+  it.each([0, 1])("role %i: showing and hiding a key does not invalidate a pending test", async (index) => {
+    const finish = deferProbe();
+    await render(<ModelPage />);
+    await click(test(index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    await click(container.querySelectorAll<HTMLButtonElement>('[aria-label="apiKey.showKey"]')[index]!);
+    await click(container.querySelector<HTMLButtonElement>('[aria-label="apiKey.hideKey"]')!);
+    expect(test(index).disabled).toBe(true);
+    await finish();
+    expect(test(index).textContent).toBe("apiKey.testSuccess");
+    expect(next().disabled).toBe(false);
+    await click(next());
+    await vi.waitFor(() => expect(server.write).toHaveBeenCalled());
+  });
+
+  it.each([0, 1])("role %i: editing the other independent card leaves this request valid", async (index) => {
+    const finish = deferProbe();
+    await render(<ModelPage />);
+    await click(test(index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    await change(field("apiKey.model", 1 - index), "other-model");
+    await finish();
+    expect(test(index).textContent).toBe("apiKey.testSuccess");
+    expect(next().disabled).toBe(true);
+    await testAndSave(scenarios[index === 0 ? 4 : 5]!);
+    expect(await server.key("memory_evolution")).toBe("sk-team-1111");
+    expect(await server.key("memory_summary")).toBe("sk-summary-1111");
+  });
+
+  it.each(["old-first", "new-first", "return-to-original"])("roles: overlapping requests (%s) cannot overwrite the latest result", async (order) => {
+    const finishOld = deferProbe();
+    const finishNew = deferProbe();
+    await render(<ModelPage />);
+    await click(test(1));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    await change(field("apiKey.model", 1), "new-model");
+    if (order === "return-to-original") await change(field("apiKey.model", 1), "same-model");
+    await click(test(1));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(2));
+    if (order === "old-first") {
+      await finishOld();
+      expect(test(1).textContent).toBe("apiKey.testing");
+      expect(next().disabled).toBe(true);
+      await finishNew();
+    } else {
+      await finishNew();
+      await finishOld(false);
+    }
+    expect(test(1).textContent).toBe("apiKey.testSuccess");
+    expect(next().disabled).toBe(false);
+    await click(next());
+    await vi.waitFor(() => expect(server.write).toHaveBeenCalled());
+    expect(await server.key("memory_evolution")).toBe("sk-team-1111");
+  });
+
+  it("roles: upstream edits invalidate a following summary and recover after retesting", async () => {
+    const finishOld = deferProbe();
+    await render(<ModelPage />);
+    await click(test(0));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    await click(container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')[0]!);
+    await change(field("API Key"), "sk-updated-team-9999");
+    expect(next().disabled).toBe(true);
+    await finishOld();
+    expect(next().disabled).toBe(true);
+    await testAndSave({ ...scenarios[4]!, index: 0, fieldIndex: 0 });
+    expect(await server.key("memory_evolution")).toBe("sk-updated-team-9999");
+    expect(await server.key("memory_summary")).toBe("sk-updated-team-9999");
   });
 
   it("follow chain: primary rotation flows through evolution and summary, while a fixed role keeps its own key", async () => {

From 1fe1a6f83224c071129ea163bf23ed76ceb282aa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Sat, 17 Oct 2026 20:31:51 +0800
Subject: [PATCH 67/85] fix: isolate onboarding connection test responses

---
 .../src/pages/api-key-optional-page.tsx       |  47 +++----
 .../desktop/src/pages/api-key-page.tsx        |  48 +++----
 ...redential-consistency.interaction.test.tsx | 129 ++++++++++++++++++
 .../src/pages/use-model-connection-test.ts    |  48 +++++++
 4 files changed, 214 insertions(+), 58 deletions(-)
 create mode 100644 App/frontend/desktop/src/pages/use-model-connection-test.ts

diff --git a/App/frontend/desktop/src/pages/api-key-optional-page.tsx b/App/frontend/desktop/src/pages/api-key-optional-page.tsx
index bb5164e66..c4335c977 100644
--- a/App/frontend/desktop/src/pages/api-key-optional-page.tsx
+++ b/App/frontend/desktop/src/pages/api-key-optional-page.tsx
@@ -1,3 +1,4 @@
+import { useModelConnectionTest } from "./use-model-connection-test.js";
 import { bindSavedValidation, endpointCredentialSignature, resolveModelCredentials, type SavedEndpointIdentity } from "./model-credentials.js";
 import { useRef, useState } from "react";
 import { ChevronLeft, Image as ImageIcon, Mic } from "lucide-react";
@@ -34,8 +35,7 @@ import {
 } from "./optional-model-missing-warning-modal.js";
 import {
   canSaveModelConfig,
-  createModelConfigValidationKey,
-  type ModelConfigValidationState
+  createModelConfigValidationKey
 } from "./model-config-validation.js";
 import {
   ASR_DEFAULT_ENDPOINT,
@@ -47,7 +47,6 @@ import {
   createImageGenModelFormValues,
   createTestModelConnectionMessages,
   hydrateModelConfigForm,
-  testModelConnection,
   type ImageProtocol
 } from "./model-config.js";
 
@@ -81,10 +80,16 @@ export function ApiKeyOptionalPage() {
     ...createAsrModelFormValues(asrModel, asrEndpoint, asrApiKey, asrApiKeyMasked),
     protocol: "dashscope-input-audio-chat"
   }, savedEndpointIdentitiesRef.current.asr);
-  const [asrValidation, setAsrValidation] = useState<ModelConfigValidationState>(() => bindSavedValidation(initialModelForm.asrValidation, asrFormValues));
+  const { validation: asrValidation, isStale: isAsrTestStale, testConnection: testAsrConnection } = useModelConnectionTest({
+    configClient: clients?.config,
+    values: asrFormValues,
+    initialValidation: () => bindSavedValidation(initialModelForm.asrValidation, asrFormValues),
+    secretTarget: "asr",
+    capability: "asr",
+    messages: createTestModelConnectionMessages(t)
+  });
   const isAsrUsable = canSaveModelConfig(asrFormValues, asrValidation);
   const asrTestKey = createModelConfigValidationKey(asrFormValues);
-  const isAsrTestStale = Boolean(asrValidation.testedKey && asrValidation.testedKey !== asrTestKey);
   const [imageGenProtocol, setImageGenProtocol] = useState<ImageProtocol>(initialModelForm.imageGenProtocol);
   const [imageGenModel, setImageGenModel] = useState(initialModelForm.imageGenModelId);
   const [imageGenEndpoint, setImageGenEndpoint] = useState(initialModelForm.imageGenEndpoint);
@@ -96,10 +101,16 @@ export function ApiKeyOptionalPage() {
     ...createImageGenModelFormValues(imageGenProtocol, imageGenModel, imageGenEndpoint, imageGenApiKey, imageGenApiKeyMasked),
     protocol: imageGenProtocol === "qwen" ? "dashscope-multimodal-generation" : "openai-images"
   }, savedEndpointIdentitiesRef.current.imageGeneration);
-  const [imageGenValidation, setImageGenValidation] = useState<ModelConfigValidationState>(() => bindSavedValidation(initialModelForm.imageGenValidation, imageGenFormValues));
+  const { validation: imageGenValidation, isStale: isImageGenTestStale, testConnection: testImageGenConnection } = useModelConnectionTest({
+    configClient: clients?.config,
+    values: imageGenFormValues,
+    initialValidation: () => bindSavedValidation(initialModelForm.imageGenValidation, imageGenFormValues),
+    secretTarget: "image",
+    capability: "image",
+    messages: createTestModelConnectionMessages(t)
+  });
   const isImageGenUsable = canSaveModelConfig(imageGenFormValues, imageGenValidation);
   const imageGenTestKey = createModelConfigValidationKey(imageGenFormValues);
-  const isImageGenTestStale = Boolean(imageGenValidation.testedKey && imageGenValidation.testedKey !== imageGenTestKey);
   const imageGenEndpointProtocol = imageGenProtocol === "qwen"
     ? "dashscope-multimodal-generation"
     : "openai-images";
@@ -137,28 +148,6 @@ export function ApiKeyOptionalPage() {
     setImageGenWarningAcknowledged(false);
   }
 
-  function testAsrConnection() {
-    testModelConnection({
-      configClient: clients?.config,
-      values: asrFormValues,
-      setValidation: setAsrValidation,
-      capability: "asr",
-      secretTarget: "asr",
-      messages: createTestModelConnectionMessages(t)
-    });
-  }
-
-  function testImageGenConnection() {
-    testModelConnection({
-      configClient: clients?.config,
-      values: imageGenFormValues,
-      setValidation: setImageGenValidation,
-      capability: "image",
-      secretTarget: "image",
-      messages: createTestModelConnectionMessages(t)
-    });
-  }
-
   function closeOptionalModelMissingWarning() {
     if (optionalModelMissingWarning === "asr" || optionalModelMissingWarning === "both") {
       setAsrWarningAcknowledged(true);
diff --git a/App/frontend/desktop/src/pages/api-key-page.tsx b/App/frontend/desktop/src/pages/api-key-page.tsx
index 646ddd12a..c83f17a4b 100644
--- a/App/frontend/desktop/src/pages/api-key-page.tsx
+++ b/App/frontend/desktop/src/pages/api-key-page.tsx
@@ -1,3 +1,4 @@
+import { useModelConnectionTest } from "./use-model-connection-test.js";
 import { bindSavedValidation, endpointCredentialSignature, resolveModelCredentials, type SavedEndpointIdentity, chatProtocol } from "./model-credentials.js";
 import { useRef, useState } from "react";
 import { Brain, ChevronLeft, Search } from "lucide-react";
@@ -30,14 +31,12 @@ import {
 import {
   canSaveOptionalModelConfig,
   canSaveModelConfig,
-  createModelConfigValidationKey,
-  type ModelConfigValidationState
+  createModelConfigValidationKey
 } from "./model-config-validation.js";
 import {
   createTestModelConnectionMessages,
   fromProtocol,
-  hydrateModelConfigForm,
-  testModelConnection
+  hydrateModelConfigForm
 } from "./model-config.js";
 
 type EmbeddingMode = "local" | "custom";
@@ -109,7 +108,13 @@ export function ApiKeyPage() {
     apiKeyMasked,
     hasExistingApiKey: Boolean(apiKeyMasked)
   }, savedEndpointIdentitiesRef.current.agent);
-  const [llmValidation, setLlmValidation] = useState<ModelConfigValidationState>(() => bindSavedValidation(initialModelForm.llmValidation, modelFormValues));
+  const { validation: llmValidation, isStale: isTestStale, testConnection: testLlmConnection } = useModelConnectionTest({
+    configClient: clients?.config,
+    values: modelFormValues,
+    initialValidation: () => bindSavedValidation(initialModelForm.llmValidation, modelFormValues),
+    secretTarget: "primary",
+    messages: createTestModelConnectionMessages(t)
+  });
   const initialEmbeddingMode: EmbeddingMode = initialWorkspace.catalog.modelAssignments.byok.embedding
     ? "custom"
     : "local";
@@ -130,15 +135,21 @@ export function ApiKeyPage() {
     apiKeyMasked: embeddingConfig.apiKeyMasked,
     hasExistingApiKey: Boolean(embeddingConfig.apiKeyMasked)
   }, savedEndpointIdentitiesRef.current.embedding);
-  const [embeddingValidation, setEmbeddingValidation] = useState<ModelConfigValidationState>(() => bindSavedValidation(initialModelForm.embValidation, embeddingFormValues));
+  const { validation: embeddingValidation, isStale: isEmbeddingTestStale, testConnection: testEmbeddingConnection } = useModelConnectionTest({
+    configClient: clients?.config,
+    values: embeddingFormValues,
+    initialValidation: () => bindSavedValidation(initialModelForm.embValidation, embeddingFormValues),
+    secretTarget: "embedding",
+    capability: "embedding",
+    enabled: embeddingMode === "custom",
+    messages: createTestModelConnectionMessages(t)
+  });
   const canSave = canSaveModelConfig(modelFormValues, llmValidation)
     && canSaveOptionalModelConfig(embeddingMode === "custom", embeddingFormValues, embeddingValidation);
   const [savePending, setSavePending] = useState(false);
   const [saveError, setSaveError] = useState<string | null>(null);
   const testedKey = createModelConfigValidationKey(modelFormValues);
-  const isTestStale = Boolean(llmValidation.testedKey && llmValidation.testedKey !== testedKey);
   const embeddingTestKey = createModelConfigValidationKey(embeddingFormValues);
-  const isEmbeddingTestStale = Boolean(embeddingValidation.testedKey && embeddingValidation.testedKey !== embeddingTestKey);
   const agentCredentialSignature = endpointCredentialSignature(
     provider,
     chatProtocol(provider),
@@ -165,27 +176,6 @@ export function ApiKeyPage() {
     setApiKey("");
   }
 
-  function testLlmConnection() {
-    testModelConnection({
-      configClient: clients?.config,
-      values: modelFormValues,
-      setValidation: setLlmValidation,
-      secretTarget: "primary",
-      messages: createTestModelConnectionMessages(t)
-    });
-  }
-
-  function testEmbeddingConnection() {
-    testModelConnection({
-      configClient: clients?.config,
-      values: embeddingFormValues,
-      setValidation: setEmbeddingValidation,
-      capability: "embedding",
-      secretTarget: "embedding",
-      messages: createTestModelConnectionMessages(t)
-    });
-  }
-
   function updateEmbeddingConfig(field: keyof EmbeddingCustomConfig, value: string) {
     setEmbeddingConfig((current) => ({ ...current, [field]: value }));
   }
diff --git a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
index 42079a4d0..487acada6 100644
--- a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
@@ -484,6 +484,135 @@ describe("BYOK displayed, tested and saved credentials", () => {
     };
   }
 
+  it.each(scenarios.slice(0, 4))("onboarding $role: new success survives an older failure and saves the new key", async (scenario) => {
+    const finishOld = deferProbe();
+    const finishNew = deferProbe();
+    await render(scenario.page());
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    await change(field(scenario.endpoint), "https://changed.example/v1");
+    // Exact review reproduction: validate the now-missing credential before re-entry.
+    await click(test(scenario.index));
+    expect(server.probe).toHaveBeenCalledTimes(1);
+    await change(field(scenario.key), "sk-new-onboarding-9999");
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(2));
+    await finishNew();
+    expect(test(scenario.index).textContent).toBe("apiKey.testSuccess");
+    await finishOld(false);
+    expect(test(scenario.index).textContent).toBe("apiKey.testSuccess");
+    await click(next());
+    await vi.waitFor(() => expect(server.write).toHaveBeenCalled());
+    expect(await server.key(scenario.role)).toBe("sk-new-onboarding-9999");
+  });
+
+  it.each(scenarios.slice(0, 4).flatMap((scenario) =>
+    ["old-first", "new-first-success", "new-first-rejection", "new-failure", "return-to-original"].map((order) => ({ scenario, order }))
+  ))("onboarding $scenario.role: overlapping requests $order preserve the latest result", async ({ scenario, order }) => {
+    let rejectOld!: (error: Error) => void;
+    let finishOld: (ok?: boolean) => Promise<void>;
+    if (order === "new-first-rejection") {
+      server.probe.mockImplementationOnce(() => new Promise((_resolve, reject) => { rejectOld = reject; }));
+      finishOld = async () => { await act(async () => rejectOld(new Error("old transport failure"))); };
+    } else finishOld = deferProbe();
+    const finishNew = deferProbe();
+    await render(scenario.page());
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    await change(field(scenario.key), "sk-new-onboarding-9999");
+    if (order === "return-to-original") await change(field(scenario.key), "");
+    expect(test(scenario.index).disabled).toBe(false);
+    expect(test(scenario.index).textContent).toBe("apiKey.test");
+    await click(next());
+    expect(server.write).not.toHaveBeenCalled();
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(2));
+    if (order === "old-first") {
+      await finishOld();
+      expect(test(scenario.index).textContent).toBe("apiKey.testing");
+      expect(test(scenario.index).disabled).toBe(true);
+      await finishNew();
+    } else {
+      await finishNew(order !== "new-failure");
+      await finishOld();
+    }
+    if (order === "new-failure") {
+      expect(test(scenario.index).textContent).toBe("apiKey.testRetry");
+      await click(next());
+      expect(server.write).not.toHaveBeenCalled();
+      await testAndSave(scenario);
+    } else {
+      expect(test(scenario.index).textContent).toBe("apiKey.testSuccess");
+      await click(next());
+      await vi.waitFor(() => expect(server.write).toHaveBeenCalled());
+    }
+    expect(await server.key(scenario.role)).toBe(order === "return-to-original" ? scenario.expected : "sk-new-onboarding-9999");
+  });
+
+  it.each(scenarios.slice(0, 4).flatMap((scenario) =>
+    (scenario.role === "asr" ? ["key"] : ["key", "model"]).map((edit) => ({ scenario, edit }))
+  ))("onboarding $scenario.role: $edit edit unlocks retry before the old response", async ({ scenario, edit }) => {
+    const finishOld = deferProbe();
+    await render(scenario.page());
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    await change(field(edit === "key" ? scenario.key : scenario.model), edit === "key" ? "sk-new-onboarding-9999" : "new-model");
+    expect(test(scenario.index).disabled).toBe(false);
+    await finishOld();
+    expect(test(scenario.index).textContent).toBe("apiKey.test");
+    await click(next());
+    expect(server.write).not.toHaveBeenCalled();
+    const tested = await testAndSave(scenario);
+    expect(tested).toMatchObject(edit === "key" ? { apiKey: "sk-new-onboarding-9999" } : { modelId: "new-model" });
+  });
+
+  it.each(scenarios.slice(0, 4))("onboarding $role: visibility, normalized URL and other-card edits preserve the pending request", async (scenario) => {
+    const finish = deferProbe();
+    await render(scenario.page());
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    await click(container.querySelectorAll<HTMLButtonElement>('[aria-label="apiKey.showKey"]')[scenario.index]!);
+    await click(container.querySelector<HTMLButtonElement>('[aria-label="apiKey.hideKey"]')!);
+    await change(field(scenario.endpoint), "  https://provider.example/v1///  ");
+    const other = scenarios[(scenario.role === "agent" || scenario.role === "embedding" ? 0 : 2) + 1 - scenario.index]!;
+    await change(field(other.key), "sk-independent-8888");
+    expect(test(scenario.index).disabled).toBe(true);
+    await finish();
+    expect(test(scenario.index).textContent).toBe("apiKey.testSuccess");
+    await testAndSave(other);
+    expect(await server.key(scenario.role)).toBe(scenario.expected);
+  });
+
+  it.each([scenarios[0]!, scenarios[3]!])("onboarding $role: changing protocol during a request invalidates it and permits retry", async (scenario) => {
+    const finishOld = deferProbe();
+    await render(scenario.page());
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    await click(container.querySelector<HTMLButtonElement>('button[role="combobox"]')!);
+    await click([...container.querySelectorAll<HTMLButtonElement>('button[role="option"]')].find((item) => item.getAttribute("aria-selected") === "false")!);
+    await change(field(scenario.model), "new-protocol-model");
+    expect(test(scenario.index).disabled).toBe(false);
+    await finishOld();
+    expect(test(scenario.index).textContent).not.toBe("apiKey.testSuccess");
+    await change(field(scenario.key), "sk-new-onboarding-9999");
+    await testAndSave(scenario);
+  });
+
+  it("onboarding embedding: disabling and reenabling invalidates the pending request", async () => {
+    const finish = deferProbe();
+    await render(<ApiKeyPage />);
+    await click(test(1));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    for (let i = 0; i < 2; i++) {
+      await click(container.querySelectorAll<HTMLButtonElement>('button[role="combobox"]')[1]!);
+      await click([...container.querySelectorAll<HTMLButtonElement>('button[role="option"]')].find((item) => item.getAttribute("aria-selected") === "false")!);
+    }
+    await finish();
+    expect(test(1).textContent).toBe("apiKey.test");
+    expect(next().disabled).toBe(true);
+    await testAndSave(scenarios[1]!);
+  });
+
   it.each([0, 1].flatMap((index) => ["model", "key"].map((edit) => ({ index, edit }))))(
     "role $index: editing $edit during a test unlocks retry and allows saving the new configuration",
     async ({ index, edit }) => {
diff --git a/App/frontend/desktop/src/pages/use-model-connection-test.ts b/App/frontend/desktop/src/pages/use-model-connection-test.ts
new file mode 100644
index 000000000..391f8b27e
--- /dev/null
+++ b/App/frontend/desktop/src/pages/use-model-connection-test.ts
@@ -0,0 +1,48 @@
+import { useLayoutEffect, useRef, useState } from "react";
+import { createModelConfigValidationKey, type ModelConfigValidationState } from "./model-config-validation.js";
+import { testModelConnection, type TestModelConnectionInput } from "./model-config.js";
+
+type ConnectionTestOptions = Omit<TestModelConnectionInput, "setValidation" | "onSuccess"> & {
+  initialValidation: () => ModelConfigValidationState;
+  enabled?: boolean;
+};
+
+/** One card owns one request generation, independent of presentation-only edits. */
+export function useModelConnectionTest({ initialValidation, enabled = true, ...input }: ConnectionTestOptions) {
+  const [validation, setValidation] = useState(initialValidation);
+  const [isStale, setIsStale] = useState(false);
+  const revision = useRef(0);
+  const connectionKey = createModelConfigValidationKey(input.values);
+  const previous = useRef({ connectionKey, enabled });
+
+  // Invalidate before paint so editing immediately unlocks retry and disables save.
+  // A generation (rather than only a key comparison) also handles A -> B -> A.
+  useLayoutEffect(() => {
+    if (previous.current.connectionKey === connectionKey && previous.current.enabled === enabled) return;
+    const connectionChanged = previous.current.connectionKey !== connectionKey;
+    previous.current = { connectionKey, enabled };
+    revision.current += 1;
+    // Merely hiding an already validated optional card preserves its credential.
+    // A pending request must still be invalidated when the card is disabled.
+    if (connectionChanged || validation.status === "testing") {
+      setValidation({ status: "idle", message: null, testedKey: null });
+      setIsStale(true);
+    }
+  }, [connectionKey, enabled, validation.status]);
+
+  useLayoutEffect(() => () => { revision.current += 1; }, []);
+
+  function testConnection() {
+    if (!enabled) return;
+    const requestRevision = ++revision.current;
+    setIsStale(false);
+    testModelConnection({
+      ...input,
+      setValidation: (next) => {
+        if (revision.current === requestRevision) setValidation(next);
+      }
+    });
+  }
+
+  return { validation, isStale, testConnection };
+}

From e00425f6432565959358be434084379389fa1b94 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=83=AD=E6=B5=A9=E6=B4=8B?= <3253580733@qq.com>
Date: Sat, 17 Oct 2026 22:03:10 +0800
Subject: [PATCH 68/85] test: cover BYOK requests completing after page unmount

---
 ...redential-consistency.interaction.test.tsx | 56 +++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
index 487acada6..101c32995 100644
--- a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
@@ -484,6 +484,62 @@ describe("BYOK displayed, tested and saved credentials", () => {
     };
   }
 
+  it.each(scenarios.flatMap((scenario) =>
+    ["success", "failure", "rejection"].flatMap((outcome) =>
+      ["while-away", "new-pending", "new-succeeded"].map((timing) => ({ scenario, outcome, timing }))
+    )
+  ))("$scenario.role: leaving during a request isolates its $outcome ($timing) from reentry and save", async ({ scenario, outcome, timing }) => {
+    let finishOld: () => Promise<void>;
+    if (outcome === "rejection") {
+      let rejectOld!: (error: Error) => void;
+      server.probe.mockImplementationOnce(() => new Promise((_resolve, reject) => { rejectOld = reject; }));
+      finishOld = async () => { await act(async () => rejectOld(new Error("request from unmounted page rejected"))); };
+    } else {
+      const finish = deferProbe();
+      finishOld = () => finish(outcome === "success");
+    }
+    const finishNew = deferProbe();
+    await render(scenario.page());
+    await change(field(scenario.key, scenario.fieldIndex), "sk-before-leaving-7777");
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
+    expect(test(scenario.index).textContent).toBe("apiKey.testing");
+
+    // Route departure unmounts the page, while the real client/server promise stays pending.
+    await render(null);
+    expect(container.childElementCount).toBe(0);
+    if (timing === "while-away") await finishOld();
+    expect(server.write).not.toHaveBeenCalled();
+    expect(mocks.dispatch).not.toHaveBeenCalled();
+    await render(scenario.page());
+    expect(test(scenario.index).disabled).toBe(false);
+    expect(test(scenario.index).textContent).toBe("apiKey.test");
+    expect(field(scenario.key, scenario.fieldIndex).value).toBe("");
+    expect(field(scenario.key, scenario.fieldIndex).placeholder).toContain(scenario.expected.slice(-4));
+
+    await change(field(scenario.key, scenario.fieldIndex), "sk-after-reentry-9999");
+    await click(next());
+    expect(server.write).not.toHaveBeenCalled();
+    await click(test(scenario.index));
+    await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(2));
+    expect(server.probe.mock.calls[0]![0].apiKey).toBe("sk-before-leaving-7777");
+    expect(server.probe.mock.calls[1]![0].apiKey).toBe("sk-after-reentry-9999");
+    if (timing === "new-pending") await finishOld();
+    expect(test(scenario.index).textContent).toBe("apiKey.testing");
+    expect(test(scenario.index).disabled).toBe(true);
+    await click(next());
+    expect(server.write).not.toHaveBeenCalled();
+    await finishNew();
+    if (timing === "new-succeeded") await finishOld();
+    expect(test(scenario.index).textContent).toBe("apiKey.testSuccess");
+    expect(next().disabled).toBe(false);
+    expect(server.write).not.toHaveBeenCalled();
+    await click(next());
+    await vi.waitFor(() => expect(server.write).toHaveBeenCalled());
+    await vi.waitFor(() => expect(mocks.dispatch).toHaveBeenCalledWith(expect.objectContaining({ type: "navigation/changed" })));
+    expect(await server.key(scenario.role)).toBe("sk-after-reentry-9999");
+  });
+
   it.each(scenarios.slice(0, 4))("onboarding $role: new success survives an older failure and saves the new key", async (scenario) => {
     const finishOld = deferProbe();
     const finishNew = deferProbe();

From 9a86f5040f02cddb7fadea4f95ac24d877100147 Mon Sep 17 00:00:00 2001
From: Daoji Wang <627665797@qq.com>
Date: Mon, 19 Oct 2026 16:10:31 +0800
Subject: [PATCH 69/85] Register DeepSeek-V4.1-Flash-1017 so exact model
 lookups keep its token limits and vision support.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 App/memmy-agent/src/providers/model-input-capabilities.ts  | 7 ++++---
 App/memmy-agent/src/providers/model-token-defaults.ts      | 5 ++++-
 App/memmy-agent/tests/providers/litellm-kwargs.test.ts     | 2 +-
 .../tests/providers/model-input-capabilities.test.ts       | 3 ++-
 .../tests/providers/model-token-defaults.test.ts           | 6 +++++-
 .../tests/providers/openai-compat-image-input.test.ts      | 1 +
 6 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/App/memmy-agent/src/providers/model-input-capabilities.ts b/App/memmy-agent/src/providers/model-input-capabilities.ts
index 83e49587a..194f6b3f7 100644
--- a/App/memmy-agent/src/providers/model-input-capabilities.ts
+++ b/App/memmy-agent/src/providers/model-input-capabilities.ts
@@ -168,13 +168,14 @@ export const MODEL_INPUT_CAPABILITIES = defineModelInputCapabilities([
   ["groq/compound-mini", TEXT],
   ["qwen/qwen3.6-27b", TEXT_IMAGE],
 
-  // DeepSeek. Reviewed 2026-09-15.
+  // DeepSeek. Reviewed 2026-10-19.
   // Source: https://api-docs.deepseek.com/quick_start/pricing
   // Source: https://api-docs.deepseek.com/guides/vision/
-  // Official API ID is deepseek-flash (DeepSeek-V4.1-Flash) with native vision.
-  // deepseek-v4.1-flash is the Hugging Face / informal ID; lookup is exact, so register both.
+  // Official API ID remains deepseek-flash, now served by DeepSeek-V4.1-Flash-1017, with native vision.
+  // deepseek-v4.1-flash and deepseek-v4.1-flash-1017 are Hugging Face / informal IDs; lookup is exact.
   ["deepseek-flash", TEXT_IMAGE],
   ["deepseek-v4.1-flash", TEXT_IMAGE],
+  ["deepseek-v4.1-flash-1017", TEXT_IMAGE],
   ["deepseek-v4-pro", TEXT],
   ["deepseek-v4-flash", TEXT],
   ["deepseek-v4-flash-0731", TEXT],
diff --git a/App/memmy-agent/src/providers/model-token-defaults.ts b/App/memmy-agent/src/providers/model-token-defaults.ts
index 1b31eb850..436ef3d1e 100644
--- a/App/memmy-agent/src/providers/model-token-defaults.ts
+++ b/App/memmy-agent/src/providers/model-token-defaults.ts
@@ -269,13 +269,16 @@ export const MODEL_TOKEN_DEFAULTS = defineModelTokenDefaults([
   },
   { models: ["qwen/qwen3.6-27b"], contextWindowTokens: 131_072, maxTokens: 16_384 },
 
-  // DeepSeek. Reviewed 2026-09-15.
+  // DeepSeek. Reviewed 2026-10-19.
   // Source: https://api-docs.deepseek.com/quick_start/pricing
+  // Official API ID remains deepseek-flash, now served by DeepSeek-V4.1-Flash-1017.
   // Official Flash/Pro limits are 1M context and 384K max output.
+  // deepseek-v4.1-flash and deepseek-v4.1-flash-1017 are Hugging Face / informal IDs.
   {
     models: [
       "deepseek-flash",
       "deepseek-v4.1-flash",
+      "deepseek-v4.1-flash-1017",
       "deepseek-v4-pro",
       "deepseek-v4-flash",
       "deepseek-v4-flash-0731",
diff --git a/App/memmy-agent/tests/providers/litellm-kwargs.test.ts b/App/memmy-agent/tests/providers/litellm-kwargs.test.ts
index 73114b203..71a619e90 100644
--- a/App/memmy-agent/tests/providers/litellm-kwargs.test.ts
+++ b/App/memmy-agent/tests/providers/litellm-kwargs.test.ts
@@ -957,7 +957,7 @@ describe("OpenAI-compatible request kwargs", () => {
     expect(kwargs.messages[1]).not.toHaveProperty("reasoning_content");
   });
 
-  it.each(["deepseek-v4-pro", "deepseek-flash", "deepseek-v4.1-flash"])(
+  it.each(["deepseek-v4-pro", "deepseek-flash", "deepseek-v4.1-flash", "deepseek-v4.1-flash-1017"])(
     "backfills DeepSeek reasoning history for %s when effort is implicit",
     (model) => {
       const kwargs = providerFor("deepseek", model).buildKwargs({
diff --git a/App/memmy-agent/tests/providers/model-input-capabilities.test.ts b/App/memmy-agent/tests/providers/model-input-capabilities.test.ts
index 072e99ed7..715904954 100644
--- a/App/memmy-agent/tests/providers/model-input-capabilities.test.ts
+++ b/App/memmy-agent/tests/providers/model-input-capabilities.test.ts
@@ -15,7 +15,7 @@ describe("model input capabilities", () => {
     const allowed = new Set<ModelInputModality>(["text", "image", "video"]);
 
     expect(MODEL_INPUT_CAPABILITIES_REVIEWED_AT).toBe("2026-09-15");
-    expect(Object.keys(MODEL_INPUT_CAPABILITIES)).toHaveLength(244);
+    expect(Object.keys(MODEL_INPUT_CAPABILITIES)).toHaveLength(245);
     expect(Object.isFrozen(MODEL_INPUT_CAPABILITIES)).toBe(true);
     for (const [model, modalities] of Object.entries(MODEL_INPUT_CAPABILITIES)) {
       expect(model).toBeTruthy();
@@ -38,6 +38,7 @@ describe("model input capabilities", () => {
     expect(getModelInputModalities("deepseek-v4-pro")).toEqual(["text"]);
     expect(getModelInputModalities("deepseek-flash")).toEqual(["text", "image"]);
     expect(getModelInputModalities("deepseek-v4.1-flash")).toEqual(["text", "image"]);
+    expect(getModelInputModalities("deepseek-v4.1-flash-1017")).toEqual(["text", "image"]);
     expect(getModelInputModalities("deepseek-v4-flash-vision-exp")).toEqual(["text", "image"]);
     expect(getModelInputModalities("kimi-k3")).toEqual(["text", "image", "video"]);
     expect(getModelInputModalities("glm-5v-turbo")).toEqual(["text", "image", "video"]);
diff --git a/App/memmy-agent/tests/providers/model-token-defaults.test.ts b/App/memmy-agent/tests/providers/model-token-defaults.test.ts
index d2ff3b426..7c7f49a21 100644
--- a/App/memmy-agent/tests/providers/model-token-defaults.test.ts
+++ b/App/memmy-agent/tests/providers/model-token-defaults.test.ts
@@ -18,7 +18,7 @@ describe("model token defaults", () => {
       .sort();
     const tokenDefaultModels = Object.keys(MODEL_TOKEN_DEFAULTS).sort();
 
-    expect(tokenDefaultModels).toHaveLength(243);
+    expect(tokenDefaultModels).toHaveLength(244);
     expect(tokenDefaultModels).toEqual(inputCapabilityModels);
     expect(MODEL_TOKEN_DEFAULTS_REVIEWED_AT >= MODEL_INPUT_CAPABILITIES_REVIEWED_AT).toBe(true);
     expect(Object.isFrozen(MODEL_TOKEN_DEFAULTS)).toBe(true);
@@ -66,6 +66,10 @@ describe("model token defaults", () => {
       contextWindowTokens: 1_000_000,
       maxTokens: 384_000,
     });
+    expect(getModelTokenDefaults("deepseek-v4.1-flash-1017")).toEqual({
+      contextWindowTokens: 1_000_000,
+      maxTokens: 384_000,
+    });
     expect(getModelTokenDefaults("deepseek-v4-flash-vision-exp")).toEqual({
       contextWindowTokens: 1_000_000,
       maxTokens: 384_000,
diff --git a/App/memmy-agent/tests/providers/openai-compat-image-input.test.ts b/App/memmy-agent/tests/providers/openai-compat-image-input.test.ts
index 00ad44f4e..59eec49e9 100644
--- a/App/memmy-agent/tests/providers/openai-compat-image-input.test.ts
+++ b/App/memmy-agent/tests/providers/openai-compat-image-input.test.ts
@@ -55,6 +55,7 @@ describe("OpenAI-compatible image input", () => {
   it.each([
     "deepseek-flash",
     "deepseek-v4.1-flash",
+    "deepseek-v4.1-flash-1017",
     "deepseek-v4-flash-vision-exp",
   ])("sends image blocks to DeepSeek vision model %s", async (model) => {
     const create = vi.fn(async () => ({

From 98f629b8239a2ce3bae568f9c2a4fbd51e89e7c7 Mon Sep 17 00:00:00 2001
From: jiachengzhen <jiacz@memtensor.cn>
Date: Tue, 20 Oct 2026 11:05:21 +0800
Subject: [PATCH 70/85] fix: close PR 668 merge verification

---
 .../src/api/tests/config-client.test.ts       |  6 +--
 App/frontend/desktop/src/pages/home-page.tsx  | 21 +---------
 .../desktop/src/pages/model-config.ts         | 11 +++--
 App/frontend/desktop/src/pages/model-page.tsx | 22 +++++-----
 ...redential-consistency.interaction.test.tsx | 42 +++++++++----------
 ...k-setup-save-feedback.interaction.test.tsx | 10 +++--
 .../src/pages/tests/model-page-source.test.ts |  2 +-
 App/memmy-agent/scripts/build-npm-package.mjs |  1 +
 App/memmy-agent/scripts/build-runtime.mjs     |  1 +
 App/memmy-agent/src/config/schema.ts          |  3 ++
 .../src/entrypoints/cli/commands.ts           |  2 +-
 .../src/entrypoints/openai-like-api/server.ts |  2 +-
 12 files changed, 57 insertions(+), 66 deletions(-)

diff --git a/App/frontend/desktop/src/api/tests/config-client.test.ts b/App/frontend/desktop/src/api/tests/config-client.test.ts
index 087050f8c..c6dbb89c3 100644
--- a/App/frontend/desktop/src/api/tests/config-client.test.ts
+++ b/App/frontend/desktop/src/api/tests/config-client.test.ts
@@ -245,9 +245,9 @@ describe("config-client canonical model catalog", () => {
         endpointId: "chat-duplicate",
         apiBase: "https://api.openai.com/v1/",
         protocol: "openai-chat-completions",
-        ...(keyLocation === "endpoint apiKey" ? { apiKey: "  sk-live1234  " } : {})
+        ...(keyLocation === "endpoint apiKey" ? { apiKey: "  fixture-live-key-1234  " } : {})
       });
-      if (keyLocation === "provider apiKey") input.providers[0]!.apiKey = "  sk-live1234  ";
+      if (keyLocation === "provider apiKey") input.providers[0]!.apiKey = "  fixture-live-key-1234  ";
       input.providers[0]!.models.push({
         presetId: clientPresetId,
         endpointId: "chat-duplicate",
@@ -303,7 +303,7 @@ describe("config-client canonical model catalog", () => {
       input.providers[0]!.endpoints.push({
         ...input.providers[0]!.endpoints[0]!,
         endpointId: "chat-copy",
-        apiKey: "sk-different-secret1234"
+        apiKey: "fixture-different-key-1234"
       });
       input.providers[0]!.models.push({
         presetId: clientId,
diff --git a/App/frontend/desktop/src/pages/home-page.tsx b/App/frontend/desktop/src/pages/home-page.tsx
index 00a39cd0a..620e4cb7d 100644
--- a/App/frontend/desktop/src/pages/home-page.tsx
+++ b/App/frontend/desktop/src/pages/home-page.tsx
@@ -2349,21 +2349,6 @@ export function HomePage() {
     }
   }
 
-  function resetComposerDraftUi(scopeKey = chatScopeKey) {
-    setSelectedComposerCommandForScope(scopeKey, null);
-    for (const item of pendingAttachmentsRef.current[scopeKey] ?? []) {
-      revokePendingAttachment(item);
-    }
-    const nextDrafts = { ...composerDraftsRef.current };
-    const nextPendingAttachments = { ...pendingAttachmentsRef.current };
-    delete nextDrafts[scopeKey];
-    delete nextPendingAttachments[scopeKey];
-    composerDraftsRef.current = nextDrafts;
-    pendingAttachmentsRef.current = nextPendingAttachments;
-    dispatch(agentActions.composerScopeCleared(scopeKey));
-    resetComposerHeight();
-  }
-
   function closeLastCompactionPanel() {
     lastCompactionRequestIdRef.current += 1;
     pendingLastCompactionChatRef.current = null;
@@ -2783,7 +2768,7 @@ export function HomePage() {
           }
         : item));
       return true;
-    } catch (error) {
+    } catch {
       setPendingAttachmentsForScope(scopeKey, (current) => {
         const failed = current.find((item) => item.id === id);
         if (failed) revokePendingAttachment(failed);
@@ -4108,10 +4093,6 @@ function formatBytes(bytes: number): string {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 
-function isMessageKey(value: string): value is MessageKey {
-  return Object.prototype.hasOwnProperty.call(zhCNMessages, value);
-}
-
 export function hasCompletedAssistantAnswer(messages: AgentChatMessage[]): boolean {
   return firstCompletedAssistantAnswerMessageId(messages) !== null;
 }
diff --git a/App/frontend/desktop/src/pages/model-config.ts b/App/frontend/desktop/src/pages/model-config.ts
index 55de4bb18..71eff98e2 100644
--- a/App/frontend/desktop/src/pages/model-config.ts
+++ b/App/frontend/desktop/src/pages/model-config.ts
@@ -328,15 +328,16 @@ export function hydrateModelConfigForm(
     imageGenApiKeyMasked
   );
   const byokAssignments = saved.catalog?.modelAssignments.byok;
+  const hasAssignedByokPrimary = Boolean(byokAssignments?.agent?.default || byokAssignments?.agent?.candidates?.length);
   const skillModel = hydrateRoleModelConfig(
     saved.memmyMemory?.evolution,
     primary,
-    Boolean(byokAssignments?.memoryEvolution)
+    Boolean(byokAssignments?.memoryEvolution || hasAssignedByokPrimary)
   );
   const memoryModel = hydrateRoleModelConfig(
     saved.memmyMemory?.summary,
     modelFormValuesAsPrimary(createModelFormValues(skillModel, primary)),
-    Boolean(byokAssignments?.memorySummary)
+    Boolean(byokAssignments?.memorySummary || hasAssignedByokPrimary)
   );
 
   return {
@@ -500,10 +501,14 @@ function hydrateRoleModelConfig(
   primary: PrimaryModelValues,
   _inherited = false
 ): ModelConfig {
-  if (!role || role.mode === "follow" || (role.mode !== "fixed" && !role.configured && !role.apiKeyMasked && !role.apiKey.trim())) {
+  if (_inherited && (!role || role.mode === "follow")) {
     return createModelConfig(primary.protocol);
   }
 
+  if (!role || role.mode === "follow" || (role.mode !== "fixed" && !role.configured && !role.apiKeyMasked && !role.apiKey.trim())) {
+    return { ...createModelConfig(primary.protocol), reuse: false };
+  }
+
   const protocol = toProtocol(role.provider);
   const config: ModelConfig = {
     reuse: false,
diff --git a/App/frontend/desktop/src/pages/model-page.tsx b/App/frontend/desktop/src/pages/model-page.tsx
index 5f270c81b..41ad88044 100644
--- a/App/frontend/desktop/src/pages/model-page.tsx
+++ b/App/frontend/desktop/src/pages/model-page.tsx
@@ -241,17 +241,6 @@ export function ModelPage() {
           </p>
         </div>
 
-        <ModelCard
-          icon={<Cog size={18} className="text-action-sky" />}
-          title={t("apiKey.modelPage.skillTitle")}
-          subtitle={t("apiKey.modelPage.skillSubtitle")}
-          cfg={skill}
-          primary={primaryModel}
-          reuseLabel={t("apiKey.modelPage.reuseAgentChat")}
-          onPatch={patchSkill}
-          onTest={() => testModelConfigConnection(skill, primaryModel, patchSkill, "skill")}
-        />
-
         <ModelCard
           icon={<Brain size={18} className="text-action-sky" />}
           title={t("apiKey.modelPage.memoryTitle")}
@@ -264,6 +253,17 @@ export function ModelPage() {
           onTest={() => testModelConfigConnection(mem, evolutionModel, patchMem, "memory")}
         />
 
+        <ModelCard
+          icon={<Cog size={18} className="text-action-sky" />}
+          title={t("apiKey.modelPage.skillTitle")}
+          subtitle={t("apiKey.modelPage.skillSubtitle")}
+          cfg={skill}
+          primary={primaryModel}
+          reuseLabel={t("apiKey.modelPage.reuseAgentChat")}
+          onPatch={patchSkill}
+          onTest={() => testModelConfigConnection(skill, primaryModel, patchSkill, "skill")}
+        />
+
         <button
           type="button"
           disabled={!canContinue || savePending}
diff --git a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
index aaaabf2fd..101c32995 100644
--- a/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/byok-credential-consistency.interaction.test.tsx
@@ -95,8 +95,8 @@ const scenarios: Scenario[] = [
   { role: "embedding", page: () => <ApiKeyPage />, endpoint: "apiKey.embeddingEndpoint", model: "apiKey.embeddingModel", key: "apiKey.embeddingKey", expected: "sk-embedding-2222", index: 1 },
   { role: "asr", page: () => <ApiKeyOptionalPage />, endpoint: "apiKey.asrEndpoint", model: "apiKey.asrModel", key: "apiKey.asrKey", expected: "sk-asr-3333", index: 0 },
   { role: "image_generation", page: () => <ApiKeyOptionalPage />, endpoint: "apiKey.imageGenEndpoint", model: "apiKey.imageGenModel", key: "apiKey.imageGenKey", expected: "sk-image-4444", index: 1 },
-  { role: "memory_evolution", page: () => <ModelPage />, endpoint: "apiKey.endpoint", model: "apiKey.model", key: "API Key", expected: "sk-team-1111", index: 0, fieldIndex: 0 },
-  { role: "memory_summary", page: () => <ModelPage />, endpoint: "apiKey.endpoint", model: "apiKey.model", key: "API Key", expected: "sk-summary-1111", index: 1, fieldIndex: 1 }
+  { role: "memory_evolution", page: () => <ModelPage />, endpoint: "apiKey.endpoint", model: "apiKey.model", key: "API Key", expected: "sk-team-1111", index: 1, fieldIndex: 1 },
+  { role: "memory_summary", page: () => <ModelPage />, endpoint: "apiKey.endpoint", model: "apiKey.model", key: "API Key", expected: "sk-summary-1111", index: 0, fieldIndex: 0 }
 ];
 
 describe("BYOK displayed, tested and saved credentials", () => {
@@ -149,9 +149,7 @@ describe("BYOK displayed, tested and saved credentials", () => {
     const writes = server.write.mock.calls.length;
     await click(next());
     await vi.waitFor(() => expect(server.write.mock.calls.length).toBeGreaterThan(writes));
-    if (mocks.dispatch.mock.calls.length > 0) {
-      await vi.waitFor(() => expect(mocks.dispatch).toHaveBeenCalledWith(expect.objectContaining({ type: "navigation/changed" })));
-    }
+    await vi.waitFor(() => expect(mocks.dispatch).toHaveBeenCalledWith(expect.objectContaining({ type: "navigation/changed" })));
     expect(await server.key(scenario.role)).toBe(tested.apiKey);
     return tested;
   }
@@ -213,7 +211,7 @@ describe("BYOK displayed, tested and saved credentials", () => {
     await render(<ModelPage />);
     const checkbox = () => [...container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')][index]!;
     expect(checkbox().getAttribute("aria-checked")).toBe("false");
-    const scenario = scenarios[index === 0 ? 4 : 5]!;
+    const scenario = scenarios[index === 0 ? 5 : 4]!;
     await click(test(index));
     await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
     expect(server.probe.mock.calls[0]![0].apiKey).toBe(scenario.expected);
@@ -254,7 +252,7 @@ describe("BYOK displayed, tested and saved credentials", () => {
     await click([...container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')][index]!);
     await click(next());
     await vi.waitFor(() => expect(mocks.dispatch).toHaveBeenCalledWith(expect.objectContaining({ type: "navigation/changed" })));
-    expect(await server.key(index === 0 ? "memory_evolution" : "memory_summary")).toBe(index === 0 ? "sk-personal-1111" : "sk-team-1111");
+    expect(await server.key(index === 0 ? "memory_summary" : "memory_evolution")).toBe(index === 0 ? "sk-team-1111" : "sk-personal-1111");
   });
 
   it.each([0, 1])("role %i: disabling explicit follow copies the displayed inherited key and its actual source", async (index) => {
@@ -265,7 +263,7 @@ describe("BYOK displayed, tested and saved credentials", () => {
     const checkbox = [...container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')][index]!;
     expect(checkbox.getAttribute("aria-checked")).toBe("true");
     await click(checkbox);
-    const scenario = { ...scenarios[index === 0 ? 4 : 5]!, index: 0, fieldIndex: 0 };
+    const scenario = { ...scenarios[index === 0 ? 5 : 4]!, index: 0, fieldIndex: 0 };
     expect(field("API Key").placeholder).toContain("1111");
     expect((await testAndSave(scenario)).apiKey).toBe("sk-personal-1111");
   });
@@ -305,7 +303,7 @@ describe("BYOK displayed, tested and saved credentials", () => {
   it("a rejected independent key cannot fall back to the valid primary key or be saved", async () => {
     await render(<ModelPage />);
     server.probe.mockResolvedValueOnce({ ok: false, message: "rejected team key", checkedAt: "2026-10-16T00:00:00.000Z" });
-    await click(test(0));
+    await click(test(1));
     await vi.waitFor(() => expect(container.textContent).toContain("rejected team key"));
     expect(server.probe.mock.calls[0]![0].apiKey).toBe("sk-team-1111");
     expect(next().disabled).toBe(true);
@@ -462,17 +460,17 @@ describe("BYOK displayed, tested and saved credentials", () => {
     let finish!: (result: Awaited<ReturnType<typeof server.probe>>) => void;
     server.probe.mockImplementationOnce(() => new Promise((resolve) => { finish = resolve; }));
     await render(<ModelPage />);
-    await click(test(0));
+    await click(test(1));
     await vi.waitFor(() => expect(finish).toBeTypeOf("function"));
-    if (edit === "model") await change(field("apiKey.model", 0), "changed-model");
-    if (edit === "key") await change(field("API Key", 0), "sk-new-team-1111");
+    if (edit === "model") await change(field("apiKey.model", 1), "changed-model");
+    if (edit === "key") await change(field("API Key", 1), "sk-new-team-1111");
     if (edit === "reuse") {
-      const checkbox = () => container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')[0]!;
+      const checkbox = () => container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')[1]!;
       await click(checkbox());
       await click(checkbox());
     }
     await act(async () => finish({ ok: true, message: "ok", checkedAt: "2026-10-16T00:00:00.000Z" }));
-    expect(test(0).textContent).not.toBe("apiKey.testSuccess");
+    expect(test(1).textContent).not.toBe("apiKey.testSuccess");
     expect(next().disabled).toBe(true);
     expect(server.write).not.toHaveBeenCalled();
     await testAndSave(scenarios[4]!);
@@ -686,7 +684,7 @@ describe("BYOK displayed, tested and saved credentials", () => {
       await finishOld();
       expect(test(index).disabled).toBe(false);
       expect(test(index).textContent).toBe("apiKey.test");
-      const scenario = scenarios[index === 0 ? 4 : 5]!;
+      const scenario = scenarios[index === 0 ? 5 : 4]!;
       const tested = await testAndSave(scenario);
       expect(tested).toMatchObject(edit === "model" ? { modelId: "corrected-model" } : { apiKey: "sk-corrected-9999" });
     }
@@ -725,22 +723,22 @@ describe("BYOK displayed, tested and saved credentials", () => {
     const finishOld = deferProbe();
     const finishNew = deferProbe();
     await render(<ModelPage />);
-    await click(test(0));
+    await click(test(1));
     await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(1));
-    await change(field("apiKey.model", 0), "new-model");
-    if (order === "return-to-original") await change(field("apiKey.model", 0), "same-model");
-    await click(test(0));
+    await change(field("apiKey.model", 1), "new-model");
+    if (order === "return-to-original") await change(field("apiKey.model", 1), "same-model");
+    await click(test(1));
     await vi.waitFor(() => expect(server.probe).toHaveBeenCalledTimes(2));
     if (order === "old-first") {
       await finishOld();
-      expect(test(0).textContent).toBe("apiKey.testing");
+      expect(test(1).textContent).toBe("apiKey.testing");
       expect(next().disabled).toBe(true);
       await finishNew();
     } else {
       await finishNew();
       await finishOld(false);
     }
-    expect(test(0).textContent).toBe("apiKey.testSuccess");
+    expect(test(1).textContent).toBe("apiKey.testSuccess");
     expect(next().disabled).toBe(false);
     await click(next());
     await vi.waitFor(() => expect(server.write).toHaveBeenCalled());
@@ -781,7 +779,7 @@ describe("BYOK displayed, tested and saved credentials", () => {
     await render(<ModelPage />);
     const boxes = () => container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]');
     expect([...boxes()].map((b) => b.getAttribute("aria-checked"))).toEqual(["true", "true"]);
-    await click(boxes()[0]!); // Copy the new primary into an independent evolution configuration.
+    await click(boxes()[1]!); // Copy the new primary into an independent evolution configuration.
     expect(field("API Key").placeholder).toContain("9999");
     await change(field("API Key"), "sk-chain-team-7777");
     expect(next().disabled).toBe(true);
diff --git a/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx
index 7f06ac565..9d437e12e 100644
--- a/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/byok-setup-save-feedback.interaction.test.tsx
@@ -469,7 +469,7 @@ describe("BYOK setup save feedback", () => {
 
     const reuseButtons = () => [...container.querySelectorAll<HTMLButtonElement>('button[role="checkbox"]')];
     await click(reuseButtons()[1]!);
-    await click(testButton());
+    await click(testButton(0));
     await vi.waitFor(() => expect(testModelConfig).toHaveBeenNthCalledWith(
       1,
       expect.objectContaining({ endpointId: agentEndpointId, apiKey: "" }),
@@ -478,7 +478,7 @@ describe("BYOK setup save feedback", () => {
     ));
 
     await click(reuseButtons()[0]!);
-    await click(testButton());
+    await click(testButton(0));
     await vi.waitFor(() => expect(testModelConfig).toHaveBeenNthCalledWith(
       2,
       expect.objectContaining({ endpointId: agentEndpointId, apiKey: "" }),
@@ -494,8 +494,10 @@ describe("BYOK setup save feedback", () => {
       .mockResolvedValueOnce(savedModelConfig());
     mocks.clients = createClients(saveModelCatalog);
     await render(<ModelPage />);
-    await click(button("apiKey.modelPage.reuseAgentChat"));
-    await click(button("apiKey.modelPage.reuseEvolution"));
+    for (const label of ["apiKey.modelPage.reuseAgentChat", "apiKey.modelPage.reuseEvolution"]) {
+      const reuse = button(label);
+      if (reuse.getAttribute("aria-checked") !== "true") await click(reuse);
+    }
     const nextButton = button("apiKey.next");
 
     await click(nextButton);
diff --git a/App/frontend/desktop/src/pages/tests/model-page-source.test.ts b/App/frontend/desktop/src/pages/tests/model-page-source.test.ts
index dc8cf3640..1b266778a 100644
--- a/App/frontend/desktop/src/pages/tests/model-page-source.test.ts
+++ b/App/frontend/desktop/src/pages/tests/model-page-source.test.ts
@@ -21,7 +21,7 @@ describe("ModelPage source", () => {
     expect(messagesSource).toContain('"apiKey.modelPage.reusePrevious": "沿用上一步的 Agent 任务模型"');
     expect(messagesSource).toContain('"apiKey.modelPage.memoryHint": "可用更轻量的模型（如 30B），性价比更高"');
     expect(pageSource).toContain('t("apiKey.modelPage.title")');
-    expect(pageSource.indexOf('title={t("apiKey.modelPage.skillTitle")}')).toBeLessThan(pageSource.indexOf('title={t("apiKey.modelPage.memoryTitle")}'));
+    expect(pageSource.indexOf('title={t("apiKey.modelPage.memoryTitle")}')).toBeLessThan(pageSource.indexOf('title={t("apiKey.modelPage.skillTitle")}'));
     expect(pageSource).toContain('dispatch(appActions.navigate("/api-key"))');
     expect(pageSource).toContain('dispatch(appActions.navigate("/api-key-optional"))');
     expect(pageSource).not.toContain("resolveByokModelCompletion");
diff --git a/App/memmy-agent/scripts/build-npm-package.mjs b/App/memmy-agent/scripts/build-npm-package.mjs
index 6955161aa..5833f50aa 100644
--- a/App/memmy-agent/scripts/build-npm-package.mjs
+++ b/App/memmy-agent/scripts/build-npm-package.mjs
@@ -1,3 +1,4 @@
+/* global console */
 import { chmod, cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { npmInvocation } from "../../../scripts/internal/shared/npm-invocation.mjs";
 import { dirname, join, resolve } from "node:path";
diff --git a/App/memmy-agent/scripts/build-runtime.mjs b/App/memmy-agent/scripts/build-runtime.mjs
index 0a1d934c6..62ab47e8b 100644
--- a/App/memmy-agent/scripts/build-runtime.mjs
+++ b/App/memmy-agent/scripts/build-runtime.mjs
@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+/* global console */
 import { npmInvocation } from "../../../scripts/internal/shared/npm-invocation.mjs";
 import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
diff --git a/App/memmy-agent/src/config/schema.ts b/App/memmy-agent/src/config/schema.ts
index 7fdf6323c..9c4c72c42 100644
--- a/App/memmy-agent/src/config/schema.ts
+++ b/App/memmy-agent/src/config/schema.ts
@@ -1029,12 +1029,14 @@ export class HeartbeatConfig extends Base {
 export class ApiConfig extends Base {
   host = "127.0.0.1";
   port = 18990;
+  timeout = 120;
   apiKey: string | null = null;
 
   constructor(init: Dict = {}) {
     super();
     this.host = pick(init, ["host"], this.host);
     this.port = pick(init, ["port"], this.port);
+    this.timeout = pick(init, ["timeout"], this.timeout);
     this.apiKey = pick(init, ["apiKey"], null);
   }
 
@@ -1042,6 +1044,7 @@ export class ApiConfig extends Base {
     return {
       host: this.host,
       port: this.port,
+      timeout: this.timeout,
       apiKey: this.apiKey,
     };
   }
diff --git a/App/memmy-agent/src/entrypoints/cli/commands.ts b/App/memmy-agent/src/entrypoints/cli/commands.ts
index 40d60bbd1..0d3185cce 100644
--- a/App/memmy-agent/src/entrypoints/cli/commands.ts
+++ b/App/memmy-agent/src/entrypoints/cli/commands.ts
@@ -926,7 +926,7 @@ export async function serve({
   const appServer = createApp(
     loop,
     resolved.model,
-
+    timeout == null ? loaded.api.timeout : Number(timeout),
   );
   const bindHost = host ?? loaded.api.host;
   const bindPort = port == null ? loaded.api.port : Number(port);
diff --git a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
index 325100c0e..d3af8afb7 100644
--- a/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
+++ b/App/memmy-agent/src/entrypoints/openai-like-api/server.ts
@@ -441,7 +441,7 @@ async function handleTimedChatCompletions(request: Request, ctx?: ApiContext): P
       return { text: textResponse, usage };
     });
     return Response.json(chatCompletionResponse(reply.text, context.modelName, reply.usage));
-  } catch (err) {
+  } catch {
     if (controller.signal.aborted) return errorJson(409, "Task cancelled by user.", "cancelled");
     return errorJson(500, "Internal server error", "server_error");
   } finally {

From dcca76770ff3237b04e90dd8e9cdfb67f7a452b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Tue, 20 Oct 2026 15:22:21 +0800
Subject: [PATCH 71/85] =?UTF-8?q?fix:=20=E5=85=BC=E5=AE=B9=20OpenCode=20V2?=
 =?UTF-8?q?=20=E5=B9=B6=E6=9B=B4=E6=96=B0=E5=B7=B2=E6=9C=89=E8=AE=B0?=
 =?UTF-8?q?=E5=BF=86=E6=8F=92=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AgentSourceCore/src/index.ts                  |   1 +
 .../src/opencode-database-source.ts           |  86 +++++++++
 AgentSourceCore/src/opencode-source-turn.ts   |   9 +-
 .../agent-source/opencode/db-reader.ts        |  54 +-----
 .../outbound/skill-writer/opencode/target.ts  |  69 +++++--
 .../opencode/tests/target.test.ts             |  19 +-
 .../templates/memmy-opencode-plugin.ts        | 112 ++++++++++-
 .../skill-writer/workspace-bridge/runtime.ts  |  43 ++---
 .../agent-source-auto-inject-service.ts       |   2 +-
 .../agent-source-auto-inject-service.test.ts  |   6 +-
 App/frontend/desktop/src/i18n/messages.ts     |   2 +
 .../desktop/src/pages/memory-sources-page.tsx |   3 +
 .../adapters/opencode/db-reader.ts            |  58 +-----
 .../integration/opencode/target.ts            |  69 +++++--
 .../templates/memmy-opencode-plugin.ts        | 112 ++++++++++-
 Memory/src/agent-source/integration/types.ts  |   1 +
 .../integration/workspace-bridge/runtime.ts   |  43 ++---
 Memory/src/agent-source/runtime.ts            |  23 +++
 Memory/tests/agent-source-runtime.test.ts     |  33 ++++
 Memory/viewer/src/stores/i18n.ts              |   2 +
 Memory/viewer/src/views/SettingsView.tsx      |   3 +
 docs/opencode-v2-validation.txt               |  72 +++++++
 package.json                                  |   3 +-
 scripts/test-opencode-loader.mjs              |  84 ++++++++
 tests/opencode-compatibility.test.mjs         | 182 ++++++++++++++++++
 25 files changed, 861 insertions(+), 230 deletions(-)
 create mode 100644 AgentSourceCore/src/opencode-database-source.ts
 create mode 100644 docs/opencode-v2-validation.txt
 create mode 100644 scripts/test-opencode-loader.mjs
 create mode 100644 tests/opencode-compatibility.test.mjs

diff --git a/AgentSourceCore/src/index.ts b/AgentSourceCore/src/index.ts
index cd3020e3e..f432e22b5 100644
--- a/AgentSourceCore/src/index.ts
+++ b/AgentSourceCore/src/index.ts
@@ -4,6 +4,7 @@ export * from "./cursor-source-turn.js";
 export * from "./claude-code-source-turn.js";
 export * from "./openclaw-source-turn.js";
 export * from "./opencode-source-turn.js";
+export * from "./opencode-database-source.js";
 export * from "./hermes-source-turn.js";
 export * from "./deepseek-source-turn.js";
 export * from "./deepseek-session-files.js";
diff --git a/AgentSourceCore/src/opencode-database-source.ts b/AgentSourceCore/src/opencode-database-source.ts
new file mode 100644
index 000000000..5ce8a49e2
--- /dev/null
+++ b/AgentSourceCore/src/opencode-database-source.ts
@@ -0,0 +1,86 @@
+import type { OpencodeSource, OpencodeSession } from "./opencode-source-turn.js";
+
+interface Database {
+  prepare(sql: string): { all(...parameters: string[]): unknown[]; get(...parameters: string[]): unknown };
+}
+type Row = Record<string, unknown>;
+const record = (value: unknown): Row => value && typeof value === "object" && !Array.isArray(value) ? value as Row : {};
+const parse = (value: unknown): Row => {
+  if (typeof value !== "string") return record(value);
+  try { return record(JSON.parse(value)); } catch { return {}; }
+};
+
+/** Adapt both native database generations to the same turn parser. Only one
+ * session is materialised at a time; all callers open the database read-only. */
+export function createOpencodeDatabaseSource(db: Database, conversationId?: string): OpencodeSource | null {
+  const hasTable = (name: string) => Boolean(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(name));
+  const v2 = hasTable("session_v2") && hasTable("session_message");
+  if (!v2 && !(hasTable("session") && hasTable("message") && hasTable("part"))) return null;
+  const table = v2 ? "session_v2" : "session";
+  const columns = new Set(db.prepare(`PRAGMA table_info(${table})`).all().map(row => record(row).name));
+  const sessions = db.prepare(`SELECT id, parent_id AS parentId, directory${columns.has("agent") ? ", agent" : ""}${columns.has("revert") ? ", revert" : ""} FROM ${table}${conversationId ? " WHERE id = ?" : ""} ORDER BY time_created ASC, id ASC`);
+  const messages = db.prepare(v2
+    ? "SELECT id, type, data, time_created FROM session_message WHERE session_id = ? ORDER BY seq ASC, id ASC"
+    : "SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created ASC, id ASC");
+  const parts = v2 ? null : db.prepare("SELECT id, data FROM part WHERE message_id = ? ORDER BY time_created ASC, id ASC");
+  const currentParts = new Map<string, Array<{ id: string; data: unknown }>>();
+  return {
+    sessions: () => sessions.all(...(conversationId ? [conversationId] : [])).map(value => {
+      const row = record(value);
+      const revert = parse(row.revert);
+      return {
+        id: String(row.id), parentId: row.parentId == null ? null : String(row.parentId),
+        directory: row.directory == null ? null : String(row.directory),
+        agent: typeof row.agent === "string" ? row.agent : null,
+        revertMessageId: typeof revert.messageID === "string" ? revert.messageID : null
+      } satisfies OpencodeSession;
+    }),
+    messages(sessionId) {
+      const rows = messages.all(sessionId).map(record);
+      if (!v2) return rows.map(row => ({ id: String(row.id), data: parse(row.data) }));
+      currentParts.clear();
+      let parentID = "";
+      let agent = "";
+      let lastAssistant: Row | undefined;
+      const result: Array<{ id: string; data: Row }> = [];
+      for (const row of rows) {
+        const data = parse(row.data);
+        const type = data.type || row.type;
+        const id = String(row.id);
+        if (type === "agent-switched") { agent = String(data.agent || ""); continue; }
+        if (type === "user") {
+          parentID = id;
+          lastAssistant = undefined;
+          result.push({ id, data: { role: "user", time: data.time || { created: row.time_created } } });
+          currentParts.set(id, [{ id: id + ":text", data: { type: "text", text: data.text } }]);
+        } else if (type === "assistant" && parentID) {
+          lastAssistant = { ...data, role: "assistant", parentID, agent: data.agent || agent };
+          result.push({ id, data: lastAssistant });
+          const content = Array.isArray(data.content) ? data.content.map(record) : [];
+          currentParts.set(id, content.map((part, index) => {
+            if (part.type !== "tool") return { id: `${id}:${index}`, data: part };
+            const state = record(part.state);
+            const output = Array.isArray(state.content)
+              ? state.content.map(record).filter(item => item.type === "text").map(item => item.text).join("\n") : "";
+            return { id: `${id}:${index}`, data: {
+              type: "tool", callID: part.id, tool: part.name,
+              metadata: { providerExecuted: part.executed === true },
+              state: { ...state, output: state.status === "error" ? record(state.error).message || output : output, time: part.time }
+            } };
+          }));
+        } else if (type === "idle" && lastAssistant) {
+          // V2 persists an explicit terminal boundary, including tool-only and
+          // interrupted turns. Do not infer completion from an intermediate step.
+          lastAssistant.nativeTurnCompleted = true;
+          if (data.outcome === "failed" || data.outcome === "interrupted") lastAssistant.nativeStatus = "failed";
+          if (data.outcome === "interrupted") lastAssistant.error = { name: "MessageAbortedError" };
+          lastAssistant.time = { ...record(lastAssistant.time), completed: record(data.time).created || row.time_created };
+        }
+      }
+      return result;
+    },
+    parts: messageId => parts
+      ? parts.all(messageId).map(value => { const row = record(value); return { id: String(row.id), data: parse(row.data) }; })
+      : currentParts.get(messageId) || []
+  };
+}
diff --git a/AgentSourceCore/src/opencode-source-turn.ts b/AgentSourceCore/src/opencode-source-turn.ts
index 823228e9d..e8c7e3aec 100644
--- a/AgentSourceCore/src/opencode-source-turn.ts
+++ b/AgentSourceCore/src/opencode-source-turn.ts
@@ -59,6 +59,8 @@ interface OpencodeAssistant {
   pendingTool: boolean;
   hasOrdinaryTool: boolean;
   hasStructuredOutput: boolean;
+  nativeTurnCompleted: boolean;
+  nativeStatus?: "succeeded" | "failed";
 }
 
 /**
@@ -112,7 +114,9 @@ export async function* readOpencodeSession(
       toolResults: collected.toolResults,
       pendingTool: collected.pendingTool,
       hasOrdinaryTool: collected.hasOrdinaryTool,
-      hasStructuredOutput: data.structured !== undefined
+      hasStructuredOutput: data.structured !== undefined,
+      nativeTurnCompleted: data.nativeTurnCompleted === true,
+      nativeStatus: data.nativeStatus === "failed" ? "failed" : undefined
     };
     // An assistant with neither text nor a tool is idle bookkeeping (`step-finish` only).
     if (!assistant.assistantText && assistant.toolCalls.length === 0 && !assistant.pendingTool) continue;
@@ -145,7 +149,7 @@ export async function* readOpencodeSession(
       source: OPENCODE_SOURCE_ID, conversationId: session.id, turnId: user.id, profileId,
       startedAt: user.startedAt, completedAt, sequence: user.ordinal,
       completionEvidence: last!.aborted ? `assistant_aborted:${last!.id}` : `assistant_completed:${last!.id}`,
-      query: redactSecrets(user.query), answer: redactSecrets(answer), status: "succeeded",
+      query: redactSecrets(user.query), answer: redactSecrets(answer), status: last!.nativeStatus || "succeeded",
       toolCalls: pairSourceToolCalls(toolCalls, toolResults).map(redactCall), toolResults: toolResults.map(redactResult),
       ...(session.directory ? { workspacePath: session.directory } : {})
     };
@@ -229,6 +233,7 @@ function collectParts(source: OpencodeSource, messageId: string): {
  */
 function opencodeAssistantStillOpen(last: OpencodeAssistant): boolean {
   if (!last.completedAt) return true;
+  if (last.nativeTurnCompleted) return false;
   if (last.hasStructuredOutput) return false;
   if (!last.finish || last.finish === "tool-calls" || last.finish === "unknown") return true;
   return last.hasOrdinaryTool;
diff --git a/App/backend/src/adapters/outbound/agent-source/opencode/db-reader.ts b/App/backend/src/adapters/outbound/agent-source/opencode/db-reader.ts
index 791a8748d..82c0d0e01 100644
--- a/App/backend/src/adapters/outbound/agent-source/opencode/db-reader.ts
+++ b/App/backend/src/adapters/outbound/agent-source/opencode/db-reader.ts
@@ -2,8 +2,7 @@
 import { DatabaseSync } from "node:sqlite";
 import {
   readOpencodeSessions,
-  type OpencodeSession,
-  type OpencodeSource,
+  createOpencodeDatabaseSource,
   type RawSourceMessage
 } from "@memmy/agent-source-core";
 
@@ -22,7 +21,7 @@ export interface RawOpencodeDatabaseMessage extends RawSourceMessage {
 export async function* readOpencodeDatabase(path: string, signal?: AbortSignal): AsyncIterable<RawOpencodeDatabaseMessage> {
   const db = new DatabaseSync(path, { readOnly: true });
   try {
-    const source = createSource(db);
+    const source = createOpencodeDatabaseSource(db);
     if (!source) return;
     const directories = new Map([...source.sessions()].map((session) => [session.id, session.directory ?? null]));
     for await (const message of readOpencodeSessions(source, signal)) {
@@ -38,52 +37,3 @@ export async function* readOpencodeDatabase(path: string, signal?: AbortSignal):
 export async function* streamOpencodeDatabase(path: string, signal?: AbortSignal): AsyncIterable<RawOpencodeDatabaseMessage> {
   yield* readOpencodeDatabase(path, signal);
 }
-
-/** A database without the conversation tables is not a conversation store. */
-function createSource(db: DatabaseSync): OpencodeSource | null {
-  if (!hasTable(db, "session") || !hasTable(db, "message") || !hasTable(db, "part")) return null;
-  const columns = tableColumns(db, "session");
-  const sessions = db.prepare(`SELECT id, parent_id AS parentId, directory${columns.has("agent") ? ", agent" : ""}${columns.has("revert") ? ", revert" : ""} FROM session ORDER BY time_created ASC, id ASC`);
-  const messages = db.prepare("SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created ASC, id ASC");
-  const parts = db.prepare("SELECT id, data FROM part WHERE message_id = ? ORDER BY time_created ASC, id ASC");
-  return {
-    sessions: () => (sessions.all() as unknown as Array<Record<string, unknown>>).map(toOpencodeSession),
-    messages: (sessionId) => (messages.all(sessionId) as unknown as Array<{ id: string; data: string }>)
-      .map((row) => ({ id: row.id, data: parseJson(row.data) })),
-    parts: (messageId) => (parts.all(messageId) as unknown as Array<{ id: string; data: string }>)
-      .map((row) => ({ id: row.id, data: parseJson(row.data) }))
-  };
-}
-
-function toOpencodeSession(row: Record<string, unknown>): OpencodeSession {
-  return {
-    id: String(row.id),
-    parentId: row.parentId == null ? null : String(row.parentId),
-    directory: row.directory == null ? null : String(row.directory),
-    agent: typeof row.agent === "string" ? row.agent : null,
-    revertMessageId: revertMessageId(row.revert)
-  };
-}
-
-function revertMessageId(value: unknown): string | null {
-  const parsed = typeof value === "string" ? parseJson(value) : value;
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-  const messageId = (parsed as { messageID?: unknown }).messageID;
-  return typeof messageId === "string" && messageId ? messageId : null;
-}
-
-function tableColumns(db: DatabaseSync, tableName: string): Set<string> {
-  return new Set((db.prepare(`PRAGMA table_info(${tableName})`).all() as Array<{ name: string }>).map((row) => row.name));
-}
-
-function parseJson(value: string): unknown {
-  try {
-    return JSON.parse(value);
-  } catch {
-    return undefined;
-  }
-}
-
-function hasTable(db: DatabaseSync, tableName: string): boolean {
-  return Boolean(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(tableName));
-}
diff --git a/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts b/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts
index 11b4622ac..41e6006d3 100644
--- a/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts
@@ -1,5 +1,6 @@
 /** Target module. */
 import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { resolveOpencodeConfigDirectory } from "../../agent-paths.js";
@@ -18,6 +19,9 @@ const PLUGIN_DIRECTORY_NAME = "plugins";
 const PLUGIN_FILE_NAME = "memmy-memory.js";
 const PLUGIN_CONFIG_FILE_NAME = "memmy-memory-config.json";
 const WORKSPACE_BRIDGE_FILE_NAME = "memmy-workspace-bridge.mjs";
+// Bump when the OpenCode bridge contract changes. Backend/Memory bundles have
+// different bytes, so their valid installations must share a logical revision.
+const OPENCODE_BRIDGE_REVISION = "v2-1";
 const COMMAND_DIRECTORY_NAME = "commands";
 const RESUME_COMMAND_FILE_NAME = "memmy-resume.md";
 const START_MARKER = "<!-- memmy:start v=1 -->";
@@ -70,25 +74,36 @@ export function createOpencodeSkillTarget(deps: CreateOpencodeSkillTargetDeps =
       return (await readTextFile(join(rootDirectory, TARGET_FILE_NAME))).includes(START_MARKER);
     },
 
+    async isInstalledHookCurrent() {
+      const expected = await pluginAssets();
+      const config = await readPluginConfig(join(rootDirectory, PLUGIN_DIRECTORY_NAME, PLUGIN_CONFIG_FILE_NAME));
+      if (config.plugin_revision !== pluginRevision(expected)) return false;
+      const installed: Array<[string, string]> = [];
+      for (const [path, content] of expected) {
+        const actual = await readTextFile(join(rootDirectory, path));
+        if (!actual || (basename(path) !== WORKSPACE_BRIDGE_FILE_NAME && actual !== content)) return false;
+        installed.push([path, actual]);
+      }
+      return config.plugin_integrity === assetRevision(installed);
+    },
+
     async installPlugin(_targetId) {
       await mkdir(rootDirectory, { recursive: true });
       const pluginDirectory = join(rootDirectory, PLUGIN_DIRECTORY_NAME);
       const commandDirectory = join(rootDirectory, COMMAND_DIRECTORY_NAME);
       await mkdir(pluginDirectory, { recursive: true });
       await mkdir(commandDirectory, { recursive: true });
-      await writeFileAtomically(
-        join(pluginDirectory, PLUGIN_CONFIG_FILE_NAME),
-        `${JSON.stringify({
-          memmy_config_path: memmyConfigPath,
-          ...(await readMemmyMemoryServiceConfig(memmyConfigPath))
-        }, null, 2)}\n`
-      );
-      await writeFileAtomically(join(pluginDirectory, PLUGIN_FILE_NAME), renderMemmyOpencodePlugin());
-      await writeFileAtomically(
-        join(pluginDirectory, WORKSPACE_BRIDGE_FILE_NAME),
-        await loadMemmyWorkspaceBridgeRuntimeAsset()
-      );
-      await writeFileAtomically(join(commandDirectory, RESUME_COMMAND_FILE_NAME), renderMemmyOpencodeResumeCommand());
+      const configPath = join(pluginDirectory, PLUGIN_CONFIG_FILE_NAME);
+      // Parse before writing anything. A malformed existing config must not be
+      // silently replaced with empty credentials or defaults.
+      const existingConfig = await readPluginConfig(configPath);
+      const config = {
+        memmy_config_path: memmyConfigPath,
+        ...(await readMemmyMemoryServiceConfig(memmyConfigPath)),
+        ...existingConfig
+      };
+      const assets = await pluginAssets();
+      for (const [path, content] of assets) await writeFileAtomically(join(rootDirectory, path), content);
 
       const manifest = renderMemmyPluginSkillManifest(_targetId);
       const filePath = join(rootDirectory, TARGET_FILE_NAME);
@@ -100,6 +115,10 @@ export function createOpencodeSkillTarget(deps: CreateOpencodeSkillTargetDeps =
         )
       );
       await replaceMemmySkillDirectory(rootDirectory, manifest);
+      // Publish the revision only after every managed file was installed.
+      await writeFileAtomically(configPath, `${JSON.stringify({ ...config,
+        plugin_revision: pluginRevision(assets), plugin_integrity: assetRevision(assets)
+      }, null, 2)}\n`);
     },
 
     async uninstallPlugin(_targetId) {
@@ -122,6 +141,30 @@ export function createOpencodeSkillTarget(deps: CreateOpencodeSkillTargetDeps =
   };
 }
 
+async function pluginAssets(): Promise<Array<[string, string]>> {
+  return [
+    [join(PLUGIN_DIRECTORY_NAME, PLUGIN_FILE_NAME), renderMemmyOpencodePlugin()],
+    [join(PLUGIN_DIRECTORY_NAME, WORKSPACE_BRIDGE_FILE_NAME), await loadMemmyWorkspaceBridgeRuntimeAsset()],
+    [join(COMMAND_DIRECTORY_NAME, RESUME_COMMAND_FILE_NAME), renderMemmyOpencodeResumeCommand()]
+  ];
+}
+
+function assetRevision(assets: Array<[string, string]>): string {
+  return createHash("sha256").update(JSON.stringify(assets.map(([, content]) => content))).digest("hex");
+}
+
+function pluginRevision(assets: Array<[string, string]>): string {
+  return OPENCODE_BRIDGE_REVISION + ":" + assetRevision(assets.filter(([path]) => basename(path) !== WORKSPACE_BRIDGE_FILE_NAME));
+}
+
+async function readPluginConfig(path: string): Promise<Record<string, unknown>> {
+  const content = await readTextFile(path);
+  if (!content.trim()) return {};
+  const value: unknown = JSON.parse(content);
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid Memmy OpenCode plugin config");
+  return value as Record<string, unknown>;
+}
+
 async function readTextFile(filePath: string): Promise<string> {
   try {
     return await readFile(filePath, "utf8");
diff --git a/App/backend/src/adapters/outbound/skill-writer/opencode/tests/target.test.ts b/App/backend/src/adapters/outbound/skill-writer/opencode/tests/target.test.ts
index c22792ed1..8029122d8 100644
--- a/App/backend/src/adapters/outbound/skill-writer/opencode/tests/target.test.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/opencode/tests/target.test.ts
@@ -98,8 +98,8 @@ describe("opencode skill target", () => {
     });
     const bridgePath = join(rootDirectory, "plugins", "memmy-workspace-bridge.mjs");
     expect(existsSync(bridgePath)).toBe(true);
-    expect(pluginSource).toContain('import { tool } from "@opencode-ai/plugin";');
-    expect(pluginSource).toContain("export const MemmyMemoryPlugin");
+    expect(pluginSource).not.toContain('from "@opencode-ai/plugin"');
+    expect(pluginSource).toContain("export default");
     expect(pluginSource).toContain('"chat.message"');
     expect(pluginSource).toContain('"experimental.text.complete"');
     expect(pluginSource).toContain('event: async ({ event }) =>');
@@ -368,24 +368,17 @@ interface OpencodePluginHooks {
 
 async function loadPluginHooks(rootDirectory: string): Promise<OpencodePluginHooks> {
   const pluginDirectory = join(rootDirectory, "plugins");
-  const pluginSource = readFileSync(join(pluginDirectory, "memmy-memory.js"), "utf8").replace(
-    'import { tool } from "@opencode-ai/plugin";',
-    [
-      "const schemaValue = () => ({ optional() { return this; } });",
-      "const tool = (definition) => definition;",
-      "tool.schema = { string: schemaValue, enum: schemaValue, array: schemaValue };"
-    ].join("\n")
-  );
+  const pluginSource = readFileSync(join(pluginDirectory, "memmy-memory.js"), "utf8");
   const runtimePath = join(pluginDirectory, `memmy-memory-runtime-${Date.now()}-${Math.random().toString(36).slice(2)}.mjs`);
   writeFileSync(runtimePath, pluginSource, "utf8");
   const module = await import(pathToFileURL(runtimePath).href) as {
-    MemmyMemoryPlugin(input: {
+    default: { server(input: {
       client: { app: { log(input: unknown): Promise<void> } };
       directory: string;
       worktree: string;
-    }): Promise<OpencodePluginHooks>;
+    }): Promise<OpencodePluginHooks> };
   };
-  return module.MemmyMemoryPlugin({
+  return module.default.server({
     client: { app: { async log() { return undefined; } } },
     directory: rootDirectory,
     worktree: rootDirectory
diff --git a/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts b/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
index 9ace951b2..a6aabc60e 100644
--- a/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
@@ -5,8 +5,9 @@ export function renderMemmyOpencodePlugin(): string {
   return String.raw`import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { tool } from "@opencode-ai/plugin";
 import {
+  opencodeTool as tool,
+  opencodeToolJsonSchema,
   closeRuntimeSession,
   completeSourceTurn,
   loadRuntimeL3,
@@ -25,8 +26,94 @@ const DISPLAY_LIMIT = 5;
 const RESUME_STATE_TTL_MS = 10 * 60 * 1000;
 const RESUME_CONTEXT_MAX_CHARS = 24000;
 const TOOL_OUTPUT_MAX_CHARS = 12000;
+const PLUGIN_REVISION = "opencode-v2-1";
+
+// A single default export prevents V1 from registering the same plugin twice.
+// The schema helper is bundled in our bridge; neither host needs the other SDK.
+export default {
+  id: "memmy-memory",
+  async server(input) {
+    const hooks = await createMemmyHooks(input);
+    console.error("Memmy plugin loaded: revision=" + PLUGIN_REVISION + ", entry=v1");
+    return hooks;
+  },
+  async setup(ctx) {
+    const hooks = await createMemmyHooks({ directory: ctx.location.directory });
+    const controller = new AbortController();
+    const registrations = [];
+    let events;
+    let cleanupPromise;
+    const cleanup = () => cleanupPromise || (cleanupPromise = (async () => {
+      controller.abort();
+      await Promise.allSettled(registrations.map((registration) => registration.dispose()));
+      await events;
+      await hooks.dispose();
+    })());
+    try {
+      registrations.push(await ctx.tool.transform((editor) => {
+        for (const [name, definition] of Object.entries(hooks.tool)) {
+          editor.add({
+            name,
+            description: definition.description,
+            input: opencodeToolJsonSchema(definition.args),
+            async execute(input, context) {
+              return { content: await definition.execute(input, context) };
+            }
+          });
+        }
+      }));
+      registrations.push(await ctx.session.hook("prompt", async (event) => {
+        if (controller.signal.aborted) return;
+        try {
+          const parts = [{ type: "text", text: event.prompt.text }];
+          // Agent selection lives on the V2 session, not on SessionPrompt.
+          const session = await ctx.session.get({ sessionID: event.sessionID });
+          if (session.parentID) return;
+          await hooks["chat.message"](
+            { sessionID: event.sessionID, messageID: event.messageID, agent: session.agent },
+            { message: { id: event.messageID }, parts }
+          );
+          event.prompt.text = extractUserText(parts);
+        } catch (error) {
+          console.warn("Memmy prompt recall skipped: " + formatError(error));
+        }
+      }));
+      registrations.push(await ctx.command.transform((editor) => editor.add({
+        name: "memmy-resume",
+        description: "Search and resume a previous Memmy episode",
+        async execute({ sessionID, prompt, delivery }) {
+          await ctx.session.prompt({ ...prompt, sessionID, delivery,
+            text: "MEMMY_RESUME_COMMAND_ARGUMENTS: " + prompt.text + "\nMEMMY_RESUME_COMMAND_END" });
+        }
+      })));
+      events = (async () => {
+        try {
+          for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+            if (controller.signal.aborted) break;
+            if (!["session.created", "session.compacted", "session.deleted", "session.idle", "session.status"].includes(event.type)) continue;
+            const properties = event.data || {};
+            if (properties.parentID) continue;
+            if (event.type === "session.status" && properties.status?.type !== "idle") continue;
+            try {
+              await hooks.event({ event: { type: event.type === "session.status" ? "session.idle" : event.type, properties } });
+            } catch (error) {
+              console.warn("Memmy event failed: " + formatError(error));
+            }
+          }
+        } catch (error) {
+          if (!controller.signal.aborted) console.warn("Memmy event subscription failed: " + formatError(error));
+        }
+      })();
+      console.error("Memmy plugin loaded: revision=" + PLUGIN_REVISION + ", entry=v2");
+      return cleanup;
+    } catch (error) {
+      await cleanup();
+      throw error;
+    }
+  }
+};
 
-export const MemmyMemoryPlugin = async ({ client, directory, worktree }) => {
+const createMemmyHooks = async ({ client, directory, worktree }) => {
   const sessionCache = new Map();
   const l3InjectOnce = new Map();
   const pendingTurns = new Map();
@@ -54,6 +141,17 @@ export const MemmyMemoryPlugin = async ({ client, directory, worktree }) => {
     }
   }
 
+  async function closeSession(sessionID) {
+    for (const [key, session] of sessionCache) {
+      if (!key.startsWith(sessionID + ":")) continue;
+      sessionCache.delete(key);
+      await closeRuntimeSession(session).catch(() => undefined);
+    }
+    l3InjectOnce.delete(sessionID);
+    pendingResumeSelections.delete(sessionID);
+    latestRequests.delete(sessionID);
+  }
+
   async function ensureSession(memmy, externalSessionId, agent) {
     const profileId = normalizeText(agent) || "main";
     const cacheKey = externalSessionId + ":" + profileId;
@@ -372,7 +470,7 @@ export const MemmyMemoryPlugin = async ({ client, directory, worktree }) => {
       }
       if (event && event.type === "session.compacted") {
         const sessionID = normalizeText(properties.sessionID || properties.id);
-        const runtimeSession = sessionCache.get(sessionID) || await ensureSession(null, sessionID, "main");
+        const runtimeSession = await ensureSession(null, sessionID, "main");
         await notifyRuntimeBoundary(runtimeSession, "token_compaction");
         const loaded = await loadRuntimeL3(runtimeSession);
         if (loaded.additionalContext) l3InjectOnce.set(sessionID, loaded.additionalContext);
@@ -381,10 +479,7 @@ export const MemmyMemoryPlugin = async ({ client, directory, worktree }) => {
       if (event && event.type === "session.deleted") {
         const sessionID = normalizeText(properties.sessionID || properties.id);
         queueTurnCompletion(sessionID);
-        const runtimeSession = sessionCache.get(sessionID);
-        if (runtimeSession) await closeRuntimeSession(runtimeSession).catch(() => undefined);
-        sessionCache.delete(sessionID);
-        l3InjectOnce.delete(sessionID);
+        await closeSession(sessionID);
         return;
       }
       if (event && event.type === "message.part.updated") {
@@ -422,6 +517,9 @@ export const MemmyMemoryPlugin = async ({ client, directory, worktree }) => {
       await Promise.allSettled([...sessionCache.values()].map((session) => closeRuntimeSession(session)));
       sessionCache.clear();
       l3InjectOnce.clear();
+      pendingResumeSelections.clear();
+      latestRequests.clear();
+      console.error("Memmy plugin disposed: revision=" + PLUGIN_REVISION);
     }
   };
 };
diff --git a/App/backend/src/adapters/outbound/skill-writer/workspace-bridge/runtime.ts b/App/backend/src/adapters/outbound/skill-writer/workspace-bridge/runtime.ts
index 32b881c67..1105322d8 100644
--- a/App/backend/src/adapters/outbound/skill-writer/workspace-bridge/runtime.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/workspace-bridge/runtime.ts
@@ -11,7 +11,7 @@ import {
   readOpencodeSourceTurn,
   type CursorVscdbSource,
   type OpenclawTranscriptSource,
-  type OpencodeSource,
+  createOpencodeDatabaseSource,
   type SourceTurn
 } from "@memmy/agent-source-core";
 export { readClaudeCodeSourceTurn, readCodexSourceTurn } from "@memmy/agent-source-core";
@@ -28,6 +28,14 @@ import { homedir } from "node:os";
 import { isAbsolute, parse, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import YAML from "yaml";
+import { z } from "zod";
+
+/** OpenCode V1 tools are plain definitions containing real Zod schemas. Bundle them
+ * locally so installing Memmy never depends on the host's SDK package resolution. */
+export const opencodeTool = Object.assign(<T>(definition: T): T => definition, { schema: z });
+export function opencodeToolJsonSchema(args: Record<string, z.ZodType>): Record<string, unknown> {
+  return z.toJSONSchema(z.object(args));
+}
 import {
   normalizeWorkspaceUri,
   renderL3WorldModelContext,
@@ -412,37 +420,8 @@ export async function readOpencodeHookSourceTurn(input: {
     return { turn: null, reason: "source_store_unavailable" };
   }
   try {
-    const columns = new Set((db.prepare("PRAGMA table_info(session)").all() as Array<{ name: string }>).map((row) => row.name));
-    const sessions = db.prepare(`SELECT id, parent_id AS parentId, directory${columns.has("agent") ? ", agent" : ""}${columns.has("revert") ? ", revert" : ""} FROM session WHERE id = ?`);
-    const messages = db.prepare("SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created ASC, id ASC");
-    const parts = db.prepare("SELECT id, data FROM part WHERE message_id = ? ORDER BY time_created ASC, id ASC");
-    const parse = (value: unknown): unknown => {
-      if (typeof value !== "string") return undefined;
-      try {
-        return JSON.parse(value);
-      } catch {
-        return undefined;
-      }
-    };
-    const source: OpencodeSource = {
-      sessions: () => (sessions.all(input.conversationId) as unknown as Array<Record<string, unknown>>).map((row) => {
-        const revert = typeof row.revert === "string" ? parse(row.revert) : row.revert;
-        const messageId = revert && typeof revert === "object" && !Array.isArray(revert)
-          ? (revert as { messageID?: unknown }).messageID
-          : undefined;
-        return {
-          id: String(row.id),
-          parentId: row.parentId == null ? null : String(row.parentId),
-          directory: row.directory == null ? null : String(row.directory),
-          agent: typeof row.agent === "string" ? row.agent : null,
-          revertMessageId: typeof messageId === "string" && messageId ? messageId : null
-        };
-      }),
-      messages: (sessionId) => (messages.all(sessionId) as unknown as Array<{ id: string; data: string }>)
-        .map((row) => ({ id: row.id, data: parse(row.data) })),
-      parts: (messageId) => (parts.all(messageId) as unknown as Array<{ id: string; data: string }>)
-        .map((row) => ({ id: row.id, data: parse(row.data) }))
-    };
+    const source = createOpencodeDatabaseSource(db, input.conversationId);
+    if (!source) return { turn: null, reason: "source_store_unavailable" };
     return await readOpencodeSourceTurn(source, input);
   } finally {
     db.close();
diff --git a/App/backend/src/services/agent-source-auto-inject-service.ts b/App/backend/src/services/agent-source-auto-inject-service.ts
index a5ddd7dfe..389b4fb71 100644
--- a/App/backend/src/services/agent-source-auto-inject-service.ts
+++ b/App/backend/src/services/agent-source-auto-inject-service.ts
@@ -16,7 +16,7 @@ const AUTO_INJECT_AGENT_SOURCE_IDS = new Set([
   "qwenwork"
 ]);
 const HOOK_OR_PLUGIN_AGENT_SOURCE_IDS = new Set(["cursor", "claude_code", "codex", "opencode", "openclaw", "hermes", "deepseek_harness"]);
-const UPDATABLE_HOOK_AGENT_SOURCE_IDS = new Set(["cursor", "claude_code", "codex"]);
+const UPDATABLE_HOOK_AGENT_SOURCE_IDS = new Set(["cursor", "claude_code", "codex", "opencode"]);
 
 export interface AgentSourceAutoInjectService {
   runOnce(): Promise<AgentSourceAutoInjectResult>;
diff --git a/App/backend/src/services/tests/agent-source-auto-inject-service.test.ts b/App/backend/src/services/tests/agent-source-auto-inject-service.test.ts
index 6d9a80016..8c50ed1a4 100644
--- a/App/backend/src/services/tests/agent-source-auto-inject-service.test.ts
+++ b/App/backend/src/services/tests/agent-source-auto-inject-service.test.ts
@@ -222,7 +222,7 @@ describe("agent source auto inject service", () => {
     ]);
   });
 
-  it("does not refresh installed plugins that are not hooks", async () => {
+  it("refreshes outdated OpenCode plugins without refreshing unrelated plugins", async () => {
     const calls: string[] = [];
     const service = createAgentSourceAutoInjectService({
       agentSources: {
@@ -244,10 +244,10 @@ describe("agent source auto inject service", () => {
     await expect(service.runOnce()).resolves.toEqual({
       ok: true,
       skipped: false,
-      installed: [],
+      installed: ["opencode"],
       failed: []
     });
-    expect(calls).toEqual([]);
+    expect(calls).toEqual(["plugin:opencode:auto_inject"]);
   });
 
   it("skips an outdated hook when the agent is unavailable or not writable", async () => {
diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index 4d0446812..90c0ecd5f 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -873,6 +873,7 @@ export const zhCNMessages = {
   "memory.skillInstalled": "已写入 Skill",
   "memory.hookInstalled": "已安装 Hook",
   "memory.pluginInstalled": "已安装插件",
+  "memory.opencodeReloadHint": "安装或更新 Memmy 插件后，请保存工作并完全退出、重新打开 OpenCode。若使用独立 OpenCode 服务，也需重启该服务。",
   "memory.notConnected": "未接入",
   "memory.agentNotDetected": "未检测到",
   "memory.skillNotInstalled": "未安装 Skill",
@@ -2616,6 +2617,7 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "memory.skillInstalled": "Skill installed",
   "memory.hookInstalled": "Hook installed",
   "memory.pluginInstalled": "Plugin installed",
+  "memory.opencodeReloadHint": "After installing or updating the Memmy plugin, save your work and fully quit and reopen OpenCode. Restart any separate OpenCode server as well.",
   "memory.notConnected": "Not connected",
   "memory.skillNotInstalled": "Skill not installed",
   "memory.hookNotInstalled": "Hook not installed",
diff --git a/App/frontend/desktop/src/pages/memory-sources-page.tsx b/App/frontend/desktop/src/pages/memory-sources-page.tsx
index 176f39b7a..fd60bc249 100644
--- a/App/frontend/desktop/src/pages/memory-sources-page.tsx
+++ b/App/frontend/desktop/src/pages/memory-sources-page.tsx
@@ -856,6 +856,9 @@ export function MemorySourcesContent(props: MemorySourcesContentProps = {}) {
               <AgentSourceLogo source={source} />
               <div className="flex-1 min-w-0">
                 <div className="text-sm font-normal text-text-ink/80">{source.displayName}</div>
+                {source.sourceId === "opencode" && source.status === "plugin_installed" && (
+                  <p className="mt-1 text-xs text-text-ink/60">{t("memory.opencodeReloadHint")}</p>
+                )}
                 <div className="flex items-center gap-2 mt-1">
                   <SourceStatusBadge source={source} />
                   {source.messageCount > 0 && <span className="text-xs text-text-ink/50 shrink-0 whitespace-nowrap">{formatSourceMemoryCount(source.messageCount, t)}</span>}
diff --git a/Memory/src/agent-source/adapters/opencode/db-reader.ts b/Memory/src/agent-source/adapters/opencode/db-reader.ts
index cf5257670..82c0d0e01 100644
--- a/Memory/src/agent-source/adapters/opencode/db-reader.ts
+++ b/Memory/src/agent-source/adapters/opencode/db-reader.ts
@@ -1,9 +1,8 @@
 /** Db reader module. */
-import Database from "better-sqlite3";
+import { DatabaseSync } from "node:sqlite";
 import {
   readOpencodeSessions,
-  type OpencodeSession,
-  type OpencodeSource,
+  createOpencodeDatabaseSource,
   type RawSourceMessage
 } from "@memmy/agent-source-core";
 
@@ -20,9 +19,9 @@ export interface RawOpencodeDatabaseMessage extends RawSourceMessage {
  * turn that is still only in the write-ahead log would be missed.
  */
 export async function* readOpencodeDatabase(path: string, signal?: AbortSignal): AsyncIterable<RawOpencodeDatabaseMessage> {
-  const db = new Database(path, { readonly: true, fileMustExist: true });
+  const db = new DatabaseSync(path, { readOnly: true });
   try {
-    const source = createSource(db);
+    const source = createOpencodeDatabaseSource(db);
     if (!source) return;
     const directories = new Map([...source.sessions()].map((session) => [session.id, session.directory ?? null]));
     for await (const message of readOpencodeSessions(source, signal)) {
@@ -38,52 +37,3 @@ export async function* readOpencodeDatabase(path: string, signal?: AbortSignal):
 export async function* streamOpencodeDatabase(path: string, signal?: AbortSignal): AsyncIterable<RawOpencodeDatabaseMessage> {
   yield* readOpencodeDatabase(path, signal);
 }
-
-/** A database without the conversation tables is not a conversation store. */
-function createSource(db: Database.Database): OpencodeSource | null {
-  if (!hasTable(db, "session") || !hasTable(db, "message") || !hasTable(db, "part")) return null;
-  const columns = tableColumns(db, "session");
-  const sessions = db.prepare(`SELECT id, parent_id AS parentId, directory${columns.has("agent") ? ", agent" : ""}${columns.has("revert") ? ", revert" : ""} FROM session ORDER BY time_created ASC, id ASC`);
-  const messages = db.prepare("SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created ASC, id ASC");
-  const parts = db.prepare("SELECT id, data FROM part WHERE message_id = ? ORDER BY time_created ASC, id ASC");
-  return {
-    sessions: () => (sessions.all() as Array<Record<string, unknown>>).map(toOpencodeSession),
-    messages: (sessionId) => (messages.all(sessionId) as Array<{ id: string; data: string }>)
-      .map((row) => ({ id: row.id, data: parseJson(row.data) })),
-    parts: (messageId) => (parts.all(messageId) as Array<{ id: string; data: string }>)
-      .map((row) => ({ id: row.id, data: parseJson(row.data) }))
-  };
-}
-
-function toOpencodeSession(row: Record<string, unknown>): OpencodeSession {
-  return {
-    id: String(row.id),
-    parentId: row.parentId == null ? null : String(row.parentId),
-    directory: row.directory == null ? null : String(row.directory),
-    agent: typeof row.agent === "string" ? row.agent : null,
-    revertMessageId: revertMessageId(row.revert)
-  };
-}
-
-function revertMessageId(value: unknown): string | null {
-  const parsed = typeof value === "string" ? parseJson(value) : value;
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-  const messageId = (parsed as { messageID?: unknown }).messageID;
-  return typeof messageId === "string" && messageId ? messageId : null;
-}
-
-function tableColumns(db: Database.Database, tableName: string): Set<string> {
-  return new Set((db.prepare(`PRAGMA table_info(${tableName})`).all() as Array<{ name: string }>).map((row) => row.name));
-}
-
-function parseJson(value: string): unknown {
-  try {
-    return JSON.parse(value);
-  } catch {
-    return undefined;
-  }
-}
-
-function hasTable(db: Database.Database, tableName: string): boolean {
-  return Boolean(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(tableName));
-}
diff --git a/Memory/src/agent-source/integration/opencode/target.ts b/Memory/src/agent-source/integration/opencode/target.ts
index 11b4622ac..41e6006d3 100644
--- a/Memory/src/agent-source/integration/opencode/target.ts
+++ b/Memory/src/agent-source/integration/opencode/target.ts
@@ -1,5 +1,6 @@
 /** Target module. */
 import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { resolveOpencodeConfigDirectory } from "../../agent-paths.js";
@@ -18,6 +19,9 @@ const PLUGIN_DIRECTORY_NAME = "plugins";
 const PLUGIN_FILE_NAME = "memmy-memory.js";
 const PLUGIN_CONFIG_FILE_NAME = "memmy-memory-config.json";
 const WORKSPACE_BRIDGE_FILE_NAME = "memmy-workspace-bridge.mjs";
+// Bump when the OpenCode bridge contract changes. Backend/Memory bundles have
+// different bytes, so their valid installations must share a logical revision.
+const OPENCODE_BRIDGE_REVISION = "v2-1";
 const COMMAND_DIRECTORY_NAME = "commands";
 const RESUME_COMMAND_FILE_NAME = "memmy-resume.md";
 const START_MARKER = "<!-- memmy:start v=1 -->";
@@ -70,25 +74,36 @@ export function createOpencodeSkillTarget(deps: CreateOpencodeSkillTargetDeps =
       return (await readTextFile(join(rootDirectory, TARGET_FILE_NAME))).includes(START_MARKER);
     },
 
+    async isInstalledHookCurrent() {
+      const expected = await pluginAssets();
+      const config = await readPluginConfig(join(rootDirectory, PLUGIN_DIRECTORY_NAME, PLUGIN_CONFIG_FILE_NAME));
+      if (config.plugin_revision !== pluginRevision(expected)) return false;
+      const installed: Array<[string, string]> = [];
+      for (const [path, content] of expected) {
+        const actual = await readTextFile(join(rootDirectory, path));
+        if (!actual || (basename(path) !== WORKSPACE_BRIDGE_FILE_NAME && actual !== content)) return false;
+        installed.push([path, actual]);
+      }
+      return config.plugin_integrity === assetRevision(installed);
+    },
+
     async installPlugin(_targetId) {
       await mkdir(rootDirectory, { recursive: true });
       const pluginDirectory = join(rootDirectory, PLUGIN_DIRECTORY_NAME);
       const commandDirectory = join(rootDirectory, COMMAND_DIRECTORY_NAME);
       await mkdir(pluginDirectory, { recursive: true });
       await mkdir(commandDirectory, { recursive: true });
-      await writeFileAtomically(
-        join(pluginDirectory, PLUGIN_CONFIG_FILE_NAME),
-        `${JSON.stringify({
-          memmy_config_path: memmyConfigPath,
-          ...(await readMemmyMemoryServiceConfig(memmyConfigPath))
-        }, null, 2)}\n`
-      );
-      await writeFileAtomically(join(pluginDirectory, PLUGIN_FILE_NAME), renderMemmyOpencodePlugin());
-      await writeFileAtomically(
-        join(pluginDirectory, WORKSPACE_BRIDGE_FILE_NAME),
-        await loadMemmyWorkspaceBridgeRuntimeAsset()
-      );
-      await writeFileAtomically(join(commandDirectory, RESUME_COMMAND_FILE_NAME), renderMemmyOpencodeResumeCommand());
+      const configPath = join(pluginDirectory, PLUGIN_CONFIG_FILE_NAME);
+      // Parse before writing anything. A malformed existing config must not be
+      // silently replaced with empty credentials or defaults.
+      const existingConfig = await readPluginConfig(configPath);
+      const config = {
+        memmy_config_path: memmyConfigPath,
+        ...(await readMemmyMemoryServiceConfig(memmyConfigPath)),
+        ...existingConfig
+      };
+      const assets = await pluginAssets();
+      for (const [path, content] of assets) await writeFileAtomically(join(rootDirectory, path), content);
 
       const manifest = renderMemmyPluginSkillManifest(_targetId);
       const filePath = join(rootDirectory, TARGET_FILE_NAME);
@@ -100,6 +115,10 @@ export function createOpencodeSkillTarget(deps: CreateOpencodeSkillTargetDeps =
         )
       );
       await replaceMemmySkillDirectory(rootDirectory, manifest);
+      // Publish the revision only after every managed file was installed.
+      await writeFileAtomically(configPath, `${JSON.stringify({ ...config,
+        plugin_revision: pluginRevision(assets), plugin_integrity: assetRevision(assets)
+      }, null, 2)}\n`);
     },
 
     async uninstallPlugin(_targetId) {
@@ -122,6 +141,30 @@ export function createOpencodeSkillTarget(deps: CreateOpencodeSkillTargetDeps =
   };
 }
 
+async function pluginAssets(): Promise<Array<[string, string]>> {
+  return [
+    [join(PLUGIN_DIRECTORY_NAME, PLUGIN_FILE_NAME), renderMemmyOpencodePlugin()],
+    [join(PLUGIN_DIRECTORY_NAME, WORKSPACE_BRIDGE_FILE_NAME), await loadMemmyWorkspaceBridgeRuntimeAsset()],
+    [join(COMMAND_DIRECTORY_NAME, RESUME_COMMAND_FILE_NAME), renderMemmyOpencodeResumeCommand()]
+  ];
+}
+
+function assetRevision(assets: Array<[string, string]>): string {
+  return createHash("sha256").update(JSON.stringify(assets.map(([, content]) => content))).digest("hex");
+}
+
+function pluginRevision(assets: Array<[string, string]>): string {
+  return OPENCODE_BRIDGE_REVISION + ":" + assetRevision(assets.filter(([path]) => basename(path) !== WORKSPACE_BRIDGE_FILE_NAME));
+}
+
+async function readPluginConfig(path: string): Promise<Record<string, unknown>> {
+  const content = await readTextFile(path);
+  if (!content.trim()) return {};
+  const value: unknown = JSON.parse(content);
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid Memmy OpenCode plugin config");
+  return value as Record<string, unknown>;
+}
+
 async function readTextFile(filePath: string): Promise<string> {
   try {
     return await readFile(filePath, "utf8");
diff --git a/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts b/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
index 9ace951b2..a6aabc60e 100644
--- a/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
+++ b/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
@@ -5,8 +5,9 @@ export function renderMemmyOpencodePlugin(): string {
   return String.raw`import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { tool } from "@opencode-ai/plugin";
 import {
+  opencodeTool as tool,
+  opencodeToolJsonSchema,
   closeRuntimeSession,
   completeSourceTurn,
   loadRuntimeL3,
@@ -25,8 +26,94 @@ const DISPLAY_LIMIT = 5;
 const RESUME_STATE_TTL_MS = 10 * 60 * 1000;
 const RESUME_CONTEXT_MAX_CHARS = 24000;
 const TOOL_OUTPUT_MAX_CHARS = 12000;
+const PLUGIN_REVISION = "opencode-v2-1";
+
+// A single default export prevents V1 from registering the same plugin twice.
+// The schema helper is bundled in our bridge; neither host needs the other SDK.
+export default {
+  id: "memmy-memory",
+  async server(input) {
+    const hooks = await createMemmyHooks(input);
+    console.error("Memmy plugin loaded: revision=" + PLUGIN_REVISION + ", entry=v1");
+    return hooks;
+  },
+  async setup(ctx) {
+    const hooks = await createMemmyHooks({ directory: ctx.location.directory });
+    const controller = new AbortController();
+    const registrations = [];
+    let events;
+    let cleanupPromise;
+    const cleanup = () => cleanupPromise || (cleanupPromise = (async () => {
+      controller.abort();
+      await Promise.allSettled(registrations.map((registration) => registration.dispose()));
+      await events;
+      await hooks.dispose();
+    })());
+    try {
+      registrations.push(await ctx.tool.transform((editor) => {
+        for (const [name, definition] of Object.entries(hooks.tool)) {
+          editor.add({
+            name,
+            description: definition.description,
+            input: opencodeToolJsonSchema(definition.args),
+            async execute(input, context) {
+              return { content: await definition.execute(input, context) };
+            }
+          });
+        }
+      }));
+      registrations.push(await ctx.session.hook("prompt", async (event) => {
+        if (controller.signal.aborted) return;
+        try {
+          const parts = [{ type: "text", text: event.prompt.text }];
+          // Agent selection lives on the V2 session, not on SessionPrompt.
+          const session = await ctx.session.get({ sessionID: event.sessionID });
+          if (session.parentID) return;
+          await hooks["chat.message"](
+            { sessionID: event.sessionID, messageID: event.messageID, agent: session.agent },
+            { message: { id: event.messageID }, parts }
+          );
+          event.prompt.text = extractUserText(parts);
+        } catch (error) {
+          console.warn("Memmy prompt recall skipped: " + formatError(error));
+        }
+      }));
+      registrations.push(await ctx.command.transform((editor) => editor.add({
+        name: "memmy-resume",
+        description: "Search and resume a previous Memmy episode",
+        async execute({ sessionID, prompt, delivery }) {
+          await ctx.session.prompt({ ...prompt, sessionID, delivery,
+            text: "MEMMY_RESUME_COMMAND_ARGUMENTS: " + prompt.text + "\nMEMMY_RESUME_COMMAND_END" });
+        }
+      })));
+      events = (async () => {
+        try {
+          for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+            if (controller.signal.aborted) break;
+            if (!["session.created", "session.compacted", "session.deleted", "session.idle", "session.status"].includes(event.type)) continue;
+            const properties = event.data || {};
+            if (properties.parentID) continue;
+            if (event.type === "session.status" && properties.status?.type !== "idle") continue;
+            try {
+              await hooks.event({ event: { type: event.type === "session.status" ? "session.idle" : event.type, properties } });
+            } catch (error) {
+              console.warn("Memmy event failed: " + formatError(error));
+            }
+          }
+        } catch (error) {
+          if (!controller.signal.aborted) console.warn("Memmy event subscription failed: " + formatError(error));
+        }
+      })();
+      console.error("Memmy plugin loaded: revision=" + PLUGIN_REVISION + ", entry=v2");
+      return cleanup;
+    } catch (error) {
+      await cleanup();
+      throw error;
+    }
+  }
+};
 
-export const MemmyMemoryPlugin = async ({ client, directory, worktree }) => {
+const createMemmyHooks = async ({ client, directory, worktree }) => {
   const sessionCache = new Map();
   const l3InjectOnce = new Map();
   const pendingTurns = new Map();
@@ -54,6 +141,17 @@ export const MemmyMemoryPlugin = async ({ client, directory, worktree }) => {
     }
   }
 
+  async function closeSession(sessionID) {
+    for (const [key, session] of sessionCache) {
+      if (!key.startsWith(sessionID + ":")) continue;
+      sessionCache.delete(key);
+      await closeRuntimeSession(session).catch(() => undefined);
+    }
+    l3InjectOnce.delete(sessionID);
+    pendingResumeSelections.delete(sessionID);
+    latestRequests.delete(sessionID);
+  }
+
   async function ensureSession(memmy, externalSessionId, agent) {
     const profileId = normalizeText(agent) || "main";
     const cacheKey = externalSessionId + ":" + profileId;
@@ -372,7 +470,7 @@ export const MemmyMemoryPlugin = async ({ client, directory, worktree }) => {
       }
       if (event && event.type === "session.compacted") {
         const sessionID = normalizeText(properties.sessionID || properties.id);
-        const runtimeSession = sessionCache.get(sessionID) || await ensureSession(null, sessionID, "main");
+        const runtimeSession = await ensureSession(null, sessionID, "main");
         await notifyRuntimeBoundary(runtimeSession, "token_compaction");
         const loaded = await loadRuntimeL3(runtimeSession);
         if (loaded.additionalContext) l3InjectOnce.set(sessionID, loaded.additionalContext);
@@ -381,10 +479,7 @@ export const MemmyMemoryPlugin = async ({ client, directory, worktree }) => {
       if (event && event.type === "session.deleted") {
         const sessionID = normalizeText(properties.sessionID || properties.id);
         queueTurnCompletion(sessionID);
-        const runtimeSession = sessionCache.get(sessionID);
-        if (runtimeSession) await closeRuntimeSession(runtimeSession).catch(() => undefined);
-        sessionCache.delete(sessionID);
-        l3InjectOnce.delete(sessionID);
+        await closeSession(sessionID);
         return;
       }
       if (event && event.type === "message.part.updated") {
@@ -422,6 +517,9 @@ export const MemmyMemoryPlugin = async ({ client, directory, worktree }) => {
       await Promise.allSettled([...sessionCache.values()].map((session) => closeRuntimeSession(session)));
       sessionCache.clear();
       l3InjectOnce.clear();
+      pendingResumeSelections.clear();
+      latestRequests.clear();
+      console.error("Memmy plugin disposed: revision=" + PLUGIN_REVISION);
     }
   };
 };
diff --git a/Memory/src/agent-source/integration/types.ts b/Memory/src/agent-source/integration/types.ts
index 9ec21586a..a1c8cd20e 100644
--- a/Memory/src/agent-source/integration/types.ts
+++ b/Memory/src/agent-source/integration/types.ts
@@ -25,5 +25,6 @@ export interface SkillTarget {
   isInstalled(targetId: string): Promise<boolean>;
   installPlugin?(targetId: string): Promise<void>;
   uninstallPlugin?(targetId: string): Promise<void>;
+  isInstalledHookCurrent?(): Promise<boolean>;
   detectMemoryPluginConflict?(): Promise<MemoryPluginConflict | null>;
 }
diff --git a/Memory/src/agent-source/integration/workspace-bridge/runtime.ts b/Memory/src/agent-source/integration/workspace-bridge/runtime.ts
index 70e25f49e..3527c4c70 100644
--- a/Memory/src/agent-source/integration/workspace-bridge/runtime.ts
+++ b/Memory/src/agent-source/integration/workspace-bridge/runtime.ts
@@ -11,7 +11,7 @@ import {
   readOpencodeSourceTurn,
   type CursorVscdbSource,
   type OpenclawTranscriptSource,
-  type OpencodeSource,
+  createOpencodeDatabaseSource,
   type SourceTurn
 } from "@memmy/agent-source-core";
 export { readClaudeCodeSourceTurn, readCodexSourceTurn } from "@memmy/agent-source-core";
@@ -28,6 +28,14 @@ import { homedir } from "node:os";
 import { isAbsolute, parse, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import YAML from "yaml";
+import { z } from "zod";
+
+/** OpenCode V1 tools are plain definitions containing real Zod schemas. Bundle them
+ * locally so installing Memmy never depends on the host's SDK package resolution. */
+export const opencodeTool = Object.assign(<T>(definition: T): T => definition, { schema: z });
+export function opencodeToolJsonSchema(args: Record<string, z.ZodType>): Record<string, unknown> {
+  return z.toJSONSchema(z.object(args));
+}
 import {
   normalizeWorkspaceUri,
   renderL3WorldModelContext,
@@ -412,37 +420,8 @@ export async function readOpencodeHookSourceTurn(input: {
     return { turn: null, reason: "source_store_unavailable" };
   }
   try {
-    const columns = new Set((db.prepare("PRAGMA table_info(session)").all() as Array<{ name: string }>).map((row) => row.name));
-    const sessions = db.prepare(`SELECT id, parent_id AS parentId, directory${columns.has("agent") ? ", agent" : ""}${columns.has("revert") ? ", revert" : ""} FROM session WHERE id = ?`);
-    const messages = db.prepare("SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created ASC, id ASC");
-    const parts = db.prepare("SELECT id, data FROM part WHERE message_id = ? ORDER BY time_created ASC, id ASC");
-    const parse = (value: unknown): unknown => {
-      if (typeof value !== "string") return undefined;
-      try {
-        return JSON.parse(value);
-      } catch {
-        return undefined;
-      }
-    };
-    const source: OpencodeSource = {
-      sessions: () => (sessions.all(input.conversationId) as unknown as Array<Record<string, unknown>>).map((row) => {
-        const revert = typeof row.revert === "string" ? parse(row.revert) : row.revert;
-        const messageId = revert && typeof revert === "object" && !Array.isArray(revert)
-          ? (revert as { messageID?: unknown }).messageID
-          : undefined;
-        return {
-          id: String(row.id),
-          parentId: row.parentId == null ? null : String(row.parentId),
-          directory: row.directory == null ? null : String(row.directory),
-          agent: typeof row.agent === "string" ? row.agent : null,
-          revertMessageId: typeof messageId === "string" && messageId ? messageId : null
-        };
-      }),
-      messages: (sessionId) => (messages.all(sessionId) as unknown as Array<{ id: string; data: string }>)
-        .map((row) => ({ id: row.id, data: parse(row.data) })),
-      parts: (messageId) => (parts.all(messageId) as unknown as Array<{ id: string; data: string }>)
-        .map((row) => ({ id: row.id, data: parse(row.data) }))
-    };
+    const source = createOpencodeDatabaseSource(db, input.conversationId);
+    if (!source) return { turn: null, reason: "source_store_unavailable" };
     return await readOpencodeSourceTurn(source, input);
   } finally {
     db.close();
diff --git a/Memory/src/agent-source/runtime.ts b/Memory/src/agent-source/runtime.ts
index 863404f00..f075860ab 100644
--- a/Memory/src/agent-source/runtime.ts
+++ b/Memory/src/agent-source/runtime.ts
@@ -554,6 +554,29 @@ export function createAgentSourceExecutor(options: CreateAgentSourceExecutorOpti
   async function runAutomation(startup: boolean): Promise<void> {
     if (disposed || scan.running) return;
     const config = loadMemmyConfig(configPath).config.agentAccess;
+    // Refresh an existing connection even when automatic *new* connections are
+    // disabled. Explicit removal remains authoritative.
+    const refreshTarget = integrationRegistry.get("opencode");
+    if (registry.get("opencode") && refreshTarget?.isInstalledHookCurrent) {
+      const stateBeforeRefresh = await readState();
+      if (!stateBeforeRefresh.sources.opencode?.autoInjectSuppressed
+        && (stateBeforeRefresh.sources.opencode?.status === "plugin_installed" || await refreshTarget.isInstalled("opencode"))) {
+        try {
+          if (!(await refreshTarget.isInstalledHookCurrent())) {
+            const latestState = await readState();
+            if (!disposed && !latestState.sources.opencode?.autoInjectSuppressed) {
+              await mutateConnection("opencode", "plugin", "POST", "auto_inject");
+              const installedState = await readState();
+              if (installedState.sources.opencode?.autoInjectSuppressed) {
+                await mutateConnection("opencode", "plugin", "DELETE", "auto_inject");
+              }
+            }
+          }
+        } catch (error) {
+          logger.warn("connection.auto_update_failed", { sourceId: "opencode", ...memoryErrorFields(error) });
+        }
+      }
+    }
     if (config.autoInjectSkill) {
       const state = await readState();
       const discovered = await list();
diff --git a/Memory/tests/agent-source-runtime.test.ts b/Memory/tests/agent-source-runtime.test.ts
index 1c87afb6d..51cf65e67 100644
--- a/Memory/tests/agent-source-runtime.test.ts
+++ b/Memory/tests/agent-source-runtime.test.ts
@@ -22,6 +22,39 @@ afterEach(() => {
 });
 
 describe("standalone Agent source executor", () => {
+  it.each([[false, true], [true, true], [false, false]])("refreshes installed OpenCode with auto injection disabled, removal=%s, storedState=%s", async (removed, storedState) => {
+    const root = tempRoot();
+    const configPath = join(root, "config.yaml");
+    const statePath = join(root, "agent-sources.json");
+    writeFileSync(configPath, JSON.stringify({ memmyMemory: { agentAccess: {
+      autoScanKnownAgents: false, watchFileChanges: false, autoInjectSkill: false
+    } } }));
+    writeFileSync(statePath, JSON.stringify({ version: 2, sources: storedState ? { opencode: {
+      status: "plugin_installed", autoInjectSuppressed: removed, messageCount: 0, lastScannedAt: null, latestSeenAt: null
+    } } : {} }));
+    const installPlugin = vi.fn(async () => {});
+    const isInstalledHookCurrent = vi.fn(async () => installPlugin.mock.calls.length > 0);
+    const target: SkillTarget = {
+      targetId: "opencode", displayName: "OpenCode", async resolveRootDirectory() { return root; },
+      async install() {}, async uninstall() {}, async isInstalled() { return true; },
+      installPlugin, isInstalledHookCurrent
+    };
+    const executor = createAgentSourceExecutor({
+      service: {} as MemoryService, configPath, statePath, initialScanDelayMs: 0, scheduledScanIntervalMs: 10,
+      sourceRegistry: createSourceRegistry([{
+        descriptor: { sourceId: "opencode", displayName: "OpenCode", builtin: true, dataPath: root },
+        detect: async () => true, async *scan() {}
+      }]),
+      integrationRegistry: createSkillTargetRegistry([target])
+    });
+    try {
+      executor.startAutomation();
+      if (!removed) await vi.waitFor(() => expect(isInstalledHookCurrent.mock.calls.length).toBeGreaterThan(1));
+      else await new Promise(resolve => setTimeout(resolve, 60));
+      expect(installPlugin).toHaveBeenCalledTimes(removed ? 0 : 1);
+    } finally { await executor.dispose(); }
+  });
+
   it("also waits for a canceled scan when a replacement scan starts before disposal", async () => {
     const root = tempRoot();
     let finishFirst!: () => void;
diff --git a/Memory/viewer/src/stores/i18n.ts b/Memory/viewer/src/stores/i18n.ts
index 386498418..87aa19950 100644
--- a/Memory/viewer/src/stores/i18n.ts
+++ b/Memory/viewer/src/stores/i18n.ts
@@ -1032,6 +1032,7 @@ const en = {
   "settings.agents.skillInstalled": "Skill installed",
   "settings.agents.hookInstalled": "Hook installed",
   "settings.agents.pluginInstalled": "Plugin installed",
+  "settings.agents.opencodeReloadHint": "After installing or updating the Memmy plugin, save your work and fully quit and reopen OpenCode. Restart any separate OpenCode server as well.",
   "settings.agents.skillNotInstalled": "Skill not installed",
   "settings.agents.hookNotInstalled": "Hook not installed",
   "settings.agents.pluginNotInstalled": "Plugin not installed",
@@ -1984,6 +1985,7 @@ const zh: Record<TranslationKey, string> = {
   "settings.agents.skillInstalled": "已写入 Skill",
   "settings.agents.hookInstalled": "已安装 Hook",
   "settings.agents.pluginInstalled": "已安装插件",
+  "settings.agents.opencodeReloadHint": "安装或更新 Memmy 插件后，请保存工作并完全退出、重新打开 OpenCode。若使用独立 OpenCode 服务，也需重启该服务。",
   "settings.agents.skillNotInstalled": "未安装 Skill",
   "settings.agents.hookNotInstalled": "未安装 Hook",
   "settings.agents.pluginNotInstalled": "未安装插件",
diff --git a/Memory/viewer/src/views/SettingsView.tsx b/Memory/viewer/src/views/SettingsView.tsx
index 59e776b4d..ceb452cef 100644
--- a/Memory/viewer/src/views/SettingsView.tsx
+++ b/Memory/viewer/src/views/SettingsView.tsx
@@ -1468,6 +1468,9 @@ function AgentAccessTab({
                         {t("settings.agents.memoryCount", { count: source.messageCount })}
                         {source.dataPath ? ` · ${source.dataPath}` : ""}
                       </p>
+                      {source.sourceId === "opencode" && source.status === "plugin_installed" && (
+                        <p class="card__subtitle">{t("settings.agents.opencodeReloadHint")}</p>
+                      )}
                     </div>
                   </div>
                   <div class="hstack" style="gap:var(--sp-2);flex-shrink:0">
diff --git a/docs/opencode-v2-validation.txt b/docs/opencode-v2-validation.txt
new file mode 100644
index 000000000..d2fdf116a
--- /dev/null
+++ b/docs/opencode-v2-validation.txt
@@ -0,0 +1,72 @@
+Bug 678 — OpenCode V1/V2 compatibility and upgrade validation
+
+Support scope
+V1 minimum target: 1.18.29. Regression binaries: 1.18.29, 1.19.2, V2 2.0.26.
+Earlier V1 and other V2 releases are not claimed as verified.
+Official migration reference: https://dev.opencode.ai/v2/docs/build/plugins/migrate-v1
+
+Implementation
+- One default export: V1 calls server(), V2 calls setup(). The V2 adapter registers
+  JSON Schema tools, the prompt hook, the memmy-resume command and event subscription.
+- The bridge bundles real Zod schemas. No runtime import of either host's SDK is
+  necessary. V1 receives Zod arguments; V2 receives JSON Schema and structured output.
+- Plugin capture and offline scanning use the same V1/V2 database adapter. V2 uses
+  session_v2/session_message; native user message IDs remain the source-turn identity.
+- Backend and Memory installers preserve existing connection config and unknown
+  fields. Malformed config aborts the update without overwriting the old plugin.
+- plugin_revision combines plugin/command content with OPENCODE_BRIDGE_REVISION.
+  Bump OPENCODE_BRIDGE_REVISION in BOTH targets whenever the OpenCode bridge contract
+  changes. plugin_integrity verifies the actual installed artifacts. This allows
+  Backend and Memory bundles to differ without repeatedly replacing each other.
+- Revision/integrity are written last. Missing or modified managed files trigger
+  repair. User removal suppression remains authoritative.
+- Both UIs show a restart instruction for connected OpenCode. This is guidance,
+  not a claim that the currently running OpenCode process has reloaded the plugin.
+
+Automated checks
+  npm run test:opencode
+  npm run lint
+  npm run typecheck
+  npm test
+
+The ordinary compatibility tests exercise real installed bridge/schema code with
+controlled HTTP/event fixtures. They do NOT replace the real-loader check below.
+
+Real loader check (macOS/Linux shell; substitute actual absolute binary paths)
+Install official pinned CLIs into separate temporary prefixes, not the user's
+global OpenCode installation. V1 package: opencode-ai. V2 package: @opencode/cli.
+Set OPENCODE_TEST_BINARIES to a JSON map such as:
+  {"1.18.29":"/absolute/v1/bin/opencode","1.19.2":"/absolute/recent-v1/bin/opencode","2.0.26":"/absolute/v2/bin/opencode"}
+Then run:
+  node --import tsx scripts/test-opencode-loader.mjs
+
+The script uses independent XDG/config/project directories and a local fixture
+Memory HTTP service. It checks the reported CLI version, actual plugin initialization,
+and V2's real tool registry, prompt recall request and cleanup. It deliberately uses
+an unavailable model: the model error is expected and no model call is made. The
+script prints the evidence directory containing process logs and fixture requests.
+This proves host integration, not complete model conversation or packaged GUI behavior.
+
+Packaged acceptance (next phase, after user confirmation)
+1. Prepare an isolated old-plugin installation with a valid test Memmy connection,
+   a separate third-party plugin, custom OpenCode settings and AGENTS.md content.
+2. Install/start the packaged repaired Memmy. Confirm the already-connected OpenCode
+   plugin is refreshed without removing/reconnecting it. Compare endpoint, token,
+   config path and other user files locally; never print tokens in evidence logs.
+3. Save work, fully quit and reopen OpenCode. If it uses a separate server, restart
+   the server that loads the plugin too. Do not treat a new chat/window refresh as
+   sufficient until verified on that exact version.
+4. Look for "Memmy plugin loaded: revision=opencode-v2-1, entry=v1/v2" in stderr or
+   host logs. Lifecycle diagnostics use stderr because V2 can consume stdout.
+5. Exercise search/get/add, pre-turn recall, completed conversation capture and
+   /memmy-resume search plus selection. Verify one completed turn is stored once,
+   including after a history scan. Check non-Memmy tools still work.
+6. Fully quit/reopen again. On V2 verify the disposed log and no duplicate tools,
+   callbacks or captures. A forced process kill is not a graceful cleanup test.
+7. Repeat update: no duplicate config sections, no repeated replacement across the
+   Backend/Memory installation paths. Remove the integration and restart Memmy:
+   it must remain removed. Also test missing bridge and malformed config recovery.
+8. Run the Windows OpenCode Desktop 2.0.26 reproduction separately; macOS CLI
+   results do not constitute Windows Desktop acceptance.
+
+No data migration or user-database writes are needed for the read-only V2 adapter.
diff --git a/package.json b/package.json
index 383e21434..87bdfbfa9 100644
--- a/package.json
+++ b/package.json
@@ -26,7 +26,7 @@
     "build": "npm run memory:build && npm run workspace:build",
     "lint": "npm run memory:lint && npm run workspace:lint",
     "typecheck": "npm run memory:lint && npm run workspace:typecheck",
-    "test": "npm run test:release-workflow && npm run test:packaging-guards && npm run test:contracts && npm run memory:test && npm run workspace:test && npm run agent:test:tui-cursor",
+    "test": "npm run test:release-workflow && npm run test:packaging-guards && npm run test:contracts && npm run test:opencode && npm run memory:test && npm run workspace:test && npm run agent:test:tui-cursor",
     "test:release-workflow": "vitest run tests/release-workflow.test.ts tests/oss-crc64.test.mjs tests/windows-memory-workflow.test.ts",
     "test:packaging-guards": "vitest run tests/package-version-guard.test.mjs tests/packaged-runtime-config.test.mjs tests/open-computer-use-packaging.test.mjs tests/computer-history-packaging.test.mjs tests/prune-packaged-runtime.test.mjs tests/package-logging.test.mjs tests/runtime-bundle.test.ts",
     "test:linux-cli": "vitest run tests/linux-cli-packaging.test.mjs tests/linux-open-computer-use-bundle.test.mjs tests/linux-computer-use-deps.test.mjs && npm --prefix App/memmy-agent exec vitest run tests/entrypoints/cli/linux-systemd-gateway.test.ts tests/entrypoints/cli/gateway-lifecycle.test.ts tests/entrypoints/cli/root-terminal-options.test.ts tests/entrypoints/cli/terminal-target.test.ts tests/tools/computer-use/mac-permission-settings.test.ts tests/tools/computer-use/mac-permission-preflight.test.ts && npm --prefix Memory test -- tests/cli-setup.test.ts",
@@ -79,6 +79,7 @@
     "workspace:typecheck": "npm run typecheck --workspaces --if-present",
     "workspace:test": "npm run test --workspaces --if-present",
     "db:migrate": "npm run db:migrate -w @memmy/backend",
+    "test:opencode": "npm run build -w @memmy/agent-source-core && npm run build -w @memmy/local-api-contracts && npm run workspace-bridge:build -w @memmy/backend && npm run integration:build -w @memmy/memory && vitest run tests/opencode-compatibility.test.mjs",
     "test:contracts": "vitest run tests/computer-history-contract.test.ts"
   },
   "engines": {
diff --git a/scripts/test-opencode-loader.mjs b/scripts/test-opencode-loader.mjs
new file mode 100644
index 000000000..2e8556693
--- /dev/null
+++ b/scripts/test-opencode-loader.mjs
@@ -0,0 +1,84 @@
+/** Opt-in integration check against official, pinned CLI binaries. No SDK or
+ * loader mocks. Run with `node --import tsx scripts/test-opencode-loader.mjs`.
+ * OPENCODE_TEST_BINARIES is a JSON map of exact version to absolute binary path.
+ */
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import assert from "node:assert/strict";
+import { createOpencodeSkillTarget as backend } from "../App/backend/src/adapters/outbound/skill-writer/opencode/target.ts";
+import { createOpencodeSkillTarget as memory } from "../Memory/src/agent-source/integration/opencode/target.ts";
+
+const binaries = JSON.parse(process.env.OPENCODE_TEST_BINARIES || "{}");
+assert(Object.keys(binaries).length, "Set OPENCODE_TEST_BINARIES to pinned official V1/V2 binaries");
+const root = await mkdtemp(join(tmpdir(), "memmy-opencode-loader-"));
+console.log("Isolated loader evidence:", root);
+for (const [version, binary] of Object.entries(binaries)) {
+  for (const [name, factory] of [["Backend", backend], ["Memory", memory]]) {
+    const dir = join(root, version, name);
+    const config = join(dir, "config/opencode");
+    const project = join(dir, "project"); await mkdir(project, { recursive: true });
+    // A local fixture service records real host callbacks; no user Memory service.
+    const calls = [];
+    const server = createServer(async (request, response) => {
+      let raw = "";
+      for await (const chunk of request) raw += chunk;
+      calls.push({ path: request.url, body: raw ? JSON.parse(raw) : {} });
+      let result;
+      if (request.url === "/api/v1/sessions/open") result = { sessionId: "fixture-session" };
+      if (request.url === "/api/v1/turns/start") result = { turnId: "fixture-turn", injectedContext: { markdown: "MEMMY_TEST_RECALL" } };
+      response.writeHead(result ? 200 : 404, { "content-type": "application/json" });
+      response.end(JSON.stringify(result || {}));
+    });
+    await new Promise(resolve => server.listen(0, "127.0.0.1", resolve));
+    try {
+      const yaml = join(dir, "memmy.yaml");
+      await writeFile(yaml, `memmyMemory:\n  storage:\n    endpoint: http://127.0.0.1:${server.address().port}\n`);
+      await factory({ rootDirectory: config, memmyConfigPath: yaml }).installPlugin("opencode");
+      const v2 = version.startsWith("2.");
+      if (v2) await writeFile(join(config, "plugins/zz-loader-check.js"), `export default {
+        id: "memmy-loader-check", async setup(ctx) {
+          const tools = await ctx.tool.list();
+          for (const name of ["memmy_memory_search", "memmy_memory_get", "memmy_memory_add"]) {
+            if (!tools.some(tool => tool.name === name || tool.id === name)) throw new Error("Missing tool " + name);
+          }
+          console.error("MEMMY_REAL_V2_TOOLS_OK");
+        }
+      };`);
+      const env = { ...process.env, PWD: project, OPENCODE_CONFIG_DIR: config,
+        XDG_CONFIG_HOME: join(dir, "config"), XDG_DATA_HOME: join(dir, "data"),
+        XDG_CACHE_HOME: join(dir, "cache"), XDG_STATE_HOME: join(dir, "state") };
+      const reported = await run(resolve(binary), ["--version"], env, project);
+      assert.equal(reported.output.trim().replace(/^opencode v/, ""), version);
+      // The nonexistent model deliberately stops after initialization, with no LLM request.
+      const result = await run(resolve(binary), ["run", ...(v2 ? ["--standalone"] : []),
+        "--model", "memmy-loader-check/no-model", "--print-logs", "--log-level", v2 ? "debug" : "DEBUG", "loader check"], env, project);
+      await writeFile(join(dir, "process.log"), result.output);
+      assert(!result.timeout, `${version}/${name}: timed out`);
+      assert(result.output.includes(`entry=${v2 ? "v2" : "v1"}`), `${version}/${name}: missing actual plugin initialization`);
+      assert(!/failed to load plugin|Cannot find package/.test(result.output), `${version}/${name}: plugin loading error`);
+      if (v2) {
+        assert(result.output.includes("MEMMY_REAL_V2_TOOLS_OK"), `${version}/${name}: tools absent from real registry`);
+        assert(result.output.includes("Memmy plugin disposed:"), `${version}/${name}: cleanup did not finish`);
+      }
+      await writeFile(join(dir, "fixture-requests.json"), JSON.stringify(calls, null, 2));
+      if (v2) assert(calls.some(call => call.path === "/api/v1/turns/start"), `${version}/${name}: actual prompt hook did not recall memory`);
+      assert(/Model.*not found|ModelUnavailable|ProviderModelNotFound|Unknown model/i.test(result.output), "Expected intentional unavailable model termination");
+      console.log(`${version}/${name}: real loader passed (model intentionally unavailable)`);
+    } finally { await new Promise(resolve => server.close(resolve)); }
+  }
+}
+
+function run(binary, args, env, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let output = "", timeout = false;
+    child.stdout.on("data", chunk => output += chunk);
+    child.stderr.on("data", chunk => output += chunk);
+    const timer = setTimeout(() => { timeout = true; child.kill("SIGTERM"); }, 45000);
+    child.on("error", error => { clearTimeout(timer); reject(error); });
+    child.on("close", code => { clearTimeout(timer); resolve({ output, timeout, code }); });
+  });
+}
diff --git a/tests/opencode-compatibility.test.mjs b/tests/opencode-compatibility.test.mjs
new file mode 100644
index 000000000..7a7e7d29a
--- /dev/null
+++ b/tests/opencode-compatibility.test.mjs
@@ -0,0 +1,182 @@
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, describe, it, expect, vi } from "vitest";
+import { createOpencodeSkillTarget as backend } from "../App/backend/src/adapters/outbound/skill-writer/opencode/target.ts";
+import { createOpencodeSkillTarget as memory } from "../Memory/src/agent-source/integration/opencode/target.ts";
+import { readOpencodeDatabase } from "../Memory/src/agent-source/adapters/opencode/db-reader.ts";
+import { selectSourceTurn } from "../AgentSourceCore/src/source-turn.ts";
+
+const roots = [];
+afterEach(() => {
+  vi.restoreAllMocks(); vi.unstubAllGlobals(); vi.unstubAllEnvs();
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+function fixture(factory) {
+  const root = mkdtempSync(join(tmpdir(), "memmy-opencode-upgrade-")); roots.push(root);
+  return { root, target: factory({ rootDirectory: root, memmyConfigPath: join(root, "missing.yaml") }) };
+}
+async function load(root) {
+  // Import the installed artifact unchanged: real bridge, real Zod, no SDK substitution.
+  const source = readFileSync(join(root, "plugins/memmy-memory.js"), "utf8");
+  const path = join(root, "plugins/test-runtime.mjs"); writeFileSync(path, source);
+  return (await import(pathToFileURL(path).href)).default;
+}
+
+describe.each([["Backend", backend], ["Memory", memory]])("%s OpenCode upgrade", (_, factory) => {
+  it("refreshes old files, preserves connection settings and other plugins, and detects partial updates", async () => {
+    const { root, target } = fixture(factory);
+    mkdirSync(join(root, "plugins"));
+    const original = { endpoint: "http://127.0.0.1:19991", token: "fixture-token", memmy_config_path: join(root, "custom.yaml"), custom: { enabled: true } };
+    const config = join(root, "plugins/memmy-memory-config.json");
+    writeFileSync(config, JSON.stringify(original));
+    writeFileSync(join(root, "plugins/memmy-memory.js"), "old plugin");
+    writeFileSync(join(root, "plugins/other.js"), "other plugin");
+    writeFileSync(join(root, "opencode.jsonc"), "// custom model settings\n{}");
+    writeFileSync(join(root, "AGENTS.md"), "user instructions\n");
+    expect(await target.isInstalledHookCurrent()).toBe(false);
+    await target.installPlugin("opencode");
+    expect(JSON.parse(readFileSync(config, "utf8"))).toMatchObject(original);
+    expect(await target.isInstalledHookCurrent()).toBe(true);
+    const otherPath = (factory === backend ? memory : backend)({ rootDirectory: root });
+    expect(await otherPath.isInstalledHookCurrent()).toBe(true);
+    const installed = readFileSync(config, "utf8");
+    await target.installPlugin("opencode");
+    expect(readFileSync(config, "utf8")).toBe(installed);
+    expect(readFileSync(join(root, "plugins/other.js"), "utf8")).toBe("other plugin");
+    expect(readFileSync(join(root, "opencode.jsonc"), "utf8")).toBe("// custom model settings\n{}");
+    expect(readFileSync(join(root, "AGENTS.md"), "utf8").match(/memmy:start/g)).toHaveLength(1);
+    writeFileSync(join(root, "plugins/memmy-workspace-bridge.mjs"), "partial write");
+    expect(await target.isInstalledHookCurrent()).toBe(false);
+    await target.installPlugin("opencode");
+    expect(await target.isInstalledHookCurrent()).toBe(true);
+    rmSync(join(root, "commands/memmy-resume.md"));
+    expect(await target.isInstalledHookCurrent()).toBe(false);
+  });
+
+  it("does not overwrite a malformed user config or publish a new revision", async () => {
+    const { root, target } = fixture(factory);
+    mkdirSync(join(root, "plugins"));
+    writeFileSync(join(root, "plugins/memmy-memory-config.json"), "{broken");
+    writeFileSync(join(root, "plugins/memmy-memory.js"), "old");
+    await expect(target.installPlugin("opencode")).rejects.toThrow();
+    expect(readFileSync(join(root, "plugins/memmy-memory.js"), "utf8")).toBe("old");
+  });
+
+  it("registers V2 tools, recalls, captures the V2 database once, resumes, and cleans up", async () => {
+    const { root, target } = fixture(factory);
+    await target.installPlugin("opencode");
+    const plugin = await load(root);
+    const requests = [];
+    vi.stubGlobal("fetch", vi.fn(async (url, init) => {
+      const path = new URL(url).pathname;
+      const body = init?.body ? JSON.parse(init.body) : {};
+      requests.push({ path, body });
+      const data = path === "/api/v1/sessions/open" ? { sessionId: "memmy-session" }
+        : path === "/api/v1/turns/start" ? { turnId: body.turnId, injectedContext: { markdown: "Remembered preference" } }
+        : path === "/api/v1/memory/search" ? { debug: { hits: [{ id: "trace-1", score: 1 }] } }
+        : path === "/api/v1/memory/trace-1" ? { id: "trace-1", summary: "Remembered", refs: { episode: { id: "episode-1", title: "Task" } } }
+        : path === "/api/v1/memory/episode-1" ? { id: "episode-1", title: "Task", body: "Episode detail" }
+        : path === "/api/v1/memory/add" ? { id: "new-memory" }
+        : { status: "stored" };
+      return new Response(JSON.stringify(data), { headers: { "content-type": "application/json" } });
+    }));
+    const dataHome = join(root, "data"); vi.stubEnv("XDG_DATA_HOME", dataHome);
+    const dbPath = writeV2Fixture(dataHome);
+    const tools = new Map(); let promptHook; let command; let signal; let deliver;
+    const disposals = [];
+    const registration = () => { const dispose = vi.fn(); disposals.push(dispose); return { dispose }; };
+    const ctx = {
+      location: { directory: root },
+      tool: { async transform(fn) { fn({ add(t) { tools.set(t.name, t); } }); return registration(); } },
+      command: { async transform(fn) { fn({ add(c) { command = c; } }); return registration(); } },
+      session: {
+        async get() { return { agent: "build" }; },
+        async hook(name, fn) { expect(name).toBe("prompt"); promptHook = fn; return registration(); },
+        async prompt(input) { const event = { sessionID: input.sessionID, messageID: "resume", prompt: { text: input.text } }; await promptHook(event); return event; }
+      },
+      event: { async *subscribe(options) {
+        signal = options.signal;
+        while (!signal.aborted) {
+          const event = await new Promise(resolve => {
+            const abort = () => resolve(null);
+            signal.addEventListener("abort", abort, { once: true });
+            deliver = value => { signal.removeEventListener("abort", abort); resolve(value); };
+          });
+          if (event) yield event;
+        }
+      } }
+    };
+    const cleanup = await plugin.setup(ctx);
+    try {
+      expect([...tools.keys()]).toEqual(["memmy_memory_search", "memmy_memory_get", "memmy_memory_add"]);
+      expect(tools.get("memmy_memory_search").input).toMatchObject({ type: "object", required: ["query"] });
+      const context = { sessionID: "session-1", agent: "build" };
+      for (const [name, args] of [["search", { query: "preference" }], ["get", { id: "trace-1" }], ["add", { content: "fixture fact" }]]) {
+        expect(await tools.get("memmy_memory_" + name).execute(args, context)).toHaveProperty("content");
+      }
+      await expect(tools.get("memmy_memory_add").execute({ content: "" }, context)).rejects.toThrow("Missing required");
+      const event = { sessionID: "session-1", messageID: "user-1", prompt: { text: "Inspect README", files: [{ uri: "file:///fixture" }] } };
+      await promptHook(event);
+      expect(event.prompt.text).toContain("Remembered preference");
+      expect(event.prompt.files).toHaveLength(1);
+      deliver({ type: "session.status", data: { sessionID: "session-1", status: { type: "idle" } } });
+      await vi.waitFor(() => expect(requests.filter(r => r.path === "/api/v1/source-turns/complete")).toHaveLength(1));
+      deliver({ type: "session.idle", data: { sessionID: "session-1" } });
+      const capture = requests.find(r => r.path === "/api/v1/source-turns/complete").body;
+      expect(capture).toMatchObject({ query: "Inspect README", answer: "Verified", toolCalls: [expect.objectContaining({ name: "read", output: "README contents" })] });
+      const scanned = await selectSourceTurn(readOpencodeDatabase(dbPath), { conversationId: "session-1", turnId: "user-1" });
+      expect(capture.sourceTurn.turnId).toBe(scanned.turn.turnId);
+      expect(capture.answer).toBe(scanned.turn.answer);
+      await command.execute({ sessionID: "resume-session", prompt: { text: "prior task" }, delivery: "queue" });
+      expect(requests.some(r => r.path === "/api/v1/memory/search" && r.body.query === "prior task")).toBe(true);
+      const selection = { sessionID: "resume-session", messageID: "selection", prompt: { text: "1" } };
+      await promptHook(selection);
+      expect(selection.prompt.text).toContain("Episode detail");
+      ctx.session.get = async () => { throw new Error("session temporarily unavailable"); };
+      const unavailable = { sessionID: "unavailable", messageID: "retry", prompt: { text: "Keep my request" } };
+      await expect(promptHook(unavailable)).resolves.toBeUndefined();
+      expect(unavailable.prompt.text).toBe("Keep my request");
+    } finally { await cleanup(); await cleanup(); }
+    expect(signal.aborted).toBe(true);
+    for (const dispose of disposals) expect(dispose).toHaveBeenCalledTimes(1);
+    expect(requests.filter(r => r.path === "/api/v1/source-turns/complete")).toHaveLength(1);
+  });
+});
+
+describe("V2 native completion boundaries", () => {
+  it.each(["unfinished", "tool-only", "interrupted", "subagent", "reverted"])("handles %s without capturing an invalid turn", async (kind) => {
+    const { root } = fixture(memory);
+    const dbPath = writeV2Fixture(root);
+    const db = new DatabaseSync(dbPath);
+    if (kind === "subagent") db.exec("UPDATE session_v2 SET parent_id = 'parent'");
+    if (kind === "reverted") {
+      db.exec("ALTER TABLE session_v2 ADD COLUMN revert TEXT");
+      db.prepare("UPDATE session_v2 SET revert = ?").run(JSON.stringify({ messageID: "user-1" }));
+    }
+    if (["unfinished", "tool-only", "interrupted"].includes(kind)) db.exec("DELETE FROM session_message WHERE id = 'assistant-2'");
+    if (["tool-only", "interrupted"].includes(kind)) db.prepare("INSERT INTO session_message VALUES ('idle', 'session-1', 'idle', ?, 4, ?)").run(
+      JSON.stringify({ outcome: kind === "interrupted" ? "interrupted" : "succeeded", time: { created: 1792371600010 } }), 1792371600010);
+    db.close();
+    const { turn } = await selectSourceTurn(readOpencodeDatabase(dbPath), { conversationId: "session-1", turnId: "user-1" });
+    if (["tool-only", "interrupted"].includes(kind)) {
+      expect(turn.status).toBe(kind === "interrupted" ? "failed" : "succeeded");
+      expect(turn.toolCalls).toHaveLength(1);
+    } else expect(turn).toBeNull();
+  });
+});
+
+function writeV2Fixture(dataHome) {
+  mkdirSync(join(dataHome, "opencode"), { recursive: true });
+  const path = join(dataHome, "opencode/opencode.db"); const db = new DatabaseSync(path);
+  db.exec("CREATE TABLE session_v2 (id TEXT, parent_id TEXT, directory TEXT, agent TEXT, time_created INTEGER); CREATE TABLE session_message (id TEXT, session_id TEXT, type TEXT, data TEXT, seq INTEGER, time_created INTEGER)");
+  db.prepare("INSERT INTO session_v2 VALUES (?, NULL, ?, 'build', 1)").run("session-1", dataHome);
+  const insert = db.prepare("INSERT INTO session_message VALUES (?, 'session-1', ?, ?, ?, ?)");
+  const start = Date.parse("2026-10-19T01:00:00Z");
+  insert.run("user-1", "user", JSON.stringify({ type: "user", text: "Inspect README", time: { created: start } }), 1, start);
+  insert.run("assistant-1", "assistant", JSON.stringify({ type: "assistant", agent: "build", finish: "tool-calls", time: { created: start + 1, completed: start + 2 }, content: [{ type: "tool", id: "call-1", name: "read", state: { status: "completed", input: { path: "README.md" }, content: [{ type: "text", text: "README contents" }] } }] }), 2, start + 1);
+  insert.run("assistant-2", "assistant", JSON.stringify({ type: "assistant", agent: "build", finish: "stop", time: { created: start + 3, completed: start + 4 }, content: [{ type: "text", text: "Verified" }] }), 3, start + 3);
+  db.close(); return path;
+}

From cf9db79690ac1b7e95e0396cb2972b696847ef92 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=95=E5=B8=83=E5=B8=83?=
 <lvbubu@MacBook-Pro-0018.local>
Date: Tue, 20 Oct 2026 16:57:37 +0800
Subject: [PATCH 72/85] fix(wechat): clarify Memmy Full Disk Access permission
 copy

---
 App/frontend/desktop/src/i18n/messages.ts          |  8 ++++----
 .../computer-history-sub-page.interaction.test.tsx | 12 ++++++------
 ...istory-wechat-confirmation.interaction.test.tsx | 14 +++++++-------
 3 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index 794d828a9..a814d8bff 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -1092,9 +1092,9 @@ export const zhCNMessages = {
   "computerHistory.wechat.guideLoginBody": "在电脑微信中登录要同步的账号，然后点「我已登录」开始连接。\n连接时微信会暂时退出，完成后自动重新打开。",
   "computerHistory.wechat.guideLoginBodyWindows": "让这台电脑上的微信保持登录，停在你要同步的账号。准备好后点「我已登录」。",
   "computerHistory.wechat.guideLoginButton": "我已登录",
-  "computerHistory.wechat.guideDiskTitle": "需要完全磁盘访问",
+  "computerHistory.wechat.guideDiskTitle": "Memmy 需要完全磁盘访问",
   "computerHistory.wechat.guideDiskBody": "1. 打开系统设置 → 隐私与安全性 → 完全磁盘访问。\n2. 开启 Memmy；列表没有时，点「+」添加你正在使用的 Memmy。\n3. 退出并重新打开 Memmy。",
-  "computerHistory.wechat.guideDiskButton": "打开完全磁盘访问",
+  "computerHistory.wechat.guideDiskButton": "打开 Memmy 的完全磁盘访问",
   "computerHistory.wechat.guideDiskChecking": "正在检查 Memmy 的完全磁盘访问权限…",
   "computerHistory.wechat.guideDiskCheckFailed": "暂时无法确认完全磁盘访问权限。\n1. 打开系统设置 → 隐私与安全性 → 完全磁盘访问。\n2. 确认你正在使用的 Memmy 已开启权限；列表没有时，点「+」添加。\n3. 退出并重新打开 Memmy。",
   "computerHistory.wechat.guideDiskRestart": "重启 Memmy",
@@ -3317,9 +3317,9 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "computerHistory.wechat.guideLoginBody": "Sign in to the WeChat account you want to sync on this Mac, then choose I am signed in to connect.\nWeChat will quit briefly during connection and reopen when it finishes.",
   "computerHistory.wechat.guideLoginBodyWindows": "Leave WeChat signed in on this computer, on the account you want to sync. Then choose I am signed in.",
   "computerHistory.wechat.guideLoginButton": "I am signed in",
-  "computerHistory.wechat.guideDiskTitle": "Full Disk Access is required",
+  "computerHistory.wechat.guideDiskTitle": "Memmy needs Full Disk Access",
   "computerHistory.wechat.guideDiskBody": "1. Open System Settings → Privacy & Security → Full Disk Access.\n2. Enable Memmy. If it is not listed, use + to add the Memmy app you are using.\n3. Quit and reopen Memmy.",
-  "computerHistory.wechat.guideDiskButton": "Open Full Disk Access",
+  "computerHistory.wechat.guideDiskButton": "Open Memmy's Full Disk Access",
   "computerHistory.wechat.guideDiskChecking": "Checking Memmy's Full Disk Access…",
   "computerHistory.wechat.guideDiskCheckFailed": "Full Disk Access could not be checked.\n1. Open System Settings → Privacy & Security → Full Disk Access.\n2. Confirm access is enabled for the Memmy app you are using. If it is not listed, use + to add it.\n3. Quit and reopen Memmy.",
   "computerHistory.wechat.guideDiskRestart": "Restart Memmy",
diff --git a/App/frontend/desktop/src/pages/tests/computer-history-sub-page.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/computer-history-sub-page.interaction.test.tsx
index ec27183af..e3f053b9c 100644
--- a/App/frontend/desktop/src/pages/tests/computer-history-sub-page.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/computer-history-sub-page.interaction.test.tsx
@@ -417,9 +417,9 @@ describe("ComputerHistorySubPage", () => {
     expect(setComputerHistoryWeChatAccess).not.toHaveBeenCalled();
     expect(dialogButton("我已登录")).toBeUndefined();
     expect(openExternal).not.toHaveBeenCalled();
-    await act(async () => dialogButton("打开完全磁盘访问")!.click());
+    await act(async () => dialogButton("打开 Memmy 的完全磁盘访问")!.click());
     expect(openExternal).toHaveBeenCalledWith("x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles");
-    expect(document.querySelector('[role="dialog"]')?.textContent).toContain("需要完全磁盘访问");
+    expect(document.querySelector('[role="dialog"]')?.textContent).toContain("Memmy 需要完全磁盘访问");
     expect(document.querySelector('[role="dialog"]')?.textContent).toContain("重启后重新打开");
     expect(readWeChatPermissionReturn()).not.toBeNull();
 
@@ -476,7 +476,7 @@ describe("ComputerHistorySubPage", () => {
     const client = await renderWith(disabled);
     await act(async () => container.querySelector<HTMLButtonElement>('[aria-labelledby="computer-history-wechat-label"]')!.click());
     await confirmWeChatRisk();
-    await act(async () => dialogButton("打开完全磁盘访问")!.click());
+    await act(async () => dialogButton("打开 Memmy 的完全磁盘访问")!.click());
     await act(async () => dialogButton("重启 Memmy")!.click());
     expect(restartForComputerHistoryPermissions).toHaveBeenCalledOnce();
     expect(client.setComputerHistoryWeChatAccess).not.toHaveBeenCalled();
@@ -520,14 +520,14 @@ describe("ComputerHistorySubPage", () => {
     const accessSwitch = () => container.querySelector<HTMLButtonElement>('[aria-labelledby="computer-history-wechat-label"]')!;
     await act(async () => accessSwitch().click());
     await confirmWeChatRisk();
-    act(() => dialogButton("打开完全磁盘访问")!.click());
+    act(() => dialogButton("打开 Memmy 的完全磁盘访问")!.click());
     act(() => dialogButton("取消")!.click());
     await act(async () => accessSwitch().click());
     await confirmWeChatRisk();
     await act(async () => oldSession.resolve("current-process"));
     expect(openExternal).not.toHaveBeenCalled();
     expect(readWeChatPermissionReturn()).toBeNull();
-    await act(async () => dialogButton("打开完全磁盘访问")!.click());
+    await act(async () => dialogButton("打开 Memmy 的完全磁盘访问")!.click());
     expect(openExternal).toHaveBeenCalledOnce();
     expect(readWeChatPermissionReturn()?.sessionId).toBe("current-process");
   });
@@ -543,7 +543,7 @@ describe("ComputerHistorySubPage", () => {
     const client = await renderWith(disabled);
     await act(async () => container.querySelector<HTMLButtonElement>('[aria-labelledby="computer-history-wechat-label"]')!.click());
     await confirmWeChatRisk();
-    await act(async () => dialogButton("打开完全磁盘访问")!.click());
+    await act(async () => dialogButton("打开 Memmy 的完全磁盘访问")!.click());
     expect(document.querySelector('[role="alert"]')?.textContent).toContain("未能打开系统设置或重启 Memmy");
     expect(dialogButton("重启 Memmy")).toBeUndefined();
     expect(client.connectComputerHistoryWeChat).not.toHaveBeenCalled();
diff --git a/App/frontend/desktop/src/pages/tests/computer-history-wechat-confirmation.interaction.test.tsx b/App/frontend/desktop/src/pages/tests/computer-history-wechat-confirmation.interaction.test.tsx
index 908904192..55625de0f 100644
--- a/App/frontend/desktop/src/pages/tests/computer-history-wechat-confirmation.interaction.test.tsx
+++ b/App/frontend/desktop/src/pages/tests/computer-history-wechat-confirmation.interaction.test.tsx
@@ -68,7 +68,7 @@ describe("WeChat connection preparation and Memmy permission guide", () => {
   it("uses the Memmy permission guide and requires a fresh confirmation after restarting", async () => {
     const prepare = vi.fn().mockResolvedValueOnce(denied).mockResolvedValue(ready);
     await render({ onPrepareReader: prepare });
-    expect(document.body.textContent).toContain("需要完全磁盘访问");
+    expect(document.body.textContent).toContain("Memmy 需要完全磁盘访问");
     expect(document.body.textContent).toContain("当前打开的 Memmy 无法访问微信数据");
     expect(document.body.textContent).toContain("1. 打开系统设置");
     expect(document.body.textContent).toContain("2. 开启 Memmy");
@@ -76,7 +76,7 @@ describe("WeChat connection preparation and Memmy permission guide", () => {
     expect(document.body.textContent).not.toMatch(/Reader|Finder|助手/u);
     expect(props.onLoggedIn).not.toHaveBeenCalled();
     expect(openExternal).not.toHaveBeenCalled();
-    await click("打开完全磁盘访问");
+    await click("打开 Memmy 的完全磁盘访问");
     expect(openExternal).toHaveBeenCalledWith("x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles");
     expect(props.onLoggedIn).not.toHaveBeenCalled();
     await click("重启 Memmy");
@@ -94,9 +94,9 @@ describe("WeChat connection preparation and Memmy permission guide", () => {
 
   it("does not prepare or connect automatically when returning from System Settings", async () => {
     await render({ onPrepareReader: vi.fn().mockResolvedValue(denied) });
-    await click("打开完全磁盘访问");
+    await click("打开 Memmy 的完全磁盘访问");
     await act(async () => { window.dispatchEvent(new Event("focus")); });
-    expect(document.body.textContent).toContain("需要完全磁盘访问");
+    expect(document.body.textContent).toContain("Memmy 需要完全磁盘访问");
     expect(document.body.textContent).toContain("重启 Memmy");
     expect(props.onLoggedIn).not.toHaveBeenCalled();
     expect(props.onPrepareReader).toHaveBeenCalledOnce();
@@ -118,7 +118,7 @@ describe("WeChat connection preparation and Memmy permission guide", () => {
     await click("我已登录");
     expect(getFullDiskAccessStatus).toHaveBeenCalledTimes(2);
     expect(props.onPrepareReader).toHaveBeenCalledOnce();
-    expect(document.body.textContent).toContain("需要完全磁盘访问");
+    expect(document.body.textContent).toContain("Memmy 需要完全磁盘访问");
     expect(openExternal).not.toHaveBeenCalled();
     expect(props.onLoggedIn).not.toHaveBeenCalled();
   });
@@ -126,7 +126,7 @@ describe("WeChat connection preparation and Memmy permission guide", () => {
   it("keeps the existing Memmy permission guide ahead of connection preparation", async () => {
     getFullDiskAccessStatus.mockResolvedValue(false);
     await render();
-    expect(document.body.textContent).toContain("需要完全磁盘访问");
+    expect(document.body.textContent).toContain("Memmy 需要完全磁盘访问");
     expect(props.onPrepareReader).not.toHaveBeenCalled();
     expect(props.onLoggedIn).not.toHaveBeenCalled();
   });
@@ -159,7 +159,7 @@ describe("WeChat connection preparation and Memmy permission guide", () => {
     await render({ open: false });
     await render({ open: true });
     await act(async () => { old.resolve(ready); });
-    expect(document.body.textContent).toContain("需要完全磁盘访问");
+    expect(document.body.textContent).toContain("Memmy 需要完全磁盘访问");
     expect(document.body.textContent).not.toContain("先登录微信");
     expect(props.onLoggedIn).not.toHaveBeenCalled();
   });

From 216e3ce8cd62028e81aa04fd01cc3d44bfe1dd62 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Tue, 20 Oct 2026 17:01:19 +0800
Subject: [PATCH 73/85] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8D=20OpenCode=20V2?=
 =?UTF-8?q?=20=E8=BF=9E=E7=BB=AD=E5=AF=B9=E8=AF=9D=E8=AE=B0=E5=BF=86?=
 =?UTF-8?q?=E6=BC=8F=E9=87=87=E9=9B=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/opencode-database-source.ts           |  24 ++--
 AgentSourceCore/src/opencode-source-turn.ts   |   4 +-
 .../outbound/skill-writer/opencode/target.ts  |   2 +-
 .../templates/memmy-opencode-plugin.ts        |  91 +++++++-----
 .../integration/opencode/target.ts            |   2 +-
 .../templates/memmy-opencode-plugin.ts        |  91 +++++++-----
 .../session/source-turn-opencode-v2.test.ts   |  42 ++++++
 docs/opencode-v2-validation.txt               |  34 ++++-
 scripts/test-opencode-lifecycle.mjs           | 134 +++++++++++++++++
 tests/opencode-compatibility.test.mjs         | 136 +++++++++++++++++-
 10 files changed, 474 insertions(+), 86 deletions(-)
 create mode 100644 Memory/tests/service/session/source-turn-opencode-v2.test.ts
 create mode 100644 scripts/test-opencode-lifecycle.mjs

diff --git a/AgentSourceCore/src/opencode-database-source.ts b/AgentSourceCore/src/opencode-database-source.ts
index 5ce8a49e2..eb2cb33ab 100644
--- a/AgentSourceCore/src/opencode-database-source.ts
+++ b/AgentSourceCore/src/opencode-database-source.ts
@@ -41,7 +41,7 @@ export function createOpencodeDatabaseSource(db: Database, conversationId?: stri
       currentParts.clear();
       let parentID = "";
       let agent = "";
-      let lastAssistant: Row | undefined;
+      let turnAssistants: Row[] = [];
       const result: Array<{ id: string; data: Row }> = [];
       for (const row of rows) {
         const data = parse(row.data);
@@ -50,12 +50,13 @@ export function createOpencodeDatabaseSource(db: Database, conversationId?: stri
         if (type === "agent-switched") { agent = String(data.agent || ""); continue; }
         if (type === "user") {
           parentID = id;
-          lastAssistant = undefined;
+          turnAssistants = [];
           result.push({ id, data: { role: "user", time: data.time || { created: row.time_created } } });
           currentParts.set(id, [{ id: id + ":text", data: { type: "text", text: data.text } }]);
         } else if (type === "assistant" && parentID) {
-          lastAssistant = { ...data, role: "assistant", parentID, agent: data.agent || agent };
-          result.push({ id, data: lastAssistant });
+          const assistant = { ...data, nativeTurnPending: true, role: "assistant", parentID, agent: data.agent || agent };
+          turnAssistants.push(assistant);
+          result.push({ id, data: assistant });
           const content = Array.isArray(data.content) ? data.content.map(record) : [];
           currentParts.set(id, content.map((part, index) => {
             if (part.type !== "tool") return { id: `${id}:${index}`, data: part };
@@ -68,13 +69,18 @@ export function createOpencodeDatabaseSource(db: Database, conversationId?: stri
               state: { ...state, output: state.status === "error" ? record(state.error).message || output : output, time: part.time }
             } };
           }));
-        } else if (type === "idle" && lastAssistant) {
+        } else if (type === "idle") {
           // V2 persists an explicit terminal boundary, including tool-only and
           // interrupted turns. Do not infer completion from an intermediate step.
-          lastAssistant.nativeTurnCompleted = true;
-          if (data.outcome === "failed" || data.outcome === "interrupted") lastAssistant.nativeStatus = "failed";
-          if (data.outcome === "interrupted") lastAssistant.error = { name: "MessageAbortedError" };
-          lastAssistant.time = { ...record(lastAssistant.time), completed: record(data.time).created || row.time_created };
+          // A final failed/empty assistant can be filtered by the shared parser.
+          // Close all steps so the last useful text/tool still has the terminal status.
+          for (const assistant of turnAssistants) {
+            assistant.nativeTurnCompleted = true;
+            assistant.nativeTurnPending = false;
+            if (data.outcome === "failed" || data.outcome === "interrupted") assistant.nativeStatus = "failed";
+            if (data.outcome === "interrupted") assistant.error = { name: "MessageAbortedError" };
+            assistant.time = { ...record(assistant.time), completed: record(data.time).created || row.time_created };
+          }
         }
       }
       return result;
diff --git a/AgentSourceCore/src/opencode-source-turn.ts b/AgentSourceCore/src/opencode-source-turn.ts
index e8c7e3aec..b40438225 100644
--- a/AgentSourceCore/src/opencode-source-turn.ts
+++ b/AgentSourceCore/src/opencode-source-turn.ts
@@ -60,6 +60,7 @@ interface OpencodeAssistant {
   hasOrdinaryTool: boolean;
   hasStructuredOutput: boolean;
   nativeTurnCompleted: boolean;
+  nativeTurnPending: boolean;
   nativeStatus?: "succeeded" | "failed";
 }
 
@@ -116,6 +117,7 @@ export async function* readOpencodeSession(
       hasOrdinaryTool: collected.hasOrdinaryTool,
       hasStructuredOutput: data.structured !== undefined,
       nativeTurnCompleted: data.nativeTurnCompleted === true,
+      nativeTurnPending: data.nativeTurnPending === true,
       nativeStatus: data.nativeStatus === "failed" ? "failed" : undefined
     };
     // An assistant with neither text nor a tool is idle bookkeeping (`step-finish` only).
@@ -138,7 +140,7 @@ export async function* readOpencodeSession(
     const profileId = user.userAgent || assistantProfileId(assistants);
     let reason = "";
     if (!user.query.trim()) reason = "turn_content_incomplete";
-    else if (!last) reason = "turn_incomplete";
+    else if (!last || last.nativeTurnPending) reason = "turn_incomplete";
     else if (assistants.some((assistant) => assistant.pendingTool)) reason = "turn_incomplete";
     else if (!last.aborted && opencodeAssistantStillOpen(last)) reason = "turn_incomplete";
     // An interrupted turn still counts when it produced text or a finished tool.
diff --git a/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts b/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts
index 41e6006d3..79d4ea032 100644
--- a/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts
@@ -21,7 +21,7 @@ const PLUGIN_CONFIG_FILE_NAME = "memmy-memory-config.json";
 const WORKSPACE_BRIDGE_FILE_NAME = "memmy-workspace-bridge.mjs";
 // Bump when the OpenCode bridge contract changes. Backend/Memory bundles have
 // different bytes, so their valid installations must share a logical revision.
-const OPENCODE_BRIDGE_REVISION = "v2-1";
+const OPENCODE_BRIDGE_REVISION = "v2-2";
 const COMMAND_DIRECTORY_NAME = "commands";
 const RESUME_COMMAND_FILE_NAME = "memmy-resume.md";
 const START_MARKER = "<!-- memmy:start v=1 -->";
diff --git a/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts b/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
index a6aabc60e..4d3dd67d5 100644
--- a/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
@@ -26,7 +26,7 @@ const DISPLAY_LIMIT = 5;
 const RESUME_STATE_TTL_MS = 10 * 60 * 1000;
 const RESUME_CONTEXT_MAX_CHARS = 24000;
 const TOOL_OUTPUT_MAX_CHARS = 12000;
-const PLUGIN_REVISION = "opencode-v2-1";
+const PLUGIN_REVISION = "opencode-v2-2";
 
 // A single default export prevents V1 from registering the same plugin twice.
 // The schema helper is bundled in our bridge; neither host needs the other SDK.
@@ -90,12 +90,16 @@ export default {
         try {
           for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
             if (controller.signal.aborted) break;
-            if (!["session.created", "session.compacted", "session.deleted", "session.idle", "session.status"].includes(event.type)) continue;
             const properties = event.data || {};
             if (properties.parentID) continue;
-            if (event.type === "session.status" && properties.status?.type !== "idle") continue;
+            // V2 terminal events contain a session ID, not a user message ID.
+            // The pending native messages and durable DB boundaries select the turns.
+            const terminal = ["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"].includes(event.type);
+            // Shutdown preserves V2's execution claim: it is not a completed turn.
+            if (event.type === "session.execution.interrupted" && properties.reason === "shutdown") continue;
+            if (!terminal && !["session.created", "session.compacted", "session.deleted"].includes(event.type)) continue;
             try {
-              await hooks.event({ event: { type: event.type === "session.status" ? "session.idle" : event.type, properties } });
+              await hooks.event({ event: { type: terminal ? "session.idle" : event.type, properties } });
             } catch (error) {
               console.warn("Memmy event failed: " + formatError(error));
             }
@@ -196,7 +200,11 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
         input.sessionID,
         cleanQuery
       ].join("\u0000"));
-      pendingTurns.set(input.sessionID, {
+      // A new prompt must not replace a previous native user message. Retry older
+      // persisted turns even when the host missed an earlier completion event.
+      queueTurnCompletion(input.sessionID);
+      const key = JSON.stringify([input.sessionID, requestedTurnId || turnId]);
+      if (!pendingTurns.has(key)) pendingTurns.set(key, {
         externalSessionId: input.sessionID,
         sessionId,
         turnId,
@@ -228,35 +236,51 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     }
   }
 
+  function latestPendingTurn(sessionID) {
+    let latest;
+    for (const pending of pendingTurns.values()) {
+      if (pending.externalSessionId === sessionID) latest = pending;
+    }
+    return latest;
+  }
+
   function queueTurnCompletion(sessionID) {
-    const pending = pendingTurns.get(sessionID);
-    if (!pending) {
-      return;
+    for (const [key, pending] of pendingTurns) {
+      if (pending.externalSessionId !== sessionID || pending.capturing) continue;
+      pending.capturing = true;
+      const job = completeTurn(pending)
+        .then((done) => { if (done) pendingTurns.delete(key); })
+        .catch((error) => {
+          log("warn", "Memmy turn capture failed", { error: formatError(error), sessionID });
+        })
+        .finally(() => {
+          pending.capturing = false;
+          captureJobs.delete(job);
+        });
+      captureJobs.add(job);
     }
-    pendingTurns.delete(sessionID);
-    const job = completeTurn(pending)
-      .catch((error) => {
-        log("warn", "Memmy turn capture failed", { error: formatError(error), sessionID });
-      })
-      .finally(() => {
-        captureJobs.delete(job);
-      });
-    captureJobs.add(job);
   }
 
-  // Capture reads the turn back from opencode.db so the plugin and the offline scan submit
-  // the same identity, text and tools. A turn that is not on disk yet is left for the scan.
+  // Event delivery can precede the database projection. Retry briefly without
+  // blocking prompts or the event subscription; retain unresolved records for the
+  // next terminal event / prompt / cleanup and leave durable recovery to scanning.
   async function completeTurn(pending) {
     const conversationId = normalizeText(pending.externalSessionId);
     const turnId = normalizeText(pending.userMessageId);
     if (!conversationId || !turnId) {
       log("warn", "Memmy turn capture skipped", { reason: "identity_unresolved", sessionID: pending.externalSessionId });
-      return;
+      return true;
+    }
+    let parsed;
+    for (const wait of [0, 50, 100, 200, 400, 800, 1600]) {
+      if (wait) await new Promise((resolve) => setTimeout(resolve, wait));
+      parsed = await readOpencodeHookSourceTurn({ conversationId, turnId });
+      if (parsed.turn) break;
+      if (!["source_store_unavailable", "turn_incomplete", "turn_content_incomplete", "identity_unresolved"].includes(parsed.reason)) break;
     }
-    const parsed = await readOpencodeHookSourceTurn({ conversationId, turnId });
     if (!parsed.turn) {
-      log("warn", "Memmy turn capture skipped", { reason: parsed.reason || "identity_unresolved", sessionID: conversationId });
-      return;
+      log("warn", "Memmy turn capture deferred", { reason: parsed.reason || "identity_unresolved", sessionID: conversationId, turnId });
+      return false;
     }
     const result = await completeSourceTurn({
       configUrl: CONFIG_URL,
@@ -267,9 +291,9 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       adapterId: "memmy-opencode-plugin"
     });
     const status = normalizeText(result && result.status);
-    if (status !== "stored" && status !== "existing" && status !== "rejected") {
-      log("warn", "Memmy turn capture failed", { reason: normalizeText(result && result.reason) || status || "unexpected_response", sessionID: conversationId });
-    }
+    if (status === "stored" || status === "existing" || status === "rejected") return true;
+    log("warn", "Memmy turn capture failed", { reason: normalizeText(result && result.reason) || status || "unexpected_response", sessionID: conversationId, turnId });
+    return false;
   }
 
   async function handleResumeSearch(sessionID, query, parts) {
@@ -417,7 +441,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       if (isMemmyTool(input.tool)) {
         return;
       }
-      const pending = pendingTurns.get(input.sessionID);
+      const pending = latestPendingTurn(input.sessionID);
       if (!pending) {
         return;
       }
@@ -436,7 +460,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       if (isMemmyTool(input.tool)) {
         return;
       }
-      const pending = pendingTurns.get(input.sessionID);
+      const pending = latestPendingTurn(input.sessionID);
       if (!pending) {
         return;
       }
@@ -449,7 +473,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     },
 
     "experimental.text.complete": async (input, output) => {
-      const pending = pendingTurns.get(input.sessionID);
+      const pending = latestPendingTurn(input.sessionID);
       if (!pending || normalizeText(input.messageID) === normalizeText(pending.userMessageId)) {
         return;
       }
@@ -484,7 +508,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       }
       if (event && event.type === "message.part.updated") {
         const part = properties.part && typeof properties.part === "object" ? properties.part : {};
-        const pending = pendingTurns.get(normalizeText(part.sessionID));
+        const pending = latestPendingTurn(normalizeText(part.sessionID));
         if (
           pending &&
           part.type === "text" &&
@@ -497,24 +521,25 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       // An interrupted turn is not dropped here: the database decides whether it produced
       // usable text or a finished tool, and the scan can still fill it in later.
       if (event && event.type === "session.error") {
-        const pending = pendingTurns.get(normalizeText(properties.sessionID));
+        const pending = latestPendingTurn(normalizeText(properties.sessionID));
         if (pending) {
           pending.status = "failed";
           pending.error = errorText(properties.error);
         }
         return;
       }
-      if (event && event.type === "session.idle") {
+      if (event && (event.type === "session.idle" || (event.type === "session.status" && properties.status?.type === "idle"))) {
         queueTurnCompletion(normalizeText(properties.sessionID));
       }
     },
 
     dispose: async () => {
-      for (const sessionID of [...pendingTurns.keys()]) {
+      for (const sessionID of new Set([...pendingTurns.values()].map((pending) => pending.externalSessionId))) {
         queueTurnCompletion(sessionID);
       }
       await Promise.allSettled([...captureJobs]);
       await Promise.allSettled([...sessionCache.values()].map((session) => closeRuntimeSession(session)));
+      pendingTurns.clear();
       sessionCache.clear();
       l3InjectOnce.clear();
       pendingResumeSelections.clear();
diff --git a/Memory/src/agent-source/integration/opencode/target.ts b/Memory/src/agent-source/integration/opencode/target.ts
index 41e6006d3..79d4ea032 100644
--- a/Memory/src/agent-source/integration/opencode/target.ts
+++ b/Memory/src/agent-source/integration/opencode/target.ts
@@ -21,7 +21,7 @@ const PLUGIN_CONFIG_FILE_NAME = "memmy-memory-config.json";
 const WORKSPACE_BRIDGE_FILE_NAME = "memmy-workspace-bridge.mjs";
 // Bump when the OpenCode bridge contract changes. Backend/Memory bundles have
 // different bytes, so their valid installations must share a logical revision.
-const OPENCODE_BRIDGE_REVISION = "v2-1";
+const OPENCODE_BRIDGE_REVISION = "v2-2";
 const COMMAND_DIRECTORY_NAME = "commands";
 const RESUME_COMMAND_FILE_NAME = "memmy-resume.md";
 const START_MARKER = "<!-- memmy:start v=1 -->";
diff --git a/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts b/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
index a6aabc60e..4d3dd67d5 100644
--- a/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
+++ b/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
@@ -26,7 +26,7 @@ const DISPLAY_LIMIT = 5;
 const RESUME_STATE_TTL_MS = 10 * 60 * 1000;
 const RESUME_CONTEXT_MAX_CHARS = 24000;
 const TOOL_OUTPUT_MAX_CHARS = 12000;
-const PLUGIN_REVISION = "opencode-v2-1";
+const PLUGIN_REVISION = "opencode-v2-2";
 
 // A single default export prevents V1 from registering the same plugin twice.
 // The schema helper is bundled in our bridge; neither host needs the other SDK.
@@ -90,12 +90,16 @@ export default {
         try {
           for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
             if (controller.signal.aborted) break;
-            if (!["session.created", "session.compacted", "session.deleted", "session.idle", "session.status"].includes(event.type)) continue;
             const properties = event.data || {};
             if (properties.parentID) continue;
-            if (event.type === "session.status" && properties.status?.type !== "idle") continue;
+            // V2 terminal events contain a session ID, not a user message ID.
+            // The pending native messages and durable DB boundaries select the turns.
+            const terminal = ["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"].includes(event.type);
+            // Shutdown preserves V2's execution claim: it is not a completed turn.
+            if (event.type === "session.execution.interrupted" && properties.reason === "shutdown") continue;
+            if (!terminal && !["session.created", "session.compacted", "session.deleted"].includes(event.type)) continue;
             try {
-              await hooks.event({ event: { type: event.type === "session.status" ? "session.idle" : event.type, properties } });
+              await hooks.event({ event: { type: terminal ? "session.idle" : event.type, properties } });
             } catch (error) {
               console.warn("Memmy event failed: " + formatError(error));
             }
@@ -196,7 +200,11 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
         input.sessionID,
         cleanQuery
       ].join("\u0000"));
-      pendingTurns.set(input.sessionID, {
+      // A new prompt must not replace a previous native user message. Retry older
+      // persisted turns even when the host missed an earlier completion event.
+      queueTurnCompletion(input.sessionID);
+      const key = JSON.stringify([input.sessionID, requestedTurnId || turnId]);
+      if (!pendingTurns.has(key)) pendingTurns.set(key, {
         externalSessionId: input.sessionID,
         sessionId,
         turnId,
@@ -228,35 +236,51 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     }
   }
 
+  function latestPendingTurn(sessionID) {
+    let latest;
+    for (const pending of pendingTurns.values()) {
+      if (pending.externalSessionId === sessionID) latest = pending;
+    }
+    return latest;
+  }
+
   function queueTurnCompletion(sessionID) {
-    const pending = pendingTurns.get(sessionID);
-    if (!pending) {
-      return;
+    for (const [key, pending] of pendingTurns) {
+      if (pending.externalSessionId !== sessionID || pending.capturing) continue;
+      pending.capturing = true;
+      const job = completeTurn(pending)
+        .then((done) => { if (done) pendingTurns.delete(key); })
+        .catch((error) => {
+          log("warn", "Memmy turn capture failed", { error: formatError(error), sessionID });
+        })
+        .finally(() => {
+          pending.capturing = false;
+          captureJobs.delete(job);
+        });
+      captureJobs.add(job);
     }
-    pendingTurns.delete(sessionID);
-    const job = completeTurn(pending)
-      .catch((error) => {
-        log("warn", "Memmy turn capture failed", { error: formatError(error), sessionID });
-      })
-      .finally(() => {
-        captureJobs.delete(job);
-      });
-    captureJobs.add(job);
   }
 
-  // Capture reads the turn back from opencode.db so the plugin and the offline scan submit
-  // the same identity, text and tools. A turn that is not on disk yet is left for the scan.
+  // Event delivery can precede the database projection. Retry briefly without
+  // blocking prompts or the event subscription; retain unresolved records for the
+  // next terminal event / prompt / cleanup and leave durable recovery to scanning.
   async function completeTurn(pending) {
     const conversationId = normalizeText(pending.externalSessionId);
     const turnId = normalizeText(pending.userMessageId);
     if (!conversationId || !turnId) {
       log("warn", "Memmy turn capture skipped", { reason: "identity_unresolved", sessionID: pending.externalSessionId });
-      return;
+      return true;
+    }
+    let parsed;
+    for (const wait of [0, 50, 100, 200, 400, 800, 1600]) {
+      if (wait) await new Promise((resolve) => setTimeout(resolve, wait));
+      parsed = await readOpencodeHookSourceTurn({ conversationId, turnId });
+      if (parsed.turn) break;
+      if (!["source_store_unavailable", "turn_incomplete", "turn_content_incomplete", "identity_unresolved"].includes(parsed.reason)) break;
     }
-    const parsed = await readOpencodeHookSourceTurn({ conversationId, turnId });
     if (!parsed.turn) {
-      log("warn", "Memmy turn capture skipped", { reason: parsed.reason || "identity_unresolved", sessionID: conversationId });
-      return;
+      log("warn", "Memmy turn capture deferred", { reason: parsed.reason || "identity_unresolved", sessionID: conversationId, turnId });
+      return false;
     }
     const result = await completeSourceTurn({
       configUrl: CONFIG_URL,
@@ -267,9 +291,9 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       adapterId: "memmy-opencode-plugin"
     });
     const status = normalizeText(result && result.status);
-    if (status !== "stored" && status !== "existing" && status !== "rejected") {
-      log("warn", "Memmy turn capture failed", { reason: normalizeText(result && result.reason) || status || "unexpected_response", sessionID: conversationId });
-    }
+    if (status === "stored" || status === "existing" || status === "rejected") return true;
+    log("warn", "Memmy turn capture failed", { reason: normalizeText(result && result.reason) || status || "unexpected_response", sessionID: conversationId, turnId });
+    return false;
   }
 
   async function handleResumeSearch(sessionID, query, parts) {
@@ -417,7 +441,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       if (isMemmyTool(input.tool)) {
         return;
       }
-      const pending = pendingTurns.get(input.sessionID);
+      const pending = latestPendingTurn(input.sessionID);
       if (!pending) {
         return;
       }
@@ -436,7 +460,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       if (isMemmyTool(input.tool)) {
         return;
       }
-      const pending = pendingTurns.get(input.sessionID);
+      const pending = latestPendingTurn(input.sessionID);
       if (!pending) {
         return;
       }
@@ -449,7 +473,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     },
 
     "experimental.text.complete": async (input, output) => {
-      const pending = pendingTurns.get(input.sessionID);
+      const pending = latestPendingTurn(input.sessionID);
       if (!pending || normalizeText(input.messageID) === normalizeText(pending.userMessageId)) {
         return;
       }
@@ -484,7 +508,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       }
       if (event && event.type === "message.part.updated") {
         const part = properties.part && typeof properties.part === "object" ? properties.part : {};
-        const pending = pendingTurns.get(normalizeText(part.sessionID));
+        const pending = latestPendingTurn(normalizeText(part.sessionID));
         if (
           pending &&
           part.type === "text" &&
@@ -497,24 +521,25 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       // An interrupted turn is not dropped here: the database decides whether it produced
       // usable text or a finished tool, and the scan can still fill it in later.
       if (event && event.type === "session.error") {
-        const pending = pendingTurns.get(normalizeText(properties.sessionID));
+        const pending = latestPendingTurn(normalizeText(properties.sessionID));
         if (pending) {
           pending.status = "failed";
           pending.error = errorText(properties.error);
         }
         return;
       }
-      if (event && event.type === "session.idle") {
+      if (event && (event.type === "session.idle" || (event.type === "session.status" && properties.status?.type === "idle"))) {
         queueTurnCompletion(normalizeText(properties.sessionID));
       }
     },
 
     dispose: async () => {
-      for (const sessionID of [...pendingTurns.keys()]) {
+      for (const sessionID of new Set([...pendingTurns.values()].map((pending) => pending.externalSessionId))) {
         queueTurnCompletion(sessionID);
       }
       await Promise.allSettled([...captureJobs]);
       await Promise.allSettled([...sessionCache.values()].map((session) => closeRuntimeSession(session)));
+      pendingTurns.clear();
       sessionCache.clear();
       l3InjectOnce.clear();
       pendingResumeSelections.clear();
diff --git a/Memory/tests/service/session/source-turn-opencode-v2.test.ts b/Memory/tests/service/session/source-turn-opencode-v2.test.ts
new file mode 100644
index 000000000..076d27840
--- /dev/null
+++ b/Memory/tests/service/session/source-turn-opencode-v2.test.ts
@@ -0,0 +1,42 @@
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildSourceTurnRequest, createOpencodeDatabaseSource, readOpencodeSourceTurn } from "@memmy/agent-source-core";
+import { createMemoryServiceFixture } from "../../fixtures/memory-service-fixture.js";
+
+const fixture = createMemoryServiceFixture();
+afterEach(() => fixture.cleanup());
+
+describe("OpenCode V2 live capture and historical scan", () => {
+  it.each(["hook", "agent_source_scan"] as const)("stores consecutive turns once when %s arrives first", async (firstChannel) => {
+    const native = new DatabaseSync(":memory:");
+    const { db, service } = fixture.createTestService();
+    try {
+      native.exec("CREATE TABLE session_v2 (id TEXT, parent_id TEXT, directory TEXT, agent TEXT, time_created INTEGER); CREATE TABLE session_message (id TEXT, session_id TEXT, type TEXT, data TEXT, seq INTEGER, time_created INTEGER)");
+      native.exec("INSERT INTO session_v2 VALUES ('native-session', NULL, '/fixture', 'build', 1)");
+      const insert = native.prepare("INSERT INTO session_message VALUES (?, 'native-session', ?, ?, ?, ?)");
+      for (const [index, outcome] of ["succeeded", "failed", "interrupted"].entries()) {
+        const id = `native-user-${index}`;
+        const time = 4_070_944_800_000 + index * 1000;
+        insert.run(id, "user", JSON.stringify({ type: "user", text: `Inspect and document lifecycle case ${index}.`, time: { created: time } }), index * 3, time);
+        insert.run(`${id}-answer`, "assistant", JSON.stringify({ type: "assistant", agent: "build", finish: "stop", content: [{ type: "text", text: `Verified and documented lifecycle case ${index}.` }], time: { created: time + 1, completed: time + 2 } }), index * 3 + 1, time + 1);
+        insert.run(`${id}-idle`, "idle", JSON.stringify({ type: "idle", outcome, time: { created: time + 3 } }), index * 3 + 2, time + 3);
+        const identity = { conversationId: "native-session", turnId: id };
+        const live = await readOpencodeSourceTurn(createOpencodeDatabaseSource(native)!, identity);
+        const scanned = await readOpencodeSourceTurn(createOpencodeDatabaseSource(native)!, identity);
+        expect(live.turn).not.toBeNull();
+        expect(scanned.turn).toEqual(live.turn);
+        const request = (channel: "hook" | "agent_source_scan") => ({
+          ...buildSourceTurnRequest(channel === "hook" ? live.turn! : scanned.turn!, channel),
+          namespace: { source: "opencode", profileId: "build", userId: "fixture-user" }
+        });
+        const first = service.completeSourceTurn(request(firstChannel));
+        expect(first.status).toBe("stored");
+        const second = service.completeSourceTurn(request(firstChannel === "hook" ? "agent_source_scan" : "hook"));
+        expect(second.status).toBe("existing");
+        expect(second.result?.l1MemoryId).toBe(first.result?.l1MemoryId);
+      }
+      expect(db.db.prepare("SELECT COUNT(*) AS count FROM source_turn_captures").get()).toEqual({ count: 3 });
+      expect(db.db.prepare("SELECT COUNT(*) AS count FROM memories WHERE memory_layer = 'L1'").get()).toEqual({ count: 3 });
+    } finally { native.close(); }
+  });
+});
diff --git a/docs/opencode-v2-validation.txt b/docs/opencode-v2-validation.txt
index d2fdf116a..af4de2995 100644
--- a/docs/opencode-v2-validation.txt
+++ b/docs/opencode-v2-validation.txt
@@ -47,7 +47,37 @@ an unavailable model: the model error is expected and no model call is made. The
 script prints the evidence directory containing process logs and fixture requests.
 This proves host integration, not complete model conversation or packaged GUI behavior.
 
-Packaged acceptance (next phase, after user confirmation)
+Real V2 lifecycle check (required in addition to the loader check)
+  OPENCODE_V2_BINARY=/absolute/v2/bin/opencode node --import tsx scripts/test-opencode-lifecycle.mjs
+
+This starts the official 2.0.26 server with an isolated profile and local model /
+Memory HTTP fixtures. The observer only reports real host events; it never calls
+Memmy's internal hooks or fabricates terminal events. Both installation paths run
+consecutive successful turns in the same live session: capture counts must be 1,
+then 2 before exit. A model failure with no output must not create empty memory;
+a real user interruption of a streaming answer captures its useful partial text.
+Normal shutdown must not repeat any completed capture. Native identity fields and
+answers are compared to the historical scanner. Memory service tests separately
+verify that hook-first and scan-first submissions create only one L1 per turn.
+Use --reproduce on the pre-fix code to record counts without requiring captures.
+
+Lifecycle implementation and review regression
+- V2 success/failure/user-interruption events map to the internal completion path.
+  Shutdown interruption is not a final boundary: official V2 keeps that execution
+  resumable. See the pinned upstream contract and projection:
+  https://github.com/anomalyco/opencode/blob/v2.0.26/packages/schema/src/session-event.ts
+  https://github.com/anomalyco/opencode/blob/v2.0.26/packages/core/src/session/message-updater.ts
+- Pending captures are keyed by session plus native user message, not session alone.
+  In-flight jobs are exclusive per message; successful captures are removed. New
+  prompts and late/duplicate terminal events cannot overwrite the earlier record.
+- Read-only capture waits for V2's persisted idle row, including for a final-looking
+  assistant response. Bounded retries (up to 3.15 seconds) cover projection delay.
+  An unresolved record stays pending for the next event/prompt/cleanup; historical
+  scanning remains the recovery path if the process exits before persistence.
+- Both plugin and bridge revisions advance to v2-2 so installed v2-1 artifacts are
+  updated. Save work and fully restart OpenCode, including any separate server.
+
+Packaged acceptance
 1. Prepare an isolated old-plugin installation with a valid test Memmy connection,
    a separate third-party plugin, custom OpenCode settings and AGENTS.md content.
 2. Install/start the packaged repaired Memmy. Confirm the already-connected OpenCode
@@ -56,7 +86,7 @@ Packaged acceptance (next phase, after user confirmation)
 3. Save work, fully quit and reopen OpenCode. If it uses a separate server, restart
    the server that loads the plugin too. Do not treat a new chat/window refresh as
    sufficient until verified on that exact version.
-4. Look for "Memmy plugin loaded: revision=opencode-v2-1, entry=v1/v2" in stderr or
+4. Look for "Memmy plugin loaded: revision=opencode-v2-2, entry=v1/v2" in stderr or
    host logs. Lifecycle diagnostics use stderr because V2 can consume stdout.
 5. Exercise search/get/add, pre-turn recall, completed conversation capture and
    /memmy-resume search plus selection. Verify one completed turn is stored once,
diff --git a/scripts/test-opencode-lifecycle.mjs b/scripts/test-opencode-lifecycle.mjs
new file mode 100644
index 000000000..a65fe91d1
--- /dev/null
+++ b/scripts/test-opencode-lifecycle.mjs
@@ -0,0 +1,134 @@
+/** Real OpenCode V2 lifecycle regression. The official host loads the installed
+ * plugin and runs multiple turns against a local OpenAI-compatible fixture.
+ * OPENCODE_V2_BINARY=/absolute/path/opencode node --import tsx scripts/test-opencode-lifecycle.mjs
+ * Add --reproduce to record the pre-fix behavior without requiring captures.
+ */
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createServer } from "node:http";
+import { setTimeout as delay } from "node:timers/promises";
+import assert from "node:assert/strict";
+import { createOpencodeSkillTarget as backend } from "../App/backend/src/adapters/outbound/skill-writer/opencode/target.ts";
+import { createOpencodeSkillTarget as memory } from "../Memory/src/agent-source/integration/opencode/target.ts";
+import { readOpencodeDatabase } from "../Memory/src/agent-source/adapters/opencode/db-reader.ts";
+import { selectSourceTurn } from "../AgentSourceCore/src/source-turn.ts";
+
+assert(process.env.OPENCODE_V2_BINARY, "Set OPENCODE_V2_BINARY to the official 2.0.26 CLI");
+const root = await mkdtemp(join(tmpdir(), "memmy-opencode-lifecycle-"));
+console.log("Lifecycle evidence:", root);
+for (const [name, factory] of [["Backend", backend], ["Memory", memory]]) {
+  const dir = join(root, name), config = join(dir, "config/opencode"), project = join(dir, "project");
+  await mkdir(project, { recursive: true });
+  const calls = [], events = [], counts = [];
+  let mode = "success", modelRequests = 0;
+  const fixture = createServer(async (req, res) => {
+    let raw = ""; for await (const chunk of req) raw += chunk;
+    const body = raw ? JSON.parse(raw) : {};
+    if (req.url === "/events") { events.push(body); res.end("{}"); return; }
+    calls.push({ path: req.url, body });
+    if (req.url?.endsWith("/chat/completions")) {
+      modelRequests++;
+      if (mode === "failure") { res.writeHead(400, { "content-type": "application/json" }); res.end(JSON.stringify({ error: { message: "Intentional lifecycle fixture failure", type: "invalid_request_error" } })); return; }
+      res.writeHead(200, { "content-type": "text/event-stream" });
+      const chunk = (delta, finish_reason = null) => res.write(`data: ${JSON.stringify({ id: "fixture", object: "chat.completion.chunk", created: 1, model: "fixture", choices: [{ index: 0, delta, finish_reason }] })}\n\n`);
+      chunk({ role: "assistant", content: `Local fixture answer ${modelRequests}` });
+      if (mode === "interrupt") return; // client aborts this stream using the real host API
+      chunk({}, "stop"); res.end("data: [DONE]\n\n"); return;
+    }
+    const data = req.url === "/api/v1/sessions/open" ? { sessionId: "fixture-session" }
+      : req.url === "/api/v1/turns/start" ? { turnId: body.turnId, injectedContext: { markdown: "MEMMY_LIFECYCLE_RECALL" } }
+      : { status: "stored" };
+    res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify(data));
+  });
+  await new Promise(r => fixture.listen(0, "127.0.0.1", r));
+  const endpoint = `http://127.0.0.1:${fixture.address().port}`;
+  const yaml = join(dir, "memmy.yaml");
+  await writeFile(yaml, `memmyMemory:\n  storage:\n    endpoint: ${endpoint}\n`);
+  await factory({ rootDirectory: config, memmyConfigPath: yaml }).installPlugin("opencode");
+  await writeFile(join(config, "opencode.json"), JSON.stringify({
+    provider: { fixture: { npm: "@ai-sdk/openai-compatible", options: { baseURL: endpoint + "/v1", apiKey: "local-fixture" }, models: { fixture: { name: "fixture", limit: { context: 32768, output: 256 } } } } }
+  }));
+  // Observer only: never invokes Memmy hooks or fabricates completion events.
+  await writeFile(join(config, "plugins/zz-lifecycle-observer.js"), `export default { id: "lifecycle-observer", async setup(ctx) {
+    const controller = new AbortController();
+    const title = await ctx.session.hook("title", async event => { event.result = "Lifecycle fixture"; });
+    const job = (async () => { try { for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+      if (event.type.startsWith("session.execution.") || event.type === "session.message.created") await fetch(${JSON.stringify(endpoint + "/events")}, { method: "POST", body: JSON.stringify(event) });
+    } } catch (error) { if (!controller.signal.aborted) throw error; } })();
+    return async () => { controller.abort(); await job; await title.dispose(); };
+  } };`);
+  const probe = createServer(); await new Promise(r => probe.listen(0, "127.0.0.1", r));
+  const port = probe.address().port; await new Promise(r => probe.close(r));
+  const env = { ...process.env, PWD: project, OPENCODE_CONFIG_DIR: config,
+    XDG_CONFIG_HOME: join(dir, "config"), XDG_DATA_HOME: join(dir, "data"), XDG_CACHE_HOME: join(dir, "cache"), XDG_STATE_HOME: join(dir, "state") };
+  const version = await promisify(execFile)(resolve(process.env.OPENCODE_V2_BINARY), ["--version"], { env, cwd: project });
+  assert.equal(version.stdout.trim().replace(/^opencode v/, ""), "2.0.26");
+  const child = spawn(resolve(process.env.OPENCODE_V2_BINARY), ["serve", "--hostname", "127.0.0.1", "--port", String(port), "--print-logs", "--log-level", "debug"], { cwd: project, env, stdio: ["ignore", "pipe", "pipe"] });
+  let output = ""; child.stdout.on("data", c => output += c); child.stderr.on("data", c => output += c);
+  const closed = new Promise(r => child.on("close", r));
+  const api = async (path, body) => {
+    const response = await fetch(`http://127.0.0.1:${port}/api${path}`, { method: body === undefined ? "GET" : "POST", headers: { "content-type": "application/json", authorization: "Basic " + Buffer.from("opencode:" + (output.match(/server password (\S+)/)?.[1] || "")).toString("base64") }, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(15000) });
+    const text = await response.text(); assert(response.ok, `${path}: ${response.status} ${text}`); return text ? JSON.parse(text) : null;
+  };
+  const captures = () => calls.filter(c => c.path === "/api/v1/source-turns/complete");
+  try {
+    await waitFor(async () => { try { await api("/session"); return true; } catch { return false; } }, 30000);
+    const created = await api("/session", { title: "Lifecycle fixture", model: { providerID: "fixture", id: "fixture" }, location: { directory: project } });
+    const session = created.data || created; console.log(name, "session", session.id);
+    for (let i = 1; i <= 2; i++) {
+      const before = events.length;
+      await api(`/session/${session.id}/prompt`, { text: `Lifecycle round ${i}: respond with a short answer.` });
+      await waitFor(() => events.slice(before).some(e => e.type === "session.execution.succeeded" && e.data.sessionID === session.id), 20000);
+      await delay(500);
+      counts.push(captures().length);
+    }
+    console.log(name, "captures before exit:", counts);
+    if (!process.argv.includes("--reproduce")) {
+      assert.deepEqual(counts, [1, 2], "Each real completed turn must be captured before the next prompt or exit");
+      // An actual model failure with no usable output must not store an empty memory.
+      mode = "failure";
+      let before = events.length;
+      await api(`/session/${session.id}/prompt`, { text: "Lifecycle failure: model rejects this request." });
+      await waitFor(() => events.slice(before).some(e => e.type === "session.execution.failed" && e.data.sessionID === session.id), 20000);
+      await delay(500);
+      assert.equal(captures().length, 2);
+      // Interrupt a real streaming answer through the host, preserving useful partial text.
+      mode = "interrupt";
+      before = events.length;
+      const previousRequests = modelRequests;
+      await api(`/session/${session.id}/prompt`, { text: "Lifecycle interruption: wait for user cancel." });
+      await waitFor(() => modelRequests > previousRequests, 10000);
+      await delay(150);
+      await api(`/session/${session.id}/interrupt`, {});
+      await waitFor(() => events.slice(before).some(e => e.type === "session.execution.interrupted" && e.data.sessionID === session.id), 10000);
+      await waitFor(() => captures().length === 3, 5000);
+      assert.equal(captures().at(-1).body.status, "failed");
+      for (const capture of captures()) {
+        const { turn } = await selectSourceTurn(readOpencodeDatabase(join(dir, "data/opencode/opencode.db")), { conversationId: session.id, turnId: capture.body.sourceTurn.turnId });
+        assert(turn, "Historical scan must resolve the same native user message");
+        assert.equal(capture.body.answer, turn.answer);
+        for (const field of ["source", "conversationId", "turnId", "profileId", "startedAt", "completedAt", "sequence", "completionEvidence"]) {
+          assert.equal(capture.body.sourceTurn[field], turn[field], "Hook and scan identity differ: " + field);
+        }
+      }
+    }
+  } finally {
+    child.kill("SIGTERM");
+    const killTimer = setTimeout(() => child.kill("SIGKILL"), 10000);
+    await closed; clearTimeout(killTimer);
+    await writeFile(join(dir, "process.log"), output.replace(/server password \S+/g, "server password [local test credential]"));
+    await writeFile(join(dir, "evidence.json"), JSON.stringify({ counts, capturesAfterExit: captures().length, events, calls }, null, 2));
+    fixture.closeAllConnections(); await new Promise(r => fixture.close(r));
+  }
+  assert(output.includes("Memmy plugin disposed:"), "Official host must finish normal plugin cleanup");
+  console.log(name, "captures after exit:", captures().length);
+  if (!process.argv.includes("--reproduce")) assert.equal(captures().length, 3, "Exit must not repeat completed captures");
+}
+async function waitFor(predicate, timeout) {
+  const end = Date.now() + timeout;
+  while (Date.now() < end) { if (await predicate()) return; await delay(50); }
+  throw new Error("Timed out waiting for real host lifecycle");
+}
diff --git a/tests/opencode-compatibility.test.mjs b/tests/opencode-compatibility.test.mjs
index 7a7e7d29a..1fb0121cc 100644
--- a/tests/opencode-compatibility.test.mjs
+++ b/tests/opencode-compatibility.test.mjs
@@ -122,9 +122,9 @@ describe.each([["Backend", backend], ["Memory", memory]])("%s OpenCode upgrade",
       await promptHook(event);
       expect(event.prompt.text).toContain("Remembered preference");
       expect(event.prompt.files).toHaveLength(1);
-      deliver({ type: "session.status", data: { sessionID: "session-1", status: { type: "idle" } } });
+      deliver({ type: "session.execution.succeeded", data: { sessionID: "session-1" } });
       await vi.waitFor(() => expect(requests.filter(r => r.path === "/api/v1/source-turns/complete")).toHaveLength(1));
-      deliver({ type: "session.idle", data: { sessionID: "session-1" } });
+      deliver({ type: "session.execution.succeeded", data: { sessionID: "session-1" } });
       const capture = requests.find(r => r.path === "/api/v1/source-turns/complete").body;
       expect(capture).toMatchObject({ query: "Inspect README", answer: "Verified", toolCalls: [expect.objectContaining({ name: "read", output: "README contents" })] });
       const scanned = await selectSourceTurn(readOpencodeDatabase(dbPath), { conversationId: "session-1", turnId: "user-1" });
@@ -147,7 +147,7 @@ describe.each([["Backend", backend], ["Memory", memory]])("%s OpenCode upgrade",
 });
 
 describe("V2 native completion boundaries", () => {
-  it.each(["unfinished", "tool-only", "interrupted", "subagent", "reverted"])("handles %s without capturing an invalid turn", async (kind) => {
+  it.each(["unfinished", "tool-only", "interrupted", "failed-after-tool", "subagent", "reverted"])("handles %s without capturing an invalid turn", async (kind) => {
     const { root } = fixture(memory);
     const dbPath = writeV2Fixture(root);
     const db = new DatabaseSync(dbPath);
@@ -156,13 +156,17 @@ describe("V2 native completion boundaries", () => {
       db.exec("ALTER TABLE session_v2 ADD COLUMN revert TEXT");
       db.prepare("UPDATE session_v2 SET revert = ?").run(JSON.stringify({ messageID: "user-1" }));
     }
-    if (["unfinished", "tool-only", "interrupted"].includes(kind)) db.exec("DELETE FROM session_message WHERE id = 'assistant-2'");
+    if (["unfinished", "tool-only", "interrupted"].includes(kind)) db.exec("DELETE FROM session_message WHERE id IN ('assistant-2', 'idle')");
     if (["tool-only", "interrupted"].includes(kind)) db.prepare("INSERT INTO session_message VALUES ('idle', 'session-1', 'idle', ?, 4, ?)").run(
       JSON.stringify({ outcome: kind === "interrupted" ? "interrupted" : "succeeded", time: { created: 1792371600010 } }), 1792371600010);
+    if (kind === "failed-after-tool") {
+      db.prepare("UPDATE session_message SET data = ? WHERE id = 'assistant-2'").run(JSON.stringify({ type: "assistant", agent: "build", content: [] }));
+      db.prepare("UPDATE session_message SET data = ? WHERE id = 'idle'").run(JSON.stringify({ outcome: "failed", time: { created: 1792371600010 } }));
+    }
     db.close();
     const { turn } = await selectSourceTurn(readOpencodeDatabase(dbPath), { conversationId: "session-1", turnId: "user-1" });
-    if (["tool-only", "interrupted"].includes(kind)) {
-      expect(turn.status).toBe(kind === "interrupted" ? "failed" : "succeeded");
+    if (["tool-only", "interrupted", "failed-after-tool"].includes(kind)) {
+      expect(turn.status).toBe(kind === "tool-only" ? "succeeded" : "failed");
       expect(turn.toolCalls).toHaveLength(1);
     } else expect(turn).toBeNull();
   });
@@ -178,5 +182,125 @@ function writeV2Fixture(dataHome) {
   insert.run("user-1", "user", JSON.stringify({ type: "user", text: "Inspect README", time: { created: start } }), 1, start);
   insert.run("assistant-1", "assistant", JSON.stringify({ type: "assistant", agent: "build", finish: "tool-calls", time: { created: start + 1, completed: start + 2 }, content: [{ type: "tool", id: "call-1", name: "read", state: { status: "completed", input: { path: "README.md" }, content: [{ type: "text", text: "README contents" }] } }] }), 2, start + 1);
   insert.run("assistant-2", "assistant", JSON.stringify({ type: "assistant", agent: "build", finish: "stop", time: { created: start + 3, completed: start + 4 }, content: [{ type: "text", text: "Verified" }] }), 3, start + 3);
+  insert.run("idle", "idle", JSON.stringify({ type: "idle", outcome: "succeeded", time: { created: start + 5 } }), 4, start + 5);
   db.close(); return path;
 }
+
+// This harness exercises installed artifacts with exact V2 event names. The
+// separate real-host script guards the contract against changes in OpenCode.
+async function lifecycleHarness(factory) {
+  const { root, target } = fixture(factory);
+  await target.installPlugin("opencode");
+  const plugin = await load(root);
+  const dataHome = join(root, "data"); vi.stubEnv("XDG_DATA_HOME", dataHome);
+  const dbPath = writeV2Fixture(dataHome);
+  const requests = [];
+  vi.stubGlobal("fetch", vi.fn(async (url, init) => {
+    const path = new URL(url).pathname, body = init?.body ? JSON.parse(init.body) : {};
+    requests.push({ path, body });
+    return Response.json(path === "/api/v1/sessions/open" ? { sessionId: "memmy-session" }
+      : path === "/api/v1/turns/start" ? { turnId: body.turnId } : { status: "stored" });
+  }));
+  const buffer = []; let wake; let prompt; let aborted = false;
+  const ctx = {
+    location: { directory: root },
+    tool: { async transform() { return { dispose() {} }; } },
+    command: { async transform() { return { dispose() {} }; } },
+    session: { async get() { return { agent: "build" }; }, async hook(_, fn) { prompt = fn; return { dispose() {} }; } },
+    event: { async *subscribe({ signal }) {
+      signal.addEventListener("abort", () => { aborted = true; wake?.(); }, { once: true });
+      while (!aborted) { if (!buffer.length) await new Promise(r => wake = r); while (buffer.length) yield buffer.shift(); }
+    } }
+  };
+  const cleanup = await plugin.setup(ctx);
+  return {
+    dbPath, cleanup, plugin,
+    captures: () => requests.filter(r => r.path === "/api/v1/source-turns/complete").map(r => r.body),
+    prompt: id => prompt({ sessionID: "session-1", messageID: id, prompt: { text: "Native request " + id } }),
+    emit: (type, extra = {}) => { buffer.push({ type, data: { sessionID: "session-1", ...extra } }); wake?.(); }
+  };
+}
+function appendTurn(dbPath, id, { outcome = "succeeded", terminal = true } = {}) {
+  const db = new DatabaseSync(dbPath);
+  const seq = db.prepare("SELECT MAX(seq) AS n FROM session_message").get().n + 1;
+  const time = 1792371600000 + seq;
+  const insert = db.prepare("INSERT INTO session_message VALUES (?, 'session-1', ?, ?, ?, ?)");
+  insert.run(id, "user", JSON.stringify({ type: "user", text: "Native request " + id, time: { created: time } }), seq, time);
+  insert.run(id + "-assistant", "assistant", JSON.stringify({ type: "assistant", agent: "build", finish: "stop", content: [{ type: "text", text: "Native answer " + id }], time: { created: time + 1, completed: time + 2 } }), seq + 1, time + 1);
+  if (terminal) insert.run(id + "-idle", "idle", JSON.stringify({ type: "idle", outcome, time: { created: time + 3 } }), seq + 2, time + 3);
+  db.close();
+}
+
+describe.each([["Backend", backend], ["Memory", memory]])("%s turn lifecycle", (_, factory) => {
+  it("captures success, failure and user interruption once with the scan identity, never again on exit", async () => {
+    const h = await lifecycleHarness(factory);
+    try {
+      for (const [index, outcome] of ["succeeded", "failed", "interrupted"].entries()) {
+        const id = "native-" + index;
+        appendTurn(h.dbPath, id, { outcome });
+        await h.prompt(id);
+        h.emit("session.execution." + outcome, outcome === "interrupted" ? { reason: "user" } : {});
+        await vi.waitFor(() => expect(h.captures()).toHaveLength(index + 1));
+        h.emit("session.execution." + outcome, { reason: "user" });
+        const capture = h.captures().at(-1);
+        const { turn } = await selectSourceTurn(readOpencodeDatabase(h.dbPath), { conversationId: "session-1", turnId: id });
+        expect(capture.sourceTurn.turnId).toBe(turn.turnId);
+        expect(capture.answer).toBe(turn.answer);
+        expect(turn.status).toBe(outcome === "succeeded" ? "succeeded" : "failed");
+      }
+    } finally { await h.cleanup(); }
+    expect(h.captures()).toHaveLength(3);
+  });
+
+  it("waits for the durable terminal boundary and retains overlapping native messages", async () => {
+    const h = await lifecycleHarness(factory);
+    const db = new DatabaseSync(h.dbPath);
+    // Even a final-looking assistant is not complete until V2 persists its idle row.
+    db.exec("DELETE FROM session_message WHERE id = 'idle'"); db.close();
+    try {
+      await h.prompt("user-1");
+      h.emit("session.execution.succeeded");
+      await new Promise(r => setTimeout(r, 80));
+      expect(h.captures()).toHaveLength(0);
+      await h.prompt("user-2"); // must not replace user-1 while capture retries
+      h.emit("session.execution.succeeded"); // duplicate must not capture user-2 early
+      const writer = new DatabaseSync(h.dbPath);
+      writer.prepare("INSERT INTO session_message VALUES ('idle', 'session-1', 'idle', ?, 4, ?)").run(JSON.stringify({ outcome: "succeeded", time: { created: 1792371600010 } }), 1792371600010);
+      writer.close();
+      await vi.waitFor(() => expect(h.captures()).toHaveLength(1));
+      expect(h.captures()[0].sourceTurn.turnId).toBe("user-1");
+      appendTurn(h.dbPath, "user-2");
+      h.emit("session.execution.succeeded");
+      await vi.waitFor(() => expect(h.captures()).toHaveLength(2));
+    } finally { await h.cleanup(); }
+    expect(h.captures().map(c => c.sourceTurn.turnId).sort()).toEqual(["user-1", "user-2"]);
+  });
+
+  it("does not capture unfinished shutdown or empty failed turns", async () => {
+    const h = await lifecycleHarness(factory);
+    try {
+      appendTurn(h.dbPath, "shutdown", { terminal: false });
+      await h.prompt("shutdown");
+      h.emit("session.execution.interrupted", { reason: "shutdown" });
+      await new Promise(r => setTimeout(r, 80));
+      expect(h.captures()).toHaveLength(0);
+      // Failure with no assistant output remains ineligible for memory storage.
+      const db = new DatabaseSync(h.dbPath);
+      db.exec("DELETE FROM session_message WHERE id = 'shutdown-assistant'"); db.close();
+      h.emit("session.execution.failed", { error: { message: "No model output" } });
+    } finally { await h.cleanup(); }
+    expect(h.captures()).toHaveLength(0);
+  });
+
+  it("keeps V1 idle/status lifecycle working and duplicate terminal events idempotent", async () => {
+    const h = await lifecycleHarness(factory);
+    const hooks = await h.plugin.server({ directory: "fixture" });
+    try {
+      await hooks["chat.message"]({ sessionID: "session-1", messageID: "user-1", agent: "build" }, { message: { id: "user-1" }, parts: [{ type: "text", text: "Inspect README" }] });
+      await hooks.event({ event: { type: "session.status", properties: { sessionID: "session-1", status: { type: "idle" } } } });
+      await vi.waitFor(() => expect(h.captures()).toHaveLength(1));
+      await hooks.event({ event: { type: "session.idle", properties: { sessionID: "session-1" } } });
+    } finally { await hooks.dispose(); await h.cleanup(); }
+    expect(h.captures()).toHaveLength(1);
+  });
+});

From 57acb2a814a092c635eb1f74b216c4e5f9403eaa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Tue, 20 Oct 2026 17:09:08 +0800
Subject: [PATCH 74/85] =?UTF-8?q?fix:=20=E9=80=80=E5=87=BA=E6=97=B6?=
 =?UTF-8?q?=E5=8F=96=E6=B6=88=20OpenCode=20=E9=87=87=E9=9B=86=E9=87=8D?=
 =?UTF-8?q?=E8=AF=95=E7=AD=89=E5=BE=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../templates/memmy-opencode-plugin.ts        | 20 ++++++++++++++++++-
 .../templates/memmy-opencode-plugin.ts        | 20 ++++++++++++++++++-
 docs/opencode-v2-validation.txt               |  2 ++
 tests/opencode-compatibility.test.mjs         |  4 ++++
 4 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts b/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
index 4d3dd67d5..a61a8090e 100644
--- a/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
@@ -124,6 +124,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
   const pendingResumeSelections = new Map();
   const latestRequests = new Map();
   const captureJobs = new Set();
+  const captureStop = new AbortController();
 
   function log(level, message, extra = {}) {
     try {
@@ -261,6 +262,19 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     }
   }
 
+  function waitForCaptureRead(ms) {
+    if (captureStop.signal.aborted) return Promise.resolve();
+    return new Promise((resolve) => {
+      const done = () => {
+        clearTimeout(timer);
+        captureStop.signal.removeEventListener("abort", done);
+        resolve();
+      };
+      const timer = setTimeout(done, ms);
+      captureStop.signal.addEventListener("abort", done, { once: true });
+    });
+  }
+
   // Event delivery can precede the database projection. Retry briefly without
   // blocking prompts or the event subscription; retain unresolved records for the
   // next terminal event / prompt / cleanup and leave durable recovery to scanning.
@@ -273,7 +287,8 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     }
     let parsed;
     for (const wait of [0, 50, 100, 200, 400, 800, 1600]) {
-      if (wait) await new Promise((resolve) => setTimeout(resolve, wait));
+      if (wait && captureStop.signal.aborted) break;
+      if (wait) await waitForCaptureRead(wait);
       parsed = await readOpencodeHookSourceTurn({ conversationId, turnId });
       if (parsed.turn) break;
       if (!["source_store_unavailable", "turn_incomplete", "turn_content_incomplete", "identity_unresolved"].includes(parsed.reason)) break;
@@ -534,6 +549,9 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     },
 
     dispose: async () => {
+      // Host shutdown has a short cleanup budget. Wake retries for one last read;
+      // never wait through the whole projection backoff while the host is exiting.
+      captureStop.abort();
       for (const sessionID of new Set([...pendingTurns.values()].map((pending) => pending.externalSessionId))) {
         queueTurnCompletion(sessionID);
       }
diff --git a/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts b/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
index 4d3dd67d5..a61a8090e 100644
--- a/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
+++ b/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
@@ -124,6 +124,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
   const pendingResumeSelections = new Map();
   const latestRequests = new Map();
   const captureJobs = new Set();
+  const captureStop = new AbortController();
 
   function log(level, message, extra = {}) {
     try {
@@ -261,6 +262,19 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     }
   }
 
+  function waitForCaptureRead(ms) {
+    if (captureStop.signal.aborted) return Promise.resolve();
+    return new Promise((resolve) => {
+      const done = () => {
+        clearTimeout(timer);
+        captureStop.signal.removeEventListener("abort", done);
+        resolve();
+      };
+      const timer = setTimeout(done, ms);
+      captureStop.signal.addEventListener("abort", done, { once: true });
+    });
+  }
+
   // Event delivery can precede the database projection. Retry briefly without
   // blocking prompts or the event subscription; retain unresolved records for the
   // next terminal event / prompt / cleanup and leave durable recovery to scanning.
@@ -273,7 +287,8 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     }
     let parsed;
     for (const wait of [0, 50, 100, 200, 400, 800, 1600]) {
-      if (wait) await new Promise((resolve) => setTimeout(resolve, wait));
+      if (wait && captureStop.signal.aborted) break;
+      if (wait) await waitForCaptureRead(wait);
       parsed = await readOpencodeHookSourceTurn({ conversationId, turnId });
       if (parsed.turn) break;
       if (!["source_store_unavailable", "turn_incomplete", "turn_content_incomplete", "identity_unresolved"].includes(parsed.reason)) break;
@@ -534,6 +549,9 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     },
 
     dispose: async () => {
+      // Host shutdown has a short cleanup budget. Wake retries for one last read;
+      // never wait through the whole projection backoff while the host is exiting.
+      captureStop.abort();
       for (const sessionID of new Set([...pendingTurns.values()].map((pending) => pending.externalSessionId))) {
         queueTurnCompletion(sessionID);
       }
diff --git a/docs/opencode-v2-validation.txt b/docs/opencode-v2-validation.txt
index af4de2995..9e7c0b5d7 100644
--- a/docs/opencode-v2-validation.txt
+++ b/docs/opencode-v2-validation.txt
@@ -74,6 +74,8 @@ Lifecycle implementation and review regression
   assistant response. Bounded retries (up to 3.15 seconds) cover projection delay.
   An unresolved record stays pending for the next event/prompt/cleanup; historical
   scanning remains the recovery path if the process exits before persistence.
+  Shutdown cancels retry delays and performs one last read, rather than spending
+  the host's short cleanup budget waiting through the full projection backoff.
 - Both plugin and bridge revisions advance to v2-2 so installed v2-1 artifacts are
   updated. Save work and fully restart OpenCode, including any separate server.
 
diff --git a/tests/opencode-compatibility.test.mjs b/tests/opencode-compatibility.test.mjs
index 1fb0121cc..48556e0ae 100644
--- a/tests/opencode-compatibility.test.mjs
+++ b/tests/opencode-compatibility.test.mjs
@@ -288,6 +288,10 @@ describe.each([["Backend", backend], ["Memory", memory]])("%s turn lifecycle", (
       const db = new DatabaseSync(h.dbPath);
       db.exec("DELETE FROM session_message WHERE id = 'shutdown-assistant'"); db.close();
       h.emit("session.execution.failed", { error: { message: "No model output" } });
+      await new Promise(r => setTimeout(r, 80));
+      const started = performance.now();
+      await h.cleanup();
+      expect(performance.now() - started).toBeLessThan(1000);
     } finally { await h.cleanup(); }
     expect(h.captures()).toHaveLength(0);
   });

From 2ca30e7e9f073851a5e5e940bb4464ffc904b52a Mon Sep 17 00:00:00 2001
From: Wenqiang Wei <46308778+endxxxx@users.noreply.github.com>
Date: Tue, 20 Oct 2026 17:16:19 +0800
Subject: [PATCH 75/85] fix(wechat): retry snapshots after transient source
 changes

---
 .../mac/computer-history-api.ts               | 16 +++-
 .../computer-history/mac/wechat/connect.py    |  2 +
 .../mac/wechat/private_storage.py             | 80 ++++++++++++++---
 .../mac/wechat-connection-process.test.ts     | 28 ++++++
 .../mac/wechat_connect_permissions_test.py    |  6 ++
 .../mac/wechat_private_storage_test.py        | 90 ++++++++++++++++++-
 6 files changed, 209 insertions(+), 13 deletions(-)

diff --git a/App/memmy-agent/src/tools/computer-history/mac/computer-history-api.ts b/App/memmy-agent/src/tools/computer-history/mac/computer-history-api.ts
index 0f36bafc4..00acdf7ac 100644
--- a/App/memmy-agent/src/tools/computer-history/mac/computer-history-api.ts
+++ b/App/memmy-agent/src/tools/computer-history/mac/computer-history-api.ts
@@ -824,7 +824,21 @@ export class ComputerHistoryDemoService {
   /** Keep the latest failure and where it happened; never key manifests or reader stdout. */
   private saveWeChatFailure(category: string, phase: string | null, detail?: unknown): void {
     if (!/^[a-zA-Z_][a-zA-Z_:0-9-]{0,127}$/u.test(category)) return;
-    const failureDetail = weChatFailureDetail(detail);
+    let failureDetail: Record<string, string | number> | undefined = weChatFailureDetail(detail);
+    if (category === "wechat_private_storage_source_changed") {
+      const diagnostics: Record<string, string | number> = {};
+      if (detail && typeof detail === "object") {
+        const value = detail as Record<string, unknown>;
+        if (value.kind === "file" || value.kind === "directory" || value.kind === "entry") diagnostics.kind = value.kind;
+        if (["cache", "database", "other"].includes(value.area as string)) diagnostics.area = value.area as string;
+        if (typeof value.pathHash === "string" && /^[a-f0-9]{16}$/u.test(value.pathHash)) diagnostics.pathHash = value.pathHash;
+        if (typeof value.fields === "string" && /^(?:size|dev|ino|mtime_ns|ctime_ns)(?:,(?:size|dev|ino|mtime_ns|ctime_ns)){0,4}$/u.test(value.fields)) diagnostics.fields = value.fields;
+        for (const key of ["attempts", "elapsedMs"] as const) {
+          if (typeof value[key] === "number" && Number.isSafeInteger(value[key]) && value[key] >= 0) diagnostics[key] = value[key];
+        }
+      }
+      failureDetail = Object.keys(diagnostics).length ? diagnostics : undefined;
+    }
     const file = path.join(this.weChatStateDirectory, "last-connection-error.json");
     const temporary = `${file}.${crypto.randomUUID()}.tmp`;
     try {
diff --git a/App/memmy-agent/src/tools/computer-history/mac/wechat/connect.py b/App/memmy-agent/src/tools/computer-history/mac/wechat/connect.py
index 9e001a2e7..2fed38b11 100644
--- a/App/memmy-agent/src/tools/computer-history/mac/wechat/connect.py
+++ b/App/memmy-agent/src/tools/computer-history/mac/wechat/connect.py
@@ -29,6 +29,8 @@ def connection_error_fields(error):
     if not re.fullmatch(r"[a-zA-Z_][a-zA-Z_:0-9-]{0,127}", category):
         category = "connection_process_failed"
     detail = getattr(error, "detail", None)
+    if category == "wechat_private_storage_source_changed" and isinstance(detail, dict):
+        return {"category": category, "detail": dict(detail)}
     if isinstance(detail, dict) and detail and all(
             isinstance(key, str) and isinstance(value, str) for key, value in detail.items()):
         return {"category": category, "detail": dict(detail)}
diff --git a/App/memmy-agent/src/tools/computer-history/mac/wechat/private_storage.py b/App/memmy-agent/src/tools/computer-history/mac/wechat/private_storage.py
index ac529ef15..7ba9a8bc4 100644
--- a/App/memmy-agent/src/tools/computer-history/mac/wechat/private_storage.py
+++ b/App/memmy-agent/src/tools/computer-history/mac/wechat/private_storage.py
@@ -6,6 +6,7 @@
 import ctypes
 import errno
 import fcntl
+import hashlib
 import json
 import os
 from pathlib import Path
@@ -15,6 +16,23 @@
 import shutil
 import stat
 import tempfile
+import time
+
+
+class SourceChangedError(RuntimeError):
+    """Metadata-only diagnostics; never include account names or chat paths."""
+
+    def __init__(self, source, kind, fields):
+        super().__init__("wechat_private_storage_source_changed")
+        parts = source.parts
+        area = "cache" if any("cache" in part.lower() for part in parts) else (
+            "database" if "db_storage" in parts else "other")
+        self.detail = {"kind": kind, "area": area, "fields": ",".join(fields),
+                       "pathHash": hashlib.sha256(os.fsencode(source)).hexdigest()[:16]}
+
+
+def _changed_fields(before, after, fields):
+    return [field for field in fields if getattr(before, "st_" + field) != getattr(after, "st_" + field)]
 
 
 _CONTAINER = "Library/Containers/com.tencent.xinWeChat"
@@ -175,6 +193,8 @@ def _clone_file(source, destination, root=None):
     operation = "open"
     try:
         source_descriptor = os.open(source, os.O_RDONLY | os.O_NOFOLLOW)
+    except FileNotFoundError:
+        raise SourceChangedError(source, "file", ("ino",)) from None
     except OSError as error:
         raise StorageError("wechat_private_storage_clone_failed", source, operation=operation,
                            errno=error.errno) from None
@@ -183,7 +203,10 @@ def _clone_file(source, destination, root=None):
         operation = "fstat"
         info = os.fstat(source_descriptor)
         operation = "lstat"
-        expected = _source_lstat(source)
+        try:
+            expected = _source_lstat(source)
+        except FileNotFoundError:
+            raise SourceChangedError(source, "file", ("ino",)) from None
         if (not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid()
                 or (info.st_dev, info.st_ino) != (expected.st_dev, expected.st_ino)):
             raise StorageError("wechat_private_storage_unsafe_path", source, reason="identity")
@@ -213,8 +236,9 @@ def _clone_file(source, destination, root=None):
                 raise OSError(error_number, os.strerror(error_number))
         operation = "verify"
         after = os.fstat(source_descriptor)
-        if (after.st_size, after.st_mtime_ns, after.st_ctime_ns) != (info.st_size, info.st_mtime_ns, info.st_ctime_ns):
-            raise RuntimeError("wechat_private_storage_source_changed")
+        changed = _changed_fields(info, after, ("size", "mtime_ns", "ctime_ns"))
+        if changed:
+            raise SourceChangedError(source, "file", changed)
         cloned = os.open(destination, os.O_RDONLY | os.O_NOFOLLOW)
         try:
             copied = os.fstat(cloned)
@@ -330,15 +354,22 @@ def preflight_private_storage(state, consent_id):
 
 def _clone_tree(source, destination, root, home, guard):
     guard()
-    original = _source_directory(source, root)
+    try:
+        original = _source_directory(source, root)
+        names = _source_names(source)
+    except FileNotFoundError:
+        raise SourceChangedError(source, "directory", ("ino",)) from None
     destination.mkdir(mode=0o700)
-    for name in _source_names(source):
+    for name in names:
         guard()
         path = source / name
         if _container_manager_metadata(path, root):
             continue
         copy = destination / name
-        info, target, standard_alias = _source_item(path, root, home)
+        try:
+            info, target, standard_alias = _source_item(path, root, home)
+        except FileNotFoundError:
+            raise SourceChangedError(path, "entry", ("ino",)) from None
         if stat.S_ISLNK(info.st_mode):
             relative = path.relative_to(root)
             if standard_alias:
@@ -365,14 +396,41 @@ def _clone_tree(source, destination, root, home, guard):
                 os.close(copied_descriptor)
         else:
             raise StorageError("wechat_private_storage_unsafe_path", path, reason="file_type")
-    after = _source_lstat(source)
-    if (after.st_dev, after.st_ino, after.st_mtime_ns, after.st_ctime_ns) != (
-            original.st_dev, original.st_ino, original.st_mtime_ns, original.st_ctime_ns):
-        raise RuntimeError("wechat_private_storage_source_changed")
+    try:
+        after = _source_lstat(source)
+    except FileNotFoundError:
+        raise SourceChangedError(source, "directory", ("ino",)) from None
+    changed = _changed_fields(original, after, ("dev", "ino", "mtime_ns", "ctime_ns"))
+    if changed:
+        raise SourceChangedError(source, "directory", changed)
     guard()
 
 
 def create_private_storage(state, original_container=None, optional_group=None, consent_id=None):
+    """Allow exit-time writes to settle; discard every inconsistent attempt."""
+    state = _absolute(state)
+    _directory(state, private=True)
+    if os.getuid() == 0 or os.getuid() != os.geteuid():
+        raise RuntimeError("root_execution_refused")
+    _consent(state, consent_id, initial=True)
+    started = time.monotonic()
+    for attempt in range(1, 4):
+        # A vanished main process does not mean helpers have finished writing.
+        # This pause is only a settling grace period, not proof of consistency:
+        # all strict source checks below still apply on every attempt.
+        for _ in range(4 * attempt):
+            _consent(state, consent_id)
+            time.sleep(0.25)
+        _consent(state, consent_id)
+        try:
+            return _create_private_storage_once(state, original_container, optional_group, consent_id)
+        except SourceChangedError as error:
+            error.detail.update(attempts=attempt, elapsedMs=int((time.monotonic() - started) * 1000))
+            if attempt == 3:
+                raise
+
+
+def _create_private_storage_once(state, original_container=None, optional_group=None, consent_id=None):
     state = _absolute(state)
     home = _absolute(_real_home())
     _directory(state, private=True)
@@ -429,7 +487,7 @@ def create_private_storage(state, original_container=None, optional_group=None,
             if stat.S_ISDIR(info.st_mode) and (info.st_dev, info.st_ino) == (original_session.st_dev, original_session.st_ino):
                 shutil.rmtree(session)
         except OSError:
-            pass
+            raise RuntimeError("wechat_private_storage_cleanup_failed") from None
         raise
 
 
diff --git a/App/memmy-agent/tests/tools/computer-history/mac/wechat-connection-process.test.ts b/App/memmy-agent/tests/tools/computer-history/mac/wechat-connection-process.test.ts
index fb84a1444..9c8f13aa9 100644
--- a/App/memmy-agent/tests/tools/computer-history/mac/wechat-connection-process.test.ts
+++ b/App/memmy-agent/tests/tools/computer-history/mac/wechat-connection-process.test.ts
@@ -68,6 +68,34 @@ function connect() {
 }
 
 describe("WeChat connection process diagnostics", () => {
+  it("persists only allowed source-change metadata and keeps the original failure phase", () => {
+    const child = connect();
+    child.stdout.write(JSON.stringify({ event: "preparing_wechat_data" }) + "\n");
+    const detail = { kind: "directory", area: "cache", fields: "mtime_ns,ctime_ns",
+      pathHash: "0123456789abcdef", attempts: 3, elapsedMs: 12000,
+      path: "/private/account/chat-name", keys: "never save this" };
+    child.stdout.write(JSON.stringify({ event: "connection_error", category: "wechat_private_storage_source_changed", detail }) + "\n");
+    child.stdout.write(JSON.stringify({ event: "original_reopened", success: true }) + "\n");
+    child.stdout.write(JSON.stringify({ event: "connection_error", category: "wechat_private_storage_source_changed", detail }) + "\n");
+    child.emit("close", 2, null);
+    const saved = JSON.parse(fs.readFileSync(path.join(root, "wechat", "last-connection-error.json"), "utf8"));
+    expect(saved).toMatchObject({ phase: "preparing_wechat_data", detail: {
+      kind: "directory", area: "cache", fields: "mtime_ns,ctime_ns", pathHash: "0123456789abcdef", attempts: 3, elapsedMs: 12000,
+    } });
+    expect(saved.detail).not.toHaveProperty("path");
+    expect(saved.detail).not.toHaveProperty("keys");
+  });
+
+  it("discards malformed source-change diagnostics", () => {
+    const child = connect();
+    child.stdout.write(JSON.stringify({ event: "connection_error", category: "wechat_private_storage_source_changed",
+      detail: { kind: "/private/path", area: "chat-name", fields: "arbitrary", pathHash: "secret", attempts: -1, elapsedMs: "secret" },
+    }) + "\n");
+    child.emit("close", 2, null);
+    const saved = JSON.parse(fs.readFileSync(path.join(root, "wechat", "last-connection-error.json"), "utf8"));
+    expect(saved).not.toHaveProperty("detail");
+  });
+
   it("shares a running connection instead of launching another helper for repeated requests", () => {
     const child = connect();
     expect(service.connectWeChat().wechat?.connection).toBe("connecting");
diff --git a/App/memmy-agent/tests/tools/computer-history/mac/wechat_connect_permissions_test.py b/App/memmy-agent/tests/tools/computer-history/mac/wechat_connect_permissions_test.py
index 382f69063..bf1f5a5db 100644
--- a/App/memmy-agent/tests/tools/computer-history/mac/wechat_connect_permissions_test.py
+++ b/App/memmy-agent/tests/tools/computer-history/mac/wechat_connect_permissions_test.py
@@ -20,6 +20,12 @@
 
 
 class ConnectPermissionTests(unittest.TestCase):
+    def test_source_change_metadata_is_forwarded_without_changing_error_category(self):
+        error = RuntimeError("wechat_private_storage_source_changed")
+        error.detail = {"kind": "file", "area": "cache", "attempts": 3, "elapsedMs": 12000}
+        self.assertEqual(connect.connection_error_fields(error), {
+            "category": "wechat_private_storage_source_changed", "detail": error.detail})
+
     def setUp(self):
         temporary = tempfile.TemporaryDirectory()
         self.addCleanup(temporary.cleanup)
diff --git a/App/memmy-agent/tests/tools/computer-history/mac/wechat_private_storage_test.py b/App/memmy-agent/tests/tools/computer-history/mac/wechat_private_storage_test.py
index f53f06da0..799419355 100644
--- a/App/memmy-agent/tests/tools/computer-history/mac/wechat_private_storage_test.py
+++ b/App/memmy-agent/tests/tools/computer-history/mac/wechat_private_storage_test.py
@@ -38,6 +38,7 @@ def setUp(self):
         self.native_clone = self.helper._clone_file
         self.write_consent()
         patches = [
+            mock.patch.object(self.helper.time, "sleep"),
             mock.patch.object(self.helper, "_real_home", return_value=self.home),
             mock.patch.object(self.helper, "_clone_file", side_effect=self.copy_fixture),
         ]
@@ -446,10 +447,13 @@ def revoke(source, destination, root=None):
         self.assertEqual(self.sessions(), [])
 
     def test_final_snapshot_source_change_is_rejected_and_partial_session_removed(self):
+        writes = 0
         def change(source, destination, root=None):
+            nonlocal writes
             self.copy_fixture(source, destination)
             # This synthetic new entry exercises the strict directory check.
-            (source.parent / "later-cache-entry").write_bytes(b"synthetic cache write")
+            writes += 1
+            (source.parent / ("later-cache-entry-" + str(writes))).write_bytes(b"synthetic cache write")
 
         self.clone.side_effect = change
         with self.assertRaisesRegex(RuntimeError, "^wechat_private_storage_source_changed$"):
@@ -457,6 +461,90 @@ def change(source, destination, root=None):
         self.assertEqual(self.sessions(), [])
         self.assertEqual(self.file.read_bytes(), b"only synthetic fixture bytes")
 
+    def test_transient_change_retries_with_a_fresh_session(self):
+        attempts = []
+        def change_once(source, destination, root=None):
+            self.copy_fixture(source, destination)
+            if source == self.file:
+                attempts.append(destination)
+                if len(attempts) == 1:
+                    (source.parent / "later-cache-entry").write_bytes(b"synthetic cache write")
+        self.clone.side_effect = change_once
+        storage = self.create()
+        self.assertEqual(len(attempts), 2)
+        self.assertFalse(attempts[0].exists())
+        self.assertEqual(len(self.sessions()), 1)
+        self.assertEqual((Path(storage["containerPath"]) / "Data/Documents/fixture.db").read_bytes(),
+                         b"only synthetic fixture bytes")
+
+    def test_continuous_changes_stop_after_three_attempts_with_private_diagnostics(self):
+        def change(source, destination, root=None):
+            self.copy_fixture(source, destination)
+            raise self.helper.SourceChangedError(source, "file", ("mtime_ns",))
+        self.clone.side_effect = change
+        with self.assertRaises(self.helper.SourceChangedError) as caught:
+            self.create()
+        self.assertEqual(self.clone.call_count, 3)
+        self.assertEqual(self.sessions(), [])
+        self.assertEqual(caught.exception.detail["attempts"], 3)
+        self.assertEqual(caught.exception.detail["fields"], "mtime_ns")
+        self.assertNotIn(str(self.file), json.dumps(caught.exception.detail))
+        self.assertGreaterEqual(caught.exception.detail["elapsedMs"], 0)
+
+    def test_revocation_during_retry_wait_stops_before_another_clone(self):
+        def change(source, destination, root=None):
+            self.copy_fixture(source, destination)
+            raise self.helper.SourceChangedError(source, "file", ("mtime_ns",))
+        self.clone.side_effect = change
+        def revoke_during_retry(seconds):
+            if self.clone.call_count:
+                self.write_consent(enabled=False)
+        self.helper.time.sleep.side_effect = revoke_during_retry
+        with self.assertRaisesRegex(RuntimeError, "^wechat_consent_revoked$"):
+            self.create()
+        self.assertEqual(self.clone.call_count, 1)
+        self.assertEqual(self.sessions(), [])
+
+    def test_clone_failure_is_not_retried(self):
+        self.clone.side_effect = RuntimeError("wechat_private_storage_clone_failed")
+        with self.assertRaisesRegex(RuntimeError, "^wechat_private_storage_clone_failed$"):
+            self.create()
+        self.assertEqual(self.clone.call_count, 1)
+        self.assertEqual(self.sessions(), [])
+
+    def test_permission_failure_is_not_retried(self):
+        self.clone.side_effect = PermissionError("synthetic permission denial")
+        with self.assertRaises(PermissionError):
+            self.create()
+        self.assertEqual(self.clone.call_count, 1)
+        self.assertEqual(self.sessions(), [])
+
+    def test_cache_removed_after_enumeration_retries_instead_of_failing_permanently(self):
+        cache = self.data / "Caches"
+        cache.mkdir()
+        entry = cache / "temporary"
+        entry.write_bytes(b"synthetic cache")
+        original_item = self.helper._source_item
+        removed = False
+        def remove_once(path, root, home):
+            nonlocal removed
+            if path == entry and not removed:
+                removed = True
+                entry.unlink()
+            return original_item(path, root, home)
+        with mock.patch.object(self.helper, "_source_item", side_effect=remove_once):
+            storage = self.create()
+        self.assertTrue(removed)
+        self.assertEqual(len(self.sessions()), 1)
+        self.assertFalse((Path(storage["containerPath"]) / "Data/Documents/Caches/temporary").exists())
+
+    def test_failed_cleanup_prevents_retry(self):
+        self.clone.side_effect = self.helper.SourceChangedError(self.file, "file", ("mtime_ns",))
+        with mock.patch.object(self.helper.shutil, "rmtree", side_effect=OSError("fixture cleanup failed")):
+            with self.assertRaisesRegex(RuntimeError, "^wechat_private_storage_cleanup_failed$"):
+                self.create()
+        self.assertEqual(self.clone.call_count, 1)
+
     def test_preflight_rejects_unknown_external_symlink_without_creating_a_session(self):
         (self.data / "external").symlink_to(self.home / "Desktop")
         with self.assertRaisesRegex(RuntimeError, "unsafe_path"):

From 6a3b011eb2c6d8ca2f3ecabb2f9ce50cf91cf127 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Tue, 20 Oct 2026 19:46:55 +0800
Subject: [PATCH 76/85] =?UTF-8?q?fix:=20=E8=A1=A5=E9=BD=90=20OpenCode=20?=
 =?UTF-8?q?=E7=94=9F=E5=91=BD=E5=91=A8=E6=9C=9F=E4=B8=8E=E8=BF=81=E7=A7=BB?=
 =?UTF-8?q?=E8=AE=B0=E5=BF=86=E9=87=87=E9=9B=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/opencode-database-source.ts           |  31 +++
 .../outbound/skill-writer/opencode/target.ts  |   2 +-
 .../templates/memmy-opencode-plugin.ts        | 125 ++++++---
 .../skill-writer/workspace-bridge/runtime.ts  |  41 ++-
 .../integration/opencode/target.ts            |   2 +-
 .../templates/memmy-opencode-plugin.ts        | 125 ++++++---
 .../integration/workspace-bridge/runtime.ts   |  41 ++-
 .../session/source-turn-opencode-v2.test.ts   |  55 ++++
 docs/opencode-v2-validation.txt               |  71 ++++-
 scripts/test-opencode-review.mjs              | 261 ++++++++++++++++++
 tests/opencode-compatibility.test.mjs         |  49 +++-
 11 files changed, 716 insertions(+), 87 deletions(-)
 create mode 100644 scripts/test-opencode-review.mjs

diff --git a/AgentSourceCore/src/opencode-database-source.ts b/AgentSourceCore/src/opencode-database-source.ts
index eb2cb33ab..89949dd4d 100644
--- a/AgentSourceCore/src/opencode-database-source.ts
+++ b/AgentSourceCore/src/opencode-database-source.ts
@@ -23,6 +23,13 @@ export function createOpencodeDatabaseSource(db: Database, conversationId?: stri
     ? "SELECT id, type, data, time_created FROM session_message WHERE session_id = ? ORDER BY seq ASC, id ASC"
     : "SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created ASC, id ASC");
   const parts = v2 ? null : db.prepare("SELECT id, data FROM part WHERE message_id = ? ORDER BY time_created ASC, id ASC");
+  // Official V1 -> V2 migration retains the original tables. They are positive
+  // provenance for migrated messages, whose completion/parent/tool identity must
+  // remain identical to captures made before upgrading. Native V2 rows still
+  // require their own durable idle boundary.
+  const legacyMessages = v2 && hasTable("message") && hasTable("part")
+    ? db.prepare("SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created ASC, id ASC") : null;
+  const legacyParts = legacyMessages ? db.prepare("SELECT id, data FROM part WHERE message_id = ? ORDER BY time_created ASC, id ASC") : null;
   const currentParts = new Map<string, Array<{ id: string; data: unknown }>>();
   return {
     sessions: () => sessions.all(...(conversationId ? [conversationId] : [])).map(value => {
@@ -43,10 +50,30 @@ export function createOpencodeDatabaseSource(db: Database, conversationId?: stri
       let agent = "";
       let turnAssistants: Row[] = [];
       const result: Array<{ id: string; data: Row }> = [];
+      const legacy = legacyMessages?.all(sessionId).map(record) || [];
+      const migratedIds = new Set(rows.map(row => String(row.id)));
+      const legacyIds = new Set<string>();
+      if (legacy.some(row => migratedIds.has(String(row.id)))) {
+        for (const row of legacy) {
+          const id = String(row.id);
+          legacyIds.add(id);
+          const data = parse(row.data);
+          const owner = data.role === "assistant" ? String(data.parentID || "") : id;
+          // V2 may have removed/reverted a migrated user. Keep its ordinal slot
+          // for existing source identities, but never resurrect deleted history.
+          const visible = migratedIds.has(owner);
+          result.push({ id, data: visible ? data : {} });
+          if (!visible) continue;
+          currentParts.set(id, legacyParts!.all(id).map(value => {
+            const part = record(value); return { id: String(part.id), data: parse(part.data) };
+          }));
+        }
+      }
       for (const row of rows) {
         const data = parse(row.data);
         const type = data.type || row.type;
         const id = String(row.id);
+        if (legacyIds.has(id)) continue;
         if (type === "agent-switched") { agent = String(data.agent || ""); continue; }
         if (type === "user") {
           parentID = id;
@@ -81,6 +108,10 @@ export function createOpencodeDatabaseSource(db: Database, conversationId?: stri
             if (data.outcome === "interrupted") assistant.error = { name: "MessageAbortedError" };
             assistant.time = { ...record(assistant.time), completed: record(data.time).created || row.time_created };
           }
+          // Freeze the completed turn. Synthetic continuations and independent
+          // compactions are not new user turns and cannot reopen this parent.
+          parentID = "";
+          turnAssistants = [];
         }
       }
       return result;
diff --git a/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts b/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts
index 79d4ea032..774af7d95 100644
--- a/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/opencode/target.ts
@@ -21,7 +21,7 @@ const PLUGIN_CONFIG_FILE_NAME = "memmy-memory-config.json";
 const WORKSPACE_BRIDGE_FILE_NAME = "memmy-workspace-bridge.mjs";
 // Bump when the OpenCode bridge contract changes. Backend/Memory bundles have
 // different bytes, so their valid installations must share a logical revision.
-const OPENCODE_BRIDGE_REVISION = "v2-2";
+const OPENCODE_BRIDGE_REVISION = "v2-3";
 const COMMAND_DIRECTORY_NAME = "commands";
 const RESUME_COMMAND_FILE_NAME = "memmy-resume.md";
 const START_MARKER = "<!-- memmy:start v=1 -->";
diff --git a/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts b/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
index a61a8090e..6f010f85d 100644
--- a/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
@@ -14,6 +14,8 @@ import {
   notifyRuntimeBoundary,
   openRuntimeSession,
   readOpencodeHookSourceTurn,
+  readOpencodeCompactionBoundary,
+  resolveOpencodeAgent,
   startRuntimeTurn
 } from "./memmy-workspace-bridge.mjs";
 
@@ -26,7 +28,7 @@ const DISPLAY_LIMIT = 5;
 const RESUME_STATE_TTL_MS = 10 * 60 * 1000;
 const RESUME_CONTEXT_MAX_CHARS = 24000;
 const TOOL_OUTPUT_MAX_CHARS = 12000;
-const PLUGIN_REVISION = "opencode-v2-2";
+const PLUGIN_REVISION = "opencode-v2-3";
 
 // A single default export prevents V1 from registering the same plugin twice.
 // The schema helper is bundled in our bridge; neither host needs the other SDK.
@@ -38,7 +40,11 @@ export default {
     return hooks;
   },
   async setup(ctx) {
-    const hooks = await createMemmyHooks({ directory: ctx.location.directory });
+    const resolveAgent = async (sessionID) => {
+      const session = await ctx.session.get({ sessionID });
+      return resolveOpencodeAgent(session.agent, undefined, session.agent ? undefined : await ctx.agent.list());
+    };
+    const hooks = await createMemmyHooks({ directory: ctx.location.directory, resolveAgent, modelContextL3: true });
     const controller = new AbortController();
     const registrations = [];
     let events;
@@ -70,7 +76,7 @@ export default {
           const session = await ctx.session.get({ sessionID: event.sessionID });
           if (session.parentID) return;
           await hooks["chat.message"](
-            { sessionID: event.sessionID, messageID: event.messageID, agent: session.agent },
+            { sessionID: event.sessionID, messageID: event.messageID, agent: await resolveAgent(event.sessionID) },
             { message: { id: event.messageID }, parts }
           );
           event.prompt.text = extractUserText(parts);
@@ -78,6 +84,17 @@ export default {
           console.warn("Memmy prompt recall skipped: " + formatError(error));
         }
       }));
+      registrations.push(await ctx.session.hook("context", async (event) => {
+        if (controller.signal.aborted) return;
+        try {
+          const session = await ctx.session.get({ sessionID: event.sessionID });
+          if (session.parentID) return;
+          const context = await hooks.l3Context(event.sessionID, event.agent);
+          // Context hooks receive a fresh model request, not a persisted user
+          // message. Inject one current L3 block even after automatic compaction.
+          if (context && !event.system.some(part => part.text === context)) event.system.push({ type: "text", text: context });
+        } catch (error) { console.warn("Memmy L3 context skipped: " + formatError(error)); }
+      }));
       registrations.push(await ctx.command.transform((editor) => editor.add({
         name: "memmy-resume",
         description: "Search and resume a previous Memmy episode",
@@ -97,9 +114,9 @@ export default {
             const terminal = ["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"].includes(event.type);
             // Shutdown preserves V2's execution claim: it is not a completed turn.
             if (event.type === "session.execution.interrupted" && properties.reason === "shutdown") continue;
-            if (!terminal && !["session.created", "session.compacted", "session.deleted"].includes(event.type)) continue;
+            if (!terminal && !["session.compaction.ended", "session.deleted"].includes(event.type)) continue;
             try {
-              await hooks.event({ event: { type: terminal ? "session.idle" : event.type, properties } });
+              await hooks.event({ event: { type: terminal ? "session.idle" : event.type === "session.compaction.ended" ? "session.compacted" : event.type, properties } });
             } catch (error) {
               console.warn("Memmy event failed: " + formatError(error));
             }
@@ -117,9 +134,10 @@ export default {
   }
 };
 
-const createMemmyHooks = async ({ client, directory, worktree }) => {
+const createMemmyHooks = async ({ client, directory, worktree, resolveAgent, modelContextL3 = false }) => {
   const sessionCache = new Map();
-  const l3InjectOnce = new Map();
+  const l3States = new Map();
+  const sessionAgents = new Map();
   const pendingTurns = new Map();
   const pendingResumeSelections = new Map();
   const latestRequests = new Map();
@@ -150,21 +168,22 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     for (const [key, session] of sessionCache) {
       if (!key.startsWith(sessionID + ":")) continue;
       sessionCache.delete(key);
-      await closeRuntimeSession(session).catch(() => undefined);
+      await Promise.resolve(session).then(closeRuntimeSession).catch(() => undefined);
     }
-    l3InjectOnce.delete(sessionID);
+    l3States.delete(sessionID);
+    sessionAgents.delete(sessionID);
     pendingResumeSelections.delete(sessionID);
     latestRequests.delete(sessionID);
   }
 
   async function ensureSession(memmy, externalSessionId, agent) {
-    const profileId = normalizeText(agent) || "main";
+    const profileId = resolveOpencodeAgent(agent);
     const cacheKey = externalSessionId + ":" + profileId;
     const cached = sessionCache.get(cacheKey);
     if (cached) {
       return cached;
     }
-    const opened = await openRuntimeSession({
+    const opening = openRuntimeSession({
       configUrl: CONFIG_URL,
       source: SOURCE,
       adapterId: "memmy-opencode-plugin",
@@ -172,10 +191,39 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       sessionKey: "opencode-memory-" + externalSessionId,
       workspaceRoot: worktree || directory || null,
       transition: "allow_legacy_rollover"
+    }).then((opened) => {
+      if (!opened) throw new Error("Memmy session unavailable");
+      return opened;
+    }).catch((error) => { sessionCache.delete(cacheKey); throw error; });
+    sessionCache.set(cacheKey, opening);
+    return opening;
+  }
+
+  async function l3Context(sessionID, agent) {
+    const profile = resolveOpencodeAgent(agent || sessionAgents.get(sessionID));
+    sessionAgents.set(sessionID, profile);
+    let state = l3States.get(sessionID);
+    if (!state) { state = { initialized: false, context: "", boundary: "", job: Promise.resolve() }; l3States.set(sessionID, state); }
+    // Serialize initialization and compaction refresh per native session.
+    const job = state.job.catch(() => undefined).then(async () => {
+      const runtime = await ensureSession(null, sessionID, profile);
+      const boundary = await readOpencodeCompactionBoundary(sessionID).catch(() => null);
+      const changed = boundary && boundary !== state.boundary;
+      if (!state.initialized || changed) {
+        if (changed && state.initialized && state.notifiedBoundary !== boundary) {
+          await notifyRuntimeBoundary(runtime, "token_compaction");
+          state.notifiedBoundary = boundary;
+        }
+        const loaded = await loadRuntimeL3(runtime);
+        state.context = loaded.additionalContext || "";
+        state.initialized = true;
+        state.pendingInjection = true;
+        if (boundary !== null) state.boundary = boundary;
+      }
+      return state.context;
     });
-    if (!opened) throw new Error("Memmy session unavailable");
-    sessionCache.set(cacheKey, opened);
-    return opened;
+    state.job = job;
+    return job;
   }
 
   async function beginTurn(input, output, query, selectedContext = "") {
@@ -188,7 +236,17 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     let recalledContext = "";
     try {
       const memmy = await createMemmyClient();
+      input = { ...input, agent: resolveOpencodeAgent(input.agent, output && output.message && output.message.agent) };
+      sessionAgents.set(input.sessionID, input.agent);
       const runtimeSession = await ensureSession(memmy, input.sessionID, input.agent);
+      if (!modelContextL3) {
+        const context = await l3Context(input.sessionID, input.agent);
+        const state = l3States.get(input.sessionID);
+        if (state.pendingInjection) {
+          selectedContext = [selectedContext, context].filter(Boolean).join("\n\n");
+          state.pendingInjection = false;
+        }
+      }
       const sessionId = runtimeSession.sessionId;
       const requestedTurnId = normalizeText(input.messageID) || normalizeText(output && output.message && output.message.id);
       const turn = await startRuntimeTurn(
@@ -213,7 +271,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
         sourceMemoryIds: Array.isArray(turn && turn.sourceMemoryIds) ? turn.sourceMemoryIds : undefined,
         query: cleanQuery,
         userMessageId: normalizeText(output && output.message && output.message.id) || requestedTurnId,
-        profileId: normalizeText(input.agent) || "main",
+        profileId: input.agent,
         answerParts: new Map(),
         toolCalls: [],
         toolResults: [],
@@ -297,12 +355,16 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       log("warn", "Memmy turn capture deferred", { reason: parsed.reason || "identity_unresolved", sessionID: conversationId, turnId });
       return false;
     }
+    // Preserve the Memory scope check. If execution selected another agent,
+    // resolve its scoped session instead of reusing the old agent's session ID.
+    const captureSession = parsed.turn.profileId === pending.profileId
+      ? pending.sessionId : (await ensureSession(null, conversationId, parsed.turn.profileId)).sessionId;
     const result = await completeSourceTurn({
       configUrl: CONFIG_URL,
       turn: parsed.turn,
-      sessionId: normalizeText(pending.sessionId) || undefined,
+      sessionId: normalizeText(captureSession) || undefined,
       sourceMemoryIds: pending.sourceMemoryIds,
-      profileId: normalizeText(parsed.turn.profileId) || normalizeText(pending.profileId) || "main",
+      profileId: parsed.turn.profileId,
       adapterId: "memmy-opencode-plugin"
     });
     const status = normalizeText(result && result.status);
@@ -365,6 +427,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
   }
 
   return {
+    l3Context,
     tool: {
       memmy_memory_search: tool({
         description: "Search Memmy local memory for relevant facts, preferences, decisions, procedures, and prior tasks.",
@@ -419,7 +482,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
             throw new Error("Missing required parameter: content");
           }
           const memmy = await createMemmyClient();
-          const sessionId = (await ensureSession(memmy, context.sessionID, context.agent)).sessionId;
+          const sessionId = (await ensureSession(memmy, context.sessionID, context.agent || sessionAgents.get(context.sessionID) || (resolveAgent && await resolveAgent(context.sessionID)))).sessionId;
           const result = await memmy.post("/api/v1/memory/add", {
             content,
             title: normalizeText(args.title) || undefined,
@@ -447,9 +510,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
         await handleResumeSearch(input.sessionID, normalizeText(commandArguments), output.parts);
         return;
       }
-      const l3Context = l3InjectOnce.get(input.sessionID) || "";
-      l3InjectOnce.delete(input.sessionID);
-      await beginTurn(input, output, rawPrompt, l3Context);
+      await beginTurn(input, output, rawPrompt);
     },
 
     "tool.execute.before": async (input, output) => {
@@ -497,22 +558,10 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
 
     event: async ({ event }) => {
       const properties = event && event.properties && typeof event.properties === "object" ? event.properties : {};
-      if (event && event.type === "session.created") {
-        const info = properties.info && typeof properties.info === "object" ? properties.info : properties;
-        const sessionID = normalizeText(info.id || info.sessionID);
-        if (sessionID) {
-          const runtimeSession = await ensureSession(null, sessionID, "main");
-          const loaded = await loadRuntimeL3(runtimeSession);
-          if (loaded.additionalContext) l3InjectOnce.set(sessionID, loaded.additionalContext);
-        }
-        return;
-      }
       if (event && event.type === "session.compacted") {
         const sessionID = normalizeText(properties.sessionID || properties.id);
-        const runtimeSession = await ensureSession(null, sessionID, "main");
-        await notifyRuntimeBoundary(runtimeSession, "token_compaction");
-        const loaded = await loadRuntimeL3(runtimeSession);
-        if (loaded.additionalContext) l3InjectOnce.set(sessionID, loaded.additionalContext);
+        const agent = sessionAgents.get(sessionID) || (resolveAgent && await resolveAgent(sessionID));
+        if (agent) await l3Context(sessionID, agent);
         return;
       }
       if (event && event.type === "session.deleted") {
@@ -556,10 +605,12 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
         queueTurnCompletion(sessionID);
       }
       await Promise.allSettled([...captureJobs]);
-      await Promise.allSettled([...sessionCache.values()].map((session) => closeRuntimeSession(session)));
+      await Promise.allSettled([...l3States.values()].map(state => state.job));
+      await Promise.allSettled([...sessionCache.values()].map((session) => Promise.resolve(session).then(closeRuntimeSession)));
       pendingTurns.clear();
       sessionCache.clear();
-      l3InjectOnce.clear();
+      l3States.clear();
+      sessionAgents.clear();
       pendingResumeSelections.clear();
       latestRequests.clear();
       console.error("Memmy plugin disposed: revision=" + PLUGIN_REVISION);
diff --git a/App/backend/src/adapters/outbound/skill-writer/workspace-bridge/runtime.ts b/App/backend/src/adapters/outbound/skill-writer/workspace-bridge/runtime.ts
index 1105322d8..db3305bc8 100644
--- a/App/backend/src/adapters/outbound/skill-writer/workspace-bridge/runtime.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/workspace-bridge/runtime.ts
@@ -290,7 +290,7 @@ export async function completeSourceTurn(input: {
   })));
 }
 
-type NodeSqliteDatabase = import("node:sqlite").DatabaseSync;
+type NodeSqliteDatabase = Pick<import("node:sqlite").DatabaseSync, "prepare" | "close">;
 
 let nodeSqlite: Promise<typeof import("node:sqlite")> | undefined;
 
@@ -315,10 +315,49 @@ function silenceSqliteExperimentalWarning(): void {
 }
 
 async function openReadOnlySqlite(path: string): Promise<NodeSqliteDatabase> {
+  // Official V1 embeds Bun, which does not implement node:sqlite. Choose the
+  // host driver before opening; never retry an open error with a writable DB.
+  if ("Bun" in globalThis) {
+    const moduleName = "bun:sqlite";
+    const { Database } = await import(moduleName);
+    return new Database(path, { readonly: true, create: false, strict: true });
+  }
   const { DatabaseSync } = await loadNodeSqlite();
   return new DatabaseSync(path, { readOnly: true });
 }
 
+/** Resolve only host-provided identities. V1 exposes the selected agent on
+ * output.message; V2 agent.list puts its configured effective default first. */
+export function resolveOpencodeAgent(selected: unknown, messageAgent?: unknown, agents?: unknown): string {
+  const explicit = text(selected) || text(messageAgent);
+  if (explicit) return explicit;
+  const list = Array.isArray(agents) ? agents : objectValue(agents).data;
+  if (Array.isArray(list)) {
+    const candidate = list.map(objectValue).find(agent => agent.mode !== "subagent" && !agent.hidden);
+    const id = text(candidate?.id) || text(candidate?.name);
+    if (id) return id;
+  }
+  throw new Error("OpenCode effective agent unavailable");
+}
+
+/** Durable success identity also covers a compaction event delivered before its
+ * projection, missed during restart, or repeated by the host. Failed rows are ignored. */
+export async function readOpencodeCompactionBoundary(conversationId: string): Promise<string> {
+  const db = await openReadOnlySqlite(resolveOpencodeDatabasePath());
+  try {
+    const v2 = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'session_v2'").get();
+    const rows = db.prepare(v2
+      ? "SELECT id, data FROM session_message WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC"
+      : "SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created DESC, id DESC").all(conversationId);
+    for (const value of rows) {
+      const row = objectValue(value);
+      const data = objectValue(JSON.parse(String(row.data)));
+      if (v2 ? data.status === "completed" : data.summary === true && objectValue(data.time).completed && !data.error) return text(row.id);
+    }
+    return "";
+  } finally { db.close(); }
+}
+
 /**
  * Reads the turn Cursor just finished out of its own global `state.vscdb`, using the same
  * parser the offline scan uses. The hook only receives `generation_id`, which is the user
diff --git a/Memory/src/agent-source/integration/opencode/target.ts b/Memory/src/agent-source/integration/opencode/target.ts
index 79d4ea032..774af7d95 100644
--- a/Memory/src/agent-source/integration/opencode/target.ts
+++ b/Memory/src/agent-source/integration/opencode/target.ts
@@ -21,7 +21,7 @@ const PLUGIN_CONFIG_FILE_NAME = "memmy-memory-config.json";
 const WORKSPACE_BRIDGE_FILE_NAME = "memmy-workspace-bridge.mjs";
 // Bump when the OpenCode bridge contract changes. Backend/Memory bundles have
 // different bytes, so their valid installations must share a logical revision.
-const OPENCODE_BRIDGE_REVISION = "v2-2";
+const OPENCODE_BRIDGE_REVISION = "v2-3";
 const COMMAND_DIRECTORY_NAME = "commands";
 const RESUME_COMMAND_FILE_NAME = "memmy-resume.md";
 const START_MARKER = "<!-- memmy:start v=1 -->";
diff --git a/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts b/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
index a61a8090e..6f010f85d 100644
--- a/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
+++ b/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
@@ -14,6 +14,8 @@ import {
   notifyRuntimeBoundary,
   openRuntimeSession,
   readOpencodeHookSourceTurn,
+  readOpencodeCompactionBoundary,
+  resolveOpencodeAgent,
   startRuntimeTurn
 } from "./memmy-workspace-bridge.mjs";
 
@@ -26,7 +28,7 @@ const DISPLAY_LIMIT = 5;
 const RESUME_STATE_TTL_MS = 10 * 60 * 1000;
 const RESUME_CONTEXT_MAX_CHARS = 24000;
 const TOOL_OUTPUT_MAX_CHARS = 12000;
-const PLUGIN_REVISION = "opencode-v2-2";
+const PLUGIN_REVISION = "opencode-v2-3";
 
 // A single default export prevents V1 from registering the same plugin twice.
 // The schema helper is bundled in our bridge; neither host needs the other SDK.
@@ -38,7 +40,11 @@ export default {
     return hooks;
   },
   async setup(ctx) {
-    const hooks = await createMemmyHooks({ directory: ctx.location.directory });
+    const resolveAgent = async (sessionID) => {
+      const session = await ctx.session.get({ sessionID });
+      return resolveOpencodeAgent(session.agent, undefined, session.agent ? undefined : await ctx.agent.list());
+    };
+    const hooks = await createMemmyHooks({ directory: ctx.location.directory, resolveAgent, modelContextL3: true });
     const controller = new AbortController();
     const registrations = [];
     let events;
@@ -70,7 +76,7 @@ export default {
           const session = await ctx.session.get({ sessionID: event.sessionID });
           if (session.parentID) return;
           await hooks["chat.message"](
-            { sessionID: event.sessionID, messageID: event.messageID, agent: session.agent },
+            { sessionID: event.sessionID, messageID: event.messageID, agent: await resolveAgent(event.sessionID) },
             { message: { id: event.messageID }, parts }
           );
           event.prompt.text = extractUserText(parts);
@@ -78,6 +84,17 @@ export default {
           console.warn("Memmy prompt recall skipped: " + formatError(error));
         }
       }));
+      registrations.push(await ctx.session.hook("context", async (event) => {
+        if (controller.signal.aborted) return;
+        try {
+          const session = await ctx.session.get({ sessionID: event.sessionID });
+          if (session.parentID) return;
+          const context = await hooks.l3Context(event.sessionID, event.agent);
+          // Context hooks receive a fresh model request, not a persisted user
+          // message. Inject one current L3 block even after automatic compaction.
+          if (context && !event.system.some(part => part.text === context)) event.system.push({ type: "text", text: context });
+        } catch (error) { console.warn("Memmy L3 context skipped: " + formatError(error)); }
+      }));
       registrations.push(await ctx.command.transform((editor) => editor.add({
         name: "memmy-resume",
         description: "Search and resume a previous Memmy episode",
@@ -97,9 +114,9 @@ export default {
             const terminal = ["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"].includes(event.type);
             // Shutdown preserves V2's execution claim: it is not a completed turn.
             if (event.type === "session.execution.interrupted" && properties.reason === "shutdown") continue;
-            if (!terminal && !["session.created", "session.compacted", "session.deleted"].includes(event.type)) continue;
+            if (!terminal && !["session.compaction.ended", "session.deleted"].includes(event.type)) continue;
             try {
-              await hooks.event({ event: { type: terminal ? "session.idle" : event.type, properties } });
+              await hooks.event({ event: { type: terminal ? "session.idle" : event.type === "session.compaction.ended" ? "session.compacted" : event.type, properties } });
             } catch (error) {
               console.warn("Memmy event failed: " + formatError(error));
             }
@@ -117,9 +134,10 @@ export default {
   }
 };
 
-const createMemmyHooks = async ({ client, directory, worktree }) => {
+const createMemmyHooks = async ({ client, directory, worktree, resolveAgent, modelContextL3 = false }) => {
   const sessionCache = new Map();
-  const l3InjectOnce = new Map();
+  const l3States = new Map();
+  const sessionAgents = new Map();
   const pendingTurns = new Map();
   const pendingResumeSelections = new Map();
   const latestRequests = new Map();
@@ -150,21 +168,22 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     for (const [key, session] of sessionCache) {
       if (!key.startsWith(sessionID + ":")) continue;
       sessionCache.delete(key);
-      await closeRuntimeSession(session).catch(() => undefined);
+      await Promise.resolve(session).then(closeRuntimeSession).catch(() => undefined);
     }
-    l3InjectOnce.delete(sessionID);
+    l3States.delete(sessionID);
+    sessionAgents.delete(sessionID);
     pendingResumeSelections.delete(sessionID);
     latestRequests.delete(sessionID);
   }
 
   async function ensureSession(memmy, externalSessionId, agent) {
-    const profileId = normalizeText(agent) || "main";
+    const profileId = resolveOpencodeAgent(agent);
     const cacheKey = externalSessionId + ":" + profileId;
     const cached = sessionCache.get(cacheKey);
     if (cached) {
       return cached;
     }
-    const opened = await openRuntimeSession({
+    const opening = openRuntimeSession({
       configUrl: CONFIG_URL,
       source: SOURCE,
       adapterId: "memmy-opencode-plugin",
@@ -172,10 +191,39 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       sessionKey: "opencode-memory-" + externalSessionId,
       workspaceRoot: worktree || directory || null,
       transition: "allow_legacy_rollover"
+    }).then((opened) => {
+      if (!opened) throw new Error("Memmy session unavailable");
+      return opened;
+    }).catch((error) => { sessionCache.delete(cacheKey); throw error; });
+    sessionCache.set(cacheKey, opening);
+    return opening;
+  }
+
+  async function l3Context(sessionID, agent) {
+    const profile = resolveOpencodeAgent(agent || sessionAgents.get(sessionID));
+    sessionAgents.set(sessionID, profile);
+    let state = l3States.get(sessionID);
+    if (!state) { state = { initialized: false, context: "", boundary: "", job: Promise.resolve() }; l3States.set(sessionID, state); }
+    // Serialize initialization and compaction refresh per native session.
+    const job = state.job.catch(() => undefined).then(async () => {
+      const runtime = await ensureSession(null, sessionID, profile);
+      const boundary = await readOpencodeCompactionBoundary(sessionID).catch(() => null);
+      const changed = boundary && boundary !== state.boundary;
+      if (!state.initialized || changed) {
+        if (changed && state.initialized && state.notifiedBoundary !== boundary) {
+          await notifyRuntimeBoundary(runtime, "token_compaction");
+          state.notifiedBoundary = boundary;
+        }
+        const loaded = await loadRuntimeL3(runtime);
+        state.context = loaded.additionalContext || "";
+        state.initialized = true;
+        state.pendingInjection = true;
+        if (boundary !== null) state.boundary = boundary;
+      }
+      return state.context;
     });
-    if (!opened) throw new Error("Memmy session unavailable");
-    sessionCache.set(cacheKey, opened);
-    return opened;
+    state.job = job;
+    return job;
   }
 
   async function beginTurn(input, output, query, selectedContext = "") {
@@ -188,7 +236,17 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
     let recalledContext = "";
     try {
       const memmy = await createMemmyClient();
+      input = { ...input, agent: resolveOpencodeAgent(input.agent, output && output.message && output.message.agent) };
+      sessionAgents.set(input.sessionID, input.agent);
       const runtimeSession = await ensureSession(memmy, input.sessionID, input.agent);
+      if (!modelContextL3) {
+        const context = await l3Context(input.sessionID, input.agent);
+        const state = l3States.get(input.sessionID);
+        if (state.pendingInjection) {
+          selectedContext = [selectedContext, context].filter(Boolean).join("\n\n");
+          state.pendingInjection = false;
+        }
+      }
       const sessionId = runtimeSession.sessionId;
       const requestedTurnId = normalizeText(input.messageID) || normalizeText(output && output.message && output.message.id);
       const turn = await startRuntimeTurn(
@@ -213,7 +271,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
         sourceMemoryIds: Array.isArray(turn && turn.sourceMemoryIds) ? turn.sourceMemoryIds : undefined,
         query: cleanQuery,
         userMessageId: normalizeText(output && output.message && output.message.id) || requestedTurnId,
-        profileId: normalizeText(input.agent) || "main",
+        profileId: input.agent,
         answerParts: new Map(),
         toolCalls: [],
         toolResults: [],
@@ -297,12 +355,16 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
       log("warn", "Memmy turn capture deferred", { reason: parsed.reason || "identity_unresolved", sessionID: conversationId, turnId });
       return false;
     }
+    // Preserve the Memory scope check. If execution selected another agent,
+    // resolve its scoped session instead of reusing the old agent's session ID.
+    const captureSession = parsed.turn.profileId === pending.profileId
+      ? pending.sessionId : (await ensureSession(null, conversationId, parsed.turn.profileId)).sessionId;
     const result = await completeSourceTurn({
       configUrl: CONFIG_URL,
       turn: parsed.turn,
-      sessionId: normalizeText(pending.sessionId) || undefined,
+      sessionId: normalizeText(captureSession) || undefined,
       sourceMemoryIds: pending.sourceMemoryIds,
-      profileId: normalizeText(parsed.turn.profileId) || normalizeText(pending.profileId) || "main",
+      profileId: parsed.turn.profileId,
       adapterId: "memmy-opencode-plugin"
     });
     const status = normalizeText(result && result.status);
@@ -365,6 +427,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
   }
 
   return {
+    l3Context,
     tool: {
       memmy_memory_search: tool({
         description: "Search Memmy local memory for relevant facts, preferences, decisions, procedures, and prior tasks.",
@@ -419,7 +482,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
             throw new Error("Missing required parameter: content");
           }
           const memmy = await createMemmyClient();
-          const sessionId = (await ensureSession(memmy, context.sessionID, context.agent)).sessionId;
+          const sessionId = (await ensureSession(memmy, context.sessionID, context.agent || sessionAgents.get(context.sessionID) || (resolveAgent && await resolveAgent(context.sessionID)))).sessionId;
           const result = await memmy.post("/api/v1/memory/add", {
             content,
             title: normalizeText(args.title) || undefined,
@@ -447,9 +510,7 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
         await handleResumeSearch(input.sessionID, normalizeText(commandArguments), output.parts);
         return;
       }
-      const l3Context = l3InjectOnce.get(input.sessionID) || "";
-      l3InjectOnce.delete(input.sessionID);
-      await beginTurn(input, output, rawPrompt, l3Context);
+      await beginTurn(input, output, rawPrompt);
     },
 
     "tool.execute.before": async (input, output) => {
@@ -497,22 +558,10 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
 
     event: async ({ event }) => {
       const properties = event && event.properties && typeof event.properties === "object" ? event.properties : {};
-      if (event && event.type === "session.created") {
-        const info = properties.info && typeof properties.info === "object" ? properties.info : properties;
-        const sessionID = normalizeText(info.id || info.sessionID);
-        if (sessionID) {
-          const runtimeSession = await ensureSession(null, sessionID, "main");
-          const loaded = await loadRuntimeL3(runtimeSession);
-          if (loaded.additionalContext) l3InjectOnce.set(sessionID, loaded.additionalContext);
-        }
-        return;
-      }
       if (event && event.type === "session.compacted") {
         const sessionID = normalizeText(properties.sessionID || properties.id);
-        const runtimeSession = await ensureSession(null, sessionID, "main");
-        await notifyRuntimeBoundary(runtimeSession, "token_compaction");
-        const loaded = await loadRuntimeL3(runtimeSession);
-        if (loaded.additionalContext) l3InjectOnce.set(sessionID, loaded.additionalContext);
+        const agent = sessionAgents.get(sessionID) || (resolveAgent && await resolveAgent(sessionID));
+        if (agent) await l3Context(sessionID, agent);
         return;
       }
       if (event && event.type === "session.deleted") {
@@ -556,10 +605,12 @@ const createMemmyHooks = async ({ client, directory, worktree }) => {
         queueTurnCompletion(sessionID);
       }
       await Promise.allSettled([...captureJobs]);
-      await Promise.allSettled([...sessionCache.values()].map((session) => closeRuntimeSession(session)));
+      await Promise.allSettled([...l3States.values()].map(state => state.job));
+      await Promise.allSettled([...sessionCache.values()].map((session) => Promise.resolve(session).then(closeRuntimeSession)));
       pendingTurns.clear();
       sessionCache.clear();
-      l3InjectOnce.clear();
+      l3States.clear();
+      sessionAgents.clear();
       pendingResumeSelections.clear();
       latestRequests.clear();
       console.error("Memmy plugin disposed: revision=" + PLUGIN_REVISION);
diff --git a/Memory/src/agent-source/integration/workspace-bridge/runtime.ts b/Memory/src/agent-source/integration/workspace-bridge/runtime.ts
index 3527c4c70..c0868bf3c 100644
--- a/Memory/src/agent-source/integration/workspace-bridge/runtime.ts
+++ b/Memory/src/agent-source/integration/workspace-bridge/runtime.ts
@@ -290,7 +290,7 @@ export async function completeSourceTurn(input: {
   })));
 }
 
-type NodeSqliteDatabase = import("node:sqlite").DatabaseSync;
+type NodeSqliteDatabase = Pick<import("node:sqlite").DatabaseSync, "prepare" | "close">;
 
 let nodeSqlite: Promise<typeof import("node:sqlite")> | undefined;
 
@@ -315,10 +315,49 @@ function silenceSqliteExperimentalWarning(): void {
 }
 
 async function openReadOnlySqlite(path: string): Promise<NodeSqliteDatabase> {
+  // Official V1 embeds Bun, which does not implement node:sqlite. Choose the
+  // host driver before opening; never retry an open error with a writable DB.
+  if ("Bun" in globalThis) {
+    const moduleName = "bun:sqlite";
+    const { Database } = await import(moduleName);
+    return new Database(path, { readonly: true, create: false, strict: true });
+  }
   const { DatabaseSync } = await loadNodeSqlite();
   return new DatabaseSync(path, { readOnly: true });
 }
 
+/** Resolve only host-provided identities. V1 exposes the selected agent on
+ * output.message; V2 agent.list puts its configured effective default first. */
+export function resolveOpencodeAgent(selected: unknown, messageAgent?: unknown, agents?: unknown): string {
+  const explicit = text(selected) || text(messageAgent);
+  if (explicit) return explicit;
+  const list = Array.isArray(agents) ? agents : objectValue(agents).data;
+  if (Array.isArray(list)) {
+    const candidate = list.map(objectValue).find(agent => agent.mode !== "subagent" && !agent.hidden);
+    const id = text(candidate?.id) || text(candidate?.name);
+    if (id) return id;
+  }
+  throw new Error("OpenCode effective agent unavailable");
+}
+
+/** Durable success identity also covers a compaction event delivered before its
+ * projection, missed during restart, or repeated by the host. Failed rows are ignored. */
+export async function readOpencodeCompactionBoundary(conversationId: string): Promise<string> {
+  const db = await openReadOnlySqlite(resolveOpencodeDatabasePath());
+  try {
+    const v2 = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'session_v2'").get();
+    const rows = db.prepare(v2
+      ? "SELECT id, data FROM session_message WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC"
+      : "SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created DESC, id DESC").all(conversationId);
+    for (const value of rows) {
+      const row = objectValue(value);
+      const data = objectValue(JSON.parse(String(row.data)));
+      if (v2 ? data.status === "completed" : data.summary === true && objectValue(data.time).completed && !data.error) return text(row.id);
+    }
+    return "";
+  } finally { db.close(); }
+}
+
 /**
  * Reads the turn Cursor just finished out of its own global `state.vscdb`, using the same
  * parser the offline scan uses. The hook only receives `generation_id`, which is the user
diff --git a/Memory/tests/service/session/source-turn-opencode-v2.test.ts b/Memory/tests/service/session/source-turn-opencode-v2.test.ts
index 076d27840..3907c44d1 100644
--- a/Memory/tests/service/session/source-turn-opencode-v2.test.ts
+++ b/Memory/tests/service/session/source-turn-opencode-v2.test.ts
@@ -40,3 +40,58 @@ describe("OpenCode V2 live capture and historical scan", () => {
     } finally { native.close(); }
   });
 });
+
+describe("OpenCode V2 migration and immutable native boundaries", () => {
+  it.each(["hook", "agent_source_scan"] as const)("keeps migrated V1 identity and freezes native turns when %s arrives first", async (firstChannel) => {
+    const native = new DatabaseSync(":memory:");
+    const { service, db } = fixture.createTestService();
+    try {
+      native.exec(`CREATE TABLE session_v2 (id TEXT, parent_id TEXT, directory TEXT, agent TEXT, time_created INTEGER);
+        CREATE TABLE session_message (id TEXT, session_id TEXT, type TEXT, data TEXT, seq INTEGER, time_created INTEGER);
+        CREATE TABLE message (id TEXT, session_id TEXT, data TEXT, time_created INTEGER);
+        CREATE TABLE part (id TEXT, message_id TEXT, data TEXT, time_created INTEGER);
+        INSERT INTO session_v2 VALUES ('session', NULL, '/fixture', 'build', 1)`);
+      const time = 4_070_944_800_000;
+      const insert = native.prepare("INSERT INTO session_message VALUES (?, 'session', ?, ?, ?, ?)");
+      const user = { role: "user", agent: "build", time: { created: time } };
+      const assistant = { role: "assistant", parentID: "old-user", agent: "build", finish: "stop", time: { created: time + 1, completed: time + 2 } };
+      native.prepare("INSERT INTO message VALUES (?, 'session', ?, ?)").run("old-user", JSON.stringify(user), time);
+      native.prepare("INSERT INTO message VALUES (?, 'session', ?, ?)").run("old-answer", JSON.stringify(assistant), time + 1);
+      native.prepare("INSERT INTO part VALUES ('old-query', 'old-user', ?, ?)").run(JSON.stringify({ type: "text", text: "Inspect and document migrated storage behavior." }), time);
+      native.prepare("INSERT INTO part VALUES ('old-text', 'old-answer', ?, ?)").run(JSON.stringify({ type: "text", text: "Verified migrated storage behavior." }), time + 1);
+      // Official migration keeps the original rows and creates V2 rows without idle.
+      insert.run("old-user", "user", JSON.stringify({ text: "Inspect and document migrated storage behavior.", time: user.time }), 0, time);
+      insert.run("old-answer", "assistant", JSON.stringify({ agent: "build", finish: "stop", time: assistant.time, content: [{ type: "text", text: "Verified migrated storage behavior." }] }), 1, time + 1);
+      const read = async (turnId: string) => (await readOpencodeSourceTurn(createOpencodeDatabaseSource(native)!, { conversationId: "session", turnId })).turn;
+      const migrated = await read("old-user");
+      expect(migrated).toMatchObject({ completedAt: new Date(time + 2).toISOString(), profileId: "build", answer: "Verified migrated storage behavior." });
+      const capture = (turn: NonNullable<typeof migrated>, channel: "hook" | "agent_source_scan") => service.completeSourceTurn({
+        ...buildSourceTurnRequest(turn, channel), namespace: { source: "opencode", profileId: "build", userId: "fixture-user" }
+      });
+      expect(capture(migrated!, firstChannel).status).toBe("stored");
+      insert.run("new-user", "user", JSON.stringify({ text: "Inspect and document native boundaries.", time: { created: time + 10 } }), 2, time + 10);
+      insert.run("tool-step", "assistant", JSON.stringify({ agent: "build", finish: "tool-calls", time: { created: time + 11, completed: time + 12 }, content: [{ type: "tool", id: "read", name: "read", time: { created: time + 11, completed: time + 12 }, state: { status: "completed", input: {}, content: [{ type: "text", text: "file contents" }] } }] }), 3, time + 11);
+      expect(await read("new-user")).toBeNull(); // completed tool step is not a completed execution
+      insert.run("final-step", "assistant", JSON.stringify({ agent: "build", finish: "stop", time: { created: time + 13, completed: time + 14 }, content: [{ type: "text", text: "Verified native boundaries." }] }), 4, time + 13);
+      expect(await read("new-user")).toBeNull(); // native V2 still needs idle
+      insert.run("idle", "idle", JSON.stringify({ outcome: "succeeded", time: { created: time + 15 } }), 5, time + 15);
+      const completed = await read("new-user");
+      expect(completed).not.toBeNull();
+      expect(capture(completed!, firstChannel).status).toBe("stored");
+      insert.run("maintenance", "synthetic", JSON.stringify({ text: "System continuation" }), 6, time + 16);
+      insert.run("maintenance-answer", "assistant", JSON.stringify({ agent: "build", finish: "stop", time: { created: time + 17, completed: time + 18 }, content: [{ type: "text", text: "This is not part of the previous user turn." }] }), 7, time + 17);
+      insert.run("maintenance-idle", "idle", JSON.stringify({ outcome: "succeeded", time: { created: time + 19 } }), 8, time + 19);
+      insert.run("compact", "compaction", JSON.stringify({ status: "completed", summary: "Independent compaction" }), 9, time + 20);
+      insert.run("compaction-idle", "idle", JSON.stringify({ outcome: "succeeded", time: { created: time + 21 } }), 10, time + 21);
+      expect(await read("new-user")).toEqual(completed);
+      expect(await read("old-user")).toEqual(migrated);
+      const second = firstChannel === "hook" ? "agent_source_scan" : "hook";
+      expect(capture((await read("new-user"))!, second).status).toBe("existing");
+      expect(capture((await read("old-user"))!, second).status).toBe("existing");
+      expect(db.db.prepare("SELECT COUNT(*) AS count FROM source_turn_captures").get()).toEqual({ count: 2 });
+      native.exec("DELETE FROM session_message WHERE id = 'old-user'");
+      expect(await read("old-user")).toBeNull();
+      expect(await read("new-user")).toEqual(completed);
+    } finally { native.close(); }
+  });
+});
diff --git a/docs/opencode-v2-validation.txt b/docs/opencode-v2-validation.txt
index 9e7c0b5d7..06b9f108d 100644
--- a/docs/opencode-v2-validation.txt
+++ b/docs/opencode-v2-validation.txt
@@ -7,7 +7,7 @@ Official migration reference: https://dev.opencode.ai/v2/docs/build/plugins/migr
 
 Implementation
 - One default export: V1 calls server(), V2 calls setup(). The V2 adapter registers
-  JSON Schema tools, the prompt hook, the memmy-resume command and event subscription.
+  JSON Schema tools, the prompt/context hooks, the memmy-resume command and event subscription.
 - The bridge bundles real Zod schemas. No runtime import of either host's SDK is
   necessary. V1 receives Zod arguments; V2 receives JSON Schema and structured output.
 - Plugin capture and offline scanning use the same V1/V2 database adapter. V2 uses
@@ -76,7 +76,7 @@ Lifecycle implementation and review regression
   scanning remains the recovery path if the process exits before persistence.
   Shutdown cancels retry delays and performs one last read, rather than spending
   the host's short cleanup budget waiting through the full projection backoff.
-- Both plugin and bridge revisions advance to v2-2 so installed v2-1 artifacts are
+- Both plugin and bridge revisions advance to v2-3 so older artifacts are
   updated. Save work and fully restart OpenCode, including any separate server.
 
 Packaged acceptance
@@ -88,7 +88,7 @@ Packaged acceptance
 3. Save work, fully quit and reopen OpenCode. If it uses a separate server, restart
    the server that loads the plugin too. Do not treat a new chat/window refresh as
    sufficient until verified on that exact version.
-4. Look for "Memmy plugin loaded: revision=opencode-v2-2, entry=v1/v2" in stderr or
+4. Look for "Memmy plugin loaded: revision=opencode-v2-3, entry=v1/v2" in stderr or
    host logs. Lifecycle diagnostics use stderr because V2 can consume stdout.
 5. Exercise search/get/add, pre-turn recall, completed conversation capture and
    /memmy-resume search plus selection. Verify one completed turn is stored once,
@@ -102,3 +102,68 @@ Packaged acceptance
    results do not constitute Windows Desktop acceptance.
 
 No data migration or user-database writes are needed for the read-only V2 adapter.
+
+Review follow-up: L3, effective Agent, migrated history (2026-10-20)
+- Initialization occurs on actual use, not session.created. V2 context hooks add
+  the current L3 block to each fresh model request, including the first request
+  after restart and after compaction; it is not persisted in the native user text.
+  Initialization/read jobs are serialized per session. Repeated hooks do not append
+  the same block twice to one request. V1 injects on the first prompt and refresh.
+- V2 session.compaction.ended maps to V1's internal successful-compaction path.
+  Both paths verify a durable successful compaction ID in the native read-only DB.
+  Duplicate events cannot notify/reload twice; failed rows do not advance the ID.
+  Checking at model/prompt use also catches event/projection races and missed events.
+- Resolve V2 session.agent or the first effective default from the host agent.list
+  (which orders the configured selected default first). V1 uses the resolved agent
+  on output.message when input.agent is absent. Do not guess main/build. Session
+  opening, recall and capture use this scope; Memory's scope validation is unchanged.
+  If execution ultimately selected another agent, capture resolves that agent's
+  scoped Memory session instead of passing the prior agent's session ID.
+- Official V1 embeds Bun: the read-only bridge selects bun:sqlite there and
+  node:sqlite in Node. Both installers bundle the same behavior without SDK imports.
+- Official V1 migration retains original message/part tables. Those rows provide
+  positive migration provenance and preserve the original completion timestamp,
+  parent links, tools and sequence. Native V2 messages still require durable idle;
+  a completed intermediate tool step never establishes final execution completion.
+  Idle clears the active parent/assistant list so later synthetic replies or
+  standalone compaction cannot rewrite a previously completed source turn.
+
+Required real-storage regression (in addition to loader and lifecycle checks)
+  OPENCODE_V2_BINARY=/absolute/v2/bin/opencode OPENCODE_V1_BINARY=/absolute/v1/bin/opencode node --import tsx scripts/test-opencode-review.mjs
+Run with each supported V1 binary (1.18.29 and 1.19.2). The V2 binary is 2.0.26.
+The script installs through Backend and Memory separately, starts real Memory HTTP
+and SQLite storage, and records actual OpenCode model requests and native events.
+Only model replies and embeddings are fixtures; Memory acceptance, scope checks,
+capture policy and deduplication remain real. Test prompts contain concrete coding
+feedback so a recalled prior fixture answer is not rejected as memory-only chatter.
+L3 markers are seeded into the actual project-scoped Memory records. Background
+summary/evolution model jobs are outside this test (no Memory LLM is configured).
+
+Acceptance assertions:
+- Unspecified Agent uses real CLI run --server without --agent, twice in one live
+  session. Custom default plan is also tested through the CLI; explicit build and
+  mid-session switch to plan are exercised through the official session API.
+- Eight eligible V2 turns per installation path are accepted before exit. Source
+  scopes are checked by actual Memory, and history rescan returns existing.
+- Cold first use, newly created sessions and restart/resume include current L3 in
+  the actual model request. Successful compaction notifies once and refreshes the
+  next request; failed compaction neither notifies nor refreshes.
+- A synthetic continuation and standalone compaction leave completed turns intact.
+- Six actual V1 turns (default plan then explicit build) are stored and deduplicated,
+  then migrated by the official V2 executable. All six remain eligible, preserve
+  the entire normalized source turn and rescan as existing after migration.
+- Service tests separately exercise hook-first and scan-first with real Memory
+  storage, native intermediate-tool exclusion, and immutable terminal boundaries.
+- Controlled plugin tests cover concurrent initialization, repeated context hooks,
+  duplicate successful events and failed compaction across both installed templates.
+
+The previous HEAD adapter was also checked against these real native databases:
+all six migrated turns returned turn_incomplete; a synthetic reply was appended
+into the prior user turn. The repaired adapter resolves all six and freezes that
+turn's original answer. This is not a claim based only on hand-made DB fixtures.
+
+Validation limit: these are macOS official CLI/server tests with local model
+replies, not a Windows Desktop or new DMG acceptance. The upstream v1.2.4 missing
+settings.modelWorkspace.replaceKey / replaceKeyPlaceholder translations still
+block the full typecheck/build. Per user instruction they are left untouched;
+no new package is claimed for this revision.
diff --git a/scripts/test-opencode-review.mjs b/scripts/test-opencode-review.mjs
new file mode 100644
index 000000000..99c0f8281
--- /dev/null
+++ b/scripts/test-opencode-review.mjs
@@ -0,0 +1,261 @@
+/** Official-host review regressions, with real Memory HTTP/storage and a local
+ * model fixture. No user data or external model service is used.
+ * OPENCODE_V2_BINARY=... [OPENCODE_V1_BINARY=...] node --import tsx scripts/test-opencode-review.mjs
+ * --reproduce records failing baseline observations without asserting acceptance.
+ */
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createServer } from "node:http";
+import { setTimeout as delay } from "node:timers/promises";
+import assert from "node:assert/strict";
+import { DatabaseSync } from "node:sqlite";
+import { createOpencodeSkillTarget as backend } from "../App/backend/src/adapters/outbound/skill-writer/opencode/target.ts";
+import { createOpencodeSkillTarget as memory } from "../Memory/src/agent-source/integration/opencode/target.ts";
+import { readOpencodeDatabase } from "../Memory/src/agent-source/adapters/opencode/db-reader.ts";
+import { selectSourceTurn, buildSourceTurnRequest } from "../AgentSourceCore/src/source-turn.ts";
+import { createMemoryServiceFixture } from "../Memory/tests/fixtures/memory-service-fixture.ts";
+import { createMemoryHttpServer } from "../Memory/src/index.ts";
+import { Repositories } from "../Memory/src/storage/repositories.ts";
+
+assert(process.env.OPENCODE_V2_BINARY, "Set OPENCODE_V2_BINARY to official 2.0.26");
+const reproduce = process.argv.includes("--reproduce");
+const root = await mkdtemp(join(tmpdir(), "memmy-opencode-review-"));
+console.log("Review evidence:", root);
+const check = (condition, message) => { if (reproduce) console.log(condition ? "PASS" : "REPRODUCED", message); else assert(condition, message); };
+for (const [name, factory] of [["Backend", backend], ["Memory", memory]]) {
+  const h = await harness(name, factory);
+  try {
+    await h.start(process.env.OPENCODE_V2_BINARY, 2);
+    const first = await h.session();
+    for (let i = 0; i < 2; i++) {
+      const turn = await h.prompt(first, "Review normal round " + i, undefined, true);
+      check(h.stored() === i + 1, name + " default Agent: each turn stored before exit");
+      check(h.lastRequest().includes("MEMMY_L3_INITIAL"), name + " first/next real request includes L3");
+      await h.scan(first, turn);
+    }
+    const original = await h.scanned(first, h.turns[0].turnId);
+    await h.api(`/session/${first}/synthetic`, { text: "System follow-up: acknowledge this maintenance message.", resume: true });
+    await h.waitTerminal(first);
+    const after = await h.scanned(first, h.turns[0].turnId);
+    check(JSON.stringify(original) === JSON.stringify(after), name + " synthetic continuation cannot rewrite the completed turn");
+    await h.scan(first, h.turns[0].turnId);
+    await h.api(`/session/${first}/agent`, { agent: "plan" });
+    const switched = await h.prompt(first, "Review switched agent: answer without tools.");
+    check(h.latestCapture()?.namespace?.profileId === "plan", name + " switched Agent uses plan");
+    await h.scan(first, switched);
+
+    h.seed("MEMMY_L3_COMPACTED");
+    const reads = h.l3Reads(), boundaries = h.boundaries();
+    await h.compact(first, true);
+    const compacted = await h.prompt(first, "Review after successful compaction.");
+    check(h.lastRequest().includes("MEMMY_L3_COMPACTED") && !h.lastRequest().includes("MEMMY_L3_INITIAL"), name + " next model request contains refreshed L3");
+    check(h.l3Reads() === reads + 1, name + " compaction refresh reads L3 exactly once");
+    check(h.boundaries() === boundaries + 1, name + " successful compaction notifies Memory once");
+    await h.scan(first, compacted);
+    const failedReads = h.l3Reads(), failedBoundaries = h.boundaries();
+    h.seed("MEMMY_L3_MUST_NOT_REFRESH_ON_FAILURE");
+    await h.compact(first, false);
+    await h.prompt(first, "Review after failed compaction.");
+    check(h.l3Reads() === failedReads && h.boundaries() === failedBoundaries, name + " failed compaction neither refreshes nor reports success");
+    check(!h.lastRequest().includes("MEMMY_L3_MUST_NOT_REFRESH_ON_FAILURE"), name + " failed compaction keeps prior L3");
+
+    const count = h.stored();
+    await h.stop();
+    check(h.stored() === count, name + " cleanup does not duplicate captures");
+    h.seed("MEMMY_L3_RESTARTED");
+    await h.configure("plan");
+    await h.start(process.env.OPENCODE_V2_BINARY, 2);
+    await h.prompt(first, "Review resume existing session after restart.");
+    check(h.lastRequest().includes("MEMMY_L3_RESTARTED"), name + " resumed existing session initializes current L3");
+    const second = await h.session();
+    await h.prompt(second, "Review custom default agent without an explicit selection.", undefined, true);
+    check(h.latestCapture()?.namespace?.profileId === "plan", name + " configured default plan is respected");
+    check(h.lastRequest().includes("MEMMY_L3_RESTARTED"), name + " new session initializes current L3");
+    const third = await h.session("build");
+    await h.prompt(third, "Review explicit build overrides default plan.");
+    check(h.latestCapture()?.namespace?.profileId === "build", name + " explicit build overrides configured default");
+    check(h.captureResponses().every(r => ["stored", "existing"].includes(r.status)), name + " all live captures accepted by real Memory");
+    console.log(name, "V2 real stored turns", h.stored());
+  } finally { await h.close(); }
+
+  if (process.env.OPENCODE_V1_BINARY) {
+    const old = await harness(name + "-migration", factory);
+    try {
+      await old.configure("plan");
+      await old.start(process.env.OPENCODE_V1_BINARY, 1);
+      const session = await old.session();
+      const before = [];
+      for (let i = 0; i < 6; i++) {
+        const id = await old.prompt(session, "Migration completed round " + i, i < 3 ? undefined : "build");
+        before.push(await old.scanned(session, id));
+        check(old.stored() === i + 1, name + " V1 turn " + i + " stored via host SQLite driver");
+        await old.scan(session, id);
+      }
+      await old.stop();
+      await old.start(process.env.OPENCODE_V2_BINARY, 2);
+      await waitFor(() => {
+        const native = new DatabaseSync(old.nativePath, { readOnly: true });
+        try { return native.prepare("SELECT COUNT(*) AS n FROM session_v2 WHERE id = ?").get(session)?.n === 1; }
+        catch { return false; } finally { native.close(); }
+      }, 30000);
+      for (const turn of before) {
+        const migrated = await old.scanned(session, turn?.turnId);
+        check(Boolean(migrated), name + " migrated completed turn is eligible");
+        check(JSON.stringify(turn) === JSON.stringify(migrated), name + " migration preserves original source-turn identity/content/time");
+        if (migrated) await old.scan(session, migrated.turnId);
+      }
+      console.log(name, "V1 -> V2 migrated turns", before.length);
+    } finally { await old.close(); }
+  }
+}
+
+async function harness(name, factory) {
+  const dir = join(root, name), config = join(dir, "config/opencode"), project = join(dir, "project");
+  await mkdir(project, { recursive: true });
+  const mf = createMemoryServiceFixture(), { service, db } = mf.createTestService();
+  const repos = new Repositories(db.db);
+  const memoryServer = createMemoryHttpServer({ service, startAgentSourceAutomation: false, auth: { mode: "dev", allowAnonymous: true } });
+  await listen(memoryServer);
+  const memoryEndpoint = `http://127.0.0.1:${memoryServer.address().port}`;
+  const calls = [], events = [], turns = [];
+  const seededProjects = new Set(); let seedValue = "MEMMY_L3_INITIAL";
+  let mode = "success", serial = 0, generation = 2, child, closed, output = "", port, cursor = 0, hostBinary;
+  const fixture = createServer(async (req, res) => {
+    try {
+      let raw = ""; for await (const chunk of req) raw += chunk;
+      const body = raw ? JSON.parse(raw) : {};
+      if (req.url === "/events") { events.push(body); res.end("{}"); return; }
+      const call = { path: req.url, body }; calls.push(call);
+      if (req.url?.endsWith("/chat/completions")) {
+        serial++;
+        if (mode === "failure") { res.writeHead(400, { "content-type": "application/json" }); res.end(JSON.stringify({ error: { message: "Intentional review model failure", type: "invalid_request_error" } })); return; }
+        res.writeHead(200, { "content-type": "text/event-stream" });
+        const chunk = (delta, finish_reason = null) => res.write(`data: ${JSON.stringify({ id: "fixture", object: "chat.completion.chunk", created: 1, model: "fixture", choices: [{ index: 0, delta, finish_reason }] })}\n\n`);
+        const answer = mode === "compaction"
+          ? ["## Objective", "## Requirements", "## Decisions", "## Work State", "### Completed", "### Active", "### Blocked", "## Next Move", "## Relevant Files", "## Important Context"].map(heading => heading + "\n- Preserve user data and finish the review fixture.").join("\n\n")
+          : `Verified local fixture answer ${serial}. Continue the requested task safely.`;
+        chunk({ role: "assistant", content: answer });
+        chunk({}, "stop"); res.end("data: [DONE]\n\n"); return;
+      }
+      const response = await fetch(memoryEndpoint + req.url, { method: req.method, headers: { ...req.headers, host: new URL(memoryEndpoint).host }, body: raw || undefined });
+      const text = await response.text(); call.response = { code: response.status, body: JSON.parse(text) };
+      const projectId = call.response.body.projectId;
+      if (req.url === "/api/v1/sessions/open" && projectId && !seededProjects.has(projectId)) {
+        seededProjects.add(projectId);
+        repos.l3WorldModels.upsertField({ userId: "local-user", projectId, targetField: "project_contract", value: seedValue });
+      }
+      res.writeHead(response.status, { "content-type": "application/json" }); res.end(text);
+    } catch (error) { res.writeHead(500); res.end(JSON.stringify({ error: String(error) })); }
+  });
+  await listen(fixture);
+  const endpoint = `http://127.0.0.1:${fixture.address().port}`;
+  const yaml = join(dir, "memmy.yaml"); await writeFile(yaml, `memmyMemory:\n  storage:\n    endpoint: ${endpoint}\n`);
+  await factory({ rootDirectory: config, memmyConfigPath: yaml }).installPlugin("opencode");
+  const nativePath = join(dir, "data/opencode/opencode.db");
+  const env = { ...process.env, PWD: project, OPENCODE_CONFIG_DIR: config, XDG_CONFIG_HOME: join(dir, "config"), XDG_DATA_HOME: join(dir, "data"), XDG_CACHE_HOME: join(dir, "cache"), XDG_STATE_HOME: join(dir, "state") };
+  const api = async (path, body) => {
+    const response = await fetch(`http://127.0.0.1:${port}${generation === 2 ? "/api" : ""}${path}`, { method: body === undefined ? "GET" : "POST", headers: { "content-type": "application/json", ...(generation === 2 ? { authorization: "Basic " + Buffer.from("opencode:" + (output.match(/server password (\S+)/)?.[1] || "")).toString("base64") } : {}) }, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(30000) });
+    const text = await response.text(); assert(response.ok, `${path}: ${response.status} ${text}`); return text ? JSON.parse(text) : null;
+  };
+  const h = {
+    nativePath, turns, api,
+    async configure(defaultAgent) { await writeFile(join(config, "opencode.json"), JSON.stringify({ ...(defaultAgent ? { default_agent: defaultAgent } : {}), provider: { fixture: { npm: "@ai-sdk/openai-compatible", options: { baseURL: endpoint + "/v1", apiKey: "local-fixture" }, models: { fixture: { name: "fixture", limit: { context: 32768, output: 256 } } } } } })); },
+    seed(value) {
+      seedValue = value;
+      repos.l3WorldModels.upsertField({ userId: "local-user", targetField: "general_rules_and_safety_constraints", value, eligibleL1MemoryIds: [] });
+      for (const row of db.db.prepare("SELECT DISTINCT project_id FROM sessions WHERE project_id IS NOT NULL").all()) {
+        repos.l3WorldModels.upsertField({ userId: "local-user", projectId: row.project_id, targetField: "project_contract", value });
+      }
+    },
+    stored: () => db.db.prepare("SELECT COUNT(*) AS n FROM source_turn_captures").get().n,
+    latestCapture: () => calls.filter(c => c.path === "/api/v1/source-turns/complete").at(-1)?.body,
+    captureResponses: () => calls.filter(c => c.path === "/api/v1/source-turns/complete").map(c => c.response?.body || {}),
+    lastRequest: () => JSON.stringify(calls.filter(c => c.path?.endsWith("/chat/completions")).at(-1)?.body),
+    l3Reads: () => calls.filter(c => c.path.includes("/context?")).length,
+    boundaries: () => calls.filter(c => c.path.endsWith("/l3-world-model-boundary")).length,
+    async start(binary, gen) {
+      generation = gen; output = ""; hostBinary = resolve(binary);
+      const observer = `export default { id: "review-observer", async server() { return { event: async ({event}) => fetch(${JSON.stringify(endpoint + "/events")}, {method:"POST",body:JSON.stringify(event)}) }; }, async setup(ctx) {
+        const stop = new AbortController();
+        const title = await ctx.session.hook("title", async event => { event.result = "Review fixture"; });
+        const job = (async()=> {try {for await(const event of ctx.event.subscribe({signal:stop.signal})) if(event.type.startsWith("session.")) await fetch(${JSON.stringify(endpoint + "/events")},{method:"POST",body:JSON.stringify(event)});}catch(e){if(!stop.signal.aborted)throw e;}})();
+        return async()=>{stop.abort();await job;await title.dispose();};
+      }};`;
+      await writeFile(join(config, "plugins/zz-review-observer.js"), observer);
+      const probe = createServer(); await listen(probe); port = probe.address().port; await shutdown(probe);
+      child = spawn(resolve(binary), ["serve", "--hostname", "127.0.0.1", "--port", String(port), "--print-logs", "--log-level", gen === 2 ? "debug" : "DEBUG"], { cwd: project, env, stdio: ["ignore", "pipe", "pipe"] });
+      child.stdout.on("data", c => output += c); child.stderr.on("data", c => output += c);
+      closed = new Promise(r => child.on("close", r));
+      await waitFor(async () => { try { await api("/session"); return true; } catch { return false; } }, 30000);
+    },
+    async stop() {
+      if (!child) return;
+      child.kill("SIGTERM"); const timer = setTimeout(() => child.kill("SIGKILL"), 10000);
+      await closed; clearTimeout(timer); child = undefined;
+      await writeFile(join(dir, `process-${generation}-${Date.now()}.log`), output.replace(/server password \S+/g, "server password [local test credential]"));
+    },
+    async session(agent) {
+      const response = await api("/session", generation === 2 ? { title: "Review fixture", ...(agent ? { agent } : {}), model: { providerID: "fixture", id: "fixture" }, location: { directory: project } } : { title: "Review fixture" });
+      return (response.data || response).id;
+    },
+    async waitTerminal(sessionID) {
+      await waitFor(() => events.slice(cursor).some(e => generation === 2 ? ["session.execution.succeeded", "session.execution.failed"].includes(e.type) && e.data.sessionID === sessionID : e.type === "session.idle" && e.properties.sessionID === sessionID), 25000);
+      cursor = events.length; await delay(500);
+    },
+    async prompt(session, text, agent, cli = false) {
+      // Concrete coding feedback remains capture-eligible even if prior fixture
+      // turns are recalled. Keep the real Memory content policy enabled.
+      text = "This implementation should preserve user data and verify the requested change. " + text;
+      cursor = events.length;
+      let cliTurn;
+      if (cli) {
+        const credential = output.match(/server password (\S+)/)?.[1];
+        const running = promisify(execFile)(hostBinary, ["run", "--server", `http://127.0.0.1:${port}`, "--session", session, "--model", "fixture/fixture", text], { cwd: project, env: { ...env, OPENCODE_PASSWORD: credential }, timeout: 30000 });
+        running.child.stdin.end();
+        await running;
+        const native = new DatabaseSync(nativePath, { readOnly: true });
+        try { cliTurn = native.prepare("SELECT id FROM session_message WHERE session_id = ? AND type = 'user' ORDER BY seq DESC LIMIT 1").get(session)?.id; } finally { native.close(); }
+      }
+      const answer = cli ? { id: cliTurn } : await api(`/session/${session}/${generation === 2 ? "prompt" : "message"}`, generation === 2 ? { text } : { parts: [{ type: "text", text }], model: { providerID: "fixture", modelID: "fixture" }, ...(agent ? { agent } : {}) });
+      await h.waitTerminal(session);
+      let turnId;
+      if (generation === 2) turnId = (answer.data || answer).id;
+      else {
+        const native = new DatabaseSync(nativePath, { readOnly: true });
+        try { turnId = native.prepare("SELECT id FROM message WHERE session_id = ? AND json_extract(data, '$.role') = 'user' ORDER BY time_created DESC, id DESC LIMIT 1").get(session)?.id; } finally { native.close(); }
+      }
+      turns.push({ session, turnId });
+      return turnId;
+    },
+    async compact(session, success) {
+      cursor = events.length; mode = success ? "compaction" : "failure";
+      await api(`/session/${session}/compact`, {});
+      await waitFor(() => events.slice(cursor).some(e => e.type === (success ? "session.compaction.ended" : "session.compaction.failed") && e.data.sessionID === session), 25000);
+      await delay(500); mode = "success";
+    },
+    async scanned(session, turnId) { return (await selectSourceTurn(readOpencodeDatabase(nativePath), { conversationId: session, turnId })).turn; },
+    async scan(session, turnId) {
+      const turn = await h.scanned(session, turnId); check(Boolean(turn), name + " scanner finds completed turn");
+      if (!turn) return;
+      const result = service.completeSourceTurn({ ...buildSourceTurnRequest(turn, "agent_source_scan"), namespace: { source: "opencode", profileId: turn.profileId, userId: "local-user" } });
+      check(result.status === "existing", name + " history scan deduplicates actual live storage: " + result.status + "/" + (result.reason || ""));
+    },
+    async close() {
+      await h.stop();
+      await writeFile(join(dir, "evidence.json"), JSON.stringify({ stored: h.stored(), turns, calls, events }, null, 2));
+      await shutdown(fixture); await shutdown(memoryServer); mf.cleanup();
+    }
+  };
+  await h.configure(); h.seed("MEMMY_L3_INITIAL");
+  return h;
+}
+async function listen(server) { await new Promise(r => server.listen(0, "127.0.0.1", r)); }
+async function shutdown(server) { server.closeAllConnections(); await new Promise(r => server.close(r)); }
+async function waitFor(predicate, timeout) {
+  const end = Date.now() + timeout;
+  while (Date.now() < end) { if (await predicate()) return; await delay(50); }
+  throw new Error("Timed out waiting for official host lifecycle");
+}
diff --git a/tests/opencode-compatibility.test.mjs b/tests/opencode-compatibility.test.mjs
index 48556e0ae..2ce9311a6 100644
--- a/tests/opencode-compatibility.test.mjs
+++ b/tests/opencode-compatibility.test.mjs
@@ -94,7 +94,7 @@ describe.each([["Backend", backend], ["Memory", memory]])("%s OpenCode upgrade",
       command: { async transform(fn) { fn({ add(c) { command = c; } }); return registration(); } },
       session: {
         async get() { return { agent: "build" }; },
-        async hook(name, fn) { expect(name).toBe("prompt"); promptHook = fn; return registration(); },
+        async hook(name, fn) { expect(["prompt", "context"]).toContain(name); if (name === "prompt") promptHook = fn; return registration(); },
         async prompt(input) { const event = { sessionID: input.sessionID, messageID: "resume", prompt: { text: input.text } }; await promptHook(event); return event; }
       },
       event: { async *subscribe(options) {
@@ -188,7 +188,7 @@ function writeV2Fixture(dataHome) {
 
 // This harness exercises installed artifacts with exact V2 event names. The
 // separate real-host script guards the contract against changes in OpenCode.
-async function lifecycleHarness(factory) {
+async function lifecycleHarness(factory, options = {}) {
   const { root, target } = fixture(factory);
   await target.installPlugin("opencode");
   const plugin = await load(root);
@@ -198,15 +198,19 @@ async function lifecycleHarness(factory) {
   vi.stubGlobal("fetch", vi.fn(async (url, init) => {
     const path = new URL(url).pathname, body = init?.body ? JSON.parse(init.body) : {};
     requests.push({ path, body });
-    return Response.json(path === "/api/v1/sessions/open" ? { sessionId: "memmy-session" }
+    return Response.json(options.l3 && path === "/api/v1/health" ? { features: { l3WorldModelProtocolVersions: [2] } }
+      : path === "/api/v1/sessions/open" ? { sessionId: "memmy-session" }
+      : path.endsWith("/context") ? { renderedContext: options.l3?.() || "" }
+      : path.endsWith("/l3-world-model-trace-head") ? { throughL1MemoryId: "trace" }
       : path === "/api/v1/turns/start" ? { turnId: body.turnId } : { status: "stored" });
   }));
-  const buffer = []; let wake; let prompt; let aborted = false;
+  const buffer = []; let wake; let prompt; let context; let aborted = false;
   const ctx = {
     location: { directory: root },
     tool: { async transform() { return { dispose() {} }; } },
     command: { async transform() { return { dispose() {} }; } },
-    session: { async get() { return { agent: "build" }; }, async hook(_, fn) { prompt = fn; return { dispose() {} }; } },
+    agent: { async list() { return [{ id: options.defaultAgent || "build", mode: "primary" }]; } },
+    session: { async get() { return { agent: options.defaultAgent ? undefined : "build" }; }, async hook(name, fn) { if (name === "prompt") prompt = fn; else if (name === "context") context = fn; return { dispose() {} }; } },
     event: { async *subscribe({ signal }) {
       signal.addEventListener("abort", () => { aborted = true; wake?.(); }, { once: true });
       while (!aborted) { if (!buffer.length) await new Promise(r => wake = r); while (buffer.length) yield buffer.shift(); }
@@ -214,7 +218,8 @@ async function lifecycleHarness(factory) {
   };
   const cleanup = await plugin.setup(ctx);
   return {
-    dbPath, cleanup, plugin,
+    dbPath, cleanup, plugin, requests,
+    context: async (system = []) => { const event = { sessionID: "session-1", agent: options.defaultAgent || "build", system }; await context(event); return event.system; },
     captures: () => requests.filter(r => r.path === "/api/v1/source-turns/complete").map(r => r.body),
     prompt: id => prompt({ sessionID: "session-1", messageID: id, prompt: { text: "Native request " + id } }),
     emit: (type, extra = {}) => { buffer.push({ type, data: { sessionID: "session-1", ...extra } }); wake?.(); }
@@ -308,3 +313,35 @@ describe.each([["Backend", backend], ["Memory", memory]])("%s turn lifecycle", (
     expect(h.captures()).toHaveLength(1);
   });
 });
+
+describe.each([["Backend", backend], ["Memory", memory]])("%s L3 and effective Agent", (_, factory) => {
+  it("initializes on actual use, coalesces concurrent reads and refreshes only a durable successful compaction", async () => {
+    let l3 = "INITIAL_L3";
+    const h = await lifecycleHarness(factory, { l3: () => l3, defaultAgent: "plan" });
+    const reads = () => h.requests.filter(r => r.path.endsWith("/context"));
+    const boundaries = () => h.requests.filter(r => r.path.endsWith("/l3-world-model-boundary"));
+    try {
+      // No session.created: same path for cold start and restored existing sessions.
+      await h.prompt("user-1");
+      const contexts = await Promise.all([h.context(), h.context()]);
+      expect(contexts.every(parts => JSON.stringify(parts).includes("INITIAL_L3"))).toBe(true);
+      expect(reads()).toHaveLength(1);
+      expect(h.requests.find(r => r.path === "/api/v1/sessions/open").body.namespace.profileId).toBe("plan");
+      expect(h.requests.find(r => r.path === "/api/v1/turns/start").body.namespace.profileId).toBe("plan");
+      expect(await h.context(contexts[0])).toHaveLength(1); // duplicate hook does not append twice
+      l3 = "UPDATED_L3";
+      const db = new DatabaseSync(h.dbPath);
+      db.prepare("INSERT INTO session_message VALUES ('compact', 'session-1', 'compaction', ?, 20, 20)").run(JSON.stringify({ status: "failed" }));
+      h.emit("session.compaction.failed");
+      expect(JSON.stringify(await h.context())).toContain("INITIAL_L3");
+      expect(reads()).toHaveLength(1); expect(boundaries()).toHaveLength(0);
+      db.prepare("UPDATE session_message SET data = ? WHERE id = 'compact'").run(JSON.stringify({ status: "completed" })); db.close();
+      h.emit("session.compaction.ended");
+      h.emit("session.compaction.ended");
+      const refreshed = await h.context();
+      expect(JSON.stringify(refreshed)).toContain("UPDATED_L3");
+      expect(JSON.stringify(refreshed)).not.toContain("INITIAL_L3");
+      expect(reads()).toHaveLength(2); expect(boundaries()).toHaveLength(1);
+    } finally { await h.cleanup(); }
+  });
+});

From a4b869c1ac0094c552b2ca608140d2bf014017a0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Tue, 20 Oct 2026 19:51:46 +0800
Subject: [PATCH 77/85] =?UTF-8?q?fix:=20=E4=BF=9D=E6=8C=81=20L3=20?=
 =?UTF-8?q?=E6=9A=82=E4=B8=8D=E5=8F=AF=E7=94=A8=E6=97=B6=E7=9A=84=20OpenCo?=
 =?UTF-8?q?de=20=E8=AE=B0=E5=BF=86=E9=87=87=E9=9B=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../templates/memmy-opencode-plugin.ts            | 14 +++++++++-----
 .../templates/memmy-opencode-plugin.ts            | 14 +++++++++-----
 tests/opencode-compatibility.test.mjs             | 15 +++++++++++++++
 3 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts b/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
index 6f010f85d..7503dfc78 100644
--- a/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
+++ b/App/backend/src/adapters/outbound/skill-writer/templates/memmy-opencode-plugin.ts
@@ -240,11 +240,15 @@ const createMemmyHooks = async ({ client, directory, worktree, resolveAgent, mod
       sessionAgents.set(input.sessionID, input.agent);
       const runtimeSession = await ensureSession(memmy, input.sessionID, input.agent);
       if (!modelContextL3) {
-        const context = await l3Context(input.sessionID, input.agent);
-        const state = l3States.get(input.sessionID);
-        if (state.pendingInjection) {
-          selectedContext = [selectedContext, context].filter(Boolean).join("\n\n");
-          state.pendingInjection = false;
+        try {
+          const context = await l3Context(input.sessionID, input.agent);
+          const state = l3States.get(input.sessionID);
+          if (state.pendingInjection) {
+            selectedContext = [selectedContext, context].filter(Boolean).join("\n\n");
+            state.pendingInjection = false;
+          }
+        } catch (error) {
+          log("warn", "Memmy L3 initialization deferred", { error: formatError(error), sessionID: input.sessionID });
         }
       }
       const sessionId = runtimeSession.sessionId;
diff --git a/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts b/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
index 6f010f85d..7503dfc78 100644
--- a/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
+++ b/Memory/src/agent-source/integration/templates/memmy-opencode-plugin.ts
@@ -240,11 +240,15 @@ const createMemmyHooks = async ({ client, directory, worktree, resolveAgent, mod
       sessionAgents.set(input.sessionID, input.agent);
       const runtimeSession = await ensureSession(memmy, input.sessionID, input.agent);
       if (!modelContextL3) {
-        const context = await l3Context(input.sessionID, input.agent);
-        const state = l3States.get(input.sessionID);
-        if (state.pendingInjection) {
-          selectedContext = [selectedContext, context].filter(Boolean).join("\n\n");
-          state.pendingInjection = false;
+        try {
+          const context = await l3Context(input.sessionID, input.agent);
+          const state = l3States.get(input.sessionID);
+          if (state.pendingInjection) {
+            selectedContext = [selectedContext, context].filter(Boolean).join("\n\n");
+            state.pendingInjection = false;
+          }
+        } catch (error) {
+          log("warn", "Memmy L3 initialization deferred", { error: formatError(error), sessionID: input.sessionID });
         }
       }
       const sessionId = runtimeSession.sessionId;
diff --git a/tests/opencode-compatibility.test.mjs b/tests/opencode-compatibility.test.mjs
index 2ce9311a6..f9c9f8a64 100644
--- a/tests/opencode-compatibility.test.mjs
+++ b/tests/opencode-compatibility.test.mjs
@@ -198,6 +198,7 @@ async function lifecycleHarness(factory, options = {}) {
   vi.stubGlobal("fetch", vi.fn(async (url, init) => {
     const path = new URL(url).pathname, body = init?.body ? JSON.parse(init.body) : {};
     requests.push({ path, body });
+    if (options.failL3 && path.endsWith("/context")) return Response.json({ error: "L3 temporarily unavailable" }, { status: 503 });
     return Response.json(options.l3 && path === "/api/v1/health" ? { features: { l3WorldModelProtocolVersions: [2] } }
       : path === "/api/v1/sessions/open" ? { sessionId: "memmy-session" }
       : path.endsWith("/context") ? { renderedContext: options.l3?.() || "" }
@@ -345,3 +346,17 @@ describe.each([["Backend", backend], ["Memory", memory]])("%s L3 and effective A
     } finally { await h.cleanup(); }
   });
 });
+
+
+describe.each([["Backend", backend], ["Memory", memory]])("%s V1 L3 degradation", (_, factory) => {
+  it("keeps recall and capture active when L3 initialization fails", async () => {
+    const h = await lifecycleHarness(factory, { l3: () => "unused", failL3: true });
+    const hooks = await h.plugin.server({ directory: "fixture" });
+    try {
+      await hooks["chat.message"]({ sessionID: "session-1", messageID: "user-1" }, { message: { id: "user-1", agent: "build" }, parts: [{ type: "text", text: "Inspect README" }] });
+      expect(h.requests.filter(r => r.path === "/api/v1/turns/start")).toHaveLength(1);
+      await hooks.event({ event: { type: "session.idle", properties: { sessionID: "session-1" } } });
+      await vi.waitFor(() => expect(h.captures()).toHaveLength(1));
+    } finally { await hooks.dispose(); await h.cleanup(); }
+  });
+});

From 7001b4f8ef13361e15df5a930777425832a626f4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=98=89?= <lijia@lijiadeMacBook-Pro.local>
Date: Tue, 20 Oct 2026 19:57:20 +0800
Subject: [PATCH 78/85] =?UTF-8?q?test:=20=E9=AA=8C=E8=AF=81=20OpenCode=20?=
 =?UTF-8?q?=E7=9C=9F=E5=AE=9E=E6=89=AB=E6=8F=8F=E5=85=88=E5=88=B0=E6=97=B6?=
 =?UTF-8?q?=E7=9A=84=E9=87=87=E9=9B=86=E5=8E=BB=E9=87=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/test-opencode-review.mjs | 31 +++++++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/scripts/test-opencode-review.mjs b/scripts/test-opencode-review.mjs
index 99c0f8281..915e654a3 100644
--- a/scripts/test-opencode-review.mjs
+++ b/scripts/test-opencode-review.mjs
@@ -74,9 +74,11 @@ for (const [name, factory] of [["Backend", backend], ["Memory", memory]]) {
     await h.prompt(second, "Review custom default agent without an explicit selection.", undefined, true);
     check(h.latestCapture()?.namespace?.profileId === "plan", name + " configured default plan is respected");
     check(h.lastRequest().includes("MEMMY_L3_RESTARTED"), name + " new session initializes current L3");
+    h.scanFirstNext();
     const third = await h.session("build");
     await h.prompt(third, "Review explicit build overrides default plan.");
     check(h.latestCapture()?.namespace?.profileId === "build", name + " explicit build overrides configured default");
+    check(h.scanFirstResults()[0]?.status === "stored" && h.captureResponses().at(-1)?.status === "existing", name + " actual scan-first stores once and live plugin capture deduplicates");
     check(h.captureResponses().every(r => ["stored", "existing"].includes(r.status)), name + " all live captures accepted by real Memory");
     console.log(name, "V2 real stored turns", h.stored());
   } finally { await h.close(); }
@@ -120,7 +122,8 @@ async function harness(name, factory) {
   const memoryServer = createMemoryHttpServer({ service, startAgentSourceAutomation: false, auth: { mode: "dev", allowAnonymous: true } });
   await listen(memoryServer);
   const memoryEndpoint = `http://127.0.0.1:${memoryServer.address().port}`;
-  const calls = [], events = [], turns = [];
+  const calls = [], events = [], turns = [], scanFirstResults = [];
+  let scanFirstPending = false;
   const seededProjects = new Set(); let seedValue = "MEMMY_L3_INITIAL";
   let mode = "success", serial = 0, generation = 2, child, closed, output = "", port, cursor = 0, hostBinary;
   const fixture = createServer(async (req, res) => {
@@ -140,6 +143,13 @@ async function harness(name, factory) {
         chunk({ role: "assistant", content: answer });
         chunk({}, "stop"); res.end("data: [DONE]\n\n"); return;
       }
+      if (req.url === "/api/v1/source-turns/complete" && scanFirstPending) {
+        scanFirstPending = false;
+        const scanned = await scanTurn(nativePath, body.sourceTurn.conversationId, body.sourceTurn.turnId);
+        const turn = scanned.turn;
+        assert(turn, "Scan-first must read the actual persisted native turn: " + scanned.reason);
+        scanFirstResults.push(service.completeSourceTurn({ ...buildSourceTurnRequest(turn, "agent_source_scan"), namespace: body.namespace }));
+      }
       const response = await fetch(memoryEndpoint + req.url, { method: req.method, headers: { ...req.headers, host: new URL(memoryEndpoint).host }, body: raw || undefined });
       const text = await response.text(); call.response = { code: response.status, body: JSON.parse(text) };
       const projectId = call.response.body.projectId;
@@ -148,7 +158,7 @@ async function harness(name, factory) {
         repos.l3WorldModels.upsertField({ userId: "local-user", projectId, targetField: "project_contract", value: seedValue });
       }
       res.writeHead(response.status, { "content-type": "application/json" }); res.end(text);
-    } catch (error) { res.writeHead(500); res.end(JSON.stringify({ error: String(error) })); }
+    } catch (error) { console.error("Review fixture request failed:", String(error)); res.writeHead(500); res.end(JSON.stringify({ error: String(error) })); }
   });
   await listen(fixture);
   const endpoint = `http://127.0.0.1:${fixture.address().port}`;
@@ -162,6 +172,8 @@ async function harness(name, factory) {
   };
   const h = {
     nativePath, turns, api,
+    scanFirstNext: () => { scanFirstPending = true; },
+    scanFirstResults: () => scanFirstResults,
     async configure(defaultAgent) { await writeFile(join(config, "opencode.json"), JSON.stringify({ ...(defaultAgent ? { default_agent: defaultAgent } : {}), provider: { fixture: { npm: "@ai-sdk/openai-compatible", options: { baseURL: endpoint + "/v1", apiKey: "local-fixture" }, models: { fixture: { name: "fixture", limit: { context: 32768, output: 256 } } } } } })); },
     seed(value) {
       seedValue = value;
@@ -236,7 +248,7 @@ async function harness(name, factory) {
       await waitFor(() => events.slice(cursor).some(e => e.type === (success ? "session.compaction.ended" : "session.compaction.failed") && e.data.sessionID === session), 25000);
       await delay(500); mode = "success";
     },
-    async scanned(session, turnId) { return (await selectSourceTurn(readOpencodeDatabase(nativePath), { conversationId: session, turnId })).turn; },
+    async scanned(session, turnId) { return (await scanTurn(nativePath, session, turnId)).turn; },
     async scan(session, turnId) {
       const turn = await h.scanned(session, turnId); check(Boolean(turn), name + " scanner finds completed turn");
       if (!turn) return;
@@ -245,7 +257,7 @@ async function harness(name, factory) {
     },
     async close() {
       await h.stop();
-      await writeFile(join(dir, "evidence.json"), JSON.stringify({ stored: h.stored(), turns, calls, events }, null, 2));
+      await writeFile(join(dir, "evidence.json"), JSON.stringify({ stored: h.stored(), turns, calls, events, scanFirstResults }, null, 2));
       await shutdown(fixture); await shutdown(memoryServer); mf.cleanup();
     }
   };
@@ -259,3 +271,14 @@ async function waitFor(predicate, timeout) {
   while (Date.now() < end) { if (await predicate()) return; await delay(50); }
   throw new Error("Timed out waiting for official host lifecycle");
 }
+
+async function scanTurn(path, conversationId, turnId) {
+  // selectSourceTurn deliberately rejects mixed conversations. The production
+  // scanner partitions by conversation before passing messages to this parser.
+  async function* conversation() {
+    for await (const message of readOpencodeDatabase(path)) {
+      if (message.conversationId === conversationId) yield message;
+    }
+  }
+  return selectSourceTurn(conversation(), { conversationId, turnId });
+}

From 26fd17f27659792cf401e7fc3d8f55bdfefdfaa3 Mon Sep 17 00:00:00 2001
From: jiachengzhen <jiacz@memtensor.cn>
Date: Wed, 21 Oct 2026 00:38:43 +0800
Subject: [PATCH 79/85] chore(release): prepare v1.2.4 metadata

---
 .github/release-notes/v1.2.4.md               | 12 +++++++
 App/backend/src/project-version.ts            |  2 +-
 App/memmy-agent/package-lock.json             | 36 ++-----------------
 App/memmy-agent/package.json                  |  2 +-
 .../apps/OpenComputerUseLinux/version.go      |  2 +-
 .../apps/OpenComputerUseWindows/version.go    |  2 +-
 .../OpenComputerUseVersion.swift              |  2 +-
 App/shell/desktop/package.json                |  2 +-
 package-lock.json                             |  6 ++--
 package.json                                  |  2 +-
 10 files changed, 24 insertions(+), 44 deletions(-)
 create mode 100644 .github/release-notes/v1.2.4.md

diff --git a/.github/release-notes/v1.2.4.md b/.github/release-notes/v1.2.4.md
new file mode 100644
index 000000000..907796dfd
--- /dev/null
+++ b/.github/release-notes/v1.2.4.md
@@ -0,0 +1,12 @@
+# Memmy v1.2.4
+
+基于 v1.2.3 之后已合入并验证的改动，发布稳定版 v1.2.4；本版本集中改进模型配置、Agent 运行时、Memory 可靠性、浏览器与电脑历史采集，以及跨平台运行时分发。
+
+- OpenCode V2 对话采集支持连续会话和真实扫描先到场景，补齐生命周期、去重和 L3 暂不可用时的可恢复行为；微信采集增加瞬态变化重试，并在退出时取消等待中的采集任务。
+- BYOK 与内置模型配置统一凭据来源和账号投影，连接测试隔离页面卸载后的响应，保留迁移后的模型模式；补充模型思考级别、token 预算、协议选择、视觉能力和 DeepSeek-V4.1-Flash-1017 能力登记。
+- Agent runtime 增强 Hook 生命周期、执行等待、OpenAI-compatible 请求、模型错误诊断和工具结果处理；显式停止取代整轮超时，恢复会话继续使用明确的模型选择。
+- Memory 改进跨账号候选去重、Embedding 输入校验与失败批次隔离、任务记忆删除、采集边界和运行时构建，并为各平台 runtime 产物生成校验和。
+- 桌面端补齐 slash command 与子命令建议、技能 Markdown 展示、社交登录入口、模型思考控制，以及浏览器和电脑历史授权与恢复路径；Windows History 与微信路径继续保留失败可见性和隐私边界。
+- 打包链路统一 Agent 与 Memory 多平台 runtime 构建、版本同步和依赖安装脚本，保持源码、安装包和运行时元数据一致；真实安装、覆盖升级和签名发布仍需按发版门禁分别验收。
+
+本文件只记录 v1.2.4 的版本范围；Full Harness 回归、独立审查、Draft PR、合并、签名 tag、打包和发布仍是相互独立的门槛。
diff --git a/App/backend/src/project-version.ts b/App/backend/src/project-version.ts
index 11f9a99d3..6852134c5 100644
--- a/App/backend/src/project-version.ts
+++ b/App/backend/src/project-version.ts
@@ -1,2 +1,2 @@
 /** Generated from the root package.json by scripts/sync-project-version.mjs. */
-export const MEMMY_VERSION = "1.2.3";
+export const MEMMY_VERSION = "1.2.4";
diff --git a/App/memmy-agent/package-lock.json b/App/memmy-agent/package-lock.json
index 8d0e9eb37..4231c796d 100644
--- a/App/memmy-agent/package-lock.json
+++ b/App/memmy-agent/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "memmy-agent",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "memmy-agent",
-      "version": "1.2.3",
+      "version": "1.2.4",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.100.1",
         "@aws-sdk/client-bedrock-runtime": "^3.1061.0",
@@ -1105,7 +1105,6 @@
       "version": "1.10.0",
       "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.10.0.tgz",
       "integrity": "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==",
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -1117,7 +1116,6 @@
       "version": "1.10.0",
       "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
       "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -1128,7 +1126,6 @@
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
       "integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -1827,7 +1824,6 @@
       "version": "1.1.4",
       "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.4.tgz",
       "integrity": "sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow==",
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -1954,7 +1950,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1969,7 +1964,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1986,7 +1980,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2003,7 +1996,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2020,7 +2012,6 @@
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2037,7 +2028,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2054,7 +2044,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2071,7 +2060,6 @@
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2088,7 +2076,6 @@
       "cpu": [
         "s390x"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2105,7 +2092,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2122,7 +2108,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2139,7 +2124,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2156,7 +2140,6 @@
       "cpu": [
         "wasm32"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -2175,7 +2158,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2192,7 +2174,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2578,7 +2559,6 @@
       "version": "0.10.2",
       "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.2.tgz",
       "integrity": "sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg==",
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -5684,7 +5664,6 @@
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
       "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
-      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
@@ -7025,7 +7004,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -7044,7 +7022,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -7065,7 +7042,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -7086,7 +7062,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -7107,7 +7082,6 @@
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -7128,7 +7102,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -7149,7 +7122,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -7170,7 +7142,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -7191,7 +7162,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -7212,7 +7182,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -7233,7 +7202,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MPL-2.0",
       "optional": true,
       "os": [
diff --git a/App/memmy-agent/package.json b/App/memmy-agent/package.json
index f83d2a011..9f0fcee55 100644
--- a/App/memmy-agent/package.json
+++ b/App/memmy-agent/package.json
@@ -1,6 +1,6 @@
 {
   "name": "memmy-agent",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "TypeScript refactor of memmy's agent runtime.",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/App/native-computer-use/apps/OpenComputerUseLinux/version.go b/App/native-computer-use/apps/OpenComputerUseLinux/version.go
index bc55d1b5b..c041e42e2 100644
--- a/App/native-computer-use/apps/OpenComputerUseLinux/version.go
+++ b/App/native-computer-use/apps/OpenComputerUseLinux/version.go
@@ -1,3 +1,3 @@
 package main
 
-var version = "1.2.3"
+var version = "1.2.4"
diff --git a/App/native-computer-use/apps/OpenComputerUseWindows/version.go b/App/native-computer-use/apps/OpenComputerUseWindows/version.go
index bc55d1b5b..c041e42e2 100644
--- a/App/native-computer-use/apps/OpenComputerUseWindows/version.go
+++ b/App/native-computer-use/apps/OpenComputerUseWindows/version.go
@@ -1,3 +1,3 @@
 package main
 
-var version = "1.2.3"
+var version = "1.2.4"
diff --git a/App/native-computer-use/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/OpenComputerUseVersion.swift b/App/native-computer-use/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/OpenComputerUseVersion.swift
index 109e7ebf7..744231161 100644
--- a/App/native-computer-use/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/OpenComputerUseVersion.swift
+++ b/App/native-computer-use/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/OpenComputerUseVersion.swift
@@ -1,6 +1,6 @@
 import Foundation
 
-public let openComputerUseVersion = "1.2.3"
+public let openComputerUseVersion = "1.2.4"
 
 public func resolvedOpenComputerUseVersion(bundle: Bundle = .main) -> String {
     if let version = bundle.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String,
diff --git a/App/shell/desktop/package.json b/App/shell/desktop/package.json
index e4514d9dc..55df2318e 100644
--- a/App/shell/desktop/package.json
+++ b/App/shell/desktop/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@memmy/desktop",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "private": true,
   "type": "module",
   "description": "Memmy desktop client.",
diff --git a/package-lock.json b/package-lock.json
index ff6f3ad21..eeda1125d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "memmy-agent",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "memmy-agent",
-      "version": "1.2.3",
+      "version": "1.2.4",
       "workspaces": [
         "Migrations",
         "AgentSourceCore",
@@ -590,7 +590,7 @@
     },
     "App/shell/desktop": {
       "name": "@memmy/desktop",
-      "version": "1.2.3",
+      "version": "1.2.4",
       "dependencies": {
         "@memmy/backend": "0.0.0",
         "@memmy/desktop-interface": "0.0.0",
diff --git a/package.json b/package.json
index 2f6f61fb0..78a1fc37a 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "memmy-agent",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "private": true,
   "type": "module",
   "description": "Local-first agent memory substrate with desktop and CLI surfaces.",

From 1c85772a880035d3809149a05e38c8600ffa14ca Mon Sep 17 00:00:00 2001
From: jiachengzhen <jiacz@memtensor.cn>
Date: Wed, 21 Oct 2026 01:17:21 +0800
Subject: [PATCH 80/85] fix(release): align provider lint and model key copy

---
 App/frontend/desktop/src/i18n/messages.ts | 4 ++++
 App/memmy-agent/src/providers/factory.ts  | 1 -
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/App/frontend/desktop/src/i18n/messages.ts b/App/frontend/desktop/src/i18n/messages.ts
index 9e2a85763..8d8143c4d 100644
--- a/App/frontend/desktop/src/i18n/messages.ts
+++ b/App/frontend/desktop/src/i18n/messages.ts
@@ -1982,6 +1982,8 @@ export const zhCNMessages = {
   "settings.modelWorkspace.endpoint": "Endpoint",
   "settings.modelWorkspace.initialModel": "首个模型名称",
   "settings.modelWorkspace.apiKey": "API Key",
+  "settings.modelWorkspace.replaceKey": "更换 API Key",
+  "settings.modelWorkspace.replaceKeyPlaceholder": "留空以保留现有 API Key，或输入新的 API Key",
   "settings.modelWorkspace.apiKeyPlaceholder": "输入你的 API Key",
   "settings.modelWorkspace.deleteTitle": "删除配置？",
   "settings.modelWorkspace.deleteConfirm": "删除 {provider} 配置后，其下模型会从当前空间和候选列表中移除。此操作需要重新添加才能恢复。",
@@ -4209,6 +4211,8 @@ export const enUSMessages: Record<keyof typeof zhCNMessages, string> = {
   "settings.modelWorkspace.endpoint": "Endpoint",
   "settings.modelWorkspace.initialModel": "First model name",
   "settings.modelWorkspace.apiKey": "API key",
+  "settings.modelWorkspace.replaceKey": "Replace API key",
+  "settings.modelWorkspace.replaceKeyPlaceholder": "Leave blank to keep the current API key, or enter a new one",
   "settings.modelWorkspace.apiKeyPlaceholder": "Enter your API key",
   "settings.modelWorkspace.deleteTitle": "Delete configuration?",
   "settings.modelWorkspace.deleteConfirm": "Deleting the {provider} configuration removes all of its models from this space and its candidate lists. Re-add the configuration to restore them.",
diff --git a/App/memmy-agent/src/providers/factory.ts b/App/memmy-agent/src/providers/factory.ts
index cc6ac81b3..57c89b7d6 100644
--- a/App/memmy-agent/src/providers/factory.ts
+++ b/App/memmy-agent/src/providers/factory.ts
@@ -175,7 +175,6 @@ export function makeProvider(
   }
 
   const opts = typeof optsOrModel === "string" ? { model: optsOrModel } : optsOrModel;
-  const resolved = resolveModelPreset(configOrName, opts);
   let provider = makeProviderCore(configOrName, opts);
   const fallbackPresets = resolveFallbackPresets(configOrName);
   if (fallbackPresets.length) {

From b0feb2156e4b9594e83f6f2d1e0997b84822ed95 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=95=E5=B8=83=E5=B8=83?=
 <lvbubu@MacBook-Pro-0018.local>
Date: Wed, 21 Oct 2026 12:30:43 +0800
Subject: [PATCH 81/85] fix(mac): collect task native agents when desktop exits

---
 .../src/main/computer-use-agent-restart.ts    | 185 ++++++--
 App/shell/desktop/src/main/main.ts            |  45 +-
 .../computer-history-permission-ipc.test.ts   |  24 +-
 .../tests/computer-use-agent-restart.test.ts  | 398 ++++++++++++++++++
 .../mac-permission-restart-lifecycle.test.ts  | 110 ++++-
 5 files changed, 718 insertions(+), 44 deletions(-)
 create mode 100644 App/shell/desktop/tests/computer-use-agent-restart.test.ts

diff --git a/App/shell/desktop/src/main/computer-use-agent-restart.ts b/App/shell/desktop/src/main/computer-use-agent-restart.ts
index 2844abfc5..76e38af8a 100644
--- a/App/shell/desktop/src/main/computer-use-agent-restart.ts
+++ b/App/shell/desktop/src/main/computer-use-agent-restart.ts
@@ -1,36 +1,169 @@
-import { spawn } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { constants, accessSync, realpathSync } from 'node:fs';
-import { basename, dirname, isAbsolute, join } from 'node:path';
-import { computerUseAgentEnvironment } from './memmy-screen-permission.js';
+import net from 'node:net';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 
-/** A permission change requires a fresh native TCC process before restarting Memmy. */
-export async function stopComputerUseAgentForPermissionRestart(
-  packaged: boolean,
-  resourcesPath: string,
-  developmentBinary?: string,
-): Promise<void> {
+const AGENT_MARKER = '__memmy-computer-use-app-agent';
+const SOCKET_NAME = /^memmy-computer-use-agent(?:-[a-f0-9]{16})?\.sock$/;
+const BUNDLE_IDS = new Set(['cn.memtensor.memmy', 'cn.memtensor.memmy.computeruse', 'cn.memtensor.memmy.computeruse.dev']);
+const PROCESS_QUERY_TIMEOUT_MS = 1_000;
+const AGENT_STOP_TIMEOUT_MS = 1_000;
+
+interface AgentProcess {
+  pid: number;
+  socketPath: string;
+}
+
+function resolveAgentBinary(packaged: boolean, resourcesPath: string, developmentBinary?: string): string | null {
+  if (process.platform !== 'darwin') return null;
   const candidate = packaged
     ? join(resourcesPath, 'app.asar.unpacked/dist/runtime/memmy-agent/dist/native-computer-use/Memmy Computer Use.app/Contents/MacOS/MemmyComputerUse')
     : developmentBinary;
-  if (!candidate || !isAbsolute(candidate) || basename(candidate) !== 'MemmyComputerUse') return;
-  let binary: string;
+  if (!candidate || !isAbsolute(candidate) || basename(candidate) !== 'MemmyComputerUse') return null;
   try {
     accessSync(candidate, constants.X_OK);
-    binary = realpathSync(candidate);
-  } catch { return; }
-  const app = dirname(dirname(dirname(binary)));
-  if (!['Memmy Computer Use.app', 'Memmy Computer Use (Dev).app'].includes(basename(app))) return;
-  const stopAgent = (env: NodeJS.ProcessEnv) => new Promise<void>((resolve) => {
-    const child = spawn(binary, ['__memmy-history', '--stop-agent'], {
-      stdio: 'ignore', windowsHide: true, env,
+    const binary = realpathSync(candidate);
+    if (basename(binary) !== 'MemmyComputerUse' || basename(dirname(binary)) !== 'MacOS'
+      || basename(dirname(dirname(binary))) !== 'Contents') return null;
+    const app = dirname(dirname(dirname(binary)));
+    return ['Memmy Computer Use.app', 'Memmy Computer Use (Dev).app'].includes(basename(app)) ? binary : null;
+  } catch { return null; }
+}
+
+/** LaunchServices owns these processes, so killing the gateway's process tree cannot collect them. */
+function listAgentProcesses(binary: string): AgentProcess[] {
+  const output = execFileSync('/bin/ps', ['-ww', '-axo', 'pid=,command='], {
+    encoding: 'utf8', timeout: PROCESS_QUERY_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024,
+  });
+  const marker = ` ${AGENT_MARKER} `;
+  const temporaryDirectory = realpathSync(tmpdir());
+  const agents: AgentProcess[] = [];
+  for (const line of output.split('\n')) {
+    const match = /^\s*(\d+)\s+(.+)$/.exec(line);
+    if (!match) continue;
+    const command = match[2]!;
+    const markerOffset = command.indexOf(marker);
+    if (markerOffset <= 0) continue;
+    const executable = command.slice(0, markerOffset);
+    if (!isAbsolute(executable)) continue;
+    const pid = Number(match[1]);
+    const socketPath = command.slice(markerOffset + marker.length);
+    if (!Number.isSafeInteger(pid) || pid <= 1 || pid === process.pid || !isAbsolute(socketPath)
+      || !SOCKET_NAME.test(basename(socketPath)) || resolve(socketPath) !== socketPath) continue;
+    try {
+      // LaunchServices/ps may preserve an alias such as /tmp versus /private/tmp.
+      if (realpathSync(executable) !== binary || realpathSync(dirname(socketPath)) !== temporaryDirectory) continue;
+      agents.push({ pid, socketPath });
+    } catch { /* A removed or foreign temporary directory is not owned by this app. */ }
+  }
+  return agents;
+}
+
+function stopVerifiedAgent(binary: string, agent: AgentProcess): Promise<void> {
+  const bundle = dirname(dirname(dirname(binary)));
+  return new Promise((resolveStop, rejectStop) => {
+    let connected = false;
+    let verified = false;
+    let accepted = false;
+    let finished = false;
+    let buffered = '';
+    const socket = net.createConnection(agent.socketPath);
+    const finish = (error?: Error) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      socket.destroy();
+      if (error) rejectStop(error); else resolveStop();
+    };
+    const timer = setTimeout(() => finish(new Error('Native Computer Use agent shutdown timed out')), AGENT_STOP_TIMEOUT_MS);
+    socket.setEncoding('utf8');
+    socket.on('connect', () => {
+      connected = true;
+      socket.write(JSON.stringify({ kind: 'agentInfo' }) + '\n');
+    });
+    socket.on('data', chunk => {
+      buffered += chunk;
+      if (buffered.length > 8192) { finish(new Error('Unexpected native agent lifecycle response')); return; }
+      let end: number;
+      while (!finished && (end = buffered.indexOf('\n')) >= 0) {
+        const line = buffered.slice(0, end);
+        buffered = buffered.slice(end + 1);
+        try {
+          const reply = JSON.parse(line);
+          if (!verified) {
+            if (!BUNDLE_IDS.has(reply.bundleIdentifier)
+              || realpathSync(reply.bundleURL) !== bundle || realpathSync(reply.executableURL) !== binary) {
+              throw new Error('Native agent identity does not match this Memmy installation');
+            }
+            verified = true;
+            socket.write(JSON.stringify({ kind: 'terminate' }) + '\n');
+          } else if (reply.ok === true) accepted = true;
+          else throw new Error('Native agent refused shutdown');
+        } catch (error) { finish(error instanceof Error ? error : new Error('Invalid native agent identity')); }
+      }
     });
-    const timer = setTimeout(() => child.kill('SIGTERM'), 4_000);
-    child.once('error', () => { clearTimeout(timer); resolve(); });
-    child.once('close', () => { clearTimeout(timer); resolve(); });
+    socket.on('error', error => {
+      if (!connected && ['ENOENT', 'ECONNREFUSED'].includes((error as NodeJS.ErrnoException).code ?? '')) finish();
+      else finish(error);
+    });
+    socket.on('close', () => finish(accepted ? undefined : new Error('Native agent closed without confirming shutdown')));
   });
-  // The previous release used the default socket from the desktop process;
-  // stop it once during migration as well as the app-scoped socket used now.
-  const legacyEnvironment = { ...process.env };
-  delete legacyEnvironment.OPEN_COMPUTER_USE_AGENT_SOCKET_NAMESPACE;
-  await Promise.all([stopAgent(computerUseAgentEnvironment(binary)), stopAgent(legacyEnvironment)]);
+}
+
+/** Whole-app shutdown collects base, legacy and task agents belonging to this installation. */
+export async function stopComputerUseAgentForPermissionRestart(
+  packaged: boolean,
+  resourcesPath: string,
+  developmentBinary?: string,
+): Promise<void> {
+  const binary = resolveAgentBinary(packaged, resourcesPath, developmentBinary);
+  if (!binary) return;
+  const results = await Promise.allSettled(listAgentProcesses(binary).map(agent => stopVerifiedAgent(binary, agent)));
+  const failures = results.filter(result => result.status === 'rejected');
+  if (failures.length > 0) {
+    throw new AggregateError(failures.map(result => result.reason), 'Some native Computer Use agents did not complete shutdown');
+  }
+}
+
+/** The quit deadline cannot await sockets. Recheck the actual executable before a final signal. */
+export function stopComputerUseAgentsOnExitSync(
+  packaged: boolean,
+  resourcesPath: string,
+  developmentBinary?: string,
+): void {
+  const binary = resolveAgentBinary(packaged, resourcesPath, developmentBinary);
+  if (!binary) return;
+  try {
+    const agents = listAgentProcesses(binary);
+    if (agents.length === 0) return;
+    // One bounded query keeps the quit deadline independent of the number of tasks.
+    // argv alone can be stale or misleading; verify each PID's actual mapped executable.
+    let files: string;
+    try {
+      files = execFileSync('/usr/sbin/lsof', ['-a', '-p', agents.map(agent => agent.pid).join(','), '-d', 'txt', '-Fn'], {
+        encoding: 'utf8', timeout: PROCESS_QUERY_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024,
+      });
+    } catch (error) {
+      // Some candidates may exit during the query. lsof still returns valid records for the survivors.
+      const partial = error as { status?: unknown; stdout?: unknown };
+      if (partial.status !== 1 || typeof partial.stdout !== 'string') throw error;
+      files = partial.stdout;
+    }
+    const candidates = new Set(agents.map(agent => agent.pid));
+    const verified = new Set<number>();
+    let pid = 0;
+    for (const line of files.split('\n')) {
+      if (/^p\d+$/.test(line)) pid = Number(line.slice(1));
+      if (!candidates.has(pid) || !line.startsWith('n')) continue;
+      try {
+        if (realpathSync(line.slice(1)) === binary) verified.add(pid);
+      } catch { /* An executable that cannot be resolved is not verified. */ }
+    }
+    for (const target of verified) {
+      try { process.kill(target, 'SIGKILL'); } catch { /* Already exited. */ }
+    }
+  } catch (error) {
+    console.warn('Could not inspect native Computer Use agents during exit:', error instanceof Error ? error.message : String(error));
+  }
 }
diff --git a/App/shell/desktop/src/main/main.ts b/App/shell/desktop/src/main/main.ts
index dbd7dc0bf..d1115931f 100644
--- a/App/shell/desktop/src/main/main.ts
+++ b/App/shell/desktop/src/main/main.ts
@@ -5,7 +5,7 @@ import { captureMemmyScreen, computerUseApp, memmyPermissionSnapshot, resolveCom
 import { desktopSaveFileName } from './save-file-name.js';
 import { createComputerUseOnboarding } from './computer-use-onboarding.js';
 import { createComputerUsePIPScreenPermissionGuide } from './computer-use-pip-screen-permission.js';
-import { stopComputerUseAgentForPermissionRestart } from './computer-use-agent-restart.js';
+import { stopComputerUseAgentForPermissionRestart, stopComputerUseAgentsOnExitSync } from './computer-use-agent-restart.js';
 import { createComputerUseSurfaceWindows } from './computer-use-surface-window.js';
 import { captureComputerUseWindow } from './computer-use-window-capture.js';
 import { createBrowserSidebarBridge } from './browser-sidebar-bridge.js';
@@ -1652,7 +1652,10 @@ function registerIpcHandlers(): void {
   ipcMain.handle("memmy:restart-for-computer-history-permissions", async () => {
     if (process.platform !== "darwin") throw new Error("Computer History permissions require macOS");
     await stopComputerUseAgentForPermissionRestart(app.isPackaged, process.resourcesPath,
-      process.env.MEMMY_DEV_COMPUTER_USE_BINARY);
+      process.env.MEMMY_DEV_COMPUTER_USE_BINARY).catch(error => {
+        // The normal quit path retries native cleanup and has a synchronous exit fallback.
+        console.warn("Failed to stop the native Computer Use agent before permission restart:", error);
+      });
     shouldRelaunchAfterQuitCleanup = true;
     // Let IPC finish, then reuse the normal recording/service shutdown path.
     setImmediate(() => app.quit());
@@ -6004,6 +6007,10 @@ app.on("before-quit", (event) => {
       clearQuitCleanupForceExitTimer();
       isQuitCleanupComplete = true;
       isQuitCleanupInProgress = false;
+      if (process.platform === 'darwin') {
+        stopComputerUseAgentsOnExitSync(app.isPackaged, process.resourcesPath,
+          process.env.MEMMY_DEV_COMPUTER_USE_BINARY);
+      }
       relaunchAfterQuitCleanupIfRequested();
       app.quit();
     });
@@ -6033,10 +6040,20 @@ function relaunchAfterQuitCleanupIfRequested(): void {
 
 function armQuitCleanupForceExitTimer(): void {
   clearQuitCleanupForceExitTimer();
+  // cleanupBeforeQuit clears the global while its asynchronous service close is pending.
+  const services = runtimeServices;
   quitCleanupForceExitTimer = setTimeout(() => {
     console.warn("quit cleanup timed out; forcing app exit");
     // Apply the same service-lifecycle choice when graceful cleanup times out.
-    runtimeServices?.terminateSync({ stopMemory: stopMemoryServiceForCurrentQuit });
+    try {
+      services?.terminateSync({ stopMemory: stopMemoryServiceForCurrentQuit });
+    } catch (error) {
+      console.warn("Failed to terminate runtime services during forced quit:", error);
+    }
+    if (process.platform === 'darwin') {
+      stopComputerUseAgentsOnExitSync(app.isPackaged, process.resourcesPath,
+        process.env.MEMMY_DEV_COMPUTER_USE_BINARY);
+    }
     relaunchAfterQuitCleanupIfRequested();
     app.exit(0);
   }, APP_QUIT_CLEANUP_FORCE_EXIT_DELAY_MS);
@@ -6152,15 +6169,19 @@ async function cleanupBeforeQuit(): Promise<void> {
   browserWebviewDownloads = null;
   disposeBrowserWebviewPermissions?.();
   disposeBrowserWebviewPermissions = null;
-  await services?.close({ stopMemory: stopMemoryServiceForCurrentQuit });
-  // History permission checks run through the separate signed native app
-  // agent. It can outlive Electron when macOS performs “Quit & Reopen”, and
-  // then keeps the old TCC preflight result on the next launch. Stop any
-  // leftover agent so the next process observes the current grant.
-  await stopComputerUseAgentForPermissionRestart(app.isPackaged, process.resourcesPath,
-    process.env.MEMMY_DEV_COMPUTER_USE_BINARY).catch(error => {
-      console.warn("Failed to stop the native Computer Use agent during quit cleanup:", error);
-    });
+  // Native app agents belong to LaunchServices, outside the gateway process tree.
+  // Start their shutdown before awaiting services, which may fail or hit the quit deadline.
+  const nativeAgentShutdown = process.platform === 'darwin'
+    ? stopComputerUseAgentForPermissionRestart(app.isPackaged, process.resourcesPath,
+      process.env.MEMMY_DEV_COMPUTER_USE_BINARY).catch(error => {
+        console.warn("Failed to stop the native Computer Use agent during quit cleanup:", error);
+      })
+    : Promise.resolve();
+  try {
+    await services?.close({ stopMemory: stopMemoryServiceForCurrentQuit });
+  } finally {
+    await nativeAgentShutdown;
+  }
   browserSidebarBridge?.dispose();
   browserSidebarBridge = null;
   embeddedBrowserDriver.dispose();
diff --git a/App/shell/desktop/tests/computer-history-permission-ipc.test.ts b/App/shell/desktop/tests/computer-history-permission-ipc.test.ts
index ee63a3e3e..f393afe04 100644
--- a/App/shell/desktop/tests/computer-history-permission-ipc.test.ts
+++ b/App/shell/desktop/tests/computer-history-permission-ipc.test.ts
@@ -51,6 +51,7 @@ function loadPermissionIpc(platform: NodeJS.Platform) {
   const deferred: Array<() => void> = [];
   const app = { quit: vi.fn(), relaunch: vi.fn() };
   const stopComputerUseAgentForPermissionRestart = vi.fn().mockResolvedValue(undefined);
+  const warn = vi.fn();
   const createSessionId = vi.fn(randomUUID);
   let systemSessionEnding = false;
   const ipcMain = {
@@ -74,9 +75,9 @@ function loadPermissionIpc(platform: NodeJS.Platform) {
     compilerOptions: { target: ts.ScriptTarget.ES2022 },
   }).outputText;
   // Execute the real handler bodies without importing Electron's app entrypoint.
-  const lifecycle = Function("ipcMain", "app", "process", "setImmediate", "randomUUID", "writePackagedStartupLog", "stopComputerUseAgentForPermissionRestart", "isMacSystemSessionEnding", compiled)(
+  const lifecycle = Function("ipcMain", "app", "process", "setImmediate", "randomUUID", "writePackagedStartupLog", "stopComputerUseAgentForPermissionRestart", "isMacSystemSessionEnding", "console", compiled)(
     ipcMain, app, { platform, env: {}, argv: ["Memmy"] }, (callback: () => void) => deferred.push(callback), createSessionId, vi.fn(), stopComputerUseAgentForPermissionRestart,
-    () => systemSessionEnding,
+    () => systemSessionEnding, { warn },
   ) as { relaunchRequested(): boolean; finishCleanup(): void; removeHandlers(): void };
 
   let api: PermissionApi | undefined;
@@ -105,7 +106,7 @@ function loadPermissionIpc(platform: NodeJS.Platform) {
     module, module.exports, { platform },
   );
   if (!api) throw new Error("Preload did not expose the Memmy API");
-  return { api, app, deferred, handlers, createSessionId, ipcRenderer, stopComputerUseAgentForPermissionRestart,
+  return { api, app, deferred, handlers, createSessionId, ipcRenderer, stopComputerUseAgentForPermissionRestart, warn,
     setSystemSessionEnding: (next: boolean) => { systemSessionEnding = next; }, ...lifecycle };
 }
 
@@ -183,6 +184,23 @@ describe("Computer History permission IPC", () => {
     expect(shell.app.relaunch).not.toHaveBeenCalled();
   });
 
+  it("continues permission restart through normal quit cleanup if native shutdown fails", async () => {
+    const shell = loadPermissionIpc("darwin");
+    const error = new Error("native agent shutdown timed out");
+    shell.stopComputerUseAgentForPermissionRestart.mockRejectedValueOnce(error);
+    await expect(shell.api.restartForComputerHistoryPermissions()).resolves.toBeUndefined();
+    expect(shell.warn).toHaveBeenCalledWith(
+      "Failed to stop the native Computer Use agent before permission restart:", error);
+    expect(shell.relaunchRequested()).toBe(true);
+    expect(shell.app.quit).not.toHaveBeenCalled();
+    expect(shell.deferred).toHaveLength(1);
+    shell.deferred[0]();
+    expect(shell.app.quit).toHaveBeenCalledOnce();
+    shell.finishCleanup();
+    expect(shell.app.relaunch).toHaveBeenCalledExactlyOnceWith({ args: [] });
+    expect(shell.relaunchRequested()).toBe(false);
+  });
+
   it("a system-session quit overrides a pending explicit History permission restart", async () => {
     const shell = loadPermissionIpc("darwin");
     await shell.api.restartForComputerHistoryPermissions();
diff --git a/App/shell/desktop/tests/computer-use-agent-restart.test.ts b/App/shell/desktop/tests/computer-use-agent-restart.test.ts
new file mode 100644
index 000000000..a998ef05e
--- /dev/null
+++ b/App/shell/desktop/tests/computer-use-agent-restart.test.ts
@@ -0,0 +1,398 @@
+import { once } from 'node:events';
+import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  stopComputerUseAgentForPermissionRestart,
+  stopComputerUseAgentsOnExitSync,
+} from '../src/main/computer-use-agent-restart.js';
+
+const mocks = vi.hoisted(() => ({ execFileSync: vi.fn(), temporaryDirectory: '' }));
+vi.mock('node:child_process', async (importOriginal) => ({
+  ...await importOriginal<typeof import('node:child_process')>(),
+  execFileSync: mocks.execFileSync,
+}));
+vi.mock('node:os', async (importOriginal) => {
+  const original = await importOriginal<typeof import('node:os')>();
+  const tmpdir = () => mocks.temporaryDirectory || original.tmpdir();
+  return { ...original, tmpdir, default: { ...original.default, tmpdir } };
+});
+
+const hostPlatform = process.platform;
+const platformDescriptor = Object.getOwnPropertyDescriptor(process, 'platform')!;
+const cleanups: Array<() => void | Promise<void>> = [];
+let processRows: string[] = [];
+let textFiles: Map<number, string | Error>;
+let kill: ReturnType<typeof vi.spyOn>;
+
+function asPlatform(platform: NodeJS.Platform): void {
+  Object.defineProperty(process, 'platform', { value: platform, configurable: true });
+}
+
+function fixture(development = false) {
+  // A separate short socket directory keeps fixtures below macOS's Unix socket
+  // path limit and prevents discovery or connection to any real Memmy agent.
+  const root = realpathSync(mkdtempSync('/tmp/memmy-quit-'));
+  mocks.temporaryDirectory = root;
+  cleanups.push(() => rmSync(root, { recursive: true, force: true }));
+  const resources = path.join(root, 'Applications with spaces/Memmy.app/Contents/Resources');
+  const bundle = development ? path.join(root, 'Memmy Computer Use (Dev).app')
+    : path.join(resources, 'app.asar.unpacked/dist/runtime/memmy-agent/dist/native-computer-use/Memmy Computer Use.app');
+  const binary = path.join(bundle, 'Contents/MacOS/MemmyComputerUse');
+  mkdirSync(path.dirname(binary), { recursive: true });
+  writeFileSync(binary, 'test fixture; never execute');
+  chmodSync(binary, 0o755);
+  const socket = (hash?: string) => path.join(root, `memmy-computer-use-agent${hash ? `-${hash}` : ''}.sock`);
+  const info = { bundleIdentifier: 'cn.memtensor.memmy', bundleURL: bundle, executableURL: binary };
+  return { root, resources, bundle, binary, socket, info };
+}
+
+type Fixture = ReturnType<typeof fixture>;
+type Request = { kind: string };
+function row(f: Fixture, pid: number, socket: string, binary = f.binary): string {
+  return `${pid} ${binary} __memmy-computer-use-app-agent ${socket}`;
+}
+
+async function agent(socketPath: string, respond: (request: Request, socket: net.Socket) => void) {
+  const requests: string[] = [];
+  const sockets = new Set<net.Socket>();
+  const server = net.createServer(socket => {
+    sockets.add(socket);
+    socket.on('error', () => {});
+    socket.on('close', () => sockets.delete(socket));
+    socket.setEncoding('utf8');
+    let buffered = '';
+    socket.on('data', data => {
+      buffered += data;
+      let end: number;
+      while ((end = buffered.indexOf('\n')) >= 0) {
+        const request = JSON.parse(buffered.slice(0, end)) as Request;
+        buffered = buffered.slice(end + 1);
+        requests.push(request.kind);
+        respond(request, socket);
+      }
+    });
+  });
+  cleanups.push(async () => {
+    for (const socket of sockets) socket.destroy();
+    await new Promise<void>(resolve => server.close(() => resolve()));
+  });
+  server.listen(socketPath);
+  await once(server, 'listening');
+  return { requests, sockets };
+}
+
+function shutdownReply(f: Fixture, request: Request, socket: net.Socket): void {
+  if (request.kind === 'agentInfo') socket.write(`${JSON.stringify(f.info)}\n`);
+  else if (request.kind === 'terminate') socket.end('{"ok":true}\n');
+}
+
+describe.skipIf(hostPlatform === 'win32')('Computer Use cleanup for a complete desktop exit', () => {
+  beforeEach(() => {
+    asPlatform('darwin');
+    processRows = [];
+    textFiles = new Map();
+    mocks.execFileSync.mockReset();
+    mocks.execFileSync.mockImplementation((file: string, args: string[]) => {
+      if (file === '/bin/ps') return `${processRows.join('\n')}\n`;
+      if (file === '/usr/sbin/lsof') {
+        return args[args.indexOf('-p') + 1]!.split(',').map(value => {
+          const result = textFiles.get(Number(value));
+          if (result instanceof Error) throw result;
+          return result ?? '';
+        }).join('');
+      }
+      throw new Error(`Unexpected subprocess: ${file}`);
+    });
+    // Every signal is intercepted: fixture PIDs never identify real processes.
+    kill = vi.spyOn(process, 'kill').mockImplementation(() => true);
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(async () => {
+    for (const cleanup of cleanups.splice(0).reverse()) await cleanup();
+    mocks.temporaryDirectory = '';
+    Object.defineProperty(process, 'platform', platformDescriptor);
+    vi.restoreAllMocks();
+  });
+
+  it('stops task, base and legacy agents belonging to this installation', async () => {
+    const f = fixture();
+    const sockets = [f.socket('a'.repeat(16)), f.socket('b'.repeat(16)), f.socket('c'.repeat(16)), f.socket()];
+    const agents = await Promise.all(sockets.map(socket => agent(socket, (request, connection) => shutdownReply(f, request, connection))));
+    processRows = sockets.map((socket, index) => row(f, 900_001 + index, socket));
+
+    await stopComputerUseAgentForPermissionRestart(true, f.resources);
+
+    for (const native of agents) expect(native.requests).toEqual(['agentInfo', 'terminate']);
+    expect(kill).not.toHaveBeenCalled();
+    expect(mocks.execFileSync).toHaveBeenCalledWith('/bin/ps', ['-ww', '-axo', 'pid=,command='],
+      expect.objectContaining({ encoding: 'utf8', timeout: 1000 }));
+  });
+
+  it('waits for the verified helper to close after acknowledging terminate', async () => {
+    const f = fixture();
+    const socketPath = f.socket('a'.repeat(16));
+    let close!: () => void;
+    const native = await agent(socketPath, (request, socket) => {
+      if (request.kind === 'agentInfo') socket.write(`${JSON.stringify(f.info)}\n`);
+      else { socket.write('{"ok":true}\n'); close = () => socket.end(); }
+    });
+    processRows = [row(f, 900_001, socketPath)];
+    let finished = false;
+    const stopping = stopComputerUseAgentForPermissionRestart(true, f.resources).then(() => { finished = true; });
+    await vi.waitFor(() => expect(close).toBeTypeOf('function'));
+    expect(native.requests).toEqual(['agentInfo', 'terminate']);
+    expect(finished).toBe(false);
+    close();
+    await stopping;
+    expect(finished).toBe(true);
+  });
+
+  it('collects this installation when ps and lsof report a legitimate executable path alias', async () => {
+    const f = fixture();
+    const aliasBundle = path.join(f.root, 'Linked helper.app');
+    symlinkSync(f.bundle, aliasBundle, 'dir');
+    const aliasBinary = path.join(aliasBundle, 'Contents/MacOS/MemmyComputerUse');
+    const socketPath = f.socket('a'.repeat(16));
+    const native = await agent(socketPath, (request, socket) => shutdownReply(f, request, socket));
+    processRows = [row(f, 900_001, socketPath, aliasBinary)];
+    textFiles.set(900_001, `p900001\nn${aliasBinary}\n`);
+
+    await stopComputerUseAgentForPermissionRestart(true, f.resources);
+    stopComputerUseAgentsOnExitSync(true, f.resources);
+
+    expect(native.requests).toEqual(['agentInfo', 'terminate']);
+    expect(kill).toHaveBeenCalledExactlyOnceWith(900_001, 'SIGKILL');
+  });
+
+  it.each(['cn.memtensor.memmy.computeruse', 'cn.memtensor.memmy.computeruse.dev'])('accepts the upgrade-compatible helper identity %s', async bundleIdentifier => {
+    const f = fixture();
+    f.info.bundleIdentifier = bundleIdentifier;
+    const socketPath = f.socket('a'.repeat(16));
+    const native = await agent(socketPath, (request, socket) => shutdownReply(f, request, socket));
+    processRows = [row(f, 900_001, socketPath)];
+    await stopComputerUseAgentForPermissionRestart(true, f.resources);
+    expect(native.requests).toEqual(['agentInfo', 'terminate']);
+  });
+
+  it.each(['bundleIdentifier', 'bundleURL', 'executableURL'] as const)('does not send terminate when %s identifies another installation', async field => {
+    const f = fixture();
+    const socketPath = f.socket('a'.repeat(16));
+    const native = await agent(socketPath, (_request, socket) => socket.end(`${JSON.stringify({ ...f.info, [field]: '/another/Memmy.app' })}\n`));
+    processRows = [row(f, 900_001, socketPath)];
+    await expect(stopComputerUseAgentForPermissionRestart(true, f.resources)).rejects.toThrow();
+    expect(native.requests).toEqual(['agentInfo']);
+    expect(kill).not.toHaveBeenCalled();
+  });
+
+  it('rejects other copies, ambiguous command lines and sockets outside the current temporary directory', async () => {
+    const f = fixture();
+    const socketPath = f.socket('a'.repeat(16));
+    const native = await agent(socketPath, (request, socket) => shutdownReply(f, request, socket));
+    processRows = [
+      row(f, 900_001, socketPath, `/other${f.binary}`),
+      `900002 /bin/sh -c ${f.binary} __memmy-computer-use-app-agent ${socketPath}`,
+      `900003 ${f.binary} __memmy-computer-use-app-agent ${socketPath} --extra`,
+      `900004 ${f.binary} __memmy-computer-use-app-agent ${socketPath} ${socketPath}`,
+      `900005 ${f.binary} __memmy-computer-use-app-agentX ${socketPath}`,
+      row(f, 900_006, path.join(f.root, 'nested', path.basename(socketPath))),
+      row(f, 900_007, path.join('/other', path.basename(socketPath))),
+      row(f, 900_008, f.socket('A'.repeat(16))),
+      row(f, 900_009, f.socket('a'.repeat(15))),
+      row(f, 900_010, path.join(f.root, 'unrelated.sock')),
+      row(f, 0, socketPath),
+      row(f, -1, socketPath),
+      `${f.binary} __memmy-computer-use-app-agent ${socketPath}`,
+    ];
+    await stopComputerUseAgentForPermissionRestart(true, f.resources);
+    stopComputerUseAgentsOnExitSync(true, f.resources);
+    expect(native.requests).toEqual([]);
+    expect(kill).not.toHaveBeenCalled();
+    expect(mocks.execFileSync.mock.calls.filter(([file]) => file === '/usr/sbin/lsof')).toEqual([]);
+  });
+
+  it('never terminates an existing different installation even when a command line claims our executable', async () => {
+    const f = fixture();
+    const otherBundle = path.join(f.root, 'Another installation/Memmy Computer Use.app');
+    const otherBinary = path.join(otherBundle, 'Contents/MacOS/MemmyComputerUse');
+    mkdirSync(path.dirname(otherBinary), { recursive: true });
+    writeFileSync(otherBinary, 'another test installation; never execute');
+    chmodSync(otherBinary, 0o755);
+    const socketPath = f.socket('d'.repeat(16));
+    const native = await agent(socketPath, (_request, socket) => socket.end(`${JSON.stringify({
+      ...f.info, bundleURL: otherBundle, executableURL: otherBinary,
+    })}\n`));
+    processRows = [row(f, 900_001, socketPath, otherBinary), row(f, 900_002, socketPath)];
+    textFiles.set(900_002, `p900002\nn${otherBinary}\n`);
+
+    await expect(stopComputerUseAgentForPermissionRestart(true, f.resources)).rejects.toThrow();
+    stopComputerUseAgentsOnExitSync(true, f.resources);
+
+    expect(native.requests).toEqual(['agentInfo']);
+    expect(kill).not.toHaveBeenCalled();
+  });
+
+  it('tolerates an already removed socket and safely rejects a stale non-socket file', async () => {
+    const f = fixture();
+    const stale = f.socket('b'.repeat(16));
+    writeFileSync(stale, 'stale socket fixture');
+    processRows = [row(f, 900_001, f.socket('a'.repeat(16)))];
+    await expect(stopComputerUseAgentForPermissionRestart(true, f.resources)).resolves.toBeUndefined();
+    processRows = [row(f, 900_002, stale)];
+    await expect(stopComputerUseAgentForPermissionRestart(true, f.resources)).rejects.toThrow();
+    expect(kill).not.toHaveBeenCalled();
+  });
+
+  it('bounds an unresponsive helper and uses executable-verified synchronous exit cleanup', async () => {
+    const f = fixture();
+    const socketPath = f.socket('a'.repeat(16));
+    const native = await agent(socketPath, () => {});
+    processRows = [row(f, 900_001, socketPath)];
+    textFiles.set(900_001, `p900001\nn${f.binary}\n`);
+    const began = Date.now();
+    await expect(stopComputerUseAgentForPermissionRestart(true, f.resources)).rejects.toThrow();
+    expect(Date.now() - began).toBeLessThan(2500);
+    expect(native.requests).toEqual(['agentInfo']);
+    expect(kill).not.toHaveBeenCalled();
+
+    stopComputerUseAgentsOnExitSync(true, f.resources);
+
+    expect(mocks.execFileSync).toHaveBeenCalledWith('/usr/sbin/lsof', ['-a', '-p', '900001', '-d', 'txt', '-Fn'],
+      expect.objectContaining({ encoding: 'utf8' }));
+    expect(kill).toHaveBeenCalledExactlyOnceWith(900_001, 'SIGKILL');
+  });
+
+  it('bounds a terminate acknowledgement whose connection never closes', async () => {
+    const f = fixture();
+    const socketPath = f.socket('a'.repeat(16));
+    const native = await agent(socketPath, (request, socket) => socket.write(`${JSON.stringify(request.kind === 'agentInfo' ? f.info : { ok: true })}\n`));
+    processRows = [row(f, 900_001, socketPath)];
+    const began = Date.now();
+    await expect(stopComputerUseAgentForPermissionRestart(true, f.resources)).rejects.toThrow();
+    expect(Date.now() - began).toBeLessThan(2500);
+    expect(native.requests).toEqual(['agentInfo', 'terminate']);
+  });
+
+  it.each(['{not json}\n', `${'x'.repeat(9000)}\n`])('does not terminate a helper sending an invalid identity response', async response => {
+    const f = fixture();
+    const socketPath = f.socket('a'.repeat(16));
+    const native = await agent(socketPath, (_request, socket) => socket.end(response));
+    processRows = [row(f, 900_001, socketPath)];
+    await expect(stopComputerUseAgentForPermissionRestart(true, f.resources)).rejects.toThrow();
+    expect(native.requests).toEqual(['agentInfo']);
+  });
+
+  it('rechecks executable text before signalling and skips changed or unavailable processes', () => {
+    const f = fixture();
+    processRows = [1, 2, 3, 4].map(index => row(f, 900_000 + index, f.socket(index.toString().repeat(16))));
+    textFiles.set(900_001, `p900001\nn${f.binary}\n`);
+    textFiles.set(900_002, `p900002\nn${f.binary}.another-copy\n`);
+    textFiles.set(900_003, '');
+    textFiles.set(900_004, `p900004\nn/other/MemmyComputerUse\n`);
+    stopComputerUseAgentsOnExitSync(true, f.resources);
+    expect(kill).toHaveBeenCalledExactlyOnceWith(900_001, 'SIGKILL');
+  });
+
+  it('cleans every verified process and can safely run again after they exit', () => {
+    const f = fixture();
+    processRows = [row(f, 900_001, f.socket('a'.repeat(16))), row(f, 900_002, f.socket())];
+    for (const pid of [900_001, 900_002]) textFiles.set(pid, `p${pid}\nn${f.binary}\n`);
+    kill.mockImplementation((pid: number) => { processRows = processRows.filter(line => !line.startsWith(`${pid} `)); return true; });
+    stopComputerUseAgentsOnExitSync(true, f.resources);
+    stopComputerUseAgentsOnExitSync(true, f.resources);
+    expect(kill.mock.calls).toEqual([[900_001, 'SIGKILL'], [900_002, 'SIGKILL']]);
+  });
+
+  it('continues cleaning sibling helpers when signalling one fails', () => {
+    const f = fixture();
+    processRows = [row(f, 900_001, f.socket('a'.repeat(16))), row(f, 900_002, f.socket('b'.repeat(16)))];
+    for (const pid of [900_001, 900_002]) textFiles.set(pid, `p${pid}\nn${f.binary}\n`);
+    kill.mockImplementation((pid: number) => { if (pid === 900_001) throw new Error('ESRCH'); return true; });
+    expect(() => stopComputerUseAgentsOnExitSync(true, f.resources)).not.toThrow();
+    expect(kill).toHaveBeenCalledWith(900_002, 'SIGKILL');
+  });
+
+  it('uses verified partial lsof output when one queried process has already exited', () => {
+    const f = fixture();
+    processRows = [row(f, 900_001, f.socket('a'.repeat(16))), row(f, 900_002, f.socket('b'.repeat(16)))];
+    mocks.execFileSync.mockImplementation((file: string) => {
+      if (file === '/bin/ps') return `${processRows.join('\n')}\n`;
+      throw Object.assign(new Error('one process has exited'), { status: 1, stdout: `p900001\nn${f.binary}\n` });
+    });
+
+    expect(() => stopComputerUseAgentsOnExitSync(true, f.resources)).not.toThrow();
+
+    expect(kill).toHaveBeenCalledExactlyOnceWith(900_001, 'SIGKILL');
+  });
+
+  it.each(['other-status', 'buffer-output', 'no-status', 'timed-out'] as const)('does not use failed lsof output with %s', failure => {
+    const f = fixture();
+    processRows = [row(f, 900_001, f.socket('a'.repeat(16)))];
+    const stdout = `p900001\nn${f.binary}\n`;
+    mocks.execFileSync.mockImplementation((file: string) => {
+      if (file === '/bin/ps') return `${processRows.join('\n')}\n`;
+      throw Object.assign(new Error('lsof failed'), {
+        status: failure === 'other-status' ? 2 : failure === 'no-status' ? undefined : failure === 'timed-out' ? null : 1,
+        code: failure === 'timed-out' ? 'ETIMEDOUT' : undefined,
+        signal: failure === 'timed-out' ? 'SIGTERM' : undefined,
+        stdout: failure === 'buffer-output' ? Buffer.from(stdout) : stdout,
+      });
+    });
+
+    expect(() => stopComputerUseAgentsOnExitSync(true, f.resources)).not.toThrow();
+
+    expect(kill).not.toHaveBeenCalled();
+    expect(console.warn).toHaveBeenCalled();
+  });
+
+  it('supports a development helper only when it belongs to the expected app bundle', async () => {
+    const f = fixture(true);
+    const socketPath = f.socket('a'.repeat(16));
+    const native = await agent(socketPath, (request, socket) => shutdownReply(f, request, socket));
+    processRows = [row(f, 900_001, socketPath)];
+    await stopComputerUseAgentForPermissionRestart(false, '', f.binary);
+    expect(native.requests).toEqual(['agentInfo', 'terminate']);
+
+    mocks.execFileSync.mockClear();
+    const unrelated = path.join(f.root, 'Other.app/Contents/MacOS/MemmyComputerUse');
+    mkdirSync(path.dirname(unrelated), { recursive: true });
+    writeFileSync(unrelated, 'fixture'); chmodSync(unrelated, 0o755);
+    await stopComputerUseAgentForPermissionRestart(false, '', unrelated);
+    stopComputerUseAgentsOnExitSync(false, '', unrelated);
+    expect(mocks.execFileSync).not.toHaveBeenCalled();
+  });
+
+  it('does not inspect processes when the binary is missing, relative or non-executable', async () => {
+    const f = fixture();
+    chmodSync(f.binary, 0o644);
+    for (const binary of [undefined, 'relative/MemmyComputerUse', path.join(f.root, 'missing'), f.binary]) {
+      await stopComputerUseAgentForPermissionRestart(false, '', binary);
+      stopComputerUseAgentsOnExitSync(false, '', binary);
+    }
+    expect(mocks.execFileSync).not.toHaveBeenCalled();
+    expect(kill).not.toHaveBeenCalled();
+  });
+
+  it('contains process enumeration failures during both exit paths', async () => {
+    const f = fixture();
+    mocks.execFileSync.mockImplementation(() => { throw new Error('ps unavailable'); });
+    await expect(stopComputerUseAgentForPermissionRestart(true, f.resources)).rejects.toThrow('ps unavailable');
+    expect(() => stopComputerUseAgentsOnExitSync(true, f.resources)).not.toThrow();
+    expect(kill).not.toHaveBeenCalled();
+  });
+
+  it.each(['win32', 'linux'] as const)('does not enumerate, connect or signal on %s', async platform => {
+    const f = fixture();
+    const socketPath = f.socket('a'.repeat(16));
+    const native = await agent(socketPath, (request, socket) => shutdownReply(f, request, socket));
+    processRows = [row(f, 900_001, socketPath)];
+    asPlatform(platform);
+    await stopComputerUseAgentForPermissionRestart(true, f.resources);
+    stopComputerUseAgentsOnExitSync(true, f.resources);
+    expect(mocks.execFileSync).not.toHaveBeenCalled();
+    expect(native.requests).toEqual([]);
+    expect(kill).not.toHaveBeenCalled();
+  });
+});
diff --git a/App/shell/desktop/tests/mac-permission-restart-lifecycle.test.ts b/App/shell/desktop/tests/mac-permission-restart-lifecycle.test.ts
index 8ccb5af11..f8285663f 100644
--- a/App/shell/desktop/tests/mac-permission-restart-lifecycle.test.ts
+++ b/App/shell/desktop/tests/mac-permission-restart-lifecycle.test.ts
@@ -33,6 +33,11 @@ const selected = source.statements.filter((statement) => {
 const code = ts.transpileModule(selected.map((statement) => statement.getText(source)).join("\n"), {
   compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.CommonJS },
 }).outputText;
+const cleanupFunction = source.statements.find((statement) => ts.isFunctionDeclaration(statement)
+  && statement.name?.text === "cleanupBeforeQuit")!;
+const actualCleanupCode = ts.transpileModule(cleanupFunction.getText(source), {
+  compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.CommonJS },
+}).outputText;
 
 const systemQuit: MacPermissionQuitContext = {
   eventClass: "aevt",
@@ -66,6 +71,7 @@ function setup(options: {
   nativeSessionError?: Error;
   relaunchMarker?: boolean;
   argv?: string[];
+  actualCleanup?: boolean;
 } = {}) {
   vi.useFakeTimers();
   vi.setSystemTime(0);
@@ -81,7 +87,11 @@ function setup(options: {
   let failCleanup!: (error: Error) => void;
   const cleanup = new Promise<void>((resolve, reject) => { completeCleanup = resolve; failCleanup = reject; });
   const cleanupBeforeQuit = vi.fn(() => cleanup);
+  const closeServices = vi.fn(() => cleanup);
   const terminateSync = vi.fn(() => events.push("terminate"));
+  const stopComputerUseAgentsOnExitSync = vi.fn();
+  const stopComputerUseAgentForPermissionRestart = vi.fn().mockResolvedValue(undefined);
+  const installPreparedRequiredUpdateOnQuit = vi.fn().mockResolvedValue(undefined);
   let quitContext = options.quitContext === undefined ? systemQuit : options.quitContext;
   let systemSessionEnding: boolean | undefined = options.nativeSessionUnavailable ? undefined : options.systemSessionEnding ?? false;
   let notificationSequence = systemSessionEnding === true ? 1 : 0;
@@ -113,6 +123,7 @@ function setup(options: {
     return event;
   };
   Object.assign(app, {
+    isPackaged: true,
     requestSingleInstanceLock: vi.fn(() => options.ownsLock !== false),
     quit: vi.fn(requestQuit),
     relaunch: vi.fn(() => events.push("relaunch")),
@@ -120,7 +131,7 @@ function setup(options: {
   });
   const context = createContext({
     app,
-    process: { platform: options.platform ?? "darwin",
+    process: { platform: options.platform ?? "darwin", env: {}, resourcesPath: "/Applications/Memmy.app/Contents/Resources",
       argv: options.argv ?? ["Memmy", ...(options.relaunchMarker ? ["--memmy-permission-relaunch"] : [])] },
     Date, setTimeout, clearTimeout, queueMicrotask,
     console: { warn: vi.fn() },
@@ -130,13 +141,27 @@ function setup(options: {
     writePackagedStartupLog: async (message: string) => { logs.push(message); },
     closeSplashWindow: vi.fn(), hideAppShellForQuit: vi.fn(),
     readStopMemoryServiceOnExitSetting: () => false,
-    cleanupBeforeQuit, runtimeServices: { terminateSync },
+    cleanupBeforeQuit, runtimeServices: { terminateSync, close: closeServices },
+    stopComputerUseAgentsOnExitSync, stopComputerUseAgentForPermissionRestart,
+    requiredUpdateBackgroundFirstCheckTimer: null, requiredUpdateBackgroundCheckTimer: null,
+    pendingMainWindowAction: null, memoryServiceControl: null, localBackend: null,
+    browserWebviewDownloads: null, disposeBrowserWebviewPermissions: null, browserSidebarBridge: null,
+    pipScreenPermissionGuide: null, computerUseSurfaceWindows: null, areIpcHandlersRegistered: true,
+    ipcMain: { removeHandler: vi.fn(), removeListener: vi.fn(), removeAllListeners: vi.fn() },
+    clearPetWindowCloseActivateSuppression: vi.fn(), closePetWindow: vi.fn(),
+    installPreparedRequiredUpdateOnQuit, destroyMenuBarTray: vi.fn(),
+    embeddedBrowserDriver: { dispose: vi.fn() }, stopPackagedRendererServer: vi.fn().mockResolvedValue(undefined),
+    sendAppExitEventBeforeQuit: vi.fn().mockResolvedValue(undefined),
+    EXTERNAL_BROWSER_EXTENSION_DRAG_CHANNEL: "test-browser-drag",
+    handleComputerHistoryTrayIndicator: vi.fn(), handleMovePetWindow: vi.fn(), handleStartPetWindowDrag: vi.fn(),
+    handleStopPetWindowDrag: vi.fn(), handleUpdatePetWindowLayout: vi.fn(), handleAnalyticsClientId: vi.fn(),
     formatStartupError: (error: Error) => error.message,
     isBootReady: true,
     consumePetWindowCloseActivateSuppression: () => false,
     activateMainWindow: vi.fn(),
   });
   runInContext(code, context);
+  if (options.actualCleanup) runInContext(actualCleanupCode, context);
   if (options.waitedForLock) runInContext("didWaitForSingleInstanceLock = true", context);
   const beginGuide = () => runInContext("macPermissionRestartIntent.begin()", context) as number;
   const finishGuide = (token: number, approved: boolean) => runInContext(`macPermissionRestartIntent.finish(${token}, ${approved})`, context);
@@ -144,7 +169,10 @@ function setup(options: {
   return {
     app, logs, events, readCurrentQuitContext, readSystemSessionEnding, readSystemSessionEndingState,
     loadMenuBarAppearanceNative, policy,
-    cleanupBeforeQuit, terminateSync, requestQuit, completeCleanup, failCleanup,
+    cleanupBeforeQuit, closeServices, terminateSync, requestQuit, completeCleanup, failCleanup,
+    stopComputerUseAgentsOnExitSync, stopComputerUseAgentForPermissionRestart,
+    installPreparedRequiredUpdateOnQuit,
+    hasRuntimeServices: () => runInContext("runtimeServices !== null", context) as boolean,
     beginGuide, finishGuide,
     setQuitContext: (next: MacPermissionQuitContext | null) => { quitContext = next; },
     setSystemSessionEnding: (next: boolean | undefined) => {
@@ -158,6 +186,82 @@ function setup(options: {
 
 afterEach(() => vi.useRealTimers());
 
+describe("native app-agent shutdown during desktop quit", () => {
+  it.each(["resolved", "rejected"] as const)("cleans native agents before permission relaunch when services close is %s", async (completion) => {
+    const test = setup({ actualCleanup: true });
+    test.stopComputerUseAgentForPermissionRestart.mockImplementation(async () => { test.events.push("native-async"); });
+    const closeServices = test.closeServices.getMockImplementation()!;
+    test.closeServices.mockImplementation(() => {
+      test.events.push("services-close");
+      return closeServices();
+    });
+    test.stopComputerUseAgentsOnExitSync.mockImplementation(() => { test.events.push("native-sync"); });
+    test.requestQuit();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(test.events).toEqual(["native-async", "services-close"]);
+    expect(test.hasRuntimeServices()).toBe(false);
+    if (completion === "resolved") test.completeCleanup();
+    else test.failCleanup(new Error("service close failed"));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(test.events).toEqual(["native-async", "services-close", "native-sync", "relaunch", "quit"]);
+    expect(test.stopComputerUseAgentsOnExitSync).toHaveBeenCalledExactlyOnceWith(true,
+      "/Applications/Memmy.app/Contents/Resources", undefined);
+  });
+
+  it("runs native exit cleanup after an earlier cleanup failure and before an ordinary quit", async () => {
+    const test = setup({ actualCleanup: true, quitContext: userQuit });
+    test.installPreparedRequiredUpdateOnQuit.mockRejectedValueOnce(new Error("update cleanup failed"));
+    test.stopComputerUseAgentsOnExitSync.mockImplementation(() => { test.events.push("native-sync"); });
+    test.requestQuit();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(test.events).toEqual(["native-sync", "quit"]);
+    expect(test.stopComputerUseAgentForPermissionRestart).not.toHaveBeenCalled();
+    expect(test.logs).toContain("quit:cleanup-failed\nupdate cleanup failed");
+  });
+
+  it("retains the services captured before cleanup clears them and stops native agents before forced relaunch/exit", async () => {
+    const test = setup({ actualCleanup: true });
+    test.stopComputerUseAgentsOnExitSync.mockImplementation(() => { test.events.push("native-sync"); });
+    test.requestQuit();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(test.hasRuntimeServices()).toBe(false);
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(test.terminateSync).toHaveBeenCalledExactlyOnceWith({ stopMemory: false });
+    expect(test.events).toEqual(["terminate", "native-sync", "relaunch", "exit"]);
+    test.completeCleanup();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(test.app.relaunch).toHaveBeenCalledOnce();
+  });
+
+  it("still stops native agents and exits if forced service termination throws", async () => {
+    const test = setup({ actualCleanup: true, quitContext: userQuit });
+    test.terminateSync.mockImplementation(() => { throw new Error("service termination failed"); });
+    test.stopComputerUseAgentsOnExitSync.mockImplementation(() => { test.events.push("native-sync"); });
+    test.requestQuit();
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(test.events).toEqual(["native-sync", "exit"]);
+    test.completeCleanup();
+    await vi.advanceTimersByTimeAsync(0);
+  });
+
+  it.each(["win32", "linux"] as const)("does not invoke macOS agent cleanup on %s for normal or forced quit", async (platform) => {
+    const normal = setup({ platform, actualCleanup: true });
+    normal.requestQuit();
+    normal.completeCleanup();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(normal.stopComputerUseAgentForPermissionRestart).not.toHaveBeenCalled();
+    expect(normal.stopComputerUseAgentsOnExitSync).not.toHaveBeenCalled();
+
+    const forced = setup({ platform, actualCleanup: true });
+    forced.requestQuit();
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(forced.stopComputerUseAgentForPermissionRestart).not.toHaveBeenCalled();
+    expect(forced.stopComputerUseAgentsOnExitSync).not.toHaveBeenCalled();
+    forced.completeCleanup();
+    await vi.advanceTimersByTimeAsync(0);
+  });
+});
+
 describe("macOS system permission restart lifecycle", () => {
   it("relaunches after cleanup for the system quit request even without an activate event", async () => {
     const test = setup();

From fe02b11ba33a3019910252a5ac1f42575b8614a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=95=E5=B8=83=E5=B8=83?=
 <lvbubu@MacBook-Pro-0018.local>
Date: Wed, 21 Oct 2026 12:37:25 +0800
Subject: [PATCH 82/85] fix(memory): recover History quotes from retained
 source text

---
 .github/workflows/memory-release.yml          |   2 +-
 .../tests/packaged-runtime-boundary.test.ts   |   2 +-
 Memory/package.json                           |   2 +-
 Memory/src/cli/npm/package.json               |   2 +-
 .../evidence/observation-memory-pipeline.ts   |  67 +++-----
 .../evidence/observation-quote-grounding.ts   | 157 ++++++++++++++++++
 Memory/src/version.ts                         |   2 +-
 Memory/tests/project-version.test.ts          |   2 +-
 .../observation-memory-validation.test.ts     |  48 +++++-
 .../evidence/observation-memory.test.ts       |   4 +-
 .../observation-quote-grounding.test.ts       | 120 +++++++++++++
 .../evidence/observation-recovery.test.ts     | 103 ++++++++++++
 Memory/viewer/package.json                    |   2 +-
 docs/qa/history-quote-grounding-20261021.md   |  42 +++++
 package-lock.json                             |   2 +-
 15 files changed, 501 insertions(+), 56 deletions(-)
 create mode 100644 Memory/src/service/evidence/observation-quote-grounding.ts
 create mode 100644 Memory/tests/service/evidence/observation-quote-grounding.test.ts
 create mode 100644 Memory/tests/service/evidence/observation-recovery.test.ts
 create mode 100644 docs/qa/history-quote-grounding-20261021.md

diff --git a/.github/workflows/memory-release.yml b/.github/workflows/memory-release.yml
index 91dde3a24..da445a357 100644
--- a/.github/workflows/memory-release.yml
+++ b/.github/workflows/memory-release.yml
@@ -6,7 +6,7 @@ on:
       version:
         description: Memory version (X.Y.Z)
         required: true
-        default: 2.1.6
+        default: 2.1.7
   push:
     tags:
       - "memory-v*"
diff --git a/App/shell/desktop/tests/packaged-runtime-boundary.test.ts b/App/shell/desktop/tests/packaged-runtime-boundary.test.ts
index 527e1a952..883b41108 100644
--- a/App/shell/desktop/tests/packaged-runtime-boundary.test.ts
+++ b/App/shell/desktop/tests/packaged-runtime-boundary.test.ts
@@ -126,7 +126,7 @@ describe("desktop packaged runtime boundaries", () => {
       yaml: expect.any(String),
       zod: expect.any(String)
     });
-    expect(memoryPackage.version).toBe("2.1.6");
+    expect(memoryPackage.version).toBe("2.1.7");
     expect(memoryPackage.dependencies ?? {}).not.toHaveProperty("@memmy/local-api-contracts");
     expect(memoryPackage.dependencies ?? {}).not.toHaveProperty("@memmy/migrations");
     expect(memoryPackage.scripts?.prebuild).toBeUndefined();
diff --git a/Memory/package.json b/Memory/package.json
index a3aaa023f..3d70f08dd 100644
--- a/Memory/package.json
+++ b/Memory/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@memmy/memory",
-  "version": "2.1.6",
+  "version": "2.1.7",
   "private": true,
   "type": "module",
   "main": "./dist/src/index.js",
diff --git a/Memory/src/cli/npm/package.json b/Memory/src/cli/npm/package.json
index dbbbc610d..29bf36d47 100644
--- a/Memory/src/cli/npm/package.json
+++ b/Memory/src/cli/npm/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@memtensor/memmy-memory-cli",
-  "version": "2.1.6",
+  "version": "2.1.7",
   "description": "Memmy Memory CLI for local agent memory.",
   "type": "module",
   "bin": {
diff --git a/Memory/src/service/evidence/observation-memory-pipeline.ts b/Memory/src/service/evidence/observation-memory-pipeline.ts
index 546bae6d9..fc7f6ff43 100644
--- a/Memory/src/service/evidence/observation-memory-pipeline.ts
+++ b/Memory/src/service/evidence/observation-memory-pipeline.ts
@@ -11,6 +11,7 @@ import { isObservationMemory, isObservationMemoryProcessed, observationJobPayloa
 import { lookupExternalEvidence } from "../external-evidence-source.js";
 import { namespaceForMemory } from "../namespace/namespace-scope.js";
 import type { RuntimeNamespace } from "../../types.js";
+import { resolveObservationQuote } from "./observation-quote-grounding.js";
 
 export class ObservationDependenciesPendingError extends Error {
   constructor() { super("observation sources are still being processed"); }
@@ -37,8 +38,8 @@ const VALIDATION_CORRECTIONS = {
 
 /** Fixed reasons let a model correct its output without replaying or logging private text. */
 class ObservationOutputValidationError extends Error {
-  constructor(readonly reason: keyof typeof VALIDATION_CORRECTIONS, message: string) {
-    super(`${message} (${reason})`);
+  constructor(readonly reason: keyof typeof VALIDATION_CORRECTIONS, message: string, readonly itemIndex?: number) {
+    super(`${message} (${reason})${itemIndex === undefined ? "" : ` [item ${itemIndex + 1}]`}`);
   }
 }
 
@@ -60,9 +61,9 @@ Do not infer stable user preferences, identity facts, ownership of another perso
 Absence of visible completion is unknown status, not proof of noncompletion. A pending parent task does not prove every subtask is pending. Qualify time-sensitive states as "at the time observed", "no completion was shown", or "status not confirmed" as appropriate; never turn missing evidence into a permanent state assertion.
 An opened or visible document/task establishes its existence, not its creation or ownership. Adding or editing subtasks does not imply creating their parent task. Preserve the actual observed action and do not upgrade "opened" or "edited" into "created".
 When parent sources are supplied, consolidate the useful work context across them: remove duplicates, preserve specific constraints and unresolved issues, and only describe a changed decision or resolved blocker if a source explicitly supports it. Do not merely shorten the aggregate narrative.
-Sources marked truncated contain only retained excerpts; missing portions are unknown. Quote one continuous retained excerpt, never join across an omission. Title and summary provide topic context; ground each item in the displayed source content.
+Sources marked truncated contain only retained excerpts; missing portions are unknown. Quote one continuous retained excerpt, never join across an omission. The source title provides topic context only; ground each item in the displayed source content.
 For useful content return JSON {"keep":true,"title":"specific work topic, not a generic activity label","summary":"one or two sentences capturing what matters for later work","items":[{"category":"context|decision|constraint|todo|blocker|progress","text":"one grounded, self-contained fact with its scope and uncertainty","source_memory_id":"an input source ID","evidence_quote":"an exact short quotation from that source content"}]}.
-Return 1-12 nonredundant items. Every item must be supported by its exact quotation; do not add steps, dates or success claims absent from the sources. The summary and title must describe only those grounded items. Never output secrets, credentials or verification codes. Use the language, script, and regional conventions of the requested BCP 47 locale for title, summary, item text, and reason, preserving useful names. Keep JSON keys, category codes, source IDs, and exact evidence quotes unchanged.`;
+Return 1-12 nonredundant items. Copy evidence_quote directly from source.content, including its Markdown emphasis, list labels and punctuation. Prefer a short continuous original line or block; do not shorten it with ellipses or quote the source title instead. Every item must be supported by its quotation; do not add steps, dates or success claims absent from the sources. The summary and title must describe only those grounded items. Never output secrets, credentials or verification codes. Use the language, script, and regional conventions of the requested BCP 47 locale for title, summary, item text, and reason, preserving useful names. Keep JSON keys, category codes, source IDs, and exact evidence quotes unchanged.`;
 
 /** Uses the ordinary durable summary/embedding stages without fabricating a conversational turn. */
 export class ObservationMemoryPipeline {
@@ -148,7 +149,8 @@ export class ObservationMemoryPipeline {
       if (!current || !this.matches(job, current)) return;
       // One bounded correction uses exactly the same evidence snapshot. Never
       // weaken grounding or retain some items from an invalid model response.
-      const correction = `The previous response failed validation: ${error.reason}. ${VALIDATION_CORRECTIONS[error.reason]} Regenerate the complete response using the original schema and exact source quotes; title and summary must cover only the grounded items.`;
+      const itemHint = error.itemIndex === undefined ? "" : ` Item ${error.itemIndex + 1} failed.`;
+      const correction = `The previous response failed validation: ${error.reason}.${itemHint} ${VALIDATION_CORRECTIONS[error.reason]} Regenerate the complete response using the original schema and exact source quotes; title and summary must cover only the grounded items.`;
       const messages = input.messages.map((message) => message.role === "system"
         ? { ...message, content: `${message.content}\n\n${correction}` } : message);
       output = validateOutput(await complete(messages), input.sources);
@@ -217,31 +219,6 @@ function externalEvidence(memory: MemoryRow): Record<string, unknown> {
 }
 
 function string(value: unknown): string { return typeof value === "string" ? value.trim() : ""; }
-function normalizeQuote(value: string): string { return value.normalize("NFKC").replace(/\s+/gu, " ").trim(); }
-
-// Models shorten a sentence with "..." (NFKC also turns "…" into "..."). Accept that only when
-// every piece is exact and in order on one source line, so a cut cannot splice separate claims.
-const MAX_ELIDED_QUOTE_GAP = 40;
-function quoteIsGrounded(fragment: string, quote: string): boolean {
-  const text = normalizeQuote(fragment), normalized = normalizeQuote(quote);
-  if (text.includes(normalized)) return true;
-  const pieces = normalized.split(/\s*\.{3,}\s*/u).filter(Boolean);
-  if (pieces.length === 0 || pieces.some((piece) => piece.length < 4)) return false;
-  if (pieces.length === 1) return text.includes(pieces[0]!);
-  return fragment.normalize("NFKC").split("\n").some((rawLine) => {
-    const line = normalizeQuote(rawLine);
-    for (let start = line.indexOf(pieces[0]!); start >= 0; start = line.indexOf(pieces[0]!, start + 1)) {
-      let end = start + pieces[0]!.length;
-      if (pieces.slice(1).every((piece) => {
-        const at = line.indexOf(piece, end);
-        if (at < 0 || at - end > MAX_ELIDED_QUOTE_GAP) return false;
-        end = at + piece.length;
-        return true;
-      })) return true;
-    }
-    return false;
-  });
-}
 
 /** Preserve every source identity and valid JSON while sharing evidence space. */
 export function prepareObservationExtractionInput(input: {
@@ -253,24 +230,23 @@ export function prepareObservationExtractionInput(input: {
   const systemTokens = count(PROMPT);
   const sourceCount = Math.max(1, input.sources.length);
   let titleBudget = Math.min(48, Math.max(8, Math.floor(320 / sourceCount)));
-  let summaryBudget = Math.min(160, Math.max(16, Math.floor(1_000 / sourceCount)));
   const bodyTokens = input.sources.map((source) => encode(source.content));
   const serialize = (sources: Source[]): string => JSON.stringify({ language: input.language,
     observedAt: input.observedAt, aggregate: input.aggregate,
-    sources: sources.map(({ id, title, summary, content, truncated }) => ({ id, title, summary, content, truncated })) });
+    sources: sources.map(({ id, title, content, truncated }) => ({ id, title, content, truncated })) });
   const metadataSources = (): Source[] => input.sources.map((source) => {
     const title = tokenPrefix(encode(source.title), titleBudget);
-    const summary = tokenPrefix(encode(source.summary), summaryBudget);
-    return { ...source, title, summary, content: "", evidenceFragments: [],
-      truncated: Boolean(source.content) || title !== source.title || summary !== source.summary };
+    // Metadata summaries are generated prose, not quoteable source content.
+    // Keep provenance internally, but expose only the body as evidence.
+    return { ...source, title, content: "", evidenceFragments: [],
+      truncated: Boolean(source.content) || title !== source.title };
   });
   let metadata = metadataSources();
   // Even unusually long IDs retain their identity. Metadata gets shorter
   // before evidence is sacrificed; no whole parent disappears from a rollup.
   while (systemTokens + count(serialize(metadata)) + sourceCount * 12 > MODEL_INPUT_TOKEN_LIMIT
-    && (titleBudget > 0 || summaryBudget > 0)) {
+    && titleBudget > 0) {
     titleBudget = Math.floor(titleBudget * 0.75);
-    summaryBudget = Math.floor(summaryBudget * 0.75);
     metadata = metadataSources();
   }
   const fixedTokens = systemTokens + count(serialize(metadata));
@@ -285,7 +261,7 @@ export function prepareObservationExtractionInput(input: {
         ? [original.content]
         : retainedTokenFragments(tokens, shares[index]!);
       return { ...source, content: fragments.join("\n\n"), evidenceFragments: fragments,
-        truncated: fragments.length !== 1 || fragments[0] !== original.content || source.title !== original.title || source.summary !== original.summary };
+        truncated: fragments.length !== 1 || fragments[0] !== original.content || source.title !== original.title };
     });
     const content = serialize(prepared);
     const totalTokens = systemTokens + count(content);
@@ -340,20 +316,21 @@ function validateOutput(result: Record<string, unknown>, sources: Source[]):
   if (!title || title.length > 160 || !summary || summary.length > 1_200 || !result.items.length || result.items.length > 12) {
     throw new ObservationOutputValidationError("semantic_fields", "observation extraction returned invalid semantic memory fields");
   }
-  const items: Item[] = result.items.map((item) => {
-    if (!isRecord(item)) throw new ObservationOutputValidationError("item_shape", "observation extraction item is not grounded");
+  const items: Item[] = result.items.map((item, itemIndex) => {
+    if (!isRecord(item)) throw new ObservationOutputValidationError("item_shape", "observation extraction item is not grounded", itemIndex);
     const category = item.category as Category, text = string(item.text), quote = string(item.evidence_quote), id = string(item.source_memory_id);
     const source = sources.find((candidate) => candidate.id === id);
     if (!CATEGORIES.includes(category) || !text || text.length > 900 || quote.length < 4 || quote.length > 800) {
-      throw new ObservationOutputValidationError("item_fields", "observation extraction item is not grounded in its source");
+      throw new ObservationOutputValidationError("item_fields", "observation extraction item is not grounded in its source", itemIndex);
     }
     if (!source) {
-      throw new ObservationOutputValidationError("source_id", "observation extraction item is not grounded in its source");
+      throw new ObservationOutputValidationError("source_id", "observation extraction item is not grounded in its source", itemIndex);
     }
-    if (!(source.evidenceFragments ?? [source.content]).some((fragment) => quoteIsGrounded(fragment, quote))) {
-      throw new ObservationOutputValidationError("quote_grounding", "observation extraction item is not grounded in its source");
+    const originalQuote = resolveObservationQuote(source.evidenceFragments ?? [source.content], quote);
+    if (!originalQuote) {
+      throw new ObservationOutputValidationError("quote_grounding", "observation extraction item is not grounded in its source", itemIndex);
     }
-    return { category, text, evidence_quote: quote, source_memory_id: id };
+    return { category, text, evidence_quote: originalQuote, source_memory_id: id };
   });
   return { keep: true, title, summary, items };
 }
diff --git a/Memory/src/service/evidence/observation-quote-grounding.ts b/Memory/src/service/evidence/observation-quote-grounding.ts
new file mode 100644
index 000000000..f7ae3d096
--- /dev/null
+++ b/Memory/src/service/evidence/observation-quote-grounding.ts
@@ -0,0 +1,157 @@
+/** Resolve a display quotation to one continuous span of the retained source.
+ * Formatting tolerance never changes the evidence saved in the memory. */
+export function resolveObservationQuote(fragments: readonly string[], quote: string): string | undefined {
+  const rawQuote = normalizedView(quote, false).text, displayQuote = normalizedView(quote, true).text;
+  if (!rawQuote) return undefined;
+  for (const [fragmentIndex, fragment] of fragments.entries()) {
+    // Keep the original exact/whitespace-normalized behavior first, including
+    // valid quotations that start or end inside an emphasis span.
+    // A retained tail may start inside code after its opening fence was cut.
+    // Only the original head has enough context for formatting tolerance.
+    for (const stripEmphasis of fragmentIndex === 0 ? [false, true] : [false]) {
+      const wanted = stripEmphasis ? displayQuote : rawQuote;
+      if (!wanted) continue;
+      const source = normalizedView(fragment, stripEmphasis);
+      for (let exact = source.text.indexOf(wanted); exact >= 0; exact = source.text.indexOf(wanted, exact + 1)) {
+        const span = originalSpan(fragment, source, exact, exact + wanted.length);
+        if (span && span.text.length <= MAX_QUOTE_LENGTH) return span.text;
+      }
+      const pieces = wanted.split(/\s*\.{3,}\s*/u).filter(Boolean);
+      if (!pieces.length || pieces.some((piece) => piece.length < 4)) continue;
+      for (let start = source.text.indexOf(pieces[0]!); start >= 0; start = source.text.indexOf(pieces[0]!, start + 1)) {
+        let end = start + pieces[0]!.length;
+        const gaps: Array<{ start: number; end: number }> = [];
+        let found = true;
+        for (const piece of pieces.slice(1)) {
+          const at = source.text.indexOf(piece, end);
+          if (at < 0 || at - end > MAX_SINGLE_LINE_GAP) { found = false; break; }
+          gaps.push({ start: end, end: at });
+          end = at + piece.length;
+        }
+        if (!found) continue;
+        const span = originalSpan(fragment, source, start, end);
+        if (!span || span.text.length > MAX_QUOTE_LENGTH) continue;
+        if (!/[\r\n]/u.test(span.text)
+          && gaps.every((gap) => gap.end - gap.start <= MAX_SINGLE_LINE_GAP)) return span.text;
+      }
+    }
+  }
+  return undefined;
+}
+
+const MAX_QUOTE_LENGTH = 800;
+const MAX_SINGLE_LINE_GAP = 40;
+const graphemes = new Intl.Segmenter("und", { granularity: "grapheme" });
+type Emphasis = { start: number; contentStart: number; contentEnd: number; end: number };
+type NormalizedView = { text: string; starts: number[]; ends: number[]; emphasis: Emphasis[] };
+type Line = { start: number; end: number; text: string; code: boolean };
+
+function lines(value: string): Line[] {
+  const result: Line[] = [];
+  let offset = 0, fence: { character: string; length: number } | undefined;
+  for (const raw of value.split("\n")) {
+    const text = raw.replace(/\r$/u, "");
+    const marker = /^[ \t]*(`{3,}|~{3,})/u.exec(text)?.[1];
+    const indentedCode = /^(?: {4}|\t)/u.test(text) && !/^[ \t]*(?:[-+*]|\d+[.)])[ \t]+/u.test(text);
+    const code = Boolean(fence || marker || indentedCode);
+    if (fence) {
+      if (marker?.[0] === fence.character && marker.length >= fence.length
+        && new RegExp(`^[ \\t]*${fence.character}{${fence.length},}\\s*$`, "u").test(text)) fence = undefined;
+    } else if (marker) fence = { character: marker[0]!, length: marker.length };
+    result.push({ start: offset, end: offset + raw.length, text, code });
+    offset += raw.length + 1;
+  }
+  return result;
+}
+
+function escaped(value: string, at: number): boolean {
+  let count = 0;
+  while (at > 0 && value[--at] === "\\") count += 1;
+  return count % 2 === 1;
+}
+
+/** Only explicit Markdown labels and complete table cells permit optional
+ * bold markers. Ordinary prose and exponent operators remain exact text. */
+function emphasisSpans(value: string): Emphasis[] {
+  const result: Emphasis[] = [];
+  for (const line of lines(value)) {
+    if (line.code) continue;
+    const protectedCode = new Uint8Array(line.text.length);
+    for (let at = 0; at < line.text.length; at += 1) {
+      if (line.text[at] !== "`" || escaped(line.text, at)) continue;
+      let after = at + 1;
+      while (line.text[after] === "`") after += 1;
+      const marker = line.text.slice(at, after);
+      let close = line.text.indexOf(marker, after);
+      while (close >= 0 && (line.text[close - 1] === "`" || line.text[close + marker.length] === "`")) {
+        close = line.text.indexOf(marker, close + marker.length);
+      }
+      const end = close < 0 ? line.text.length : close + marker.length;
+      protectedCode.fill(1, at, end);
+      at = end - 1;
+    }
+    for (let at = 0; at < line.text.length - 1; at += 1) {
+      if (line.text.slice(at, at + 2) !== "**" || protectedCode[at] || escaped(line.text, at)
+        || line.text[at - 1] === "*" || line.text[at + 2] === "*"
+        || !line.text[at + 2] || /\s/u.test(line.text[at + 2]!)
+        || (at > 0 && /[\p{L}\p{N}_]/u.test(line.text[at - 1]!))) continue;
+      let close = line.text.indexOf("**", at + 2);
+      while (close >= 0 && (protectedCode[close] || escaped(line.text, close)
+        || line.text[close - 1] === "*" || line.text[close + 2] === "*"
+        || /\s/u.test(line.text[close - 1]!)
+        || (line.text[close + 2] && /[\p{L}\p{N}_]/u.test(line.text[close + 2]!)))) {
+        close = line.text.indexOf("**", close + 2);
+      }
+      if (close < 0) continue;
+      const label = /[:：]/u.test(line.text[close + 2] ?? "");
+      const leftCell = line.text.lastIndexOf("|", at), rightCell = line.text.indexOf("|", close + 2);
+      const tableCell = line.text.trim().startsWith("|") && line.text.trim().endsWith("|")
+        && leftCell >= 0 && rightCell >= 0 && !escaped(line.text, leftCell) && !escaped(line.text, rightCell)
+        && !line.text.slice(leftCell + 1, at).trim() && !line.text.slice(close + 2, rightCell).trim();
+      if (!label && !tableCell) continue;
+      result.push({ start: line.start + at, contentStart: line.start + at + 2,
+        contentEnd: line.start + close, end: line.start + close + 2 });
+      at = close + 1;
+    }
+  }
+  return result;
+}
+
+function normalizedView(value: string, stripEmphasis: boolean): NormalizedView {
+  const emphasis = emphasisSpans(value), removed = new Uint8Array(value.length);
+  for (const pair of stripEmphasis ? emphasis : []) {
+    removed.fill(1, pair.start, pair.contentStart);
+    removed.fill(1, pair.contentEnd, pair.end);
+  }
+  let text = "", pendingSpace: { start: number; end: number } | undefined;
+  const starts: number[] = [], ends: number[] = [];
+  for (const part of graphemes.segment(value)) {
+    if (removed[part.index]) continue;
+    const end = part.index + part.segment.length;
+    for (const character of part.segment.normalize("NFKC")) {
+      if (/\s/u.test(character)) {
+        if (text) pendingSpace = { start: pendingSpace?.start ?? part.index, end };
+        continue;
+      }
+      if (pendingSpace) {
+        text += " "; starts.push(pendingSpace.start); ends.push(pendingSpace.end); pendingSpace = undefined;
+      }
+      text += character;
+      // Search indices are UTF-16 offsets, including supplementary characters.
+      for (let unit = 0; unit < character.length; unit += 1) { starts.push(part.index); ends.push(end); }
+    }
+  }
+  return { text, starts, ends, emphasis };
+}
+
+function originalSpan(value: string, view: NormalizedView, from: number, to: number):
+  { start: number; end: number; text: string } | undefined {
+  let start = view.starts[from], end = view.ends[to - 1];
+  if (start === undefined || end === undefined) return undefined;
+  for (const pair of view.emphasis) {
+    if (start <= pair.contentStart && end >= pair.contentEnd) {
+      start = Math.min(start, pair.start); end = Math.max(end, pair.end);
+    }
+  }
+  return { start, end, text: value.slice(start, end) };
+}
diff --git a/Memory/src/version.ts b/Memory/src/version.ts
index b61cd2de8..54dd27f52 100644
--- a/Memory/src/version.ts
+++ b/Memory/src/version.ts
@@ -1,5 +1,5 @@
 /** Independent Memory/Local Plugin release identity. */
-export const MEMORY_SERVICE_VERSION = "2.1.6";
+export const MEMORY_SERVICE_VERSION = "2.1.7";
 export const MEMORY_VIEWER_VERSION = MEMORY_SERVICE_VERSION;
 export const MEMORY_PROTOCOL_VERSION = 1;
 
diff --git a/Memory/tests/project-version.test.ts b/Memory/tests/project-version.test.ts
index 9beda24cb..49114d5f2 100644
--- a/Memory/tests/project-version.test.ts
+++ b/Memory/tests/project-version.test.ts
@@ -14,7 +14,7 @@ describe("Memory service version", () => {
       readFileSync(resolve(fileURLToPath(import.meta.url), "../../viewer/package.json"), "utf8")
     );
 
-    expect(PROJECT_VERSION).toBe("2.1.6");
+    expect(PROJECT_VERSION).toBe("2.1.7");
     expect(PROJECT_VERSION).toBe(manifest.version);
     expect(cliManifest.version).toBe(manifest.version);
     expect(viewerManifest.version).toBe(manifest.version);
diff --git a/Memory/tests/service/evidence/observation-memory-validation.test.ts b/Memory/tests/service/evidence/observation-memory-validation.test.ts
index 31ba2b3b5..45a7982bd 100644
--- a/Memory/tests/service/evidence/observation-memory-validation.test.ts
+++ b/Memory/tests/service/evidence/observation-memory-validation.test.ts
@@ -42,6 +42,52 @@ function model(generate: (input: Input, call: number, messages: LlmMessage[]) =>
 }
 
 describe("observation validation correction", () => {
+  it("saves the original Markdown span when the model drops bold presentation markers", async () => {
+    const content = "- **业务时点**: 2026-10-22 开工前\n- **计划周**: 2026-10-19 — 2026-10-23";
+    const quote = "业务时点: 2026-10-22 开工前\n- **计划周**: 2026-10-19 — 2026-10-23";
+    const { llm, calls } = model((input) => ({ ...grounded(input), items: [{ ...grounded(input).items[0]!, evidence_quote: quote }] }));
+    const { service, db } = createTestService({ llm });
+    const row = service.syncExternalEvidence({ ...evidence, content });
+    await runWorkerRounds(service, 2);
+    const state = observationMemoryState(new Repositories(db.db).memories.get(row.id)!);
+    expect(calls).toHaveLength(1);
+    expect(state?.status).toBe("processed");
+    const savedQuote = (state?.items as Array<{ evidence_quote: string }>)[0]!.evidence_quote;
+    expect(savedQuote).toContain("**业务时点**:");
+    expect(content).toContain(savedQuote);
+    expect(savedQuote).not.toBe(quote);
+    expect(service.memoryProcessingStatus([row.id]).items[0]?.state).toBe("ready");
+  });
+
+  it("does not expose generated metadata summaries as quoteable source content", async () => {
+    const { llm, calls } = model(grounded);
+    const { service, db } = createTestService({ llm });
+    const sourceSummary = "METADATA_ONLY_SUMMARY_SENTINEL";
+    const row = service.syncExternalEvidence({ ...evidence, summary: sourceSummary });
+    await runWorkerRounds(service, 2);
+    const input = JSON.parse(calls[0]![1]!.content) as Input;
+    expect(input.sources[0]).not.toHaveProperty("summary");
+    expect(calls[0]![1]!.content).not.toContain(sourceSummary);
+    expect(new Repositories(db.db).memories.get(row.id)!.properties.internal_info.external_evidence)
+      .toMatchObject({ source_summary: sourceSummary });
+  });
+
+  it("identifies the failing item without echoing its private quote or the prior output", async () => {
+    const { llm, calls } = model((input, call) => call === 1
+      ? { ...grounded(input), items: [grounded(input).items[0], ungrounded(input).items[0]] }
+      : grounded(input));
+    const { service } = createTestService({ llm });
+    const row = service.syncExternalEvidence(evidence);
+    await runWorkerRounds(service, 2);
+    expect(calls).toHaveLength(2);
+    const feedback = calls[1]![0]!.content.slice(calls[0]![0]!.content.length);
+    expect(feedback).toContain("Item 2 failed.");
+    expect(feedback).not.toContain("PRIVATE_SOURCE_SENTINEL");
+    expect(feedback).not.toContain("already been approved");
+    expect(feedback).not.toContain(row.id);
+    expect(service.memoryProcessingStatus([row.id]).items[0]?.state).toBe("ready");
+  });
+
   it("does not regenerate a valid first response", async () => {
     const { llm, calls } = model(grounded);
     const { service } = createTestService({ llm });
@@ -85,7 +131,7 @@ describe("observation validation correction", () => {
     expect(calls).toHaveLength(2);
     expect(service.memoryProcessingStatus([row.id]).items[0]).toMatchObject({
       state: "summary_pending", errorCode: "processing_failed", attemptCount: 1,
-      errorMessage: "observation extraction item is not grounded in its source (quote_grounding)"
+      errorMessage: "observation extraction item is not grounded in its source (quote_grounding) [item 1]"
     });
     await runWorkerRounds(service, 2);
     expect(calls).toHaveLength(6);
diff --git a/Memory/tests/service/evidence/observation-memory.test.ts b/Memory/tests/service/evidence/observation-memory.test.ts
index b3bacaaa2..e4022e0d7 100644
--- a/Memory/tests/service/evidence/observation-memory.test.ts
+++ b/Memory/tests/service/evidence/observation-memory.test.ts
@@ -85,12 +85,12 @@ describe("History meaningful-memory processing", () => {
     try {
       expect(prepared.messages.reduce((total, message) => total + encoder.encode(message.content, [], []).length, 0)).toBeLessThanOrEqual(5_000);
     } finally { encoder.free(); }
-    const payload = JSON.parse(prepared.messages[1]!.content) as { sources: Array<{ id: string; title: string; summary: string; content: string; truncated: boolean }> };
+    const payload = JSON.parse(prepared.messages[1]!.content) as { sources: Array<{ id: string; title: string; content: string; truncated: boolean }> };
     expect(payload.sources.map((source) => source.id)).toEqual(sources.map((source) => source.id));
     expect(payload.sources).toHaveLength(sourceCount);
     for (const source of payload.sources) {
       expect(source.title).not.toBe("");
-      expect(source.summary).not.toBe("");
+      expect(source).not.toHaveProperty("summary");
       expect(source.content).not.toBe("");
       expect(source.content).not.toContain("\uFFFD");
       expect(source.truncated).toBe(true);
diff --git a/Memory/tests/service/evidence/observation-quote-grounding.test.ts b/Memory/tests/service/evidence/observation-quote-grounding.test.ts
new file mode 100644
index 000000000..eb5de83d5
--- /dev/null
+++ b/Memory/tests/service/evidence/observation-quote-grounding.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { resolveObservationQuote } from "../../../src/service/evidence/observation-quote-grounding.js";
+
+describe("observation quote resolution", () => {
+  it("restores balanced Markdown bold markers from the original source", () => {
+    const source = '- **业务时点**: “2026-10-22 开工前”，计划周 “2026-10-19 — 2026-10-23”。';
+    const quote = '业务时点: “2026-10-22 开工前”，计划周 “2026-10-19 — 2026-10-23”。';
+    expect(resolveObservationQuote([source], quote)).toBe(source.slice(2));
+  });
+
+  it("restores only the selected original span, preserving internal Markdown and newlines", () => {
+    const source = "环境信息\n- **角色**: 计划专员\n- **业务时点**: 2026-10-22 开工前\n- **其他**: 只读";
+    const result = resolveObservationQuote([source], "角色: 计划专员\n- 业务时点: 2026-10-22 开工前");
+    expect(result).toBe("**角色**: 计划专员\n- **业务时点**: 2026-10-22 开工前");
+    expect(source).toContain(result);
+  });
+
+  it("preserves exact quotations beginning inside paired formatting", () => {
+    const source = "- **角色**: 计划专员";
+    expect(resolveObservationQuote([source], "角色**:   计划专员")).toBe("**角色**: 计划专员");
+  });
+
+  it.each(["...", "…", "……"])("restores a same-line %s omission to its full source span", (ellipsis) => {
+    const source = "签名请求需要访问密钥，系统要求输入密码，用户两次点击拒绝。\n流程未获授权。";
+    expect(resolveObservationQuote([source], `签名请求需要访问密钥${ellipsis}用户两次点击拒绝`))
+      .toBe("签名请求需要访问密钥，系统要求输入密码，用户两次点击拒绝");
+  });
+
+  it("keeps literal source ellipses intact", () => {
+    expect(resolveObservationQuote(["等待中...仍未确认。"], "等待中...仍未确认。")).toBe("等待中...仍未确认。");
+  });
+
+  it("preserves normalization compatibility and original UTF-16 offsets", () => {
+    const source = "前缀👩🏽‍💻 **Cafe\u0301**：  \r\n  final ２００ 件。 后缀";
+    expect(resolveObservationQuote([source], "Café: final 200 件。"))
+      .toBe("**Cafe\u0301**：  \r\n  final ２００ 件。");
+  });
+
+  it("requires correction for cross-line omissions even within one product list", () => {
+    const source = ["- **Q305**:", "    - 可用产线: L1、L2", "    - 工时: 单件 0.02小时 / 件, 换线 0.5小时",
+      "    - 批次约束: 单日整批，不拆分", "- **Q306**:", "    - 状态: 锁定批次，不调整"].join("\n");
+    const resolved = resolveObservationQuote([source], "Q305... 可用产线: L1、L2... 批次约束: 单日整批，不拆分");
+    expect(resolved).toBeUndefined();
+    expect(resolveObservationQuote([source], "Q306... 状态: 锁定批次，不调整"))
+      .toBeUndefined();
+    const continuous = "Q306**:\n    - 状态: 锁定批次，不调整";
+    expect(source).toContain(resolveObservationQuote([source], continuous));
+  });
+
+  it("restores optional bold only for a complete Markdown table cell", () => {
+    const source = "| **Q305** | L1 | 单日整批 |";
+    expect(resolveObservationQuote([source], "| Q305 | L1 | 单日整批 |")).toBe(source);
+    expect(resolveObservationQuote(["prefix | **Q305** | suffix"], "prefix | Q305 | suffix")).toBeUndefined();
+  });
+
+  it("does not infer missing code-fence context in a retained tail", () => {
+    const head = "开始片段包含正文和截断前的代码围栏。\n```text\n";
+    const tail = "**审批状态**: 尚未确认\n```";
+    expect(resolveObservationQuote([head, tail], "审批状态: 尚未确认")).toBeUndefined();
+    expect(resolveObservationQuote([head, tail], "**审批状态**: 尚未确认")).toBe("**审批状态**: 尚未确认");
+    expect(resolveObservationQuote(["头部内容", "| **Q305** | L1 |"], "| Q305 | L1 |")).toBeUndefined();
+  });
+
+  it("requires correction for omitted sibling properties without their owner", () => {
+    const source = ["- **可见内容**:", "  - **物料状态详情**:", "    - 已检可用量（扣除预留）：200件。",
+      "    - 入库日期：2026-10-22。", "    - 检验状态：已检合格，状态正常。", "    - 来源批次：BATCH-01。",
+      "  - **其他事项**:", "    - 状态：尚未确认。"].join("\n");
+    expect(resolveObservationQuote([source], "已检可用量（扣除预留）：200件。... 来源批次：BATCH-01。"))
+      .toBeUndefined();
+  });
+
+  it.each([
+    ["plain lines", "已确认 A 方案可行。\nB 方案被否决。", "已确认 A 方案...B 方案被否决"],
+    ["peer product subtrees", "- 产品:\n  - **P204**:\n    - 可用产线: L1\n  - **P205**:\n    - 可用产线: L2", "P204...可用产线: L2"],
+    ["flat product list", "- 产品:\n  - P204: 已检可用量200件\n  - P205: 已检可用量0件", "P204: 已检可用量200件...P205: 已检可用量0件"],
+    ["natural-language product names", "- 产品:\n  - 普通泵: 已检可用量200件\n  - 增压泵: 已检可用量0件", "普通泵: 已检可用量200件...增压泵: 已检可用量0件"],
+    ["blank boundary", "- 物料:\n  - 可用数量: 200件\n\n  - 来源批次: BATCH-01", "可用数量: 200件...来源批次: BATCH-01"],
+    ["heading boundary", "- 物料:\n  - 可用数量: 200件\n## 另一产品\n  - 来源批次: BATCH-01", "可用数量: 200件...来源批次: BATCH-01"],
+    ["table rows", "| P204 | 200件 |\n| P205 | 0件 |", "P204...P205"],
+    ["fenced code", "```text\n- 物料:\n  - 可用数量: 200件\n  - 来源批次: BATCH-01\n```", "可用数量: 200件...来源批次: BATCH-01"]
+  ])("rejects an omission across %s", (_name, source, quote) => {
+    expect(resolveObservationQuote([source!], quote!)).toBeUndefined();
+  });
+
+  it("never joins separate retained fragments", () => {
+    expect(resolveObservationQuote(["已确认采购审批状态。", "采购尚未完成，需继续跟进。"], "已确认采购审批状态...采购尚未完成"))
+      .toBeUndefined();
+  });
+
+  it.each([
+    ["`**approval**` is required", "approval is required"],
+    ["```text\n**approval** is required\n```", "approval is required"],
+    ["    ```text\n    **approval** is required\n    ```", "approval is required"],
+    ["    **approval** is required", "approval is required"],
+    ["amount ** 2 ** rate", "amount 2 rate"],
+    ["amount **2** rate", "amount 2 rate"],
+    ["amount**2**rate", "amount2rate"],
+    ["result = 2 **n** 3", "result = 2 n 3"],
+    ["yield = base **power** cap", "yield = base power cap"],
+    ["Ordinary **approval** is required", "Ordinary approval is required"],
+    ["\\**approval** is required", "approval is required"],
+    ["order_id: ABC_204", "orderid: ABC204"],
+    ["**未批准**: 200件", "已批准: 200件"],
+    ["**可用数量**: 200件", "可用数量: 300件"],
+    ["**入库日期**: 2026-10-22", "入库日期: 2026-10-23"]
+  ])("does not change code, operators, identifiers, or meaning: %s", (source, quote) => {
+    expect(resolveObservationQuote([source!], quote!)).toBeUndefined();
+  });
+
+  it("retains the existing single-line omitted-gap limit", () => {
+    const source = `开头证据${"中".repeat(41)}结尾证据`;
+    expect(resolveObservationQuote([source], "开头证据...结尾证据")).toBeUndefined();
+  });
+
+  it("limits the complete restored quotation, including omitted text", () => {
+    const source = `- 业务:\n  - 开头证据: ${"中".repeat(780)}\n  - 结尾证据: 仍待确认`;
+    expect(resolveObservationQuote([source], "开头证据...结尾证据: 仍待确认")).toBeUndefined();
+    expect(resolveObservationQuote(["证据".repeat(401)], "证据".repeat(401))).toBeUndefined();
+  });
+});
diff --git a/Memory/tests/service/evidence/observation-recovery.test.ts b/Memory/tests/service/evidence/observation-recovery.test.ts
new file mode 100644
index 000000000..7d30a801b
--- /dev/null
+++ b/Memory/tests/service/evidence/observation-recovery.test.ts
@@ -0,0 +1,103 @@
+import type { Server } from "node:http";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { DEFAULT_MEMMY_CONFIG, MemoryDb, createMemoryHttpServer, type LlmClient } from "../../../src/index.js";
+import type { LlmMessage } from "../../../src/model/types.js";
+import { closeMemoryHttpServer } from "../../../src/server/http.js";
+import { observationMemoryState } from "../../../src/service/observation-memory-state.js";
+import { Repositories } from "../../../src/storage/repositories.js";
+import { createMemoryServiceFixture, runWorkerRounds } from "../../fixtures/memory-service-fixture.js";
+
+const { cleanup, createTestMemoryService } = createMemoryServiceFixture();
+const servers: Server[] = [];
+afterEach(async () => {
+  for (const server of servers.splice(0)) await closeMemoryHttpServer(server);
+  cleanup();
+});
+
+const namespace = { source: "memmy", profileId: "default", userId: "history-recovery-user" };
+const revision = "2026-10-19T12:00:00.000Z";
+
+describe("History recovery across runtime lifecycle", () => {
+  it.each(["startup", "config reload"] as const)("recovers five exhausted observation failures on %s without manual retry", async (lifecycle) => {
+    let validOutput = false;
+    const llm: LlmClient = {
+      config: DEFAULT_MEMMY_CONFIG.summary,
+      isConfigured: () => true,
+      complete: async () => "",
+      status: () => ({ provider: "test", configured: true, remote: false }),
+      async completeJson<T extends Record<string, unknown>>(messages: LlmMessage[]) {
+        const input = JSON.parse(messages[1]!.content) as { sources: Array<{ id: string; content: string }> };
+        const source = input.sources.find((item) => item.content.includes("The A17 order review"))!;
+        const fact = validOutput
+          ? source.content.match(/The A17 order review for source \d must retain locked production orders\./u)![0]
+          : "All locked production orders were rescheduled.";
+        return { keep: true, title: "A17 production constraint", summary: fact,
+          items: [{ category: "constraint", text: fact, source_memory_id: source.id, evidence_quote: fact }] } as unknown as T;
+      }
+    };
+    const skillLlm: LlmClient = { ...llm, async completeJson<T extends Record<string, unknown>>() {
+      return { create: true, name: "review_a17_production", summary: "Review A17 production while preserving locked orders.",
+        trigger: "When planning the A17 order", selectedActionIds: ["a1", "a2", "a3", "a4"] } as unknown as T;
+    } };
+    const db = new MemoryDb({ path: ":memory:" });
+    let service = createTestMemoryService({ db, mode: "dev", config: DEFAULT_MEMMY_CONFIG,
+      configLoader: () => ({ config: DEFAULT_MEMMY_CONFIG }), llm, skillLlm });
+    const repos = new Repositories(db.db);
+    const sourceRecordIds = Array.from({ length: 5 }, (_value, index) => `recovery-window-${index}`);
+    const baseEvidence = { action: "upsert" as const, source: "computer_history", namespace, revision,
+      title: "A17 production review", summary: "Preserve locked orders when reviewing A17 production.",
+      startedAt: "2026-10-19T10:00:00.000Z", endedAt: "2026-10-19T10:10:00.000Z" };
+    const rows = sourceRecordIds.map((sourceRecordId, index) => service.syncExternalEvidence({ ...baseEvidence, sourceRecordId,
+      content: `**Production constraint**: The A17 order review for source ${index} must retain locked production orders.` }));
+    await runWorkerRounds(service, 3);
+    for (const row of rows) {
+      expect(service.memoryProcessingStatus([row.id]).items[0]).toMatchObject({
+        state: "failed", stage: "summary", attemptCount: 3, manualRetryCount: 0,
+        errorMessage: expect.stringContaining("quote_grounding")
+      });
+    }
+
+    const aggregate = service.syncExternalEvidence({ ...baseEvidence, sourceRecordId: "recovery-six-hour-summary",
+      content: "Six hours of A17 production planning observations.", parentSourceRecordIds: sourceRecordIds });
+    const suggestion = { source: "computer_history", namespace, revision, groupId: "a17-production-recovery",
+      sourceRecordIds: sourceRecordIds.slice(0, 2), actions: [
+        { sourceRecordId: sourceRecordIds[0]!, text: "Open the A17 order" },
+        { sourceRecordId: sourceRecordIds[0]!, text: "Review the production requirement" },
+        { sourceRecordId: sourceRecordIds[1]!, text: "Identify locked production orders" },
+        { sourceRecordId: sourceRecordIds[1]!, text: "Preserve the locked production schedule" }
+      ] };
+    await expect(service.suggestExternalEvidenceSkill(suggestion)).rejects.toThrow("source meaningful memory requires retry");
+
+    validOutput = true;
+    if (lifecycle === "startup") {
+      await service.stop();
+      service = createTestMemoryService({ db, mode: "dev", config: DEFAULT_MEMMY_CONFIG,
+        configLoader: () => ({ config: DEFAULT_MEMMY_CONFIG }), llm, skillLlm });
+      // Exercise the actual HTTP startup worker used by a newly activated runtime.
+      const server = createMemoryHttpServer({ service, workerStartupFallbackMs: 0 });
+      servers.push(server);
+      await new Promise<void>((resolveListen) => server.listen(0, "127.0.0.1", resolveListen));
+    } else {
+      service.reloadConfig();
+      for (const row of rows) expect(service.memoryProcessingStatus([row.id]).items[0]).toMatchObject({
+        state: "summary_pending", attemptCount: 0, manualRetryCount: 0
+      });
+    }
+
+    await vi.waitFor(async () => {
+      if (lifecycle === "config reload") await service.runWorkerOnce(100);
+      for (const row of [...rows, aggregate]) expect(service.memoryProcessingStatus([row.id]).items[0]?.state).toBe("ready");
+    }, { timeout: 5_000, interval: 20 });
+
+    for (const row of rows) {
+      expect(service.memoryProcessingStatus([row.id]).items[0]).toMatchObject({
+        state: "ready", manualRetryCount: 0, errorCode: null, errorMessage: null, failedAt: null
+      });
+      expect(observationMemoryState(repos.memories.get(row.id)!)).toMatchObject({ status: "processed" });
+      expect(db.db.prepare("SELECT status, attempts FROM evolution_jobs WHERE target_memory_id = ? AND job_type = 'observation_extract' ORDER BY created_at, id")
+        .all(row.id)).toEqual(expect.arrayContaining([{ status: "dead_letter", attempts: 3 }, { status: "succeeded", attempts: 1 }]));
+    }
+    expect(observationMemoryState(repos.memories.get(aggregate.id)!)).toMatchObject({ status: "processed" });
+    expect(await service.suggestExternalEvidenceSkill(suggestion)).toMatchObject({ status: "active" });
+  });
+});
diff --git a/Memory/viewer/package.json b/Memory/viewer/package.json
index e0d76a0cd..4a246ded1 100644
--- a/Memory/viewer/package.json
+++ b/Memory/viewer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@memmy/memory-viewer",
-  "version": "2.1.6",
+  "version": "2.1.7",
   "private": true,
   "type": "module"
 }
diff --git a/docs/qa/history-quote-grounding-20261021.md b/docs/qa/history-quote-grounding-20261021.md
new file mode 100644
index 000000000..ace7e8ef0
--- /dev/null
+++ b/docs/qa/history-quote-grounding-20261021.md
@@ -0,0 +1,42 @@
+# History observation quote recovery — 2026-10-21
+
+## Scope
+
+Repair the History → meaningful memory → dependent Skill path on the formal 1.2.3 source baseline. Memory is versioned 2.1.7 for package/runtime identification. This task does not build, install, sign, or push a desktop package; the integration agent owns packaging and the user owns GUI acceptance.
+
+## Behavior
+
+- Resolve permitted display differences to a continuous literal span of retained source content; save that original span rather than model-modified text.
+- Keep NFKC/whitespace compatibility. Restrict Markdown tolerance to clearly marked presentation, leaving code, operators, identifiers, numbers and dates intact.
+- Keep the existing bounded single-line ellipsis compatibility. Reject cross-line ellipsis, different product subtrees and retained-fragment joins; use bounded correction to request a continuous original quotation instead of guessing list/entity scope.
+- Remove generated metadata summaries from model input; keep them in provenance. Require quotes from the displayed body.
+- Include a fixed item ordinal and validation reason in persisted failures and the one bounded corrective generation. Do not echo failed quotes, source IDs or private text into feedback/logs.
+- Existing startup/config-reload recovery requeues exhausted retryable observations. Regression tests cover five sources, their six-hour aggregate and Skill resumption without manual retries.
+
+## Evidence
+
+The five persisted failure inputs were replayed in isolation using the actual Windows package’s configured summary client, the new prepared input/validator and the same generation settings (temperature 0, max_tokens 2400, thinking disabled). The Windows application and original database were not replaced or mutated.
+
+| Source window (UTC, 2026-10-19) | Model calls | Final result |
+| --- | ---: | --- |
+| 06:20 | 1 | valid |
+| 06:30 | 1 | valid |
+| 06:10 | 1 | valid |
+| 05:40 | 1 | valid |
+| 05:30 | 2 | valid after bounded correction |
+
+All six HTTP responses succeeded. Feeding the captured responses through the repaired full MemoryService in temporary databases produced five ready/processed, recallable observations. Every saved evidence_quote is a literal substring of its original source. These are isolated replay results, not installed-app or GUI acceptance.
+
+Sensitive original inputs and model responses remain outside the repository under the local diagnostic directory. Committed tests use synthetic sources, not copied personal paths or recordings.
+
+## Validation
+
+- Final formal-1.2.3 baseline: 411 relevant tests passed (298 Memory, 113 Desktop), plus Memory typecheck and project version consistency.
+- Memory evidence/recovery, source filtering and LLM JSON retry suites.
+- Memory typecheck, version consistency and runtime build/installer tests.
+- Desktop packaged-runtime boundary and Memory runtime upgrade tests (Node subprocess fixtures only; no GUI).
+- Regression boundaries include variable exponent operators, code/escaped Markdown, changed quantity/date/negation/product ID, cross-product list roots, fragment joins and Unicode source offsets.
+
+## User acceptance after integration/package
+
+Install the combined test package normally while retaining existing data. Check Memory 2.1.7 activates, the five sources finish processing, their aggregate/Skill stops reporting source retry required, and new History/WeChat sources remain readable. Then rehearse the actual A17 context → live Excel → Dolibarr draft flow. Source/CLI checks do not establish these GUI results.
diff --git a/package-lock.json b/package-lock.json
index 62d9213bc..c8bbb9385 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -745,7 +745,7 @@
     },
     "Memory": {
       "name": "@memmy/memory",
-      "version": "2.1.6",
+      "version": "2.1.7",
       "dependencies": {
         "@huggingface/transformers": "^3.8.0",
         "@memmy/agent-source-core": "0.0.0",

From c41b9785db66547adb537c150b40b45258ab03e8 Mon Sep 17 00:00:00 2001
From: jiachengzhen <jiacz@memtensor.cn>
Date: Wed, 21 Oct 2026 18:33:56 +0800
Subject: [PATCH 83/85] fix(installer): let non-C Windows installs continue
 after an explicit risk confirmation

Per-user Setup cannot set an owner on the shared drive data root, so v1.2.3 disabled Install for every non-C path. Create that directory as the current user, and ask before continuing when ownership still cannot be verified.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../build/MemmyWindowsRuntimeOwnership.ps1    | 71 ++++++++++++++++---
 .../desktop/build/installer-win-unsigned.nsh  | 26 +++++--
 .../tests/windows-runtime-ownership.test.ts   | 11 +++
 3 files changed, 93 insertions(+), 15 deletions(-)

diff --git a/App/shell/desktop/build/MemmyWindowsRuntimeOwnership.ps1 b/App/shell/desktop/build/MemmyWindowsRuntimeOwnership.ps1
index cc5b8f975..4edf20122 100644
--- a/App/shell/desktop/build/MemmyWindowsRuntimeOwnership.ps1
+++ b/App/shell/desktop/build/MemmyWindowsRuntimeOwnership.ps1
@@ -1,4 +1,4 @@
-param([string]$RuntimeHomePath = '', [switch]$LibraryOnly)
+param([string]$RuntimeHomePath = '', [switch]$LibraryOnly, [switch]$AcceptDriveRisk)
 
 # Every consumer calls this before probing or reading a shared non-C runtime.
 # An installation folder on the same drive still resolves to the same MemmyData.
@@ -29,10 +29,10 @@ function Get-MemmyOwnershipSid([string]$Path) {
   return (Get-Acl -LiteralPath $Path -ErrorAction Stop).GetOwner([System.Security.Principal.SecurityIdentifier]).Value
 }
 
-function New-MemmyPrivateOwnershipAcl([string]$Sid, [switch]$Directory) {
+function New-MemmyPrivateAccessAcl([string]$Sid, [switch]$Directory) {
+  # A per-user installer cannot SetOwner. The creator already owns a new object.
   $acl = if ($Directory) { New-Object System.Security.AccessControl.DirectorySecurity } else { New-Object System.Security.AccessControl.FileSecurity }
   $acl.SetAccessRuleProtection($true, $false)
-  $acl.SetOwner((New-Object System.Security.Principal.SecurityIdentifier($Sid)))
   foreach ($allowedSid in @($Sid, 'S-1-5-18', 'S-1-5-32-544')) {
     $identity = New-Object System.Security.Principal.SecurityIdentifier($allowedSid)
     $rule = if ($Directory) {
@@ -45,6 +45,35 @@ function New-MemmyPrivateOwnershipAcl([string]$Sid, [switch]$Directory) {
   return $acl
 }
 
+function New-MemmyPrivateOwnershipAcl([string]$Sid, [switch]$Directory) {
+  $acl = New-MemmyPrivateAccessAcl $Sid -Directory:$Directory
+  $acl.SetOwner((New-Object System.Security.Principal.SecurityIdentifier($Sid)))
+  return $acl
+}
+
+function Get-MemmyAcceptedDriveRiskPath {
+  if (-not $env:LOCALAPPDATA) { return $null }
+  return Join-Path $env:LOCALAPPDATA 'Memmy\data-layout\accepted-shared-drive-risk.json'
+}
+
+function Test-MemmyAcceptedDriveRisk([string]$DriveRoot, [string]$CurrentSid) {
+  $path = Get-MemmyAcceptedDriveRiskPath
+  if (-not $path -or -not (Test-Path -LiteralPath $path -PathType Leaf)) { return $false }
+  try {
+    $accepted = Get-Content -LiteralPath $path -Raw -ErrorAction Stop | ConvertFrom-Json
+    return [int]$accepted.schemaVersion -eq 1 -and [string]$accepted.windowsSid -eq $CurrentSid -and [string]$accepted.driveRoot -eq $DriveRoot
+  } catch { return $false }
+}
+
+function Save-MemmyAcceptedDriveRisk([string]$DriveRoot, [string]$CurrentSid) {
+  $path = Get-MemmyAcceptedDriveRiskPath
+  if (-not $path) { throw 'LOCALAPPDATA is required to record shared-drive install risk acceptance' }
+  $parent = Split-Path -Parent $path
+  if (-not (Test-Path -LiteralPath $parent -PathType Container)) { New-Item -ItemType Directory -Path $parent -Force | Out-Null }
+  $payload = [ordered]@{ schemaVersion = 1; windowsSid = $CurrentSid; driveRoot = $DriveRoot }
+  [System.IO.File]::WriteAllText($path, ($payload | ConvertTo-Json -Compress))
+}
+
 function Assert-MemmyOwnershipEvidence([string]$CurrentSid, [string]$OwnerSid, $Claim, [string]$ClaimOwnerSid) {
   if ($CurrentSid -notmatch '^S-1-(?:5-21|12-1)-\d+(?:-\d+)+$' -or $OwnerSid -ne $CurrentSid) { throw 'Cannot verify this Memmy data directory belongs to the current Windows account' }
   if ($null -ne $Claim) {
@@ -55,12 +84,21 @@ function Assert-MemmyOwnershipEvidence([string]$CurrentSid, [string]$OwnerSid, $
 function Assert-MemmySharedRuntimeOwnership([string]$RuntimeHomePath) {
   $root = Get-MemmySharedRuntimeRoot $RuntimeHomePath
   if (-not $root) { return }
-  $result = Assert-MemmyRuntimeRootOwnership $root
-  Assert-MemmyOwnershipNoReparse $RuntimeHomePath
-  if (Test-Path -LiteralPath $RuntimeHomePath) {
-    Assert-MemmyOwnershipEvidence $result.currentSid (Get-MemmyOwnershipSid $RuntimeHomePath) $null ''
+  try {
+    $result = Assert-MemmyRuntimeRootOwnership $root
+    Assert-MemmyOwnershipNoReparse $RuntimeHomePath
+    if (Test-Path -LiteralPath $RuntimeHomePath) {
+      Assert-MemmyOwnershipEvidence $result.currentSid (Get-MemmyOwnershipSid $RuntimeHomePath) $null ''
+    }
+    return $result
+  } catch {
+    if ($_.Exception.Message -like '*reparse*') { throw }
+    $drive = [System.IO.Path]::GetPathRoot([System.IO.Path]::GetFullPath($RuntimeHomePath))
+    $sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+    if (-not (Test-MemmyAcceptedDriveRisk $drive $sid)) { throw }
+    Assert-MemmyOwnershipNoReparse $RuntimeHomePath
+    return [ordered]@{ currentSid = $sid; ownerSid = $sid; claimOwnerSid = $sid; claimSid = $sid; fresh = $false }
   }
-  return $result
 }
 
 function Assert-MemmyRuntimeRootOwnership([string]$RootPath) {
@@ -71,10 +109,11 @@ function Assert-MemmyRuntimeRootOwnership([string]$RootPath) {
   $fresh = -not (Test-Path -LiteralPath $root)
   if ($fresh) {
     # Publish a fully private directory atomically. Never alter a raced/legacy root ACL.
+    # Create as the current user, then protect the DACL. SetOwner requires elevation.
     $staging = "$root.owner-init-$([Guid]::NewGuid().ToString('N'))"
     try {
-      $acl = New-MemmyPrivateOwnershipAcl $currentSid -Directory
-      [System.IO.Directory]::CreateDirectory($staging, $acl) | Out-Null
+      New-Item -ItemType Directory -Path $staging -ErrorAction Stop | Out-Null
+      Set-Acl -LiteralPath $staging -AclObject (New-MemmyPrivateAccessAcl $currentSid -Directory)
       [System.IO.Directory]::Move($staging, $root)
     } catch {
       if (-not (Test-Path -LiteralPath $root -PathType Container)) { throw }
@@ -103,7 +142,7 @@ function Assert-MemmyRuntimeRootOwnership([string]$RootPath) {
     $bytes = [System.Text.UTF8Encoding]::new($false).GetBytes(($claim | ConvertTo-Json -Compress))
     $stream = $null
     try {
-      $security = New-MemmyPrivateOwnershipAcl $currentSid
+      $security = New-MemmyPrivateAccessAcl $currentSid
       $stream = New-Object System.IO.FileStream($claimPath, [System.IO.FileMode]::CreateNew, [System.Security.AccessControl.FileSystemRights]::Write, [System.IO.FileShare]::None, 4096, [System.IO.FileOptions]::None, $security)
       $stream.Write($bytes, 0, $bytes.Length)
     } catch {
@@ -136,6 +175,16 @@ function Assert-MemmyRuntimeRootOwnership([string]$RootPath) {
 if (-not $LibraryOnly) {
   try {
     [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+    if ($AcceptDriveRisk) {
+      $acceptedPath = [System.IO.Path]::GetFullPath($RuntimeHomePath)
+      $acceptedDrive = [System.IO.Path]::GetPathRoot($acceptedPath)
+      $acceptedSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+      if ($acceptedDrive -notmatch '^[A-Za-z]:\\$' -or [string]::Equals($acceptedDrive, 'C:\', [System.StringComparison]::OrdinalIgnoreCase)) {
+        throw 'Shared-drive risk acceptance applies only to a non-C local drive'
+      }
+      Assert-MemmyOwnershipNoReparse $acceptedPath
+      Save-MemmyAcceptedDriveRisk $acceptedDrive $acceptedSid
+    }
     $result = Assert-MemmySharedRuntimeOwnership $RuntimeHomePath
     if ($null -ne $result) { $result | ConvertTo-Json -Compress }
     exit 0
diff --git a/App/shell/desktop/build/installer-win-unsigned.nsh b/App/shell/desktop/build/installer-win-unsigned.nsh
index cf4ce5cdd..b8b5d4670 100644
--- a/App/shell/desktop/build/installer-win-unsigned.nsh
+++ b/App/shell/desktop/build/installer-win-unsigned.nsh
@@ -432,10 +432,28 @@ Function MemmyValidateSelectedDirectories
   Pop $0
   Pop $1
   StrCmp $0 "0" memmy_validate_ownership_succeeded
-  StrCpy $R8 "Cannot verify that this drive's Memmy data belongs to your Windows account. Choose C: for a per-user installation, or a separate drive. Another folder on this same drive cannot isolate the data."
-  StrCmp $LANGUAGE ${MEMMY_LANG_SIMPCHINESE} 0 memmy_validate_failed
-  StrCpy $R8 "无法确认此盘的 Memmy 数据属于当前 Windows 账户。请选择 C 盘按用户安装，或使用独立盘；选择同一盘上的其他文件夹无法隔离数据。"
-  Goto memmy_validate_failed
+  ${If} ${Silent}
+    Goto memmy_validate_ownership_denied
+  ${EndIf}
+  StrCpy $R8 "Cannot verify that this drive's Memmy data belongs to your Windows account. Choose C: for a per-user installation, or a separate drive. Another folder on this same drive cannot isolate the data.$\r$\n$\r$\nI understand the risk and still want to install on this drive."
+  StrCmp $LANGUAGE ${MEMMY_LANG_SIMPCHINESE} 0 memmy_validate_ownership_confirm
+  StrCpy $R8 "无法确认此盘的 Memmy 数据属于当前 Windows 账户。请选择 C 盘按用户安装，或使用独立盘；选择同一盘上的其他文件夹无法隔离数据。$\r$\n$\r$\n我确认风险，仍要继续安装到该盘。"
+
+  memmy_validate_ownership_confirm:
+    MessageBox MB_YESNO|MB_ICONEXCLAMATION|MB_DEFBUTTON2 "$R8" IDYES memmy_accept_drive_risk
+    Goto memmy_validate_failed
+
+  memmy_accept_drive_risk:
+    nsExec::ExecToStack '"$SYSDIR\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$PLUGINSDIR\MemmyDataMigration\MemmyWindowsRuntimeOwnership.ps1" -RuntimeHomePath "$MemmyTargetRuntimeHomePath" -AcceptDriveRisk'
+    Pop $0
+    Pop $1
+    StrCmp $0 "0" memmy_validate_ownership_succeeded
+
+  memmy_validate_ownership_denied:
+    StrCpy $R8 "Cannot verify that this drive's Memmy data belongs to your Windows account. Choose C: for a per-user installation, or a separate drive. Another folder on this same drive cannot isolate the data."
+    StrCmp $LANGUAGE ${MEMMY_LANG_SIMPCHINESE} 0 memmy_validate_failed
+    StrCpy $R8 "无法确认此盘的 Memmy 数据属于当前 Windows 账户。请选择 C 盘按用户安装，或使用独立盘；选择同一盘上的其他文件夹无法隔离数据。"
+    Goto memmy_validate_failed
 
   memmy_validate_ownership_succeeded:
   StrCpy $R0 "$INSTDIR"
diff --git a/App/shell/desktop/tests/windows-runtime-ownership.test.ts b/App/shell/desktop/tests/windows-runtime-ownership.test.ts
index 5e5eedc31..8e18d3eec 100644
--- a/App/shell/desktop/tests/windows-runtime-ownership.test.ts
+++ b/App/shell/desktop/tests/windows-runtime-ownership.test.ts
@@ -78,6 +78,17 @@ describe("Windows shared drive runtime ownership", () => {
     const validate = nsis.slice(nsis.indexOf("Function MemmyValidateSelectedDirectories"), nsis.indexOf("Function MemmyExtractDataMigrationScript"));
     expect(validate.indexOf("MemmyWindowsRuntimeOwnership.ps1")).toBeLessThan(validate.indexOf("Call MemmyProbeWritableDirectory"));
     expect(validate).toContain("选择同一盘上的其他文件夹无法隔离数据");
+    expect(validate).toContain("我确认风险，仍要继续安装到该盘");
+    expect(validate).toContain("MB_YESNO|MB_ICONEXCLAMATION|MB_DEFBUTTON2");
+    expect(validate).toContain("-AcceptDriveRisk");
+    expect(validate.indexOf("${If} ${Silent}")).toBeLessThan(validate.indexOf("memmy_validate_ownership_confirm:"));
+    const guard = readSource("../build/MemmyWindowsRuntimeOwnership.ps1");
+    const freshInit = guard.slice(guard.indexOf("if ($fresh)"), guard.indexOf("$ownerSid = Get-MemmyOwnershipSid"));
+    expect(freshInit).toContain("New-Item -ItemType Directory -Path $staging");
+    expect(freshInit).toContain("New-MemmyPrivateAccessAcl $currentSid -Directory");
+    expect(freshInit).not.toContain("New-MemmyPrivateOwnershipAcl");
+    expect(guard).toContain("accepted-shared-drive-risk.json");
+    expect(guard).toContain("if ($_.Exception.Message -like '*reparse*') { throw }");
     expect(nsis.match(/File \/oname=MemmyWindowsRuntimeOwnership.ps1/g)).toHaveLength(4);
     const migration = readSource("../build/MemmyWindowsDataMigration.ps1");
     expect(migration).toContain("try {\n  Invoke-MemmyRuntimeOwnershipGuard $TargetRuntimeHomePath\n  if ($AcquireLock)");

From ab7d74603a9c838a41af56913a0abe114dab5d50 Mon Sep 17 00:00:00 2001
From: Yicheng <yicheng@yichengs-MacBook-Pro-893.local>
Date: Thu, 22 Oct 2026 21:19:44 +0800
Subject: [PATCH 84/85] fix: declare fzstd for the Memmy agent runtime package

wechat-message-batch.ts imports fzstd, but App/memmy-agent/package.json
did not list it. Local builds resolve it from the root workspace, while
agent:runtime:package installs only the agent's own dependencies, so the
bundle step failed with: Could not resolve "fzstd".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 App/memmy-agent/package-lock.json | 7 +++++++
 App/memmy-agent/package.json      | 1 +
 2 files changed, 8 insertions(+)

diff --git a/App/memmy-agent/package-lock.json b/App/memmy-agent/package-lock.json
index 4231c796d..847c5295e 100644
--- a/App/memmy-agent/package-lock.json
+++ b/App/memmy-agent/package-lock.json
@@ -37,6 +37,7 @@
         "eventsource": "^4.1.0",
         "exceljs": "^4.4.0",
         "fast-xml-parser": "^5.8.0",
+        "fzstd": "^0.1.1",
         "grammy": "^1.43.0",
         "html-validate": "10.17.0",
         "iconv-lite": "^0.7.2",
@@ -5699,6 +5700,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/fzstd": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/fzstd/-/fzstd-0.1.1.tgz",
+      "integrity": "sha512-dkuVSOKKwh3eas5VkJy1AW1vFpet8TA/fGmVA5krThl8YcOVE/8ZIoEA1+U1vEn5ckxxhLirSdY837azmbaNHA==",
+      "license": "MIT"
+    },
     "node_modules/get-caller-file": {
       "version": "2.0.5",
       "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
diff --git a/App/memmy-agent/package.json b/App/memmy-agent/package.json
index 9f0fcee55..e2bb45a25 100644
--- a/App/memmy-agent/package.json
+++ b/App/memmy-agent/package.json
@@ -52,6 +52,7 @@
     "eventsource": "^4.1.0",
     "exceljs": "^4.4.0",
     "fast-xml-parser": "^5.8.0",
+    "fzstd": "^0.1.1",
     "grammy": "^1.43.0",
     "html-validate": "10.17.0",
     "iconv-lite": "^0.7.2",

From 9693d250d8d2e5099a5218cac6f877df01e56445 Mon Sep 17 00:00:00 2001
From: jiachengzhen <jiacz@memtensor.cn>
Date: Thu, 22 Oct 2026 21:06:54 +0800
Subject: [PATCH 85/85] fix(cli): retry transient gateway bootstrap 503

---
 .../entrypoints/cli/linux-systemd-gateway.ts  |  6 +++
 .../cli/linux-systemd-gateway.test.ts         | 39 +++++++++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/App/memmy-agent/src/entrypoints/cli/linux-systemd-gateway.ts b/App/memmy-agent/src/entrypoints/cli/linux-systemd-gateway.ts
index 9508d0861..24488c9ef 100644
--- a/App/memmy-agent/src/entrypoints/cli/linux-systemd-gateway.ts
+++ b/App/memmy-agent/src/entrypoints/cli/linux-systemd-gateway.ts
@@ -216,6 +216,12 @@ export async function probeGateway(
         : undefined,
       signal: controller.signal,
     });
+    if (response.status === 503) {
+      return {
+        status: "unavailable",
+        detail: "bootstrap HTTP 503",
+      };
+    }
     if (!response.ok) {
       return {
         status: "unexpected",
diff --git a/App/memmy-agent/tests/entrypoints/cli/linux-systemd-gateway.test.ts b/App/memmy-agent/tests/entrypoints/cli/linux-systemd-gateway.test.ts
index 40c7431af..f28321b81 100644
--- a/App/memmy-agent/tests/entrypoints/cli/linux-systemd-gateway.test.ts
+++ b/App/memmy-agent/tests/entrypoints/cli/linux-systemd-gateway.test.ts
@@ -79,6 +79,9 @@ describe("Linux systemd Gateway probing", () => {
     const unauthorizedFetch = vi.fn(
       async () => new Response("Unauthorized", { status: 401 }),
     ) as unknown as typeof fetch;
+    const startingFetch = vi.fn(
+      async () => new Response("Gateway is still starting", { status: 503 }),
+    ) as unknown as typeof fetch;
     const invalidFetch = vi.fn(async () => new Response("{}", {
       status: 200,
       headers: { "content-type": "application/json" },
@@ -91,6 +94,10 @@ describe("Linux systemd Gateway probing", () => {
       status: "unexpected",
       detail: "bootstrap HTTP 401",
     });
+    await expect(probeGateway(configured(), { fetchImpl: startingFetch })).resolves.toEqual({
+      status: "unavailable",
+      detail: "bootstrap HTTP 503",
+    });
     await expect(probeGateway(configured(), { fetchImpl: invalidFetch })).resolves.toEqual({
       status: "unexpected",
       detail: "bootstrap response is incompatible",
@@ -294,6 +301,38 @@ describe("Linux systemd Gateway root terminal flow", () => {
     ]);
   });
 
+  it("retries a transient bootstrap 503 while the managed service starts", async () => {
+    const config = configured();
+    let serviceRunning = false;
+    const probes: GatewayProbe[] = [
+      { status: "unavailable", detail: "bootstrap HTTP 503" },
+      { status: "unavailable", detail: "bootstrap HTTP 503" },
+      { status: "ready" },
+    ];
+    const enableGatewayService = vi.fn(async () => {
+      serviceRunning = true;
+    });
+    const runInteractive = vi.fn(async () => null);
+
+    await runLinuxRootTerminal({
+      platform: "linux",
+      stdinIsTTY: true,
+      stdoutIsTTY: true,
+      systemdGatewayEnabled: true,
+      loadConfig: () => config,
+      onboardWizard: vi.fn(),
+      prepareGatewayEnvironment: async () => false,
+      enableGatewayService,
+      probeGateway: vi.fn(async (): Promise<GatewayProbe> => probes.shift() ?? { status: "ready" }),
+      gatewayServiceMainPid: vi.fn(async () => serviceRunning ? 789 : null),
+      sleep: async () => undefined,
+      runInteractive,
+    });
+
+    expect(enableGatewayService).toHaveBeenCalledWith({ restart: false });
+    expect(runInteractive).toHaveBeenCalledWith(config);
+  });
+
   it("keeps systemd ownership and restarts when the persisted environment changes", async () => {
     const config = configured();
     const prepareGatewayConfig = vi.fn(async () => config);