@quecue/dev-notify 0.2.3 → 0.2.5

package/CHANGELOG.en.md

@@ -2,6 +2,20 @@
 
 English | [简体中文](CHANGELOG.md)
 
+## 0.2.5 — 2026-11-07
+
+- Distinguish Telegram `getMe` failures during reply-button preparation, bridge unreadiness, and notification-delivery failures. Retain bounded API error codes and report safe delivery categories and API-acknowledged part counts, without exposing underlying exceptions or server bodies. Do not infer exact send error codes discarded by the communication library.
+- Add isolated regressions for Telegram failure with successful buttonless Feishu delivery, bridge unreadiness with ordinary delivery on both channels, and recovery with buttons on both channels. No new retries, replays, or authorization.
+- Cover explicit channel rejection, unknown exceptions, and successful API delivery followed by local message-mapping failure without incorrectly claiming non-delivery or resending. Windows x64 / Node 24 totals 247 tests: 246 passed, 0 failed, and 1 opt-in native credential test skipped; not macOS real-machine acceptance.
+- This release improves diagnostics; it does not establish or fix the specific cause of historical missing notifications on any particular device.
+
+## 0.2.4 — 2026-11-07
+
+- Recover valid bot locks belonging to confirmed exited processes so a crashed reply bridge does not permanently remove Reply to Claude buttons. Live processes, reused PIDs, unknown permissions, and damaged locks are not preempted; concurrent recovery is serialized.
+- Maintain an independent bridge heartbeat and distinguish process liveness from readiness. Bound startup waiting at 15 seconds and ignore errors left by an exited instance while a new instance starts.
+- Restore an authorized but stopped bridge during `update` maintenance; wait for the old process to exit rather than treating a stale heartbeat as an exit. After npm installation, verify the current entry's package version and report a mismatch instead of maintaining hooks from an old Node/npm installation.
+- Add dead-lock, concurrent recovery, actual isolated child-process termination, heartbeat, stale-error, and update-maintenance regressions. Current totals: 237 tests, 236 passed and 1 opt-in native credential test skipped; not acceptance on every platform.
+
 ## 0.2.3 — 2026-11-07
 
 - Change `@quecue/notify-core` from exact `0.1.0` to the compatible range `^0.1.0`, allowing stable releases `>=0.1.0 <0.2.0`. The lockfile still pins the tested `0.1.0`; update package validation and tests accordingly. This does not change the published `0.2.2`.

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 简体中文 | [English](CHANGELOG.en.md)
 
+## 0.2.5 — 2026-11-07
+
+- 区分回复按钮的 Telegram `getMe` 身份查询失败、桥接未就绪与通知投递失败；保留有界 API 错误码，投递失败显示安全分类及 API 确认分段数，不输出底层异常或服务端正文。通讯库未保留的具体发送错误码不会猜测。
+- 补充 Telegram 失败而飞书成功且无按钮、桥接未就绪仍发送双渠道普通通知、恢复后双渠道带按钮的隔离回归；不新增重试、补发或授权。
+- 补充渠道明确拒绝、未知异常和 API 成功但本地消息映射失败的回归，避免误报未送达或重复发送。Windows x64／Node 24 共 247 项测试：246 通过、0 失败、1 项显式原生凭据测试跳过；不代表 macOS 实机验收。
+- 本版改进故障诊断，不代表已确认或修复某台设备历史漏发的具体根因。
+
+## 0.2.4 — 2026-11-07
+
+- 修复回复桥接异常退出后残留 Bot 锁导致通知不再出现“回复 Claude”按钮：仅回收格式有效且已确认进程退出的锁；活进程、PID 复用、权限未知或损坏锁均不抢占，并串行化并发恢复。
+- 独立续写桥接心跳，区分“进程存活”和“就绪”；启动等待延长为有界 15 秒，不再被上次已退出实例的错误提前中断。
+- `update` 维护恢复已授权但未运行的桥接；重启前等待旧进程真正退出，而非依据过期心跳提前启动。npm 安装结束后核验当前入口对应的包版本，若更新了另一 Node/npm 安装则明确失败，不从旧入口改写 hooks。
+- 新增死亡锁、并发恢复、真实隔离子进程强杀、心跳、旧错误及升级维护回归；当前共 237 项测试，236 通过、1 项显式原生凭据测试跳过，不代表所有平台实机验收。
+
 ## 0.2.3 — 2026-11-07
 
 - 将 `@quecue/notify-core` 依赖由精确 `0.1.0` 改为兼容范围 `^0.1.0`，允许 `>=0.1.0 <0.2.0` 的稳定版本。锁文件仍固定已验证的 `0.1.0`；同步发布校验和测试。此调整不改变已发布的 `0.2.2`。

package/README.en.md

@@ -53,7 +53,7 @@ dev-notify update --yes     # skip confirmation (suitable for scripts)
 dev-notify update --no-post # update the package only, skip hooks/bridge maintenance
 ```
 
-Actual integrity verification, registry configuration, permission handling, and native dependency resolution are still handled by npm. After a successful install, `update` automatically reinstalls the Claude Code hooks bound to the current configuration (when they exist and the configuration matches) and restarts a running reply bridge; use `--no-post` to skip this when not needed. As of 0.1.3, `update` performs the same maintenance even when already up to date, so the same command can complete post-upgrade cleanup.
+Actual integrity verification, registry configuration, permission handling, and native dependency resolution are still handled by npm. Version 0.2.4 verifies that the current command entry matches the target version after installation. If npm updated another Node/npm installation, it reports a mismatch instead of maintaining from the old entry. Once verified, `update` reinstalls Claude Code hooks bound to the current configuration (when they exist and match) and restores or restarts the authorized reply bridge; use `--no-post` to skip. As of 0.1.3, `update` performs the same maintenance even when already up to date, so the same command can complete post-upgrade cleanup.
 
 ## Features
 
@@ -172,11 +172,11 @@ dev-notify reply disable    # revoke authorization and request stop after confir
 dev-notify reply run        # start in the foreground to diagnose startup/network issues; do not run in parallel with a start instance
 ```
 
-Stop sends a request through a control file with a random instance identifier and does not force-kill based on an old PID. System input that has already started cannot be withdrawn. `status` reflects only the local process and heartbeat; Telegram end-to-end and real Claude still require separate acceptance.
+Stop sends a request through a control file with a random instance identifier and does not force-kill based on an old PID. System input that has already started cannot be withdrawn. Version 0.2.4 maintains an independent heartbeat and separates liveness from readiness: an expired heartbeat is not an exited process. Startup waits at most 15 seconds and is not interrupted by an exited instance's old error. `status` still reflects only local state; Telegram end-to-end and real Claude require separate acceptance.
 
 Authorization is in `<notification config>.reply.json`; messages/sessions/offset/queue/interaction state in `<notification config>.reply-data/`; the bot lock in `reply-bots/` under the data directory shown by `paths`. Queued reply text, questions, tool input, and answers pending return are briefly written to local state; normal reply text is removed before submission; structured interactions are retained until completion or confirmation timeout, after which question, argument, and answer text are cleared, while result receipts and message IDs are retained briefly for feedback and for rejecting old buttons. Validity checks are logical decisions only; files are not automatically erased after shutdown. POSIX uses 0700/0600; Windows relies on account directory ACLs; other processes of the same user can still read them. Do not commit, share, or package these files (already added to ignore rules and kept out of the npm whitelist).
 
