taskboard-workbench 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/CHANGELOG.md +132 -0
  2. package/LICENSE +21 -0
  3. package/README.md +121 -2
  4. package/cli/tb.mjs +314 -0
  5. package/cordis.patch.yml +5 -0
  6. package/index.js +633 -0
  7. package/lib/client.js +522 -0
  8. package/package.json +83 -4
  9. package/spec//345/233/242/351/230/237agent.md +171 -0
  10. package/src/core/advance.mjs +192 -0
  11. package/src/core/agent-teams.mjs +48 -0
  12. package/src/core/binding.mjs +44 -0
  13. package/src/core/config.mjs +22 -0
  14. package/src/core/debug-dispatch.mjs +94 -0
  15. package/src/core/delivery.mjs +93 -0
  16. package/src/core/deps.mjs +53 -0
  17. package/src/core/diagnostics.mjs +648 -0
  18. package/src/core/domain.mjs +235 -0
  19. package/src/core/empty-state.mjs +240 -0
  20. package/src/core/errors.mjs +139 -0
  21. package/src/core/executor.mjs +645 -0
  22. package/src/core/human-review.mjs +773 -0
  23. package/src/core/intake.mjs +116 -0
  24. package/src/core/kickoff.mjs +147 -0
  25. package/src/core/loop.mjs +498 -0
  26. package/src/core/memory.mjs +193 -0
  27. package/src/core/next-step.mjs +377 -0
  28. package/src/core/notify.mjs +183 -0
  29. package/src/core/owner.mjs +41 -0
  30. package/src/core/requirements.mjs +262 -0
  31. package/src/core/review.mjs +82 -0
  32. package/src/core/session-naming.mjs +64 -0
  33. package/src/core/split-ask.mjs +107 -0
  34. package/src/core/store.mjs +3103 -0
  35. package/src/core/team.mjs +170 -0
  36. package/src/core/verify.mjs +170 -0
  37. package/src/core/watchdog.mjs +144 -0
  38. package/src/host/ai-elaborator.mjs +26 -0
  39. package/src/host/team-engine.mjs +125 -0
  40. package/src/host/tool-surface.mjs +205 -0
  41. package/src/server/api.mjs +1974 -0
  42. package/src/server/events.mjs +32 -0
  43. package/src/server/kickoff.mjs +46 -0
  44. package/src/server/server.mjs +211 -0
  45. package/src/server/verify.mjs +112 -0
  46. package/tools/env-check.mjs +35 -0
  47. package/tools/seed.mjs +67 -0
  48. package/web/app.js +5237 -0
  49. package/web/index.html +15 -0
  50. package/web/tokens.css +1139 -0
