feat: add engine-first unattended recovery

Author: hellowind777

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "HelloLoop 的 Claude Code 原生插件元数据，用于多 CLI 宿主分发。",
   "author": {
     "name": "HelloLoop"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件，Codex 路径为首发与参考实现。",
   "author": {
     "name": "HelloLoop"
@@ -17,15 +17,15 @@
   "interface": {
     "displayName": "HelloLoop",
     "shortDescription": "基于 backlog 的持续仓库开发与验证循环",
-    "longDescription": "HelloLoop 把基于 backlog 的持续开发能力封装为官方 Codex 插件 bundle。显式调用 helloloop skill 时，默认优先进入 npx helloloop 主 CLI 流程：支持 npx helloloop、npx helloloop <PATH>、npx helloloop codex|claude|gemini ...，先分析、再展示确认单、确认后自动接续推进。",
+    "longDescription": "HelloLoop 把基于 backlog 的持续开发能力封装为官方 Codex 插件 bundle。显式调用 helloloop skill 时，默认优先进入 npx helloloop 主 CLI 流程：支持 npx helloloop、npx helloloop <PATH>、npx helloloop codex|claude|gemini ...，先分析、再展示确认单、确认后自动接续推进；运行中按无人值守自动恢复持续推进主线。",
     "developerName": "HelloLoop",
     "category": "Coding",
     "capabilities": [
       "Interactive",
       "Write"
     ],
     "defaultPrompt": [
-      "使用 HelloLoop 时，优先执行 npx helloloop 或 npx helloloop <PATH>；如果用户明确指定执行引擎，也允许使用 npx helloloop codex|claude|gemini ...，而不是在对话里手工模拟分析与续跑。"
+      "使用 HelloLoop 时，优先执行 npx helloloop 或 npx helloloop <PATH>；如果用户明确指定执行引擎，也允许使用 npx helloloop codex|claude|gemini ...。启动前确认一次，启动后按无人值守自动恢复与主线续跑执行，不要在对话里手工模拟流程。"
     ],
     "brandColor": "#0F766E"
   }

README.md

@@ -18,10 +18,10 @@
 
 这意味着：
 
-- 终端里执行 `npx helloloop` 时，不会再静默固定用 `Codex`
-- 在 `Codex` 里触发 `$helloloop` 时，默认优先当前宿主 `Codex`
-- 在 `Claude` / `Gemini` 原生命令里触发时，默认优先各自当前宿主
-- 如果你在某个宿主里显式要求改用别的引擎，`HelloLoop` 会先确认，不会静默切换
+- 无论在终端还是在 `Codex` / `Claude` / `Gemini` 宿主内，只要用户未明确指定引擎，`HelloLoop` 都会先询问本轮执行引擎
+- 当前宿主、项目历史、用户历史只作为推荐依据，不会自动替你选中引擎
+- 如果你已经显式指定，或已经在首轮确认中明确选定了引擎，本轮就固定按该引擎执行
+- 如果后续因为登录、配额、限流等问题需要改用别的引擎，`HelloLoop` 也会先询问，不会静默切换
 
 ## 支持矩阵
 
@@ -50,20 +50,19 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 
 ## 执行引擎选择规则
 
-默认选择顺序如下：
+执行规则如下：
 
 1. 命令首参数显式引擎：`codex` / `claude` / `gemini`
-2. 当前宿主默认引擎
-3. 项目上次引擎 / 项目默认引擎
-4. 用户上次引擎 / 用户默认引擎
-5. 当前唯一可用引擎
-6. 多个可用但仍无结论时，停下来询问一次
+2. 自然语言中明确且不歧义地指定了引擎
+3. 如果前两步仍未明确，先停下来询问本轮执行引擎；当前宿主、项目上次 / 默认、用户上次 / 默认只作为推荐依据
+4. `-y` / `--yes` 等非交互模式下，如果你没有显式指定引擎，`HelloLoop` 会直接停止并要求补充引擎
 
 补充说明：
 
 - 首参只有第一个裸词会被解释为引擎；如果你真要把 `claude` 当目录名，请写成 `./claude`、`.\claude` 或绝对路径
 - 命令后的自然语言如果明确提到 `codex`、`claude`、`gemini`，也会纳入意图判断
-- `已安装` 不等于 `可继续执行`；如果当前引擎在运行中遇到登录失效、额度耗尽、429 限流等问题，`HelloLoop` 会暂停并询问是否切换到其他可用引擎
+- 当前宿主、项目历史、用户历史不会触发自动选中，只会影响“推荐项”
+- `已安装` 不等于 `可继续执行`；如果当前引擎在运行中遇到 429、5xx、网络抖动、流中断、长时间卡死等问题，`HelloLoop` 会先按无人值守策略做同引擎自动恢复，不会中途停下来询问
 
 ## 默认工作流
 
@@ -86,6 +85,29 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 - 如果 backlog 清空了，但主线终态复核仍发现文档目标还有缺口，`HelloLoop` 会自动重新分析并继续推进
 - 如果模型只做了一半就想停下来给“下一步建议”，`HelloLoop` 会优先按主线目标继续推进，而不是把半成品当完成
 
+## 无人值守恢复
+
+`HelloLoop` 的设计目标不是“跑一轮停一轮”，而是启动前确认一次，启动后持续无人值守推进。
+
+因此运行中的默认策略是：
+
+- 普通运行故障不再中途提问：不会因为 429、5xx、网络抖动、结果流中断、短时空输出就停下来问用户
+- 同引擎优先恢复：默认不会自动切换引擎，也不会偷偷改用别的 CLI
+- 保留主线上下文恢复：同引擎恢复时会生成恢复记录与恢复 prompt，要求新一轮执行直接基于当前仓库状态继续，而不是从头另起一套
+- 定时心跳检查：运行中会持续写入心跳与恢复状态，用于判断当前阶段是否还在正常推进
+- 先预警再终止：默认每 60 秒刷新一次心跳；若长时间没有可见进展，先标记为疑似卡住；达到更长的自动恢复阈值后，才会终止当前进程并做同引擎恢复
+- 硬错误直接停止：如果识别为 400 请求错误、登录/鉴权/订阅问题、本地 CLI 缺失或权限错误，不会盲目重试
+
+默认恢复节奏：
+
+- 心跳间隔：60 秒
+- 疑似卡住预警：15 分钟无可见进展
+- 自动恢复阈值：45 分钟无可见进展
+- 同阶段最多自动恢复：4 次
+- 恢复等待：2 分钟 → 5 分钟 → 15 分钟 → 30 分钟
+
+如果你明确指定或确认了本轮引擎，`HelloLoop` 在自动恢复阶段也会继续锁定该引擎，不会擅自切换。
+
 ## 自动发现与交互逻辑
 
 ### 1. 只输入 `npx helloloop`
@@ -96,7 +118,7 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 npx helloloop
 ```
 
-`HelloLoop` 会先快速扫描当前目录：
+`HelloLoop` 会先明确执行引擎，再快速扫描当前目录：
 
 - 当前目录本身就是项目仓库或开发文档目录时，直接进入分析
 - 当前目录更像工作区时，优先利用顶层文档，再提示选择候选项目目录
@@ -177,6 +199,7 @@ npx helloloop --rebuild-existing
 - 每个任务完成后复核其验收是否真的闭合
 - backlog 清空后再复核一次整个主线目标
 - 只有“任务验收闭合 + 主线目标闭合 + 验证通过”才算真正结束
+- 运行中若出现可恢复的 CLI 故障，则按无人值守策略自动恢复，不打断主线
 
 ## 安装
 
@@ -277,7 +300,7 @@ helloloop:helloloop
 npx helloloop
 ```
 
-默认优先当前宿主 `Codex`；如果你在 `Codex` 内显式要求改用 `Claude` / `Gemini`，会先确认再切换。
+如果你在 `Codex` 中直接使用 `$helloloop` 或 `npx helloloop`，但没有明确指定引擎，`HelloLoop` 仍会先让你确认本轮引擎；`Codex` 只会作为推荐项，不会被自动选中。
 
 ### Claude Code / Gemini CLI
 
@@ -307,7 +330,7 @@ npx helloloop
 | --- | --- |
 | `codex` / `claude` / `gemini` | 作为 `analyze` 模式的命令首参数，显式指定执行引擎 |
 | `--dry-run` | 只分析并输出确认单，不开始自动执行 |
-| `-y` / `--yes` | 跳过交互确认，分析后直接执行 |
+| `-y` / `--yes` | 跳过执行确认直接开始；但如果未显式指定引擎，会直接报错而不是自动选引擎 |
 | `--repo <dir>` | 高级覆盖：显式指定项目仓库 |
 | `--docs <dir|file>` | 高级覆盖：显式指定开发文档 |
 | `--rebuild-existing` | 项目与文档冲突时，自动清理现有项目后重建 |

hosts/claude/marketplace/plugins/helloloop/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "HelloLoop 的 Claude Code 原生插件。",
   "author": {
     "name": "HelloLoop"

hosts/claude/marketplace/plugins/helloloop/commands/helloloop.md

@@ -10,7 +10,7 @@ argument-hint: [PATH]
 1. 将当前代码视为事实源，将开发文档视为目标源。
 2. 如果用户在命令后提供了 `$ARGUMENTS`，必须同时保留其中的显式路径和自然语言补充要求，不要依赖固定关键词硬编码决策。
 3. 自动识别目标仓库与开发文档，并先分析“当前代码做到哪里了”“与文档目标是否存在偏差”“当前项目与文档目标是否匹配”。
-4. 当前宿主是 `Claude`，默认优先使用 `Claude` 作为执行引擎；如果用户明确要求改用 `Codex` 或 `Gemini`，必须先确认，不允许静默切换。
+4. 当前宿主是 `Claude`；如果用户未明确指定执行引擎，必须先确认本轮引擎，`Claude` 只可作为推荐项，不允许自动选中；如果用户明确要求改用 `Codex` 或 `Gemini`，必须先确认，不允许静默切换。
 5. 如果当前目录没有明确开发文档，先展示顶层文档文件、顶层目录和疑似项目目录，再询问用户开发文档路径。
 6. 项目路径对外只有一个概念；如果用户输入的项目路径不存在，就把它视为准备创建的新项目目录，不要再单独追问“新项目路径”。
 7. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
@@ -32,7 +32,7 @@ argument-hint: [PATH]
    - 自动执行停止条件
 11. 未经用户确认，不要开始正式修改代码。
 12. 用户确认后，使用当前确认的执行引擎原生工具持续推进 backlog；每个任务完成后还要再做任务完成复核，backlog 清空后还要再做主线终态复核，直到开发文档的最终目标完成，且相关测试、验证、验收都已通过；遇到硬阻塞或需要用户补充关键信息时再停下。
-13. 如果当前引擎在运行中遇到登录失效、额度耗尽、429 限流等问题，必须暂停并询问是否切换到其他可用引擎。
+13. 如果当前引擎在运行中遇到 429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎自动恢复，不要中途停下来询问用户；只有明确硬阻塞时才停止。
 14. 用户需求明确且当前任务可直接完成时，必须一次性完成本轮应交付的全部工作；禁止做一半后用“如果你要”“是否继续”之类的话术停下，也禁止用“希望这对你有帮助”等套话收尾。
 15. 始终优先使用安全 shell 与原生文件工具；在 Windows 上避免危险的嵌套命令、路径拼接删除和 `cmd` 风格破坏性命令。
 16. 不要调用外部 `npx helloloop` 来替代这个原生工作流；你现在就在 HelloLoop 的 Claude Code 原生模式中。

hosts/claude/marketplace/plugins/helloloop/skills/helloloop/SKILL.md

@@ -10,7 +10,7 @@ description: 当用户希望 Claude Code 按开发文档先分析当前进度，
 ## 默认流程
 
 1. 自动识别目标仓库与开发文档
-2. 默认优先使用 `Claude` 作为执行引擎；如果用户明确要求改用 `Codex` / `Gemini`，先确认再切换
+2. 如果用户未明确指定执行引擎，先确认本轮引擎；`Claude` 只作为推荐项，不自动选中；如果用户明确要求改用 `Codex` / `Gemini`，先确认再切换
 3. 分析当前代码与文档目标之间的真实进度和偏差
 4. 在目标仓库根目录创建或刷新 `.helloloop/`
 5. 输出中文执行确认单
@@ -22,7 +22,8 @@ description: 当用户希望 Claude Code 按开发文档先分析当前进度，
 - 如果当前目录没有明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再询问文档路径。
 - 项目路径对外只有一个概念；如果用户提供的项目路径不存在，直接按新项目路径处理，不要再追问“新项目路径”。
 - 如果当前项目与开发文档目标明显冲突，必须先确认是继续现有项目、清理后重建，还是取消。
-- 如果当前引擎在运行中遇到登录失效、额度耗尽、429 限流等问题，必须暂停并询问是否切换到其他可用引擎。
+- 如果当前引擎在运行中遇到 429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎自动恢复，不要中途停下来询问用户。
+- 只有识别为 400 请求错误、登录/鉴权/订阅问题、本地 CLI 缺失或权限错误等硬阻塞时，才允许结束本轮自动执行。
 - 不允许跳过执行确认单直接开始正式开发。
 - 不允许把开发文档整体压成一个大任务；需要输出足够细的 backlog。
 - 代码是事实源，开发文档是目标源。

hosts/gemini/extension/GEMINI.md

@@ -9,7 +9,7 @@
 ## 默认流程
 
 1. 自动识别项目仓库与开发文档
-2. 默认优先使用 `Gemini` 作为执行引擎；如果用户明确要求改用 `Codex` / `Claude`，先确认再切换
+2. 如果用户未明确指定执行引擎，先确认本轮引擎；`Gemini` 只作为推荐项，不自动选中；如果用户明确要求改用 `Codex` / `Claude`，先确认再切换
 3. 如果当前目录没有明确开发文档，先展示顶层文档文件、顶层目录和疑似项目目录，再询问文档路径
 4. 项目路径对外只有一个概念；若用户输入的路径不存在，直接按新项目路径处理
 5. 分析当前代码与开发文档的差距，并判断当前项目与文档目标是否匹配
@@ -25,7 +25,8 @@
 - 如果无法识别目标仓库或开发文档，必须停下来询问用户。
 - 不要单独追问“新项目路径”；项目路径只需要用户给一次。
 - 如果识别到偏差修正任务，优先收口偏差，再推进后续 backlog。
-- 如果当前引擎在运行中遇到登录失效、额度耗尽、429 限流等问题，必须暂停并询问是否切换。
+- 如果当前引擎在运行中遇到 429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎自动恢复，不要中途停下来询问用户。
+- 只有识别为 400 请求错误、登录/鉴权/订阅问题、本地 CLI 缺失或权限错误等硬阻塞时，才允许结束本轮自动执行。
 - 不允许因为执行引擎一句“已完成”就直接结束；必须经过任务复核和主线终态复核。
 - 用户需求明确且当前任务可直接完成时，必须一次性完成本轮应交付的全部工作；禁止做一半后用“如果你要”“是否继续”之类的话术停下，也禁止用客套套话收尾。
 - 真正执行前确认，真正结束前验证。

hosts/gemini/extension/commands/helloloop.toml

@@ -5,7 +5,7 @@ prompt = """
 执行要求：
 
 1. 自动识别目标仓库与开发文档；如果用户在命令后提供了参数，必须同时保留其中的显式路径和自然语言补充要求，不要靠固定关键词硬编码判断。
-2. 当前宿主是 `Gemini`，默认优先使用 `Gemini` 作为执行引擎；如果用户明确要求改用 `Codex` 或 `Claude`，必须先确认，不允许静默切换。
+2. 当前宿主是 `Gemini`；如果用户未明确指定执行引擎，必须先确认本轮引擎，`Gemini` 只可作为推荐项，不允许自动选中；如果用户明确要求改用 `Codex` 或 `Claude`，必须先确认，不允许静默切换。
 3. 如果当前目录没有明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再询问用户开发文档路径。
 4. 项目路径对外只有一个概念；如果用户给出的项目路径不存在，直接按新项目路径处理，不要再单独追问“新项目路径”。
 5. 分析当前代码与开发文档之间的真实进度和偏差，并判断当前项目目录与开发文档目标是否匹配。
@@ -28,7 +28,7 @@ prompt = """
 8. 如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，必须先明确提示用户，并确认是继续现有项目、还是清理后按文档重建。
 9. 用户未确认前，不要开始正式修改代码。
 10. 用户确认后，继续用当前确认的执行引擎原生工具推进 backlog；每个任务完成后还要再做任务完成复核，backlog 清空后还要再做主线终态复核，直到开发文档的最终目标完成，且相关测试、验证、验收都已通过；遇到硬阻塞或需要用户补充关键信息时再停下。
-11. 如果当前引擎在运行中遇到登录失效、额度耗尽、429 限流等问题，必须暂停并询问是否切换到其他可用引擎。
+11. 如果当前引擎在运行中遇到 429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎自动恢复，不要中途停下来询问用户；只有明确硬阻塞时才停止。
 12. 如果用户给了开发文档但找不到项目仓库，或给了项目路径但找不到开发文档，必须停下来询问。
 13. 用户需求明确且当前任务可直接完成时，必须一次性完成本轮应交付的全部工作；禁止做一半后用“如果你要”“是否继续”之类的话术停下，也禁止用“希望这对你有帮助”等套话收尾。
 14. Windows 上优先用安全的文件与 shell 操作；禁止危险删除、硬重置、强推和其他破坏性命令。

hosts/gemini/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "HelloLoop 的 Gemini CLI 原生扩展，用于按开发文档接续推进项目开发。",
   "contextFileName": "GEMINI.md",
   "excludeTools": [

package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件",
   "author": "HelloLoop",
   "license": "Apache-2.0",
@@ -30,7 +30,7 @@
     "templates"
   ],
   "scripts": {
-    "test": "node --test tests/analyze_cli.test.mjs tests/analyze_intent_cli.test.mjs tests/engine_selection_cli.test.mjs tests/cli_surface.test.mjs tests/cli_doctor_surface.test.mjs tests/host_lifecycle_integrity.test.mjs tests/host_single_host_integrity.test.mjs tests/install_script.test.mjs tests/mainline_continuation.test.mjs tests/multi_host_runtime.test.mjs tests/process_shell.test.mjs tests/prompt_guardrails.test.mjs tests/ralph_loop.test.mjs tests/plugin_bundle.test.mjs"
+    "test": "node --test tests/analyze_cli.test.mjs tests/analyze_intent_cli.test.mjs tests/engine_selection_cli.test.mjs tests/cli_surface.test.mjs tests/cli_doctor_surface.test.mjs tests/host_lifecycle_integrity.test.mjs tests/host_single_host_integrity.test.mjs tests/install_script.test.mjs tests/mainline_continuation.test.mjs tests/multi_host_runtime.test.mjs tests/process_shell.test.mjs tests/prompt_guardrails.test.mjs tests/ralph_loop.test.mjs tests/runtime_recovery.test.mjs tests/plugin_bundle.test.mjs"
   },
   "engines": {
     "node": ">=20"