[nyx-cell]

Part of #147（四层全部合入才算关闭，单层不 Closes）。

Stack

四层自底向上：kit/discovery → kit/sessions → kit/leases → kit/room-web，四个 PR 全部 --base main。

下层 #150 kit/discovery 与 #151 kit/sessions 已合入（squash 为 14d6ab7 / 60fb524），本分支已 rebase 到新 main：GitHub diff 与 git diff main..kit/leases 即本层全部增量（21 files, +1050/−1076）。

本层专属提交（git log --oneline main..kit/leases）：

• 0c0919d feat(kit): replace task leases with @rivus/agent-kit-collab
• 73e6a52 fix(review): describe the kit lease architecture in overview

选定版本

• @rivus/agent-kit-collab@0.11.0——packages/agent-task-loop/package.json 新增 "@rivus/agent-kit-collab": "0.11.0"（exact，npm view 核对其 peer 为 effect: 4.0.1）。
• effect@4.0.1——exact dependency（collab 层引入）；lockfile 中 kit 两个包都 peer 解析到同一份 effect@4.0.1（@rivus/agent-kit@0.11.0(effect@4.0.1)、@rivus/agent-kit-collab@0.11.0(...(effect@4.0.1))）。
• 移除 @rivus/agent-orchestration: workspace:*（task-loop 的编排租约半边改走 kit；其 AgentRuntime 半边保留到 room-web 层）。

导入的 kit 子路径入口（git diff main..kit/leases）

子路径	使用处
@rivus/agent-kit-collab/lease	src/orchestration/lease.ts（新装配层）、src/task-manager/task-occupancy-service.ts、tests/orchestration/lease.test.ts
@rivus/agent-kit/node / @rivus/agent-kit/platform	lease.ts 与其测试（NodePlatformLive / 平台服务）

Summary

• task-occupancy-service.ts 重写：createLeaseManager({ ttlMs: 120_000, heartbeatMs }) + 作用域 manager.acquire(key)（Effect.scoped）；handle.lost 与 workflow Effect.raceFirst 竞速；mutationFence 走 handle.runFenced（不可取消写用 Effect.uninterruptible 包 tryPromise）。TaskOccupancyContext.signal/mutationFence 接口语义保留，二次启动冲突消息 Task <id> already has an active orchestration (pid <pid>) 逐字保留。
• 删除旧编排门面 src/orchestration/orchestration.ts（265 行）、node-factory.ts、task-orchestration.ts；装配移到新 src/orchestration/lease.ts（fileLeaseRepository({ dir }).pipe(Layer.provideMerge(NodePlatformLive))）；taskOrchestrationKey（task:<id> 键名保留）移入 lease.ts:30。
• memory-orchestrated-task-runtime.ts 重写为 kit lease 句柄 + 原 Run 状态机（occupyTaskLease 跨调用显式 Scope 持有 + runFenced + handle.lost 竞速中断 runner）；座席策略/允许座/env 合并/释放顺序不变。
• Effect 宿主边界选择：Effect.runPromiseExit / Effect.runPromise（一次性调用），无需 ManagedRuntime（每个占用/fence 都是独立 Promise 调用，无长期共享 Effect 服务宿主；adoption.md 两分法的前者）。
• 租约半边之外的 task policy（run/template/types/ports/file-store/memory-store/execa-runner/node-paths）保留，错误类改为本地 src/orchestration/errors.ts，从而移除对 @rivus/agent-orchestration 的依赖。
• 15 条移植测试 tests/orchestration/lease.test.ts：CAS 心跳续约与丢失中止、过期接管、崩溃恢复、不可读记录拒绝、per-key fenced write 序列化与 stale 拒绝、跨释放/重开的 generation 单调、task:<id> 键名、释放只动自己的租约——全部走 /lease + 应用 file 仓库 + 真实定时器。

Validation

以下为步骤会话 2026-10-12 在本分支内容上实跑的记录（证据：/tmp/kit-step3-evidence.md §5 + §8 评审修复轮复跑，CI 顺序；本次开 PR 会话未复跑全套门禁）：

