修复预览测试时序断言

允许最后一个预览在被动 effect 调度中延后一轮提交
Merge remote-tracking branch 'origin/master' into codex/ci-stability-20260917
2026-09-17 01:13:24 +08:00 · 2026-09-17 01:08:03 +08:00 · 2026-09-17 00:54:28 +08:00 · 2026-09-17 00:54:28 +08:00 · 2026-09-17 00:54:28 +08:00 · 2026-09-17 00:54:28 +08:00
53 changed files with 2290 additions and 308 deletions
@@ -7,6 +7,10 @@ on:
  pull_request:
  workflow_dispatch:

+concurrency:
+  group: project-ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 permissions:
  contents: read

@@ -38,6 +38,7 @@ vi.mock('../api/adminApiClient', () => ({

 interface MockIntersectionObserverController {
  enter: (target: Element) => void;
+  enterAll: (targets: Element[]) => void;
  isObserved: (target: Element) => boolean;
 }

@@ -106,6 +107,25 @@ function installIntersectionObserverMock(): MockIntersectionObserverController {
        );
      });
    },
+    enterAll(targets) {
+      act(() => {
+        for (const target of targets) {
+          const record = observed.get(target);
+          if (!record) {
+            throw new Error('目标缩略图尚未进入 IntersectionObserver');
+          }
+          record.callback(
+            [
+              {
+                isIntersecting: true,
+                target,
+              } as IntersectionObserverEntry,
+            ],
+            record.observer,
+          );
+        }
+      });
+    },
    isObserved(target) {
      return observed.has(target);
    },
@@ -753,10 +773,10 @@ test('后台素材查询为大量同时可见的缩略图持续错峰换签', as
  const thumbnails = entries.map((entry) =>
    thumbnailElementForLabel(entry.label),
  );
-  thumbnails.forEach((thumbnail) => {
+  for (const thumbnail of thumbnails) {
    expect(observer.isObserved(thumbnail)).toBe(true);
-    observer.enter(thumbnail);
-  });
+  }
+  observer.enterAll(thumbnails);
  await act(async () => {
    await Promise.resolve();
  });
@@ -776,7 +796,7 @@ test('后台素材查询为大量同时可见的缩略图持续错峰换签', as
    await vi.advanceTimersByTimeAsync(200);
  });
  expect(getAdminAssetReadUrl).toHaveBeenCalledTimes(105);
