helloloop 0.8.4 → 0.8.6

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件，Codex 路径为首发与参考实现。",
   "author": {
     "name": "HelloLoop"

package/README.md

@@ -97,6 +97,22 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 - 如果 backlog 清空了，但主线终态复核仍发现文档目标还有缺口，`HelloLoop` 会自动重新分析并继续推进
 - 如果模型只做了一半就想停下来给“下一步建议”，`HelloLoop` 会优先按主线目标继续推进，而不是把半成品当完成
 
+## 后台监督执行
+
+从当前版本开始，`HelloLoop` 的自动执行主线统一走 **detached supervisor + host lease** 模式：
+
+- `analyze` 确认后的自动执行、`run-once`、`run-loop` 都默认切到后台 supervisor
+- 当前对话 turn 就算被误按 `Esc`、被宿主暂停、或当前工具调用被中断，后台 supervisor 仍会继续
+- 原有的 15 分钟级恢复、健康探测、同引擎自动恢复，也会继续由这个后台 supervisor 接管
+- 这不是“当前进程死掉后每 15 分钟重新拉起一遍主进程”，而是 supervisor 本身持续存活，所以恢复链不会因为当前 turn 消失而断掉
+- 真正的停止边界改成 **宿主租约**：只要宿主 CLI 窗口 / 进程还活着，任务就继续；如果宿主窗口真的关闭，HelloLoop 才会停止当前子进程并把任务回退为 `pending`
+
+常见场景：
+
+- 在 `Codex` / `Claude` / `Gemini` 宿主里运行 `helloloop`：确认后默认转入后台执行，可用 `helloloop status` 查看进度
+- 在普通终端里运行 `npx helloloop`、`npx helloloop run-once`、`npx helloloop run-loop`：默认也会转入后台执行
+- `--supervised` 仍然保留，但现在只是兼容参数，不再是开启后台 supervisor 的前提
+
 ## 无人值守恢复
 
 `HelloLoop` 的设计目标不是“跑一轮停一轮”，而是启动前确认一次，启动后持续无人值守推进。
@@ -120,6 +136,13 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 
 如果你明确指定或确认了本轮引擎，`HelloLoop` 在自动恢复阶段也会继续锁定该引擎，不会擅自切换。
 
+但要特别注意：
+
+- 在 `Codex` / `Claude` / `Gemini` 宿主里，当前 turn 被误按 `Esc`、当前工具调用被取消，或当前会话暂时暂停时，只要宿主窗口本身还活着，后台 supervisor 仍会继续，原有自动恢复节奏也会继续生效
+- 如果真正关闭了宿主 CLI 窗口、终端进程结束，或宿主租约已经失效，HelloLoop 会停止当前子进程，并把未完成任务回退为 `pending`
+- 也就是说：**当前 turn 取消 ≠ 停止 HelloLoop；关闭宿主窗口 = 停止 HelloLoop**
+- 宿主窗口已经关闭后，HelloLoop 不会再脱离宿主自行无限后台驻留；这时需要你重新打开宿主并再次显式调用 `helloloop` 来接续
+
 ## 全局告警配置
 
 如果希望在“自动恢复彻底停止”后收到邮件告警，可在：
@@ -154,6 +177,46 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 - 建议把 SMTP 密码放在环境变量里，不要明文写进配置文件
 - 邮件只在“本轮不再继续自动重试”时发送，不会每次失败都刷屏
 
+## 终端并发上限
+
+`HelloLoop` 不会主动再额外弹出一堆可见终端窗口；这里的：
+
+- **显示终端** 指当前前台运行中的 `helloloop` 会话
+- **背景终端** 指 detached supervisor 后台会话
+
+默认限制为：
+
+- 显示终端最多 `8`
+- 背景终端最多 `8`
+- 显示 + 背景合计最多 `8`
+
+可在：
+
+```text
+~/.helloloop/settings.json
+```
+
+中自行调整，例如：
+
+```json
+{
+  "runtime": {
+    "terminalConcurrency": {
+      "enabled": true,
+      "visibleMax": 8,
+      "backgroundMax": 8,
+      "totalMax": 8
+    }
+  }
+}
+```
+
+说明：
+
+- 只要合计并发达到 `totalMax`，新前台会话或新的后台 supervisor 都不会再继续启动
+- 如果只是想临时完全关闭这个保护，可把 `enabled` 设为 `false`
+- 这个限制主要用于避免同时占用过多本机终端资源，或因为并发过高触发模型 / API 限速
+
 ## 自动发现与交互逻辑
 
 ### 1. 只输入 `npx helloloop`
@@ -393,6 +456,7 @@ npx helloloop
 | `-y` / `--yes` | 跳过执行确认直接开始；但如果未显式指定引擎，会直接报错而不是自动选引擎 |
 | `--repo <dir>` | 高级覆盖：显式指定项目仓库 |
 | `--docs <dir|file>` | 高级覆盖：显式指定开发文档 |
+| `--supervised` | 兼容保留；当前版本默认已启用 detached supervisor |
 | `--rebuild-existing` | 项目与文档冲突时，自动清理现有项目后重建 |
 | `--host <name>` | 安装宿主：`codex` / `claude` / `gemini` / `all` |
 | `--config-dir <dir>` | 状态目录名，默认 `.helloloop` |
@@ -463,7 +527,8 @@ git push origin vX.Y.Z-beta.N
 
 - 正式版本使用 npm `latest` 渠道，beta 版本使用 npm `beta` 渠道
 - 如果测试、版本校验或打包检查失败，npm 发布与 GitHub Release 都不会继续执行
-- `0.8.4` 起已补齐 Codex Structured Outputs 严格 schema 兼容，并修复快退出 CLI 在 CI 中可能触发的 `stdin EPIPE` 问题，避免发布工作流被非业务性故障打断
+- `0.8.6` 起已统一为全流程后台 supervisor：`analyze` 确认后的自动执行、`run-once`、`run-loop` 默认都后台化，不再要求普通终端显式追加 `--supervised`
+- GitHub Release 阶段现已改为使用官方 `gh` CLI + `generate-notes` API 创建 / 更新 release，不再依赖会触发 Node runtime deprecation warning 的第三方 action
 
 ## 宿主写入范围
 

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

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

package/hosts/gemini/extension/gemini-extension.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "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/analyze_runtime_failure.test.mjs tests/output_schema_contract.test.mjs tests/engine_process_support.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"
+    "test": "node --test tests/analyze_cli.test.mjs tests/analyze_cli_path_resolution.test.mjs tests/analyze_intent_cli.test.mjs tests/analyze_runtime_failure.test.mjs tests/output_schema_contract.test.mjs tests/engine_process_support.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/user_settings_lifecycle.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/multi_host_runtime_recovery.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 tests/supervisor_runtime.test.mjs tests/terminal_session_limits.test.mjs"
   },
   "engines": {
     "node": ">=20"

package/src/analyzer.mjs

@@ -1,9 +1,8 @@
 import path from "node:path";
 
-import { summarizeBacklog, selectNextTask } from "./backlog.mjs";
+import { summarizeBacklog } from "./backlog.mjs";
 import { nowIso, writeJson, writeText, readTextIfExists } from "./common.mjs";
 import {
-  loadBacklog,
   loadPolicy,
   loadProjectConfig,
   scaffoldIfMissing,
@@ -17,205 +16,17 @@ import {
   rememberEngineSelection,
   resolveEngineSelection,
 } from "./engine_selection.mjs";
+import {
+  buildAnalysisSummaryText,
+  buildCurrentWorkspaceDiscovery,
+  normalizeAnalysisPayload,
+  persistAnalysisFailure,
+  renderAnalysisState,
+  summarizeFailedAnalysisResult,
+} from "./analyzer_support.mjs";
 import { runEngineTask } from "./process.mjs";
 import { buildAnalysisPrompt } from "./analyze_prompt.mjs";
 
-function renderAnalysisState(context, backlog, analysis) {
-  const summary = summarizeBacklog(backlog);
-  const nextTask = selectNextTask(backlog);
-
-  return [
-    "## 当前状态",
-    `- backlog 文件：${path.relative(context.repoRoot, context.backlogFile).replaceAll("\\", "/")}`,
-    `- 总任务数：${summary.total}`,
-    `- 已完成：${summary.done}`,
-    `- 待处理：${summary.pending}`,
-    `- 进行中：${summary.inProgress}`,
-    `- 失败：${summary.failed}`,
-    `- 阻塞：${summary.blocked}`,
-    `- 当前任务：${nextTask ? nextTask.title : "无"}`,
-    `- 最近结果：${analysis.summary.currentState}`,
-    `- 下一建议：${analysis.summary.nextAction}`,
-  ].join("\n");
-}
-
-function createEmptyBacklogSummary() {
-  return {
-    total: 0,
-    pending: 0,
-    inProgress: 0,
-    done: 0,
-    failed: 0,
-    blocked: 0,
-  };
-}
-
-function getExistingBacklogSnapshot(context) {
-  try {
-    const backlog = loadBacklog(context);
-    return {
-      summary: summarizeBacklog(backlog),
-      nextTask: selectNextTask(backlog),
-    };
-  } catch {
-    return {
-      summary: createEmptyBacklogSummary(),
-      nextTask: null,
-    };
-  }
-}
-
-function firstMeaningfulLine(text, fallback) {
-  return String(text || "")
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .find(Boolean) || fallback;
-}
-
-function summarizeFailedAnalysisResult(result, fallback) {
-  const combined = [
-    String(result?.stdout || "").trim(),
-    String(result?.stderr || "").trim(),
-  ].filter(Boolean).join("\n\n").trim();
-  return combined || fallback;
-}
-
-function renderAnalysisFailureState(context, backlogSummary, nextTask, failureSummary, runDir = "") {
-  const runDirHint = runDir
-    ? path.relative(context.repoRoot, runDir).replaceAll("\\", "/")
-    : "";
-
-  return [
-    "## 当前状态",
-    `- backlog 文件：${path.relative(context.repoRoot, context.backlogFile).replaceAll("\\", "/")}`,
-    `- 总任务数：${backlogSummary.total}`,
-    `- 已完成：${backlogSummary.done}`,
-    `- 待处理：${backlogSummary.pending}`,
-    `- 进行中：${backlogSummary.inProgress}`,
-    `- 失败：${backlogSummary.failed}`,
-    `- 阻塞：${backlogSummary.blocked}`,
-    `- 当前任务：${nextTask ? nextTask.title : "无"}`,
-    `- 最近结果：${firstMeaningfulLine(failureSummary, "HelloLoop 分析失败")}`,
-    `- 下一建议：${runDirHint ? `先检查 ${runDirHint} 中的日志后再重新执行 npx helloloop` : "修复错误后重新执行 npx helloloop"}`,
-  ].join("\n");
-}
-
-function persistAnalysisFailure(context, failureSummary, runDir = "") {
-  const snapshot = getExistingBacklogSnapshot(context);
-  writeStatus(context, {
-    ok: false,
-    stage: "analysis_failed",
-    taskId: null,
-    taskTitle: "",
-    runDir,
-    summary: snapshot.summary,
-    message: failureSummary,
-  });
-  writeStateMarkdown(
-    context,
-    renderAnalysisFailureState(context, snapshot.summary, snapshot.nextTask, failureSummary, runDir),
-  );
-}
-
-function sanitizeTask(task) {
-  return {
-    id: String(task.id || "").trim(),
-    title: String(task.title || "").trim(),
-    status: ["done", "blocked"].includes(String(task.status || "")) ? String(task.status) : "pending",
-    priority: ["P0", "P1", "P2", "P3"].includes(String(task.priority || "")) ? String(task.priority) : "P2",
-    risk: ["medium", "high", "critical"].includes(String(task.risk || "")) ? String(task.risk) : "low",
-    goal: String(task.goal || "").trim(),
-    docs: Array.isArray(task.docs) ? task.docs.map((item) => String(item || "").trim()).filter(Boolean) : [],
-    paths: Array.isArray(task.paths) ? task.paths.map((item) => String(item || "").trim()).filter(Boolean) : [],
-    acceptance: Array.isArray(task.acceptance) ? task.acceptance.map((item) => String(item || "").trim()).filter(Boolean) : [],
-    dependsOn: Array.isArray(task.dependsOn) ? task.dependsOn.map((item) => String(item || "").trim()).filter(Boolean) : [],
-    verify: Array.isArray(task.verify) ? task.verify.map((item) => String(item || "").trim()).filter(Boolean) : [],
-  };
-}
-
-function normalizeAnalysisPayload(payload, docsEntries) {
-  const summary = {
-    currentState: String(payload?.summary?.currentState || "").trim() || "已完成接续分析。",
-    implemented: Array.isArray(payload?.summary?.implemented) ? payload.summary.implemented.map((item) => String(item || "").trim()).filter(Boolean) : [],
-    remaining: Array.isArray(payload?.summary?.remaining) ? payload.summary.remaining.map((item) => String(item || "").trim()).filter(Boolean) : [],
-    nextAction: String(payload?.summary?.nextAction || "").trim() || "查看下一任务。",
-  };
-  const tasks = Array.isArray(payload.tasks)
-    ? payload.tasks.map((task) => sanitizeTask(task)).filter((task) => (
-      task.id && task.title && task.goal && task.acceptance.length
-    ))
-    : [];
-
-  if (!tasks.length && summary.remaining.length) {
-    throw new Error("分析结果无效：仍存在剩余工作，但未生成可用任务。");
-  }
-
-  const requestInterpretation = payload?.requestInterpretation && typeof payload.requestInterpretation === "object"
-    ? {
-      summary: String(payload.requestInterpretation.summary || "").trim(),
-      priorities: Array.isArray(payload.requestInterpretation.priorities)
-        ? payload.requestInterpretation.priorities.map((item) => String(item || "").trim()).filter(Boolean)
-        : [],
-      cautions: Array.isArray(payload.requestInterpretation.cautions)
-        ? payload.requestInterpretation.cautions.map((item) => String(item || "").trim()).filter(Boolean)
-        : [],
-    }
-    : null;
-  const repoDecision = payload?.repoDecision && typeof payload.repoDecision === "object"
-    ? {
-      compatibility: ["compatible", "conflict", "uncertain"].includes(String(payload.repoDecision.compatibility || ""))
-        ? String(payload.repoDecision.compatibility)
-        : "compatible",
-      action: ["continue_existing", "confirm_rebuild", "start_new"].includes(String(payload.repoDecision.action || ""))
-        ? String(payload.repoDecision.action)
-        : "continue_existing",
-      reason: String(payload.repoDecision.reason || "").trim(),
-    }
-    : null;
-
-  return {
-    project: String(payload.project || "").trim() || "helloloop-project",
-    summary,
-    constraints: Array.isArray(payload.constraints)
-      ? payload.constraints.map((item) => String(item || "").trim()).filter(Boolean)
-      : [],
-    requestInterpretation: requestInterpretation && (
-      requestInterpretation.summary
-      || requestInterpretation.priorities.length
-      || requestInterpretation.cautions.length
-    )
-      ? requestInterpretation
-      : null,
-    repoDecision: repoDecision && repoDecision.reason
-      ? repoDecision
-      : null,
-    tasks,
-    requiredDocs: docsEntries,
-  };
-}
-
-function buildAnalysisSummaryText(context, analysis, backlog, engineResolution) {
-  const summary = summarizeBacklog(backlog);
-  const nextTask = selectNextTask(backlog);
-
-  return [
-    "HelloLoop 已完成接续分析。",
-    `项目仓库：${context.repoRoot}`,
-    `开发文档：${analysis.requiredDocs.join(", ")}`,
-    `执行引擎：${engineResolution?.displayName || "未记录"}`,
-    "",
-    "当前进度：",
-    analysis.summary.currentState,
-    "",
-    `任务统计：done ${summary.done} / pending ${summary.pending} / blocked ${summary.blocked}`,
-    nextTask ? `下一任务：${nextTask.title}` : "下一任务：暂无可执行任务",
-    "",
-    "下一步建议：",
-    `- npx helloloop`,
-    `- npx helloloop --dry-run`,
-  ].join("\n");
-}
-
 async function analyzeResolvedWorkspace(context, discovery, options = {}) {
   scaffoldIfMissing(context);
   const policy = loadPolicy(context);
@@ -268,9 +79,20 @@ async function analyzeResolvedWorkspace(context, discovery, options = {}) {
     outputSchemaFile: schemaFile,
     outputPrefix: `${engineResolution.engine}-analysis`,
     skipGitRepoCheck: true,
+    hostLease: options.hostLease || null,
   });
 
   if (!analysisResult.ok) {
+    if (analysisResult.leaseExpired) {
+      return {
+        ok: false,
+        code: "host-lease-stopped",
+        summary: analysisResult.leaseReason || "检测到宿主窗口已关闭，主线终态复核已停止。",
+        stopped: true,
+        engineResolution,
+        discovery,
+      };
+    }
     const failureSummary = summarizeFailedAnalysisResult(
       analysisResult,
       `${engineResolution.displayName} 接续分析失败。`,
@@ -368,38 +190,6 @@ async function analyzeResolvedWorkspace(context, discovery, options = {}) {
   };
 }
 
-function buildCurrentWorkspaceDiscovery(context, docsEntries) {
-  return {
-    ok: true,
-    repoRoot: context.repoRoot,
-    docsEntries,
-    resolvedDocs: docsEntries,
-    resolution: {
-      repo: {
-        source: "current_repo",
-        sourceLabel: "当前项目",
-        confidence: "high",
-        confidenceLabel: "高",
-        path: context.repoRoot,
-        exists: true,
-        basis: [
-          "已在当前项目基础上执行主线终态复核。",
-        ],
-      },
-      docs: {
-        source: "existing_state",
-        sourceLabel: "已有 .helloloop 配置",
-        confidence: "high",
-        confidenceLabel: "高",
-        entries: docsEntries,
-        basis: [
-          "已复用 `.helloloop/project.json` 中记录的 requiredDocs。",
-        ],
-      },
-    },
-  };
-}
-
 export async function reanalyzeCurrentWorkspace(context, options = {}) {
   const existingProjectConfig = loadProjectConfig(context);
   const docsEntries = Array.isArray(options.requiredDocs) && options.requiredDocs.length

package/src/analyzer_support.mjs

@@ -0,0 +1,232 @@
+import path from "node:path";
+
+import { selectNextTask, summarizeBacklog } from "./backlog.mjs";
+import { loadBacklog, writeStateMarkdown, writeStatus } from "./config.mjs";
+
+export function renderAnalysisState(context, backlog, analysis) {
+  const summary = summarizeBacklog(backlog);
+  const nextTask = selectNextTask(backlog);
+
+  return [
+    "## 当前状态",
+    `- backlog 文件：${path.relative(context.repoRoot, context.backlogFile).replaceAll("\\", "/")}`,
+    `- 总任务数：${summary.total}`,
+    `- 已完成：${summary.done}`,
+    `- 待处理：${summary.pending}`,
+    `- 进行中：${summary.inProgress}`,
+    `- 失败：${summary.failed}`,
+    `- 阻塞：${summary.blocked}`,
+    `- 当前任务：${nextTask ? nextTask.title : "无"}`,
+    `- 最近结果：${analysis.summary.currentState}`,
+    `- 下一建议：${analysis.summary.nextAction}`,
+  ].join("\n");
+}
+
+function createEmptyBacklogSummary() {
+  return {
+    total: 0,
+    pending: 0,
+    inProgress: 0,
+    done: 0,
+    failed: 0,
+    blocked: 0,
+  };
+}
+
+export function getExistingBacklogSnapshot(context) {
+  try {
+    const backlog = loadBacklog(context);
+    return {
+      summary: summarizeBacklog(backlog),
+      nextTask: selectNextTask(backlog),
+    };
+  } catch {
+    return {
+      summary: createEmptyBacklogSummary(),
+      nextTask: null,
+    };
+  }
+}
+
+function firstMeaningfulLine(text, fallback) {
+  return String(text || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean) || fallback;
+}
+
+export function summarizeFailedAnalysisResult(result, fallback) {
+  const combined = [
+    String(result?.stdout || "").trim(),
+    String(result?.stderr || "").trim(),
+  ].filter(Boolean).join("\n\n").trim();
+  return combined || fallback;
+}
+
+function renderAnalysisFailureState(context, backlogSummary, nextTask, failureSummary, runDir = "") {
+  const runDirHint = runDir
+    ? path.relative(context.repoRoot, runDir).replaceAll("\\", "/")
+    : "";
+
+  return [
+    "## 当前状态",
+    `- backlog 文件：${path.relative(context.repoRoot, context.backlogFile).replaceAll("\\", "/")}`,
+    `- 总任务数：${backlogSummary.total}`,
+    `- 已完成：${backlogSummary.done}`,
+    `- 待处理：${backlogSummary.pending}`,
+    `- 进行中：${backlogSummary.inProgress}`,
+    `- 失败：${backlogSummary.failed}`,
+    `- 阻塞：${backlogSummary.blocked}`,
+    `- 当前任务：${nextTask ? nextTask.title : "无"}`,
+    `- 最近结果：${firstMeaningfulLine(failureSummary, "HelloLoop 分析失败")}`,
+    `- 下一建议：${runDirHint ? `先检查 ${runDirHint} 中的日志后再重新执行 npx helloloop` : "修复错误后重新执行 npx helloloop"}`,
+  ].join("\n");
+}
+
+export function persistAnalysisFailure(context, failureSummary, runDir = "") {
+  const snapshot = getExistingBacklogSnapshot(context);
+  writeStatus(context, {
+    ok: false,
+    stage: "analysis_failed",
+    taskId: null,
+    taskTitle: "",
+    runDir,
+    summary: snapshot.summary,
+    message: failureSummary,
+  });
+  writeStateMarkdown(
+    context,
+    renderAnalysisFailureState(context, snapshot.summary, snapshot.nextTask, failureSummary, runDir),
+  );
+}
+
+function sanitizeTask(task) {
+  return {
+    id: String(task.id || "").trim(),
+    title: String(task.title || "").trim(),
+    status: ["done", "blocked"].includes(String(task.status || "")) ? String(task.status) : "pending",
+    priority: ["P0", "P1", "P2", "P3"].includes(String(task.priority || "")) ? String(task.priority) : "P2",
+    risk: ["medium", "high", "critical"].includes(String(task.risk || "")) ? String(task.risk) : "low",
+    goal: String(task.goal || "").trim(),
+    docs: Array.isArray(task.docs) ? task.docs.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    paths: Array.isArray(task.paths) ? task.paths.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    acceptance: Array.isArray(task.acceptance) ? task.acceptance.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    dependsOn: Array.isArray(task.dependsOn) ? task.dependsOn.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    verify: Array.isArray(task.verify) ? task.verify.map((item) => String(item || "").trim()).filter(Boolean) : [],
+  };
+}
+
+export function normalizeAnalysisPayload(payload, docsEntries) {
+  const summary = {
+    currentState: String(payload?.summary?.currentState || "").trim() || "已完成接续分析。",
+    implemented: Array.isArray(payload?.summary?.implemented) ? payload.summary.implemented.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    remaining: Array.isArray(payload?.summary?.remaining) ? payload.summary.remaining.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    nextAction: String(payload?.summary?.nextAction || "").trim() || "查看下一任务。",
+  };
+  const tasks = Array.isArray(payload.tasks)
+    ? payload.tasks.map((task) => sanitizeTask(task)).filter((task) => (
+      task.id && task.title && task.goal && task.acceptance.length
+    ))
+    : [];
+
+  if (!tasks.length && summary.remaining.length) {
+    throw new Error("分析结果无效：仍存在剩余工作，但未生成可用任务。");
+  }
+
+  const requestInterpretation = payload?.requestInterpretation && typeof payload.requestInterpretation === "object"
+    ? {
+      summary: String(payload.requestInterpretation.summary || "").trim(),
+      priorities: Array.isArray(payload.requestInterpretation.priorities)
+        ? payload.requestInterpretation.priorities.map((item) => String(item || "").trim()).filter(Boolean)
+        : [],
+      cautions: Array.isArray(payload.requestInterpretation.cautions)
+        ? payload.requestInterpretation.cautions.map((item) => String(item || "").trim()).filter(Boolean)
+        : [],
+    }
+    : null;
+  const repoDecision = payload?.repoDecision && typeof payload.repoDecision === "object"
+    ? {
+      compatibility: ["compatible", "conflict", "uncertain"].includes(String(payload.repoDecision.compatibility || ""))
+        ? String(payload.repoDecision.compatibility)
+        : "compatible",
+      action: ["continue_existing", "confirm_rebuild", "start_new"].includes(String(payload.repoDecision.action || ""))
+        ? String(payload.repoDecision.action)
+        : "continue_existing",
+      reason: String(payload.repoDecision.reason || "").trim(),
+    }
+    : null;
+
+  return {
+    project: String(payload.project || "").trim() || "helloloop-project",
+    summary,
+    constraints: Array.isArray(payload.constraints)
+      ? payload.constraints.map((item) => String(item || "").trim()).filter(Boolean)
+      : [],
+    requestInterpretation: requestInterpretation && (
+      requestInterpretation.summary
+      || requestInterpretation.priorities.length
+      || requestInterpretation.cautions.length
+    )
+      ? requestInterpretation
+      : null,
+    repoDecision: repoDecision && repoDecision.reason
+      ? repoDecision
+      : null,
+    tasks,
+    requiredDocs: docsEntries,
+  };
+}
+
+export function buildAnalysisSummaryText(context, analysis, backlog, engineResolution) {
+  const summary = summarizeBacklog(backlog);
+  const nextTask = selectNextTask(backlog);
+
+  return [
+    "HelloLoop 已完成接续分析。",
+    `项目仓库：${context.repoRoot}`,
+    `开发文档：${analysis.requiredDocs.join(", ")}`,
+    `执行引擎：${engineResolution?.displayName || "未记录"}`,
+    "",
+    "当前进度：",
+    analysis.summary.currentState,
+    "",
+    `任务统计：done ${summary.done} / pending ${summary.pending} / blocked ${summary.blocked}`,
+    nextTask ? `下一任务：${nextTask.title}` : "下一任务：暂无可执行任务",
+    "",
+    "下一步建议：",
+    `- npx helloloop`,
+    `- npx helloloop --dry-run`,
+  ].join("\n");
+}
+
+export function buildCurrentWorkspaceDiscovery(context, docsEntries) {
+  return {
+    ok: true,
+    repoRoot: context.repoRoot,
+    docsEntries,
+    resolvedDocs: docsEntries,
+    resolution: {
+      repo: {
+        source: "current_repo",
+        sourceLabel: "当前项目",
+        confidence: "high",
+        confidenceLabel: "高",
+        path: context.repoRoot,
+        exists: true,
+        basis: [
+          "已在当前项目基础上执行主线终态复核。",
+        ],
+      },
+      docs: {
+        source: "existing_state",
+        sourceLabel: "已有 .helloloop 配置",
+        confidence: "high",
+        confidenceLabel: "高",
+        entries: docsEntries,
+        basis: [
+          "已复用 `.helloloop/project.json` 中记录的 requiredDocs。",
+        ],
+      },
+    },
+  };
+}