zen-gitsync 2.17.31 → 2.17.33

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

@@ -47,6 +47,17 @@
 //     界面不画那条进度条：宁可什么都不画，也不画一条我们自己编出来的进度。
 //   · 解析fail-safe：认不出来的标记行**留在正文里**（不吞内容），只把真认下来的那两行
 //     从正文里摘掉。老模型 / 不听话的模型不过是少一条进度条，报告本身照常。
+//
+// 2026-09-30 晚修的「有时候生成失败」（用户报的，历史里三条连着空报告）：
+//   · 失败形态：errorCode=LLM_FAILED、errorDetail **空**、text 空 —— 界面上只有一句
+//     "生成失败，只记录了任务事实"，盘上查不出任何原因。
+//   · 根因：`max_tokens` 是**思考 + 正文共用**的，而 900 的预算被推理模型的思考写满了。
+//     用本机默认模型（deepseek-v4.1-flash）复现：同样一份 prompt，一轮思考 2708 字符、
+//     content 0 字节，HTTP 却是 200 —— 前端看到的"有时候"，就是模型这次想得多不多。
+//   · 三处改动：预算 900 → 3000（正文只要 200~400，其余是思考的余量）；
+//     被截断且正文为空时**加预算重试一次**（第二种预算见 MAX_REPORT_TOKENS_RETRY）；
+//     两轮都空记成 `LLM_EMPTY`，并把 finish_reason / token 用量写进 errorDetail，
+//     下次不用再翻网关日志。
 
 import { callLlmStream } from './llmClient.js';
 import { createThinkFilter } from '../../../../cli/ai/streamFilter.js';
@@ -68,8 +79,23 @@ export const MAX_FACT_TASKS = 8;
 const MAX_TITLE_CHARS = 140;
 const MAX_REPORT_CHARS = 2000;
 const MAX_ERROR_CHARS = 300;
-/** 一次汇报只有几句话，给足余量（部分模型会把预算用在 thinking 上） */
-const MAX_REPORT_TOKENS = 900;
+/**
+ * 生成预算。**注意这是"思考 + 正文"共用的**：推理模型（本机默认的
+ * deepseek-v4.1-flash 就是）在写正文之前会先想一遍，思考的 token 也从这里扣。
+ *
+ * 2026-09-30 从 900 提到 3000：900 的时候观察到的失败形态是**思考把预算写满、
+ * 正文一个字都没有**，HTTP 200、`finish_reason='length'`、content 空 —— 界面上
+ * 就是"生成失败，只记录了任务事实"（那三条失败报告全是这个，见下面的重试）。
+ * 正文本身只要 200~400（220 字的汇报），剩下的全是留给思考的余量。
+ */
+export const MAX_REPORT_TOKENS = 3000;
+
+/**
+ * 还是被截断时的重试预算。只在"第一次被截断且正文为空"时用一次 ——
+ * 思考的长度跟任务数量、日志长度一起涨，3000 也不是保险箱（实测 4 个任务时
+ * 思考已到 2708 字符），而重试的代价只是一次已经失败掉的调用。
+ */
+export const MAX_REPORT_TOKENS_RETRY = 8000;
 /** 生成超时。它跑在服务端后台，卡住不返回会一直占着"正在生成"这个位子 */
 const REPORT_TIMEOUT_MS = 90000;
 
