helloloop 0.8.5 → 0.9.1

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -99,8 +99,10 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 
 ## 后台监督执行
 
-从 `Codex CLI`、`Claude Code`、`Gemini CLI` 这些宿主里发起 `HelloLoop` 时，确认自动执行后会默认切到 **detached supervisor + host lease** 模式：
+从当前版本开始，`HelloLoop` 的自动执行主线统一走 **detached supervisor + host lease** 模式：
 
+- `analyze` 确认后的自动执行、`run-once`、`run-loop` 都默认切到后台 supervisor
+- 交互终端里默认会**自动附着观察**这个后台 supervisor：你仍然能在当前 CLI 里看到实时进度与流式输出
 - 当前对话 turn 就算被误按 `Esc`、被宿主暂停、或当前工具调用被中断，后台 supervisor 仍会继续
 - 原有的 15 分钟级恢复、健康探测、同引擎自动恢复，也会继续由这个后台 supervisor 接管
 - 这不是“当前进程死掉后每 15 分钟重新拉起一遍主进程”，而是 supervisor 本身持续存活，所以恢复链不会因为当前 turn 消失而断掉
@@ -108,8 +110,11 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 
 常见场景：
 
-- 在 `Codex` / `Claude` / `Gemini` 宿主里运行 `helloloop`：确认后默认转入后台执行，可用 `helloloop status` 查看进度
-- 在普通终端里运行 `npx helloloop run-once --supervised` 或 `npx helloloop run-loop --supervised`：即使中途 `Ctrl+C` 当前命令，只要终端窗口没关，后台 supervisor 仍会继续
+- 在 `Codex` / `Claude` / `Gemini` 宿主里运行 `helloloop`：确认后默认后台执行，并尽量保持当前 CLI 可观察
+- 在普通终端里运行 `npx helloloop`、`npx helloloop run-once`、`npx helloloop run-loop`：默认也是“后台执行 + 当前终端附着观察”
+- 如果你就是想让命令立刻返回、不占当前终端：显式加 `--detach`
+- 如果你稍后想重新接上实时观察：运行 `helloloop watch` 或 `helloloop status --watch`
+- 因此当前版本**不需要先上 Web 看板** 才能解决“后台执行看不到过程”的问题；CLI 观察链已经是第一优先级
 
 ## 无人值守恢复
 
@@ -175,6 +180,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`
@@ -332,7 +377,7 @@ npx helloloop install --host all --force
 - `Codex` 会刷新 home 根下的插件源码目录、已安装缓存、`config.toml` 启用项和 marketplace 条目
 - `Claude` 会刷新 marketplace、缓存插件目录，以及 `settings.json` / `known_marketplaces.json` / `installed_plugins.json` 中的 `helloloop` 条目
 - `Gemini` 会刷新 `extensions/helloloop/`，不会动同目录下其他扩展
-- 安装 / 升级 / 重装时，会同步校准 `~/.helloloop/settings.json` 的当前版本结构：补齐缺失项、清理未知项、保留已知项现有值
+- 安装 / 升级 / 重装时，会把 `~/.helloloop/settings.json` 严格收敛到当前版本 schema：补齐缺失项、清理未知项、把非法值重置为当前版本默认值
 - 如果 `~/.helloloop/settings.json` 被确认不是合法 JSON，会先备份原文件，再按当前版本结构重建
 - 如果只是首次读取时出现瞬时异常，但重读后内容合法，则不会误生成备份文件
 - 如果宿主自己的配置 JSON（如 `Codex marketplace.json`、`Claude settings.json`、`known_marketplaces.json`、`installed_plugins.json`）本身已损坏，`HelloLoop` 会先明确报错并停止，不会先清理现有安装再失败
@@ -401,6 +446,7 @@ npx helloloop
 | `doctor` | 检查宿主环境、插件资产与目标仓库状态 |
 | `init` | 手动初始化 `.helloloop/` 模板 |
 | `status` | 查看 backlog 摘要和当前状态 |
+| `watch` | 重新附着后台 supervisor，持续查看实时进度 |
 | `next` | 生成下一任务的干跑预览 |
 | `run-once` | 执行一个任务 |
 | `run-loop` | 连续执行多个任务 |
@@ -414,7 +460,8 @@ npx helloloop
 | `-y` / `--yes` | 跳过执行确认直接开始；但如果未显式指定引擎，会直接报错而不是自动选引擎 |
 | `--repo <dir>` | 高级覆盖：显式指定项目仓库 |
 | `--docs <dir|file>` | 高级覆盖：显式指定开发文档 |
-| `--supervised` | 在普通终端里显式启用 detached supervisor；当前命令被打断时，后台执行仍可继续 |
+| `--watch` | 启动后台 supervisor 后，当前终端继续附着观察实时输出 |
+| `--detach` | 仅启动后台 supervisor，立即返回，不进入观察模式 |
 | `--rebuild-existing` | 项目与文档冲突时，自动清理现有项目后重建 |
 | `--host <name>` | 安装宿主：`codex` / `claude` / `gemini` / `all` |
 | `--config-dir <dir>` | 状态目录名，默认 `.helloloop` |
@@ -423,8 +470,11 @@ npx helloloop
 
 ```bash
 npx helloloop status
