helloloop 0.8.6 → 0.10.0

package/src/runner_status.mjs

@@ -1,5 +1,10 @@
 import path from "node:path";
 
+import {
+  readJsonIfExists,
+  selectLatestActivityFile,
+  selectLatestRuntimeFile,
+} from "./activity_projection.mjs";
 import { fileExists, readJson, sanitizeId, tailText, timestampForFile } from "./common.mjs";
 import { renderTaskSummary, selectNextTask, summarizeBacklog } from "./backlog.mjs";
 import { loadBacklog } from "./config.mjs";
@@ -83,13 +88,42 @@ export function renderStatusMarkdown(context, { summary, currentTask, lastResult
   ].join("\n");
 }
 
-export function renderStatusText(context, options = {}) {
+export function collectRepoStatusSnapshot(context, options = {}) {
   const backlog = loadBacklog(context);
   const summary = summarizeBacklog(backlog);
   const nextTask = selectNextTask(backlog, options);
-  const supervisor = fileExists(context.supervisorStateFile)
-    ? readJson(context.supervisorStateFile)
-    : null;
+  const supervisor = fileExists(context.supervisorStateFile) ? readJson(context.supervisorStateFile) : null;
+  const latestStatus = fileExists(context.statusFile) ? readJson(context.statusFile) : null;
+  const runtimeFile = latestStatus?.runDir ? selectLatestRuntimeFile(latestStatus.runDir) : "";
+  const runtime = readJsonIfExists(runtimeFile);
+  const activityFile = runtime?.activityFile && fileExists(runtime.activityFile)
+    ? runtime.activityFile
+    : (latestStatus?.runDir ? selectLatestActivityFile(latestStatus.runDir, runtime?.attemptPrefix || "") : "");
+  const activity = readJsonIfExists(activityFile);
+
+  return {
+    summary,
+    nextTask,
+    supervisor,
+    latestStatus,
+    runtimeFile,
+    runtime,
+    activityFile,
+    activity,
+  };
+}
+
+export function renderStatusText(context, options = {}) {
+  const snapshot = collectRepoStatusSnapshot(context, options);
+  const {
+    summary,
+    nextTask,
+    supervisor,
+    latestStatus,
+    runtime,
+    activity,
+  } = snapshot;
+  const hostResume = options.hostResume || null;
 
   return [
     "HelloLoop 状态",
@@ -106,10 +140,44 @@ export function renderStatusText(context, options = {}) {
         `后台会话：${supervisor.status}`,
         `后台会话 ID：${supervisor.sessionId || "unknown"}`,
         `后台租约：${renderHostLeaseLabel(supervisor.lease)}`,
+        ...(Number.isFinite(Number(supervisor.guardianRestartCount)) && Number(supervisor.guardianRestartCount) > 0
+          ? [`守护重拉起次数：${supervisor.guardianRestartCount}`]
+          : []),
+      ]
+      : []),
+    ...(latestStatus?.taskTitle
+      ? [
+        `当前运行任务：${latestStatus.taskTitle}`,
+        `当前运行目录：${latestStatus.runDir || "unknown"}`,
+        `当前运行阶段：${latestStatus.stage || "unknown"}`,
       ]
       : []),
+    ...(runtime?.status
+      ? [
+        `当前引擎状态：${runtime.status}`,
+        ...(Number.isFinite(Number(runtime.recoveryCount))
+          ? [`自动恢复次数：${runtime.recoveryCount}`]
+          : []),
+      ]
+      : []),
+    ...(activity?.current?.label
+      ? [`当前动作：${activity.current.label}`]
+      : []),
+    ...(activity?.todo?.total
+      ? [`当前待办：${activity.todo.completed}/${activity.todo.total}`]
+      : []),
+    ...(Array.isArray(activity?.activeCommands) && activity.activeCommands[0]?.label
+      ? [`活动命令：${activity.activeCommands[0].label}`]
+      : []),
+    ...(hostResume?.issue?.label
+      ? [`宿主续跑：${hostResume.issue.label}`]
+      : (hostResume?.supervisorActive ? ["宿主续跑：后台仍在运行，可直接接续观察"] : [])),
     "",
     nextTask ? "下一任务：" : "下一任务：无",
     nextTask ? renderTaskSummary(nextTask) : "",
+    "",
+    "聚合看板：helloloop dashboard",
+    "续跑提示：helloloop resume-host",
+    "实时观察：helloloop watch",
   ].filter(Boolean).join("\n");
 }

