fix(packaging): amd64 GUI 从未走过 electron 缓存，且空壳 node_modules 被当作已安装

干净 worktree 上打包时 GUI 被静默跳过。两个缺陷叠加，都属于「所有外层
检查都通过，只有嵌套的运行时缺失，而没有任何东西喊出来」。

## 一：electron 架构名与 Debian 架构名混用

electron 官方发布物命名用 x64/arm64，Debian 用 amd64/arm64。缓存查找
一直统一用 TAR_ARCH（amd64），于是 electron-v*-linux-x64.zip 永远命中
不到。arm64 两边恰好同名，所以上次修 arm64 GUI 架构污染（743b963）时
这个不一致没暴露。

推论：v1.0.3 的 amd64 GUI 实际是靠「回退到 host node_modules/electron/
dist」这条路组装的，不是走缓存——那条回退只在目标架构 == host 架构时
才允许，恰好成立所以没出错。干净 checkout 里没有完整 node_modules，
回退路径也没有，GUI 就消失了。

修法：单独映射 ELECTRON_ARCH（amd64→x64，arm64→arm64）。

## 二：判 node_modules 目录存在，而非判 electron 包存在

npm install 失败（离线/网络受限）会留下只有一两个条目的空壳
node_modules。原判据 [ ! -d node_modules ] 认为「已安装」，于是跳过
install → ever 读不到版本 → 缓存匹配退化到通配 → host dist 也没有 →
静默跳过 GUI。包名、目录名、变体名全部正确，只是没有 GUI。

修法：判据改为 electron/package.json 是否存在；目录在而包缺失时明确
说明「疑似上次 npm install 未完成」再重试；install 失败给出明确提示
而不是继续往下走。

顺带给 ever 加兜底：读不到已安装版本时从 package.json 的依赖声明取
数字部分（那里是 "^33.0.0" 这类范围，仅用于给缓存匹配一个提示）。

## 验证

干净 worktree（/tmp/rel104，release/v1.0.x）上重跑：
  node_modules 存在但 electron 缺失（疑似上次 npm install 未完成）
  electron 版本取自 package.json 依赖声明: 33.0.0（非精确）
  electron runtime: electron-v33.4.11-linux-x64.zip
  GUI built: build/homeagent-gui-linux-amd64 (263M, x86-64)

file -b 确认 electron 二进制为 x86-64，与目标架构一致（该硬校验由
743b963 引入，此处继续生效）。

README.md

@@ -193,6 +193,12 @@ internal/
 
 ## 项目状态
 
+**v1.0.4** — 两处数据竞争修复（现网 `/api/v1/device/ws` 通道与终端推流）。此前 `-race` 全仓复验即暴露：`remotedevice` 网关对同一连接的 `bufio.Writer` 由两条路径并发写（`handleWS` 主循环回写 hello_ack/绑定回执/pong，与 `PushJSON`/`PushData` 的 agent→设备下发），`bufio.Writer` 非线程安全，`TestWSPushDataAudio` 异步下发即稳定撞车；`agentcli` 终端把共享读缓冲传给 reader goroutine（OS 层持续覆写）又在 `readLoop` 里 `copy(data, buf[:r.n])`，读写并发。修法：连接级写锁（`wconn.wmu`，Push* 与 handleWS 共用同一把锁，`PushData` 整条下发持锁保证协议顺序）与「读结果随 `readResult` 自带切片传递、不再共享缓冲」。全仓 `go test ./... -race` 由 7 处 race / 5 个测试 FAIL 变为 32 包全绿。
+
+**v1.0.3** — 内核 stage 协调器双重解锁修复。现网 homed 主进程曾一次 `fatal error: sync: unlock of unlocked mutex` 整体死亡（带走全部 27 个子进程插件）：`Host.endStage` 把「递减 inflight、判定最后离开者」放在 `coordMu` 临界区之外，而摘除协调器在临界区之内，于是后到插件能挂进一个正在收尾的协调器、被误判成最后离开者，对同一把 `stageMu` 解了两次。**`sync.Mutex` 双重解锁是 runtime fatal 而非 panic，两层 `recover` 结构上拦不住**，这才让「插件崩溃不拖垮内核」的隔离设计整体失效。修法是把计数、判定、摘除收进同一临界区，并把首进者写共享段的 `enter()` 也移入锁内（此前后到者可能读到写一半的段）。配套 5 个回归用例，含把旧实现 stash 回来验证测试确实能复现 fatal 的反向验证。
+
+**v1.0.1** — 多模态 bugfix。插件 ABI/协议未变，1.0.0 编出的 `plugin.bin` 无需重编。修三类缺陷：（1）**看图假成功**——媒体块挂在 tool message 上不被模型当作可视内容（实测同一张图：tool message 0/3 读到、独立 user message 3/3），改为另起一条紧随其后的 user message 承载，落实插件文案一直在说的「注入后续对话」；（2）**新增多模态能力声明与回退链**——`core.llm.sources.<name>.vision/.audio` 声明源能否真正处理媒体（网关会静默剥离 `image_url` 后仍返回 200，带图与不带图 prompt_tokens 完全相同），不支持时自动走视觉源转写成文字，并落实了 `core.input_processing.image.fallback_provider` 这批早已注册却从未被读取的配置项；（3）**`see_video` 帧数语义反了**——`fps=1/N` 是频率不是数量，20s 视频请求 10 帧只得 2 帧、请求 1 帧反得 20 帧，改为 `ffprobe` 取时长 + `fps=N/时长` + `-frames:v` 硬封顶。
+
 **v1.0.0** — 外部插件从 C ABI 动态库迁移到**子进程 + 共享内存**。首个不再加载 `.so`/`.dll` 的版本，与 0.9.x 不兼容（存量插件须用新版 `plugindev` 重编为 `plugin.bin`，**业务代码零改动**）。消除 6 类此前在生产造成故障的缺陷：热重载失效（`DF_1_NODELETE` 让 `dlclose` 成 no-op）、崩溃隔离缺失（插件 panic 带崩 homed）、stage lost update（副本模型丢失 35.8~36.8%）、cgo 超时不可中断（线程线性泄漏）、`output_send` 假成功（模型收到「已发送」而消息未送达）、Windows 能力断层（只见 3 个 stage 字段且无法写回）。三面通信：stdio JSON-RPC（控制）+ 共享内存段（数据）+ 事件环（通知）；权限梯度显式化为三道闸。RPC 往返 p50 24.1µs，崩溃到恢复 <1s。
 
 **v0.9.0** — C ABI v2：外部插件 Stage 回调支持写回（`invoke_stage` 增加 result 输出，插件可在 OnInput/AfterToolcall/PostAction 修改 RawMessage/LLMText/ToolResults 等并同步回内核），ABI 版本随内核 minor 对齐（v0.9.x → ABIVersion=2，`version_min=1` 向后兼容旧插件）。同步修复工具循环 zen 兼容补位误伤首轮 system 上下文的问题。配套 SDK 提供增强版 sanitizer 示例（坏 UTF-8/U+FFFD/ANSI 转义全链路清洗）。**该 ABI 已随 v1.0.0 退场。**
@@ -218,7 +224,7 @@ internal/
 | **client** | waiter + 桌面 GUI | 连接远程 HomeAgent |
 
 - Linux：`.deb`（amd64/arm64）、`.rpm`（x86_64）、`.tar.gz`
-- Windows：`HomeAgent_v1.0.0_{Full,Server,Client}_win64.exe`（NSIS 安装向导）
+- Windows：`HomeAgent_v1.0.4_{Full,Server,Client}_win64.exe`（NSIS 安装向导）
 - 免安装：`homeagent-bin-<os>_<arch>.tar.gz`（含 homed/waiter/initconfig）
 - 校验：`SHA256SUMS`
 

README_EN.md

