helloloop 0.8.2 → 0.8.5

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -1,5 +1,9 @@
 # HelloLoop
 
+> [!WARNING]
+> **风险提示**
+> 使用 `HelloLoop` 执行持续 / 持久型任务仍存在不可完全控制的风险。虽然项目已经加入高危行为管控与防护策略，但仍不能排除误删数据、误改文件、异常覆盖或其他不可预期后果。请在使用前务必先备份重要数据，并自行通过人工或借助 AI 对 `HelloLoop` 的安全风险做评估与审计；因使用本插件造成的数据丢失或其他损失，项目方不承担责任。
+
 `HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发、测试、验收，直到最终目标完成”收敛成一条统一、可确认、可追踪的标准流程。
 
 它的核心原则很简单：
@@ -93,6 +97,20 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 - 如果 backlog 清空了，但主线终态复核仍发现文档目标还有缺口，`HelloLoop` 会自动重新分析并继续推进
 - 如果模型只做了一半就想停下来给“下一步建议”，`HelloLoop` 会优先按主线目标继续推进，而不是把半成品当完成
 
+## 后台监督执行
+
+从 `Codex CLI`、`Claude Code`、`Gemini CLI` 这些宿主里发起 `HelloLoop` 时，确认自动执行后会默认切到 **detached supervisor + host lease** 模式：
+
+- 当前对话 turn 就算被误按 `Esc`、被宿主暂停、或当前工具调用被中断，后台 supervisor 仍会继续
+- 原有的 15 分钟级恢复、健康探测、同引擎自动恢复，也会继续由这个后台 supervisor 接管
+- 这不是“当前进程死掉后每 15 分钟重新拉起一遍主进程”，而是 supervisor 本身持续存活，所以恢复链不会因为当前 turn 消失而断掉
+- 真正的停止边界改成 **宿主租约**：只要宿主 CLI 窗口 / 进程还活着，任务就继续；如果宿主窗口真的关闭，HelloLoop 才会停止当前子进程并把任务回退为 `pending`
+
+常见场景：
+
+- 在 `Codex` / `Claude` / `Gemini` 宿主里运行 `helloloop`：确认后默认转入后台执行，可用 `helloloop status` 查看进度
+- 在普通终端里运行 `npx helloloop run-once --supervised` 或 `npx helloloop run-loop --supervised`：即使中途 `Ctrl+C` 当前命令，只要终端窗口没关，后台 supervisor 仍会继续
+
 ## 无人值守恢复
 
 `HelloLoop` 的设计目标不是“跑一轮停一轮”，而是启动前确认一次，启动后持续无人值守推进。
@@ -116,6 +134,13 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 
 如果你明确指定或确认了本轮引擎，`HelloLoop` 在自动恢复阶段也会继续锁定该引擎，不会擅自切换。
 
+但要特别注意：
+
+- 在 `Codex` / `Claude` / `Gemini` 宿主里，当前 turn 被误按 `Esc`、当前工具调用被取消，或当前会话暂时暂停时，只要宿主窗口本身还活着，后台 supervisor 仍会继续，原有自动恢复节奏也会继续生效
+- 如果真正关闭了宿主 CLI 窗口、终端进程结束，或宿主租约已经失效，HelloLoop 会停止当前子进程，并把未完成任务回退为 `pending`
+- 也就是说：**当前 turn 取消 ≠ 停止 HelloLoop；关闭宿主窗口 = 停止 HelloLoop**
+- 宿主窗口已经关闭后，HelloLoop 不会再脱离宿主自行无限后台驻留；这时需要你重新打开宿主并再次显式调用 `helloloop` 来接续
+
 ## 全局告警配置
 
 如果希望在“自动恢复彻底停止”后收到邮件告警，可在：
@@ -389,6 +414,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` |
@@ -421,6 +447,47 @@ npx helloloop doctor --host all
 npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_HOME> --gemini-home <GEMINI_HOME>
 ```
 
+## 发布流程
+
+`HelloLoop` 当前采用 **tag 驱动发布**：
+
+1. 先在源码仓库完成版本号更新（`package.json` 与各宿主 manifest 保持一致）
+2. 本地先执行：
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+3. 推送 Git tag：
+
+```bash
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+或 beta 版本：
+
+```bash
+git tag vX.Y.Z-beta.N
+git push origin vX.Y.Z-beta.N
+```
+
+随后 GitHub Actions `Publish to npm` 会自动执行：
+
+- tag / 版本一致性校验
+- `npm test`
+- `npm pack --dry-run`
+- `npm publish`
+- GitHub Release
+
+补充说明：
+
+- 正式版本使用 npm `latest` 渠道，beta 版本使用 npm `beta` 渠道
+- 如果测试、版本校验或打包检查失败，npm 发布与 GitHub Release 都不会继续执行
+- `0.8.5` 起已补齐 host-aware supervisor 后台执行链路：宿主内自动执行默认后台化，当前 turn 被 `Esc` / cancel 不再直接打断 HelloLoop 主线
+- 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.2",
+  "version": "0.8.5",
   "description": "HelloLoop 的 Claude Code 原生插件元数据，用于多 CLI 宿主分发。",
   "author": {
     "name": "HelloLoop"

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.8.2",
+  "version": "0.8.5",
   "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/runtime_recovery.test.mjs tests/plugin_bundle.test.mjs"
+    "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 tests/supervisor_runtime.test.mjs"
   },
   "engines": {
     "node": ">=20"

package/src/analyzer.mjs

@@ -1,8 +1,14 @@
 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 { loadPolicy, loadProjectConfig, scaffoldIfMissing, writeStateMarkdown, writeStatus } from "./config.mjs";
+import {
+  loadPolicy,
+  loadProjectConfig,
+  scaffoldIfMissing,
+  writeStateMarkdown,
+  writeStatus,
+} from "./config.mjs";
 import { createContext } from "./context.mjs";
 import { discoverWorkspace } from "./discovery.mjs";
 import { readDocumentPackets } from "./doc_loader.mjs";
@@ -10,127 +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 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);
@@ -183,13 +79,33 @@ 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} 接续分析失败。`,
+    );
+    persistAnalysisFailure(
+      context,
+      failureSummary,
+      runDir,
+    );
     return {
       ok: false,
       code: "analysis_failed",
-      summary: analysisResult.stderr || analysisResult.stdout || `${engineResolution.displayName} 接续分析失败。`,
+      summary: failureSummary,
       engineResolution,
       discovery,
     };
@@ -199,6 +115,11 @@ async function analyzeResolvedWorkspace(context, discovery, options = {}) {
   try {
     payload = JSON.parse(analysisResult.finalMessage);
   } catch (error) {
+    persistAnalysisFailure(
+      context,
+      `${engineResolution.displayName} 分析结果无法解析为 JSON：${String(error?.message || error || "")}`,
+      runDir,
+    );
     return {
       ok: false,
       code: "invalid_analysis_json",
@@ -208,7 +129,24 @@ async function analyzeResolvedWorkspace(context, discovery, options = {}) {
     };
   }
 
-  const analysis = normalizeAnalysisPayload(payload, discovery.docsEntries);
+  let analysis;
+  try {
+    analysis = normalizeAnalysisPayload(payload, discovery.docsEntries);
+  } catch (error) {
+    persistAnalysisFailure(
+      context,
+      `${engineResolution.displayName} 分析结果无效：${String(error?.message || error || "")}`,
+      runDir,
+    );
+    return {
+      ok: false,
+      code: "invalid_analysis_payload",
+      summary: `${engineResolution.displayName} 分析结果无效：${String(error?.message || error || "")}`,
+      engineResolution,
+      discovery,
+    };
+  }
+
   const backlog = {
     version: 1,
     project: analysis.project,
@@ -252,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。",
+        ],
+      },
+    },
+  };
+}

package/src/cli.mjs

@@ -13,6 +13,7 @@ import {
 } from "./cli_command_handlers.mjs";
 import { resolveContextFromOptions, resolveStandardCommandOptions } from "./cli_context.mjs";
 import { runDoctor } from "./cli_support.mjs";
+import { runSupervisedCommandFromSessionFile } from "./supervisor_runtime.mjs";
 
 export async function runCli(argv) {
   const parsed = parseArgs(argv);
@@ -21,6 +22,13 @@ export async function runCli(argv) {
     printHelp();
     return;
   }
+  if (command === "__supervise") {
+    if (!parsed.options.sessionFile) {
+      throw new Error("缺少 --session-file，无法启动 HelloLoop supervisor。");
+    }
+    await runSupervisedCommandFromSessionFile(parsed.options.sessionFile);
+    return;
+  }
 
   if (command === "analyze") {
     process.exitCode = await handleAnalyzeCommand(normalizeAnalyzeOptions(parsed.options, process.cwd()));