ygl-trees 0.78.0 → 0.80.0

package/dist/packages/core/database/src/db.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.COND_KINDS = exports.EDGE_MODES = exports.EDGE_RELS = exports.DB = exports.SCHEMA_SQL = exports.SCHEMA_VERSION = void 0;
+exports.pidAlive = pidAlive;
 exports.dbPath = dbPath;
 /**
  * Database: single source of truth for ygl-trees.
@@ -395,6 +396,9 @@ CREATE UNIQUE INDEX IF NOT EXISTS uq_skill_refs ON skill_refs(skill_id, path);
 class DB {
     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;
         fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -455,18 +459,39 @@ class DB {
                 catch { /* */ }
             }
             else {
+                // 0.79.1 (R297 user report): the old hint guessed "serve? webui
+                // dashboard" — but serve never takes the write lock, so the guess
+                // sent users to kill the wrong process. The lock dir now carries a
+                // `cmd` file (written at acquisition) naming the real holder.
+                let holderCmd = "";
+                try {
+                    holderCmd = fs.readFileSync(path.join(lockDir, "cmd"), "utf8").trim();
+                }
+                catch { /* */ }
                 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}"`);
+                    (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}"`);
             }
         }
         // acquire the lock (best-effort; crash cleanup via stale detection above)
+        let acquired = false;
         if (useLock)
             try {
                 fs.mkdirSync(lockDir, { recursive: true });
                 fs.writeFileSync(path.join(lockDir, "pid"), String(process.pid));
+                acquired = true;
+                // 0.79.1: self-reported holder identity — the collision error and
+                // `db unlock` read this back instead of guessing who holds the lock.
+                try {
+                    const cmd = [process.argv0, ...process.argv.slice(1)].join(" ").slice(0, 240);
+                    fs.writeFileSync(path.join(lockDir, "cmd"), cmd);
+                }
+                catch { /* identity is best-effort */ }
                 // P1 cold-user report (Windows): `process.on("exit")` rmSync can silently
                 // fail when the SQLite handle hasn't been released yet (EBUSY on the dir).
                 // Two mitigations:
@@ -486,6 +511,10 @@ class DB {
                 process.on("exit", cleanup);
             }
             catch { /* lock creation failure is non-fatal (read-only scenarios) */ }
+        // 0.79.1: ownership flag — lock-less instances (serve, db unlock) must
+        // never release a FOREIGN lock on close/exit (latent since serve existed,
+        // made acute by lock-free `db unlock`).
+        this.ownsLock = acquired;
         this.db = new node_sqlite3_wasm_1.Database(file);
         this.db.exec("PRAGMA journal_mode=WAL");
         // WAL + NORMAL (sqlite.org recommended pairing): commits skip the per-tx
@@ -495,8 +524,13 @@ class DB {
         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 (fs.existsSync(lockDir))
@@ -513,6 +547,24 @@ class DB {
         }
         catch { /* */ }
     }
+    /** Static: read the holder pid of a lock file ("" when absent/unreadable). */
+    static lockHolder(file) {
+        try {
+            return fs.readFileSync(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 fs.readFileSync(path.join(`${file}.ygllock`, "cmd"), "utf8").trim();
+        }
+        catch {
+            return "";
+        }
+    }
     migrate() {
         let row;
         try {
@@ -720,6 +772,22 @@ exports.EDGE_RELS = ["prereq", "unlock", "excludes", "enables"];
 exports.EDGE_MODES = ["AND", "OR", "XOR", "NOT"];
 /** Condition kinds for non-structural gates. */
 exports.COND_KINDS = ["flag", "resource", "level", "quest", "time", "expr"];
+/** 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"; // EPERM = alive (Windows), ESRCH = dead
+    }
+}
 /** Resolve the active database file. */
 function dbPath(home) {
     return path.join(home, "ygl-trees.db");

package/dist/packages/knowledge/skills/src/cmds.js

@@ -75,7 +75,32 @@ function run(env, action, rest, args) {
                 force,
             }))
                 .then((r) => {
-                (0, fmt_1.writeResult)(ctx, r, (row) => `note stored: ${row.id}  ${(0, text_1.clip)(title, 50)}`);
+                const row = r.row;
+                // Real-user report ①: three kb adds returned ✓, none was ever
+                // readable back. The transaction itself is sound (kb_notes +
+                // kb_fts + event commit together), so the loss was environmental
+                // (split workspace / different YGL_HOME between calls). Two in-band
+                // signals now make the landing point visible:
+                //   1. every receipt carries the workspace it wrote to
+                //   2. a verify probe re-reads the row through the SAME read path
+                //      kb search/list use — a miss is printed loudly, not silently
+                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 {
+                    (0, fmt_1.writeResult)(ctx, r, (rw) => `note stored: ${rw.id}  ${(0, text_1.clip)(title, 50)}`);
+                    (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  @ ${env.home}`, ctx.color));
+                    if (!verify) {
+                        (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.yellow, `  ⚠ verify miss: id ${row.id} not readable back — the write may not have landed.`, ctx.color));
+                        (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.yellow, `    run: ygl-trees doctor   (write_integrity check names phantom writes)`, ctx.color));
+                    }
+                }
                 return 0;
             })
                 .catch((e) => {

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

@@ -23,6 +23,41 @@ function buildBrief(env) {
     let project = null;
     if (cur)
         project = store.projectByName(cur);
+    // Report ③: selection-change awareness. tree.use / project.use events are
+    // logged by every selection flip; a recent one the CLI session didn't make
+    // itself usually means a parallel session re-pointed current_tree /
+    // current_project — exactly the 0.76 "node not found" incident class.
+    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 { /* events table optional in exotic setups */ }
     if (project) {
         const claims = store.claimList(project.id);
         const ev = store.evidenceList(project.id);

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

@@ -134,6 +134,76 @@ function run(env, action, rest, args) {
             else
                 (0, fmt_1.out)(ctx, file);
             return 0;
+        case "unlock": {
+            // Real-user report ②: residual .ygllock after a crash left users with
+            // an "rmdir" instruction and no safety net. `db unlock` checks pid
+            // liveness — dead/absent holder clears, a LIVE holder is refused
+            // (that is a parallel session or webui serve, not garbage) unless --force.
+            const lockDir = `${file}.ygllock`;
+            let holder = "";
+            try {
+                holder = fs.readFileSync(`${lockDir}/pid`, "utf8").trim();
+            }
+            catch { /* */ }
+            if (!fs.existsSync(lockDir)) {
+                if (ctx.json)
+                    console.log(JSON.stringify({ lock: lockDir, holder: null, cleared: false, reason: "no lock present" }, null, 2));
+                else
+                    (0, fmt_1.ok)(ctx, `no lock present: ${lockDir}`);
+                return 0;
+            }
+            if (holder && (0, db_1.pidAlive)(holder) && !args.flags.force) {
+                // Self-check: OUR OWN boot may hold this lock — that is not a
+                // parallel session, and refusing here would deadlock the command
+                // against itself. Clear it; the process exits right after anyway.
+                const self = Number(holder) === process.pid;
+                // 0.79.1: echo the holder's self-reported command line (R297 report —
+                // guessing "serve?" sent users to kill the wrong process).
+                let holderCmd = "";
+                try {
+                    holderCmd = 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 {
+                        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
+                            (0, fmt_1.ok)(ctx, `lock cleared: ${lockDir}  (self — acquired during boot)`);
+                        return 0;
+                    }
+                    catch { /* fall through to the generic clear below */ }
+                }
+                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 {
+                    (0, fmt_1.bad)(ctx, msg);
+                    (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.yellow, `  that is a parallel CLI session (serve never takes the write lock) — retry after it exits;`, ctx.color));
+                    (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.yellow, `  the lock self-heals then. --force overrides (corruption risk if writes are in flight).`, ctx.color));
+                }
+                return 1;
+            }
+            try {
+                fs.rmSync(lockDir, { recursive: true, force: true });
+                const why = !holder || !(0, db_1.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
+                    (0, fmt_1.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
+                    (0, fmt_1.bad)(ctx, `remove failed: ${e?.message || e}`);
+                return 1;
+            }
+        }
         case "stats": {
             const s = env.store.stats();
             if (ctx.json) {

package/dist/packages/ops/tools/src/doctor.js

@@ -137,23 +137,44 @@ function run(env, action, rest, args) {
         });
     }
     // ── 7. Stale lock check ──
-    // The CLI process running doctor holds its own .ygllock while checking —
-    // exclude our own live lock; warn only on foreign/stale holders.
+    // Real-user report ②: a residual lock with a DEAD pid earned an ambiguous
+    // "remove if no other process is running" warning, and a LIVE holder
+    // (parallel session / serve) was indistinguishable from garbage. Now the
+    // pid liveness probe (same one lock acquisition uses) decides:
+    //   dead holder → warn (clearable via `db unlock` / doctor --fix)
+    //   live holder → PASS (a live write-lock is a legitimate parallel session)
     const dbPath = db.path;
     const lockPath = `${dbPath}.ygllock`;
-    let lockHolder = "";
-    try {
-        lockHolder = require("node:fs").readFileSync(`${lockPath}/pid`, "utf8").trim();
+    {
+        // Report ②: a foreign LIVE holder is normal multi-session usage; only a
+        // DEAD holder is stale residue (db unlock / doctor --fix clear it).
+        let lockHolder = "";
+        try {
+            lockHolder = fs.readFileSync(`${lockPath}/pid`, "utf8").trim();
+        }
+        catch { /* absent/unreadable */ }
+        const mine = lockHolder === String(process.pid);
+        const foreignLock = fs.existsSync(lockPath) && !mine;
+        const holderAlive = !!lockHolder && (0, db_1.pidAlive)(lockHolder);
+        // 0.79.1: echo the holder's self-reported command line — naming the real
+        // holder beats guessing (R297 report: "serve?" guess sent users astray).
+        let holderCmd = "";
+        try {
+            holderCmd = fs.readFileSync(`${lockPath}/cmd`, "utf8").trim();
+        }
+        catch { /* pre-0.79.1 lock */ }
+        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 });
     }
-    catch { /* absent/unreadable */ }
-    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",
-    });
     // ── 8. eval-family envelope sanity (0.28.0) ──
     // A malformed envelope silently degrades: evalChoice/evalScore fall back to
     // empty options/levels → the gate can never resolve (always pending).
@@ -208,6 +229,35 @@ function run(env, action, rest, args) {
             checks.push({ name: "plugin_profile", status: "fail", detail: `profile read failed: ${e?.message || e}` });
         }
     }
+    // ── 10. Write integrity: recent write events whose rows are missing ──
+    // Real-user report ①: `kb add` returned ✓ but the note was never found
+    // again (search/list/promote all missed it). If a write event landed but
+    // the row did not, the write path lost data (rollback / crash between
+    // commit and receipt / a different workspace). This check replays recent
+    // write events against the base tables and names the phantom ids.
+    {
+        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",
+        });
+    }
     // ── Output ──
     const failed = checks.filter((c) => c.status === "fail").length;
     const warned = checks.filter((c) => c.status === "warn").length;
@@ -247,19 +297,24 @@ 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)");
         }
-        // stale lock → remove (never our own live lock)
-        const lockDir = `${env.db.path}.ygllock`;
-        let holder = "";
-        try {
-            holder = fs.readFileSync(`${lockDir}/pid`, "utf8").trim();
-        }
-        catch { /* */ }
-        if (fs.existsSync(lockDir) && holder !== String(process.pid)) {
+        // stale lock → remove ONLY if the holder pid is dead (report ②: --fix used
+        // to nuke ANY non-self lock — including a live parallel session's, which
+        // reintroduced exactly the double-writer corruption the lock prevents)
+        {
+            const { pidAlive } = require("../../../core/database/src/db");
+            const lockDir = `${env.db.path}.ygllock`;
+            let holder = "";
             try {
-                fs.rmSync(lockDir, { recursive: true, force: true });
-                fixes.push("stale lock removed");
+                holder = fs.readFileSync(`${lockDir}/pid`, "utf8").trim();
             }
             catch { /* */ }
+            if (fs.existsSync(lockDir) && holder !== String(process.pid) && !pidAlive(holder)) {
+                try {
+                    fs.rmSync(lockDir, { recursive: true, force: true });
+                    fixes.push("stale lock removed (holder pid dead)");
+                }
+                catch { /* */ }
+            }
         }
         if (fixes.length) {
             for (const f of fixes)

package/dist/packages/ops/tools/src/webui.js

@@ -997,6 +997,15 @@ function createDashboardServer(env) {
  *  lifecycle-managed: dispose cleans it automatically. */
 function serve(env, args) {
     const { ctx } = env;
+    // 0.79.1 (R297 user report): `webui serve --help` used to fall through and
+    // actually start a server — an accidental extra process. Short-circuit.
+    if (args.flags.help || args.flags.h) {
+        (0, fmt_1.out)(ctx, `usage: ygl-trees webui serve [--port N] [--host H]`);
+        (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  --port N    listen port (default 8642; 0 = pick a free one)`, ctx.color));
+        (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  --host H    bind address (default 127.0.0.1; 0.0.0.0 opens to LAN)`, ctx.color));
+        (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  endpoints:  / React client · /classic embedded dashboard · /api/events SSE`, ctx.color));
+        return Promise.resolve(0);
+    }
     // re-check (the server's hasWebApp is scoped to createDashboardServer)
     const reactAvailable = (0, index_1.resolveDistRoot)() !== null;
     return new Promise((resolve) => {

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

@@ -48,6 +48,10 @@ const config_1 = require("../../../ops/tools/src/config");
 const entities_1 = require("./entities");
 /** 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 new Date().toISOString().replace(/[-:T]/g, "").slice(0, 12);
+}
 function runWrite(env, fn, human) {
     const { ctx } = env;
     return (0, orm_1.getOrm)(env.db.path)
@@ -177,14 +181,31 @@ function run(env, action, rest, args) {
                 (0, fmt_1.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 || "");
+            // 0.80: in-session adjudication carrier — the most common human
+            // arbitration form had no native --url shape (http(s)/file only),
+            // forcing temp-file workarounds. `--adjudication "<裁决摘要>"`
+            // fills url with a session:// pseudo-scheme and doubles as the
+            // title when --title is absent.
+            const adjRaw = args.flags.adjudication;
+            if (adjRaw === true) {
+                (0, fmt_1.bad)(ctx, 'flag needs a value: --adjudication "<裁决摘要>"');
+                return 2;
+            }
+            if (adjRaw !== undefined && adjRaw !== "") {
+                const adj = String(adjRaw);
+                if (!url)
+                    url = `session://adjudication/${nowCompact()}`;
+                if (!title)
+                    title = adj.slice(0, 60);
+            }
             if (!title && !url) {
                 (0, fmt_1.bad)(ctx, "need --title and/or --url");
                 return 2;
             }
-            if (url && !/^https?:\/\/|^file:\/\//.test(url)) {
-                (0, fmt_1.bad)(ctx, `--url must be http(s):// or file:// (got: "${(0, text_1.clip)(url, 30)}")`);
+            if (url && !/^https?:\/\/|^file:\/\/|^session:\/\//.test(url)) {
+                (0, fmt_1.bad)(ctx, `--url must be http(s)://, file:// or session:// (got: "${(0, text_1.clip)(url, 30)}")`);
                 return 2;
             }
             const spec = {
@@ -358,9 +379,31 @@ function run(env, action, rest, args) {
     if (sub === "evidence") {
         if (subAction === "add") {
             const sourceId = rest[1];
-            const quote = String(args.flags.quote || readBody());
+            // Report ⑤: --file reads the quote from disk — long multi-line excerpts
+            // stop fighting the shell for --quote escaping.
+            const file = String(args.flags.file || "");
+            let quote = String(args.flags.quote || "");
+            if (file) {
+                if (quote) {
+                    (0, fmt_1.bad)(ctx, "--file and --quote are mutually exclusive");
+                    return 2;
+                }
+                try {
+                    quote = require("fs").readFileSync(file, "utf8").trim();
+                }
+                catch (e) {
+                    (0, fmt_1.bad)(ctx, `cannot read --file: ${e?.message || e}`);
+                    return 1;
+                }
+                if (!quote) {
+                    (0, fmt_1.bad)(ctx, `--file is empty: ${file}`);
+                    return 2;
+                }
+            }
+            if (!quote)
+                quote = readBody();
             if (!sourceId || !quote) {
-                (0, fmt_1.bad)(ctx, "usage: research evidence add <sourceId> --quote \"...\"");
+                (0, fmt_1.bad)(ctx, "usage: research evidence add <sourceId> --quote \"...\" | --file <path> [--note ..] [--locator ..]");
                 return 2;
             }
             const note = String(args.flags.note || "");
@@ -451,7 +494,7 @@ function run(env, action, rest, args) {
         }
         if (subAction === "link") {
             if (!rest[1] || !rest[2]) {
-                (0, fmt_1.bad)(ctx, "usage: research claim link <claimId> <evidenceId> [--stance refutes]");
+                (0, fmt_1.bad)(ctx, "usage: research claim link <claimId> <evidenceId> [--stance refutes] [--by-source]");
                 return 2;
             }
             const stanceRaw = String(args.flags.stance || "supports");
@@ -462,6 +505,39 @@ function run(env, action, rest, args) {
                 return 2;
             }
             const stance = stanceRaw;
+            // Report ④-3: --by-source sugar — hand a SOURCE id and every evidence
+            // under it links in one shot (the three-id taxonomy forced a per-evidence
+            // lookup round trip before this).
+            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) {
+                    const srcExists = store.db.get("SELECT id FROM sources WHERE id=? AND project_id=?", [rest[2], project.id]);
+                    (0, fmt_1.bad)(ctx, srcExists
+                        ? `source ${rest[2]} has no evidence yet — research evidence add ${rest[2]} --quote ".." first`
+                        : `source not found: ${rest[2]}`);
+                    return 1;
+                }
+                return (0, orm_1.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 writes.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
+                        (0, fmt_1.ok)(ctx, `linked ${linked} evidence from source ${rest[2]} (${dups} already) — claim status: ${status}`);
+                    return 0;
+                })
+                    .catch((e) => {
+                    (0, fmt_1.bad)(ctx, e?.message || String(e));
+                    return 1;
+                });
+            }
             return (0, orm_1.getOrm)(env.db.path)
                 .then((ds) => writes.claimLink(ds, rest[1], rest[2], stance))
                 .then((r) => {
@@ -491,6 +567,22 @@ function run(env, action, rest, args) {
                 return 0;
             })
                 .catch((e) => {
+                // Report ④-2: the three-id taxonomy (source/evidence/claim) makes
+                // "evidence not found: X" ambiguous when X is actually a SOURCE id.
+                // Detect that case and hand back the real evidence ids to use.
+                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) {
+                        (0, fmt_1.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;
+                    }
+                    const srcExists = store.db.get("SELECT id FROM sources WHERE id=? AND project_id=?", [m[1], project.id]);
+                    if (srcExists) {
+                        (0, fmt_1.bad)(ctx, `${e.message} — that id is a SOURCE with no evidence yet: research evidence add ${m[1]} --quote ".." first`);
+                        return 1;
+                    }
+                }
                 (0, fmt_1.bad)(ctx, e?.message || String(e));
                 return 1;
             });
@@ -613,29 +705,43 @@ function run(env, action, rest, args) {
                     (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, "  no [预测·…] claims in this project", ctx.color));
                 return 0;
             }
-            const { auditPredictions } = require("./predict");
+            const { auditPredictions, loadStateSource } = require("./predict");
             return (async () => {
-                const rows = await auditPredictions({ claims, db: store.db, npmProbe: args.flags.offline !== true });
+                // 0.79.1 --state bridge: external counter map (JSON file or URL, e.g.
+                // DSH API counts) turns state-referencing criteria auto-measurable.
+                let state = null;
+                if (args.flags.state) {
+                    state = await loadStateSource(String(args.flags.state));
+                    if (!state && !ctx.json) {
+                        (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.yellow, `  ⚠ --state ${args.flags.state} 加载失败（文件/URL 不可读或非 JSON）——相关判据回落 manual`, ctx.color));
+                    }
+                }
+                const rows = await auditPredictions({ claims, db: store.db, 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) {
+                    (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  全部 ${rows.length} 条预测已结案（resolved）——--all 查看终态表`, ctx.color));
+                }
                 else {
-                    (0, fmt_1.head)(ctx, `prediction audit — ${project.name} (${rows.length} predictions)`);
-                    (0, fmt_1.table)(ctx, rows, ["claim", "horizon", "deadline", "判据", "实测", "判定", "days"], [
+                    (0, fmt_1.head)(ctx, `prediction audit — ${project.name} (${visible.length}/${rows.length}${resolvedN && !args.flags.all ? ` · ${resolvedN} resolved 隐藏 (--all)` : ""})`);
+                    (0, fmt_1.table)(ctx, visible, ["claim", "horizon", "deadline", "判据", "实测", "判定", "days"], [
                         "claim_id", "horizon", "deadline", "criterion", "actual", "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) {
                         (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.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")) {
+                    for (const r of visible.filter((x) => x.verdict === "manual")) {
                         (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  · ${r.claim_id}: ${r.hint}`, ctx.color));
                     }
                 }
                 return 0;
             })();
         }
-        (0, fmt_1.bad)(ctx, "usage: research predict audit [--offline]");
+        (0, fmt_1.bad)(ctx, "usage: research predict audit [--offline] [--state <file|url>] [--all]");
         return 2;
     }
     (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, "  research: query add|list · source add|list|search|show|rm · evidence add|list · claim add|link|list · predict audit", ctx.color));