helloloop 0.9.1 → 0.10.0

package/src/cli_args.mjs

@@ -1,30 +1,60 @@
 const REPO_ROOT_PLACEHOLDER = "<REPO_ROOT>";
 const DOCS_PATH_PLACEHOLDER = "<DOCS_PATH>";
-const KNOWN_COMMANDS = new Set([
-  "__supervise",
-  "analyze",
-  "install",
-  "uninstall",
-  "init",
-  "status",
-  "watch",
-  "next",
-  "run-once",
-  "run-loop",
-  "doctor",
-  "help",
-  "--help",
-  "-h",
+const KNOWN_ENGINES = new Set([
+  "codex",
+  "claude",
+  "gemini",
 ]);
+const COMMAND_ALIASES = Object.freeze({
+  "__supervise": "__supervise",
+  "__supervise-worker": "__supervise-worker",
+  "__web-server": "__web-server",
+  analyze: "analyze",
+  a: "analyze",
+  dashboard: "dashboard",
+  dash: "dashboard",
+  db: "dashboard",
+  tui: "tui",
+  web: "web",
+  install: "install",
+  i: "install",
+  uninstall: "uninstall",
+  un: "uninstall",
+  init: "init",
+  resume: "resume-host",
+  rh: "resume-host",
+  "resume-host": "resume-host",
+  status: "status",
+  st: "status",
+  watch: "watch",
+  w: "watch",
+  next: "next",
+  n: "next",
+  "run-once": "run-once",
+  once: "run-once",
+  "run-loop": "run-loop",
+  loop: "run-loop",
+  doctor: "doctor",
+  dr: "doctor",
+  help: "help",
+  "--help": "help",
+  "-h": "help",
+});
+const KNOWN_COMMANDS = new Set(Object.keys(COMMAND_ALIASES));
+
+function normalizeCommand(value = "") {
+  return COMMAND_ALIASES[String(value || "").trim()] || "";
+}
 
 export function parseArgs(argv) {
   const [first = "", ...restArgs] = argv;
+  const normalizedFirstCommand = normalizeCommand(first);
   const command = !first
     ? "analyze"
-    : (KNOWN_COMMANDS.has(first) ? first : "analyze");
+    : (normalizedFirstCommand || "analyze");
   const rest = !first
     ? []
-    : (KNOWN_COMMANDS.has(first) ? restArgs : argv);
+    : (normalizedFirstCommand ? restArgs : argv);
   const options = {
     requiredDocs: [],
     constraints: [],
@@ -35,11 +65,11 @@ export function parseArgs(argv) {
     const arg = rest[index];
     if (arg === "--dry-run") options.dryRun = true;
     else if (arg === "--yes" || arg === "-y") options.yes = true;
-    else if (arg === "--allow-high-risk") options.allowHighRisk = true;
+    else if (arg === "--allow-high-risk" || arg === "-r") options.allowHighRisk = true;
     else if (arg === "--rebuild-existing") options.rebuildExisting = true;
     else if (arg === "--force") options.force = true;
-    else if (arg === "--task-id") { options.taskId = rest[index + 1]; index += 1; }
-    else if (arg === "--max-tasks") { options.maxTasks = Number(rest[index + 1]); index += 1; }
+    else if (arg === "--task-id" || arg === "-t") { options.taskId = rest[index + 1]; index += 1; }
+    else if (arg === "--max-tasks" || arg === "-m") { options.maxTasks = Number(rest[index + 1]); index += 1; }
     else if (arg === "--max-attempts") { options.maxAttempts = Number(rest[index + 1]); index += 1; }
     else if (arg === "--max-strategies") { options.maxStrategies = Number(rest[index + 1]); index += 1; }
     else if (arg === "--repo") { options.repoRoot = rest[index + 1]; index += 1; }
@@ -52,15 +82,32 @@ 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 === "--watch") options.watch = true;
-    else if (arg === "--detach") options.detach = true;
+    else if (arg === "--launch-id") { options.launchId = rest[index + 1]; index += 1; }
+    else if (arg === "--watch" || arg === "-w") options.watch = true;
+    else if (arg === "--detach" || arg === "-d") options.detach = true;
+    else if (arg === "--foreground") options.foreground = true;
+    else if (arg === "--stop") options.stop = true;
+    else if (arg === "--json" || arg === "-j") options.json = true;
+    else if (arg === "--compact" || arg === "-c") options.compact = true;
+    else if (arg === "--events" || arg === "-e") options.events = 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 === "--poll-ms" || arg === "-p") { options.pollMs = Number(rest[index + 1]); index += 1; }
+    else if (arg === "--port") { options.port = Number(rest[index + 1]); index += 1; }
+    else if (arg === "--bind") { options.bind = 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); }
   }
 
+  const [leadingPositional = "", ...remainingPositionals] = options.positionalArgs;
+  const normalizedLeadingEngine = String(leadingPositional || "").trim().toLowerCase();
+  if (!options.engine && KNOWN_ENGINES.has(normalizedLeadingEngine)) {
+    options.engine = normalizedLeadingEngine;
+    options.engineSource = "leading_positional";
+    options.positionalArgs = remainingPositionals;
+  }
+
   return { command, options };
 }
 
