dsh-any-agent 0.6.0 → 0.6.2

package/src/conversation.mjs

@@ -40,6 +40,7 @@ import { rssMb } from './procstat.mjs';
 import { readConversationMeta } from './titles.mjs';
 import { gitStatus, sameWorkspaceSnapshot } from './git-snapshot.mjs';
 import { writeTombstone } from './hub-store.mjs';
+import { emitLive, livePreview, liveSettings, removeLive, summarizeToolInput } from './live.mjs';
 import {
   classifyHolder,
   describeLeaseConflict,
@@ -141,6 +142,82 @@ export class Conversation {
 
   #hub;
 
+  /**
+   * live 事件流用的工具跟踪：tool_call_id → {at, status, hasInput}。
+   * 单独放在这里而不是回合收集器里：收集器的 tools 会原样进 tools_used，不能混入新字段。
+   */
+  #liveTools = new Map();
+
+  /** 当前 run_id（live 事件用；回合外为 null）。 */
+  #liveRunId() {
+    return this.currentRun?.run_id ?? null;
+  }
+
+  /** 写一条 live 事件（永不抛错，见 live.mjs）。 */
+  #live(type, fields = {}, detail = null) {
+    emitLive(this.id, type, { run: this.#liveRunId(), turn: this.currentTurn, ...fields }, detail);
+  }
+
+  /**
+   * live 事件流的 token 跟踪：`{runId, base, at, last}`。
+   * DSH 在投影缓存里维护**会话累计**的 tokenUsage.totals，并在回合中每个模型步之后更新
+   * （真机实测）；回合开始时记下基线，之后发的是"本回合增量"。
+   */
+  #liveUsage = null;
+
+  /** 读 DSH 投影缓存里的 token 累计与上下文压力；读不到返回 null。 */
+  #readTokenUsage() {
+    try {
+      const meta = readConversationMeta(this.id);
+      const t = meta?.usage?.totals;
+      const p = meta?.pressure;
+      if (!t && !p) return null;
+      const n = (v) => (Number.isFinite(v) && v > 0 ? v : 0);
+      return {
+        totals: t
+          ? { input: n(t.uncachedInputTokens), output: n(t.outputTokens), cache_read: n(t.cacheReadTokens), cache_write: n(t.cacheWriteTokens) }
+          : null,
+        context: p && Number.isFinite(p.contextWindow) ? { used: n(p.pressureTokens ?? p.surfaceTokens), window: p.contextWindow } : null,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 发一条 `usage` 事件（本回合 token 增量 + 会话累计 + 上下文占用）。
+   * 回合中节流到 2 秒一次、且只在数字变化时发；回合结束后 force 再发一次最终值。
+   */
+  #liveUsageTick({ force = false } = {}) {
+    const u = this.#liveUsage;
+    if (!u) return;
+    const t = now();
+    if (!force && t - u.at < 2000) return;
+    u.at = t;
+    const cur = this.#readTokenUsage();
+    if (!cur?.totals && !cur?.context) return;
+    const base = u.base ?? { input: 0, output: 0, cache_read: 0, cache_write: 0 };
+    const tokens = cur.totals
+      ? Object.fromEntries(Object.keys(base).map((k) => [k, Math.max(0, cur.totals[k] - base[k])]))
+      : null;
+    const sig = JSON.stringify([tokens, cur.context]);
+    if (!force && sig === u.last) return;
+    u.last = sig;
+    emitLive(this.id, 'usage', {
+      run: u.runId,
+      turn: u.turn,
+      tokens,
+      session_tokens: cur.totals,
+      context: cur.context,
+      final: force || undefined,
+    });
+  }
+
+  /** 审批裁决事件（decide / 超时 / 回合结束 / 关闭 统一走这里）。 */
+  #liveApprovalDecided(approvalId, by, decision = null, effective = null) {
+    this.#live('approval.decided', { approval_id: approvalId, by, decision, effective });
+  }
+
   /** 序列化进注册表的最小状态——**只有元数据，没有对话内容**。 */
   toState() {
     return {
@@ -571,10 +648,12 @@ export class Conversation {
         if (u.title !== undefined || u.status !== undefined || u.name !== undefined) {
           this.pushOut('tool', `${label}${tag}`, { tool_call_id: id });
         }
+        this.#liveTool(id, merged);
         break;
       }
       case 'usage_update':
         c.usage = u;
+        this.#liveUsageTick();
         break;
       case 'plan':
       case 'plan_update':
@@ -585,6 +664,36 @@ export class Conversation {
     }
   }
 
+  /**
+   * 工具状态 → live 事件。DSH 的工具更新是快照、会重复推同一状态，所以只在
+   * "第一次出现 / 状态变化 / 第一次拿到输入"时写，避免刷屏。
+   */
+  #liveTool(id, merged) {
+    const seen = this.#liveTools.get(id);
+    const hasInput = merged.input !== undefined && merged.input !== null;
+    const status = merged.status ?? null;
+    if (seen && seen.status === status && (seen.hasInput || !hasInput)) return;
+    const at = seen?.at ?? now();
+    this.#liveTools.set(id, { at, status, hasInput });
+    const terminal = status === 'completed' || status === 'failed';
+    // 真实 DSH 的 tool_call 不带 name，工具名在 title 里（"read" / "pwsh"）。title 是纯标识符时
+    // 当作名字写进 meta 级字段；带空格等可能含命令原文的 title 只进 detail。
+    const titleAsName =
+      typeof merged.title === 'string' && /^[\w.:-]{1,40}$/.test(merged.title) ? merged.title : null;
+    this.#live(
+      'tool',
+      {
+        tool_call_id: id,
+        name: merged.name ?? titleAsName,
+        kind: merged.kind ?? null,
+        status,
+        elapsed_ms: terminal ? now() - at : undefined,
+      },
+      { title: livePreview(merged.title, 200), input_preview: summarizeToolInput(merged.input) },
+    );
+    this.#liveUsageTick();
+  }
+
   async onPermissionRequest(params) {
     const options = params?.options ?? [];
     const rawToolCall = params?.toolCall ?? {};
@@ -605,11 +714,24 @@ export class Conversation {
     const desc = sanitizeApprovalContext(String(toolCall.title ?? toolCall.name ?? toolCall.toolCallId ?? '未知操作'));
     const allowId = pickOption(options, 'allow');
     const rejectId = pickOption(options, 'reject');
+    const liveApproval = (mode, extra = {}) => {
+      const input = toolCall.rawInput ?? toolCall.input ?? null;
+      const escalation =
+        input && typeof input === 'object' && typeof input.sandbox_permissions === 'string'
+          ? input.sandbox_permissions
+          : null;
+      this.#live(
+        'approval',
+        { tool_call_id: toolCall.toolCallId ?? null, tool: toolCall.name ?? null, mode, escalation, ...extra },
+        { title: livePreview(desc, 200), command_preview: summarizeToolInput(input) },
+      );
+    };
 
     // ★ read-only 是硬边界：即使会话被旧版本/显式参数配成 auto-allow，
     //   这里也绝不放行任何审批 —— DSH 会借审批把 sandbox 提权到可写。
     if (this.permission === 'read-only') {
       this.#hub.log.info(`[conv ${this.id}] read-only 强制拒绝审批: ${desc}`);
+      liveApproval('read-only-deny');
       return rejectId
         ? { outcome: { outcome: 'selected', optionId: rejectId } }
         : { outcome: { outcome: 'cancelled' } };
@@ -619,22 +741,26 @@ export class Conversation {
       // ★ 自动放行必须对调用方可见：DSH 会借审批把沙箱提升到 danger-full-access，
       //   不记下来的话 workspace-write 会话事后看起来像从未越界（实测一轮 6 次提权无人知晓）。
       if (allowId) this.#recordAutoApproval(params, toolCall, desc, options);
+      liveApproval('auto-allow');
       return allowId
         ? { outcome: { outcome: 'selected', optionId: allowId } }
         : { outcome: { outcome: 'cancelled' } };
     }
     if (this.onApproval === 'auto-deny') {
       this.#hub.log.info(`[conv ${this.id}] 审批拒绝: ${desc}`);
+      liveApproval('auto-deny');
       return rejectId
         ? { outcome: { outcome: 'selected', optionId: rejectId } }
         : { outcome: { outcome: 'cancelled' } };
     }
     const approvalId = `ap-${Math.random().toString(36).slice(2, 10)}`;
     this.#hub.log.info(`[conv ${this.id}] 审批待裁决: ${approvalId}`);
+    liveApproval('ask', { approval_id: approvalId });
     return await new Promise((resolve) => {
       const timer = setTimeout(() => {
         if (this.pendingApprovals.delete(approvalId)) {
           this.#hub.log.info(`[conv ${this.id}] 审批 ${approvalId} 超时，按拒绝处理`);
+          this.#liveApprovalDecided(approvalId, 'timeout', 'reject', 'cancelled');
           resolve({ outcome: { outcome: 'cancelled' } });
         }
       }, this.#hub.approvalTimeoutMs);
@@ -690,6 +816,7 @@ export class Conversation {
     //   否则 dsh_approval_decide 会渲染成"已裁决为 allow"，而 DSH 收到的是取消（假成功）。
     const effective = chosen ? 'selected' : 'cancelled';
     p.resolve(chosen ? { outcome: { outcome: 'selected', optionId: chosen } } : { outcome: { outcome: 'cancelled' } });
+    this.#liveApprovalDecided(approvalId, 'caller', decision, effective);
     return {
       approval_id: approvalId,
       decision,
@@ -719,6 +846,13 @@ export class Conversation {
     runRecord.status = 'error';
     runRecord.error = error?.message ?? String(error);
     runRecord.elapsed_ms = 0;
+    if (this.#liveUsage?.runId === runRecord.run_id) this.#liveUsage = null;
+    emitLive(
+      this.id,
+      'run.end',
+      { run: runRecord.run_id, turn: this.currentTurn, status: 'error', stop_reason: 'error' },
+      { error: livePreview(runRecord.error, 300) },
+    );
     runRecord.result = {
       conversation_id: this.id,
       run_id: runRecord.run_id,
@@ -789,7 +923,7 @@ export class Conversation {
    *
    * @returns 等到回合结束 → 完整 result；没等到（wait=false 或等超时）→ 收据对象
    */
-  async prompt(text, { reasoning = 'hide', timeoutMs = PROMPT_TIMEOUT_MS, run, wait = true, review } = {}) {
+  async prompt(text, { reasoning = 'hide', timeoutMs = PROMPT_TIMEOUT_MS, run, wait = true, review, via = 'send' } = {}) {
     if (this.busy) {
       throw new Error(
         `会话 ${this.id} 正在跑另一个回合。可以：dsh_interject 插话（打断并改口 / 排队），或 dsh_interrupt 打断。`,
@@ -835,6 +969,16 @@ export class Conversation {
     this.currentTool = null;
     this.pushOut('user', text.length > MAX_PROMPT_ECHO ? `${text.slice(0, MAX_PROMPT_ECHO)}…（已截断）` : text);
     this.pushOut('turn', `第 ${this.currentTurn} 轮开始`, { phase: 'start' });
+    this.#liveTools.clear();
+    // live 关闭时不读投影缓存（emitLive 会直接丢弃，读了也白读）。
+    this.#liveUsage = liveSettings().level === 'off'
+      ? null
+      : { runId: runRecord.run_id, turn: this.currentTurn, base: this.#readTokenUsage()?.totals ?? null, at: 0, last: '' };
+    this.#live(
+      'run.start',
+      { via, permission: this.permission, on_approval: this.onApproval, cwd: this.cwd },
+      { prompt_preview: livePreview(text, 200) },
+    );
     const c = {
       answer: '',
       /** 上一段正文之后出现过工具调用：下一段正文前要补段落分隔（见 onUpdate）。 */
@@ -900,10 +1044,11 @@ export class Conversation {
           this.currentTool = null;
           // 回合结束后，任何仍挂着的审批都已失效：统一取消并清空，避免状态里
           // 留下一个 dsh_approval_decide 只会回"没有待决审批"的幽灵。
-          for (const [, p] of this.pendingApprovals) {
+          for (const [apId, p] of this.pendingApprovals) {
             try {
               p.resolve({ outcome: { outcome: 'cancelled' } });
             } catch {}
+            this.#liveApprovalDecided(apId, 'turn_end', null, 'cancelled');
           }
           this.pendingApprovals.clear();
           this.pushOut('turn', `第 ${this.currentTurn} 轮结束（${stopReason ?? 'unknown'}）`, {
@@ -911,6 +1056,21 @@ export class Conversation {
             stop_reason: stopReason,
             error: failure ?? undefined,
           });
+          emitLive(
+            this.id,
+            'run.end',
+            {
+              run: runRecord.run_id,
+              turn: this.currentTurn,
+              status: failure ? 'error' : stopReason === 'cancelled' ? 'cancelled' : 'done',
+              stop_reason: stopReason ?? null,
+              duration_ms: now() - t0,
+              tool_count: c.tools.size,
+              auto_approvals: c.autoApprovalTotal,
+              auto_escalations: c.autoEscalationTotal,
+            },
+            { error: livePreview(failure, 300) },
+          );
           this.turnCount += 1;
           this.lastUsedAt = now();
           this.#hub.save();
@@ -921,6 +1081,12 @@ export class Conversation {
           this.#scheduleDrain();
           // 到这里才允许被 git 拖慢；结果/审核单/哨兵必须等快照完成后再落。
           const after = await afterPromise;
+          // 回合结束后 DSH 的 token 累计已经落盘（真机实测在哨兵之前）：发一次最终值。
+          // 只发给本回合自己的跟踪器——下一回合可能已经在 git 快照期间开始了。
+          if (this.#liveUsage?.runId === runRecord.run_id) {
+            this.#liveUsageTick({ force: true });
+            this.#liveUsage = null;
+          }
           const result = {
             conversation_id: this.id,
             run_id: runRecord.run_id,
@@ -1063,6 +1229,7 @@ export class Conversation {
   async interrupt() {
     if (!this.proc?.alive) return { interrupted: false, reason: 'DSH 进程未运行' };
     this.proc.notify('session/cancel', { sessionId: this.id });
+    this.#live('interrupt', { busy: this.busy });
     if (!this.busy) {
       return { interrupted: false, reason: '当前没有进行中的回合（已发送 cancel，用于清空排队输入）' };
     }
@@ -1206,6 +1373,12 @@ export class Conversation {
     const run = this.createRun(preview ?? text, { clientRunId, review });
     run.status = 'queued';
     this.queue.push({ run, text, reasoning, clientRunId, enqueued_at: now() });
+    emitLive(
+      this.id,
+      'run.queued',
+      { run: run.run_id, turn: this.currentTurn, position: this.queue.length, cwd: this.cwd },
+      { prompt_preview: livePreview(run.prompt_preview, 200) },
+    );
     return { run, position: this.queue.length, deduped: false };
   }
 
@@ -1250,6 +1423,7 @@ export class Conversation {
           permission: this.permission,
         });
       }
+      emitLive(this.id, 'run.end', { run: run.run_id, turn: this.currentTurn, status: 'cancelled', stop_reason: 'cancelled' });
       // 取消也是终态 → 写哨兵，避免等待方永远空等。
       const file = this.#hub.writeRunSentinel(this.id, run);
       run.result.sentinel_file = file ?? this.#hub.runSentinelPath(this.id, run.run_id);
@@ -1284,7 +1458,7 @@ export class Conversation {
       const item = this.queue.shift();
       const run = item.run;
       run.status = 'running';
-      this.prompt(item.text, { reasoning: item.reasoning, run, wait: false })
+      this.prompt(item.text, { reasoning: item.reasoning, run, wait: false, via: 'queue' })
         .catch(() => {})
         .finally(() => this.#scheduleDrain());
     }, 0);
@@ -1481,13 +1655,14 @@ export class Conversation {
     // 先建 run：幂等键要在"等待上一轮"之前就登记，否则重试会造出第二个 run。
     const run = this.createRun(message, { clientRunId, review });
     if (!this.busy) {
-      const r = await this.prompt(message, { reasoning, timeoutMs, run });
+      const r = await this.prompt(message, { reasoning, timeoutMs, run, via: 'interject' });
       return { ...r, interjected: 'idle', waited_ms: 0 };
     }
     const t0 = now();
     if (mode === 'interject') {
       this.proc?.notify('session/cancel', { sessionId: this.id });
     }
+    this.#live('interject', { mode, pending_run: run.run_id }, { text_preview: livePreview(message, 200) });
     // 排队等待的时长跟随调用方的 timeoutMs（0 = 一直等），不再固定 30 分钟。
     const idle = await this.waitIdle(timeoutMs);
     const waited = now() - t0;
@@ -1519,11 +1694,12 @@ export class Conversation {
           permission: this.permission,
         });
       }
+      emitLive(this.id, 'run.end', { run: run.run_id, turn: this.currentTurn, status: 'cancelled', stop_reason: 'cancelled' }, { error: livePreview(err.message, 300) });
       const file = this.#hub.writeRunSentinel?.(this.id, run);
       run.result.sentinel_file = file ?? this.#hub.runSentinelPath?.(this.id, run.run_id) ?? null;
       throw err;
     }
-    const r = await this.prompt(message, { reasoning, timeoutMs, run });
+    const r = await this.prompt(message, { reasoning, timeoutMs, run, via: mode === 'queue' ? 'queue' : 'interject' });
     return { ...r, interjected: mode, waited_ms: waited };
   }
 
@@ -1559,10 +1735,11 @@ export class Conversation {
       this.proc = null;
     }
     // 回合已经结束/进程正在关闭，任何仍挂着的审批都不再可裁决。
-    for (const [, p] of this.pendingApprovals) {
+    for (const [apId, p] of this.pendingApprovals) {
       try {
         p.resolve({ outcome: { outcome: 'cancelled' } });
       } catch {}
+      this.#liveApprovalDecided(apId, 'close', null, 'cancelled');
     }
     this.pendingApprovals.clear();
     // 只有确认进程退出后才删登记；否则把登记留着，让 takeover/classifyHolder
@@ -1579,7 +1756,12 @@ export class Conversation {
       // 而不是从 DSH 会话存储把它重建回来（否则 forget 形同虚设）。
       writeTombstone(this.id);
       this.#hub.remove(this.id);
-    } else this.#hub.save();
+      // forget 是"永久移除"：事件流也一并删掉，查看器里不再出现这个会话。
+      removeLive(this.id);
+    } else {
+      this.#hub.save();
+      this.#live('conv.close', { stopped });
+    }
     return { closed: stopped, forgotten: forget, ...(stopped ? {} : { error: '进程未能确认退出，登记已保留' }) };
   }
 }

package/src/hub.mjs

@@ -63,6 +63,7 @@ import { rssMb } from './procstat.mjs';
 import { readConversationMeta } from './titles.mjs';
 import { Conversation } from './conversation.mjs';
 import { pruneDirTree, sanitizeResultForSentinel } from './sentinel.mjs';
+import { emitLive, livePreview } from './live.mjs';
 import { homeWorkspaceProblem } from './workspace-guard.mjs';
 import { registerWorkspace, findSessionHeaderStatus } from './workspace.mjs';
 import {
@@ -579,6 +580,12 @@ export class Hub {
       }
       this.conversations.set(conv.id, conv);
       this.save();
+      emitLive(
+        conv.id,
+        'conv.open',
+        { cwd, permission, on_approval: conv.onApproval, model: conv.cfg?.model ?? null },
+        { title_hint: livePreview(conv.titleHint, 120) },
+      );
       this.log.info(
         `[hub] 新建会话 ${conv.id}（cwd=${cwd}, 权限=${permission}, 思考深度=${effort}` +
           `${conv.workspace?.registered ? ', 工作区已登记' : `, 工作区登记失败: ${conv.workspace?.error}`}）`,

package/src/live-cli.mjs

@@ -0,0 +1,142 @@
+/**
+ * `dsh-any-agent watch` / `dsh-any-agent dashboard` 两个子命令的入口。
+ *
+ * 两者都是**独立进程**、只读 live 事件流，与 MCP 服务进程无关：不碰写锁、不连 DSH、
+ * 不需要服务在跑（没有事件时就显示空）。
+ */
+
+import { LIVE_DIR, STATE_FILE } from './config.mjs';
+import { LiveTail, diffFrame, layoutFrame, renderText } from './live-view.mjs';
+import { readConversationMeta } from './titles.mjs';
+
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const [k, v] = a.slice(2).split('=', 2);
+      if (v !== undefined) flags[k] = v;
+      else if (args[i + 1] !== undefined && !args[i + 1].startsWith('--')) flags[k] = args[++i];
+      else flags[k] = true;
+    } else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+const intFlag = (v, d, min, max) => {
+  const n = Number.parseInt(v, 10);
+  return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : d;
+};
+
+export function makeTail(dir = LIVE_DIR) {
+  return new LiveTail(dir, {
+    stateFile: STATE_FILE,
+    readTitle: (id) => readConversationMeta(id)?.title ?? null,
+  });
+}
+
+export const WATCH_USAGE =
+  '用法: dsh-any-agent watch [会话id前缀] [--once] [--interval 毫秒] [--runs N] [--items N] [--no-color]\n';
+
+/** watch：终端里实时显示调用链（Ctrl+C 退出）。`--once` 打印一次就退出。 */
+export async function runWatch(args, { out = process.stdout } = {}) {
+  const { flags, positional } = parseFlags(args);
+  if (flags.help || flags.h) {
+    out.write(WATCH_USAGE);
+    return 0;
+  }
+  const tail = makeTail(typeof flags.dir === 'string' ? flags.dir : LIVE_DIR);
+  const opts = {
+    conv: positional[0] ?? null,
+    runs: intFlag(flags.runs, 3, 1, 30),
+    items: intFlag(flags.items, 12, 1, 300),
+    color: !flags['no-color'] && Boolean(out.isTTY),
+  };
+  tail.poll();
+  if (flags.once) {
+    out.write(renderText(tail.view(), opts) + '\n');
+    return 0;
+  }
+  const interval = intFlag(flags.interval, 500, 100, 10_000);
+  const tty = Boolean(out.isTTY);
+  const clock = () => new Date().toTimeString().slice(0, 8);
+  const frameText = () =>
+    renderText(tail.view(), opts) + `\n\n\x1b[2m更新于 ${clock()} · live 目录: ${tail.dir} · Ctrl+C 退出\x1b[0m`;
+
+  // ★ 在 TTY 上用"备用屏幕"原地刷新（同 top / htop）：每帧只重写变化的行。
+  //   旧实现每次 `ESC[2J` 清屏，Windows Terminal 会把被清掉的整屏推进回滚区，
+  //   往上一翻就是一摞重复的帧。备用屏幕没有回滚区，退出时原样恢复用户的终端。
+  let prev = null;
+  let lastText = '';
+  const draw = (force = false) => {
+    const text = frameText();
+    if (!tty) {
+      // 管道 / 重定向：没有光标控制，内容变了才追加一帧（去掉时间行再比较，免得每次都算变化）。
+      const body = text.slice(0, text.lastIndexOf('\n\n'));
+      if (body !== lastText) out.write(text.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '') + '\n\n');
+      lastText = body;
+      return;
+    }
+    const next = layoutFrame(text, { cols: out.columns ?? 120, rows: out.rows ?? 40 });
+    const seq = diffFrame(force ? null : prev, next);
+    if (seq) out.write(seq);
+    prev = next;
+  };
+  const restore = () => {
+    if (tty) out.write('\x1b[0m\x1b[?25h\x1b[?1049l');
+  };
+  if (tty) out.write('\x1b[?1049h\x1b[?25l');
+  process.once('exit', restore);
+  draw(true);
+  const onResize = () => draw(true);
+  if (tty) out.on?.('resize', onResize);
+  await new Promise((resolve) => {
+    const timer = setInterval(() => {
+      // 有新事件才重算；时间行每秒在变，所以每次都会写，但 diffFrame 只重写真正变了的那几行。
+      tail.poll();
+      draw();
+    }, interval);
+    const stop = () => {
+      clearInterval(timer);
+      resolve();
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+  });
+  out.off?.('resize', onResize);
+  restore();
+  process.off('exit', restore);
+  return 0;
+}
+
+export const DASHBOARD_USAGE = '用法: dsh-any-agent dashboard [--port 端口] [--interval 毫秒]\n';
+
+/** dashboard：起一个只读本地页面（127.0.0.1 + 一次性 token），Ctrl+C 退出。 */
+export async function runDashboard(args, { out = process.stdout } = {}) {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) {
+    out.write(DASHBOARD_USAGE);
+    return 0;
+  }
+  const { startDashboard } = await import('./live-dashboard.mjs');
+  const tail = makeTail(typeof flags.dir === 'string' ? flags.dir : LIVE_DIR);
+  const dash = await startDashboard({
+    tail,
+    port: intFlag(flags.port, 0, 0, 65535),
+    pollMs: intFlag(flags.interval, 500, 100, 10_000),
+  });
+  out.write(
+    `DSH live dashboard（只读）\n` +
+      `  打开: ${dash.url}\n` +
+      `  live 目录: ${tail.dir}\n` +
+      `  链接里带一次性 token，只在本机 127.0.0.1 可访问；Ctrl+C 退出。\n`,
+  );
+  await new Promise((resolve) => {
+    const stop = () => resolve();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+  });
+  await dash.close();
+  return 0;
+}