用途：让 Codex 在同一有界任务上自动继续，直到助手输出出现完成信号或达到最大迭代次数。适用于修复测试、持续改进等有明确终点的任务，不适用于广泛编排、后台监督或多智能体管理。
主要能力：技能在工作区写入状态文件 .codex/ralph-loop-state.json；用户级 Stop 钩子分发器在 ~/.codex/hooks.json 中于每次助手响应后读取该状态。若缺少完成信号且未达上限，Stop 钩子会阻止本轮结束并回传续跑提示，使循环保持自动模式，不询问是否继续。
用法：以 $ralph-loop 显式调用，例如 $ralph-loop Fix the failing tests and stop only when they pass。可选约定：--max-iterations N、--completion-promise TEXT、--magic-word TEXT。默认最大迭代 50，完成承诺 DONE，续跑魔法词 RALPH_AUTO_CONTINUE；完成信号为 <promise>DONE</promise>，非最终轮续跑信号为 <ralph-continue>RALPH_AUTO_CONTINUE</ralph-continue>。
安装：在技能根目录运行 bash scripts/install-user-scope.sh，可选 --codex-home /absolute/path/to/.codex 与 --mode copy|symlink。安装会写入 ~/.codex/skills/ralph-loop、~/.codex/hooks/ralph-loop-stop.sh、~/.codex/hooks/managed-stop-dispatch.sh，并在 ~/.codex/config.toml 启用 codex_hooks = true；若已有 cmux 管理的 hooks.json 指向 cmux-stop-dispatch.sh 则保留。
启动循环需从技能根目录运行：bash scripts/start-loop.sh --workspace "/absolute/path/to/current/workspace" --max-iterations 50 --completion-promise DONE --magic-word RALPH_AUTO_CONTINUE --prompt "TASK GOES HERE"，并始终显式传入工作区路径。取消用 --cancel，查看状态用 --show。
限制：ralph-loop 与 $loop 不可互换，前者负责同会话续跑，后者负责周期性新会话调度且不应安装或编辑 Stop 钩子；cmux autopilot 使用同一 Stop 钩子通道，同一时间只能有一个 home 分发器拥有 ~/.codex/hooks.json。验证钩子逻辑可运行 bash scripts/test-stop-hook.sh、bash scripts/test-managed-stop-dispatch.sh、bash scripts/test-install-user-scope.sh。