@agentunion/fastaun-browser 0.5.9 → 0.5.11

package/CHANGELOG.md

@@ -6,6 +6,70 @@
 
 ---
 
+## 0.5.11 — 2026-09-03
+
+### 新功能
+
+#### 消息来源与同步生命周期
+- P2P 消息、群消息、群事件、撤回和不可解密事件的应用 payload 新增 `source`，统一标识 `push`、`pull`、`inline_push` 或 `pending_retry`；`delivery.changed` 同步增加规范化 `source`。
+- 新增 `sync.started`、`sync.progress`、`sync.stopped` 生命周期事件。首次进入 Pull 时启动同步，每个 P2P/群 Pull page 完成后报告 namespace、页数、原始/已投递条数、`has_more`、`remaining`/估算剩余量，全部 Pull work 排空或中止时结束。
+- 同步事件继续经应用异步 FIFO 分发；并发 namespace 归入同一 run，Pull 失败、断线、关闭或身份代次重置以 `reason: "aborted"` 收口，不再把失败同步报告为正常排空。
+
+#### 连接后身份准入自愈
+- 每次 Gateway 连接成功后异步执行一次身份准入检查：普通 AID 缺少远端 agent.md 时复用本地内容或生成默认内容并补传。
+- 对当前 AID 作为群主的群逐个检查 group AID；缺少本地群证书/私钥时触发绑定并沿用绑定流程上传 group agent.md，已有群身份但远端缺少 group agent.md 时补传。检查失败只记录告警，不阻塞已建立的连接。
+
+### 修复
+
+#### 浏览器 Worker 与 CSP 兼容
+- Worker WebSocket 代理增加 `ready`/`open` 两阶段启动确认和超时；`worker-src 'none'` 等 CSP 导致的异步 `error`、启动无响应、open 前关闭均会销毁 Worker、撤销 Blob URL，并自动回退原生 WebSocket。
+- Worker 已连接后异常也可切换到原生 WebSocket，待发送请求会明确完成或失败；无 Worker 环境直接使用原生 WebSocket，应用事件仍由异步 dispatcher 隔离，避免 handler 阻塞网络处理。
+
+#### V2 消息兼容与来源保持
+- Tail/Forward/History 能识别 V1 wrapper 内的 `e2ee.p2p_encrypted` / `e2ee.group_encrypted` V2 envelope，并进入 V2 解密路径；群撤回在旧格式行中仍优先归一化为撤回事件。
+- ordered queue、sender IK 延迟恢复、inline realtime 和不可解密事件保持原始来源，避免补洞消息被误标为 push；群 Tail 同步进度仅由当前实例拥有的 cursor 产生。
+
+### 改进
+
+- SDK 包、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version`、conformance 及相关测试期望统一更新为 `0.5.11`。
+
+### 测试
+
+- 新增 Worker 正常可用、CSP 禁止 Blob Worker、无 Worker、异步启动失败、open 超时及运行中崩溃的单元与 Playwright 浏览器测试。
+- 扩展 `source`、`sync.*` 状态机、Pull 中止、分页进度、V1 wrapper 内 V2 envelope、连接后普通/群 agent.md 自愈及版本 conformance 测试。
+
+## 0.5.10 — 2026-09-02
+
+### 新功能
+
+#### `delivery.changed` 投递汇总
+- 新增应用事件 `delivery.changed`，覆盖 `push`、`inline_push` 和全局 Pull 排空（`pull_drained`）三类触发来源；payload 按 namespace 聚合 `deliveredCount`。
+- P2P 统一归入 `p2p` namespace，群消息按 canonical group AID 归一化；多页/并发/重复/空 Pull、ordered queue 和 inline push 均折叠为稳定的单次通知。
+- continuation、sender IK 延迟恢复和 ordered drain 均计入全局 Pull 保留量；全部排空后才发布 `pull_drained`，连接或身份代次切换会隔离旧结果，原消息事件先于汇总事件。
+
+### 修复
+
+#### 事件分发与生命周期
+- 应用事件改由单客户端 FIFO 异步队列分发，handler 不再阻塞网络或内部处理；单个 handler 异常隔离，`close()` 会排空已接受事件。
+- 支持 handler 内重入 RPC、Pull 和 `close()`，避免自等待死锁；trace/meta observer、断线回调及解密/状态事件也经过异步分发边界。
+
+#### WebSocket、Pull 与消息幂等
+- 浏览器 WebSocket 支持并发短 RPC、取消和超时；连接代次变化会丢弃旧事件并清理 pending，WebSocket 写入统一串行化。
+- 普通 Pull、P2P/群 V2 Pull、inline realtime、续拉和 ACK 提交纳入统一的 Pull 排空生命周期，旧代次不会继续发布、持久化或确认消息。
+- `message.send`/`group.send` preflight 自动生成 `messageId`，显式值保持不变；V2 重试、缓存 envelope 和底层 RPC 继续传递同一 ID，缺失响应 ID 时从请求回填。
+
+#### agent.md 与短 RPC 错误
+- 远端缺失的 agent.md 增加约 60 秒负缓存窗口，避免重复下载；短 RPC 错误保留服务端映射属性，便于调用方识别原始错误。
+
+### 改进
+
+- SDK 包、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version`、conformance 及相关测试期望统一更新为 `0.5.10`。
+
+### 测试
+
+- 新增 `delivery.changed` 单元、单域集成和浏览器 E2E 测试，覆盖 namespace 归一化、来源折叠、Pull 排空、ordered queue、inline push 和代次隔离。
+- 扩展异步 dispatcher、短 RPC 并发与取消、Pull 排空生命周期、messageId、agent.md 负缓存、错误映射及 observer/断线回调测试。
+
 ## 0.5.9 — 2026-08-31
 
 ### 安全性

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,70 @@
 
 ---
 