+npx helloloop status --watch
+npx helloloop watch
 npx helloloop next
 npx helloloop run-once
+npx helloloop run-loop --detach
 ```
 
 ## Doctor
@@ -485,7 +535,7 @@ git push origin vX.Y.Z-beta.N
 
 - 正式版本使用 npm `latest` 渠道，beta 版本使用 npm `beta` 渠道
 - 如果测试、版本校验或打包检查失败，npm 发布与 GitHub Release 都不会继续执行
-- `0.8.5` 起已补齐 host-aware supervisor 后台执行链路：宿主内自动执行默认后台化，当前 turn 被 `Esc` / cancel 不再直接打断 HelloLoop 主线
+- `0.9.1` 起按破坏性升级思路继续收紧：后台 supervisor + CLI 附着观察成为默认工作流，同时 `settings.json` 与 Codex 安装布局只接受当前版本规范，不再为旧布局做兼容兜底
 - GitHub Release 阶段现已改为使用官方 `gh` CLI + `generate-notes` API 创建 / 更新 release，不再依赖会触发 Node runtime deprecation warning 的第三方 action
 
 ## 宿主写入范围
@@ -525,7 +575,7 @@ git push origin vX.Y.Z-beta.N
 说明：
 
 - 这里不保存项目 backlog、状态、运行记录
-- 安装 / 升级 / 重装时，会对 `settings.json` 做结构校准，但不会校验或篡改你已存在的已知项内容
+- 安装 / 升级 / 重装时，会对 `settings.json` 做严格 schema 校准；已知字段只要值不合法，也会按当前版本默认值重置
 - 只有在 `settings.json` 被确认非法时，才会先备份，再重建为当前版本结构
 - 如果只是读取瞬时异常、重读后合法，不会误生成 `.bak`
 

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

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

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

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

package/package.json

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

package/src/cli.mjs

@@ -10,53 +10,71 @@ import {
   handleRunOnceCommand,
   handleStatusCommand,
   handleUninstallCommand,
+  handleWatchCommand,
 } from "./cli_command_handlers.mjs";
 import { resolveContextFromOptions, resolveStandardCommandOptions } from "./cli_context.mjs";
 import { runDoctor } from "./cli_support.mjs";
 import { runSupervisedCommandFromSessionFile } from "./supervisor_runtime.mjs";
+import {
+  acquireVisibleTerminalSession,
+  releaseCurrentTerminalSession,
+  shouldTrackVisibleTerminalCommand,
+} from "./terminal_session_limits.mjs";
 
 export async function runCli(argv) {
-  const parsed = parseArgs(argv);
-  const command = parsed.command;
-  if (command === "help" || command === "--help" || command === "-h") {
-    printHelp();
-    return;
-  }
-  if (command === "__supervise") {
-    if (!parsed.options.sessionFile) {
-      throw new Error("缺少 --session-file，无法启动 HelloLoop supervisor。");
+  try {
+    const parsed = parseArgs(argv);
+    const command = parsed.command;
+    if (command === "help" || command === "--help" || command === "-h") {
+      printHelp();
+      return;
+    }
+    if (command === "__supervise") {
+      if (!parsed.options.sessionFile) {
+        throw new Error("缺少 --session-file，无法启动 HelloLoop supervisor。");
+      }
+      await runSupervisedCommandFromSessionFile(parsed.options.sessionFile);
+      return;
     }
-    await runSupervisedCommandFromSessionFile(parsed.options.sessionFile);
-    return;
-  }
 
-  if (command === "analyze") {
-    process.exitCode = await handleAnalyzeCommand(normalizeAnalyzeOptions(parsed.options, process.cwd()));
-    return;
-  }
+    if (process.env.HELLOLOOP_SUPERVISOR_ACTIVE !== "1" && shouldTrackVisibleTerminalCommand(command)) {
+      acquireVisibleTerminalSession({
+        command,
+        repoRoot: process.cwd(),
+      });
+    }
 
-  const options = resolveStandardCommandOptions(parsed.options);
-  if (command === "install") {
-    process.exitCode = handleInstallCommand(options);
-    return;
-  }
-  if (command === "uninstall") {
-    process.exitCode = handleUninstallCommand(options);
-    return;
-  }
+    if (command === "analyze") {
+      process.exitCode = await handleAnalyzeCommand(normalizeAnalyzeOptions(parsed.options, process.cwd()));
+      return;
+    }
 
-  const context = resolveContextFromOptions(options);
-  const handlers = {
-    doctor: () => handleDoctorCommand(context, options, runDoctor),
-    init: () => handleInitCommand(context),
-    next: () => handleNextCommand(context, options),
-    "run-loop": () => handleRunLoopCommand(context, options),
-    "run-once": () => handleRunOnceCommand(context, options),
-    status: () => handleStatusCommand(context, options),
-  };
-  if (!handlers[command]) {
-    throw new Error(`未知命令：${command}`);
-  }
+    const options = resolveStandardCommandOptions(parsed.options);
+    if (command === "install") {
+      process.exitCode = handleInstallCommand(options);
+      return;
+    }
+    if (command === "uninstall") {
+      process.exitCode = handleUninstallCommand(options);
+      return;
+    }
 
-  process.exitCode = await handlers[command]();
+    const context = resolveContextFromOptions(options);
+    const handlers = {
+      doctor: () => handleDoctorCommand(context, options, runDoctor),
+      init: () => handleInitCommand(context),
+      next: () => handleNextCommand(context, options),
+      "run-loop": () => handleRunLoopCommand(context, options),
+      "run-once": () => handleRunOnceCommand(context, options),
+      status: () => handleStatusCommand(context, options),
+      watch: () => handleWatchCommand(context, options),
+    };
+    if (!handlers[command]) {
+      throw new Error(`未知命令：${command}`);
+    }
+
+    process.exitCode = await handlers[command]();
+  } finally {
+    releaseCurrentTerminalSession();
+  }
 }

package/src/cli_analyze_command.mjs

@@ -4,7 +4,6 @@ import {
   confirmAutoExecution,
   confirmRepoConflictResolution,
   renderAnalyzeStopMessage,
-  renderAutoRunSummary,
   renderRepoConflictStopMessage,
 } from "./cli_support.mjs";
 import { analyzeWorkspace } from "./analyzer.mjs";
@@ -12,18 +11,14 @@ import {
   hasBlockingInputIssues,
   renderBlockingInputIssueMessage,
 } from "./analyze_user_input.mjs";
-import { loadBacklog, loadPolicy } from "./config.mjs";
+import { loadPolicy } from "./config.mjs";
 import { createContext } from "./context.mjs";
 import { createDiscoveryPromptSession, resolveDiscoveryFailureInteractively } from "./discovery_prompt.mjs";
-import { resolveEngineSelection, resolveHostContext } from "./engine_selection.mjs";
+import { resolveEngineSelection } from "./engine_selection.mjs";
 import { resetRepoForRebuild } from "./rebuild.mjs";
 import { renderRebuildSummary } from "./cli_render.mjs";
 import { shouldConfirmRepoRebuild } from "./cli_support.mjs";
-import {
-  launchSupervisedCommand,
-  renderSupervisorLaunchSummary,
-  waitForSupervisedResult,
-} from "./supervisor_runtime.mjs";
+import { launchAndMaybeWatchSupervisedCommand } from "./supervisor_cli_support.mjs";
 
 async function resolveAnalyzeEngineSelection(options) {
   if (options.engineResolution?.ok) {
@@ -206,11 +201,6 @@ async function prepareAnalyzeExecution(initialOptions) {
   }
 }
 
-function shouldDetachSupervisor(options = {}) {
-  return process.env.HELLOLOOP_SUPERVISOR_ACTIVE !== "1"
-    && resolveHostContext(options) !== "terminal";
-}
-
 async function maybeRunAutoExecution(result, activeOptions) {
   const execution = analyzeExecution(result.backlog, activeOptions);
 
@@ -231,27 +221,13 @@ async function maybeRunAutoExecution(result, activeOptions) {
 
   console.log("");
   console.log("开始自动接续执行...");
-  const session = launchSupervisedCommand(result.context, "run-loop", {
+  const payload = await launchAndMaybeWatchSupervisedCommand(result.context, "run-loop", {
     ...activeOptions,
-    supervised: false,
     engineResolution: result.engineResolution?.ok ? result.engineResolution : activeOptions.engineResolution,
     maxTasks: resolveAutoRunMaxTasks(result.backlog, activeOptions) || undefined,
     fullAutoMainline: true,
   });
-  console.log(renderSupervisorLaunchSummary(session));
-  if (shouldDetachSupervisor(activeOptions)) {
-    console.log("- 已切换为后台执行；可稍后运行 `helloloop status` 查看进度。");
-    return 0;
-  }
-  const supervisorPayload = await waitForSupervisedResult(result.context, session);
-  const results = supervisorPayload.results;
-  if (!results) {
-    console.error(supervisorPayload.error || "HelloLoop supervisor 执行失败。");
-    return supervisorPayload.exitCode || 1;
-  }
-  const refreshedBacklog = loadBacklog(result.context);
-  console.log(renderAutoRunSummary(result.context, refreshedBacklog, results, activeOptions));
-  return supervisorPayload.exitCode || 0;
+  return payload.exitCode || 0;
 }
 
 export async function handleAnalyzeCommand(options) {

package/src/cli_args.mjs

@@ -7,6 +7,7 @@ const KNOWN_COMMANDS = new Set([
   "uninstall",
   "init",
   "status",
+  "watch",
   "next",
   "run-once",
   "run-loop",
@@ -51,7 +52,10 @@ export function parseArgs(argv) {
     else if (arg === "--gemini-home") { options.geminiHome = rest[index + 1]; index += 1; }
     else if (arg === "--config-dir") { options.configDirName = rest[index + 1]; index += 1; }
     else if (arg === "--session-file") { options.sessionFile = rest[index + 1]; index += 1; }
-    else if (arg === "--supervised") options.supervised = true;
+    else if (arg === "--watch") options.watch = true;
+    else if (arg === "--detach") options.detach = true;
+    else if (arg === "--session-id") { options.sessionId = rest[index + 1]; index += 1; }
+    else if (arg === "--watch-poll-ms") { options.watchPollMs = Number(rest[index + 1]); index += 1; }
     else if (arg === "--required-doc") { options.requiredDocs.push(rest[index + 1]); index += 1; }
     else if (arg === "--constraint") { options.constraints.push(rest[index + 1]); index += 1; }
     else { options.positionalArgs.push(arg); }
@@ -70,6 +74,7 @@ function helpText() {
     "  uninstall             从所选宿主卸载插件并清理注册信息",
     "  init                  初始化 .helloloop 配置",
     "  status                查看 backlog 与下一任务",
+    "  watch                 附着到后台 supervisor，持续查看实时进度",
     "  next                  生成下一任务干跑预览",
     "  run-once              执行一个任务",
     "  run-loop              连续执行多个任务",
@@ -90,7 +95,9 @@ function helpText() {
     "  --max-tasks <n>       run-loop 最多执行 n 个任务",
     "  --max-attempts <n>    每种策略内最多重试 n 次",
     "  --max-strategies <n>  单任务最多切换 n 种策略继续重试",
-    "  --supervised          通过独立 supervisor 执行；当前 turn 被中断时任务仍可继续",
+    "  --watch               启动后台 supervisor 后，当前终端继续附着观察实时输出",
+    "  --detach              仅启动后台 supervisor 后立即返回，不进入观察模式",
+    "  --session-id <id>     status/watch 指定附着的后台会话 ID",
     "  --allow-high-risk     允许执行 medium/high/critical 风险任务",
     "  --rebuild-existing    分析判断当前项目与文档冲突时，自动清理当前项目后按文档重建",
     "  --required-doc <p>    增加一个全局必读文档（AGENTS.md 会被自动忽略）",
@@ -99,7 +106,9 @@ function helpText() {
     "补充说明：",
     "  analyze 默认支持在命令后混合传入引擎、路径和自然语言要求。",
     "  如果同时检测到多个可用引擎且没有明确指定，会先询问你选择。",
-    "  在 Codex / Claude / Gemini 宿主内，确认后的自动执行会默认切到后台 supervisor。",
+    "  当前版本默认会把自动执行 / run-once / run-loop 切到后台 supervisor。",
+    "  交互终端默认会自动附着观察；如只想立即返回，请显式加 --detach。",
+    "  任何时候都可运行 `helloloop watch` 或 `helloloop status --watch` 重新附着观察。",
     "  示例：npx helloloop claude <DOCS_PATH> <PROJECT_ROOT> 先分析偏差，不要执行",
   ].join("\n");
 }

package/src/cli_command_handlers.mjs

@@ -2,41 +2,15 @@ import path from "node:path";
 
 import { createContext } from "./context.mjs";
 import { loadBacklog, scaffoldIfMissing } from "./config.mjs";
-import { resolveHostContext } from "./engine_selection.mjs";
 import { syncUserSettingsFile } from "./engine_selection_settings.mjs";
 import { installPluginBundle, uninstallPluginBundle } from "./install.mjs";
 import { runLoop, runOnce, renderStatusText } from "./runner.mjs";
 import { renderInstallSummary, renderUninstallSummary } from "./cli_render.mjs";
 import {
-  launchSupervisedCommand,
-  renderSupervisorLaunchSummary,
-  waitForSupervisedResult,
-} from "./supervisor_runtime.mjs";
-
-function shouldUseSupervisor(options = {}) {
-  return !options.dryRun
-    && process.env.HELLOLOOP_SUPERVISOR_ACTIVE !== "1"
-    && (Boolean(options.supervised) || resolveHostContext(options) !== "terminal");
-}
-
-function shouldDetachSupervisor(options = {}) {
-  return resolveHostContext(options) !== "terminal";
-}
-
-async function runSupervised(context, command, options = {}) {
-  const session = launchSupervisedCommand(context, command, options);
-  console.log(renderSupervisorLaunchSummary(session));
-  if (shouldDetachSupervisor(options)) {
-    console.log("- 已切换为后台执行；可稍后运行 `helloloop status` 查看进度。");
-    return {
-      detached: true,
-      exitCode: 0,
-      ok: true,
-      session,
-    };
-  }
-  return waitForSupervisedResult(context, session);
-}
+  launchAndMaybeWatchSupervisedCommand,
+  shouldUseSupervisor,
+} from "./supervisor_cli_support.mjs";
+import { watchSupervisorSession } from "./supervisor_watch.mjs";
 
 export function handleInstallCommand(options) {
   const userSettings = syncUserSettingsFile({
@@ -89,9 +63,33 @@ export async function handleDoctorCommand(context, options, runDoctor) {
   return 0;
 }
 
-export function handleStatusCommand(context, options) {
+export async function handleStatusCommand(context, options) {
   console.log(renderStatusText(context, options));
-  return 0;
+  if (!options.watch) {
+    return 0;
+  }
+
+  const result = await watchSupervisorSession(context, {
+    sessionId: options.sessionId,
+    pollMs: options.watchPollMs,
+  });
+  if (result.empty) {
+    console.log("当前没有正在运行的后台 supervisor。");
+    return 1;
+  }
+  return result.exitCode || 0;
+}
+
+export async function handleWatchCommand(context, options) {
+  const result = await watchSupervisorSession(context, {
+    sessionId: options.sessionId,
+    pollMs: options.watchPollMs,
+  });
+  if (result.empty) {
+    console.log("当前没有正在运行的后台 supervisor。");
+    return 1;
+  }
+  return result.exitCode || 0;
 }
 
 export async function handleNextCommand(context, options) {
@@ -119,25 +117,8 @@ export async function handleNextCommand(context, options) {
 
 export async function handleRunOnceCommand(context, options) {
   if (shouldUseSupervisor(options)) {
-    const payload = await runSupervised(context, "run-once", options);
-    if (payload.detached) {
-      return payload.exitCode || 0;
-    }
-    if (!payload.result) {
-      console.error(payload.error || "HelloLoop supervisor 执行失败。");
-      return payload.exitCode || 1;
-    }
-
-    const result = payload.result;
-    if (!result.ok) {
-      console.error(result.summary || "执行失败。");
-      return payload.exitCode || 1;
-    }
-
-    console.log(result.task
-      ? `完成任务：${result.task.title}\n运行目录：${result.runDir}`
-      : "没有可执行任务。");
-    return 0;
+    const payload = await launchAndMaybeWatchSupervisedCommand(context, "run-once", options);
+    return payload.exitCode || 0;
   }
 
   const result = await runOnce(context, options);
@@ -160,28 +141,8 @@ export async function handleRunOnceCommand(context, options) {
 
 export async function handleRunLoopCommand(context, options) {
   if (shouldUseSupervisor(options)) {
-    const payload = await runSupervised(context, "run-loop", options);
-    if (payload.detached) {
-      return payload.exitCode || 0;
-    }
-    if (!payload.results) {
-      console.error(payload.error || "HelloLoop supervisor 执行失败。");
-      return payload.exitCode || 1;
-    }
-
-    const failed = payload.results.find((item) => !item.ok);
-    for (const item of payload.results) {
-      if (!item.task) {
-        console.log("没有更多可执行任务。");
-        break;
-      }
-      console.log(`${item.ok ? "成功" : "失败"}：${item.task.title}`);
-    }
-    if (failed) {
-      console.error(failed.summary || "连续执行中断。");
-      return payload.exitCode || 1;
-    }
-    return 0;
+    const payload = await launchAndMaybeWatchSupervisedCommand(context, "run-loop", options);
+    return payload.exitCode || 0;
   }
 
   const results = await runLoop(context, options);

package/src/common.mjs

@@ -26,6 +26,11 @@ export function writeText(filePath, content) {
   fs.writeFileSync(filePath, content, "utf8");
 }
 
+export function appendText(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.appendFileSync(filePath, content, "utf8");
+}
+
 export function writeJson(filePath, value) {
   writeText(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
@@ -64,3 +69,9 @@ export function resolveFrom(rootDir, ...segments) {
 export function normalizeRelative(rootDir, targetPath) {
   return path.relative(rootDir, targetPath).replaceAll("\\", "/");
 }
+
+export function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, Math.max(0, Number(ms || 0)));
+  });
+}

package/src/engine_process_support.mjs

@@ -121,17 +121,21 @@ export function runChild(command, args, options = {}) {
     emitHeartbeat("running");
 
     child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
+      const text = chunk.toString();
+      stdout += text;
       stdoutBytes += chunk.length;
       lastOutputAt = Date.now();
       stallWarned = false;
+      options.onStdout?.(text);
       emitHeartbeat("running");
     });
     child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
+      const text = chunk.toString();
+      stderr += text;
       stderrBytes += chunk.length;
       lastOutputAt = Date.now();
       stallWarned = false;
+      options.onStderr?.(text);
       emitHeartbeat("running");
     });