-Force-kill may leave locks; first confirm that the relevant bridge/writer process has exited, then handle residual locks manually, and do not delete them while the process is running. `reply disable` does not delete historical state on its own; to clear it, first disable or stop, then manually delete the dedicated files after confirmation. Clearing credentials, removing hooks, and deleting reply state are three independent operations.
+Force-kill may leave locks. Version 0.2.4 can recover a valid bot lock at startup only after confirming its PID no longer exists. Unknown permissions, PIDs reused by a live process, damaged locks, and leftover `.recover` recovery gates fail closed. Other locks such as state-write locks are not recovered automatically; confirm their owning process has exited before handling them manually. Never delete a live process's lock. `reply disable` does not delete historical state on its own; to clear it, first disable or stop, then manually delete the dedicated files after confirmation. Clearing credentials, removing hooks, and deleting reply state are three independent operations.
 
 ## System credentials and compatibility
 
@@ -314,9 +314,9 @@ For other CLI examples, replace `dev-notify` with `node dist/cli.js`; no global
 
 `node-src/` is TypeScript source, `dist/` is compiled output, and `test-js/` is tests. Default tests use only fake credentials and mock backends/network; the local native fake-entry round-trip test requires explicitly setting `DEV_NOTIFY_NATIVE_TEST=1`, is enabled only on Windows, uses random IDs, and cleans up afterward.
 
-For the current 0.2.2 source, the package whitelist includes only this application's compiled CLI JavaScript, README, SECURITY, CHANGELOG, LICENSE and package.json. Library copies, tests, real configuration, ciphertext and dependency tarballs are excluded. npm resolves runtime dependencies separately. Published package contents depend on the corresponding version. There is no postinstall, auto-start, or self-written download script; prebuilt native dependencies are resolved by npm's platform optional packages, **do not use `--omit=optional`**. macOS x64/arm64 and Windows x64/arm64 prebuilt packages are provided by dependencies; providing packages does not mean this project has completed real-machine acceptance.
+For the 0.2.4 source, the package whitelist includes only this application's compiled CLI JavaScript, README, SECURITY, CHANGELOG, LICENSE and package.json. Library copies, tests, real configuration, ciphertext and dependency tarballs are excluded. npm resolves runtime dependencies separately. Published package contents depend on the corresponding version. There is no postinstall, auto-start, or self-written download script; prebuilt native dependencies are resolved by npm's platform optional packages, **do not use `--omit=optional`**. macOS x64/arm64 and Windows x64/arm64 prebuilt packages are provided by dependencies; providing packages does not mean this project has completed real-machine acceptance.
 
-See [CHANGELOG.en.md](CHANGELOG.en.md) for verification results of published versions. The regression record for this 0.2.2 source on Windows x64 with Node 24 is 219 tests: 218 passed, 0 failed, and 1 opt-in native credential test skipped. This record does not describe verification of the published npm package.
+See [CHANGELOG.en.md](CHANGELOG.en.md) for verification results of published versions. The regression record for the 0.2.4 source on Windows x64 with Node 24 is 237 tests: 236 passed, 0 failed, and 1 opt-in native credential test skipped. This record does not establish real-machine acceptance on every platform.
 
 Automated coverage includes temporary hooks, reply/authorization/expiry/anti-replay, single-select/multi-select/custom input, one-time permission JSON, two-sided races, feedback exceptions, and per-recipient duplicate reminder suppression. The actual CLI subprocess completes the loop of background start → PreToolUse registration → PermissionRequest → fake bot button → JSON answer → simulated PostToolUse → final feedback → notification deduplication/subsequent tool reminder → stop; this loop uses mock network and process metadata and cannot replace real-machine input verification. Automated tests for the Windows native input helper class only verify compilation/layout and do not perform a real Send.
 

package/README.md

@@ -53,7 +53,7 @@ dev-notify update --yes     # 跳过确认（适合脚本）
 dev-notify update --no-post # 只更新包，不执行 hooks/桥接维护
 ```
 
-实际的完整性校验、registry 配置、权限处理和原生依赖解析仍由 npm 完成。安装成功后，`update` 会自动重新安装绑定当前配置的 Claude Code hooks（已存在且配置匹配时），并重启正在运行的回复桥接；不需要时可用 `--no-post` 跳过。在 0.1.3 及以后，即使已经是最新版本，`update` 也会执行同样的维护，因此可以用同一条命令完成升级后的收尾。
+实际的完整性校验、registry 配置、权限处理和原生依赖解析仍由 npm 完成。0.2.4会在安装后核验当前命令入口确实对应目标版本；若 npm 更新了另一份 Node/npm 安装，会明确报错而不从旧入口维护。核验通过后，`update` 会重新安装绑定当前配置的 Claude Code hooks（已存在且配置匹配时），并恢复或重启已授权回复桥接；不需要时可用 `--no-post` 跳过。在 0.1.3 及以后，即使已经是最新版本，`update` 也会执行同样的维护，因此可以用同一条命令完成升级后的收尾。
 
 ## 已提供的功能
 
@@ -172,11 +172,11 @@ dev-notify reply disable    # 确认后撤销授权并请求停止；彻底关
 dev-notify reply run        # 前台诊断启动/网络问题，不与 start 实例并行
 ```
 
-停止通过实例随机标识的控制文件请求，不会根据旧 PID 强制结束进程。已经开始的系统输入无法撤回。`status` 只反映本地进程和心跳，Telegram 端到端和真实 Claude 仍需另行验收。
+停止通过实例随机标识的控制文件请求，不会根据旧 PID 强制结束进程。已经开始的系统输入无法撤回。0.2.4使用独立心跳区分进程存活与就绪；心跳过期不会被当作进程已退出，启动最多等待 15 秒且不被旧实例错误提前中断。`status` 仍只反映本地状态，Telegram 端到端和真实 Claude 需另行验收。
 
 授权在 `<通知配置>.reply.json`，消息/会话/offset/队列/交互状态在 `<通知配置>.reply-data/`；Bot 锁在 `paths` 所示 data 目录的 `reply-bots/`。排队回复原文、问题、工具输入和待回传答案会短暂写入本地状态；提交前会移除普通回复原文；结构化交互保留到完成或确认超时，随后清除问题、参数与答案正文，短期保留结果收据和消息 ID，用于反馈及拒绝旧按钮。有效期检查只是逻辑判断，停机后文件不会自动擦除。POSIX 使用 0700/0600，Windows 依赖账号目录 ACL；同一用户的其他进程仍然可以读取。请不要提交、共享或打包这些文件（已加入忽略规则及 npm 白名单）。
 
-强杀可能留下锁；请先确认相应桥接/写入进程已经退出，再手工处理残留锁，不要在进程运行中删除。`reply disable` 不会擅自删除历史状态；需要清除时，请先禁用或停止，确认后手工删除上述专属文件。清理凭据、移除 hooks 和删除回复状态是三项独立操作。
+强杀可能留下锁。0.2.4可在启动时自动回收有效 Bot 锁，但必须先确认原 PID 已不存在；权限未知、PID 复用为活进程、坏锁及残留 `.recover` 恢复门闩一律保守拒绝。状态写入锁等其他锁不自动回收，需先确认对应进程已退出再人工处理。不能在进程运行时删除锁。`reply disable` 不会擅自删除历史状态；需要清除时，请先禁用或停止，确认后手工删除上述专属文件。清理凭据、移除 hooks 和删除回复状态是三项独立操作。
 
 ## 系统凭据与兼容性
 
