taskboard-workbench 0.3.2 → 0.3.3

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.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,49 @@
6
6
  版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
7
7
  每个版本对应一个 annotated tag(`vX.Y.Z`)与一条 GitHub Release;npm dist-tag 与 dsh 兼容区间随版本记录。
8
8
 
9
+ ## [0.3.3] - 2026-11-12
10
+
11
+ > 主题:**把「团队执行时缺的那几条路」补齐,并让两个宿主看见同一份库** —— 双宿主对齐(写者租约 + 数据目录自证)、
12
+ > 按卡选执行者、交付证据写入口双通道(含 `agents` 雏形与 WAL)、开局提示词注入当前项目、人工撤单入口,
13
+ > 外加四条团队执行期实测出来的缺陷修复。
14
+ > 版号按本仓既定口径走 **`0.3.x` patch**(`0.3.2` 已声明「`0.3.x` 期 patch 号承载修复 + 可选能力」,
15
+ > `0.4.0` 留给计划文档里预留的确认层 `acceptance_state`)—— 不另起 minor 线。
16
+ > 读数:`npm test` **1225 / 0** · `release-precheck` **EXIT=0** · tarball **86** 文件 · `schemaVersion` **14 → 15**。
17
+
18
+ ### 新增
19
+
20
+ - **双宿主数据对齐(卡 `-236`/`-237` / 需求 `R173`)** —— web 与 desktop **共用同一份库**,且界面能自证「连的是哪个库」:
21
+ 只读跟随者常驻条(`role=follower` 30s 刷新)、写者租约(同时只有一个写者)、`/api/health` 直接给 `dataDir` 与 `dbPath`。
22
+ - **按卡选执行者(卡 `-238` / 需求 `R174`)** —— 任务卡「启动执行」可按卡挑执行者(团队 / 宿主会话 / claude · codex · hermes 等 CLI),
23
+ 前端按注册表渲染图标并按 `id` 派发;**不传执行者 = 原口径**,升级后默认行为不变。
24
+ - **交付证据写入口双通道(卡 `-239`/`-241` / 需求 `R175`)** —— HTTP 与 MCP `card_evidence_submit` **同源**:
25
+ 同一个 store 方法、同一道四字段硬门、同一套错误码;`task_evidence` 增 `evidence_hash` 幂等索引(重复推送不再堆重复行),
26
+ 并落 `agents` / `agent_sessions` 雏形与 WAL(`schemaVersion` **14 → 15**)。
27
+ - **人工撤单入口(卡 `-252` / 需求 `R180`)** —— 抽屉标题栏新增 danger 档「取消任务(撤单)」:原因必填、页内 dialog 二次确认,
28
+ 撤单后把原因写成评论(此前「确认不执行」的卡在界面上根本没有出口,只能挂着)。
29
+
30
+ ### 修复
31
+
32
+ - **内嵌宿主下 `window.prompt` 直接报错(卡 `-240`/`-242` / 需求 `R176`)** —— 新建项目 / 返工说明 / 人工结论 / 需求标题
33
+ 四处取值出口改走**页内 dialog**(`askFields`),取消零副作用;`tests/no-prompt.test.mjs` 守结构门与「三条取消出口统一归 `null`」。
34
+ - **配置页「复制开局提示词」注入当前项目(卡 `-243` / 需求 `R177`)** —— 此前复制的是**默认项目**的开局语,新会话按错误目录开工;
35
+ 现按 `state.projectId` 现算,未设工作目录时**如实提示不猜路径**。
36
+ - **`requestReview` 缺省自动指派评审者(卡 `-244` / 需求 `R178`)** —— 此前只把 `review_state` 置 pending、`reviewer` 留空,
37
+ ⇒ `review_deadlock` 是**必然产物**;现按团队模板缺省指派(真机验证:不传 reviewer ⇒ 回读 `reviewer="reviewer"`)。
38
+ - **同态迁移不再写空转事件(卡 `-245` / 需求 `R178`)** —— `in_review → in_review` 不再追加 `status_changed`,事件流恢复成「状态真的变了」才算。
39
+ - **复核命令不可执行时判「不适用」,不再谎报失败(卡 `-249` / 需求 `R179`)** —— 命令里带未替换占位符(如 `<diff文件>`)时,
40
+ 此前跑出 `sh: syntax error` 并被记成「失败(退出码 2)」;现在 `applicable=false` 且明确说出是哪个占位符没替换。
41
+ - **发布门禁误报(测试夹具)** —— `tests/executors.test.mjs` / `tests/kickoff-prompt-project.test.mjs` 的假家目录写成真机路径形态,
42
+ 命中 L2「mac-home」规则使门禁转红;夹具改中性临时路径,门禁回到 `EXIT=0`。
43
+
44
+ ### 兼容性与升级注意
45
+
46
+ - **npm `latest` 升到 `0.3.3`**;`engines.dsh` 仍为 `>=0.2.1-rc.3`(本机验证形态 `0.2.2-rc.1`)。
47
+ - **`schemaVersion` 14 → 15**:首启自动迁移(`task_evidence` 补 `evidence_hash` 列 + 指纹索引,幂等)。
48
+ 回退到 `0.3.2` 读同一个库**不安全**(旧代码不认识新列),要回退请连同 `.data` 快照一起回。
49
+ - **证据写入变幂等**:同一张卡、同一份产物指纹重复推送只留一行 —— 依赖「每次 push 都新增一行」的外部统计口径需要改。
50
+ - **撤单不会自动解锁下游**:`isTaskReady` 仍只把 `done` 当完成(`canceled` 算未完成),口径待定,见卡 `-253` / 需求 `R181`(backlog)。
51
+
9
52
  ## [0.3.2] - 2026-11-06
