pi-proactive 0.0.0-stage → 0.2.0-beta.2

package/build/src/task-store.js

@@ -0,0 +1,438 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PROACTIVE_FILE_MODE, chmodQuiet, ensureDir, proactiveDir, resolveAgentDir, writeAtomicFile, } from "./config.js";
+/**
+ * 任务记录的版本号。
+ *
+ * 为什么落在**每条记录**上而不是文件顶层：`tasks.json` 的顶层一直是数组，
+ * 既有读写方直接 `JSON.parse` 整个文件并按下标取任务
+ * （`tests/m5c-wiring.test.ts`、`tests/extension-entry.test.ts` 都这么读）——
+ * 顶层改成对象会破坏这些读方。版本号落在记录上，落盘文件同样含 `version:"v1"`，
+ * 且「不认识的版本 → 忽略整个文件」的保护语义不变。
+ */
+const TASK_RECORD_VERSION = "v1";
+/**
+ * global 任务认领（`tasks/claims/<id>.claim`）的**失效时长**（ms）。
+ *
+ * 偏差 P-D9：认领文件原先**永不失效**（只在 `store.remove(id)` 时删）→ 持有者进程崩溃后，
+ * 该任务对所有其它 agent **永久锁死**（repeat 任务尤其明显：它永远不会被 remove）。
+ * 按规范 §6 阈值表「`tasks/claims/*.claim` · 任务持有者 · 每 1 小时 · claim 年龄 > 1 小时
+ * → 删除（允许接管）」：超过 1 小时即视为持有者已崩溃 → **允许接管**。
+ */
+export const DEFAULT_TASK_CLAIM_STALE_MS = 3_600_000;
+/**
+ * 任务表（落盘）。
+ *
+ * 落盘位置：`<agentDir>/proactive/tasks.json`；global 任务的认领文件在 `<agentDir>/proactive/tasks/claims/<id>.claim`。
+ *
+ * 约定：
+ * - 写：先写 `tasks.json.tmp` 再 `rename` 覆盖（同目录内 tmp+rename 是原子的）；
+ * - 读：文件缺失 → 空表；JSON 坏 → 备份为 `tasks.json.corrupt-<ts>` 并以空表启动，**绝不抛出**；
+ * - 版本：落盘记录带 `version:"v1"`；读到**不认识的版本** → 记日志并**忽略整个文件**
+ *   （不抛错、不用默认值覆盖原文件、拒绝写入）；旧格式（顶层数组、无版本号）仍按已知格式读取。
+ * - 归属：`scope:"session"` 的任务由 `ownerSessionId`（会话，跨进程重启稳定）决定，
+ *   旧任务（无 `ownerSessionId`）退回 `ownerAgentId`（过滤在调度器侧，list() 一律可见）；
+ *   `scope:"global"` 的任务任何 agent 都能执行，但必须先用 O_EXCL 原子认领（见 claimIfGlobal）。
+ */
+export class TaskStore {
+    agentDir;
+    now;
+    agentId;
+    /** 内存副本（最近一次读盘的内容）。 */
+    tasks = [];
+    /** 当前文件带**不认识的版本** → 忽略它，且拒绝写入（不覆盖原文件）。 */
+    foreignVersion = false;
+    /** 用户可见通道（宿主 `ui.notify`）；缺省 → 提示进 `pendingNotices` 队列（降级路径）。 */
+    notify;
+    /** global 任务认领的失效时长（ms）。 */
+    staleClaimMs;
+    /** 已投递过的提示（同一进程内不重复刷屏）。 */
+    notifiedKeys = new Set();
+    /** **未送达**的用户可见提示（没有通道时的降级队列；宿主拿到通道后可 `flushNotices()`）。 */
+    pendingNotices = [];
+    constructor(opts = {}) {
+        this.agentDir = opts.agentDir ?? resolveAgentDir();
+        this.now = opts.now ?? Date.now;
+        this.agentId = opts.agentId ?? "unknown";
+        this.notify = opts.notify;
+        this.staleClaimMs = opts.staleClaimMs ?? DEFAULT_TASK_CLAIM_STALE_MS;
+    }
+    /** 任务表文件绝对路径。 */
+    get filePath() {
+        return path.join(proactiveDir(this.agentDir), "tasks.json");
+    }
+    /** 读任务表（坏文件自动降级为空表）。 */
+    list() {
+        return this.readFromDisk();
+    }
+    /** 追加任务并原子落盘。 */
+    add(task) {
+        const tasks = this.readFromDisk();
+        tasks.push(task);
+        this.tasks = tasks;
+        this.flush();
+        return task;
+    }
+    /** 删除任务并原子落盘；删除时一并清理其认领文件。 */
+    remove(id) {
+        const tasks = this.readFromDisk();
+        const next = tasks.filter((t) => t.id !== id);
+        const removed = next.length !== tasks.length;
+        this.tasks = next;
+        this.flush();
+        if (removed)
+            this.removeClaim(id);
+        return removed;
+    }
+    /** 更新任务字段（如 lastFiredAt / dueAt / enabled）并原子落盘。 */
+    update(id, patch) {
+        const tasks = this.readFromDisk();
+        const idx = tasks.findIndex((t) => t.id === id);
+        if (idx < 0)
+            throw new Error(`任务不存在：${id}`);
+        const updated = { ...tasks[idx], ...patch };
+        tasks[idx] = updated;
+        this.tasks = tasks;
+        this.flush();
+        return updated;
+    }
+    /**
+     * global 任务原子认领（O_EXCL）。
+     *
+     * - 认领文件不存在 → 创建成功 → 返回 true（内容：`<agentId> <ts>`，便于审计）；
+     * - 认领文件已存在且属于**他人**且**未失效** → 返回 false（跳过，避免重复执行）；
+     * - 认领文件已存在且属于**自己** → 返回 true（同一 owner 后续 tick 不丢失自己的认领，
+     *   否则 global repeat 任务在第二次 tick 就永远无法再投递）；
+     * - 认领文件已存在且属于**他人**但**已失效**（年龄 ≥ `staleClaimMs`，缺省 1 小时）→
+     *   **允许接管**：删旧锁 + 用 O_EXCL 重建（**只有一个人能重建成功** → 接管是原子的；
+     *   活跃持有者不会被抢）。
+     */
+    claimIfGlobal(task, agentId) {
+        if (task.scope !== "global")
+            return false;
+        const owner = agentId ?? this.agentId;
+        const claimPath = this.claimPath(task.id);
+        try {
+            ensureDir(path.dirname(claimPath));
+        }
+        catch {
+            return false;
+        }
+        // 最多 3 轮：① O_EXCL 抢占 ② 判定能否接管 ③ 接管后重新抢占。
+        // 接管 = 「删旧锁 + O_EXCL 重建」→ **只有一个人能重建成功** → 接管是原子的。
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                // O_EXCL：原子创建，已存在则抛 EEXIST
+                const fd = fs.openSync(claimPath, "wx");
+                try {
+                    fs.writeFileSync(fd, `${owner} ${this.now()}\n`, "utf8");
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                // 认领锁属「同机其它进程不该读」的落盘面 → 0600（规范 P0）。
+                chmodQuiet(claimPath, PROACTIVE_FILE_MODE);
+                return true;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    return false;
+            }
+            // 已存在 → 读持有者与时间戳
+            const content = readFileSafe(claimPath);
+            if (content === null)
+                continue; // 刚被别人删掉 → 下一轮重新抢占
+            const parts = content.trim().split(/\s+/);
+            const holder = parts[0] ?? "";
+            if (holder === owner)
+                return true; // 自己的认领 → 保持（不丢自己的执行权）
+            const ts = Number.parseInt(parts[1] ?? "", 10);
+            const age = Number.isFinite(ts) ? this.now() - ts : Number.POSITIVE_INFINITY;
+            // **活跃持有者不得被抢**（P-D9：只接管「已失效」的认领）
+            if (age < this.staleClaimMs)
+                return false;
+            // 认领已失效（持有者崩溃）→ 删旧锁，下一轮用 O_EXCL 重建（只有一个赢家）
+            try {
+                fs.unlinkSync(claimPath);
+            }
+            catch {
+                // 已被别人删掉 → 下一轮重新抢占（成功或 EEXIST 都会回到判定）
+            }
+        }
+        return false;
+    }
+    /**
+     * 原子落盘（tmp + rename）。
+     *
+     * 落盘记录带 `version:"v1"`（版本号只存在于落盘格式，读回时剥离）。
+     * 若当前文件带**不认识的版本** → 拒绝写入（保留原文件，避免用默认值覆盖它）。
+     */
+    flush() {
+        if (this.foreignVersion) {
+            console.error("[proactive] tasks.json 版本无法识别 → 拒绝写入（保留原文件，不用默认值覆盖）");
+            return;
+        }
+        const file = this.filePath;
+        const payload = this.tasks.map((t) => ({ ...t, version: TASK_RECORD_VERSION }));
+        // 原子写（tmp **独占** + 同目录 rename + 0600 + fsync）：
+        // 任务表是「不能丢」的面（用户的排期，规范 I3）→ 文件与父目录都要 fsync。
+        writeAtomicFile(file, `${JSON.stringify(payload, null, 2)}\n`, { durable: true });
+    }
+    // ---- 内部实现 ----
+    /**
+     * global 任务认领文件：`proactive/tasks/claims/<id>.claim`。
+     *
+     * 与邮箱的认领锁（`proactive/mailbox/claims/<id>.lock`）**分属两个命名空间**（RP-9）：
+     * 同目录同文件名会让两边的清理逻辑互相误删。
+     */
+    claimPath(id) {
+        return path.join(proactiveDir(this.agentDir), "tasks", "claims", `${id}.claim`);
+    }
+    removeClaim(id) {
+        try {
+            fs.unlinkSync(this.claimPath(id));
+        }
+        catch {
+            // 认领文件不存在或删不掉都不影响主流程
+        }
+    }
+    /**
+     * 读盘；文件缺失/读失败 → 空表；JSON 坏 → 备份 + 空表（绝不抛出）。
+     *
+     * 版本判定：
+     * - 顶层数组：记录级 `version` 存在且 ≠ `v1` → **不认识的版本** → 忽略整个文件；
+     *   记录无 `version` → 旧格式，按已知格式读取。
+     * - 顶层对象：`version:"v1"` → 读 `tasks`；其余（`v99` / 缺 version）→ **不认识的版本** → 忽略整个文件。
+     * - 其它形状 → 坏格式 → 备份 + 空表（既有降级策略）。
+     */
+    readFromDisk() {
+        const file = this.filePath;
+        let raw;
+        try {
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            this.tasks = [];
+            this.foreignVersion = false;
+            return this.tasks;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.backupCorrupt(file);
+            this.tasks = [];
+            this.foreignVersion = false;
+            return this.tasks;
+        }
+        if (Array.isArray(parsed)) {
+            const unknown = parsed.find((r) => hasVersion(r) && recordVersion(r) !== TASK_RECORD_VERSION);
+            if (unknown) {
+                this.ignoreForeignVersion(recordVersion(unknown), parsed);
+                return this.tasks;
+            }
+            this.foreignVersion = false;
+            this.tasks = parsed.filter(isTaskLike).map(stripVersion);
+            return this.tasks;
+        }
+        if (parsed !== null && typeof parsed === "object") {
+            const obj = parsed;
+            if (obj.version === TASK_RECORD_VERSION && Array.isArray(obj.tasks)) {
+                this.foreignVersion = false;
+                this.tasks = obj.tasks.filter(isTaskLike).map(stripVersion);
+                return this.tasks;
+            }
+            this.ignoreForeignVersion(obj.version, parsed);
+            return this.tasks;
+        }
+        this.backupCorrupt(file);
+        this.tasks = [];
+        this.foreignVersion = false;
+        return this.tasks;
+    }
+    /** 坏文件 → 备份改名 + 空表（备份失败也绝不抛出）。 */
+    backupCorrupt(file) {
+        try {
+            fs.renameSync(file, `${file}.corrupt-${this.now()}`);
+        }
+        catch {
+            // 备份失败也绝不抛出（宁可空表启动）
+        }
+    }
+    /**
+     * 不认识的版本 → **用户可见地**告知 + 忽略整个文件（不覆盖原文件）。
+     *
+     * 偏差 P-D5（规范 V3③）：原先只打一行 stderr（宿主通常不展示）→ 用户的定时任务
+     * **静默停止**而用户毫不知情。现在额外走**用户可见通道**（宿主 `ui.notify`），
+     * 内容含：版本号、原文件位置、**不执行其中 N 个任务**、迁移命令。
+     */
+    ignoreForeignVersion(version, parsed) {
+        this.foreignVersion = true;
+        this.tasks = [];
+        const versionText = typeof version === "string" ? version : JSON.stringify(version) ?? "缺失";
+        console.error(`[proactive] tasks.json 版本无法识别（version=${versionText}）→ 忽略该文件（不覆盖原文件）`);
+        this.publishNotice(formatForeignVersionNotice({
+            version: versionText,
+            file: this.filePath,
+            count: countTaskRecords(parsed),
+        }));
+    }
+    /**
+     * 送出用户可见提示：有通道 → 直接送；无通道（或通道抛错）→ 进降级队列。
+     *
+     * 同一进程内**只送一次**（读盘每个 tick 都会触发 → 否则每秒刷屏）。
+     */
+    publishNotice(message) {
+        const key = `${this.filePath}|${message}`;
+        if (this.notifiedKeys.has(key))
+            return;
+        this.notifiedKeys.add(key);
+        if (this.notify) {
+            try {
+                this.notify(message);
+                return;
+            }
+            catch {
+                // 通道抛错 → 落降级队列（宿主可稍后 flushNotices）
+            }
+        }
+        this.pendingNotices.push(message);
+    }
+    /**
+     * 清理**已失效**的 global 任务认领文件（偏差 P-D9 / 规范 §6 阈值表）。
+     *
+     * 责任方 = 任务持有者；周期 = 每 1 小时；阈值 = claim 年龄 > 1 小时 → 删除（允许接管）。
+     * 返回被删除的认领文件数（**不抛错**）。
+     */
+    sweepStaleClaims() {
+        const dir = path.join(proactiveDir(this.agentDir), "tasks", "claims");
+        let removed = 0;
+        let names;
+        try {
+            names = fs.readdirSync(dir);
+        }
+        catch {
+            return 0;
+        }
+        for (const name of names) {
+            if (!name.endsWith(".claim"))
+                continue;
+            const file = path.join(dir, name);
+            const content = readFileSafe(file);
+            const ts = content === null ? Number.NaN : Number.parseInt(content.trim().split(/\s+/)[1] ?? "", 10);
+            const age = Number.isFinite(ts) ? this.now() - ts : mtimeAge(file, this.now());
+            if (age < this.staleClaimMs)
+                continue;
+            try {
+                fs.unlinkSync(file);
+                removed += 1;
+            }
+            catch {
+                // 删不掉不算失败（别人可能正在接管）
+            }
+        }
+        return removed;
+    }
+    /**
+     * 把**未送达**的用户可见提示交给宿主通道（降级路径：构造时没有 notify 通道时用）。
+     *
+     * 返回本次送达的条数。宿主拿到通道后应调用它（如 session_start 时）。
+     */
+    flushNotices(deliver) {
+        const pending = this.pendingNotices.splice(0);
+        let delivered = 0;
+        for (const message of pending) {
+            try {
+                deliver(message);
+                delivered += 1;
+            }
+            catch {
+                // 通道失败不得抛给调用方（宁可少送一条）
+            }
+        }
+        return delivered;
+    }
+    /** 当前**未送达**的用户可见提示（降级队列；只读）。 */
+    get undeliveredNotices() {
+        return [...this.pendingNotices];
+    }
+}
+/** 记录是否带版本号。 */
+function hasVersion(value) {
+    return typeof value === "object" && value !== null && "version" in value;
+}
+/** 读记录上的版本号（不存在 → undefined）。 */
+function recordVersion(value) {
+    return hasVersion(value) ? value.version : undefined;
+}
+/** 剥掉落盘格式的版本号（内存里的任务对象只保留 Task 字段）。 */
+function stripVersion(task) {
+    const copy = { ...task };
+    delete copy.version;
+    return copy;
+}
+/** 任务项形状校验（丢掉明显不是 Task 的条目，避免坏表污染调度）。 */
+function isTaskLike(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const t = value;
+    return typeof t.id === "string" && typeof t.dueAt === "number" && typeof t.prompt === "string";
+}
+/** 读文件；失败 → null（**不抛错**）。 */
+function readFileSafe(file) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** 文件年龄（ms，按 mtime；读不到 → 0）。 */
+function mtimeAge(file, now) {
+    try {
+        return now - fs.statSync(file).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * 文件里「有多少条任务记录」（**只数条数，不解释内容**）。
+ *
+ * 用途：未知版本时要告诉用户「本版本不执行其中的 N 个任务」——
+ * 数条数不需要理解格式（不理解正是「拒绝按已知格式解析」的含义）。
+ */
+function countTaskRecords(parsed) {
+    if (Array.isArray(parsed))
+        return parsed.length;
+    if (parsed !== null && typeof parsed === "object") {
+        const tasks = parsed.tasks;
+        if (Array.isArray(tasks))
+            return tasks.length;
+    }
+    return 0;
+}
+/**
+ * 未知版本的**用户可见提示**（偏差 P-D5 / 规范 V6）。
+ *
+ * 必含四项（缺一不可）：版本号、原文件位置、**不执行其中 N 个任务**、迁移命令。
+ *
+ * 迁移命令为什么是一条**生成副本**的命令（而不是就地改写）：
+ * 就地改写会在用户没看过内容前就动原文件（不可逆）→ 只生成 `<file>.migrated`，
+ * 用户确认后再覆盖回去（原文件在此之前始终逐字保留）。
+ */
+export function formatForeignVersionNotice(args) {
+    const quoted = `'${args.file.replace(/'/g, `'\\''`)}'`;
+    const migrate = `node -e 'const fs=require("fs"),f=process.argv[1],t=JSON.parse(fs.readFileSync(f,"utf8")),` +
+        `a=Array.isArray(t)?t:(t.tasks||[]);fs.writeFileSync(f+".migrated",` +
+        `JSON.stringify(a.map(r=>({...r,version:"v1"})),null,2)+"\\n")' ${quoted}`;
+    return [
+        `proactive: 任务表版本无法识别（version=${args.version}）→ 本次不执行其中的 ${args.count} 个任务。`,
+        `· 版本：${args.version}`,
+        `· 原文件：${args.file}（已原样保留，未覆盖）`,
+        `· 影响：其中 ${args.count} 个任务本版本不会触发（排期静默停止）`,
+        `· 迁移命令（生成 v1 副本，不动原文件）：${migrate}`,
+        `· 迁移步骤：确认副本无误后用它覆盖原文件，再重启会话。`,
+    ].join("\n");
+}

package/build/src/thread.js

@@ -0,0 +1,196 @@
+import fs from "node:fs";
+import path from "node:path";
+import { agentSegment } from "./envelope.js";
+import { PROACTIVE_FILE_MODE, chmodQuiet, ensureDir, isKnownOnDiskVersion, onDiskVersionOf } from "./config.js";
+/**
+ * 默认轮次上限（**往返**数）：4 轮后停机，防 A→B→A 环路。
+ *
+ * 单位 = **往返**（一次 ask + 其对应 reply 才算 1 轮）——
+ * 旧的「按事件数计」口径把**未获回答的提问**也算进去（P-1）：
+ * 连发 9 条提问就把线程计数推到 9 ≥ 上限 → 之后所有回信被静默拒发、请求方零通知。
+ *
+ * 数值 4 不是「把上限改小」：旧口径 8 条 ask/reply 事件 = **4 次往返** → 与旧口径**同一预算**
+ * （环路防护强度不变），只是计数单位从「事件」换成「往返」。
+ */
+export const DEFAULT_MAX_ROUNDS = 4;
+/**
+ * threadId → 文件名片段（**防路径穿越**）。
+ *
+ * 与 `src/envelope.ts` 的 `agentSegment` 同类做法（替换路径分隔符与空白），但**独立实现**：
+ * threadId 的片段化额外把纯 `.`/`..` 折叠掉，保证结果永远落在
+ * `<agentDir>/proactive/threads/` 内。
+ * （**agentId 段不复用本函数** —— 它直接用 `src/envelope.ts` 的 `agentSegment`，
+ * 那是跨模块唯一真源：写端与读端必须逐字一致。）
+ */
+function threadSegment(threadId) {
+    const s = String(threadId ?? "")
+        .replace(/[/\\\s]/g, "_")
+        .replace(/^\.+$/, "_");
+    return s || "unknown";
+}
+/** 判断一行是否为合法事件对象（坏行 → 跳过，不抛错）。 */
+function isThreadEvent(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const e = value;
+    // 未知版本 → 拒绝按已知格式解析（规范 V3）→ 该行按坏行处理（跳过 + 计数）。
+    if (!isKnownOnDiskVersion(onDiskVersionOf(value)))
+        return false;
+    if (e.type !== "ask" &&
+        e.type !== "reply" &&
+        e.type !== "note" &&
+        e.type !== "close" &&
+        e.type !== "outcome")
+        return false;
+    if (typeof e.at !== "number" || !Number.isFinite(e.at))
+        return false;
+    if (e.from !== undefined && typeof e.from !== "string")
+        return false;
+    if (e.correlationId !== undefined && typeof e.correlationId !== "string")
+        return false;
+    if (e.text !== undefined && typeof e.text !== "string")
+        return false;
+    if (e.outcome !== undefined && e.outcome !== "answered" && e.outcome !== "unanswered" && e.outcome !== "unreachable")
+        return false;
+    if (e.cause !== undefined && typeof e.cause !== "string")
+        return false;
+    if (e.peer !== undefined && typeof e.peer !== "string")
+        return false;
+    if (e.elapsedMs !== undefined && typeof e.elapsedMs !== "number")
+        return false;
+    return true;
+}
+/**
+ * 协作线程存储（**追加式日志**）。
+ *
+ * 落盘位置：`<agentDir>/proactive/threads/<agentSegment(agentId)>/<threadId>.jsonl`，
+ * 每行一个 JSON 事件（**按 agent 隔离** —— G-R1）。
+ *
+ * 设计要点：
+ * - **只追加、不重写** —— 没有读-改-写窗口，并发追加不会丢行
+ *   （`appendFileSync` 单次写，行长 < PIPE_BUF 视为原子追加）；
+ * - **每个 agent 各有一份本地线程日志**（路径含 agentId 段 —— G-R1）——
+ *   轮次上限由**各接收方独立强制**，上界保守（不依赖任何共享可写状态）；
+ * - **坏行跳过并计数** —— 外部可写目录的容错，与 mailbox 的 `corrupt/` 策略同源，
+ *   但这里不隔离文件（只跳过 + 计数），绝不抛错（宿主对未捕获异常直接 exit(1)）。
+ */
+export class ThreadStore {
+    agentDir;
+    agentId;
+    threadId;
+    now;
+    constructor(opts) {
+        this.agentDir = opts.agentDir;
+        this.agentId = opts.agentId;
+        this.threadId = opts.threadId;
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * 线程日志文件绝对路径：**`threads/<agentSegment>/<threadSegment>.jsonl`**（G-R1）。
+     *
+     * agentId 段是**必需**的：规格 §6.4「计数归属：各接收方独立（每个 agent 各有一份本地线程日志）」。
+     * 旧路径（`threads/<threadSegment>.jsonl`，无 agent 段）会让同机多个 agent **共用**一份日志 →
+     * 轮次互相污染（实测 rounds() = 2，应为 1）。段名用 `agentSegment()`（与 `mailbox/<seg>/`、
+     * `processed/<seg>/` 同一约定，`src/envelope.ts` 是跨模块唯一真源）。
+     */
+    path() {
+        return path.join(this.agentDir, "proactive", "threads", agentSegment(this.agentId), `${threadSegment(this.threadId)}.jsonl`);
+    }
+    /**
+     * **旧路径**（G-R1 修复前）：`<agentDir>/proactive/threads/<threadSegment>.jsonl`。
+     *
+     * 取舍：**只读新路径，旧路径的历史数据一律不读**（不迁移、不合并）。
+     * 理由：旧文件里混着**多个 agent** 的事件，无法按 agent 拆分 —— 读它就是重新引入串扰
+     * （G-R1 要消灭的正是这个）。代价：修复前累计的轮次数**归零**（上限从 4 轮重新开始计），
+     * 旧文件**原样留在磁盘上**（不删、不改，可人工审计）。
+     */
+    legacyPath() {
+        return path.join(this.agentDir, "proactive", "threads", `${threadSegment(this.threadId)}.jsonl`);
+    }
+    /**
+     * 追加一条事件（单次 write，行尾补 `\n`）。
+     *
+     * **持久化分层（P-D4）**：线程事件属「**可重建的中间态**」→ **不 durable**（不 fsync）。
+     * - 理由：线程日志承载的是「审计 + 轮次计数」；丢了最坏是轮次上限判定偏差（多跑几轮），
+     *   **不会丢消息、不会丢用户排期**；而每条事件都 fsync 会把同步落盘加到**每条消息**的路径上。
+     * - 形态：只追加（`appendFileSync`），不写 tmp、不 rename —— 追加的半截行由读方跳过
+     *   （`staleLines` 计数），不隔离文件、绝不抛错。
+     * - 权限：文件显式 `chmod 0600`（规范 P0：同机其它进程不该读）。
+     */
+    append(event) {
+        const file = this.path();
+        try {
+            ensureDir(path.dirname(file));
+        }
+        catch {
+            // 目录建不出来时下面写会失败；不抛裸异常，交由宿主兜底
+        }
+        const full = { ...event, at: event.at ?? this.now() };
+        fs.appendFileSync(file, `${JSON.stringify(full)}\n`, "utf8");
+        // 线程日志属「同机其它进程不该读」的落盘面 → 0600（规范 P0）。
+        chmodQuiet(file, PROACTIVE_FILE_MODE);
+    }
+    /**
+     * 读取历史事件（坏行跳过）。
+     * `limit` 给出时只返回**最近** `limit` 条。
+     */
+    history(limit) {
+        const { events } = this.read();
+        if (limit === undefined || limit >= events.length)
+            return events;
+        return events.slice(events.length - limit);
+    }
+    /**
+     * 轮次计数 = **已完成的往返数**（一次 ask + 其对应 reply 才算 1 轮）。
+     *
+     * 只数 `reply` 事件（`ask` / `note` / `close` 都不计）：
+     * - `ask` 事件在**收到提问**时就写入 —— 提问若还没被回答，它**不占**轮次额度（P-1）；
+     * - `reply` 事件只在**回信投递成功**后写入 —— 投递失败的回信不虚增轮次（Minor-4）。
+     */
+    rounds() {
+        return this.read().events.filter((e) => e.type === "reply").length;
+    }
+    /** 是否已达轮次上限（`rounds() >= maxRounds`，默认 4 轮往返）。 */
+    shouldStop(maxRounds = DEFAULT_MAX_ROUNDS) {
+        return this.rounds() >= maxRounds;
+    }
+    /** 追加 `close` 事件（线程结束）。 */
+    close(text) {
+        this.append({ type: "close", text });
+    }
+    /** 坏行计数（供审计）。 */
+    staleLines() {
+        return this.read().stale;
+    }
+    // ---- 内部实现 ----
+    /** 读盘并解析；文件缺失/读失败 → 空列表；坏行跳过并计数（绝不抛出）。 */
+    read() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.path(), "utf8");
+        }
+        catch {
+            return { events: [], stale: 0 };
+        }
+        const events = [];
+        let stale = 0;
+        for (const line of raw.split("\n")) {
+            if (line.trim().length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                stale++;
+                continue;
+            }
+            if (!isThreadEvent(parsed)) {
+                stale++;
+                continue;
+            }
+            events.push(parsed);
+        }
+        return { events, stale };
+    }
+}