@@ -104,6 +130,12 @@ export function buildRunningFacts({ jobs = [], tasks = [], now = Date.now() } =
     const started = Date.parse(job.startedAt || '');
     out.push({
       taskId: job.taskId || null,
+      /**
+       * 这条事实对应哪次执行。报告本身用不到（一张卡片一条事实），
+       * 但静默看门狗要拿着判定结果**回到那条 job 上改状态** ——
+       * 同一个任务可能有好几条 job（重跑 / 并行子任务），按 taskId 改会改错人。
+       */
+      jobId: job.id || null,
       taskTitle: String((task && task.title) || '').slice(0, MAX_TITLE_CHARS),
       projectName: projectName(projectPath),
       startedAt: job.startedAt || null,
@@ -358,6 +390,30 @@ Then write **one English progress report**:
 5. Output only the report itself`;
 }
 
+/**
+ * 一次调用的元信息摘要 → 写进 errorDetail（界面上悬停可见的那个 tooltip）。
+ *
+ * 为什么值得单独写一行：界面上"生成失败"三个字背后是几种完全不同的处理办法，
+ * 而它们在盘上的记录里**长得一模一样**。2026-09-30 那三条失败报告就是
+ * `errorCode=LLM_FAILED` + `errorDetail=''` + `text=''`，光看 orchestrator-reports.json
+ * 什么都查不出来（得去翻网关日志才知道是被 max_tokens 截断）。
+ * 摘要里放 finish_reason 与 token 用量，下次一眼能分清"被预算截断"和"网关没回话"。
+ *
+ * 认不出来的字段一律不写（老网关不给 usage），整串截到 MAX_ERROR_CHARS。
+ */
+export function describeCallResult(res, maxTokens) {
+  const r = res && typeof res === 'object' ? res : {};
+  const parts = [`max_tokens=${Number(maxTokens) || 0}`];
+  parts.push(`finish_reason=${r.finishReason || 'unknown'}`);
+  const u = r.usage && typeof r.usage === 'object' ? r.usage : null;
+  if (u && u.completion_tokens != null) parts.push(`completion_tokens=${u.completion_tokens}`);
+  // reasoning_tokens 是"预算里有多少花在思考上"的唯一直接证据
+  const detail = u && u.completion_tokens_details;
+  if (detail && detail.reasoning_tokens != null) parts.push(`reasoning_tokens=${detail.reasoning_tokens}`);
+  if (r.aborted) parts.push('aborted');
+  return parts.join(' ').slice(0, MAX_ERROR_CHARS);
+}
+
 /**
  * 生成一份进度报告。**不落盘**（落盘由 orchestratorStore.appendReport 负责），
  * 返回的就是要存的那个记录。
@@ -365,6 +421,7 @@ Then write **one English progress report**:
  * 三种"没有正文"的情况都记成一条**带事实的报告**而不是抛错，理由是一样：
  * 面板上"有 2 个任务在跑，但没配模型"远比一个空白面板有用，
  * 而且失败会留在历史里 —— 用户能看出"是模型挂了"而不是"这个功能没做"。
+ * （第四种，"模型答了但没写正文"，记成 LLM_EMPTY —— 成因与处理办法都不同。）
  *
  * @param {object}   input
  * @param {object[]} input.facts        buildRunningFacts 的输出
@@ -403,58 +460,92 @@ export async function generateProgressReport({
 
   const zh = !String(locale || '').startsWith('en');
   const prompt = buildReportPrompt(facts, locale);
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), REPORT_TIMEOUT_MS);
-
-  // 部分模型把推理也塞进 content（与 recentDirectoriesAiSummary 同一处理）：
-  // 汇报里混进一段思考过程，用户会以为那是结论。
-  const filter = createThinkFilter();
-  let text = '';
-  const forward = (segments) => {
-    for (const seg of segments) if (seg.content) text += seg.content;
-  };
 
-  try {
-    const { aborted } = await callStream(
-      model,
-      prompt,
-      (delta) => { if (delta.content) forward(filter.feed(delta.content)); },
-      {
-        maxTokens: MAX_REPORT_TOKENS,
-        systemPrompt: zh ? SYSTEM_PROMPT_ZH : SYSTEM_PROMPT_EN,
-        signal: controller.signal,
-      }
-    );
-    forward(filter.flush());
-    if (aborted) return { ...base, errorCode: 'LLM_TIMEOUT' };
-  } catch (err) {
-    return {
-      ...base,
-      errorCode: 'LLM_FAILED',
-      errorDetail: String((err && err.message) || err).slice(0, MAX_ERROR_CHARS),
+  /**
+   * 跑一次模型。每次调用**自带** AbortController 与过滤器：重试必须是干净的一次，
+   * 上一轮的超时定时器和半截 think 状态都不能带过来。
+   * 部分模型把推理也塞进 content（与 recentDirectoriesAiSummary 同一处理）：
+   * 汇报里混进一段思考过程，用户会以为那是结论。
+   */
+  async function attempt(maxTokens) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REPORT_TIMEOUT_MS);
+    const filter = createThinkFilter();
+    let raw = '';
+    const forward = (segments) => {
+      for (const seg of segments) if (seg.content) raw += seg.content;
     };
-  } finally {
-    clearTimeout(timer);
+    try {
+      const res = await callStream(
+        model,
+        prompt,
+        (delta) => { if (delta.content) forward(filter.feed(delta.content)); },
+        {
+          maxTokens,
+          systemPrompt: zh ? SYSTEM_PROMPT_ZH : SYSTEM_PROMPT_EN,
+          signal: controller.signal,
+        }
+      );
+      forward(filter.flush());
+      return {
+        raw,
+        aborted: !!(res && res.aborted),
+        // 老签名（单测注入的假流）没有这两个字段 —— 拿不到就当"不知道"，
+        // 后果是退化成"不重试"，不是重试到天荒地老
+        finishReason: String((res && res.finishReason) || ''),
+        meta: describeCallResult(res, maxTokens),
+      };
+    } finally {
+      clearTimeout(timer);
+    }
   }
 
-  // 先摘掉头部那两行（PROGRESS / TASKS），剩下的才是给用户看的正文。
-  // 顺序不能反：先截断再解析，免得 2000 字的正文把标记行挤出去（标记总在最前面，
-  // 截断其实伤不到它，但"先解析"这件事本身更经得起以后改格式）
-  const parsed = parseProgressHeader(text.trim().slice(0, MAX_REPORT_CHARS));
-  const out = parsed.text;
-  // 空正文按失败记：界面上一张"什么都没有"的报告卡片和"模型没返回内容"是两回事
-  if (!out) return { ...base, errorCode: 'LLM_FAILED' };
-  return {
-    ...base,
-    text: out,
-    percent: parsed.percent,
-    // 每个任务各自的百分比挂在事实快照上：报告卡片里那一行行事实本来就在，
-    // 挂上去才不会"整体 62%，但看不出是哪两个任务拖的"
-    tasks: facts.map((f, i) => ({
-      ...f,
-      percent: i < parsed.taskPercents.length ? parsed.taskPercents[i] : null,
-    })),
-  };
+  // 两轮：常规预算 → （只有**被截断且正文为空**才）加预算重试一次。
+  // 中途任何一次拿到正文就返回；一次都没拿到正文时，第二轮的元信息更值得留档
+  // （它才带着"两次都空"这个事实）。
+  let meta = '';
+  for (let round = 0; round < 2; round++) {
+    const budget = round === 0 ? MAX_REPORT_TOKENS : MAX_REPORT_TOKENS_RETRY;
+    let res;
+    try {
+      res = await attempt(budget);
+    } catch (err) {
+      return {
+        ...base,
+        errorCode: 'LLM_FAILED',
+        errorDetail: String((err && err.message) || err).slice(0, MAX_ERROR_CHARS),
+      };
+    }
+    // 超时不重试：90 秒没回来，再来一次大概率还是 90 秒
+    if (res.aborted) return { ...base, errorCode: 'LLM_TIMEOUT', errorDetail: res.meta };
+    meta = res.meta;
+
+    // 先摘掉头部那两行（PROGRESS / TASKS），剩下的才是给用户看的正文。
+    // 顺序不能反：先截断再解析，免得 2000 字的正文把标记行挤出去（标记总在最前面，
+    // 截断其实伤不到它，但"先解析"这件事本身更经得起以后改格式）
+    const parsed = parseProgressHeader(res.raw.trim().slice(0, MAX_REPORT_CHARS));
+    if (parsed.text) {
+      return {
+        ...base,
+        text: parsed.text,
+        percent: parsed.percent,
+        // 每个任务各自的百分比挂在事实快照上：报告卡片里那一行行事实本来就在，
+        // 挂上去才不会"整体 62%，但看不出是哪两个任务拖的"
+        tasks: facts.map((f, i) => ({
+          ...f,
+          percent: i < parsed.taskPercents.length ? parsed.taskPercents[i] : null,
+        })),
+      };
+    }
+    // 空正文但不是被预算截断（模型自己 stop 了、或只回了那两行标记）：
+    // 加预算重试解决不了，直接按空正文记
+    if (res.finishReason !== 'length') break;
+  }
+
+  // 空正文按失败记：界面上一张"什么都没有"的报告卡片和"模型没返回内容"是两回事。
+  // 单独一个码是因为它的成因与前两个不同（模型答了，但没写正文），
+  // 处理办法也不同 —— LLM_EMPTY 要调的是生成预算，不是网络。
+  return { ...base, errorCode: 'LLM_EMPTY', errorDetail: meta };
 }
 
 export const __testables = {

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

@@ -28,11 +28,14 @@ import { readFile } from 'node:fs/promises';
 import {
   buildRunningFacts,
   buildReportPrompt,
+  describeCallResult,
   formatDuration,
   generateProgressReport,
   normalizePercent,
   parseProgressHeader,
   MAX_FACT_TASKS,
+  MAX_REPORT_TOKENS,
+  MAX_REPORT_TOKENS_RETRY,
   SYSTEM_PROMPT_ZH,
   SYSTEM_PROMPT_EN,
 } from './progressReport.js';
@@ -237,11 +240,11 @@ test('英文模板同样给思考 / 工具分布 / 静默', () => {
 // ── generateProgressReport ──────────────────────────────────────────────
 
 /** 假流式调用：按 delta 序列回调，再给出终态 */
-function fakeStream(deltas, { aborted = false, error = null } = {}) {
+function fakeStream(deltas, { aborted = false, error = null, finishReason = '', usage = null } = {}) {
   return async (_model, _prompt, onDelta) => {
     if (error) throw error;
     for (const d of deltas) onDelta(d);
-    return { content: deltas.map(d => d.content || '').join(''), aborted };
+    return { content: deltas.map(d => d.content || '').join(''), aborted, finishReason, usage };
   };
 }
 
@@ -300,7 +303,7 @@ test('thinking 段被滤掉，不混进正文（否则用户会以为那是结
   assert.equal(report.text, '一切正常。');
 });
 
-test('模型报错 → LLM_FAILED 并留住原因；空正文也按失败记', async () => {
+test('模型报错 → LLM_FAILED 并留住原因；空正文记成 LLM_EMPTY', async () => {
   const facts = buildRunningFacts({ jobs: [runningJob()], tasks: TASKS, now: NOW });
   const failed = await generateProgressReport({
     facts,
@@ -310,13 +313,107 @@ test('模型报错 → LLM_FAILED 并留住原因；空正文也按失败记', a
   assert.equal(failed.errorCode, 'LLM_FAILED');
   assert.equal(failed.errorDetail, 'HTTP 401');
 
+  // 空正文与"报错"分开记：成因不同（这个是模型答了但没写正文），处理办法也不同
   const empty = await generateProgressReport({
     facts,
     model: MODEL,
     callStream: fakeStream([{ content: '   ' }]),
   });
-  assert.equal(empty.errorCode, 'LLM_FAILED');
+  assert.equal(empty.errorCode, 'LLM_EMPTY');
   assert.equal(empty.text, '');
+  // detail 里必须留下可以查的东西 —— 老实现这里是空串，界面上只有一句"生成失败"，
+  // 盘上也查不出原因（2026-09-30 那三条失败报告就是这么埋掉的）
+  assert.match(empty.errorDetail, /finish_reason=/);
+});
+
+// ── 空正文：预算被思考吃光（2026-09-30 用户报的"有时候生成失败"）──────────
+//
+// 复现过的形态：推理模型的 `max_tokens` 是**思考 + 正文共用**的，思考写满预算时
+// 正文一个字都没写出来，HTTP 还是 200。900 的老预算下实测思考 2708 字符 / content 0。
+// 这三条守的是"预算够用 + 截断了会自己重试一次 + 重试也没用时不假装成功"。
+
+test('生成预算够装下思考与正文（900 那个老值会被推理模型吃光）', () => {
+  assert.ok(MAX_REPORT_TOKENS >= 2000, `MAX_REPORT_TOKENS=${MAX_REPORT_TOKENS}`);
+  assert.ok(MAX_REPORT_TOKENS_RETRY > MAX_REPORT_TOKENS, '重试预算必须比常规预算大');
+});
+
+test('第一次被截断（finish_reason=length）且正文为空 → 加预算重试一次并拿到正文', async () => {
+  const facts = buildRunningFacts({ jobs: [runningJob()], tasks: TASKS, now: NOW });
+  const budgets = [];
+  const report = await generateProgressReport({
+    facts,
+    model: MODEL,
+    callStream: async (_m, _p, onDelta, opts) => {
+      budgets.push(opts.maxTokens);
+      if (budgets.length === 1) return { content: '', aborted: false, finishReason: 'length' };
+      onDelta({ content: 'PROGRESS: 40\nTASKS: 40\n第二次拿到了汇报正文。' });
+      return { content: '...', aborted: false, finishReason: 'stop' };
+    },
+  });
+  assert.equal(report.errorCode, '');
+  assert.equal(report.text, '第二次拿到了汇报正文。');
+  assert.equal(report.percent, 40);
+  assert.equal(budgets.length, 2, '必须恰好重试一次');
+  assert.ok(budgets[1] > budgets[0], `预算没加大：${budgets.join(' -> ')}`);
+});
+
+test('空正文但没被截断（模型自己 stop 了）→ 不重试，加预算也没用', async () => {
+  const facts = buildRunningFacts({ jobs: [runningJob()], tasks: TASKS, now: NOW });
+  let calls = 0;
+  const report = await generateProgressReport({
+    facts,
+    model: MODEL,
+    callStream: async () => { calls++; return { content: '', aborted: false, finishReason: 'stop' }; },
+  });
+  assert.equal(calls, 1);
+  assert.equal(report.errorCode, 'LLM_EMPTY');
+  assert.match(report.errorDetail, /finish_reason=stop/);
+});
+
+test('重试也没拿到正文时，errorDetail 里留下 finish_reason 与思考用量', async () => {
+  const facts = buildRunningFacts({ jobs: [runningJob()], tasks: TASKS, now: NOW });
+  let calls = 0;
+  const report = await generateProgressReport({
+    facts,
+    model: MODEL,
+    callStream: async () => {
+      calls++;
+      return {
+        content: '',
+        aborted: false,
+        finishReason: 'length',
+        usage: { completion_tokens: 8000, completion_tokens_details: { reasoning_tokens: 7980 } },
+      };
+    },
+  });
+  assert.equal(calls, 2, '被截断时两轮都该跑');
+  assert.equal(report.errorCode, 'LLM_EMPTY');
+  // 这一串就是"下次不用再翻网关日志"的全部意义
+  assert.match(report.errorDetail, /finish_reason=length/);
+  assert.match(report.errorDetail, /reasoning_tokens=7980/);
+  assert.match(report.errorDetail, /max_tokens=8000/);
+});
+
+test('超时不重试（90 秒没回来，再来一次大概率还是 90 秒）', async () => {
+  const facts = buildRunningFacts({ jobs: [runningJob()], tasks: TASKS, now: NOW });
+  let calls = 0;
+  const report = await generateProgressReport({
+    facts,
+    model: MODEL,
+    callStream: async () => { calls++; return { content: '', aborted: true, finishReason: 'length' }; },
+  });
+  assert.equal(calls, 1);
+  assert.equal(report.errorCode, 'LLM_TIMEOUT');
+  assert.match(report.errorDetail, /aborted/);
+});
+
+test('describeCallResult 认不出的字段不写，整串有上限', () => {
+  assert.equal(describeCallResult(null, 900), 'max_tokens=900 finish_reason=unknown');
+  assert.equal(
+    describeCallResult({ finishReason: 'stop' }, 3000),
+    'max_tokens=3000 finish_reason=stop'
+  );
+  assert.ok(describeCallResult({ finishReason: 'x'.repeat(600) }, 1).length <= 300);
 });
 
 test('流被中断（超时）→ LLM_TIMEOUT，而不是当成一句空汇报', async () => {

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

@@ -124,22 +124,53 @@ export function latestJob(jobsForTask) {
   return best;
 }
 
+/**
+ * 用户手动标的「已完成」（`task.manualDoneAt`，由 POST /tasks/:id/done 写）现在还成不成立。
+ *
+ * 为什么要这么个字段：列本来纯靠执行事实推导，但有**两件事只有人知道** ——
+ * 一条待在「待处理」里的任务其实早在别处干完了；一条「进行中」的任务模型已经不说话了，
+ * 用户比静默看门狗更早判断它干完了。这两件事推导不出来，只能由人落一个标记。
+ *
+ * 为什么写成"时间比较"而不是"起新一轮时把标记清掉"：
+ * 起 job 的入口不止一处（看板「执行」、编辑器「执行任务」、续聊、主 Agent 自动派发），
+ * 每处都去清一遍，漏掉任何一处就会留下一张"明明刚跑完却还挂在已完成"的卡片 —— 而且不报错。
+ * 时间比较把判据收在一个纯函数里：**标记之后又跑过一轮，这次标记就作废**
+ * （那次执行才是最新的事实，用户标完成时看到的不是它）。
+ *
+ * jobsForTask 里没有 startedAt 的老记录不算数：宁可让标记继续成立，
+ * 也不能凭空认为"标记过期了"而把用户手动收掉的任务又弹回待处理。
+ */
+export function manualDoneHolds(task, jobsForTask = []) {
+  const at = task && typeof task.manualDoneAt === 'string' ? task.manualDoneAt : '';
+  if (!at) return false;
+  return !(Array.isArray(jobsForTask) ? jobsForTask : [])
+    .some(j => j && typeof j.startedAt === 'string' && j.startedAt > at);
+}
+
 /**
  * 把一个任务推导到看板的四列之一。纯函数，单测覆盖。
  *
  * 口径（按优先级，逐条短路）：
  *   1. 有 job 处于 running/pending → `doing`
- *   2. 从没执行过 → `todo`
- *   3. 最近一条 job 是 done → `done`；其余终态（error/cancelled）→ `todo`
+ *   2. 有成立的手动「已完成」标记 → `done`
+ *   3. 从没执行过 → `todo`
+ *   4. 最近一条 job 是 done → `done`；其余终态（error/cancelled）→ `todo`
  *
  * error/cancelled 不再单列：列表示任务是否仍待处理，错误是这一轮执行的结果，
  * 具体错误继续通过卡片标记和任务详情展示。
+ *
+ * 「在跑」为什么排在手写标记前面：手动完成一条**正在跑**的任务时，路由会先把这一轮停掉
+ * 再落标记（见 /tasks/:id/done）。停不掉的那种（任务跑在另一个 g ui 实例里）路由会直接
+ * 拒绝，所以正常情况下走不到这条 —— 真走到了，也宁可继续显示「进行中」：
+ * 卡片说"已完成"而进程还在写代码，是比列不准更难发现的一种撒谎。
  */
 export function deriveTaskColumn(task, jobsForTask = []) {
   const jobs = Array.isArray(jobsForTask) ? jobsForTask : [];
 
   if (jobs.some(j => j && (j.status === 'running' || j.status === 'pending'))) return 'doing';
 
+  if (manualDoneHolds(task, jobs)) return 'done';
+
   if (jobs.length === 0) return 'todo';
   const last = latestJob(jobs);
   return last && last.status === 'done' ? 'done' : 'todo';
@@ -364,6 +395,31 @@ export function decorateTaskForBoard(task, jobsForTask = [], { now = Date.now()
     lastDurationMs: jobDurationMs(last),
     /** 那条 job 的启动时刻，配合 lastJobEndedAt 给悬停提示里的「几点到几点」 */
     lastJobStartedAt: last ? (last.startedAt || null) : null,
+    /**
+     * 「这条不是跑完的，是**判**完的」——静默看门狗给的 `{at, reason, silentMs}`，没判过是 null。
+     *
+     * 为什么要专门给卡片一个字段：自动收尾和"进程自己正常退出"在看板上长得一模一样
+     * （都是「已完成」+ 一段用时），但它俩的含义差很远 —— 前者是模型读了思考与最后那段话
+     * 后认为活已经干完，用户多半想扫一眼依据再决定要不要信。没有这个字段，卡片只会
+     * 不声不响地换个列，模型那句依据就永远躺在 jobs.json 里没人看得到。
+     */
+    autoCompleted: (last && last.autoCompleted && typeof last.autoCompleted === 'object')
+      ? {
+        at: last.autoCompleted.at || null,
+        reason: typeof last.autoCompleted.reason === 'string' ? last.autoCompleted.reason : '',
+        silentMs: Number.isFinite(last.autoCompleted.silentMs) ? last.autoCompleted.silentMs : null,
+      }
+      : null,
+    /**
+     * 用户手动标的「已完成」时刻（`POST /tasks/:id/done`），没标过 / 已经被新一轮执行作废 → null。
+     *
+     * 给的是**成立与否**（manualDoneHolds）而不是原始字段：卡片拿它做两件事 ——
+     * ① 决定右下角那颗按钮是「完成」还是「撤销」（撤销只该出现在"手动标的"那种卡上，
+     * 撤销一个自己跑完的任务什么都不会发生）；② 当完成时刻显示。
+     * ② 是必须的：手动收掉的任务没有"跑完的时刻"，最近一条 job 可能是三天前那次报错，
+     * 照旧取 lastJobEndedAt 的话，用户刚点完完成，卡片上写的是「3 天前」。
+     */
+    manualDoneAt: manualDoneHolds(task, jobs) ? task.manualDoneAt : null,
     createdAt: task.createdAt || null,
     updatedAt: task.updatedAt || null,
   };

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

@@ -23,6 +23,7 @@ import {
   projectName,
   resolveTaskRepoPath,
   deriveTaskColumn,
+  manualDoneHolds,
   latestJob,
   summarizeProjectTasks,
   buildProjectEntries,
@@ -113,6 +114,56 @@ test('latestJob 按 startedAt 取最新的一条', () => {
   assert.equal(latestJob([]), null);
 });
 
+// ── 手动「已完成」标记（看板卡片右下角的「完成」） ──────────────────
+
+test('deriveTaskColumn: 手动标的已完成能盖住"从没跑过"与"上一轮报错"', () => {
+  const marked = { manualDoneAt: '2026-01-02T00:00:00Z' };
+  assert.equal(deriveTaskColumn(marked, []), 'done');
+  // 上一轮报错/被取消的任务，本来退回待处理 —— 手动标完就留在已完成
+  const err = [job('j1', 't1', 'error', '2026-01-01T00:00:00Z', '2026-01-01T00:01:00Z')];
+  assert.equal(deriveTaskColumn({ manualDoneAt: '2026-01-02T00:00:00Z' }, err), 'done');
+});
+
+test('deriveTaskColumn: 标记之后又起过一轮，这次标记作废', () => {
+  // 用户标完成时看到的是"上一轮报错"，之后又跑了一轮 —— 那次执行才是最新的事实。
+  // 用时间比较而不是"起 job 时清标记"：起 job 的入口有四个，漏一处就会留下
+  // 一张"刚跑完却还挂在已完成"的卡片，而且不报错。
+  const jobs = [
+    job('j1', 't1', 'running', '2026-01-03T00:00:00Z'),
+  ];
+  assert.equal(manualDoneHolds({ manualDoneAt: '2026-01-02T00:00:00Z' }, jobs), false);
+  // 新一轮跑挂了 → 回到待处理，不是已完成（那条错误正等着人看）
+  const later = [job('j2', 't1', 'error', '2026-01-03T00:00:00Z', '2026-01-03T00:01:00Z')];
+  assert.equal(deriveTaskColumn({ manualDoneAt: '2026-01-02T00:00:00Z' }, later), 'todo');
+});
+
+test('deriveTaskColumn: 在跑永远压过手动标记（卡片不能说"已完成"而进程还在写代码）', () => {
+  const jobs = [job('j1', 't1', 'running', '2026-01-01T00:00:00Z')];
+  // 正常路径下走不到：路由会先把这一轮停掉再落标记，停不掉（别的实例在跑）直接拒绝。
+  assert.equal(deriveTaskColumn({ manualDoneAt: '2026-01-02T00:00:00Z' }, jobs), 'doing');
+});
+
+test('manualDoneHolds: 缺 startedAt 的老记录不算"标记过期"', () => {
+  // 宁可让标记继续成立，也不能凭空认为它过期、把用户手动收掉的任务弹回待处理
+  const legacy = [{ id: 'j1', taskId: 't1', status: 'error', startedAt: '' }];
+  assert.equal(manualDoneHolds({ manualDoneAt: '2026-01-02T00:00:00Z' }, legacy), true);
+  // 从没标过 / 字段不是字符串 → 一律不成立
+  assert.equal(manualDoneHolds({}, []), false);
+  assert.equal(manualDoneHolds({ manualDoneAt: 12345 }, []), false);
+});
+
+test('decorateTaskForBoard: manualDoneAt 给的是"成立与否"，不是原始字段', () => {
+  const now = Date.parse('2026-01-05T00:00:00Z');
+  const task = { id: 't1', manualDoneAt: '2026-01-02T00:00:00Z' };
+  // 标记之后没跑过 → 卡片拿到它，据此显示「撤销」并把完成时间显示成标记时刻
+  assert.equal(decorateTaskForBoard(task, [], { now }).manualDoneAt, '2026-01-02T00:00:00Z');
+  // 标记之后又跑了一轮 → 给 null：卡片上那颗按钮该变回「完成」，不能还挂着「撤销」
+  const later = [job('j2', 't1', 'done', '2026-01-03T00:00:00Z', '2026-01-03T00:01:00Z')];
+  assert.equal(decorateTaskForBoard(task, later, { now }).manualDoneAt, null);
+  // 没标过就是 null（不是 undefined —— 前端按 truthy 判断）
+  assert.equal(decorateTaskForBoard({ id: 't2' }, [], { now }).manualDoneAt, null);
+});
+
 // ── 项目合并去重 ────────────────────────────────────────────────────
 
 test('buildProjectEntries: 最近目录与任务路径取并集去重，大小写与斜杠都归一', () => {