@@ -179,6 +179,12 @@ External plugin development: see [homeagent-sdk](https://gitcode.com/JianFeeeee/
 
 ## Project Status
 
+**v1.0.4** — Two data-race fixes (the live `/api/v1/device/ws` gateway and terminal streaming). A full `-race` pass exposed both: `remotedevice` wrote one connection's `bufio.Writer` from two concurrent paths (`handleWS` loop replies hello_ack/bind_ack/pong, plus `PushJSON`/`PushData` agent→device pushes) — `bufio.Writer` is not thread-safe, and `TestWSPushDataAudio` async push hit it reliably; `agentcli` handed the shared read buffer to the reader goroutine (which the OS keeps overwriting) while `readLoop` did `copy(data, buf[:r.n])` — concurrent read/write of the same buffer. Fix: connection-level write lock (`wconn.wmu`, shared by Push* and handleWS; `PushData` holds it across the whole start/chunks/end sequence to preserve protocol order) plus carrying read results in per-result slices instead of a shared buffer. Repo-wide `go test ./... -race` went from 7 races / 5 failing tests to all-clean.
+
+**v1.0.3** — Kernel stage-coordinator double-unlock fix. The production `homed` main process once died outright with `fatal error: sync: unlock of unlocked mutex`, taking all 27 subprocess plugins with it: `Host.endStage` performed "decrement inflight, decide whether I'm the last leaver" *outside* the `coordMu` critical section while detaching the coordinator *inside* it, so a late-arriving plugin could attach to a coordinator that was already finishing, be misjudged as the last leaver, and unlock the same `stageMu` twice. **A `sync.Mutex` double unlock is a runtime fatal, not a panic, so the two layers of `recover` structurally cannot catch it**—which is exactly why the "a crashing plugin must not take down the kernel" isolation design failed wholesale here. The fix folds counting, decision, and detach into one critical section, and also moves the first arriver's `enter()` (which writes the shared segment) inside the lock—previously a late arriver could read a half-written segment. Ships with 5 regression cases, including a reverse check that stashes the old implementation back to confirm the tests really do reproduce the fatal.
+
+**v1.0.1** — Multimodal bugfix. The plugin ABI/protocol is unchanged, so `plugin.bin` artifacts built for 1.0.0 need no rebuild. Three defects fixed: (1) **vision silently failing**—media blocks attached to a tool message are not treated as viewable content by the model (measured on one image: 0/3 read from a tool message, 3/3 from a standalone user message); media now rides its own user message placed immediately after, which is what the plugin's own wording ("injected into the following conversation") always claimed; (2) **new multimodal capability declaration + fallback chain**—`core.llm.sources.<name>.vision/.audio` declares whether a source can genuinely process media (a gateway may strip `image_url` and still return 200, with identical prompt_tokens with and without the image); when it cannot, media is transcribed to text via a vision-capable source, finally wiring up the long-registered but never-read `core.input_processing.image.fallback_provider` settings; (3) **`see_video` frame-count semantics were inverted**—`fps=1/N` is a *rate*, not a count, so a 20s video yielded 2 frames when 10 were requested and 20 frames when 1 was requested; now `ffprobe` measures duration and the filter becomes `fps=N/duration` with `-frames:v` as a hard cap.
+
 **v1.0.0** — External plugins moved from C ABI shared libraries to **subprocess + shared memory**. The first release that no longer loads `.so`/`.dll`, and it is incompatible with 0.9.x (existing plugins must be rebuilt into `plugin.bin` with the new `plugindev`, though **business code needs zero changes**). Eliminates 6 classes of defects that had caused production incidents: hot-reload silently failing (`DF_1_NODELETE` making `dlclose` a no-op), no crash isolation (a plugin panic took down homed), stage lost updates (35.8~36.8% loss under the copy model), uncancellable cgo timeouts (linear OS-thread leaks), `output_send` reporting false success (the model was told "sent" while the message never went out), and Windows capability degradation (only 3 stage fields visible, no write-back). Three communication planes: stdio JSON-RPC (control) + shared memory segment (data) + event ring (notification); the privilege gradient is now enforced by three explicit gates. RPC round-trip p50 24.1µs; crash-to-recovery under 1s.
 
 **v0.9.0** — C ABI v2: external plugin Stage callbacks can now write back (`invoke_stage` gained a result out-param; plugins may mutate RawMessage/LLMText/ToolResults etc. in OnInput/AfterToolcall/PostAction and have them synced to the core). ABI version now tracks core minor releases (v0.9.x → ABIVersion=2, `version_min=1` keeps old plugins loadable). Also fixes the tool-loop zen-compat placeholder that wrongly fired on first-turn system context tail. The SDK ships an enhanced sanitizer example (bad-UTF-8 / U+FFFD / ANSI-escape scrub across the whole pipeline). **This ABI retired with v1.0.0.**
@@ -204,7 +210,7 @@ External plugin development: see [homeagent-sdk](https://gitcode.com/JianFeeeee/
 | **client** | waiter + desktop GUI | Connecting to a remote HomeAgent |
 
 - Linux: `.deb` (amd64/arm64), `.rpm` (x86_64), `.tar.gz`
-- Windows: `HomeAgent_v1.0.0_{Full,Server,Client}_win64.exe` (NSIS installer)
+- Windows: `HomeAgent_v1.0.4_{Full,Server,Client}_win64.exe` (NSIS installer)
 - Portable: `homeagent-bin-<os>_<arch>.tar.gz` (homed/waiter/initconfig)
 - Verification: `SHA256SUMS`
 

deploy/packaging/build.sh

@@ -27,10 +27,19 @@ COMPONENT="${2:-all}"
 case "$TARGET" in
   native)   GOOS="" GOARCH="" ;;
   linux/amd64)  GOOS=linux   GOARCH=amd64  CC="${CC:-}" ;;
-  # arm64 刻意不设 CXX：设了会让 Go 用 aarch64 的 g++ 去链接，
-  # 而它对 host 产生的 .o 报 "file format not recognized"。
-  # gojieba 的 C++ 源仍由 CC 对应的 gcc 驱动编译（gcc 能编 C++）。
-  linux/arm64)  GOOS=linux   GOARCH=arm64  CC="${CC:-aarch64-linux-gnu-gcc}" ;;
+  # arm64 必须同时给 CXX：gojieba 是 C++，缺 CXX 时 cgo 用宿主 g++ 编出
+  # x86-64 的 .o，链接时报 "Relocations in generic ELF (EM: 183)"（183 = aarch64）。
+  #
+  # 此处曾有一条注释写着「arm64 刻意不设 CXX」，理由是设了会报
+  # "file format not recognized"。那个判断是错的：那个报错的真因是
+  # cmd/{homed,waiter}/*.syso（x86-64 COFF Windows 资源对象）被链进了目标，
+  # 与 CXX 无关。四组对照：
+  #   syso 在   + 无 CXX → Relocations in generic ELF (EM: 183)
+  #   syso 在   + 有 CXX → 000000.o: file format not recognized
+  #   syso 隐藏 + 无 CXX → Relocations in generic ELF (EM: 183)
+  #   syso 隐藏 + 有 CXX → 成功，ELF aarch64
+  # 本脚本的 hide_syso_for_target 已处理前一个条件，这里补上后一个。
+  linux/arm64)  GOOS=linux   GOARCH=arm64  CC="${CC:-aarch64-linux-gnu-gcc}" CXX="${CXX:-aarch64-linux-gnu-g++}" ;;
   darwin/amd64) GOOS=darwin  GOARCH=amd64  CC="${CC:-}" ;;
   darwin/arm64) GOOS=darwin  GOARCH=arm64  CC="${CC:-}" ;;
   # Windows 必须同时给 CXX：gojieba 是 C++，缺 CXX 时 cgo 回退到宿主 g++，
@@ -144,6 +153,14 @@ build_initconfig() {
 }
 
 # ---- gui (Electron) ----
