swarm-kit

全系统唯一的并行编排工具 wave_run——合并谱系：

wave-orchestrator（waves/relay 分批接力、event-bus RPC seam）
   + fractal-swarm（强类型 Envelope 归并、审计打回、DEGRADED 终态、树状归并）
   → 跑在 pi-subagents 引擎上

被合并的两份实现已归档：~/code/_archive/wave-orchestrator.ts、~/code/_archive/fractal-swarm/。

运行

npm run typecheck   # tsc --noEmit
npm test            # 44 条：契约/审计/脚本生成/防漂移/mock 沙箱干跑 + verify 循环

扩展装载（已就位）：~/.pi/agent/extensions/swarm-kit → 本仓库（目录扩展，入口必须是根 index.ts）。 重启 pi 后生效；headless 冒烟：pi -p --no-builtin-tools -t wave_run "..."。

安装（发布后）

pi install npm:@maimaimai/swarm-kit   # 官方机制：写入 settings packages，无需 symlink
# 前置：Node ≥22.6、pi 已装、pi-subagents 已装（pi install npm:pi-subagents）
# 重启 pi 生效

备选（裸目录装载）：npm i -g @maimaimai/swarm-kit 后把包目录放进 ~/.pi/agent/extensions/swarm-kit（Windows 用 mklink /J 目录联接，无需管理员）。

wave_run 参数

旧参数不变：mode(waves|relay|verify) / agent / tasks(复数) / batchSize / model / concurrency / maxSpawns。

新增（默认开 envelope）：

| 参数 | 默认 | 说明 | |---|---|---| | envelope | true | 子任务按强类型信封输出，父脚本机械校验，不合格打回；false 退回旧版纯文本语义 | | audit_agent | 无 | 指定后归并前过模型对抗审查（不通过 → 打回修正，带审计理由）；与 envelope=false 互斥（参数报错） | | max_audit_retries | 2 | 契约/审计打回上限，超限标 DEGRADED 终态（防死循环） | | audit_sample_rate | 1 | 模型审计抽样率 | | verify_agent | verify 必填 | 沙箱执行者（需 bash/write 工具）；mode=verify 时只传 1 条总目标，失败回喂 ≤max_rounds 轮，未过 root=DEGRADED 禁落地 |

返回：旧字段 results[] 原样保留（兼容旧调用方）+ 新字段 root（树状归并信封：SUCCESS | FAILED | DEGRADED）。

实现要点

• 生成的 workflowScript 跑在 pi-subagents 沙箱：禁止嵌套 async 函数（打回/审计循环内联在主循环顶层 await）、无 import——运行时 helper 以内联纯函数注入
• src/envelope.ts/audit.ts 是宿主侧同构实现，test/script.test.ts 的防漂移断言锁住两者一致
• 超大 payload 自动转 artifact:// 引用（摘要+路径），保护上级上下文
• 打回用新 key（w0.r1/w0.a0/w0.ra1），不复用原 key（同 key 返回同一回执）

已验证

• 44/44 单测 + tsc 零错
• mock 沙箱干跑 8 条：一次过/打回超限 DEGRADED/修正后 SUCCESS/审计 3 轮耗尽/审计 PASS/子任务失败 FAILED/宽松模式/relay {{prev}}
• 真实冒烟 ×2：headless pi -p 下 2 任务 Envelope 归并全 SUCCESS；带 audit_agent 审计一次通过（子信封 confidence 0.95、error_context null）