feat(zcode): add ZCode goal-mode surface

[now-ing]

Motivation

ZCode is a terminal coding agent whose extension points are markdown skills and hooks — no goal primitive, no host automation scheduler. LoopX could not reach a ZCode session as a first-class host: the /loopx skill had to fall back to --host-surface other-agent, losing the surface-specific install command, activation contract, and catalog entry.

What this adds

Follows the gemini-cli / cursor-agent skill-facade pattern exactly (the lightest existing host class), plus a loopx/zcode_goal_mode host-facts package in the style of pi_goal_mode:

• loopx/zcode_goal_mode/ — install surface id, AGENTS_HOME/skills root resolution with ZCODE_AGENTS_HOME override, README
• start-goal — zcode in the host-surface selection gate and guided packet
• activation — _zcode_activation via _skill_facade_cli_activation, agent-type catalog entry + aliases, scheduler binding, scope label
• onboarding — surface install command, start instruction, skill_delivery stays surface_managed
• installer — --surface zcode writes managed SKILL.md facades into AGENTS_HOME/skills; --zcode-agents-home override; uninstall retires managed files and preserves user-owned ones
• contracts — slash_commands and start_contract host-surface maps
• docs — README / README.zh-CN start-from-your-agent table rows

The activation packet states plainly that ZCode has no host loop primitive: the loop driver is the agent's own turn loop and every continuation enters through quota should-run.

Validation

python -m pytest tests/test_zcode_host_surface.py -q          # 7 passed
python -m pytest tests/test_gemini_cursor_host_surfaces.py \
  tests/test_slash_command_install.py tests/test_host_loop_activation.py \
  tests/test_agent_onboarding_pi_host.py \
  tests/test_agent_onboarding_unconnected_project.py -q       # 132 passed
python -m pytest tests/control_plane/... -q                   # green (gate list updated)
python -m ruff check ...                                      # clean
python -m mypy                                                # clean

Real-CLI smoke on the branch: selection gate lists zcode; start-goal --host-surface zcode returns activation zcode_agent_loop with setup loopx slash-commands --install --surface zcode; install creates the managed skill set; agent-onboard --list-agent-types shows ZCode; todo add / refresh-state / todo complete round-trip works end to end.

[huangruiteng]

评审对象：3365@32d85c7356a5b60548665e83bed0784dfccbad9e

动机

这个 PR 想把 ZCode 纳入 LoopX 的 host-surface 体系，让用户能够安装 LoopX skill、从 start-goal --host-surface zcode 获得激活包，并让 onboarding、scheduler profile、README 和卸载流程都认识这个宿主。这个目标本身合理：LoopX 已经有 Gemini CLI、Cursor Agent 一类的 skill-facade 模式，新增宿主应该复用同一套受管文件、quota 入口和用户文件保护机制。

但当前实现建立在两个已经不成立的宿主事实之上。ZCode 官方文档明确给出了原生 Goal Mode（/goal 会逐轮验证并自动续跑）和 Automations；官方 Skill 文档 也把用户级目录定义为 ~/.zcode/skills/<skill-name>/SKILL.md。因此“ZCode 没有 goal primitive / automation scheduler，只能依赖 agent 自己续轮”并不是一个可以进入公共 host contract 的事实，~/.agents/skills 也不是该产品当前公开的安装目录。这里需要先确认目标产品和版本，再选择正确的集成层级；否则 LoopX 会公开一个看起来完整、实际宿主无法发现的 surface。

改动思路

当前路径是：slash-commands --install --surface zcode 经过 CLI 参数归一化进入 install_slash_commands，把生成的 SKILL.md facade 写到 zcode_home()/skills；start-goal、agent catalog 和 onboarding 再把 zcode 映射到 _zcode_activation，后者复用 _skill_facade_cli_activation 并声明 agent_cli_turn_loop / generic_cli。正向路径在 LoopX 内部是连通的：安装、host selection、activation packet、catalog 和卸载都有测试覆盖。

负向路径却在真正进入 ZCode 前失败：默认安装写到 ~/.agents/skills，而 ZCode 官方用户级发现目录是 ~/.zcode/skills，所以真实宿主不会发现这些 facade；即使手动搬过去，激活包仍会告诉用户宿主没有 Goal/Automation primitive，并把原生可治理的续跑能力降级成“agent 自己每轮执行 quota”。更合理的设计是把“ZCode 原生具有什么能力”和“LoopX 当前能绑定到其中哪些能力”分开建模：安装先使用官方目录和调用语义；若当前还没有原生 Goal/Automation 的机器接口，就明确写成“LoopX 暂未绑定该接口”，而不是写成“宿主不存在该能力”。

具体改动

