ygl-trees 0.78.0 → 0.80.0

package/dist/bundle/bin.cjs

@@ -34,8 +34,23 @@ var db_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll({
 	EDGE_RELS: () => EDGE_RELS,
 	SCHEMA_SQL: () => SCHEMA_SQL,
 	SCHEMA_VERSION: () => 9,
-	dbPath: () => dbPath
+	dbPath: () => dbPath,
+	pidAlive: () => pidAlive
 });
+/** PID liveness probe (shared by lock acquisition, `db unlock`, and doctor).
+*  signal 0 = pure existence check (does NOT kill the process)
+*  EPERM    = exists but permission-denied (Windows ACL) — still alive
+*  ESRCH    = no such process — dead. NaN (garbage pid file) counts as dead. */
+function pidAlive(pidStr) {
+	const pid = Number(pidStr);
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		return e.code === "EPERM";
+	}
+}
 /** Resolve the active database file. */
 function dbPath(home) {
 	return node_path.join(home, "ygl-trees.db");
@@ -392,6 +407,9 @@ CREATE UNIQUE INDEX IF NOT EXISTS uq_skill_refs ON skill_refs(skill_id, path);
 	DB = class {
 		db;
 		path;
+		/** True when THIS instance acquired the .ygllock (0.79.1) — lock-less
+		*  instances (serve, db unlock) never release a foreign lock. */
+		ownsLock = false;
 		constructor(file, opts) {
 			this.path = file;
 			node_fs.mkdirSync(node_path.dirname(file), { recursive: true });
@@ -424,11 +442,23 @@ CREATE UNIQUE INDEX IF NOT EXISTS uq_skill_refs ON skill_refs(skill_id, path);
 						force: true
 					});
 				} catch {}
-				else throw new Error(`database is locked by another process (pid: ${holder}).\n  lock: ${lockDir}\n  if this is a webui serve dashboard, it shares WAL safely — CLI reads work,\n  write commands need the serve process stopped (or YGL_TEST=1 to bypass)\n  if no other ygl-trees is running, remove it:  rmdir "${lockDir}"`);
+				else {
+					let holderCmd = "";
+					try {
+						holderCmd = node_fs.readFileSync(node_path.join(lockDir, "cmd"), "utf8").trim();
+					} catch {}
+					throw new Error(`database is locked by another process (pid: ${holder}).\n` + (holderCmd ? `  holder command: ${holderCmd}\n` : `  the holder is almost certainly a parallel CLI session (serve never takes the write lock);\n`) + `  read commands still work. The lock self-heals once pid ${holder} exits —\n  simply retry after it finishes.\n  to clear manually:  ygl-trees db unlock   (checks pid liveness, refuses live holders)\n  last resort:         rmdir "${lockDir}"`);
+				}
 			}