10
53
 
11
54
  > 主题:**把三轮「卡上已收口、包里还没有」的改动一次补齐** —— `0.3.1` 之后又攒了开局长注入(P5 档 C)、
package/index.js CHANGED
@@ -5,8 +5,8 @@
5
5
  * 挂到独立命名空间 /integrations/taskboard-workbench 下,并同时托管 web/ 静态资源
6
6
  * (客户端面板通过同源脚本加载复用 web/app.js 的看板渲染)。
7
7
  *
8
- * 数据目录:插件配置 dataDir > 宿主 `ctx.get("config").dataDir` > TB_DATA_DIR > 系统临时目录
9
- * (默认不写代码仓库)。**不得直接读 `ctx.config`**:本插件 `inject` 只声明了 `webServer`,
8
+ * 数据目录:插件配置 dataDir > 宿主 `ctx.get("config").dataDir` > TB_DATA_DIR > `~/.dsh/data/taskboard-workbench`
9
+ * (默认不写代码仓库;2026-11-10 起不再落系统临时目录 —— 见 `src/core/config.mjs`)。**不得直接读 `ctx.config`**:本插件 `inject` 只声明了 `webServer`,
10
10
  * cordis 会对未声明属性抛「cannot get property "config" without inject」⇒ 装载期整条 entry
11
11
  * 不激活(2026-10-26 用隔离真宿主 `--from-default-profile` 复现;真实 profile 因为用户层
12
12
  * patch 显式给了 `config.dataDir`,把 `??` 右边短路掉,才一直没暴露)。
@@ -15,9 +15,12 @@ import { fileURLToPath, pathToFileURL } from "node:url";
15
15
  import { createRequire } from "node:module";
16
16
  import { existsSync, realpathSync } from "node:fs";
17
17
  import path from "node:path";
18
+ import os from "node:os";
18
19
 
19
20
  import { resolveDataDir } from "./src/core/config.mjs";
21
+ import { detectLegacyDataHint } from "./src/core/data-dir-hint.mjs";
20
22
  import { openStore } from "./src/core/store.mjs";
23
+ import { LEASE_HEARTBEAT_MS } from "./src/core/instance-lease.mjs";
21
24
  import { createRequestHandler, ensureDefaultProject, WEB_DIR } from "./src/server/server.mjs";
22
25
  import { createEventHub } from "./src/server/events.mjs";
23
26
  import { runExecutionLoop, listLoopProjects } from "./src/core/loop.mjs";
