feat(codex-bridge): notify origin on async completion

docs/solutions/developer-experience/codex-bridge-async-completion-notifications-2026-04-25.md

@@ -0,0 +1,85 @@
+---
+title: Codex Bridge 异步任务需要持久化完成通知状态
+date: 2026-04-25
+category: docs/solutions/developer-experience/
+module: Codex Bridge
+problem_type: developer_experience
+component: assistant
+severity: medium
+applies_when:
+  - 异步 agent 任务由本地 bridge 启动，但完成结果需要回到原平台会话
+  - 任务状态已经持久化，但缺少完成后主动送达能力
+  - 测试不能向真实外部平台发送消息
+tags: [codex-bridge, async-notification, app-server, send-message, watcher]
+---
+
+# Codex Bridge 异步任务需要持久化完成通知状态
+
+## Context
+
+Codex Bridge 已经通过 app-server stdio 启动 Codex 任务，并把状态写入 `codex_bridge.db`。dogfood 暴露出的体验问题是：异步任务完成后没有主动通知原 Feishu/平台会话，用户必须再次触发 Hermes 查询 `status` 或 `list` 才能知道结果。
+
+这类问题不需要先做多租户调度系统。MVP 的关键是让任务在启动时可选记录通知目标，并让一个 one-shot watcher 可以可靠地处理 terminal 任务。
+
+## Guidance
+
+在已有任务表上补齐三个概念，而不是重写底层通信协议：
+
+- `notify_target`：启动时可选记录目标，例如 `local` 或 `feishu:<chat_id>`。
+- `notification_status`：记录通知生命周期，例如 `pending`、`sent`、`failed`、`no_target`。
+- `notified_at` / `notification_error`：让 watcher 重启后能防重复，并保留失败原因。
+
+watcher 应该只扫描 terminal 状态任务，并做幂等处理：
+
+- 有目标：构造简洁完成摘要，调用可注入 notifier，成功后标记 `sent`。
+- 无目标：标记 `no_target`，不发送，避免每次扫描重复捞到同一任务。
+- dry-run：返回预览，不发送，也不写通知状态。
+
+默认 notifier 可以复用现有 `send_message` 能力，但核心 manager 方法要允许注入 notifier。这样单元测试可以用 fake notifier 验证行为，避免真实平台副作用。
+
+## Why This Matters
+
+异步 bridge 的产品承诺不是“能启动后台任务”，而是“任务结束后用户能在原上下文看到结果”。如果只有状态表但没有通知状态，系统会卡在“完成但无人查收”的灰区；如果没有持久化防重复，watcher 或 daemon 重启又可能重复推送。
+
+把通知状态做成任务元数据，可以在不引入 mailbox/outbox/inbox 通信机制的情况下满足 MVP，并为后续实时 approval / `requestUserInput` 扩展留下同一套 target 语义。
+
+## When to Apply
+
+- 异步任务生命周期已经持久化，但完成后需要跨平台送达。
+- 现有平台发送能力已经存在，新增功能只需要选择目标和调用发送。
+- 需要保证测试环境不触发真实外部消息。
+- 需要 watcher/daemon 重启后不重复通知。
+
+## Examples
+
+启动时记录目标：
+
+```python
+codex_bridge(
+    action="start",
+    prompt="Investigate the failing tests",
+    notify_target="feishu:chat-1",
+)
+```
+
+one-shot watcher dry-run：
+
+```bash
+python skills/codex-bridge/references/cli.py notify-completed --dry-run
+```
+
+测试中注入 notifier：
+
+```python
+deliveries = []
+manager.notify_completed(
+    notifier=lambda target, message: deliveries.append((target, message)) or {"ok": True}
+)
+```
+
+## Related
+
+- `docs/brainstorms/2026-04-25-codex-bridge-completion-notification-requirements.md`
+- `docs/plans/2026-04-25-codex-bridge-completion-notification-plan.md`
+- `tools/codex_bridge_tool.py`
+- `skills/codex-bridge/references/cli.py`