zen-gitsync 2.17.20 → 2.17.21

package/src/ui/server/routes/workbench/jobStore.test.js

@@ -60,15 +60,21 @@ after(async () => {
 });
 
 const modUrl = (rel) => pathToFileURL(path.join(projectRoot, rel)).href;
-const { DATA_DIR } = await import(modUrl('src/ui/server/routes/workbench/shared.js'));
+const { DATA_DIR, LIVE_JOBS_DIR } = await import(modUrl('src/ui/server/routes/workbench/shared.js'));
 const {
   jobs,
   snapshotJobs,
   mergedJobs,
   refreshJobsFromDisk,
   flushJobsSaveNow,
+  flushActiveJobsSave,
 } = await import(modUrl('src/ui/server/routes/workbench/jobStore.js'));
-const { deriveTaskColumn, groupJobsByTask } = await import(modUrl('src/ui/server/routes/workbench/projectRegistry.js'));
+const {
+  writeLiveJobsFile,
+  toLiveRecord,
+  liveJobsFilePath,
+} = await import(modUrl('src/ui/server/routes/workbench/liveJobs.js'));
+const { deriveTaskColumn, groupJobsByTask, decorateTaskForBoard } = await import(modUrl('src/ui/server/routes/workbench/projectRegistry.js'));
 
 const dataDir = path.join(fakeHome, '.zen-gitsync');
 const jobsFile = path.join(dataDir, 'jobs.json');
@@ -215,3 +221,134 @@ test('落盘不抹别人的记录:flush 必须并上磁盘上的历史 job 再
     jobs.delete('j-mine');
   }
 });