@@ -69,16 +116,21 @@ function helpText() {
     "用法：helloloop [command] [engine] [path|需求说明...] [options]",
     "",
     "命令：",
-    "  analyze               自动分析并生成执行确认单；确认后继续自动接续开发（默认）",
-    "  install               安装插件到 Codex Home（适合 npx / npm bin 分发）",
-    "  uninstall             从所选宿主卸载插件并清理注册信息",
+    "  analyze | a           自动分析并生成执行确认单；确认后继续自动接续开发（默认）",
+    "  dashboard | dash | db 在当前终端启动动态 TUI 看板（默认总控台）",
+    "  tui                   dashboard 的显式别名，适合从主终端直接打开实时任务看板",
+    "  web                   启动本地 Web 看板；默认后台启动并输出访问地址",
+    "  install | i           安装插件到 Codex Home（适合 npx / npm bin 分发）",
+    "  uninstall | un        从所选宿主卸载插件并清理注册信息",
     "  init                  初始化 .helloloop 配置",
-    "  status                查看 backlog 与下一任务",
-    "  watch                 附着到后台 supervisor，持续查看实时进度",
-    "  next                  生成下一任务干跑预览",
-    "  run-once              执行一个任务",
-    "  run-loop              连续执行多个任务",
-    "  doctor                检查 Codex、当前插件 bundle 与目标仓库 .helloloop 配置是否可用",
+    "  resume-host | resume | rh",
+    "                        输出当前仓库的宿主续跑自然语言提示，供主 CLI / 主代理中断后继续输入",
+    "  status | st           查看 backlog 与下一任务",
+    "  watch | w             附着到后台 supervisor，持续查看实时进度",
+    "  next | n              生成下一任务干跑预览",
+    "  run-once | once       执行一个任务",
+    "  run-loop | loop       连续执行多个任务",
+    "  doctor | dr           检查 Codex、当前插件 bundle 与目标仓库 .helloloop 配置是否可用",
     "",
     "选项：",
     "  --host <name>        安装宿主：codex | claude | gemini | all（默认 codex）",
@@ -91,14 +143,20 @@ function helpText() {
     "  --config-dir <dir>    配置目录，默认 .helloloop",
     "  -y, --yes             跳过交互确认，分析后直接开始自动执行",
     "  --dry-run             只分析并输出确认单，不真正开始自动执行",
-    "  --task-id <id>        指定任务 id",
-    "  --max-tasks <n>       run-loop 最多执行 n 个任务",
+    "  -t, --task-id <id>    指定任务 id",
+    "  -m, --max-tasks <n>   run-loop 最多执行 n 个任务",
     "  --max-attempts <n>    每种策略内最多重试 n 次",
     "  --max-strategies <n>  单任务最多切换 n 种策略继续重试",
-    "  --watch               启动后台 supervisor 后，当前终端继续附着观察实时输出",
-    "  --detach              仅启动后台 supervisor 后立即返回，不进入观察模式",
+    "  -w, --watch           启动后台 supervisor 后，当前终端继续附着观察实时输出",
+    "  -d, --detach          仅启动后台 supervisor 后立即返回，不进入观察模式",
+    "  --foreground          web 命令以前台模式运行本地服务",
+    "  --stop                web 命令停止当前本地看板服务",
+    "  -j, --json            以 JSON / NDJSON 形式输出结构化状态",
     "  --session-id <id>     status/watch 指定附着的后台会话 ID",
-    "  --allow-high-risk     允许执行 medium/high/critical 风险任务",
+    "  -r, --allow-high-risk 手动 run-once/run-loop 时允许执行 medium/high/critical 风险任务",
+    "  -p, --poll-ms <n>     dashboard 轮询间隔（毫秒）",
+    "  --port <n>            web 命令指定监听端口，默认优先尝试 3210",
+    "  --bind <addr>         web 命令指定监听地址，默认 127.0.0.1",
     "  --rebuild-existing    分析判断当前项目与文档冲突时，自动清理当前项目后按文档重建",
     "  --required-doc <p>    增加一个全局必读文档（AGENTS.md 会被自动忽略）",
     "  --constraint <text>   增加一个全局实现约束",
@@ -107,8 +165,15 @@ function helpText() {
     "  analyze 默认支持在命令后混合传入引擎、路径和自然语言要求。",
     "  如果同时检测到多个可用引擎且没有明确指定，会先询问你选择。",
     "  当前版本默认会把自动执行 / run-once / run-loop 切到后台 supervisor。",
+    "  `helloloop dashboard` / `helloloop tui` 会打开终端实时总控台，不再把文本 dashboard 作为默认交互形态。",
+    "  `helloloop dashboard --json --watch` 仍可为宿主主代理提供结构化状态流。",
+    "  `helloloop web` 会启动本地 Web 看板，适合长时间像 Jira 一样查看多仓任务板。",
+    "  `helloloop resume-host --json` 会输出结构化续跑提示；不带 `--json` 时直接输出自然语言续跑内容。",
+    "  Windows 下 `analyze -y --detach` 会直接切到隐藏后台引导，不再保留前台空白控制台等待分析完成。",
+    "  Windows 下运行 Codex 时会优先绕过 codex.ps1，直接以隐藏原生 codex.exe 启动，并把内部 pwsh/powershell 调度重定向到隐藏代理，尽量避免额外 PowerShell 窗口闪烁。",
+    "  `watch` / `status --watch` / `dashboard --json --watch` 会按全局设置自动重试附着或重连；后台守护进程也会按设置保活重拉起。",
     "  交互终端默认会自动附着观察；如只想立即返回，请显式加 --detach。",
-    "  任何时候都可运行 `helloloop watch` 或 `helloloop status --watch` 重新附着观察。",
+    "  任何时候都可运行 `helloloop watch` / `helloloop w` 或 `helloloop status --watch` / `helloloop st -w` 重新附着观察。",
     "  示例：npx helloloop claude <DOCS_PATH> <PROJECT_ROOT> 先分析偏差，不要执行",
   ].join("\n");
 }

package/src/cli_command_handlers.mjs

@@ -1,16 +1,21 @@
 import path from "node:path";
 
 import { createContext } from "./context.mjs";
+import { runDashboardCommand } from "./dashboard_command.mjs";
+import { runDashboardTuiCommand } from "./dashboard_tui.mjs";
+import { runDashboardWebCommand } from "./dashboard_web.mjs";
 import { loadBacklog, scaffoldIfMissing } from "./config.mjs";
 import { syncUserSettingsFile } from "./engine_selection_settings.mjs";
+import { readHostContinuationSnapshot, runHostContinuationCommand } from "./host_continuation.mjs";
 import { installPluginBundle, uninstallPluginBundle } from "./install.mjs";
 import { runLoop, runOnce, renderStatusText } from "./runner.mjs";
+import { collectRepoStatusSnapshot } from "./runner_status.mjs";
 import { renderInstallSummary, renderUninstallSummary } from "./cli_render.mjs";
 import {
   launchAndMaybeWatchSupervisedCommand,
   shouldUseSupervisor,
 } from "./supervisor_cli_support.mjs";
-import { watchSupervisorSession } from "./supervisor_watch.mjs";
+import { watchSupervisorSessionWithRecovery } from "./supervisor_watch.mjs";
 
 export function handleInstallCommand(options) {
   const userSettings = syncUserSettingsFile({
@@ -64,14 +69,29 @@ export async function handleDoctorCommand(context, options, runDoctor) {
 }
 
 export async function handleStatusCommand(context, options) {
-  console.log(renderStatusText(context, options));
+  const hostResume = readHostContinuationSnapshot(context, {
+    refresh: true,
+    sessionId: options.sessionId || "",
+  });
+  if (options.json) {
+    console.log(JSON.stringify({
+      ...collectRepoStatusSnapshot(context, options),
+      hostResume,
+    }, null, 2));
+  } else {
+    console.log(renderStatusText(context, {
+      ...options,
+      hostResume,
+    }));
+  }
   if (!options.watch) {
     return 0;
   }
 
-  const result = await watchSupervisorSession(context, {
+  const result = await watchSupervisorSessionWithRecovery(context, {
     sessionId: options.sessionId,
     pollMs: options.watchPollMs,
+    globalConfigFile: options.globalConfigFile,
   });
   if (result.empty) {
     console.log("当前没有正在运行的后台 supervisor。");
@@ -80,10 +100,30 @@ export async function handleStatusCommand(context, options) {
   return result.exitCode || 0;
 }
 
+export async function handleDashboardCommand(options) {
+  if (options.json === true) {
+    return runDashboardCommand(options);
+  }
+  return runDashboardTuiCommand(options);
+}
+
+export async function handleTuiCommand(options) {
+  return runDashboardTuiCommand(options);
+}
+
+export async function handleWebCommand(options) {
+  return runDashboardWebCommand(options);
+}
+
+export async function handleResumeHostCommand(context, options) {
+  return runHostContinuationCommand(context, options);
+}
+
 export async function handleWatchCommand(context, options) {
-  const result = await watchSupervisorSession(context, {
+  const result = await watchSupervisorSessionWithRecovery(context, {
     sessionId: options.sessionId,
     pollMs: options.watchPollMs,
+    globalConfigFile: options.globalConfigFile,
   });
   if (result.empty) {
     console.log("当前没有正在运行的后台 supervisor。");

package/src/cli_support.mjs

@@ -19,6 +19,7 @@ function probeCodexVersion() {
   const codexVersion = spawnSync(invocation.command, [...invocation.argsPrefix, "--version"], {
     encoding: "utf8",
     shell: invocation.shell,
+    windowsHide: process.platform === "win32",
   });
   const ok = codexVersion.status === 0;
   return {
@@ -113,6 +114,7 @@ function probeNamedCliVersion(commandName, toolDisplayName) {
   const result = spawnSync(invocation.command, [...invocation.argsPrefix, "--version"], {
     encoding: "utf8",
     shell: invocation.shell,
+    windowsHide: process.platform === "win32",
   });
   const ok = result.status === 0;
   return {

package/src/dashboard_command.mjs

@@ -0,0 +1,371 @@
+import path from "node:path";
+
+import { nowIso, sleep } from "./common.mjs";
+import { createContext } from "./context.mjs";
+import { analyzeExecution } from "./backlog.mjs";
+import { loadBacklog } from "./config.mjs";
+import { buildDashboardHostContinuation } from "./host_continuation.mjs";
+import { loadRuntimeSettings } from "./runtime_settings_loader.mjs";
+import { collectRepoStatusSnapshot } from "./runner_status.mjs";
+import { hasRetryBudget, pickRetryDelaySeconds } from "./runtime_settings.mjs";
+import { isTrackedPidAlive } from "./supervisor_state.mjs";
+import { listActiveSessionEntries, listKnownWorkspaceEntries } from "./workspace_registry.mjs";
+
+function formatRuntimeLabel(runtime) {
+  if (!runtime?.status) {
+    return "idle";
+  }
+  const details = [runtime.status];
+  if (Number.isFinite(Number(runtime.recoveryCount)) && Number(runtime.recoveryCount) > 0) {
+    details.push(`recovery=${runtime.recoveryCount}`);
+  }
+  if (Number.isFinite(Number(runtime?.heartbeat?.idleSeconds)) && Number(runtime.heartbeat.idleSeconds) > 0) {
+    details.push(`idle=${runtime.heartbeat.idleSeconds}s`);
+  }
+  return details.join(" | ");
+}
+
+function formatCurrentAction(session) {
+  return session.activity?.current?.label
+    || session.runtime?.failureReason
+    || session.latestStatus?.message
+    || session.runtime?.status
+    || "等待新事件";
+}
+
+function formatTodoLabel(activity) {
+  if (!activity?.todo?.total) {
+    return "";
+  }
+  return `${activity.todo.completed}/${activity.todo.total}`;
+}
+
+function readBacklogSnapshot(context) {
+  try {
+    const backlog = loadBacklog(context);
+    return {
+      tasks: Array.isArray(backlog.tasks) ? backlog.tasks : [],
+      execution: analyzeExecution(backlog),
+    };
+  } catch {
+    return {
+      tasks: [],
+      execution: null,
+    };
+  }
+}
+
+function normalizeSupervisorSnapshot(supervisor) {
+  if (!supervisor?.status) {
+    return supervisor;
+  }
+  if (["launching", "running"].includes(String(supervisor.status)) && !isTrackedPidAlive(supervisor.guardianPid || supervisor.pid)) {
+    return {
+      ...supervisor,
+      status: "stopped",
+      message: supervisor.message || "后台会话当前未运行。",
+    };
+  }
+  return supervisor;
+}
+
+function normalizeRuntimeSnapshot(supervisor, runtime) {
+  if (!runtime) {
+    return runtime;
+  }
+  if (!supervisor?.status || supervisor.status !== "stopped") {
+    return runtime;
+  }
+  if (!["launching", "running", "recovering", "probe_running", "probe_waiting", "retry_waiting"].includes(String(runtime.status || ""))) {
+    return runtime;
+  }
+
+  const stoppedReason = "后台 supervisor 当前未运行；以下展示的是最近一次执行快照。";
+  return {
+    ...runtime,
+    status: "stopped",
+    failureReason: runtime.failureReason || stoppedReason,
+    heartbeat: runtime.heartbeat
+      ? {
+        ...runtime.heartbeat,
+        status: "stopped",
+        leaseExpired: true,
+        leaseReason: runtime.heartbeat.leaseReason || stoppedReason,
+      }
+      : runtime.heartbeat,
+  };
+}
+
+function normalizeActivitySnapshot(supervisor, activity) {
+  if (!activity) {
+    return activity;
+  }
+  if (!supervisor?.status || supervisor.status !== "stopped") {
+    return activity;
+  }
+  if (String(activity.status || "") !== "running") {
+    return activity;
+  }
+
+  return {
+    ...activity,
+    status: "stopped",
+    runtime: activity.runtime
+      ? {
+        ...activity.runtime,
+        status: "stopped",
+      }
+      : activity.runtime,
+  };
+}
+
+function buildSessionSnapshot(entry) {
+  const context = createContext({
+    repoRoot: entry.repoRoot,
+    configDirName: entry.configDirName,
+  });
+  let repoSnapshot;
+  try {
+    repoSnapshot = collectRepoStatusSnapshot(context, {
+      sessionId: entry.sessionId,
+    });
+  } catch (error) {
+    repoSnapshot = {
+      supervisor: null,
+      latestStatus: {
+        message: String(error?.message || error || "状态读取失败。"),
+      },
+      runtime: null,
+      activity: null,
+      summary: null,
+      nextTask: null,
+    };
+  }
+  const backlogSnapshot = readBacklogSnapshot(context);
+  const supervisor = normalizeSupervisorSnapshot(repoSnapshot.supervisor);
+  const runtime = normalizeRuntimeSnapshot(supervisor, repoSnapshot.runtime);
+  const activity = normalizeActivitySnapshot(supervisor, repoSnapshot.activity);
+  const snapshotForContinuation = {
+    ...repoSnapshot,
+    supervisor,
+    runtime,
+    activity,
+  };
+
+  return {
+    repoRoot: entry.repoRoot,
+    repoName: path.basename(entry.repoRoot),
+    sessionId: entry.sessionId || repoSnapshot.latestStatus?.sessionId || "",
+    command: entry.command || supervisor?.command || "",
+    supervisor,
+    latestStatus: repoSnapshot.latestStatus,
+    runtime,
+    activity,
+    summary: repoSnapshot.summary,
+    nextTask: repoSnapshot.nextTask,
+    tasks: backlogSnapshot.tasks,
+    execution: backlogSnapshot.execution,
+    isActive: entry.isActive === true,
+    hostResume: buildDashboardHostContinuation(entry, snapshotForContinuation),
+    updatedAt: repoSnapshot.activity?.updatedAt
+      || repoSnapshot.runtime?.updatedAt
+      || repoSnapshot.latestStatus?.updatedAt
+      || supervisor?.updatedAt
+      || entry.updatedAt
+      || "",
+  };
+}
+
+function buildTaskTotals(sessions) {
+  const totals = {
+    total: 0,
+    pending: 0,
+    inProgress: 0,
+    done: 0,
+    failed: 0,
+    blocked: 0,
+  };
+
+  for (const session of sessions) {
+    totals.total += Number(session.summary?.total || 0);
+    totals.pending += Number(session.summary?.pending || 0);
+    totals.inProgress += Number(session.summary?.inProgress || 0);
+    totals.done += Number(session.summary?.done || 0);
+    totals.failed += Number(session.summary?.failed || 0);
+    totals.blocked += Number(session.summary?.blocked || 0);
+  }
+
+  return totals;
+}
+
+export function collectDashboardSnapshot() {
+  const activeEntries = listActiveSessionEntries()
+    .map((entry) => ({ ...entry, isActive: true }));
+  const knownEntries = listKnownWorkspaceEntries()
+    .map((entry) => ({ ...entry, isActive: false }));
+  const mergedEntries = new Map();
+
+  for (const entry of [...knownEntries, ...activeEntries]) {
+    const key = `${entry.repoRoot}::${entry.configDirName || ""}`;
+    const current = mergedEntries.get(key) || {};
+    mergedEntries.set(key, {
+      ...current,
+      ...entry,
+      isActive: entry.isActive === true || current.isActive === true,
+    });
+  }
+
+  const sessions = [...mergedEntries.values()]
+    .map((entry) => buildSessionSnapshot(entry))
+    .sort((left, right) => String(right.updatedAt || "").localeCompare(String(left.updatedAt || "")));
+
+  return {
+    schemaVersion: 1,
+    generatedAt: nowIso(),
+    activeCount: activeEntries.length,
+    repoCount: sessions.length,
+    taskTotals: buildTaskTotals(sessions),
+    primaryHostResume: sessions[0]?.hostResume || null,
+    sessions,
+  };
+}
+
+function renderCompactSession(session, index) {
+  return [
+    `${index + 1}. ${session.repoName}`,
+    `   session=${session.sessionId}`,
+    `   task=${session.latestStatus?.taskTitle || "无"}`,
+    `   runtime=${formatRuntimeLabel(session.runtime)}`,
+    `   action=${formatCurrentAction(session)}`,
+    ...(formatTodoLabel(session.activity) ? [`   todo=${formatTodoLabel(session.activity)}`] : []),
+  ].join("\n");
+}
+
+function renderDetailedSession(session, index, options) {
+  const lines = [
+    `[${index + 1}] ${session.repoName}`,
+    `- 仓库：${session.repoRoot}`,
+    `- 会话：${session.sessionId}`,
+    `- supervisor：${session.supervisor?.status || "unknown"}`,
+    `- 命令：${session.command || "unknown"}`,
+    `- 当前任务：${session.latestStatus?.taskTitle || "无"}`,
+    `- 当前阶段：${session.latestStatus?.stage || "unknown"}`,
+    `- backlog：已完成 ${session.summary?.done || 0} / 总计 ${session.summary?.total || 0} / 待处理 ${session.summary?.pending || 0}`,
+    `- 运行状态：${formatRuntimeLabel(session.runtime)}`,
+    `- 当前动作：${formatCurrentAction(session)}`,
+    `- 宿主续跑：${session.hostResume?.issue?.label || (session.hostResume?.supervisorActive ? "后台仍在运行，可直接接续观察" : "需要按续跑提示继续")}`,
+  ];
+
+  if (formatTodoLabel(session.activity)) {
+    lines.push(`- 当前待办：${formatTodoLabel(session.activity)}`);
+  }
+  if (Array.isArray(session.activity?.activeCommands) && session.activity.activeCommands[0]?.label) {
+    lines.push(`- 活动命令：${session.activity.activeCommands[0].label}`);
+  }
+  if (Array.isArray(session.activity?.recentFileChanges) && session.activity.recentFileChanges[0]?.changes?.length) {
+    const fileLabels = session.activity.recentFileChanges[0].changes
+      .slice(0, 3)
+      .map((item) => `${item.kind}:${item.path}`);
+    lines.push(`- 最近文件：${fileLabels.join(" | ")}`);
+  }
+  if (options.events && Array.isArray(session.activity?.recentEvents) && session.activity.recentEvents.length) {
+    lines.push("- 最近事件：");
+    for (const event of session.activity.recentEvents.slice(-5)) {
+      lines.push(`  - [${event.status || "info"}] ${event.kind}: ${event.label}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function renderDashboardText(snapshot, options = {}) {
+  const lines = [
+    "HelloLoop Dashboard",
+    "===================",
+    `仓库总数：${snapshot.repoCount}`,
+    `活跃会话：${snapshot.activeCount}`,
+    `更新时间：${snapshot.generatedAt}`,
+  ];
+
+  if (!snapshot.sessions.length) {
+    lines.push("");
+    lines.push("当前没有已登记仓库或后台会话。");
+    return lines.join("\n");
+  }
+
+  for (const [index, session] of snapshot.sessions.entries()) {
+    lines.push("");
+    lines.push(options.compact
+      ? renderCompactSession(session, index)
+      : renderDetailedSession(session, index, options));
+  }
+
+  return lines.join("\n");
+}
+
+export function buildDashboardSnapshotSignature(snapshot) {
+  return JSON.stringify(snapshot.sessions.map((session) => ({
+    repoRoot: session.repoRoot,
+    sessionId: session.sessionId,
+    taskId: session.latestStatus?.taskId || "",
+    stage: session.latestStatus?.stage || "",
+    runtimeStatus: session.runtime?.status || "",
+    idleSeconds: session.runtime?.heartbeat?.idleSeconds || 0,
+    action: session.activity?.current?.label || "",
+    todoCompleted: session.activity?.todo?.completed || 0,
+    todoTotal: session.activity?.todo?.total || 0,
+    eventLabel: session.activity?.recentEvents?.at(-1)?.label || "",
+    resumeIssue: session.hostResume?.issue?.code || "",
+    taskFingerprint: (session.tasks || [])
+      .map((task) => `${task.id}:${task.status || "pending"}:${task.title}`)
+      .join("|"),
+  })));
+}
+
+export async function runDashboardCommand(options = {}) {
+  const pollMs = Math.max(500, Number(options.pollMs || options.watchPollMs || 2000));
+  const observerRetry = loadRuntimeSettings({
+    globalConfigFile: options.globalConfigFile,
+  }).observerRetry;
+  let previousSignature = "";
+  let retryCount = 0;
+
+  while (true) {
+    try {
+      const snapshot = collectDashboardSnapshot();
+      const signature = buildDashboardSnapshotSignature(snapshot);
+      retryCount = 0;
+
+      if (signature !== previousSignature || !options.watch) {
+        previousSignature = signature;
+        if (options.json) {
+          console.log(JSON.stringify(snapshot));
+        } else {
+          if (options.watch && process.stdout.isTTY) {
+            process.stdout.write("\x1bc");
+          }
+          console.log(renderDashboardText(snapshot, options));
+        }
+      }
+    } catch (error) {
+      const nextAttempt = retryCount + 1;
+      if (!options.watch || !observerRetry.enabled || !hasRetryBudget(observerRetry.maxRetryCount, nextAttempt)) {
+        throw error;
+      }
+
+      const delaySeconds = pickRetryDelaySeconds(observerRetry.retryDelaysSeconds, nextAttempt);
+      process.stderr.write(
+        `[HelloLoop dashboard] 看板采集失败，将在 ${delaySeconds} 秒后自动重试（第 ${nextAttempt} 次）：${String(error?.message || error || "unknown error")}\n`,
+      );
+      retryCount = nextAttempt;
+      await sleep(delaySeconds * 1000);
+      continue;
+    }
+
+    if (!options.watch) {
+      return 0;
+    }
+
+    await sleep(pollMs);
+  }
+}