package/src/runtime_engine_support.mjs

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { nowIso, writeText } from "./common.mjs";
+import { createActivityProjector } from "./activity_projection.mjs";
+import { appendText, nowIso, writeText } from "./common.mjs";
 import { getEngineDisplayName } from "./engine_metadata.mjs";
 import {
   buildClaudeArgs,
@@ -53,14 +54,16 @@ export function buildHostLeaseStoppedResult(reason) {
   };
 }
 
-export function createRuntimeStatusWriter(runtimeStatusFile, baseState) {
+export function createRuntimeStatusWriter(runtimeStatusFile, baseState, onUpdate) {
   return function writeRuntimeStatus(status, extra = {}) {
-    writeJson(runtimeStatusFile, {
+    const payload = {
       ...baseState,
       ...extra,
       status,
       updatedAt: nowIso(),
-    });
+    };
+    writeJson(runtimeStatusFile, payload);
+    onUpdate?.(payload);
   };
 }
 
@@ -165,6 +168,16 @@ export async function runEngineAttempt({
 }) {
   const attemptPromptFile = path.join(runDir, `${attemptPrefix}-prompt.md`);
   const attemptLastMessageFile = path.join(runDir, `${attemptPrefix}-last-message.txt`);
+  const attemptStdoutFile = path.join(runDir, `${attemptPrefix}-stdout.log`);
+  const attemptStderrFile = path.join(runDir, `${attemptPrefix}-stderr.log`);
+  const activityProjector = createActivityProjector({
+    engine,
+    phase: executionMode,
+    repoRoot: context.repoRoot,
+    runDir,
+    outputPrefix: attemptPrefix,
+    attemptPrefix,
+  });
 
   if (invocation.error) {
     const result = {
@@ -181,6 +194,17 @@ export async function runEngineAttempt({
     };
     writeText(attemptPromptFile, prompt);
     writeEngineRunArtifacts(runDir, attemptPrefix, result, "");
+    activityProjector.onRuntimeStatus({
+      status: "failed",
+      attemptPrefix,
+      activityFile: activityProjector.activityFile,
+      activityEventsFile: activityProjector.activityEventsFile,
+    });
+    activityProjector.finalize({
+      status: "failed",
+      result,
+      finalMessage: "",
+    });
     return {
       result,
       finalMessage: "",
@@ -208,11 +232,16 @@ export async function runEngineAttempt({
     recoveryCount,
     recoveryHistory,
   });
+  writeText(attemptStdoutFile, "");
+  writeText(attemptStderrFile, "");
 
   const result = await runChild(invocation.command, finalArgs, {
     cwd: context.repoRoot,
     stdin: prompt,
-    env,
+    env: {
+      ...(invocation.env || {}),
+      ...(env || {}),
+    },
     shell: invocation.shell,
     heartbeatIntervalMs: recoveryPolicy.heartbeatIntervalSeconds * 1000,
     stallWarningMs: recoveryPolicy.stallWarningSeconds * 1000,
@@ -224,8 +253,22 @@ export async function runEngineAttempt({
         recoveryCount,
         recoveryHistory,
         heartbeat: payload,
+        activityFile: activityProjector.activityFile,
+        activityEventsFile: activityProjector.activityEventsFile,
+      });
+      activityProjector.onRuntimeStatus({
+        ...payload,
+        attemptPrefix,
+        recoveryCount,
       });
     },
+    onStdout(text) {
+      appendText(attemptStdoutFile, text);
+      activityProjector.onStdoutChunk(text);
+    },
+    onStderr(text) {
+      appendText(attemptStderrFile, text);
+    },
     shouldKeepRunning() {
       return isHostLeaseAlive(hostLease);
     },
@@ -235,6 +278,10 @@ export async function runEngineAttempt({
 
   writeText(attemptPromptFile, prompt);
   writeEngineRunArtifacts(runDir, attemptPrefix, result, finalMessage);
+  activityProjector.finalize({
+    result,
+    finalMessage,
+  });
 
   return {
     result,

package/src/runtime_engine_task.mjs

@@ -3,6 +3,7 @@ import path from "node:path";
 import { ensureDir, nowIso, tailText, writeJson, writeText } from "./common.mjs";
 import { getEngineDisplayName, normalizeEngineName } from "./engine_metadata.mjs";
 import { resolveEngineInvocation } from "./engine_process_support.mjs";
+import { refreshHostContinuationArtifacts } from "./host_continuation.mjs";
 import { isHostLeaseAlive } from "./host_lease.mjs";
 import {
   buildRuntimeRecoveryPrompt,
@@ -52,6 +53,12 @@ export async function runEngineTask({
     outputPrefix: prefix,
     hardRetryBudget: recoveryPolicy.hardRetryDelaysSeconds.length,
     softRetryBudget: recoveryPolicy.softRetryDelaysSeconds.length,
+  }, () => {
+    try {
+      refreshHostContinuationArtifacts(context);
+    } catch {
+      // ignore continuation snapshot refresh failures during heartbeat writes
+    }
   });
 
   const recoveryHistory = [];

package/src/runtime_settings.mjs

@@ -0,0 +1,105 @@
+function normalizeBoolean(value, fallback = false) {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+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);
+}
+
+function normalizePositiveInteger(value, fallbackValue, minimum = 1) {
+  const parsed = normalizeNonNegativeInteger(value, fallbackValue);
+  if (!Number.isFinite(parsed) || parsed < minimum) {
+    return fallbackValue;
+  }
+  return parsed;
+}
+
+function normalizeSecondsList(values, fallbackValues) {
+  if (!Array.isArray(values) || !values.length) {
+    return [...fallbackValues];
+  }
+  const normalized = values
+    .map((item) => normalizePositiveInteger(item, 0))
+    .filter((item) => item > 0);
+  return normalized.length ? normalized : [...fallbackValues];
+}
+
+export function defaultTerminalConcurrencySettings() {
+  return {
+    enabled: true,
+    visibleMax: 8,
+    backgroundMax: 8,
+    totalMax: 8,
+  };
+}
+
+export function defaultObserverRetrySettings() {
+  return {
+    enabled: true,
+    missingPollsBeforeRetry: 3,
+    retryDelaysSeconds: [2, 5, 10, 15, 30, 60],
+    maxRetryCount: 0,
+  };
+}
+
+export function defaultSupervisorKeepAliveSettings() {
+  return {
+    enabled: true,
+    restartDelaysSeconds: [2, 5, 10, 15, 30, 60],
+    maxRestartCount: 0,
+  };
+}
+
+export function normalizeTerminalConcurrencySettings(settings = {}) {
+  const defaults = defaultTerminalConcurrencySettings();
+  return {
+    enabled: normalizeBoolean(settings?.enabled, defaults.enabled),
+    visibleMax: normalizeNonNegativeInteger(settings?.visibleMax, defaults.visibleMax),
+    backgroundMax: normalizeNonNegativeInteger(settings?.backgroundMax, defaults.backgroundMax),
+    totalMax: normalizeNonNegativeInteger(settings?.totalMax, defaults.totalMax),
+  };
+}
+
+export function normalizeObserverRetrySettings(settings = {}) {
+  const defaults = defaultObserverRetrySettings();
+  return {
+    enabled: normalizeBoolean(settings?.enabled, defaults.enabled),
+    missingPollsBeforeRetry: normalizePositiveInteger(
+      settings?.missingPollsBeforeRetry,
+      defaults.missingPollsBeforeRetry,
+    ),
+    retryDelaysSeconds: normalizeSecondsList(settings?.retryDelaysSeconds, defaults.retryDelaysSeconds),
+    maxRetryCount: normalizeNonNegativeInteger(settings?.maxRetryCount, defaults.maxRetryCount),
+  };
+}
+
+export function normalizeSupervisorKeepAliveSettings(settings = {}) {
+  const defaults = defaultSupervisorKeepAliveSettings();
+  return {
+    enabled: normalizeBoolean(settings?.enabled, defaults.enabled),
+    restartDelaysSeconds: normalizeSecondsList(settings?.restartDelaysSeconds, defaults.restartDelaysSeconds),
+    maxRestartCount: normalizeNonNegativeInteger(settings?.maxRestartCount, defaults.maxRestartCount),
+  };
+}
+
+export function pickRetryDelaySeconds(delays, attemptNumber) {
+  const values = Array.isArray(delays) && delays.length
+    ? delays.map((item) => normalizePositiveInteger(item, 0)).filter((item) => item > 0)
+    : [];
+  if (!values.length) {
+    return 0;
+  }
+  const index = Math.max(0, Math.min(Number(attemptNumber || 1) - 1, values.length - 1));
+  return values[index];
+}
+
+export function hasRetryBudget(maxRetryCount, nextAttemptNumber) {
+  return Number(maxRetryCount || 0) <= 0 || Number(nextAttemptNumber || 0) <= Number(maxRetryCount || 0);
+}

package/src/runtime_settings_loader.mjs

@@ -0,0 +1,19 @@
+import { loadGlobalConfig } from "./global_config.mjs";
+import {
+  normalizeObserverRetrySettings,
+  normalizeSupervisorKeepAliveSettings,
+  normalizeTerminalConcurrencySettings,
+} from "./runtime_settings.mjs";
+
+export function loadRuntimeSettings(options = {}) {
+  const globalConfig = loadGlobalConfig({
+    globalConfigFile: options.globalConfigFile,
+  });
+
+  return {
+    terminalConcurrency: normalizeTerminalConcurrencySettings(globalConfig?.runtime?.terminalConcurrency || {}),
+    observerRetry: normalizeObserverRetrySettings(globalConfig?.runtime?.observerRetry || {}),
+    supervisorKeepAlive: normalizeSupervisorKeepAliveSettings(globalConfig?.runtime?.supervisorKeepAlive || {}),
+    _meta: globalConfig?._meta || {},
+  };
+}

package/src/shell_invocation.mjs

@@ -1,5 +1,16 @@
+import fs from "node:fs";
+import path from "node:path";
 import { spawnSync } from "node:child_process";
 
+import { resolveWindowsHiddenShellEnvPatch } from "./windows_hidden_shell_proxy.mjs";
+
+function buildSyncSpawnOptions(platform = process.platform, extra = {}) {
+  return {
+    ...extra,
+    ...(platform === "win32" ? { windowsHide: true } : {}),
+  };
+}
+
 function createUnavailableInvocation(message) {
   return {
     command: "",
@@ -19,15 +30,19 @@ function parseWindowsCommandMatches(output) {
 function hasCommand(command, platform = process.platform) {
   if (platform === "win32") {
     const result = spawnSync("where.exe", [command], {
-      encoding: "utf8",
-      shell: false,
+      ...buildSyncSpawnOptions(platform, {
+        encoding: "utf8",
+        shell: false,
+      }),
     });
     return result.status === 0;
   }
 
   const result = spawnSync("sh", ["-lc", `command -v ${command}`], {
-    encoding: "utf8",
-    shell: false,
+    ...buildSyncSpawnOptions(platform, {
+      encoding: "utf8",
+      shell: false,
+    }),
   });
   return result.status === 0;
 }
@@ -35,8 +50,10 @@ function hasCommand(command, platform = process.platform) {
 function findWindowsCommandPaths(command, resolver) {
   const lookup = resolver || ((name) => {
     const result = spawnSync("where.exe", [name], {
-      encoding: "utf8",
-      shell: false,
+      ...buildSyncSpawnOptions("win32", {
+        encoding: "utf8",
+        shell: false,
+      }),
     });
     return result.status === 0 ? parseWindowsCommandMatches(result.stdout) : [];
   });
@@ -125,6 +142,14 @@ function isCmdLikeExecutable(executable) {
   return /\.(cmd|bat)$/i.test(String(executable || ""));
 }
 
+function trimOuterQuotes(value) {
+  return String(value || "").trim().replace(/^"(.*)"$/u, "$1");
+}
+
+function uniqueNonEmpty(values) {
+  return [...new Set(values.map((item) => trimOuterQuotes(item)).filter(Boolean))];
+}
+
 function resolveWindowsNamedExecutable(toolName, options = {}) {
   const explicitExecutable = String(options.explicitExecutable || "").trim();
   const findCommandPaths = options.findCommandPaths || ((command) => findWindowsCommandPaths(command));
@@ -133,7 +158,7 @@ function resolveWindowsNamedExecutable(toolName, options = {}) {
     return explicitExecutable;
   }
 
-  const searchOrder = [`${toolName}.ps1`, `${toolName}.exe`, toolName];
+  const searchOrder = [`${toolName}.exe`, `${toolName}.ps1`, toolName];
   for (const query of searchOrder) {
     const safeMatch = findCommandPaths(query).find((candidate) => !isCmdLikeExecutable(candidate));
     if (safeMatch) {
@@ -144,6 +169,189 @@ function resolveWindowsNamedExecutable(toolName, options = {}) {
   return "";
 }
 
+function resolveNodeHostForWrapper(wrapperPath) {
+  const wrapperDir = path.dirname(wrapperPath);
+  const bundledNode = path.join(wrapperDir, "node.exe");
+  if (fs.existsSync(bundledNode)) {
+    return bundledNode;
+  }
+  return process.execPath || "node";
+}
+
+function getUpdatedWindowsPath(newDirs, basePath = process.env.PATH || "") {
+  const existing = String(basePath || "")
+    .split(";")
+    .map((item) => trimOuterQuotes(item))
+    .filter(Boolean);
+  return uniqueNonEmpty([...newDirs, ...existing]).join(";");
+}
+
+function resolveCodexWindowsTargetTriple() {
+  if (process.arch === "arm64") {
+    return {
+      packageName: "@openai/codex-win32-arm64",
+      targetTriple: "aarch64-pc-windows-msvc",
+      managedEnvKey: "CODEX_MANAGED_BY_NPM",
+    };
+  }
+
+  if (process.arch === "x64") {
+    return {
+      packageName: "@openai/codex-win32-x64",
+      targetTriple: "x86_64-pc-windows-msvc",
+      managedEnvKey: "CODEX_MANAGED_BY_NPM",
+    };
+  }
+
+  return null;
+}
+
+function resolveWindowsNativeCodexInvocation(options = {}) {
+  const platform = options.platform || process.platform;
+  if (platform !== "win32") {
+    return null;
+  }
+
+  const target = resolveCodexWindowsTargetTriple();
+  if (!target) {
+    return null;
+  }
+
+  const explicitExecutable = trimOuterQuotes(options.explicitExecutable || "");
+  if (explicitExecutable && /\.exe$/iu.test(explicitExecutable) && fs.existsSync(explicitExecutable)) {
+    return {
+      command: explicitExecutable,
+      argsPrefix: [],
+      shell: false,
+    };
+  }
+
+  const findCommandPaths = options.findCommandPaths || ((command) => findWindowsCommandPaths(command));
+  const wrapperCandidates = [];
+
+  if (explicitExecutable) {
+    if (fs.existsSync(explicitExecutable)) {
+      wrapperCandidates.push(explicitExecutable);
+    } else {
+      wrapperCandidates.push(...findCommandPaths(explicitExecutable));
+    }
+  } else {
+    wrapperCandidates.push(...findCommandPaths("codex.ps1"));
+    wrapperCandidates.push(...findCommandPaths("codex"));
+  }
+
+  for (const wrapperPath of uniqueNonEmpty(wrapperCandidates)) {
+    const wrapperDir = path.dirname(wrapperPath);
+    const codexPackageRoot = path.join(wrapperDir, "node_modules", "@openai", "codex");
+    const vendorRoot = path.join(
+      codexPackageRoot,
+      "node_modules",
+      target.packageName,
+      "vendor",
+      target.targetTriple,
+    );
+    const binaryPath = path.join(vendorRoot, "codex", "codex.exe");
+    if (!fs.existsSync(binaryPath)) {
+      continue;
+    }
+    const rgPathDir = path.join(vendorRoot, "path");
+    const envPatch = {
+      [target.managedEnvKey]: "1",
+    };
+    if (fs.existsSync(rgPathDir)) {
+      envPatch.PATH = getUpdatedWindowsPath([rgPathDir], process.env.PATH || "");
+    }
+    return {
+      command: binaryPath,
+      argsPrefix: [],
+      shell: false,
+      env: envPatch,
+    };
+  }
+
+  return null;
+}
+
+function attachWindowsHiddenShellProxy(invocation, options = {}) {
+  if (!invocation || (options.platform || process.platform) !== "win32") {
+    return invocation;
+  }
+
+  try {
+    const envPatch = resolveWindowsHiddenShellEnvPatch({
+      basePath: invocation.env?.PATH || process.env.PATH || "",
+    });
+    if (!envPatch || !Object.keys(envPatch).length) {
+      return invocation;
+    }
+    return {
+      ...invocation,
+      env: {
+        ...(invocation.env || {}),
+        ...envPatch,
+      },
+    };
+  } catch (error) {
+    return {
+      ...invocation,
+      error: [
+        String(invocation.error || "").trim(),
+        `HelloLoop 无法准备 Windows 隐藏 shell 代理：${String(error?.message || error || "未知错误")}`,
+      ].filter(Boolean).join("\n"),
+    };
+  }
+}
+
+function resolveWindowsNodePackageInvocation(toolName, packageScriptSegments, options = {}) {
+  const platform = options.platform || process.platform;
+  if (platform !== "win32") {
+    return null;
+  }
+
+  const explicitExecutable = trimOuterQuotes(options.explicitExecutable || "");
+  if (explicitExecutable && /\.m?js$/iu.test(explicitExecutable) && fs.existsSync(explicitExecutable)) {
+    return {
+      command: process.execPath || "node",
+      argsPrefix: [explicitExecutable],
+      shell: false,
+    };
+  }
+
+  const findCommandPaths = options.findCommandPaths || ((command) => findWindowsCommandPaths(command));
+  const wrapperCandidates = [];
+
+  if (explicitExecutable) {
+    if (fs.existsSync(explicitExecutable)) {
+      wrapperCandidates.push(explicitExecutable);
+    } else {
+      wrapperCandidates.push(...findCommandPaths(explicitExecutable));
+    }
+  }
+
+  if (!wrapperCandidates.length) {
+    wrapperCandidates.push(...findCommandPaths(`${toolName}.ps1`));
+    wrapperCandidates.push(...findCommandPaths(`${toolName}.exe`));
+    wrapperCandidates.push(...findCommandPaths(toolName));
+  }
+
+  for (const wrapperPath of uniqueNonEmpty(wrapperCandidates)) {
+    if (isCmdLikeExecutable(wrapperPath) || !fs.existsSync(wrapperPath)) {
+      continue;
+    }
+    const packageScript = path.join(path.dirname(wrapperPath), "node_modules", ...packageScriptSegments);
+    if (!fs.existsSync(packageScript)) {
+      continue;
+    }
+    return {
+      command: resolveNodeHostForWrapper(wrapperPath),
+      argsPrefix: [packageScript],
+      shell: false,
+    };
+  }
+
+  return null;
+}
+
 export function resolveVerifyShellInvocation(options = {}) {
   const platform = options.platform || process.platform;
 
@@ -217,11 +425,21 @@ export function resolveCliInvocation(options = {}) {
 }
 
 export function resolveCodexInvocation(options = {}) {
-  return resolveCliInvocation({
+  const nativeCodexInvocation = resolveWindowsNativeCodexInvocation(options);
+  if (nativeCodexInvocation) {
+    return attachWindowsHiddenShellProxy(nativeCodexInvocation, options);
+  }
+
+  const nodePackageInvocation = resolveWindowsNodePackageInvocation("codex", ["@openai", "codex", "bin", "codex.js"], options);
+  if (nodePackageInvocation) {
+    return attachWindowsHiddenShellProxy(nodePackageInvocation, options);
+  }
+
+  return attachWindowsHiddenShellProxy(resolveCliInvocation({
     ...options,
     commandName: "codex",
     toolDisplayName: "Codex",
-  });
+  }), options);
 }
 
 export function resolveClaudeInvocation(options = {}) {

package/src/supervisor_cli_support.mjs

@@ -0,0 +1,49 @@
+import { launchSupervisedCommand, renderSupervisorLaunchSummary } from "./supervisor_runtime.mjs";
+import { watchSupervisorSessionWithRecovery } from "./supervisor_watch.mjs";
+
+export function shouldUseSupervisor(options = {}) {
+  return !options.dryRun
+    && process.env.HELLOLOOP_SUPERVISOR_ACTIVE !== "1";
+}
+
+export function shouldAutoWatchSupervisor(options = {}) {
+  if (options.detach) {
+    return false;
+  }
+  if (options.watch === true) {
+    return true;
+  }
+  if (options.watch === false) {
+    return false;
+  }
+  return Boolean(process.stdout.isTTY);
+}
+
+export async function launchAndMaybeWatchSupervisedCommand(context, command, options = {}) {
+  const session = launchSupervisedCommand(context, command, options);
+  console.log(renderSupervisorLaunchSummary(session));
+
+  if (!shouldAutoWatchSupervisor(options)) {
+    console.log("- 已切换为后台执行；可稍后运行 `helloloop watch` 或 `helloloop status` 查看进度。");
+    return {
+      detached: true,
+      exitCode: 0,
+      ok: true,
+      session,
+    };
+  }
+
+  console.log("- 已进入附着观察模式；按 Ctrl+C 仅退出观察，不会停止后台任务。");
+  const watchResult = await watchSupervisorSessionWithRecovery(context, {
+    sessionId: session.sessionId,
+    pollMs: options.watchPollMs,
+    globalConfigFile: options.globalConfigFile,
+  });
+  return {
+    detached: false,
+    exitCode: watchResult.exitCode,
+    ok: watchResult.ok,
+    session,
+    watchResult,
+  };
+}