• README.md / README.zh-CN.md 新增 ZCode 入口；loopx/zcode_goal_mode/README.md 说明安装、使用和边界。
• agent_onboarding.py、bootstrap_command_pack.py、start_contract.py 和 slash_commands.py 把 zcode 加入选择门、引导命令与 host contract。
• host_loop_activation.py 增加 catalog/alias/scheduler 映射以及 _zcode_activation。
• slash_command_install.py 和 CLI parser 增加 surface、home override、managed facade 的安装/更新/卸载。
• tests/test_zcode_host_surface.py 用 7 个端到端风格测试覆盖 start-goal、selection gate、onboarding、home override、用户文件保护、catalog 和 activation 声明；compact projection fixture 同步增加一项。

关键代码讲解

1. zcode_home() 是整个安装目标的权威来源，但它把默认值设为 ~/.agents，并引入未在官方 ZCode 文档中出现的 ZCODE_AGENTS_HOME。这一错误会贯穿 install、update、uninstall 和 onboarding 返回的命令。
2. _zcode_activation() 复用了 _skill_facade_cli_activation()；复用本身简洁，但同时继承了“没有 goal/automation primitive、只能由 agent 自驱”的强语义，因此不是单纯的展示文案问题，而是 scheduler/authority contract 错位。
3. install_slash_commands() 保留用户自有文件、只退休带 LoopX marker 的文件，这个边界设计是好的；问题在于它保护和操作的是错误目录，现有测试也只证明了虚拟目录里的文件语义。
4. test_start_goal_accepts_the_zcode_host_surface() 等测试直接调用 LoopX CLI，并没有启动或读取真实 ZCode。它们能证明 LoopX 内部 dispatch 不会 dead-end，却不能支撑 PR 描述里的“real-CLI smoke”或宿主可发现性结论。

对主干的风险

[P1] 安装目录和宿主能力模型与 ZCode 官方契约冲突

官方 Skill 文档当前指定 ~/.zcode/skills/<skill-name>/SKILL.md，调用语义是 $skill-name（也可从 / 面板找到 Skill）；本 PR 则写入 ~/.agents/skills，并把 README/activation 声明为 /loopx 与 AGENTS_HOME/skills。实际用户执行成功的 LoopX 安装命令后，ZCode 仍可能完全看不到 LoopX skill。请以官方目录和调用语义重做安装/readback 测试，并把 loopx/zcode_goal_mode/README.md 的占位链接 https://github.com/ 换成具体官方入口。

同样，官方 Goal Mode 和 Automations 已经存在。请重新做 capability placement：至少区分“宿主具有原生 Goal/Automation”与“LoopX 是否已有可调用绑定”，更新 scheduler profile、host_mutation、activation steps、README 和测试；不要把机器可执行的宿主能力错误降级成 generic agent self-loop。若此 PR 只打算先交付 skill 安装，应收窄成真实、可验证的安装 surface，而不是同时发布错误的 runtime contract。

[P1] required Python Tests 当前因公共 CLI 输出预算回归而失败

GitHub Actions 的 pytest job 在 cli-output-budget-regression-smoke.py 失败：surface/bootstrap_command_pack/{crowded,multi_agent,small}/json 的字符数增长 197（allowance 182），compact payload 增长 173（allowance 163/164）。新增 host choice 改变了 agent-facing compact surface；需要压缩投影，或在有明确公共契约依据时更新预算和回归测试，不能以其他单测通过替代这个 required check。

验证矩阵与剩余风险

• exact-head focused suite：175 passed；另 1 个既有 linked-worktree 测试因本机工作时段 hard commit gate 无法创建 fixture commit，与本 PR 代码无关。
• changed Python surfaces：Ruff clean。
• GitHub checks：8 个成功/跳过，pytest 失败，失败原因如上。
• 未验证：没有在真实 ZCode 中完成“官方目录安装 -> Settings/Skills readback -> $loopx 调用 -> 原生 Goal/Automation 边界”链路；这正是当前最大风险。
• typed state / domain neutrality：canonical agent-type 映射是显式枚举，没有 substring heuristic；通用控制面文案仍保持 goal-neutral。主要问题是宿主事实与 delivery semantics 错误，而不是类型化方式。

我的整体评价

LoopX 内部的 plumbing 做得比较完整，managed-file ownership、显式 alias、catalog 和 focused tests 都有可取之处；409 行改动也基本围绕一个主题。但这个 PR 的关键价值是“真实 ZCode 用户能安装并获得正确的续跑契约”，而当前两个权威前提——skill 目录与宿主原生能力——都与官方文档相反，同时 required CI 仍红。因此当前 exact head 不能合入。修复官方目录/调用方式、重新界定 Goal/Automation 集成层级，并让 CLI budget check 变绿后，我会按新 exact head 重新评审。

English verdict: REQUEST_CHANGES for exact head 32d85c7356a5b60548665e83bed0784dfccbad9e. The LoopX-side wiring is cohesive, but it installs to a non-canonical ZCode skill root and models ZCode as lacking native Goal Mode/Automations even though the official product exposes both. The required Python Tests check also fails the public CLI output budget. Focused validation passed 175 tests and Ruff; one unrelated fixture test was blocked by the local hard commit window. Rework the host facts and installation/readback path, then fix the budget regression before re-review.