+			let acquired = false;
 			if (useLock) try {
 				node_fs.mkdirSync(lockDir, { recursive: true });
 				node_fs.writeFileSync(node_path.join(lockDir, "pid"), String(process.pid));
+				acquired = true;
+				try {
+					const cmd = [process.argv0, ...process.argv.slice(1)].join(" ").slice(0, 240);
+					node_fs.writeFileSync(node_path.join(lockDir, "cmd"), cmd);
+				} catch {}
 				const cleanup = () => {
 					for (let i = 0; i < 3; i++) try {
 						node_fs.rmSync(lockDir, {
@@ -441,14 +471,19 @@ CREATE UNIQUE INDEX IF NOT EXISTS uq_skill_refs ON skill_refs(skill_id, path);
 				process.on("beforeExit", cleanup);
 				process.on("exit", cleanup);
 			} catch {}
+			this.ownsLock = acquired;
 			this.db = new node_sqlite3_wasm.Database(file);
 			this.db.exec("PRAGMA journal_mode=WAL");
 			this.db.exec("PRAGMA synchronous=NORMAL");
 			this.db.exec("PRAGMA foreign_keys=ON");
 			this.migrate();
 		}
-		/** Release the write lock (called by close() and process exit). */
+		/** Release the write lock (called by close() and process exit).
+		*  Ownership-guarded since 0.79.1: a lock-less instance (serve, db unlock)
+		*  shares the workspace with a foreign holder — its close() must not nuke
+		*  that holder's lock. */
 		releaseLock() {
+			if (!this.ownsLock) return;
 			try {
 				const lockDir = `${this.path}.ygllock`;
 				if (node_fs.existsSync(lockDir)) node_fs.rmSync(lockDir, {
@@ -467,6 +502,22 @@ CREATE UNIQUE INDEX IF NOT EXISTS uq_skill_refs ON skill_refs(skill_id, path);
 				});
 			} catch {}
 		}
+		/** Static: read the holder pid of a lock file ("" when absent/unreadable). */
+		static lockHolder(file) {
+			try {
+				return node_fs.readFileSync(node_path.join(`${file}.ygllock`, "pid"), "utf8").trim();
+			} catch {
+				return "";
+			}
+		}
+		/** Static: read the holder's self-reported command line ("" when absent). */
+		static lockHolderCmd(file) {
+			try {
+				return node_fs.readFileSync(node_path.join(`${file}.ygllock`, "cmd"), "utf8").trim();
+			} catch {
+				return "";
+			}
+		}
 		migrate() {
 			let row;
 			try {
@@ -1927,6 +1978,18 @@ var TreeStore = class {
 			keyOrId
 		]);
 	}
+	/** Which OTHER trees contain this key? (Report ③: a parallel session
+	*  flipped current_tree; `node can p_dates` then said just "node not
+	*  found" — the key existed the whole time, in another tree. This lookup
+	*  lets the error name the tree instead of forcing a blind node list.) */
+	nodeInOtherTrees(keyOrId, excludeTreeId) {
+		return this.db.all(`SELECT t.name AS tree, n.key FROM nodes n JOIN trees t ON t.id=n.tree_id
+        WHERE n.tree_id<>? AND (n.key=? OR n.id=?) LIMIT 5`, [
+			excludeTreeId,
+			keyOrId,
+			keyOrId
+		]);
+	}
 	/** Runtime state for one node (default context). Separate from nodeGet on
 	*  purpose: nodeGet feeds WRITE paths, and a context join there could return
 	*  one row per context — silently wrong for link/unlink/rm. */
@@ -2250,6 +2313,12 @@ var TreeStore = class {
 	* + unlocked set + the caller's state bag. The eval API demands a context
 	* package — bare state fell into the gray band 6/8 in the material's
 	* routing test, so we ship everything the tree knows about this node.
+	*
+	* 0.80: the rel fabric joins the package — evidence/claim/kb summaries
+	* attached to the node (either direction) land in `attachments`, so a
+	* decided-by chain is visible to the eval model without manually
+	* re-carrying facts via --state (user finding: P 0.30 → 0.92 gap).
+	* Bounded: ≤12 rows, text clipped to 120 chars.
 	*/
 	evalContext(treeId, keyOrId, stateBag, context = "default") {
 		const n = this.nodeGet(treeId, keyOrId);
@@ -2273,7 +2342,7 @@ var TreeStore = class {
 			effect: c.effect
 		}));
 		const unlocked = [...this.unlockedSet(treeId, context)].map((id) => idToKey.get(id) || id);
-		return {
+		const pkg = {
 			node: {
 				key: n.key,
 				name: n.name,
@@ -2287,6 +2356,62 @@ var TreeStore = class {
 			unlocked,
 			state: stateBag
 		};
+		const attachments = this.relAttachments(String(n.id));
+		if (attachments.length) pkg.attachments = attachments;
+		return pkg;
+	}
+	/** 0.80: rel-fabric summaries for the eval context package (both directions). */
+	relAttachments(nodeId) {
+		const rows = this.db.all(`SELECT rel, src_type, src_id, dst_type, dst_id FROM relations
+       WHERE (src_type='node' AND src_id=?) OR (dst_type='node' AND dst_id=?)
+       ORDER BY rowid LIMIT 12`, [nodeId, nodeId]);
+		const clip = (v, n = 120) => String(v ?? "").slice(0, n);
+		return rows.map((r) => {
+			const srcIsMe = r.src_type === "node" && r.src_id === nodeId;
+			const type = String(srcIsMe ? r.dst_type : r.src_type);
+			const id = String(srcIsMe ? r.dst_id : r.src_id);
+			const base = {
+				rel: String(r.rel),
+				type,
+				id
+			};
+			const q = (sql) => this.db.get(sql, [id]);
+			if (type === "claim") {
+				const c = q("SELECT text, status, confidence FROM claims WHERE id=?");
+				if (c) return {
+					...base,
+					text: clip(c.text),
+					status: c.status,
+					confidence: c.confidence
+				};
+			} else if (type === "evidence") {
+				const e = q("SELECT quote FROM evidence WHERE id=?");
+				if (e) return {
+					...base,
+					quote: clip(e.quote)
+				};
+			} else if (type === "kb") {
+				const k = q("SELECT title FROM kb_notes WHERE id=?");
+				if (k) return {
+					...base,
+					title: clip(k.title, 80)
+				};
+			} else if (type === "source") {
+				const s = q("SELECT title FROM sources WHERE id=?");
+				if (s) return {
+					...base,
+					title: clip(s.title, 80)
+				};
+			} else if (type === "node") {
+				const nd = q("SELECT key, name FROM nodes WHERE id=?");
+				if (nd) return {
+					...base,
+					key: nd.key,
+					name: clip(nd.name, 80)
+				};
+			}
+			return base;
+		});
 	}
 	/** Every node whose required gates are currently satisfied. */
 	ready(treeId, context = "default", state = {}) {
@@ -4684,6 +4809,77 @@ function run$12(env, action, rest, args) {
 			if (ctx.json) console.log(JSON.stringify({ path: file }, null, 2));
 			else out(ctx, file);
 			return 0;
+		case "unlock": {
+			const lockDir = `${file}.ygllock`;
+			let holder = "";
+			try {
+				holder = node_fs.readFileSync(`${lockDir}/pid`, "utf8").trim();
+			} catch {}
+			if (!node_fs.existsSync(lockDir)) {
+				if (ctx.json) console.log(JSON.stringify({
+					lock: lockDir,
+					holder: null,
+					cleared: false,
+					reason: "no lock present"
+				}, null, 2));
+				else ok(ctx, `no lock present: ${lockDir}`);
+				return 0;
+			}
+			if (holder && pidAlive(holder) && !args.flags.force) {
+				const self = Number(holder) === process.pid;
+				let holderCmd = "";
+				try {
+					holderCmd = node_fs.readFileSync(`${lockDir}/cmd`, "utf8").trim();
+				} catch {}
+				const msg = self ? `lock is held by THIS process (pid ${holder}) — acquired during boot; clearing.` : `lock held by LIVE process (pid: ${holder}${holderCmd ? ` — ${holderCmd}` : ""}) — refusing to clear.`;
+				if (self) try {
+					node_fs.rmSync(lockDir, {
+						recursive: true,
+						force: true
+					});
+					if (ctx.json) console.log(JSON.stringify({
+						lock: lockDir,
+						holder,
+						cleared: true,
+						reason: "self (acquired during boot)"
+					}, null, 2));
+					else ok(ctx, `lock cleared: ${lockDir}  (self — acquired during boot)`);
+					return 0;
+				} catch {}
+				if (ctx.json) console.log(JSON.stringify({
+					lock: lockDir,
+					holder,
+					holder_cmd: holderCmd || null,
+					cleared: false,
+					reason: "holder alive (use --force to override)"
+				}, null, 2));
+				else {
+					bad(ctx, msg);
+					out(ctx, paint(C.yellow, `  that is a parallel CLI session (serve never takes the write lock) — retry after it exits;`, ctx.color));
+					out(ctx, paint(C.yellow, `  the lock self-heals then. --force overrides (corruption risk if writes are in flight).`, ctx.color));
+				}
+				return 1;
+			}
+			try {
+				node_fs.rmSync(lockDir, {
+					recursive: true,
+					force: true
+				});
+				const why = !holder || !pidAlive(holder) ? `stale (pid ${holder || "?"} dead)` : "forced";
+				if (ctx.json) console.log(JSON.stringify({
+					lock: lockDir,
+					holder: holder || null,
+					cleared: true,
+					reason: why
+				}, null, 2));
+				else ok(ctx, `lock cleared: ${lockDir}  (${why})`);
+				return 0;
+			} catch (e) {
+				if (ctx.json) console.log(JSON.stringify({ error: `remove failed: ${e?.message || e}` }, null, 2));
+				else bad(ctx, `remove failed: ${e?.message || e}`);
+				return 1;
+			}
+		}
 		case "stats": {
 			const s = env.store.stats();
 			if (ctx.json) {
@@ -5635,6 +5831,34 @@ function buildBrief(env) {
 	};
 	let project = null;
 	if (cur) project = store.projectByName(cur);
+	try {
+		const recent = store.db.all(`SELECT kind, entity_id, ts, payload FROM events
+        WHERE kind IN ('tree.use','project.use')
+          AND ts >= datetime('now','-10 minutes')
+        ORDER BY ts DESC LIMIT 5`);
+		if (recent.length) {
+			payload.selection_changed = recent.map((r) => ({
+				kind: r.kind,
+				name: r.entity_id,
+				session: (() => {
+					try {
+						return JSON.parse(r.payload || "{}").session || null;
+					} catch {
+						return null;
+					}
+				})(),
+				ts: r.ts
+			}));
+			const others = recent.filter((r) => {
+				try {
+					return (JSON.parse(r.payload || "{}").session || "cli") !== (process.env.YGL_SESSION || "cli");
+				} catch {
+					return false;
+				}
+			});
+			if (others.length) payload.next_actions.unshift(`# 并行会话切换过选择: ${others.map((o) => `${o.kind === "tree.use" ? "tree" : "project"} '${o.entity_id}'`).join(", ")} — 命令请带 -t/-p 固定上下文`);
+		}
+	} catch {}
 	if (project) {
 		const claims = store.claimList(project.id);
 		const ev = store.evidenceList(project.id);
@@ -6146,6 +6370,7 @@ var init_eval_enhance = require_rolldown_runtime.__esmMin((() => {
 //#region packages/research/pipeline/src/predict.ts
 var predict_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll({
 	auditPredictions: () => auditPredictions,
+	loadStateSource: () => loadStateSource,
 	measureCriterion: () => measureCriterion,
 	measureNpmVersions: () => measureNpmVersions,
 	parsePrediction: () => parsePrediction
@@ -6173,23 +6398,74 @@ function parsePrediction(text, created) {
 		deadline: ""
 	};
 }
-/** Locally measurable criterion matchers. Null → manual. */
-function measureCriterion(crit, db) {
-	const tree = crit.match(/树\s*≥\s*(\d+)/);
-	const kb = crit.match(/kb\s*≥\s*(\d+)/);
-	if (!tree && !kb) return null;
+/** 0.79.1 --state bridge: load a flat counter map from a JSON file path or an
+*  http(s) URL (e.g. a DSH API endpoint). Nested objects flatten to dot keys
+*  ({counts:{y:12}} → "counts.y"); only finite numbers are kept. Null on any
+*  failure — the audit degrades those criteria back to manual. */
+async function loadStateSource(src, fetchImpl = fetch) {
+	try {
+		let text;
+		if (/^https?:\/\//.test(src)) {
+			const ctl = new AbortController();
+			const t = setTimeout(() => ctl.abort(), 3e3);
+			const r = await fetchImpl(src, { signal: ctl.signal });
+			clearTimeout(t);
+			if (!r.ok) return null;
+			text = await r.text();
+		} else text = require("node:fs").readFileSync(src, "utf8");
+		const flat = {};
+		const walk = (obj, prefix) => {
+			if (!obj || typeof obj !== "object") return;
+			for (const [k, v] of Object.entries(obj)) {
+				const key = prefix ? `${prefix}.${k}` : k;
+				if (typeof v === "number" && Number.isFinite(v)) flat[key] = v;
+				else if (v && typeof v === "object" && !Array.isArray(v)) walk(v, key);
+			}
+		};
+		walk(JSON.parse(text), "");
+		return flat;
+	} catch {
+		return null;
+	}
+}
+/** Locally measurable criterion matchers. Null → manual.
+*  Precedence: 树/kb workspace counts (local truth) → any `key≥N` whose key
+*  exists in the optional --state counter map (external truth, 0.79.1). */
+function measureCriterion(crit, db, state) {
 	const parts = [];
 	const hits = [];
+	const tree = crit.match(/树\s*≥\s*(\d+)/);
 	if (tree) {
 		const n = db.get("SELECT COUNT(*) c FROM trees").c;
 		parts.push(`trees=${n}/${tree[1]}`);
 		hits.push(n >= +tree[1]);
 	}
+	const kb = crit.match(/kb\s*≥\s*(\d+)/);
 	if (kb) {
 		const n = db.get("SELECT COUNT(*) c FROM kb_notes").c;
 		parts.push(`kb=${n}/${kb[1]}`);
 		hits.push(n >= +kb[1]);
 	}
+	if (state) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const m of crit.matchAll(/([\w\u4e00-\u9fa5][\w\u4e00-\u9fa5.-]*)\s*≥\s*(\d+)/g)) {
+			const key = m[1], need = +m[2];
+			if (key === "树" || key === "kb" || seen.has(key)) continue;
+			let stateKey = key in state ? key : null;
+			if (!stateKey) {
+				const cands = Object.keys(state).filter((sk) => sk.endsWith("." + key) && Number.isFinite(state[sk]));
+				if (cands.length) {
+					cands.sort((a, b) => a.split(".").length - b.split(".").length || a.localeCompare(b));
+					stateKey = cands[0];
+				}
+			}
+			if (!stateKey || !Number.isFinite(state[stateKey])) continue;
+			seen.add(key);
+			parts.push(`${key}=${state[stateKey]}/${need}${stateKey !== key ? ` (${stateKey})` : ""}`);
+			hits.push(state[stateKey] >= need);
+		}
+	}
+	if (!parts.length) return null;
 	const hit = crit.includes(" 或 ") ? hits.some(Boolean) : hits.every(Boolean);
 	return {
 		actual: parts.join(" · "),
@@ -6224,7 +6500,8 @@ async function auditPredictions(inp) {
 		const m = c.text.match(/\d{4}-\d{2}-\d{2}\s*前\s*(.+?)(?:——|$)/) || c.text.match(/\]\s*(.+?)(?:——|$)/);
 		const criterion = m ? m[1].trim() : "";
 		const daysLeft = deadline ? Math.round((Date.parse(deadline) - Date.parse(today)) / 864e5) : null;
-		let measure = measureCriterion(criterion, inp.db);
+		const resolved = c.status === "supported" || c.status === "refuted";
+		let measure = measureCriterion(criterion, inp.db, inp.state);
 		if (!measure && /npm 再发\s*≥\s*(\d+)\s*个版本/.test(criterion)) {
 			const need = +criterion.match(/npm 再发\s*≥\s*(\d+)/)[1];
 			const base = c.text.match(/基线\s*\S*?@?(\d{4}-\d{2}-\d{2})/);
@@ -6242,7 +6519,10 @@ async function auditPredictions(inp) {
 		}
 		let verdict;
 		let hint;
-		if (!measure) {
+		if (resolved) {
+			verdict = "resolved";
+			hint = `已人工仲裁：${c.status}（回测终态，不再复判）`;
+		} else if (!measure) {
 			verdict = "manual";
 			hint = "外部世界判据——人工核验后 claim resolve";
 		} else if (daysLeft !== null && daysLeft > 0) verdict = "pending";
@@ -6252,7 +6532,7 @@ async function auditPredictions(inp) {
 			horizon,
 			deadline,
 			criterion,
-			actual: measure ? measure.actual + (verdict === "pending" && measure.hit ? " · 已达标" : "") : "—",
+			actual: measure ? measure.actual + (!resolved && verdict === "pending" && measure.hit ? " · 已达标" : "") : "—",
 			verdict,
 			days_left: daysLeft,
 			hint
@@ -6274,6 +6554,10 @@ init_writes();
 init_entities$1();
 /** Run a write through the TypeORM transactional write service and print
 *  with JSON discipline. Keeps every write command 6 lines. */
+/** 0.80: compact timestamp for session:// adjudication urls (yyyymmddhhmm). */
+function nowCompact() {
+	return (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/g, "").slice(0, 12);
+}
 function runWrite(env, fn, human) {
 	const { ctx } = env;
 	return getOrm(env.db.path).then(fn).then((r) => {
@@ -6398,14 +6682,24 @@ function run$8(env, action, rest, args) {
 				bad(ctx, "flag needs a value: --title \"...\" / --url \"...\"  (bare flag was treated as boolean)");
 				return 2;
 			}
-			const title = String(titleRaw || "");
-			const url = String(urlRaw || "");
+			let title = String(titleRaw || "");
+			let url = String(urlRaw || "");
+			const adjRaw = args.flags.adjudication;
+			if (adjRaw === true) {
+				bad(ctx, "flag needs a value: --adjudication \"<裁决摘要>\"");
+				return 2;
+			}
+			if (adjRaw !== void 0 && adjRaw !== "") {
+				const adj = String(adjRaw);
+				if (!url) url = `session://adjudication/${nowCompact()}`;
+				if (!title) title = adj.slice(0, 60);
+			}
 			if (!title && !url) {
 				bad(ctx, "need --title and/or --url");
 				return 2;
 			}
-			if (url && !/^https?:\/\/|^file:\/\//.test(url)) {
-				bad(ctx, `--url must be http(s):// or file:// (got: "${require_text.clip(url, 30)}")`);
+			if (url && !/^https?:\/\/|^file:\/\/|^session:\/\//.test(url)) {
+				bad(ctx, `--url must be http(s)://, file:// or session:// (got: "${require_text.clip(url, 30)}")`);
 				return 2;
 			}
 			const spec = {
@@ -6572,9 +6866,27 @@ function run$8(env, action, rest, args) {
 	if (sub === "evidence") {
 		if (subAction === "add") {
 			const sourceId = rest[1];
-			const quote = String(args.flags.quote || readBody());
+			const file = String(args.flags.file || "");
+			let quote = String(args.flags.quote || "");
+			if (file) {
+				if (quote) {
+					bad(ctx, "--file and --quote are mutually exclusive");
+					return 2;
+				}
+				try {
+					quote = require("fs").readFileSync(file, "utf8").trim();
+				} catch (e) {
+					bad(ctx, `cannot read --file: ${e?.message || e}`);
+					return 1;
+				}
+				if (!quote) {
+					bad(ctx, `--file is empty: ${file}`);
+					return 2;
+				}
+			}
+			if (!quote) quote = readBody();
 			if (!sourceId || !quote) {
-				bad(ctx, "usage: research evidence add <sourceId> --quote \"...\"");
+				bad(ctx, "usage: research evidence add <sourceId> --quote \"...\" | --file <path> [--note ..] [--locator ..]");
 				return 2;
 			}
 			const note = String(args.flags.note || "");
@@ -6674,7 +6986,7 @@ function run$8(env, action, rest, args) {
 		}
 		if (subAction === "link") {
 			if (!rest[1] || !rest[2]) {
-				bad(ctx, "usage: research claim link <claimId> <evidenceId> [--stance refutes]");
+				bad(ctx, "usage: research claim link <claimId> <evidenceId> [--stance refutes] [--by-source]");
 				return 2;
 			}
 			const stanceRaw = String(args.flags.stance || "supports");
@@ -6683,6 +6995,34 @@ function run$8(env, action, rest, args) {
 				return 2;
 			}
 			const stance = stanceRaw;
+			if (args.flags["by-source"]) {
+				const evs = store.db.all("SELECT id FROM evidence WHERE source_id=? AND project_id=? ORDER BY created", [rest[2], project.id]);
+				if (!evs.length) {
+					bad(ctx, store.db.get("SELECT id FROM sources WHERE id=? AND project_id=?", [rest[2], project.id]) ? `source ${rest[2]} has no evidence yet — research evidence add ${rest[2]} --quote ".." first` : `source not found: ${rest[2]}`);
+					return 1;
+				}
+				return getOrm(env.db.path).then(async (ds) => {
+					const existing = new Set(store.db.all("SELECT evidence_id FROM claim_evidence WHERE claim_id=?", [rest[1]]).map((x) => x.evidence_id));
+					let linked = 0, dups = 0, status = "";
+					for (const ev of evs) {
+						const r = await claimLink(ds, rest[1], ev.id, stance);
+						existing.has(ev.id) ? dups++ : linked++;
+						status = r.status;
+					}
+					if (ctx.json) console.log(JSON.stringify({
+						claim: rest[1],
+						source: rest[2],
+						linked,
+						duplicates: dups,
+						status
+					}, null, 2));
+					else ok(ctx, `linked ${linked} evidence from source ${rest[2]} (${dups} already) — claim status: ${status}`);
+					return 0;
+				}).catch((e) => {
+					bad(ctx, e?.message || String(e));
+					return 1;
+				});
+			}
 			return getOrm(env.db.path).then((ds) => claimLink(ds, rest[1], rest[2], stance)).then((r) => {
 				ok(ctx, `linked; claim status now: ${r.status}`);
 				try {
@@ -6717,6 +7057,18 @@ function run$8(env, action, rest, args) {
 				} catch {}
 				return 0;
 			}).catch((e) => {
+				const m = /^evidence not found: (.+)$/.exec(e?.message || "");
+				if (m) {
+					const evs = store.db.all("SELECT id FROM evidence WHERE source_id=? AND project_id=? ORDER BY created LIMIT 8", [m[1], project.id]);
+					if (evs.length) {
+						bad(ctx, `${e.message} — that id is a SOURCE; its evidence: ${evs.map((x) => x.id).join(" ")} (or rerun with --by-source to link them all)`);
+						return 1;
+					}
+					if (store.db.get("SELECT id FROM sources WHERE id=? AND project_id=?", [m[1], project.id])) {
+						bad(ctx, `${e.message} — that id is a SOURCE with no evidence yet: research evidence add ${m[1]} --quote ".." first`);
+						return 1;
+					}
+				}
 				bad(ctx, e?.message || String(e));
 				return 1;
 			});
@@ -6846,17 +7198,26 @@ function run$8(env, action, rest, args) {
 				else out(ctx, paint(C.dim, "  no [预测·…] claims in this project", ctx.color));
 				return 0;
 			}
-			const { auditPredictions } = require_rolldown_runtime.__toCommonJS(predict_exports);
+			const { auditPredictions, loadStateSource } = require_rolldown_runtime.__toCommonJS(predict_exports);
 			return (async () => {
+				let state = null;
+				if (args.flags.state) {
+					state = await loadStateSource(String(args.flags.state));
+					if (!state && !ctx.json) out(ctx, paint(C.yellow, `  ⚠ --state ${args.flags.state} 加载失败（文件/URL 不可读或非 JSON）——相关判据回落 manual`, ctx.color));
+				}
 				const rows = await auditPredictions({
 					claims,
 					db: store.db,
-					npmProbe: args.flags.offline !== true
+					npmProbe: args.flags.offline !== true,
+					state
 				});
+				const resolvedN = rows.filter((r) => r.verdict === "resolved").length;
+				const visible = args.flags.all ? rows : rows.filter((r) => r.verdict !== "resolved");
 				if (ctx.json) console.log(JSON.stringify(rows, null, 2));
+				else if (!visible.length) out(ctx, paint(C.dim, `  全部 ${rows.length} 条预测已结案（resolved）——--all 查看终态表`, ctx.color));
 				else {
-					head(ctx, `prediction audit — ${project.name} (${rows.length} predictions)`);
-					table(ctx, rows, [
+					head(ctx, `prediction audit — ${project.name} (${visible.length}/${rows.length}${resolvedN && !args.flags.all ? ` · ${resolvedN} resolved 隐藏 (--all)` : ""})`);
+					table(ctx, visible, [
 						"claim",
 						"horizon",
 						"deadline",
@@ -6873,14 +7234,14 @@ function run$8(env, action, rest, args) {
 						"verdict",
 						"days_left"
 					]);
-					const actionable = rows.filter((r) => r.verdict === "hit" || r.verdict === "miss");
+					const actionable = visible.filter((r) => r.verdict === "hit" || r.verdict === "miss");
 					for (const r of actionable) out(ctx, paint(C.dim, `  → research claim resolve ${r.claim_id} --as ${r.verdict === "hit" ? "supported" : "refuted"}   # ${r.deadline} 已到`, ctx.color));
-					for (const r of rows.filter((x) => x.verdict === "manual")) out(ctx, paint(C.dim, `  · ${r.claim_id}: ${r.hint}`, ctx.color));
+					for (const r of visible.filter((x) => x.verdict === "manual")) out(ctx, paint(C.dim, `  · ${r.claim_id}: ${r.hint}`, ctx.color));
 				}
 				return 0;
 			})();
 		}
-		bad(ctx, "usage: research predict audit [--offline]");
+		bad(ctx, "usage: research predict audit [--offline] [--state <file|url>] [--all]");
 		return 2;
 	}
 	out(ctx, paint(C.dim, "  research: query add|list · source add|list|search|show|rm · evidence add|list · claim add|link|list · predict audit", ctx.color));
@@ -6896,6 +7257,25 @@ init_entities$1();
 function run$7(env, action, rest, args) {
 	const { ctx, store } = env;
 	const name = rest[0];
+	/** Report ③-3: selection changes are events (session-tagged) — see the
+	*  twin helper in techtree/model/src/cmds.ts for the rationale. */
+	function logSelectionEvent(kind, projName) {
+		try {
+			store.db.run("INSERT INTO events(id,ts,actor,kind,entity,entity_id,payload,level) VALUES(?,?,?,?,?,?,?,?)", [
+				`ev${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+				(/* @__PURE__ */ new Date()).toISOString(),
+				process.env.YGL_SESSION || "cli",
+				kind,
+				"project",
+				projName,
+				JSON.stringify({
+					name: projName,
+					session: process.env.YGL_SESSION || "cli"
+				}),
+				"info"
+			]);
+		} catch {}
+	}
 	switch (action) {
 		case "new": {
 			if (!name) {
@@ -6903,8 +7283,11 @@ function run$7(env, action, rest, args) {
 				return 2;
 			}
 			const question = String(args.flags.q || args.flags.question || "");
+			const prior = store.db.metaGet("current_project");
+			const priorHint = prior && prior !== name ? `  (prior project '${prior}' is no longer selected — project use ${prior} to switch back)` : "";
 			return getOrm(env.db.path).then((ds) => projectCreate(ds, name, question)).then((p) => {
-				ack(ctx, p, p?.duplicate === true ? `project exists, selected: ${p.name}  (duplicate, not re-created)` : `project created and selected: ${p.name}`);
+				logSelectionEvent("project.use", p.name);
+				ack(ctx, p, p?.duplicate === true ? `project exists, selected: ${p.name}  (duplicate, not re-created)${priorHint}` : `project created and selected: ${p.name}${priorHint}`);
 				return 0;
 			}).catch((e) => {
 				bad(ctx, e?.message || String(e));
@@ -6944,6 +7327,7 @@ function run$7(env, action, rest, args) {
 				return 1;
 			}
 			store.db.metaSet("current_project", name);
+			logSelectionEvent("project.use", name);
 			ack(ctx, { project: name }, `now using: ${name}`);
 			return 0;
 		case "show": {
@@ -7109,6 +7493,10 @@ function run$6(env, action, rest, args) {
 		case "spec": {
 			const title = rest[0] || String(args.flags.title || "");
 			const body = readBody();
+			if (args.flags["design-type"] !== void 0) {
+				bad(ctx, "--design-type belongs to 'produce design' (spec does not take it; if this is a design decision, use: produce design <title> --design-type decision)");
+				return 2;
+			}
 			if (!title || !body) {
 				bad(ctx, "usage: produce spec <title> --body|-f <file>");
 				return 2;
@@ -7946,10 +8334,41 @@ function run$5(env, action, rest, args) {
 	/** tree-domain write through the transactional service (async command). */
 	function runTreeWrite(fn, print) {
 		return getOrm(env.db.path).then(fn).then(print).catch((e) => {
-			bad(ctx, e?.message || String(e));
+			bad(ctx, enrichNodeNotFound(e?.message || String(e)));
 			return 1;
 		});
 	}
+	/** Report ③-3: selection changes are now first-class events — a parallel
+	*  session flipping current_tree/current_project becomes observable
+	*  (agent brief surfaces it; db timeline shows the history). Session
+	*  identity comes from YGL_SESSION (agents that care can set it). */
+	function logSelectionEvent(database, kind, name) {
+		try {
+			database.run("INSERT INTO events(id,ts,actor,kind,entity,entity_id,payload,level) VALUES(?,?,?,?,?,?,?,?)", [
+				`ev${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+				(/* @__PURE__ */ new Date()).toISOString(),
+				process.env.YGL_SESSION || "cli",
+				kind,
+				kind === "tree.use" ? "tree" : "project",
+				name,
+				JSON.stringify({
+					name,
+					session: process.env.YGL_SESSION || "cli"
+				}),
+				"info"
+			]);
+		} catch {}
+	}
+	/** Report ③ enrichment: "node not found: X" earned a cross-tree lookup —
+	*  if a parallel session flipped current_tree, the key usually exists in
+	*  another tree; name it instead of making the user blind-list. */
+	function enrichNodeNotFound(msg) {
+		const m = /^node not found: (.+)$/.exec(msg);
+		if (!m) return msg;
+		const others = trees.nodeInOtherTrees(m[1], tid);
+		if (others.length) return `${msg}\n  key exists in other tree(s): ${others.map((o) => `'${o.tree}'`).join(", ")} — pin it: ygl-trees ${env.group} ... -t ${others[0].tree}`;
+		return `${msg}  (current tree: '${tree?.name ?? "?"}' — node list to inspect, -t <tree> to switch)`;
+	}
 	if (env.group === "tree") {
 		const sub = action;
 		const name = rest[0];
@@ -7962,6 +8381,7 @@ function run$5(env, action, rest, args) {
 			const proj = pid ? db.get("SELECT id FROM projects WHERE name=?", [pid]) : null;
 			return runTreeWrite((ds) => treeCreate(ds, name, proj?.id || ""), (t) => {
 				db.metaSet("current_tree", t.name);
+				logSelectionEvent(db, "tree.use", t.name);
 				ack(ctx, t, t?.duplicate === true ? `tree exists, selected: ${t.name}  (duplicate, not re-created)` : `tree created and selected: ${t.name}`);
 				return 0;
 			});
@@ -7990,6 +8410,7 @@ function run$5(env, action, rest, args) {
 				return 1;
 			}
 			db.metaSet("current_tree", name);
+			logSelectionEvent(db, "tree.use", name);
 			ack(ctx, { tree: name }, `now using tree: ${name}`);
 			return 0;
 		}
@@ -8198,43 +8619,43 @@ function run$5(env, action, rest, args) {
 		});
 		if (sub === "can") {
 			if (!key) {
-				bad(ctx, "usage: node can <key> [--context ctx] [--state k=v] [--eval]");
+				bad(ctx, "usage: node can <key...> [--context ctx] [--state k=v] [--state-file file] [--eval]");
 				return 2;
 			}
-			const state = parseState(args);
-			const ctxName = flagStr("context", "default");
-			const r = trees.canUnlock(tid, key, ctxName, state);
-			const evalConds = flagBool("eval") ? trees.condList(tid, key).filter((c) => /^eval(-choice|-score)?$/.test(String(c.op))) : [];
-			if (!evalConds.length) {
-				if (ctx.json) {
-					console.log(JSON.stringify(r, null, 2));
-					return 0;
-				}
-				head(ctx, `can unlock: ${r.key}`);
-				out(ctx, `  ${r.ok ? paint(C.green, "✓ 可解锁", ctx.color) : paint(C.red, "✗ 不可解锁", ctx.color)}`);
-				if (r.missing_required.length) {
-					out(ctx, paint(C.bold, "  必检未满足", ctx.color));
-					for (const m of r.missing_required) out(ctx, `    - ${m}`);
-				}
-				if (r.blocked_by.length) {
-					out(ctx, paint(C.bold, "  被排斥", ctx.color));
-					for (const b of r.blocked_by) out(ctx, `    - ${b}`);
-				}
-				if (r.missing_optional.length) {
-					out(ctx, paint(C.dim, "  可选未满足（不阻塞）", ctx.color));
-					for (const m of r.missing_optional) out(ctx, `    - ${m}`);
-				}
-				if (r.cost_multiplier !== 1) out(ctx, `  成本系数 ${r.cost_multiplier}`);
-				return 0;
+			const keys = [...new Set(rest.filter(Boolean))];
+			const sharedState = parseState(args);
+			let perKeyBags = null;
+			try {
+				perKeyBags = loadStateFile(args, sharedState);
+			} catch (e) {
+				const msg = e?.message || String(e);
+				bad(ctx, msg);
+				return /^usage:/.test(msg) ? 2 : /must contain a JSON object/.test(msg) ? 2 : 1;
 			}
+			const stateFor = (k) => perKeyBags ? perKeyBags[k] && typeof perKeyBags[k] === "object" && !Array.isArray(perKeyBags[k]) ? perKeyBags[k] : {} : sharedState;
+			const ctxName = flagStr("context", "default");
 			const offline = !!process.env.YGL_EVAL_OFFLINE || configGetBool(env.db, "eval.offline");
 			const cfgToken = configGet(env.db, "decision_model_llm_token").trim();
 			const token = offline ? "" : cfgToken || evalToken();
 			const endpoint = configGet(env.db, "decision_model_llm_api_base").trim() || "https://ai-gateway.vercel.sh/v4/ai/evaluation-model";
 			const passT = configGetNumber(env.db, "eval.pass_threshold");
 			const failT = configGetNumber(env.db, "eval.fail_threshold");
-			const contextPkg = trees.evalContext(tid, key, state, ctxName);
-			return (async () => {
+			/** Judge one node: canUnlock (+ eval gates when --eval). Never throws —
+			*  hard failures come back as {key, error}. */
+			const judgeOne = async (k) => {
+				let r;
+				try {
+					r = trees.canUnlock(tid, k, ctxName, stateFor(k));
+				} catch (e) {
+					return {
+						key: k,
+						error: enrichNodeNotFound(e?.message || String(e))
+					};
+				}
+				const state = stateFor(k);
+				const evalConds = flagBool("eval") ? trees.condList(tid, k).filter((c) => /^eval(-choice|-score)?$/.test(String(c.op))) : [];
+				if (!evalConds.length) return r;
+				const contextPkg = trees.evalContext(tid, k, state, ctxName);
 				const evaluated = [];
 				let usageIn = 0, usageOut = 0;
 				for (const c of evalConds) {
@@ -8295,13 +8716,13 @@ function run$5(env, action, rest, args) {
 						require_text.shortId([
 							"eval.gate",
 							"node",
-							key
+							k
 						], 12),
 						require_text.nowIso(),
 						"cli",
 						"eval.gate",
 						"node",
-						key,
+						k,
 						JSON.stringify({
 							conds: evaluated.map((e) => ({
 								name: e.name,
@@ -8318,31 +8739,74 @@ function run$5(env, action, rest, args) {
 						})
 					]);
 				} catch {}
+				return r;
+			};
+			const batch = keys.length > 1;
+			return (async () => {
+				const results = [];
+				for (const k of keys) results.push(await judgeOne(k));
 				if (ctx.json) {
-					console.log(JSON.stringify(r, null, 2));
-					return 0;
+					console.log(JSON.stringify(batch ? results : results[0], null, 2));
+					return results.some((r) => r.error) ? 1 : 0;
 				}
-				head(ctx, `can unlock: ${r.key}`);
-				out(ctx, `  ${r.ok ? paint(C.green, "✓ 可解锁", ctx.color) : pendingList.length ? paint(C.yellow, "… 待判定（决策模型 pending）", ctx.color) : paint(C.red, "✗ 不可解锁", ctx.color)}`);
-				if (r.missing_required.length) {
-					out(ctx, paint(C.bold, "  必检未满足", ctx.color));
-					for (const m of r.missing_required) out(ctx, `    - ${m}`);
-				}
-				if (pendingList.length) {
-					out(ctx, paint(C.bold, "  决策模型 pending（灰带/未配置，非终态）", ctx.color));
-					for (const p of pendingList) out(ctx, `    - ${p}`);
-				}
-				if (r.blocked_by.length) {
-					out(ctx, paint(C.bold, "  被排斥", ctx.color));
-					for (const b of r.blocked_by) out(ctx, `    - ${b}`);
+				if (!batch) {
+					const r = results[0];
+					if (r.error) {
+						bad(ctx, r.error);
+						return 1;
+					}
+					if (!r.evaluated) {
+						head(ctx, `can unlock: ${r.key}`);
+						out(ctx, `  ${r.ok ? paint(C.green, "✓ 可解锁", ctx.color) : paint(C.red, "✗ 不可解锁", ctx.color)}`);
+						if (r.missing_required.length) {
+							out(ctx, paint(C.bold, "  必检未满足", ctx.color));
+							for (const m of r.missing_required) out(ctx, `    - ${m}`);
+						}
+						if (r.blocked_by.length) {
+							out(ctx, paint(C.bold, "  被排斥", ctx.color));
+							for (const b of r.blocked_by) out(ctx, `    - ${b}`);
+						}
+						if (r.missing_optional.length) {
+							out(ctx, paint(C.dim, "  可选未满足（不阻塞）", ctx.color));
+							for (const m of r.missing_optional) out(ctx, `    - ${m}`);
+						}
+						if (r.cost_multiplier !== 1) out(ctx, `  成本系数 ${r.cost_multiplier}`);
+						return 0;
+					}
+					head(ctx, `can unlock: ${r.key}`);
+					out(ctx, `  ${r.ok ? paint(C.green, "✓ 可解锁", ctx.color) : r.pending.length ? paint(C.yellow, "… 待判定（决策模型 pending）", ctx.color) : paint(C.red, "✗ 不可解锁", ctx.color)}`);
+					if (r.missing_required.length) {
+						out(ctx, paint(C.bold, "  必检未满足", ctx.color));
+						for (const m of r.missing_required) out(ctx, `    - ${m}`);
+					}
+					if (r.pending.length) {
+						out(ctx, paint(C.bold, "  决策模型 pending（灰带/未配置，非终态）", ctx.color));
+						for (const p of r.pending) out(ctx, `    - ${p}`);
+					}
+					if (r.blocked_by.length) {
+						out(ctx, paint(C.bold, "  被排斥", ctx.color));
+						for (const b of r.blocked_by) out(ctx, `    - ${b}`);
+					}
+					if (r.missing_optional.length) {
+						out(ctx, paint(C.dim, "  可选未满足（不阻塞）", ctx.color));
+						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 (r.cost_multiplier !== 1) out(ctx, `  成本系数 ${r.cost_multiplier}`);
+					return 0;
 				}
-				if (r.missing_optional.length) {
-					out(ctx, paint(C.dim, "  可选未满足（不阻塞）", ctx.color));
-					for (const m of r.missing_optional) out(ctx, `    - ${m}`);
+				const via = perKeyBags ? "per-node --state-file" : Object.keys(sharedState).length ? "shared state" : "";
+				head(ctx, `can unlock × ${results.length}${via ? ` (${via})` : ""}`);
+				for (const r of results) {
+					if (r.error) {
+						out(ctx, `  ${paint(C.red, "✗", ctx.color)} ${r.key}  ${r.error}`);
+						continue;
+					}
+					const mark = r.ok ? paint(C.green, "✓", ctx.color) : r.pending?.length ? paint(C.yellow, "…", ctx.color) : paint(C.red, "✗", ctx.color);
+					const blockers = [...(r.missing_required || []).map((m) => m), ...(r.blocked_by || []).map((b) => `excluded:${b}`)].join(", ");
+					out(ctx, `  ${mark} ${r.key}${r.pending?.length ? " (eval pending)" : ""}${blockers ? `  — ${blockers}` : ""}`);
 				}
-				for (const e of evaluated) out(ctx, paint(C.dim, `  eval ${e.name}: P=${e.p ?? "-"} → ${e.outcome}${e.reason ? ` (${e.reason})` : ""}`, ctx.color));
-				if (r.cost_multiplier !== 1) out(ctx, `  成本系数 ${r.cost_multiplier}`);
-				return 0;
+				return results.some((r) => r.error) ? 1 : 0;
 			})().catch((e) => {
 				bad(ctx, e?.message || String(e));
 				return 1;
@@ -8350,6 +8814,16 @@ function run$5(env, action, rest, args) {
 		}
 		if (sub === "ready") {
 			const state = parseState(args);
+			try {
+				if (loadStateFile(args, state)) {
+					bad(ctx, "--state-file per-node shape (key→object) only applies to batch `node can k1 k2 …`; ready wants a flat counter object");
+					return 2;
+				}
+			} catch (e) {
+				const msg = e?.message || String(e);
+				bad(ctx, msg);
+				return /^usage:/.test(msg) || /must contain a JSON object/.test(msg) ? 2 : 1;
+			}
 			const ctxName = flagStr("context", "default");
 			if (!flagBool("eval")) {
 				const rows = trees.ready(tid, ctxName, state);
@@ -8530,7 +9004,13 @@ function run$5(env, action, rest, args) {
 				bad(ctx, "usage: node path <key>");
 				return 2;
 			}
-			const p = trees.pathTo(tid, key, flagStr("context", "default"));
+			let p;
+			try {
+				p = trees.pathTo(tid, key, flagStr("context", "default"));
+			} catch (e) {
+				bad(ctx, enrichNodeNotFound(e?.message || String(e)));
+				return 1;
+			}
 			if (ctx.json) {
 				console.log(JSON.stringify(p, null, 2));
 				return 0;
@@ -8640,7 +9120,7 @@ function run$5(env, action, rest, args) {
 		if (sub === "show") {
 			const n = trees.nodeGet(tid, key);
 			if (!n) {
-				bad(ctx, `node not found: ${key}`);
+				bad(ctx, enrichNodeNotFound(`node not found: ${key}`));
 				return 1;
 			}
 			const st = trees.nodeStateOf(tid, key);
@@ -8747,10 +9227,36 @@ function run$5(env, action, rest, args) {
 					conditions: r.conditions
 				}, `imported tree ${r.tree.name}: ${r.nodes} nodes, ${r.edges} edges, ${r.conditions} conditions`);
 				db.metaSet("current_tree", r.tree.name);
+				logSelectionEvent(db, "tree.use", r.tree.name);
 				if (!ctx.json) out(ctx, paint(C.dim, `  index rebuilt; now using tree: ${r.tree.name}`, ctx.color));
 				return 0;
 			});
 		}
+		if (sub === "timeline") {
+			const rows = db.all(`SELECT e.ts, e.kind, e.payload FROM events e
+          WHERE e.entity = 'node'
+            AND e.entity_id IN (SELECT id FROM nodes WHERE tree_id = ?)
+          ORDER BY e.ts DESC LIMIT 30`, [tid]);
+			if (ctx.json) {
+				console.log(JSON.stringify(rows.map((r) => ({
+					ts: r.ts,
+					kind: r.kind,
+					...JSON.parse(r.payload || "{}")
+				})), null, 2));
+				return 0;
+			}
+			head(ctx, `Timeline — tree '${tree.name}' (last ${rows.length})`);
+			for (const r of rows) {
+				let detail = "";
+				try {
+					const p = JSON.parse(r.payload || "{}");
+					detail = [p.key, p.name ? String(p.name).slice(0, 30) : ""].filter(Boolean).join("  ");
+				} catch {}
+				out(ctx, `  ${String(r.ts).slice(0, 16)}  ${r.kind.padEnd(14)} ${detail}`);
+			}
+			if (!rows.length) out(ctx, paint(C.dim, "  (no node events yet — unlock/add to start the history)", ctx.color));
+			return 0;
+		}
 		if (sub === "rm") {
 			if (!key) {
 				bad(ctx, "usage: node rm <key>");
@@ -8777,6 +9283,30 @@ function parseState(args) {
 	}
 	return out;
 }
+/**
+* 0.79.1 (R297 user report): `--state-file <path.json>` loads the state bag
+* from JSON instead of inline `--state k=v`. Two accepted shapes:
+*   flat shared   {"y_imported": 12}            → merged over --state, all keys share it
+*   per-node map  {"node-a": {"y": 1}, ...}     → each judged node gets its own bag
+* (disambiguated by "every value is a plain object"). Returns the per-node map
+* when shape B, null when merged into `shared`. Throws on unreadable/invalid.
+*/
+function loadStateFile(args, shared) {
+	const sf = args.flags["state-file"];
+	if (sf === void 0) return null;
+	if (sf === true || sf === "") throw new Error("usage: --state-file <path.json>");
+	let parsed;
+	try {
+		parsed = JSON.parse(require("node:fs").readFileSync(String(sf), "utf8"));
+	} catch (e) {
+		throw new Error(`cannot read --state-file ${sf}: ${e?.message || e}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("--state-file must contain a JSON object (flat counters, or per-node key→object map)");
+	const vals = Object.values(parsed);
+	if (vals.length && vals.every((v) => v && typeof v === "object" && !Array.isArray(v))) return parsed;
+	Object.assign(shared, parsed);
+	return null;
+}
 //#endregion
 //#region packages/knowledge/skills/src/skill-cmds.ts
 /** skill group — the L1/L2/L3 registry agents query before acting.
@@ -9151,7 +9681,22 @@ function run$3(env, action, rest, args) {
 				confidence: String(args.flags.confidence || configGet(env.db, "default_confidence")),
 				force
 			})).then((r) => {
-				writeResult(ctx, r, (row) => `note stored: ${row.id}  ${require_text.clip(title, 50)}`);
+				const row = r.row;
+				const verify = store.kbGet(row.id);
+				if (ctx.json) console.log(JSON.stringify({
+					...row,
+					...r.dup ? { duplicate: true } : {},
+					verified: !!verify,
+					workspace: env.home
+				}, null, 2));
+				else {
+					writeResult(ctx, r, (rw) => `note stored: ${rw.id}  ${require_text.clip(title, 50)}`);
+					out(ctx, paint(C.dim, `  @ ${env.home}`, ctx.color));
+					if (!verify) {
+						out(ctx, paint(C.yellow, `  ⚠ verify miss: id ${row.id} not readable back — the write may not have landed.`, ctx.color));
+						out(ctx, paint(C.yellow, `    run: ygl-trees doctor   (write_integrity check names phantom writes)`, ctx.color));
+					}
+				}
 				return 0;
 			}).catch((e) => {
 				bad(ctx, e?.message || String(e));
@@ -10675,6 +11220,13 @@ function createDashboardServer(env) {
 *  lifecycle-managed: dispose cleans it automatically. */
 function serve(env, args) {
 	const { ctx } = env;
+	if (args.flags.help || args.flags.h) {
+		out(ctx, `usage: ygl-trees webui serve [--port N] [--host H]`);
+		out(ctx, paint(C.dim, `  --port N    listen port (default 8642; 0 = pick a free one)`, ctx.color));
+		out(ctx, paint(C.dim, `  --host H    bind address (default 127.0.0.1; 0.0.0.0 opens to LAN)`, ctx.color));
+		out(ctx, paint(C.dim, `  endpoints:  / React client · /classic embedded dashboard · /api/events SSE`, ctx.color));
+		return Promise.resolve(0);
+	}
 	const reactAvailable = resolveDistRoot() !== null;
 	return new Promise((resolve) => {
 		const port = Number(args.flags.port || 8642);
@@ -10832,16 +11384,33 @@ function run(env, action, rest, args) {
 		detail: configRows.length === 0 ? "no overrides (all defaults)" : `${configRows.length} override(s), all valid`
 	});
 	const lockPath = `${db.path}.ygllock`;
-	let lockHolder = "";
-	try {
-		lockHolder = require("node:fs").readFileSync(`${lockPath}/pid`, "utf8").trim();
-	} catch {}
-	const hasLock = require("node:fs").existsSync(lockPath) && lockHolder !== String(process.pid);
-	checks.push({
-		name: "stale_lock",
-		status: hasLock ? "warn" : "pass",
-		detail: hasLock ? `lock dir detected: ${lockPath} — remove if no other ygl-trees process is running` : "no stale locks"
-	});
+	{
+		let lockHolder = "";
+		try {
+			lockHolder = node_fs.readFileSync(`${lockPath}/pid`, "utf8").trim();
+		} catch {}
+		const mine = lockHolder === String(process.pid);
+		const foreignLock = node_fs.existsSync(lockPath) && !mine;
+		const holderAlive = !!lockHolder && pidAlive(lockHolder);
+		let holderCmd = "";
+		try {
+			holderCmd = node_fs.readFileSync(`${lockPath}/cmd`, "utf8").trim();
+		} catch {}
+		let status = "pass";
+		let detail = "no stale locks";
+		if (foreignLock && holderAlive) {
+			status = "pass";
+			detail = `lock held by live pid ${lockHolder}${holderCmd ? ` (${holderCmd.slice(0, 80)})` : " (parallel session)"} — normal in multi-session use`;
+		} else if (foreignLock) {
+			status = "warn";
+			detail = `stale lock (pid ${lockHolder || "?"} dead) — ygl-trees db unlock or doctor --fix clears it`;
+		}
+		checks.push({
+			name: "stale_lock",
+			status,
+			detail
+		});
+	}
 	{
 		const evalConds = db.all(`SELECT c.id, c.name, c.op, c.value, n.key AS node
          FROM node_conditions c JOIN nodes n ON n.id=c.node_id
@@ -10885,6 +11454,38 @@ function run(env, action, rest, args) {
 			detail: `profile read failed: ${e?.message || e}`
 		});
 	}
+	{
+		const PHANTOM_SPECS = [
+			{
+				kind: "kb.add",
+				table: "kb_notes",
+				label: "kb"
+			},
+			{
+				kind: "source.add",
+				table: "sources",
+				label: "source"
+			},
+			{
+				kind: "evidence.add",
+				table: "evidence",
+				label: "evidence"
+			}
+		];
+		const phantoms = [];
+		for (const spec of PHANTOM_SPECS) {
+			const rows = db.all(`SELECT e.entity_id id, e.ts FROM events e
+          WHERE e.kind='${spec.kind}'
+            AND e.ts >= datetime('now', '-2 days')
+            AND NOT EXISTS (SELECT 1 FROM ${spec.table} t WHERE t.id = e.entity_id)`);
+			for (const r of rows) phantoms.push(`${spec.label} ${r.id} (${String(r.ts).slice(0, 16)})`);
+		}
+		checks.push({
+			name: "write_integrity",
+			status: phantoms.length ? "fail" : "pass",
+			detail: phantoms.length ? `${phantoms.length} phantom write event(s) in last 48h: ${phantoms.slice(0, 3).join(", ")}${phantoms.length > 3 ? " …" : ""} — event logged but row missing (rollback or different workspace; check receipts' workspace line)` : "recent write events all match stored rows"
+		});
+	}
 	const failed = checks.filter((c) => c.status === "fail").length;
 	const warned = checks.filter((c) => c.status === "warn").length;
 	const passed = checks.filter((c) => c.status === "pass").length;
@@ -10910,18 +11511,21 @@ function run(env, action, rest, args) {
 			db.run("UPDATE meta SET value='0' WHERE key='index_dirty'");
 			fixes.push("index dirty flag cleared (run: ygl-trees node index)");
 		}
-		const lockDir = `${env.db.path}.ygllock`;
-		let holder = "";
-		try {
-			holder = node_fs.readFileSync(`${lockDir}/pid`, "utf8").trim();
-		} catch {}
-		if (node_fs.existsSync(lockDir) && holder !== String(process.pid)) try {
-			node_fs.rmSync(lockDir, {
-				recursive: true,
-				force: true
-			});
-			fixes.push("stale lock removed");
-		} catch {}
+		{
+			const { pidAlive } = (init_db(), require_rolldown_runtime.__toCommonJS(db_exports));
+			const lockDir = `${env.db.path}.ygllock`;
+			let holder = "";
+			try {
+				holder = node_fs.readFileSync(`${lockDir}/pid`, "utf8").trim();
+			} catch {}
+			if (node_fs.existsSync(lockDir) && holder !== String(process.pid) && !pidAlive(holder)) try {
+				node_fs.rmSync(lockDir, {
+					recursive: true,
+					force: true
+				});
+				fixes.push("stale lock removed (holder pid dead)");
+			} catch {}
+		}
 		if (fixes.length) for (const f of fixes) ok(ctx, `  fixed: ${f}`);
 		else out(ctx, paint(C.dim, "  (--fix: no auto-fixable issues found)", ctx.color));
 	}
@@ -11046,10 +11650,11 @@ ${paint(C.bold, "research", true)}    collect → screen → extract → claim
   source add --title --url [--abstract --content --relevance --confidence --query]
   source fetch <url>          fetch page, extract title/meta/text (zero side-effect on failure)
   source list | search "<q>" | show <id> | rm <id>
-  evidence add <sourceId> --quote "..." [--note --locator]
+  evidence add <sourceId> --quote "..." | --file <path> [--note --locator]
   evidence list
   claim add "<text>" [--confidence A|B|C]
   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 list
 
@@ -11105,6 +11710,7 @@ ${paint(C.bold, "tree / node", true)}   tech-tree node model
   node validate                      cycles, dangling edges, dirty index
   node export [--out file.json]      portable JSON
   node import --file <file.json>     [--tree name] [--merge] — strict, transactional
+  node timeline [tree]               per-tree growth history (add/link/unlock events)
 
   Writes are idempotent (claim/evidence/query/kb/job dedupe by content
   hash); pass --force to keep a deliberate duplicate.
@@ -11145,6 +11751,7 @@ async function main(argv) {
 	const group = args._[0];
 	const action = args._[1];
 	if (group === "webui" && (action === "serve" || action === "export")) process.env.YGL_SERVE = "1";
+	if (group === "db" && action === "unlock") process.env.YGL_SERVE = "1";
 	if (args.flags.version === true || group === "version") {
 		out(ctx, appVersion());
 		return 0;
@@ -11264,8 +11871,13 @@ async function main(argv) {
 				alive = err.code === "EPERM";
 			}
 			if (alive) {
-				out(ctx, `  lock held by live process pid ${holder} (serve? webui dashboard)`);
-				out(ctx, `  to run CLI write commands, stop that process first — or use YGL_TEST=1 to bypass`);
+				let holderCmd = "";
+				try {
+					holderCmd = require("node:fs").readFileSync(require("node:path").join(lock, "cmd"), "utf8").trim();
+				} catch {}
+				out(ctx, `  lock held by live process pid ${holder}${holderCmd ? `\n  holder command: ${holderCmd}` : " (parallel CLI session — serve never takes the write lock)"}`);
+				out(ctx, `  reads still work; the lock serializes CLI writers and self-heals when pid ${holder} exits`);
+				out(ctx, `  force through (know what you are doing): YGL_TEST=1  ·  inspect/clear: ygl-trees db unlock`);
 			} else {
 				out(ctx, `  orphaned lock (pid ${holder} is dead) — removing: ${lock}`);
 				try {
@@ -11289,7 +11901,9 @@ async function main(argv) {
 			db?.close();
 		} catch {}
 		try {
-			(init_db(), require_rolldown_runtime.__toCommonJS(db_exports)).DB.releaseLockFor(file);
+			const { DB } = (init_db(), require_rolldown_runtime.__toCommonJS(db_exports));
+			if (db?.ownsLock) DB.releaseLockFor(file);
+			else if (DB.lockHolder(file) === String(process.pid)) DB.releaseLockFor(file);
 		} catch {}
 	});
 	process.on("SIGINT", () => shutdown.interrupt(0));
@@ -11584,13 +12198,14 @@ function generateLlmsManifest() {
 				["db export <file>", "full backup"],
 				["db sync pg <url>", "one-way mirror to PostgreSQL"],
 				["db migrate pg <url> [--fresh]", "full-fidelity graduation (with type preflight)"],
+				["db unlock [--force]", "clear stale .ygllock (pid-liveness checked; refuses live holders)"],
 				["db reset", "delete database"]
 			]
 		],
 		[
 			"doctor",
-			"Health check (9 items)",
-			[["doctor [--fix]", "diagnose (+ auto-fix: dirty index, stale lock)"]]
+			"Health check (10 items)",
+			[["doctor [--fix]", "diagnose (+ auto-fix: dirty index, dead stale lock, phantom writes)"]]
 		],
 		[
 			"config",