helloloop 0.8.5 → 0.8.6

package/.claude-plugin/plugin.json

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

package/README.md

@@ -99,8 +99,9 @@ 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
 - 当前对话 turn 就算被误按 `Esc`、被宿主暂停、或当前工具调用被中断，后台 supervisor 仍会继续
 - 原有的 15 分钟级恢复、健康探测、同引擎自动恢复，也会继续由这个后台 supervisor 接管
 - 这不是“当前进程死掉后每 15 分钟重新拉起一遍主进程”，而是 supervisor 本身持续存活，所以恢复链不会因为当前 turn 消失而断掉
@@ -109,7 +110,8 @@ npx helloloop gemini <PATH> 接续完成剩余开发
 常见场景：
 
 - 在 `Codex` / `Claude` / `Gemini` 宿主里运行 `helloloop`：确认后默认转入后台执行，可用 `helloloop status` 查看进度
-- 在普通终端里运行 `npx helloloop run-once --supervised` 或 `npx helloloop run-loop --supervised`：即使中途 `Ctrl+C` 当前命令，只要终端窗口没关，后台 supervisor 仍会继续
+- 在普通终端里运行 `npx helloloop`、`npx helloloop run-once`、`npx helloloop run-loop`：默认也会转入后台执行
+- `--supervised` 仍然保留，但现在只是兼容参数，不再是开启后台 supervisor 的前提
 
 ## 无人值守恢复
 
