ygl-trees 0.82.0 → 0.83.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.83.0（2026-10-17）并发防护：指针钉住 + 半写拒绝 + 帮助面
+- **写命令长旗标钉住**（用户上报①，最重：并发会话两次劫持共享 current-project 指针，资产碎片化跨 3 项目）：`research *` / `produce *`（含 task）/ `project *` 全部接受 `--project <p>` 长旗标，`node *` 接受 `--tree <t>`（短旗标 `-p`/`-t` 不变；`node import --tree` 仍是目标树名，别名不遮蔽）；source/evidence/claim/task 写回执带 `· project <名>` 回显落点——写错项目当场可见，不必事后对账
+- **`source add --query` 半写防护**（上报①：attach 失败仍落源）：引用不存在时**先拒绝后写入**（rc=1 点名、零落地），不再"源已落、链接失败"；attach 落库后失败的路径改报已落 id + `research query attach` 重试指路
+- **`--help` 任意深度**（上报②：`kb add --help` 不识别直接 rc=2）：任意子命令带 `--help` 打印所在组的用法切片 rc=0（`--json` 返回 `{help}`），在 flag 校验与 db boot 之前短路；`webui serve --help` 等原有短路兼容
+- **no-db 报错点名工作区根因**（上报③：`db init` 前报错不提示 YGL_HOME）：无库时错误带 `workspace: <path>` 与来源（YGL_HOME 显式 / 默认 ~/.ygl-trees），冷启动错环境一眼可辨
+- **`node can --eval` attachments 快照**（建议④：P 值过了看不出吃了哪些 rel 证据）：输出回显本次判定实际吃到的 rel 挂接——`--json` 增 `eval_attachments[]`，人类视图 `attachments ×N:` 逐条（rel ← type:id 摘要），复现不必翻库；无挂接时字段省略（字节兼容）
+- **job 子命令无锁启动**（建议⑤配套）：`job run/tick` 的子进程带 `YGL_SERVE=1` 启动——此前 runner 自持应用级写锁，任何 `ygl-trees …` 型任务命令必撞自身死锁（rc=1 "locked"）；WAL 并发读 + SQLite 层写串行，与 webui serve 同推理。到期巡检范式：`job add "到期巡检" --every 1440 -- ygl-trees node cond --due --days 30`（真实工作区已挂，30 天窗口即刻命中 w1 三门槛）
+- 测试：demo 5k 段 7 断言（--project 钉住 / 落点校验 / 半写拒绝+零落地 / --help rc=0 / attachments 快照）+ 5h `--tree` 别名断言 → 113；readme-verify +3（kb add --help、source add --project、node list --tree 点名）→ 46
+
+## 0.82.1（2026-10-17）预测生命周期护栏：挂证据 ≠ 仲裁
+- **`claim link` 不再抢跑预测仲裁**（用户上报③：`--stance supports` 自动把 [预测·…] 断言置 supported，predict audit 判 supported||refuted → resolved——预测刚挂证据就退出跟踪表，实际无人仲裁）：预测前缀断言挂证据时跳过自动晋升，状态保持 unverified 直到显式 `claim resolve` / 到期回测；证据链接与 stance 照常落库，回执明示 `auto_promote: false`（`--json` 返回 `{claim, evidence, stance, status, auto_promote}`）；普通断言的自动推导不变（回归护栏）
+- **`claim unresolve <claimId>`**（建议②：误晋升后无归位命令）：复位通道把断言重置回 unverified（撤销链接副作用 / 抢跑仲裁），幂等（已 unverified → `duplicate:true`），落 `claim.unresolve` 事件留痕——0.82.1 前被误晋升的预测可用它归队
+- **predict audit `--json` 覆盖确认**（建议③）：`--json` 始终输出全量 rows（含 resolved 终态行），人类视图默认隐藏终态——机器读全量、人看增量，同构无缺口
+- 测试：predlink.spec.ts 5 例（预测不晋升 / 普通照常推导 / unresolve 复位+事件 / 幂等 / 坏 id 点名）→ 177；demo 5j 段 5 断言（挂证据不晋升 / 普通推导回归 / unresolve 复位 / 幂等 / 复位后仍在跟踪表）→ 106
+
 ## 0.82.0（2026-10-17）跨树巡检 + 临期 eval 门槛 + 幻影对账一键修复
 - **`node ready --all`**（用户建议②：12 棵树巡检要 24 条命令——每树 tree use + ready）：一次进程扫全部树的就绪集，无需 tree use / `-t`；`--json` 返回 `[{tree, ready[]}]`，人类输出按树分节
 - **`node cond --due [--days N] [--eval]`**（建议③：w1/d90 检验依赖人记得看）：扫描全部 eval 族条件，提取问题文本中的 `YYYY-MM-DD` 期限，列出 N 天内到期（含逾期）的条件（树/节点/deadline/剩余天数）；`--days` 放宽窗口（默认 7）；`--eval` 逐条组装上下文包送判定模型（三题型按 op 自动选择，离线安全回落 pending）——**判定只报告不仲裁**，通过 ≠ 自动解锁，resolve/unlock 保持人工（与 predict audit 同纪律）；跨树扫描前置于树解析，无当前树也能跑

package/README.md

@@ -109,9 +109,12 @@ ygl-trees node import --file tree.json --tree copy  # 严格校验、事务导
 
 **跨树巡检 + 临期门槛（0.82）**：`node ready --all` 一次扫全部树（12 棵树 24 条命令 → 1 条）；`node cond --due [--days N]` 列出问题文本带 `YYYY-MM-DD` 期限且 N 天内到期（含逾期）的 eval 条件——w1/d90 预测门槛不再依赖人记得看；`--eval` 逐条送判定模型（离线安全回落 pending），**判定只报告不仲裁**（通过 ≠ 自动解锁，resolve/unlock 保持人工，与 predict audit 同纪律）。
 
+**并发钉住 + 半写防护（0.83，真实用户报告）**：并发会话共享 `current_project` 指针互踩导致资产碎片化——研究/产出/树三域写命令全部接受长旗标钉住：`research * --project <p>`、`produce/task * --project <p>`、`node * --tree <t>`（短旗标 `-p`/`-t` 不变）；写回执带 `· project <名>` 回显落点，写错项目当场可见。`source add --query` 引用不存在时**先拒绝后写入**（rc=1、零落地），不再出现"源已落、链接失败"的半写；`job run/tick` 的子命令以无锁环境启动（WAL 并发读），`ygl-trees …` 型任务命令不再与运行器自身死锁。`--help` 在任意深度（如 `kb add --help`）打组帮助 rc=0；`db init` 前的报错提示 `YGL_HOME` 工作区根因；到期巡检可直接挂 job（`job add "到期巡检" --every 1440 -- ygl-trees node cond --due --days 30`）。
+
 **决策模型评估门（spec R8；0.14 布尔 → 0.26 三题型 → 0.27 混批 → 0.80 织物并入）**：语义型必检条件用 eval 题型声明，`node can <key> --eval` 会把**节点元数据 + 直接父（关联）+ 祖先链（闭包索引）+ 条件组 + 已解锁集 + --state 袋 + rel 挂接摘要**组装为上下文包，交给评估模型（TypeSafe jev，经 Vercel AI Gateway）判定：
 
 - **rel 织物并入（0.80）**：节点挂接的 evidence（quote 摘要）/ claim（text+status+confidence）/ kb/source（标题）等 rel 关系（双向，≤12 条，文本截 120 字）自动进上下文包的 `attachments`——「证据挂链」纪律从此对语义门槛可见，不必再 `--state k=v` 手动携带裁决事实（实测 P 0.30 → 0.92 的差距由挂链补平）
