delivery: 统一后台完成事件的 owner 路由、epoch 与消费收据合同

[tt-a1i]

一句话结论

OpenPI 的 Direct Subagent、Background Terminal、Workflow 都已实现“完成后投递给父会话”，但分别维护三套 pending map、消费、重试、持久化与 wake 语义。

建议抽取一个薄的 completion inbox contract：生产者仍拥有终态和 artifact，inbox 只负责 owner 路由、generation/epoch、防重复消费、投递收据和 wake policy。不要把三套执行状态机合并。

固定证据

对比固定在：

• OpenPI main@2a69d3f32994da4123f1312b7fa84ef3d6119be1
• OMP main@151dc754e8cd9314721aa6c78a168a205a4b0e4c

OMP 当前：

• 每个 AgentSession 用自己的 agent id 注册 delivery sink，避免所有 completion 被硬路由到第一个 top-level Session：owner-routed contract
• delivery entry 带 Session generation；/new、switch、handoff 后旧 epoch 会被丢弃，即使 job id 被复用：epoch contract, format/enqueue fence
• owner sink late cleanup不会删除 revival 后的新 sink；没有 live owner 时 dead-letter，不会误投给其他 Session，结果仍暂存于 job row：sink replacement, dead-letter boundary
• sink 失败采用有界退避重试，成功后才消费结果：delivery receipt path

OpenPI 当前：

• Direct Subagent 使用内存 pending map；auto-delivery 与 explicit wait 谁先 drain 谁消费，delivery throw 会恢复批次：subagent delivery
• Background Terminal 使用另一套 pending map + idle batcher，并在 idle 时 followUp/triggerTurn、busy backlog 时 nextTurn：terminal pending, wake policy
• Workflow 有第三套 durable delivery plane：稳定 delivery id、per-run receipt、retry、restart restore；transport 成功但 receipt 落盘失败时采用 at-least-once recovery：workflow delivery contract, receipt/retry

为什么值得讨论

三条实现分别解决了真实竞态，但合同逐渐漂移：

• 只有 Workflow completion 可跨 process restart 恢复；
• Direct Subagent 会主动重新唤醒 parent，Terminal 对 busy backlog 选择 nextTurn；
• stable identity、attempt、receipt、dead-letter、owner-lost 的表达不同；
• Session switch / branch / resume 后 stale completion 的判定没有统一 epoch vocabulary；
• 修过的一类竞态需要在三条路径重新证明。

共享的应是 transport/inbox 不变量，不是 producer lifecycle。

OpenPI 应保留的优势

• WorkflowDetails、SubagentSnapshot、TerminalSnapshot 仍是各自 canonical execution facts；
• inbox 不从 UI label 推断完成；
• producer 自己决定何时 terminal、artifact 在哪里、取消如何结算；
• wake policy 可按 producer 和 client capability 配置，不统一成“一完成就强制起 turn”；
• fail closed：不确定 owner/epoch 时保留可检查状态，不误投。

建议的最小 envelope

示意：

type CompletionEnvelope = {
  deliveryId: string;
  ownerSessionId: string;
  ownerEpoch: number;
  producer: "subagent" | "workflow" | "background";
  producerId: string;
  terminalRef: unknown;
  wake: "follow-up" | "next-turn" | "producer-policy";
}

具体 API 需先确认 Pi 是否已有 completion/yield queue seam；若有，应扩展 Pi seam，而不是 OpenPI 自建第二个 Session mailbox。

必须明确的语义

• exactly-once 是“模型可见消费”还是 transport acceptance？崩溃窗口下能否真正保证？
• transport 成功、receipt 失败时是 at-least-once，并如何让模型识别 replay？
• explicit wait/status 与 automatic delivery 如何原子争抢消费权？
• owner Session switch、fork、resume、dispose、revive 时 epoch 如何变化？
• 无 live owner 是 dead-letter、durable pending，还是迁移到新 owner？
• client 不支持 agent-initiated turn 时如何降级为 next-turn/card？
• 一批 completion 部分成功时如何只重试未确认 sibling？