+## 0.5.11 — 2026-09-03
+
+### 新功能
+
+#### 消息来源与同步生命周期
+- P2P 消息、群消息、群事件、撤回和不可解密事件的应用 payload 新增 `source`，统一标识 `push`、`pull`、`inline_push` 或 `pending_retry`；`delivery.changed` 同步增加规范化 `source`。
+- 新增 `sync.started`、`sync.progress`、`sync.stopped` 生命周期事件。首次进入 Pull 时启动同步，每个 P2P/群 Pull page 完成后报告 namespace、页数、原始/已投递条数、`has_more`、`remaining`/估算剩余量，全部 Pull work 排空或中止时结束。
+- 同步事件继续经应用异步 FIFO 分发；并发 namespace 归入同一 run，Pull 失败、断线、关闭或身份代次重置以 `reason: "aborted"` 收口，不再把失败同步报告为正常排空。
+
+#### 连接后身份准入自愈
+- 每次 Gateway 连接成功后异步执行一次身份准入检查：普通 AID 缺少远端 agent.md 时复用本地内容或生成默认内容并补传。
+- 对当前 AID 作为群主的群逐个检查 group AID；缺少本地群证书/私钥时触发绑定并沿用绑定流程上传 group agent.md，已有群身份但远端缺少 group agent.md 时补传。检查失败只记录告警，不阻塞已建立的连接。
+
+### 修复
+
+#### 浏览器 Worker 与 CSP 兼容
+- Worker WebSocket 代理增加 `ready`/`open` 两阶段启动确认和超时；`worker-src 'none'` 等 CSP 导致的异步 `error`、启动无响应、open 前关闭均会销毁 Worker、撤销 Blob URL，并自动回退原生 WebSocket。
+- Worker 已连接后异常也可切换到原生 WebSocket，待发送请求会明确完成或失败；无 Worker 环境直接使用原生 WebSocket，应用事件仍由异步 dispatcher 隔离，避免 handler 阻塞网络处理。
+
+#### V2 消息兼容与来源保持
+- Tail/Forward/History 能识别 V1 wrapper 内的 `e2ee.p2p_encrypted` / `e2ee.group_encrypted` V2 envelope，并进入 V2 解密路径；群撤回在旧格式行中仍优先归一化为撤回事件。
+- ordered queue、sender IK 延迟恢复、inline realtime 和不可解密事件保持原始来源，避免补洞消息被误标为 push；群 Tail 同步进度仅由当前实例拥有的 cursor 产生。
+
+### 改进
+
+- SDK 包、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version`、conformance 及相关测试期望统一更新为 `0.5.11`。
+
+### 测试
+
+- 新增 Worker 正常可用、CSP 禁止 Blob Worker、无 Worker、异步启动失败、open 超时及运行中崩溃的单元与 Playwright 浏览器测试。
+- 扩展 `source`、`sync.*` 状态机、Pull 中止、分页进度、V1 wrapper 内 V2 envelope、连接后普通/群 agent.md 自愈及版本 conformance 测试。
+
+## 0.5.10 — 2026-09-02
+
+### 新功能
+
+#### `delivery.changed` 投递汇总
+- 新增应用事件 `delivery.changed`，覆盖 `push`、`inline_push` 和全局 Pull 排空（`pull_drained`）三类触发来源；payload 按 namespace 聚合 `deliveredCount`。
+- P2P 统一归入 `p2p` namespace，群消息按 canonical group AID 归一化；多页/并发/重复/空 Pull、ordered queue 和 inline push 均折叠为稳定的单次通知。
+- continuation、sender IK 延迟恢复和 ordered drain 均计入全局 Pull 保留量；全部排空后才发布 `pull_drained`，连接或身份代次切换会隔离旧结果，原消息事件先于汇总事件。
+
+### 修复
+
+#### 事件分发与生命周期
+- 应用事件改由单客户端 FIFO 异步队列分发，handler 不再阻塞网络或内部处理；单个 handler 异常隔离，`close()` 会排空已接受事件。
+- 支持 handler 内重入 RPC、Pull 和 `close()`，避免自等待死锁；trace/meta observer、断线回调及解密/状态事件也经过异步分发边界。
+
+#### WebSocket、Pull 与消息幂等
+- 浏览器 WebSocket 支持并发短 RPC、取消和超时；连接代次变化会丢弃旧事件并清理 pending，WebSocket 写入统一串行化。
+- 普通 Pull、P2P/群 V2 Pull、inline realtime、续拉和 ACK 提交纳入统一的 Pull 排空生命周期，旧代次不会继续发布、持久化或确认消息。
+- `message.send`/`group.send` preflight 自动生成 `messageId`，显式值保持不变；V2 重试、缓存 envelope 和底层 RPC 继续传递同一 ID，缺失响应 ID 时从请求回填。
+
+#### agent.md 与短 RPC 错误
+- 远端缺失的 agent.md 增加约 60 秒负缓存窗口，避免重复下载；短 RPC 错误保留服务端映射属性，便于调用方识别原始错误。
+
+### 改进
+
+- SDK 包、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version`、conformance 及相关测试期望统一更新为 `0.5.10`。
+
+### 测试
+
+- 新增 `delivery.changed` 单元、单域集成和浏览器 E2E 测试，覆盖 namespace 归一化、来源折叠、Pull 排空、ordered queue、inline push 和代次隔离。
+- 扩展异步 dispatcher、短 RPC 并发与取消、Pull 排空生命周期、messageId、agent.md 负缓存、错误映射及 observer/断线回调测试。
+
 ## 0.5.9 — 2026-08-31
 
 ### 安全性