+- **attachments 快照（0.83）**：`node can <key> --eval` 的输出（`--json` 的 `eval_attachments[]` + 人类视图 `attachments ×N:`）回显本次判定实际吃到的 rel 挂接——P 值过了也能一眼看出依据是哪几条 evidence/claim，复现不必翻库
 
 - **三题型**：`--op eval`（布尔 P(true)）/ `--op eval-choice`（多选一，判 **P(期望答案)**，`--options "k=desc,..."` + `--answer k`）/ `--op eval-score`（等级评分 `--levels "级0,..."` 2-10 级 + `--min-score n`，判概率加权均值 ±1 灰带）
 - P≥0.7 通过 · P≤0.4 未通过 · **灰带 pending**（过程态，禁作终态，单列不阻塞也不放行）；score 的灰带是 [min−1, min)
@@ -131,14 +134,17 @@ ygl-trees node import --file tree.json --tree copy  # 严格校验、事务导
 ```
 query add       登记检索式
 query attach    检索式 ↔ 来源关联（query list 显示召回数）
-source add      收来源，按 (project, url_hash) 去重；--query 顺带关联
+source add      收来源，按 (project, url_hash) 去重；--query 顺带关联（引用不存在 → 整体拒绝 rc=1，零落地）
+                全组接受 --project <p> 长旗标钉住目标项目（并发会话不依赖共享 current 指针；回执带 · project 回显）
                 --adjudication "<裁决摘要>"：会话内裁决原生载体（url 自动 session://adjudication/<时刻>，摘要兼作标题）；--url 收任意 <scheme>://（https/file/session/a2a/… 跨 Agent 引用免落盘）
 source fetch <url>  直接抓取网页入库：title/meta description/去标签正文；15s 超时、非 html 拒收、失败零副作用，正文过薄自动打 needs_review
 evidence add    从来源摘原文片段，带 locator（页码/章节）；长摘录用 --file <path> 免转义
 claim add       写下断言；--confidence 收 A|B|C 或数值档（0.92 / 85% 原样入库）
 claim link      断言 ↔ 证据，自动算 supported / refuted / contested
                 --by-source：传来源 id 一次挂齐其全部证据；误传来源 id 会列出该来源的证据 id
+                [预测·…] 断言不自动晋升（0.82.1）：挂证据≠仲裁，状态保持 unverified 直到显式 resolve / 到期回测
 claim resolve   人工仲裁出口：--as supported|refuted|contested，事件留痕；后续新证据链接会重新推导
+claim unresolve 复位通道：把断言重置回 unverified（撤销链接副作用 / 抢跑仲裁），幂等 duplicate:true
 predict audit   预测回测：扫描 [预测·N天] 断言，本地可测判据自动测（树/kb 计数、npm 版本数），判 hit/miss/pending/manual——只报告不仲裁，给出待 resolve 建议
                 --state <file|url>：外部计数桥接（如 DSH API 快照），判据里的裸键名后缀匹配嵌套键（y_imported≥12 ← counts.y_imported）
                 已 claim resolve 的预测默认隐藏（回测终态），--all 查看全表
@@ -294,7 +300,7 @@ ygl-trees agent ask "<question>"     natural language interface
 ## 五b、开发与运维工具
 
 ```bash
-pnpm test          # 四段制回归：unit (vitest 172 例) + build (tsc + tsdown) + demo（101 条断言）+ contract:audit（86 项）
+pnpm test          # 四段制回归：unit (vitest 177 例) + build (tsc + tsdown) + demo（113 条断言）+ contract:audit（86 项）
 pnpm bench         # 性能基准七席（startup/写路径/检索/索引），每席含 RSS 内存端点 → tmp/bench-results.json
 node benchmarks/bench.js --quick   # 缩小规模快速跑
 pnpm pack:check    # 发布就绪门禁：打包 → 隔离安装 → 驱动发布产物跑命令面 + --json 纯净性

package/dist/apps/cli/src/bin.js

@@ -42,6 +42,7 @@ exports.loadBundle = loadBundle;
 exports.repoRoot = repoRoot;
 exports.appVersion = appVersion;
 exports.usage = usage;
