runtime: 建立跨 Subagent、Workflow 与 Background Terminal 的总资源准入合同

[tt-a1i]

一句话结论

OpenPI 的三类后台能力各自都有严谨的并发上限和并发预留，但它们互相看不见。一个 Session 可以同时占用 Direct Subagent、多个 Workflow run 和 Background Terminal 的全部局部额度。

建议研究 package-wide admission leases：各 owner 继续拥有自己的 lifecycle 和局部策略，共享层只负责总资源事实、排队/拒绝、释放和可观测性。不要把三种能力合并成一个 orchestration runtime。

固定证据

对比固定在：

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

OMP 当前提供了一个有用但不完整的参照：

• process/session 的 AsyncJobManager 统一登记 bash | task | eval，并带 owner identity、query/cancel、delivery 和总 running-job limit：job model, admission check
• task 另有 Session-scoped semaphore、request budget、wall-clock 和 recursion gate：task limits
• queued task job 不占 manager running slot，直到调用方 markRunning()；这说明 OMP 也不是完整的统一资源 governor，不能原样复制：queued boundary, mark running

OpenPI 当前：

• Direct Subagent 有两个独立 pool：普通 child 最多 4 个，by-the-way 最多 2 个；spawn 前同步 reserve，避免并发越限：pool admission, atomic reservation
• Background Terminal 独立最多 8 个，同样同步 reserve：terminal admission
• 每个 Workflow run 自己创建 semaphore，默认并发 8、最多 64；默认总 Agent call 128、最多 1024：run-local controller, configured limits
• 当前没有一个共享 admission owner 能回答“整个 OpenPI Session 正在使用多少 child model slots、process slots、memory/disk budget”。

为什么值得讨论

局部上限都正确，不代表组合后安全。典型风险包括：

• 两个并行 Workflow 各自使用 8 个 child，同时还有 4 个 Direct Subagent；
• 8 个 Background Terminal 全量写 spill log，同时 Workflow/child 写 artifacts；
• provider 并发、文件描述符、内存、worktree 和磁盘在多个 owner 间叠加；
• 某个能力排满资源后，其他更高优先级的交互式请求没有保留槽位；
• operator 只能看到各自列表，无法解释“为什么整套 Agent 变慢/被 429”。

这属于 runtime invariant，不应交给 prompt 提醒模型“少开一点”。

OpenPI 应保留的优势

• Subagent、Workflow、Background Terminal 仍各自拥有状态机、取消、清理和 artifacts；
• 不引入 OMP 式全局 Agent OS 或统一 job lifecycle；
• 模型仍决定 decomposition 和 fan-out；runtime 只接受、排队或拒绝；
• 普通回合保持 zero-resident，admission 不需要模型工具；
• setup 仍只有 /openpi-setup 一个入口。

建议的最小机制

先从 lease 接口研究，不预设全局 scheduler：

acquire({
  owner,
  kind: "model-session" | "process" | "worktree" | "artifact-bytes",
  units,
  signal,
}): Promise<Lease>

需要进一步决定：

• 是排队还是立即 fail closed；
• interactive Direct Subagent、Workflow child、terminal 的公平性/优先级；
• Session scope、process scope与 provider scope的边界；
• owner 丢失、abort、exception、resume 后如何回收 lease；
• live configuration 缩小时，已持有 lease 怎么处理；
• 是否需要 weighted units，而不只是任务数。

非目标

• 不把三套 manager 合并；
• 不让 admission 决定模型策略；
• 不根据任务关键词硬编码优先级；
• 不用一个“最大并发数”假装覆盖内存、磁盘和 provider rate limit；
• 不默认提高现有上限；
• 不依赖 prompt 释放资源。

完成条件

• 盘点三类能力所有可同时持有的 model/process/worktree/artifact 资源
• 定义 lease identity、owner、scope、acquire、release、abort 与 owner-lost 语义
• 并发 acquire 不可越过总上限，异常/取消路径不可泄漏 lease
• 多 Workflow run 与 Direct Subagent/Terminal 组合测试覆盖真实叠加
• operator 能读取总使用量、排队量和阻塞原因，模型不需要常驻新工具
• 局部上限继续生效，并明确它们与全局上限的优先关系
• 用压力场景验证 provider 429、内存、FD、磁盘和交互延迟是否改善
• 若单一 weighted governor 无法准确表达资源，拆成正交 leases 而不是强行统一

与现有 Issue 的关系

• Background Terminal：补齐模型输出清洗、session 磁盘预算与 Windows 终止验证 #72：Background Terminal 自己的 session 磁盘预算与终止验证
• Workflow 自适应 fan-out：按任务结构自由决定 Agent 规模，不引入固定数量策略 #75：Workflow 模型如何自主决定 fan-out
• workflows: agent startup (session creation + extension binding) is not abortable #116：Workflow child startup cancellation
• design: 研究跨能力的可恢复资源引用，但不引入 OpenPI 全局资源路由器 #157：跨 owner 的 artifact/resource 引用
• 本 Issue：执行资源的 package-wide admission，不改变 fan-out 判断或 artifact 寻址

[627150795]

I am taking a focused design slice: define a package-wide admission lease contract across Direct Subagents, Workflows, and Background Terminals. This pass will preserve each owner lifecycle and specify shared resource identity, acquire/release, cancellation, owner loss, rejection, and observability; it will not merge the managers or implement a global scheduler.

[627150795]