+
+// ── 运行中(live-jobs):别的实例正在跑的任务 ─────────────────────────
+// 2026-09-28:终态以前才是唯一落盘点,运行中的 job 只活在跑它的进程内存里 ——
+// 于是「已完成」两边一致,「进行中」只有跑的那个实例看得到。这一组钉住修复后的口径:
+// 内存 > live > 磁盘,且终态 flush 之后 live 文件必须立刻消失。
+
+/** 一个"别的实例正在跑"的 job。pid 用假值,只影响 taskRunner 那边,读者不看它。 */
+const liveJob = (id, taskId, extra = {}) => ({
+  id,
+  taskId,
+  subId: `${taskId}__simple`,
+  title: `job-${id}`,
+  status: 'running',
+  startedAt: '2026-09-28T14:56:51.650Z',
+  endedAt: null,
+  pid: 4242,
+  agent: 'claude',
+  prompt: 'p',
+  output: 'partial output',
+  thinking: '',
+  toolCalls: [],
+  claudeSessionId: null,
+  ...extra,
+});
+
+/** 每个用例从空的 live 目录 + 空的 jobs.json 开始,免得上一轮的 owner 文件串味 */
+async function resetStores() {
+  jobs.clear();
+  await fs.rm(LIVE_JOBS_DIR, { recursive: true, force: true });
+  await seedJobsFile([]);
+  await refreshJobsFromDisk({ force: true });
+}
+
+/**
+ * 写一份"别的实例"的 live 文件。ownerPid 用**本测试进程**的 pid:读者靠
+ * process.kill(pid, 0) 判存活,只有真实存在的 pid 才会被采信(见 liveJobs.js)。
+ */
+async function seedLiveFile(records, ownerPid = process.pid) {
+  await writeLiveJobsFile(ownerPid, records.map(r => toLiveRecord(r)));
+}
+
+test('另一个实例正在跑的任务:刷新后必须推导成「进行中」', async () => {
+  await resetStores();
+  await seedLiveFile([liveJob('j-run', 't1')]);
+  await refreshJobsFromDisk({ force: true });
+
+  const snap = snapshotJobs();
+  assert.ok(snap.some(j => j.id === 'j-run'), '运行中的记录必须出现在快照里');
+  assert.equal(snap.find(j => j.id === 'j-run').status, 'running');
+
+  const byTask = groupJobsByTask(snap);
+  // 修复前这里是 todo —— 运行中的 job 根本没落盘,jobs.json 里查不到
+  assert.equal(deriveTaskColumn(simpleTask('t1'), byTask.get('t1') || []), 'doing');
+  assert.equal(deriveTaskColumn(simpleTask('t2'), byTask.get('t2') || []), 'todo');
+  // 看板卡片上的"进行中"计数也来自同一份快照
+  assert.equal(decorateTaskForBoard(simpleTask('t1'), byTask.get('t1') || []).runningJobs, 1);
+});
+
+test('live 覆盖磁盘:同一条历史 + 新一轮正在跑,以「进行中」为准', async () => {
+  await resetStores();
+  await seedJobsFile([diskJob('j-run', 't1', 'done')]);
+  await seedLiveFile([liveJob('j-run', 't1')]);
+  await refreshJobsFromDisk({ force: true });
+
+  assert.equal(
+    mergedJobs().get('j-run').status,
+    'running',
+    '磁盘上那条是上一轮的终态,不能盖住"这一轮正在跑"'
+  );
+});
+
+test('内存 > live:本进程跑的 job 用内存里的那份(带流式输出),不用广播文件里截过的', async () => {
+  await resetStores();
+  await seedLiveFile([liveJob('j-run', 't1', { output: '截断过的尾巴' })]);
+  jobs.set('j-run', {
+    id: 'j-run',
+    taskId: 't1',
+    subId: '',
+    title: 'job-j-run',
+    status: 'running',
+    pid: process.pid,
+    output: '本进程完整的输出',
+  });
+  await refreshJobsFromDisk({ force: true });
+
+  assert.equal(mergedJobs().get('j-run').output, '本进程完整的输出');
+});
+
+test('owner 进程没了:它的运行中记录不再出现在快照里', async () => {
+  await resetStores();
+  // 2147483647 = 一定不存在的 pid
+  await seedLiveFile([liveJob('j-ghost', 't1')], 2147483647);
+  await refreshJobsFromDisk({ force: true });
+
+  assert.equal(snapshotJobs().some(j => j.id === 'j-ghost'), false);
+  assert.equal(deriveTaskColumn(simpleTask('t1'), []), 'todo');
+});
+
+test('终态收口:job 跑完后自己那份 live 文件必须消失,读者看到的是 done', async () => {
+  await resetStores();
+  jobs.set('j-run', {
+    id: 'j-run',
+    taskId: 't1',
+    subId: '',
+    title: 'job-j-run',
+    status: 'running',
+    startedAt: '2026-09-28T14:56:51.650Z',
+    pid: process.pid,
+    output: '跑着呢',
+  });
+
+  // 1) 运行中:文件里有它
+  await flushActiveJobsSave();
+  const raw = JSON.parse(await fs.readFile(liveJobsFilePath(process.pid), 'utf-8'));
+  assert.deepEqual(raw.jobs.map(j => j.id), ['j-run']);
+
+  // 2) 终态:flush 之后文件必须删掉(留一个空壳会让别的实例白扫,留着 running 会一直转圈)
+  jobs.get('j-run').status = 'done';
+  jobs.get('j-run').endedAt = '2026-09-28T15:00:00.000Z';
+  await flushJobsSaveNow();
+  await assert.rejects(
+    fs.stat(liveJobsFilePath(process.pid)),
+    (err) => err.code === 'ENOENT',
+    '没有活跃 job 了就不该再留 live 文件'
+  );
+
+  // 3) 别的实例这时候读到的是 jobs.json 里的终态
+  await refreshJobsFromDisk({ force: true });
+  assert.equal(snapshotJobs().find(j => j.id === 'j-run').status, 'done');
+  jobs.clear();
+});

package/src/ui/server/routes/workbench/liveJobs.js