+#
+# 输出目录必须用 --config.directories.output，**不能用 -o**：
+# electron-builder 的 `-o` 是 `--mac`/`--macos` 的短别名（见 --help 的 Building 段），
+# 不是 output。此前 `-o "$BUILD_DIR"` 被当成 macOS 的 target 列表，报
+#   ⨯ Unknown target: /home/program/trueagent/build
+# （路径被 lowercase 后去匹配 target 名表，所以错误信息里的路径是全小写的，
+#  这也是它看起来像「路径错」而实际是「参数位置错」的原因）。
+# v1.0.1 与 v1.0.3 两次发布都因此手工组装过 GUI。
 build_gui() {
   if [ -n "${GOOS:-}" ] && [ "$GOOS" != "$("$GO" env GOOS)" ]; then
     echo "[SKIP] gui ${GOOS}/${GOARCH} — electron-builder handles cross-platform natively; run 'all' on CI host"
@@ -161,12 +178,21 @@ build_gui() {
   # 不传 --config：electron-builder 默认从 package.json 的 "build" 键读配置。
   # 传 --config package.json 会让它把**整个** package.json 当配置校验，
   # 于是 devDependencies / build / scripts 全被判为 "unknown property" 而失败。
-  (cd "$gui_dir" && npx electron-builder \
-    --linux --win --mac \
-    --x64 --arm64 \
-    -p never \
-    -o "$BUILD_DIR")
-  echo "  OK"
+  #
+  # GUI 失败不中断整体构建：homed/waiter/initconfig 是发布的主体，
+  # 而 GUI 依赖 electron 运行时下载（离线机器、arm64 缺缓存都会失败）。
+  # set -e 下若不接住，一个可选组件会让整轮跨平台构建全废。
+  if (cd "$gui_dir" && npx electron-builder \
+      --linux --win --mac \
+      --x64 --arm64 \
+      -p never \
+      --config.directories.output="$BUILD_DIR"); then
+    echo "  OK"
+  else
+    echo "  WARN: gui 构建失败（可选组件，不影响 homed/waiter/initconfig）"
+    echo "        Linux 包可用 deploy/packaging/package-linux.sh 内置的手工组装路径"
+    return 0
+  fi
 }
 
 # ---- dispatch ----

deploy/packaging/installer.nsi

@@ -14,7 +14,7 @@
 # 此前硬编码 0.8.0 而 release 已到 1.0.0，装出来的包在「添加/删除程序」里
 # 会显示错误版本（DisplayVersion 也取自这个宏）。
 !ifndef PRODUCT_VERSION
-  !define PRODUCT_VERSION "1.0.0"
+  !define PRODUCT_VERSION "1.0.4"
 !endif
 
 !if "${VARIANT}" == "full"

deploy/packaging/package-linux.sh

@@ -9,14 +9,20 @@ PACKAGE_ROOT="${PROJECT_ROOT}/deploy/packaging/linux"
 GO="${GO:-$(command -v go 2>/dev/null || echo "go")}"
 
 ARCH="${1:-amd64}"   # amd64 or arm64
+
+# electron 官方发布物用 x64/arm64 命名，而 Debian 用 amd64/arm64。
+# 两者在 arm64 上恰好同名，amd64 上不同——此前缓存查找统一用 TAR_ARCH
+# （amd64），于是 electron-v*-linux-x64.zip 永远命中不到，amd64 GUI 只能
+# 靠"回退到 host node_modules"这条路组装。干净 worktree 里没有完整
+# node_modules，GUI 就被静默跳过。故单独映射。
 ACTION="${2:-all}"    # all, build, deb, tar, rpm
 
 DEB_ARCH="$ARCH"
 RPM_ARCH="$ARCH"
 TAR_ARCH="$ARCH"
 case "$ARCH" in
-  amd64) DEB_ARCH="amd64"; RPM_ARCH="x86_64"; TAR_ARCH="amd64" ;;
-  arm64) DEB_ARCH="arm64"; RPM_ARCH="aarch64"; TAR_ARCH="arm64" ;;
+  amd64) DEB_ARCH="amd64"; RPM_ARCH="x86_64"; TAR_ARCH="amd64"; ELECTRON_ARCH="x64" ;;
+  arm64) DEB_ARCH="arm64"; RPM_ARCH="aarch64"; TAR_ARCH="arm64"; ELECTRON_ARCH="arm64" ;;
   *) echo "Unknown arch: $ARCH (use amd64 or arm64)"; exit 1 ;;
 esac
 
@@ -122,6 +128,15 @@ build_go() {
 }
 
 # ---- build GUI (manual directory assembly, avoids electron-packager network issues) ----
