zen-gitsync 2.17.19 → 2.17.21

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, []);
+});

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

@@ -14,12 +14,17 @@
 //
 // 主 Agent 编排台的状态存储 + 活动流拼装。
 //
-// 三件事：
+// 四件事：
 //   1. 调度开关（active）+ 人类干预指令存档，持久化到 ~/.zen-gitsync/orchestrator.json。
 //      「暂停调度」是服务端强制的：暂停期间自动派发会被拒绝（手动点执行不受影响）。
 //   2. 派发默认提示词：一条全局的 + 每个项目一条的，同样存在 orchestrator.json。
 //      它们是「派发时自动附加的约束」，不是任务内容 —— 解析规则见 resolveDispatchPrompt。
-//   3. buildActivityFeed —— 把 job 的起止事实与人类指令合成一条时间倒序的活动流。
+//   3. 进度报告：自动报告的间隔配置存在 orchestrator.json（一个数字，跟着轮询下发），
+//      历史报告存在 orchestrator-reports.json（几 KB 一份，只在面板打开时按需取）。
+//      报告正文由 progressReport.js 生成，这里只负责"存哪、存几份、什么时候允许再生成"。
+//   4. buildActivityFeed —— 把 job 的起止事实与人类指令合成一条时间倒序的活动流。
+//      （控制台右栏的「活动日志」已换成进度报告，但这条流还在供顶栏「今日完成」计数，
+//      以及编排台接口的数据完整性 —— 别看到没人渲染就把它删了。）
 //
 // 活动流为什么不在服务端拼好文案：
 //   UI 文案统一走前端 i18n（lang/{zh,en}），服务端只回**结构化事实**
@@ -31,8 +36,12 @@
 
 import {
   ORCHESTRATOR_FILE,
+  ORCHESTRATOR_REPORTS_FILE,
   MAX_ORCHESTRATOR_INSTRUCTIONS,
   MAX_DEFAULT_PROMPT_CHARS,
+  MAX_PROGRESS_REPORTS,
+  PROGRESS_REPORT_INTERVALS_MS,
+  DEFAULT_PROGRESS_REPORT_INTERVAL_MS,
   readJson,
   writeJson,
   nowIso,
@@ -56,9 +65,20 @@ function defaultState() {
     instructions: [],
     defaultPrompt: '',
     projectPrompts: {},
+    reportIntervalMs: DEFAULT_PROGRESS_REPORT_INTERVAL_MS,
+    lastReportAt: null,
   };
 }
 
+/**
+ * 报告间隔归一。**只认白名单里的值**，其余（缺字段 / 脏值 / 手改文件写进去的 7 分钟）
+ * 一律回落到默认 10 分钟。老版本没有这个字段 —— 那正是"升级后按新默认开始报告"的语义。
+ */
+export function normalizeReportIntervalMs(value) {
+  const n = Number(value);
+  return PROGRESS_REPORT_INTERVALS_MS.includes(n) ? n : DEFAULT_PROGRESS_REPORT_INTERVAL_MS;
+}
+
 /** 单条指令归一：老数据/半损坏数据都要能渲染，不能让整份状态读不出来 */
 function normalizeInstruction(raw) {
   const it = raw && typeof raw === 'object' ? raw : {};
@@ -122,6 +142,8 @@ export function normalizeOrchestrator(raw) {
       ? state.defaultPrompt.slice(0, MAX_DEFAULT_PROMPT_CHARS)
       : '',
     projectPrompts: normalizeProjectPrompts(state.projectPrompts),
+    reportIntervalMs: normalizeReportIntervalMs(state.reportIntervalMs),
+    lastReportAt: typeof state.lastReportAt === 'string' ? state.lastReportAt : null,
   };
 }
 
@@ -258,6 +280,95 @@ export async function clearInstructions() {
   });
 }
 
