Codex/dsh loopx native plugin implementation

[wujc12]

Summary

Issue Or Task

• Closes #
• Contributor task ID:

Validation

• python3 -m py_compile loopx/*.py
• loopx check --scan-root .
• Other:

Type of Change

• Bug fix
• New feature
• Breaking change
• Refactoring (no functional changes)
• Documentation update
• Test update

LoopX Area

• Control plane (goals, todos, quota, scheduler, registry, runtime)
• Benchmark boundary (adapters, runners, verifiers, scoring, evidence)
• Capability or extension (providers, adapters, skills)
• Public docs or presentation surface (README, protocols, dashboard)
• Build, packaging, installer, or CI
• Host or runtime integration

Technical Direction

• Core control-plane hardening

• Long-horizon benchmark evidence

• Operator surface and IM integration

• Shared Goal Authority and cross-host coordination

• Architecture and research incubator

• Target base branch:

• Direction tracker or promotion unit:

Boundary Checklist

• I did not commit .loopx/, .codex/goals/, live ACTIVE_GOAL_STATE.md, credentials, private benchmark traces, verifier output, raw agent sessions, internal document links, or local machine paths.
• I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
• I kept the change scoped to the linked issue/task.
• Every commit includes a DCO Signed-off-by trailer (git commit -s).

[huangruiteng]

详细中文评审

评审对象：450a58ec2618397f72a5704e3f1a2a098efff68e

动机

这个 PR 想把 LoopX 从“由外部 Python adapter 驱动一次独立 DSH Turn”的既有集成，扩展为“在当前可见 DeepSeek Harness Session 内原生运行”的可选 provider：用户通过 /loopx 进入语义路由，模型只调用有类型约束的 loopx_* tools；LoopX 继续作为 Goal、Todo、quota、scheduler 和终态的唯一权威，DSH 只持久化 Session 到 Goal/agent 的 Host-side binding。这个目标有清晰的用户价值，也符合 packages/<provider> 承载可选、独立版本 provider 的放置原则。不过当前 PR description 仍是空模板，没有关联 issue、设计/推广单元、变更类型或已执行验证，使一个跨 Python 控制面、Node provider、安装包和公开运维文档的 59-file 变更缺少可审计的问题边界与默认行为披露。

改动思路

整体架构分为两层。LoopX core 把 deepseek-harness-native 注册为新的 Host surface，并为 guided start/bootstrap、fresh-agent registration、thread binding 和 Host activation 补充版本化 JSON 契约；可选 provider 则位于 packages/dsh-loopx-plugin/，通过 LoopXCliClient 以 argv-only execFile 调用本地 loopx --format json，用 Zod 校验返回值，再由 LoopXService 管理 start/attach/activate/status/pause/resume/detach/Todo/quota 的权威读写。LoopXContinuationDriver 在 DSH idle 边界获取 quota 和 task body，并使用 Session identity、binding generation、message reservation 与 lifecycle epoch 多层 fencing，遇到人工输入、过期 readback、超时或不确定写入时 fail closed。

正向路径是：/loopx <request> 只注入一条带固定 routing policy 的 plugin follow-up；模型调用 loopx_goal_start，必要时按 loopx_start_goal_connect_v0 执行 allowlisted bootstrap，获得 planning checkpoint；随后经 loopx_todo_add 写入计划，loopx_goal_activate 做 suppressed-sink refresh 和权威 reread，driver 才能 armed；下一次 idle 时 driver 用唯一 turn id 调用 quota，并在 should_run/run_now 时投递 task body。负向路径也有明确封口：alternate Session/未知字段被 tools schema 拒绝；switch 先返回短期 confirmation token；CLI schema 不兼容、registry preflight 失败、超时或 uncertain write 都不会偷偷绑定或继续自动推进。这里把 prompt routing 明确称为 guidance，同时把 tool schema、readback 与 fencing 称为 machine-enforced obligation，语义区分是正确的。

具体改动

• Python 控制面：host_loop_activation.py、bootstrap_command_pack.py、bootstrap_connect.py 和各 CLI command 将 native Host surface、版本化 connect/bootstrap/result schema、fresh peer 默认选择与 thread binding 投影接入现有控制面；registry_admin.py 给 agent registration 增加 source-to-global dry-run preflight、partial-write/uncertain-write 分类和精确 readback；agent_onboarding.py、start_contract.py、heartbeat/status/quota/todo/project lifecycle 只做相应 surface 枚举和契约贯通。
• Node provider：manifest、Cordis patch、build 配置、lockfile、LICENSE/NOTICE 和 installer 构成独立 package；binding.ts 定义 planning/armed/paused/uncertain typed state 与 generation fence；schemas.ts 固定可接受的 LoopX JSON 版本；service.ts 串起所有权威操作；tools.ts 暴露 11 个严格输入的 model tools；command.ts 实现 /loopx semantic entry；driver.ts 负责 idle continuation、人类输入让路、timer/backoff、cold restore 与 disposal；cli-client.ts 限制 child env、stdout/stderr、timeout 和 shell-free argv。
• 文档与入口：新增 native plugin 集成指南和 package README，并在外部 DSH connector 与 runtime catalog 中明确 native/external 两种模式；.gitignore 另外加入了与本能力无关的 docs/superpowers/ 规则，建议移出本 PR。
• 验证：Python/TS 单元测试覆盖 bootstrap、fresh identity、thread binding、typed tool、service、driver、planning recovery 和 semantic command；Hermetic smoke 同时验证 unpacked package 与 tarball 的真实 DSH add/dump/remove 路径。

关键代码讲解

1. LoopXCliClient.runJson 是进程信任边界：固定 --format json、禁用 shell、限制继承环境和输出大小，并按 read/idempotent-write/write 区分 retryability 与 uncertain outcome。
2. LoopXService.start / attach / activate 把 Session 内的 planning、显式 switch confirmation、fresh-agent registration、thread binding 和 activation reread 放入 per-Session queue，避免一个 model turn 绕过 LoopX 权威。
3. LoopXContinuationDriver.evaluate 在 exact fence 下复用一个 turn identity 做至多一次 quota retry，识别 terminal closure，按 scheduler hint run/wait；onPreStep 再校验 plugin-owned follow-up 的 reservation，避免 stale message 被模型消费。
4. register_agent_via_source_registry 在 source write 前先做 global sync preflight，并将 source write 后 sync/readback 失败标为 partial/uncertain，而不是把 fresh peer 冒充为已成功注册。
5. build_start_goal_guided_packet 新增 connect_contract，为 provider 提供无需执行 producer-supplied command text 的 allowlisted bootstrap 输入；这个方向正确，但目前它被放进默认 agent-facing payload，直接触发下面的输出预算回归。

对主干的风险

当前有三个合并阻断项：

1. [P1] 必需的 Python CI 仍失败。 cli-output-budget-regression-smoke.py 在 bootstrap_command_pack 三个场景中报告字符增长 210（allowance 182），在 start_goal_guided 多个默认/详情场景中报告字符增长 687、12 行、compact payload 548；这说明新 connect_contract/native activation 数据进入了默认 agent hot path，却没有被压缩或放到显式 detail projection。请保留 typed contract，但把只供 native provider 的材料移到按需 detail/host-specific projection，或用一个更小的 stable reference；如果确实要改变默认输出，必须先明确披露受影响 lane，再让 differential budget 以经过评审的新语义通过，而不是放宽/绕过 gate。
2. [P1] DCO check 失败。 exact head 中 964c353c、8508c90b、354c6219、5f9ef463、dd40a6a4 五个 commit 缺少有效 Signed-off-by。需要重写这些 commit（或整理为签署过的 reviewer-logical commits）后重新推送。
3. [P1] 公开安装命令引用了不存在的 artifact。 package.json 当前版本是 0.1.3，实测 pnpm pack 生成 dsh-loopx-plugin-0.1.3.tgz；但 package README 与 canonical integration doc 的安装和 hermetic smoke 示例仍硬编码 dsh-loopx-plugin-0.1.0.tgz。照文档执行会在 add/smoke 阶段找不到文件。请统一版本，最好从 pnpm pack 输出/manifest 派生 tarball 路径，避免下一次 bump 再漂移。

此外，23,514 additions / 110 deletions 的总量虽主要来自 lockfile 与完整测试，但 core contract、provider、installer、文档和 unrelated ignore rule 同批使回滚面较大。至少应删除 docs/superpowers/ 这条无关规则，并在 PR body 补上 issue/任务、surface ownership、默认行为变化及验证矩阵；如果输出契约修复需要继续扩大 core diff，建议先拆成“版本化 core contract”与“provider/package”两个 reviewer-logical PR。

我独立运行了 provider typecheck、95 个 Vitest、build、package-directory smoke、0.1.3 tarball smoke，均通过；py_compile 与 loopx check --scan-root . 的公开边界检查通过。聚焦 Python 集合得到 231 passed / 6 failed，其中 2 个 linked-worktree fixture 失败由本机工作时间 Git hard gate 导致，另外 settlement/workspace 失败来自 archive 验证目录没有 .git 元数据；这些环境项不替代远端真实 CI。远端 exact-head CI 的 DCO 与 CLI output-budget failure 均为可复现、与本 PR 直接相关的 blocker。未启动真实模型或生产 DSH Session。

我的整体评价

这个 PR 的 provider 设计质量高于通常的“shell 包装器”：authority 分层、typed schema、uncertain-write 语义、same-session fencing、人工输入抢占和 hermetic package smoke 都是值得保留的；测试也真正覆盖了正负路径。但合并标准看的是整个 exact head，而不是 provider 单测。当前 required checks 红、公开 runbook 不能按版本执行、PR 本身缺少变更披露，因此结论是 REQUEST_CHANGES。修复 hot-path payload、DCO history 和 artifact 版本后，请在同一新 head 重跑 Python CI、TS tests/build、path+tarball smoke；届时可以基于新 exact head 快速复审。

English verdict: REQUEST_CHANGES on exact head 450a58ec2618397f72a5704e3f1a2a098efff68e. The same-session provider has a strong typed/fail-closed architecture and its 95 Vitest cases, build, and path/tarball DSH smokes passed independently, but merge is blocked by the required CLI output-budget regression, five unsigned commits, and public install/smoke commands hard-coded to 0.1.0 while the package emits 0.1.3. Compress or move native-only payloads off the default agent hot path, repair DCO history, derive the artifact version in docs, remove the unrelated ignore rule, and rerun the full exact-head checks.

[huangruiteng]

动机

本轮按新的 exact head ab311980faf576c62551767d1d3de6c14bb1feb9 重新完整评审。这个 PR 的目标是把 LoopX 能力接入 DSH 插件，并在同一 Agent Session 内完成可治理的自动续跑；这类集成会进入会话生命周期、命令执行、任务投影和恢复路径，必须同时满足正确性、失败封闭、可安装性和发布可复现性。

改动思路

当前实现的总体分层是合理的：CoordinatorRegistry 集中持有 Session 对象、命令屏障、activation epoch、维护 admission 与连续失败抑制；LoopXContinuationDriver 在同一 session 上执行 reservation / idle admission / quota / task / continuation，并允许人类输入抢占；LoopXService 作为 LoopX authority bridge，LoopXCliClient 以 argv-only、受限环境、超时和不确定态处理守住 CLI 信任边界；receipts/tools 使用 execution、application、delivery、recovery 的类型化回执；Python 侧补齐 schema、注册、thread binding 与 activation。相比上一 head，这一版的 coordinator 和 receipt 结构更清楚，失败路径也更集中。

正向路径上，激活后由 coordinator 驱动同 session 续跑，显式记录命令/交付回执；负向路径上，人工输入、epoch 变化、命令未完成、quota/task 不确定、连续失败达到阈值都会阻断或抑制自动续跑，而不是静默放行。这些方向符合 LoopX 的控制面语义。

具体改动

我重新检查了 TypeScript runtime、service/CLI bridge、typed receipts/tools、Python capability/schema/registry/thread binding、安装与运维文档、package metadata 和测试。对 exact head 的独立验证结果：

• TypeScript typecheck 通过；
• 8 个测试文件、101 个测试全部通过；
• 插件 build 通过；
• npm pack --ignore-scripts --dry-run --json 通过，并确认实际产物名为 dsh-loopx-plugin-0.2.0.tgz；
• 远端 Windows、dependency review、frontstage build、release artifact build 通过；
• 未进行真实生产 DSH 会话验证，因此这部分不能作为已覆盖证据。

但当前 head 仍有以下合并阻塞项：

1. CLI 输出预算回归仍未解决。 远端 pytest 继续失败：bootstrap pack 的 rows 输出超预算约 210 字符、compact 约 190 字符；start_goal_guided 的 rows 输出超预算约 687 字符/687 bytes/12 行，compact 也超约 548 字符。控制面热路径输出预算是既有契约，不能用新增字段无界扩张。请压缩默认投影，把诊断细节放到 opt-in/detail surface，并补齐与 intended budget 对齐的测试。
2. DCO 仍失败。 当前检查指出 7 个提交缺少 sign-off：964c353c、8508c90b、354c6219、5f9ef463、dd40a6a4、9af371ce、ab311980。请补签并重写相应提交，然后确认 exact head 的 Sign-off 检查通过。
3. 公开安装文档与实际包名不一致。 package.json 已是 0.2.0，实际 dry-run 产物是 dsh-loopx-plugin-0.2.0.tgz，README/文档仍引用 dsh-loopx-plugin-0.1.0.tgz。这会让用户按 canonical 文档直接安装失败；请统一为真实、可复现的 artifact/version，并用 pack/install smoke 验证文档命令。

另外两项需要在本 PR 一并收口：PR 描述仍是未填写的模板，缺少变更类型、影响面和验证说明；.gitignore 新增的 docs/superpowers/ 与本 PR 的 DSH/LoopX 集成主题无明显关系，请删除或给出明确、可审阅的归属理由。

对主干的风险

主要风险不是 happy path，而是三个边界：第一，默认控制面输出增长会放大每轮模型上下文和自动化成本；第二，文档/包版本漂移会形成无法按说明安装的公开发布面；第三，会话协调代码若绕过人工输入或 epoch fence，可能在错误 session 上继续执行。当前 coordinator 的 typed state、barrier 与 fail-closed 设计显著降低了第三类风险，但前两类已有确定失败证据，DCO 也尚未满足仓库合规门槛，因此不能合并。

我的整体评价

REQUEST_CHANGES。 架构方向正确，新的 coordinator/receipt 设计比旧 head 更容易推理和测试，101 个测试与跨平台检查也提供了较好基础；不过输出预算、DCO、可安装 artifact 三个阻塞项在 exact head 上仍然存在。请先修复这些问题、补全 PR 描述并清理无关 ignore 规则，再以新的 exact head 请求复审。

English verdict: REQUEST_CHANGES on exact head ab311980faf576c62551767d1d3de6c14bb1feb9 — the typed coordinator and fail-closed session design are strong, but the CLI output-budget regression, seven unsigned commits, and the documented 0.1.0 artifact versus the actual 0.2.0 package remain merge blockers.