+#
+# electron 运行时必须按**目标架构**取，不能用 host 的
+# node_modules/electron/dist——那里永远是 host 架构（本机 x64）。
+# v1.0.0 / v1.0.1 的 arm64 full/client 包都踩了这个坑：目录名带
+# -arm64、homed/waiter 确实是 aarch64，但里面的 electron 是 x86-64，
+# 在 arm64 机器上一启动就是 Exec format error（从未被交叉验证过）。
+#
+# 现在改为优先从 electron 缓存里取对应架构的 zip，并在最后做
+# 一道强制校验：架构不符就删掉目录并跳过 GUI，宁可不发也不发坏包。
 build_gui() {
   local gui_dir="$PROJECT_ROOT/cmd/gui"
   local gui_out="$BUILD_DIR/homeagent-gui-linux-${TAR_ARCH}"
@@ -133,22 +148,81 @@ build_gui() {
 
   echo ">>> Building GUI directory for linux/$ARCH..."
 
-  if [ ! -d "$gui_dir/node_modules" ]; then
+  # 判据是 electron 包本身在不在，而不是 node_modules 目录在不在。
+  #
+  # npm install 失败（离线、网络受限）会留下一个只有一两个条目的空壳
+  # node_modules，目录存在但 electron 缺失。只看目录会以为"已安装"，
+  # 于是 ever 读不到版本、缓存匹配退化、最后走到"host dist 也没有"而
+  # 静默跳过 GUI——包名和目录名全都正确，只是没有 GUI，没有任何一步报错。
+  if [ ! -f "$gui_dir/node_modules/electron/package.json" ]; then
+    if [ -d "$gui_dir/node_modules" ]; then
+      echo "  node_modules 存在但 electron 缺失（疑似上次 npm install 未完成）"
+    fi
     echo "  npm install..."
-    (cd "$gui_dir" && npm install --production)
+    if ! (cd "$gui_dir" && npm install --production); then
+      echo "  WARNING: npm install 失败——离线环境下这是预期的。"
+      echo "           GUI 需要 cmd/gui/node_modules/electron 或 ~/.cache/electron 缓存。"
+    fi
   fi
 
-  local electron_dir="$gui_dir/node_modules/electron/dist"
-  if [ ! -f "$electron_dir/electron" ]; then
-    echo "  WARNING: electron binary not found at $electron_dir. GUI will be skipped."
-    return
+  # electron 版本优先从已安装的包里读，保证运行时与 app 依赖一致。
+  # 读不到时退而从 package.json 的依赖声明里取数字部分（它可能写成
+  # "^33.0.0" 这类范围，只用于给缓存匹配一个提示，匹配不上仍会走通配）。
+  local ever
+  ever=$(python3 -c "import json;print(json.load(open('$gui_dir/node_modules/electron/package.json'))['version'])" 2>/dev/null || true)
+  if [ -z "$ever" ]; then
+    ever=$(python3 -c "
+import json, re
+d = json.load(open('$gui_dir/package.json'))
+spec = (d.get('devDependencies', {}) or {}).get('electron') or (d.get('dependencies', {}) or {}).get('electron') or ''
+m = re.search(r'(\\d+(?:\\.\\d+)*)', spec)
+print(m.group(1) if m else '')
+" 2>/dev/null || true)
+    [ -n "$ever" ] && echo "  electron 版本取自 package.json 依赖声明: $ever（非精确）"
+  fi
+
+  mkdir -p "$gui_out"
+
+  # 优先：缓存里的目标架构 zip（~/.cache/electron/<hash>/electron-v<ver>-linux-<arch>.zip）
+  local zip=""
+  if [ -n "$ever" ]; then
+    zip=$(find "$HOME/.cache/electron" -name "electron-v${ever}-linux-${ELECTRON_ARCH}.zip" 2>/dev/null | head -1)
+  fi
+  if [ -z "$zip" ]; then
+    zip=$(find "$HOME/.cache/electron" -name "electron-v*-linux-${ELECTRON_ARCH}.zip" 2>/dev/null | head -1)
+  fi
+
+  if [ -n "$zip" ]; then
+    echo "  electron runtime: $(basename "$zip")"
+    unzip -q -o "$zip" -d "$gui_out"
+  else
+    # 回退：仅当目标架构 == host 架构时才能用 host 的 dist
+    local host_arch
+    case "$(uname -m)" in
+      x86_64) host_arch=amd64 ;;
+      aarch64|arm64) host_arch=arm64 ;;
+      *) host_arch=unknown ;;
+    esac
+    if [ "$TAR_ARCH" != "$host_arch" ]; then
+      echo "  WARNING: 缺 electron-v*-linux-${ELECTRON_ARCH}.zip 缓存，且目标架构与 host"
+      echo "           ($host_arch) 不同——不能用 host 的 electron 冒充。跳过 GUI。"
+      echo "           解法：下载 electron-v${ever:-<ver>}-linux-${ELECTRON_ARCH}.zip 到"
+      echo "           ~/.cache/electron/<任意子目录>/ 后重跑。"
+      rm -rf "$gui_out"
+      return
+    fi
+    local electron_dir="$gui_dir/node_modules/electron/dist"
+    if [ ! -f "$electron_dir/electron" ]; then
+      echo "  WARNING: electron binary not found at $electron_dir. GUI will be skipped."
+      rm -rf "$gui_out"
+      return
+    fi
+    echo "  electron runtime: host node_modules (同架构 $host_arch)"
+    cp -r "$electron_dir"/* "$gui_out/" 2>/dev/null
   fi
 
   mkdir -p "$gui_out/resources/app/node_modules"
   mkdir -p "$gui_out/resources/app/renderer"
-
-  # copy electron runtime (binary + shared libs)
-  cp -r "$electron_dir"/* "$gui_out/" 2>/dev/null
   rm -f "$gui_out/resources/default_app.asar" 2>/dev/null
 
   # copy app source
@@ -190,7 +264,28 @@ LAUNCHER
   chmod +x "$gui_out/homeagent-gui"
   chmod +x "$gui_out/electron"
 
-  echo "  GUI built: $gui_out ($(du -sh "$gui_out" | cut -f1))"
+  # 最后一道强制校验：electron 二进制的实际架构必须匹配目标架构。
+  # 不做这步就会重现 v1.0.0/v1.0.1 的隐形坏包：包名、目录名、
+  # homed/waiter 全对，只有 electron 是错架构，直到用户在 arm64 机器上
+  # 双击才发现 Exec format error。
+  local want_pat
+  case "$TAR_ARCH" in
+    amd64) want_pat="x86-64" ;;
+    arm64) want_pat="aarch64" ;;
+    *)     want_pat="" ;;
+  esac
+  if [ -n "$want_pat" ]; then
+    local got
+    got=$(file -b "$gui_out/electron" 2>/dev/null || echo "")
+    if ! printf '%s' "$got" | grep -q "$want_pat"; then
+      echo "  ERROR: electron 架构不符——期望 $want_pat，实际: ${got%%,*}"
+      echo "         删除 GUI 目录并跳过（宁可不发，也不发装了跑不起来的包）。"
+      rm -rf "$gui_out"
+      return
+    fi
+  fi
+
+  echo "  GUI built: $gui_out ($(du -sh "$gui_out" | cut -f1), $(file -b "$gui_out/electron" | cut -d, -f2 | tr -d ' '))"
   echo ""
 }
 

deploy/scripts/upload_assets.py

@@ -66,19 +66,41 @@ def put_file(url: str, headers: dict, path: str) -> tuple[int, str]:
         return 0, f"{type(e).__name__}: {e}"
 
 
+def project_root() -> str:
+    """向上找带 go.mod 的目录作为仓库根。
+
+    为何不数 dirname：本脚本初版在 scripts/（深度 1），移到 deploy/scripts/
+    （深度 2）后写死的两层 dirname 就指向了 deploy/dist/release，上传直接
+    FileNotFoundError。这正是 v0.7.2 那次 package/ → deploy/packaging/ 打断
+    PROJECT_ROOT 的同一个坑，改成按标记文件定位以后怎么挑位置都不会错。
+    """
+    d = os.path.dirname(os.path.abspath(__file__))
+    while d != os.path.dirname(d):
+        if os.path.exists(os.path.join(d, "go.mod")):
+            return d
+        d = os.path.dirname(d)
+    # 实在找不到（脚本被单独拷出仓库）就回退到 cwd，给 ASSET_DIR 一个机会
+    return os.getcwd()
+
+
 def main() -> int:
     if len(sys.argv) < 3:
         print(__doc__)
         return 2
     tag, token = sys.argv[1], sys.argv[2]
     outdir = os.environ.get("ASSET_DIR") or os.path.join(
-        os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
-        "dist",
-        "release",
+        project_root(), "dist", "release"
     )
+    if not os.path.isdir(outdir):
+        print(f"error: 资产目录不存在: {outdir}")
+        print("       用 ASSET_DIR=<目录> 显式指定，或先跑构建生成 dist/release/")
+        return 2
     files = sys.argv[3:] or sorted(
         f for f in os.listdir(outdir) if is_artifact(f)
     )
+    if not files:
+        print(f"error: {outdir} 下没有可识别的发布产物")
+        return 2
     print(f"repo={REPO} tag={tag} dir={outdir}", flush=True)
     failed = []
     for name in files:

internal/meta/meta.go

@@ -10,7 +10,10 @@ var (
 	// 1.0.0：外部插件从 C ABI 动态库迁到子进程 + 共享内存。
 	// 这是首个不再加载 `.so`/`.dll` 的版本，与 0.9.x 不兼容（存量插件必须
 	// 用新版 plugindev 重编），故跃到主版本号。
-	Version = "1.0.0"
+	//
+	// 1.0.1：多模态修复。仅内核与内置插件改动，插件 ABI/协议未变，
+	// 1.0.0 编出的 plugin.bin 无需重编。
+	Version = "1.0.4"
 
 	// Commit 是构建时的 Git commit hash。
 	Commit = "unknown"

internal/plugin/proc/host.go

@@ -144,48 +144,83 @@ func (h *Host) Close() error {
 //
 // 首个进入者：获取 stageMu（独占共享段）→ 把内核 StageContext 写入段。
 // 后续进入者：仅递增 inflight。
+//
+// enter() 在 coordMu 内完成，两个原因：
+//  1. 首进者的 WriteAll 未结束前不能让后到者拿到 coord 就去读共享段
+//     （旧码的后到者 enter 立即返回，可能读到写一半的段）。
+//  2. 与 endStage 的摘除互斥，防止后到者挂进一个正在收尾的协调器
+//     （具体见 endStage 的注释）。
+//
+// 锁序：stageMu → coordMu。endStage 只解锁 stageMu、不获取，所以无环。
 func (h *Host) beginStage(sc *pubsdk.StageContext) (*stageCoordinator, error) {
 	h.coordMu.Lock()
-	first := h.coord == nil
-	if first {
-		// 独占共享段直到本次 stage 全部插件离开
+	if h.coord == nil {
+		// 首个进入者：独占共享段直到本次 stage 全部插件离开。
+		// 必须先放 coordMu 再取 stageMu，不能反序。
 		h.coordMu.Unlock()
 		h.stageMu.Lock()
 		h.coordMu.Lock()
-		// 双检：等锁期间可能已有其他插件建好协调器（它们会先拿到 stageMu）
-		if h.coord != nil {
-			first = false
-			h.stageMu.Unlock()
-		} else {
-			h.coord = newStageCoordinator(h.seg)
-		}
-	}
-	coord := h.coord
-	h.coordMu.Unlock()
-
-	if err := coord.enter(sc, first); err != nil {
-		if first {
-			h.coordMu.Lock()
-			h.coord = nil
+		if h.coord == nil {
+			coord := newStageCoordinator(h.seg)
+			h.coord = coord
+			if err := coord.enter(sc, true); err != nil {
+				// 注意：runStage 的 defer endStage(coord) 是在 beginStage
+				// 返回 err 的检查之后才注册的，所以这条路径上
+				// endStage 永远不会被调用——stageMu 必须在此自行释放，
+				// 否则整个 stage 通道永久卡死。
+				h.coord = nil
+				h.coordMu.Unlock()
+				h.stageMu.Unlock()
+				return nil, err
+			}
 			h.coordMu.Unlock()
-			h.stageMu.Unlock()
+			h.locks.bind(coord.lock)
+			return coord, nil
 		}
+		// 双检失败：等锁期间已有其他插件建好协调器，退回后到者路径。
+		h.stageMu.Unlock()
+	}
+
+	coord := h.coord
+	if err := coord.enter(sc, false); err != nil {
+		h.coordMu.Unlock()
 		return nil, err
 	}
+	h.coordMu.Unlock()
 	h.locks.bind(coord.lock)
 	return coord, nil
 }
 
 // endStage 由插件 handler 返回时调用。
 // 最后离开者：把共享段结果读回内核 StageContext → 压实 arena → 释放 stageMu。
+//
+// coordMu 必须覆盖「递减 inflight → 判定最后离开者 → 摘除 h.coord」全过程。
+// 旧码把 leave() 放在 coordMu 之外，留出了这个窗口（即 2026-09-04 06:56:18
+// 线上 fatal error: sync: unlock of unlocked mutex 的真因）：
+//
+//	A.endStage: leave() → inflight 1→0, last=true，尚未摘除 h.coord
+//	B.beginStage: 看到 h.coord != nil，以「后到者」身份 enter，inflight 0→1
+//	              （后到者不取 stageMu）
+//	A.endStage: h.coord = nil；stageMu.Unlock()            ← 第 1 次
+//	B.endStage: leave() → inflight 1→0, last=true → stageMu.Unlock()  ← 第 2 次 💥
+//
+// B 从未持有 stageMu（它是后到者），却因为挂进了一个正在收尾的协调器
+// 而成为“最后离开者”，于是对同一把锁解了两次。sync.Mutex 的双重解锁是
+// runtime fatal，**recover 捕不到**——这就是为何 stage.go / stages.go 里
+// 那两层 recover 全部失效、整个 homed 直接死掉的原因。
 func (h *Host) endStage(coord *stageCoordinator) error {
-	last, err := coord.leave()
-	if !last {
-		return err
-	}
 	h.coordMu.Lock()
-	h.coord = nil
+	last, sc, written := coord.depart()
+	if last && h.coord == coord {
+		h.coord = nil
+	}
 	h.coordMu.Unlock()
+	if !last {
+		return nil
+	}
+	// finish 必须在 stageMu.Unlock() 之前：先放锁会让下一轮 stage
+	// 在回读未完时就改写共享段。
+	err := coord.finish(sc, written)
 	h.stageMu.Unlock()
 	return err
 }
@@ -232,26 +267,38 @@ func (c *stageCoordinator) enter(sc *pubsdk.StageContext, first bool) error {
 
 // leave 登记一个插件离开；返回是否为最后一个离开者。
 //
-// 最后离开者负责把共享段结果读回内核 StageContext，并压实 arena
-// （此时无插件持锁，满足 §3.3 的压实前提）。
+// 拆成两段：depart() 只动计数（由 endStage 在 coordMu 内调用，使
+// 「递减 → 判定最后者 → 摘除 h.coord」成为原子操作），finish() 做
+// 共享段回读与压实。本方法保留给单测用。
 func (c *stageCoordinator) leave() (last bool, err error) {
-	c.mu.Lock()
-	c.inflight--
-	last = c.inflight == 0
-	sc := c.ctxRef
-	written := c.written
-	c.mu.Unlock()
-
-	if !last || !written || sc == nil {
+	last, sc, written := c.depart()
+	if !last {
 		return last, nil
 	}
+	return last, c.finish(sc, written)
+}
+
+// depart 递减 inflight 并报告是否为最后离开者。
+func (c *stageCoordinator) depart() (last bool, sc *pubsdk.StageContext, written bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.inflight--
+	return c.inflight == 0, c.ctxRef, c.written
+}
+
+// finish 把共享段结果读回内核 StageContext 并压实 arena
+// （此时无插件持锁，满足 §3.3 的压实前提）。
+func (c *stageCoordinator) finish(sc *pubsdk.StageContext, written bool) error {
+	if !written || sc == nil {
+		return nil
+	}
 	if rErr := c.seg.ReadInto(sc); rErr != nil {
-		return last, fmt.Errorf("回读共享段: %w", rErr)
+		return fmt.Errorf("回读共享段: %w", rErr)
 	}
 	if reclaimed := c.seg.Compact(); reclaimed > 0 {
 		log.Printf("[proc] stage 结束，arena 压实回收 %d 字节", reclaimed)
 	}
-	return last, nil
+	return nil
 }
 
 // ShmSize 返回共享段大小（供诊断/日志）。

internal/plugin/proc/host_stage_test.go

@@ -0,0 +1,220 @@
+package proc
+
+import (
+	"sync"
+	"sync/atomic"
+	"testing"
+
+	pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
+)
+
+// 本文件是 2026-09-04 06:56:18 线上 crash 的回归测试。
+//
+// 崩溃形态：homed 主进程直接死亡，退出码 2。
+//
+//	fatal error: sync: unlock of unlocked mutex
+//	proc.(*Host).endStage(...) host.go:189
+//	proc.(*coreHandler).runStage.func1() stage.go:94
+//	core.(*StageHost).RunStage.func1() stages.go:190
+//
+// 注意 stage.go 与 stages.go 各有一层 recover，却都没拦住——
+// sync.Mutex 的双重解锁是 runtime fatal，recover 捕不到。这是本次
+// "整个内核本体崩溃"而非"插件崩溃被隔离"的直接原因。
+
+// TestEndStage_LateArrivalNoDoubleUnlock 复现根因竞态。
+//
+// 旧实现把 leave() 放在 coordMu 之外，留出这个窗口：
+//
+//	A.endStage: leave() → inflight 1→0, last=true，尚未摘除 h.coord
+//	B.beginStage: 看到 h.coord != nil，以「后到者」身份 enter，inflight 0→1
+//	              （后到者不取 stageMu）
+//	A.endStage: h.coord = nil; stageMu.Unlock()                    ← 第 1 次
+//	B.endStage: leave() → inflight 1→0, last=true → stageMu.Unlock() ← 第 2 次 💥
+//
+// B 从未持有 stageMu，却因为挂进了一个正在收尾的协调器而成为
+// "最后离开者"，于是对同一把锁解了两次。
+//
+// 本测试直接驱动 depart/enter 制造那个时序，不依赖调度巧合。
+func TestEndStage_LateArrivalNoDoubleUnlock(t *testing.T) {
+	host, err := NewHost()
+	if err != nil {
+		t.Fatalf("NewHost: %v", err)
+	}
+	defer host.Close()
+
+	scA := &pubsdk.StageContext{RawMessage: "A"}
+	coordA, err := host.beginStage(scA)
+	if err != nil {
+		t.Fatalf("A beginStage: %v", err)
+	}
+
+	// A 收尾：修复后 depart 与摘除 h.coord 在同一个 coordMu 临界区内，
+	// 所以此刻起 h.coord 已是 nil，B 不可能再挂进 A 的协调器。
+	if err := host.endStage(coordA); err != nil {
+		t.Fatalf("A endStage: %v", err)
+	}
+
+	// B 现在进入：必须成为新的首进者（拿到自己的 stageMu），
+	// 而不是挂进 A 那个已收尾的协调器。
+	scB := &pubsdk.StageContext{RawMessage: "B"}
+	coordB, err := host.beginStage(scB)
+	if err != nil {
+		t.Fatalf("B beginStage: %v", err)
+	}
+	if coordB == coordA {
+		t.Fatal("B 不该复用 A 已收尾的协调器——这正是 double-unlock 的来源")
+	}
+	if err := host.endStage(coordB); err != nil {
+		t.Fatalf("B endStage: %v", err)
+	}
+
+	// 若上面多解了一次锁，这里会 fatal（runtime 级，测试进程直接死）；
+	// 能走到这一步说明配对正确。
+	scC := &pubsdk.StageContext{RawMessage: "C"}
+	coordC, err := host.beginStage(scC)
+	if err != nil {
+		t.Fatalf("C beginStage: %v", err)
+	}
+	if err := host.endStage(coordC); err != nil {
+		t.Fatalf("C endStage: %v", err)
+	}
+}
+
+// TestEndStage_ConcurrentChurnNoFatal 高并发进出：真实触发线上那个窗口。
+//
+// 旧实现下这个测试会以 fatal error: sync: unlock of unlocked mutex 结束
+// （整个测试二进制死亡，不是 FAIL）。修复后应干净通过。
+func TestEndStage_ConcurrentChurnNoFatal(t *testing.T) {
+	host, err := NewHost()
+	if err != nil {
+		t.Fatalf("NewHost: %v", err)
+	}
+	defer host.Close()
+
+	const workers = 8
+	const rounds = 40
+	var wg sync.WaitGroup
+	var failures atomic.Int64
+
+	for w := 0; w < workers; w++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for r := 0; r < rounds; r++ {
+				sc := &pubsdk.StageContext{RawMessage: "churn"}
+				coord, err := host.beginStage(sc)
+				if err != nil {
+					failures.Add(1)
+					return
+				}
+				if err := host.endStage(coord); err != nil {
+					failures.Add(1)
+					return
+				}
+			}
+		}()
+	}
+	wg.Wait()
+
+	if n := failures.Load(); n > 0 {
+		t.Fatalf("%d 次 begin/end 失败", n)
+	}
+}
+
+// TestBeginStage_MultiPluginSameStage 同阶段多插件扇出：
+// 首进者取 stageMu，后到者只递增 inflight，最后离开者才解锁。
+// 验证并发扇出这一原始设计仍然成立（§0.2 第 1 条）。
+func TestBeginStage_MultiPluginSameStage(t *testing.T) {
+	host, err := NewHost()
+	if err != nil {
+		t.Fatalf("NewHost: %v", err)
+	}
+	defer host.Close()
+
+	sc := &pubsdk.StageContext{RawMessage: "fanout"}
+
+	// 三个插件先后进入同一次 stage
+	c1, err := host.beginStage(sc)
+	if err != nil {
+		t.Fatalf("plugin1 beginStage: %v", err)
+	}
+	c2, err := host.beginStage(sc)
+	if err != nil {
+		t.Fatalf("plugin2 beginStage: %v", err)
+	}
+	c3, err := host.beginStage(sc)
+	if err != nil {
+		t.Fatalf("plugin3 beginStage: %v", err)
+	}
+	// 同一次 stage 内必须共用一个协调器（共享同一份 StageContext 段）
+	if c1 != c2 || c2 != c3 {
+		t.Fatal("同阶段并发插件应共用一个协调器")
+	}
+
+	// 前两个离开不该释放 stageMu
+	if err := host.endStage(c1); err != nil {
+		t.Fatalf("plugin1 endStage: %v", err)
+	}
+	if err := host.endStage(c2); err != nil {
+		t.Fatalf("plugin2 endStage: %v", err)
+	}
+	// 最后一个离开才释放
+	if err := host.endStage(c3); err != nil {
+		t.Fatalf("plugin3 endStage: %v", err)
+	}
+
+	// 锁已释放：新一轮能立即开始
+	c4, err := host.beginStage(sc)
+	if err != nil {
+		t.Fatalf("新一轮 beginStage 应成功（stageMu 已释放）: %v", err)
+	}
+	if c4 == c1 {
+		t.Fatal("新一轮应是新的协调器")
+	}
+	if err := host.endStage(c4); err != nil {
+		t.Fatalf("新一轮 endStage: %v", err)
+	}
+}
+
+// TestBeginStage_SerialRounds 长串行：确认没有单向泄漏（少解锁会在第二轮卡死）。
+func TestBeginStage_SerialRounds(t *testing.T) {
+	host, err := NewHost()
+	if err != nil {
+		t.Fatalf("NewHost: %v", err)
+	}
+	defer host.Close()
+
+	for round := 0; round < 50; round++ {
+		sc := &pubsdk.StageContext{RawMessage: "serial"}
+		coord, err := host.beginStage(sc)
+		if err != nil {
+			t.Fatalf("round %d beginStage: %v", round, err)
+		}
+		if err := host.endStage(coord); err != nil {
+			t.Fatalf("round %d endStage: %v", round, err)
+		}
+	}
+}
+
+// TestBeginStage_PhaseSequence 模拟一条消息走完 pre_action → chat → post_action。
+func TestBeginStage_PhaseSequence(t *testing.T) {
+	host, err := NewHost()
+	if err != nil {
+		t.Fatalf("NewHost: %v", err)
+	}
+	defer host.Close()
+
+	phases := []pubsdk.Stage{"pre_action", "chat", "after_toolcall", "post_action"}
+	for msg := 0; msg < 10; msg++ {
+		for _, p := range phases {
+			sc := &pubsdk.StageContext{RawMessage: "msg", Phase: p}
+			coord, err := host.beginStage(sc)
+			if err != nil {
+				t.Fatalf("msg %d phase %s beginStage: %v", msg, p, err)
+			}
+			if err := host.endStage(coord); err != nil {
+				t.Fatalf("msg %d phase %s endStage: %v", msg, p, err)
+			}
+		}
+	}
+}

internal/plugins/agentcli/plugin.go

@@ -18,10 +18,10 @@ import (
 )
 
 const (
-	DefaultTimeout      = 5 * time.Minute
-	ReadBufSize         = 4096
-	MaxOutputBuffer     = 128 * 1024
-	DefaultNotifyBytes  = 2048 // 积累 2KB 未读输出再通知
+	DefaultTimeout        = 5 * time.Minute
+	ReadBufSize           = 4096
+	MaxOutputBuffer       = 128 * 1024
+	DefaultNotifyBytes    = 2048            // 积累 2KB 未读输出再通知
 	DefaultNotifyInterval = 2 * time.Second // 同一终端两次通知的最小间隔（兜底）
 )
 
@@ -68,12 +68,12 @@ type TerminalSession struct {
 	done      chan struct{}
 
 	// 通知节流字段
-	unreadBytes  int             // 最近一次通知后积累的未读字节数
-	lastNotify   time.Time       // 最近一次通知时间
-	lastData     time.Time       // 最近一次读到的数据时间（用于判定输出停止）
-	lastFeedback time.Time       // 最近一次定时反馈时间
-	backoff      time.Duration   // 输出风暴退避：持续高速输出时通知间隔翻倍
-	watch        terminalWatch   // 该终端的提醒规则
+	unreadBytes  int           // 最近一次通知后积累的未读字节数
+	lastNotify   time.Time     // 最近一次通知时间
+	lastData     time.Time     // 最近一次读到的数据时间（用于判定输出停止）
+	lastFeedback time.Time     // 最近一次定时反馈时间
+	backoff      time.Duration // 输出风暴退避：持续高速输出时通知间隔翻倍
+	watch        terminalWatch // 该终端的提醒规则
 
 	// 实时画面推流（terminal_output 事件）
 	stream bytes.Buffer // 待推送的增量输出，由 readLoop 每 200ms flush 一次
@@ -226,7 +226,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 		Description: "创建一个新的交互式终端会话。返回终端 ID，后续通过此 ID 进行读写操作。适用于运行交互式程序如 vim、ssh、top、nano 等。" +
 			"通知模式通过 notify 参数选择（默认 exit）：exit=仅命令执行结束后提醒一次；interval=定时反馈（如 interval=30s 每 30 秒反馈一次状态摘要）；" +
 			"buffer=未读输出积累到指定字节数后提醒（如 buffer=8192）；多个模式用逗号组合（如 interval=30s,buffer=8192）。终端默认 5 分钟后自动关闭，可通过 timeout 参数调整。",
-		NoMemory:    true,
+		NoMemory: true,
 		Parameters: map[string]interface{}{
 			"type": "object",
 			"properties": map[string]interface{}{
@@ -283,7 +283,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	})
 
 	s.RegisterTool("terminal_read", sdk.ToolDef{
-		Name: "terminal_read",
+		Name:        "terminal_read",
 		Description: "读取指定终端的输出。mode=new（默认）返回自上次读取以来的新输出并清空缓冲；mode=now 返回终端当前显示的全部屏幕内容（不清空缓冲）。如需持续监控请多次调用。",
 		NoMemory:    true,
 		Parameters: map[string]interface{}{
@@ -759,11 +759,11 @@ func (p *Plugin) handleList() (interface{}, error) {
 	defer p.mu.Unlock()
 
 	type termInfo struct {
-		ID       string `json:"id"`
-		Command  string `json:"command"`
-		Uptime   string `json:"uptime"`
+		ID        string `json:"id"`
+		Command   string `json:"command"`
+		Uptime    string `json:"uptime"`
 		ExpiresIn string `json:"expires_in"`
-		Running  bool   `json:"running"`
+		Running   bool   `json:"running"`
 	}
 
 	var terms []termInfo
@@ -787,8 +787,8 @@ func (p *Plugin) handleList() (interface{}, error) {
 	}
 
 	return map[string]interface{}{
-		"status":   "ok",
-		"count":    len(terms),
+		"status":    "ok",
+		"count":     len(terms),
 		"terminals": terms,
 	}, nil
 }
@@ -797,6 +797,9 @@ func (p *Plugin) readLoop(t *TerminalSession, s *sdk.PluginSDK) {
 	defer p.wg.Done()
 	defer close(t.done)
 
+	// reader 协程独享这个读缓冲：结果随 readResult 携带，
+	// readLoop 不再从其中做 copy（见 reader 注释，那是对共享缓冲
+	// 的并发读写，-race 实测触发）。
 	buf := make([]byte, ReadBufSize)
 	pollInterval := 200 * time.Millisecond
 
@@ -816,7 +819,7 @@ func (p *Plugin) readLoop(t *TerminalSession, s *sdk.PluginSDK) {
 	t.lastFeedback = now
 	t.mu.Unlock()
 
-// 硬上限：未读输出积累达到该值也通知一次（防大输出静默丢失），频率极低
+	// 硬上限：未读输出积累达到该值也通知一次（防大输出静默丢失），频率极低
 	hardNotifyBytes := 64 * 1024
 	hardNotifyInterval := 10 * time.Second
 	// 输出停止判定：超过该时长无新数据则视为输出停止
@@ -886,9 +889,7 @@ func (p *Plugin) readLoop(t *TerminalSession, s *sdk.PluginSDK) {
 				return
 			}
 			if r.n > 0 {
-				data := make([]byte, r.n)
-				copy(data, buf[:r.n])
-				t.appendOutput(data)
+				t.appendOutput(r.data)
 
 				// 缓冲阈值通知（仅当 agent 显式选择 buffer 模式，或未读积累达到硬上限）。
 				// 默认模式（仅 exit 提醒）下不随输出流通知，杜绝通知风暴。
@@ -951,15 +952,28 @@ func previewTail(s string, n int) string {
 }
 
 type readResult struct {
-	n   int
-	err error
+	n    int
+	data []byte
+	err  error
 }
 
+// reader 从终端读取输出并通过 channel 交给 readLoop。
+//
+// 读到的数据**随结果一起传**而不是复用外层共享的 buf：
+// reader 是唯一写 buf 的 goroutine，readLoop 又常在 reader 尚未
+// 写完下一段时就从 buf[:r.n] 做 copy——同一个 shared buf 被并发
+// 读写就是 data race（-race 实测触发）。改为每个结果自带切片后，
+// 读与拷贝天然隔离，不再共享可变状态。
 func (p *Plugin) reader(t *TerminalSession, buf []byte, ch chan<- readResult) {
 	for {
 		n, err := t.session.Read(buf)
+		var data []byte
+		if n > 0 {
+			data = make([]byte, n)
+			copy(data, buf[:n])
+		}
 		select {
-		case ch <- readResult{n, err}:
+		case ch <- readResult{n, data, err}:
 		case <-t.stopCh:
 			return
 		}

internal/plugins/real_plugin_smoke_test.go

@@ -213,27 +213,68 @@ func TestRealPlugin_CrashDoesNotKillKernel(t *testing.T) {
 		t.Fatal("editdoc 未加载")
 	}
 
-	// 找到插件子进程并 SIGKILL
-	pid := findPluginPID(t, "editdoc")
+	// 找插件子进程并 SIGKILL。
+	//
+	// 必须拿 plgDir 限定范围：旧实现用全系统 pgrep -f plugin.bin 后
+	// 只比“路径含 editdoc”，于是在跑着生产实例的机器上，它会把
+	// /home/newqqagent/plugins/editdoc/plugin.bin 当成目标杀掉（实测 9 次，
+	// 全部落在有人跑 go test 的时段）。更糟的是此时本测试仍会通过：
+	// 它断言的是测试内核存活，而那个内核的插件压根没死——**它在测一件
+	// 没发生的事**，同时还把生产环境打坏了。
+	pid := findPluginPID(t, plgDir, "editdoc")
 	if pid == 0 {
-		t.Skip("未找到插件子进程（进程名匹配失败）")
+		t.Skip("未找到本测试自己拉起的插件子进程")
 	}
-	t.Logf("kill 插件进程 pid=%d", pid)
+	t.Logf("kill 插件进程 pid=%d (exe 在 %s 下)", pid, plgDir)
 	if err := syscall.Kill(pid, syscall.SIGKILL); err != nil {
 		t.Fatalf("kill: %v", err)
 	}
 
-	// 内核必须存活并能继续工作
-	time.Sleep(300 * time.Millisecond)
+	// 先确认目标进程真的死了。
+	//
+	// 这步不能省：旧版直接断言“内核存活”，而内核本来就活着——
+	// 即使 SIGKILL 发错了对象（杀了生产实例的插件）测试也会结束。
+	// 先验“目标真死”再验“内核未被连带”，两步都成立才能证明隔离生效。
+	deadline := time.Now().Add(3 * time.Second)
+	dead := false
+	for time.Now().Before(deadline) {
+		if syscall.Kill(pid, 0) != nil {
+			dead = true
+			break
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	if !dead {
+		t.Fatalf("pid=%d 在 SIGKILL 后 3s 内未退出，崩溃隔离无从验证", pid)
+	}
+
+	// 内核（本测试进程）必须存活并能继续工作
 	if env.pluginReg.List() == nil {
 		t.Fatal("内核在插件崩溃后不可用")
 	}
-	t.Logf("插件崩溃后内核存活，已加载插件数=%d", len(env.pluginReg.List()))
+	t.Logf("插件进程已确认退出，内核存活，已加载插件数=%d", len(env.pluginReg.List()))
 }
 
-// findPluginPID 按二进制路径找插件子进程 pid。
-func findPluginPID(t *testing.T, name string) int {
+// findPluginPID 在**指定插件目录下**找插件子进程 pid。
+//
+// root 参数是硬约束，不是可选过滤器：本函数的唯一用途是给崩溃隔离
+// 测试提供一个“可以安全 SIGKILL 的 pid”，而安全的定义就是它必须属于
+// 本测试自己的临时目录。不带这个约束就会误杀同机生产实例的插件。
+//
+// 匹配依据是 /proc/<pid>/exe 的真实路径必须以 root 为前缀。
+// 用 exe 而不用 cmdline：cmdline 可被进程自行改写，而 exe 符链由内核维护。
+// root 先过一道 EvalSymlinks：/tmp 在部分发行版上是符链（如 macOS 的
+// /tmp -> /private/tmp），不归一化会让前缀比较永远不命中，退化成静默 Skip。
+func findPluginPID(t *testing.T, root, name string) int {
 	t.Helper()
+	if root == "" {
+		t.Fatal("findPluginPID: root 不得为空（防止误杀全系统同名插件）")
+	}
+	realRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		realRoot = root
+	}
+
 	out, err := exec.Command("pgrep", "-f", "plugin.bin").Output()
 	if err != nil {
 		return 0
@@ -244,15 +285,18 @@ func findPluginPID(t *testing.T, name string) int {
 		if pid == 0 {
 			continue
 		}
-		// 校验 cwd 或 cmdline 含插件名
 		exe, err := os.Readlink(fmt.Sprintf("/proc/%d/exe", pid))
-		if err == nil && strings.Contains(exe, name) {
-			return pid
+		if err != nil {
+			continue
 		}
-		cwd, err := os.Readlink(fmt.Sprintf("/proc/%d/cwd", pid))
-		if err == nil && strings.Contains(cwd, name) {
-			return pid
+		// 两道条件同时成立才算命中：在本测试的目录树内，且是目标插件
+		if !strings.HasPrefix(exe, realRoot+string(os.PathSeparator)) {
+			continue
 		}
+		if !strings.Contains(exe, name) {
+			continue
+		}
+		return pid
 	}
 	return 0
 }

internal/plugins/remotedevice/registry.go

@@ -37,6 +37,24 @@ type DeviceMeta struct {
 type wconn struct {
 	deviceID string
 	w        *bufio.Writer
+	// wmu 序列化对该连接 bufio.Writer 的所有写。
+	//
+	// 两个角色会并发写同一连接：handleWS 主循环（读设备帧后的 hello_ack/
+	// bind_ack/pong 回写）与 PushJSON/PushData（agent→设备的下发路径，可能
+	// 来自任意 goroutine）。bufio.Writer 不是线程安全的，不加锁会在
+	// WriteByte/Flush 上产生 data race（生产实测触发）。
+	wmu sync.Mutex
+}
+
+// lockWrite 对 wconn 加写锁并返回 writer；调用方必须 defer unlockWrite。
+// 单独写成方法而不是直接暴露字段，避免调用方绕过锁。
+func (c *wconn) lockWrite() *bufio.Writer {
+	c.wmu.Lock()
+	return c.w
+}
+
+func (c *wconn) unlockWrite() {
+	c.wmu.Unlock()
 }
 
 // Registry 是设备接入网关的注册表：管理在线连接、设备元数据。线程安全。
@@ -319,7 +337,9 @@ func (r *Registry) PushJSON(deviceID string, payload map[string]interface{}) err
 	if !ok {
 		return fmt.Errorf("device %s not online", deviceID)
 	}
-	return writeText(c.w, mustJSON(payload))
+	w := c.lockWrite()
+	defer c.unlockWrite()
+	return writeText(w, mustJSON(payload))
 }
 
 // PushCmd 向设备发送命令执行请求。
@@ -348,7 +368,11 @@ func (r *Registry) PushData(deviceID, reqID, kind, mime string, data []byte) err
 	if !ok {
 		return fmt.Errorf("device %s not online", deviceID)
 	}
-	if err := writeText(c.w, mustJSON(map[string]interface{}{
+	// 整条下发（start + N 个 chunk + end）持锁：设备侧按协议串行聚合，
+	// 若中途被 handleWS 的 hello/pong 插帧会破坏协议顺序。
+	w := c.lockWrite()
+	defer c.unlockWrite()
+	if err := writeText(w, mustJSON(map[string]interface{}{
 		"op":     "cmd_speech_start",
 		"req_id": reqID,
 		"kind":   kind,
@@ -363,11 +387,11 @@ func (r *Registry) PushData(deviceID, reqID, kind, mime string, data []byte) err
 		if end > len(data) {
 			end = len(data)
 		}
-		if err := writeBinary(c.w, data[off:end]); err != nil {
+		if err := writeBinary(w, data[off:end]); err != nil {
 			return fmt.Errorf("push data chunk: %w", err)
 		}
 	}
-	if err := writeText(c.w, mustJSON(map[string]interface{}{
+	if err := writeText(w, mustJSON(map[string]interface{}{
 		"op":     "cmd_speech_end",
 		"req_id": reqID,
 	})); err != nil {
@@ -618,6 +642,26 @@ func (r *Registry) ServeWS(w http.ResponseWriter, req *http.Request) {
 	go r.handleWS(conn, rw)
 }
 
+// wsWriteLocked 在指定设备连接的写锁保护下执行写回调。
+//
+// handleWS 主循环与 Push* 是两条并发写同一 bufio.Writer 的路径，
+// 必须共用同一把锁。handleWS 里拿到的是 rw.Writer（与 conns 存储的是
+// 同一个对象），回写前必须经此函数取锁，否则跟 Push* 依然会撞。
+//
+// 注意设备已离线（conns 中已删除）时直接报错——设备断开后仍尝试
+// 回写没有意义，还可能在已关闭的 bufio 上写入。
+func (r *Registry) wsWriteLocked(deviceID string, fn func(w *bufio.Writer) error) error {
+	r.mu.RLock()
+	c, ok := r.conns[deviceID]
+	r.mu.RUnlock()
+	if !ok {
+		return fmt.Errorf("device %s not online", deviceID)
+	}
+	w := c.lockWrite()
+	defer c.unlockWrite()
+	return fn(w)
+}
+
 func (r *Registry) handleWS(conn net.Conn, rw *bufio.ReadWriter) {
 	defer conn.Close()
 	var curID string
@@ -635,7 +679,9 @@ func (r *Registry) handleWS(conn net.Conn, rw *bufio.ReadWriter) {
 		payload, isClose, opcode, err := readFrame(rw.Reader)
 		if err != nil {
 			if err == errPing {
-				if werr := writePong(rw.Writer); werr != nil {
+				// pong 也走写锁：它可能在 Push* 持锁推送大块数据时到达。
+				err := r.wsWriteLocked(curID, writePong)
+				if err != nil {
 					return
 				}
 				continue
@@ -679,11 +725,13 @@ func (r *Registry) handleWS(conn net.Conn, rw *bufio.ReadWriter) {
 			r.mu.Lock()
 			r.conns[meta.DeviceID] = &wconn{deviceID: meta.DeviceID, w: rw.Writer}
 			r.mu.Unlock()
-			if err := writeText(rw.Writer, mustJSON(map[string]interface{}{
-				"op":     "hello_ack",
-				"device": meta.DeviceID,
-				"online": true,
-			})); err != nil {
+			if err := r.wsWriteLocked(meta.DeviceID, func(w *bufio.Writer) error {
+				return writeText(w, mustJSON(map[string]interface{}{
+					"op":     "hello_ack",
+					"device": meta.DeviceID,
+					"online": true,
+				}))
+			}); err != nil {
 				return
 			}
 		case "bind":
@@ -694,11 +742,17 @@ func (r *Registry) handleWS(conn net.Conn, rw *bufio.ReadWriter) {
 					// 默认不授权：bind 仅验证 token + 登记设备；授权完全由用户手动
 					// （GUI 设备页 / REST /api/v1/device/auth）控制，绝不自动授权。
 				}
-				if err := writeText(rw.Writer, mustJSON(map[string]interface{}{"op": "bind_ack", "ok": true})); err != nil {
+				err := r.wsWriteLocked(curID, func(w *bufio.Writer) error {
+					return writeText(w, mustJSON(map[string]interface{}{"op": "bind_ack", "ok": true}))
+				})
+				if err != nil {
 					return
 				}
 			} else {
-				if err := writeText(rw.Writer, mustJSON(map[string]interface{}{"op": "bind_ack", "ok": false, "error": "bad token"})); err != nil {
+				err := r.wsWriteLocked(curID, func(w *bufio.Writer) error {
+					return writeText(w, mustJSON(map[string]interface{}{"op": "bind_ack", "ok": false, "error": "bad token"}))
+				})
+				if err != nil {
 					return
 				}
 			}