内部 launcher 的兼容背景
0.3.x 时代，Comet 的状态、守卫、交接和归档逻辑由 7 个 Bash 脚本承担。这在 macOS 和 Linux 上工作良好，但 Windows 用户必须额外安装 Git Bash 或 WSL 才能跑完整工作流，路径转义和 shell 差异也常常带来隐患。 0.4.0-beta.1 把这些脚本迁移到 Node.mjs 运行时；当前发布形态是薄 launcher 加共享的生成 runtime，带来了三点变化：
公开/兼容 launcher 只导入同目录的
comet-runtime.mjs 并调用对应命令。共享 runtime 由 TypeScript 源码构建，并把运行依赖一起打包，因此不依赖项目自己的 node_modules；排障或复制安装资产时，launcher 与 comet-runtime.mjs 必须保持同一版本。
随包 launcher 一览
comet-*.mjs 是随包分发的内部 launcher，保留给兼容和高级排障。普通用户与 Agent 应使用上面的稳定 CLI；多数用户只需要 /comet、comet status 和 comet doctor。兼容模式下如何定位 launcher
Skill 内会先定位comet-env.mjs，再由它打印出脚本目录。这样做是为了不把用户机器路径硬编码进提示词——不同平台、不同安装范围的目录结构差异很大。
comet-env.mjs 是唯一的非打包启动器，它把目录里的反斜杠统一成正斜杠，保证路径能安全地插值进任何 shell，也能被 Windows 上的 Node 原样接受：
脚本如何协作
一次正常的阶段推进，背后是几个脚本的接力：comet guard先做 YAML 状态预检；状态文件结构不合法时直接中止，不会继续检查阶段条件。- 不带
--apply时，守卫只报告”是否就绪”，不改任何状态；带--apply时，校验全过后才会推进phase。 comet state transition和comet guard --apply共享同一份转移语义，所以两条推进路径的行为一致。comet-hook-guard作为 PreToolUse 钩子常驻，在open/design/archive阶段阻止源码写入，把”提前写实现”挡在发生之前。
关键命令与标志
下表汇总最常用的子命令和标志。完整语义见各脚本的专属页面。状态文件的三层拆分
0.4.0-beta.1 把每个 change 的状态从单一文件拆成了三份，各司其职：.comet.yaml保持 YAML 可读，你可以直接看懂当前在哪个阶段；机器字段不再混在里面，避免手工误改。.comet/run-state.json由运行时原子写入（临时文件 + 重命名），comet state set会拒绝直接写其中的 machine-owned 字段。.comet/state-events.jsonl只追加、不覆盖，由comet state transition、comet guard --apply和comet archive写入，给你一条可追溯的状态历史。
.comet.yaml 里）在首次读取时会自动迁移到拆分结构，无需手动处理。
在哪里能看到运行时证据
如果你想知道当前 change 走到了哪一步、状态是否健康，不必直接读这些脚本文件。优先用面向用户的命令：status 和 doctor 走的是和脚本相同的运行时证据路径，所以它们报告的问题就是脚本实际会拦截的问题。