-});
+}, 10_000);

 test('后台素材查询读取更多后为新进入可视区域的素材换签', async () => {
  const observer = installIntersectionObserverMock();
@@ -1,7 +1,7 @@
 {
  "name": "@genarrative/ai-game-creator-shell",
  "private": true,
-  "version": "0.1.45",
+  "version": "0.1.47",
  "type": "module",
  "scripts": {
    "dev": "node scripts/start-tauri-dev.mjs",
@@ -1725,7 +1725,7 @@ dependencies = [

 [[package]]
 name = "genarrative-ai-game-creator-shell"
-version = "0.1.45"
+version = "0.1.47"
 dependencies = [
 "agent-runtime-core",
 "axum",
@@ -1,6 +1,6 @@
 [package]
 name = "genarrative-ai-game-creator-shell"
-version = "0.1.45"
+version = "0.1.47"
 edition = "2021"
 publish = false

@@ -2,7 +2,7 @@
  {"type":"function","function":{"name":"get_workflow_status","description":"读取当前策划工作流状态，只返回阶段列表、当前阶段、已批准阶段和待审批阶段；不推进阶段、不提交审批、不修改文件。","parameters":{"type":"object","properties":{},"additionalProperties":false}}},
  {"type":"function","function":{"name":"list_resources","description":"列出固定资源的逻辑目录、资源 ID、标题和简介。资源是只读的随包文档；不要猜测物理路径。","parameters":{"type":"object","properties":{},"additionalProperties":false}}},
  {"type":"function","function":{"name":"read_resource","description":"读取一份固定资源文档全文。每次读取一个 resource_id；资源只读。读到未实现占位文档时由你自行判断和处理。","parameters":{"type":"object","properties":{"resource_id":{"type":"string"}},"required":["resource_id"],"additionalProperties":false}}},
-  {"type":"function","function":{"name":"patch_file","description":"局部修改 UTF-8 文件。使用 old_text/new_text，或使用 edits 一次进行多个独立替换；每个 old_text 必须非空且在原文件中唯一，匹配失败、重复或范围重叠时不修改文件。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"},"old_text":{"type":"string"},"new_text":{"type":"string"},"edits":{"type":"array","items":{"type":"object","properties":{"old_text":{"type":"string"},"new_text":{"type":"string"}},"required":["old_text","new_text"],"additionalProperties":false}}},"required":["path"],"additionalProperties":false}}},
+  {"type":"function","function":{"name":"patch_file","description":"局部修改 UTF-8 文件。使用 old_text/new_text，或使用 edits 一次进行多个独立替换；每个 old_text 必须非空且在原文件中唯一。所有 edit 会一次性校验；任何失败都不修改文件，错误会列出各失败项及可唯一匹配的其余项。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"},"old_text":{"type":"string"},"new_text":{"type":"string"},"edits":{"type":"array","items":{"type":"object","properties":{"old_text":{"type":"string"},"new_text":{"type":"string"}},"required":["old_text","new_text"],"additionalProperties":false}}},"required":["path"],"additionalProperties":false}}},
  {"type":"function","function":{"name":"delete_path","description":"谨慎使用；永久删除工作区内的文件或目录；目录会连同全部内容递归删除，不备份。先确认目标及删除范围。path 使用相对路径，不能删除工作区根目录，也不能经过链接。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}},
  {"type":"function","function":{"name":"list_dir","description":"列出工作目录内的文件和目录。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}},
  {"type":"function","function":{"name":"read_file","description":"读取工作目录内的 UTF-8 文本文件。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}},
@@ -14,7 +14,7 @@ Let the client derive projections from real disk changes and trusted tool result
 3. Keep read scopes separate: `asset.list` is the current project manifest, `asset.library.list` is the signed-in account library, and the web project's canvas resource read model is the authoritative canvas list. The account library is not the complete canvas list.
 4. Use `canvas.asset_import` for safe account/canvas asset IDs or project-relative local paths. The client rechecks ownership and validates bytes; host absolute paths require native UI file-picker authorization.
 5. When the user explicitly asks to create or derive video, character animation, sound effect, or background music, call `agc_create_or_derive_resource`. Use `create` only for video/audio without a source and `derive` with a registered `sourceLocalAssetId`; character animation is always derived from an image.
-6. When the user explicitly asks to remove an image background, call `agc_remove_background` with a registered image `sourceLocalAssetId` and an output name. The client requires the signed-in account, owns canvas/folder context and task identity, and returns only bounded queue state.
+6. When the user explicitly asks to remove an image background, call `agc_remove_background` with a registered image `sourceLocalAssetId` and `assetName`. Optional `backgroundMode` is `complex` (semantic foreground segmentation; default) or `flat` (solid-colour background removal). Prefer `flat` when the background is known to be solid. Only `flat` accepts optional `screenColor`: `auto`, `#RRGGBB`, or omitted for automatic detection by the service. Do not select a colour on behalf of `auto`. The client requires the signed-in account, owns canvas/folder context and task identity, and returns only bounded queue state.
 7. Preserve existing relative paths when a small edit is sufficient so client resource identities remain stable.
 8. Do not edit `.agent/manifest.json`, revision counters, version records, resource IDs, canvas identities, source provenance, generation ledgers, or browser receipts by hand.
 9. Do not create a version when no game file changed. The client compares content fingerprints and advances revision only after an actual source change.
@@ -14,4 +14,4 @@ Read scopes remain separate: `asset.list` is the current project's local manifes

 `agc_create_or_derive_resource` accepts only semantic intent. The client resolves `sourceLocalAssetId`, creates stable request identities, recovers matching pending operations, serializes paid submissions, writes supported media into the current canvas and same-name asset folder, validates downloaded bytes, commits the local manifest transaction, and returns redacted warnings. A tool error or timeout is not permission to generate again with a new identity.

-`agc_remove_background` is the semantic image post-processing path. It accepts only a registered image `sourceLocalAssetId` and output name; the client resolves the formal source resource, canvas/folder context, stable operation identity, idempotency key, and authenticated External v1 `/api/external/v1/editor/images/background-removals` call. Its result is bounded queue state; Codex must not poll internal workers, construct source URLs, or retry with a new identity after an uncertain response.
+`agc_remove_background` accepts a registered image `sourceLocalAssetId`, `assetName`, and optional `backgroundMode` and `screenColor`. `complex` uses semantic segmentation to identify the foreground; `flat` removes a solid-colour background. Prefer `flat` when the background is known to be solid; omitting the mode selects `complex`. Only `flat` accepts a colour: `auto`, `#RRGGBB`, or omitted for automatic service detection. Never infer a concrete colour for `auto`. Empty or invalid values and colour without `flat` are rejected. The client resolves the formal source resource, canvas/folder context, stable operation identity, idempotency key, and authenticated External v1 `/api/external/v1/editor/images/background-removals` call. Mode and colour are part of request identity. Its result is bounded queue state; Codex must not poll internal workers, construct source URLs, or retry with a new identity after an uncertain response.
@@ -1,6 +1,6 @@
 {
  "schemaVersion": "agc-skill-pack.v1",
-  "version": "2026-08-26.16",
+  "version": "2026-08-26.17",
  "skills": [
    {
      "name": "agc-game-production-workflow",
@@ -123,7 +123,7 @@
        "agents/openai.yaml",
        "references/projection-contract.md"
      ],
-      "sha256": "96b5bf9e2ed150bbe934a888867c1bb500b214a131f8b36c4830f51ca30267b6"
+      "sha256": "a929c27bc5b2b0bee0b7935e5c7b04ddbab1eb1804fe196f8c2537ad040ca5b1"
    }
  ]
 }
@@ -195,6 +195,20 @@ impl CodexAppServerStderrSummary {
    }
 }

+/// 派发 app-server 的收尾与中断任务。
+///
+/// 这个入口会被**没有 tokio runtime 上下文的线程**调用：`cancel_direct_codex_turn`
+/// 是同步 Tauri 命令，直接跑在 IPC 回调线程（Windows 上是 WebView2 的 UI 线程）；
+/// [`CodexThreadLease`] 与 [`CodexTurnGuard`] 的 `Drop` 也在调用方线程上执行。
+/// `tokio::spawn` 在那样的线程上会经 `Handle::current()` panic（"there is no reactor
+/// running"），而 panic 跨不过 Tauri 的 IPC 回调边界，整个进程会以 `0xC0000409`
+/// （FAST_FAIL_FATAL_APP_EXIT）abort——现场就是"点终止，App 闪退"（2026-09-16 的 WER
+/// 记录：`genarrative-ai-game-creator-shell.exe`，异常代码 `0xc0000409`，fail-fast
+/// 参数 `7`）。一律走 Tauri 的全局异步 runtime：`main` 已把深栈 runtime 装进去。
+fn spawn_codex_app_server_task(task: impl std::future::Future<Output = ()> + Send + 'static) {
+    tauri::async_runtime::spawn(task);
+}
+
 struct CodexTurnStartCancellation {
    inner: Weak<CodexAppServerInner>,
    thread_id: String,
@@ -256,7 +270,7 @@ impl CodexTurnStartCancellation {
        };
        let connection = CodexAppServerConnection { inner };
        let thread_id = self.thread_id.clone();
-        tokio::spawn(async move {
+        spawn_codex_app_server_task(async move {
            let _ = connection
                .request(
                    "turn/interrupt",
@@ -3566,7 +3580,7 @@ impl Drop for CodexThreadLease {
        let connection = self.connection.clone();
        let key = self.key.clone();
        let thread_id = self.thread_id.clone();
-        tokio::spawn(async move {
+        spawn_codex_app_server_task(async move {
            let mut threads = connection.inner.threads.lock().await;
            if let Some(entry) = threads.get_mut(&key) {
                if entry.thread_id == thread_id {
@@ -3593,7 +3607,7 @@ impl Drop for CodexTurnGuard {
        let connection = self.connection.clone();
        let thread_id = self.thread_id.clone();
        let turn_id = self.turn_id.clone();
-        tokio::spawn(async move {
+        spawn_codex_app_server_task(async move {
            connection.inner.turns.lock().await.remove(&turn_id);
            connection.inner.turn_backlog.lock().await.remove(&turn_id);
            let _ = connection
@@ -4489,6 +4503,19 @@ mod tests {
        assert!(table.select(&key, None).is_err());
    }

+    /// 终止路径会从同步命令线程和 `Drop` 里派发 app-server 任务：那些线程没有 tokio
+    /// runtime 上下文。`tokio::spawn` 在那里 panic，panic 跨不过 IPC 回调边界就把整个
+    /// 进程 abort（0xC0000409，"点终止就闪退"）。这条用例把派发入口钉在没有 runtime
+    /// 上下文的线程上，回退到 `tokio::spawn` 时它会失败。
+    #[test]
+    fn codex_app_server_task_dispatch_needs_no_tokio_runtime_context() {
+        let joined = std::thread::spawn(|| spawn_codex_app_server_task(async {}));
+        assert!(
+            joined.join().is_ok(),
+            "没有 tokio runtime 上下文的线程也必须能派发 app-server 收尾任务"
+        );
+    }
+
    /// 注册键：前端传的项目路径与回合注册时的路径必须归一化成同一个键（Windows 上
    /// `canonicalize` 会带 `\\?\` 前缀，去掉后两边才相等）。
    #[test]
@@ -527,10 +527,6 @@ fn process_design_batch(
        let result = if uncertain {
            Err("进程在工具执行期间中断，执行结果未保存。未重复执行；请读取实际工作区确认结果后再决定下一步。".to_string())
        } else {
-            let _write = acquire_game_creator_agent_runtime_project_write_lock_with_wait(
-                root,
-                "design.tool",
-            )?;
            execute_design_tool(root, resources, session, &call)
        };
        let error = result
@@ -1026,6 +1022,15 @@ pub(crate) async fn continue_design_agent_at(
    finish_design_command(root, resources, session, active, run, emit).await
 }

+async fn recover_uncertain_design_batch(
+    root: &Path,
+    resources: &DesignResources,
+    session: DesignSession,
+    active: File,
+) -> Result<DesignView, String> {
+    finish_design_command(root, resources, session, active, true, |_| {}).await
+}
+
 pub(crate) async fn decide_design_phase_at(
    root: &Path,
    resources: &DesignResources,
@@ -1058,7 +1063,8 @@ fn ensure_design_runtime_active(root: &Path) -> Result<(), String> {
 }

 #[tauri::command]
-pub(crate) fn hydrate_design_agent_session(
+pub(crate) async fn hydrate_design_agent_session(
+    app: tauri::AppHandle,
    project_path: String,
 ) -> Result<Option<DesignView>, String> {
    let root = Path::new(project_path.trim());
@@ -1084,8 +1090,33 @@ pub(crate) fn hydrate_design_agent_session(
    if session.project_id != project_id {
        return Err("策划会话与当前项目不匹配".into());
    }
-    let active = try_open_game_creator_agent_runtime_task_lock_file(root, DESIGN_ACTIVE_LOCK)?;
-    Ok(Some(design_view(&session, active.is_none())))
+    let Some(active) =
+        try_open_game_creator_agent_runtime_task_lock_file(root, DESIGN_ACTIVE_LOCK)?
+    else {
+        return Ok(Some(design_view(&session, true)));
+    };
+    if design_session_has_uncertain_batch(&session) {
+        let resources = DesignResources::new(resolve_design_resources_root(&app)?)?;
+        let view = recover_uncertain_design_batch(root, &resources, session, active).await?;
+        return Ok(Some(view));
+    }
+    drop(active);
+    Ok(Some(design_view(&session, false)))
+}
+
+fn design_session_has_uncertain_batch(session: &DesignSession) -> bool {
+    let Some(batch) = session.pending_batch.as_ref() else {
+        return false;
+    };
+    if !batch.executing || batch.cursor >= batch.calls.len() {
+        return false;
+    }
+    let call_id = batch.calls[batch.cursor].id.as_str();
+    session.turn.as_ref().is_some_and(|turn| turn.pending)
+        && !session.history.iter().any(|item| {
+            item.get("type").and_then(Value::as_str) == Some("function_call_output")
+                && item.get("call_id").and_then(Value::as_str) == Some(call_id)
+        })
 }

 fn design_session_error_is_recoverable(error: &str) -> bool {
@@ -1958,4 +1989,94 @@ mod tests {
            .any(|message| message.text.contains("重试后继续")));
        assert!(next.session.last_error.is_none());
    }
+
+    #[tokio::test(flavor = "current_thread")]
+    async fn uncertain_batch_hydrate_continues_the_original_turn_without_replaying_file_tools() {
+        let (_temp, root, resources) = init_design_project();
+        execute_design_file_tool(
+            &root,
+            "write_file",
+            &json!({"path":"project/00_concept/design.md","content":"概念"}),
+        )
+        .expect("write concept");
+        let mut session = new_design_session("design-fake", "quality");
+        let call = platform_llm::LlmToolCall {
+            id: "interrupted-call".into(),
+            name: "patch_file".into(),
+            arguments: json!({
+                "path":"project/00_concept/design.md",
+                "old_text":"概念",
+                "new_text":"概念设计"
+            })
+            .to_string(),
+        };
+        session.history.push(json!({
+            "type":"function_call",
+            "call_id":call.id,
+            "name":call.name,
+            "arguments":call.arguments,
+        }));
+        session.messages = vec![DesignMessage {
+            id: "turn:user".into(),
+            role: "user".into(),
+            text: "继续".into(),
+        }];
+        session.turn = Some(DesignTurn {
+            id: "turn-recovery".into(),
+            pending: true,
+            request_index: 0,
+            attempt: 0,
+        });
+        session.pending_batch = Some(DesignToolBatch {
+            calls: vec![call],
+            cursor: 0,
+            executing: true,
+        });
+        assert!(design_session_has_uncertain_batch(&session));
+        write_design_session(&root, &session).expect("write interrupted session");
+
+        let _fake = fake_provider::install(
+            vec![Ok(fake_response(
+                "recovered-after-uncertain-tool",
+                "已读取文件并确认。",
+                Vec::new(),
+            ))],
+            0,
+        );
+        let view = recover_uncertain_design_batch(&root, &resources, session, {
+            try_open_game_creator_agent_runtime_task_lock_file(
+                &root,
+                ".agent/design-agent/active.lock",
+            )
+            .expect("open active lock")
+            .expect("active lock is free")
+        })
+        .await
+        .expect("recover uncertain batch");
+
+        assert!(!view.running);
+        assert!(view.session.last_error.is_none());
+        let restored = read_design_session(&root)
+            .expect("read restored")
+            .expect("session");
+        assert!(restored.pending_batch.is_none());
+        assert!(!restored.turn.expect("turn").pending);
+        assert!(restored.history.iter().any(|item| {
+            item.get("type").and_then(Value::as_str) == Some("function_call_output")
+                && item.get("call_id").and_then(Value::as_str) == Some("interrupted-call")
+                && item
+                    .get("output")
+                    .and_then(Value::as_str)
+                    .is_some_and(|output| output.contains("执行结果未保存"))
+        }));
+        assert!(restored.history.iter().any(|item| {
+            item.get("role").and_then(Value::as_str) == Some("assistant")
+                && item.get("content").is_some()
+        }));
+        assert!(
+            fs::read_to_string(root.join("design_artifacts/project/00_concept/design.md"))
+                .expect("read target")
+                == "概念"
+        );
+    }
 }
@@ -321,15 +321,31 @@ pub(crate) fn execute_design_file_tool(
                })
                .collect::<Vec<_>>();
            let mut matches = Vec::new();
+            let mut edit_errors = Vec::new();
+            let mut valid_edits = 0;
            for (index, (old, new)) in normalized.iter().enumerate() {
+                if old == new {
+                    edit_errors.push(format!(
+                        "edits[{index}] new_text 与 old_text 相同，不会产生修改"
+                    ));
+                    continue;
+                }
                let count = content.matches(old).count();
                if count == 0 {
-                    return Err(format!("edits[{index}] 原文未找到：{display}"));
+                    edit_errors.push(format!(
+                        "edits[{index}] 原文未找到：{}{}",
+                        display,
+                        design_patch_location_hint(&content, old)
+                    ));
+                    continue;
                }
                if count != 1 {
-                    return Err(format!(
-                        "edits[{index}] 原文匹配 {count} 处，必须唯一：{display}"
+                    let start = content.find(old).expect("count checked");
+                    let line = design_patch_line_number(&content, start);
+                    edit_errors.push(format!(
+                        "edits[{index}] 原文匹配 {count} 处，必须唯一；首次位于第 {line} 行"
                    ));
+                    continue;
                }
                let start = content.find(old).expect("count checked");
                let end = start + old.len();
@@ -337,13 +353,33 @@ pub(crate) fn execute_design_file_tool(
                    .iter()
                    .find(|(_, other_start, other_end)| start < *other_end && *other_start < end)
                {
-                    return Err(format!(
-                        "edits[{index}] 与 edits[{other_index}] 修改范围重叠：{display}"
+                    edit_errors.push(format!(
+                        "edits[{index}] 与 edits[{other_index}] 修改范围重叠；请合并为一个 edit 或缩短 old_text"
                    ));
+                    continue;
                }
                matches.push((index, start, end));
+                valid_edits += 1;
                let _ = new;
            }
+            if !edit_errors.is_empty() {
+                let shown = edit_errors.len().min(4);
+                let mut details = edit_errors[..shown].to_vec();
+                if shown < edit_errors.len() {
+                    details.push(format!(
+                        "另有 {} 个 edit 校验失败（详情省略）",
+                        edit_errors.len() - shown
+                    ));
+                }
+                if valid_edits > 0 {
+                    details.push(format!(
+                        "其余 {valid_edits} 个 edit 当前可唯一匹配；本次未写入文件"
+                    ));
+                } else {
+                    details.push("本次未写入文件".to_string());
+                }
+                return Err(details.join("\n"));
+            }
            let mut updated = content.clone();
            for (index, start, end) in matches.into_iter().rev() {
                let (_, new) = &normalized[index];
@@ -396,6 +432,60 @@ pub(crate) fn execute_design_file_tool(
    }
 }

+fn design_patch_line_number(content: &str, start: usize) -> usize {
+    1 + content[..start]
+        .bytes()
+        .filter(|byte| *byte == b'\n')
+        .count()
+}
+
+fn design_patch_visible_line(line: &str) -> String {
+    line.replace('\t', "\\t").chars().take(180).collect()
+}
+
+fn design_patch_location_hint(content: &str, old: &str) -> String {
+    let Some(anchor) = old.lines().map(str::trim).find(|line| !line.is_empty()) else {
+        return String::new();
+    };
+
+    let mut candidates = content
+        .lines()
+        .enumerate()
+        .filter(|(_, line)| line.trim() == anchor)
+        .map(|(index, line)| (index + 1, line))
+        .collect::<Vec<_>>();
+    if candidates.is_empty() {
+        let token = anchor.split_whitespace().find(|token| token.len() >= 3);
+        if let Some(token) = token {
+            candidates = content
+                .lines()
+                .enumerate()
+                .filter(|(_, line)| line.trim().contains(token))
+                .map(|(index, line)| (index + 1, line))
+                .collect();
+        }
+    }
+    if candidates.is_empty() {
+        return format!(
+            "；未找到与 old_text 首个非空行相似的行（当前文件约 {} 行）",
+            content.lines().count()
+        );
+    }
+
+    let details = candidates
+        .iter()
+        .take(2)
+        .map(|(line, text)| format!("第 {line} 行：{}", design_patch_visible_line(text)))
+        .collect::<Vec<_>>()
+        .join("；");
+    let suffix = if candidates.len() > 2 {
+        format!("等 {} 处", candidates.len())
+    } else {
+        String::new()
+    };
+    format!("；old_text 首个非空行可能对应 {details}{suffix}（tab 显示为 \\t）")
+}
+
 pub(crate) fn list_design_workspace_files(
    root: &Path,
 ) -> Result<Vec<DesignWorkspaceEntry>, String> {
@@ -693,6 +783,22 @@ mod tests {
        )
        .expect_err("escape");
        assert!(escaped.contains("路径"));
+        let mismatch = execute_design_file_tool(
+            root,
+            "patch_file",
+            &json!({
+                "path":"notes/design.md",
+                "edits":[
+                    {"old_text":"  游戏设计","new_text":"游戏概念"},
+                    {"old_text":"设计","new_text":"方案"}
+                ]
+            }),
+        )
+        .expect_err("report all patch failures");
+        assert!(mismatch.contains("edits[0] 原文未找到"));
+        assert!(mismatch.contains("第 1 行：游戏设计"));
+        assert!(mismatch.contains("其余 1 个 edit 当前可唯一匹配"));
+        assert!(mismatch.contains("本次未写入文件"));
        let patched = execute_design_file_tool(
            root,
            "patch_file",
@@ -1887,7 +1887,7 @@ async fn bridge_create_or_derive_resource(

 async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Value) -> Value {
    let result = async {
-        bridge_reject_unknown_fields(arguments, &["sourceLocalAssetId", "assetName"])?;
+        super::direct_tools_mcp::validate_remove_background_arguments(arguments)?;
        enforce_project_permission_policy(&state.root, "canvas.asset_generate")?;
        enforce_project_permission_policy(&state.root, "asset.register")?;
        let source_asset_id = bridge_bounded_string(arguments, "sourceLocalAssetId", 80)?;
@@ -1896,6 +1896,8 @@ async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Val
            "assetName",
            DIRECT_TOOL_BRIDGE_MAX_RESOURCE_NAME_CHARS,
        )?;
+        let background_mode = arguments.get("backgroundMode").and_then(Value::as_str);
+        let screen_color = arguments.get("screenColor").and_then(Value::as_str);
        let manifest = read_existing_manifest_for_project(&state.root)?;
        let source_asset = manifest
            .assets
@@ -1920,22 +1922,34 @@ async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Val
            .map_err(|_| "创建抠图服务连接失败".to_string())?;
        let context =
            prepare_external_canvas_generation_context(&state.root, &client, &access).await?;
-        let fingerprint = format!("{}\0{}", source_asset_id, asset_name);
+        let fingerprint = background_removal_request_fingerprint(
+            &source_asset_id,
+            &asset_name,
+            background_mode,
+            screen_color,
+        );
        let (_operation_id, idempotency_key) = state.resource_request_ids(&fingerprint)?;
        let route = "/api/external/v1/editor/images/background-removals";
+        let mut request_body = json!({
+            "sourceImageSrc": source_resource_id,
+            "projectId": manifest.project_id,
+            "assetKind": source_asset.kind,
+            "assetFolderId": context.asset_folder_id,
+            "assetLabel": asset_name,
+            "sourceResourceId": source_resource_id,
+        });
+        if background_mode == Some("flat") {
+            request_body["backgroundMode"] = json!("flat");
+        }
+        if let Some(color) = screen_color {
+            request_body["screenColor"] = json!(color);
+        }
        let response = crate::http_client::with_agc_main_site_marker(
            client
                .post(format!("{}{}", api_base_url, route))
                .bearer_auth(api_key)
                .header("Idempotency-Key", idempotency_key)
-                .json(&json!({
-                    "sourceImageSrc": source_resource_id,
-                    "projectId": manifest.project_id,
-                    "assetKind": source_asset.kind,
-                    "assetFolderId": context.asset_folder_id,
-                    "assetLabel": asset_name,
-                    "sourceResourceId": source_resource_id,
-                })),
+                .json(&request_body),
        )
        .send()
        .await
@@ -1972,6 +1986,20 @@ async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Val
    }
 }

+fn background_removal_request_fingerprint(
+    source: &str,
+    name: &str,
+    mode: Option<&str>,
+    color: Option<&str>,
+) -> String {
+    let mode = mode.unwrap_or("complex");
+    if mode == "complex" && color.is_none() {
+        format!("{source}\0{name}")
+    } else {
+        format!("{source}\0{name}\0{mode}\0{}", color.unwrap_or(""))
+    }
+}
+
 fn bridge_safe_queue_state(value: Value) -> Value {
    let object = value.as_object();
    json!({
@@ -2703,6 +2731,29 @@ pub(crate) async fn start_direct_tool_bridge(

 #[cfg(test)]
 mod tests {
+    #[test]
+    fn remove_background_identity_preserves_default_and_distinguishes_options() {
+        let legacy = "asset-1\0透明图";
+        assert_eq!(
+            background_removal_request_fingerprint("asset-1", "透明图", None, None),
+            legacy
+        );
+        assert_eq!(
+            background_removal_request_fingerprint("asset-1", "透明图", Some("complex"), None),
+            legacy
+        );
+        let mut identities = std::collections::HashSet::new();
+        identities.insert(legacy.to_string());
+        for color in [None, Some("auto"), Some("#CFEFFF"), Some("#112233")] {
+            let id =
+                background_removal_request_fingerprint("asset-1", "透明图", Some("flat"), color);
+            assert_eq!(
+                id,
+                background_removal_request_fingerprint("asset-1", "透明图", Some("flat"), color)
+            );
+            assert!(identities.insert(id));
+        }
+    }
    use super::*;
    use std::io::{Cursor, Read, Write};

@@ -435,7 +435,7 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab
        }),
        json!({
                "name": "agc_remove_background",
-                "description": "为当前项目已登记的图片资源去除背景。客户端使用当前登录账号的抠图服务、项目画布和素材目录，模型只能提供已登记资源身份与结果名称；不会返回 Token、内部路由、宿主路径或临时签名 URL。",
+                "description": "为当前项目已登记的图片资源去除背景。complex 通过语义分割识别前景；flat 用于纯色背景抠图，确定背景为纯色时优先选择 flat。提供资源身份、结果名称及可选模式和背景色；客户端管理登录、项目画布和素材目录，不返回 Token、内部路由、宿主路径或临时签名 URL。",
                "inputSchema": {
                    "type": "object",
                    "properties": {
@@ -449,6 +449,16 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab
                            "type": "string",
                            "minLength": 1,
                            "maxLength": DIRECT_TOOLS_MCP_MAX_RESOURCE_NAME_CHARS
+                        },
+                        "backgroundMode": {
+                            "type": "string",
+                            "enum": ["complex", "flat"],
+                            "description": "可选抠图模式：complex 用语义分割识别前景，flat 用纯色背景抠图；确定背景为纯色时优先使用 flat。省略时使用 complex"
+                        },
+                        "screenColor": {
+                            "type": "string",
+                            "pattern": "^(auto|#[0-9A-Fa-f]{6})$",
+                            "description": "flat 模式可选背景色；传 auto 或 #RRGGBB，省略时由服务自动检测"
                        }
                    },
                    "required": ["sourceLocalAssetId", "assetName"],
@@ -881,14 +891,46 @@ fn validate_resource_generation_arguments(arguments: &Value) -> Result<(), Strin
    }
 }

-fn validate_remove_background_arguments(arguments: &Value) -> Result<(), String> {
-    validate_tool_object_fields(arguments, &["sourceLocalAssetId", "assetName"])?;
+pub(super) fn validate_remove_background_arguments(arguments: &Value) -> Result<(), String> {
+    validate_tool_object_fields(
+        arguments,
+        &[
+            "sourceLocalAssetId",
+            "assetName",
+            "backgroundMode",
+            "screenColor",
+        ],
+    )?;
    bounded_tool_string(arguments, "sourceLocalAssetId", 80)?;
    bounded_tool_string(
        arguments,
        "assetName",
        DIRECT_TOOLS_MCP_MAX_RESOURCE_NAME_CHARS,
    )?;
+    if let Some(mode) = arguments.get("backgroundMode") {
+        let mode = mode
+            .as_str()
+            .ok_or_else(|| "backgroundMode 必须是 complex 或 flat".to_string())?;
+        if mode != "complex" && mode != "flat" {
+            return Err("backgroundMode 必须是 complex 或 flat".to_string());
+        }
+    }
+    if let Some(color) = arguments.get("screenColor") {
+        let color = color
+            .as_str()
+            .ok_or_else(|| "screenColor 必须是 auto 或 #RRGGBB".to_string())?;
+        let valid_hex = color.len() == 7
+            && color.starts_with('#')
+            && color[1..]
+                .chars()
+                .all(|character| character.is_ascii_hexdigit());
+        if color != "auto" && !valid_hex {
+            return Err("screenColor 必须是 auto 或 #RRGGBB".to_string());
+        }
+        if arguments.get("backgroundMode").and_then(Value::as_str) != Some("flat") {
+            return Err("complex 模式不能传 screenColor".to_string());
+        }
+    }
    Ok(())
 }

@@ -1849,6 +1891,51 @@ pub(crate) fn stop_game_creator_external_mcp() -> Result<(), String> {
 mod tests {
    use super::*;

+    #[test]
+    fn remove_background_arguments_enforce_mode_color_contract() {
+        for fields in [
+            json!({}),
+            json!({"backgroundMode":"complex"}),
+            json!({"backgroundMode":"flat"}),
+            json!({"backgroundMode":"flat","screenColor":"auto"}),
+            json!({"backgroundMode":"flat","screenColor":"#Ab12EF"}),
+        ] {
+            let mut arguments = json!({"sourceLocalAssetId":"asset-1","assetName":"透明图"});
+            arguments
+                .as_object_mut()
+                .unwrap()
+                .extend(fields.as_object().unwrap().clone());
+            assert!(
+                validate_remove_background_arguments(&arguments).is_ok(),
+                "{fields}"
+            );
+        }
+        for fields in [
+            json!({"screenColor":"auto"}),
+            json!({"backgroundMode":"complex","screenColor":"auto"}),
+            json!({"backgroundMode":"flat","screenColor":""}),
+            json!({"backgroundMode":"flat","screenColor":" auto "}),
+            json!({"backgroundMode":"flat","screenColor":"AUTO"}),
+            json!({"backgroundMode":"flat","screenColor":"#GGGGGG"}),
+            json!({"backgroundMode":"flat","screenColor":null}),
+            json!({"backgroundMode":"flat","screenColor":12}),
+            json!({"backgroundMode":""}),
+            json!({"backgroundMode":"FLAT"}),
+            json!({"backgroundMode":" flat "}),
+            json!({"backgroundMode":null}),
+        ] {
+            let mut arguments = json!({"sourceLocalAssetId":"asset-1","assetName":"透明图"});
+            arguments
+                .as_object_mut()
+                .unwrap()
+                .extend(fields.as_object().unwrap().clone());
+            assert!(
+                validate_remove_background_arguments(&arguments).is_err(),
+                "{fields}"
+            );
+        }
+    }
+
    #[cfg(all(windows, feature = "cocos-editor-execute"))]
    #[test]
    fn builtin_mcp_process_probe() {
@@ -2,8 +2,9 @@ use super::*;

 pub(super) static GAME_CREATOR_AGENT_RUNTIME_UPDATE_APP_HANDLE: OnceLock<tauri::AppHandle> =
    OnceLock::new();
-pub(super) static GAME_CREATOR_MANIFEST_INVALIDATION_EVENT_SINK: OnceLock<
-    std::sync::Mutex<Option<GameCreatorManifestInvalidationEventSink>>,
+/// 同一 AppData 允许多个界面窗口同时挂载事件接收端，因此这里是按 token 去重的注册表。
+pub(super) static GAME_CREATOR_MANIFEST_INVALIDATION_EVENT_SINKS: OnceLock<
+    std::sync::Mutex<Vec<GameCreatorManifestInvalidationEventSink>>,
 > = OnceLock::new();
 #[cfg(test)]
 pub(super) static GAME_CREATOR_MANIFEST_INVALIDATION_EVENT_SINK_TEST_LOCK: std::sync::Mutex<()> =
@@ -293,8 +294,8 @@ pub(crate) use entrypoints::{
    configure_game_creator_manifest_invalidation_event_sink, emit_direct_game_creator_progress,
    emit_game_creator_agent_runtime_update, emit_game_creator_manifest_invalidated,
    game_creator_agent_runtime_update_event, generate_local_game_draft_at,
-    install_game_creator_manifest_invalidation_event_sink, read_game_creator_agent_runtime_at,
-    read_game_creator_agent_runtime_for_session_at, read_game_creator_agent_runtimes_at,
+    read_game_creator_agent_runtime_at, read_game_creator_agent_runtime_for_session_at,
+    read_game_creator_agent_runtimes_at, register_game_creator_manifest_invalidation_event_sink,
    set_game_creator_agent_runtime_update_app_handle,
    start_game_creator_manifest_invalidation_event_sink,
    validate_game_creator_manifest_invalidation_event_sink,
@@ -1,11 +1,12 @@
 use super::*;

 const GAME_CREATOR_MANIFEST_INVALIDATION_RELAY_MAX_BYTES: u64 = 64 * 1024;
+const GAME_CREATOR_MANIFEST_INVALIDATION_EVENT_SINK_MAX: usize = 16;

-fn lock_game_creator_manifest_invalidation_event_sink(
-) -> std::sync::MutexGuard<'static, Option<GameCreatorManifestInvalidationEventSink>> {
-    GAME_CREATOR_MANIFEST_INVALIDATION_EVENT_SINK
-        .get_or_init(|| Mutex::new(None))
+fn lock_game_creator_manifest_invalidation_event_sinks(
+) -> std::sync::MutexGuard<'static, Vec<GameCreatorManifestInvalidationEventSink>> {
+    GAME_CREATOR_MANIFEST_INVALIDATION_EVENT_SINKS
+        .get_or_init(|| Mutex::new(Vec::new()))
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner())
 }
@@ -219,7 +220,7 @@ pub(crate) fn configure_game_creator_manifest_invalidation_event_sink(
    token: &str,
 ) -> Result<(), String> {
    let sink = validate_game_creator_manifest_invalidation_event_sink(port, token)?;
-    install_game_creator_manifest_invalidation_event_sink(sink);
+    register_game_creator_manifest_invalidation_event_sink(sink);
    Ok(())
 }

@@ -240,10 +241,29 @@ pub(crate) fn validate_game_creator_manifest_invalidation_event_sink(
    })
 }

-pub(crate) fn install_game_creator_manifest_invalidation_event_sink(
+/// 登记一个界面窗口的事件接收端。
+///
+/// 同一窗口重复 attach 用同一个 token，按 token 覆盖旧登记；不同窗口各自持有
+/// 自己的 token，注册表按登记顺序保留，最多 `GAME_CREATOR_MANIFEST_INVALIDATION_EVENT_SINK_MAX` 个。
+pub(crate) fn register_game_creator_manifest_invalidation_event_sink(
    sink: GameCreatorManifestInvalidationEventSink,
 ) {
-    *lock_game_creator_manifest_invalidation_event_sink() = Some(sink);
+    let mut sinks = lock_game_creator_manifest_invalidation_event_sinks();
+    if let Some(existing) = sinks
+        .iter_mut()
+        .find(|existing| existing.token == sink.token)
+    {
+        *existing = sink;
+        return;
+    }
+    if sinks.len() >= GAME_CREATOR_MANIFEST_INVALIDATION_EVENT_SINK_MAX {
+        sinks.remove(0);
+    }
+    sinks.push(sink);
+}
+
+fn remove_game_creator_manifest_invalidation_event_sink(token: &str) {
+    lock_game_creator_manifest_invalidation_event_sinks().retain(|sink| sink.token != token);
 }

 #[cfg(test)]
@@ -258,14 +278,20 @@ impl GameCreatorManifestInvalidationEventSinkTestGuard {
    }

    pub(crate) fn configured_sink(&self) -> Option<GameCreatorManifestInvalidationEventSink> {
-        lock_game_creator_manifest_invalidation_event_sink().clone()
+        lock_game_creator_manifest_invalidation_event_sinks()
+            .first()
+            .cloned()
+    }
+
+    pub(crate) fn configured_sinks(&self) -> Vec<GameCreatorManifestInvalidationEventSink> {
+        lock_game_creator_manifest_invalidation_event_sinks().clone()
    }
 }

 #[cfg(test)]
 impl Drop for GameCreatorManifestInvalidationEventSinkTestGuard {
    fn drop(&mut self) {
-        *lock_game_creator_manifest_invalidation_event_sink() = None;
+        lock_game_creator_manifest_invalidation_event_sinks().clear();
    }
 }

@@ -281,16 +307,43 @@ pub(crate) fn acquire_game_creator_manifest_invalidation_event_sink_test_guard(
 }

 fn relay_game_creator_manifest_invalidation(root: &Path, agent_id: &str) -> Result<(), String> {
-    let sink = lock_game_creator_manifest_invalidation_event_sink().clone();
-    let Some(sink) = sink else {
+    let sinks = lock_game_creator_manifest_invalidation_event_sinks().clone();
+    if sinks.is_empty() {
        return Ok(());
+    }
+    let event = GameCreatorManifestInvalidatedEvent {
+        project_path: root.to_string_lossy().into_owned(),
+        agent_id: agent_id.to_string(),
    };
+    let mut failed_tokens = Vec::new();
+    let mut last_error = None;
+    for sink in &sinks {
+        match relay_game_creator_manifest_invalidation_to_sink(sink, &event) {
+            Ok(()) => {}
+            Err(error) => {
+                // 窗口已退出或接收端已释放时只淘汰该接收端，不能影响其它窗口。
+                failed_tokens.push(sink.token.clone());
+                last_error = Some(error);
+            }
+        }
+    }
+    if !failed_tokens.is_empty() {
+        lock_game_creator_manifest_invalidation_event_sinks()
+            .retain(|sink| !failed_tokens.contains(&sink.token));
+    }
+    match last_error {
+        Some(error) => Err(error),
+        None => Ok(()),
+    }
+}
+
+fn relay_game_creator_manifest_invalidation_to_sink(
+    sink: &GameCreatorManifestInvalidationEventSink,
+    event: &GameCreatorManifestInvalidatedEvent,
+) -> Result<(), String> {
    let envelope = GameCreatorManifestInvalidationRelayEnvelope {
-        token: sink.token,
-        event: GameCreatorManifestInvalidatedEvent {
-            project_path: root.to_string_lossy().into_owned(),
-            agent_id: agent_id.to_string(),
-        },
+        token: sink.token.clone(),
+        event: event.clone(),
    };
    let payload = serde_json::to_vec(&envelope)
        .map_err(|error| format!("序列化 manifest 失效事件失败：{error}"))?;
@@ -2219,6 +2219,8 @@ fn game_creator_gui_run_event_requests_runner_shutdown(event: &tauri::RunEvent)
 enum GameCreatorGuiRunnerShutdownOutcome {
    NotRequested,
    Requested,
+    /// 仍有其它界面窗口持有参与锁，Runner 必须保留给它们。
+    Retained,
    Failed(GameCreatorGuiRunnerShutdownFailure),
 }

@@ -2256,7 +2258,8 @@ fn classify_game_creator_gui_runner_shutdown_error(
        GameCreatorGuiRunnerShutdownFailure::ProcessIdentity
    } else if error.contains("当前平台不支持") || error.contains("macOS 不提供") {
        GameCreatorGuiRunnerShutdownFailure::PlatformUnsupported
-    } else if error.contains("实例锁") || error.contains("owner 锁") {
+    } else if error.contains("实例锁") || error.contains("参与锁") || error.contains("owner 锁")
+    {
        GameCreatorGuiRunnerShutdownFailure::LockTimeout
    } else if error.contains("endpoint") {
        GameCreatorGuiRunnerShutdownFailure::EndpointUnavailable
@@ -2272,13 +2275,14 @@ fn resolve_game_creator_gui_runner_shutdown<F>(
    shutdown: F,
 ) -> GameCreatorGuiRunnerShutdownOutcome
 where
-    F: FnOnce() -> Result<(), String>,
+    F: FnOnce() -> Result<bool, String>,
 {
    if !game_creator_gui_run_event_requests_runner_shutdown(event) {
        return GameCreatorGuiRunnerShutdownOutcome::NotRequested;
    }
    match shutdown() {
-        Ok(()) => GameCreatorGuiRunnerShutdownOutcome::Requested,
+        Ok(true) => GameCreatorGuiRunnerShutdownOutcome::Requested,
+        Ok(false) => GameCreatorGuiRunnerShutdownOutcome::Retained,
        Err(error) => GameCreatorGuiRunnerShutdownOutcome::Failed(
            classify_game_creator_gui_runner_shutdown_error(&error),
        ),
@@ -2298,11 +2302,17 @@ fn handle_game_creator_gui_run_event(event: &tauri::RunEvent) {
            app_log!("agent.direct_codex.gui_exit.shutdown_failed: {error}");
        }
    }
-    match resolve_game_creator_gui_runner_shutdown(event, shutdown_external_agent_runner) {
+    match resolve_game_creator_gui_runner_shutdown(
+        event,
+        shutdown_external_agent_runner_for_gui_exit,
+    ) {
        GameCreatorGuiRunnerShutdownOutcome::NotRequested => {}
        GameCreatorGuiRunnerShutdownOutcome::Requested => {
            app_log!("agent.runner.gui_exit.shutdown_requested")
        }
+        GameCreatorGuiRunnerShutdownOutcome::Retained => {
+            app_log!("agent.runner.gui_exit.retained_for_other_windows")
+        }
        GameCreatorGuiRunnerShutdownOutcome::Failed(failure) => {
            app_log!("agent.runner.gui_exit.shutdown_failed.{}", failure.code())
        }
@@ -2611,27 +2621,25 @@ fn main() {
                    )
                })?;
            setup_log.append("startup.runner.configure.complete");
-            let gui_owner_lock = acquire_external_agent_runner_gui_owner_lock(&config_dir)
+            hold_external_agent_runner_gui_participant_lock(&config_dir)
                .inspect_err(|error| {
                    let details = sanitize_diagnostic_message(error, Some(config_dir.as_path()));
                    setup_log.fail(&format!(
-                        "startup.runner.owner-lock.failed details={details}"
+                        "startup.runner.participant-lock.failed details={details}"
                    ));
                })
                .map_err(|error| {
                    std::io::Error::new(
                        std::io::ErrorKind::AlreadyExists,
-                        format!("获取 GUI owner 锁失败：{error}"),
+                        format!("建立 AGC 界面参与锁失败：{error}"),
                    )
                })?;
-            let gui_owner_epoch = gui_owner_lock.owner_epoch().to_string();
-            app.manage(gui_owner_lock);
            setup_log.append("startup.runner.start.begin");
            set_game_creator_agent_runtime_update_app_handle(app.handle().clone());
            set_direct_thread_manager_app_handle(app.handle().clone());
            let manifest_event_sink =
                start_game_creator_manifest_invalidation_event_sink(app.handle().clone())?;
-            attach_external_agent_runner_gui_owner(&manifest_event_sink, &gui_owner_epoch)
+            attach_external_agent_runner_gui_owner(&manifest_event_sink)
                .inspect_err(|error| {
                    let details = sanitize_diagnostic_message(error, Some(config_dir.as_path()));
                    setup_log.fail(&format!(
@@ -12,21 +12,20 @@ pub(crate) use client::{
    clear_external_agent_runner_platform_session, compact_external_agent_runner_context,
    configure_external_agent_runner, configure_external_agent_runner_read_only,
    continue_external_agent_runner_action, ensure_external_agent_runner_started,
-    ensure_external_agent_runner_started_for_gui, install_external_agent_runner_platform_session,
+    ensure_external_agent_runner_started_for_gui, hold_external_agent_runner_gui_participant_lock,
+    install_external_agent_runner_platform_session,
    interrupt_external_agent_runner_provider_for_steer_decision, notify_external_agent_runner,
    pause_external_agent_runner, read_external_agent_runner_status,
    require_external_agent_runner_configured_for_cli_runtime_write,
    require_external_agent_runner_for_cli_runtime_write, resume_external_agent_runner,
    shutdown_external_agent_runner, shutdown_external_agent_runner_for_client_exit,
-    shutdown_external_agent_runner_if_idle, steer_external_agent_runner,
-    wake_external_agent_runner_pending, wake_external_agent_runner_pending_for_run,
+    shutdown_external_agent_runner_for_gui_exit, shutdown_external_agent_runner_if_idle,
+    steer_external_agent_runner, wake_external_agent_runner_pending,
+    wake_external_agent_runner_pending_for_run,
 };
 #[cfg(windows)]
 pub(crate) use endpoint::validate_windows_regular_file_handle;
-pub(crate) use endpoint::{
-    acquire_external_agent_runner_gui_owner_lock, external_agent_runner_enabled,
-    external_agent_runner_is_server_process,
-};
+pub(crate) use endpoint::{external_agent_runner_enabled, external_agent_runner_is_server_process};
 #[allow(unused_imports)]
 pub(crate) use protocol::{ExternalAgentRunnerStatus, EXTERNAL_AGENT_RUNNER_PROTOCOL_VERSION};
 pub(crate) use server::{
@@ -25,35 +25,76 @@ pub(super) struct ExternalAgentRunnerGuiOwnerAttachmentState {

 struct ExternalAgentRunnerGuiOwnerRegistration {
    generation: u64,
+    claim_mode: ExternalAgentRunnerGuiOwnerClaimMode,
    config_dir: PathBuf,
    params: ExternalAgentRunnerRequestParams,
    attached_boot_id: Option<String>,
 }

+/// claim 解析模式。
+///
+/// `Adopt` 用于窗口启动：沿用现有 durable claim，只有 claim 缺失或不可读时才发布。
+/// `Publish` 用于本窗口改动了平台登录态：发布新 epoch，成为新的登录态权威。
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) enum ExternalAgentRunnerGuiOwnerClaimMode {
+    Adopt,
+    Publish,
+}
+
 static EXTERNAL_AGENT_RUNNER_GUI_OWNER_ATTACHMENT_STATE: OnceLock<
    Mutex<ExternalAgentRunnerGuiOwnerAttachmentState>,
 > = OnceLock::new();

+static EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK: OnceLock<
+    Mutex<Option<ExternalAgentRunnerGuiParticipantLock>>,
+> = OnceLock::new();
+
 fn external_agent_runner_gui_owner_attachment_state(
 ) -> &'static Mutex<ExternalAgentRunnerGuiOwnerAttachmentState> {
    EXTERNAL_AGENT_RUNNER_GUI_OWNER_ATTACHMENT_STATE
        .get_or_init(|| Mutex::new(ExternalAgentRunnerGuiOwnerAttachmentState::default()))
 }

+fn external_agent_runner_gui_participant_lock(
+) -> &'static Mutex<Option<ExternalAgentRunnerGuiParticipantLock>> {
+    EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK.get_or_init(|| Mutex::new(None))
+}
+
+/// 取得并持有本窗口的界面参与锁，直到窗口退出。
+///
+/// 参与锁是共享句柄锁：同一 AppData 的多个窗口可以同时持有，Runner 用独占探测
+/// 判断是否仍有窗口存活，因此这个锁同时也是“Runner 不能先退出”的存活凭据。
+pub(crate) fn hold_external_agent_runner_gui_participant_lock(
+    config_dir: &Path,
+) -> Result<(), String> {
+    let lock = acquire_external_agent_runner_gui_participant_lock(config_dir)?;
+    *lock_unpoisoned(external_agent_runner_gui_participant_lock()) = Some(lock);
+    Ok(())
+}
+
+fn release_external_agent_runner_gui_participant_lock() {
+    drop(lock_unpoisoned(external_agent_runner_gui_participant_lock()).take());
+}
+
+/// 登记本窗口的 owner claim 与 attach 参数。
+///
+/// 这里不做 claim 文件 IO：claim 由调用方按 `claim_mode` 解析后写进 `params`，
+/// 因此该函数可以在没有真实 AppData 的单元测试里使用。
 pub(super) fn register_external_agent_runner_gui_owner_attachment(
    state: &Mutex<ExternalAgentRunnerGuiOwnerAttachmentState>,
    config_dir: &Path,
+    claim_mode: ExternalAgentRunnerGuiOwnerClaimMode,
    mut params: ExternalAgentRunnerRequestParams,
 ) -> Result<(), String> {
    let mut state = lock_unpoisoned(state);
    state.generation = state.generation.wrapping_add(1);
    let generation = state.generation;
-    params.gui_owner_session_revision = Some(generation);
-    if let Some(owner_epoch) = params.gui_owner_epoch.as_deref() {
-        write_external_agent_runner_gui_owner_claim_atomic(config_dir, owner_epoch, generation)?;
+    if params.gui_owner_session_revision.is_none() {
+        params.gui_owner_session_revision = Some(generation);
    }
    state.registration = Some(ExternalAgentRunnerGuiOwnerRegistration {
        generation,
+        claim_mode,
        config_dir: config_dir.to_path_buf(),
        params,
        attached_boot_id: None,
@@ -61,6 +102,29 @@ pub(super) fn register_external_agent_runner_gui_owner_attachment(
    Ok(())
 }

+pub(super) fn reserve_external_agent_runner_gui_owner_claim_revision(
+    state: &Mutex<ExternalAgentRunnerGuiOwnerAttachmentState>,
+) -> u64 {
+    let mut state = lock_unpoisoned(state);
+    state.generation = state.generation.wrapping_add(1);
+    state.generation
+}
+
+pub(super) fn resolve_external_agent_runner_gui_owner_claim(
+    config_dir: &Path,
+    claim_mode: ExternalAgentRunnerGuiOwnerClaimMode,
+    session_revision: u64,
+) -> Result<ExternalAgentRunnerGuiOwnerClaim, String> {
+    match claim_mode {
+        ExternalAgentRunnerGuiOwnerClaimMode::Adopt => {
+            adopt_or_publish_external_agent_runner_gui_owner_claim(config_dir, session_revision)
+        }
+        ExternalAgentRunnerGuiOwnerClaimMode::Publish => {
+            publish_external_agent_runner_gui_owner_claim(config_dir, session_revision)
+        }
+    }
+}
+
 pub(super) fn attach_registered_external_agent_runner_gui_owner_if_needed_with<F>(
    state: &Mutex<ExternalAgentRunnerGuiOwnerAttachmentState>,
    config_dir: &Path,
@@ -68,27 +132,72 @@ pub(super) fn attach_registered_external_agent_runner_gui_owner_if_needed_with<F
    attach: F,
 ) -> Result<(), String>
 where
-    F: FnOnce(&ExternalAgentRunnerEndpoint, ExternalAgentRunnerRequestParams) -> Result<(), String>,
+    F: Fn(&ExternalAgentRunnerEndpoint, ExternalAgentRunnerRequestParams) -> Result<(), String>,
 {
-    let Some((generation, params)) = ({
-        let state = lock_unpoisoned(state);
-        state.registration.as_ref().and_then(|registration| {
-            (registration.config_dir == config_dir
-                && registration.attached_boot_id.as_deref() != Some(endpoint.boot_id.as_str()))
-            .then(|| (registration.generation, registration.params.clone()))
-        })
-    }) else {
-        return Ok(());
-    };
+    const ATTACH_CLAIM_RETRY_LIMIT: usize = 3;
+    let mut last_claim_error = None;
+    for attempt in 0..ATTACH_CLAIM_RETRY_LIMIT {
+        let Some((generation, params, claim_mode)) = ({
+            let state = lock_unpoisoned(state);
+            state.registration.as_ref().and_then(|registration| {
+                (registration.config_dir == config_dir
+                    && registration.attached_boot_id.as_deref() != Some(endpoint.boot_id.as_str()))
+                .then(|| {
+                    (
+                        registration.generation,
+                        registration.params.clone(),
+                        registration.claim_mode,
+                    )
+                })
+            })
+        }) else {
+            return Ok(());
+        };

-    attach(endpoint, params)?;
-
-    let mut state = lock_unpoisoned(state);
-    if let Some(registration) = state.registration.as_mut() {
-        if registration.generation == generation && registration.config_dir == config_dir {
-            registration.attached_boot_id = Some(endpoint.boot_id.clone());
+        match attach(endpoint, params) {
+            Ok(()) => {
+                let mut state = lock_unpoisoned(state);
+                if let Some(registration) = state.registration.as_mut() {
+                    if registration.generation == generation
+                        && registration.config_dir == config_dir
+                    {
+                        registration.attached_boot_id = Some(endpoint.boot_id.clone());
+                    }
+                }
+                return Ok(());
+            }
+            Err(error) if attempt + 1 < ATTACH_CLAIM_RETRY_LIMIT && error.contains("claim") => {
+                // 另一个窗口在本次 attach 前后发布了新 claim：按最新 claim 重新解析后重试。
+                last_claim_error = Some(error);
+                refresh_registered_external_agent_runner_gui_owner_claim(
+                    state, config_dir, claim_mode,
+                )?;
+            }
+            Err(error) => return Err(error),
        }
    }
+    Err(last_claim_error.unwrap_or_else(|| "Agent Runner attach 重试后仍然失败".to_string()))
+}
+
+fn refresh_registered_external_agent_runner_gui_owner_claim(
+    state: &Mutex<ExternalAgentRunnerGuiOwnerAttachmentState>,
+    config_dir: &Path,
+    claim_mode: ExternalAgentRunnerGuiOwnerClaimMode,
+) -> Result<(), String> {
+    let session_revision = reserve_external_agent_runner_gui_owner_claim_revision(state);
+    let claim =
+        resolve_external_agent_runner_gui_owner_claim(config_dir, claim_mode, session_revision)?;
+    let mut state = lock_unpoisoned(state);
+    let Some(registration) = state.registration.as_mut() else {
+        return Ok(());
+    };
+    if registration.config_dir != config_dir {
+        return Ok(());
+    }
+    registration.claim_mode = claim_mode;
+    registration.params.gui_owner_epoch = Some(claim.owner_epoch);
+    registration.params.gui_owner_session_revision = Some(claim.session_revision);
+    registration.attached_boot_id = None;
    Ok(())
 }

@@ -963,7 +1072,6 @@ pub(crate) fn shutdown_external_agent_runner() -> Result<(), String> {

 pub(crate) fn attach_external_agent_runner_gui_owner(
    event_sink: &GameCreatorManifestInvalidationEventSink,
-    gui_owner_epoch: &str,
 ) -> Result<(), String> {
    EXTERNAL_AGENT_RUNNER_GUI_OWNER_REQUIRED_CLIENT
        .store(true, std::sync::atomic::Ordering::Release);
@@ -971,13 +1079,25 @@ pub(crate) fn attach_external_agent_runner_gui_owner(
    let config_dir = external_agent_runner_config_dir()
        .ok_or_else(|| "外部 Agent Runner 尚未配置 AppData；请显式传入 --config-dir".to_string())?;
    let platform_session = crate::current_platform_session();
+    // 启动阶段先采纳现有 durable claim：第二个及后续窗口与第一个窗口共享同一
+    // epoch，因此不会被判定为抢走登录态权威；claim 缺失或不可读时才发布新 claim。
+    let session_revision = reserve_external_agent_runner_gui_owner_claim_revision(
+        external_agent_runner_gui_owner_attachment_state(),
+    );
+    let claim = resolve_external_agent_runner_gui_owner_claim(
+        &config_dir,
+        ExternalAgentRunnerGuiOwnerClaimMode::Adopt,
+        session_revision,
+    )?;
    register_external_agent_runner_gui_owner_attachment(
        external_agent_runner_gui_owner_attachment_state(),
        &config_dir,
+        ExternalAgentRunnerGuiOwnerClaimMode::Adopt,
        ExternalAgentRunnerRequestParams {
            event_sink_port: Some(event_sink.port),
            event_sink_token: Some(event_sink.token.clone()),
-            gui_owner_epoch: Some(gui_owner_epoch.to_string()),
+            gui_owner_epoch: Some(claim.owner_epoch),
+            gui_owner_session_revision: Some(claim.session_revision),
            platform_user_id: platform_session
                .as_ref()
                .map(|session| session.user_id.clone()),
@@ -1122,7 +1242,7 @@ pub(super) fn remember_external_agent_runner_platform_session(
        session,
        identity_generation,
        revision,
-        write_external_agent_runner_gui_owner_claim_atomic,
+        publish_external_agent_runner_gui_owner_claim,
    )
 }

@@ -1131,7 +1251,7 @@ pub(super) fn remember_external_agent_runner_platform_session_with(
    session: Option<(&str, &str, &str)>,
    identity_generation: u64,
    revision: u64,
-    write_claim: impl FnOnce(&Path, &str, u64) -> Result<(), String>,
+    publish_claim: impl FnOnce(&Path, u64) -> Result<ExternalAgentRunnerGuiOwnerClaim, String>,
 ) -> Result<(), String> {
    let mut state = lock_unpoisoned(state);
    let Some(registration) = state.registration.as_ref() else {
@@ -1167,21 +1287,23 @@ pub(super) fn remember_external_agent_runner_platform_session_with(
    }
    state.generation = state.generation.wrapping_add(1);
    let registration_generation = state.generation;
-    let claim = state.registration.as_ref().and_then(|registration| {
-        registration
-            .params
-            .gui_owner_epoch
-            .as_deref()
-            .map(|owner_epoch| (registration.config_dir.clone(), owner_epoch.to_string()))
-    });
-    if let Some((config_dir, owner_epoch)) = claim {
-        write_claim(&config_dir, &owner_epoch, registration_generation)?;
-    }
+    // 本窗口改动了平台登录态：发布新 epoch 的 claim，成为新的登录态权威。
+    // 并发发布以最后一次成功写入为准，落败窗口在 attach 阶段按最新 claim 重试。
+    // 只有已经建立过 claim 的登记才需要发布：没有 epoch 的登记（纯 CLI / 单元测试替身）
+    // 不写任何 claim 文件。
+    let published_claim = state
+        .registration
+        .as_ref()
+        .filter(|registration| registration.params.gui_owner_epoch.is_some())
+        .map(|registration| registration.config_dir.clone())
+        .map(|config_dir| publish_claim(&config_dir, registration_generation))
+        .transpose()?;
    let registration = state
        .registration
        .as_mut()
        .expect("checked GUI owner registration must remain present while locked");
    registration.generation = registration_generation;
+    registration.claim_mode = ExternalAgentRunnerGuiOwnerClaimMode::Publish;
    registration.attached_boot_id = None;
    registration.params.platform_user_id = session.map(|(user_id, _, _)| user_id.to_string());
    registration.params.platform_access_token =
@@ -1190,7 +1312,10 @@ pub(super) fn remember_external_agent_runner_platform_session_with(
        session.map(|(_, _, api_base_url)| api_base_url.to_string());
    registration.params.platform_auth_generation = Some(identity_generation);
    registration.params.platform_auth_revision = Some(revision);
-    registration.params.gui_owner_session_revision = Some(registration_generation);
+    if let Some(claim) = published_claim {
+        registration.params.gui_owner_epoch = Some(claim.owner_epoch);
+        registration.params.gui_owner_session_revision = Some(claim.session_revision);
+    }
    Ok(())
 }

@@ -1284,6 +1409,25 @@ pub(crate) fn shutdown_external_agent_runner_for_client_exit() -> Result<bool, S
    shutdown_external_agent_runner_for_client_exit_at(&config_dir)
 }

+/// 窗口退出的收尾：先释放本窗口参与锁，再决定 Runner 是否需要关闭。
+///
+/// 返回 `Ok(false)` 表示仍检测到其它窗口持有参与锁，Runner 必须保留给它们；
+/// 返回 `Ok(true)` 表示本窗口是最后一个界面进程，Runner 已请求关闭。
+pub(crate) fn shutdown_external_agent_runner_for_gui_exit() -> Result<bool, String> {
+    let _configure = lock_unpoisoned(external_agent_runner_configure_lock());
+    let Some(config_dir) = external_agent_runner_config_dir() else {
+        return Ok(true);
+    };
+    release_external_agent_runner_gui_participant_lock();
+    if external_agent_runner_lock_is_held(&external_agent_runner_gui_participant_lock_path(
+        &config_dir,
+    ))? {
+        return Ok(false);
+    }
+    shutdown_external_agent_runner_at(&config_dir)?;
+    Ok(true)
+}
+
 pub(super) fn wait_for_external_agent_runner(
    config_dir: &Path,
    child: &mut Child,
@@ -1322,34 +1466,12 @@ pub(super) fn ensure_external_agent_runner(
 ) -> Result<ExternalAgentRunnerEndpoint, String> {
    let endpoint_path = external_agent_runner_endpoint_path(config_dir);
    let executable_fingerprint = current_external_agent_runner_executable_fingerprint()?;
-    if let Ok(endpoint) = read_external_agent_runner_endpoint(&endpoint_path) {
-        match external_agent_runner_endpoint_reuse_decision(&endpoint, &executable_fingerprint) {
-            ExternalAgentRunnerReuseDecision::Reuse => {
-                if ping_external_agent_runner(&endpoint).is_ok() {
-                    attach_registered_external_agent_runner_gui_owner_if_needed(
-                        config_dir, &endpoint,
-                    )?;
-                    return Ok(endpoint);
-                }
-            }
-            ExternalAgentRunnerReuseDecision::Retire => {
-                let incompatible_ping = send_external_agent_runner_request_with_protocol_and_id(
-                    &endpoint,
-                    endpoint.protocol_version,
-                    random_identifier(b"genarrative-agent-runner-upgrade-ping-id")?,
-                    "runner.ping",
-                    ExternalAgentRunnerRequestParams::default(),
-                );
-                if incompatible_ping.is_ok() {
-                    retire_incompatible_external_agent_runner(
-                        &endpoint_path,
-                        &endpoint,
-                        EXTERNAL_AGENT_RUNNER_GUI_OWNER_REQUIRED_CLIENT
-                            .load(std::sync::atomic::Ordering::Acquire),
-                    )?;
-                }
-            }
-        }
+    if let Some(endpoint) = reuse_or_retire_external_agent_runner_endpoint(
+        config_dir,
+        &endpoint_path,
+        &executable_fingerprint,
+    )? {
+        return Ok(endpoint);
    }
    let mut launched = launch_external_agent_runner(config_dir)?;
    match wait_for_external_agent_runner(config_dir, &mut launched.child, &executable_fingerprint) {
@@ -1366,11 +1488,57 @@ pub(super) fn ensure_external_agent_runner(
        Err(error) => {
            let _ = launched.child.kill();
            let _ = launched.child.wait();
+            // 同一 AppData 的另一个窗口可能在这段时间里已经启动了 Runner：
+            // 实例锁竞争失败不能立刻报成启动失败，先按最新 endpoint 复用一次。
+            if let Some(endpoint) = reuse_or_retire_external_agent_runner_endpoint(
+                config_dir,
+                &endpoint_path,
+                &executable_fingerprint,
+            )? {
+                return Ok(endpoint);
+            }
            Err(error)
        }
    }
 }

+fn reuse_or_retire_external_agent_runner_endpoint(
+    config_dir: &Path,
+    endpoint_path: &Path,
+    executable_fingerprint: &str,
+) -> Result<Option<ExternalAgentRunnerEndpoint>, String> {
+    if let Ok(endpoint) = read_external_agent_runner_endpoint(&endpoint_path) {
+        match external_agent_runner_endpoint_reuse_decision(&endpoint, executable_fingerprint) {
+            ExternalAgentRunnerReuseDecision::Reuse => {
+                if ping_external_agent_runner(&endpoint).is_ok() {
+                    attach_registered_external_agent_runner_gui_owner_if_needed(
+                        config_dir, &endpoint,
+                    )?;
+                    return Ok(Some(endpoint));
+                }
+            }
+            ExternalAgentRunnerReuseDecision::Retire => {
+                let incompatible_ping = send_external_agent_runner_request_with_protocol_and_id(
+                    &endpoint,
+                    endpoint.protocol_version,
+                    random_identifier(b"genarrative-agent-runner-upgrade-ping-id")?,
+                    "runner.ping",
+                    ExternalAgentRunnerRequestParams::default(),
+                );
+                if incompatible_ping.is_ok() {
+                    retire_incompatible_external_agent_runner(
+                        endpoint_path,
+                        &endpoint,
+                        EXTERNAL_AGENT_RUNNER_GUI_OWNER_REQUIRED_CLIENT
+                            .load(std::sync::atomic::Ordering::Acquire),
+                    )?;
+                }
+            }
+        }
+    }
+    Ok(None)
+}
+
 pub(crate) fn configure_external_agent_runner(config_dir: impl AsRef<Path>) -> Result<(), String> {
    let _configure = lock_unpoisoned(external_agent_runner_configure_lock());
    let config_dir = normalize_external_agent_runner_config_dir(config_dir.as_ref())?;
@@ -1,6 +1,6 @@
 use super::{endpoint::*, project_owner::*, protocol::*, state::*};
 use crate::{
-    install_game_creator_manifest_invalidation_event_sink,
+    register_game_creator_manifest_invalidation_event_sink,
    validate_game_creator_manifest_invalidation_event_sink,
 };
 use serde::Deserialize;
@@ -116,9 +116,9 @@ fn apply_external_agent_runner_gui_owner_attachment(
        .gui_owner_session_revision
        .ok_or_else(|| "Agent Runner GUI owner 缺少 session revision".to_string())?;
    let config_dir = state
-        .gui_owner_lock_path
+        .gui_participant_lock_path
        .parent()
-        .ok_or_else(|| "Agent Runner GUI owner 锁缺少 AppData 父目录".to_string())?;
+        .ok_or_else(|| "AGC 界面参与锁缺少 AppData 父目录".to_string())?;
    let mut active_claim = lock_unpoisoned(&state.gui_owner_platform_session_claim);
    let durable_claim = read_external_agent_runner_gui_owner_claim(config_dir)?;
    if durable_claim.owner_epoch != requested_epoch
@@ -127,7 +127,14 @@ fn apply_external_agent_runner_gui_owner_attachment(
        return Err("Agent Runner GUI owner claim 已过期".to_string());
    }
    let requested_claim = (requested_epoch.to_string(), requested_revision);
-    let replace_claim = active_claim.as_ref() != Some(&requested_claim);
+    // 同一 AppData 的多个窗口共享同一个 epoch：只有 epoch 变化（本窗口发布了新的
+    // 登录态权威）才允许强制替换会话。同一 epoch 内的重复 attach 只做单调校验，
+    // 因此后开窗口的“无登录态 attach”不会清空已有会话。
+    let epoch_changed = match active_claim.as_ref() {
+        Some(active) => active.0 != requested_epoch,
+        None => true,
+    };
+    let replace_claim = epoch_changed;
    let result = match (
        params.platform_user_id.as_deref(),
        params.platform_access_token.as_deref(),
@@ -168,7 +175,7 @@ fn apply_external_agent_runner_gui_owner_attachment(
                crate::clear_platform_session_checked(identity_generation, revision)
            }
        }
-        (None, None, None, None, None) if replace_claim => {
+        (None, None, None, None, None) if epoch_changed => {
            crate::clear_platform_session_for_gui_owner(0, 0);
            Ok(())
        }
@@ -194,7 +201,7 @@ fn apply_external_agent_runner_gui_owner_attachment(
        return Err("Agent Runner GUI owner claim 在 attach 提交期间已变化".to_string());
    }
    if let Some(event_sink) = event_sink {
-        install_game_creator_manifest_invalidation_event_sink(event_sink);
+        register_game_creator_manifest_invalidation_event_sink(event_sink);
    }
    *active_claim = Some(requested_claim);
    Ok(())
@@ -204,9 +211,9 @@ pub(super) fn validate_external_agent_runner_gui_owner_claim_current(
    state: &ExternalAgentRunnerServerState,
 ) -> Result<(), String> {
    let config_dir = state
-        .gui_owner_lock_path
+        .gui_participant_lock_path
        .parent()
-        .ok_or_else(|| "Agent Runner GUI owner 锁缺少 AppData 父目录".to_string())?;
+        .ok_or_else(|| "AGC 界面参与锁缺少 AppData 父目录".to_string())?;
    let mut active_claim = lock_unpoisoned(&state.gui_owner_platform_session_claim);
    let durable_claim = read_external_agent_runner_gui_owner_claim(config_dir);
    let matches = durable_claim.as_ref().is_ok_and(|claim| {
@@ -777,7 +784,7 @@ pub(super) fn dispatch_external_agent_runner_runtime_request_with_owner_claim(
            }
        }
        "runner.attach_gui_owner" => {
-            match external_agent_runner_gui_owner_is_locked(&state.gui_owner_lock_path) {
+            match external_agent_runner_lock_is_held(&state.gui_participant_lock_path) {
                Ok(true) => {
                    let event_sink = request
                        .params
@@ -819,7 +826,7 @@ pub(super) fn dispatch_external_agent_runner_runtime_request_with_owner_claim(
                Ok(false) => ExternalAgentRunnerResponse::failure(
                    &request.request_id,
                    "gui-owner-missing",
-                    "Agent Runner 未检测到活跃 GUI owner 锁",
+                    "Agent Runner 未检测到活跃的 AGC 界面进程",
                ),
                Err(error) => ExternalAgentRunnerResponse::failure(
                    &request.request_id,
@@ -6,7 +6,12 @@ use std::io::{self, Read, Seek, SeekFrom, Write};
 use std::path::{Path, PathBuf};
 use std::sync::atomic::Ordering;
 use std::sync::Mutex;
-use std::time::{SystemTime, UNIX_EPOCH};
+use std::thread;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+const EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK_ACQUIRE_TIMEOUT: Duration = Duration::from_secs(5);
+const EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK_RETRY_INTERVAL: Duration =
+    Duration::from_millis(40);

 pub(super) fn external_agent_runner_config_dir_lock() -> &'static Mutex<Option<PathBuf>> {
    EXTERNAL_AGENT_RUNNER_CONFIG_DIR.get_or_init(|| Mutex::new(None))
@@ -305,8 +310,8 @@ pub(super) fn external_agent_runner_lock_path(config_dir: &Path) -> PathBuf {
    config_dir.join(EXTERNAL_AGENT_RUNNER_LOCK_FILE_NAME)
 }

-pub(super) fn external_agent_runner_gui_owner_lock_path(config_dir: &Path) -> PathBuf {
-    config_dir.join(EXTERNAL_AGENT_RUNNER_GUI_OWNER_LOCK_FILE_NAME)
+pub(super) fn external_agent_runner_gui_participant_lock_path(config_dir: &Path) -> PathBuf {
+    config_dir.join(EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK_FILE_NAME)
 }

 pub(super) fn external_agent_runner_gui_owner_claim_path(config_dir: &Path) -> PathBuf {
@@ -341,8 +346,9 @@ pub(super) fn read_external_agent_runner_gui_owner_claim(
    Ok(claim)
 }

-pub(super) fn external_agent_runner_gui_owner_is_locked(path: &Path) -> Result<bool, String> {
-    match try_open_external_agent_runner_lock(path, "Agent Runner GUI owner 锁")? {
+/// 独占探测：返回 `true` 表示仍有界面进程持有该参与锁。
+pub(super) fn external_agent_runner_lock_is_held(path: &Path) -> Result<bool, String> {
+    match try_open_external_agent_runner_lock(path, "AGC 界面参与锁")? {
        Some(lock) => {
            drop(lock);
            Ok(false)
@@ -743,10 +749,21 @@ pub(super) fn read_current_external_agent_runner_endpoint(
        })
 }

+/// 锁文件的两种打开方式。
+///
+/// `Exclusive` 是权威探测：能否独占取得句柄决定“还有没有存活持有者”。
+/// `Shared` 是参与者持有：同一 AppData 的多个界面进程可以同时持有。
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) enum ExternalAgentRunnerLockMode {
+    Exclusive,
+    Shared,
+}
+
 #[cfg(unix)]
-pub(super) fn try_open_external_agent_runner_lock(
+pub(super) fn open_external_agent_runner_lock_file(
    path: &Path,
    label: &str,
+    mode: ExternalAgentRunnerLockMode,
 ) -> Result<Option<File>, String> {
    use std::os::fd::AsRawFd;
    use std::os::unix::fs::{MetadataExt, OpenOptionsExt, PermissionsExt};
@@ -809,14 +826,30 @@ pub(super) fn try_open_external_agent_runner_lock(
            path.display()
        ));
    }
+    let flock_operation = match mode {
+        ExternalAgentRunnerLockMode::Exclusive => libc::LOCK_EX | libc::LOCK_NB,
+        ExternalAgentRunnerLockMode::Shared => libc::LOCK_SH | libc::LOCK_NB,
+    };
    // SAFETY: flock only observes the valid fd owned by `file`; `file` remains alive on success.
-    let result = unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) };
+    let result = unsafe { libc::flock(file.as_raw_fd(), flock_operation) };
    if result == 0 {
        return Ok(Some(file));
    }
    let error = io::Error::last_os_error();
    if error.kind() == io::ErrorKind::WouldBlock {
-        Ok(None)
+        return match mode {
+            ExternalAgentRunnerLockMode::Exclusive => Ok(None),
+            ExternalAgentRunnerLockMode::Shared => Err(format!(
+                "{label} 正被独占探测或持有，稍后重试：{}",
+                path.display()
+            )),
+        };
+    }
+    if mode == ExternalAgentRunnerLockMode::Shared {
+        Err(format!(
+            "以共享方式获取 {label} 失败：{}: {error}",
+            path.display()
+        ))
    } else {
        Err(format!(
            "获取 {label} 系统锁失败：{}: {error}",
@@ -825,39 +858,58 @@ pub(super) fn try_open_external_agent_runner_lock(
    }
 }

+#[cfg(unix)]
+pub(super) fn try_open_external_agent_runner_lock(
+    path: &Path,
+    label: &str,
+) -> Result<Option<File>, String> {
+    open_external_agent_runner_lock_file(path, label, ExternalAgentRunnerLockMode::Exclusive)
+}
+
 #[cfg(windows)]
 pub(super) fn windows_external_agent_runner_lock_is_busy_error(error: &io::Error) -> bool {
    matches!(error.raw_os_error(), Some(32 | 33))
 }

 #[cfg(windows)]
-pub(super) fn try_open_external_agent_runner_lock(
+pub(super) fn open_external_agent_runner_lock_file(
    path: &Path,
    label: &str,
+    mode: ExternalAgentRunnerLockMode,
 ) -> Result<Option<File>, String> {
    use std::os::windows::fs::OpenOptionsExt;

    const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;
+    const FILE_SHARE_READ: u32 = 0x0000_0001;
+    const FILE_SHARE_WRITE: u32 = 0x0000_0002;
+    const FILE_SHARE_DELETE: u32 = 0x0000_0004;

    let parent = path
        .parent()
        .ok_or_else(|| format!("{label} 缺少 AppData 父目录：{}", path.display()))?;
    let private_parent = crate::inspect_game_creator_runtime_config_dir(parent)?;
    let runner_lock_path = private_parent.join(EXTERNAL_AGENT_RUNNER_LOCK_FILE_NAME);
-    let gui_owner_lock_path = private_parent.join(EXTERNAL_AGENT_RUNNER_GUI_OWNER_LOCK_FILE_NAME);
-    if path != runner_lock_path && path != gui_owner_lock_path {
+    let gui_participant_lock_path =
+        private_parent.join(EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK_FILE_NAME);
+    if path != runner_lock_path && path != gui_participant_lock_path {
        return Err(format!(
            "{label} 必须位于已验证的私有 AppData 固定锁路径：{} 或 {}",
            runner_lock_path.display(),
-            gui_owner_lock_path.display()
+            gui_participant_lock_path.display()
        ));
    }

+    let share_mode = match mode {
+        ExternalAgentRunnerLockMode::Exclusive => 0,
+        ExternalAgentRunnerLockMode::Shared => {
+            FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE
+        }
+    };
    match OpenOptions::new()
        .create(true)
        .read(true)
        .write(true)
-        .share_mode(0)
+        .share_mode(share_mode)
        .custom_flags(FILE_FLAG_OPEN_REPARSE_POINT)
        .open(path)
    {
@@ -875,16 +927,30 @@ pub(super) fn try_open_external_agent_runner_lock(
                ));
            }
            validate_windows_regular_file_handle(&file, label)?;
-            // share_mode(0) gives this process an exclusive handle. At this point the fixed
-            // lock path is known to be a stale, single-link, non-reparse regular file inside
-            // the current TokenUser's private AppData. Repairing its owner is therefore safe
-            // and is required when Windows creates it with TokenOwner=Administrators.
+            // The fixed lock path is known to be a single-link, non-reparse regular file
+            // inside the current TokenUser's private AppData. Repairing its owner is
+            // therefore safe and is required when Windows creates it with
+            // TokenOwner=Administrators.
            crate::initialize_windows_game_creator_file_owner_for_current_user(path)?;
            validate_windows_regular_file_handle(&file, label)?;
            crate::secure_windows_game_creator_path_for_current_user(path, false, false)?;
            Ok(Some(file))
        }
-        Err(error) if windows_external_agent_runner_lock_is_busy_error(&error) => Ok(None),
+        Err(error)
+            if mode == ExternalAgentRunnerLockMode::Exclusive
+                && windows_external_agent_runner_lock_is_busy_error(&error) =>
+        {
+            Ok(None)
+        }
+        Err(error)
+            if mode == ExternalAgentRunnerLockMode::Shared
+                && windows_external_agent_runner_lock_is_busy_error(&error) =>
+        {
+            Err(format!(
+                "{label} 正被独占探测或持有，稍后重试：{}",
+                path.display()
+            ))
+        }
        Err(error) => Err(format!(
            "安全打开 {label} 失败：{}: {error}",
            path.display()
@@ -892,12 +958,29 @@ pub(super) fn try_open_external_agent_runner_lock(
    }
 }

+#[cfg(windows)]
+pub(super) fn try_open_external_agent_runner_lock(
+    path: &Path,
+    label: &str,
+) -> Result<Option<File>, String> {
+    open_external_agent_runner_lock_file(path, label, ExternalAgentRunnerLockMode::Exclusive)
+}
+
+#[cfg(not(any(unix, windows)))]
+pub(super) fn open_external_agent_runner_lock_file(
+    path: &Path,
+    label: &str,
+    _mode: ExternalAgentRunnerLockMode,
+) -> Result<Option<File>, String> {
+    Err(format!("当前平台不支持 {label} 系统锁：{}", path.display()))
+}
+
 #[cfg(not(any(unix, windows)))]
 pub(super) fn try_open_external_agent_runner_lock(
    path: &Path,
    label: &str,
 ) -> Result<Option<File>, String> {
-    Err(format!("当前平台不支持 {label} 系统锁：{}", path.display()))
+    open_external_agent_runner_lock_file(path, label, ExternalAgentRunnerLockMode::Exclusive)
 }

 pub(super) fn acquire_external_agent_runner_instance_lock(
@@ -929,40 +1012,90 @@ pub(super) fn acquire_external_agent_runner_instance_lock(
    Ok(ExternalAgentRunnerInstanceLock { _file: file })
 }

-pub(crate) fn acquire_external_agent_runner_gui_owner_lock(
+/// 取得本窗口在该 AppData 下的界面参与锁。
+///
+/// 参与锁以共享句柄打开：同一 AppData 可以同时持有任意数量的界面窗口。
+/// Runner 侧用同文件的独占探测判断“是否仍有界面进程存活”，探测窗口很短，
+/// 所以这里遇到瞬时冲突时按 `EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK_RETRY_INTERVAL`
+/// 重试，直到 `EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK_ACQUIRE_TIMEOUT` 截止。
+pub(crate) fn acquire_external_agent_runner_gui_participant_lock(
    config_dir: &Path,
-) -> Result<ExternalAgentRunnerGuiOwnerLock, String> {
-    let path = external_agent_runner_gui_owner_lock_path(config_dir);
-    let Some(mut file) = try_open_external_agent_runner_lock(&path, "Agent Runner GUI owner 锁")?
-    else {
-        return Err("AI 游戏创作界面已由同一 AppData 目录中的其他进程运行".to_string());
-    };
-    let owner_epoch = uuid::Uuid::new_v4().to_string();
-    let acquired_at = unix_millis();
+) -> Result<ExternalAgentRunnerGuiParticipantLock, String> {
+    let path = external_agent_runner_gui_participant_lock_path(config_dir);
+    let deadline = Instant::now() + EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK_ACQUIRE_TIMEOUT;
+    let mut last_error = "AGC 界面参与锁未知失败".to_string();
+    loop {
+        match open_external_agent_runner_lock_file(
+            &path,
+            "AGC 界面参与锁",
+            ExternalAgentRunnerLockMode::Shared,
+        ) {
+            Ok(Some(mut file)) => {
+                write_external_agent_runner_gui_participant_diagnostic(&mut file, &path)?;
+                return Ok(ExternalAgentRunnerGuiParticipantLock { _file: file });
+            }
+            Ok(None) => {
+                last_error = format!("AGC 界面参与锁无法以共享方式取得：{}", path.display());
+            }
+            Err(error) => last_error = error,
+        }
+        if Instant::now() >= deadline {
+            return Err(format!("取得 AGC 界面参与锁失败：{last_error}"));
+        }
+        thread::sleep(EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK_RETRY_INTERVAL);
+    }
+}
+
+/// 参与锁诊断内容只由首个窗口写入，后续窗口不覆写，避免并发写坏 JSON。
+fn write_external_agent_runner_gui_participant_diagnostic(
+    file: &mut File,
+    path: &Path,
+) -> Result<(), String> {
+    let existing_len = file.metadata().map(|metadata| metadata.len()).unwrap_or(0);
+    if existing_len > 0 {
+        return Ok(());
+    }
    let diagnostic = serde_json::to_vec(&json!({
        "protocolVersion": EXTERNAL_AGENT_RUNNER_PROTOCOL_VERSION,
        "pid": std::process::id(),
-        "ownerEpoch": owner_epoch,
-        "acquiredAt": acquired_at,
+        "instanceId": uuid::Uuid::new_v4().to_string(),
+        "acquiredAt": unix_millis(),
    }))
-    .map_err(|error| format!("生成 Agent Runner GUI owner 锁信息失败：{error}"))?;
+    .map_err(|error| format!("生成 AGC 界面参与锁信息失败：{error}"))?;
    file.set_len(0)
        .and_then(|_| file.seek(SeekFrom::Start(0)).map(|_| ()))
        .and_then(|_| file.write_all(&diagnostic))
        .and_then(|_| file.sync_data())
-        .map_err(|error| {
-            format!(
-                "写入 Agent Runner GUI owner 锁信息失败：{}: {error}",
-                path.display()
-            )
-        })?;
-    write_external_agent_runner_gui_owner_claim_atomic(config_dir, &owner_epoch, 0)?;
-    Ok(ExternalAgentRunnerGuiOwnerLock {
-        _file: file,
+        .map_err(|error| format!("写入 AGC 界面参与锁信息失败：{}: {error}", path.display()))
+}
+
+/// 发布新的 durable claim：新 epoch + 本次会话 revision。
+///
+/// 发布是“谁改动登录态谁成为新 epoch 权威”的实现；并发发布以最后一次
+/// 成功写入为准，落败窗口按最新 claim 重试。
+pub(crate) fn publish_external_agent_runner_gui_owner_claim(
+    config_dir: &Path,
+    session_revision: u64,
+) -> Result<ExternalAgentRunnerGuiOwnerClaim, String> {
+    let owner_epoch = uuid::Uuid::new_v4().to_string();
+    write_external_agent_runner_gui_owner_claim_atomic(config_dir, &owner_epoch, session_revision)?;
+    Ok(ExternalAgentRunnerGuiOwnerClaim {
        owner_epoch,
+        session_revision,
    })
 }

+/// 采纳现有 durable claim；只有 claim 缺失或不可读时才发布新 claim。
+pub(crate) fn adopt_or_publish_external_agent_runner_gui_owner_claim(
+    config_dir: &Path,
+    session_revision: u64,
+) -> Result<ExternalAgentRunnerGuiOwnerClaim, String> {
+    match read_external_agent_runner_gui_owner_claim(config_dir) {
+        Ok(claim) => Ok(claim),
+        Err(_) => publish_external_agent_runner_gui_owner_claim(config_dir, session_revision),
+    }
+}
+
 pub(super) fn write_external_agent_runner_gui_owner_claim_atomic(
    config_dir: &Path,
    owner_epoch: &str,
@@ -13,8 +13,8 @@ pub(crate) const EXTERNAL_AGENT_RUNNER_PROTOCOL_VERSION: u32 = 7;

 pub(super) const EXTERNAL_AGENT_RUNNER_ENDPOINT_FILE_NAME: &str = "agent-runner.endpoint.json";
 pub(super) const EXTERNAL_AGENT_RUNNER_LOCK_FILE_NAME: &str = "agent-runner.lock";
-pub(super) const EXTERNAL_AGENT_RUNNER_GUI_OWNER_LOCK_FILE_NAME: &str =
-    "agent-runner.gui-owner.lock";
+pub(super) const EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK_FILE_NAME: &str =
+    "agent-runner.gui-participant.lock";
 pub(super) const EXTERNAL_AGENT_RUNNER_GUI_OWNER_CLAIM_FILE_NAME: &str =
    "agent-runner.gui-owner.claim.json";
 pub(super) const EXTERNAL_AGENT_RUNNER_PROJECT_OWNER_FILE_NAME: &str = "execution-owner.lock";
@@ -156,7 +156,7 @@ fn external_agent_runner_watchdog_tick(state: &ExternalAgentRunnerServerState) -
    if !state.gui_owner_attached.load(Ordering::Acquire) {
        return false;
    }
-    match external_agent_runner_gui_owner_is_locked(&state.gui_owner_lock_path) {
+    match external_agent_runner_lock_is_held(&state.gui_participant_lock_path) {
        Ok(true) => {
            let _ = validate_external_agent_runner_gui_owner_claim_current(state);
            false
@@ -224,7 +224,7 @@ pub(crate) fn run_external_agent_runner_server(
    )?;
    let gui_owner_present_at_start = resolve_external_agent_runner_initial_gui_owner(
        gui_owner_required,
-        external_agent_runner_gui_owner_is_locked(&external_agent_runner_gui_owner_lock_path(
+        external_agent_runner_lock_is_held(&external_agent_runner_gui_participant_lock_path(
            &config_dir,
        ))?,
    )?;
@@ -16,7 +16,7 @@ pub(super) struct ExternalAgentRunnerServerState {
    pub(super) draining: AtomicBool,
    pub(super) active_connections: AtomicUsize,
    pub(super) known_roots: Mutex<BTreeSet<PathBuf>>,
-    pub(super) gui_owner_lock_path: PathBuf,
+    pub(super) gui_participant_lock_path: PathBuf,
    pub(super) project_execution_owners:
        Mutex<BTreeMap<PathBuf, ExternalAgentRunnerProjectExecutionOwnerEntry>>,
    project_execution_owner_recovery_changed: Condvar,
@@ -80,10 +80,10 @@ impl Drop for ExternalAgentRunnerProjectExecutionOwnerRecoveryGuard<'_> {

 impl ExternalAgentRunnerServerState {
    pub(super) fn new(endpoint_path: PathBuf, endpoint: ExternalAgentRunnerEndpoint) -> Self {
-        let gui_owner_lock_path = endpoint_path
+        let gui_participant_lock_path = endpoint_path
            .parent()
-            .map(external_agent_runner_gui_owner_lock_path)
-            .unwrap_or_else(|| PathBuf::from(EXTERNAL_AGENT_RUNNER_GUI_OWNER_LOCK_FILE_NAME));
+            .map(external_agent_runner_gui_participant_lock_path)
+            .unwrap_or_else(|| PathBuf::from(EXTERNAL_AGENT_RUNNER_GUI_PARTICIPANT_LOCK_FILE_NAME));
        Self {
            endpoint_path,
            endpoint: Mutex::new(endpoint),
@@ -94,7 +94,7 @@ impl ExternalAgentRunnerServerState {
            draining: AtomicBool::new(false),
            active_connections: AtomicUsize::new(0),
            known_roots: Mutex::new(BTreeSet::new()),
-            gui_owner_lock_path,
+            gui_participant_lock_path,
            project_execution_owners: Mutex::new(BTreeMap::new()),
            project_execution_owner_recovery_changed: Condvar::new(),
            write_request_cache: Mutex::new(ExternalAgentRunnerRequestCache::default()),
@@ -231,16 +231,10 @@ pub(super) struct ExternalAgentRunnerInstanceLock {
    pub(super) _file: File,
 }

+/// 界面进程持有的参与锁。共享句柄，同一 AppData 可同时存在多个窗口。
 #[derive(Debug)]
-pub(crate) struct ExternalAgentRunnerGuiOwnerLock {
+pub(crate) struct ExternalAgentRunnerGuiParticipantLock {
    pub(super) _file: File,
-    pub(super) owner_epoch: String,
-}
-
-impl ExternalAgentRunnerGuiOwnerLock {
-    pub(crate) fn owner_epoch(&self) -> &str {
-        &self.owner_epoch
-    }
 }

 pub(super) struct ExternalAgentRunnerProjectOwnerStorage {
--- a/Show More
+++ b/Show More