@@ -175,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`
@@ -414,7 +456,7 @@ npx helloloop
 | `-y` / `--yes` | 跳过执行确认直接开始；但如果未显式指定引擎，会直接报错而不是自动选引擎 |
 | `--repo <dir>` | 高级覆盖：显式指定项目仓库 |
 | `--docs <dir|file>` | 高级覆盖：显式指定开发文档 |
-| `--supervised` | 在普通终端里显式启用 detached supervisor；当前命令被打断时，后台执行仍可继续 |
+| `--supervised` | 兼容保留；当前版本默认已启用 detached supervisor |
 | `--rebuild-existing` | 项目与文档冲突时，自动清理现有项目后重建 |
 | `--host <name>` | 安装宿主：`codex` / `claude` / `gemini` / `all` |
 | `--config-dir <dir>` | 状态目录名，默认 `.helloloop` |
@@ -485,7 +527,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.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.5",
+  "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.5",
+  "version": "0.8.6",
   "description": "HelloLoop 的 Gemini CLI 原生扩展，用于按开发文档接续推进项目开发。",
   "contextFileName": "GEMINI.md",
   "excludeTools": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.8.5",
+  "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 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/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/cli.mjs

@@ -14,49 +14,65 @@ import {
 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),
+    };
+    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,17 +11,16 @@ 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";
 
 async function resolveAnalyzeEngineSelection(options) {
@@ -206,11 +204,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);
 
@@ -239,19 +232,8 @@ async function maybeRunAutoExecution(result, activeOptions) {
     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;
+  console.log("- 已切换为后台执行；可稍后运行 `helloloop status` 查看进度。");
+  return 0;
 }
 
 export async function handleAnalyzeCommand(options) {

package/src/cli_args.mjs

@@ -90,7 +90,7 @@ function helpText() {
     "  --max-tasks <n>       run-loop 最多执行 n 个任务",
     "  --max-attempts <n>    每种策略内最多重试 n 次",
     "  --max-strategies <n>  单任务最多切换 n 种策略继续重试",
-    "  --supervised          通过独立 supervisor 执行；当前 turn 被中断时任务仍可继续",
+    "  --supervised          兼容保留；当前版本默认就会通过独立 supervisor 后台执行",
     "  --allow-high-risk     允许执行 medium/high/critical 风险任务",
     "  --rebuild-existing    分析判断当前项目与文档冲突时，自动清理当前项目后按文档重建",
     "  --required-doc <p>    增加一个全局必读文档（AGENTS.md 会被自动忽略）",
@@ -99,7 +99,7 @@ function helpText() {
     "补充说明：",
     "  analyze 默认支持在命令后混合传入引擎、路径和自然语言要求。",
     "  如果同时检测到多个可用引擎且没有明确指定，会先询问你选择。",
-    "  在 Codex / Claude / Gemini 宿主内，确认后的自动执行会默认切到后台 supervisor。",
+    "  当前版本默认会把自动执行 / run-once / run-loop 切到后台 supervisor。",
     "  示例：npx helloloop claude <DOCS_PATH> <PROJECT_ROOT> 先分析偏差，不要执行",
   ].join("\n");
 }

package/src/cli_command_handlers.mjs

@@ -2,7 +2,6 @@ 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";
@@ -10,32 +9,23 @@ 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";
+    && process.env.HELLOLOOP_SUPERVISOR_ACTIVE !== "1";
 }
 
 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);
+  console.log("- 已切换为后台执行；可稍后运行 `helloloop status` 查看进度。");
+  return {
+    detached: true,
+    exitCode: 0,
+    ok: true,
+    session,
+  };
 }
 
 export function handleInstallCommand(options) {
@@ -120,24 +110,7 @@ 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;
+    return payload.exitCode || 0;
   }
 
   const result = await runOnce(context, options);
@@ -161,27 +134,7 @@ 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;
+    return payload.exitCode || 0;
   }
 
   const results = await runLoop(context, options);

package/src/engine_selection_settings.mjs

@@ -24,6 +24,15 @@ function defaultEmailNotificationSettings() {
   };
 }
 
+function defaultTerminalConcurrencySettings() {
+  return {
+    enabled: true,
+    visibleMax: 8,
+    backgroundMax: 8,
+    totalMax: 8,
+  };
+}
+
 function defaultUserSettings() {
   return {
     defaultEngine: "",
@@ -31,6 +40,9 @@ function defaultUserSettings() {
     notifications: {
       email: defaultEmailNotificationSettings(),
     },
+    runtime: {
+      terminalConcurrency: defaultTerminalConcurrencySettings(),
+    },
   };
 }
 

package/src/supervisor_runtime.mjs

@@ -6,6 +6,12 @@ import { createContext } from "./context.mjs";
 import { nowIso, readJson, writeJson, readTextIfExists, timestampForFile } from "./common.mjs";
 import { isHostLeaseAlive, renderHostLeaseLabel, resolveHostLease } from "./host_lease.mjs";
 import { runLoop, runOnce } from "./runner.mjs";
+import {
+  bindBackgroundTerminalSession,
+  cancelPreparedTerminalSessionBackground,
+  finalizePreparedTerminalSessionBackground,
+  prepareCurrentTerminalSessionForBackground,
+} from "./terminal_session_limits.mjs";
 
 const ACTIVE_STATUSES = new Set(["launching", "running"]);
 const FINAL_STATUSES = new Set(["completed", "failed", "stopped"]);
@@ -78,6 +84,11 @@ export function launchSupervisedCommand(context, command, options = {}) {
 
   const sessionId = timestampForFile();
   const lease = resolveHostLease({ hostContext: options.hostContext });
+  const terminalSession = prepareCurrentTerminalSessionForBackground({
+    command,
+    repoRoot: context.repoRoot,
+    sessionId,
+  });
   const request = {
     sessionId,
     command,
@@ -87,6 +98,7 @@ export function launchSupervisedCommand(context, command, options = {}) {
     },
     options: toSerializableOptions(options),
     lease,
+    terminalSessionFile: terminalSession?.file || "",
   };
 
   fs.mkdirSync(context.supervisorRoot, { recursive: true });
@@ -122,6 +134,11 @@ export function launchSupervisedCommand(context, command, options = {}) {
         HELLOLOOP_SUPERVISOR_ACTIVE: "1",
       },
     });
+    finalizePreparedTerminalSessionBackground(child.pid ?? 0, {
+      command,
+      repoRoot: context.repoRoot,
+      sessionId,
+    });
     child.unref();
     writeState(context, {
       sessionId,
@@ -137,6 +154,13 @@ export function launchSupervisedCommand(context, command, options = {}) {
       pid: child.pid ?? 0,
       lease,
     };
+  } catch (error) {
+    cancelPreparedTerminalSessionBackground({
+      command,
+      repoRoot: context.repoRoot,
+      sessionId,
+    });
+    throw error;
   } finally {
     fs.closeSync(stdoutFd);
     fs.closeSync(stderrFd);
@@ -184,6 +208,11 @@ export async function runSupervisedCommandFromSessionFile(sessionFile) {
   const context = createContext(request.context || {});
   const command = String(request.command || "").trim();
   const lease = request.lease || {};
+  bindBackgroundTerminalSession(request.terminalSessionFile || "", {
+    command,
+    repoRoot: context.repoRoot,
+    sessionId: request.sessionId,
+  });
   const commandOptions = {
     ...(request.options || {}),
     hostLease: lease,

package/src/terminal_session_limits.mjs

@@ -0,0 +1,394 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { ensureDir, fileExists, nowIso, readJson, timestampForFile, writeJson } from "./common.mjs";
+import { loadGlobalConfig } from "./global_config.mjs";
+
+const SESSION_DIR_NAME = "terminal-sessions";
+const RUNTIME_DIR_NAME = "runtime";
+const LOCK_FILE_NAME = ".lock";
+const LOCK_RETRY_DELAYS_MS = [0, 20, 50, 100, 200, 300, 500];
+const STALE_PREPARED_SESSION_MS = 60_000;
+const TRACKED_VISIBLE_COMMANDS = new Set(["analyze", "next", "run-loop", "run-once"]);
+
+let currentTerminalSession = null;
+let cleanupRegistered = false;
+
+function sleepSync(ms) {
+  const shared = new SharedArrayBuffer(4);
+  const view = new Int32Array(shared);
+  Atomics.wait(view, 0, 0, Math.max(0, ms));
+}
+
+function isPidAlive(pid) {
+  const value = Number(pid || 0);
+  if (!Number.isFinite(value) || value <= 0) {
+    return false;
+  }
+  try {
+    process.kill(value, 0);
+    return true;
+  } catch (error) {
+    return String(error?.code || "") === "EPERM";
+  }
+}
+
+function normalizeNonNegativeInteger(value, fallbackValue) {
+  if (value === null || value === undefined || value === "") {
+    return fallbackValue;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallbackValue;
+  }
+  return Math.floor(parsed);
+}
+
+export function normalizeTerminalConcurrencySettings(settings = {}) {
+  const source = settings && typeof settings === "object" ? settings : {};
+  return {
+    enabled: source.enabled !== false,
+    visibleMax: normalizeNonNegativeInteger(source.visibleMax, 8),
+    backgroundMax: normalizeNonNegativeInteger(source.backgroundMax, 8),
+    totalMax: normalizeNonNegativeInteger(source.totalMax, 8),
+  };
+}
+
+function resolveTerminalRuntimeConfig(options = {}) {
+  const globalConfig = loadGlobalConfig({
+    globalConfigFile: options.globalConfigFile,
+  });
+  const settingsFile = globalConfig?._meta?.configFile || "";
+  const settingsHome = settingsFile ? path.dirname(settingsFile) : process.cwd();
+  return {
+    settingsFile,
+    registryRoot: path.join(settingsHome, RUNTIME_DIR_NAME, SESSION_DIR_NAME),
+    limits: normalizeTerminalConcurrencySettings(globalConfig?.runtime?.terminalConcurrency || {}),
+  };
+}
+
+function withRegistryLock(registryRoot, callback) {
+  ensureDir(registryRoot);
+  const lockFile = path.join(registryRoot, LOCK_FILE_NAME);
+  let lastError = null;
+
+  for (const delayMs of LOCK_RETRY_DELAYS_MS) {
+    if (delayMs > 0) {
+      sleepSync(delayMs);
+    }
+    let lockFd = null;
+    try {
+      lockFd = fs.openSync(lockFile, "wx");
+      const result = callback();
+      fs.closeSync(lockFd);
+      fs.rmSync(lockFile, { force: true });
+      return result;
+    } catch (error) {
+      lastError = error;
+      if (lockFd !== null) {
+        try {
+          fs.closeSync(lockFd);
+        } catch {
+          // ignore lock close failure
+        }
+        fs.rmSync(lockFile, { force: true });
+        throw error;
+      }
+      if (String(error?.code || "").toUpperCase() !== "EEXIST") {
+        throw error;
+      }
+    }
+  }
+
+  throw lastError || new Error(`无法获取 HelloLoop 终端会话锁：${registryRoot}`);
+}
+
+function listSessionFiles(registryRoot) {
+  if (!fileExists(registryRoot)) {
+    return [];
+  }
+  return fs.readdirSync(registryRoot)
+    .filter((item) => item.endsWith(".json"))
+    .map((item) => path.join(registryRoot, item));
+}
+
+function readSessionRecord(sessionFile) {
+  try {
+    return readJson(sessionFile);
+  } catch {
+    return null;
+  }
+}
+
+function isPreparedSessionExpired(record) {
+  const updatedAt = Date.parse(String(record?.updatedAt || record?.createdAt || ""));
+  if (!Number.isFinite(updatedAt)) {
+    return true;
+  }
+  return Date.now() - updatedAt > STALE_PREPARED_SESSION_MS;
+}
+
+function isStaleSession(record) {
+  const kind = String(record?.kind || "");
+  if (!["visible", "background"].includes(kind)) {
+    return true;
+  }
+  if (Number(record?.pid || 0) > 0) {
+    return !isPidAlive(record.pid);
+  }
+  if (Number(record?.ownerPid || 0) > 0 && !isPidAlive(record.ownerPid)) {
+    return true;
+  }
+  return isPreparedSessionExpired(record);
+}
+
+function cleanupStaleSessions(registryRoot) {
+  const activeSessions = [];
+  for (const sessionFile of listSessionFiles(registryRoot)) {
+    const record = readSessionRecord(sessionFile);
+    if (!record || isStaleSession(record)) {
+      fs.rmSync(sessionFile, { force: true });
+      continue;
+    }
+    activeSessions.push({
+      ...record,
+      file: sessionFile,
+    });
+  }
+  return activeSessions;
+}
+
+function countSessions(sessions, excludingId = "") {
+  return sessions
+    .filter((session) => session.id !== excludingId)
+    .reduce((counts, session) => {
+      if (session.kind === "visible") {
+        counts.visible += 1;
+      }
+      if (session.kind === "background") {
+        counts.background += 1;
+      }
+      counts.total += 1;
+      return counts;
+    }, { visible: 0, background: 0, total: 0 });
+}
+
+function throwSessionLimitError(kind, counts, limits, settingsFile, reason) {
+  const kindLabel = kind === "background" ? "背景终端" : "显示终端";
+  const scope = [
+    `显示终端 ${counts.visible}/${limits.visibleMax}`,
+    `背景终端 ${counts.background}/${limits.backgroundMax}`,
+    `总并发 ${counts.total}/${limits.totalMax}`,
+  ].join("，");
+  throw new Error(
+    `${kindLabel}${reason}，当前 ${scope}。`
+    + ` 如需调整，请修改 ${settingsFile} 中的 runtime.terminalConcurrency.visibleMax / backgroundMax / totalMax。`,
+  );
+}
+
+function assertSessionLimit(kind, sessions, limits, settingsFile, excludingId = "") {
+  if (!limits.enabled) {
+    return;
+  }
+
+  const counts = countSessions(sessions, excludingId);
+  const nextCounts = {
+    visible: counts.visible + (kind === "visible" ? 1 : 0),
+    background: counts.background + (kind === "background" ? 1 : 0),
+    total: counts.total + 1,
+  };
+
+  if (kind === "visible" && nextCounts.visible > limits.visibleMax) {
+    throwSessionLimitError(kind, nextCounts, limits, settingsFile, "并发已达上限");
+  }
+  if (kind === "background" && nextCounts.background > limits.backgroundMax) {
+    throwSessionLimitError(kind, nextCounts, limits, settingsFile, "并发已达上限");
+  }
+  if (nextCounts.total > limits.totalMax) {
+    throwSessionLimitError(kind, nextCounts, limits, settingsFile, "启动被阻止：显示终端与背景终端合计并发已达上限");
+  }
+}
+
+function buildSessionRecord(kind, options = {}) {
+  return {
+    id: options.id || `${timestampForFile()}-${kind}-${process.pid}`,
+    kind,
+    pid: Number(options.pid || process.pid),
+    ownerPid: Number(options.ownerPid || process.pid),
+    command: String(options.command || "").trim(),
+    sessionId: String(options.sessionId || "").trim(),
+    repoRoot: String(options.repoRoot || "").trim(),
+    createdAt: options.createdAt || nowIso(),
+    updatedAt: nowIso(),
+  };
+}
+
+function writeSessionRecord(sessionFile, record) {
+  writeJson(sessionFile, record);
+  return {
+    ...record,
+    file: sessionFile,
+  };
+}
+
+function ensureCleanupRegistration() {
+  if (cleanupRegistered) {
+    return;
+  }
+  cleanupRegistered = true;
+  process.on("exit", () => {
+    try {
+      releaseCurrentTerminalSession();
+    } catch {
+      // ignore exit cleanup failure
+    }
+  });
+}
+
+function setCurrentTerminalSession(record) {
+  if (!record) {
+    return null;
+  }
+  currentTerminalSession = {
+    ...record,
+    preparedForBackground: false,
+    handedOff: false,
+  };
+  ensureCleanupRegistration();
+  return currentTerminalSession;
+}
+
+export function shouldTrackVisibleTerminalCommand(command) {
+  return TRACKED_VISIBLE_COMMANDS.has(String(command || "").trim());
+}
+
+export function acquireVisibleTerminalSession(options = {}) {
+  if (currentTerminalSession) {
+    return currentTerminalSession;
+  }
+
+  const runtime = resolveTerminalRuntimeConfig(options);
+  if (!runtime.limits.enabled) {
+    return null;
+  }
+
+  return withRegistryLock(runtime.registryRoot, () => {
+    const sessions = cleanupStaleSessions(runtime.registryRoot);
+    assertSessionLimit("visible", sessions, runtime.limits, runtime.settingsFile);
+    const record = buildSessionRecord("visible", options);
+    const sessionFile = path.join(runtime.registryRoot, `${record.id}.json`);
+    return setCurrentTerminalSession(writeSessionRecord(sessionFile, record));
+  });
+}
+
+export function prepareCurrentTerminalSessionForBackground(options = {}) {
+  const runtime = resolveTerminalRuntimeConfig(options);
+  if (!runtime.limits.enabled) {
+    return null;
+  }
+
+  return withRegistryLock(runtime.registryRoot, () => {
+    const sessions = cleanupStaleSessions(runtime.registryRoot);
+
+    if (!currentTerminalSession) {
+      assertSessionLimit("background", sessions, runtime.limits, runtime.settingsFile);
+      const record = buildSessionRecord("background", {
+        ...options,
+        pid: 0,
+      });
+      const sessionFile = path.join(runtime.registryRoot, `${record.id}.json`);
+      const next = writeSessionRecord(sessionFile, record);
+      currentTerminalSession = {
+        ...next,
+        preparedForBackground: true,
+        handedOff: false,
+      };
+      ensureCleanupRegistration();
+      return currentTerminalSession;
+    }
+
+    assertSessionLimit("background", sessions, runtime.limits, runtime.settingsFile, currentTerminalSession.id);
+    const record = buildSessionRecord("background", {
+      ...currentTerminalSession,
+      ...options,
+      pid: 0,
+      ownerPid: process.pid,
+    });
+    const next = writeSessionRecord(currentTerminalSession.file, record);
+    currentTerminalSession = {
+      ...next,
+      preparedForBackground: true,
+      handedOff: false,
+    };
+    return currentTerminalSession;
+  });
+}
+
+export function finalizePreparedTerminalSessionBackground(pid, options = {}) {
+  if (!currentTerminalSession?.file) {
+    return null;
+  }
+
+  const runtime = resolveTerminalRuntimeConfig(options);
+  return withRegistryLock(runtime.registryRoot, () => {
+    const record = buildSessionRecord("background", {
+      ...currentTerminalSession,
+      ...options,
+      pid,
+      ownerPid: pid,
+      createdAt: currentTerminalSession.createdAt,
+    });
+    const next = writeSessionRecord(currentTerminalSession.file, record);
+    currentTerminalSession = {
+      ...next,
+      preparedForBackground: false,
+      handedOff: true,
+    };
+    return currentTerminalSession;
+  });
+}
+
+export function cancelPreparedTerminalSessionBackground(options = {}) {
+  if (!currentTerminalSession?.file || !currentTerminalSession.preparedForBackground) {
+    return false;
+  }
+
+  const runtime = resolveTerminalRuntimeConfig(options);
+  return withRegistryLock(runtime.registryRoot, () => {
+    fs.rmSync(currentTerminalSession.file, { force: true });
+    currentTerminalSession = null;
+    return true;
+  });
+}
+
+export function bindBackgroundTerminalSession(sessionFile, options = {}) {
+  if (!sessionFile) {
+    return null;
+  }
+
+  const registryRoot = path.dirname(sessionFile);
+  return withRegistryLock(registryRoot, () => {
+    const existing = fileExists(sessionFile) ? readSessionRecord(sessionFile) : null;
+    const record = buildSessionRecord("background", {
+      ...existing,
+      ...options,
+      pid: process.pid,
+      ownerPid: process.pid,
+    });
+    return setCurrentTerminalSession(writeSessionRecord(sessionFile, record));
+  });
+}
+
+export function releaseCurrentTerminalSession() {
+  if (!currentTerminalSession?.file || currentTerminalSession.handedOff) {
+    return false;
+  }
+
+  const sessionFile = currentTerminalSession.file;
+  const registryRoot = path.dirname(sessionFile);
+  withRegistryLock(registryRoot, () => {
+    fs.rmSync(sessionFile, { force: true });
+  });
+  currentTerminalSession = null;
+  return true;
+}