命令	结果
pnpm install --frozen-lockfile	OK（"Lockfile passes supply-chain policies"，"Lockfile is up to date"）
pnpm format:check	OK（544 files，0 问题）
pnpm test	全绿：agent-room 70；agent-finder-cli 23；agent-orchestration 67 passed + 3 skipped（未动包的既有证据）；agent-task-loop 92 文件 / 541 tests；room-web 182（日志 /tmp/kit-step3-test.log）
pnpm build	OK（/tmp/kit-step3-build.log）
pnpm typecheck	OK（/tmp/kit-step3-typecheck.log）
pnpm lint	0 warnings, 0 errors（type-aware，463 files / 137 rules；/tmp/kit-step3-lint.log）
npm pack --dry-run + node scripts/check-package.mjs	21 files tarball；"Clean consumer package check passed"
pnpm changeset status	正常（新增 .changeset/agent-task-loop-kit-lease.md，minor，含已接受差异）
聚焦复跑 pnpm exec vp test run tests/orchestration tests/task-manager tests/task-delivery.test.ts tests/commands/reject.test.ts	6 文件 / 51 tests 全绿（lease.test.ts 15）；评审修复轮再复跑 tests/orchestration/ tests/task-manager/ → 41/41（910ms）

新旧对拍证据摘录（先证据后删除）

摘自 /tmp/kit-step3-evidence.md §2/§4/§6 结论：

• 替换前旧基线（实跑）：agent-orchestration 67 passed / 3 skipped（含 tests/lease.test.ts 16 个：CAS create/replace/touch、stale takeover、crash recovery、fenced write、generation）；agent-task-loop 93 文件 / 550 tests 全绿；受影响文件单独跑 7 文件 / 60 tests 全绿。
• 替换后：旧 lease 测试逐条移植为 tests/orchestration/lease.test.ts 15 用例（对应关系在证据 §4 逐条注明：旧 :192 CAS 心跳、:168 过期接管、:117 崩溃恢复、:68/:97 fenced write、:34/:47 generation）；task-delivery / reject 测试不改断言即通过（冲突消息保留）。
• lockfile 的 effect 核对：只有一个 effect@4.0.1 解析块、物理一份（node_modules/.pnpm/effect@4.0.1）；kit 侧 Effect 图单份。

已接受的修正（等 owner 确认，changeset 已列，测试钉住）

摘自 /tmp/kit-step3-evidence.md §6（对拍记录，非静默放过）：

1. 接管判定：旧 pid 存活 + 心跳新鲜；kit Holder 含 host/bootId/pid/startTime，liveness 经 platform.process.identify 查询、查不到按 TTL 判。
2. 不可读/更新 schema 的租约记录：旧当 absent→冲突；kit 拒绝（invalid-record/unsupported-schema）且绝不覆写 → 应用面 TaskLeaseStoreError。
3. 租约丢失的错误面：旧 OrchestrationConflictError → 新 TaskLeaseLostError（key/generation/reason）；FenceRejected 仍映射 OrchestrationConflictError；二次启动用户可见消息保留原文。
4. 双失败竞态：raceFirst(workflow, handle.lost)——丢失先完成则丢失胜（窗口与旧实现等价）。
5. per-mutation 租约 CAS（旧 touch）取消：kit 心跳 fiber 是唯一租约写者；run 状态写改为丢失观测检查（isHeld()）+ 状态写。
6. 占用不再写文件型 run 状态：旧 ~/.agent-orchestration/runs/<key>/state.json 只被被删门面自身读取（全仓 rg 证实无其他读者）；占用证明现在是 kit 租约记录（tombstone 持久、generation 单调）。
7. 文件布局不兼容：kit 记录 <key>.lease.json（schemaVersion 1 + tombstone），旧 lease.lock 不迁移；现存持有者继续运行，后续 run 重新获取。

跳过的检查说明

• packages/agent-orchestration 的租约半边及其 16 个测试本步未删（room-web 层范围：AgentRuntime 仍在用，agent-runtime.ts:19,247 依赖 ./lease-manager）；其测试全绿作为"未动"证据。
• lockfile 中的 effect@3.22.2 来自 @rivus/agent@0.17.0（agent-task-loop 的可选 devDependency peer）自身依赖树，与 kit 的 Effect 图不相交，不在本步统一。

Known non-blocking notes

none——本层（租约层）评审轮次的唯一 finding 是"评审目标为空 diff（交付未提交）"，已由脚本统一提交解决（零代码改动、门禁全量复跑，见 /tmp/kit-step3-evidence.md §8）；无其他未处置遗留项。