@@ -314,9 +314,9 @@ npm pack --dry-run
 
 `node-src/` 是 TypeScript 源码，`dist/` 是编译输出，`test-js/` 是测试。默认测试只用假凭据和模拟后端/网络；本机原生假条目往返测试需显式设置 `DEV_NOTIFY_NATIVE_TEST=1`，且只在 Windows 启用，使用随机 ID，结束后清理。
 
-当前 0.2.2 源码的 npm 白名单仅包含本应用 CLI 编译 JS、README、SECURITY、CHANGELOG、LICENSE 和 package.json；不包含通讯库副本、测试、真实配置、密文或依赖 tarball。运行时依赖由 npm 单独解析。已发布版本的包内容以对应版本为准。没有 postinstall、自动启动或自写下载脚本；预编译原生依赖由 npm 的平台 optional 包解析，**请勿使用 `--omit=optional`**。macOS x64/arm64 和 Windows x64/arm64 预编译包由依赖提供，提供包并不等同于本项目已完成实机验收。
+0.2.4 源码的 npm 白名单仅包含本应用 CLI 编译 JS、README、SECURITY、CHANGELOG、LICENSE 和 package.json；不包含通讯库副本、测试、真实配置、密文或依赖 tarball。运行时依赖由 npm 单独解析。已发布版本的包内容以对应版本为准。没有 postinstall、自动启动或自写下载脚本；预编译原生依赖由 npm 的平台 optional 包解析，**请勿使用 `--omit=optional`**。macOS x64/arm64 和 Windows x64/arm64 预编译包由依赖提供，提供包并不等同于本项目已完成实机验收。
 
-各已发布版本的验证结果见 [CHANGELOG.md](CHANGELOG.md)。当前 0.2.2 源码在 Windows x64、Node 24 下的回归记录为 219 项：218 通过、0 失败、1 项需显式启用的原生凭据测试跳过；该记录不代表已发布 npm 包的验证结果。
+各已发布版本的验证结果见 [CHANGELOG.md](CHANGELOG.md)。0.2.4 源码在 Windows x64、Node 24 下的回归记录为 237 项：236 通过、0 失败、1 项需显式启用的原生凭据测试跳过；该记录不代表所有平台的实机验收。
 
 自动化覆盖临时 hooks、回复/授权/过期/防重放、单选/多选/自定义、单次权限 JSON、双端竞争、反馈异常及按接收人的重复提醒去重。实际 CLI 子进程完成后台 start → PreToolUse 登记 → PermissionRequest → 假 Bot 按钮 → JSON 答案 → 模拟 PostToolUse → 最终反馈 → 通知去重/后续工具提醒 → stop；该闭环使用模拟网络和进程元数据，不能替代实机输入验证。Windows 原生输入帮助类的自动化测试只做编译/布局验证，不会执行真实 Send。
 

package/SECURITY.en.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](SECURITY.md)
 