@@ -383,7 +386,12 @@ export function createHostSessionPort({ getService, getCtx, getStore } = {}) {
383
386
  const q = getService?.("sessionQuery");
384
387
  if (!q) return { sessionId, cwd: null, source: "unavailable" };
385
388
  try {
386
- const index = await sessionIndex();
389
+ // 卡 `-235`(需求 `R172`)· lint `no-undef` 抓到的真缺陷:原写 `await sessionIndex()`,
390
+ // 而那是**同一对象的方法**、不在当前作用域 ⇒ ReferenceError ⇒ 被下面的 `catch` 静默吞掉 ⇒
391
+ // 「先查持久化索引(带 TTL 缓存)」这条路径**从未生效**,每次都退到 readSession。
392
+ // 改为直接调上面那个闭包(`sessionIndex()` 方法体也是它),同源、同缓存,语义不变。
393
+ const built = await buildSessionIndex();
394
+ const index = built?.map ?? null;
387
395
  if (index?.has(sessionId)) {
388
396
  return { sessionId, cwd: index.get(sessionId)?.cwd ?? null, source: "sessionQuery.listSessions" };
389
397
  }
@@ -599,17 +607,51 @@ export function apply(ctx, config) {
599
607
  disposed = false;
600
608
  registerRoutes(getWebServer());
601
609
  registerTools(ctx?.get?.("tools") ?? ctx?.tools);
610
+ // 卡 `-237`(需求 `R173`):**多实例单写者租约**。dsh web 与 dsh desktop 可以同时打开同一个库,
611
+ // 谁先抢到谁写;后起者降级为 follower(只读 + 不起执行循环 + 不做 boot 收口)。
612
+ let leaseRole = "writer";
613
+ let leaseOwner = null;
614
+ try {
615
+ const lease = runtime.store.acquireInstanceLease({ host: os.hostname(), pid: process.pid });
616
+ leaseRole = lease.role;
617
+ leaseOwner = lease.owner;
618
+ if (leaseRole !== "writer") {
619
+ console.log(`[taskboard-workbench] 只读跟随:另一实例正在写同一个库(${lease.owner?.host} · pid ${lease.owner?.pid} · ${runtime.store.dbPath})`);
620
+ } else if (lease.tookOver) {
621
+ console.log(`[taskboard-workbench] 写者租约接管:上一实例 ${lease.previous?.host} · pid ${lease.previous?.pid} 已过期`);
622
+ }
623
+ } catch (error) {
624
+ console.error(`[taskboard-workbench] 写者租约获取失败(按 writer 继续):${error?.message ?? error}`);
625
+ }
602
626
  // FR-82 收口(启动口径):上一进程留下的「进行中」尝试不会有人闭合 —— 启动时一次结清(**不看时长**)。
627
+ // **只有 writer 才做 boot 收口** —— 它分不清「上一进程」与「另一个还活着的进程」,
628
+ // follower 跑一次就会把对端正跑着的执行当孤儿结清(这正是 R173 的真机风险)。
629
+ if (leaseRole === "writer") {
630
+ try {
631
+ const rec = runtime.store.reconcileOrphanRuns({ boot: true });
632
+ if (rec.ended.length || rec.ghostClaims.length) {
633
+ console.log(`[taskboard-workbench] boot reconcile: 收口孤儿尝试 ${rec.ended.length} 条(${rec.ended.map((r) => `${r.identifier}#${r.attempt}→${r.outcome}`).join(", ")});清幽灵认领 ${rec.ghostClaims.length} 条`);
634
+ }
635
+ } catch (error) {
636
+ console.error(`[taskboard-workbench] boot reconcile failed: ${error?.message ?? error}`);
637
+ }
638
+ }
639
+ // 卡 `-236`(需求 `R173`):默认目录从系统临时目录搬到 `~/.dsh/data/taskboard-workbench` 之后,
640
+ // 老用户的卡还在旧目录 —— 只读对照一次,把「升级后看板全空」变成一条能看懂的提示。
641
+ // **不搬库、不删旧库**:搬数据属破坏性动作,交用户决定(提示里给两条明路)。
603
642
  try {
604
- const rec = runtime.store.reconcileOrphanRuns({ boot: true });
605
- if (rec.ended.length || rec.ghostClaims.length) {
606
- console.log(`[taskboard-workbench] boot reconcile: 收口孤儿尝试 ${rec.ended.length} 条(${rec.ended.map((r) => `${r.identifier}#${r.attempt}→${r.outcome}`).join(", ")});清幽灵认领 ${rec.ghostClaims.length} 条`);
643
+ const hint = detectLegacyDataHint({ dataDir: runtime.dataDir, activeTaskCount: runtime.store.stats().tasks });
644
+ if (hint) {
645
+ runtime.store.dataDirHint = hint;
646
+ console.warn(`[taskboard-workbench] 数据目录迁移提示:${hint.hint}`);
607
647
  }
608
648
  } catch (error) {
609
- console.error(`[taskboard-workbench] boot reconcile failed: ${error?.message ?? error}`);
649
+ console.error(`[taskboard-workbench] 迁移提示探测失败(忽略):${error?.message ?? error}`);
610
650
  }
611
651
  // 看板执行循环定时器(FR-70):仅对"已开启循环"的项目按活跃引擎自动派发待执行任务
612
652
  const loopTimer = setInterval(() => {
653
+ // 卡 `-237`:follower 不跑执行循环(否则同一张卡会被两个宿主同时派发)。
654
+ if (leaseRole !== "writer") return;
613
655
  // FR-77:回收失效认领(认领过期 / 心跳陈旧)——执行侧仍存活则延后,避免重复派发。
614
656
  try {
615
657
  const reclaimed = runtime.store.reclaimStaleClaims();
@@ -636,6 +678,28 @@ export function apply(ctx, config) {
636
678
  }
637
679
  }, 30000);
638
680
  loopTimer.unref?.();
681
+ // 卡 `-237`:心跳 15s。**follower 也每拍一次 acquire** —— 对端一退出(租约过期 45s)就能接管。
682
+ const leaseTimer = setInterval(() => {
683
+ try {
684
+ const next = runtime.store.acquireInstanceLease({ host: os.hostname(), pid: process.pid });
685
+ if (next.role === "writer" && leaseRole !== "writer") {
686
+ leaseRole = "writer";
687
+ leaseOwner = null;
688
+ console.log("[taskboard-workbench] 已接管写者租约(对端已过期),本窗口恢复读写");
689
+ try {
690
+ const rec = runtime.store.reconcileOrphanRuns({ boot: true });
691
+ if (rec.ended.length || rec.ghostClaims.length) console.log(`[taskboard-workbench] 接管收口:孤儿 ${rec.ended.length} 条 / 幽灵认领 ${rec.ghostClaims.length} 条`);
692
+ } catch (error) { console.error(`[taskboard-workbench] 接管收口失败:${error?.message ?? error}`); }
693
+ } else if (next.role !== "writer" && leaseRole === "writer") {
694
+ leaseRole = "follower";
695
+ leaseOwner = next.owner;
696
+ console.log(`[taskboard-workbench] 失去写者租约 → 只读跟随(${next.owner?.host} · pid ${next.owner?.pid})`);
697
+ }
698
+ } catch (error) {
699
+ console.error(`[taskboard-workbench] 租约心跳失败:${error?.message ?? error}`);
700
+ }
701
+ }, LEASE_HEARTBEAT_MS);
702
+ leaseTimer.unref?.();
639
703
  // 服务在插件 apply 之后才出现/被替换时,重新注册(agent-teams 同款做法)。
640
704
  const onService = (name) => {
641
705
  if (name === "webServer" || name === "httpServer") registerRoutes(getWebServer());
@@ -645,6 +709,8 @@ export function apply(ctx, config) {
645
709
  return () => {
646
710
  disposed = true;
647
711
  try { clearInterval(loopTimer); } catch (_) {}
712
+ try { clearInterval(leaseTimer); } catch (_) {}
713
+ try { runtime.store.releaseInstanceLease(); } catch (_) {}
648
714
  try {
649
715
  off?.();
650
716
  } catch (_) {}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "taskboard-workbench",
3
- "version": "0.3.2",
3
+ "version": "0.3.3",
4
4
  "type": "module",
5
5
  "description": "agent team 任务工作台:零依赖核心(node:sqlite)+ CLI + 本地 Web 看板 + DSH 内嵌插件",
6
6
  "license": "MIT",
@@ -34,7 +34,7 @@ requires_contract: v1
34
34
  | **S2** | 分拆成卡 | `card_create` | 条目存在 + 同项目 + 归因硬门 | 返回 `attribution.kind="requirement"`;卡在 `backlog`;依赖真成边 | `tasks` + `task_events`(`created` / `attributed`) | `REQUIREMENT_REQUIRED` ⇒ 补 `requirement`,或显式 `unattributed_reason`(会落审计);`DEPENDENCY_CROSS_PROJECT` ⇒ 前置卡挂错项目;`AUTHORIZATION_REQUIRED` ⇒ 新卡只能进 `backlog` | FR-29 / FR-38 |
35
35
  | **S3** | 授权开工(人) | 看板「启动执行」/ 人点 | 归因门 → 授权门 | `backlog → todo` 由**人**点;执行侧不得自我授权 | `task_events`(`set-status`,`actor=human`) | 执行侧想推 ⇒ `AUTHORIZATION_REQUIRED`;卡还没归因 ⇒ 先回 S2 | FR-40 / FR-84 |
36
36
  | **S4** | 派发 / 执行 | 看板派发 · 宿主团队工具 · MCP `card_progress` 推进状态 | 归因 + 授权 + **人工校验门** | 卡进 `in_progress` 且带认领心跳;人工校验任务不得被执行侧改状态 | `team_runs` / claims / `task_events` | `HUMAN_REVIEW_NOT_EXECUTABLE` ⇒ 这是人在环任务,走人工结论入口;`EXECUTION_NOT_ATTRIBUTED` ⇒ 回 S2 补归因 | FR-41 / FR-42 / FR-85 |
37
- | **S5** | 回填进度 + 证据 | `card_progress` | `contract_version` 一致 + `norm_digest` 一致 | 每条进展带**可核验证据**(`file` / `command` / `url` / `reading`),不是「已完成」三个字;`in_review` 前必须有证据 | 评论(`【MCP 证据】hash=…`)+ 审计 | `EVIDENCE_REQUIRED` / `EVIDENCE_INVALID` ⇒ 按形状补;`NORM_DIGEST_REQUIRED` / `NORM_STALE` ⇒ 先 `norm_get {norm:"card-update"}` 再回填 | FR-94 / FR-50 |
37
+ | **S5** | 回填进度 + 证据 | `card_progress` · `card_evidence_submit` | `contract_version` 一致 + `norm_digest` 一致 | 每条进展带**可核验证据**(`file` / `command` / `url` / `reading`),不是「已完成」三个字;`in_review` 前必须有证据 | 评论(`【MCP 证据】hash=…`)+ 审计 | `EVIDENCE_REQUIRED` / `EVIDENCE_INVALID` ⇒ 按形状补;`NORM_DIGEST_REQUIRED` / `NORM_STALE` ⇒ 先 `norm_get {norm:"card-update"}` 再回填 | FR-94 / FR-50 |
38
38
  | **S6** | 需求变更 | `requirement_change` | 影响面已计算(`affected_cards`) | 先预览拿 `change_id`,确认影响面后带 `change_id` + `apply:true` 才落地;`done` 卡**不自动重开** | `governance_audit`(`requirement-change`,带 `reason`) | `CHANGE_NEEDS_APPROVAL` ⇒ 忘了先预览;`CHANGE_ID_MISMATCH` ⇒ 条目在预览后被改过,重新预览;`CHANGE_REASON_REQUIRED` ⇒ 补理由 | FR-39 / FR-100 |
39
39
  | **S7** | 验收收口(人) | 看板「完成」/ 人点 | 评审门 `review_state==='approved'`(或显式 `skipReview`) | `in_review → done` **只由人**;执行侧写 `done` 一律被拒 | `governance_audit`(`actor=human`) | `REVIEW_NOT_APPROVED` ⇒ 先评审通过;`GOVERNANCE_AGENT_DONE` ⇒ 这不是执行侧该做的事 | FR-83 / FR-99 |
40
40
  <!-- /flow-block:steps -->
@@ -17,8 +17,28 @@ card_progress {
17
17
  }
18
18
  ```
19
19
 
20
+ ## 交付证据(另一种写入口 · 不是"进度")
21
+
22
+ `card_progress` 写的是**过程性证据**(command / url / reading)。要把**交付证据**(判定 / 偏离 / 边界 / 产物)
23
+ 落到 `task_evidence` 表,用 `card_evidence_submit`(HTTP 侧对应 `POST /api/tasks/:ref/evidence`,同源同门):
24
+
25
+ ```
26
+ card_evidence_submit {
27
+ card,
28
+ verdict: "做了什么、结论是什么",
29
+ deviation: "没按原计划做的部分(不写 = 隐藏信息)",
30
+ boundary: "未取得 / 无法判定的读数必须明说",
31
+ artifacts: ["docs/进度/xxx.md", "npm test 1186/1186"],
32
+ artifact_refs: [ { kind: "commit", ref: "57e97f9" }, { kind: "file", ref: "src/core/store.mjs" } ]
33
+ }
34
+ ```
35
+
36
+ - 四字段**缺一即拒**(`EVIDENCE_INCOMPLETE`),不会落半条;
37
+ - `artifact_refs` 只接受 `commit` / `file`(其余 ⇒ `INVALID_ARTIFACT_REF`);过程性证据走 `evidence[]` 那一侧;
38
+ - 同指纹重复提交**幂等**(`deduped: true`,不增行)。
39
+
20
40
  ## 判据
21
- - `evidence[].kind` ∈ `file` / `command` / `url` / `reading`,`ref` 非空;
41
+ - `evidence[].kind` ∈ `file` / `command` / `url` / `reading`(`commit` 属交付证据侧),`ref` 非空;
22
42
  - 返回 `comment.deduped === false`(第二次同样证据会是 `true`,不会刷重复评论);
23
43
  - `card.statusAfter` 与你期望的一致;
24
44
  - 评论正文里有 `【MCP 证据】hash=…` —— 这就是事后复核的锚点。
@@ -1,12 +1,21 @@
1
1
  /**
2
2
  * 运行期配置:数据目录解析(FR-31/FR-33)。
3
- * 优先级:显式参数 --data-dir > 环境变量 TB_DATA_DIR > 默认临时目录。
4
- * 默认放临时目录,保证"运行不写仓库"(本机仓库目录只读)。
3
+ * 优先级:显式参数 --data-dir > 环境变量 TB_DATA_DIR > 默认目录。
4
+ *
5
+ * 默认目录(2026-11-10 · 卡 `-236` / 需求 `R173` 改):
6
+ * `~/.dsh/data/taskboard-workbench`
7
+ * 原默认是 `os.tmpdir()/tb-workbench-mvp-a` —— 两个问题:
8
+ * ① **临时目录会被 macOS 定期清理** ⇒ 看板数据随时静默消失;
9
+ * ② dsh web 与 dsh desktop 是**两个宿主**,只要有一边没显式配 `dataDir`,就会落到
10
+ * 自己解析的默认位置,于是「两边看到两份库」(真机:web 264 张卡 / desktop 0 张)。
11
+ * 改成用户目录下的固定路径后,**两个宿主不配置也是同一份库**。
5
12
  */
6
13
  import os from "node:os";
7
14
  import path from "node:path";
8
15
 
9
- export const DEFAULT_DATA_DIR = path.join(os.tmpdir(), "tb-workbench-mvp-a");
16
+ export const DEFAULT_DATA_DIR = path.join(os.homedir(), ".dsh", "data", "taskboard-workbench");
17
+ /** 旧默认目录:**只用于「空库检测 / 迁移提示」**,不再作为任何写入目标。 */
18
+ export const LEGACY_DATA_DIR = path.join(os.tmpdir(), "tb-workbench-mvp-a");
10
19
  export const DB_FILENAME = "taskboard.sqlite";
11
20
 
12
21
  export function resolveDataDir({ dataDir, env = process.env } = {}) {
@@ -0,0 +1,52 @@
1
+ /**
2
+ * data-dir-hint.mjs —— 「你这个库是空的,但旧默认目录里还有数据」的**只读**检测(卡 `-236` / 需求 `R173`)。
3
+ *
4
+ * 为什么需要它:默认目录从 `os.tmpdir()/tb-workbench-mvp-a` 改到 `~/.dsh/data/taskboard-workbench` 之后,
5
+ * 老用户的卡还在旧目录里。如果只是静默换目录,用户看到的就是「升级后看板全空」——比原来的 bug 更吓人。
6
+ * 所以启动时做一次**只读**对照:新库 0 张卡 + 旧库有卡 ⇒ 打一条明确的迁移提示(并在 /api/health 里带出来)。
7
+ *
8
+ * 边界(都很硬):
9
+ * - **不复制、不删除、不写入**旧库;只读打开 + 一条 count。旧库打开失败一律当"没有提示",绝不打断启动。
10
+ * - 新库已经有卡 ⇒ 不提示(用户显然已在用新目录)。
11
+ * - 两个目录相同(用户显式把 dataDir 指回旧目录)⇒ 不提示。
12
+ */
13
+ import { existsSync } from "node:fs";
14
+ import path from "node:path";
15
+ import { DatabaseSync } from "node:sqlite";
16
+
17
+ import { DB_FILENAME, LEGACY_DATA_DIR } from "./config.mjs";
18
+
19
+ export function detectLegacyDataHint({
20
+ dataDir,
21
+ activeTaskCount = 0,
22
+ legacyDir = LEGACY_DATA_DIR,
23
+ dbFilename = DB_FILENAME,
24
+ } = {}) {
25
+ if (!dataDir || !legacyDir) return null;
26
+ if (path.resolve(String(dataDir)) === path.resolve(String(legacyDir))) return null;
27
+ if (Number(activeTaskCount) > 0) return null;
28
+
29
+ const legacyDbPath = path.join(legacyDir, dbFilename);
30
+ if (!existsSync(legacyDbPath)) return null;
31
+
32
+ let legacyTaskCount = 0;
33
+ try {
34
+ const db = new DatabaseSync(legacyDbPath, { readOnly: true });
35
+ try {
36
+ const row = db.prepare("select count(*) as n from tasks").get();
37
+ legacyTaskCount = Number(row?.n ?? 0);
38
+ } finally { db.close(); }
39
+ } catch {
40
+ return null; // 旧库读不开(权限 / 损坏 / 不是本插件库)⇒ 不当提示,更不当错误
41
+ }
42
+ if (legacyTaskCount <= 0) return null;
43
+
44
+ return {
45
+ reason: "EMPTY_ACTIVE_WITH_LEGACY_DATA",
46
+ dataDir: path.resolve(String(dataDir)),
47
+ legacyDir: path.resolve(String(legacyDir)),
48
+ legacyDbPath,
49
+ legacyTaskCount,
50
+ hint: `当前数据目录(${path.resolve(String(dataDir))})没有任务,但旧默认目录 ${legacyDir} 里有 ${legacyTaskCount} 张卡。要看旧数据:把 dataDir 指回旧目录(TB_DATA_DIR=… 或插件配置 dataDir),或自行把 ${dbFilename} 复制过来后重启。本插件不会自动搬库。`,
51
+ };
52
+ }
@@ -98,6 +98,15 @@ export const ERROR_CATEGORY = Object.freeze({
98
98
  REQ_IDENTIFIER_CONFLICT: EXIT.CONFLICT,
99
99
  DEPENDENCY_EXISTS: EXIT.CONFLICT,
100
100
  DOC_EXISTS: EXIT.CONFLICT,
101
+ // 卡 `-238`(R174):执行者按卡选择 —— 三种「选不了」必须**分开报**,否则人分不清该去装 CLI、
102
+ // 还是去改项目设置(forbiddenExecutors 优先级最高)。
103
+ EXECUTOR_UNKNOWN: EXIT.USAGE,
104
+ EXECUTOR_NOT_INSTALLED: EXIT.USAGE,
105
+ EXECUTOR_FORBIDDEN: EXIT.USAGE,
106
+ // 选了一个「不是 CLI 形态」的执行者(team / host-session)却打到 exec-cli 上 ⇒ 用法错误,并指路正确入口
107
+ EXECUTOR_NOT_CLI: EXIT.USAGE,
108
+ // 卡 `-237`(R173):同一个库同一时刻只允许一个写者;follower 的所有写操作一律 409。
109
+ FOLLOWER_READ_ONLY: EXIT.CONFLICT,
101
110
  });
102
111
 
103
112
  /** 领域错误:带 code / 退出码 / 可选细节。 */
@@ -10,6 +10,16 @@ import path from "node:path";
10
10
  import { execFileSync } from "node:child_process";
11
11
 
12
12
  export const EVIDENCE_FIELDS = Object.freeze(["verdict", "deviation", "boundary", "artifacts"]);
13
+
14
+ /**
15
+ * `kind` 的**唯一枚举**(FR-106 · 0-B-b):证据条目可用的五类。
16
+ * 为什么要收在一处:MCP 的 `card_progress.evidence[]`、MCP 的 `card_evidence_submit`、
17
+ * HTTP 的 `POST /api/tasks/:ref/evidence` 三个入口都要判同一套值 ——
18
+ * 各写一份必然漂移(此前 tools.mjs 里就有一份只到 `reading` 的副本)。
19
+ */
20
+ export const EVIDENCE_KINDS = Object.freeze(["file", "command", "url", "reading", "commit"]);
21
+
22
+ /** 真正参与 `artifact_refs` 核验的 kind(其余**逐条不进** `artifact_refs` ⇒ 行级 `unchecked`)。 */
13
23
  export const EVIDENCE_REF_KINDS = Object.freeze(["commit", "file"]);
14
24
 
15
25
  const text = (v) => (typeof v === "string" ? v.trim() : "");
@@ -39,6 +49,24 @@ export function normalizeArtifactRefs(refs) {
39
49
  return out;
40
50
  }
41
51
 
52
+ /**
53
+ * **入口层**白名单校验(FR-106 第 3 条):`artifact_refs[].kind` 不在 `{commit,file}` 内就**显式报错**。
54
+ *
55
+ * 与 `normalizeArtifactRefs` 的分工必须区分清楚:
56
+ * · **规则层**(`normalizeArtifactRefs`)继续**静默丢弃**非法项 —— 契约不变,`tests/task-evidence.test.mjs` D 组钉着;
57
+ * · **入口层**(MCP / HTTP 的写入口)先跑这里,非法即整笔拒(`INVALID_ARTIFACT_REF`)⇒ 调用方拿得到真原因。
58
+ * 只在入口层做,是为了不改动任何既有规则层行为。
59
+ */
60
+ export function artifactRefKindProblems(refs) {
61
+ if (!Array.isArray(refs)) return [];
62
+ const bad = [];
63
+ refs.forEach((r, index) => {
64
+ const kind = text(r?.kind);
65
+ if (!EVIDENCE_REF_KINDS.includes(kind)) bad.push({ index, kind: kind || null, allowedKinds: [...EVIDENCE_REF_KINDS] });
66
+ });
67
+ return bad;
68
+ }
69
+
42
70
  /**
43
71
  * 核验 `artifact_refs`:任一解不开即整体 `unresolved`(不"部分通过")。
44
72
  * `resolve({kind, ref})` 由调用方注入 —— 默认实现见 `makeResolver`。
@@ -96,6 +96,11 @@ export function cliArgsFor({ executorId, cwd, settings }) {
96
96
  */
97
97
  export const EDIT_PERMISSION_HINTS = Object.freeze([
98
98
  "acceptEdits", "bypassPermissions", "--dangerously-skip-permissions",
99
+ // 卡 `-238`:判据从「只认 claude 的写法」扩到「**任一 CLI 的显式写权限**」——
100
+ // codex 的 `-s workspace-write` / `--dangerously-bypass-approvals-and-sandbox`、
101
+ // hermes 的 `--yolo` 都是「允许落盘」的明示开关。这几个 token 语义单一,
102
+ // 扩进来只会**减少**误判成「盲跑」,不会把只读参数误认成可写。
103
+ "workspace-write", "danger-full-access", "--yolo",
99
104
  ]);
100
105
 
101
106
  export function argsAllowEdits(args) {
@@ -423,16 +428,25 @@ export async function runCliExecutor({
423
428
  timeoutMs = DEFAULT_TIMEOUT_MS, spawnImpl = spawn, env = process.env, now = () => Date.now(),
424
429
  verifyCommand = null, requirementId = null,
425
430
  store = null, heartbeatIntervalMs = HEARTBEAT_INTERVAL_MS,
431
+ // 卡 `-238`(R174):按卡选执行者时,参数与「指令怎么给」由**注册表**决定,不再写死 claude 那套。
432
+ // 两者缺省即老行为(`cliArgsFor` + stdin),**零回归**。
433
+ argsOverride = null, promptVia = "stdin",
426
434
  } = {}) {
427
435
  if (!executor?.cli) return { started: false, reason: "no-cli-executor" };
428
436
  const workdir = cwd ?? project?.workspacePath ?? null;
429
437
  if (!workdir) return { started: false, reason: "no-workspace", executorId: executor.id };
430
438
  // 测试/离线替身:`TB_CLI_EXECUTOR_BIN` 指定可执行文件时优先使用(不改 executor id 语义)。
431
- const cli = String(env?.TB_CLI_EXECUTOR_BIN ?? "") || executor.cli;
439
+ // `binPath` 优先于裸命令名:宿主由 launchd 拉起时 PATH 常缺 `~/.npm-global/bin`,
440
+ // 只写命令名会在 `exec-cli` 真跑时报 ENOENT(探测到绝对路径就用它)。
441
+ // `TB_CLI_EXECUTOR_BIN` 仍是最高优先(测试/离线替身语义不变)。
442
+ const cli = String(env?.TB_CLI_EXECUTOR_BIN ?? "") || executor.binPath || executor.cli;
432
443
  const prompt = buildTaskPrompt(task, { project, requirementId, verifyCommand });
433
- const args = cliArgsFor({ executorId: executor.id, cwd: workdir, settings });
444
+ const explicitArgs = Array.isArray(argsOverride) && argsOverride.length ? argsOverride.map(String) : null;
445
+ const args = explicitArgs ?? cliArgsFor({ executorId: executor.id, cwd: workdir, settings });
434
446
  // 参数来源与「能不能写文件」都要如实记进结果(证据与状态都取它,见 isBlindRun)。
435
- const argsSource = (Array.isArray(settings?.teamTemplate?.engineer?.args) && settings.teamTemplate.engineer.args.length) ? "override" : "default";
447
+ // `executor` 档=按卡选执行者时注册表给的参数(非 claude 的 CLI 只有这一种来源)。
448
+ const argsSource = explicitArgs ? "executor"
449
+ : (Array.isArray(settings?.teamTemplate?.engineer?.args) && settings.teamTemplate.engineer.args.length) ? "override" : "default";
436
450
  const startedAt = now();
437
451
  // 基线快照(脏仓库下用于算"本次真实产出")。
438
452
  // 拿不到基线**不得静默继续**:在结果上打 `baseline: "unavailable"`,证据评论里显式告警,
@@ -444,7 +458,7 @@ export async function runCliExecutor({
444
458
  let beforeSnap = null;
445
459
  if (!before) { try { beforeSnap = await snapshotWorkspace(workdir); } catch { beforeSnap = null; } }
446
460
  const baseline = before ? "git" : beforeSnap ? "fs" : "unavailable";
447
- const result = { started: true, executorId: executor.id, cli, cwd: workdir, args, argsSource, argsAllowsEdits: argsAllowEdits(args), baseline, exitCode: null, signal: null, timedOut: false, durationMs: 0, stdout: "", stderr: "", diff: null, ok: false };
461
+ const result = { started: true, executorId: executor.id, cli, cwd: workdir, args, argsSource, argsAllowsEdits: argsAllowEdits(args), promptVia, baseline, exitCode: null, signal: null, timedOut: false, durationMs: 0, stdout: "", stderr: "", diff: null, ok: false };
448
462
  // ---- 执行期心跳(2026-10-22 真机 `-122`)----
449
463
  // 子进程活着期间必须持续续命认领锁:否则心跳停在开跑那刻,10 分钟后 `claim.stale=true`、
450
464
  // 看护按 `session-offline` 判 `stalled/high`,主按钮变「退回待办(重新派发)」——
@@ -479,8 +493,10 @@ export async function runCliExecutor({
479
493
  child.stdout?.on("data", (b) => { result.stdout += String(b); });
480
494
  child.stderr?.on("data", (b) => { result.stderr += String(b); });
481
495
  child.on?.("close", (code, signal) => { clearTimeout(timer); result.exitCode = code; result.signal = signal ?? null; finish(); });
482
- // 指令走 stdin(避免超长命令行)+ 立即结束 stdin
483
- try { child.stdin?.write(prompt); child.stdin?.end(); } catch { /* ignore */ }
496
+ // 指令投递:默认走 stdin(避免超长命令行);`promptVia=argv` 的 CLI(hermes `-z <prompt>`)
497
+ // 指令已经在参数里,**不再往 stdin 写**(写了它也不读,白占缓冲),但仍要 end() 收口,
498
+ // 否则子进程等 stdin EOF 会挂到超时。
499
+ try { if (promptVia !== "argv") child.stdin?.write(prompt); child.stdin?.end(); } catch { /* ignore */ }
484
500
  });
485
501
  } finally {
486
502
  stopHeartbeat();
@@ -600,13 +616,17 @@ export function evidenceComment(task, result, { actor = "cli-executor" } = {}) {
600
616
  export async function executeTaskWithCli({
601
617
  store, task, project, settings = null, role = "engineer", timeoutMs = DEFAULT_TIMEOUT_MS,
602
618
  spawnImpl = spawn, env = process.env, now = () => Date.now(), heartbeatIntervalMs = HEARTBEAT_INTERVAL_MS,
619
+ // 卡 `-238`:显式选定的执行者(及其参数)优先于「项目配置解析出来的那个」。
620
+ // 不传时**逐字节**走老路径 —— 项目级配置仍是默认口径。
621
+ resolvedExecutor = null, argsOverride = null, promptVia = "stdin",
603
622
  } = {}) {
604
- const executor = resolveCliExecutor(settings ?? store.getProjectSettings(task.projectId), { role });
623
+ const executor = resolvedExecutor ?? resolveCliExecutor(settings ?? store.getProjectSettings(task.projectId), { role });
605
624
  if (!executor) return { ran: false, reason: "no-cli-executor" };
606
625
  const verifyCommand = settings?.teamTemplate?.engineer?.verifyCommand ?? null;
607
626
  const result = await runCliExecutor({
608
627
  task, project, executor, settings, timeoutMs, spawnImpl, env, now,
609
628
  verifyCommand, requirementId: task.requirementId ?? null, store, heartbeatIntervalMs,
629
+ argsOverride, promptVia,
610
630
  });
611
631
  const body = evidenceComment(task, result);
612
632
  let review = null; let blocked = null;