+// ── 进度报告的配置与历史 ────────────────────────────────────────────────
+// 「报告时间我自己设置」的那个设置：0 = 关掉自动报告（手动「立即报告」始终可用，
+// 它不受这个开关影响 —— 关掉的是"自己隔一会儿跑一次"，不是"不许报告"）。
+
+/** 写自动报告间隔。返回写后的值（已归一） */
+export async function setReportIntervalMs(value) {
+  return serialize(async () => {
+    const state = await readOrchestrator();
+    state.reportIntervalMs = normalizeReportIntervalMs(value);
+    state.updatedAt = nowIso();
+    await persist(state);
+    return state.reportIntervalMs;
+  });
+}
+
+/**
+ * 抢占一次自动报告的"名额"：距上次报告不足 intervalMs 就返回 false。
+ *
+ * 为什么占坑要写盘而不是只放内存里一个时间戳：报告历史是**多实例共享**的
+ * （同一个 ~/.zen-gitsync 可能同时开着两个 g ui），各自跑一个定时器的话，
+ * 内存里各记各的，两边会在同一分钟各生成一份内容几乎一样的报告。
+ * 时间戳落在共享文件上，后到的那个实例读到的就是"刚报过"。
+ *
+ * 抢占发生在**生成之前**（生成要等一次模型往返，几秒到几十秒）：
+ * 等生成完再写，两个实例的窗口就大得多。代价是生成失败也要等满一个间隔才重试 ——
+ * 失败会记进报告历史（errorCode），比"同一分钟内连打两次模型"划算。
+ */
+export async function claimReportSlot(intervalMs, now = Date.now()) {
+  return serialize(async () => {
+    const state = await readOrchestrator();
+    const last = Date.parse(state.lastReportAt || '');
+    if (Number.isFinite(last) && now - last < intervalMs) return false;
+    state.lastReportAt = new Date(now).toISOString();
+    await persist(state);
+    return true;
+  });
+}
+
+/** 单份报告归一：字段缺失 / 脏数据都必须能渲染，不能让面板整个读不出来 */
+function normalizeReport(raw) {
+  const r = raw && typeof raw === 'object' ? raw : {};
+  const tasks = Array.isArray(r.tasks) ? r.tasks : [];
+  return {
+    id: typeof r.id === 'string' && r.id ? r.id : genId(),
+    at: typeof r.at === 'string' ? r.at : null,
+    trigger: r.trigger === 'auto' ? 'auto' : 'manual',
+    text: typeof r.text === 'string' ? r.text : '',
+    errorCode: typeof r.errorCode === 'string' ? r.errorCode : '',
+    errorDetail: typeof r.errorDetail === 'string' ? r.errorDetail : '',
+    tasks: tasks
+      .filter(t => t && typeof t === 'object')
+      .map(t => ({
+        taskId: typeof t.taskId === 'string' ? t.taskId : null,
+        taskTitle: typeof t.taskTitle === 'string' ? t.taskTitle : '',
+        projectName: typeof t.projectName === 'string' ? t.projectName : '',
+        startedAt: typeof t.startedAt === 'string' ? t.startedAt : null,
+        // 跑多久是**生成那一刻**的事实，跟着报告存下来：
+        // 前端拿现在的时钟去减 startedAt，"已运行 12 分钟"会随报告变旧一路涨，
+        // 历史报告就再也说不清"当时是什么情况"了。
+        elapsedMs: Number.isFinite(Number(t.elapsedMs)) ? Math.max(0, Math.floor(Number(t.elapsedMs))) : 0,
+        agent: typeof t.agent === 'string' ? t.agent : '',
+        toolCallCount: Number.isFinite(Number(t.toolCallCount)) ? Math.max(0, Math.floor(Number(t.toolCallCount))) : 0,
+        lastTool: typeof t.lastTool === 'string' ? t.lastTool : '',
+        lastLine: typeof t.lastLine === 'string' ? t.lastLine : '',
+      })),
+  };
+}
+
+/** 读报告历史（新的在前）。文件缺失 / 损坏一律当"还没有报告"，不抛错 */
+export async function readReports() {
+  const data = await readJson(ORCHESTRATOR_REPORTS_FILE, null);
+  const list = data && Array.isArray(data.reports) ? data.reports : [];
+  return list
+    .map(normalizeReport)
+    .sort((a, b) => String(b.at || '').localeCompare(String(a.at || '')))
+    .slice(0, MAX_PROGRESS_REPORTS);
+}
+
+/** 追加一份报告（新的在前），超出上限的旧报告直接丢掉 */
+export async function appendReport(entry) {
+  return serialize(async () => {
+    const report = normalizeReport({ id: genId(), at: nowIso(), ...entry });
+    const existing = await readReports();
+    const reports = [report, ...existing].slice(0, MAX_PROGRESS_REPORTS);
+    await writeJson(ORCHESTRATOR_REPORTS_FILE, { version: 1, reports });
+    return report;
+  });
+}
+
 /**
  * 正在执行的执行体清单（看板左栏「执行监控」用）。
  *