-The npm package name is `@quecue/dev-notify`, with public source at [QueCue/dev-notify](https://github.com/QueCue/dev-notify). Published versions are authoritative on the npm registry; this document describes the dependency range and security boundaries of 0.2.3, and a source version alone does not establish that an installation package has been published. This project has not completed a security audit or real-machine acceptance on both platforms.
+The npm package name is `@quecue/dev-notify`, with public source at [QueCue/dev-notify](https://github.com/QueCue/dev-notify). Published versions are authoritative on the npm registry; this document describes the dependency range and security boundaries of 0.2.4, and a source version alone does not establish that an installation package has been published. This project has not completed a security audit or real-machine acceptance on both platforms.
 
 ## Communication dependency in current source
 
@@ -67,12 +67,12 @@ Reusing a dependency does not automatically share credentials or authorization,
 - Questions, options, tool arguments, reply text, and answers may contain sensitive information; after enabling, questions and the corresponding requests are sent to authorized private chats and configured Feishu, with no automatic redaction. Queued text, request input, answers pending return, and session paths are persistently written to dedicated local state; 0600/0700 cannot replace Windows ACL and cannot defend against same-user processes. Logical TTLs do not automatically erase files after power loss.
 - The dedicated files are `<config>.reply.json`, `<config>.reply-data/`, and the data directory `reply-bots/`, already added to ignore rules and not in the npm whitelist. Disabling does not delete historical state on its own; to clear it, disable and stop first, then confirm deletion of the dedicated files. The bot token exists only in system credentials, environment variables, or memory and is not written to reply state.
 - The bridge does not listen on ports or configure system auto-start. After user authorization, it can be started manually or on demand by hooks; it exits after 24 hours without updates, and also after 5 consecutive polling failures or a 409 conflict. It does not delete webhooks or force-kill old or other instances; cross-machine, cross-implementation bot exclusivity must be ensured by the user. This tool's lock only constrains instances that follow the same local lock directory.
-- Stop sends a control request using a random instance identifier and does not kill processes based on an old PID; stop does not revoke authorization, and later hooks may restart the bridge. Use disable for a complete shutdown; native calls cannot be withdrawn once started. Heartbeat/PID are only status snapshots; network connectivity needs separate verification; crash-residual locks require confirming that the process has exited before manual handling, and the program does not automatically seize locks.
+- Stop sends a control request using a random instance identifier and does not kill processes based on an old PID; stop does not revoke authorization, and later hooks may restart the bridge. Use disable for a complete shutdown; native calls cannot be withdrawn once started. Version 0.2.4 separates process liveness from heartbeat readiness; an expired heartbeat is not grounds for preemption. A valid bot lock is recovered only when its PID is confirmed absent, with an exclusive recovery gate serializing recovery. Live processes (including reused PIDs), unknown permissions, damaged locks, and leftover recovery gates fail closed; other locks such as state-write locks still require manual handling after exit confirmation. Heartbeat/PID remain status snapshots, not proof of network connectivity.
 
 ## npm and testing
 
 - Runtime has a native credential dependency, with the version and platform optional packages pinned in `package-lock.json`. Keep optional dependencies. There is no postinstall, self-written binary download, or background startup script.
-- For the current 0.2.2 source, the npm whitelist includes only this application's compiled CLI JS, README, SECURITY, CHANGELOG, LICENSE and package.json. Library copies, tests, real configuration, logs, ciphertext and dependency tarballs are excluded. Published versions are governed by their actual package contents.
+- For the 0.2.4 source, the npm whitelist includes only this application's compiled CLI JS, README, SECURITY, CHANGELOG, LICENSE and package.json. Library copies, tests, real configuration, logs, ciphertext and dependency tarballs are excluded. Published versions are governed by their actual package contents.
 - Third-party native packages carry their own licenses and Rust dependency declarations. Check the supply chain and licenses for releases and dependency upgrades; pinned versions are not equivalent to a completed audit.
 - Default tests use fake credentials, temporary directories, and mock system backends/network. `DEV_NOTIFY_NATIVE_TEST=1` explicitly enables Windows native tests, creates only fake entries with random IDs for this run, cleans up afterward, and does not read the user's existing entries.
 - npm uninstall does not automatically delete user configuration or credentials. To clean up, first run the interactive cleanup command; uninstall lifecycle scripts will not secretly manipulate the user's system storage.

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 简体中文 | [English](SECURITY.en.md)
 
-npm 包名为 `@quecue/dev-notify`，公开源码见 [QueCue/dev-notify](https://github.com/QueCue/dev-notify)。发布版本以 npm registry 为准，本文描述 0.2.3 的依赖范围与安全边界，不能仅依据源码版本认定安装包已发布。本项目尚未完成安全审计或双平台实机验收。
+npm 包名为 `@quecue/dev-notify`，公开源码见 [QueCue/dev-notify](https://github.com/QueCue/dev-notify)。发布版本以 npm registry 为准，本文描述 0.2.4 的依赖范围与安全边界，不能仅依据源码版本认定安装包已发布。本项目尚未完成安全审计或双平台实机验收。
 
 ## 当前源码的通讯层依赖
 
@@ -67,12 +67,12 @@ npm 包名为 `@quecue/dev-notify`，公开源码见 [QueCue/dev-notify](https:/
 - 问题、选项、工具参数、回复正文和答案可能包含敏感信息；启用后，问题和相应请求会发送到授权私聊及已配置飞书，无法自动脱敏。排队文本、请求输入、待回传答案及会话路径会持久写入专属本地状态；0600/0700 无法替代 Windows ACL，也无法防御同一用户的进程。逻辑 TTL 不会在断电后自动擦除文件。
 - 专属文件为 `<config>.reply.json`、`<config>.reply-data/` 与数据目录 `reply-bots/`，已加入忽略规则，且不在 npm 白名单中。禁用不会擅自删除历史状态；需要清除时，请先禁用并停止，再确认删除专属文件。Bot Token 只存在于系统凭据、环境变量或内存中，不会写入回复状态。
 - 桥接不监听端口，也不配置系统自启动。用户授权后可手动或由 hook 按需启动；24 小时没有更新会退出，连续轮询失败 5 次或遇到 409 冲突也会退出。不会删除 webhook，也不会强制结束旧版或其他实例；跨机器、跨实现的 Bot 独占需要由用户保证。本工具的锁只能约束遵守相同本地锁目录的实例。
-- stop 使用随机实例标识发送控制请求，不会依据旧 PID 结束进程；stop 不撤销授权，后续 hook 仍可重启。彻底关闭请使用 disable；原生调用一旦开始就无法撤回。心跳/PID 只是状态快照，网络连通性需要单独验证；崩溃残留的锁需要先核实进程已退出，再人工处理，程序不会自动抢占锁。
+- stop 使用随机实例标识发送控制请求，不会依据旧 PID 结束进程；stop 不撤销授权，后续 hook 仍可重启。彻底关闭请使用 disable；原生调用一旦开始就无法撤回。0.2.4区分进程存活和心跳就绪，心跳过期不作为抢占依据；有效 Bot 锁仅在原 PID 确认不存在时自动回收，并通过独占恢复门闩串行化。活进程（包括 PID 复用）、权限未知、坏锁和残留恢复门闩不抢占；状态写入锁等其他锁仍需人工确认后处理。心跳/PID 只是状态快照，网络连通性需单独验证。
 
 ## npm 与测试
 
 - 运行时有原生凭据依赖，版本和平台 optional 包锁定于 `package-lock.json`。请保留 optional 依赖。项目没有 postinstall、自写二进制下载或后台启动脚本。
-- 当前 0.2.2 源码的 npm 白名单仅包含本应用 CLI 编译 JS、README、SECURITY、CHANGELOG、LICENSE 和 package.json。通讯库副本、测试、真实配置、日志、密文及依赖 tarball 不进入发布包；已发布版本以实际包内容为准。
+- 0.2.4 源码的 npm 白名单仅包含本应用 CLI 编译 JS、README、SECURITY、CHANGELOG、LICENSE 和 package.json。通讯库副本、测试、真实配置、日志、密文及依赖 tarball 不进入发布包；已发布版本以实际包内容为准。
 - 第三方原生包带有其许可证与 Rust 依赖声明。发布及依赖升级时应核对供应链和许可；固定版本并不等同于完成审计。
 - 默认测试使用假凭据、临时目录和模拟系统后端、网络。`DEV_NOTIFY_NATIVE_TEST=1` 会显式开启 Windows 原生测试，只创建本次随机 ID 的假条目，结束后清理，不读取用户现有条目。
 - npm 卸载不会自动删除用户配置或凭据。需要清理时，请先运行交互清理命令；卸载生命周期脚本不会偷偷操作用户的系统存储。

package/dist/claude-hook.js

@@ -6,6 +6,7 @@ import { t } from './i18n.js';
 import { shouldNotify } from './notifications.js';
 import { transcriptEndTime } from './hook-time.js';
 import { findSessionName } from './reply-platform.js';
+import { ReplyPreparationError, safeDeliveryReason, safeFailureReason } from './notification-diagnostics.js';
 import { lifecycleHook, interactionHook, attachReply, mapReplies, notificationCoverage } from './reply-hooks.js';
 export const MAX_HOOK_BYTES = 8 * 1024 * 1024;
 export async function readHookInput(input = process.stdin, limit = MAX_HOOK_BYTES) {
@@ -139,8 +140,8 @@ export async function dispatchClaudeHook(bytes, configFile, context) {
     try {
         binding = await attachReply(notification, data, configFile, options);
     }
-    catch {
-        context.err(t('hook.replyNotReady'));
+    catch (error) {
+        context.err(error instanceof ReplyPreparationError ? error.message : t('hook.replyNotReady'));
     }
     let covered = { telegram: [], feishu: false };
     try {
@@ -168,10 +169,12 @@ export async function dispatchClaudeHook(bytes, configFile, context) {
                 mapReplies(plan, binding);
             const result = await context.send(plan, config);
             if (!result.ok)
-                context.err(t('hook.sendIncomplete', { channel }));
+                context.err(t('hook.sendIncompleteDetail', {
+                    channel, sent: result.sent, planned: result.planned, reason: safeDeliveryReason(result.error),
+                }));
         }
-        catch {
-            context.err(t('hook.sendFailed', { channel }));
+        catch (error) {
+            context.err(t('hook.sendFailedDetail', { channel, reason: safeFailureReason(error) }));
         }
     }
     if (!channels)

package/dist/cli.js

@@ -16,7 +16,7 @@ import { startBridge, stopBridge, bridgeStatus, runBridge } from './reply-bridge
 import { updatePackage } from './update.js';
 import { postUpdate } from './maintenance.js';
 import { localeName, parseLocale, resolveLocale, setLocale, t } from './i18n.js';
-export const VERSION = '0.2.3';
+export const VERSION = '0.2.5';
 const helpText = () => t('cli.help', { version: VERSION });
 function rawLang(argv) {
     for (let i = 0; i < argv.length; i++) {

package/dist/i18n.js

@@ -237,11 +237,12 @@ const zh = {
     'update.maintenanceNote': '将执行 Claude Code hooks 和回复桥接维护。',
     'update.versions': '当前版本 {current}，npm 最新版本 {latest}。',
     'update.checkHint': '运行 dev-notify update 更新。',
-    'update.postNote': '更新完成后会自动重新安装绑定当前配置的 Claude Code hooks，并重启正在运行的回复桥接；可用 --no-post 跳过。',
+    'update.postNote': '更新并核验命令入口后，会重新安装绑定当前配置的 Claude Code hooks，并恢复或重启已授权回复桥接；可用 --no-post 跳过。',
     'update.cancelled': '已取消，没有更新。',
     'update.running': '运行 npm install -g {name}@{latest} ...',
     'update.failed': '更新没有完成。请检查 npm 权限，或手动运行 npm install -g {name}@latest。',
     'update.updated': '已更新到 {latest}。请重新打开终端后运行 dev-notify --version 确认。',
+    'update.entryMismatch': 'npm 安装已结束，但当前命令入口未更新到 {latest}，可能使用了不同 Node/npm 安装目录。未从旧入口改写 hooks 或重启桥接。请在目标 Node 环境重新打开终端，核对 dev-notify --version 后运行 dev-notify update 完成维护。',
     'maintenance.runFailed': '无法运行更新后的 dev-notify。请重新打开终端后运行 dev-notify --version 检查。',
     'maintenance.reasonHint': '请运行 dev-notify integration claude-code status 或 dev-notify reply status 检查。',
     'maintenance.hooksCheckFailed': '无法检查 Claude Code hooks：{reason}',
@@ -253,6 +254,7 @@ const zh = {
     'maintenance.hooksFailedReason': 'Claude Code hooks 更新失败：{reason}',
     'maintenance.bridgeCheckFailed': '无法检查回复桥接：{reason}',
     'maintenance.restartingBridge': '重启回复桥接 ...',
+    'maintenance.startingBridge': '恢复已授权但未运行的回复桥接 ...',
     'maintenance.bridgeStillRunning': '回复桥接仍在退出，请稍后运行 dev-notify reply start。',
     'maintenance.bridgeRestarted': '回复桥接已重启。',
     'maintenance.bridgeStartFailed': '回复桥接启动失败。',
@@ -303,7 +305,16 @@ const zh = {
     'hook.notificationFallback': 'Claude Code 正在等待你的确认或输入，请回到终端处理。',
     'hook.interactionFailed': 'Claude Code 的回复状态或交互处理失败。没有自动选择答案或批准权限，请在本机处理。',
     'hook.sessionNameFailed': '读取不到 Claude Code 会话名称，通知底部将省略主题。',
-    'hook.replyNotReady': '远程回复还没有就绪，仍会尝试发送普通通知。',
+    'hook.replyNotReady': '回复按钮准备失败（会话、授权、本地状态或桥接检查）；仍会尝试向各渠道发送普通通知，不代表 Telegram 已送达。',
+    'hook.replyIdentityFailed': '回复按钮准备失败：Telegram getMe 身份查询失败（{reason}）；仍会尝试发送不带按钮的普通通知。',
+    'hook.sendIncompleteDetail': '{channel}：通知投递或发送后处理未全部完成（API 确认 {sent}/{planned} 段；{reason}）。整条消息不会自动重发。',
+    'hook.sendFailedDetail': '{channel}：通知发送流程失败（{reason}）。整条消息不会自动重发。',
+    'diagnostic.network': '网络请求失败或响应无效（可能为超时或连接异常，无法进一步区分）',
+    'diagnostic.rejected': '渠道明确拒绝请求（当前接口未保留具体错误码）',
+    'diagnostic.unknown': '原因未分类；为避免泄密，不显示底层错误',
+    'diagnostic.telegramCode': 'Telegram API 错误码 {code}',
+    'diagnostic.telegramUnknown': 'Telegram API 返回失败，错误码未知',
+    'diagnostic.httpCode': 'HTTP 状态码 {code}',
     'hook.coverageFailed': '没有核验到选择题通知的覆盖情况，将保留普通权限提醒。',
     'hook.sendIncomplete': '{channel}：Claude Code 通知没有完整发送。整条消息不会自动重发。',
     'hook.sendFailed': '{channel}：Claude Code 通知发送失败。请检查配置、系统凭据和网络；整条消息不会自动重发。',
@@ -477,7 +488,7 @@ const zh = {
     'reply.telegramRequestFailed': 'Telegram 桥接请求失败；不输出服务端正文或秘密',
     'reply.bridgeAuthFirst': '远程回复尚未授权，请先运行 reply setup。',
     'reply.bridgeNotAuthorized': '远程回复尚未授权。',
-    'reply.bridgeLocked': '当前用户已经有同一个 Bot 的桥接在运行，或残留了锁文件。请确认进程退出后，再处理 reply-bots 中对应的锁。',
+    'reply.bridgeLocked': '同一个 Bot 的桥接锁仍被占用，或不能安全确认其归属。仅确认进程已退出的有效残留锁会自动恢复；活进程、权限未知或损坏锁不会被抢占，请运行 reply status 检查。',
     'reply.webhookConflict': '这个 Bot 已经设置了 webhook，不能同时使用 getUpdates。请先移除 webhook；本工具不会自动删除。',
     'reply.pollFailedLog': 'Telegram 轮询失败；日志中没有记录密钥或服务端正文。',
     'reply.pollFailedFatal': 'Telegram 连续轮询失败 5 次，桥接已经退出。请检查网络、Token 或 API 冲突后重新启动。',
@@ -733,11 +744,12 @@ secrets are never written in plaintext.`,
     'update.maintenanceNote': 'Claude Code hooks and reply bridge maintenance will run.',
     'update.versions': 'Current version {current}; latest npm version {latest}.',
     'update.checkHint': 'Run dev-notify update to update.',
-    'update.postNote': 'After updating, Claude Code hooks bound to the current configuration will be reinstalled and a running reply bridge restarted; use --no-post to skip.',
+    'update.postNote': 'After updating and verifying the command entry, Claude Code hooks bound to the current configuration will be reinstalled and the authorized reply bridge restored or restarted; use --no-post to skip.',
     'update.cancelled': 'Cancelled; no update was performed.',
     'update.running': 'Running npm install -g {name}@{latest} ...',
     'update.failed': 'The update did not complete. Check npm permissions, or run npm install -g {name}@latest manually.',
     'update.updated': 'Updated to {latest}. Reopen the terminal and run dev-notify --version to confirm.',
+    'update.entryMismatch': 'npm finished, but the current command entry was not updated to {latest}; different Node/npm installation directories may be in use. Hooks and the bridge were not maintained from the old entry. Reopen a terminal in the intended Node environment, verify dev-notify --version, then run dev-notify update to finish maintenance.',
     'maintenance.runFailed': 'Could not run the updated dev-notify. Reopen the terminal and run dev-notify --version to check.',
     'maintenance.reasonHint': 'Run dev-notify integration claude-code status or dev-notify reply status to check.',
     'maintenance.hooksCheckFailed': 'Could not check Claude Code hooks: {reason}',
@@ -749,6 +761,7 @@ secrets are never written in plaintext.`,
     'maintenance.hooksFailedReason': 'Claude Code hooks update failed: {reason}',
     'maintenance.bridgeCheckFailed': 'Could not check the reply bridge: {reason}',
     'maintenance.restartingBridge': 'Restarting the reply bridge ...',
+    'maintenance.startingBridge': 'Restoring the authorized reply bridge that is not running ...',
     'maintenance.bridgeStillRunning': 'The reply bridge is still exiting; run dev-notify reply start later.',
     'maintenance.bridgeRestarted': 'Reply bridge restarted.',
     'maintenance.bridgeStartFailed': 'The reply bridge failed to start.',
@@ -799,7 +812,16 @@ secrets are never written in plaintext.`,
     'hook.notificationFallback': 'Claude Code is waiting for your confirmation or input. Return to the terminal to handle it.',
     'hook.interactionFailed': 'Claude Code reply state or interaction handling failed. No answer or permission was selected automatically; handle it locally.',
     'hook.sessionNameFailed': 'Could not read the Claude Code session name; the topic will be omitted from the notification footer.',
-    'hook.replyNotReady': 'Remote replies are not ready yet; a normal notification will still be attempted.',
+    'hook.replyNotReady': 'Reply button preparation failed during session, authorization, local-state, or bridge checks; normal notifications will still be attempted on each channel. This does not mean Telegram delivery succeeded.',
+    'hook.replyIdentityFailed': 'Reply button preparation failed: Telegram getMe identity lookup failed ({reason}); normal notifications without buttons will still be attempted.',
+    'hook.sendIncompleteDetail': '{channel}: delivery or post-send processing did not fully complete (API acknowledged {sent}/{planned} parts; {reason}). The message will not be resent automatically.',
+    'hook.sendFailedDetail': '{channel}: notification sending failed ({reason}). The message will not be resent automatically.',
+    'diagnostic.network': 'Network request failed or response was invalid (possibly a timeout or connection failure; cannot distinguish further)',
+    'diagnostic.rejected': 'The channel explicitly rejected the request (the current interface does not retain its exact error code)',
+    'diagnostic.unknown': 'Unclassified reason; underlying error withheld to protect secrets',
+    'diagnostic.telegramCode': 'Telegram API error code {code}',
+    'diagnostic.telegramUnknown': 'Telegram API failed with an unknown error code',
+    'diagnostic.httpCode': 'HTTP status {code}',
     'hook.coverageFailed': 'Could not verify question-notification coverage; the general permission reminder will be kept.',
     'hook.sendIncomplete': '{channel}: the Claude Code notification was not fully sent. The message will not be resent automatically.',
     'hook.sendFailed': '{channel}: the Claude Code notification failed to send. Check configuration, system credentials, and network; the message will not be resent automatically.',
@@ -973,7 +995,7 @@ secrets are never written in plaintext.`,
     'reply.telegramRequestFailed': 'The Telegram bridge request failed; the server body and secrets are not printed',
     'reply.bridgeAuthFirst': 'Remote replies are not authorized yet. Run reply setup first.',
     'reply.bridgeNotAuthorized': 'Remote replies are not authorized yet.',
-    'reply.bridgeLocked': 'A bridge for the same bot is already running for this user, or a lock file was left behind. Confirm the process has exited, then handle the corresponding lock in reply-bots.',
+    'reply.bridgeLocked': 'The bridge lock for the same bot is occupied or its ownership cannot be verified safely. Only valid locks belonging to confirmed exited processes are recovered automatically; live processes, unknown permissions, and damaged locks are not preempted. Run reply status to check.',
     'reply.webhookConflict': 'This bot already has a webhook and cannot use getUpdates at the same time. Remove the webhook first; this tool will not delete it automatically.',
     'reply.pollFailedLog': 'Telegram polling failed; no secrets or server body are written to the log.',
     'reply.pollFailedFatal': 'Telegram polling failed 5 times in a row; the bridge has exited. Check the network, token, or API conflicts, then start it again.',

package/dist/maintenance.js

@@ -6,6 +6,7 @@ import { ConfigError } from './config.js';
 import { t } from './i18n.js';
 import { claudeCodeStatus } from './claude-code.js';
 import { bridgeStatus } from './reply-bridge.js';
+import { accessReplies } from './reply-state.js';
 function runCli(args) {
     const cli = fileURLToPath(new URL('./cli.js', import.meta.url));
     const result = spawnSync(process.execPath, [cli, ...args], { stdio: 'inherit', timeout: 300000 });
@@ -62,22 +63,34 @@ export async function postUpdate(options) {
         options.err(t('maintenance.bridgeCheckFailed', { reason: reason(error) }));
         failed = true;
     }
-    if (bridgeState?.running) {
-        options.out(t('maintenance.restartingBridge'));
+    let resume = bridgeState?.running === true;
+    if (bridgeState && !resume) {
         try {
-            // 0 表示已停止或本来未运行；1 表示停止请求已登记，下面等待进程释放锁。
-            run(['reply', 'stop', '--config', options.config]);
-            let stillRunning = true;
-            for (let i = 0; i < 20; i++) {
-                try {
-                    stillRunning = (await bridge()).running;
-                }
-                catch {
-                    break;
+            resume = await (options.authorized ?? (async () => !!await accessReplies(options.config, options.env)))();
+        }
+        catch (error) {
+            options.err(t('maintenance.bridgeCheckFailed', { reason: reason(error) }));
+            failed = true;
+        }
+    }
+    if (bridgeState && resume) {
+        options.out(t(bridgeState.running ? 'maintenance.restartingBridge' : 'maintenance.startingBridge'));
+        try {
+            let stillRunning = bridgeState.running;
+            if (stillRunning) {
+                // 心跳过期不等于进程退出；必须等待活进程真正退出，才启动新版本。
+                run(['reply', 'stop', '--config', options.config]);
+                for (let i = 0; i < 20; i++) {
+                    try {
+                        stillRunning = (await bridge()).running;
+                    }
+                    catch {
+                        break;
+                    }
+                    if (!stillRunning)
+                        break;
+                    await wait(500);
                 }
-                if (!stillRunning)
-                    break;
-                await wait(500);
             }
             if (stillRunning) {
                 options.err(t('maintenance.bridgeStillRunning'));

package/dist/notification-diagnostics.js

@@ -0,0 +1,41 @@
+import { HttpError, TelegramApiError, TransportError } from '@quecue/notify-core';
+import { ConfigError } from './config.js';
+import { t } from './i18n.js';
+// 仅保留类型和有界状态码；不输出底层异常、URL、Token 或服务端正文。
+export class TelegramRequestError extends ConfigError {
+    code;
+    constructor(code) {
+        super(t(code === 409 ? 'reply.telegramConflict' : 'reply.telegramRequestFailed'));
+        this.code = code;
+    }
+}
+export function safeFailureReason(error) {
+    if (error instanceof TelegramRequestError || error instanceof TelegramApiError) {
+        const code = error.code;
+        return Number.isSafeInteger(code) && code >= 100 && code <= 599
+            ? t('diagnostic.telegramCode', { code }) : t('diagnostic.telegramUnknown');
+    }
+    if (error instanceof HttpError) {
+        const code = error.status;
+        return Number.isSafeInteger(code) && code >= 100 && code <= 599
+            ? t('diagnostic.httpCode', { code }) : t('diagnostic.network');
+    }
+    if (error instanceof TransportError)
+        return t('diagnostic.network');
+    return t('diagnostic.unknown');
+}
+export class ReplyPreparationError extends ConfigError {
+    constructor(error) {
+        super(t('hook.replyIdentityFailed', { reason: safeFailureReason(error) }));
+    }
+}
+// 公共库目前只返回安全文本而非错误类型。仅匹配本地已知值，不转发任意字符串。
+export function safeDeliveryReason(error) {
+    for (const key of ['channels.network', 'channels.noResponse', 'channels.responseTooLarge', 'channels.notJsonObject']) {
+        if (error === t(key))
+            return t('diagnostic.network');
+    }
+    if (error === t('channels.rejected'))
+        return t('diagnostic.rejected');
+    return t('diagnostic.unknown');
+}

package/dist/reply-bridge.js

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { mkdir, open, unlink, realpath } from 'node:fs/promises';
+import { mkdir, unlink, realpath } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { randomBytes } from 'node:crypto';
@@ -8,6 +8,7 @@ import { appPaths, ConfigError, readConfigLanguage } from './config.js';
 import { resolveLocale, setLocale, t } from './i18n.js';
 import { accessReplies, atomicJson, readJson, replyDirectory, stateTransaction } from './reply-state.js';
 import { telegramApi } from './reply-telegram.js';
+import { acquireBotLock, processState } from './reply-lock.js';
 import { drainReplies, processUpdate } from './reply-engine.js';
 import { drainInteractionFeedback } from './reply-outcomes.js';
 const leasePath = (file) => path.join(replyDirectory(file), 'bridge.json');
@@ -15,18 +16,16 @@ const controlPath = (file) => path.join(replyDirectory(file), 'stop.json');
 function alive(pid) {
     if (!Number.isSafeInteger(pid) || Number(pid) <= 0)
         return false;
-    try {
-        process.kill(Number(pid), 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    // 权限不足不能当作已退出，否则升级维护可能提前启动第二个消费者。
+    return processState(Number(pid)) !== 'dead';
+}
+function statusOf(lease) {
+    const running = !!lease && alive(lease.pid);
+    const fresh = !!lease && Number.isFinite(lease.updated) && Date.now() - lease.updated < 30000 && lease.updated <= Date.now() + 10000;
+    return { running, ready: lease?.ready === true && running && fresh && !lease.error && processState(lease.pid) === 'alive', error: lease?.error };
 }
 export async function bridgeStatus(file) {
-    const lease = await readJson(leasePath(file));
-    const running = !!lease && alive(lease.pid) && Date.now() - lease.updated < 30000;
-    return { running, ready: !!lease?.ready && running, error: lease?.error };
+    return statusOf(await readJson(leasePath(file)));
 }
 export async function stopBridge(file) {
     const lease = await readJson(leasePath(file));
@@ -42,29 +41,30 @@ export async function stopBridge(file) {
     }
     return false;
 }
-export async function startBridge(file, env = process.env) {
+export async function startBridge(file, env = process.env, deps = {}) {
     const access = await accessReplies(file, env);
     if (!access)
         throw new ConfigError(t('reply.bridgeAuthFirst'));
-    const existing = await bridgeStatus(file);
+    const previous = await readJson(leasePath(file));
+    const existing = statusOf(previous);
     if (existing.running)
         return existing.ready;
     const node = await realpath(process.execPath), cli = await realpath(fileURLToPath(new URL('./cli.js', import.meta.url)));
     // 无 shell、无命令行秘密、无系统开机自启；worker 自己持有排他锁。
-    const child = spawn(node, [cli, 'reply', 'run', '--config', path.resolve(file)], {
+    const child = (deps.spawn ?? spawn)(node, [cli, 'reply', 'run', '--config', path.resolve(file)], {
         detached: true, windowsHide: true, shell: false, stdio: 'ignore', env: { ...process.env, ...env },
     });
-    let failed = false;
+    let failed = false, exited = false;
     child.once('error', () => { failed = true; });
+    child.once('exit', () => { exited = true; });
     child.unref();
-    for (let attempt = 0; attempt < 20; attempt++) {
-        await delay(150);
-        if (failed)
-            return false;
-        const status = await bridgeStatus(file);
-        if (status.ready)
+    // 实际网络启动可能超过3秒；只等待有界15秒，不因旧进程留下的error提前放弃。
+    for (let attempt = 0; attempt < 100; attempt++) {
+        await (deps.sleep ?? delay)(150);
+        const lease = await readJson(leasePath(file));
+        if (statusOf(lease).ready)
             return true;
-        if (status.error)
+        if (failed || exited || lease?.pid === child.pid && lease?.owner !== previous?.owner && lease?.error)
             return false;
     }
     return false;
@@ -74,19 +74,17 @@ export async function runBridge(file, options = {}) {
     let access = await accessReplies(file, env);
     if (!access)
         throw new ConfigError(t('reply.bridgeNotAuthorized'));
+    const heartbeatMs = options.heartbeatMs ?? 5000;
+    if (!Number.isSafeInteger(heartbeatMs) || heartbeatMs < 10 || heartbeatMs > 10000)
+        throw new ConfigError(t('reply.bridgeFailed'));
     const directory = replyDirectory(file);
     await mkdir(directory, { recursive: true, mode: 0o700 });
     const botDirectory = path.join(appPaths(process.platform, env).data, 'reply-bots');
     await mkdir(botDirectory, { recursive: true, mode: 0o700 });
     const lockPath = path.join(botDirectory, access.policy.bot + '.lock');
-    let lock;
-    try {
-        lock = await open(lockPath, 'wx', 0o600);
-    }
-    catch {
-        throw new ConfigError(t('reply.bridgeLocked'));
-    }
-    const owner = randomBytes(16).toString('hex'), lease = { pid: process.pid, owner, ready: false, updated: Date.now() };
+    const owner = randomBytes(16).toString('hex');
+    const lock = await acquireBotLock(lockPath, owner);
+    const lease = { pid: process.pid, owner, ready: false, updated: Date.now() };
     let stopping = false;
     const stop = () => { stopping = true; };
     process.on('SIGTERM', stop);
@@ -95,9 +93,27 @@ export async function runBridge(file, options = {}) {
     const log = options.log ?? (() => { });
     let lastActivity = Date.now();
     const isStopped = async () => stopping || options.stopped?.() === true || (await readJson(controlPath(file)))?.owner === owner;
+    let writes = Promise.resolve();
+    const saveLease = () => {
+        lease.updated = Date.now();
+        const snapshot = { ...lease };
+        const next = writes.then(() => atomicJson(leasePath(file), snapshot));
+        writes = next.catch(() => { });
+        return next;
+    };
+    let heartbeat;
+    let beating = false, heartbeatFailed = false;
+    const stopHeartbeat = () => { stopping = true; if (heartbeat)
+        clearInterval(heartbeat); };
     try {
-        await lock.writeFile(JSON.stringify({ pid: process.pid, owner }));
-        await atomicJson(leasePath(file), lease);
+        await saveLease();
+        heartbeat = setInterval(() => {
+            if (beating || stopping)
+                return;
+            beating = true;
+            void saveLease().catch(() => { heartbeatFailed = true; stopping = true; }).finally(() => { beating = false; });
+        }, heartbeatMs);
+        heartbeat.unref();
         let api = (options.api ?? (value => telegramApi(value.config.telegram.token)))(access);
         const webhook = await api('getWebhookInfo', {});
         if (webhook?.url)
@@ -114,8 +130,7 @@ export async function runBridge(file, options = {}) {
                 });
         }
         lease.ready = true;
-        lease.updated = Date.now();
-        await atomicJson(leasePath(file), lease);
+        await saveLease();
         let iteration = 0, failures = 0;
         while (!await isStopped() && iteration++ < (options.maxIterations ?? Infinity)) {
             // 桥接是长驻进程，语言切换后要跟着配置文件走；否则后续消息会和 hook 进程的语言不一致。
@@ -145,8 +160,7 @@ export async function runBridge(file, options = {}) {
                 log(t('reply.pollFailedLog'));
                 if (++failures >= 5)
                     throw new ConfigError(t('reply.pollFailedFatal'));
-                lease.updated = Date.now();
-                await atomicJson(leasePath(file), lease);
+                await saveLease();
                 await (options.sleep ?? delay)(3000);
                 continue;
             }
@@ -168,25 +182,32 @@ export async function runBridge(file, options = {}) {
             }
             if (updates.length)
                 lastActivity = Date.now();
-            lease.updated = Date.now();
-            await atomicJson(leasePath(file), lease);
+            await saveLease();
             if (Date.now() - lastActivity > 24 * 60 * 60 * 1000)
                 break;
         }
+        if (heartbeatFailed)
+            throw new ConfigError(t('reply.bridgeFailed'));
     }
     catch (error) {
+        stopHeartbeat();
         lease.ready = false;
         lease.error = error instanceof ConfigError ? error.message : t('reply.bridgeFailed');
-        await atomicJson(leasePath(file), lease).catch(() => { });
+        await saveLease().catch(() => { });
         throw error;
     }
     finally {
+        stopHeartbeat();
+        await writes;
         process.off('SIGTERM', stop);
         process.off('SIGINT', stop);
-        const current = await readJson(leasePath(file)).catch(() => null);
-        if (current?.owner === owner && !lease.error)
-            await unlink(leasePath(file)).catch(() => { });
-        await lock.close();
-        await unlink(lockPath);
+        try {
+            const current = await readJson(leasePath(file)).catch(() => null);
+            if (current?.owner === owner && !lease.error)
+                await unlink(leasePath(file)).catch(() => { });
+        }
+        finally {
+            await lock.release();
+        }
     }
 }

package/dist/reply-hooks.js

@@ -6,6 +6,7 @@ import { findSession } from './reply-platform.js';
 import { textHash } from './reply-engine.js';
 import { telegramApi, replyHint } from './reply-telegram.js';
 import { bridgeStatus, startBridge } from './reply-bridge.js';
+import { ReplyPreparationError } from './notification-diagnostics.js';
 import { createInteraction, questionsContent, showInteraction, waitInteraction } from './reply-interactions.js';
 import { makePlan, deliver } from './channels.js';
 import { completeToolCall, endSessionInteractions, finishInteraction, matchingCall, registerToolCall } from './reply-outcomes.js';
@@ -115,7 +116,14 @@ export async function attachReply(message, data, file, options = {}) {
         options.err?.(t('reply.bridgeNotReadyButton'));
         return null;
     }
-    const api = apiFor(access, options), bot = await api('getMe', {});
+    const api = apiFor(access, options);
+    let bot;
+    try {
+        bot = await api('getMe', {});
+    }
+    catch (error) {
+        throw new ReplyPreparationError(error);
+    }
     if (typeof bot?.username !== 'string' || !/^[A-Za-z0-9_]{5,64}$/.test(bot.username))
         throw new ConfigError(t('reply.botUsernameInvalid'));
     const token = randomBytes(16).toString('hex');

package/dist/reply-lock.js

@@ -0,0 +1,116 @@
+import { open, readFile, unlink, lstat } from 'node:fs/promises';
+import { ConfigError } from './config.js';
+import { t } from './i18n.js';
+export function processState(pid) {
+    try {
+        process.kill(pid, 0);
+        return 'alive';
+    }
+    catch (error) {
+        return error.code === 'ESRCH' ? 'dead' : 'unknown';
+    }
+}
+// 只有 ESRCH 可证明进程已退出；权限不足、PID复用、坏文件都不允许抢占。
+export async function acquireBotLock(file, owner, probe = processState) {
+    if (!/^[a-f0-9]{32}$/.test(owner))
+        throw new ConfigError(t('reply.bridgeLocked'));
+    const record = { pid: process.pid, owner };
+    const readRecord = async () => {
+        try {
+            const info = await lstat(file);
+            if (!info.isFile() || info.isSymbolicLink() || info.size > 4096)
+                throw new Error();
+            const value = JSON.parse(await readFile(file, 'utf8'));
+            if (!Number.isSafeInteger(value?.pid) || value.pid <= 0 || typeof value.owner !== 'string' ||
+                !/^[a-f0-9]{32}$/.test(value.owner))
+                throw new Error();
+            return value;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw new ConfigError(t('reply.bridgeLocked'));
+        }
+    };
+    const dead = (value) => {
+        if (!value)
+            return true;
+        try {
+            return probe(value.pid) === 'dead';
+        }
+        catch {
+            return false;
+        }
+    };
+    const create = async () => {
+        const handle = await open(file, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(record));
+            await handle.sync();
+        }
+        catch (error) {
+            try {
+                await handle.close();
+            }
+            finally {
+                await unlink(file);
+            }
+            throw error;
+        }
+        let released = false;
+        return { async release() {
+                if (released)
+                    return;
+                released = true;
+                try {
+                    const current = await readRecord();
+                    if (current?.pid === record.pid && current.owner === record.owner)
+                        await unlink(file);
+                }
+                finally {
+                    await handle.close();
+                }
+            } };
+    };
+    try {
+        return await create();
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw new ConfigError(t('reply.bridgeLocked'));
+    }
+    if (!dead(await readRecord()))
+        throw new ConfigError(t('reply.bridgeLocked'));
+    // 串行化“检查死亡→删除→重新创建”，两个恢复者不能误删对方的新锁。
+    // 恢复门闩自身若损坏或残留则保守拒绝，不递归猜测并抢锁。
+    const recoveryFile = file + '.recover';
+    let gate;
+    try {
+        gate = await open(recoveryFile, 'wx', 0o600);
+    }
+    catch {
+        throw new ConfigError(t('reply.bridgeLocked'));
+    }
+    try {
+        await gate.writeFile(JSON.stringify(record));
+        const current = await readRecord();
+        if (!dead(current))
+            throw new ConfigError(t('reply.bridgeLocked'));
+        if (current)
+            await unlink(file);
+        try {
+            return await create();
+        }
+        catch {
+            throw new ConfigError(t('reply.bridgeLocked'));
+        }
+    }
+    finally {
+        try {
+            await gate.close();
+        }
+        finally {
+            await unlink(recoveryFile);
+        }
+    }
+}

package/dist/reply-telegram.js

@@ -2,6 +2,7 @@ import { createTelegramApi, TelegramApiError } from '@quecue/notify-core';
 import { requestJson } from './channels.js';
 import { ConfigError } from './config.js';
 import { t } from './i18n.js';
+import { TelegramRequestError } from './notification-diagnostics.js';
 export function telegramApi(token, request = requestJson) {
     const call = createTelegramApi(token, { request });
     return async (method, payload) => {
@@ -12,9 +13,7 @@ export function telegramApi(token, request = requestJson) {
         }
         catch (error) {
             if (error instanceof TelegramApiError) {
-                if (error.code === 409)
-                    throw new ConfigError(t('reply.telegramConflict'));
-                throw new ConfigError(t('reply.telegramRequestFailed'));
+                throw new TelegramRequestError(error.code);
             }
             throw error;
         }

package/dist/update.js

@@ -1,4 +1,5 @@
 import { spawnSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
 import { ConfigError } from './config.js';
 import { t } from './i18n.js';
 import { terminalPrompts } from './prompts.js';
@@ -78,6 +79,15 @@ async function runMaintenance(options, updated) {
     options.out(t(updated ? 'update.postDoneUpdated' : 'update.postDone'));
     return 0;
 }
+async function currentEntryInstalled(expected) {
+    try {
+        const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+        return pkg.name === NAME && pkg.version === expected;
+    }
+    catch {
+        return false;
+    }
+}
 export async function updatePackage(current, options) {
     if (!VERSION.test(current))
         throw new ConfigError(t('update.currentFormat'));
@@ -107,6 +117,8 @@ export async function updatePackage(current, options) {
     const result = (options.runner ?? npmRunner)(['install', '-g', `${NAME}@${latest}`], false);
     if (result.status !== 0)
         throw new ConfigError(t('update.failed', { name: NAME }));
+    if (!await (options.installed ?? currentEntryInstalled)(latest))
+        throw new ConfigError(t('update.entryMismatch', { latest }));
     options.out(t('update.updated', { latest }));
     return await runMaintenance(options, true);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quecue/dev-notify",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "跨平台开发任务通知工具，支持 Telegram 与飞书",
   "license": "MIT",
   "repository": {