非目标

• 不统一三类执行状态机；
• 不把 producer result 内联进 inbox storage；
• 不声称分布式 exactly-once；
• 不让 completion 自动决定 Goal/Task 完成；
• 不强制所有 producer 采用相同 wake 行为；
• 不把 delivery success 当 execution success。

完成条件

• 明确 canonical execution、delivery envelope、model context、UI projection 四层边界
• envelope 有稳定 delivery id、owner identity、epoch、producer identity 和 terminal reference
• wait/status 与 auto-delivery 并发只产生一次模型可见消费
• transport/receipt 失败、process crash、session switch/resume、owner dispose/revive 全部有测试矩阵
• stale completion 不会进入新 transcript，结果仍可从 producer canonical state 找回
• partial batch receipt 只重试未确认 envelope
• wake policy 尊重 interactive/print/RPC/ACP client 能力
• 迁移后删除重复机制，不能在共享层外继续保留三套消费 gate

与现有 Issue 的关系

• 在进行code review双轨审查的时候主代理无法被后面完成的那个子代理唤醒 #47：双轨 review 的第二个 child 完成后未唤醒 parent，已关闭
• Workflow：终态持久化失败与完成通知失败会留下不可恢复的不一致 #71：Workflow 终态持久化与通知失败
• workflows: completion enqueued during in-flight flush can be stranded when delivery fails #107/workflows: persistence exception mid-batch drops later envelopes from in-memory retry queue #108/workflows: one failed restore() aborts entire session-start delivery reconciliation #109：Workflow delivery races，已关闭
• context: 研究可回收的探索 checkpoint/rewind，不把它等同于 context_pivot #154：探索 rewind 与 background completion 的交互
• 本 Issue：跨 producer 的 owner/epoch/receipt 共用合同

[627150795]

Hi! I would like to work on the documentation/design part of this issue.

I will define a thin completion-inbox contract across Direct Subagent, Background Terminal, and Workflow: producer ownership, destination Session, epoch, delivery identity, consumption receipts, wake policy, duplicate/crash handling, fork/resume boundaries, and at-least-once limits. I will not merge the three execution state machines or add a global task store in this contribution.

[627150795]

Update: the completion inbox contract is implemented in PR #254: #254

Validation completed: git diff --cached --check, bun run lint, and bun run typecheck passed. This is documentation-only; the three producer state machines and their owners remain unchanged, with no global task store or exactly-once claim. The PR uses the repository template and will close this issue when merged.

[testikun]

我来认领 #160 尚未落地的运行时代码阶段，不重复此前的 completion-inbox 设计文档。

技术方案：抽取只负责 transport/inbox 不变量的共享 primitive，并迁移 Direct Subagent、Workflow、Background Terminal 三条完成投递；producer 仍拥有终态、artifact、取消和恢复。envelope 具有稳定 delivery id、owner Session identity/epoch、producer identity、terminal reference 与 wake policy；wait/status 与 auto-delivery 原子争抢消费权，transport/receipt failure 可重试，stale epoch 不进入新 transcript，partial batch 只重试未确认项。不会合并三套执行状态机，也不宣称崩溃窗口下 exactly-once。

已完成：

• PR: delivery: unify background completion inbox contract #382
• 共享 pending/in-flight 消费门、ack/retry、owner/epoch fence 与可检查 dead letter
• 三类 producer 已迁移，原有 wake、canonical state 与 Workflow durable receipt 语义保留
• 同 Session restart 显式 revive；旧实例与跨 Session completion 不会进入新 transcript
• 设计记录：https://github.com/openpi-dev/openpi/blob/codex/issue-160-completion-inbox/docs/design/COMPLETION_INBOX.md

验证：

• bun run check：通过
• bun run test：1,253 passed / 0 failed / 1 skipped；Vitest 30 passed
• Node 22 全量：1,253 passed / 0 failed / 1 skipped；Vitest 30 passed
• shared inbox + Workflow delivery/lifecycle e2e 聚焦：40 passed / 0 failed

该 PR 不修改 UI，因此真实测试截图不适用。