ygl-trees 0.82.1 → 0.83.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.83.1（2026-10-17）job 运行史持久化热修
+- **`jobFinish` 漏传 runId（UPDATE 静默 no-op）**：`UPDATE runs SET finished=?,rc=?,output=? WHERE id=?` 的参数数组只有 3 个值——缺失的占位符绑定为 NULL，WHERE id=NULL 匹配 0 行且不报错。后果：**runs 运行史从未落库**（rc/output/finished 恒空，job logs 看到的 rc 全部来自 reaper 兜底）；jobs 侧的 last_run/status 更新正常，掩盖了缺陷。在验证 0.83 到期巡检任务的落库输出时捕获。demo §7 增回归断言（job run 后 runs 表 rc=0 可读回）→ 114
+
+## 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 前被误晋升的预测可用它归队

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,7 +134,8 @@ 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> 免转义
@@ -296,7 +300,7 @@ ygl-trees agent ask "<question>"     natural language interface
 ## 五b、开发与运维工具
 
 ```bash
-pnpm test          # 四段制回归：unit (vitest 177 例) + build (tsc + tsdown) + demo（106 条断言）+ contract:audit（86 项）
+pnpm test          # 四段制回归：unit (vitest 177 例) + build (tsc + tsdown) + demo（114 条断言）+ 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;
 /**
@@ -251,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);
@@ -291,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
@@ -364,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) ──

package/dist/bundle/bin.cjs

@@ -3092,7 +3092,8 @@ var Store = class {
 		this.db.run("UPDATE runs SET finished=?, rc=?, output=? WHERE id=?", [
 			require_text.nowIso(),
 			rc,
-			output.slice(0, 8e3)
+			output.slice(0, 8e3),
+			runId
 		]);
 		this.db.run("UPDATE jobs SET runs=runs+1, last_run=?, status=? WHERE id=(SELECT job_id FROM runs WHERE id=?)", [
 			require_text.nowIso(),
@@ -5788,7 +5789,11 @@ function execute(env, job) {
 				"pipe",
 				"pipe"
 			],
-			timeout: 6e5
+			timeout: 6e5,
+			env: {
+				...process.env,
+				YGL_SERVE: "1"
+			}
 		});
 		rc = 0;
 	} catch (e) {
@@ -6631,7 +6636,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;
@@ -6770,12 +6775,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) => {
@@ -6948,7 +6966,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];
@@ -7044,7 +7062,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]) {
@@ -7425,7 +7443,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 },
@@ -7846,7 +7864,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;
@@ -7958,7 +7976,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) => {
@@ -8782,7 +8800,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;
@@ -9343,6 +9361,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 || "";
@@ -9426,6 +9446,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;
 				}
@@ -9717,10 +9744,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), [
@@ -12136,6 +12164,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 = {
@@ -12151,6 +12195,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)) {
@@ -12211,6 +12261,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();
@@ -12664,6 +12715,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]) {

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

@@ -297,7 +297,11 @@ class Store {
         return id;
     }
     jobFinish(runId, rc, output) {
-        this.db.run("UPDATE runs SET finished=?, rc=?, output=? WHERE id=?", [(0, text_1.nowIso)(), rc, output.slice(0, 8000)]);
+        // 0.83.1: the UPDATE params were missing runId (3 values for 4
+        // placeholders → WHERE id=NULL → silent no-op). Run history (rc/output/
+        // finished) never persisted — only the jobs-row side updated. Caught
+        // while verifying the 0.83 patrol job's captured output.
+        this.db.run("UPDATE runs SET finished=?, rc=?, output=? WHERE id=?", [(0, text_1.nowIso)(), rc, output.slice(0, 8000), runId]);
         this.db.run("UPDATE jobs SET runs=runs+1, last_run=?, status=? WHERE id=(SELECT job_id FROM runs WHERE id=?)", [
             (0, text_1.nowIso)(),
             rc === 0 ? "ok" : "failed",

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.1",
+  "version": "0.83.1",
   "description": "猿光 · 科技树 — database-centric CLI for research → production → knowledge reuse, built for AI agents.",
   "type": "commonjs",
   "main": "dist/apps/cli/index.js",
@@ -25,10 +25,10 @@
     "node-sqlite3-wasm": "^0.8.61",
     "reflect-metadata": "^0.2.2",
     "typeorm": "^1.1.2",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
     "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.2",
-    "@deepseek-ai/schemastery": "~3.18.5-alpha.2",
-    "@deepseek-ai/cosmokit": "~1.8.6-alpha.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"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -54,7 +54,8 @@
     ],
     "env": {
       "YGL_TEST": "1"
-    }
+    },
+    "hookTimeout": 30000
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && pnpm build:bundle:only && pnpm --filter @ygl/web build",
@@ -63,7 +64,7 @@
     "start": "node dist/bundle/bin.cjs",
     "demo": "bash examples/demo.sh",
     "test": "pnpm test:unit && pnpm build && bash examples/demo.sh && bash scripts/contract-audit.sh",
-    "test:unit": "vitest run",
+    "test:unit": "vitest run --hook-timeout=30000",
     "smoke:bun": "bash scripts/bun-smoke.sh",
     "bench": "pnpm build && node benchmarks/bench.js",
     "pack:check": "bash scripts/pack-check.sh",

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. 摘录与断言
 

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. 迁移与保真