package/_packed_docs/INDEX.md

@@ -30,7 +30,7 @@
 | [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、四 SDK 当前 access token getter、Python Push 自动登记/Facade、RPC 手册、E2EE、Storage VFS、Group FS 和 Collab 的子索引 |
 | [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md) | SDK 文档按行区间渐进式查阅方法 |
 | [AUN SDK 0.5.6 更新日志](sdk/CHANGELOG-0.5.6.md) | 以 0.5.5 为基线的四 SDK 发布汇总；覆盖首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 和语言能力边界 |
-| [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md) | 以 Python 实现为主线的 v0.3.3 至 v0.5.6 跨语言对齐清单；0.5.6 重点覆盖首次签名者发现、下载提交前验签、消息窗口、inline push、显式 change-seed 与语言能力边界 |
+| [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md) | 以 Python 实现为主线的 v0.3.3 至 v0.5.11 跨语言对齐清单；0.5.11 重点覆盖消息来源、sync 生命周期、连接后身份准入自愈、Worker 降级与 V1 wrapper 内 V2 envelope 兼容 |
 | [AUN CLI 手册](cli/CLI手册.md) | Python CLI 源码位置、安装运行入口、全局选项、profile 配置和主要命令集 |
 | [AUN CLI 设计文档](cli/AUN-CLI设计文档.md) | `python/src/aun_cli` 当前实现架构、命令注册面、配置解析、SDK 桥接和实现边界 |
 | [AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、下载 ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink、服务端分层和 direct backend 上传下载 |
@@ -86,7 +86,7 @@
 - 四 SDK 当前 access token getter、缓存快照语义和外部 HTTP 数据面下载凭据生命周期 → [连接与认证](sdk/04-连接与认证.md)、[API 手册](sdk/06-API手册.md)、[Storage RPC 手册](sdk/09-storage-rpc-manual.md)、[AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>)
 - 按主题和行区间查 SDK 文档 → [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md)
 - 四 SDK 0.5.6 发布摘要、首次签名者回源、可信缓存提交、消息窗口、语言能力边界 → [AUN SDK 0.5.6 更新日志](sdk/CHANGELOG-0.5.6.md)
-- 四 SDK 相对发布基线的实现级差异、代码/测试落点、对齐优先级、首次签名者发现、可信缓存和显式 change-seed 边界 → [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md)
+- 四 SDK 相对发布基线的实现级差异、代码/测试落点、对齐优先级、消息来源、sync 生命周期、身份准入自愈和 Worker 降级边界 → [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md)
 - Python CLI 源码位置、安装运行入口、全局选项、profile 配置、身份/消息/群组/Storage/Group FS/Collab/诊断等命令用法 → [AUN CLI 手册](cli/CLI手册.md)
 - Python CLI 当前实现架构、`main.py` 命令注册、`CLISession` SDK 桥接、配置解析和实现边界 → [AUN CLI 设计文档](cli/AUN-CLI设计文档.md)
 - Storage SDK VFS、控制面/数据面分离、下载 ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink、direct backend 上传下载和服务端分层 → [AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>)
@@ -222,7 +222,7 @@
 
 ### 四 SDK 版本对齐变更清单
 
-`python/CHANGES_FOR_PARITY.md` 以 Python SDK 历史实现为主线记录 Go / TypeScript / JavaScript 的对齐要求。v0.5.6 章节以 `ce56814a` 的 v0.5.5 为基线，区分四语言共有能力与 Python/Go/浏览器专属边界，并明确 `lookupPeer` 回源、`group.index` / `agent.md` 下载提交前验签、已验证缓存读取、消息窗口、inline push 和显式 change-seed 的一致性要求。
+`python/CHANGES_FOR_PARITY.md` 以 Python SDK 历史实现为主线记录 Go / TypeScript / JavaScript 的对齐要求。当前 v0.5.11 章节以 `8abb1d7d` 的 v0.5.10 为基线，区分四语言共有能力与 JS/TS Worker 专属边界，并明确消息来源、sync 生命周期、连接后身份准入自愈、V1 wrapper 内 V2 envelope 兼容和分页进度的一致性要求。
 
 ### AUN CLI 手册
 

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -102,7 +102,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | SDK API、RPC、E2EE、Storage VFS、Group FS、Collab GC/reflog/reset 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
 | 四 SDK 当前 access token getter、缓存快照语义和外部 HTTP 数据面下载凭据生命周期 | `docs/sdk/04-连接与认证.md` L94-123、`docs/sdk/06-API手册.md` L192-209、`docs/sdk/09-storage-rpc-manual.md` L621-663、`docs/sdk/09-group-rpc-manual.md` L1448-1452、`docs/aun-fs/AUN Storage架构设计.md` L153-166 |
 | 四 SDK 0.5.6 发布摘要、验签缓存、消息窗口与语言能力边界 | `docs/sdk/CHANGELOG-0.5.6.md` L1-73 |
-| 四 SDK 版本差异、跨语言对齐优先级、验签缓存与 change-seed 边界 | `python/CHANGES_FOR_PARITY.md` L11-110 |
+| 四 SDK 版本差异、跨语言对齐优先级、消息来源、sync 生命周期、身份准入自愈与 Worker 降级边界 | `python/CHANGES_FOR_PARITY.md` L11-101 |
 | 群 `mention_mode` 提及过滤、Agent 自主行为、SDK group.index facade 和 CAS 冲突处理 | `docs/protocol/10-Group-子协议.md`、`docs/protocol/13-Agent行为规范.md`、`docs/sdk/09-group-rpc-manual.md`、`docs/sdk/07-错误处理.md` |
 | AUN Python CLI 源码位置、安装入口、全局选项、profile 配置和主要命令集 | `docs/cli/CLI手册.md` L3-333 |
 | AUN Python CLI 当前实现架构、命令注册、SDK 桥接和实现边界 | `docs/cli/AUN-CLI设计文档.md` L3-265 |

package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md

@@ -206,11 +206,12 @@ print(client.can_connect, client.can_send, client.is_online)
 | `connection.error` | 连接、认证、重连错误 |
 | `token.refreshed` | token 自动刷新完成 |
 | `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token，下一次重连会重新走完整登录 |
-| `message.received` | 收到消息 |
-| `group.changed` | 群组事件 |
-| `message.undecryptable` / `group.message_undecryptable` | E2EE 解密失败 |
-
-建议在 `connect()` 前注册事件处理器。
+| `message.received` | 收到消息 |
+| `group.changed` | 群组事件 |
+| `message.undecryptable` / `group.message_undecryptable` | E2EE 解密失败 |
+| `delivery.changed` | SDK 本地批量交付完成通知，用于合并 UI 刷新（完整契约见 [06-API手册](06-API手册.md#deliverychanged)） |
+
+建议在 `connect()` 前注册事件处理器。
 
 ---
 

package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md

@@ -734,17 +734,111 @@ sub.unsubscribe()
 | `connection.error` | 连接或重连错误 |
 | `token.refreshed` | token 刷新完成 |
 | `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token 并等待重新登录 |
-| `message.received` | 收到 P2P 消息 |
-| `message.ack` | 消息 ack |
-| `message.undecryptable` | P2P E2EE 解密失败 |
-| `group.changed` | 群组事件 |
+| `message.received` | 收到 P2P 消息 |
+| `message.ack` | 消息 ack |
+| `message.undecryptable` | P2P E2EE 解密失败 |
+| `group.message_created` | 收到群消息 |
+| `group.changed` | 群组事件 |
+| `group.message_recalled` | 群消息撤回 |
 | `group.message_undecryptable` | 群 E2EE 解密失败 |
+| `sync.started` / `sync.progress` / `sync.stopped` | Pull 同步生命周期 |
+| `delivery.changed` | SDK 本地批量交付完成通知，用于合并应用层 UI 刷新 |
 | `push.offline_message` | Push Server 收到离线唤醒批次；普通终端无需订阅 |
 | `storage.object_changed` | Storage 对象变更事件透传 |
-
----
-
-## E2EE 高级 API
+
+### delivery.changed
+
+`delivery.changed` 是 Python、Go、JavaScript 和 TypeScript SDK 统一提供的本地事件，用于通知应用层一批消息已经完成交付，可以从业务仓库刷新相关会话 UI。它不替代 `message.received` / `group.message_created`：应用仍应逐条处理和持久化原消息事件，再把 `delivery.changed` 作为批量刷新信号。
+
+该事件由 SDK 本地 dispatcher 发布，不是 Gateway 推送事件，不属于 JSON-RPC `event/...` 协议；裸 WebSocket 客户端不会收到它。
+
+**Payload**：
+
+```json
+{
+    "trigger": "pull_drained",
+    "changes": [
+        {"namespace": "group:team.agentid.pub", "delivered_count": 50},
+        {"namespace": "p2p", "delivered_count": 3}
+    ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `trigger` | string | `pull_drained`、`push` 或 `inline_push` |
+| `changes` | array | 本次刷新涉及的 namespace，按 `namespace` 稳定排序且不重复 |
+| `changes[].namespace` | string | P2P 固定为 `p2p`；群消息为 `group:<canonical-group-aid>` |
+| `changes[].delivered_count` | integer | 本次合并窗口内已发布到应用层的原消息事件数；不是未读数、服务端页大小或最大 seq |
+
+触发与折叠规则：
+
+- `pull_drained`：当前 `AUNClient` 上所有已排队或正在执行的 Pull 工作，包括后续分页、continuation、gap fill 和缺失 Sender IK 的延迟补齐，全部排空后最多发布一次。一次通知可以同时包含 P2P 和多个群 namespace，不会按 Pull 页或单个 namespace 分别通知。
+- `push` / `inline_push`：有效实时消息在对应的 `message.received` / `group.message_created` 事件处理完成后通知；同一次有序队列 drain 放行的同类实时消息折叠为一次通知。
+- 有效的 `push` / `inline_push` 可以原子吸收尚未通知的 Pull 变更；这些变更不会在后续 `pull_drained` 中再次通知。
+- 空 Pull、重复或过滤消息、非法 payload、解密失败，以及未带来有效消息交付的 Head 通知，不发布 `delivery.changed`。
+
+`delivery.changed` 只表示 UI 刷新时机，不是消息明细或持久化账本。应用仓库仍应按照原消息事件的 `(namespace, message_id)` 做幂等，并按 `seq` 排序。
+
+### 消息来源 `source`
+
+消息、群消息、群事件、撤回和不可解密事件的 payload 可能带有顶层 `source`，用于区分 SDK 的投递来源：
+
+| `source` | 含义 |
+|----------|------|
+| `push` | 普通实时推送 |
+| `pull` | Pull、Tail、Forward 或群事件补洞 |
+| `inline_push` | 已在连续窗口内直接消费的实时载荷 |
+| `pending_retry` | 缺失 Sender IK 后延迟恢复的消息 |
+
+直接由应用或无来源内部调用产生的事件不强行添加 `source`。`source` 位于应用事件 payload 顶层，不改变业务 `payload` 内的数据结构；应用应将其视为保留字段。
+
+### Pull 同步生命周期
+
+四个 SDK 均通过本地 dispatcher 发布以下异步生命周期事件；它们不是 Gateway 的 `event/...` 消息，应用 handler 不会阻塞网络 reader。
+
+`sync.started` 在本次 Pull 的第一个 namespace 开始时发布一次：
+
+```json
+{
+    "run_id": 7,
+    "source": "pull",
+    "syncing": true,
+    "namespaces_pending": 1,
+    "namespace": "p2p",
+    "received_total": 0,
+    "started_at": 1730000000000
+}
+```
+
+每完成一页消息或群事件的处理、提交和有序投递，发布一次 `sync.progress`。`page_raw_count` 是本页有效原始条数，`page_pulled_count` 是本页实际投递条数；`pulled_count` / `received_total` 是本次 namespace 的累计投递数。服务端返回合法非负整数时透传 `remaining`，并同步设置 `estimated_remaining`；否则仅在协议可推导时提供估算值。
+
+```json
+{
+    "run_id": 7,
+    "source": "pull",
+    "namespace": "p2p",
+    "page": 2,
+    "page_raw_count": 50,
+    "page_pulled_count": 48,
+    "pulled_count": 98,
+    "received_total": 98,
+    "batch_size": 48,
+    "has_more": true,
+    "remaining": 102,
+    "estimated_remaining": 102
+}
+```
+
+当所有 namespace、续页、gap fill、ordered drain 和延迟 Sender IK 任务均排空时发布一次 `sync.stopped`。正常终态使用 `reason: "pull_drained"`；异常、取消、断线或连接/身份代次失效使用 `reason: "aborted"`。`sync.stopped` 描述同步生命周期终点，`delivery.changed(trigger="pull_drained")` 只汇总实际投递变化；空 Pull 可以有前者而没有后者。
+
+### JS/TS Worker 降级
+
+JavaScript 浏览器 SDK 的 Worker 是网络隔离增强：`new Worker()` 同步失败、CSP `worker-src` 阻止、Worker 启动后未及时 `open` 或异步崩溃时，SDK 会销毁 Worker 并回退原生 WebSocket。TypeScript Node.js SDK 在 `worker_threads` 不可用、启动超时或 Network Actor 崩溃时回退本地 transport。两种降级均保留异步 dispatcher 和 Pull 生命周期语义，不要求应用改变消息处理代码。
+
+---
+
+## E2EE 高级 API
 
 普通业务无需直接操作 E2EE manager；`message.send` / `group.send` 默认加密并自动解密收到的消息。
 

package/_packed_docs/sdk/09-group-rpc-manual.md

@@ -1899,9 +1899,24 @@ SDK 收到新 Head 后自动同步最新消息页并逐条解密；若 A 与 T
 }
 ```
 
-SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。当前仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `mention_mode` 等字段；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
-
-### event/group.message_recalled
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。当前仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `mention_mode` 等字段；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
+
+### delivery.changed
+
+成功交付 `group.message_created` 后，四个 SDK 会通过本地 `delivery.changed` 事件通知应用合并刷新群会话 UI。群变更项使用 canonical group AID：
+
+```json
+{
+    "trigger": "pull_drained",
+    "changes": [
+        {"namespace": "group:g-abc123.agentid.pub", "delivered_count": 50}
+    ]
+}
+```
+
+该事件不是服务端 `event/group.*`。多个群和 P2P 的 Pull 共用当前 `AUNClient` 的全局排空边界，因此一次 `pull_drained` 可以包含多个 `group:<canonical-group-aid>` 和 `p2p` 变更；有效 Push / Inline Push 则在原群消息事件处理完成后实时通知。完整 payload、折叠和零通知条件见 [06-API手册：delivery.changed](06-API手册.md#deliverychanged)。
+
+### event/group.message_recalled
 
 群消息撤回后推送给所有在线成员（与 pull 双 tombstone 兜底互补）。在线 push 是实时通道，双 tombstone 是离线 / 未读 / push 丢失时的可靠性兜底；两者最终一致，SDK 去重保证应用层只感知一次。
 

package/_packed_docs/sdk/09-message-rpc-manual.md

@@ -42,10 +42,11 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 
 ## 事件索引
 
-| 事件 | 说明 |
-|------|------|
-| [event/message.received](#eventmessagereceived) | 收到新消息 |
-| [event/message.recalled](#eventmessagerecalled) | 消息被撤回 |
+| 事件 | 说明 |
+|------|------|
+| [event/message.received](#eventmessagereceived) | 收到新消息 |
+| [event/message.recalled](#eventmessagerecalled) | 消息被撤回 |
+| [delivery.changed](#deliverychanged) | SDK 本地批量交付完成通知，用于合并 UI 刷新 |
 
 ---
 
@@ -598,12 +599,35 @@ SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；信封字段
 ### 订阅
 
 ```python
-client.on("message.received", lambda msg: print(msg["payload"]))
-```
-
----
-
-## event/message.recalled
+client.on("message.received", lambda msg: print(msg["payload"]))
+```
+
+---
+
+## delivery.changed
+
+`delivery.changed` 是四个 SDK 的本地事件，不是 Message 服务或 Gateway 发送的 `event/...`。应用仍通过 `message.received` 逐条接收和保存 P2P 消息，再使用该事件合并刷新 UI。
+
+```json
+{
+    "trigger": "pull_drained",
+    "changes": [
+        {"namespace": "p2p", "delivered_count": 50}
+    ]
+}
+```
+
+- 多页自动 Pull 不按页通知；当前 `AUNClient` 的所有 Pull 工作排空后，最多发布一次 `pull_drained`。
+- 有效 Push / Inline Push 在原消息事件处理完成后分别以 `push` / `inline_push` 通知；同一次有序队列 drain 内的同类消息会折叠。
+- 实时通知可以吸收尚未通知的 Pull 变更，后续不会再为同一批变更发布 `pull_drained`。
+- 空页、重复或过滤消息、非法 payload、解密失败及没有交付消息的 Head 通知不产生该事件。
+- `delivered_count` 是合并窗口内已经发布的原消息事件数，不表示当前未读总数。
+
+Pull 全局排空、群 namespace 和完整字段定义见 [06-API手册：delivery.changed](06-API手册.md#deliverychanged)。
+
+---
+
+## event/message.recalled
 
 消息被发送方撤回时推送给**接收方**。
 

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -32,7 +32,7 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 - E2EE：默认加密、ProtectedHeaders、P2P / Group V2
 - RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
 - 离线推送：Python `connect()` 的 `push_notify_aid/push_token`、`client.push.register/unregister`、Push Server ACK
-- 消息同步：A/T/H、Tail、Forward、History、页内唯一有序发布、应用层跨页幂等排序、每个 AUNClient 一个 Pull Gate（P2P Message/Group Message/Group Event Pull 共享，始终单飞、相同 key 折叠、不同 key 排队、前台 FIFO 优先）、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进
+- 消息同步：A/T/H、Tail、Forward、History、页内唯一有序发布、应用层跨页幂等排序、每个 AUNClient 一个 Pull Gate（P2P Message/Group Message/Group Event Pull 共享，始终单飞、相同 key 折叠、不同 key 排队、前台 FIFO 优先）、`source` 来源、`sync.started/progress/stopped` 生命周期、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进
 - Storage：SDK VFS、direct backend 数据面、下载 ticket / AID Bearer 边界、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
 - Group RPC：群提及过滤 `mention_mode`、`group_aid` / `group_id` 兼容、`group.index` 签名索引、`_meta.group_indexes`、`check/get/updateGroupIndex`、`expected_index_etag` CAS（见 `09-group-rpc-manual.md`、`06-API手册.md`）
 - 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
@@ -55,7 +55,7 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 | 03 | [核心概念](03-核心概念.md) | AID、A/T/H、Pull Gate、状态机、E2EE |
 | 04 | [连接与认证](04-连接与认证.md) | AIDStore、默认 agent.md 自动上传、连接生命周期并发/取消、当前 access token getter、网关发现、事件、agent.md 校验和自动观察 |
 | 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、agent.md 版本提示、recipient wrap |
-| 06 | [API手册](06-API手册.md) | AIDStore / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 门面 / 事件 / RPC |
+| 06 | [API手册](06-API手册.md) | AIDStore / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 门面 / 消息来源与 Pull 同步生命周期 / 事件 / RPC |
 | 07 | [错误处理](07-错误处理.md) | Result、异常、错误码、重试 |
 | 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、AUNClient 级 Pull Gate（始终单飞）、测试数据 |
 | - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、数据面 HTTP 下载流程、ticket / AID Bearer 边界、跨 issuer 下载 |
@@ -80,6 +80,7 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 | 查方法签名、群组高层 facade 和 `aid_store` / `aidStore` | [06-API手册](06-API手册.md) |
 | 查消息或群组 RPC、群提及过滤 `mention_mode` | 对应 `09-*-rpc-manual.md`；`mention_mode` 详见 [09-group-rpc-manual.md](09-group-rpc-manual.md) |
 | 查 A/T/H、SDK 自动最新页同步与 AUNClient 级 Pull Gate | [03-核心概念.md](03-核心概念.md)、[08-最佳实践.md](08-最佳实践.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查消息事件 `source`、`sync.started/progress/stopped` 和 `delivery.changed` | [06-API手册](06-API手册.md) |
 | 查 History、Forward、Pull Gate、Group 成员可见性 floor 与 Piggy ACK | [09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
 | 查群组标识 `group_aid` / `group_id` 兼容规范 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
 | 查 group.index 签名索引、版本观察、不同步判断、CAS 更新和 facade | [03-核心概念.md](03-核心概念.md)、[06-API手册.md](06-API手册.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md)、[08-最佳实践.md](08-最佳实践.md) |

package/_packed_docs/sdk/INDEX.md

@@ -15,7 +15,7 @@
 | [04-连接与认证](04-连接与认证.md) | 注册加载 · 认证连接 · 当前 access token getter · Python Push 自动登记 · 网关发现 · 事件 · agent.md 自动观察 |
 | [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE V2 消息 · ProtectedHeaders · agent.md 版本提示 · recipient wrap |
 | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2 P2P/GROUP 明文与加密主链路 |
-| [06-API手册](06-API手册.md) | AIDStore · AID · AUNClient · 四 SDK access token getter · Python PushFacade · Message/Group History 门面 · 事件 · E2EE 高级 API · RPC 索引 |
+| [06-API手册](06-API手册.md) | AIDStore · AID · AUNClient · 四 SDK access token getter · Python PushFacade · Message/Group History 门面 · 消息来源与 Pull 同步生命周期 · 事件 · E2EE 高级 API · RPC 索引 |
 | [07-错误处理](07-错误处理.md) | Result · 错误类层级 · 错误码 · 重试 |
 | [08-最佳实践](08-最佳实践.md) | 幂等连接 · 消息同步/History · AUNClient 级 Pull Gate（始终单飞）· group.index · 测试数据保护 |
 | [09-payload-reference](09-payload-reference.md) | message / group / thought payload 格式 |
@@ -50,6 +50,7 @@
 - 九态状态机、device_id / slot_id 隔离键 → [03-核心概念](03-核心概念.md)
 - `connect()` 选项、长短连接、网关发现 → [04-连接与认证](04-连接与认证.md)
 - capability getter、事件、生命周期 API → [06-API手册](06-API手册.md)
+- 消息事件 `source`、`sync.started/progress/stopped`、`delivery.changed` → [06-API手册](06-API手册.md)
 - Capabilities 能力声明、`inline_realtime_payload_v1` 实时推送优化 → [02-WebSocket协议](02-WebSocket协议.md)、[CHANGELOG-0.5.6](CHANGELOG-0.5.6.md)
 - 裸 WebSocket 握手 → [02-WebSocket协议](02-WebSocket协议.md)
 

package/dist/agent-md.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-md.d.ts","sourceRoot":"","sources":["../src/agent-md.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-md.d.ts","sourceRoot":"","sources":["../src/agent-md.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAI/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAI3D,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACnE,MAAM,CAkBR;AAiJD,MAAM,MAAM,mBAAmB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,mBAAmB,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAkBF,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjD,gBAAgB,CAAC,EAAE,MAAM,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC;IAChD,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAC5D,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACpF,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACpF,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAqED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,qBAAqB,CAAU;IACvC,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,eAAe,CAAC,CAAkC;IAC1D,OAAO,CAAC,iBAAiB,CAAC,CAA+B;IACzD,OAAO,CAAC,gBAAgB,CAAC,CAA4C;IACrE,OAAO,CAAC,aAAa,CAAC,CAAuE;IAC7F,OAAO,CAAC,oBAAoB,CAAC,CAAgE;IAC7F,OAAO,CAAC,aAAa,CAAC,CAAwB;IAC9C,OAAO,CAAC,MAAM,CAAmD;IACjE,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,cAAc,CAA0B;IAChD,OAAO,CAAC,cAAc,CAAyC;IAC/D,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,kBAAkB,CAAK;gBAEnB,IAAI,EAAE,qBAAqB;IAcvC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKjC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAU/B,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAiDjE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,SAA0B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAoDlG,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiFpE,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAK,EAAE,YAAY,SAAK,EAAE,MAAM,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBlF,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBzE,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCjD,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IA4B/F,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKhD,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAgChE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;WAkCnF,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAM1D,OAAO,CAAC,MAAM,CAAC,cAAc;IAO7B,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAQhC,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;YAIL,eAAe;YAIf,YAAY;YAaZ,YAAY;IAM1B,OAAO,CAAC,IAAI;YAIE,WAAW;YAqDX,aAAa;YA+Cb,KAAK;YAkCL,YAAY;YAeZ,aAAa;YAgBb,SAAS;IAavB,OAAO,CAAC,gBAAgB;YAaV,oBAAoB;YASpB,mBAAmB;YAWnB,gBAAgB;YAShB,uBAAuB;CAoBtC"}

package/dist/agent-md.js

@@ -24,6 +24,7 @@ export function buildDefaultAgentMd(aid, options = {}) {
     ].join('\n');
 }
 const HEAD_HTTP_TIMEOUT_MS = 15_000;
+const AGENT_MD_NEGATIVE_CACHE_TTL_MS = 60_000;
 const noopLogger = {
     error: () => { },
     warn: () => { },
@@ -385,6 +386,24 @@ export class AgentMdManager {
                 ttl_days: Number(ttlDays) || 0,
             };
         }
+        const remoteMissingCached = String(before.remote_status ?? '').trim().toLowerCase() === 'missing';
+        if (!localFound && !remoteEtagCached && remoteMissingCached && AgentMdManager.checkedAtFresh(checkedAtCached, ttlDays)) {
+            return {
+                aid: target,
+                local_found: false,
+                remote_found: false,
+                local_etag: '',
+                remote_etag: '',
+                in_sync: false,
+                needs_update: false,
+                last_modified: '',
+                status: 404,
+                cached: true,
+                verify_status: '',
+                verify_error: '',
+                ttl_days: Number(ttlDays) || 0,
+            };
+        }
         const now = Date.now();
         let remote;
         try {
@@ -912,6 +931,10 @@ export class AgentMdManager {
         const target = String(aid ?? '').trim();
         if (!target || await this._hasLocalContent(target, record))
             return;
+        const cached = record ?? await this.loadRecord(target) ?? {};
+        const checkedAt = Number(cached.checked_at ?? 0) || 0;
+        if (String(cached.remote_status ?? '').trim().toLowerCase() === 'missing' && checkedAt > 0 && Date.now() - checkedAt <= AGENT_MD_NEGATIVE_CACHE_TTL_MS)
+            return;
         if (this._fetchInflight.has(target))
             return;
         this._fetchInflight.add(target);
@@ -921,7 +944,6 @@ export class AgentMdManager {
         catch (err) {
             await this.saveRecord(target, {
                 last_error: err instanceof Error ? err.message : String(err),
-                remote_status: 'found',
             });
             this._log.debug(`agent.md auto fetch failed: aid=${target} source=${source || '-'} err=${err instanceof Error ? err.message : String(err)}`);
         }