+exports.groupHelp = groupHelp;
 exports.main = main;
 exports.generateLlmsManifest = generateLlmsManifest;
 /**
@@ -163,6 +164,7 @@ ${(0, fmt_1.paint)(fmt_1.C.bold, "research", true)}    collect → screen → ex
   claim link <claimId> <evidenceId> [--stance supports|refutes]
                                       --by-source <claimId> <sourceId>: link ALL evidence under a source
   claim resolve <claimId> --as supported|refuted|contested [--note]
+  claim unresolve <claimId>   reset to unverified (undo auto-promote / early arbitration)
   claim list
 
 ${(0, fmt_1.paint)(fmt_1.C.bold, "produce", true)}     outline → section → report · spec/design（工程产出）
@@ -250,6 +252,25 @@ Global: --json  --no-color  --db <file>  --home <dir>
 function usage() {
     return USAGE;
 }
+/** 0.83 (user report ②): `--help` at any depth prints the relevant usage
+ * slice — `kb add --help` used to fall into flag validation rc=2. Renders the
+ * group's own block (found by its bold header line); unknown groups get the
+ * full usage. */
+function groupHelp(group) {
+    const pfx = (0, fmt_1.paint)(fmt_1.C.bold, group, true);
+    const lines = USAGE.split("\n");
+    const start = lines.findIndex((l) => l.startsWith(pfx));
+    if (start < 0)
+        return USAGE;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (lines[i].startsWith("\u001b[1m")) {
+            end = i;
+            break;
+        }
+    }
+    return lines.slice(0, 4).join("\n") + "\n\n" + lines.slice(start, end).join("\n").trimEnd();
+}
 // ── Main ──
 async function main(argv) {
     const args = (0, types_1.parse)(argv);
@@ -290,6 +311,17 @@ async function main(argv) {
         (0, fmt_1.out)(ctx, appVersion());
         return 0;
     }
+    // 0.83 (user report ②): `--help` at ANY depth prints the group's usage
+    // slice rc=0 — `kb add --help` used to fall into flag validation rc=2.
+    // Fires before dispatch and before db boot: help never touches the db.
+    if (args.flags.help === true && group) {
+        const text = groupHelp(group);
+        if (ctx.json)
+            console.log(JSON.stringify({ help: text.replace(/\u001b\[[0-9;]*m/g, "") }, null, 2));
+        else
+            (0, fmt_1.out)(ctx, text);
+        return 0;
+    }
     // llms: structured capability manifest for LLM consumption (Ant Design
     // "for-agents" pattern — one output gives any Agent the full command surface).
     // Onboarding: detect first run (no DB) and guide to db init
@@ -363,6 +395,10 @@ async function main(argv) {
     if (needInit && !require("node:fs").existsSync(file)) {
         (0, fmt_1.bad)(ctx, `no database at ${file}`);
         (0, fmt_1.out)(ctx, `  run: ygl-trees db init`);
+        // 0.83 (user report ③): name the workspace root cause — a foreign
+        // YGL_HOME (or its absence) is invisible otherwise, and the user chases
+        // the db instead of the environment.
+        (0, fmt_1.out)(ctx, `  workspace: ${home}${process.env.YGL_HOME ? "  (from YGL_HOME)" : "  (default ~/.ygl-trees — set YGL_HOME to switch)"}`);
         return 2;
     }
     // ── Cordis composition via bootApp (DSH profile-boot exemplar) ──
@@ -664,6 +700,7 @@ function generateLlmsManifest() {
                 ["research claim add \"<text>\"", "refutable assertion"],
                 ["research claim link <cid> <eid> --stance supports|refutes", "link claim to evidence"],
                 ["research claim resolve <cid> --as supported|refuted|contested", "manual arbitration"],
+                ["research claim unresolve <cid>", "reset to unverified (undo link auto-promote)"],
                 ["research claim evaluate <cid>", "decision model confidence (0-5 → A/B/C/D)"],
                 ["research evidence assess <eid>", "decision model quality assessment"],
             ]],

package/dist/bundle/bin.cjs

@@ -4088,6 +4088,7 @@ var writes_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll({
 	claimAdd: () => claimAdd,
 	claimLink: () => claimLink,
 	claimResolve: () => claimResolve,
+	claimUnresolve: () => claimUnresolve,
 	evidenceAdd: () => evidenceAdd,
 	jobAdd: () => jobAdd,
 	kbAdd: () => kbAdd,
@@ -4343,7 +4344,8 @@ function mapClaim(c) {
 }
 async function claimLink(ds, claimId, evidenceId, stance = "supports") {
 	return ds.transaction(async (mgr) => {
-		if (!(await mgr.query(`SELECT id FROM claims WHERE id=?`, [claimId])).length) throw new Error(`claim not found: ${claimId}`);
+		const c = await mgr.query(`SELECT id, text FROM claims WHERE id=?`, [claimId]);
+		if (!c.length) throw new Error(`claim not found: ${claimId}`);
 		if (!(await mgr.query(`SELECT id FROM evidence WHERE id=?`, [evidenceId])).length) throw new Error(`evidence not found: ${evidenceId}`);
 		await mgr.query(`INSERT INTO claim_evidence(claim_id,evidence_id,stance) VALUES(?,?,?)
        ON CONFLICT(claim_id,evidence_id) DO UPDATE SET stance=excluded.stance`, [
@@ -4351,6 +4353,15 @@ async function claimLink(ds, claimId, evidenceId, stance = "supports") {
 			evidenceId,
 			stance
 		]);
+		if (String(c[0]?.text ?? "").startsWith("[预测·")) {
+			const cur = await mgr.query(`SELECT status FROM claims WHERE id=?`, [claimId]);
+			const status = String(cur?.[0]?.status ?? "unverified");
+			await logEvent$1(mgr, "claim.link", "claim", claimId, `${stance} ${evidenceId} (prediction: auto-promote skipped)`);
+			return {
+				status,
+				auto_promote: false
+			};
+		}
 		const sup = await mgr.query(`SELECT COUNT(*) AS c FROM claim_evidence WHERE claim_id=? AND stance='supports'`, [claimId]);
 		const ref = await mgr.query(`SELECT COUNT(*) AS c FROM claim_evidence WHERE claim_id=? AND stance='refutes'`, [claimId]);
 		const s = Number(sup?.[0]?.c ?? 0);
@@ -4358,7 +4369,33 @@ async function claimLink(ds, claimId, evidenceId, stance = "supports") {
 		const status = s && r ? "contested" : s ? "supported" : r ? "refuted" : "unverified";
 		await mgr.update(Claim, { id: claimId }, { status });
 		await logEvent$1(mgr, "claim.link", "claim", claimId, `${stance} ${evidenceId}`);
-		return { status };
+		return {
+			status,
+			auto_promote: true
+		};
+	});
+}
+/** 0.82.1 (user report ③): reset an auto-promoted / wrongly arbitrated claim
+* back to unverified — the repair channel for link side effects on
+* predictions (and for any claim arbitrated too early). Idempotent: already
+* unverified → duplicate:true, no event spam. */
+async function claimUnresolve(ds, claimId) {
+	return ds.transaction(async (mgr) => {
+		const c = await mgr.query(`SELECT id, status FROM claims WHERE id=?`, [claimId]);
+		if (!c.length) throw new Error(`claim not found: ${claimId}`);
+		if (String(c[0]?.status) === "unverified") return {
+			status: "unverified",
+			duplicate: true
+		};
+		await mgr.update(Claim, { id: claimId }, {
+			status: "unverified",
+			updated: require_text.nowIso()
+		});
+		await logEvent$1(mgr, "claim.unresolve", "claim", claimId, `${c[0]?.status} → unverified`);
+		return {
+			status: "unverified",
+			duplicate: false
+		};
 	});
 }
 async function claimResolve(ds, claimId, status, note = "") {
@@ -5751,7 +5788,11 @@ function execute(env, job) {
 				"pipe",
 				"pipe"
 			],
-			timeout: 6e5
+			timeout: 6e5,
+			env: {
+				...process.env,
+				YGL_SERVE: "1"
+			}
 		});
 		rc = 0;
 	} catch (e) {
@@ -6594,7 +6635,7 @@ function run$8(env, action, rest, args) {
 	const subAction = rest[0];
 	let project;
 	try {
-		project = store.projectResolve(args.flags.p ? String(args.flags.p) : void 0);
+		project = store.projectResolve(args.flags.p ?? args.flags.project ? String(args.flags.p ?? args.flags.project) : void 0);
 	} catch (e) {
 		bad(ctx, e.message);
 		return 1;
@@ -6733,12 +6774,25 @@ function run$8(env, action, rest, args) {
 				tags: String(args.flags.tags || "")
 			};
 			const qRef = String(args.flags.query || "");
+			if (qRef) {
+				if (!store.db.get("SELECT id FROM queries WHERE (id=? OR text=?) AND project_id=?", [
+					qRef,
+					qRef,
+					project.id
+				])) {
+					bad(ctx, `query not found: ${require_text.clip(qRef, 40)} — refusing to write (source add would land without its query link; fix the ref or drop --query)`);
+					return 1;
+				}
+			}
 			return getOrm(env.db.path).then(async (ds) => {
 				const r = await sourceAdd(ds, project.id, spec);
-				writeResult(ctx, r, (row) => `source added: ${row.id}  ${require_text.clip(row.title, 60)}`);
-				if (qRef) {
+				writeResult(ctx, r, (row) => `source added: ${row.id}  ${require_text.clip(row.title, 60)}  · project ${project.name}`);
+				if (qRef) try {
 					const at = await queryAttach(ds, project.id, qRef, r.row.id);
 					if (!ctx.json && !at.dup) out(ctx, paint(C.dim, `  attached to query: "${require_text.clip(at.queryText, 40)}"`, ctx.color));
+				} catch (e) {
+					bad(ctx, `source landed as ${r.row.id} but attach failed: ${e?.message} — research query attach ${require_text.clip(qRef, 20)} ${r.row.id} to retry`);
+					return 1;
 				}
 				return 0;
 			}).catch((e) => {
@@ -6911,7 +6965,7 @@ function run$8(env, action, rest, args) {
 			}
 			const note = String(args.flags.note || "");
 			const locator = String(args.flags.locator || "");
-			return runWrite(env, (ds) => evidenceAdd(ds, project.id, sourceId, quote, note, locator, force), (r) => `evidence added: ${r.id}  ${require_text.clip(quote, 50)}`);
+			return runWrite(env, (ds) => evidenceAdd(ds, project.id, sourceId, quote, note, locator, force), (r) => `evidence added: ${r.id}  ${require_text.clip(quote, 50)}  · project ${project.name}`);
 		}
 		if (action === "evidence" && subAction === "assess") {
 			const id = rest[1];
@@ -7007,7 +7061,7 @@ function run$8(env, action, rest, args) {
 				return 2;
 			}
 			const confidence = String(args.flags.confidence || configGet(env.db, "default_confidence"));
-			return runWrite(env, (ds) => claimAdd(ds, project.id, text, confidence, force), (r) => `claim added: ${r.id}  ${require_text.clip(text, 60)}`);
+			return runWrite(env, (ds) => claimAdd(ds, project.id, text, confidence, force), (r) => `claim added: ${r.id}  ${require_text.clip(text, 60)}  · project ${project.name}`);
 		}
 		if (subAction === "link") {
 			if (!rest[1] || !rest[2]) {
@@ -7049,7 +7103,15 @@ function run$8(env, action, rest, args) {
 				});
 			}
 			return getOrm(env.db.path).then((ds) => claimLink(ds, rest[1], rest[2], stance)).then((r) => {
-				ok(ctx, `linked; claim status now: ${r.status}`);
+				if (ctx.json) console.log(JSON.stringify({
+					claim: rest[1],
+					evidence: rest[2],
+					stance,
+					status: r.status,
+					auto_promote: r.auto_promote
+				}, null, 2));
+				else if (r.auto_promote === false) ok(ctx, `linked; prediction claim stays ${r.status} — auto-promote skipped (arbitration: claim resolve / deadline audit)`);
+				else ok(ctx, `linked; claim status now: ${r.status}`);
 				try {
 					const { evaluateClaimConfidence } = (init_eval_enhance(), require_rolldown_runtime.__toCommonJS(eval_enhance_exports));
 					const evRows = store.db.all(`SELECT e.quote, ce.stance, s.title AS source_title
@@ -7129,6 +7191,30 @@ function run$8(env, action, rest, args) {
 				return 1;
 			});
 		}
+		if (subAction === "unresolve") {
+			const id = rest[1];
+			if (!id) {
+				bad(ctx, "usage: research claim unresolve <claimId>");
+				return 2;
+			}
+			const c0 = store.db.get("SELECT id, status FROM claims WHERE id=? AND project_id=?", [id, project.id]);
+			if (!c0) {
+				bad(ctx, `claim not found: ${id}`);
+				return 1;
+			}
+			return getOrm(env.db.path).then((ds) => claimUnresolve(ds, id)).then((r) => {
+				if (ctx.json) console.log(JSON.stringify({
+					id,
+					status: r.status,
+					duplicate: r.duplicate
+				}, null, 2));
+				else ok(ctx, r.duplicate ? `claim ${id} already unverified (no change)` : `claim ${id}: ${c0.status} → unverified  (back in tracking; arbitration: claim resolve)`);
+				return 0;
+			}).catch((e) => {
+				bad(ctx, e?.message || String(e));
+				return 1;
+			});
+		}
 		if (subAction === "evaluate") {
 			const id = rest[1];
 			if (!id) {
@@ -7356,7 +7442,7 @@ function run$7(env, action, rest, args) {
 			ack(ctx, { project: name }, `now using: ${name}`);
 			return 0;
 		case "show": {
-			const resolved = store.projectResolve(args.flags.p ? String(args.flags.p) : void 0);
+			const resolved = store.projectResolve(args.flags.p ?? args.flags.project ? String(args.flags.p ?? args.flags.project) : void 0);
 			return getOrm(env.db.path).then(async (ds) => {
 				const proj = await ds.getRepository(Project).findOne({
 					where: { id: resolved.id },
@@ -7777,7 +7863,7 @@ function run$5(env, action, rest, args) {
 	}
 	let project;
 	try {
-		project = store.projectResolve(args.flags.p ? String(args.flags.p) : void 0);
+		project = store.projectResolve(args.flags.p ?? args.flags.project ? String(args.flags.p ?? args.flags.project) : void 0);
 	} catch (e) {
 		bad(ctx, e.message);
 		return 1;
@@ -7889,7 +7975,7 @@ function run$5(env, action, rest, args) {
 			return getOrm(env.db.path).then((ds) => taskAdd(ds, pid, title, note)).then((row) => {
 				if (!nodeRef) {
 					if (ctx.json) console.log(JSON.stringify(row, null, 2));
-					else ok(ctx, `task added: ${row.id}  ${title}`);
+					else ok(ctx, `task added: ${row.id}  ${title}  · project ${project.name}`);
 					return 0;
 				}
 				return relAdd(env, `node:${nodeRef}`, `task:${row.id}`, "tracked-by").then((r) => {
@@ -8713,7 +8799,7 @@ require_text.init_text();
 function run$4(env, action, rest, args) {
 	const { ctx, db } = env;
 	const trees = new TreeStore(db);
-	const sel = args.flags.t ? String(args.flags.t) : void 0;
+	const sel = !(action === "import") ? args.flags.t ?? args.flags.tree ? String(args.flags.t ?? args.flags.tree) : void 0 : args.flags.t ? String(args.flags.t) : void 0;
 	const flagNum = (k, d) => {
 		const v = Number(args.flags[k]);
 		return Number.isFinite(v) ? v : d;
@@ -9274,6 +9360,8 @@ function run$4(env, action, rest, args) {
 				}
 				r.pending = pendingList;
 				r.evaluated = evaluated;
+				const atts = contextPkg.attachments;
+				if (Array.isArray(atts) && atts.length) r.eval_attachments = atts;
 				r.ok = r.missing_required.length === 0 && r.blocked_by.length === 0 && pendingList.length === 0;
 				try {
 					const run = process.env.YGL_RUN_ID || "";
@@ -9357,6 +9445,13 @@ function run$4(env, action, rest, args) {
 						for (const m of r.missing_optional) out(ctx, `    - ${m}`);
 					}
 					for (const e of r.evaluated) out(ctx, paint(C.dim, `  eval ${e.name}: P=${e.p ?? "-"} → ${e.outcome}${e.reason ? ` (${e.reason})` : ""}`, ctx.color));
+					if (Array.isArray(r.eval_attachments) && r.eval_attachments.length) {
+						out(ctx, paint(C.dim, `  attachments ×${r.eval_attachments.length}:`, ctx.color));
+						for (const a of r.eval_attachments) {
+							const label = a.type === "claim" ? `${a.id}(${a.status})` : a.type === "evidence" ? `${a.id} "${require_text.clip(a.quote, 36)}"` : a.type === "kb" || a.type === "source" ? `${a.id} ${require_text.clip(a.title, 30)}` : a.type === "node" ? `${a.key ?? a.id}` : String(a.id);
+							out(ctx, paint(C.dim, `    - ${a.rel} ← ${a.type}:${label}`, ctx.color));
+						}
+					}
 					if (r.cost_multiplier !== 1) out(ctx, `  成本系数 ${r.cost_multiplier}`);
 					return 0;
 				}
@@ -9648,10 +9743,11 @@ function run$4(env, action, rest, args) {
 		if (sub === "list" || sub === void 0) {
 			for (const f of Object.keys(args.flags || {})) if (![
 				"t",
+				"tree",
 				"json",
 				"no-color"
 			].includes(f)) {
-				bad(ctx, `unknown flag --${f} for 'node list' — tree selection is '-t <tree>' (positional <tree> also works)`);
+				bad(ctx, `unknown flag --${f} for 'node list' — tree selection is '-t|--tree <tree>' (positional <tree> also works)`);
 				return 2;
 			}
 			table(ctx, trees.nodeList(tid), [
@@ -11979,6 +12075,7 @@ ${paint(C.bold, "research", true)}    collect → screen → extract → claim
   claim link <claimId> <evidenceId> [--stance supports|refutes]
                                       --by-source <claimId> <sourceId>: link ALL evidence under a source
   claim resolve <claimId> --as supported|refuted|contested [--note]
+  claim unresolve <claimId>   reset to unverified (undo auto-promote / early arbitration)
   claim list
 
 ${paint(C.bold, "produce", true)}     outline → section → report · spec/design（工程产出）
@@ -12066,6 +12163,22 @@ Global: --json  --no-color  --db <file>  --home <dir>
 function usage() {
 	return USAGE;
 }
+/** 0.83 (user report ②): `--help` at any depth prints the relevant usage
+* slice — `kb add --help` used to fall into flag validation rc=2. Renders the
+* group's own block (found by its bold header line); unknown groups get the
+* full usage. */
+function groupHelp(group) {
+	const pfx = paint(C.bold, group, true);
+	const lines = USAGE.split("\n");
+	const start = lines.findIndex((l) => l.startsWith(pfx));
+	if (start < 0) return USAGE;
+	let end = lines.length;
+	for (let i = start + 1; i < lines.length; i++) if (lines[i].startsWith("\x1B[1m")) {
+		end = i;
+		break;
+	}
+	return lines.slice(0, 4).join("\n") + "\n\n" + lines.slice(start, end).join("\n").trimEnd();
+}
 async function main(argv) {
 	const args = parse(argv);
 	const ctx = {
@@ -12081,6 +12194,12 @@ async function main(argv) {
 		out(ctx, appVersion());
 		return 0;
 	}
+	if (args.flags.help === true && group) {
+		const text = groupHelp(group);
+		if (ctx.json) console.log(JSON.stringify({ help: text.replace(/\u001b\[[0-9;]*m/g, "") }, null, 2));
+		else out(ctx, text);
+		return 0;
+	}
 	if (!group || group === "help") {
 		const dbFile = require("node:path").join(process.env.YGL_HOME || require("node:path").join(require("node:os").homedir(), ".ygl-trees"), "ygl-trees.db");
 		if (!require("node:fs").existsSync(dbFile)) {
@@ -12141,6 +12260,7 @@ async function main(argv) {
 	if (!(group === "db" && action === "init") && group !== "plugin" && !require("node:fs").existsSync(file)) {
 		bad(ctx, `no database at ${file}`);
 		out(ctx, `  run: ygl-trees db init`);
+		out(ctx, `  workspace: ${home}${process.env.YGL_HOME ? "  (from YGL_HOME)" : "  (default ~/.ygl-trees — set YGL_HOME to switch)"}`);
 		return 2;
 	}
 	const VERSION = appVersion();
@@ -12429,6 +12549,7 @@ function generateLlmsManifest() {
 				["research claim add \"<text>\"", "refutable assertion"],
 				["research claim link <cid> <eid> --stance supports|refutes", "link claim to evidence"],
 				["research claim resolve <cid> --as supported|refuted|contested", "manual arbitration"],
+				["research claim unresolve <cid>", "reset to unverified (undo link auto-promote)"],
 				["research claim evaluate <cid>", "decision model confidence (0-5 → A/B/C/D)"],
 				["research evidence assess <eid>", "decision model quality assessment"]
 			]
@@ -12593,6 +12714,7 @@ if (require.main === module) main(process.argv.slice(2)).then((rc) => {
 exports.HOME = HOME;
 exports.appVersion = appVersion;
 exports.generateLlmsManifest = generateLlmsManifest;
+exports.groupHelp = groupHelp;
 exports.loadBundle = loadBundle;
 exports.main = main;
 exports.repoRoot = repoRoot;

package/dist/packages/ops/tools/src/job-cmds.js

@@ -162,7 +162,17 @@ function execute(env, job) {
     let output = "";
     const started = Date.now();
     try {
-        output = (0, node_child_process_1.execSync)(job.command, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 600_000 });
+        // 0.83: the runner process itself holds the app-level write lock; a job
+        // command that invokes ygl-trees again would collide with its own parent
+        // (self-deadlock — every `ygl-trees …` job failed rc=1 "locked"). Children
+        // boot lock-free like webui serve: WAL already permits concurrent readers
+        // and serializes writers at the SQLite layer.
+        output = (0, node_child_process_1.execSync)(job.command, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 600_000,
+            env: { ...process.env, YGL_SERVE: "1" },
+        });
         rc = 0;
     }
     catch (e) {

package/dist/packages/research/pipeline/src/cmds.js

@@ -72,7 +72,7 @@ function run(env, action, rest, args) {
     // -- project resolution (allow --p override) -----------------------------
     let project;
     try {
-        project = store.projectResolve(args.flags.p ? String(args.flags.p) : undefined);
+        project = store.projectResolve((args.flags.p ?? args.flags.project) ? String(args.flags.p ?? args.flags.project) : undefined);
     }
     catch (e) {
         (0, fmt_1.bad)(ctx, e.message);
@@ -222,14 +222,32 @@ function run(env, action, rest, args) {
                 tags: String(args.flags.tags || ""),
             };
             const qRef = String(args.flags.query || "");
+            // 0.83 (user report ①): half-write guard — `source add --query X` used
+            // to commit the source FIRST and attach separately; a bad query ref
+            // left the source landed with a pure error receipt (assets fragment
+            // silently). Pre-validate the query ref before ANY write; if the
+            // attach still fails post-write, name the landed source + the retry.
+            if (qRef) {
+                const q = store.db.get("SELECT id FROM queries WHERE (id=? OR text=?) AND project_id=?", [qRef, qRef, project.id]);
+                if (!q) {
+                    (0, fmt_1.bad)(ctx, `query not found: ${(0, text_1.clip)(qRef, 40)} — refusing to write (source add would land without its query link; fix the ref or drop --query)`);
+                    return 1;
+                }
+            }
             return (0, orm_1.getOrm)(env.db.path)
                 .then(async (ds) => {
                 const r = await writes.sourceAdd(ds, project.id, spec);
-                (0, fmt_1.writeResult)(ctx, r, (row) => `source added: ${row.id}  ${(0, text_1.clip)(row.title, 60)}`);
+                (0, fmt_1.writeResult)(ctx, r, (row) => `source added: ${row.id}  ${(0, text_1.clip)(row.title, 60)}  · project ${project.name}`);
                 if (qRef) {
-                    const at = await writes.queryAttach(ds, project.id, qRef, r.row.id);
-                    if (!ctx.json && !at.dup)
-                        (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  attached to query: "${(0, text_1.clip)(at.queryText, 40)}"`, ctx.color));
+                    try {
+                        const at = await writes.queryAttach(ds, project.id, qRef, r.row.id);
+                        if (!ctx.json && !at.dup)
+                            (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  attached to query: "${(0, text_1.clip)(at.queryText, 40)}"`, ctx.color));
+                    }
+                    catch (e) {
+                        (0, fmt_1.bad)(ctx, `source landed as ${r.row.id} but attach failed: ${e?.message} — research query attach ${(0, text_1.clip)(qRef, 20)} ${r.row.id} to retry`);
+                        return 1;
+                    }
                 }
                 return 0;
             })
@@ -411,7 +429,7 @@ function run(env, action, rest, args) {
             }
             const note = String(args.flags.note || "");
             const locator = String(args.flags.locator || "");
-            return runWrite(env, (ds) => writes.evidenceAdd(ds, project.id, sourceId, quote, note, locator, force), (r) => `evidence added: ${r.id}  ${(0, text_1.clip)(quote, 50)}`);
+            return runWrite(env, (ds) => writes.evidenceAdd(ds, project.id, sourceId, quote, note, locator, force), (r) => `evidence added: ${r.id}  ${(0, text_1.clip)(quote, 50)}  · project ${project.name}`);
         }
         // R15.3: evidence assess — decision model evaluates evidence quality
         if (action === "evidence" && subAction === "assess") {
@@ -504,7 +522,7 @@ function run(env, action, rest, args) {
                 return 2;
             }
             const confidence = String(args.flags.confidence || (0, config_1.configGet)(env.db, "default_confidence"));
-            return runWrite(env, (ds) => writes.claimAdd(ds, project.id, text, confidence, force), (r) => `claim added: ${r.id}  ${(0, text_1.clip)(text, 60)}`);
+            return runWrite(env, (ds) => writes.claimAdd(ds, project.id, text, confidence, force), (r) => `claim added: ${r.id}  ${(0, text_1.clip)(text, 60)}  · project ${project.name}`);
         }
         if (subAction === "link") {
             if (!rest[1] || !rest[2]) {
@@ -555,7 +573,17 @@ function run(env, action, rest, args) {
             return (0, orm_1.getOrm)(env.db.path)
                 .then((ds) => writes.claimLink(ds, rest[1], rest[2], stance))
                 .then((r) => {
-                (0, fmt_1.ok)(ctx, `linked; claim status now: ${r.status}`);
+                // 0.82.1: prediction claims never auto-promote on link — the receipt
+                // says so explicitly instead of showing a silently-unchanged status.
+                if (ctx.json) {
+                    console.log(JSON.stringify({ claim: rest[1], evidence: rest[2], stance, status: r.status, auto_promote: r.auto_promote }, null, 2));
+                }
+                else if (r.auto_promote === false) {
+                    (0, fmt_1.ok)(ctx, `linked; prediction claim stays ${r.status} — auto-promote skipped (arbitration: claim resolve / deadline audit)`);
+                }
+                else {
+                    (0, fmt_1.ok)(ctx, `linked; claim status now: ${r.status}`);
+                }
                 // R15 深度集成：链接后自动触发置信度评估（有模型时静默执行）
                 try {
                     const { evaluateClaimConfidence } = require("../../../ops/tools/src/eval-enhance");
@@ -629,6 +657,36 @@ function run(env, action, rest, args) {
                 return 1;
             });
         }
+        // 0.82.1 (user report ③): the repair channel for link side effects —
+        // resets a claim to unverified. Covers predictions auto-promoted before
+        // 0.82.1 AND any claim arbitrated too early (explicit un-arbitration).
+        if (subAction === "unresolve") {
+            const id = rest[1];
+            if (!id) {
+                (0, fmt_1.bad)(ctx, "usage: research claim unresolve <claimId>");
+                return 2;
+            }
+            const c0 = store.db.get("SELECT id, status FROM claims WHERE id=? AND project_id=?", [id, project.id]);
+            if (!c0) {
+                (0, fmt_1.bad)(ctx, `claim not found: ${id}`);
+                return 1;
+            }
+            return (0, orm_1.getOrm)(env.db.path)
+                .then((ds) => writes.claimUnresolve(ds, id))
+                .then((r) => {
+                if (ctx.json)
+                    console.log(JSON.stringify({ id, status: r.status, duplicate: r.duplicate }, null, 2));
+                else
+                    (0, fmt_1.ok)(ctx, r.duplicate
+                        ? `claim ${id} already unverified (no change)`
+                        : `claim ${id}: ${c0.status} → unverified  (back in tracking; arbitration: claim resolve)`);
+                return 0;
+            })
+                .catch((e) => {
+                (0, fmt_1.bad)(ctx, e?.message || String(e));
+                return 1;
+            });
+        }
         // R15.2: claim evaluate — decision model evaluates confidence from linked evidence
         if (subAction === "evaluate") {
             const id = rest[1];

package/dist/packages/research/pipeline/src/writes.js

@@ -5,6 +5,7 @@ exports.sourceAdd = sourceAdd;
 exports.evidenceAdd = evidenceAdd;
 exports.claimAdd = claimAdd;
 exports.claimLink = claimLink;
+exports.claimUnresolve = claimUnresolve;
 exports.claimResolve = claimResolve;
 exports.queryAttach = queryAttach;
 exports.kbAdd = kbAdd;
@@ -178,7 +179,7 @@ async function claimLink(ds, claimId, evidenceId, stance = "supports") {
     return ds.transaction(async (mgr) => {
         // Resolve both ends before writing: a bad/foreign id must surface as a
         // named not-found, not as a raw FOREIGN KEY constraint failure.
-        const c = (await mgr.query(`SELECT id FROM claims WHERE id=?`, [claimId]));
+        const c = (await mgr.query(`SELECT id, text FROM claims WHERE id=?`, [claimId]));
         if (!c.length)
             throw new Error(`claim not found: ${claimId}`);
         const e = (await mgr.query(`SELECT id FROM evidence WHERE id=?`, [evidenceId]));
@@ -186,6 +187,19 @@ async function claimLink(ds, claimId, evidenceId, stance = "supports") {
             throw new Error(`evidence not found: ${evidenceId}`);
         await mgr.query(`INSERT INTO claim_evidence(claim_id,evidence_id,stance) VALUES(?,?,?)
        ON CONFLICT(claim_id,evidence_id) DO UPDATE SET stance=excluded.stance`, [claimId, evidenceId, stance]);
+        // 0.82.1 (user report ③): prediction claims (`[预测·…]` prefix) must NOT
+        // auto-promote on link — predict audit treats supported/refuted as
+        // human-arbitrated (terminal), so a mere evidence link would kick the
+        // prediction out of the tracking table before its deadline. Evidence
+        // linking is evidence gathering; arbitration stays an explicit
+        // `claim resolve` (frozen contract, same discipline as predict audit).
+        const text = String(c[0]?.text ?? "");
+        if (text.startsWith("[预测·")) {
+            const cur = (await mgr.query(`SELECT status FROM claims WHERE id=?`, [claimId]));
+            const status = String(cur?.[0]?.status ?? "unverified");
+            await logEvent(mgr, "claim.link", "claim", claimId, `${stance} ${evidenceId} (prediction: auto-promote skipped)`);
+            return { status, auto_promote: false };
+        }
         const sup = (await mgr.query(`SELECT COUNT(*) AS c FROM claim_evidence WHERE claim_id=? AND stance='supports'`, [claimId]));
         const ref = (await mgr.query(`SELECT COUNT(*) AS c FROM claim_evidence WHERE claim_id=? AND stance='refutes'`, [claimId]));
         const s = Number(sup?.[0]?.c ?? 0);
@@ -193,7 +207,23 @@ async function claimLink(ds, claimId, evidenceId, stance = "supports") {
         const status = s && r ? "contested" : s ? "supported" : r ? "refuted" : "unverified";
         await mgr.update(entities_1.Claim, { id: claimId }, { status });
         await logEvent(mgr, "claim.link", "claim", claimId, `${stance} ${evidenceId}`);
-        return { status };
+        return { status, auto_promote: true };
+    });
+}
+/** 0.82.1 (user report ③): reset an auto-promoted / wrongly arbitrated claim
+ * back to unverified — the repair channel for link side effects on
+ * predictions (and for any claim arbitrated too early). Idempotent: already
+ * unverified → duplicate:true, no event spam. */
+async function claimUnresolve(ds, claimId) {
+    return ds.transaction(async (mgr) => {
+        const c = (await mgr.query(`SELECT id, status FROM claims WHERE id=?`, [claimId]));
+        if (!c.length)
+            throw new Error(`claim not found: ${claimId}`);
+        if (String(c[0]?.status) === "unverified")
+            return { status: "unverified", duplicate: true };
+        await mgr.update(entities_1.Claim, { id: claimId }, { status: "unverified", updated: (0, text_1.nowIso)() });
+        await logEvent(mgr, "claim.unresolve", "claim", claimId, `${c[0]?.status} → unverified`);
+        return { status: "unverified", duplicate: false };
     });
 }
 async function claimResolve(ds, claimId, status, note = "") {

package/dist/packages/research/produce/src/produce-cmds.js

@@ -60,7 +60,7 @@ function run(env, action, rest, args) {
     }
     let project;
     try {
-        project = store.projectResolve(args.flags.p ? String(args.flags.p) : undefined);
+        project = store.projectResolve((args.flags.p ?? args.flags.project) ? String(args.flags.p ?? args.flags.project) : undefined);
     }
     catch (e) {
         (0, fmt_1.bad)(ctx, e.message);
@@ -204,7 +204,7 @@ function run(env, action, rest, args) {
                     if (ctx.json)
                         console.log(JSON.stringify(row, null, 2));
                     else
-                        (0, fmt_1.ok)(ctx, `task added: ${row.id}  ${title}`);
+                        (0, fmt_1.ok)(ctx, `task added: ${row.id}  ${title}  · project ${project.name}`);
                     return 0;
                 }
                 // 0.81 ⑦: tasks join the relation fabric — `task add --node` links

package/dist/packages/research/produce/src/project-cmds.js

@@ -115,7 +115,7 @@ function run(env, action, rest, args) {
             return 0;
         }
         case "show": {
-            const resolved = store.projectResolve(args.flags.p ? String(args.flags.p) : undefined);
+            const resolved = store.projectResolve((args.flags.p ?? args.flags.project) ? String(args.flags.p ?? args.flags.project) : undefined);
             return (0, orm_1.getOrm)(env.db.path)
                 .then(async (ds) => {
                 const proj = await ds.getRepository(entities_1.Project).findOne({

package/dist/packages/techtree/model/src/cmds.js

@@ -61,7 +61,14 @@ const text_1 = require("../../../core/text/src/text");
 function run(env, action, rest, args) {
     const { ctx, db } = env;
     const trees = new reads_1.TreeStore(db);
-    const sel = args.flags.t ? String(args.flags.t) : undefined;
+    // 0.83 (user report ①): --tree long alias alongside -t — pointer-hijack
+    // pinning needs an ergonomic, self-documenting form. EXCEPTION: `node
+    // import --tree <name>` is that command's own target-tree flag (create or
+    // merge destination), never a selector — alias must not shadow it.
+    const treeFlagAliasOk = !(action === "import");
+    const sel = treeFlagAliasOk
+        ? ((args.flags.t ?? args.flags.tree) ? String(args.flags.t ?? args.flags.tree) : undefined)
+        : (args.flags.t ? String(args.flags.t) : undefined);
     const flagNum = (k, d) => {
         const v = Number(args.flags[k]);
         return Number.isFinite(v) ? v : d;
@@ -548,6 +555,12 @@ function run(env, action, rest, args) {
                 }
                 r.pending = pendingList;
                 r.evaluated = evaluated;
+                // 0.83 (user report ④): snapshot the rel attachments the eval actually
+                // consumed — otherwise a passing P value can't be reproduced without
+                // digging the db. Byte-compat: field only when attachments exist.
+                const atts = contextPkg.attachments;
+                if (Array.isArray(atts) && atts.length)
+                    r.eval_attachments = atts;
                 r.ok = r.missing_required.length === 0 && r.blocked_by.length === 0 && pendingList.length === 0;
                 try {
                     const run = process.env.YGL_RUN_ID || "";
@@ -623,6 +636,18 @@ function run(env, action, rest, args) {
                     }
                     for (const e of r.evaluated)
                         (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  eval ${e.name}: P=${e.p ?? "-"} → ${e.outcome}${e.reason ? ` (${e.reason})` : ""}`, ctx.color));
+                    // 0.83 ④: what the model actually ate this run (rel fabric snapshot)
+                    if (Array.isArray(r.eval_attachments) && r.eval_attachments.length) {
+                        (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  attachments ×${r.eval_attachments.length}:`, ctx.color));
+                        for (const a of r.eval_attachments) {
+                            const label = a.type === "claim" ? `${a.id}(${a.status})`
+                                : a.type === "evidence" ? `${a.id} "${(0, text_1.clip)(a.quote, 36)}"`
+                                    : a.type === "kb" || a.type === "source" ? `${a.id} ${(0, text_1.clip)(a.title, 30)}`
+                                        : a.type === "node" ? `${a.key ?? a.id}`
+                                            : String(a.id);
+                            (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `    - ${a.rel} ← ${a.type}:${label}`, ctx.color));
+                        }
+                    }
                     if (r.cost_multiplier !== 1)
                         (0, fmt_1.out)(ctx, `  成本系数 ${r.cost_multiplier}`);
                     return 0;
@@ -819,11 +844,11 @@ function run(env, action, rest, args) {
         if (sub === "list" || sub === undefined) {
             // Contract ⑤ extension (user report: `node list --tree X` silently
             // swallowed the unknown flag and listed the CURRENT tree). node list
-            // takes exactly -t <tree> / --json — any other flag is a typo worth
-            // an explicit rc=2 instead of silent misdirection.
+            // takes exactly -t/--tree <tree> / --json — any other flag is a typo
+            // worth an explicit rc=2 instead of silent misdirection.
             for (const f of Object.keys(args.flags || {})) {
-                if (!["t", "json", "no-color"].includes(f)) {
-                    (0, fmt_1.bad)(ctx, `unknown flag --${f} for 'node list' — tree selection is '-t <tree>' (positional <tree> also works)`);
+                if (!["t", "tree", "json", "no-color"].includes(f)) {
+                    (0, fmt_1.bad)(ctx, `unknown flag --${f} for 'node list' — tree selection is '-t|--tree <tree>' (positional <tree> also works)`);
                     return 2;
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ygl-trees",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "description": "猿光 · 科技树 — database-centric CLI for research → production → knowledge reuse, built for AI agents.",
   "type": "commonjs",
   "main": "dist/apps/cli/index.js",
@@ -26,8 +26,8 @@
     "reflect-metadata": "^0.2.2",
     "typeorm": "^1.1.2",
     "@deepseek-ai/cordis": "~4.0.5-alpha.2",
-    "@deepseek-ai/cosmokit": "~1.8.6-alpha.2",
     "@deepseek-ai/schemastery": "~3.18.5-alpha.2",
+    "@deepseek-ai/cosmokit": "~1.8.6-alpha.2",
     "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.2"
   },
   "devDependencies": {

package/skills/ygl-trees-eval-gates/SKILL.md

@@ -66,6 +66,8 @@ ygl-trees node can gate-node --eval --json     # evaluated[] 带 type 字段 + p
 claim（text+status+confidence）、evidence（quote 截 120 字）、kb/source（标题）、node（key+name）、
 其余类型 id-only。裁决链 `decided-by` 挂好后 eval 模型直接可见，不必 `--state k=v` 手动携带事实
 （用户实测：不挂链 P=0.30，挂链后 0.92）。
+**快照回显（0.83）**：`node can <key> --eval` 的输出把本次吃到的 attachments 打回来——`--json` 的
+`eval_attachments[]` + 人类视图 `attachments ×N:` 逐条；P 值依据可复现，不必翻库。
 
 ## 5. 凭证与端点（优先级：config > 环境变量/文件 > 默认网关）
 

package/skills/ygl-trees-quickstart/SKILL.md

@@ -67,12 +67,16 @@ ygl-trees webui serve --help   # 只打印用法不启服务（0.79.1 短路）
 
 PG 迁移预检：`db migrate pg` 前自动逐表扫描 INTEGER 列类型——非整数值会**点名 table.column rowid=N** 而非迁移时才爆。
 
-## 2b2. 多会话安全（0.79）
+## 2b2. 多会话安全（0.79 → 0.83）
 
+- **0.83 并发钉住（最重要）**：并发会话共享 current 指针互踩——写命令直接钉住目标：`research * --project <p>`、`produce/task * --project <p>`、`node * --tree <t>`（`node import --tree` 是目标树名，非选择器）；写回执带 `· project <名>` 回显落点
 - `tree use` / `project use` 落 `tree.use` / `project.use` 事件（`YGL_SESSION` 会话标识）
 - `agent brief` 的 `selection_changed`：最近 10 分钟选择变更；跨会话变更置顶提示带 `-t`/`-p`
 - `kb add` 回执自检（`verified:true`）+ 工作区回显（防写错 home 的"丢笔记"事故）
 - `research claim link <cid> <sid> --by-source`：来源下全部证据一次挂齐；误传来源 id 会列出其证据 id
+- `research source add --query` 引用不存在 → 整体拒绝 rc=1 零落地（0.83 半写防护）
+- `--help` 任意深度打组帮助 rc=0（如 `kb add --help`）；job 子命令无锁启动（`ygl-trees …` 型任务命令不再与 runner 死锁）
+- 到期巡检范式：`job add "到期巡检" --every 1440 -- ygl-trees node cond --due --days 30`
 
 ## 2c. DB 锁行为（0.68 → 0.79.1）
 

package/skills/ygl-trees-research/SKILL.md

@@ -34,6 +34,7 @@ ygl-trees research source add --adjudication "会话内裁决：三条件已逐
 
 来源按 `(project, url_hash)` 去重；`--query` 顺带建立召回关联（query list 显示召回数）。
 `--url` 收任意 `<scheme>://`（https/file/session/a2a/…，0.81）——跨 Agent 引用免落盘。
+**并发钉住（0.83）**：全组接受 `--project <p>` 长旗标（与 `-p` 等价）——并发会话共享 current 指针互踩时直接钉住目标项目，回执带 `· project <名>` 回显落点；`--query` 引用不存在 → 整体拒绝 rc=1 零落地（半写防护）。
 
 ## 2. 摘录与断言
 
@@ -42,11 +43,13 @@ ygl-trees research evidence add <sourceId> --quote "原文片段" --locator "§2
 ygl-trees research evidence add <sourceId> --file quotes.md         # 长摘录免转义
 ygl-trees research claim add "断言文本" --confidence A               # 档位
 ygl-trees research claim add "断言文本" --confidence 0.92            # 数值档（0.81：0-1 或 0-100%）
-ygl-trees research claim link <claimId> <evidenceId> [--stance refutes]   # 状态自动推导
+ygl-trees research claim link <claimId> <evidenceId> [--stance refutes]   # 状态自动推导（普通断言）
 ygl-trees research claim resolve <claimId> --as contested --note "矛盾待查"  # 人工仲裁出口
+ygl-trees research claim unresolve <claimId>   # 复位回 unverified（0.82.1：撤销链接副作用/抢跑仲裁）
 ```
 
 - 有支持有反对 → `contested`；仲裁后新证据链接会重新推导
+- **预测断言（`[预测·…]` 前缀）挂证据不自动晋升**（0.82.1）：挂证据 ≠ 仲裁，状态保持 unverified 直到显式 resolve / 到期回测——predict audit 才不会把刚挂证据的预测误判已结案；误晋升用 `claim unresolve` 归位（幂等 duplicate:true）
 - 全部命令幂等：同内容重跑返回已存在行（`duplicate: true`，rc=0）
 
 ## 3. 产出
@@ -65,6 +68,7 @@ ygl-trees produce export <reportId> report.md
 - 先 `agent brief --json` 看 next_actions（它会告诉你缺来源/缺证据/缺断言）
 - 每条断言至少一条证据再进报告；contested 的要么补证据要么 resolve
 - 预测断言（`[预测·N天]`）定期 `research predict audit` 回测：本地判据自动测；`--state <file|url>`
-  桥接外部计数（裸键名后缀匹配 `counts.y_imported`）；已 resolve 的默认隐藏（`--all` 查看终态表）
+  桥接外部计数（裸键名后缀匹配 `counts.y_imported`）；已 resolve 的默认隐藏（`--all` 查看终态表，
+  `--json` 始终含全量行含终态——机器读全量、人看增量）
 - `--json` 输出可直接 parse 拿 id；列表命令字段：source(id,title,url,relevance,…)、
   claim(id,text,status,confidence,sup,ref)、evidence(id,source,locator,quote,used_by)

package/skills/ygl-trees-techtree/SKILL.md

@@ -54,6 +54,8 @@ ygl-trees node unlock mining && ygl-trees node lock mining
 - `--state-file` 两种形状：扁平 `{"y_imported":40}` 全节点共享；按节点 `{"a":{"y_imported":40}}` 各取各袋；多键 `--json` 返回数组（0.79.1）
 - `ready --all` / `cond --due` 前置于树解析：无当前树也能跑，跨树巡检一条命令（0.82）
 - `cond --due` 提取 eval 问题文本中的 `YYYY-MM-DD`；默认 7 天窗口（含逾期），`--eval` 判定后仍需人工 resolve/unlock——判定 ≠ 仲裁（0.82）
+- **`--tree <t>` 长旗标（0.83）**：node 组树选择别名（与 `-t` 等价）——并发会话互踩 current_tree 时钉住目标；例外：`node import --tree <name>` 是导入目标树名，不是选择器
+- **`can --eval` attachments 快照（0.83）**：`--json` 增 `eval_attachments[]`、人类视图 `attachments ×N:`——本次判定吃了哪些 rel 证据一目了然，P 值复现不必翻库
 
 ## 3. 迁移与保真