@@ -0,0 +1,226 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// 「运行中」job 的跨实例可见性：每进程一个 ~/.zen-gitsync/live-jobs/<pid>.json。
+//
+// ── 要解决的问题（2026-09-28） ────────────────────────────────
+// 看板的「进行中」列由执行记录推导（projectRegistry.deriveTaskColumn），
+// 而执行记录只有**终态**才会落进 jobs.json（taskRunner 结束时才 flush）。
+// 于是同时开两个 g ui 时：
+//   · 已完成 / 已失败 —— 两边一致（终态在 jobs.json 里，谁都能读到）
+//   · 进行中 —— 只有**跑它的那个**实例显示"进行中"，其它实例的看板上那几条还挂在
+//     「待处理」。实测复现：A(4114) 正在跑的任务，B(5966) 的 /api/workbench/projects
+//     里该任务 column=todo、runningJobs=0，A 那边 column=doing、runningJobs=1。
+// 根因不是"没读"，而是"没写"：jobStore.js 里的 scheduleJobsSave() 是死代码，
+// 全仓没有任何调用点 —— 运行中的 job 从头到尾只活在跑它的那个进程内存里。
+// （同文件 index.js 的 cancel 路由早就写了"这个任务正在另一个 g ui 实例里执行"
+//   的友好提示，说明"跨实例可见"本来就是设计意图，只是写盘这一环断了。）
+//
+// ── 为什么是目录 + 每进程一个文件 ─────────────────────────────
+// 直接让每条 chunk 都去写 jobs.json 会把历史档案整份重写（本机 7.5MB / 48 条），
+// 1.5s 一次，还要连带跑一遍保留策略 —— 搬砖量全花在"同步一条状态"上，且阻塞
+// 事件循环反过来卡住流式输出。这里只写运行中那几条，几十 KB 封顶。
+// 目录形态则沿用 instances/ 的结论：各写各的文件，天然没有 read-modify-write
+// 丢更新，也不需要在 Windows 上做跨进程锁。
+//
+// ── 生命周期 ─────────────────────────────────────────────────
+//   写：job 转 running/pending 时、以及流式 chunk 到达时，1.5s 防抖写一次
+//   删：本进程再没有 running/pending 的 job 时（终态 flush 会立刻走一次）
+//   读：遍历目录，**跳过 owner 进程已消失的文件**（顺手删掉，自愈），
+//       坏文件跳过不抛（与 instanceRegistry 同口径）
+// 所以进程被 kill -9 也不会留下幽灵"进行中"：下次别人读的时候 owner pid 已经不在了。
+//
+// 重要口径：**本进程内存里的 job 永远优先**（见 jobStore.mergedJobs）。这里的
+// output/thinking/toolCalls 是**截尾**的（远端只看个大概，不需要搬全文），
+// 本进程自己看的始终是内存里那份完整的。
+
+import fsp from 'fs/promises';
+import path from 'path';
+import { logger, LIVE_JOBS_DIR } from './shared.js';
+
+/** 远端可见的输出尾巴长度。整份日志动辄几十万字符，跨实例只需要"跑到哪了" */
+export const LIVE_OUTPUT_TAIL_CHARS = 32 * 1024;
+export const LIVE_THINKING_TAIL_CHARS = 8 * 1024;
+/** 工具调用只留最近若干条；单条字段再做一次截断 */
+export const LIVE_TOOL_CALL_LIMIT = 20;
+export const LIVE_TOOL_CALL_FIELD_CHARS = 2 * 1024;
+/**
+ * owner 进程还活着、但文件太久没更新时不再采信。
+ * 触发条件很苛刻（只有 pid 被复用才会出现），作用是给"幽灵进行中"一个硬上限，
+ * 而不是给正常任务设超时 —— 模型闷头想 20 分钟不吐一个 chunk 是正常的。
+ */
+export const LIVE_MAX_AGE_MS = 60 * 60 * 1000;
+
+/** 信号 0 探测存活。任何报错都当"进程不在了"——与 jobStore/taskRunner 同一口径 */
+function defaultIsProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch { return false; }
+}
+
+/**
+ * job → 可序列化投影。**全仓唯一一份**：SSE 快照（jobStore.snapshotJobs）与
+ * live-jobs 落盘都用它 —— 两处各写一份字段清单时，加一个字段漏掉一处不会报错，
+ * 只会让"本实例看得到、别的实例看不到"。
+ *
+ * 白名单投影：未登记字段静默剥掉（child 是 ChildProcess，不可序列化，必须剥）。
+ */
+export function projectJob(j) {
+  return {
+    id: j.id,
+    taskId: j.taskId,
+    subId: j.subId,
+    title: j.title,
+    status: j.status,
+    prompt: j.prompt || '',
+    output: j.output || '',
+    thinking: j.thinking || '',
+    pid: j.pid || null,
+    startedAt: j.startedAt || null,
+    endedAt: j.endedAt || null,
+    exitCode: typeof j.exitCode === 'number' ? j.exitCode : null,
+    error: j.error || null,
+    // 本轮用的执行器（claude | opencode）。前端对话区助手名 / 日志详情按它显示。
+    agent: j.agent || null,
+    // 工具调用流水（{id,name,argsPreview,arguments,result,status,error}[]）。
+    // 前端靠它画工具块;刷新页面 / 换实例后仍然可见,所以必须过白名单。
+    toolCalls: Array.isArray(j.toolCalls) ? j.toolCalls : [],
+    // 续接对话用:claude --output-format stream-json 的 system.init 事件捕获到的 session_id
+    claudeSessionId: j.claudeSessionId || null
+  };
+}
+
+/** 取尾部 N 个字符（截断方向与 taskRunner 的 MAX_OUTPUT 尾部保底一致） */
+function tail(text, max) {
+  const s = typeof text === 'string' ? text : '';
+  return s.length > max ? s.slice(-max) : s;
+}
+
+/** 落盘前的瘦身：正文/思考/工具流水截尾，其余字段原样 */
+export function toLiveRecord(job) {
+  const rec = projectJob(job);
+  rec.output = tail(rec.output, LIVE_OUTPUT_TAIL_CHARS);
+  rec.thinking = tail(rec.thinking, LIVE_THINKING_TAIL_CHARS);
+  rec.toolCalls = rec.toolCalls.slice(-LIVE_TOOL_CALL_LIMIT).map((c) => ({
+    id: c && c.id,
+    name: c && c.name,
+    argsPreview: tail(c && c.argsPreview, LIVE_TOOL_CALL_FIELD_CHARS),
+    arguments: tail(c && c.arguments, LIVE_TOOL_CALL_FIELD_CHARS),
+    result: tail(c && c.result, LIVE_TOOL_CALL_FIELD_CHARS),
+    status: c && c.status,
+    error: (c && c.error) || null
+  }));
+  return rec;
+}
+
+export function liveJobsFilePath(ownerPid) {
+  return path.join(LIVE_JOBS_DIR, `${ownerPid}.json`);
+}
+
+/** 写自己的那份。records 为空 = 本进程没有运行中的 job，直接删文件 */
+export async function writeLiveJobsFile(ownerPid, records) {
+  if (!Number.isInteger(ownerPid) || ownerPid <= 0) throw new Error('writeLiveJobsFile: ownerPid 非法');
+  const list = Array.isArray(records) ? records : [];
+  if (list.length === 0) return removeLiveJobsFile(ownerPid);
+  await fsp.mkdir(LIVE_JOBS_DIR, { recursive: true });
+  const file = liveJobsFilePath(ownerPid);
+  const tmp = `${file}.tmp`;
+  // 原子写：tmp + rename（与 readJson/writeJson 同口径）。tmp 文件名带 pid 后缀
+  // 天然不撞车，读者按 /^\d+\.json$/ 过滤也就不会读到半截文件。
+  await fsp.writeFile(tmp, JSON.stringify({
+    version: 1,
+    ownerPid,
+    updatedAt: Date.now(),
+    jobs: list
+  }), 'utf-8');
+  await fsp.rename(tmp, file);
+}
+
+/** 删自己的那份。失败只记 warn —— 读者那边还有"owner pid 已死就跳过"兜底 */
+export async function removeLiveJobsFile(ownerPid) {
+  try {
+    await fsp.unlink(liveJobsFilePath(ownerPid));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return;
+    logger.warn(`[workbench] 清理 live-jobs/${ownerPid}.json 失败: ${err?.message || err}`);
+  }
+}
+
+// entry 文件名匹配：<pid>.json（pid 是正整数）。跳过 .tmp 等写入中间态
+function isEntryFileName(name) {
+  return typeof name === 'string' && /^\d+\.json$/.test(name);
+}
+
+/**
+ * 扫描目录，返回所有**别的实例**正在跑的 job。
+ *
+ * 返回 `signature` 是为了让调用方（jobStore）能像 jobs.json 那样用
+ * mtime+size 做短路：看板 5s 轮询一次，目录没变化就不该真去 parse。
+ *
+ * @returns {Promise<{ signature: string, jobs: object[] }>}
+ */
+export async function scanLiveJobsDir({ isProcessAlive = defaultIsProcessAlive, now = Date.now() } = {}) {
+  let names;
+  try {
+    names = await fsp.readdir(LIVE_JOBS_DIR);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { signature: '', jobs: [] };
+    throw err;
+  }
+
+  const files = [];
+  for (const name of names) {
+    if (!isEntryFileName(name)) continue;
+    const fp = path.join(LIVE_JOBS_DIR, name);
+    try {
+      const st = await fsp.stat(fp);
+      files.push({ name, fp, size: st.size, mtimeMs: st.mtimeMs });
+    } catch { /* 刚被删掉，跳过 */ }
+  }
+  files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const signature = files.map(f => `${f.name}:${f.mtimeMs}:${f.size}`).join('|');
+
+  const jobs = [];
+  for (const f of files) {
+    const ownerPid = Number(f.name.slice(0, -'.json'.length));
+    // owner 不在了 —— 它跑到一半的 job 永远不会再有下文（连终态都没落进 jobs.json），
+    // 顺手把文件删掉自愈，别让别的实例的看板永远挂着"进行中"。
+    if (!isProcessAlive(ownerPid)) {
+      await removeLiveJobsFile(ownerPid);
+      continue;
+    }
+    let data;
+    try {
+      data = JSON.parse(await fsp.readFile(f.fp, 'utf-8'));
+    } catch (err) {
+      logger.warn(`[workbench] live-jobs/${f.name} 读取失败，跳过: ${err?.message || err}`);
+      continue;
+    }
+    if (!data || data.ownerPid !== ownerPid || !Array.isArray(data.jobs)) continue;
+    if (now - Number(data.updatedAt || 0) > LIVE_MAX_AGE_MS) continue;
+    for (const j of data.jobs) {
+      if (j && j.id) jobs.push(j);
+    }
+  }
+  return { signature, jobs };
+}
+
+export const liveJobs = {
+  projectJob,
+  toLiveRecord,
+  writeLiveJobsFile,
+  removeLiveJobsFile,
+  scanLiveJobsDir,
+  liveJobsFilePath,
+};

