cc-viewer 1.6.302 → 1.6.304

package/server/lib/workflow-journal.js

@@ -0,0 +1,155 @@
+/**
+ * Workflow Journal
+ *
+ * 定位 + 读取 + 归一化 Claude Code 的 workflow run journal：
+ *   <projectsDir>/<encoded-cwd>/<sessionId>/workflows/<runId>.json
+ *
+ * journal 运行中被整体覆写，含 workflowName / summary / status / phases[] /
+ * workflowProgress[](workflow_phase | workflow_agent) / totalTokens / totalToolCalls。
+ * 这里把它压成前端工作流面板要用的精简模型（normalizeWorkflowJournal）。
+ *
+ * 安全：runId 受 RUN_ID_RE 限制（无路径分隔符）；session 子目录由 findTranscriptPath
+ * 解析（恒在 projectsDir 内）；读盘前 realpath 复核仍落在 projectsDir 内，防穿越。
+ */
+
+import { existsSync, readFileSync, statSync, realpathSync, readdirSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { getClaudeConfigDir } from '../../findcc.js';
+import { findTranscriptPath } from './session-transcript-reader.js';
+
+const RUN_ID_RE = /^wf_[A-Za-z0-9_-]+$/;
+const TASK_ID_RE = /^[A-Za-z0-9_-]+$/;
+const MAX_JOURNAL_BYTES = 16 * 1024 * 1024;  // journal 通常 ~100KB，16MB 兜底防异常大文件
+
+function projectsDir() {
+  return process.env.CCV_PROJECTS_DIR || join(getClaudeConfigDir(), 'projects');
+}
+
+/**
+ * sessionId(+projectHint) → 该 session 的 workflows 目录绝对路径（可能不存在）。
+ * @returns {string | null}
+ */
+export function resolveWorkflowsDir(sessionId, projectHint) {
+  if (!sessionId) return null;
+  const transcript = findTranscriptPath(sessionId, projectHint);
+  if (!transcript) return null;
+  return join(dirname(transcript), sessionId, 'workflows');
+}
+
+function isInsideProjectsDir(realPath) {
+  let root;
+  try { root = realpathSync(projectsDir()); } catch { return false; }
+  return realPath === root || realPath.startsWith(root + sep);
+}
+
+/**
+ * 解析 journal 文件绝对路径。
+ * - runId：直接 <wfDir>/<runId>.json。
+ * - 否则 taskId：扫 wfDir 找 .taskId 匹配的 wf_*.json。
+ * @returns {string | null}
+ */
+export function resolveJournalPath({ sessionId, projectHint, runId, taskId }) {
+  const wfDir = resolveWorkflowsDir(sessionId, projectHint);
+  if (!wfDir) return null;
+
+  if (runId && RUN_ID_RE.test(runId)) {
+    const p = join(wfDir, `${runId}.json`);
+    if (!existsSync(p)) return null;
+    let real;
+    try { real = realpathSync(p); } catch { return null; }
+    return isInsideProjectsDir(real) ? real : null;
+  }
+
+  if (taskId && TASK_ID_RE.test(taskId)) {
+    let files;
+    try { files = readdirSync(wfDir); } catch { return null; }
+    for (const f of files) {
+      if (!f.startsWith('wf_') || !f.endsWith('.json')) continue;
+      const p = join(wfDir, f);
+      try {
+        if (statSync(p).size > MAX_JOURNAL_BYTES) continue;
+        const j = JSON.parse(readFileSync(p, 'utf-8'));
+        if (j && j.taskId === taskId) {
+          const real = realpathSync(p);
+          return isInsideProjectsDir(real) ? real : null;
+        }
+      } catch { /* 跳过坏文件 */ }
+    }
+  }
+  return null;
+}
+
+/**
+ * 把 journal 原始对象压成前端面板模型。坏输入返回 null。
+ */
+export function normalizeWorkflowJournal(j) {
+  if (!j || typeof j !== 'object') return null;
+
+  const phases = Array.isArray(j.phases)
+    ? j.phases.map((p, i) => ({
+        index: i + 1,
+        title: typeof p?.title === 'string' ? p.title : '',
+        detail: typeof p?.detail === 'string' ? p.detail : '',
+      }))
+    : [];
+
+  const agents = Array.isArray(j.workflowProgress)
+    ? j.workflowProgress
+        .filter(p => p && p.type === 'workflow_agent')
+        .map(a => ({
+          index: typeof a.index === 'number' ? a.index : null,
+          label: typeof a.label === 'string' ? a.label : '',
+          phaseIndex: typeof a.phaseIndex === 'number' ? a.phaseIndex : null,
+          phaseTitle: typeof a.phaseTitle === 'string' ? a.phaseTitle : '',
+          agentId: typeof a.agentId === 'string' ? a.agentId : '',
+          agentType: typeof a.agentType === 'string' ? a.agentType : '',
+          model: typeof a.model === 'string' ? a.model : '',
+          state: typeof a.state === 'string' ? a.state : '',
+          tokens: typeof a.tokens === 'number' ? a.tokens : 0,
+          toolCalls: typeof a.toolCalls === 'number' ? a.toolCalls : 0,
+          durationMs: typeof a.durationMs === 'number' ? a.durationMs : null,
+          lastToolName: typeof a.lastToolName === 'string' ? a.lastToolName : '',
+          lastToolSummary: typeof a.lastToolSummary === 'string' ? a.lastToolSummary : '',
+          promptPreview: typeof a.promptPreview === 'string' ? a.promptPreview : '',
+          resultPreview: typeof a.resultPreview === 'string' ? a.resultPreview : '',
+          startedAt: typeof a.startedAt === 'number' ? a.startedAt : null,
+          lastProgressAt: typeof a.lastProgressAt === 'number' ? a.lastProgressAt : null,
+        }))
+    : [];
+
+  return {
+    runId: typeof j.runId === 'string' ? j.runId : '',
+    taskId: typeof j.taskId === 'string' ? j.taskId : '',
+    workflowName: typeof j.workflowName === 'string' ? j.workflowName : '',
+    summary: typeof j.summary === 'string' ? j.summary : '',
+    status: typeof j.status === 'string' ? j.status : '',
+    durationMs: typeof j.durationMs === 'number' ? j.durationMs : null,
+    agentCount: typeof j.agentCount === 'number' ? j.agentCount : agents.length,
+    totalTokens: typeof j.totalTokens === 'number' ? j.totalTokens : 0,
+    totalToolCalls: typeof j.totalToolCalls === 'number' ? j.totalToolCalls : 0,
+    defaultModel: typeof j.defaultModel === 'string' ? j.defaultModel : '',
+    startTime: typeof j.startTime === 'number' ? j.startTime : null,
+    phases,
+    agents,
+    // 权威完成快照显式标记 live:false（与 deriveLiveJournal 的 live:true 对称）：
+    // 让前端「乱序到达的 live REST 不得覆盖已完成快照」的判断可靠，且 workflowStore
+    // 据此把该 run 移出活跃集合。
+    live: false,
+  };
+}
+
+/**
+ * 读 + 归一化一个 journal 文件路径。坏/超限返回 null。
+ */
+export function readNormalizedJournal(journalPath) {
+  try {
+    if (!journalPath || !existsSync(journalPath)) return null;
+    if (statSync(journalPath).size > MAX_JOURNAL_BYTES) return null;
+    const j = JSON.parse(readFileSync(journalPath, 'utf-8'));
+    return normalizeWorkflowJournal(j);
+  } catch {
+    return null;
+  }
+}
+
+export const _RUN_ID_RE = RUN_ID_RE;

package/server/lib/workflow-live.js

@@ -0,0 +1,255 @@
+/**
+ * Workflow Live (运行中逐帧)
+ *
+ * workflow run journal（<sessionDir>/workflows/<runId>.json）只在「完成时」一次性落盘，
+ * 运行中拿不到。但运行中以下文件在持续增长，可据此实时推导面板：
+ *   <sessionDir>/subagents/workflows/<runId>/
+ *     ├─ agent-<id>.jsonl        子代理转写（持续增长）→ token / 工具数 / model / prompt
+ *     ├─ agent-<id>.meta.json    {"agentType":...}
+ *     └─ journal.jsonl           started / result 事件（带 agentId）→ running / done 判定
+ *
+ * 推导出的模型与 normalizeWorkflowJournal 同形（phases 为空 → 前端走扁平 agent 列表），
+ * 完成后由权威的 <runId>.json 快照接管（phase 分组）。
+ *
+ * token 口径：input + output + cache_creation（运行中单调增；与完成快照略有出入，完成时被
+ * 权威值替换）。工具数与快照一致（统计 tool_use 块）。
+ */
+
+import { existsSync, readFileSync, statSync, readdirSync, realpathSync, openSync, readSync, closeSync } from 'node:fs';
+import { join, dirname, sep } from 'node:path';
+import { getClaudeConfigDir } from '../../findcc.js';
+import { findTranscriptPath } from './session-transcript-reader.js';
+import { _RUN_ID_RE as RUN_ID_RE } from './workflow-journal.js';
+
+const MAX_AGENT_BYTES = 64 * 1024 * 1024;
+const LABEL_MAX = 80;
+const PROMPT_PREVIEW_MAX = 600;  // 头部菱形 hover 预览的 prompt 截断长度（与 journal promptPreview 量级一致）
+
+function projectsDir() {
+  return process.env.CCV_PROJECTS_DIR || join(getClaudeConfigDir(), 'projects');
+}
+
+/** sessionId(+hint) → <sessionDir>/subagents/workflows/<runId>（可能不存在）。 */
+export function resolveRunDir(sessionId, projectHint, runId) {
+  if (!sessionId || !runId) return null;
+  // 与完成态 journal 同一 runId 校验：拒绝含路径分隔符/`..` 的 runId，防穿越到其他 run/session 目录。
+  if (!RUN_ID_RE.test(runId)) return null;
+  const transcript = findTranscriptPath(sessionId, projectHint);
+  if (!transcript) return null;
+  return join(dirname(transcript), sessionId, 'subagents', 'workflows', runId);
+}
+
+function isInsideProjectsDir(realPath) {
+  let root;
+  try { root = realpathSync(projectsDir()); } catch { return false; }
+  return realPath === root || realPath.startsWith(root + sep);
+}
+
+/** 从 workflows/scripts/<name>-<runId>.js 反推 workflowName（运行中即可拿到）。 */
+function deriveWorkflowName(sessionDir, runId) {
+  try {
+    const scriptsDir = join(sessionDir, 'workflows', 'scripts');
+    for (const f of readdirSync(scriptsDir)) {
+      if (f.endsWith(`-${runId}.js`)) return f.slice(0, -(`-${runId}.js`.length));
+    }
+  } catch {}
+  return '';
+}
+
+// 每文件增量解析缓存：filePath → { mtimeMs, size, offset, partial(Buffer), acc }。
+// agent-*.jsonl 是 append-only：仅从上次 offset 续读新增字节、按行喂入累加器 acc，
+// 避免每帧对正在增长的活跃 agent 文件做 O(size) 全量重读（partial 以字节保留，
+// 跨读边界的不完整行/多字节 UTF-8 字符不被切坏，只在换行符处解码）。
+const _agentParseCache = new Map();
+
+function _newAcc() {
+  return { tokens: 0, toolCalls: 0, lastToolName: '', model: '', prompt: '', startedAt: null, lastProgressAt: null };
+}
+
+function _accSnapshot(acc) {
+  return {
+    tokens: acc.tokens, toolCalls: acc.toolCalls, lastToolName: acc.lastToolName,
+    model: acc.model, prompt: acc.prompt, startedAt: acc.startedAt, lastProgressAt: acc.lastProgressAt,
+  };
+}
+
+function _applyLine(acc, line) {
+  if (!line) return;
+  let o;
+  try { o = JSON.parse(line); } catch { return; }
+  const ts = Date.parse(o.timestamp || '');
+  if (!Number.isNaN(ts)) {
+    if (acc.startedAt === null) acc.startedAt = ts;
+    acc.lastProgressAt = ts;
+  }
+  const msg = o.message;
+  if (!msg) return;
+  if (o.type === 'user' && !acc.prompt && typeof msg.content === 'string') acc.prompt = msg.content;
+  if (typeof msg.model === 'string' && msg.model) acc.model = msg.model;
+  const u = msg.usage;
+  if (u) acc.tokens += (u.input_tokens || 0) + (u.output_tokens || 0) + (u.cache_creation_input_tokens || 0);
+  if (Array.isArray(msg.content)) {
+    for (const b of msg.content) {
+      if (b && b.type === 'tool_use') { acc.toolCalls++; if (b.name) acc.lastToolName = b.name; }
+    }
+  }
+}
+
+function parseAgentFile(filePath) {
+  let st;
+  try { st = statSync(filePath); } catch { return null; }
+  const { mtimeMs, size } = st;
+
+  const cached = _agentParseCache.get(filePath);
+  if (cached && cached.mtimeMs === mtimeMs && cached.size === size) {
+    return _accSnapshot(cached.acc);   // 未变 → 直接返回快照，不读盘
+  }
+  if (size > MAX_AGENT_BYTES) return _newAcc();
+
+  // 可续读：缓存存在且文件未被截断/轮转（size 未回退到 offset 之前）→ 从 offset 增量读；否则从头读。
+  let acc, offset, partial;
+  if (cached && cached.acc && size >= cached.offset) {
+    acc = cached.acc; offset = cached.offset; partial = cached.partial || Buffer.alloc(0);
+  } else {
+    acc = _newAcc(); offset = 0; partial = Buffer.alloc(0);
+  }
+
+  let chunk = Buffer.alloc(0);
+  try {
+    if (size > offset) {
+      const fd = openSync(filePath, 'r');
+      try {
+        const len = size - offset;
+        const buf = Buffer.allocUnsafe(len);
+        let read = 0;
+        while (read < len) {
+          const n = readSync(fd, buf, read, len - read, offset + read);
+          if (n <= 0) break;
+          read += n;
+        }
+        chunk = buf.subarray(0, read);
+        offset += read;
+      } finally { closeSync(fd); }
+    }
+  } catch {
+    return _accSnapshot(acc);   // 读失败 → 返回已累计，不更新缓存（下次重试）
+  }
+
+  // 只解码到「最后一个换行符」为止；其后不完整行以字节留到下次（避免切坏多字节字符）。
+  const combined = chunk.length ? Buffer.concat([partial, chunk]) : partial;
+  const lastNL = combined.lastIndexOf(0x0A);
+  let newPartial;
+  if (lastNL === -1) {
+    newPartial = combined;
+  } else {
+    const complete = combined.subarray(0, lastNL).toString('utf-8');
+    for (const line of complete.split('\n')) _applyLine(acc, line);
+    newPartial = combined.subarray(lastNL + 1);
+  }
+
+  _agentParseCache.set(filePath, { mtimeMs, size, offset, partial: newPartial, acc });
+  return _accSnapshot(acc);
+}
+
+function readResumeJournal(runDir) {
+  const started = new Set();
+  const done = new Set();
+  try {
+    const lines = readFileSync(join(runDir, 'journal.jsonl'), 'utf-8').split('\n');
+    for (const line of lines) {
+      if (!line) continue;
+      let o;
+      try { o = JSON.parse(line); } catch { continue; }
+      if (!o.agentId) continue;
+      if (o.type === 'started') started.add(o.agentId);
+      else if (o.type === 'result') done.add(o.agentId);
+    }
+  } catch {}
+  return { started, done };
+}
+
+function labelFromPrompt(prompt, agentType) {
+  if (prompt) {
+    const firstLine = prompt.split('\n').map(s => s.trim()).find(Boolean) || '';
+    if (firstLine) return firstLine.length > LABEL_MAX ? firstLine.slice(0, LABEL_MAX) + '…' : firstLine;
+  }
+  return agentType || '';
+}
+
+/**
+ * 从 runDir 实时推导面板模型（与 normalizeWorkflowJournal 同形，phases 为空）。
+ * 无 agent 文件 → null。
+ */
+export function deriveLiveJournal(runDir, runId) {
+  if (!runDir || !existsSync(runDir)) return null;
+  let real;
+  try { real = realpathSync(runDir); } catch { return null; }
+  if (!isInsideProjectsDir(real)) return null;
+
+  let files;
+  try { files = readdirSync(runDir); } catch { return null; }
+  const agentFiles = files.filter(f => f.startsWith('agent-') && f.endsWith('.jsonl'));
+  if (agentFiles.length === 0) return null;
+
+  const { done } = readResumeJournal(runDir);
+  // sessionDir = runDir 上溯三级（runId → workflows → subagents → sessionDir）
+  const sessionDir = dirname(dirname(dirname(runDir)));
+  const workflowName = deriveWorkflowName(sessionDir, runId);
+
+  const agents = [];
+  let totalTokens = 0, totalToolCalls = 0;
+  for (const f of agentFiles) {
+    const agentId = f.slice('agent-'.length, -'.jsonl'.length);
+    const parsed = parseAgentFile(join(runDir, f));
+    if (!parsed) continue;
+    let agentType = '';
+    try { agentType = JSON.parse(readFileSync(join(runDir, `agent-${agentId}.meta.json`), 'utf-8')).agentType || ''; } catch {}
+    // agent 文件存在即已启动（排队中尚无文件），故非 done 一律 running
+    const state = done.has(agentId) ? 'done' : 'running';
+    totalTokens += parsed.tokens;
+    totalToolCalls += parsed.toolCalls;
+    agents.push({
+      index: null,
+      label: labelFromPrompt(parsed.prompt, agentType),
+      phaseIndex: null,
+      phaseTitle: '',
+      agentId,
+      agentType,
+      model: parsed.model,
+      state,
+      tokens: parsed.tokens,
+      toolCalls: parsed.toolCalls,
+      durationMs: (parsed.startedAt && parsed.lastProgressAt) ? (parsed.lastProgressAt - parsed.startedAt) : null,
+      lastToolName: parsed.lastToolName,
+      lastToolSummary: '',
+      // 头部菱形 hover 用：实时态取首条 user prompt 截断；尾部 resultPreview 待完成快照(journal)补。
+      promptPreview: parsed.prompt
+        ? (parsed.prompt.length > PROMPT_PREVIEW_MAX ? parsed.prompt.slice(0, PROMPT_PREVIEW_MAX) + '…' : parsed.prompt)
+        : '',
+      resultPreview: '',
+      startedAt: parsed.startedAt,
+      lastProgressAt: parsed.lastProgressAt,
+    });
+  }
+
+  agents.sort((a, b) => (a.startedAt || 0) - (b.startedAt || 0));
+  const allDone = agents.length > 0 && agents.every(a => a.state === 'done');
+  const startTime = agents.reduce((min, a) => (a.startedAt && (min === null || a.startedAt < min)) ? a.startedAt : min, null);
+
+  return {
+    runId: runId || '',
+    taskId: '',
+    workflowName,
+    summary: '',
+    status: allDone ? 'finishing' : 'running',
+    durationMs: null,
+    agentCount: agents.length,
+    totalTokens,
+    totalToolCalls,
+    defaultModel: '',
+    startTime,
+    phases: [],
+    agents,
+    live: true,
+  };
+}

package/server/lib/workflow-watcher.js

@@ -0,0 +1,280 @@
+/**
+ * Workflow Watcher
+ *
+ * 监视某 session 的 workflows 目录（<sessionDir>/workflows/），journal 文件被整体覆写
+ * 时读全文件 → normalizeWorkflowJournal → 经 SSE 广播 `workflow_update` 事件，让前端
+ * 工作流面板实时跟随。
+ *
+ * 设计：
+ * - 复用 log-watcher 的 dir fs.watch + 防抖 + 安全网慢轮询模式；fs.watch 不可用/漏事件时
+ *   由 SAFETY_POLL_MS 兜底。
+ * - 惰性 arm：前端首次拉 journal（REST）时按 session 武装；同目录只 arm 一次（刷新 clients
+ *   引用）。arm 时把现存 journal 记入 seen 基线（不广播，初值由 REST 返回），之后仅广播签名
+ *   变化的文件，避免历史 journal 在 arm 瞬间洪泛。
+ * - 测试缝：__setWatchImplForTests 注入假 fs.watch；__triggerScanForTests 手动触发扫描，
+ *   规避真实 fs.watch/轮询时序在 CI 上的不确定性（仿 log-watcher.__setWatchFileImplForTests）。
+ */
+
+import { existsSync, watch, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { sendEventToClients } from './log-watcher.js';
+import { readNormalizedJournal } from './workflow-journal.js';
+import { deriveLiveJournal } from './workflow-live.js';
+
+const DEBOUNCE_MS = 120;
+const SAFETY_POLL_MS = 5000;
+const PRESENCE_POLL_MS = 1000;
+
+const _armed = new Map();      // workflowsDir → state（完成快照）
+const _armedLive = new Map();  // runDir → state（运行中逐帧）
+
+let _watchImpl = watch;
+/** 测试用：替换 fs.watch 实现。生产恒为 node:fs watch。 */
+export function __setWatchImplForTests(fn) { _watchImpl = fn || watch; }
+
+function _signature(p) {
+  try { const st = statSync(p); return `${st.mtimeMs}:${st.size}`; } catch { return null; }
+}
+
+function _isJournalFile(f) { return f.startsWith('wf_') && f.endsWith('.json'); }
+
+function _scan(state) {
+  const { workflowsDir, sessionId, project, clients, seen } = state;
+  let files;
+  try { files = readdirSync(workflowsDir); } catch { return; }
+  for (const f of files) {
+    if (!_isJournalFile(f)) continue;
+    const p = join(workflowsDir, f);
+    const sig = _signature(p);
+    if (!sig) continue;
+    if (seen.get(f) === sig) continue;  // 未变
+    seen.set(f, sig);
+    const data = readNormalizedJournal(p);
+    if (!data) continue;
+    sendEventToClients(clients, 'workflow_update', {
+      sessionId,
+      project: project || null,
+      runId: data.runId,
+      taskId: data.taskId,
+      data,
+    });
+  }
+}
+
+function _scheduleScan(state) {
+  if (state.debounceTimer) return;
+  state.debounceTimer = setTimeout(() => {
+    state.debounceTimer = null;
+    _scan(state);
+  }, DEBOUNCE_MS);
+  state.debounceTimer.unref?.();
+}
+
+function _startWatch(state) {
+  if (state.watcher || !existsSync(state.workflowsDir)) return false;
+  try {
+    state.watcher = _watchImpl(state.workflowsDir, () => _scheduleScan(state));
+    state.watcher?.on?.('error', () => {
+      try { state.watcher?.close?.(); } catch {}
+      state.watcher = null;
+    });
+    return true;
+  } catch {
+    state.watcher = null;
+    return false;
+  }
+}
+
+function _baseline(state) {
+  try {
+    for (const f of readdirSync(state.workflowsDir)) {
+      if (!_isJournalFile(f)) continue;
+      const sig = _signature(join(state.workflowsDir, f));
+      if (sig) state.seen.set(f, sig);
+    }
+  } catch {}
+}
+
+/**
+ * 武装对某 workflows 目录的监视。同目录重复调用只刷新 clients 引用。
+ * @param {{ workflowsDir: string, sessionId?: string, project?: string, clients: Array }} opts
+ */
+export function armWorkflowWatch({ workflowsDir, sessionId, project, clients } = {}) {
+  if (!workflowsDir || !Array.isArray(clients)) return null;
+
+  const existing = _armed.get(workflowsDir);
+  if (existing) { existing.clients = clients; return existing; }
+
+  const state = {
+    workflowsDir, sessionId, project, clients,
+    seen: new Map(), watcher: null,
+    debounceTimer: null, safetyTimer: null, presenceTimer: null,
+  };
+  _armed.set(workflowsDir, state);
+
+  _baseline(state);  // 现存 journal 记入基线，不广播（初值走 REST）
+
+  if (!_startWatch(state)) {
+    // 目录尚不存在：轮询等它出现再 watch
+    state.presenceTimer = setInterval(() => {
+      if (_startWatch(state)) {
+        clearInterval(state.presenceTimer);
+        state.presenceTimer = null;
+        _scheduleScan(state);
+      }
+    }, PRESENCE_POLL_MS);
+    state.presenceTimer.unref?.();
+  }
+
+  // 安全网慢轮询，兜 fs.watch 漏事件
+  state.safetyTimer = setInterval(() => _scan(state), SAFETY_POLL_MS);
+  state.safetyTimer.unref?.();
+
+  return state;
+}
+
+/** 测试用：手动触发一次扫描（绕过防抖/真实 fs 事件时序）。 */
+export function __triggerScanForTests(workflowsDir) {
+  const state = _armed.get(workflowsDir);
+  if (state) _scan(state);
+}
+
+function _disposeState(state) {
+  if (!state) return;
+  if (state.debounceTimer) clearTimeout(state.debounceTimer);
+  if (state.safetyTimer) clearInterval(state.safetyTimer);
+  if (state.presenceTimer) clearInterval(state.presenceTimer);
+  try { state.watcher?.close?.(); } catch {}
+}
+
+/** 解除单个目录监视。 */
+export function unwatchWorkflowDir(workflowsDir) {
+  const state = _armed.get(workflowsDir);
+  if (!state) return;
+  _disposeState(state);
+  _armed.delete(workflowsDir);
+}
+
+/** 解除单个完成快照目录的监视别名 + 运行中目录监视，详见各自实现。 */
+
+// --- 运行中逐帧（watch <sessionDir>/subagents/workflows/<runId>/）---
+
+function _liveSignature(data) {
+  if (!data) return 'none';
+  const states = data.agents.map(a => `${a.agentId}:${a.state}:${a.tokens}:${a.toolCalls}`).join('|');
+  return `${data.status}#${data.agentCount}#${data.totalTokens}#${data.totalToolCalls}#${states}`;
+}
+
+// runDir = <sessionDir>/subagents/workflows/<runId> → 上溯三级到 sessionDir，查权威快照是否已落盘
+function _authoritativeJournalExists(runDir, runId) {
+  try {
+    const sessionDir = dirname(dirname(dirname(runDir)));
+    return existsSync(join(sessionDir, 'workflows', `${runId}.json`));
+  } catch { return false; }
+}
+
+function _scanLive(state) {
+  const { runDir, runId, sessionId, project, clients } = state;
+  const data = deriveLiveJournal(runDir, runId);
+  if (data) {
+    const sig = _liveSignature(data);
+    if (sig !== state.lastSig) {  // 有实质变化才广播
+      state.lastSig = sig;
+      sendEventToClients(clients, 'workflow_update', {
+        sessionId,
+        project: project || null,
+        runId: data.runId,
+        taskId: data.taskId || null,
+        data,
+      });
+    }
+  }
+  // 权威完成快照已落盘 → 逐帧使命结束，自我拆除（最终态由 workflows 目录 watch 接管广播，
+  // 且 workflowStore 权威锁会忽略其后乱序的 live 帧）。避免完成后 safetyTimer 永久空转重读。
+  if (_authoritativeJournalExists(runDir, runId)) {
+    unwatchWorkflowLive(runDir);
+  }
+}
+
+function _scheduleLiveScan(state) {
+  if (state.debounceTimer) return;
+  state.debounceTimer = setTimeout(() => {
+    state.debounceTimer = null;
+    _scanLive(state);
+  }, DEBOUNCE_MS);
+  state.debounceTimer.unref?.();
+}
+
+function _startLiveWatch(state) {
+  if (state.watcher || !existsSync(state.runDir)) return false;
+  try {
+    state.watcher = _watchImpl(state.runDir, () => _scheduleLiveScan(state));
+    state.watcher?.on?.('error', () => {
+      try { state.watcher?.close?.(); } catch {}
+      state.watcher = null;
+    });
+    return true;
+  } catch {
+    state.watcher = null;
+    return false;
+  }
+}
+
+/**
+ * 武装对某运行中 workflow 的逐帧监视（subagents/workflows/<runId> 目录）。
+ * 同 runDir 重复调用只刷新 clients。arm 时立即广播一次当前推导态（闭合 REST/arm 竞态）。
+ * @param {{ runDir: string, runId: string, sessionId?: string, project?: string, clients: Array }} opts
+ */
+export function armWorkflowLiveWatch({ runDir, runId, sessionId, project, clients } = {}) {
+  if (!runDir || !runId || !Array.isArray(clients)) return null;
+
+  const existing = _armedLive.get(runDir);
+  if (existing) { existing.clients = clients; return existing; }
+
+  const state = {
+    runDir, runId, sessionId, project, clients,
+    lastSig: null, watcher: null,
+    debounceTimer: null, safetyTimer: null, presenceTimer: null,
+  };
+  _armedLive.set(runDir, state);
+
+  if (!_startLiveWatch(state)) {
+    state.presenceTimer = setInterval(() => {
+      if (_startLiveWatch(state)) {
+        clearInterval(state.presenceTimer);
+        state.presenceTimer = null;
+        _scheduleLiveScan(state);
+      }
+    }, PRESENCE_POLL_MS);
+    state.presenceTimer.unref?.();
+  } else {
+    _scheduleLiveScan(state);
+  }
+
+  state.safetyTimer = setInterval(() => _scanLive(state), SAFETY_POLL_MS);
+  state.safetyTimer.unref?.();
+
+  return state;
+}
+
+/** 测试用：手动触发一次逐帧扫描。 */
+export function __triggerLiveScanForTests(runDir) {
+  const state = _armedLive.get(runDir);
+  if (state) _scanLive(state);
+}
+
+/** 解除单个运行中目录监视。 */
+export function unwatchWorkflowLive(runDir) {
+  const state = _armedLive.get(runDir);
+  if (!state) return;
+  _disposeState(state);
+  _armedLive.delete(runDir);
+}
+
+/** 解除所有 workflow 监视（workspace 切换/进程退出）。 */
+export function unwatchAllWorkflows() {
+  for (const state of _armed.values()) _disposeState(state);
+  _armed.clear();
+  for (const state of _armedLive.values()) _disposeState(state);
+  _armedLive.clear();
+}