@@ -0,0 +1,3103 @@
1
+ /**
2
+ * store.mjs —— 存储与用例层(零依赖,node:sqlite)。
3
+ * 单文件库 <dataDir>/taskboard.sqlite;幂等建库;编号事务内递增;乐观版本;
4
+ * owner 为 tasks 正式列(t24)——老库的 `owner:<role>` 标签在打开时一次性迁移(幂等)。
5
+ * 注意:tasks_owner_idx 只在迁移函数里创建(老库建表语句是 no-op,提前建索引会因缺列失败)。
6
+ */
7
+ import { randomUUID } from "node:crypto";
8
+ import { mkdirSync } from "node:fs";
9
+ import path from "node:path";
10
+ import { DatabaseSync } from "node:sqlite";
11
+
12
+ import { resolveDataDir, resolveDbPath } from "./config.mjs";
13
+ import {
14
+ DEFAULT_PRIORITY, DEFAULT_STATUS, GOVERNANCE_DEFAULTS,
15
+ assertActor, assertNoCycle, assertParentLink, assertPriority, assertProjectId,
16
+ assertStatus, assertTitle, checkGovernance, compareByPriority, formatIdentifier,
17
+ normalizeDescription, normalizeLabels, parseIdentifier, slugify,
18
+ } from "./domain.mjs";
19
+ import { normalizeOwner, splitOwnerLabels } from "./owner.mjs";
20
+ import { TbError, invalidField } from "./errors.mjs";
21
+ import { UNTAKEN_COMMENT_MARKER, detectUntakenDelivery } from "./delivery.mjs";
22
+ import { VERIFY_MAX_COMMAND, parseVerifyComment } from "./verify.mjs";
23
+ import {
24
+ assertFeasibilityVerdict, assertRequirementSource, assertSplitTasks,
25
+ elaborateDocument, formatRequirementIdentifier, normalizeTitle, parseRequirementIdentifier,
26
+ titleKey, assertRequirementStatus, normalizeCandidates, summarizeRequirementCompletion,
27
+ } from "./requirements.mjs";
28
+ import { TEAM_WRITABLE_STATUSES } from "./team.mjs";
29
+ import { REVIEW_SOURCE_STATUSES, REVIEW_IDLE_MS, detectReviewDeadlock, reviewReturnStatus } from "./review.mjs";
30
+ import { NOTIFY_DELIVERY_MODES, buildNotifyMessage, normalizeDeliveryMode, selectNotifyEvents } from "./notify.mjs";
31
+ import { HUMAN_REVIEW_LABEL, assertConclusion, categoryLabel, conclusionOutcome, isHumanReviewTask, validateHumanReviewDraft } from "./human-review.mjs";
32
+ // 项目记忆(2026-10-28 拍板 D-M1):L2 记忆条目,与内核表同库;**不是第二真源**(必带 provenance)。
33
+ import { createMemoryApi } from "./memory.mjs";
34
+
35
+ export const SCHEMA_VERSION = 11; // 11:项目记忆(memory_entries / memory_links / memory_recalls)
36
+
37
+ // ---- 任务级验收标准与复核动作(FR-94) ---------------------------------------
38
+ /**
39
+ * 真机反馈(2026-10-22,用户在概览页标注):「**为方便任务执行情况确认,应该在概览内任务添加时
40
+ * 即记录完成验收及复核动作标准,以便快速复核**」。
41
+ *
42
+ * 缺口:此前只有**需求条目**带 `acceptance`,任务级没有 —— 卡做到「待验收」时,评审人手里
43
+ * 只有 FR-90 的机器结论,**没有"这张卡当初说好按什么判定"** ⇒ 验收只能凭感觉。
44
+ * 处置:任务也带两个字段,且**添加任务时就能写**。
45
+ */
46
+ /** 验收标准上限(Markdown 原文保留;只是防把日志整段塞进来)。 */
47
+ export const ACCEPTANCE_MAX = 4000;
48
+
49
+ /** 验收标准归一:非字符串/未传 → `""`(未记录);只截断,不改写、不臆断措辞。 */
50
+ export function normalizeAcceptance(value) {
51
+ if (value === undefined || value === null) return "";
52
+ return String(value).slice(0, ACCEPTANCE_MAX);
53
+ }
54
+
55
+ /**
56
+ * 任务级「复核动作」(命令)归一:空串/未传 → `null` =**回落**(任务级 → 项目 `envConfig.verifyCommand`
57
+ * → 内置默认),只有显式写了命令才覆盖。长度上限与 FR-90 的 `normalizeVerifyCommand` **同口径**
58
+ * (常量从 `verify.mjs` 取,避免两份)。
59
+ */
60
+ export function normalizeTaskVerifyCommand(value) {
61
+ if (value === undefined || value === null) return null;
62
+ const s = String(value).trim();
63
+ return s === "" ? null : s.slice(0, VERIFY_MAX_COMMAND);
64
+ }
65
+
66
+ // ---- 尝试记录与事件流(FR-82) ------------------------------------------------
67
+ /** 单次尝试的默认运行时上限(毫秒);超过即视为"超时"(看护/诊断据此给结论)。 */
68
+ export const DEFAULT_RUN_MAX_MS = 30 * 60 * 1000;
69
+ /** 尝试的终态取值(照抄 hermes `_end_run` 的 outcome 口径)。 */
70
+ export const RUN_OUTCOMES = Object.freeze(["success", "blocked", "failed", "crash", "timeout", "reclaimed", "cancelled", "released", "ended"]);
71
+
72
+ // ---- 评审流程(FR-83) ------------------------------------------------------
73
+ /** 置"受阻"的路由方式:`wait`=等父任务(回可开工,FR-80 默认);`hold`=保持受阻直到外部解除(评审门红线③)。 */
74
+ export const BLOCK_ROUTES = Object.freeze(["wait", "hold"]);
75
+
76
+ /**
77
+ * 纯函数:一次尝试是否**超过运行时上限**(FR-82 的 `max_ms`)。
78
+ * 未结束的尝试按 `now` 计;已结束的按 `ended_at` 计 —— 用于把"跑太久"判成 `timeout` 而非"停滞"。
79
+ */
80
+ export function runExceededMax(run, { now = Date.now(), maxMs = null } = {}) {
81
+ if (!run || !run.startedAt) return false;
82
+ const limit = Number(maxMs ?? run.maxMs ?? DEFAULT_RUN_MAX_MS);
83
+ if (!Number.isFinite(limit) || limit <= 0) return false;
84
+ const end = run.endedAt ? new Date(run.endedAt).getTime() : now;
85
+ return end - new Date(run.startedAt).getTime() > limit;
86
+ }
87
+
88
+ // ---- 执行认领(FR-77):带过期的认领锁 + 心跳 ------------------------------------
89
+ /** 认领默认存活时长;到期未续即视为"在途失效"。 */
90
+ export const DEFAULT_CLAIM_TTL_MS = 30 * 60 * 1000;
91
+ /** 心跳新鲜度阈值:超过即认为执行侧已停止推进(**缺心跳本身不计为失败**)。 */
92
+ export const DEFAULT_HEARTBEAT_GAP_MS = 10 * 60 * 1000;
93
+ // ---- 失败会计与熔断(FR-78) ------------------------------------------------
94
+ /** 连续非成功次数的默认阈值;达到即自动置"受阻"并停止自动重试。 */
95
+ export const DEFAULT_FAILURE_LIMIT = 2;
96
+ /** 近期成功窗口:窗口内成功过的任务不得被再次自动派发(除非人工显式重跑)。 */
97
+ export const DEFAULT_SUCCESS_WINDOW_MS = 60 * 60 * 1000;
98
+ /**
99
+ * 配额 / 鉴权类错误:**立即阻塞、不重试**(重试不会让配额回来)。
100
+ * 正则照搬 hermes `_RESPAWN_BLOCKER_RE`(kanban_db_dispatch.py:43)。
101
+ */
102
+ export const QUOTA_AUTH_ERROR_RE = /\b(quota|rate[\s_-]?limit|429|403|auth\w*|unauthorized|forbidden|billing|subscription|access[\s_]denied|permission[\s_]denied|invalid[\s_]api[\s_]key)\b/i;
103
+ // ---- 阻断原因分类与复发升级(FR-80) ----------------------------------------
104
+ /** 阻断类型(照搬 hermes `VALID_BLOCK_KINDS`,kanban_db.py:93)。 */
105
+ export const BLOCK_KINDS = Object.freeze(["dependency", "needs_input", "capability", "transient"]);
106
+ /** 同因重复阻断的升级阈值(照搬 hermes `BLOCK_RECURRENCE_LIMIT = 2`)。 */
107
+ export const BLOCK_RECURRENCE_LIMIT = 2;
108
+ /** 升级到"人工兜底队列"时打的标签。 */
109
+ export const TRIAGE_LABEL = "triage";
110
+
111
+ const SCHEMA_SQL = `
112
+ create table if not exists projects (
113
+ id text primary key, name text not null, workspace_path text,
114
+ initial_session_id text,
115
+ next_seq integer not null default 1, next_req_seq integer not null default 1,
116
+ created_at text not null, updated_at text not null
117
+ );
118
+ create table if not exists tasks (
119
+ id text primary key, identifier text not null unique,
120
+ project_id text not null references projects(id) on delete cascade,
121
+ title text not null, description text not null default '',
122
+ -- 任务级验收标准与复核动作(FR-94):添加任务时即记录,供评审/复核时快速判定
123
+ acceptance text not null default '', verify_command text,
124
+ status text not null, priority text not null default 'none',
125
+ labels text not null default '[]', owner text,
126
+ parent_id text references tasks(id) on delete set null,
127
+ requirement_id text,
128
+ session_id text,
129
+ -- FR-11:列内手工顺序(拖拽落点)。为空 = 从未手工排过 ⇒ 排在已排过的卡之后,同为空者按 created_at。
130
+ board_position integer,
131
+ -- 执行认领(FR-77):claim_lock 为空即"未被认领";到期或心跳陈旧即可回收。
132
+ claim_lock text, claim_expires text, claim_owner text, claim_source text, last_heartbeat_at text,
133
+ -- 失败会计与熔断(FR-78):连续非成功计数(仅成功完成时清零)+ 最近失败原因 + 最近成功/重新入队时间
134
+ consecutive_failures integer not null default 0, last_failure_error text,
135
+ last_success_at text, requeued_at text, max_retries integer,
136
+ -- 阻断原因分类与复发升级(FR-80)
137
+ block_kind text, block_recurrences integer not null default 0, triage_at text,
138
+ -- 受阻起始时间(FR-79 "卡在受阻"诊断判据;离开受阻即清空)
139
+ blocked_at text,
140
+ -- 当前进行中的尝试(FR-82):认领即开一条 run,结束时清空
141
+ current_run_id text,
142
+ -- 评审流程(FR-83):评审者 / 评审态 / 返工轮次 / 请求时间 / 来源列(返工退回哪一列)/ 评审依赖
143
+ reviewer text, review_state text, review_round integer not null default 0,
144
+ review_requested_at text, review_source_status text, review_depends_on text,
145
+ -- 人工校验任务(FR-85b):判定类别 / 状态(pending|concluded)/ 结论 / 结论时间与操作者
146
+ human_review_category text, human_review_state text, human_review_conclusion text,
147
+ human_review_concluded_at text, human_review_concluded_by text,
148
+ version integer not null default 1, created_at text not null, updated_at text not null
149
+ );
150
+ create index if not exists tasks_project_status_idx on tasks(project_id, status);
151
+ create index if not exists tasks_parent_idx on tasks(parent_id);
152
+ create table if not exists comments (
153
+ id text primary key, task_id text not null references tasks(id) on delete cascade,
154
+ body text not null default '', version integer not null default 1,
155
+ -- FR-17:编辑留痕(最后一次编辑的时间/操作者;完整历史在 comment_revisions)
156
+ edited_at text, edited_by text,
157
+ created_at text not null, updated_at text not null
158
+ );
159
+ create index if not exists comments_task_idx on comments(task_id, created_at);
160
+ -- FR-17:评论编辑留痕(**保留原文本**,二选一里的强口径)。每次编辑先把**编辑前**的正文原样存一行,
161
+ -- 因此「原内容不被静默覆盖」是**可回看**的事实,而不是一句"已编辑 N 次"的声明。
162
+ create table if not exists comment_revisions (
163
+ id text primary key, comment_id text not null references comments(id) on delete cascade,
164
+ rev integer not null, body text not null, edited_at text not null, edited_by text,
165
+ unique (comment_id, rev)
166
+ );
167
+ create index if not exists comment_revisions_comment_idx on comment_revisions(comment_id, rev);
168
+ create table if not exists requirement_docs (
169
+ id text primary key, project_id text not null references projects(id) on delete cascade,
170
+ body text not null default '', version integer not null default 1,
171
+ created_at text not null, updated_at text not null
172
+ );
173
+ create unique index if not exists requirement_docs_project_idx on requirement_docs(project_id);
174
+ create table if not exists requirement_items (
175
+ id text primary key, identifier text not null unique,
176
+ project_id text not null references projects(id) on delete cascade,
177
+ doc_id text references requirement_docs(id) on delete set null,
178
+ title text not null, description text not null default '', acceptance text not null default '',
179
+ priority text not null default 'none', status text not null default 'open',
180
+ source text not null default 'manual', norm_title text,
181
+ feasibility text, feasibility_reason text, feasibility_by text, feasibility_override text,
182
+ created_at text not null, updated_at text not null
183
+ );
184
+ create index if not exists requirement_items_project_idx on requirement_items(project_id, status);
185
+ create index if not exists requirement_items_doc_idx on requirement_items(doc_id);
186
+ create table if not exists requirement_candidates (
187
+ id text primary key, doc_id text not null references requirement_docs(id) on delete cascade,
188
+ project_id text not null, title text not null, description text not null default '',
189
+ acceptance text not null default '', priority text not null default 'none',
190
+ norm_title text, source text not null default 'elaborated-rule',
191
+ status text not null default 'pending', created_at text not null
192
+ );
193
+ create index if not exists requirement_candidates_doc_idx on requirement_candidates(doc_id, status);
194
+ create table if not exists task_dependencies (
195
+ project_id text not null,
196
+ blocker_id text not null references tasks(id) on delete cascade,
197
+ blocked_id text not null references tasks(id) on delete cascade,
198
+ reason text,
199
+ created_at text not null,
200
+ primary key (blocker_id, blocked_id),
201
+ check (blocker_id <> blocked_id)
202
+ );
203
+ create index if not exists task_dependencies_blocked_idx on task_dependencies(blocked_id);
204
+ create index if not exists task_dependencies_blocker_idx on task_dependencies(blocker_id);
205
+ create table if not exists team_runs (
206
+ id text primary key,
207
+ target_task_id text references tasks(id) on delete set null,
208
+ target_requirement_id text references requirement_items(id) on delete set null,
209
+ status text not null default 'staged',
210
+ created_at text not null, updated_at text not null
211
+ );
212
+ create table if not exists team_members (
213
+ id text primary key, team_id text not null references team_runs(id) on delete cascade,
214
+ role text not null, model text, executor text, status text not null default 'ready', created_at text not null
215
+ );
216
+ create table if not exists team_tasks (
217
+ id text primary key, team_id text not null references team_runs(id) on delete cascade,
218
+ task_id text not null references tasks(id) on delete cascade,
219
+ member_id text, kind text not null default 'work', status text not null default 'open',
220
+ attempt integer, created_at text not null, updated_at text not null
221
+ );
222
+ create unique index if not exists team_tasks_active_lock on team_tasks(task_id) where status in ('open','running');
223
+ create table if not exists team_attempts (
224
+ id text primary key, team_task_id text not null references team_tasks(id) on delete cascade,
225
+ attempt_id text, result text, created_at text not null
226
+ );
227
+ create table if not exists governance_audit (
228
+ id text primary key, at text not null, actor text, action text not null,
229
+ target text, allowed integer not null, reason text, detail text
230
+ );
231
+ create table if not exists project_settings (
232
+ project_id text primary key references projects(id) on delete cascade,
233
+ env_config text not null default '{}',
234
+ team_template text not null default '{}',
235
+ loop_config text not null default '{}',
236
+ updated_at text not null
237
+ );
238
+ create table if not exists project_sessions (
239
+ project_id text not null references projects(id) on delete cascade,
240
+ session_id text not null,
241
+ status text not null default 'pending',
242
+ created_at text not null,
243
+ updated_at text not null,
244
+ primary key (project_id, session_id)
245
+ );
246
+ -- 可操作诊断(FR-79):一条任务同一类型只留一行;问题消失即 resolved_at(自动消解)。
247
+ create table if not exists task_diagnostics (
248
+ id text primary key, task_id text not null references tasks(id) on delete cascade,
249
+ kind text not null, severity text not null default 'medium', title text not null,
250
+ detail text not null default '', suggested text, actions text not null default '[]',
251
+ count integer not null default 1, first_seen_at text not null, last_seen_at text not null,
252
+ resolved_at text, dismissed_at text, version integer not null default 1
253
+ );
254
+ create unique index if not exists task_diagnostics_task_kind_idx on task_diagnostics(task_id, kind);
255
+ create index if not exists task_diagnostics_active_idx on task_diagnostics(task_id, resolved_at);
256
+ -- 尝试记录(FR-82):**每次认领执行**=一条 run;结束即闭合(outcome/摘要/错误/起止/心跳/运行时上限)。
257
+ create table if not exists task_runs (
258
+ id text primary key, task_id text not null references tasks(id) on delete cascade,
259
+ attempt integer not null, status text not null default 'running',
260
+ outcome text, summary text, error text,
261
+ claim_lock text, session_id text, actor text,
262
+ started_at text not null, ended_at text, duration_ms integer,
263
+ heartbeats integer not null default 1, last_heartbeat_at text, max_ms integer,
264
+ created_at text not null, updated_at text not null
265
+ );
266
+ create unique index if not exists task_runs_task_attempt_idx on task_runs(task_id, attempt);
267
+ create index if not exists task_runs_task_idx on task_runs(task_id, started_at);
268
+ -- 任务事件流(FR-82):**追加式**,任务内 seq 单调 + 全库 cursor 单调(FR-81 的推送游标)。
269
+ create table if not exists task_events (
270
+ id text primary key, task_id text not null references tasks(id) on delete cascade,
271
+ cursor integer not null, seq integer not null, type text not null,
272
+ from_value text, to_value text, actor text, detail text, at text not null
273
+ );
274
+ create unique index if not exists task_events_cursor_idx on task_events(cursor);
275
+ create unique index if not exists task_events_task_seq_idx on task_events(task_id, seq);
276
+ create index if not exists task_events_task_at_idx on task_events(task_id, at);
277
+ -- 全库单调游标(独立计数表:任务被删也**不回收**已发号,保证 FR-81 的"只推未推过的")
278
+ create table if not exists event_cursor (id integer primary key check (id = 1), value integer not null default 0);
279
+ insert into event_cursor (id, value) values (1, 0) on conflict(id) do nothing;
280
+ -- 通知订阅(FR-81):订阅"任务终态",带**事件游标**只推未推过的;三种交付模式 notify / notify+wake / wake。
281
+ -- task_id 为空 = **项目级**订阅(该项目所有任务的终态);否则只订阅该任务。
282
+ create table if not exists notify_subs (
283
+ id text primary key, project_id text not null references projects(id) on delete cascade,
284
+ task_id text references tasks(id) on delete cascade, session_id text not null,
285
+ mode text not null default 'notify+wake', active integer not null default 1,
286
+ last_cursor integer not null default 0,
287
+ delivered_count integer not null default 0, failed_count integer not null default 0,
288
+ last_delivery_at text, last_error text, last_kinds text not null default '[]',
289
+ created_at text not null, updated_at text not null
290
+ );
291
+ create unique index if not exists notify_subs_uniq_idx on notify_subs(project_id, ifnull(task_id, ''), session_id, mode);
292
+ create index if not exists notify_subs_project_idx on notify_subs(project_id, active);
293
+ -- 项目记忆(2026-10-28 · D-M1/D-M2/D-M5):结论条目 + 挂载关系 + 召回审计。
294
+ -- 铁律:**不是第二真源** —— 每条必带 provenance 指回 task_events/文档/会话;唯一索引去重。
295
+ create table if not exists memory_entries (
296
+ id text primary key,
297
+ scope text not null, -- project | agent | org
298
+ project_id text, agent_id text,
299
+ kind text not null, -- convention | decision | pitfall | fact | procedure
300
+ title text not null, body text not null, tags text not null default '[]',
301
+ provenance text not null, -- event:<cursor> | doc:<path>#<anchor> | session:<id> | run:<id>
302
+ confidence text not null default 'proposed', -- proposed | accepted
303
+ visibility text not null default 'shared', -- private | shared | org
304
+ verified_at text, ttl_days integer, -- kind=fact 必填 verified_at;过期即不召回
305
+ supersedes text, -- 被本条目取代的旧条目(**不删只取代**)
306
+ created_by text not null, created_at text not null, updated_at text not null
307
+ );
308
+ create unique index if not exists memory_dedupe_idx on memory_entries(scope, kind, title, provenance);
309
+ create index if not exists memory_scope_idx on memory_entries(scope, project_id, confidence);
310
+ create table if not exists memory_links (
311
+ entry_id text not null, entity_type text not null, entity_id text not null,
312
+ primary key (entry_id, entity_type, entity_id)
313
+ );
314
+ create table if not exists memory_recalls (
315
+ id integer primary key autoincrement,
316
+ session_id text, entry_id text not null, reason text, injected_chars integer, created_at text not null
317
+ );
318
+ `;
319
+
320
+ const nowIso = () => new Date().toISOString();
321
+
322
+ /**
323
+ * FR-80:阻断路由(纯函数)。对齐 hermes `_route_block`(kanban_db.py:2955)。
324
+ * - `dependency`:**不进人工受阻队列**,回到"可开工(todo)"等父任务(事件 `dependency_wait`)
325
+ * - 其它三类:进入 `blocked`;**同因再次阻断**时复发计数 +1;达阈值 → 转"人工兜底"(事件 `block-loop-detected`)
326
+ * 复发计数**只在成功完成时清零**(不在解除受阻时清零——那正是让循环无限跑下去的失忆)。
327
+ */
328
+ export function routeBlock({ kind = null, reason = null, prevKind = null, prevRecurrences = 0 } = {}) {
329
+ const payload = { reason, kind: kind ?? null };
330
+ if (kind === "dependency") {
331
+ return { status: "todo", eventKind: "dependency_wait", recurrences: 0, triage: false, payload };
332
+ }
333
+ const recurrences = prevKind === kind ? Number(prevRecurrences ?? 0) + 1 : 1;
334
+ const triage = recurrences >= BLOCK_RECURRENCE_LIMIT;
335
+ return {
336
+ status: "blocked",
337
+ eventKind: triage ? "block-loop-detected" : "blocked",
338
+ recurrences,
339
+ triage,
340
+ payload: { ...payload, recurrences, ...(triage ? { limit: BLOCK_RECURRENCE_LIMIT } : {}) },
341
+ };
342
+ }
343
+
344
+ /**
345
+ * FR-14:任务关键词匹配(大小写不敏感,子串命中)。
346
+ *
347
+ * 覆盖四类字段(验收要点逐项可测):
348
+ * · `identifier` —— 任务编号(如 `p1-3`;「编号片段」也能命中)
349
+ * · `title` —— 标题
350
+ * · `description`—— 描述
351
+ * · `labels` —— 标签(任一项命中即可)
352
+ *
353
+ * @param {{identifier?: string, title?: string, description?: string, labels?: string[]}} task
354
+ * @param {string} keyword 已 trim + 小写化的关键词(调用方保证非空)
355
+ * @returns {boolean}
356
+ */
357
+ function taskMatchesKeyword(task, keyword) {
358
+ const haystacks = [
359
+ task?.identifier,
360
+ task?.title,
361
+ task?.description,
362
+ ...(Array.isArray(task?.labels) ? task.labels : []),
363
+ ];
364
+ return haystacks.some((value) => typeof value === "string" && value.toLowerCase().includes(keyword));
365
+ }
366
+
367
+ const rowToProject = (row) => (row ? {
368
+ id: row.id, name: row.name, workspacePath: row.workspace_path, initialSessionId: row.initial_session_id ?? null,
369
+ nextSequence: row.next_seq,
370
+ createdAt: row.created_at, updatedAt: row.updated_at,
371
+ } : null);
372
+
373
+ function rowToTask(row) {
374
+ if (!row) return null;
375
+ let labels = [];
376
+ try {
377
+ labels = JSON.parse(row.labels);
378
+ } catch {
379
+ labels = [];
380
+ }
381
+ return {
382
+ id: row.id, identifier: row.identifier, projectId: row.project_id, title: row.title,
383
+ description: row.description, status: row.status, priority: row.priority,
384
+ acceptance: row.acceptance ?? "", verifyCommand: row.verify_command ?? null,
385
+ labels: Array.isArray(labels) ? labels : [], owner: row.owner ?? null,
386
+ requirementId: row.requirement_id ?? null,
387
+ sessionId: row.session_id ?? null,
388
+ // FR-11:列内手工顺序(null = 从未手工排过)。前端据此算拖拽落点,后端据此排序。
389
+ boardPosition: row.board_position === null || row.board_position === undefined ? null : Number(row.board_position),
390
+ claimLock: row.claim_lock ?? null,
391
+ claimExpires: row.claim_expires ?? null,
392
+ claimOwner: row.claim_owner ?? null,
393
+ claimSource: row.claim_source ?? null,
394
+ lastHeartbeatAt: row.last_heartbeat_at ?? null,
395
+ consecutiveFailures: Number(row.consecutive_failures ?? 0),
396
+ lastFailureError: row.last_failure_error ?? null,
397
+ lastSuccessAt: row.last_success_at ?? null,
398
+ requeuedAt: row.requeued_at ?? null,
399
+ maxRetries: row.max_retries ?? null,
400
+ blockKind: row.block_kind ?? null,
401
+ blockRecurrences: Number(row.block_recurrences ?? 0),
402
+ triageAt: row.triage_at ?? null,
403
+ blockedAt: row.blocked_at ?? null,
404
+ currentRunId: row.current_run_id ?? null,
405
+ reviewer: row.reviewer ?? null,
406
+ reviewState: row.review_state ?? null,
407
+ reviewRound: Number(row.review_round ?? 0),
408
+ reviewRequestedAt: row.review_requested_at ?? null,
409
+ reviewSourceStatus: row.review_source_status ?? null,
410
+ reviewDependsOn: row.review_depends_on ?? null,
411
+ humanReviewCategory: row.human_review_category ?? null,
412
+ humanReviewState: row.human_review_state ?? null,
413
+ humanReviewConclusion: row.human_review_conclusion ?? null,
414
+ humanReviewConcludedAt: row.human_review_concluded_at ?? null,
415
+ humanReviewConcludedBy: row.human_review_concluded_by ?? null,
416
+ parentId: row.parent_id, version: row.version, createdAt: row.created_at, updatedAt: row.updated_at,
417
+ };
418
+ }
419
+
420
+ const rowToRun = (row) => (row ? {
421
+ id: row.id, taskId: row.task_id, attempt: Number(row.attempt ?? 1), status: row.status,
422
+ outcome: row.outcome ?? null, summary: row.summary ?? null, error: row.error ?? null,
423
+ claimLock: row.claim_lock ?? null, sessionId: row.session_id ?? null, actor: row.actor ?? null,
424
+ startedAt: row.started_at, endedAt: row.ended_at ?? null,
425
+ durationMs: row.duration_ms ?? (row.ended_at ? Math.max(0, new Date(row.ended_at).getTime() - new Date(row.started_at).getTime()) : null),
426
+ heartbeats: Number(row.heartbeats ?? 1), lastHeartbeatAt: row.last_heartbeat_at ?? null,
427
+ maxMs: row.max_ms ?? null,
428
+ } : null);
429
+
430
+ const rowToTaskEvent = (row) => (row ? {
431
+ id: row.id, taskId: row.task_id, cursor: Number(row.cursor), seq: Number(row.seq), type: row.type,
432
+ from: row.from_value ?? null, to: row.to_value ?? null, actor: row.actor ?? null,
433
+ detail: row.detail ?? null, at: row.at,
434
+ } : null);
435
+
436
+ /** FR-81:订阅行 → 领域对象(`scope` 由 task_id 是否为空推导,UI 直接可用)。 */
437
+ const rowToNotifySub = (row) => (row ? {
438
+ id: row.id, projectId: row.project_id, taskId: row.task_id ?? null,
439
+ scope: row.task_id ? "task" : "project", sessionId: row.session_id,
440
+ mode: row.mode, active: Boolean(row.active), lastCursor: Number(row.last_cursor ?? 0),
441
+ deliveredCount: Number(row.delivered_count ?? 0), failedCount: Number(row.failed_count ?? 0),
442
+ lastDeliveryAt: row.last_delivery_at ?? null, lastError: row.last_error ?? null,
443
+ lastKinds: (() => { try { const a = JSON.parse(row.last_kinds ?? "[]"); return Array.isArray(a) ? a : []; } catch { return []; } })(),
444
+ createdAt: row.created_at, updatedAt: row.updated_at,
445
+ } : null);
446
+
447
+ const rowToDiagnostic = (row) => (row ? {
448
+ id: row.id, taskId: row.task_id, kind: row.kind, severity: row.severity ?? "medium",
449
+ title: row.title, detail: row.detail ?? "", suggested: row.suggested ?? null,
450
+ actions: (() => { try { const a = JSON.parse(row.actions ?? "[]"); return Array.isArray(a) ? a : []; } catch { return []; } })(),
451
+ count: Number(row.count ?? 1), firstSeenAt: row.first_seen_at, lastSeenAt: row.last_seen_at,
452
+ resolvedAt: row.resolved_at ?? null, dismissedAt: row.dismissed_at ?? null, version: row.version,
453
+ } : null);
454
+
455
+ /**
456
+ * FR-17:评论行 → 对外对象。
457
+ * 编辑留痕口径(见 §评论编辑):`edited` = 是否被编辑过;`editCount` = 编辑次数(= 历史版本数);
458
+ * `editedAt` / `editedBy` = **最后一次**编辑的时间与操作者。`revisions` 只在详情路径按需附带。
459
+ */
460
+ const rowToComment = (row) => (row ? {
461
+ id: row.id, taskId: row.task_id, body: row.body, version: row.version,
462
+ createdAt: row.created_at, updatedAt: row.updated_at,
463
+ edited: Boolean(row.edited_at),
464
+ editCount: Number(row.edit_count ?? 0),
465
+ editedAt: row.edited_at ?? null,
466
+ editedBy: row.edited_by ?? null,
467
+ } : null);
468
+
469
+ /** 评论编辑留痕行 → 对外对象(历史正文,按 rev 升序回放)。 */
470
+ const rowToCommentRevision = (row) => (row ? {
471
+ id: row.id, commentId: row.comment_id, rev: row.rev, body: row.body,
472
+ editedAt: row.edited_at, editedBy: row.edited_by ?? null,
473
+ } : null);
474
+
475
+ /** 评论查询统一出口:把留痕条数(= 编辑次数)一并取出,避免各处重复子查询。 */
476
+ const COMMENT_SELECT = `select c.*, (select count(*) from comment_revisions r where r.comment_id = c.id) as edit_count from comments c`;
477
+
478
+ // ---- 评论编辑(FR-17) --------------------------------------------------------
479
+ /**
480
+ * FR-85 升级门的「显式申报」标记。
481
+ * 权威定义在 `diagnostics.mjs` 的 `HUMAN_REVIEW_DECLARATION_MARKER`;此处**字面量重写**是
482
+ * 为了避开循环依赖(`diagnostics.mjs` 反向 import 本模块)。改动该标记时必须同步两处。
483
+ */
484
+ const HUMAN_REVIEW_DECLARATION_MARKER = "【人工校验申报】";
485
+
486
+ /**
487
+ * 评论可否编辑(纯函数,抛 `TbError`)。
488
+ *
489
+ * **红线(FR-17 验收要点③ + 评审证据旁路)**:编辑不得成为**改写评审证据**的旁路。
490
+ * 判定与处置(选定「禁止编辑」而非「仅追加更正」,理由见下):
491
+ * 1. **机器证据评论只读** —— 正文能被 `parseVerifyComment()` 解析出来的(`【自动复核】命令=…;退出码=…`,
492
+ * FR-90 自动复核落盘的证据)一律拒绝编辑。这些正是一条条**带结论的评审凭据**,
493
+ * 允许改写就等于允许把"失败(退出码 1)"改成"通过",评审人再也无法信任证据。
494
+ * 2. **不得伪造证据** —— 普通评论也不许被编辑**成**证据形态(同上,反方向的旁路)。
495
+ * 3. **人工校验申报只读** —— `【人工校验申报】` 是 FR-85 升级门的**判定输入**(`declarationEvidence()`
496
+ * 读**当前**正文,且"申报优先"直接决定判定类别)。允许事后编辑就等于允许改变门的结论,
497
+ * 而这正是评审依据之一 ⇒ 同理只读。需要改口径请**另发一条**申报评论(追加更正)。
498
+ * 4. 人写的进展/反馈评论**仍可编辑**:留痕口径是「**保留原文本**」(`comment_revisions` 逐版存原正文),
499
+ * 所以即便评审已引用过某条进展评论,其**当时原文随时可回看**,证据链不断。
500
+ * 需要更正已引用评论时,正解同样是**另发一条评论**(追加更正)—— `POST /comments` 始终可用。
501
+ */
502
+ export function assertCommentEditable(originalBody, nextBody, commentId = null) {
503
+ if (parseVerifyComment(originalBody)) {
504
+ throw new TbError("COMMENT_NOT_EDITABLE", "该评论是机器复核产出的评审证据(【自动复核】…),只读不可编辑;需要更正请另发一条评论追加说明", { commentId, reason: "review-evidence-readonly" });
505
+ }
506
+ if (parseVerifyComment(nextBody)) {
507
+ throw new TbError("COMMENT_NOT_EDITABLE", "评论不得被编辑成【自动复核】证据形态(那等于伪造评审证据);证据只能由自动复核产出", { commentId, reason: "cannot-forge-evidence" });
508
+ }
509
+ if (String(originalBody ?? "").includes(HUMAN_REVIEW_DECLARATION_MARKER)) {
510
+ throw new TbError("COMMENT_NOT_EDITABLE", "该评论是人工校验「显式申报」(【人工校验申报】…),是升级门的判定依据,只读不可编辑;需要更正口径请另发一条申报评论", { commentId, reason: "declaration-readonly" });
511
+ }
512
+ return true;
513
+ }
514
+
515
+ const rowToRequirementDoc = (row) => (row ? {
516
+ id: row.id, projectId: row.project_id, body: row.body, version: row.version,
517
+ createdAt: row.created_at, updatedAt: row.updated_at,
518
+ } : null);
519
+
520
+ const rowToRequirementItem = (row) => (row ? {
521
+ id: row.id, identifier: row.identifier, projectId: row.project_id, docId: row.doc_id,
522
+ title: row.title, description: row.description, acceptance: row.acceptance,
523
+ priority: row.priority, status: row.status, source: row.source, normTitle: row.norm_title,
524
+ feasibility: row.feasibility ?? null, feasibilityReason: row.feasibility_reason ?? null,
525
+ feasibilityBy: row.feasibility_by ?? null, feasibilityOverride: row.feasibility_override ?? null,
526
+ createdAt: row.created_at, updatedAt: row.updated_at,
527
+ } : null);
528
+
529
+ const rowToRequirementCandidate = (row) => (row ? {
530
+ id: row.id, docId: row.doc_id, projectId: row.project_id, title: row.title,
531
+ description: row.description, acceptance: row.acceptance, priority: row.priority,
532
+ normTitle: row.norm_title, source: row.source ?? "elaborated-rule", status: row.status, createdAt: row.created_at,
533
+ } : null);
534
+
535
+ /** 生成并插入一条需求条目(调用方负责事务;返回新编号)。 */
536
+ function insertRequirementItem(db, { id, projectId, docId, title, description, acceptance, priority, status, source, ts }) {
537
+ const project = db.prepare("select * from projects where id = ?").get(projectId);
538
+ const seq = project.next_req_seq ?? 1;
539
+ const identifier = formatRequirementIdentifier(projectId, seq);
540
+ db.prepare("update projects set next_req_seq = ?, updated_at = ? where id = ?").run(seq + 1, ts, projectId);
541
+ db.prepare(
542
+ `insert into requirement_items (id, identifier, project_id, doc_id, title, description, acceptance, priority, status, source, norm_title, created_at, updated_at)
543
+ values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
544
+ ).run(id, identifier, projectId, docId, title, description, acceptance, priority, status, source, titleKey(title), ts, ts);
545
+ return identifier;
546
+ }
547
+
548
+ function isConstraintError(error, needle) {
549
+ const message = String(error?.message ?? "");
550
+ return message.includes("UNIQUE constraint failed") && message.includes(needle);
551
+ }
552
+
553
+ /** 一次性迁移(幂等):1) 老库补 owner 列;2) `owner:<role>` 标签搬进 owner 并从 labels 移除。 */
554
+ export function migrateOwnerField(db) {
555
+ const columns = db.prepare("pragma table_info(tasks)").all().map((row) => row.name);
556
+ let addedColumn = false;
557
+ if (!columns.includes("owner")) {
558
+ db.exec("alter table tasks add column owner text");
559
+ addedColumn = true;
560
+ }
561
+ db.exec("create index if not exists tasks_owner_idx on tasks(owner)");
562
+
563
+ const rows = db.prepare("select id, owner, labels from tasks").all();
564
+ const update = db.prepare("update tasks set owner = ?, labels = ? where id = ?");
565
+ let migratedTasks = 0;
566
+ let strippedLabels = 0;
567
+ db.exec("begin immediate");
568
+ try {
569
+ for (const row of rows) {
570
+ let labels = [];
571
+ try {
572
+ labels = JSON.parse(row.labels);
573
+ } catch {
574
+ labels = [];
575
+ }
576
+ if (!Array.isArray(labels)) labels = [];
577
+ const split = splitOwnerLabels(labels);
578
+ const currentOwner = typeof row.owner === "string" && row.owner.trim() !== "" ? row.owner : null;
579
+ const nextOwner = currentOwner ?? (split.owner || null);
580
+ const labelsChanged = split.labels.length !== labels.length;
581
+ if (!labelsChanged && nextOwner === currentOwner) continue;
582
+ update.run(nextOwner, JSON.stringify(split.labels), row.id);
583
+ migratedTasks += 1;
584
+ if (labelsChanged) strippedLabels += 1;
585
+ }
586
+ db.exec("commit");
587
+ } catch (error) {
588
+ db.exec("rollback");
589
+ throw error;
590
+ }
591
+ return { addedOwnerColumn: addedColumn, migratedTasks, strippedLabels };
592
+ }
593
+
594
+ /**
595
+ * 迁移(幂等):老库的 `team_members` 表补 `executor` 列(FR-50 验收第一条:成员要带「执行器」)。
596
+ * 与 `migrateOwnerField` 同模式:`pragma table_info` 探列名,缺列才 `alter table add column`。
597
+ * 老行补列后为 `null`(="未配置执行器",与新建库的默认语义一致)。
598
+ */
599
+ export function migrateTeamMembers(db) {
600
+ const columns = db.prepare("pragma table_info(team_members)").all().map((row) => row.name);
601
+ if (columns.length && !columns.includes("executor")) {
602
+ db.exec("alter table team_members add column executor text");
603
+ return { addedTeamMemberExecutorColumn: true };
604
+ }
605
+ return { addedTeamMemberExecutorColumn: false };
606
+ }
607
+
608
+ /** 迁移(幂等):老库的 projects 表补 `next_req_seq` 列(需求条目编号序列)。 */
609
+ export function migrateRequirementSeq(db) {
610
+ const projectColumns = db.prepare("pragma table_info(projects)").all().map((row) => row.name);
611
+ const taskColumns = db.prepare("pragma table_info(tasks)").all().map((row) => row.name);
612
+ const candidateColumns = db.prepare("pragma table_info(requirement_candidates)").all().map((row) => row.name);
613
+ const result = { addedReqSeqColumn: false, addedTaskRequirementColumn: false, addedCandidateSourceColumn: false, addedTaskSessionColumn: false, addedProjectSessionColumn: false, addedClaimColumn: false, addedFailureColumn: false, addedBlockColumn: false, addedRunColumn: false, addedReviewColumn: false, addedCommentEditColumn: false, addedBoardPositionColumn: false };
614
+ if (!projectColumns.includes("next_req_seq")) {
615
+ db.exec("alter table projects add column next_req_seq integer not null default 1");
616
+ result.addedReqSeqColumn = true;
617
+ }
618
+ if (!projectColumns.includes("initial_session_id")) {
619
+ db.exec("alter table projects add column initial_session_id text");
620
+ result.addedProjectSessionColumn = true;
621
+ }
622
+ const psColumns = db.prepare("pragma table_info(project_settings)").all().map((row) => row.name);
623
+ if (psColumns.length && !psColumns.includes("loop_config")) {
624
+ db.exec("alter table project_settings add column loop_config text not null default '{}'");
625
+ result.addedLoopColumn = true;
626
+ }
627
+ const depColumns = db.prepare("pragma table_info(task_dependencies)").all().map((row) => row.name);
628
+ if (depColumns.length && !depColumns.includes("reason")) {
629
+ db.exec("alter table task_dependencies add column reason text");
630
+ result.addedDepReasonColumn = true;
631
+ }
632
+ if (!taskColumns.includes("requirement_id")) {
633
+ db.exec("alter table tasks add column requirement_id text");
634
+ result.addedTaskRequirementColumn = true;
635
+ }
636
+ if (!candidateColumns.includes("source")) {
637
+ db.exec("alter table requirement_candidates add column source text not null default 'elaborated-rule'");
638
+ result.addedCandidateSourceColumn = true;
639
+ }
640
+ if (!taskColumns.includes("session_id")) {
641
+ db.exec("alter table tasks add column session_id text");
642
+ result.addedTaskSessionColumn = true;
643
+ }
644
+ // FR-94:任务级验收标准 + 复核动作(老库补列,幂等)
645
+ if (!taskColumns.includes("acceptance")) {
646
+ db.exec("alter table tasks add column acceptance text not null default ''");
647
+ result.addedTaskAcceptanceColumn = true;
648
+ }
649
+ if (!taskColumns.includes("verify_command")) {
650
+ db.exec("alter table tasks add column verify_command text");
651
+ result.addedTaskVerifyCommandColumn = true;
652
+ }
653
+ // FR-77:执行认领锁 + 心跳(老库补列,幂等)
654
+ const claimColumns = { claim_lock: "text", claim_expires: "text", claim_owner: "text", claim_source: "text", last_heartbeat_at: "text" };
655
+ for (const [col, type] of Object.entries(claimColumns)) {
656
+ if (!taskColumns.includes(col)) {
657
+ db.exec(`alter table tasks add column ${col} ${type}`);
658
+ result.addedClaimColumn = true;
659
+ }
660
+ }
661
+ // FR-78:失败会计与熔断(老库补列,幂等)
662
+ const failureColumns = {
663
+ consecutive_failures: "integer not null default 0", last_failure_error: "text",
664
+ last_success_at: "text", requeued_at: "text", max_retries: "integer",
665
+ };
666
+ for (const [col, type] of Object.entries(failureColumns)) {
667
+ if (!taskColumns.includes(col)) {
668
+ db.exec(`alter table tasks add column ${col} ${type}`);
669
+ result.addedFailureColumn = true;
670
+ }
671
+ }
672
+ // FR-80:阻断原因分类 + 复发计数 + 人工兜底标记(老库补列,幂等)
673
+ // FR-79 追加 blocked_at(受阻起始时间,"卡在受阻"诊断判据)。
674
+ const blockColumns = { block_kind: "text", block_recurrences: "integer not null default 0", triage_at: "text", blocked_at: "text" };
675
+ for (const [col, type] of Object.entries(blockColumns)) {
676
+ if (!taskColumns.includes(col)) {
677
+ db.exec(`alter table tasks add column ${col} ${type}`);
678
+ result.addedBlockColumn = true;
679
+ }
680
+ }
681
+ // FR-82:当前尝试指针(老库补列,幂等)
682
+ if (!taskColumns.includes("current_run_id")) {
683
+ db.exec("alter table tasks add column current_run_id text");
684
+ result.addedRunColumn = true;
685
+ }
686
+ // FR-83:评审流程列(老库补列,幂等)
687
+ const reviewColumns = {
688
+ reviewer: "text", review_state: "text", review_round: "integer not null default 0",
689
+ review_requested_at: "text", review_source_status: "text", review_depends_on: "text",
690
+ };
691
+ for (const [col, type] of Object.entries(reviewColumns)) {
692
+ if (!taskColumns.includes(col)) {
693
+ db.exec(`alter table tasks add column ${col} ${type}`);
694
+ result.addedReviewColumn = true;
695
+ }
696
+ }
697
+ // FR-85b:人工校验任务列(老库补列,幂等)
698
+ const humanReviewColumns = {
699
+ human_review_category: "text", human_review_state: "text", human_review_conclusion: "text",
700
+ human_review_concluded_at: "text", human_review_concluded_by: "text",
701
+ };
702
+ for (const [col, type] of Object.entries(humanReviewColumns)) {
703
+ if (!taskColumns.includes(col)) {
704
+ db.exec(`alter table tasks add column ${col} ${type}`);
705
+ result.addedHumanReviewColumn = true;
706
+ }
707
+ }
708
+ // FR-17:评论编辑留痕列(老库补列,幂等)。`comment_revisions` 表由 SCHEMA_SQL 的
709
+ // `create table if not exists` 直接补齐老库(无需 alter),这里只补 comments 上的两个冗余列。
710
+ const commentColumns = db.prepare("pragma table_info(comments)").all().map((row) => row.name);
711
+ // FR-11:列内手工顺序(老库补列,幂等)。索引**必须在这里建**:老库的建表语句是 no-op,
712
+ // 若把 `create index ... board_position` 写进 SCHEMA_SQL,老库(还没有该列时)会因缺列直接失败
713
+ // —— 与顶部 `tasks_owner_idx` 的注释同一个坑。先补列、再建索引,两种库都覆盖。
714
+ if (!taskColumns.includes("board_position")) {
715
+ db.exec("alter table tasks add column board_position integer");
716
+ result.addedBoardPositionColumn = true;
717
+ }
718
+ db.exec("create index if not exists tasks_board_order_idx on tasks(project_id, status, board_position)");
719
+ for (const [col, type] of Object.entries({ edited_at: "text", edited_by: "text" })) {
720
+ if (!commentColumns.includes(col)) {
721
+ db.exec(`alter table comments add column ${col} ${type}`);
722
+ result.addedCommentEditColumn = true;
723
+ }
724
+ }
725
+ return result;
726
+ }
727
+
728
+ /**
729
+ * FR-11:**列内手工顺序**的落点计算与写回(拖拽落点 → 持久化的 `board_position`)。
730
+ *
731
+ * 口径(写在函数里,避免各处各猜):
732
+ * 1. `board_position` 是**列内**的顺序键(列 = 同 project + 同 status),跨列无意义。`resolveBoardOrder`
733
+ * 每次显式落点都会把**目标列**整列重编号成稠密 `0..n-1`;但**被移走的卡不会触发源列重编号**,
734
+ * 故源列可能留下空洞(如 `[1,2]`)—— 这只影响**数值**,**不影响相对顺序**(排序键只看大小),
735
+ * 且下一次对该列的显式落点会把空洞抹平。任何调用方**不得**假设 `board_position` 恒为稠密序列。
736
+ * 2. 列的**展示顺序** = `(board_position is null), board_position, created_at, rowid` —— 与 `listTasks`
737
+ * 的 ORDER BY 逐字一致;本函数按下标插入后**整列重编号**,保证"下次读出来的顺序"就是人看到的顺序。
738
+ * 3. 从未手工排过的卡(`board_position` 为空)在重编号时被赋上具体位置 —— 顺序**不变**(它们本就按
739
+ * created_at 排在已有位置之后),但从此成为"显式顺序",后续新建的卡会追加在它们之后(可预期)。
740
+ * 4. 写回**不动兄弟卡的 `version` / `updated_at`**:手工顺序是看板版式,兄弟卡内容一个字没变 ——
741
+ * 跟着涨版本会让别人的编辑无端撞 `VERSION_CONFLICT`(那是假冲突)。被移动的卡自己由 `updateTask`
742
+ * 主语句负责涨版本。这也是本函数**不写事件流**的原因:版式调整不该进任务生命周期事件。
743
+ *
744
+ * @param {*} db 已打开的库
745
+ * @param {{taskId: string, projectId: string, status: string, desiredIndex: number|{before: string|null}|null}} input
746
+ * `desiredIndex` 三种形态(前端用第一种,测试 / CLI 用第二种):
747
+ * · `{ before: <编号|id> }` —— **锚点式落点**:插到「该卡之前」(`before: null` = 列尾)。
748
+ * 这是**筛选生效时唯一正确的口径**:前端只看得到可见卡,锚点按可见邻居给,
749
+ * 服务端在**整列**里解析它的真实下标 ⇒ 隐藏卡不会让落点漂移。
750
+ * · `整数 n` —— 整列的 0-based 下标(含被移动卡自己之前的兄弟序列);超出上界**夹取**到列尾
751
+ * (渲染与落点之间列内容被别人改了是真实竞态,夹取是唯一不臆断的处置)。
752
+ * · `null` —— 追加到列尾。
753
+ * @returns {{ordered: string[], position: number}} 重编号后的整列 id 序列 + 移动卡的新位置
754
+ */
755
+ function resolveBoardOrder(db, { taskId, projectId, status, desiredIndex = null }) {
756
+ // 目标列里**除被移动卡之外**的卡,按当前展示顺序取出
757
+ const siblings = db.prepare(
758
+ `select id from tasks where project_id = ? and status = ? and id != ?
759
+ order by (board_position is null), board_position, created_at, rowid`,
760
+ ).all(projectId, status, taskId).map((row) => row.id);
761
+ let index;
762
+ if (desiredIndex === null || desiredIndex === undefined) index = siblings.length; // 落列尾
763
+ else if (typeof desiredIndex === "object" && !Array.isArray(desiredIndex)) {
764
+ const before = desiredIndex.before ?? null;
765
+ if (before === null || before === "") index = siblings.length;
766
+ else {
767
+ const anchor = db.prepare("select id, project_id, status from tasks where id = ? or identifier = ?").get(String(before), String(before));
768
+ if (!anchor) throw new TbError("TASK_NOT_FOUND", `落点锚点任务不存在:${before}`, { ref: before });
769
+ if (anchor.project_id !== projectId || anchor.status !== status) {
770
+ throw invalidField("boardPosition.before", `落点锚点必须与被打分卡同项目、同列(锚点 ${before} 在 ${anchor.project_id}/${anchor.status}),收到跨列/跨项目锚点`);
771
+ }
772
+ const at = siblings.indexOf(anchor.id);
773
+ if (at < 0) throw invalidField("boardPosition.before", `落点锚点 ${before} 不在目标列里(可能刚被移动/删除)`);
774
+ index = at;
775
+ }
776
+ } else {
777
+ if (!Number.isInteger(desiredIndex) || desiredIndex < 0) {
778
+ throw invalidField("boardPosition", `boardPosition 必须是 ≥0 的整数(列的 0-based 下标)、{before} 锚点或 null,收到:${JSON.stringify(desiredIndex)}`);
779
+ }
780
+ index = Math.min(desiredIndex, siblings.length);
781
+ }
782
+ return { ordered: siblings.slice(0, index).concat([taskId], siblings.slice(index)), position: index };
783
+ }
784
+
785
+ /** 把 `resolveBoardOrder` 的结果写库(整列重编号)。**只写 `board_position`**,不动兄弟卡的版本/时间。 */
786
+ function applyBoardOrder(db, ordered) {
787
+ const write = db.prepare("update tasks set board_position = ? where id = ?");
788
+ ordered.forEach((id, i) => write.run(i, id));
789
+ }
790
+
791
+ /**
792
+ * 归一「不归因理由」(P0 / D1 的逃生口)。
793
+ * 缺口径:给了就必须**非空**(空字符串等于没给),上限 500 字防灌水;没给返回 `null`。
794
+ */
795
+ function normalizeUnattributedReason(value) {
796
+ if (value === undefined || value === null) return null;
797
+ const text = String(value).trim();
798
+ if (text === "") {
799
+ throw new TbError("USAGE_ERROR", "unattributedReason 不能是空字符串:要么不传,要么给一句真实理由(会落审计)");
800
+ }
801
+ if (text.length > 500) throw new TbError("USAGE_ERROR", "unattributedReason 过长(上限 500 字)");
802
+ return text;
803
+ }
804
+
805
+ export function openStore(options = {}) {
806
+ const dataDir = resolveDataDir({ dataDir: options.dataDir, env: options.env });
807
+ const dbPath = options.dbPath ?? resolveDbPath(dataDir);
808
+ const policy = { ...GOVERNANCE_DEFAULTS, ...(options.policy ?? {}) };
809
+ // P0 归因门(D1 拍板「硬门 + 逃生口」)的**上线闸门**:默认 warn(建卡成功但返回可见警告 +
810
+ // 落 `attribution_missing` 事件),设 `TB_STRICT_ATTRIBUTION=1` 时才拒绝(`REQUIREMENT_REQUIRED`)。
811
+ // 为什么不一上来就拒:现有 Web 新建对话框 / seed / 部分团队路径还没有条目字段,直接拒会把
812
+ // 797 条既有用例与真机交互一起打红;按 §17.5「先 warn 后 reject」两步走,P3 随 MCP 一起翻默认。
813
+ const strictAttribution =
814
+ String((options.env ?? process.env)?.TB_STRICT_ATTRIBUTION ?? "") === "1";
815
+
816
+ let db;
817
+ let migration;
818
+ try {
819
+ if (dbPath !== ":memory:") mkdirSync(path.dirname(dbPath), { recursive: true });
820
+ db = new DatabaseSync(dbPath);
821
+ db.exec("pragma foreign_keys = on");
822
+ db.exec("pragma busy_timeout = 5000");
823
+ db.exec(SCHEMA_SQL);
824
+ migration = { ...migrateOwnerField(db), ...migrateRequirementSeq(db), ...migrateTeamMembers(db) };
825
+ } catch (error) {
826
+ const wrapped = new TbError(
827
+ "STORE_UNAVAILABLE",
828
+ `无法打开或初始化数据存储:${error instanceof Error ? error.message : String(error)}`,
829
+ { dbPath },
830
+ );
831
+ try {
832
+ db?.close();
833
+ } catch {
834
+ /* ignore */
835
+ }
836
+ throw wrapped;
837
+ }
838
+
839
+ const store = {
840
+ schemaVersion: SCHEMA_VERSION,
841
+ dataDir,
842
+ dbPath,
843
+ policy,
844
+ migration,
845
+
846
+ close() {
847
+ try {
848
+ db.close();
849
+ } catch {
850
+ /* ignore */
851
+ }
852
+ },
853
+
854
+ createProject(input = {}) {
855
+ const name = assertTitle(input.name, "name");
856
+ const id = assertProjectId(input.id ?? slugify(name), "id");
857
+ const workspacePath = input.workspacePath == null ? null : String(input.workspacePath);
858
+ const timestamp = nowIso();
859
+ try {
860
+ db.prepare(
861
+ `insert into projects (id, name, workspace_path, next_seq, created_at, updated_at) values (?, ?, ?, 1, ?, ?)`,
862
+ ).run(id, name, workspacePath, timestamp, timestamp);
863
+ } catch (error) {
864
+ if (isConstraintError(error, "projects.id")) throw new TbError("PROJECT_EXISTS", `项目已存在:${id}`, { id });
865
+ throw error;
866
+ }
867
+ return rowToProject(db.prepare("select * from projects where id = ?").get(id));
868
+ },
869
+
870
+ listProjects() {
871
+ return db.prepare("select * from projects order by created_at, rowid").all().map(rowToProject);
872
+ },
873
+
874
+ getProject(id) {
875
+ if (typeof id !== "string" || id === "") return null;
876
+ return rowToProject(db.prepare("select * from projects where id = ?").get(id));
877
+ },
878
+
879
+ requireProject(id) {
880
+ const project = store.getProject(id);
881
+ if (!project) throw new TbError("PROJECT_NOT_FOUND", `项目不存在:${id}`, { id });
882
+ return project;
883
+ },
884
+
885
+ /**
886
+ * FR-03:删除项目 —— **非空守卫**(验收要点:删除非空项目被拒绝且有明确提示)。
887
+ *
888
+ * 三条纪律:
889
+ * 1. **必须显式确认**:`confirm !== true` ⇒ 拒绝(`PROJECT_DELETE_UNCONFIRMED`),防误触。
890
+ * 2. **非空即拒**:项目下仍有**任务 / 需求条目 / 需求文档正文 / 项目会话关联**时一律拒绝,
891
+ * 并把**剩余数量**放进错误的 `details.remaining`,让上层能给出具体的人话提示。
892
+ * 3. **绝不级联删除**:本方法只在"确认为空"时删 `projects` 一行;任何情况下都不删任务、需求、
893
+ * 评论、事件等用户数据(守卫就是为此存在的——宁可拒绝,不可误删)。
894
+ */
895
+ deleteProject(projectId, { confirm, actor = "human", reason = null } = {}) {
896
+ const project = store.requireProject(projectId);
897
+ if (confirm !== true) {
898
+ store.recordAudit({ actor, action: "delete-project", target: project.id, allowed: false, reason: "confirm-required", detail: null });
899
+ throw new TbError("PROJECT_DELETE_UNCONFIRMED", `删除项目必须先显式确认(confirm: true):${project.id}`, { id: project.id });
900
+ }
901
+ // 非空判定:按"用户可感知的占用物"逐类计数(任务 / 需求条目 / 需求文档正文 / 项目会话关联)。
902
+ const tasks = db.prepare("select count(*) as n from tasks where project_id = ?").get(project.id).n;
903
+ const requirementItems = db.prepare("select count(*) as n from requirement_items where project_id = ?").get(project.id).n;
904
+ const doc = db.prepare("select id, body from requirement_docs where project_id = ?").get(project.id) ?? null;
905
+ const docBody = doc && String(doc.body ?? "").trim() !== "" ? 1 : 0;
906
+ const sessions = db.prepare("select count(*) as n from project_sessions where project_id = ?").get(project.id).n;
907
+ const remaining = { tasks, requirementItems, requirementDocs: docBody, sessions };
908
+ const total = tasks + requirementItems + docBody + sessions;
909
+ if (total > 0) {
910
+ store.recordAudit({ actor, action: "delete-project", target: project.id, allowed: false, reason: "project-not-empty", detail: JSON.stringify(remaining) });
911
+ throw new TbError(
912
+ "PROJECT_NOT_EMPTY",
913
+ `项目「${project.name}」仍非空,已拒绝删除:任务 ${tasks} 个、需求条目 ${requirementItems} 条、需求文档正文 ${docBody} 份、项目会话关联 ${sessions} 条。请先清空后再删(本操作不会级联删除任何数据)。`,
914
+ { id: project.id, remaining, total },
915
+ );
916
+ }
917
+ db.prepare("delete from projects where id = ?").run(project.id);
918
+ store.recordAudit({ actor, action: "delete-project", target: project.id, allowed: true, reason: reason ?? "empty-project", detail: JSON.stringify(remaining) });
919
+ return { id: project.id, name: project.name, deleted: true };
920
+ },
921
+
922
+ /** FR-60:把项目绑定到它的"初始会话"(首次绑定后不再改写)。 */
923
+ bindInitialSession(projectId, sessionId) {
924
+ const project = store.requireProject(projectId);
925
+ if (!sessionId) return project;
926
+ if (!project.initialSessionId) {
927
+ db.prepare("update projects set initial_session_id = ?, updated_at = ? where id = ?").run(String(sessionId), nowIso(), project.id);
928
+ }
929
+ return store.requireProject(project.id);
930
+ },
931
+ /** 默认(近期执行)项目:最近有任务活动的项目;无任务时回退到最近创建的项目。 */
932
+ /**
933
+ * FR-84:把项目主会话**替换**为给定会话——与 `bindInitialSession` 的"首次绑定不改写"相对,
934
+ * 供"主会话已失效 → 重建/重绑"使用。返回 `{ project, before, after, changed }` 便于审计与回滚。
935
+ */
936
+ rebindInitialSession(projectId, sessionId) {
937
+ const project = store.requireProject(projectId);
938
+ if (!sessionId) throw invalidField("sessionId", "必须提供会话标识");
939
+ const before = project.initialSessionId ?? null;
940
+ const after = String(sessionId);
941
+ if (before !== after) {
942
+ db.prepare("update projects set initial_session_id = ?, updated_at = ? where id = ?").run(after, nowIso(), project.id);
943
+ }
944
+ return { project: store.requireProject(project.id), before, after, changed: before !== after };
945
+ },
946
+ /**
947
+ * FR-84 补口(2026-10-23):把**某张任务的接续会话**改指到给定会话。
948
+ *
949
+ * 真机病根:任务级 `session_id` 是**派发/启动执行时写入的引用**。一旦它指向一个
950
+ * **别的或未归属工作区**的会话(实测 `obsidian-dsh-acp-15` → `cwd="/"`),任务详情里的
951
+ * 工作区归属门就会一直报警;而「重建并绑定项目主会话」只改**项目主会话指针**,
952
+ * **动不到任务级引用** ⇒ 用户按提示重建完,同一张卡仍然报同一句话(提示指了一条对该卡无效的路)。
953
+ *
954
+ * 本方法**只改** `tasks.session_id`:不碰状态、不碰认领锁(任务可能正被认领,
955
+ * 改指针 ≠ 重开执行)。返回 `{ task, before, after, changed }` 供审计与回滚。
956
+ */
957
+ rebindTaskSession(ref, sessionId) {
958
+ const task = store.requireTaskRef(ref);
959
+ if (!sessionId) throw invalidField("sessionId", "必须提供会话标识");
960
+ const before = task.sessionId ?? null;
961
+ const after = String(sessionId);
962
+ if (before !== after) {
963
+ db.prepare("update tasks set session_id = ?, version = version + 1, updated_at = ? where id = ?").run(after, nowIso(), task.id);
964
+ }
965
+ return { task: store.requireTaskRef(ref), before, after, changed: before !== after };
966
+ },
967
+ defaultProject() {
968
+ const row = db.prepare(
969
+ `select p.* from projects p
970
+ left join (select project_id, max(updated_at) as last from tasks group by project_id) t on t.project_id = p.id
971
+ order by coalesce(t.last, p.updated_at) desc, p.rowid desc limit 1`,
972
+ ).get();
973
+ return rowToProject(row);
974
+ },
975
+ /** 会话 ↔ 项目关联(FR-63):主会话之外,其它会话需申请、由主会话批准。 */
976
+ listProjectSessions(projectId) {
977
+ store.requireProject(projectId);
978
+ return db.prepare("select * from project_sessions where project_id = ? order by created_at, rowid").all(projectId)
979
+ .map((r) => ({ projectId: r.project_id, sessionId: r.session_id, status: r.status, createdAt: r.created_at, updatedAt: r.updated_at }));
980
+ },
981
+ requestSessionAssociation(projectId, sessionId) {
982
+ const project = store.requireProject(projectId);
983
+ if (!sessionId) throw invalidField("sessionId", "必须提供会话标识");
984
+ const ts = nowIso();
985
+ const existing = db.prepare("select status from project_sessions where project_id = ? and session_id = ?").get(project.id, String(sessionId));
986
+ if (existing?.status === "approved") return { projectId: project.id, sessionId: String(sessionId), status: "approved" };
987
+ db.prepare(
988
+ `insert into project_sessions (project_id, session_id, status, created_at, updated_at) values (?,?, 'pending', ?, ?)
989
+ on conflict(project_id, session_id) do update set status = 'pending', updated_at = excluded.updated_at`,
990
+ ).run(project.id, String(sessionId), ts, ts);
991
+ return { projectId: project.id, sessionId: String(sessionId), status: "pending" };
992
+ },
993
+ approveSessionAssociation(projectId, sessionId) {
994
+ const project = store.requireProject(projectId);
995
+ if (!sessionId) throw invalidField("sessionId", "必须提供会话标识");
996
+ const ts = nowIso();
997
+ db.prepare(
998
+ `insert into project_sessions (project_id, session_id, status, created_at, updated_at) values (?,?, 'approved', ?, ?)
999
+ on conflict(project_id, session_id) do update set status = 'approved', updated_at = excluded.updated_at`,
1000
+ ).run(project.id, String(sessionId), ts, ts);
1001
+ return { projectId: project.id, sessionId: String(sessionId), status: "approved" };
1002
+ },
1003
+ /** 该会话是否已绑定该项目:主会话=main;已批准=associated;否则 none/pending。 */
1004
+ sessionBinding(projectId, sessionId) {
1005
+ const project = store.requireProject(projectId);
1006
+ if (sessionId && project.initialSessionId && project.initialSessionId === String(sessionId)) {
1007
+ return { bound: true, role: "main", sessionId: String(sessionId) };
1008
+ }
1009
+ const row = db.prepare("select status from project_sessions where project_id = ? and session_id = ?").get(project.id, String(sessionId ?? ""));
1010
+ if (row?.status === "approved") return { bound: true, role: "associated", sessionId: String(sessionId) };
1011
+ return { bound: false, role: row?.status ?? "none", sessionId: sessionId ? String(sessionId) : null };
1012
+ },
1013
+ /** 反查:某会话归属哪个项目(主会话优先,其次已批准/待批准的关联)。用于 `/api/context?session=` 的项目解析。 */
1014
+ findProjectBySession(sessionId) {
1015
+ const s = String(sessionId ?? "");
1016
+ if (!s) return null;
1017
+ const main = db.prepare("select * from projects where initial_session_id = ? order by rowid limit 1").get(s);
1018
+ if (main) return { project: rowToProject(main), role: "main" };
1019
+ const row = db.prepare("select project_id, status from project_sessions where session_id = ? order by (status = 'approved') desc, rowid desc limit 1").get(s);
1020
+ if (row) return { project: store.requireProject(row.project_id), role: row.status };
1021
+ return null;
1022
+ },
1023
+
1024
+ createTask(input = {}) {
1025
+ const projectId = typeof input.projectId === "string" ? input.projectId : "";
1026
+ if (projectId === "") throw invalidField("projectId", "必须指定项目(--project <项目id>)");
1027
+ store.requireProject(projectId);
1028
+ const title = assertTitle(input.title);
1029
+ const description = normalizeDescription(input.description);
1030
+ // FR-94:添加任务时即记录「完成验收标准 + 复核动作」(真机反馈:便于快速复核)
1031
+ const acceptance = normalizeAcceptance(input.acceptance);
1032
+ const verifyCommand = normalizeTaskVerifyCommand(input.verifyCommand);
1033
+ const status = assertStatus(input.status ?? DEFAULT_STATUS);
1034
+ const priority = assertPriority(input.priority ?? DEFAULT_PRIORITY);
1035
+ const labels = normalizeLabels(input.labels ?? []);
1036
+ const owner = normalizeOwner(input.owner);
1037
+ const parentRef = input.parentId ?? input.parent ?? null;
1038
+ const id = input.id ?? randomUUID();
1039
+ const timestamp = nowIso();
1040
+
1041
+ // ---- P0:归因在**建卡事务内**完成(本轮拍板 D1)----------------------------------
1042
+ // 为什么必须在事务内:`POST /api/tasks` + 事后 `/attribution` 是两步,中间任何失败都会留
1043
+ // 一张无归因卡;2026-10-28 一次全量修补 69 张,其中 56 张真实来源**已不可考**,只能挂兜底条目。
1044
+ // 形状:requirement(归因)与 unattributedReason(显式声明不归因)**二选一**,都给是用法错误。
1045
+ const requirementRefRaw = input.requirementId ?? input.requirement ?? null;
1046
+ const requirementRef = requirementRefRaw == null ? "" : String(requirementRefRaw).trim();
1047
+ const unattributedReason = normalizeUnattributedReason(input.unattributedReason);
1048
+ if (requirementRef !== "" && unattributedReason) {
1049
+ throw new TbError("USAGE_ERROR", "requirement 与 unattributedReason 不能同时给:要么归属需求条目,要么显式声明不归因");
1050
+ }
1051
+ if (requirementRef === "" && !unattributedReason && strictAttribution) {
1052
+ throw new TbError("REQUIREMENT_REQUIRED", "建卡必须归属需求条目:请给 requirement <条目>;确实不需要归属时用 unattributedReason <理由> 显式声明(会落审计)", { projectId });
1053
+ }
1054
+
1055
+ let requirementId = null; // 事务内解析、事务外留痕(故声明在 try 之外)
1056
+
1057
+ db.exec("begin immediate");
1058
+ try {
1059
+ let parentId = null;
1060
+ if (parentRef) {
1061
+ const parent = store.requireTaskRef(parentRef);
1062
+ assertParentLink({ id, projectId, parentId: null }, parent);
1063
+ assertNoCycle(id, parent.id, (candidate) => store.getTaskById(candidate));
1064
+ parentId = parent.id;
1065
+ }
1066
+ // 归因校验必须在**同一事务内**:条目不存在 / 跨项目 ⇒ 整笔回滚(连 next_seq 一起回滚,
1067
+ // 不留编号空洞、不留孤儿卡)。
1068
+ if (requirementRef !== "") {
1069
+ const item = store.requireRequirementItemRef(requirementRef);
1070
+ if (item.projectId !== projectId) {
1071
+ throw new TbError("DEPENDENCY_CROSS_PROJECT", `条目与任务必须同项目(条目 ${item.projectId},任务 ${projectId})`, { requirementProjectId: item.projectId, taskProjectId: projectId });
1072
+ }
1073
+ requirementId = item.id;
1074
+ }
1075
+ const project = db.prepare("select * from projects where id = ?").get(projectId);
1076
+ const sequence = project.next_seq;
1077
+ const identifier = formatIdentifier(projectId, sequence);
1078
+ db.prepare("update projects set next_seq = ?, updated_at = ? where id = ?").run(sequence + 1, timestamp, projectId);
1079
+ db.prepare(
1080
+ `insert into tasks (id, identifier, project_id, title, description, acceptance, verify_command, status, priority, labels, owner, parent_id, requirement_id, version, created_at, updated_at)
1081
+ values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)`,
1082
+ ).run(id, identifier, projectId, title, description, acceptance, verifyCommand, status, priority, JSON.stringify(labels), owner, parentId, requirementId, timestamp, timestamp);
1083
+ db.exec("commit");
1084
+ } catch (error) {
1085
+ db.exec("rollback");
1086
+ if (isConstraintError(error, "tasks.identifier")) throw new TbError("IDENTIFIER_CONFLICT", "可读编号冲突,请重试", { projectId });
1087
+ throw error;
1088
+ }
1089
+ // FR-82:任务生命周期变化写入追加式事件流(详情 / 看护 / 通知共同消费)
1090
+ store.recordTaskEvent(id, { type: "created", to: status, actor: "human", detail: `创建任务(${status})` });
1091
+ // P0 归因留痕:三种落法都要能事后盘点(这是「逃生口」与「漏填」的唯一区别所在)
1092
+ if (requirementId) {
1093
+ store.recordTaskEvent(id, { type: "attributed", to: status, actor: "human", detail: `建卡即归属需求条目(${requirementId})` });
1094
+ } else if (unattributedReason) {
1095
+ store.recordTaskEvent(id, { type: "attribution_skipped", to: status, actor: "human", detail: `建卡未归属需求条目(显式声明:${unattributedReason})` });
1096
+ } else {
1097
+ store.recordTaskEvent(id, { type: "attribution_missing", to: status, actor: "human", detail: "建卡未归属需求条目(未声明理由)—— 启动执行/派发团队会被归因门拒绝" });
1098
+ }
1099
+ return store.getTaskById(id);
1100
+ },
1101
+
1102
+ getTaskRef(ref) {
1103
+ if (typeof ref !== "string" || ref.trim() === "") return null;
1104
+ const value = ref.trim();
1105
+ return store.getTaskById(value) ?? store.getTaskByIdentifier(value);
1106
+ },
1107
+
1108
+ requireTaskRef(ref) {
1109
+ const task = store.getTaskRef(ref);
1110
+ if (!task) throw new TbError("TASK_NOT_FOUND", `任务不存在:${ref}`, { ref });
1111
+ return task;
1112
+ },
1113
+
1114
+ getTaskById(id) {
1115
+ if (typeof id !== "string" || id === "") return null;
1116
+ return rowToTask(db.prepare("select * from tasks where id = ?").get(id));
1117
+ },
1118
+
1119
+ getTaskByIdentifier(identifier) {
1120
+ if (typeof identifier !== "string" || !parseIdentifier(identifier)) return null;
1121
+ return rowToTask(db.prepare("select * from tasks where identifier = ?").get(identifier));
1122
+ },
1123
+
1124
+ listTasks(filter = {}) {
1125
+ const clauses = [];
1126
+ const params = [];
1127
+ if (filter.projectId) {
1128
+ clauses.push("project_id = ?");
1129
+ params.push(filter.projectId);
1130
+ }
1131
+ // FR-26 / FR-28:会话归属维度(与 FR-13 的其它维度取交集)。
1132
+ // 归属判据=`session_id`(该列只在认领 / 启动执行时写入,FR-25,无需人工填写)。四档:
1133
+ // · `linked` —— 有没有关联会话(FR-26:「已关联」)
1134
+ // · `unlinked` —— 有没有关联会话(FR-26:「未关联」)
1135
+ // · `session:<id>` —— 关联的是**不是这一个具体会话**(FR-28:「仅本会话」,`session_id = <id>`)
1136
+ // 缺省(undefined/null/"")=「全部」,不加任何条件。
1137
+ // 非法值(含空 id 的 `session:`)**如实报错**,不得静默降级成「全部」。
1138
+ if (filter.sessionScope !== undefined && filter.sessionScope !== null && filter.sessionScope !== "") {
1139
+ const scope = String(filter.sessionScope);
1140
+ if (scope === "linked") clauses.push("(session_id is not null and session_id != '')");
1141
+ else if (scope === "unlinked") clauses.push("(session_id is null or session_id = '')");
1142
+ else if (scope.startsWith("session:")) {
1143
+ const wanted = scope.slice("session:".length).trim();
1144
+ if (wanted === "") throw invalidField("sessionScope", `sessionScope 的 session:<会话标识> 形式必须带非空会话标识,收到:${JSON.stringify(filter.sessionScope)}`);
1145
+ clauses.push("session_id = ?");
1146
+ params.push(wanted);
1147
+ } else throw invalidField("sessionScope", `sessionScope 必须是 linked / unlinked / session:<会话标识> 之一,收到:${JSON.stringify(filter.sessionScope)}`);
1148
+ }
1149
+ if (filter.status !== undefined && filter.status !== null) {
1150
+ clauses.push("status = ?");
1151
+ params.push(assertStatus(filter.status));
1152
+ }
1153
+ if (filter.priority !== undefined && filter.priority !== null) {
1154
+ clauses.push("priority = ?");
1155
+ params.push(assertPriority(filter.priority));
1156
+ }
1157
+ if (filter.owner !== undefined && filter.owner !== null) {
1158
+ const owner = normalizeOwner(filter.owner);
1159
+ if (owner === null) clauses.push("(owner is null or owner = '')");
1160
+ else {
1161
+ clauses.push("owner = ?");
1162
+ params.push(owner);
1163
+ }
1164
+ }
1165
+ if (filter.parentId !== undefined) {
1166
+ if (filter.parentId === null) clauses.push("parent_id is null");
1167
+ else {
1168
+ clauses.push("parent_id = ?");
1169
+ params.push(filter.parentId);
1170
+ }
1171
+ }
1172
+ const where = clauses.length ? `where ${clauses.join(" and ")}` : "";
1173
+ // FR-11 / FR-15:**列内手工顺序优先**。排序键 `(board_position is null, board_position, created_at, rowid)`:
1174
+ // · 手工排过的卡(`board_position` 非空)按人工顺序在前;从未排过的卡保持"创建顺序"接在后面。
1175
+ // · `board_position` 只在**列内**有意义(同 status 的卡共享一个 0..n-1 序列);跨状态取数时各列
1176
+ // 位置会交叠,但前端按状态分列渲染,列内相对顺序即人工顺序 —— 这正是 FR-11 要的口径。
1177
+ // · 该 ORDER BY 对"全部为空"的库**与旧的 `order by created_at, rowid` 逐行等价**(不影响既有行为)。
1178
+ let tasks = db.prepare(`select * from tasks ${where} order by (board_position is null), board_position, created_at, rowid`).all(...params).map(rowToTask);
1179
+ // FR-14:关键词搜索 —— 与上面各维度**取交集**(同一取数路径,不另开分支)。
1180
+ // 覆盖「任务编号 / 标题 / 描述 / 标签」四类字段,大小写不敏感。
1181
+ // 口径:缺省(undefined/null/空串/纯空白)=不搜索(等价于「全部」);
1182
+ // 非字符串入参**如实报错**,不静默当成「不搜索」。
1183
+ if (filter.q !== undefined && filter.q !== null) {
1184
+ if (typeof filter.q !== "string") throw invalidField("q", `搜索关键词 q 必须是字符串,收到:${JSON.stringify(filter.q)}`);
1185
+ const keyword = filter.q.trim().toLowerCase();
1186
+ if (keyword !== "") tasks = tasks.filter((task) => taskMatchesKeyword(task, keyword));
1187
+ }
1188
+ const wantedLabels = normalizeLabels(filter.labels ?? []);
1189
+ if (wantedLabels.length > 0) tasks = tasks.filter((task) => wantedLabels.every((label) => task.labels.includes(label)));
1190
+ // FR-15:`sort=priority` = 优先级档,**覆盖**手工顺序(这是"两档排序"里的另一档,二者互斥地主导顺序);
1191
+ // 缺省(含 `created`)=默认档,即 FR-15 的「默认顺序(由人工拖拽/创建顺序决定)」。
1192
+ if (filter.sort === "priority") tasks = tasks.slice().sort(compareByPriority);
1193
+ return tasks;
1194
+ },
1195
+
1196
+ updateTask(ref, changes = {}) {
1197
+ const current = store.requireTaskRef(ref);
1198
+ const { expectedVersion } = changes;
1199
+ if (expectedVersion === undefined || expectedVersion === null) {
1200
+ throw new TbError("MISSING_VERSION", "更新必须提供 expectedVersion(我读到的版本)", { taskId: current.id, currentVersion: current.version });
1201
+ }
1202
+ if (!Number.isInteger(expectedVersion) || expectedVersion < 1) throw invalidField("expectedVersion", "expectedVersion 必须是 ≥1 的整数");
1203
+ if (expectedVersion !== current.version) {
1204
+ throw new TbError("VERSION_CONFLICT", "任务已被他人修改,请重新读取后再提交", {
1205
+ taskId: current.id, identifier: current.identifier, expectedVersion, currentVersion: current.version,
1206
+ });
1207
+ }
1208
+
1209
+ const actor = assertActor(changes.actor ?? "human");
1210
+ const nextStatus = changes.status === undefined ? current.status : assertStatus(changes.status);
1211
+ // FR-85b:人工校验任务是升级门,不是交付物 —— 不得被置「完成」;
1212
+ // 它的唯一出口是 concludeHumanReview(结论给出后任务自动转「已取消」)。
1213
+ if (nextStatus === "done" && nextStatus !== current.status && isHumanReviewTask(current)) {
1214
+ try { store.recordAudit({ actor, action: "set-status", target: current.identifier, allowed: false, reason: "human-review-cannot-done", detail: "人工校验任务不得置 done,请用人工结论入口" }); } catch { /* ignore */ }
1215
+ throw new TbError("HUMAN_REVIEW_CANNOT_DONE", `任务 ${current.identifier} 是人工校验任务:不得置「完成」,请用人工结论入口(continue / change-requirement / close)`, { identifier: current.identifier });
1216
+ }
1217
+ // FR-83 补口(2026-10-27 · 卡 `-162`,人拍板口径 **C:门 + 显式逃生口**):
1218
+ // `in_review → done` 必须**评审通过**,默认拒(退出码 5 冲突类,**零副作用** —— 门在 `begin` 之前)。
1219
+ //
1220
+ // 原先为何没有这道门(-158 的登记理由仍成立,只是裁定改了):FR-83 验收原文只约束「评审通过
1221
+ // **不自动**置完成」(红线是**不得自动化**),并未要求「完成必须先评审通过」⇒ 属口径选择。
1222
+ // 裁定前 `PATCH /api/tasks/:ref` 对评审态**无任何校验**:拖拽落到「完成」列就能把未评审的卡静默收口
1223
+ // (卡片「→」/ 抽屉「下一列」已由 -158 收敛,拖拽是剩下的那条)。
1224
+ //
1225
+ // 口径边界(三条,刻意如此):
1226
+ // · **只约束「从待验收收口」**:从未请求过评审的卡(`todo → done`)照旧可完成;
1227
+ // `in_review → blocked/canceled/todo`(受阻、取消、退回返工)不受影响 —— 它们不是收口。
1228
+ // · **逃生口是显式的**:`skipReview === true`(严格布尔;字符串 `"true"` 一律不算)才放行。
1229
+ // 人有权跳过评审(完成只能人确认),但必须是**明示的一次决定**,不能是位移动作的副作用;
1230
+ // 放行后落审计 + 事件留痕(`review_skipped`),事后可回看。
1231
+ // · **不看 `actor`**:这道门只问"这张卡的评审态够不够格收口";"自动化不得写 done"的红线在
1232
+ // `governance` 与 `teamSetTaskStatus` 里,两件事不混。
1233
+ const skipReview = changes.skipReview === true;
1234
+ const closingWithoutApproval = nextStatus === "done" && nextStatus !== current.status
1235
+ && current.status === "in_review" && current.reviewState !== "approved";
1236
+ if (closingWithoutApproval && !skipReview) {
1237
+ try { store.recordAudit({ actor, action: "set-status", target: current.identifier, allowed: false, reason: "review-not-approved", detail: `review_state=${current.reviewState ?? "null"} → done 被拒` }); } catch { /* ignore */ }
1238
+ throw new TbError(
1239
+ "REVIEW_NOT_APPROVED",
1240
+ `任务 ${current.identifier} 还在「待验收」且评审未通过(review_state=${current.reviewState ?? "pending"}):请先「评审通过」再置「完成」;确需跳过评审,请显式提交 skipReview=true`,
1241
+ { identifier: current.identifier, reviewState: current.reviewState ?? null, status: current.status, nextStatus },
1242
+ );
1243
+ }
1244
+ const nextPriority = changes.priority === undefined ? current.priority : assertPriority(changes.priority);
1245
+ const nextTitle = changes.title === undefined ? current.title : assertTitle(changes.title);
1246
+ const nextDescription = changes.description === undefined ? current.description : normalizeDescription(changes.description);
1247
+ // FR-94:验收标准 / 复核动作可编辑(显式传空串即清空;复核动作清空 ⇒ 回落项目设置)
1248
+ const nextAcceptance = changes.acceptance === undefined ? (current.acceptance ?? "") : normalizeAcceptance(changes.acceptance);
1249
+ const nextVerifyCommand = changes.verifyCommand === undefined ? (current.verifyCommand ?? null) : normalizeTaskVerifyCommand(changes.verifyCommand);
1250
+ const nextOwner = changes.owner === undefined ? current.owner : normalizeOwner(changes.owner);
1251
+
1252
+ let nextLabels = current.labels;
1253
+ if (changes.labels !== undefined) nextLabels = normalizeLabels(changes.labels);
1254
+ else if (changes.addLabels !== undefined || changes.removeLabels !== undefined) {
1255
+ const merged = new Set(current.labels);
1256
+ for (const label of normalizeLabels(changes.addLabels ?? [])) merged.add(label);
1257
+ for (const label of normalizeLabels(changes.removeLabels ?? [])) merged.delete(label);
1258
+ nextLabels = normalizeLabels([...merged]);
1259
+ }
1260
+ nextLabels = nextLabels.filter((label) => !String(label).startsWith("owner:"));
1261
+
1262
+ const governance = checkGovernance({ actor, from: current.status, to: nextStatus }, store.policy);
1263
+ if (governance) throw governance;
1264
+
1265
+ let nextParentId = current.parentId;
1266
+ if (changes.parentId !== undefined || changes.clearParent === true) {
1267
+ if (changes.clearParent === true || changes.parentId === null) nextParentId = null;
1268
+ else {
1269
+ const parent = store.requireTaskRef(changes.parentId);
1270
+ assertParentLink({ id: current.id, projectId: current.projectId, parentId: current.parentId }, parent);
1271
+ assertNoCycle(current.id, parent.id, (candidate) => store.getTaskById(candidate));
1272
+ nextParentId = parent.id;
1273
+ }
1274
+ }
1275
+
1276
+ const timestamp = nowIso();
1277
+ // FR-78:任务级熔断阈值可编辑(整数 ≥1 或 null=回落到默认)
1278
+ let nextMaxRetries = current.maxRetries ?? null;
1279
+ if (changes.maxRetries !== undefined) {
1280
+ if (changes.maxRetries === null || changes.maxRetries === "") nextMaxRetries = null;
1281
+ else {
1282
+ const n = Number(changes.maxRetries);
1283
+ if (!Number.isInteger(n) || n < 1) throw invalidField("maxRetries", "maxRetries 必须是 ≥1 的整数,或 null");
1284
+ nextMaxRetries = n;
1285
+ }
1286
+ }
1287
+ // FR-77 口径对齐 `teamSetTaskStatus`:**状态离开「进行中」即释放认领**。
1288
+ // 此前人工/看板 PATCH 不走这条规则 —— 真机现场(2026-10-18)`-63`/`-69` 已进「待验收」却仍锁着
1289
+ // 一把过期认领,而回收器只扫 `in_progress`,那把锁永远没人清(幽灵在途)。
1290
+ const releaseClaim = nextStatus === "in_progress" ? "" : ", claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null";
1291
+ // FR-11:跨列移动(仅改状态、没带落点)⇒ **清空手工位置**。旧列的位置数字是**列内**坐标,
1292
+ // 带着它进新列会插到新列中间(看着像"随机插入");清空后按 created_at 落在新列的"未手工排过"段,
1293
+ // 这是"按钮换列"这条路径下唯一不臆断的落点。带落点的拖拽则由下面 resolveBoardOrder 显式定位。
1294
+ const clearOrder = nextStatus !== current.status ? ", board_position = null" : "";
1295
+ // FR-11 + 门序(`tests/gate-before-side-effects.test.mjs` 同一口径):**落点必须先解析、后写库**。
1296
+ // `resolveBoardOrder` 会因「锚点不存在 / 跨列 / 非法下标」抛错 —— 若等主 UPDATE 之后再解析,
1297
+ // 被拒的拖拽就已经把状态改了、版本涨了(门后于副作用),正是那条红线要钉死的情形。
1298
+ // 错误一律在 `begin` 之前抛出 ⇒ 连事务都不开,一个字段都不写。
1299
+ const order = changes.boardPosition !== undefined
1300
+ ? resolveBoardOrder(db, { taskId: current.id, projectId: current.projectId, status: nextStatus, desiredIndex: changes.boardPosition })
1301
+ : null;
1302
+ db.exec("begin immediate");
1303
+ try {
1304
+ db.prepare(
1305
+ `update tasks set title = ?, description = ?, acceptance = ?, verify_command = ?, status = ?, priority = ?, labels = ?, owner = ?,
1306
+ parent_id = ?, max_retries = ?, blocked_at = ?${releaseClaim}${clearOrder}, version = version + 1, updated_at = ? where id = ? and version = ?`,
1307
+ ).run(nextTitle, nextDescription, nextAcceptance, nextVerifyCommand, nextStatus, nextPriority, JSON.stringify(nextLabels), nextOwner,
1308
+ nextParentId, nextMaxRetries,
1309
+ // FR-79:受阻起始时间(人工置"受阻"也记;离开受阻即清空)
1310
+ nextStatus === "blocked" ? (current.blockedAt ?? timestamp) : null,
1311
+ timestamp, current.id, expectedVersion);
1312
+ // FR-11:显式落点(拖拽)写回 —— 放在状态更新**之后**,才能把卡放进"目标列"的正确下标
1313
+ // (列集合此刻已含它自己)。状态与位置是**同一次** PATCH 的两个字段,必须同生共死 ⇒ 同一事务。
1314
+ if (order) applyBoardOrder(db, order.ordered);
1315
+ db.exec("commit");
1316
+ } catch (error) {
1317
+ db.exec("rollback");
1318
+ throw error;
1319
+ }
1320
+ if (nextStatus !== current.status) {
1321
+ // FR-82:状态变化 → 事件流追加(不再让各处各自造"状态历史")。
1322
+ // 注意:**纯列内排序不写任何事件** —— 版式调整不是任务生命周期事件,塞进去只会污染事件流与通知口径。
1323
+ store.recordTaskEvent(current.id, { type: "status_changed", from: current.status, to: nextStatus, actor: changes.actor ?? "human" });
1324
+ }
1325
+ // FR-83 补口(卡 `-162`):逃生口放行后必须**可回看** —— 这是"人显式决定跳过评审"的取证点,
1326
+ // 否则事后只看到一张 done 卡,分不清"评审通过后收口"与"跳过评审收口"。
1327
+ if (closingWithoutApproval && skipReview) {
1328
+ store.recordTaskEvent(current.id, {
1329
+ type: "review_skipped", from: "in_review", to: "done", actor,
1330
+ detail: `跳过评审直接完成(review_state=${current.reviewState ?? "null"})`,
1331
+ });
1332
+ try { store.recordAudit({ actor, action: "set-status", target: current.identifier, allowed: true, reason: "review-skipped", detail: `skipReview=true(review_state=${current.reviewState ?? "null"})` }); } catch { /* ignore */ }
1333
+ }
1334
+ // 返回形状与其它路径一致(就是任务本身;`boardPosition` 是它的一个正式字段,前端重取即见)。
1335
+ return store.getTaskById(current.id);
1336
+ },
1337
+
1338
+ deleteTask(ref, { expectedVersion } = {}) {
1339
+ const current = store.requireTaskRef(ref);
1340
+ if (expectedVersion === undefined || expectedVersion === null) {
1341
+ throw new TbError("MISSING_VERSION", "删除必须提供 expectedVersion(我读到的版本)", { taskId: current.id, currentVersion: current.version });
1342
+ }
1343
+ if (expectedVersion !== current.version) {
1344
+ throw new TbError("VERSION_CONFLICT", "任务已被他人修改,请重新读取后再删除", {
1345
+ taskId: current.id, expectedVersion, currentVersion: current.version,
1346
+ });
1347
+ }
1348
+ db.prepare("delete from tasks where id = ?").run(current.id);
1349
+ return { id: current.id, identifier: current.identifier, deleted: true };
1350
+ },
1351
+
1352
+ addComment(ref, input = {}) {
1353
+ const task = store.requireTaskRef(ref);
1354
+ const body = normalizeDescription(input.body);
1355
+ const id = input.id ?? randomUUID();
1356
+ const timestamp = nowIso();
1357
+ db.prepare(`insert into comments (id, task_id, body, version, created_at, updated_at) values (?, ?, ?, 1, ?, ?)`)
1358
+ .run(id, task.id, body, timestamp, timestamp);
1359
+ return rowToComment(db.prepare("select * from comments where id = ?").get(id));
1360
+ },
1361
+
1362
+ listComments(ref) {
1363
+ const task = store.requireTaskRef(ref);
1364
+ return db.prepare(COMMENT_SELECT + " where c.task_id = ? order by c.created_at, c.rowid").all(task.id).map(rowToComment);
1365
+ },
1366
+
1367
+ /** 单条评论(FR-17 编辑入口要先读到 `version` 才能带乐观锁提交)。 */
1368
+ getComment(commentId) {
1369
+ if (typeof commentId !== "string" || commentId === "") return null;
1370
+ return rowToComment(db.prepare(COMMENT_SELECT + " where c.id = ?").get(commentId));
1371
+ },
1372
+
1373
+ /**
1374
+ * FR-17:编辑一条评论(**不静默覆盖**)。
1375
+ *
1376
+ * 三条纪律:
1377
+ * 1. **乐观锁**:必须带 `expectedVersion`(= 我读到的 `comment.version`),写时用
1378
+ * `where id = ? and version = ?` 做 CAS;冲突抛 `VERSION_CONFLICT`(退出码 5),绝不覆盖。
1379
+ * 2. **留痕**:编辑前先把**原正文原样**写进 `comment_revisions`(rev = 被取代的那一版),
1380
+ * 所以"原内容"是**可回看的历史**,而不是一句"已编辑 N 次"的声明。
1381
+ * 3. **证据红线**:机器产出的证据评论(`【自动复核】…`)**只读**;且**不得把普通评论改成
1382
+ * 证据形态**(否则等于伪造评审证据)。见 `assertCommentEditable`。
1383
+ *
1384
+ * 正文与当前完全一致时视为无变化:不涨版本、不留痕(避免空编辑刷版本)。
1385
+ */
1386
+ updateComment(commentId, { expectedVersion, body, actor = "human" } = {}) {
1387
+ const row = db.prepare(COMMENT_SELECT + " where c.id = ?").get(commentId);
1388
+ if (!row) throw new TbError("COMMENT_NOT_FOUND", `评论不存在:${commentId}`, { commentId });
1389
+ const current = rowToComment(row);
1390
+ if (expectedVersion === undefined || expectedVersion === null) {
1391
+ throw new TbError("MISSING_VERSION", "编辑评论必须提供 expectedVersion(我读到的版本)", { commentId, currentVersion: current.version });
1392
+ }
1393
+ if (!Number.isInteger(expectedVersion) || expectedVersion < 1) throw invalidField("expectedVersion", "expectedVersion 必须是 ≥1 的整数");
1394
+ if (expectedVersion !== current.version) {
1395
+ throw new TbError("VERSION_CONFLICT", "评论已被他人修改,请重新读取后再提交(不静默覆盖)", {
1396
+ commentId, expectedVersion, currentVersion: current.version,
1397
+ });
1398
+ }
1399
+ const nextBody = normalizeDescription(body);
1400
+ assertCommentEditable(current.body, nextBody, commentId);
1401
+ if (nextBody === current.body) return { comment: current, changed: false, revision: null };
1402
+
1403
+ const timestamp = nowIso();
1404
+ const revisions = Number(db.prepare("select count(*) as n from comment_revisions where comment_id = ?").get(commentId)?.n ?? 0);
1405
+ // 留痕:存**编辑前**的正文(rev 从 1 起;列表按 rev 升序 = 历史回放顺序)
1406
+ db.prepare("insert into comment_revisions (id, comment_id, rev, body, edited_at, edited_by) values (?, ?, ?, ?, ?, ?)")
1407
+ .run(randomUUID(), commentId, revisions + 1, current.body, timestamp, actor);
1408
+ const res = db.prepare("update comments set body = ?, version = version + 1, updated_at = ?, edited_at = ?, edited_by = ? where id = ? and version = ?")
1409
+ .run(nextBody, timestamp, timestamp, actor, commentId, expectedVersion);
1410
+ if (res.changes !== 1) {
1411
+ // CAS 兜底(极端并发):回滚刚写的留痕行,保持"未发生"。
1412
+ db.prepare("delete from comment_revisions where comment_id = ? and rev = ?").run(commentId, revisions + 1);
1413
+ throw new TbError("VERSION_CONFLICT", "评论已被他人修改,请重新读取后再提交(不静默覆盖)", {
1414
+ commentId, expectedVersion, currentVersion: Number(db.prepare("select version from comments where id = ?").get(commentId)?.version ?? 0),
1415
+ });
1416
+ }
1417
+ const comment = store.getComment(commentId);
1418
+ store.recordTaskEvent(row.task_id, { type: "comment_edited", to: "edited", actor, detail: `编辑评论(第 ${revisions + 1} 次;原正文已留痕)` });
1419
+ return { comment, changed: true, revision: store.listCommentRevisions(commentId).at(-1) };
1420
+ },
1421
+
1422
+ /** 评论编辑历史(按 rev 升序;最后一个 = 上一版正文)。 */
1423
+ listCommentRevisions(commentId) {
1424
+ if (typeof commentId !== "string" || commentId === "") return [];
1425
+ return db.prepare("select * from comment_revisions where comment_id = ? order by rev").all(commentId).map(rowToCommentRevision);
1426
+ },
1427
+
1428
+ deleteComment(commentId) {
1429
+ const row = db.prepare("select * from comments where id = ?").get(commentId);
1430
+ if (!row) throw new TbError("COMMENT_NOT_FOUND", `评论不存在:${commentId}`, { commentId });
1431
+ db.prepare("delete from comments where id = ?").run(commentId);
1432
+ return { id: commentId, deleted: true };
1433
+ },
1434
+
1435
+ // ---------------------------------------------------------------- 需求文档(FR-34)
1436
+ getRequirementDoc(projectId) {
1437
+ if (typeof projectId !== "string" || projectId === "") return null;
1438
+ return rowToRequirementDoc(db.prepare("select * from requirement_docs where project_id = ?").get(projectId));
1439
+ },
1440
+ getRequirementDocById(id) {
1441
+ if (typeof id !== "string" || id === "") return null;
1442
+ return rowToRequirementDoc(db.prepare("select * from requirement_docs where id = ?").get(id));
1443
+ },
1444
+ listRequirementDocs(filter = {}) {
1445
+ const rows = filter.projectId
1446
+ ? db.prepare("select * from requirement_docs where project_id = ? order by created_at, rowid").all(filter.projectId)
1447
+ : db.prepare("select * from requirement_docs order by created_at, rowid").all();
1448
+ return rows.map(rowToRequirementDoc);
1449
+ },
1450
+ ensureRequirementDoc(projectId, { body = "" } = {}) {
1451
+ store.requireProject(projectId);
1452
+ const existing = store.getRequirementDoc(projectId);
1453
+ if (existing) return existing;
1454
+ const id = randomUUID();
1455
+ const ts = nowIso();
1456
+ db.prepare("insert into requirement_docs (id, project_id, body, version, created_at, updated_at) values (?, ?, ?, 1, ?, ?)")
1457
+ .run(id, projectId, String(body), ts, ts);
1458
+ return store.getRequirementDoc(projectId);
1459
+ },
1460
+ updateRequirementDoc(ref, changes = {}) {
1461
+ const doc = store.getRequirementDocById(ref) ?? store.getRequirementDoc(ref);
1462
+ if (!doc) throw new TbError("REQUIREMENT_DOC_NOT_FOUND", `需求文档不存在:${ref}`, { ref });
1463
+ const { expectedVersion } = changes;
1464
+ if (expectedVersion === undefined || expectedVersion === null) {
1465
+ throw new TbError("MISSING_VERSION", "更新需求文档必须提供 expectedVersion(我读到的版本)", { docId: doc.id, currentVersion: doc.version });
1466
+ }
1467
+ if (!Number.isInteger(expectedVersion) || expectedVersion < 1) throw invalidField("expectedVersion", "expectedVersion 必须是 ≥1 的整数");
1468
+ if (expectedVersion !== doc.version) {
1469
+ throw new TbError("VERSION_CONFLICT", "需求文档已被他人修改,请重新读取后再提交", { docId: doc.id, expectedVersion, currentVersion: doc.version });
1470
+ }
1471
+ const body = changes.body === undefined ? doc.body : String(changes.body);
1472
+ db.prepare("update requirement_docs set body = ?, version = version + 1, updated_at = ? where id = ? and version = ?")
1473
+ .run(body, nowIso(), doc.id, expectedVersion);
1474
+ return store.getRequirementDocById(doc.id);
1475
+ },
1476
+
1477
+ // ---------------------------------------------------------------- 需求条目(FR-35)
1478
+ getRequirementItemRef(ref) {
1479
+ if (typeof ref !== "string" || ref.trim() === "") return null;
1480
+ const value = ref.trim();
1481
+ return store.getRequirementItemById(value) ?? store.getRequirementItemByIdentifier(value);
1482
+ },
1483
+ requireRequirementItemRef(ref) {
1484
+ const item = store.getRequirementItemRef(ref);
1485
+ if (!item) throw new TbError("REQUIREMENT_NOT_FOUND", `需求条目不存在:${ref}`, { ref });
1486
+ return item;
1487
+ },
1488
+ getRequirementItemById(id) {
1489
+ if (typeof id !== "string" || id === "") return null;
1490
+ return rowToRequirementItem(db.prepare("select * from requirement_items where id = ?").get(id));
1491
+ },
1492
+ getRequirementItemByIdentifier(identifier) {
1493
+ if (typeof identifier !== "string" || !parseRequirementIdentifier(identifier)) return null;
1494
+ return rowToRequirementItem(db.prepare("select * from requirement_items where identifier = ?").get(identifier));
1495
+ },
1496
+ listRequirementItems(filter = {}) {
1497
+ const clauses = []; const params = [];
1498
+ if (filter.projectId) { clauses.push("project_id = ?"); params.push(filter.projectId); }
1499
+ if (filter.docId) { clauses.push("doc_id = ?"); params.push(filter.docId); }
1500
+ if (filter.status) { clauses.push("status = ?"); params.push(assertRequirementStatus(filter.status)); }
1501
+ const where = clauses.length ? `where ${clauses.join(" and ")}` : "";
1502
+ return db.prepare(`select * from requirement_items ${where} order by created_at, rowid`).all(...params).map(rowToRequirementItem);
1503
+ },
1504
+ createRequirementItem(input = {}) {
1505
+ const projectId = typeof input.projectId === "string" ? input.projectId : "";
1506
+ if (projectId === "") throw invalidField("projectId", "必须指定项目(--project <项目id>)");
1507
+ store.requireProject(projectId);
1508
+ const title = assertTitle(input.title);
1509
+ const description = normalizeDescription(input.description);
1510
+ const acceptance = input.acceptance == null ? "" : String(input.acceptance);
1511
+ const priority = assertPriority(input.priority ?? DEFAULT_PRIORITY);
1512
+ const status = input.status == null ? "open" : assertRequirementStatus(input.status);
1513
+ const source = assertRequirementSource(input.source ?? "manual");
1514
+ let docId = null;
1515
+ if (input.docId) {
1516
+ const doc = store.getRequirementDocById(input.docId);
1517
+ if (!doc) throw new TbError("REQUIREMENT_DOC_NOT_FOUND", `需求文档不存在:${input.docId}`, { docId: input.docId });
1518
+ docId = doc.id;
1519
+ }
1520
+ const id = input.id ?? randomUUID();
1521
+ const ts = nowIso();
1522
+ db.exec("begin immediate");
1523
+ try {
1524
+ insertRequirementItem(db, { id, projectId, docId, title, description, acceptance, priority, status, source, ts });
1525
+ db.exec("commit");
1526
+ } catch (error) {
1527
+ db.exec("rollback");
1528
+ if (isConstraintError(error, "requirement_items.identifier")) throw new TbError("REQ_IDENTIFIER_CONFLICT", "需求条目编号冲突,请重试", { projectId });
1529
+ throw error;
1530
+ }
1531
+ return store.getRequirementItemById(id);
1532
+ },
1533
+ /** 更新需求条目(状态/标题/说明/验收/优先级)——资料引入后的"确认/修订"。 */
1534
+ updateRequirementItem(ref, changes = {}) {
1535
+ const item = store.requireRequirementItemRef(ref);
1536
+ const sets = []; const params = [];
1537
+ if (changes.title !== undefined) { sets.push("title = ?"); params.push(assertTitle(changes.title)); }
1538
+ if (changes.description !== undefined) { sets.push("description = ?"); params.push(normalizeDescription(changes.description)); }
1539
+ if (changes.acceptance !== undefined) { sets.push("acceptance = ?"); params.push(String(changes.acceptance)); }
1540
+ if (changes.priority !== undefined) { sets.push("priority = ?"); params.push(assertPriority(changes.priority)); }
1541
+ if (changes.status !== undefined) { sets.push("status = ?"); params.push(assertRequirementStatus(changes.status)); }
1542
+ // FR-91 补口:条目 ↔ 需求文档的**关联**此前无法修改(引入资料时一次性写入、之后只能删),
1543
+ // 真机上就出现了「条目没关联到需求文档」却补不回来的死结。这里补上(docId=null 表示解除关联)。
1544
+ if (changes.docId !== undefined) {
1545
+ if (changes.docId === null || changes.docId === "") { sets.push("doc_id = ?"); params.push(null); }
1546
+ else {
1547
+ const doc = store.getRequirementDocById(String(changes.docId));
1548
+ if (!doc) throw new TbError("REQUIREMENT_DOC_NOT_FOUND", `需求文档不存在:${changes.docId}`, { docId: changes.docId });
1549
+ sets.push("doc_id = ?"); params.push(doc.id);
1550
+ }
1551
+ }
1552
+ if (!sets.length) return item;
1553
+ sets.push("updated_at = ?"); params.push(nowIso());
1554
+ db.prepare(`update requirement_items set ${sets.join(", ")} where id = ?`).run(...params, item.id);
1555
+ return store.getRequirementItemById(item.id);
1556
+ },
1557
+ /** 删除需求条目(资料引入误建 / 收编合并时清理)。 */
1558
+ deleteRequirementItem(ref) {
1559
+ const item = store.requireRequirementItemRef(ref);
1560
+ db.prepare("delete from requirement_items where id = ?").run(item.id);
1561
+ return { identifier: item.identifier, deleted: true };
1562
+ },
1563
+
1564
+ // ---------------------------------------------------------------- 可行性门(FR-37,追加字段)
1565
+ setRequirementFeasibility(ref, changes = {}) {
1566
+ const item = store.requireRequirementItemRef(ref);
1567
+ const verdict = assertFeasibilityVerdict(changes.verdict);
1568
+ const reason = changes.reason == null ? "" : String(changes.reason);
1569
+ const by = changes.by === "human" ? "human" : "machine";
1570
+ const override = changes.override == null ? null : String(changes.override);
1571
+ db.prepare(
1572
+ "update requirement_items set feasibility = ?, feasibility_reason = ?, feasibility_by = ?, feasibility_override = ?, updated_at = ? where id = ?",
1573
+ ).run(verdict, reason, by, override, nowIso(), item.id);
1574
+ return store.getRequirementItemById(item.id);
1575
+ },
1576
+
1577
+ // ---------------------------------------------------------------- 条目化(FR-36,规则解析,MVP 不用 AI)
1578
+ elaborateRequirementDoc(ref, options = {}) {
1579
+ const doc = options.docId
1580
+ ? store.getRequirementDocById(options.docId)
1581
+ : (store.getRequirementDocById(ref) ?? store.getRequirementDoc(ref ?? options.projectId));
1582
+ if (!doc) throw new TbError("REQUIREMENT_DOC_NOT_FOUND", `需求文档不存在:${options.docId ?? ref ?? options.projectId}`, { ref: options.docId ?? ref ?? options.projectId });
1583
+ // 规则解析 = fallback 路径(AI 版见切片2,或由宿主注入 aiElaborator)
1584
+ // B-2:规则条目化可能一次产出成百上千条(尤其对"资料索引"这类文档)→ 加数量上限,防"候选洪水"
1585
+ const limit = Number.isFinite(options.limit) ? options.limit : 100;
1586
+ const all = elaborateDocument(doc.body);
1587
+ const capped = all.slice(0, limit);
1588
+ const res = store.addRequirementCandidates(doc.id, capped, { source: "elaborated-rule" });
1589
+ return { ...res, truncated: all.length > capped.length, totalFound: all.length };
1590
+ },
1591
+ /** 写入一组候选条目(AI 或规则产出共用);去重、未确认不落 requirement_items。 */
1592
+ addRequirementCandidates(ref, candidates, { source = "elaborated-rule" } = {}) {
1593
+ const doc = store.getRequirementDocById(ref) ?? store.getRequirementDoc(ref);
1594
+ if (!doc) throw new TbError("REQUIREMENT_DOC_NOT_FOUND", `需求文档不存在:${ref}`, { ref });
1595
+ const list = normalizeCandidates(candidates);
1596
+ const existingItems = new Set(store.listRequirementItems({ projectId: doc.projectId }).map((x) => x.normTitle));
1597
+ const pending = db.prepare("select norm_title from requirement_candidates where doc_id = ? and status = 'pending'").all(doc.id).map((r) => r.norm_title);
1598
+ const seen = new Set([...existingItems, ...pending]);
1599
+ const created = [];
1600
+ const ts = nowIso();
1601
+ const insert = db.prepare(
1602
+ `insert into requirement_candidates (id, doc_id, project_id, title, description, acceptance, priority, norm_title, source, status, created_at)
1603
+ values (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?)`,
1604
+ );
1605
+ for (const c of list) {
1606
+ const key = titleKey(c.title);
1607
+ if (key === "" || seen.has(key)) continue;
1608
+ seen.add(key);
1609
+ const id = randomUUID();
1610
+ insert.run(id, doc.id, doc.projectId, c.title, c.description, c.acceptance, c.priority, key, source, ts);
1611
+ created.push(rowToRequirementCandidate(db.prepare("select * from requirement_candidates where id = ?").get(id)));
1612
+ }
1613
+ return { docId: doc.id, candidates: created, duplicatesSkipped: list.length - created.length, source };
1614
+ },
1615
+ listRequirementCandidates(filter = {}) {
1616
+ const clauses = []; const params = [];
1617
+ if (filter.docId) { clauses.push("doc_id = ?"); params.push(filter.docId); }
1618
+ if (filter.status) { clauses.push("status = ?"); params.push(filter.status); }
1619
+ const where = clauses.length ? `where ${clauses.join(" and ")}` : "";
1620
+ return db.prepare(`select * from requirement_candidates ${where} order by created_at, rowid`).all(...params).map(rowToRequirementCandidate);
1621
+ },
1622
+ /** 批量清理候选(B-4):按 ids 或 docId+status 删除。 */
1623
+ deleteRequirementCandidates({ ids = null, docId = undefined, status = undefined } = {}) {
1624
+ let removed = 0;
1625
+ if (Array.isArray(ids) && ids.length) {
1626
+ const stmt = db.prepare("delete from requirement_candidates where id = ?");
1627
+ for (const id of ids) { const r = stmt.run(id); removed += r.changes ?? 0; }
1628
+ return { removed };
1629
+ }
1630
+ const clauses = []; const params = [];
1631
+ if (docId) { clauses.push("doc_id = ?"); params.push(docId); }
1632
+ if (status) { clauses.push("status = ?"); params.push(status); }
1633
+ if (!clauses.length) throw invalidField("candidates", "批量删除需指定 ids 或 docId/status");
1634
+ const r = db.prepare(`delete from requirement_candidates where ${clauses.join(" and ")}`).run(...params);
1635
+ return { removed: r.changes ?? 0 };
1636
+ },
1637
+ confirmRequirementCandidates(ids) {
1638
+ if (!Array.isArray(ids) || ids.length === 0) throw invalidField("ids", "必须提供要确认的候选 id 列表(非空)");
1639
+ const created = [];
1640
+ const ts = nowIso();
1641
+ const mark = db.prepare("update requirement_candidates set status = 'confirmed' where id = ? and status = 'pending'");
1642
+ db.exec("begin immediate");
1643
+ try {
1644
+ for (const cid of ids) {
1645
+ const row = db.prepare("select * from requirement_candidates where id = ?").get(cid);
1646
+ if (!row) throw new TbError("CANDIDATE_NOT_FOUND", `候选不存在:${cid}`, { candidateId: cid });
1647
+ if (row.status !== "pending") continue;
1648
+ const id = randomUUID();
1649
+ insertRequirementItem(db, {
1650
+ id, projectId: row.project_id, docId: row.doc_id, title: row.title,
1651
+ description: row.description, acceptance: row.acceptance, priority: row.priority,
1652
+ status: "open", source: row.source ?? "elaborated-rule", ts,
1653
+ });
1654
+ mark.run(cid);
1655
+ created.push(store.getRequirementItemById(id));
1656
+ }
1657
+ db.exec("commit");
1658
+ } catch (error) {
1659
+ db.exec("rollback");
1660
+ throw error;
1661
+ }
1662
+ return { created };
1663
+ },
1664
+ rejectRequirementCandidates(ids) {
1665
+ if (!Array.isArray(ids) || ids.length === 0) throw invalidField("ids", "必须提供要拒绝的候选 id 列表(非空)");
1666
+ const run = db.prepare("update requirement_candidates set status = 'rejected' where id = ? and status = 'pending'");
1667
+ let rejected = 0;
1668
+ db.exec("begin immediate");
1669
+ try { for (const cid of ids) rejected += run.run(cid).changes; db.exec("commit"); } catch (error) { db.exec("rollback"); throw error; }
1670
+ return { rejected };
1671
+ },
1672
+
1673
+ // ---------------------------------------------------------------- 任务依赖(FR-39)
1674
+ addTaskDependency(input = {}) {
1675
+ const blocker = store.requireTaskRef(input.blocker ?? input.blockerId);
1676
+ const blocked = store.requireTaskRef(input.blocked ?? input.blockedId);
1677
+ if (blocker.id === blocked.id) throw new TbError("DEPENDENCY_SELF", "任务不能依赖自己", { taskId: blocker.id });
1678
+ if (blocker.projectId !== blocked.projectId) {
1679
+ throw new TbError("DEPENDENCY_CROSS_PROJECT", `依赖不能跨项目(前置 ${blocker.projectId},后继 ${blocked.projectId})`, { blockerProjectId: blocker.projectId, blockedProjectId: blocked.projectId });
1680
+ }
1681
+ const cyc = db.prepare(
1682
+ `with recursive reach(x) as (
1683
+ select ?
1684
+ union
1685
+ select d.blocked_id from task_dependencies d join reach r on d.blocker_id = r.x
1686
+ ) select 1 as c from reach where x = ? limit 1`,
1687
+ ).get(blocked.id, blocker.id);
1688
+ if (cyc) throw new TbError("DEPENDENCY_CYCLE", "依赖会形成环,已拒绝", { blockerId: blocker.id, blockedId: blocked.id });
1689
+ const reason = input.reason == null || input.reason === "" ? null : String(input.reason);
1690
+ try {
1691
+ db.prepare("insert into task_dependencies (project_id, blocker_id, blocked_id, reason, created_at) values (?, ?, ?, ?, ?)")
1692
+ .run(blocker.projectId, blocker.id, blocked.id, reason, nowIso());
1693
+ } catch (error) {
1694
+ if (isConstraintError(error, "task_dependencies")) throw new TbError("DEPENDENCY_EXISTS", "该依赖已存在", { blocker: blocker.identifier, blocked: blocked.identifier });
1695
+ throw error;
1696
+ }
1697
+ return store.listTaskDependencies(blocked.id);
1698
+ },
1699
+ removeTaskDependency(input = {}) {
1700
+ const blocker = store.getTaskRef(input.blocker ?? input.blockerId);
1701
+ const blocked = store.getTaskRef(input.blocked ?? input.blockedId);
1702
+ if (!blocker || !blocked) return { removed: false };
1703
+ const r = db.prepare("delete from task_dependencies where blocker_id = ? and blocked_id = ?").run(blocker.id, blocked.id);
1704
+ return { removed: r.changes > 0 };
1705
+ },
1706
+ listTaskDependencies(ref) {
1707
+ const task = store.requireTaskRef(ref);
1708
+ const blockers = db.prepare(
1709
+ "select d.blocker_id as id, t.identifier as identifier, t.title as title, t.status as status, d.reason as reason from task_dependencies d join tasks t on t.id = d.blocker_id where d.blocked_id = ? order by d.created_at",
1710
+ ).all(task.id);
1711
+ const blocks = db.prepare(
1712
+ "select d.blocked_id as id, t.identifier as identifier, t.title as title, t.status as status from task_dependencies d join tasks t on t.id = d.blocked_id where d.blocker_id = ? order by d.created_at",
1713
+ ).all(task.id);
1714
+ return { taskId: task.id, identifier: task.identifier, blockers, blocks };
1715
+ },
1716
+ isTaskReady(ref) {
1717
+ const task = store.requireTaskRef(ref);
1718
+ const rows = db.prepare(
1719
+ "select d.blocker_id as id, t.identifier as identifier, t.status as status from task_dependencies d join tasks t on t.id = d.blocker_id where d.blocked_id = ?",
1720
+ ).all(task.id);
1721
+ const unfinished = rows.filter((r) => r.status !== "done");
1722
+ return { taskId: task.id, identifier: task.identifier, ready: unfinished.length === 0, blockers: rows };
1723
+ },
1724
+
1725
+ // ---------------------------------------------------------------- 分拆(FR-38)
1726
+ splitRequirement(ref, { tasks } = {}) {
1727
+ const item = store.requireRequirementItemRef(ref);
1728
+ const list = assertSplitTasks(tasks ?? []);
1729
+ if (list.length === 0) throw new TbError("SPLIT_EMPTY", "分拆产出为空:未提供任何任务", { requirement: item.identifier });
1730
+ const created = [];
1731
+ const byTitle = new Map();
1732
+ for (const t of list) {
1733
+ // 2026-10-28:`kind` 落到标签 `kind/work` / `kind/review`(任务表没有 kind 列,也不值得为此加列)。
1734
+ // 用标签而不是拼进描述:卡片与抽屉都能直接看到,且可按标签筛。
1735
+ const labels = [...(Array.isArray(t.labels) ? t.labels : [])];
1736
+ if (t.kind) labels.push(`kind/${t.kind}`);
1737
+ const task = store.createTask({
1738
+ projectId: item.projectId, title: t.title, description: t.description,
1739
+ owner: t.owner, priority: t.priority, labels, status: "backlog",
1740
+ });
1741
+ const linked = store.associateRequirementTask(item.id, task.id);
1742
+ created.push(linked);
1743
+ byTitle.set(titleKey(t.title), linked);
1744
+ }
1745
+ for (const t of list) {
1746
+ const task = byTitle.get(titleKey(t.title));
1747
+ for (const dep of t.dependsOn) {
1748
+ const target = byTitle.get(titleKey(dep)) ?? store.getTaskRef(dep);
1749
+ if (!target) throw new TbError("TASK_NOT_FOUND", `依赖目标不存在:${dep}`, { dep });
1750
+ store.addTaskDependency({ blocker: target.id, blocked: task.id });
1751
+ }
1752
+ }
1753
+ return { requirement: item.identifier, tasks: created };
1754
+ },
1755
+ associateRequirementTask(ref, taskRef) {
1756
+ const item = store.requireRequirementItemRef(ref);
1757
+ const task = store.requireTaskRef(taskRef);
1758
+ if (item.projectId !== task.projectId) {
1759
+ throw new TbError("DEPENDENCY_CROSS_PROJECT", `条目与任务必须同项目(条目 ${item.projectId},任务 ${task.projectId})`, { requirementProjectId: item.projectId, taskProjectId: task.projectId });
1760
+ }
1761
+ db.prepare("update tasks set requirement_id = ?, updated_at = ? where id = ?").run(item.id, nowIso(), task.id);
1762
+ return store.getTaskById(task.id);
1763
+ },
1764
+ listTasksByRequirement(ref) {
1765
+ const item = store.requireRequirementItemRef(ref);
1766
+ return db.prepare("select * from tasks where requirement_id = ? order by created_at, rowid").all(item.id).map(rowToTask);
1767
+ },
1768
+ /**
1769
+ * 只读:条目的「完成度」——关联任务清单 + 汇总结论(FR-91)。
1770
+ * 需求详情靠它回答「这条需求关联的任务做完了没有」,自动给建议、终态仍由人确认。
1771
+ */
1772
+ requirementCompletion(ref) {
1773
+ const item = store.requireRequirementItemRef(ref);
1774
+ const tasks = store.listTasksByRequirement(item.id);
1775
+ return { item, ...summarizeRequirementCompletion(tasks) };
1776
+ },
1777
+ /** 只读:条目的技术任务 DAG(任务节点 + 依赖边),供 UI 展示。 */
1778
+ /**
1779
+ * 需求条目的「任务 DAG」投影(FR-91 补口 · 2026-10-29 二轮优化)。
1780
+ *
1781
+ * 三条口径(都是真机读出来的,不是设计想象):
1782
+ * ① **前置在上**:按依赖做**稳定拓扑序**(Kahn;同层保持 `created_at, rowid`)。人从上往下读就是执行顺序。
1783
+ * 环在 `addTaskDependency` 已被 reach 检查拒掉,这里仍防御一次:排不进去的尾巴按原序追加,**绝不丢节点**。
1784
+ * ② **每个节点带 `blockedBy`**:前端不必自己反算边,节点上就能写「⬅ 前置 A、B」——
1785
+ * 真机批注只看到「⛔ 受阻」四个字,等于让人自己去猜"卡在谁身上"。
1786
+ * ③ **每条边带 `reason`**:`task_dependencies.reason` 本来就是"为什么卡住"的原文(如「停写窗口未确认」),
1787
+ * 投影里丢掉它,等于把最有用的那句话留在库里。
1788
+ */
1789
+ requirementTaskGraph(ref) {
1790
+ const item = store.requireRequirementItemRef(ref);
1791
+ const tasks = db.prepare("select * from tasks where requirement_id = ? order by created_at, rowid").all(item.id).map(rowToTask);
1792
+ const byId = new Map(tasks.map((t) => [t.id, t]));
1793
+ const rows = db.prepare("select blocker_id, blocked_id, reason from task_dependencies").all()
1794
+ .filter((r) => byId.has(r.blocker_id) && byId.has(r.blocked_id));
1795
+ // ---- ① 稳定拓扑序 ----
1796
+ const indeg = new Map(tasks.map((t) => [t.id, 0]));
1797
+ const downstream = new Map(tasks.map((t) => [t.id, []]));
1798
+ for (const r of rows) {
1799
+ indeg.set(r.blocked_id, (indeg.get(r.blocked_id) ?? 0) + 1);
1800
+ downstream.get(r.blocker_id).push(r.blocked_id);
1801
+ }
1802
+ const queue = tasks.filter((t) => (indeg.get(t.id) ?? 0) === 0).map((t) => t.id);
1803
+ const ordered = [];
1804
+ const placed = new Set();
1805
+ while (queue.length) {
1806
+ const id = queue.shift();
1807
+ ordered.push(id);
1808
+ placed.add(id);
1809
+ for (const nextId of downstream.get(id) ?? []) {
1810
+ const left = (indeg.get(nextId) ?? 0) - 1;
1811
+ indeg.set(nextId, left);
1812
+ if (left === 0) queue.push(nextId);
1813
+ }
1814
+ }
1815
+ for (const t of tasks) if (!placed.has(t.id)) ordered.push(t.id); // 防御:环残留按原序追加
1816
+ // ---- ② 每个节点的「被谁卡住」 ----
1817
+ const blockedBy = new Map(tasks.map((t) => [t.id, []]));
1818
+ for (const r of rows) {
1819
+ const blocker = byId.get(r.blocker_id);
1820
+ blockedBy.get(r.blocked_id).push({ identifier: blocker.identifier, title: blocker.title, status: blocker.status, reason: r.reason ?? null });
1821
+ }
1822
+ return {
1823
+ item: { id: item.id, identifier: item.identifier, title: item.title, feasibility: item.feasibility },
1824
+ nodes: ordered.map((id) => {
1825
+ const t = byId.get(id);
1826
+ return { id: t.id, identifier: t.identifier, title: t.title, status: t.status, blockedBy: blockedBy.get(id) };
1827
+ }),
1828
+ // ---- ③ 边上带原始 reason ----
1829
+ edges: rows.map((r) => ({ blocker: byId.get(r.blocker_id).identifier, blocked: byId.get(r.blocked_id).identifier, reason: r.reason ?? null })),
1830
+ };
1831
+ },
1832
+ // ---------------------------------------------------------------- 执行(FR-40 启动 / FR-41 跟踪与失败)
1833
+ /** 归因门(共享断言):任务必须归属需求条目。单执行(FR-40)与派发(FR-42)共用,防漂移。 */
1834
+ assertAttributed(ref) {
1835
+ const task = store.requireTaskRef(ref);
1836
+ if (!task.requirementId) throw new TbError("EXECUTION_NOT_ATTRIBUTED", "任务未归属需求条目:请先关联需求条目(归因门)", { taskId: task.id, identifier: task.identifier });
1837
+ return task;
1838
+ },
1839
+ /**
1840
+ * 「启动执行」的**门序列唯一来源**:人工校验门 → 归因门 → 授权/状态门。
1841
+ *
1842
+ * 真机 2026-10-22(续四十一):`POST /api/tasks/:ref/execute` 原先**先**建宿主会话
1843
+ * (`port.createSession()` + `port.openSession()`,会把主视图切走),**之后**才在
1844
+ * `startTaskExecution` 里判这三道门 ⇒ **被拒绝的动作照样留下副作用**(多出一个空会话 +
1845
+ * 视图被切),而这条路径恰恰是用户反复踩的(可开工卡点「启动执行」被归因门/授权门拒)。
1846
+ * 修法:门序列提成这一个方法,api 层在建会话**之前**先调;`startTaskExecution` 也用它
1847
+ * (复检不算重复实现,仍只有这一份口径)。
1848
+ *
1849
+ * 顺序有意为之(FR-85b):先判「是不是人工校验任务」再判归因门 —— 否则会先抛
1850
+ * `EXECUTION_NOT_ATTRIBUTED`,把"这是升级门"这个更根本的原因盖掉。
1851
+ */
1852
+ assertExecutable(ref) {
1853
+ const pre = store.requireTaskRef(ref);
1854
+ if (isHumanReviewTask(pre)) {
1855
+ throw new TbError("HUMAN_REVIEW_NOT_EXECUTABLE", `任务 ${pre.identifier} 是人工校验任务:不得派发执行,请用人工结论入口处置`, { identifier: pre.identifier });
1856
+ }
1857
+ const task = store.assertAttributed(ref);
1858
+ if (task.status === "backlog") throw new TbError("EXECUTION_NOT_AUTHORIZED", "任务未授权开工:请先移出待办池(backlog → todo)", { taskId: task.id, identifier: task.identifier });
1859
+ if (task.status !== "todo") throw new TbError("EXECUTION_NOT_AUTHORIZED", `只有"可开工(todo)"的任务可启动执行(当前 ${task.status})`, { taskId: task.id, status: task.status });
1860
+ return task;
1861
+ },
1862
+ startTaskExecution(ref, { sessionId = null } = {}) {
1863
+ // 门序列见 store.assertExecutable(唯一来源);这里必须复检 —— 调用方可能跳过 api 层的预判。
1864
+ const task = store.assertExecutable(ref);
1865
+ const directive = `任务 ${task.identifier}:${task.title}\n操作指引:认领 → 执行 → 提交"待验收";不得置"完成"(人工确认)。`;
1866
+ db.prepare("update tasks set status = 'in_progress', session_id = ?, version = version + 1, updated_at = ? where id = ?")
1867
+ .run(sessionId ?? null, nowIso(), task.id);
1868
+ // FR-77:认领即建带过期的认领锁 + 起始心跳(来源列=todo,回收时退回这里)
1869
+ const claim = store.claimTask(task.id, { sessionId, sourceStatus: "todo" });
1870
+ return { task: store.getTaskById(task.id), claim, launch: { mode: sessionId ? "session" : "degraded", sessionId: sessionId ?? null, directive } };
1871
+ },
1872
+ getTaskExecution(ref) {
1873
+ const task = store.requireTaskRef(ref);
1874
+ return {
1875
+ taskId: task.id, identifier: task.identifier, status: task.status,
1876
+ sessionId: task.sessionId ?? null, attributed: Boolean(task.requirementId),
1877
+ sessionState: store.taskSessionState(ref),
1878
+ // FR-78:失败会计可见
1879
+ consecutiveFailures: Number(task.consecutiveFailures ?? 0),
1880
+ failureLimit: task.maxRetries ?? DEFAULT_FAILURE_LIMIT,
1881
+ lastFailureError: task.lastFailureError ?? null,
1882
+ lastSuccessAt: task.lastSuccessAt ?? null,
1883
+ guard: store.dispatchGuard(task),
1884
+ // FR-80:阻断分类与复发可见
1885
+ blockKind: task.blockKind ?? null,
1886
+ blockRecurrences: task.blockRecurrences ?? 0,
1887
+ triageAt: task.triageAt ?? null,
1888
+ // FR-82:当前尝试 + 历史尝试数("按尝试看历史"的数据源)
1889
+ currentRun: store.getCurrentRun(task),
1890
+ attempts: store.listTaskRuns(task).length,
1891
+ };
1892
+ },
1893
+ /**
1894
+ * 执行会话实时状态(宿主 `agents` 注册表):会话是否仍在该进程内、是否 running、还有多少待消费消息。
1895
+ * 无宿主端口(沙箱/测试)时如实返回 unknown。
1896
+ */
1897
+ taskSessionState(ref) {
1898
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
1899
+ const sessionId = task.sessionId ?? null;
1900
+ if (!sessionId) return { sessionId: null, live: false, running: false, status: null, pending: 0, known: false };
1901
+ let state = null;
1902
+ try { state = store.hostSessionPort?.sessionState?.(sessionId) ?? null; } catch { state = null; }
1903
+ return state ?? { sessionId, live: false, running: false, status: null, pending: 0, known: false };
1904
+ },
1905
+ // ---------------- 执行认领锁 + 心跳(FR-77) ----------------
1906
+ /**
1907
+ * 认领任务(CAS):仅当**未被认领或原认领已过期**时成功;写 claim_lock/claim_expires/心跳/来源列。
1908
+ * 对齐 hermes `_claim_task_cas`:`rowcount!=1` 即"没抢到",返回 claimed:false(不抛错)。
1909
+ */
1910
+ claimTask(ref, { sessionId = null, ttlMs = DEFAULT_CLAIM_TTL_MS, sourceStatus = null, now = null } = {}) {
1911
+ const task = store.requireTaskRef(ref);
1912
+ // FR-85b:人工校验任务是"人在环升级门",执行侧不得认领(结论只能由人给出)
1913
+ if (isHumanReviewTask(task)) {
1914
+ try { store.recordAudit({ actor: sessionId ?? "team", action: "claim", target: task.identifier, allowed: false, reason: "human-review-not-claimable", detail: "人工校验任务执行侧不得认领" }); } catch { /* ignore */ }
1915
+ throw new TbError("HUMAN_REVIEW_NOT_CLAIMABLE", `任务 ${task.identifier} 是人工校验任务:执行侧不得认领,结论只能由人给出`, { identifier: task.identifier });
1916
+ }
1917
+ const ts = now ?? Date.now();
1918
+ const at = new Date(ts).toISOString();
1919
+ const expires = new Date(ts + ttlMs).toISOString();
1920
+ const lock = randomUUID();
1921
+ const cur = db.prepare("select claim_lock, claim_expires, status from tasks where id = ?").get(task.id);
1922
+ const held = cur?.claim_lock && cur.claim_expires && String(cur.claim_expires) > at;
1923
+ if (held) return { claimed: false, reason: "already-claimed", claim: { lock: cur.claim_lock, expiresAt: cur.claim_expires }, task: store.getTaskById(task.id) };
1924
+ const res = db.prepare(
1925
+ `update tasks set claim_lock = ?, claim_expires = ?, claim_owner = coalesce(?, claim_owner),
1926
+ claim_source = coalesce(?, claim_source), last_heartbeat_at = ?,
1927
+ session_id = coalesce(?, session_id), version = version + 1, updated_at = ?
1928
+ where id = ? and (claim_lock is null or claim_expires is null or claim_expires < ?)`,
1929
+ ).run(lock, expires, sessionId, sourceStatus, at, sessionId, at, task.id, at);
1930
+ if (res.changes !== 1) return { claimed: false, reason: "cas-lost", task: store.getTaskById(task.id) };
1931
+ // FR-82:**认领即开一条尝试记录**(授权→尝试→结论 可回看)
1932
+ const run = store.startTaskRun(task.identifier, { sessionId, claimLock: lock, actor: sessionId ?? "team", now: ts });
1933
+ store.recordTaskEvent(task.id, { type: "claimed", to: "claimed", actor: sessionId ?? "team", detail: `认领(来源 ${sourceStatus ?? cur?.status ?? "-"})`, now: ts });
1934
+ return { claimed: true, claim: { lock, expiresAt: expires, owner: sessionId ?? null, source: sourceStatus ?? cur?.status ?? null }, run: run.started ? run.run : null, task: store.getTaskById(task.id) };
1935
+ },
1936
+ /**
1937
+ * 执行侧心跳(FR-77):只更新 `last_heartbeat_at`(可带备注)。
1938
+ * 任务不在认领态 / 认领已过期 → 返回 false(对齐 hermes `heartbeat_worker`)。
1939
+ * **缺心跳本身不计为失败**,因此这里不碰 consecutive_failures。
1940
+ */
1941
+ heartbeatTask(ref, { lock = null, note = null, now = null } = {}) {
1942
+ const task = store.requireTaskRef(ref);
1943
+ const at = new Date(now ?? Date.now()).toISOString();
1944
+ const args = [at, at, task.id, at];
1945
+ let sql = "update tasks set last_heartbeat_at = ?, updated_at = ? where id = ? and claim_lock is not null and (claim_expires is null or claim_expires >= ?)";
1946
+ if (lock) { sql += " and claim_lock = ?"; args.push(lock); }
1947
+ const res = db.prepare(sql).run(...args);
1948
+ if (res.changes !== 1) return { ok: false, reason: "not-claimed-or-expired" };
1949
+ // FR-82:心跳同时计入当前尝试(heartbeats / last_heartbeat_at)
1950
+ store.heartbeatTaskRun(task.identifier, { now: now ?? Date.now() });
1951
+ if (note) { try { store.addComment(task.id, { body: `心跳:${note}` }); } catch { /* ignore */ } }
1952
+ return { ok: true, at };
1953
+ },
1954
+ /** 认领状态只读查询(FR-77):是否被认领 / 是否过期 / 心跳年龄(秒)。 */
1955
+ taskClaimState(ref, { now = null, heartbeatGapMs = DEFAULT_HEARTBEAT_GAP_MS } = {}) {
1956
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
1957
+ const ts = now ?? Date.now();
1958
+ const lock = task.claimLock ?? null;
1959
+ const expiresAt = task.claimExpires ?? null;
1960
+ const lastAt = task.lastHeartbeatAt ?? null;
1961
+ if (!lock) return { locked: false, expired: false, stale: false, lock: null, owner: task.claimOwner ?? null, source: task.claimSource ?? null, expiresAt: null, lastHeartbeatAt: null, heartbeatAgeSeconds: null };
1962
+ const expired = !expiresAt || String(expiresAt) < new Date(ts).toISOString();
1963
+ const hbAge = lastAt ? Math.max(0, Math.round((ts - new Date(lastAt).getTime()) / 1000)) : null;
1964
+ const stale = hbAge === null || hbAge * 1000 >= heartbeatGapMs;
1965
+ return { locked: true, expired, stale, lock, owner: task.claimOwner ?? null, source: task.claimSource ?? null, expiresAt, lastHeartbeatAt: lastAt, heartbeatAgeSeconds: hbAge };
1966
+ },
1967
+ /**
1968
+ * 回收失效认领(FR-77):认领已过期**或**心跳陈旧 → 释放认领并把任务退回**来源列**。
1969
+ * 守卫(对齐 hermes `_defer_reclaim_for_live_worker`):**执行侧仍存活则不释放**(避免重复派发)。
1970
+ */
1971
+ /**
1972
+ * 「投递到会话但没交作业」的**收口留痕**(FR-79 / FR-82 补口,真机续二十二)。
1973
+ *
1974
+ * 为什么需要:看板把派发指令投进项目主会话后,会话里的 agent 可能真干了活却**不回报**
1975
+ * (不提交「待验收」、不留评论)⇒ 被看护按心跳陈旧回收,看板只剩一句「认领已回收」,
1976
+ * 人看不出「成果可能已经落在工作区」,于是**工作成果与看板状态脱钩**。
1977
+ *
1978
+ * 判定唯一来源=`core/delivery.mjs` 的 `detectUntakenDelivery()`(纯函数,FR-79 诊断同用一份,
1979
+ * 防两份口径漂移);本方法只负责**落痕**:一条带 `【投递未收尾】` 前缀的评论 + 一条事件。
1980
+ * 措辞不许在这里重写一遍 —— 诊断里的文案由 diagnostics 侧从同一个 hit 产出。
1981
+ *
1982
+ * 调用时机(两处收口共用):`reclaimStaleClaim()`(回收)与 `reconcileOrphanRuns()`(超时)。
1983
+ * **必须在写「认领已回收」那条留痕之前调用**:虽然该文案已列入系统留痕,但"先判后写"更不容易被
1984
+ * 后续改动破坏顺序(`delivery.mjs` 的系统留痕清单是第二道保险)。
1985
+ */
1986
+ noteUntakenDelivery(ref, { now = null } = {}) {
1987
+ const task = store.requireTaskRef(ref);
1988
+ let hit = null;
1989
+ try {
1990
+ // 注意:`listComments()` 只接受 ref(内部直接走 requireTaskRef),传对象会抛 TASK_NOT_FOUND ——
1991
+ // 而这里外面包着 try/catch(故意不阻断收口)⇒ 传错就**静默永不命中**(本轮实测踩到过)。统一传 identifier。
1992
+ hit = detectUntakenDelivery({ task, runs: store.listTaskRuns(task.identifier), comments: store.listComments(task.identifier) });
1993
+ } catch { hit = null; }
1994
+ if (!hit) return null;
1995
+ const sid = String(hit.run.sessionId ?? "");
1996
+ const body = `${UNTAKEN_COMMENT_MARKER}第 ${hit.run.attempt} 次尝试是**投递给执行会话**${sid ? ` ${sid.slice(0, 18)}…` : ""} 的,`
1997
+ + `但会话里没有交作业(没提交「待验收」,且该次开始后没有任何评论)⇒ 已按「${hit.reason}」收口。\n`
1998
+ + `⚠ 工作区可能已有未提交的改动:请先人工核对(打开执行会话看现场,或直接看工作目录 diff),再决定重派还是作废。`;
1999
+ try { store.addComment(task.id, { body }); } catch { /* ignore */ }
2000
+ try {
2001
+ store.recordTaskEvent(task.id, {
2002
+ type: "delivery_untaken", actor: "watchdog", to: task.status,
2003
+ detail: `投递到会话后未收尾:第 ${hit.run.attempt} 次尝试 ${hit.reason}${sid ? `(session ${sid.slice(0, 18)}…)` : ""}`,
2004
+ now: now ?? Date.now(),
2005
+ });
2006
+ } catch { /* ignore */ }
2007
+ return { run: hit.run, reason: hit.reason };
2008
+ },
2009
+ reclaimStaleClaim(ref, { now = null, heartbeatGapMs = DEFAULT_HEARTBEAT_GAP_MS, sessionState = undefined } = {}) {
2010
+ const task = store.requireTaskRef(ref);
2011
+ const state = store.taskClaimState(task, { now, heartbeatGapMs });
2012
+ if (!state.locked) return { reclaimed: false, reason: "not-claimed" };
2013
+ // 对齐 hermes `detect_stale_running`:**过期 且 心跳陈旧**才算失效——
2014
+ // 心跳新鲜即视为"执行侧仍在推进",即便认领时间已过也先不回收。
2015
+ if (!(state.expired && state.stale)) return { reclaimed: false, reason: state.expired ? "heartbeat-fresh" : "claim-fresh" };
2016
+ // 执行侧仍活跃 → 暂不回收(下一次检查再试)
2017
+ const live = sessionState === undefined ? store.taskSessionState(task) : sessionState;
2018
+ if (live?.running) return { reclaimed: false, reason: "worker-alive", claim: state };
2019
+ const at = new Date(now ?? Date.now()).toISOString();
2020
+ const target = state.source && TEAM_WRITABLE_STATUSES.includes(state.source) ? state.source : (state.source || "todo");
2021
+ // FR-82:回收失效认领 = 本次尝试以「被回收」收场
2022
+ store.endTaskRun(task.identifier, { outcome: "reclaimed", summary: state.expired ? "认领过期被回收" : "心跳陈旧被回收", actor: "watchdog", now: now ?? Date.now() });
2023
+ db.prepare(
2024
+ "update tasks set status = ?, claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null, version = version + 1, updated_at = ? where id = ? and claim_lock = ?",
2025
+ ).run(target, at, task.id, state.lock);
2026
+ try { db.prepare("update team_tasks set status = 'cancelled', updated_at = ? where task_id = ? and status in ('open','running')").run(at, task.id); } catch { /* ignore */ }
2027
+ // FR-79/82 补口:这次收口若是「投递到会话但没交作业」,补一条可见留痕(判定只看 delivery.mjs)。
2028
+ // 必须排在下面那条「认领已回收」之前:先据事实判定,再写系统留痕。
2029
+ const untaken = (() => { try { return store.noteUntakenDelivery(task.identifier, { now: now ?? Date.now() }); } catch { return null; } })();
2030
+ try { store.addComment(task.id, { body: `认领已回收(${state.expired ? "认领过期" : "心跳陈旧"}${state.heartbeatAgeSeconds === null ? "" : `,心跳 ${state.heartbeatAgeSeconds}s 前`})→ 退回「${target}」` }); } catch { /* ignore */ }
2031
+ try { store.recordAudit({ actor: "watchdog", action: "reclaim", target: task.identifier, allowed: true, reason: state.expired ? "claim-expired" : "heartbeat-stale" }); } catch { /* ignore */ }
2032
+ return { reclaimed: true, status: target, claim: state, untaken: untaken ? { attempt: untaken.run.attempt, reason: untaken.reason } : null };
2033
+ },
2034
+ /** 批量回收(看护/定时器用):返回被回收的任务引用清单。 */
2035
+ reclaimStaleClaims({ projectId = undefined, now = null, heartbeatGapMs = DEFAULT_HEARTBEAT_GAP_MS } = {}) {
2036
+ const candidates = db.prepare("select identifier from tasks where claim_lock is not null and status = 'in_progress'").all().map((r) => r.identifier);
2037
+ const reclaimed = [];
2038
+ for (const ref of candidates) {
2039
+ const task = store.requireTaskRef(ref);
2040
+ if (projectId && task.projectId !== projectId) continue;
2041
+ const r = store.reclaimStaleClaim(ref, { now, heartbeatGapMs });
2042
+ if (r.reclaimed) reclaimed.push({ identifier: ref, status: r.status });
2043
+ }
2044
+ return reclaimed;
2045
+ },
2046
+ // ---------------- 失败会计与熔断(FR-78) ----------------
2047
+ /**
2048
+ * 记录一次**非成功**(派发失败 / 超时 / 崩溃 / 团队回报失败)。
2049
+ * 所有非成功路径都必须走这里,保证 `consecutive_failures` 一致;**成功才清零**。
2050
+ * 阈值优先级照抄 hermes:`tasks.max_retries` > 调用方 `limit` > `DEFAULT_FAILURE_LIMIT`。
2051
+ * 配额/鉴权类错误**立即熔断**(重试不会让配额回来)。
2052
+ * 返回 `{tripped, failures, effectiveLimit, limitSource, quota}`。
2053
+ */
2054
+ recordTaskFailure(ref, { error = "", outcome = "failed", limit = null, now = null, releaseClaim = true } = {}) {
2055
+ const task = store.requireTaskRef(ref);
2056
+ const at = new Date(now ?? Date.now()).toISOString();
2057
+ const msg = String(error ?? "").slice(0, 500);
2058
+ const failures = Number(task.consecutiveFailures ?? 0) + 1;
2059
+ const override = task.maxRetries ?? null;
2060
+ const effectiveLimit = override != null ? Number(override) : (limit != null ? Number(limit) : DEFAULT_FAILURE_LIMIT);
2061
+ const limitSource = override != null ? "task" : (limit != null ? "caller" : "default");
2062
+ const quota = QUOTA_AUTH_ERROR_RE.test(msg);
2063
+ const tripped = quota || failures >= effectiveLimit;
2064
+ if (tripped) {
2065
+ // 熔断:先记计数与原因,再走 FR-80 的统一受阻入口(配额类 → capability,其它 → transient)
2066
+ db.prepare("update tasks set consecutive_failures = ?, last_failure_error = ?, version = version + 1, updated_at = ? where id = ?").run(failures, msg, at, task.id);
2067
+ try { db.prepare("update team_tasks set status = 'failed', updated_at = ? where task_id = ? and status in ('open','running')").run(at, task.id); } catch { /* ignore */ }
2068
+ // FR-82:先按**失败口径**闭合尝试(blockTask 之后还会补一条"受阻"事件)
2069
+ store.endTaskRun(task.identifier, { outcome, summary: msg, error: msg, actor: "watchdog", now: now ?? Date.now() });
2070
+ store.blockTask(task.identifier, { kind: quota ? "capability" : "transient", reason: msg, actor: "watchdog", now: now ?? Date.now() });
2071
+ try {
2072
+ store.addComment(task.id, {
2073
+ body: `执行失败已熔断(第 ${failures} 次,阈值 ${effectiveLimit}${limitSource === "task" ? " · 任务级" : ""}${quota ? " · 配额/鉴权类,不重试" : ""})→ 置「受阻」并停止自动重试。${msg ? `\n原因:${msg}` : ""}`,
2074
+ });
2075
+ } catch { /* ignore */ }
2076
+ try { store.recordAudit({ actor: "watchdog", action: "gave-up", target: task.identifier, allowed: false, reason: quota ? "quota-or-auth" : "failure-limit", detail: `failures=${failures}/${effectiveLimit}` }); } catch { /* ignore */ }
2077
+ } else {
2078
+ db.prepare(
2079
+ `update tasks set consecutive_failures = ?, last_failure_error = ?${releaseClaim ? ", claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null" : ""}, version = version + 1, updated_at = ? where id = ?`,
2080
+ ).run(failures, msg, at, task.id);
2081
+ try { db.prepare("update team_tasks set status = 'failed', updated_at = ? where task_id = ? and status in ('open','running')").run(at, task.id); } catch { /* ignore */ }
2082
+ // FR-82:非熔断的失败同样要闭合尝试(照实记 outcome,供"按尝试看历史"用)
2083
+ store.endTaskRun(task.identifier, { outcome, summary: msg, error: msg, actor: "watchdog", now: now ?? Date.now() });
2084
+ }
2085
+ store.recordTaskEvent(task.id, { type: "failure_recorded", to: quota ? "capability" : "transient", actor: "watchdog", detail: `第 ${failures}/${effectiveLimit} 次非成功:${msg || "(无原因)"}`, now: now ?? Date.now() });
2086
+ return { tripped, failures, effectiveLimit, limitSource, quota, task: store.getTaskById(task.id) };
2087
+ },
2088
+ /** 成功即清零(FR-78);成功 = 产出已提交待验收(含团队回报完成)。 */
2089
+ markTaskSucceeded(ref, { now = null } = {}) {
2090
+ const task = store.requireTaskRef(ref);
2091
+ const at = new Date(now ?? Date.now()).toISOString();
2092
+ // FR-80:复发计数/阻断类型/人工兜底标记**只在成功时清零**
2093
+ db.prepare("update tasks set consecutive_failures = 0, last_failure_error = null, last_success_at = ?, block_kind = null, block_recurrences = 0, triage_at = null, blocked_at = null, version = version + 1, updated_at = ? where id = ?").run(at, at, task.id);
2094
+ try {
2095
+ const labels = (store.getTaskById(task.id).labels || []).filter((l) => l !== TRIAGE_LABEL);
2096
+ db.prepare("update tasks set labels = ? where id = ?").run(JSON.stringify(labels), task.id);
2097
+ } catch { /* ignore */ }
2098
+ // FR-82:成功 = 本次尝试的终态;事件流追加("完成"仍需人确认,这一步只记成功会计)
2099
+ store.endTaskRun(task.identifier, { outcome: "success", summary: "按成功完成记账(失败计数清零)", actor: "system", now: now ?? Date.now() });
2100
+ return store.getTaskById(task.id);
2101
+ },
2102
+ /**
2103
+ * FR-80:**置"受阻"的唯一入口**(带类型 + 复发升级)。
2104
+ * `dependency` 走"回到待执行等父任务";其它类型进入受阻,同因复发达阈值 → 人工兜底。
2105
+ */
2106
+ blockTask(ref, { kind = null, reason = null, actor = "system", now = null, route: routeMode = "wait" } = {}) {
2107
+ const task = store.requireTaskRef(ref);
2108
+ if (kind !== null && !BLOCK_KINDS.includes(kind)) throw invalidField("kind", `阻断类型必须是 ${BLOCK_KINDS.join(" / ")} 之一,或 null`);
2109
+ if (!BLOCK_ROUTES.includes(routeMode)) throw invalidField("route", `route 必须是 ${BLOCK_ROUTES.join(" / ")} 之一`);
2110
+ const at = new Date(now ?? Date.now()).toISOString();
2111
+ const route = routeBlock({ kind, reason, prevKind: task.blockKind ?? null, prevRecurrences: task.blockRecurrences ?? 0 });
2112
+ // FR-83 红线③:评审门走 `hold` —— 依赖未就绪但**必须保持受阻**(等上游整改 + 评审通过),
2113
+ // 不能按 FR-80 的默认 `wait` 回落到"可开工",否则下游会被执行循环直接派发。
2114
+ if (routeMode === "hold") route.status = "blocked";
2115
+ const triageAt = route.triage ? at : null;
2116
+ db.prepare(
2117
+ `update tasks set status = ?, block_kind = ?, block_recurrences = ?, triage_at = ?, blocked_at = ?,
2118
+ claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null,
2119
+ version = version + 1, updated_at = ? where id = ?`,
2120
+ ).run(route.status, kind, route.recurrences, triageAt,
2121
+ // FR-79:首次受阻时间保留("卡在受阻 N 分钟"从第一次受阻算起);dependency 回待执行 → 清空
2122
+ route.status === "blocked" ? (task.blockedAt ?? at) : null, at, task.id);
2123
+ if (route.triage) {
2124
+ try {
2125
+ const labels = store.getTaskById(task.id).labels || [];
2126
+ if (!labels.includes(TRIAGE_LABEL)) db.prepare("update tasks set labels = ? where id = ?").run(JSON.stringify([...labels, TRIAGE_LABEL]), task.id);
2127
+ } catch { /* ignore */ }
2128
+ }
2129
+ const kindLabel = kind ? `类型=${kind}` : "类型=未分类";
2130
+ const body = route.triage
2131
+ ? `阻断循环检测:同因重复阻断 ${route.recurrences} 次(阈值 ${BLOCK_RECURRENCE_LIMIT})→ 已转「人工兜底」。${kindLabel}${reason ? `\n原因:${reason}` : ""}`
2132
+ : route.eventKind === "dependency_wait"
2133
+ ? `依赖未就绪 → 回到「可开工」等待父任务完成(不进人工受阻队列)。${reason ? `\n原因:${reason}` : ""}`
2134
+ : `已置「受阻」。${kindLabel}${route.recurrences > 1 ? `(同因第 ${route.recurrences} 次)` : ""}${reason ? `\n原因:${reason}` : ""}`;
2135
+ try { store.addComment(task.id, { body }); } catch { /* ignore */ }
2136
+ try { store.recordAudit({ actor, action: route.triage ? "triage" : "block", target: task.identifier, allowed: route.triage, reason: route.eventKind, detail: `${kindLabel} recurrences=${route.recurrences}` }); } catch { /* ignore */ }
2137
+ // FR-82:本次尝试以「受阻」收场 + 事件流留痕(诊断/通知据此判断终态)
2138
+ store.endTaskRun(task.identifier, { outcome: "blocked", summary: reason ?? kindLabel, actor, now: at ? new Date(at).getTime() : null });
2139
+ store.recordTaskEvent(task.id, { type: "blocked", to: route.status, actor, detail: `${kindLabel} recurrences=${route.recurrences}${route.triage ? "(人工兜底)" : ""}`, now: at ? new Date(at).getTime() : null });
2140
+ return { task: store.getTaskById(task.id), route: { ...route, kind } };
2141
+ },
2142
+ /** 人工显式重跑:清计数 + 记 `requeued_at`(用于放宽"近期成功窗口")。 */
2143
+ resetTaskFailures(ref, { now = null } = {}) {
2144
+ const task = store.requireTaskRef(ref);
2145
+ const at = new Date(now ?? Date.now()).toISOString();
2146
+ db.prepare("update tasks set consecutive_failures = 0, last_failure_error = null, requeued_at = ?, version = version + 1, updated_at = ? where id = ?").run(at, at, task.id);
2147
+ return store.getTaskById(task.id);
2148
+ },
2149
+ /**
2150
+ * 派发前置守卫(FR-78):返回 null(可派发)或原因字符串。
2151
+ * - `circuit-open`:连续失败已达阈值(不自动重试)
2152
+ * - `quota-blocked`:上次失败是配额/鉴权类(不重试)
2153
+ * - `recent-success`:窗口内已成功且之后无人工重跑(防抖动/防重复产出)
2154
+ */
2155
+ dispatchGuard(ref, { limit = null, successWindowMs = DEFAULT_SUCCESS_WINDOW_MS, now = null } = {}) {
2156
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
2157
+ const ts = now ?? Date.now();
2158
+ const override = task.maxRetries ?? null;
2159
+ const effectiveLimit = override != null ? Number(override) : (limit != null ? Number(limit) : DEFAULT_FAILURE_LIMIT);
2160
+ const failures = Number(task.consecutiveFailures ?? 0);
2161
+ // 配额/鉴权类优先(照抄 hermes:重试不会让配额回来,与计数无关)
2162
+ if (QUOTA_AUTH_ERROR_RE.test(String(task.lastFailureError ?? ""))) return "quota-blocked";
2163
+ if (failures >= effectiveLimit) return "circuit-open";
2164
+ if (task.lastSuccessAt) {
2165
+ const okAt = new Date(task.lastSuccessAt).getTime();
2166
+ const requeuedAt = task.requeuedAt ? new Date(task.requeuedAt).getTime() : 0;
2167
+ // 同毫秒视为"人工重跑优先"(重跑发生在成功之后),避免同 ms 竞态误判
2168
+ if (Number.isFinite(okAt) && ts - okAt < successWindowMs && requeuedAt < okAt) return "recent-success";
2169
+ }
2170
+ return null;
2171
+ },
2172
+ recordTaskExecutionFailure(ref, { evidence = "", kind = "transient", error = null, count = true } = {}) {
2173
+ const task = store.requireTaskRef(ref);
2174
+ const at = nowIso();
2175
+ // 「结构字段里的原因」优先取 `error`(执行器传 stderr/stdout 尾段),没有才退回 `evidence`。
2176
+ const msg = String(error ?? evidence ?? "").slice(0, 500);
2177
+ if (evidence) store.addComment(task.id, { body: `执行失败:${evidence}` });
2178
+ // FR-82:人工标记失败 = 本次尝试以失败收场(再走 FR-80 的统一受阻入口)
2179
+ store.endTaskRun(task.identifier, { outcome: "failed", summary: evidence || "人工标记失败", error: msg || null, actor: "human" });
2180
+ // FR-78 记账(2026-10-26 修 · 运行期发现):本入口此前**不写** `consecutive_failures` / `last_failure_error`,
2181
+ // 而 **CLI 执行器真跑失败走的正是这里**(`executor.mjs#executeTaskWithCli` 的失败分支)⇒ 三个下游同时瞎:
2182
+ // ① 熔断诊断(`diagnostics.mjs` 连续失败 / 配额类)读不到数;
2183
+ // ② `dispatchGuard` 的 `quota-blocked` 分支永不触发(`last_failure_error` 恒空);
2184
+ // ③ 用户可见的受阻原因(`api.mjs` 读 `task.lastFailureError`)为空 —— 卡「受阻」却不写为什么。
2185
+ // 上游注释(`recordTaskFailure` 头)早已声明「所有非成功路径都必须走这里保证计数一致」⇒ 本入口是漏网路径。
2186
+ if (count) {
2187
+ db.prepare("update tasks set consecutive_failures = consecutive_failures + 1, last_failure_error = ?, version = version + 1, updated_at = ? where id = ?")
2188
+ .run(msg, at, task.id);
2189
+ store.recordTaskEvent(task.id, { type: "failure_recorded", to: kind, actor: "executor", detail: msg || "(无原因)", now: Date.now() });
2190
+ }
2191
+ // FR-80:人工「标记失败」也走统一受阻入口(默认 transient;复发同样会升级到人工兜底)
2192
+ const r = store.blockTask(task.identifier, { kind, reason: evidence || msg || "人工标记失败", actor: "human" });
2193
+ // 释放该任务的活跃团队锁(否则一直锁着,循环永久跳过;重试才可再派发)
2194
+ db.prepare("update team_tasks set status = 'failed', updated_at = ? where task_id = ? and status in ('open','running')").run(nowIso(), task.id);
2195
+ return r.task;
2196
+ },
2197
+ submitTaskForReview(ref, { comment = "" } = {}) {
2198
+ // FR-83:提交待验收 = 请求评审(从这里进评审一等流程)
2199
+ return store.requestReview(ref, { comment, actor: "team" }).task;
2200
+ },
2201
+ // ---------------- 评审流程(FR-83) ----------------
2202
+ /**
2203
+ * 请求评审(FR-83 的一等流程):进「待验收」+ **指派评审者** + 记下**来源列**(返工退回哪一列)。
2204
+ * 释放实现认领(FR-77);执行成功照 FR-78 记账;事件流写 `review_requested`。
2205
+ */
2206
+ requestReview(ref, { reviewer = null, dependsOn = null, comment = "", actor = "team", now = null } = {}) {
2207
+ const task = store.requireTaskRef(ref);
2208
+ const at = new Date(now ?? Date.now()).toISOString();
2209
+ // 来源列:第一次提交时记下当前列;返工后重提则**沿用**上次来源列(保证返工总回同一实现列)
2210
+ const source = task.status === "in_review"
2211
+ ? (task.reviewSourceStatus ?? "in_progress")
2212
+ : (REVIEW_SOURCE_STATUSES.includes(task.status) ? task.status : "in_progress");
2213
+ db.prepare(
2214
+ `update tasks set status = 'in_review', review_state = 'pending', reviewer = coalesce(?, reviewer),
2215
+ review_requested_at = ?, review_source_status = ?,
2216
+ review_depends_on = case when ? is null then review_depends_on else ? end,
2217
+ claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null,
2218
+ version = version + 1, updated_at = ? where id = ?`,
2219
+ ).run(reviewer, at, source, dependsOn, dependsOn, at, task.id);
2220
+ if (comment) store.addComment(task.id, { body: comment });
2221
+ store.markTaskSucceeded(task.identifier); // FR-78:产出已提交待验收 = 本次执行成功
2222
+ store.recordTaskEvent(task.id, { type: "status_changed", from: task.status, to: "in_review", actor });
2223
+ store.recordTaskEvent(task.id, { type: "review_requested", to: "in_review", actor, detail: `${reviewer ? `指派评审者 ${reviewer}` : "未指派评审者"}·来源列 ${source}${comment ? `|${comment}` : ""}` });
2224
+ const next = store.getTaskById(task.id);
2225
+ if (!reviewer) {
2226
+ try { store.addComment(task.id, { body: `待评审(未指派评审者):${REVIEW_IDLE_MS / 60000} 分钟无人处理将产出「评审死锁」诊断。` }); } catch { /* ignore */ }
2227
+ }
2228
+ return { task: next, review: { state: next.reviewState, reviewer: next.reviewer, sourceStatus: source, round: next.reviewRound }, deadlock: detectReviewDeadlock(store, next) };
2229
+ },
2230
+ /**
2231
+ * 请求返工(FR-83):**退回来源列**(不得退成"实现"以外的错列)+ 返工说明 + 轮次 +1。
2232
+ * 释放认领让执行侧重新接手;事件流写 `changes_requested`。
2233
+ */
2234
+ requestChanges(ref, { comment = "", actor = "reviewer", now = null } = {}) {
2235
+ const task = store.requireTaskRef(ref);
2236
+ if (task.status !== "in_review") {
2237
+ throw new TbError("REVIEW_NOT_PENDING", `任务不在「待验收」,无法请求返工(当前 ${task.status})`, { identifier: task.identifier, status: task.status });
2238
+ }
2239
+ const at = new Date(now ?? Date.now()).toISOString();
2240
+ const target = reviewReturnStatus(task.reviewSourceStatus);
2241
+ const round = Number(task.reviewRound ?? 0) + 1;
2242
+ db.prepare(
2243
+ `update tasks set status = ?, review_state = 'changes_requested', review_round = ?,
2244
+ review_requested_at = null, claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null,
2245
+ version = version + 1, updated_at = ? where id = ?`,
2246
+ ).run(target, round, at, task.id);
2247
+ store.recordTaskEvent(task.id, { type: "status_changed", from: "in_review", to: target, actor });
2248
+ store.recordTaskEvent(task.id, { type: "changes_requested", from: "in_review", to: target, actor, detail: `第 ${round} 轮返工${comment ? `|${comment}` : ""}` });
2249
+ store.addComment(task.id, {
2250
+ body: `评审未通过 → **退回「${target}」**并请求返工(第 ${round} 轮)。${comment ? `\n返工说明:${comment}` : ""}\n(返工只回来源列;下游仍保持受阻,等评审通过才解锁)`,
2251
+ });
2252
+ try { store.recordAudit({ actor, action: "review-changes", target: task.identifier, allowed: true, reason: "review-not-passed", detail: `round=${round} → ${target}` }); } catch { /* ignore */ }
2253
+ return { task: store.getTaskById(task.id), returnedTo: target, round };
2254
+ },
2255
+ /**
2256
+ * 评审通过(FR-83):只记"评审态=通过",**保持「待验收」**——红线:完成只能人确认,评审通过不自动置 done。
2257
+ */
2258
+ approveReview(ref, { comment = "", actor = "reviewer", now = null } = {}) {
2259
+ const task = store.requireTaskRef(ref);
2260
+ if (task.status !== "in_review") {
2261
+ throw new TbError("REVIEW_NOT_PENDING", `任务不在「待验收」,无法评审通过(当前 ${task.status})`, { identifier: task.identifier, status: task.status });
2262
+ }
2263
+ const at = new Date(now ?? Date.now()).toISOString();
2264
+ const round = Number(task.reviewRound ?? 0);
2265
+ db.prepare("update tasks set review_state = 'approved', review_requested_at = null, version = version + 1, updated_at = ? where id = ?").run(at, task.id);
2266
+ store.recordTaskEvent(task.id, { type: "review_approved", to: "approved", actor, detail: `评审通过(第 ${round} 轮)${comment ? `|${comment}` : ""}` });
2267
+ store.addComment(task.id, { body: `评审通过(第 ${round} 轮)。${comment ? `\n结论:${comment}\n` : ""}**仍需人工确认后置「完成」**(红线:完成只能人确认,执行侧与评审侧都不得置 done)。` });
2268
+ try { store.recordAudit({ actor, action: "review-approved", target: task.identifier, allowed: true, reason: "review-passed", detail: `round=${round}` }); } catch { /* ignore */ }
2269
+ return { task: store.getTaskById(task.id), needsHumanConfirmation: true, round };
2270
+ },
2271
+ /** 评审队列(FR-83):默认列出全部「待验收」任务;可按 review_state 过滤。 */
2272
+ listReviews(projectId, { state = null } = {}) {
2273
+ const tasks = store.listTasks({ projectId, status: "in_review" });
2274
+ return tasks
2275
+ .filter((t) => (state ? (t.reviewState ?? "pending") === state : true))
2276
+ .map((t) => ({ ...t, deadlock: detectReviewDeadlock(store, t) }))
2277
+ .sort((a, b) => String(a.reviewRequestedAt ?? a.updatedAt).localeCompare(String(b.reviewRequestedAt ?? b.updatedAt)));
2278
+ },
2279
+ retryTaskExecution(ref) {
2280
+ const task = store.requireTaskRef(ref);
2281
+ // 保留 session_id:派发前要据此判断"原执行会话是否仍在执行"(防重复下发)。
2282
+ // 需要显式解绑请用 releaseTaskAssignment(释放归属)。
2283
+ // FR-78:人工显式重跑 → 记 `requeued_at`(放宽"近期成功窗口")并清零失败计数。
2284
+ // FR-80:人工介入 → 撤下「人工兜底」标记(人已看过),但**复发计数绝不清零**——
2285
+ // 清零正是 hermes 注释警告的"失忆",会让"阻断→重跑→再阻断"无限循环且永远不升级。
2286
+ db.prepare("update tasks set status = 'todo', claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null, consecutive_failures = 0, last_failure_error = null, requeued_at = ?, triage_at = null, blocked_at = null, version = version + 1, updated_at = ? where id = ?").run(nowIso(), nowIso(), task.id);
2287
+ // FR-82:人工重跑 = 上一次尝试作废(若还挂着),并追加事件
2288
+ store.endTaskRun(task.identifier, { outcome: "cancelled", summary: "人工退回待办(重新派发)", actor: "human" });
2289
+ store.recordTaskEvent(task.id, { type: "requeued", from: task.status, to: "todo", actor: "human", detail: "人工退回待办(重新派发)" });
2290
+ try {
2291
+ const labels = (store.getTaskById(task.id).labels || []).filter((l) => l !== TRIAGE_LABEL);
2292
+ db.prepare("update tasks set labels = ? where id = ?").run(JSON.stringify(labels), task.id);
2293
+ } catch { /* ignore */ }
2294
+ // 释放该任务的活跃团队锁(否则"退回待办"后循环仍会因任务级锁跳过,永远不再派发)
2295
+ db.prepare("update team_tasks set status = 'cancelled', updated_at = ? where task_id = ? and status in ('open','running')").run(nowIso(), task.id);
2296
+ return store.getTaskById(task.id);
2297
+ },
2298
+ releaseTaskAssignment(ref) {
2299
+ const task = store.requireTaskRef(ref);
2300
+ db.prepare("update tasks set session_id = null, claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null, version = version + 1, updated_at = ? where id = ?").run(nowIso(), task.id);
2301
+ // FR-82:释放归属 = 尝试终止(避免留下永远 running 的孤儿尝试)
2302
+ store.endTaskRun(task.identifier, { outcome: "released", summary: "人工释放归属", actor: "human" });
2303
+ store.recordTaskEvent(task.id, { type: "released", actor: "human", detail: "释放执行归属" });
2304
+ return store.getTaskById(task.id);
2305
+ },
2306
+ // ---------------- 可操作诊断(FR-79) ----------------
2307
+ /**
2308
+ * 落库一批诊断(**诊断的唯一写入口**,规则在 `src/core/diagnostics.mjs`):
2309
+ * - 同一 `(task, kind)` 只留一行:问题仍在 → `count + 1` / `last_seen_at` 前进(不重复刷屏);
2310
+ * 曾经消解过又重新出现 → 计数重开(`count = 1`,`first_seen_at` 重置)
2311
+ * - 本次**未产出**的活跃行 → 写 `resolved_at`(问题消失即**自动消解**)
2312
+ * `minGapMs`(默认 60s):看板轮询会反复评估同一问题,此窗口内的重复评估**只刷新文案、不再加计数**
2313
+ * —— 让 `count` 表示"问题出现的次数(分钟粒度合并)",而不是"被轮询了几次"。
2314
+ * 返回 `{ active, resolved }`(active 已按严重度排序)。
2315
+ */
2316
+ saveTaskDiagnostics(ref, diagnostics = [], { now = null, minGapMs = 60 * 1000 } = {}) {
2317
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
2318
+ const ts = now ?? Date.now();
2319
+ const at = new Date(ts).toISOString();
2320
+ const existing = db.prepare("select * from task_diagnostics where task_id = ?").all(task.id).map(rowToDiagnostic);
2321
+ const byKind = new Map(existing.map((d) => [d.kind, d]));
2322
+ const upsert = db.prepare(
2323
+ `update task_diagnostics set severity = ?, title = ?, detail = ?, suggested = ?, actions = ?,
2324
+ count = ?, first_seen_at = ?, last_seen_at = ?, resolved_at = null, version = version + 1 where id = ?`,
2325
+ );
2326
+ const insert = db.prepare(
2327
+ `insert into task_diagnostics (id, task_id, kind, severity, title, detail, suggested, actions, count, first_seen_at, last_seen_at)
2328
+ values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
2329
+ );
2330
+ const active = [];
2331
+ for (const d of diagnostics) {
2332
+ if (!d?.kind) continue;
2333
+ const prev = byKind.get(d.kind);
2334
+ const stillActive = Boolean(prev && !prev.resolvedAt);
2335
+ const tooSoon = stillActive && (ts - new Date(prev.lastSeenAt).getTime()) < minGapMs;
2336
+ const count = stillActive ? (tooSoon ? prev.count : prev.count + 1) : 1;
2337
+ const firstSeenAt = stillActive ? prev.firstSeenAt : at;
2338
+ const lastSeenAt = tooSoon ? prev.lastSeenAt : at;
2339
+ const actions = JSON.stringify(d.actions ?? []);
2340
+ // 同一分钟内、内容也没变的重复评估 → 不写库(避免轮询制造无意义写入与版本号膨胀)
2341
+ if (prev && tooSoon && prev.severity === d.severity && prev.title === d.title && prev.detail === (d.detail ?? "") && JSON.stringify(prev.actions) === actions) {
2342
+ active.push({ ...d, taskId: task.id, taskIdentifier: task.identifier, taskTitle: task.title, count, firstSeenAt, lastSeenAt, resolvedAt: null });
2343
+ continue;
2344
+ }
2345
+ if (prev) upsert.run(d.severity, d.title, d.detail ?? "", d.suggested ?? null, actions, count, firstSeenAt, lastSeenAt, prev.id);
2346
+ else insert.run(randomUUID(), task.id, d.kind, d.severity, d.title, d.detail ?? "", d.suggested ?? null, actions, count, firstSeenAt, lastSeenAt);
2347
+ active.push({ ...d, taskId: task.id, taskIdentifier: task.identifier, taskTitle: task.title, count, firstSeenAt, lastSeenAt, resolvedAt: null });
2348
+ }
2349
+ const activeKinds = new Set(active.map((d) => d.kind));
2350
+ const resolved = [];
2351
+ const resolveSql = db.prepare("update task_diagnostics set resolved_at = ?, last_seen_at = ?, version = version + 1 where id = ?");
2352
+ for (const d of existing) {
2353
+ if (activeKinds.has(d.kind) || d.resolvedAt) continue;
2354
+ resolveSql.run(at, at, d.id);
2355
+ resolved.push({ kind: d.kind, resolvedAt: at, count: d.count });
2356
+ }
2357
+ const rank = { high: 3, medium: 2, low: 1 };
2358
+ active.sort((a, b) => (rank[b.severity] - rank[a.severity]) || a.kind.localeCompare(b.kind));
2359
+ return { active, resolved };
2360
+ },
2361
+ /** 读诊断(默认只读活跃项;`includeResolved` 带历史,供详情回溯)。 */
2362
+ listTaskDiagnostics(ref, { includeResolved = false } = {}) {
2363
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
2364
+ const rows = db.prepare("select * from task_diagnostics where task_id = ? order by rowid").all(task.id).map(rowToDiagnostic);
2365
+ const list = includeResolved ? rows : rows.filter((d) => !d.resolvedAt);
2366
+ const rank = { high: 3, medium: 2, low: 1 };
2367
+ return list
2368
+ .map((d) => ({ ...d, taskIdentifier: task.identifier, taskTitle: task.title }))
2369
+ .sort((a, b) => (rank[b.severity] - rank[a.severity]) || a.kind.localeCompare(b.kind));
2370
+ },
2371
+ /**
2372
+ * 人工忽略一条诊断(FR-79 / FR-76):写**忽略留痕评论**(原文可回溯)+ 标记 `resolved_at`/`dismissed_at`。
2373
+ * 规则侧据此停止产出(见 `diagnostics.dismissedKinds`),直到出现**更新的进展评论**。
2374
+ */
2375
+ dismissTaskDiagnostic(ref, kind, { actor = "human", note = null, now = null } = {}) {
2376
+ const task = store.requireTaskRef(ref);
2377
+ const at = new Date(now ?? Date.now()).toISOString();
2378
+ const row = db.prepare("select * from task_diagnostics where task_id = ? and kind = ?").get(task.id, String(kind));
2379
+ const body = `已忽略诊断「${kind}」:${row?.title ?? "(无记录)"}(人工决策${note ? `:${note}` : ""})`;
2380
+ store.addComment(task.id, { body });
2381
+ if (row) db.prepare("update task_diagnostics set resolved_at = ?, dismissed_at = ?, version = version + 1 where id = ?").run(at, at, row.id);
2382
+ try { store.recordAudit({ actor, action: "diagnostic-dismiss", target: task.identifier, allowed: true, reason: String(kind) }); } catch { /* ignore */ }
2383
+ return { dismissed: true, kind: String(kind), identifier: task.identifier, hadRecord: Boolean(row) };
2384
+ },
2385
+ // ---------------- 尝试记录与事件流(FR-82) ----------------
2386
+ /** 全库单调事件游标(**FR-81 的推送游标**就是它;独立计数表,任务删除也不回收已发号)。 */
2387
+ nextEventCursor() {
2388
+ db.prepare("insert into event_cursor (id, value) values (1, 1) on conflict(id) do update set value = value + 1").run();
2389
+ return Number(db.prepare("select value from event_cursor where id = 1").get()?.value ?? 0);
2390
+ },
2391
+ /**
2392
+ * 追加一条任务事件(**追加式**,供看护 / 通知 / 详情共同消费——不各自造数)。
2393
+ * 事件写失败不阻断主流程(返回 null),保证生命周期方法不被可观测性拖垮。
2394
+ */
2395
+ recordTaskEvent(ref, { type, from = null, to = null, actor = "system", detail = null, now = null } = {}) {
2396
+ try {
2397
+ if (!type) return null;
2398
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
2399
+ const at = new Date(now ?? Date.now()).toISOString();
2400
+ const seq = Number(db.prepare("select coalesce(max(seq), 0) + 1 as n from task_events where task_id = ?").get(task.id)?.n ?? 1);
2401
+ const cursor = store.nextEventCursor();
2402
+ db.prepare(
2403
+ `insert into task_events (id, task_id, cursor, seq, type, from_value, to_value, actor, detail, at)
2404
+ values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
2405
+ ).run(randomUUID(), task.id, cursor, seq, String(type), from, to, actor, detail, at);
2406
+ return { cursor, seq, type: String(type), at };
2407
+ } catch { return null; }
2408
+ },
2409
+ /** 读任务事件流(`since` = 已见到的 cursor,返回 **cursor 更大**的增量;FR-81 直接复用)。 */
2410
+ listTaskEvents(ref, { since = 0, limit = 200, order = "asc" } = {}) {
2411
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
2412
+ const dir = String(order).toLowerCase() === "desc" ? "desc" : "asc";
2413
+ return db.prepare(`select * from task_events where task_id = ? and cursor > ? order by cursor ${dir} limit ?`)
2414
+ .all(task.id, Number(since) || 0, Math.max(1, Number(limit) || 200)).map(rowToTaskEvent);
2415
+ },
2416
+ /** 读项目事件流(跨任务按全库游标排序;FR-81 订阅推送的数据源)。 */
2417
+ listProjectEvents(projectId, { since = 0, limit = 200, order = "asc" } = {}) {
2418
+ const project = store.getProject(projectId) ?? store.requireProject(projectId);
2419
+ const dir = String(order).toLowerCase() === "desc" ? "desc" : "asc";
2420
+ return db.prepare(
2421
+ `select e.* from task_events e join tasks t on t.id = e.task_id
2422
+ where t.project_id = ? and e.cursor > ? order by e.cursor ${dir} limit ?`,
2423
+ ).all(project.id, Number(since) || 0, Math.max(1, Number(limit) || 200)).map(rowToTaskEvent);
2424
+ },
2425
+ /** 全部尝试记录(按第几次尝试升序)。 */
2426
+ listTaskRuns(ref) {
2427
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
2428
+ return db.prepare("select * from task_runs where task_id = ? order by attempt, rowid").all(task.id).map(rowToRun);
2429
+ },
2430
+ getTaskRun(runId) {
2431
+ return rowToRun(db.prepare("select * from task_runs where id = ?").get(String(runId)));
2432
+ },
2433
+ /** 进行中的尝试(任务指针优先,兜底查最新 running 行)。 */
2434
+ getCurrentRun(ref) {
2435
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
2436
+ if (task.currentRunId) {
2437
+ const row = db.prepare("select * from task_runs where id = ? and status = 'running'").get(task.currentRunId);
2438
+ if (row) return rowToRun(row);
2439
+ }
2440
+ return rowToRun(db.prepare("select * from task_runs where task_id = ? and status = 'running' order by attempt desc limit 1").get(task.id));
2441
+ },
2442
+ /**
2443
+ * 开一条尝试记录(FR-82):**认领执行即自动开**(`claimTask` 已接线),也可显式调用。
2444
+ * 已在跑则返回 `{started:false}`(幂等,不产生重复尝试)。
2445
+ */
2446
+ startTaskRun(ref, { sessionId = null, claimLock = null, maxMs = DEFAULT_RUN_MAX_MS, actor = "system", now = null } = {}) {
2447
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
2448
+ // FR-85b:人工校验任务不产生"尝试"(它不是可执行工作)
2449
+ if (isHumanReviewTask(task)) {
2450
+ throw new TbError("HUMAN_REVIEW_NOT_EXECUTABLE", `任务 ${task.identifier} 是人工校验任务:不得开启执行尝试`, { identifier: task.identifier });
2451
+ }
2452
+ const existing = store.getCurrentRun(task);
2453
+ if (existing) return { started: false, reason: "already-running", run: existing };
2454
+ const at = new Date(now ?? Date.now()).toISOString();
2455
+ const attempt = Number(db.prepare("select coalesce(max(attempt), 0) + 1 as n from task_runs where task_id = ?").get(task.id)?.n ?? 1);
2456
+ const id = randomUUID();
2457
+ db.prepare(
2458
+ `insert into task_runs (id, task_id, attempt, status, claim_lock, session_id, actor, started_at, heartbeats, last_heartbeat_at, max_ms, created_at, updated_at)
2459
+ values (?, ?, ?, 'running', ?, ?, ?, ?, 1, ?, ?, ?, ?)`,
2460
+ ).run(id, task.id, attempt, claimLock, sessionId, actor, at, at, maxMs == null ? null : Number(maxMs), at, at);
2461
+ db.prepare("update tasks set current_run_id = ?, version = version + 1, updated_at = ? where id = ?").run(id, at, task.id);
2462
+ store.recordTaskEvent(task.id, { type: "run_started", actor, to: "running", detail: `第 ${attempt} 次尝试开始`, now });
2463
+ return { started: true, run: rowToRun(db.prepare("select * from task_runs where id = ?").get(id)) };
2464
+ },
2465
+ /** 尝试心跳(FR-82 的 heartbeats 计数;与 FR-77 的认领心跳同源,缺心跳本身不算失败)。 */
2466
+ heartbeatTaskRun(ref, { now = null, maxMs = null } = {}) {
2467
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
2468
+ const run = store.getCurrentRun(task);
2469
+ if (!run) return { ok: false, reason: "no-running-run" };
2470
+ const at = new Date(now ?? Date.now()).toISOString();
2471
+ db.prepare("update task_runs set heartbeats = heartbeats + 1, last_heartbeat_at = ?, updated_at = ? where id = ? and status = 'running'").run(at, at, run.id);
2472
+ if (maxMs != null) db.prepare("update task_runs set max_ms = ? where id = ?").run(Number(maxMs), run.id);
2473
+ store.recordTaskEvent(task.id, { type: "heartbeat", to: "running", detail: `第 ${run.attempt} 次尝试心跳`, now });
2474
+ return { ok: true, runId: run.id, attempt: run.attempt, at };
2475
+ },
2476
+ /**
2477
+ * 闭合当前尝试(FR-82):写 `outcome` + 摘要/错误 + `ended_at`/`duration_ms`,清空任务指针。
2478
+ * 只有**成功完成**(`outcome:"success"`)才算任务层面的成功;其余口径(blocked/crash/timeout/reclaimed…)照实记录。
2479
+ */
2480
+ endTaskRun(ref, { outcome = "ended", summary = null, error = null, actor = "system", now = null } = {}) {
2481
+ const task = ref && typeof ref === "object" && ref.id ? ref : store.requireTaskRef(ref);
2482
+ const run = store.getCurrentRun(task);
2483
+ if (!run) return { ended: false, reason: "no-running-run" };
2484
+ const at = new Date(now ?? Date.now()).toISOString();
2485
+ const durationMs = Math.max(0, new Date(at).getTime() - new Date(run.startedAt).getTime());
2486
+ db.prepare(
2487
+ "update task_runs set status = 'ended', outcome = ?, summary = ?, error = ?, ended_at = ?, duration_ms = ?, updated_at = ? where id = ? and status = 'running'",
2488
+ ).run(String(outcome), summary == null ? null : String(summary).slice(0, 500), error == null ? null : String(error).slice(0, 1000), at, durationMs, at, run.id);
2489
+ db.prepare("update tasks set current_run_id = null, version = version + 1, updated_at = ? where id = ?").run(at, task.id);
2490
+ store.recordTaskEvent(task.id, { type: "run_ended", actor, from: "running", to: String(outcome), detail: `第 ${run.attempt} 次尝试结束:${outcome}${summary ? ` — ${String(summary).slice(0, 200)}` : ""}`, now });
2491
+ return { ended: true, run: rowToRun(db.prepare("select * from task_runs where id = ?").get(run.id)) };
2492
+ },
2493
+ /**
2494
+ * FR-82 / FR-77 **收口**:结掉「孤儿尝试」,并清掉「幽灵认领」。
2495
+ *
2496
+ * 为什么会孤儿:尝试记录由**本进程内**的执行器收尾(`endTaskRun`)。插件进程一重启,
2497
+ * 那条尝试就再也没人闭合 → 永远停在 `running`(卡片「尝试记录」显示在跑,实际没有任何进程)。
2498
+ * **真机现场(2026-10-18)**:`taskboard-workbench-63` 第 3 次尝试、`-69` 第 1 次尝试,
2499
+ * 跨约 24 小时仍是 `running`;两张卡还各自挂着一把**早已过期**的认领锁。
2500
+ *
2501
+ * 两种触发,判据**故意不同**(这是本方法最容易写错的地方):
2502
+ * · `boot: true`(插件加载时调用一次)—— 本进程之前的所有执行都已随进程消失,**不看时长**,一律收口为 `interrupted`;
2503
+ * · `boot: false`(定时器轮询)—— 只用 `runExceededMax()`(尊重该次自己的 `max_ms`)判超时收口为 `timeout`,
2504
+ * **绝不误杀**正在跑的尝试。
2505
+ *
2506
+ * 另外收掉**幽灵认领**:任务已不在执行态(不是 `in_progress`)**且该认领已过期** —— `reclaimStaleClaims()`
2507
+ * 只扫 `status = 'in_progress'` 的已认领任务,这类锁它永远扫不到,会一直挂在卡片上。
2508
+ * **口径必须收在「已过期」上**:`claimTask` 本身不改任务状态,所以「刚认领、还没被推进到 in_progress
2509
+ * 的 todo 任务」天生就是「有锁且非 in_progress」,那是**正常在途**,不许清(单测当场抓到过这条)。
2510
+ */
2511
+ reconcileOrphanRuns({ projectId = undefined, now = null, boot = false, maxMs = null } = {}) {
2512
+ const ts = now ?? Date.now();
2513
+ const at = new Date(ts).toISOString();
2514
+ const rows = db.prepare(
2515
+ `select r.*, t.identifier as task_identifier, t.project_id as task_project_id, t.status as task_status
2516
+ from task_runs r join tasks t on t.id = r.task_id
2517
+ where r.status = 'running'`,
2518
+ ).all();
2519
+ const ended = [];
2520
+ for (const row of rows) {
2521
+ if (projectId && row.task_project_id !== projectId) continue;
2522
+ const run = rowToRun(row);
2523
+ if (!boot && !runExceededMax(run, { now: ts, maxMs })) continue;
2524
+ const outcome = boot ? "interrupted" : "timeout";
2525
+ const durationMs = Math.max(0, ts - new Date(run.startedAt).getTime());
2526
+ const summary = boot
2527
+ ? "插件进程重启:本次尝试随进程消失,收口为 interrupted"
2528
+ : `本次尝试超过运行时上限(已 ${Math.round(durationMs / 1000)}s),收口为 timeout`;
2529
+ db.prepare(
2530
+ "update task_runs set status = 'ended', outcome = ?, summary = ?, ended_at = ?, duration_ms = ?, updated_at = ? where id = ? and status = 'running'",
2531
+ ).run(outcome, summary, at, durationMs, at, run.id);
2532
+ // 只在指针确实指向这条时才清指针,避免误清别人刚开的新尝试
2533
+ db.prepare("update tasks set current_run_id = null, version = version + 1, updated_at = ? where id = ? and current_run_id = ?").run(at, row.task_id, run.id);
2534
+ store.recordTaskEvent(row.task_id, {
2535
+ type: "run_ended", actor: "system", from: "running", to: outcome,
2536
+ detail: `第 ${run.attempt} 次尝试收口:${outcome}${boot ? "(进程重启)" : "(超过运行时上限)"}`,
2537
+ now: ts,
2538
+ });
2539
+ try { store.recordAudit({ actor: "system", action: "reconcile-run", target: row.task_identifier, allowed: true, reason: boot ? "boot" : "run-exceeded-max", detail: `attempt=${run.attempt} outcome=${outcome}` }); } catch { /* ignore */ }
2540
+ // 超时收口同理(`boot` 的 `interrupted` 不在此列:那是进程重启,属另一类事故,已有自己的留痕)。
2541
+ const untakenRun = boot ? null : (() => { try { return store.noteUntakenDelivery(row.task_identifier, { now: ts }); } catch { return null; } })();
2542
+ ended.push({ identifier: row.task_identifier, attempt: run.attempt, outcome, untaken: untakenRun ? untakenRun.reason : null });
2543
+ }
2544
+ const ghostClaims = db.prepare(
2545
+ "select identifier from tasks where claim_lock is not null and status <> 'in_progress' and (claim_expires is null or claim_expires < ?)",
2546
+ ).all(at).map((r) => r.identifier);
2547
+ for (const ref of ghostClaims) {
2548
+ db.prepare(
2549
+ "update tasks set claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null, version = version + 1, updated_at = ? where identifier = ? and claim_lock is not null and status <> 'in_progress' and (claim_expires is null or claim_expires < ?)",
2550
+ ).run(at, ref, at);
2551
+ try { store.recordAudit({ actor: "system", action: "reconcile-claim", target: ref, allowed: true, reason: "claim-on-non-executing-task" }); } catch { /* ignore */ }
2552
+ }
2553
+ return { ended, ghostClaims };
2554
+ },
2555
+ /**
2556
+ * FR-76:把执行反馈里的"下一步建议"**派生为关联子任务**。
2557
+ * 子任务:`parentId=原任务`、归因**同一需求条目**、状态=待办池(`backlog`,不自动开工)。
2558
+ */
2559
+ deriveSubtask(ref, { title, description = "", actor = "human" } = {}) {
2560
+ const parent = store.requireTaskRef(ref);
2561
+ const t = assertTitle(title);
2562
+ const child = store.createTask({
2563
+ projectId: parent.projectId, title: t,
2564
+ description: description || `由 ${parent.identifier} 的执行反馈「下一步建议」派生(来源:${actor})`,
2565
+ status: "backlog", parentId: parent.id,
2566
+ });
2567
+ if (parent.requirementId) { try { store.associateRequirementTask(parent.requirementId, child.id); } catch { /* ignore */ } }
2568
+ store.addComment(parent.id, { body: `由「下一步建议」派生为子任务 ${child.identifier}:${t}` });
2569
+ return store.getTaskById(child.id);
2570
+ },
2571
+ // ---------------- 通知订阅与唤醒(FR-81) ----------------
2572
+ /**
2573
+ * 建订阅(同 `项目 + 任务 + 会话 + 模式` 唯一,重复即复用并重新启用)。
2574
+ * `taskRef` 为空 = **项目级**订阅(该项目所有任务的终态);`since` 可把游标放到指定位置(默认 0 = 从现在起全量)。
2575
+ */
2576
+ createNotifySubscription({ projectId, taskRef = null, sessionId = null, mode = "notify+wake", since = null } = {}) {
2577
+ const project = store.requireProject(projectId);
2578
+ const norm = normalizeDeliveryMode(mode);
2579
+ if (!norm.valid) throw invalidField("mode", `交付模式必须是 ${NOTIFY_DELIVERY_MODES.join(" / ")} 之一:${mode}`);
2580
+ const sid = String(sessionId ?? "").trim();
2581
+ if (!sid) throw invalidField("sessionId", "订阅必须指定目标会话(工作台关着时把终态闭环回去的那条会话)");
2582
+ const task = taskRef ? store.requireTaskRef(taskRef) : null;
2583
+ if (task && task.projectId !== project.id) throw invalidField("taskRef", `任务 ${task.identifier} 不属于项目 ${project.id}`);
2584
+ const ts = nowIso();
2585
+ const cursor = since == null ? null : Math.max(0, Number(since) || 0);
2586
+ const existing = db.prepare("select * from notify_subs where project_id = ? and ifnull(task_id, '') = ? and session_id = ? and mode = ?")
2587
+ .get(project.id, task?.id ?? "", sid, norm.mode);
2588
+ if (existing) {
2589
+ db.prepare("update notify_subs set active = 1, last_cursor = ?, updated_at = ? where id = ?")
2590
+ .run(cursor ?? Number(existing.last_cursor ?? 0), ts, existing.id);
2591
+ return rowToNotifySub(db.prepare("select * from notify_subs where id = ?").get(existing.id));
2592
+ }
2593
+ const id = randomUUID();
2594
+ db.prepare(
2595
+ `insert into notify_subs (id, project_id, task_id, session_id, mode, active, last_cursor, last_kinds, created_at, updated_at)
2596
+ values (?, ?, ?, ?, ?, 1, ?, '[]', ?, ?)`,
2597
+ ).run(id, project.id, task?.id ?? null, sid, norm.mode, cursor ?? 0, ts, ts);
2598
+ try {
2599
+ store.recordAudit({ actor: "human", action: "notify-subscribe", target: task ? task.identifier : project.id, allowed: true, reason: norm.mode, detail: `session=${sid}` });
2600
+ } catch { /* ignore */ }
2601
+ return rowToNotifySub(db.prepare("select * from notify_subs where id = ?").get(id));
2602
+ },
2603
+ /** 列出订阅(默认只看启用的;可按项目/任务过滤)。 */
2604
+ listNotifySubscriptions({ projectId = null, taskRef = null, activeOnly = true } = {}) {
2605
+ const clauses = []; const params = [];
2606
+ if (projectId) { clauses.push("project_id = ?"); params.push(store.requireProject(projectId).id); }
2607
+ if (taskRef) { clauses.push("task_id = ?"); params.push(store.requireTaskRef(taskRef).id); }
2608
+ if (activeOnly) clauses.push("active = 1");
2609
+ const where = clauses.length ? `where ${clauses.join(" and ")}` : "";
2610
+ return db.prepare(`select * from notify_subs ${where} order by created_at, rowid`).all(...params).map(rowToNotifySub);
2611
+ },
2612
+ getNotifySubscription(id) {
2613
+ return rowToNotifySub(db.prepare("select * from notify_subs where id = ?").get(String(id)));
2614
+ },
2615
+ requireNotifySubscription(id) {
2616
+ const sub = store.getNotifySubscription(id);
2617
+ if (!sub) throw new TbError("NOT_FOUND", `订阅不存在:${id}`, { id });
2618
+ return sub;
2619
+ },
2620
+ /** 局部更新:只改传了的字段(`since` 可重置游标;`active:false` = 软停用)。 */
2621
+ updateNotifySubscription(id, { mode, active, sessionId, since } = {}) {
2622
+ const sub = store.requireNotifySubscription(id);
2623
+ const sets = []; const params = [];
2624
+ if (mode !== undefined) {
2625
+ const norm = normalizeDeliveryMode(mode);
2626
+ if (!norm.valid) throw invalidField("mode", `交付模式必须是 ${NOTIFY_DELIVERY_MODES.join(" / ")} 之一:${mode}`);
2627
+ sets.push("mode = ?"); params.push(norm.mode);
2628
+ }
2629
+ if (sessionId !== undefined) {
2630
+ const sid = String(sessionId ?? "").trim();
2631
+ if (!sid) throw invalidField("sessionId", "目标会话不能为空");
2632
+ sets.push("session_id = ?"); params.push(sid);
2633
+ }
2634
+ if (active !== undefined) { sets.push("active = ?"); params.push(active ? 1 : 0); }
2635
+ if (since !== undefined) { sets.push("last_cursor = ?"); params.push(Math.max(0, Number(since) || 0)); }
2636
+ if (!sets.length) return sub;
2637
+ sets.push("updated_at = ?"); params.push(nowIso());
2638
+ db.prepare(`update notify_subs set ${sets.join(", ")} where id = ?`).run(...params, sub.id);
2639
+ try {
2640
+ store.recordAudit({ actor: "human", action: "notify-update", target: sub.id, allowed: true, reason: Object.keys({ mode, active, sessionId, since }).filter((k) => ({ mode, active, sessionId, since })[k] !== undefined).join(",") });
2641
+ } catch { /* ignore */ }
2642
+ return store.getNotifySubscription(sub.id);
2643
+ },
2644
+ /** 默认**软停用**(保数据、保留游标);`purge:true` 才真删(必须先有明确人工指示)。 */
2645
+ deleteNotifySubscription(id, { purge = false } = {}) {
2646
+ const sub = store.requireNotifySubscription(id);
2647
+ if (purge) {
2648
+ db.prepare("delete from notify_subs where id = ?").run(sub.id);
2649
+ try { store.recordAudit({ actor: "human", action: "notify-unsubscribe", target: sub.id, allowed: true, reason: "purge", detail: `${sub.mode} session=${sub.sessionId}` }); } catch { /* ignore */ }
2650
+ return { subscription: { ...sub, active: false }, purged: true };
2651
+ }
2652
+ const updated = store.updateNotifySubscription(sub.id, { active: false });
2653
+ try { store.recordAudit({ actor: "human", action: "notify-unsubscribe", target: sub.id, allowed: true, reason: "deactivate", detail: `${sub.mode} session=${sub.sessionId}` }); } catch { /* ignore */ }
2654
+ return { subscription: updated, purged: false };
2655
+ },
2656
+ /** 订阅可见的**未推送终态事件**(不推进游标;`since` 默认取订阅自己的游标)。 */
2657
+ notifySubPending(id, { since = null, limit = 200 } = {}) {
2658
+ const sub = store.getNotifySubscription(id);
2659
+ if (!sub) throw new TbError("NOT_FOUND", `订阅不存在:${id}`, { id });
2660
+ const from = since == null ? sub.lastCursor : Math.max(0, Number(since) || 0);
2661
+ const scoped = sub.taskId
2662
+ ? store.listTaskEvents(sub.taskId, { since: from, limit })
2663
+ : store.listProjectEvents(sub.projectId, { since: from, limit });
2664
+ const picked = selectNotifyEvents(scoped, { since: from });
2665
+ return {
2666
+ subscription: sub, since: from, cursor: picked.cursor, count: picked.events.length,
2667
+ events: picked.events, kinds: [...new Set(picked.events.map((e) => e.kind))],
2668
+ scanned: picked.scanned, skipped: picked.skipped, deduped: picked.deduped,
2669
+ };
2670
+ },
2671
+ /** 项目级"通知预览":看某项目游标之后有哪些终态事件待推(不落库、不推进游标)。 */
2672
+ notifyPreviewEvents({ projectId, taskRef = null, since = 0, limit = 200 } = {}) {
2673
+ const project = store.requireProject(projectId);
2674
+ const scoped = taskRef
2675
+ ? store.listTaskEvents(taskRef, { since, limit })
2676
+ : store.listProjectEvents(project.id, { since, limit });
2677
+ const picked = selectNotifyEvents(scoped, { since });
2678
+ return { project: project.id, since: Number(since) || 0, cursor: picked.cursor, count: picked.events.length, events: picked.events, kinds: [...new Set(picked.events.map((e) => e.kind))] };
2679
+ },
2680
+ /**
2681
+ * 推送一轮(FR-81 的**唯一投递入口**)。
2682
+ * - 成功 → 按模式写评论留痕(`notify` / `notify+wake`)+ 推进 `last_cursor`;
2683
+ * - 失败 → **不推进游标**、`failed_count+1`、`last_error` 照实记录(不静默丢失,下轮自动重试)。
2684
+ * `deliver` 由调用方注入(`sync`);不传则回落到 `store.hostSessionPort.sendPrompt`(宿主不可用 → 记为失败)。
2685
+ */
2686
+ async flushNotifySubscriptions({ projectId = null, subId = null, deliver = null, now = null } = {}) {
2687
+ const subs = subId ? [store.requireNotifySubscription(subId)] : store.listNotifySubscriptions({ projectId, activeOnly: true });
2688
+ const results = [];
2689
+ for (const sub of subs) {
2690
+ const pending = store.notifySubPending(sub.id);
2691
+ if (!pending.count) {
2692
+ results.push({ id: sub.id, projectId: sub.projectId, sessionId: sub.sessionId, mode: sub.mode, scope: sub.scope, kinds: [], count: 0, cursor: pending.cursor, delivered: false, via: null, error: null, commented: 0, reason: "no-terminal-events" });
2693
+ continue;
2694
+ }
2695
+ const project = store.getProject(sub.projectId);
2696
+ const msg = buildNotifyMessage({ project, events: pending.events, mode: sub.mode, taskOf: (tid) => store.getTaskById(tid) });
2697
+ const send = deliver ?? ((target, text) => (typeof store.hostSessionPort?.sendPrompt === "function"
2698
+ ? store.hostSessionPort.sendPrompt(target, text)
2699
+ : Promise.resolve({ sent: false, via: "unavailable", error: "宿主会话通道不可用(sessionController 未注册)" })));
2700
+ let ok = true; let via = "comment"; let error = null; let commented = 0;
2701
+ if (msg.prompt) {
2702
+ try {
2703
+ const r = await send(sub.sessionId, msg.prompt);
2704
+ ok = r?.sent !== false;
2705
+ via = r?.via ?? null;
2706
+ if (!ok) error = String(r?.error ?? "投递失败(目标会话可能已失效)");
2707
+ } catch (e) {
2708
+ ok = false; via = null; error = String(e?.message ?? e);
2709
+ }
2710
+ }
2711
+ if (ok && msg.commentBody) {
2712
+ for (const tid of msg.taskIds) {
2713
+ try { store.addComment(tid, { body: msg.commentBody }); commented += 1; } catch { /* ignore */ }
2714
+ }
2715
+ }
2716
+ const at = new Date(now ?? Date.now()).toISOString();
2717
+ if (ok) {
2718
+ db.prepare("update notify_subs set last_cursor = ?, delivered_count = delivered_count + 1, last_kinds = ?, last_delivery_at = ?, last_error = null, updated_at = ? where id = ?")
2719
+ .run(pending.cursor, JSON.stringify(pending.kinds), at, at, sub.id);
2720
+ } else {
2721
+ db.prepare("update notify_subs set failed_count = failed_count + 1, last_error = ?, last_kinds = ?, updated_at = ? where id = ?")
2722
+ .run(`${at}|${error}`.slice(0, 500), JSON.stringify(pending.kinds), at, sub.id);
2723
+ }
2724
+ results.push({
2725
+ id: sub.id, projectId: sub.projectId, sessionId: sub.sessionId, mode: sub.mode, scope: sub.scope,
2726
+ kinds: pending.kinds, count: pending.count, cursor: pending.cursor, delivered: ok, via, error, commented,
2727
+ taskIds: msg.taskIds,
2728
+ });
2729
+ }
2730
+ return { count: results.length, results };
2731
+ },
2732
+ // ---------------- 团队执行记录(FR-42) ----------------
2733
+ createTeamRun({ targetTask = null, targetRequirement = null, status = "staged" } = {}) {
2734
+ const id = randomUUID(); const ts = nowIso();
2735
+ let taskId = null; let reqId = null;
2736
+ if (targetTask) taskId = store.requireTaskRef(targetTask).id;
2737
+ if (targetRequirement) reqId = store.requireRequirementItemRef(targetRequirement).id;
2738
+ db.prepare("insert into team_runs (id, target_task_id, target_requirement_id, status, created_at, updated_at) values (?,?,?,?,?,?)").run(id, taskId, reqId, status, ts, ts);
2739
+ return store.getTeamRun(id);
2740
+ },
2741
+ getTeamRun(id) {
2742
+ const row = db.prepare("select * from team_runs where id = ?").get(id);
2743
+ return row ? { id: row.id, targetTaskId: row.target_task_id, targetRequirementId: row.target_requirement_id, status: row.status, createdAt: row.created_at, updatedAt: row.updated_at } : null;
2744
+ },
2745
+ // ---------------- 项目设置(FR-56):项目环境约束 + agent 执行团队模板 ----------------
2746
+ getProjectSettings(projectId) {
2747
+ store.requireProject(projectId);
2748
+ const row = db.prepare("select * from project_settings where project_id = ?").get(projectId);
2749
+ const parse = (s) => { try { return JSON.parse(s); } catch { return {}; } };
2750
+ return row
2751
+ ? { projectId, envConfig: parse(row.env_config), teamTemplate: parse(row.team_template), loop: parse(row.loop_config), updatedAt: row.updated_at }
2752
+ : { projectId, envConfig: {}, teamTemplate: {}, loop: {}, updatedAt: null };
2753
+ },
2754
+ saveProjectSettings(projectId, { envConfig, teamTemplate, loop } = {}) {
2755
+ store.requireProject(projectId);
2756
+ const current = store.getProjectSettings(projectId);
2757
+ const nextEnv = envConfig === undefined ? current.envConfig : envConfig;
2758
+ const nextTpl = teamTemplate === undefined ? current.teamTemplate : teamTemplate;
2759
+ const nextLoop = loop === undefined ? current.loop : loop;
2760
+ const ts = nowIso();
2761
+ db.prepare(
2762
+ `insert into project_settings (project_id, env_config, team_template, loop_config, updated_at) values (?,?,?,?,?)
2763
+ on conflict(project_id) do update set env_config = excluded.env_config, team_template = excluded.team_template, loop_config = excluded.loop_config, updated_at = excluded.updated_at`,
2764
+ ).run(projectId, JSON.stringify(nextEnv ?? {}), JSON.stringify(nextTpl ?? {}), JSON.stringify(nextLoop ?? {}), ts);
2765
+ return store.getProjectSettings(projectId);
2766
+ },
2767
+ /** 列出团队执行记录(可按目标任务过滤),并带出目标任务编号/标题,供工作台"归属团队"视图使用。 */
2768
+ listTeamRuns({ targetTask = null, status = null, limit = 100 } = {}) {
2769
+ const clauses = []; const params = [];
2770
+ if (targetTask) { const t = store.requireTaskRef(targetTask); clauses.push("r.target_task_id = ?"); params.push(t.id); }
2771
+ if (status) { clauses.push("r.status = ?"); params.push(status); }
2772
+ const where = clauses.length ? `where ${clauses.join(" and ")}` : "";
2773
+ const rows = db.prepare(
2774
+ `select r.*, t.identifier as target_identifier, t.title as target_title, t.status as target_status
2775
+ from team_runs r left join tasks t on t.id = r.target_task_id ${where}
2776
+ order by r.created_at desc, r.rowid desc limit ?`,
2777
+ ).all(...params, limit);
2778
+ return rows.map((r) => ({
2779
+ id: r.id, targetTaskId: r.target_task_id, targetTaskIdentifier: r.target_identifier ?? null,
2780
+ targetTaskTitle: r.target_title ?? null, targetTaskStatus: r.target_status ?? null,
2781
+ targetRequirementId: r.target_requirement_id, status: r.status, createdAt: r.created_at, updatedAt: r.updated_at,
2782
+ }));
2783
+ },
2784
+ addTeamMember({ teamId, role, model = null, executor = null, status = "ready" } = {}) {
2785
+ if (!store.getTeamRun(teamId)) throw new TbError("TEAM_NOT_FOUND", `团队不存在:${teamId}`, { teamId });
2786
+ // FR-50 验收第一条(2026-10-26 修):模板声明的是「角色集合与**数量**、每角色模型与**执行器**」,
2787
+ // 因此同一团队同一角色**可以有多名成员**(`count>1`)——这里**不再按 role 去重**。
2788
+ // 去重会在 `count:2` 时把两名 engineer 折叠成一名,并使「按模板装配」名不副实。
2789
+ // 需要「只有一个」的调用方,请在装配计划里自行保证(建队路径已按 count 展开)。
2790
+ const id = randomUUID();
2791
+ db.prepare("insert into team_members (id, team_id, role, model, executor, status, created_at) values (?,?,?,?,?,?,?)").run(id, teamId, String(role), model, executor, status, nowIso());
2792
+ return { id, teamId, role: String(role), model, executor, status };
2793
+ },
2794
+ listTeamMembers(teamId) {
2795
+ return db.prepare("select * from team_members where team_id = ? order by created_at, rowid").all(teamId).map((r) => ({ id: r.id, teamId: r.team_id, role: r.role, model: r.model ?? null, executor: r.executor ?? null, status: r.status }));
2796
+ },
2797
+ getTeamTask(teamTaskId) {
2798
+ const r = db.prepare("select * from team_tasks where id = ?").get(teamTaskId);
2799
+ return r ? { id: r.id, teamId: r.team_id, taskId: r.task_id, memberId: r.member_id ?? null, kind: r.kind, status: r.status, attempt: r.attempt ?? null } : null;
2800
+ },
2801
+ listTeamTasks(teamId) {
2802
+ return db.prepare("select * from team_tasks where team_id = ? order by created_at, rowid").all(teamId).map((r) => ({ id: r.id, teamId: r.team_id, taskId: r.task_id, memberId: r.member_id ?? null, kind: r.kind, status: r.status, attempt: r.attempt ?? null }));
2803
+ },
2804
+ listTeamAttempts(teamTaskId) {
2805
+ return db.prepare("select * from team_attempts where team_task_id = ? order by created_at, rowid").all(teamTaskId).map((r) => ({ id: r.id, teamTaskId: r.team_task_id, attemptId: r.attempt_id ?? null, result: r.result ?? null, createdAt: r.created_at }));
2806
+ },
2807
+ /** 任务级执行锁:同任务同时只 1 个活跃团队任务;backlog 不得被团队认领(C5-②)。 */
2808
+ acquireTeamTask({ teamId, task, member = null, kind = "work" } = {}) {
2809
+ if (!store.getTeamRun(teamId)) throw new TbError("TEAM_NOT_FOUND", `团队不存在:${teamId}`, { teamId });
2810
+ const t = store.assertTeamClaimable(task);
2811
+ const id = randomUUID(); const ts = nowIso();
2812
+ try {
2813
+ db.prepare("insert into team_tasks (id, team_id, task_id, member_id, kind, status, created_at, updated_at) values (?,?,?,?,?, 'running', ?, ?)").run(id, teamId, t.id, member, kind, ts, ts);
2814
+ } catch (error) {
2815
+ if (String(error?.message ?? "").includes("team_tasks_active_lock") || String(error?.message ?? "").includes("UNIQUE")) {
2816
+ store.recordAudit({ actor: "team", action: "claim", target: t.identifier, allowed: false, reason: "task-locked" });
2817
+ throw new TbError("TASK_LOCKED", "该任务已有活跃执行单元(任务级执行锁)", { identifier: t.identifier });
2818
+ }
2819
+ throw error;
2820
+ }
2821
+ return store.getTeamTask(id);
2822
+ },
2823
+ /**
2824
+ * 「团队不得认领」的唯一判据来源(C5-②):backlog = 未授权开工。
2825
+ *
2826
+ * 真机 2026-10-22(续四十一):`POST /api/teams` 原先**先** `createTeamRun()`(并写成员),
2827
+ * **之后**才在 `acquireTeamTask()` 里做这条判定 ⇒ 只要 `tasks` 里混进一张 backlog 卡,
2828
+ * 请求虽被拒,库里却留下一个**空团队 run**(团队视图可见的孤儿记录)。
2829
+ * 修法:判据提成这个方法,api 层在建 run **之前**先对每个待认领 ref 预判一遍;
2830
+ * `acquireTeamTask` 仍调用它复检(口径只有这一份)。
2831
+ */
2832
+ assertTeamClaimable(ref) {
2833
+ const t = store.requireTaskRef(ref);
2834
+ if (t.status === "backlog") {
2835
+ store.recordAudit({ actor: "team", action: "claim", target: t.identifier, allowed: false, reason: "backlog-not-authorized" });
2836
+ throw new TbError("EXECUTION_NOT_AUTHORIZED", "未授权不开工:backlog 任务不得被团队认领", { identifier: t.identifier });
2837
+ }
2838
+ return t;
2839
+ },
2840
+ getTaskLock(ref) {
2841
+ const t = store.requireTaskRef(ref);
2842
+ const row = db.prepare("select * from team_tasks where task_id = ? and status in ('open','running') order by created_at desc limit 1").get(t.id);
2843
+ return row ? { id: row.id, teamId: row.team_id, taskId: row.task_id, status: row.status } : null;
2844
+ },
2845
+ releaseTeamTask(teamTaskId) {
2846
+ const row = db.prepare("select * from team_tasks where id = ?").get(teamTaskId);
2847
+ if (!row) throw new TbError("TEAM_TASK_NOT_FOUND", `团队任务不存在:${teamTaskId}`, { teamTaskId });
2848
+ db.prepare("update team_tasks set status = 'cancelled', updated_at = ? where id = ?").run(nowIso(), teamTaskId);
2849
+ return { id: teamTaskId, released: true };
2850
+ },
2851
+ recordTeamAttempt({ teamTaskId, attemptId = null, result = null } = {}) {
2852
+ const row = db.prepare("select * from team_tasks where id = ?").get(teamTaskId);
2853
+ if (!row) throw new TbError("TEAM_TASK_NOT_FOUND", `团队任务不存在:${teamTaskId}`, { teamTaskId });
2854
+ const id = randomUUID();
2855
+ db.prepare("insert into team_attempts (id, team_task_id, attempt_id, result, created_at) values (?,?,?,?,?)").run(id, teamTaskId, attemptId, result, nowIso());
2856
+ return { id, teamTaskId, attemptId, result };
2857
+ },
2858
+
2859
+ // ---------------- 人工校验任务(FR-85b · 人在环升级门) ----------------
2860
+ /**
2861
+ * 由诊断 / 阻断升级落成一条**人工校验任务**(FR-85)。
2862
+ *
2863
+ * 三条硬口径:
2864
+ * ① 只有**证据充分**才落卡 —— `draft` 必须通过 `validateHumanReviewDraft`,否则抛
2865
+ * `HUMAN_REVIEW_DRAFT_INVALID`。「判不准就不升级」是 FR-85 的原话,不许自动臆断。
2866
+ * ② **幂等**:同项目同类别仍有未结论的人工校验任务时抛 `HUMAN_REVIEW_ALREADY_EXISTS`,
2867
+ * 否则诊断每轮都会重复造卡。
2868
+ * ③ 任务本身**不可执行**:执行侧认领 / 派发 / 开尝试 / 改状态 / 置 done 全部被拦(见各入口守卫)。
2869
+ */
2870
+ createHumanReviewTask({ projectId, draft, actor = "system", requirementId = null, relatedTask = null, priority = "high" } = {}) {
2871
+ const validation = validateHumanReviewDraft(draft ?? {});
2872
+ if (!validation?.ok) {
2873
+ throw new TbError("HUMAN_REVIEW_DRAFT_INVALID", `人工校验任务草案不完整:${(validation?.errors ?? []).join(";") || "未知原因"}`, { errors: validation?.errors ?? [] });
2874
+ }
2875
+ const category = String(draft.category ?? "").trim();
2876
+ const pending = store.listHumanReviews({ projectId, state: "pending" }).find((t) => (t.humanReviewCategory ?? null) === category);
2877
+ if (pending) {
2878
+ throw new TbError("HUMAN_REVIEW_ALREADY_EXISTS", `项目 ${projectId} 已有同类人工校验任务待结论:${pending.identifier}`, { identifier: pending.identifier, category });
2879
+ }
2880
+ const task = store.createTask({
2881
+ projectId,
2882
+ title: draft.title,
2883
+ description: draft.description,
2884
+ status: "backlog",
2885
+ priority,
2886
+ labels: ["FR-85", HUMAN_REVIEW_LABEL, category].filter(Boolean),
2887
+ });
2888
+ const at = nowIso();
2889
+ db.prepare(
2890
+ `update tasks set human_review_category = ?, human_review_state = 'pending',
2891
+ requirement_id = coalesce(?, requirement_id), version = version + 1, updated_at = ?
2892
+ where id = ?`,
2893
+ ).run(category, requirementId, at, task.id);
2894
+ store.recordTaskEvent(task.id, { type: "human_review_created", to: "pending", actor, detail: `人工校验(类别 ${categoryLabel(category) ?? category}):${draft.title}` });
2895
+ try { store.recordAudit({ actor, action: "human-review-created", target: task.identifier, allowed: true, reason: "escalation", detail: `category=${category}` }); } catch { /* ignore */ }
2896
+ // 影响域:把"被这扇门挡住的下游"写成真实依赖边,结论后才能按图放行(FR-86 的"只停影响域")。
2897
+ if (relatedTask) {
2898
+ try { store.addTaskDependency({ blocker: task.identifier, blocked: relatedTask, reason: "人在环升级门:需人工校验结论后才可推进" }); } catch { /* 建边失败不阻断建卡 */ }
2899
+ }
2900
+ return store.getTaskById(task.id);
2901
+ },
2902
+ /**
2903
+ * FR-85b:把原任务**停手**在「人在环升级门」后面(等人给结论期间不许再被派发)。
2904
+ *
2905
+ * 为什么不复用 `blockTask`:`blockTask` 是 FR-80 的**阻断分类唯一入口**,会按 kind 重算
2906
+ * `block_kind` / `block_recurrences` —— 而升级门的**证据恰恰就是这两列**(同因复发 ≥2 + 阻断类型)。
2907
+ * 用它去"挡住"原任务会把刚成立的证据抹掉(复发归 1、类型被改写),门一旦成立就自毁证据链,
2908
+ * 于是幂等判定与复核都失去依据。所以这里只做"移出可开工池"这一件事,**不碰阻断会计**。
2909
+ */
2910
+ holdForHumanReview(ref, { reason = null, actor = "human", reviewTask = null, now = null } = {}) {
2911
+ const task = store.requireTaskRef(ref);
2912
+ const at = new Date(now ?? Date.now()).toISOString();
2913
+ db.prepare(
2914
+ `update tasks set status = 'blocked', blocked_at = coalesce(blocked_at, ?),
2915
+ claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null,
2916
+ version = version + 1, updated_at = ? where id = ?`,
2917
+ ).run(at, at, task.id);
2918
+ try { store.endTaskRun(task.identifier, { outcome: "blocked", summary: reason ?? "停在人在环升级门", actor, now: now ?? Date.now() }); } catch { /* 无在途尝试则忽略 */ }
2919
+ try {
2920
+ store.addComment(task.id, {
2921
+ body: `已停在「人在环升级门」后${reviewTask ? `(人工校验任务 ${reviewTask})` : ""}:${reason ?? "等人工结论"}\n结论给出前不会被自动派发;放行请走人工校验结论入口(continue / change-requirement / close)。`,
2922
+ });
2923
+ } catch { /* ignore */ }
2924
+ try { store.recordAudit({ actor, action: "hold-human-review", target: task.identifier, allowed: true, reason: "human-review-gate", detail: reviewTask ?? null }); } catch { /* ignore */ }
2925
+ store.recordTaskEvent(task.id, { type: "blocked", to: "blocked", actor, detail: `人在环升级门${reviewTask ? `:${reviewTask}` : ""}`, now: now ?? Date.now() });
2926
+ return store.getTaskById(task.id);
2927
+ },
2928
+ /** 人工校验任务队列(FR-85b)。`state` ∈ `pending` / `concluded`;不传即全部。 */
2929
+ listHumanReviews({ projectId, state = null } = {}) {
2930
+ return store.listTasks({ projectId })
2931
+ .filter((t) => isHumanReviewTask(t))
2932
+ .filter((t) => (state ? (t.humanReviewState ?? "pending") === state : true))
2933
+ .sort((a, b) => String(b.createdAt ?? "").localeCompare(String(a.createdAt ?? "")));
2934
+ },
2935
+ /** 待人工校验(FR-85b):看板"待人工校验"计数与诊断去重都用它。 */
2936
+ humanReviewPending(projectId) {
2937
+ return store.listHumanReviews({ projectId, state: "pending" });
2938
+ },
2939
+ /**
2940
+ * 人工回填结论(FR-85b):**唯一的放行出口**。
2941
+ *
2942
+ * 结论语义**只认** `human-review.mjs` 的 `conclusionOutcome()`(口径只此一处,store 不另立一套):
2943
+ * · `continue` → 放行影响域(被这扇门挡住的直接下游,且其自身依赖已就绪的,回「可开工」)
2944
+ * · `change-requirement` → 不放行(需按新口径改写需求后由人重开)
2945
+ * · `close` → 不放行(等人工另行处置)
2946
+ * 结论一旦给出,这扇门就**消耗掉了**:任务本身转「已取消」(于是不再挡依赖),原任务与下游的放行
2947
+ * 由上面的影响域决定。重复结论抛 `HUMAN_REVIEW_ALREADY_CONCLUDED`。
2948
+ */
2949
+ concludeHumanReview(ref, { conclusion, comment = "", actor = "human", now = null } = {}) {
2950
+ const task = store.requireTaskRef(ref);
2951
+ if (!isHumanReviewTask(task)) {
2952
+ throw new TbError("HUMAN_REVIEW_NOT_KIND", `任务 ${task.identifier} 不是人工校验任务`, { identifier: task.identifier });
2953
+ }
2954
+ if ((task.humanReviewState ?? "pending") === "concluded") {
2955
+ throw new TbError("HUMAN_REVIEW_ALREADY_CONCLUDED", `人工校验任务 ${task.identifier} 已有结论(${task.humanReviewConclusion}),不得重复结论`, { identifier: task.identifier, conclusion: task.humanReviewConclusion });
2956
+ }
2957
+ let normalized;
2958
+ try { normalized = assertConclusion(conclusion); } catch (error) { throw invalidField("conclusion", String(error?.message ?? error)); }
2959
+ const outcome = conclusionOutcome(normalized);
2960
+ const at = new Date(now ?? Date.now()).toISOString();
2961
+ db.prepare(
2962
+ `update tasks set human_review_state = 'concluded', human_review_conclusion = ?,
2963
+ human_review_concluded_at = ?, human_review_concluded_by = ?, version = version + 1, updated_at = ?
2964
+ where id = ?`,
2965
+ ).run(normalized, at, actor, at, task.id);
2966
+ // 门已消耗:转「已取消」(canceled 不再构成阻塞,下游可被放行)
2967
+ db.prepare("update tasks set status = 'canceled', version = version + 1, updated_at = ? where id = ?").run(at, task.id);
2968
+ store.recordTaskEvent(task.id, { type: "human_review_concluded", to: "concluded", actor, detail: `人工结论=${normalized}${comment ? `|${comment}` : ""}` });
2969
+ try { store.addComment(task.id, { body: `人工校验结论:**${normalized}**${comment ? `\n说明:${comment}` : ""}\n口径:${outcome.note ?? ""}\n操作者:${actor}` }); } catch { /* ignore */ }
2970
+ try { store.recordAudit({ actor, action: "human-review-concluded", target: task.identifier, allowed: true, reason: normalized, detail: outcome.note ?? null }); } catch { /* ignore */ }
2971
+ const released = [];
2972
+ if (outcome.releaseDownstream) {
2973
+ const downstream = db.prepare("select d.blocked_id as id from task_dependencies d where d.blocker_id = ?").all(task.id);
2974
+ for (const row of downstream) {
2975
+ const t = store.getTaskById(row.id);
2976
+ if (!t || (t.status !== "blocked" && t.status !== "todo")) continue;
2977
+ // 就绪判定:其余前置必须都已「完成」或「已取消」(**不能用 isTaskReady** —— 它把 canceled 也算未完成)
2978
+ const blockers = db.prepare("select t.status as status from task_dependencies d join tasks t on t.id = d.blocker_id where d.blocked_id = ?").all(t.id);
2979
+ if (!blockers.every((b) => b.status === "done" || b.status === "canceled")) continue;
2980
+ db.prepare(
2981
+ `update tasks set status = 'todo', blocked_at = null, claim_lock = null, claim_expires = null,
2982
+ claim_owner = null, last_heartbeat_at = null, version = version + 1, updated_at = ?
2983
+ where id = ?`,
2984
+ ).run(at, t.id);
2985
+ store.recordTaskEvent(t.id, { type: "human_review_released", from: t.status, to: "todo", actor, detail: `人工校验结论=${normalized} → 放行回「可开工」` });
2986
+ try { store.addComment(t.id, { body: `人工校验结论「${normalized}」→ 本任务已放行回「可开工」。${comment ? `\n结论说明:${comment}` : ""}` }); } catch { /* ignore */ }
2987
+ released.push(t.identifier);
2988
+ }
2989
+ }
2990
+ return { task: store.getTaskById(task.id), conclusion: normalized, outcome, released };
2991
+ },
2992
+
2993
+ // ---------------- 治理层(C5 固定红线,不可配) ----------------
2994
+ recordAudit({ actor = null, action, target = null, allowed = true, reason = null, detail = null } = {}) {
2995
+ const id = randomUUID();
2996
+ db.prepare("insert into governance_audit (id, at, actor, action, target, allowed, reason, detail) values (?,?,?,?,?,?,?,?)").run(id, nowIso(), actor, action, target, allowed ? 1 : 0, reason, detail);
2997
+ return id;
2998
+ },
2999
+ listGovernanceAudit(filter = {}) {
3000
+ const clauses = []; const params = [];
3001
+ if (filter.action) { clauses.push("action = ?"); params.push(filter.action); }
3002
+ if (filter.allowed !== undefined) { clauses.push("allowed = ?"); params.push(filter.allowed ? 1 : 0); }
3003
+ const where = clauses.length ? `where ${clauses.join(" and ")}` : "";
3004
+ return db.prepare(`select * from governance_audit ${where} order by at, rowid`).all(...params).map((r) => ({ id: r.id, at: r.at, actor: r.actor, action: r.action, target: r.target, allowed: !!r.allowed, reason: r.reason, detail: r.detail }));
3005
+ },
3006
+ /** 红线①:执行侧不得写 done → 拒绝 + 审计。 */
3007
+ teamSetTaskStatus(ref, { status, actor = "team" } = {}) {
3008
+ const t = store.requireTaskRef(ref);
3009
+ if (status === "done") {
3010
+ store.recordAudit({ actor, action: "set-status", target: t.identifier, allowed: false, reason: "agent-cannot-write-done", detail: `requested done (from ${t.status})` });
3011
+ throw new TbError("GOVERNANCE_AGENT_DONE", "红线:完成只能由人确认,执行侧不得写 done", { identifier: t.identifier });
3012
+ }
3013
+ // FR-85b:人工校验任务连状态都不许执行侧改(唯一出口是人工结论入口)
3014
+ if (isHumanReviewTask(t)) {
3015
+ store.recordAudit({ actor, action: "set-status", target: t.identifier, allowed: false, reason: "human-review-not-executable", detail: `requested ${status}` });
3016
+ throw new TbError("HUMAN_REVIEW_NOT_EXECUTABLE", `任务 ${t.identifier} 是人工校验任务:执行侧不得改其状态`, { identifier: t.identifier });
3017
+ }
3018
+ if (!TEAM_WRITABLE_STATUSES.includes(status)) throw invalidField("status", `执行侧不允许写入 ${status}`);
3019
+ // 状态离开"进行中"即释放认领(FR-77)
3020
+ const clearClaim = status === "in_progress" ? "" : ", claim_lock = null, claim_expires = null, claim_owner = null, last_heartbeat_at = null";
3021
+ db.prepare(`update tasks set status = ?${clearClaim}, version = version + 1, updated_at = ? where id = ?`).run(status, nowIso(), t.id);
3022
+ store.recordAudit({ actor, action: "set-status", target: t.identifier, allowed: true, reason: "team-writable", detail: status });
3023
+ return store.getTaskById(t.id);
3024
+ },
3025
+ /** 红线③:审查未过 / 上游失败 → 下游保持 blocked(不解锁)。 */
3026
+ blockDownstream(taskId, reason = "review-not-passed") {
3027
+ const downstream = db.prepare("select d.blocked_id as id, t.identifier as identifier, t.status as status from task_dependencies d join tasks t on t.id = d.blocked_id where d.blocker_id = ?").all(taskId);
3028
+ const blocked = [];
3029
+ for (const d of downstream) {
3030
+ if (d.status !== "done" && d.status !== "canceled") {
3031
+ // FR-83:改走统一受阻入口(`hold` 路由)—— 补齐 block_kind/blocked_at/评论/事件/尝试收口,
3032
+ // 但**保持受阻**(评审门不是"等父任务自动提升")。
3033
+ try {
3034
+ store.blockTask(d.identifier, { kind: "dependency", reason: `上游${reason === "upstream-failed" ? "失败" : "评审未过"}:${taskId}`, actor: "team", route: "hold" });
3035
+ blocked.push(d.identifier);
3036
+ } catch { /* 单个下游失败不影响其它下游 */ }
3037
+ }
3038
+ }
3039
+ if (blocked.length) store.recordAudit({ actor: "team", action: "review-gate", target: taskId, allowed: false, reason, detail: blocked.join(",") });
3040
+ return blocked;
3041
+ },
3042
+ /** 团队任务结果 → 项目任务状态(部分完成回流;不自动解锁下游)。 */
3043
+ applyTeamTaskOutcome(teamTaskId, { outcome, reviewPassed = true, evidence = "" } = {}) {
3044
+ const row = db.prepare("select * from team_tasks where id = ?").get(teamTaskId);
3045
+ if (!row) throw new TbError("TEAM_TASK_NOT_FOUND", `团队任务不存在:${teamTaskId}`, { teamTaskId });
3046
+ const t = store.getTaskById(row.task_id);
3047
+ const ev = evidence ? `(证据:${evidence})` : "";
3048
+ if (outcome === "completed") {
3049
+ db.prepare("update tasks set status = 'in_review', version = version + 1, updated_at = ? where id = ?").run(nowIso(), t.id);
3050
+ db.prepare("update team_tasks set status = 'completed', updated_at = ? where id = ?").run(nowIso(), teamTaskId);
3051
+ if (row.kind === "review" && reviewPassed !== true) store.blockDownstream(t.id, "review-not-passed");
3052
+ store.addComment(t.id, { body: `团队回报:完成 → 提交待验收${ev}` }); // 自动登记反馈
3053
+ store.markTaskSucceeded(t.identifier); // FR-78:成功即清零失败计数
3054
+ } else if (outcome === "failed") {
3055
+ // FR-80:团队回报失败也走统一受阻入口(transient)
3056
+ db.prepare("update tasks set status = 'blocked', version = version + 1, updated_at = ? where id = ?").run(nowIso(), t.id);
3057
+ db.prepare("update team_tasks set status = 'failed', updated_at = ? where id = ?").run(nowIso(), teamTaskId);
3058
+ store.blockDownstream(t.id, "upstream-failed");
3059
+ store.addComment(t.id, { body: `团队回报:失败 → 受阻${ev}` }); // 自动登记失败反馈
3060
+ store.recordTaskFailure(t.identifier, { error: evidence || "团队回报失败", outcome: "failed" }); // FR-78:计入熔断
3061
+ } else {
3062
+ throw invalidField("outcome", "outcome 必须是 completed 或 failed");
3063
+ }
3064
+ return store.getTaskById(t.id);
3065
+ },
3066
+ applyTeamRunProgress(teamId, outcomes = []) {
3067
+ if (!store.getTeamRun(teamId)) throw new TbError("TEAM_NOT_FOUND", `团队不存在:${teamId}`, { teamId });
3068
+ const results = outcomes.map((o) => ({ teamTaskId: o.teamTaskId, task: store.applyTeamTaskOutcome(o.teamTaskId, { outcome: o.outcome, reviewPassed: o.reviewPassed }) }));
3069
+ const status = store.finishTeamRun(teamId);
3070
+ return { teamId, status, results };
3071
+ },
3072
+ finishTeamRun(teamId) {
3073
+ if (!store.getTeamRun(teamId)) throw new TbError("TEAM_NOT_FOUND", `团队不存在:${teamId}`, { teamId });
3074
+ const tasks = db.prepare("select status from team_tasks where team_id = ?").all(teamId).map((r) => r.status);
3075
+ let status;
3076
+ if (tasks.length === 0) status = "staged";
3077
+ else if (tasks.some((s) => s === "open" || s === "running")) status = "running";
3078
+ else if (tasks.every((s) => s === "failed")) status = "failed";
3079
+ else status = "completed";
3080
+ db.prepare("update team_runs set status = ?, updated_at = ? where id = ?").run(status, nowIso(), teamId);
3081
+ return status;
3082
+ },
3083
+ stats() {
3084
+ const count = (sql) => db.prepare(sql).get().n;
3085
+ return {
3086
+ projects: count("select count(*) as n from projects"),
3087
+ tasks: count("select count(*) as n from tasks"),
3088
+ comments: count("select count(*) as n from comments"),
3089
+ ownedTasks: count("select count(*) as n from tasks where owner is not null and owner <> ''"),
3090
+ legacyOwnerLabels: count("select count(*) as n from tasks where labels like '%owner:%'"),
3091
+ dbPath,
3092
+ dataDir,
3093
+ schemaVersion: SCHEMA_VERSION,
3094
+ migration,
3095
+ };
3096
+ },
3097
+ };
3098
+
3099
+ // 项目记忆:同库、同事务语义,但**不感知** MCP/CLI/Web(只是用例层的又一扇门)。
3100
+ Object.assign(store, createMemoryApi({ db, nowIso, randomUUID }));
3101
+
3102
+ return store;
3103
+ }