package/src/ui/server/routes/workbench/liveJobs.test.js

@@ -0,0 +1,215 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+// 「运行中 job 的跨实例广播」(live-jobs/<pid>.json) 的回归测试(2026-09-28)。
+//
+// 背景:jobStore 里的 scheduleJobsSave() 一直是死代码,运行中的 job 从头到尾只活在
+// 跑它的那个进程内存里 —— 于是同机开两个 g ui 时,「已完成」两边一致,「进行中」
+// 只有跑的那个实例看得到。修法见 liveJobs.js 文件头。本文件钉住它的四条口径:
+//   1. 写进去的活跃记录,别的实例扫得到
+//   2. owner 进程没了 → 跳过并自愈删文件(不留幽灵「进行中」)
+//   3. 没有活跃 job → 文件直接删掉(不能留个空壳让读者白扫)
+//   4. 正文/思考/工具流水**截尾**,别让一份跑了几小时的任务把广播文件撑成 MB 级
+//
+// 隔离策略与 jobStore.test.js 一致:在 import 之前把 USERPROFILE/HOME 指向 mkdtemp。
+
+import { test, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, '../../../../..');
+
+// ---- 环境隔离:必须在 import liveJobs.js 之前完成 ----
+
+const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'zgs-livejobs-test-'));
+const savedEnv = {
+  USERPROFILE: process.env.USERPROFILE,
+  HOME: process.env.HOME,
+  HOMEDRIVE: process.env.HOMEDRIVE,
+  HOMEPATH: process.env.HOMEPATH,
+};
+process.env.USERPROFILE = fakeHome;
+process.env.HOME = fakeHome;
+delete process.env.HOMEDRIVE;
+delete process.env.HOMEPATH;
+
+after(async () => {
+  for (const [k, v] of Object.entries(savedEnv)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  try { await fs.rm(fakeHome, { recursive: true, force: true }) } catch { /* 清理失败不影响结论 */ }
+});
+
+const modUrl = (rel) => pathToFileURL(path.join(projectRoot, rel)).href;
+const {
+  LIVE_JOBS_DIR,
+} = await import(modUrl('src/ui/server/routes/workbench/shared.js'));
+const {
+  projectJob,
+  toLiveRecord,
+  writeLiveJobsFile,
+  removeLiveJobsFile,
+  scanLiveJobsDir,
+  liveJobsFilePath,
+  LIVE_OUTPUT_TAIL_CHARS,
+  LIVE_THINKING_TAIL_CHARS,
+  LIVE_TOOL_CALL_LIMIT,
+} = await import(modUrl('src/ui/server/routes/workbench/liveJobs.js'));
+
+/** 一个"正在跑"的 job。字段照 taskRunner 里那个对象形状给。 */
+const runningJob = (id, extra = {}) => ({
+  id,
+  taskId: 't1',
+  subId: 't1__simple',
+  title: `job-${id}`,
+  status: 'running',
+  pid: 4242,
+  startedAt: '2026-09-28T14:56:51.650Z',
+  endedAt: null,
+  agent: 'claude',
+  prompt: 'p',
+  output: 'out',
+  thinking: 'think',
+  toolCalls: [],
+  claudeSessionId: null,
+  // 不该被广播出去的内部字段（白名单投影必须剥掉）
+  child: { pid: 4242 },
+  ...extra,
+});
+
+// 每个用例从干净的目录开始：上一轮的 owner 文件会让 scan 结果不可预期
+beforeEach(async () => {
+  await fs.rm(LIVE_JOBS_DIR, { recursive: true, force: true });
+});
+
+// ── 沙箱自检 ────────────────────────────────────────────────────────
+test('沙箱:live-jobs 目录落在 mkdtemp 里,不是用户真实 home', () => {
+  assert.ok(LIVE_JOBS_DIR.startsWith(fakeHome), `LIVE_JOBS_DIR 应落在沙箱内,实际: ${LIVE_JOBS_DIR}`);
+});
+
+// ── 投影 ────────────────────────────────────────────────────────────
+test('projectJob:白名单投影剥掉 child 等不可序列化字段,保留前端要的字段', () => {
+  const rec = projectJob(runningJob('j1'));
+  assert.equal(rec.id, 'j1');
+  assert.equal(rec.status, 'running');
+  assert.equal(rec.agent, 'claude');
+  assert.equal(rec.claudeSessionId, null);
+  assert.deepEqual(rec.toolCalls, []);
+  assert.ok(!('child' in rec), 'child 必须先剥掉,否则 JSON.stringify 直接抛');
+  // 投影结果要能真的序列化
+  assert.doesNotThrow(() => JSON.stringify(rec));
+});
+
+test('toLiveRecord:正文/思考截尾,工具流水只留最近若干条', () => {
+  const toolCalls = Array.from({ length: LIVE_TOOL_CALL_LIMIT + 5 }, (_, i) => ({
+    id: `c${i}`,
+    name: 'Bash',
+    argsPreview: 'a'.repeat(10),
+    arguments: 'b'.repeat(5000),
+    result: 'r'.repeat(5000),
+    status: 'completed',
+    error: null,
+  }));
+  const rec = toLiveRecord(runningJob('j2', {
+    output: 'o'.repeat(LIVE_OUTPUT_TAIL_CHARS + 1000) + 'TAIL',
+    thinking: 't'.repeat(LIVE_THINKING_TAIL_CHARS + 500),
+    toolCalls,
+  }));
+  assert.equal(rec.output.length, LIVE_OUTPUT_TAIL_CHARS);
+  assert.ok(rec.output.endsWith('TAIL'), '截的必须是尾巴(最新的那段)');
+  assert.equal(rec.thinking.length, LIVE_THINKING_TAIL_CHARS);
+  assert.equal(rec.toolCalls.length, LIVE_TOOL_CALL_LIMIT);
+  // 留下的是最近的:最后一条 id 应等于原数组最后一条
+  assert.equal(rec.toolCalls.at(-1).id, `c${LIVE_TOOL_CALL_LIMIT + 4}`);
+  assert.ok(rec.toolCalls[0].arguments.length <= 2 * 1024);
+  assert.ok(rec.toolCalls[0].result.length <= 2 * 1024);
+});
+
+// ── 写 / 读 ─────────────────────────────────────────────────────────
+test('写进去的活跃记录:别的实例扫得到,且字段完整', async () => {
+  await writeLiveJobsFile(4242, [toLiveRecord(runningJob('j-live'))]);
+  const { signature, jobs: found } = await scanLiveJobsDir({ isProcessAlive: () => true });
+  assert.ok(signature.length > 0, 'signature 非空才能让读者用 mtime+size 短路');
+  assert.equal(found.length, 1);
+  assert.equal(found[0].id, 'j-live');
+  assert.equal(found[0].status, 'running');
+  assert.equal(found[0].taskId, 't1');
+  assert.ok(!('child' in found[0]));
+});
+
+test('owner 进程已消失:跳过该文件并顺手删掉(不留幽灵「进行中」)', async () => {
+  // 2147483647 是不存在的 pid(沿用 jobStore.test.js 的取法),这条分支不依赖机器状态
+  await writeLiveJobsFile(2147483647, [toLiveRecord(runningJob('j-ghost'))]);
+  const { jobs: found } = await scanLiveJobsDir();
+  assert.equal(found.length, 0);
+  await assert.rejects(
+    fs.stat(liveJobsFilePath(2147483647)),
+    (err) => err.code === 'ENOENT',
+    'owner 死了的文件应当被自愈删除'
+  );
+});
+
+test('没有活跃 job:写空数组 = 直接删文件,不留空壳', async () => {
+  await writeLiveJobsFile(4242, [toLiveRecord(runningJob('j-live'))]);
+  await writeLiveJobsFile(4242, []);
+  await assert.rejects(fs.stat(liveJobsFilePath(4242)), (err) => err.code === 'ENOENT');
+  const { signature, jobs: found } = await scanLiveJobsDir({ isProcessAlive: () => true });
+  assert.equal(found.length, 0);
+  assert.equal(signature, '');
+});
+
+test('removeLiveJobsFile 幂等:文件不在也不抛', async () => {
+  await removeLiveJobsFile(999999);
+  await removeLiveJobsFile(999999);
+});
+
+test('目录里的垃圾文件(写中间的 .tmp / 非 pid 名)不参与扫描', async () => {
+  await writeLiveJobsFile(4242, [toLiveRecord(runningJob('j-live'))]);
+  await fs.writeFile(path.join(LIVE_JOBS_DIR, '4242.json.tmp'), '{ 半截', 'utf-8');
+  await fs.writeFile(path.join(LIVE_JOBS_DIR, 'notes.txt'), 'x', 'utf-8');
+  await fs.writeFile(path.join(LIVE_JOBS_DIR, '.migrated'), 'x', 'utf-8');
+  const { jobs: found } = await scanLiveJobsDir({ isProcessAlive: () => true });
+  assert.deepEqual(found.map(j => j.id), ['j-live']);
+});
+
+test('损坏的 JSON 文件只跳过,不把整次扫描搞崩', async () => {
+  await writeLiveJobsFile(4242, [toLiveRecord(runningJob('j-ok'))]);
+  await fs.mkdir(LIVE_JOBS_DIR, { recursive: true });
+  await fs.writeFile(path.join(LIVE_JOBS_DIR, '7777.json'), 'not json at all', 'utf-8');
+  const { jobs: found } = await scanLiveJobsDir({ isProcessAlive: () => true });
+  assert.deepEqual(found.map(j => j.id), ['j-ok']);
+});
+
+test('ownerPid 与文件名对不上(被谁改过)的记录不采信', async () => {
+  await fs.mkdir(LIVE_JOBS_DIR, { recursive: true });
+  await fs.writeFile(
+    path.join(LIVE_JOBS_DIR, '4242.json'),
+    JSON.stringify({ version: 1, ownerPid: 1, updatedAt: Date.now(), jobs: [runningJob('j-x')] }),
+    'utf-8'
+  );
+  const { jobs: found } = await scanLiveJobsDir({ isProcessAlive: () => true });
+  assert.equal(found.length, 0);
+});
+
+test('目录不存在时扫描返回空,不抛', async () => {
+  const { signature, jobs: found } = await scanLiveJobsDir();
+  assert.equal(signature, '');
+  assert.deepEqual(found, []);
+});