I opened #265 (#265) for the focused design slice. It defines package-wide admission leases for model sessions, processes, worktrees, and artifact bytes while preserving separate Subagent, Workflow, and Background Terminal lifecycles. The docs checks passed: git diff --check, bun run lint, and bun run typecheck. It does not add a scheduler or change current limits.

[tt-a1i]

补充 2026-09-08 对 ed9dbc1018f890fd54375f5371990ddfee8af5df 的源码核对：#159 的组合准入缺口仍然存在，建议第一步只解决 同一 Pi Session 内的 child model-session slots。

当前各上限的实际作用域

能力	当前限制	作用域
Workflow child	默认并发 8，最多配置 64；默认总调用 128，硬上限 1,024	每个 Workflow run
Direct Subagent	并发 4	当前 Subagent manager 的 model pool
用户 BTW aside	并发 2	同一 manager 内独立的 BTW pool
Background Terminal	running + pending + reserved 合计最多 8	当前 Terminal extension Session
Terminal spill	单 stream 256 MiB，Session 合计 512 MiB	Terminal 自己的日志资源

源码依据：

• Workflow 默认与硬上限。
• 每次 workflow 调用新建 RunController，每个 controller 创建自己的 semaphore。
• activeRuns 登记新的 run 后直接开始执行；当前这条启动路径没有跨 run 总准入上限。
• Direct 与 BTW 的独立池，各池计数及 reservation。
• Terminal 的运行/待投递联合准入，日志字节预算。

对组合使用意味着什么

按默认值，N 个同时运行的 Workflow，加上被使用的 Direct 与 BTW 池，可接纳 8N + 6 个 child slots。两个 Workflow 就是 22 个，另外仍可以有最多 8 个 Background Terminal。

这个数没有计算父 Session，也不代表 22 个 slot 每时每刻都在请求 provider；它描述的是运行时允许同时持有的 child 执行容量。把 Workflow concurrency 设为 8，并没有把整个 Session 限制在 8 个 child。

各局部 reservation、调用次数和取消回收机制已经存在，Terminal 也有自己的磁盘预算。缺少的是一个跨 Workflow / Direct / BTW 的共同 owner，约束同一 Session 实际持有多少 child slots。

这是源码层可确认的组合边界。此前的 HTTP 429 观测不能单凭这条证据归因于缺少全局预算；本轮没有新增模型压力测试或吞吐 Benchmark。

建议第一步的范围

先提供 Session 内的 model-session lease：Workflow child、Direct child、BTW 在真正获取 child 资源前申请，结束或取消后归还；各 manager 继续拥有自己的执行状态、清理、结果与 artifacts。

需要先明确 slot 生命周期是“活动 child 执行”，避免已完成但可续聊的 dormant Session 永久占槽。父交互请求与用户 BTW 的可用性也需要明确处理，不能因 Workflow 排队而无意被挤掉。

公平性与排队/拒绝语义应显式设计，不根据任务关键词决定优先级。具体总上限尚待选择，不能从当前默认 8 自动推导成全局默认值。

Process、worktree、artifact bytes 和 provider 级限制可以后续分别立项；不需要先把它们强行换算成一个加权总分，也不需要合并三套 manager。

最小可证伪验收

• 两个 Workflow + Direct + BTW 使用 fake child 同时争用一个测试设定的 Session slot 上限，任意时刻 held 不超过该上限，局部上限继续生效。
• 并发申请具有原子性；未获得 lease 的执行没有提前创建 child 资源。
• 排队取消、启动异常、child 终态、workflow_stop、Session shutdown、owner 丢失均回收 lease；重复释放不会增加可用容量。
• 明确 dormant child 的重新执行如何重新申请；模型/权限继承不因 shared admission 放宽。
• operator 可读到 held、queued 与阻塞原因；不要求模型新增常驻工具或持续轮询。
• 若新增用户可配置项，同步 /openpi-setup、状态输出、SETUP 与 README；若形成新的持久约束，保留对应 Decision。
• 确定性验收通过后再单独测 provider 错误率、交互延迟和资源峰值；这些指标改善之前不宣称性能收益已经验证。

本评论是范围建议和源码核对，不代表该机制已实现、已发布或已成为项目约束。

[tt-a1i]

2026-09-08 目录第二轮：provider 账单/额度不是本 Issue 的本地并发准入。

#159 仍只处理 Subagent / Workflow / Background Terminal 的 admission leases。账号额度 / 花费是否成为执行事实 → #511。

本轮未安装、未运行 pi-usage / pi-sub-bar。

[outlier27-cell]

I am taking the first implementation slice: Session-local admission for active child model-session execution slots across Workflow child, Direct Subagent, and BTW.

This preserves the existing per-Workflow limits and the Direct (4) / BTW (2) local pools, their lifecycle owners, permissions, and result delivery. It will be explicitly configured; it does not include Background Terminal, worktree, artifact bytes, provider cost/429 handling, global pause, LSP, memory, or a new orchestration runtime. I will use deterministic fake-child lifecycle tests and report the exact configuration/default contract and validation results in the PR.

[outlier27-cell]

Implementation PR for the claimed first slice: #617.

It adds an opt-in, top-level Pi Session admission limit for active Workflow / Direct Subagent / BTW child executions, while retaining each entry's local limits and lifecycle. It excludes Background Terminal, worktrees/artifacts, provider quota/cost/429 handling, and global orchestration.

Validation recorded in the PR: focused admission/lifecycle tests 36 passed; setup/config tests 46 passed; Web panel tests 17 passed; bun run check and git diff --check passed. The local full suite did not complete because existing real-Pi post-edit lifecycle tests timed out; that result is explicitly not claimed as green.