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

package/build/extensions/proactive.js

@@ -0,0 +1,2508 @@
+/**
+ * pi-proactive extension entry (M3 集成层：生命周期 / 唯一 tick / 命令面 / 任务表接线).
+ *
+ * 接线清单：
+ *   - `session_start` → 重新捕获 ctx/pi → 构造 TaskStore（resolveAgentDir()）与 Scheduler
+ *     （注入 store/trigger/guard/agentId）→ 起**唯一** 1s tick；
+ *   - tick（唯一定时器）→ `await scheduler.tick()` + 空闲判定/触发；
+ *   - `session_shutdown` → 幂等清理（tick 停止、scheduler 停止、状态栏清除、终端输入退订）；
+ *   - 代理活动事件（`agent_start`/`agent_end`/`tool_execution_*`/`message_end`）→ 刷新
+ *     「最近任何活动」空闲基线（IDLEFIX）；`input` 事件只认真人输入（扩展注入不刷新基线）。
+ *   - 命令面 `/proactive`：status | on | off | test | tasks | cancel <id> | idle on|off。
+ *
+ * 跨进程协作（M4i 接线）：
+ *   - `session_start` → 注册表注册（agentId/cwd/capabilities/transport）+ socket 通道 + 邮箱 + 30s 心跳；
+ *   - 1s tick（**不 await**）→ 邮箱扫描（后台）→ 认领 → 按 intent 走 Trigger 投递（来源 `proactive:peer`）；
+ *   - socket 通道 → 同一条入站路径（与邮箱**共用同一个 SeenSet** → 同一 id 只处理一次）；
+ *   - 模型工具 `message_agent` → 解析对端 → 跨进程投递 → 回执如实区分 8 种状态；
+ *   - `kind:"ask"` → 模型回答后回送 `kind:"reply"`（correlationId 原样带回、threadId 继承）。
+ *
+ * 约束：
+ *   - **唯一 tick**：不起第二个定时器 —— 调度由本文件的 1s tick 驱动 `scheduler.tick()`；
+ *   - **不重叠弹窗**：一次 fireIdle 未完成（Promise pending）时不再发起下一次；
+ *   - **来源前缀**：入口只传裸 body，前缀唯一由 `src/trigger.ts` 添加（避免双前缀）；
+ *   - **异常隔离**：tick / 命令处理 / 调度回调全部 try/catch（宿主 uncaughtException → process.exit(1)）。
+ */
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { Type } from "typebox";
+import { PROACTIVE_FILE_MODE, chmodQuiet, defaultConfig, ensureDir, hardenProactivePermissions, loadConfig, resolveAgentDir, saveEnabled, ConfigValidationError } from "../src/config.js";
+import { ActivityTracker } from "../src/activity.js";
+import { Guard } from "../src/guard.js";
+import { Trigger } from "../src/trigger.js";
+import { Lineage } from "../src/lineage.js";
+import { collectHealth } from "../src/health.js";
+import { effectiveIdleDetect, evaluateIdle, fireIdle } from "../src/idle.js";
+import { Scheduler } from "../src/scheduler.js";
+import { TaskStore } from "../src/task-store.js";
+import { AskLedger, PeerLifecycle, PeerResponder, PeerWatch, TIMEOUT_NOTICE_MARKER, buildDrainReplies, buildTellEnvelope, humanOriginLabel, parseTellCommand, resolveTellTarget, resolveTrustedHumanSenders, } from "../src/peer.js";
+import { shutdownSpawnedPeers, spawnPeer, } from "../src/peer-spawn.js";
+import { DEFAULT_MAX_ROUNDS, ThreadStore } from "../src/thread.js";
+import { createStrictSenderPolicy, makeAgentId, makeSessionAgentId, Registry } from "../src/registry.js";
+import { SeenSet } from "../src/dedupe.js";
+import { Mailbox, gcStaleTemporaries } from "../src/mailbox.js";
+import { createEnvelope, nextHop } from "../src/envelope.js";
+import { writeToMailbox } from "../src/outbox.js";
+import { deliverCrossProcess, startSocketServer, } from "../src/socket.js";
+import { createScheduledTask, dispatchProactiveCommand, errText, formatHumanGatedNotice, formatIdleDecision, formatScheduleResult, queryPeerDirectory, SUBCOMMANDS, } from "../src/commands.js";
+const TICK_MS = 1000;
+/**
+ * 本机 GC 周期（ms）：规范 §6 阈值表「每次启动 + 每 1 小时」。
+ *
+ * GC 的**责任方 = `<proactiveDir>` 持有者**（即本进程）。
+ */
+const GC_INTERVAL_MS = 3_600_000;
+/** 上次 GC 的时刻（ms；0 = 还没跑过）。 */
+let lastGcAt = 0;
+/**
+ * 归档/注册表条目的**保留窗口**（ms）：规范 §6 阈值表
+ * 「expired/ corrupt/ failed/ processed/ · 每 24 小时 · 年龄 > 7 天 → 删除」。
+ */
+const ARCHIVE_RETENTION_MS = 7 * 24 * 3_600_000;
+export function runGc(agentDir, store, deps) {
+    const registry = deps?.registry ?? peerRegistry;
+    const mailbox = deps?.mailbox ?? peerMailbox;
+    try {
+        const removed = gcStaleTemporaries(agentDir);
+        if (removed.length > 0)
+            console.error(`[proactive] GC：回收 ${removed.length} 个残留 tmp`);
+    }
+    catch (err) {
+        console.error("[proactive] GC（残留 tmp）失败:", err);
+    }
+    try {
+        const claims = store?.sweepStaleClaims() ?? 0;
+        if (claims > 0)
+            console.error(`[proactive] GC：回收 ${claims} 个失效的任务认领`);
+    }
+    catch (err) {
+        console.error("[proactive] GC（任务认领）失败:", err);
+    }
+    // P-D7：注册表条目的增长上限（不在场且超期 → 删除；在线条目绝不删）。
+    try {
+        const entries = registry?.sweepStaleEntries() ?? 0;
+        if (entries > 0)
+            console.error(`[proactive] GC：回收 ${entries} 个不在场的注册表条目`);
+    }
+    catch (err) {
+        console.error("[proactive] GC（注册表条目）失败:", err);
+    }
+    // P-D7：归档目录（expired/ corrupt/ failed/ processed/）的清理责任方 ——
+    // `Mailbox.cleanup()` 此前在生产代码里**从未被调用**（磁盘无限增长）。
+    try {
+        const cleaned = mailbox?.cleanup({ olderThanMs: ARCHIVE_RETENTION_MS });
+        if (cleaned && cleaned.removed > 0) {
+            console.error(`[proactive] GC：清理 ${cleaned.removed} 个归档文件（> 7 天）`);
+        }
+    }
+    catch (err) {
+        console.error("[proactive] GC（归档清理）失败:", err);
+    }
+}
+const STATUS_KEY = "proactive";
+/** 状态栏节流：内容未变时最多每 5s 更新一次（避免每秒刷一条 setStatus 噪声）。 */
+const STATUS_THROTTLE_MS = 5000;
+/**
+ * agentId：`<name>#<host>#<sessionId>`（**会话稳定** —— 跨进程重启不变）。
+ *
+ * 形态说明：
+ * - 有 `sessionId`（宿主 `ctx.sessionManager.getSessionId()`）→ `<name>#<host>#<sessionId>`
+ *   —— 跨进程重启**不变**、会话之间**唯一** → 「对端离线时消息落盘待其上线」才成立（V-03 F1）；
+ * - 没有 `sessionId`（宿主未提供）→ 退回 `<name>#<host>#<pid>`（进程级唯一，能力退化但不报错）。
+ *
+ * 不得再用常量 `"local"` —— 否则同机多会话共享同一身份 → `scope:"session"` 的旧任务（无 `ownerSessionId`）
+ * 会被多个会话各投递一次（V-02 Major-2）。`PI_PROACTIVE_AGENT_ID` 保留为显式覆盖（测试 / 调试用）。
+ *
+ * agentId 现在只用于 **peer 寻址 / global 任务认领 / 旧任务兜底**；
+ * `scope:"session"` 的归属以**会话**（`ownerSessionId`）为准。
+ */
+/**
+ * 本会话在注册表里的**注册名**。
+ *
+ * 缺省 = 当前工作目录的 basename（既有行为）。
+ * `PI_PROACTIVE_AGENT_NAME` 可覆盖 —— **被创建的对端用它拿到一个专属名字**
+ * （否则同一 cwd 起的两个会话同名 → 按名字寻址有歧义，见协议 §2.3）。
+ */
+export function resolveAgentName(env = process.env) {
+    const override = env.PI_PROACTIVE_AGENT_NAME;
+    if (override !== undefined && override !== "")
+        return override;
+    return path.basename(process.cwd());
+}
+/**
+ * 本会话的**角色**（KK-10 作用域）：`coordinator`（协调者，会主动 watch）/
+ * `worker`（执行者，只被 watch、不主动问）/ 缺省 = 不限定角色。
+ */
+export function resolvePeerRole(env = process.env) {
+    const raw = env.PI_PROACTIVE_ROLE;
+    if (raw === "coordinator")
+        return "coordinator";
+    if (raw === "worker")
+        return "worker";
+    return undefined;
+}
+/**
+ * 本会话的 **watch 名单**（KK-10 作用域）：`PI_PROACTIVE_WATCH_PEERS=<agentId,...>`。
+ *
+ * 名单**随会话**（不是全局配置）→ 问询量从 O(N²) 降回 O(实际配对数)。
+ * 缺省 / 空 = 不限定（保持既有行为）。
+ */
+export function resolveWatchList(env = process.env) {
+    const raw = env.PI_PROACTIVE_WATCH_PEERS;
+    if (raw === undefined || raw === "")
+        return [];
+    return raw
+        .split(",")
+        .map((x) => x.trim())
+        .filter((x) => x !== "");
+}
+export function resolveAgentId(env = process.env, pid = process.pid, sessionId) {
+    if (env.PI_PROACTIVE_AGENT_ID)
+        return env.PI_PROACTIVE_AGENT_ID;
+    const name = resolveAgentName(env);
+    const host = os.hostname();
+    return sessionId ? makeSessionAgentId(name, host, sessionId) : makeAgentId(name, host, pid);
+}
+/**
+ * 本进程的 agentId。
+ *
+ * **可变**：宿主只有到了 `session_start` 才给得出 `sessionId` → 那时才按会话重算
+ * （跨进程重启稳定的会话形态）。在此之前是 pid 形态（退化但不报错）。
+ */
+let AGENT_ID = resolveAgentId();
+/**
+ * 取当前会话 id（跨进程重启稳定）。
+ *
+ * 宿主不提供 `sessionManager` 或调用失败 → 返回 `undefined`（此时新建任务不带 `ownerSessionId`，
+ * 调度器退回按进程归属兜底；日志如实记录，不静默吞掉）。
+ */
+export function resolveSessionId(ctx) {
+    try {
+        const id = ctx?.sessionManager?.getSessionId?.();
+        return typeof id === "string" && id !== "" ? id : undefined;
+    }
+    catch (err) {
+        console.error("[proactive] 取 sessionId 失败:", err);
+        return undefined;
+    }
+}
+let currentCtx;
+let currentPi;
+let currentTrigger;
+/** 统一事件流（血缘）：「因」（触发原因）+「果」（结果记账），per-agent 只追加 JSONL。 */
+let currentLineage;
+/** 最近一次「由主动投递引发的回合」的来源（供派生任务绑定 `triggeredBy`）。 */
+let currentTurnSource;
+let currentStore;
+let currentScheduler;
+/** 当前会话 id（宿主 `ctx.sessionManager.getSessionId()`）→ **跨进程重启稳定**（session 作用域归属依据）。 */
+let currentSessionId;
+let config = safeConfig();
+let tracker = new ActivityTracker({ idleDetect: config.idleDetect });
+let guard = new Guard(config);
+/**
+ * 代理是否正在工作（模型回合进行中）—— IDLEFIX：触发前必须确认「代理已交回控制权」。
+ *
+ * 与宿主 `ctx.isIdle()` 取**或**：宿主信号是权威，但它的语义由宿主版本决定；
+ * 我们自己数回合/工具链 → 即使宿主的忙闲信号偏窄，**长工具链**也不会被漏判成空闲。
+ */
+let agentRunActive = false;
+/** 正在执行的工具数（长工具链）—— 同上。 */
+let activeToolCount = 0;
+/** 上一次写入状态栏的内容指纹（`enabled|reason`）与时刻（用于节流）。 */
+let lastStatusKey = "";
+let lastStatusAt = 0;
+let tickTimer;
+/** 正在进行的空闲触发（Promise pending）—— 用于避免 askUser 弹窗叠加。 */
+let idleFirePending;
+// ---- 跨进程协作（M4i） ----
+/** 跨进程消息的来源标记（模型据此区分「来自对端 agent」与本地触发）。 */
+export const PEER_CUSTOM_TYPE = "proactive:peer";
+/** 心跳周期（ms）：30s（**不是 1s** —— 心跳太密会无谓写盘）。 */
+const HEARTBEAT_MS = 30_000;
+/**
+ * 等待模型回答（ask → reply 闭环）的**上界**（ms）：10 分钟。
+ *
+ * Major-2：过期**不等于丢弃** —— ① 请求方会收到一条「等待超时」通知（过期必须对请求方可见）；
+ * ② 迟到的回答**仍会回信**（正文标注「已超过等待时限」）→ 闭环在「回答来得慢」这一正常场景下
+ * 也不静默断裂。上界仍有（10 分钟）→ 不会无限期挂起陈旧提问。
+ */
+const PEER_ANSWER_TIMEOUT_MS = 600_000;
+/**
+ * 自注入消息的**标记串**（P-4）。
+ *
+ * 宿主把自定义消息转成 role:"user" 的普通用户消息（**没有 customType**）→ 只能靠内容识别
+ * 「是不是自己注入的」。旧实现用**正文子串**（正文是否包含对端提问正文）→ 用户随后说了同样正文
+ * （如对端问「继续」、用户说「继续做第 3 步」）就被误判成自注入 → 回信**漏标【歧义归因】**。
+ *
+ * 可靠做法：注入时在内容里放一个**不可混淆的标记串**（每次注入一个随机 uuid），
+ * 识别时**精确匹配该标记本身**（而不是匹配用户可能的正文）。
+ */
+const INJECTION_MARKER_PREFIX = "[proactive-inject:";
+/** 最近若干次注入的标记串（有界：只留最近 16 条）。 */
+const injectionMarkers = [];
+/**
+ * 已被宿主「input(source:"extension")」事件**认领**的标记串（X7 · R-2）。
+ *
+ * 含义：宿主把我们的自定义消息转成了 role:"user" 的普通用户消息（**丢了 customType**），
+ * 并且**先**发了一次 `input` 事件（source="extension"）→ 这条消息**确定是我们注入的**。
+ * 这是「自己注入的消息」与「用户原样复制了整段转录」之间**唯一可区分的信号**：
+ * - 认领过的标记串 → 随后出现的同文本消息 = **我们的回声**（不得当成用户发言）；
+ * - 没被认领的标记串 → 出现在用户消息里 = **用户复制**（当成用户发言 → 宁可多标歧义）。
+ */
+const claimedInjectionMarkers = new Set();
+/** peer watch 扫描周期（ms）：注册表读盘不必每秒做。 */
+const PEER_WATCH_INTERVAL_MS = 30_000;
+/** 本 agent 的注册表（在场 / 忙闲 / 心跳）。 */
+let peerRegistry;
+/** 本 agent 的收件箱（文件邮箱）。 */
+let peerMailbox;
+/** socket 通道句柄。 */
+let peerSocket;
+/** socket 通道启动中的 promise（shutdown 时必须等它落地再关，否则会漏掉句柄）。 */
+let peerSocketStarting;
+/** 心跳定时器（独立于 1s tick → 不阻塞 tick）。 */
+let heartbeatTimer;
+/** 邮箱扫描是否正在进行（防重入）。 */
+let peerScanBusy = false;
+/**
+ * 逐条 reply 归因器（M5a）：入站 `ask` 登记 pending → 模型回答归因 → 回信。
+ * **按 pending 逐条归因**，不再用「取下一条 assistant 文本」的队列（那会把用户自己的回合当回答）。
+ */
+let peerResponder;
+/**
+ * ASKLOOP：提问方的 ask 账本（已发出的 ask → 回信配对 → 结局 → **决定还问不问**）。
+ *
+ * 语义闭环在**收讫侧**（KK-7）：没有「已答 / 未答 / 不可达」状态时，提问方只会一直问
+ * （实测 196 问 / 3 答）。频率护栏只是最后一道防线，**替代不了**语义闭环。
+ */
+let askLedger;
+/** peer 生命周期状态机（创建 → 就绪 → 可交互 → 排空 → 死亡；墓碑记下线时间与原因）。 */
+let peerLifecycle;
+/** peer watch（跨会话空闲协作）：空闲 peer 询问进度。 */
+let peerWatch;
+/** 线程日志存储缓存（线程键 → ThreadStore）。 */
+const threadStores = new Map();
+/** peer watch 扫描节流（ms）：注册表读盘不必每秒做。 */
+let lastPeerWatchAt = 0;
+/**
+ * 最近一次**配置校验错误**（拼错的配置项 → 必须让用户看见，不得静默忽略）。
+ *
+ * 通道限制：配置加载发生在宿主给出 `ctx` 之前 → 先存起来，
+ * 由 `session_start`（拿得到 `ctx.ui.notify`）呈现给用户（stderr 亦有一份）。
+ */
+let pendingConfigError;
+function safeConfig() {
+    try {
+        pendingConfigError = undefined;
+        return loadConfig();
+    }
+    catch (err) {
+        if (err instanceof ConfigValidationError) {
+            // M8：未知配置项 → **报错并指名**（键名 + 文件路径 + 建议值）。
+            pendingConfigError = err.message;
+            console.error(err.message);
+        }
+        else {
+            console.error("[proactive] 配置加载失败:", err);
+        }
+        return defaultConfig();
+    }
+}
+/**
+ * 记一次**代理活动**（模型回合 / 工具调用 / 助手消息落定）→ 刷新「最近任何活动」空闲基线。
+ *
+ * 为什么必须记（IDLEFIX，依据 `pi-proactive/docs/idle-ground-truth.md` §6.2 前提 1）：
+ * 原先空闲基线只被「用户输入」刷新 → 代理连续干活 12 分钟会被记成「用户已经 12 分钟没说话」
+ * → 工作刚结束就误触发（实测：工作期误触发率 20.07% → 3.01%）。
+ *
+ * 失败不得冒泡（宿主 uncaughtException → process.exit(1)）。
+ */
+function markAgentActivity() {
+    try {
+        tracker.mark("agent");
+    }
+    catch {
+        /* ignore: 活动标记失败不得影响宿主 */
+    }
+}
+/** 幂等清理：重复调用不抛错。 */
+function stopTick() {
+    if (tickTimer !== undefined) {
+        clearInterval(tickTimer);
+        tickTimer = undefined;
+    }
+}
+const scheduleTaskParameters = Type.Object({
+    prompt: Type.String({ description: "任务提示词" }),
+    intent: Type.Optional(Type.Union([Type.Literal("wake"), Type.Literal("interrupt"), Type.Literal("queue"), Type.Literal("notify")], {
+        description: "投递意图，默认 wake",
+    })),
+    askUser: Type.Optional(Type.Boolean({ description: "触发时是否向用户提问（仅本地）" })),
+    when: Type.Optional(Type.String({ description: "触发时间：时长（10m）/ 时刻（18:30）/ ISO 8601；缺省按 10m 处理" })),
+});
+/**
+ * 模型工具面（NATURAL）：**按能力域分组**的 4 个域工具（不是 13 个细碎工具）。
+ *
+ * 参数名与命令面一致（`when` / `content` / `id` / `peer` / `scope` / `limit` / `name` / `all` …），
+ * `action` 的取值就是命令面的子命令名 → 语义同源、可机检。
+ */
+/** 查询域：查对端 / 看历史 / 看状态 / 看任务 / 只读体检 / 看手册 / 查配置清单。 */
+const proactiveQueryParameters = Type.Object({
+    action: Type.Union([
+        Type.Literal("peers"),
+        Type.Literal("history"),
+        Type.Literal("status"),
+        Type.Literal("tasks"),
+        Type.Literal("doctor"),
+        Type.Literal("help"),
+        Type.Literal("config"),
+    ], { description: "查询动作（与 /proactive 子命令同名）" }),
+    name: Type.Optional(Type.String({ description: "peers：名字子串过滤" })),
+    all: Type.Optional(Type.Boolean({ description: "peers：是否包含离线对端" })),
+    idle: Type.Optional(Type.Boolean({ description: "peers：只看空闲对端" })),
+    detail: Type.Optional(Type.String({ description: "peers：只看这一个 agentId" })),
+    scope: Type.Optional(Type.Union([Type.Literal("peer"), Type.Literal("me")], { description: "history：范围（对端 / 我）" })),
+    peer: Type.Optional(Type.String({ description: "history：按对端 agentId 过滤" })),
+    limit: Type.Optional(Type.String({ description: "history：条数（1-200 的整数）" })),
+    json: Type.Optional(Type.Boolean({ description: "doctor / config：输出 JSON" })),
+});
+/**
+ * 进度 / ETA 查询（任务卡 ETA · E3）。
+ *
+ * 与人侧 `/proactive progress` **同源同口径**：同一个分派（`dispatchProactiveCommand`）→
+ * 同一份快照 → 两侧正文逐字一致。
+ */
+const progressQueryParameters = Type.Object({});
+/** 排程域：定时 / 定点 / 周期 / 取消。 */
+const proactiveScheduleParameters = Type.Object({
+    action: Type.Union([Type.Literal("in"), Type.Literal("at"), Type.Literal("every"), Type.Literal("cancel")], { description: "排程动作（与 /proactive 子命令同名）" }),
+    when: Type.Optional(Type.String({ description: "in/at/every：触发时间（时长 10m / 时刻 18:30）" })),
+    content: Type.Optional(Type.String({ description: "in/at/every：任务内容" })),
+    id: Type.Optional(Type.String({ description: "cancel：任务 id" })),
+});
+/** 对端协作域：给对端下指令（tell）/ 创建对端（spawn，受存活上限）。 */
+const proactivePeerParameters = Type.Object({
+    action: Type.Union([Type.Literal("tell"), Type.Literal("spawn")], { description: "对端动作（与 /proactive 子命令同名）" }),
+    peer: Type.Optional(Type.String({ description: "tell：目标对端（名字或 agentId）" })),
+    content: Type.Optional(Type.String({ description: "tell：指令内容" })),
+    kind: Type.Optional(Type.Union([Type.Literal("ask"), Type.Literal("task"), Type.Literal("notify")], {
+        description: "tell：指令类型（缺省 ask）",
+    })),
+    subject: Type.Optional(Type.String({ description: "tell：标题" })),
+    thread: Type.Optional(Type.String({ description: "tell：线程 id" })),
+    name: Type.Optional(Type.String({ description: "spawn：对端名字" })),
+});
+/**
+ * 管理域：总开关 / 空闲触发 / 自检。
+ *
+ * **全部属 human-gated**：工具可调用，但只回报「需人工确认」+ 可复制的人工指令，
+ * **不自行改全局开关**（brief-v4 §9.1：入口可达性 100%，执行自治按权限阶梯）。
+ */
+const proactiveManageParameters = Type.Object({
+    action: Type.Union([Type.Literal("on"), Type.Literal("off"), Type.Literal("idle"), Type.Literal("test")], { description: "管理动作（与 /proactive 子命令同名）" }),
+    state: Type.Optional(Type.Union([Type.Literal("on"), Type.Literal("off")], { description: "idle：开 / 关" })),
+});
+/**
+ * 命令面 / 模型工具面共用的运行期上下文（**同源接线的唯一注入点**）。
+ *
+ * 两处（`/proactive …` 命令与模型工具）都拿它去调 `dispatchProactiveCommand` →
+ * 同一能力只有一份实现；这里只负责「把运行期依赖递进去」，**不含任何业务判定**。
+ */
+function commandContext() {
+    return {
+        agentId: AGENT_ID,
+        ...(currentSessionId === undefined ? {} : { sessionId: currentSessionId }),
+        runtimeMode: currentCtx?.mode ?? "rpc",
+        getConfig: () => config,
+        setConfig: (next) => {
+            // peerWatch 是运行期字段（toggleEnabled 返回的是窄类型）→ 显式带回。
+            config = { ...next, peerWatch: config.peerWatch };
+        },
+        snapshot: () => tracker.snapshot(),
+        setIdleDetect: (detect) => {
+            if (currentCtx)
+                tracker.setIdleDetect(detect);
+        },
+        evaluateIdle: () => evaluateIdle({ config, tracker, guard, runtimeMode: currentCtx?.mode }),
+        store: currentStore,
+        registry: peerRegistry,
+        lineage: currentLineage,
+        inFlightForPeer,
+        recentEventsHint,
+        helpText: formatHelp,
+        collectHealth: () => collectHealth(resolveAgentDir()),
+        persistEnabled: (on) => saveEnabled(on),
+        spawnPeerSession: async (name) => {
+            const result = await spawnPeer({
+                ...(name === undefined ? {} : { name }),
+                ...(peerRegistry === undefined ? {} : { registry: peerRegistry }),
+                onLog: (m) => console.error(`[proactive] ${m}`),
+            });
+            if (!result.ok) {
+                return {
+                    ok: false,
+                    phase: result.phase,
+                    reason: result.reason,
+                    ...(result.error === undefined ? {} : { error: result.error }),
+                };
+            }
+            peerLifecycle?.transition(result.peer.agentId, result.peer.state);
+            return { ok: true, name: result.peer.name, agentId: result.peer.agentId, state: result.peer.state };
+        },
+        tellPeer: (args) => runTell(args),
+        selfTest: () => runSelfTest(),
+    };
+}
+/**
+ * 模型工具 → **命令面同一个分派**（NATURAL 同源硬要求）。
+ *
+ * 工具参数先拼成**命令面同名的参数**，再交给 `dispatchProactiveCommand` →
+ * 工具与命令跑的是同一段实现，产出逐字相同的结果（不可能漂移）。
+ */
+async function dispatchTool(args, details) {
+    try {
+        const out = await dispatchProactiveCommand(args, commandContext(), { origin: "model" });
+        return {
+            content: [{ type: "text", text: out.text }],
+            // `command` = 实际下发给分派的命令串（与命令面同形 → 可对照「工具走了哪条命令」）。
+            details: { ...details, level: out.level, command: args },
+        };
+    }
+    catch (err) {
+        const msg = `proactive: ${errText(err)}`;
+        return { content: [{ type: "text", text: msg }], details: { ...details, level: "error", error: msg } };
+    }
+}
+/**
+ * human-gated 能力的闸门说明（**单一真源**：与能力目录里的能力 id 逐字一致）。
+ *
+ * 口径（brief-v4 §9.1）：模型入口**可达**（工具可调用），但**不得自主执行** →
+ * 只回报「需人工确认」+ 一条可复制的人工指令。
+ */
+function humanGatedNotice(action, state) {
+    switch (action) {
+        case "on":
+            return {
+                capabilityId: "global-toggle",
+                humanCommand: "/proactive on",
+                reason: "主动性总开关是全局开关，属人工闸门（模型不得擅自改变用户的全局开关）。",
+            };
+        case "off":
+            return {
+                capabilityId: "global-toggle",
+                humanCommand: "/proactive off",
+                reason: "主动性总开关是全局开关，属人工闸门（模型不得擅自改变用户的全局开关）。",
+            };
+        case "idle":
+            return {
+                capabilityId: "idle-trigger-toggle",
+                humanCommand: `/proactive idle ${state ?? "on|off"}`,
+                reason: "空闲触发开关会改变打扰用户的时机，属人工闸门。",
+            };
+        default:
+            return {
+                capabilityId: "self-test",
+                humanCommand: "/proactive test",
+                reason: "自检会向用户会话强制投递一条消息，属诊断类人工闸门。",
+            };
+    }
+}
+/** human-gated 工具的回执（**不改任何全局状态**，只给人工指令）。 */
+function manageTool(action, state) {
+    const notice = humanGatedNotice(action, state);
+    return {
+        content: [{ type: "text", text: formatHumanGatedNotice(notice) }],
+        details: { action, humanGated: true, humanCommand: notice.humanCommand, capabilityId: notice.capabilityId },
+    };
+}
+export default function proactiveExtension(pi) {
+    pi.registerTool({
+        name: "schedule_task",
+        label: "Schedule Task",
+        description: "预约一个稍后触发的任务（真正落库到任务表，到点由调度器投递）。" +
+            "when 支持时长（10m）、时刻（18:30）或 ISO 时间；缺省按 10m 处理。",
+        parameters: scheduleTaskParameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const store = currentStore;
+            if (!store) {
+                const msg = "proactive: session_start 尚未触发，任务表未初始化，未创建任务。";
+                return { content: [{ type: "text", text: msg }], details: { created: false, error: msg } };
+            }
+            // **同源**：与命令面 `/proactive in|at|every` 共用 `createScheduledTask`（同一段解析/校验/落库）。
+            const result = createScheduledTask({
+                store,
+                config,
+                agentId: AGENT_ID,
+                // 会话归属（跨进程重启稳定）；宿主未提供 sessionId 时留空 → 退回进程归属兜底。
+                ...(currentSessionId === undefined ? {} : { sessionId: currentSessionId }),
+                form: "auto",
+                when: params.when,
+                content: params.prompt,
+                ...(params.intent === undefined ? {} : { intent: params.intent }),
+                // **不**继承 idleTrigger.askUser（M5c RP-11 M-2）：定时任务默认 askUser=false
+                // （定时投递不该弹框问用户）；只有模型显式登记 askUser:true 才问。
+                ...(params.askUser === undefined ? {} : { askUser: params.askUser }),
+                source: "model",
+                // **任务与触发源绑定（果）**：本次回合由哪一次主动投递引发？
+                // 没有主动投递引发（用户自己让模型排期）→ 不带该字段。
+                ...(currentTurnSource !== undefined ? { triggeredBy: currentTurnSource.eventId } : {}),
+            });
+            if (!result.ok) {
+                const msg = `proactive: ${result.error}`;
+                return { content: [{ type: "text", text: msg }], details: { created: false, error: msg } };
+            }
+            const task = result.task;
+            const text = formatScheduleResult(task, result.now, result.info);
+            return {
+                content: [{ type: "text", text }],
+                details: { created: true, taskId: task.id, dueAt: task.dueAt, schedule: task.schedule },
+            };
+        },
+    });
+    pi.registerTool({
+        name: "message_agent",
+        label: "Message Agent",
+        description: "给另一个正在运行的 agent 会话发消息（跨进程协作）。" +
+            "对端在线时走 socket 直达；不在线时消息落盘到对端邮箱，待其上线后处理。",
+        parameters: messageAgentParameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const registry = peerRegistry;
+            if (!registry) {
+                const msg = "proactive: 跨进程协作未初始化（session_start 尚未触发），未发送。";
+                return { content: [{ type: "text", text: msg }], details: { status: "error", error: msg } };
+            }
+            // 目标寻址：**在线优先，离线也能解析**（注册表保留离线条目）→ 离线时消息落盘待其上线。
+            let targetAgentId;
+            try {
+                targetAgentId = registry.resolve(params.to).agentId;
+            }
+            catch (err) {
+                // 解析失败：名字从未注册过（无从知道它的邮箱目录）→ 如实报错（**不是** rejected：
+                // 信封本身合法，rejected 只留给「信封非法」）。
+                // 若调用方给的是完整 agentId（含 "#"）→ 直接按该地址落盘，等对方上线即可取走。
+                if (params.to.includes("#")) {
+                    targetAgentId = params.to;
+                }
+                else {
+                    const msg = `proactive: 找不到目标 agent「${params.to}」：${errText(err)}`;
+                    return { content: [{ type: "text", text: msg }], details: { status: "error", error: msg } };
+                }
+            }
+            let envelope;
+            try {
+                // ASKLOOP：提问（kind=ask）**显式带 correlationId** → 被问方拿得到回信句柄，
+                // 回信原样带回它 → 提问方能把回信配回这条提问（闭环 + 结局记账）。
+                const kind = params.kind ?? "notify";
+                const correlationId = kind === "ask" ? `ask-${randomUUID()}` : undefined;
+                envelope = createEnvelope({
+                    from: AGENT_ID,
+                    to: targetAgentId,
+                    kind,
+                    intent: params.intent ?? "wake",
+                    subject: params.subject,
+                    body: params.body,
+                    threadId: params.threadId,
+                    ...(correlationId === undefined ? {} : { correlationId }),
+                });
+            }
+            catch (err) {
+                const msg = `proactive: 消息参数非法：${errText(err)}`;
+                return { content: [{ type: "text", text: msg }], details: { status: "rejected", error: msg } };
+            }
+            const ack = await deliverToPeer(targetAgentId, envelope);
+            // ASKLOOP：提问纳入账本 → 收到回信即记结局（answered / unanswered / unreachable）。
+            if (envelope.kind === "ask" && envelope.correlationId !== undefined) {
+                if (ack.status === "accepted" || ack.status === "duplicate") {
+                    askLedger?.recordAsk({
+                        peer: targetAgentId,
+                        correlationId: envelope.correlationId,
+                        threadKey: envelope.threadId,
+                    });
+                }
+                else {
+                    const event = askLedger?.noteUnreachable({
+                        peer: targetAgentId,
+                        correlationId: envelope.correlationId,
+                        threadKey: envelope.threadId,
+                        reason: `提问未送达（回执 ${ack.status}）`,
+                    });
+                    if (event)
+                        recordAskOutcome(event, envelope);
+                }
+            }
+            return {
+                content: [{ type: "text", text: receiptText(ack) }],
+                details: { status: ack.status, id: ack.id, path: ack.path, target: targetAgentId },
+            };
+        },
+    });
+    pi.registerTool({
+        name: "list_peers",
+        label: "List Peers",
+        description: "列出本机可见的其它 agent 对端（名字 / agentId / 在场状态 / 心跳龄 / 能力标签 / 在途任务数 / 传输方式），" +
+            "可按名字、状态、能力过滤。**只读**：不产生任何对外行为。" +
+            "发消息前先查它（先查后发），别盲发 —— 离线对端现在打扰它不合适。",
+        parameters: listPeersParameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            // 只读 → 协作层没起来也能查（注册表是落盘事实源，`resolveAgentDir()` 与协作层同一目录）。
+            const registry = peerRegistry ?? new Registry({ agentDir: resolveAgentDir() });
+            // **同源**：与命令面 `/proactive peers --…` 共用 `queryPeerDirectory`（同一套过滤与字段）。
+            const { directory, text } = queryPeerDirectory({
+                registry,
+                selfAgentId: AGENT_ID,
+                inFlight: inFlightForPeer,
+                query: {
+                    ...(params.name === undefined ? {} : { name: params.name }),
+                    ...(params.status === undefined ? {} : { status: params.status }),
+                    ...(params.capability === undefined ? {} : { capability: params.capability }),
+                    ...(params.includeOffline === undefined ? {} : { includeOffline: params.includeOffline }),
+                },
+            });
+            return {
+                content: [{ type: "text", text }],
+                details: {
+                    peers: directory.peers,
+                    ambiguous: directory.ambiguous,
+                    includeOffline: directory.includeOffline,
+                },
+            };
+        },
+    });
+    // ---- 模型工具面（NATURAL）：4 个域工具，全部走**命令面同一个分派** ----
+    // 工具参数先拼成命令面同名的参数 → `dispatchProactiveCommand` → 与命令逐字同结果。
+    pi.registerTool({
+        name: "proactive_query",
+        label: "Proactive Query",
+        description: "查询域：查对端（peers）/ 看主动行为历史（history）/ 看状态（status）/ 看任务（tasks）/ 只读体检（doctor）/ 看命令手册（help）/ 查配置清单（config）。" +
+            "**只读**：不产生任何对外行为。",
+        parameters: proactiveQueryParameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const parts = [params.action];
+            if (params.action === "peers") {
+                if (params.all === true)
+                    parts.push("--all");
+                if (params.idle === true)
+                    parts.push("--idle");
+                if (params.name !== undefined)
+                    parts.push("--name", params.name);
+                if (params.detail !== undefined)
+                    parts.push("--detail", params.detail);
+            }
+            else if (params.action === "history") {
+                if (params.scope !== undefined)
+                    parts.push(params.scope);
+                if (params.peer !== undefined)
+                    parts.push(params.peer);
+                // 只接受十进制整数（命令面的 history 也只认数字位置参数）。
+                if (params.limit !== undefined && /^\d+$/.test(params.limit))
+                    parts.push(params.limit);
+            }
+            else if ((params.action === "doctor" || params.action === "config") && params.json === true) {
+                parts.push("--json");
+            }
+            return dispatchTool(parts.join(" "), { action: params.action });
+        },
+    });
+    pi.registerTool({
+        name: "progress_query",
+        label: "Progress Query",
+        description: "查项目进度与 ETA：返回**区间 + 置信度 + 归因 + 阻塞项**（不给单点数字）。" +
+            "口径唯一（scripts/progress-clock.py），与人侧 `/proactive progress` 同源同口径、逐字一致。" +
+            "**只读**：不产生任何对外行为。",
+        parameters: progressQueryParameters,
+        async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+            // **同源**：与人侧 `/proactive progress` 走同一个分派 → 同一份快照 → 逐字一致。
+            return dispatchTool("progress", { capability: "progress-eta" });
+        },
+    });
+    pi.registerTool({
+        name: "proactive_schedule",
+        label: "Proactive Schedule",
+        description: "排程域：定时（in）/ 定点（at）/ 周期（every）/ 取消（cancel）。" +
+            "落到真实任务表，到点由调度器投递；与命令面 `/proactive in|at|every|cancel` 同源。",
+        parameters: proactiveScheduleParameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const parts = [params.action];
+            if (params.action === "cancel") {
+                if (params.id !== undefined)
+                    parts.push(params.id);
+            }
+            else {
+                if (params.when !== undefined)
+                    parts.push(params.when);
+                if (params.content !== undefined)
+                    parts.push(params.content);
+            }
+            return dispatchTool(parts.join(" "), { action: params.action });
+        },
+    });
+    pi.registerTool({
+        name: "proactive_peer",
+        label: "Proactive Peer",
+        description: "对端协作域：给对端下指令（tell）/ 创建对端会话（spawn，受同时存活数上限）。" +
+            "tell 的目标解析与回执三态与命令面 `/proactive tell` 完全同源。",
+        parameters: proactivePeerParameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const parts = [params.action];
+            if (params.action === "tell") {
+                if (params.peer !== undefined)
+                    parts.push(params.peer);
+                if (params.kind !== undefined)
+                    parts.push("--kind", params.kind);
+                if (params.subject !== undefined)
+                    parts.push("--subject", params.subject);
+                if (params.thread !== undefined)
+                    parts.push("--thread", params.thread);
+                if (params.content !== undefined)
+                    parts.push(params.content);
+            }
+            else if (params.name !== undefined) {
+                parts.push(params.name);
+            }
+            return dispatchTool(parts.join(" "), { action: params.action });
+        },
+    });
+    pi.registerTool({
+        name: "proactive_manage",
+        label: "Proactive Manage",
+        description: "管理域：主动性总开关（on/off）、空闲触发开关（idle）、自检（test）。" +
+            "这些能力属 human-gated：调用只会回报「需人工确认」并给出可复制的人工指令，**不会**自行改动全局开关。",
+        parameters: proactiveManageParameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            return manageTool(params.action, params.state);
+        },
+    });
+    pi.registerCommand("proactive", {
+        description: `proactive 主动机制：${SUBCOMMANDS}`,
+        handler: async (args, cmdCtx) => {
+            const parts = (args ?? "").trim().split(/\s+/).filter(Boolean);
+            const sub = parts[0] ?? "status";
+            // 执行扩展命令 = 用户在终端上操作 → 刷新空闲基线
+            // （否则用户正在敲命令却被判为「已离开」并被主动打扰；V-02 Minor-1）。
+            try {
+                tracker.mark("user");
+            }
+            catch {
+                // ignore: 活动标记失败不得影响命令处理
+            }
+            // 命令面子命令 → **能力 id**（与 `docs/project/capability-catalog.json` 逐字一致）。
+            //
+            // 为什么需要这张表：能力是**语义**，命令/工具只是入口；这张表是「命令面 ↔ 能力目录」的
+            // 连接点（命令失败时日志点名是哪条能力坏了 → 可归因），门禁 G15 核对
+            // 「分派支持的子命令 ↔ 本表 ↔ 能力目录」三方一致（→ 目录与实现不会各说各话）。
+            const capabilityId = (() => {
+                switch (sub) {
+                    case "status":
+                        return "session-status";
+                    case "on":
+                    case "off":
+                        return "global-toggle";
+                    case "peers":
+                        return "peer-directory";
+                    case "spawn":
+                        return "peer-spawn";
+                    case "tell":
+                        return "peer-message";
+                    case "test":
+                        return "self-test";
+                    case "tasks":
+                        return "task-list";
+                    case "cancel":
+                        return "task-cancel";
+                    case "in":
+                    case "at":
+                    case "every":
+                        return "task-schedule";
+                    case "idle":
+                        return "idle-trigger-toggle";
+                    case "history":
+                        return "activity-history";
+                    case "doctor":
+                        return "health-diagnose";
+                    case "progress":
+                        return "progress-eta";
+                    case "help":
+                        return "manual-help";
+                    case "config":
+                        return "config-inspect";
+                    default:
+                        return "unknown";
+                }
+            })();
+            try {
+                // **同一个分派**（NATURAL 同源硬要求）：模型工具面也走这里 →
+                // 同一能力只有一份实现，命令与工具不可能漂移。
+                const out = await dispatchProactiveCommand(args, commandContext());
+                if (out.level === "error")
+                    cmdCtx.ui.notify(out.text, "error");
+                else
+                    cmdCtx.ui.notify(out.text);
+            }
+            catch (err) {
+                console.error(`[proactive] 命令失败（能力 ${capabilityId}）:`, err);
+                cmdCtx.ui.notify(`proactive: ${errText(err)}`, "error");
+            }
+        },
+    });
+    // ---- 代理活动（IDLEFIX）：模型回合 / 工具调用 → 刷新「最近任何活动」空闲基线 ----
+    //
+    // 空闲判定改用「距最近**任何**活动」的基线（见 `src/activity.ts`）：
+    // 代理在干活时不能被当成「用户离开了」。
+    // 同一批事件还给出「代理是否已交回控制权」的独立信号（回合进行中 / 工具链未结束）。
+    pi.on("agent_start", () => {
+        agentRunActive = true;
+        markAgentActivity();
+    });
+    pi.on("agent_end", () => {
+        agentRunActive = false;
+        markAgentActivity();
+        // 回合结束 → 本回合不再算「由主动投递引发」（下一回合新建的任务不再绑定 triggeredBy）。
+        currentTurnSource = undefined;
+    });
+    pi.on("tool_execution_start", () => {
+        activeToolCount += 1;
+        markAgentActivity();
+    });
+    pi.on("tool_execution_end", () => {
+        activeToolCount = Math.max(0, activeToolCount - 1);
+        markAgentActivity();
+    });
+    // 模型回答回流（ask → reply 闭环）：**逐条归因**（M5a）——
+    // 有 pending 才归因（无 pending → 丢弃，绝不把用户自己的回合当回答）；
+    // 多个 pending 时归给最早未决并如实标注「歧义归因」。
+    pi.on("message_end", (event) => {
+        try {
+            // 代理活动（IDLEFIX）：助手消息落定 = 代理刚干完活 → 刷新「最近任何活动」基线。
+            // （放在 peerResponder 早退之前：没有对端会话时也该记。）
+            if (messageRole(event.message) === "assistant") {
+                markAgentActivity();
+                // **结果记账（果）**：模型在窗口内产生新消息 → 这次主动推进「被采纳」。
+                try {
+                    currentLineage?.noteResponse("model");
+                }
+                catch (err) {
+                    console.error("[proactive] 记事件流失败:", err);
+                }
+            }
+            const responder = peerResponder;
+            if (!responder)
+                return;
+            // **用户发言**（Major-3）：提问登记之后用户又说了话 → 这之后的回答**无法判别**
+            // 是在回答对端还是在回答用户 → 归因必须标为歧义（不得当作确定答案回过去）。
+            if (messageRole(event.message) === "user") {
+                if (!isInjectedPeerMessage(event.message)) {
+                    // 正文里带注入标记串 → 用户可能**原样复制**了注入正文（R-2）：
+                    // 无法区分「自注入的回显」与「用户复制」→ **宁可多标歧义**，也不漏标。
+                    if (containsInjectionMarker(event.message)) {
+                        console.error("[proactive] 用户消息里含注入标记串（疑似原样复制了注入正文）→ 按「用户发言」处理（宁可多标歧义）");
+                    }
+                    responder.noteUserInput(Date.now());
+                }
+                return;
+            }
+            const text = extractAssistantText(event.message);
+            if (!text)
+                return;
+            const plan = responder.onAssistantText(text);
+            if (!plan)
+                return;
+            void sendPeerReply(plan);
+        }
+        catch (err) {
+            console.error("[proactive] 处理 message_end 失败:", err);
+        }
+    });
+    // 空闲基线（IDLEFIX）：真人输入刷新**用户基线**与「最近任何活动」基线；
+    // 代理活动（回合/工具调用，见上）只刷新「最近任何活动」基线；
+    // **扩展注入的消息（含本插件自己的投递）不刷新任何基线** —— 防自锁。
+    pi.on("input", (event) => {
+        try {
+            // 用户在终端里说话 → 之后的回答归因存疑（Major-3）。
+            // **只认真人输入**：`source === "extension"` 是扩展自己注入的消息（本插件注入的
+            // peer 提问就走这条路）→ 不得当成「用户发言」，否则每条回信都会被误标为歧义。
+            const source = event?.source;
+            if (source === "extension") {
+                // **扩展注入的消息不是用户输入**（IDLEFIX）：
+                // 既不刷新用户基线，也不刷新「最近任何活动」基线 ——
+                // 否则插件会被**自己的投递**无限推迟下一次触发（自锁）。
+                // `mark("self")` 语义 = 「插件自投递」→ 两个基线都不刷新。
+                tracker.mark("self");
+                // **这是我们注入的消息**（宿主把自定义消息转成了 role:"user"）→
+                // 认领它的标记串 → 随后出现的同文本消息 = 我们的回声（不得当成用户发言）；
+                // 用户**原样复制**同一段文本时标记串已被一次性消费 → 判为「用户发言」（R-2）。
+                claimInjectionMarker(event?.text);
+            }
+            else {
+                // 真人输入 → 刷新用户基线与「最近任何活动」基线。
+                tracker.mark("user");
+                peerResponder?.noteUserInput(Date.now());
+                // **结果记账（果）**：真人输入（不是扩展注入）→ 用户对这次主动推进有回应。
+                try {
+                    currentLineage?.noteResponse("user");
+                }
+                catch (err) {
+                    console.error("[proactive] 记事件流失败:", err);
+                }
+            }
+        }
+        catch {
+            // ignore: activity tracking must never break input handling
+        }
+    });
+    pi.on("session_start", async (_event, ctx) => {
+        try {
+            // pi/ctx go stale after session replacement or reload -> re-capture them here.
+            currentPi = pi;
+            currentCtx = ctx;
+            config = safeConfig();
+            // 「代理是否已交回控制权」= 宿主忙闲 **或** 我们自己的回合/工具链计数。
+            // 宿主 `ctx.isIdle()`（本机 pi 1.3.0）覆盖整个 agent run（含工具执行），
+            // 我们再叠一层自己的计数 → 宿主语义变窄时长工具链仍不会漏判。
+            agentRunActive = false;
+            activeToolCount = 0;
+            tracker = new ActivityTracker({
+                idleDetect: config.idleDetect,
+                isBusy: () => !ctx.isIdle() || agentRunActive || activeToolCount > 0,
+            });
+            guard = new Guard(config);
+            currentSessionId = resolveSessionId(ctx);
+            if (currentSessionId === undefined) {
+                console.error("[proactive] 宿主未提供 sessionId → session 作用域任务退回按进程归属兜底");
+            }
+            // agentId 按**会话**派生（跨进程重启稳定）——必须在此处（拿到 sessionId 之后）重算。
+            AGENT_ID = resolveAgentId(process.env, process.pid, currentSessionId);
+            // 统一事件流（血缘）：per-agent 只追加 JSONL（<agentDir>/proactive/lineage/<agentId>.jsonl）。
+            currentLineage = new Lineage({ agentDir: resolveAgentDir(), agentId: AGENT_ID });
+            currentTurnSource = undefined;
+            currentTrigger = new Trigger({
+                pi,
+                ctx,
+                guard,
+                config,
+                agentId: AGENT_ID,
+                lineage: currentLineage,
+                // 投递成功 → 记住这次投递（派生任务据此绑定 triggeredBy）。
+                onDelivered: (info) => {
+                    currentTurnSource = info;
+                },
+            });
+            currentStore = new TaskStore({
+                agentDir: resolveAgentDir(),
+                agentId: AGENT_ID,
+                // P-D5：未知版本等「用户必须知道」的事件 → **用户可见通道**（宿主 ui.notify），
+                // 不能只在 stderr 打一行（宿主通常不展示 stderr → 用户的排期静默停止而无人知晓）。
+                notify: (message) => {
+                    try {
+                        ctx.ui.notify(message, "error");
+                    }
+                    catch {
+                        // 用户可见通道不可用 → 提示已留在 store 的降级队列（stderr 亦有一份）
+                    }
+                },
+            });
+            // 本机 GC（启动一次）：残留 tmp（P-D2）+ 失效的 global 任务认领（P-D9）。
+            lastGcAt = Date.now();
+            runGc(resolveAgentDir(), currentStore);
+            // 调度由本文件的唯一 tick 驱动（scheduler.tick()），**不**再起第二个定时器。
+            currentScheduler = new Scheduler({
+                store: currentStore,
+                // **触发原因落盘（因）**：排期投递的 cause = schedule + 任务依据。
+                trigger: withTriggerCause(currentTrigger, "schedule", (msg) => scheduleBasis(msg.id)),
+                guard,
+                agentId: AGENT_ID,
+                // session 作用域归属按**会话**（跨进程重启稳定），不再按进程（pid）。
+                sessionId: currentSessionId,
+                // 主动性总开关贯穿调度器：enabled=false 时不投递任何到期任务（V-02 Major-1）。
+                enabled: () => config.enabled,
+            });
+            // A：空闲检测档位（非 TUI 降级为 input-only）；只有 terminal 档才订阅终端输入。
+            const detect = effectiveIdleDetect(config.idleDetect, ctx.mode);
+            tracker.setIdleDetect(detect);
+            if (detect === "terminal") {
+                tracker.attachTerminalInput(ctx.ui.onTerminalInput(() => {
+                    tracker.handleTerminalInput();
+                    return undefined;
+                }));
+            }
+            // 跨进程协作层（注册表 + socket 通道 + 邮箱 + 心跳）；失败不阻断会话。
+            await stopPeerLayer();
+            await startPeerLayer(resolveAgentDir());
+            // P-D7：协作层就绪后再跑一次 GC —— 注册表条目清理与归档清理需要它们存在。
+            lastGcAt = Date.now();
+            runGc(resolveAgentDir(), currentStore);
+            stopTick();
+            tickTimer = setInterval(() => {
+                void tick();
+            }, TICK_MS);
+            void tick();
+        }
+        catch (err) {
+            console.error("[proactive] session_start 失败:", err);
+        }
+    });
+    pi.on("session_shutdown", async () => {
+        try {
+            stopTick();
+            agentRunActive = false;
+            activeToolCount = 0;
+            // **drain**（优雅退出前把在途 ask 逐条回「我下线了」）—— 必须在关通道之前。
+            await drainPeerLayer();
+            await stopPeerLayer();
+            // **不留孤儿**：被创建的对端会话逐个终止并等待退出。
+            const stopped = await shutdownSpawnedPeers();
+            if (stopped > 0)
+                console.error(`[proactive] 已终止 ${stopped} 个被创建的对端进程（不留孤儿）`);
+            currentScheduler?.stop();
+            currentScheduler = undefined;
+            currentTrigger = undefined;
+            currentLineage = undefined;
+            currentTurnSource = undefined;
+            currentStore = undefined;
+            currentSessionId = undefined;
+            // 退订终端输入（setIdleDetect("off") 会解除订阅）。
+            tracker.setIdleDetect("off");
+            currentCtx?.ui.setStatus(STATUS_KEY, undefined);
+            currentCtx = undefined;
+            currentPi = undefined;
+        }
+        catch (err) {
+            console.error("[proactive] session_shutdown 失败:", err);
+        }
+    });
+}
+/**
+ * 唯一 tick：调度 + 空闲判定/触发。
+ *
+ * 异常整体隔离（宿主对未捕获异常直接 `process.exit(1)`）。
+ */
+async function tick() {
+    try {
+        const ctx = currentCtx;
+        if (!ctx)
+            return;
+        // 主动性总开关关闭（/proactive off）→ 定时投递与空闲触发**均不发生**（V-02 Major-1）。
+        const enabled = config.enabled;
+        // 本机 GC（启动 + 每 1 小时，规范 §6 阈值表）：残留 tmp（P-D2）+ 失效任务认领（P-D9）。
+        const gcNow = Date.now();
+        if (gcNow - lastGcAt >= GC_INTERVAL_MS) {
+            lastGcAt = gcNow;
+            runGc(resolveAgentDir(), currentStore);
+        }
+        // 调度（到期任务投递）—— 调度器内部自带异常隔离。
+        if (enabled)
+            await currentScheduler?.tick();
+        // 结算判定窗口（到窗口末仍无回应 → outcome=ignored；判定只由事件流里的时间事实推出）。
+        try {
+            currentLineage?.sweep(Date.now());
+        }
+        catch (err) {
+            console.error("[proactive] 结算判定窗口失败:", err);
+        }
+        // 入站邮箱扫描：**后台**执行（不 await）—— 扫描 + 投递是重活，不得阻塞 1s tick。
+        void runPeerScan();
+        // 空闲触发：一次未完成时不再发起下一次（否则 askUser 弹窗会叠加）。
+        const trigger = currentTrigger;
+        if (enabled && trigger && idleFirePending === undefined) {
+            idleFirePending = fireIdle({
+                config,
+                tracker,
+                guard,
+                // **决策落账**：每次决策（含不触发）都进事件流 → `/proactive history` 可见。
+                lineage: currentLineage,
+                // **触发原因落盘（因）**：空闲投递的 cause = idle + 判定依据（已空闲时长 / 阈值 / 档位）。
+                // 用上面已收窄的局部 `trigger`（`currentTrigger` 是可变模块变量，TS 无法在此收窄）
+                trigger: withTriggerCause(trigger, "idle", () => idleBasis()),
+                agentId: AGENT_ID,
+                runtimeMode: ctx.mode,
+            })
+                .then((result) => {
+                // 用**最终** outcome 更新状态栏。
+                setStatus(ctx, result.decision);
+            })
+                .catch((err) => {
+                console.error("[proactive] fireIdle 失败:", err);
+            })
+                .finally(() => {
+                idleFirePending = undefined;
+            });
+        }
+        // 未触发时用判定原因填状态栏。
+        setStatus(ctx, evaluateIdle({ config, tracker, guard, runtimeMode: ctx.mode }));
+    }
+    catch (err) {
+        console.error("[proactive] tick 失败:", err);
+    }
+}
+/** 写状态栏（失败不得冒泡）。 */
+function setStatus(ctx, decision) {
+    try {
+        const text = `proactive ${config.enabled ? "on" : "off"} · ${formatIdleDecision(decision)}`;
+        // 关键状态变化（开关 / 判定原因）立即更新；否则节流到 ≥5s 一次
+        // （V-02 Minor-3：每秒一条 setStatus 打到 stdout 是噪声）。
+        const key = `${config.enabled}|${decision.reason}`;
+        const now = Date.now();
+        if (key === lastStatusKey && now - lastStatusAt < STATUS_THROTTLE_MS)
+            return;
+        lastStatusKey = key;
+        lastStatusAt = now;
+        ctx.ui.setStatus(STATUS_KEY, text);
+    }
+    catch {
+        // ignore: 状态栏失败不得让宿主崩溃
+    }
+}
+/**
+ * `/proactive test`：强制投递一次自检消息。
+ *
+ * 强制语义：不看 `config.enabled`（`/proactive off` 之后也要能自检），也不受冷却/频率上限阻塞
+ * （用一份宽松的护栏配置另建 Trigger；静默时段仍然尊重）。
+ */
+async function runSelfTest() {
+    if (!currentPi || !currentCtx || !currentTrigger) {
+        return { text: "proactive: session_start 尚未触发，无法投递", level: "error" };
+    }
+    const forcedConfig = {
+        ...config,
+        limits: { ...config.limits, minGapMs: 0, maxPerHour: 1000 },
+    };
+    const forced = new Trigger({
+        pi: currentPi,
+        ctx: currentCtx,
+        guard: new Guard(forcedConfig),
+        config: forcedConfig,
+        agentId: AGENT_ID,
+        lineage: currentLineage,
+    });
+    const envelope = {
+        id: randomUUID(),
+        from: AGENT_ID,
+        to: AGENT_ID,
+        kind: "notify",
+        intent: "wake",
+        subject: "proactive test",
+        body: "自检消息：投递链路测试",
+        hop: 0,
+        maxHops: 3,
+        ttlMs: 60_000,
+        priority: "normal",
+        createdAt: Date.now(),
+    };
+    const outcome = await forced.deliverToModel(envelope, "wake", { cause: { type: "manual" } });
+    return { text: `proactive: ${testOutcomeText(outcome)}`, level: "info" };
+}
+/** 自检结果文案（依据 Trigger 的最终 outcome）。 */
+function testOutcomeText(outcome) {
+    switch (outcome) {
+        case "delivered":
+            return "已强制投递一次测试消息（intent=wake；强制投递：不受 /proactive on/off 开关与冷却/频率上限影响）";
+        case "notified":
+            return "已强制通知一次测试消息（未启动模型回合；强制投递：不受 /proactive on/off 开关与冷却/频率上限影响）";
+        case "deferred":
+            return "测试消息被护栏推迟（静默时段）——本次未投递";
+        case "dropped":
+            return "测试消息被护栏丢弃（超出频率上限）——本次未投递";
+        default:
+            return "测试消息投递失败（详见插件日志）";
+    }
+}
+// ================================================================ 跨进程协作（M4i）
+/**
+ * 启动跨进程协作层：注册表 + socket 通道 + 文件邮箱 + 心跳。
+ *
+ * - **单一 SeenSet**：socket 通道与邮箱**共用同一个**去重集合
+ *   （`processed/<agentId>/seen.json`）→ 同一 id 经两条路径到达也只处理一次；
+ * - socket 端点被占用（另一个进程还在）→ 记日志并降级为「文件邮箱」传输，不阻断会话；
+ * - 所有异常都在内部隔离（宿主 uncaughtException → process.exit(1)）。
+ */
+async function startPeerLayer(agentDir) {
+    try {
+        const seen = new SeenSet({ agentDir, agentId: AGENT_ID });
+        peerRegistry = new Registry({ agentDir });
+        // **P0 权限收紧（启动时一次）**：既有落盘面（目录 0700 / 文件 0600）在此收紧 ——
+        // umask 只削弱、**既有文件不会自动改** → 必须显式 chmod。失败**不静默**（逐条上报）。
+        try {
+            const hardened = hardenProactivePermissions(agentDir);
+            if (hardened.failures.length > 0) {
+                console.error(`[proactive] 落盘面权限收紧失败 ${hardened.failures.length} 项（见上方逐条报错）—— 落盘面仍可能对同 UID 其它进程可见`);
+            }
+        }
+        catch (err) {
+            console.error("[proactive] 落盘面权限收紧异常（不静默）：", err);
+        }
+        peerRegistry.register({
+            agentId: AGENT_ID,
+            name: resolveAgentName(),
+            pid: process.pid,
+            host: os.hostname(),
+            cwd: process.cwd(),
+            sessionId: currentSessionId,
+            capabilities: ["message_agent"],
+            transport: "socket",
+        });
+        // **P1 来源校验（默认严格、不可关闭、不可放宽）**：`from` 不可自填即采信 ——
+        // 未在注册表登记 / 主机不符的发送方 → 拒收（不投递）+ 可审计归档。
+        // **strict 档**（具名 `createStrictSenderPolicy()`）：注册表白名单 ＋ 主机一致 —— 产品层不可关闭、
+        // 不可放宽。旧名 `createRegistrySenderPolicy()` 是**同一个函数的别名**（协议正文 §8.1 证据 2
+        // 的实现位置指针指向本文件里的这个名字）→ 别名与具名档必须保持同一语义。
+        const senderPolicy = createStrictSenderPolicy({ agentDir, registry: peerRegistry });
+        peerMailbox = new Mailbox({ agentDir, agentId: AGENT_ID, seen, senderPolicy });
+        // 姿态可见：启动时明确告知「来源校验已启用」（用户/运维可据此判断部署是否受保护）。
+        console.error("[proactive] 来源校验：已启用（注册表逐字命中 + 主机一致）—— 未注册或跨主机的发送方一律拒收");
+        // 逐条 reply 归因器（入站 ask 登记 pending → 模型回答归因 → 回信）。
+        peerResponder = new PeerResponder({ agentId: AGENT_ID, expectReplyWithinMs: PEER_ANSWER_TIMEOUT_MS });
+        // 提问方的 ask 账本（ASKLOOP）：已问 / 已答 / 未答 / 不可达 + 停止追问的状态机。
+        askLedger = new AskLedger({ waitMs: PEER_ANSWER_TIMEOUT_MS });
+        // peer watch（跨会话空闲协作）：默认关闭（不装上就不打扰别人）。
+        // **作用域**（KK-10）：配置是全局共享的 → 每个会话都 watch 对方 → 问询量 O(N²)。
+        // 两个**随会话**的旋钮把问询量降回 O(实际配对数)：
+        // ① `PI_PROACTIVE_ROLE=worker` → 本会话**只被 watch、不主动问**（执行者）；
+        // ② `PI_PROACTIVE_WATCH_PEERS=<agentId,...>` → 本会话**只问名单里的对端**（协调者）。
+        // 两者都缺省 = 保持既有行为（由 `enabled` + `afterIdleMs` 决定）。
+        peerWatch = new PeerWatch({
+            enabled: config.peerWatch.enabled,
+            afterIdleMs: config.peerWatch.afterIdleMs,
+            selfAgentId: AGENT_ID,
+            role: resolvePeerRole(),
+            watchList: resolveWatchList(),
+        });
+        // peer 生命周期状态机（创建 / 死亡 / 墓碑）。
+        peerLifecycle = new PeerLifecycle();
+        threadStores.clear();
+        peerSocketStarting = startSocketServer({
+            agentId: AGENT_ID,
+            agentDir,
+            seen,
+            // **P1 来源校验**（与邮箱路径同一策略、同一口径）。
+            senderPolicy,
+            // onMessage 只回 void/Promise<void>：投递结果由内部处理，ack 不承担业务语义。
+            onMessage: async (envelope) => {
+                const outcome = await deliverPeerEnvelope(envelope);
+                if (outcome === "deferred" || outcome === "dropped" || outcome === "failed") {
+                    // **未投递 → 绝不回 accepted（谎报「已送达」）**（Blocker-1）：
+                    // ① 先落盘到本机收件箱（**不丢消息** → 之后由邮箱扫描重试）；
+                    // ② 再抛错 → socket 回执如实变成 error（对端据此知道「尚未送达」）。
+                    const file = writeToMailbox(AGENT_ID, envelope, { agentDir });
+                    throw new Error(`入站消息未投递（${outcome}），已落盘待重试：${file}`);
+                }
+            },
+        })
+            .then((handle) => {
+            peerSocket = handle;
+            // P-D11：socket 端点 0600、端点目录 0700（规范 P0：同机其它进程不该接入）。
+            try {
+                ensureDir(path.dirname(handle.path));
+                chmodQuiet(handle.path, PROACTIVE_FILE_MODE);
+            }
+            catch {
+                // 权限收紧失败不阻断通道
+            }
+            return handle;
+        })
+            .catch((err) => {
+            console.error("[proactive] socket 通道启动失败（降级为文件邮箱）：", err);
+            // 传输方式如实改写：在线通道不可用 → 只剩文件邮箱。
+            try {
+                peerRegistry?.register({
+                    agentId: AGENT_ID,
+                    name: resolveAgentName(),
+                    pid: process.pid,
+                    host: os.hostname(),
+                    cwd: process.cwd(),
+                    sessionId: currentSessionId,
+                    capabilities: ["message_agent"],
+                    transport: "file",
+                });
+            }
+            catch {
+                // 忽略：注册失败不影响会话
+            }
+            return undefined;
+        });
+        heartbeatTimer = setInterval(() => {
+            try {
+                peerRegistry?.heartbeat(AGENT_ID, {
+                    status: currentCtx?.isIdle() ? "idle" : "busy",
+                });
+            }
+            catch (err) {
+                console.error("[proactive] 心跳失败:", err);
+            }
+            try {
+                // ASKLOOP：未获回答的 ask 超时 → 结局 unanswered（并推进停止追问的状态机）。
+                for (const event of askLedger?.expire(Date.now()) ?? []) {
+                    recordAskOutcome(event);
+                }
+            }
+            catch (err) {
+                console.error("[proactive] ask 账本超时扫描失败:", err);
+            }
+            try {
+                // **死亡检测**：对端心跳过期（= 崩溃）→ 在途 ask **立即**回执「对端已死亡」
+                // （结局记 `unreachable`）→ **不再追问**该对端 → 注册表写下**墓碑**
+                // （下线时间 + 原因；条目保留，清理仍走既有 GC 阈值）。
+                detectDeadPeers();
+            }
+            catch (err) {
+                console.error("[proactive] 死亡检测失败:", err);
+            }
+            try {
+                // 过期 pending（Major-2）：过期 ≠ 丢弃 —— 通知请求方（过期必须可见），
+                // 且过期项被保留 → 迟到的回答仍会回信。
+                void expirePeerPending()
+                    .then((n) => {
+                    if (n > 0)
+                        console.error(`[proactive] ${n} 条 pending 已过期（已通知请求方；迟到回答仍会回信）`);
+                })
+                    .catch((err) => {
+                    console.error("[proactive] 清理过期 pending 失败:", err);
+                });
+            }
+            catch (err) {
+                console.error("[proactive] 清理过期 pending 失败:", err);
+            }
+            // peer watch（跨会话空闲协作）：与心跳同周期（30s），不新增定时器。
+            const now = Date.now();
+            if (now - lastPeerWatchAt >= PEER_WATCH_INTERVAL_MS) {
+                lastPeerWatchAt = now;
+                void runPeerWatch();
+            }
+        }, HEARTBEAT_MS);
+    }
+    catch (err) {
+        console.error("[proactive] 跨进程协作层启动失败:", err);
+    }
+}
+/**
+ * **死亡检测**：对端心跳过期（= 崩溃，没走到 `unregister()`）→
+ * ① 注册表写下**墓碑**（下线时间 + 原因；条目**保留** → 离线寻址成立，
+ *    清理仍走既有 GC 阈值 `sweepStaleEntries()`，**不造第二套保留策略**）；
+ * ② 在途 ask **立即**回执「对端已死亡」（AskLedger 记 `unreachable`）；
+ * ③ **不再追问**该对端（账本状态 → `stopped`，直到它重新开始工作）。
+ */
+function detectDeadPeers() {
+    const registry = peerRegistry;
+    if (registry === undefined)
+        return;
+    const candidates = new Set();
+    for (const entry of peerLifecycle?.list() ?? [])
+        candidates.add(entry.agentId);
+    for (const peer of askLedger?.outstandingPeers() ?? [])
+        candidates.add(peer);
+    if (candidates.size === 0)
+        return;
+    for (const entry of peerLifecycle?.detectDead(registry, [...candidates]) ?? []) {
+        const reason = entry.offlineReason ?? "心跳过期（可能崩溃）";
+        try {
+            registry.markDead(entry.agentId, reason, entry.offlineAt);
+        }
+        catch (err) {
+            console.error("[proactive] 写墓碑失败:", err);
+        }
+        const events = askLedger?.notePeerDead(entry.agentId, { reason: `对端已死亡（${reason}）` }) ?? [];
+        for (const event of events)
+            recordAskOutcome(event);
+        console.error(`[proactive] 对端已死亡 ${entry.agentId}：${reason}` +
+            `${events.length > 0 ? `（${events.length} 条在途提问已记 unreachable，不再追问）` : ""}`);
+    }
+}
+/**
+ * **drain**：优雅退出前把在途 ask **逐条**回「我下线了」。
+ *
+ * 两条腿：
+ * 1. **我欠答的 ask**（别人问我、我还没答）→ 给提问方回一条带 `PEER_OFFLINE_MARKER`
+ *    的回信 → 提问方据此记 `unreachable`（对方下线 ≠ 得到答案）。
+ * 2. **我发出的、还在等的 ask** → 结局记 `unreachable`（本会话下线 → 这条提问不会有答案了）。
+ *
+ * 必须在**关闭 socket 之前**做（回信要靠通道投递出去）。
+ */
+async function drainPeerLayer() {
+    try {
+        const pending = peerResponder?.pendingList() ?? [];
+        for (const reply of buildDrainReplies(pending, AGENT_ID)) {
+            try {
+                const ack = await deliverToPeer(reply.to, reply);
+                console.error(`[proactive] drain：已回「我下线了」给 ${reply.to}（回执 ${ack.status}）`);
+            }
+            catch (err) {
+                console.error(`[proactive] drain：回「我下线了」给 ${reply.to} 失败:`, err);
+            }
+        }
+    }
+    catch (err) {
+        console.error("[proactive] drain（回在途 ask）失败:", err);
+    }
+    try {
+        for (const peer of askLedger?.outstandingPeers() ?? []) {
+            for (const event of askLedger?.notePeerDead(peer, { reason: "本会话下线（提问未得到回答）" }) ?? []) {
+                recordAskOutcome(event);
+            }
+        }
+    }
+    catch (err) {
+        console.error("[proactive] drain（结清在途提问）失败:", err);
+    }
+}
+/**
+ * 停止跨进程协作层（幂等）：注销 + 关 socket + 停心跳 + 释放等待者。
+ *
+ * **必须 await**：socket 端点文件在 close 之后才会消失 —— 不等它关闭就重新 startPeerLayer
+ * 会撞上「端点已被占用」（同一 agentId → 同一端点路径）→ 会话重启后跨进程通道静默降级。
+ */
+async function stopPeerLayer() {
+    if (heartbeatTimer !== undefined) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = undefined;
+    }
+    try {
+        // 优雅退出：**保留**注册条目并标 status:"offline"（不删除）——
+        // 删了对端再发消息就变成「未找到 agent」→ 离线排队失效（V-03 F1）。
+        peerRegistry?.unregister(AGENT_ID);
+    }
+    catch (err) {
+        console.error("[proactive] 注销失败:", err);
+    }
+    // socket 启动是异步的：等它落地再关（否则会漏掉句柄 → 端点文件与 fd 残留）。
+    const starting = peerSocketStarting;
+    peerSocketStarting = undefined;
+    const handle = peerSocket;
+    peerSocket = undefined;
+    try {
+        const h = handle ?? (await starting);
+        await h?.close();
+        // 启动 promise 的 then 回调可能又把旧句柄写回 peerSocket → 这里清干净。
+        if (peerSocket === h)
+            peerSocket = undefined;
+    }
+    catch (err) {
+        console.error("[proactive] 关闭 socket 通道失败:", err);
+    }
+    peerResponder = undefined;
+    askLedger = undefined;
+    peerWatch = undefined;
+    peerLifecycle = undefined;
+    peerMailbox = undefined;
+    peerRegistry = undefined;
+}
+/**
+ * 记一条 ask 的**结局**（ASKLOOP · 规范 §6.5）。
+ *
+ * 落点：**与统一事件流同一套**——
+ * - 线程日志（既有落盘面，不是新面）：`type:"outcome"` + `cause`/`outcome`/`peer`/`elapsedMs`；
+ * - 转录审计（`appendEntry`）：人侧可见；
+ * - stderr 一行：日志里可查。
+ *
+ * 字段名与统一事件流同族（`at`≈`ts`、`type`、`cause`、相关 id）→ 统一事件流落地后
+ * 同一套读方即可消费，**不需要另造第二个面**。
+ */
+export function recordAskOutcome(event, env) {
+    try {
+        if (env !== undefined) {
+            const threadKey = event.threadId ?? threadKeyOf(env);
+            threadStoreFor(env, threadKey).append({
+                type: "outcome",
+                at: event.at,
+                cause: event.cause,
+                outcome: event.outcome,
+                correlationId: event.correlationId,
+                peer: event.peer,
+                elapsedMs: event.elapsedMs,
+                ...(event.reason === undefined ? {} : { text: event.reason }),
+            });
+        }
+        currentPi?.appendEntry(PEER_CUSTOM_TYPE, {
+            stage: "outcome",
+            outcome: event.outcome,
+            cause: event.cause,
+            correlationId: event.correlationId,
+            peer: event.peer,
+            elapsedMs: event.elapsedMs,
+            ...(event.reason === undefined ? {} : { reason: event.reason }),
+            agentId: AGENT_ID,
+            at: event.at,
+        });
+        console.error(`[proactive] ask 结局 ${event.outcome}（对端 ${event.peer}，耗时 ${event.elapsedMs}ms）${event.reason === undefined ? "" : `：${event.reason}`}`);
+    }
+    catch (err) {
+        console.error("[proactive] 记录 ask 结局失败:", err);
+    }
+}
+/**
+ * 过期 pending 的处理（Major-2）。
+ *
+ * - 过期**不等于丢弃**：请求方必须收到一条「等待超时」通知 —— 否则闭环静默断裂、请求方零信号；
+ * - 迟到的回答**仍会回信**（`PeerResponder` 保留过期 pending → 正文标注「已超过等待时限」）。
+ *
+ * @param now 时钟（测试可注入未来时刻；缺省 = 真实时间）。
+ * @returns 本次过期的条数。
+ */
+export async function expirePeerPending(now) {
+    const responder = peerResponder;
+    if (!responder)
+        return 0;
+    const expired = responder.expireStale(now);
+    for (const pending of expired) {
+        const minutes = Math.round(PEER_ANSWER_TIMEOUT_MS / 60_000);
+        const notice = createEnvelope({
+            from: AGENT_ID,
+            to: pending.requester,
+            kind: "reply",
+            intent: "queue",
+            subject: pending.subject ? `Re: ${pending.subject}` : undefined,
+            body: `${TIMEOUT_NOTICE_MARKER}本机未在 ${minutes} 分钟内回答该提问（提问已过等待上界）。若稍后仍会回答，将另行回信。`,
+            threadId: pending.threadId,
+            correlationId: pending.correlationId,
+        });
+        // 线程记一条 note（**不**计入轮次 —— 它不是回答）。
+        const threadKey = pendingThreadKeys.get(pendingKeyOf(pending));
+        if (threadKey)
+            appendThreadEvent(notice, "note", notice.body, threadKey);
+        try {
+            const ack = await deliverToPeer(pending.requester, notice);
+            console.error(`[proactive] 提问等待超时（${pending.requester}）：${describeAck(ack.status, ack.error ?? ack.path, ack.queuedReason)}`);
+        }
+        catch (err) {
+            console.error("[proactive] 发送等待超时通知失败:", err);
+        }
+    }
+    return expired.length;
+}
+/**
+ * 扫描本 agent 的邮箱并投递（**后台**执行，不阻塞 1s tick）。
+ *
+ * 语义：scan → claim（互斥）→ 按 intent 投递 → 成功 complete / 失败 release（可重试）。
+ * `deferred`（静默时段）与 `failed` 视为「本次没处理成」→ 退回收件箱重试。
+ */
+export async function runPeerScan() {
+    if (peerScanBusy)
+        return;
+    const mailbox = peerMailbox;
+    if (!mailbox)
+        return;
+    peerScanBusy = true;
+    try {
+        for (const envelope of mailbox.scan()) {
+            const claim = mailbox.claim(envelope);
+            if (!claim.claimed)
+                continue;
+            try {
+                const outcome = await deliverPeerEnvelope(envelope);
+                // **未投递（含 dropped）→ release（退回收件箱重试），绝不 complete**（Blocker-1）：
+                // complete = 归档为「已处理」→ 入站协作消息会凭空消失（永不重试）。
+                // X5：release 必须**带退避** —— 否则 1s tick 会把它每秒重新认领、重新投递、再次失败
+                //      → 重试风暴（协调者实测：defer 形态 4 轮扫描 = 4 次重试；failed 形态无时间上界）。
+                //      `deferred`/`dropped` 是**节流**（不计入失败上限）；`failed` 是错误（计入上限，
+                //      超过上限由邮箱归档到终态目录 `failed/`，不丢、可审计）。
+                if (outcome === "deferred" || outcome === "dropped" || outcome === "failed") {
+                    mailbox.release(envelope, { reason: outcome === "failed" ? "failed" : "throttled" });
+                    continue;
+                }
+                mailbox.complete(envelope);
+            }
+            catch (err) {
+                console.error("[proactive] 入站信封处理失败，退回邮箱重试:", err);
+                // 处理异常 = 投递失败 → 计入失败重试上限（超限归档到 failed/），并带退避。
+                mailbox.release(envelope, { reason: "failed" });
+            }
+        }
+    }
+    catch (err) {
+        console.error("[proactive] 邮箱扫描失败:", err);
+    }
+    finally {
+        peerScanBusy = false;
+    }
+}
+/**
+ * 单条入站信封的投递（socket 与邮箱**共用**这条路径）。
+ *
+ * - 来源标记 `proactive:peer`；
+ * - `kind:"ask"` → 投递后在**后台**等模型回答并回送 `kind:"reply"`
+ *   （**不**阻塞 ack：socket 回执超时只有 2s，等模型会把回执拖成 timeout → 重复投递）。
+ */
+async function deliverPeerEnvelope(envelope) {
+    const trigger = currentTrigger;
+    if (!trigger) {
+        console.error("[proactive] 入站信封无处投递（session_start 尚未触发）");
+        return "failed";
+    }
+    // 收件方校验：端点/收件箱是按 agent 分的，但信封的 `to` 才是权威地址 ——
+    // 不是给我的（且不是广播）→ 不投模型，只归档（outcome 用 notified：零 token、不占额度）。
+    if (envelope.to !== AGENT_ID && envelope.to !== "broadcast") {
+        console.warn(`[proactive] 入站信封地址不匹配（to=${envelope.to}），不投模型`);
+        return "notified";
+    }
+    // 收到对端的 reply → 该链路的 hop 计数归零（链路闭合，可再次询问）。
+    if (envelope.kind === "reply") {
+        peerWatch?.resetHop(envelope.from);
+        // ASKLOOP：**收讫即停** —— 配对未决 ask → 记结局（answered / unanswered）→ 不再追问。
+        const outcomeEvent = askLedger?.onReply(envelope) ?? null;
+        if (outcomeEvent) {
+            recordAskOutcome(outcomeEvent, envelope);
+            // 人侧发起的提问 → 回信**落到人眼前**（不等模型转述；模型侧同时收到注入）。
+            if (outcomeEvent.humanOrigin === true)
+                notifyHumanReply(envelope);
+        }
+        else {
+            // 配不上 → **不臆造**对应关系（迟到的回答 / 对不上号的回信）：只留日志。
+            console.error("[proactive] 收到无法配对的回信（迟到或对不上号），不产生结局记录");
+        }
+    }
+    // **自注入标记**（P-4）：注入内容里放一个不可混淆的标记串 → 之后能精确认出
+    // 「这条 role:user 消息是自己注入的」，而不用「正文是否包含对端提问正文」这类启发式。
+    const injectionMarker = createInjectionMarker();
+    // **人类发起标记**（人侧发指令）：如实标注这条是不是**人类直接下达**的。
+    // 「信不信」由收信侧的受信集合决定：受信 → 已验证；不受信 → 只说「对端声称」（不给特权）。
+    const originLabel = humanOriginLabel(envelope, resolveTrustedHumanSenders());
+    const marked = {
+        ...envelope,
+        customType: PEER_CUSTOM_TYPE,
+        body: `${originLabel === undefined ? "" : `${originLabel}\n`}${envelope.body}\n${injectionMarker}`,
+    };
+    rememberInjectionMarker(injectionMarker);
+    // **入站协作消息旁路「本机主动触发」的频率闸门**（Blocker-1）：
+    // 护栏管的是「我主动打扰用户」的额度；对端**主动发来**的协作消息不受它约束。
+    // 记账点仍在 Trigger 内（契约 §5「记账点唯一」）—— 调用方不得自行 check/record。
+    const outcome = await trigger.deliverToModel(marked, envelope.intent, {
+        inboundPeer: true,
+        // **触发原因落盘（因）**：对端请求的 cause = peer-request + 对端 id。
+        cause: { type: "peer-request", peer: envelope.from },
+    });
+    if (envelope.kind === "ask" && outcome === "delivered") {
+        // 登记 pending **必须在投递成功之后**（投递失败/被推迟 → 没有回答可归因）。
+        // 登记表满 → 记日志、不回信（不臆造一条对应关系）。
+        // 线程记账：ask **收到**（已成功投递给模型）记一条。
+        appendThreadEvent(envelope, "ask", envelope.body);
+        const pending = peerResponder?.onAsk(envelope) ?? null;
+        if (!pending) {
+            console.error("[proactive] pending 登记表已满或不可用，本次 ask 不回信（不臆造对应关系）");
+        }
+        else {
+            // 记住「这条 pending 的线程键」→ 回信落在同一线程（Minor-2：ask 没带 id 时也成立）。
+            // 键 = threadId（缺失才回退 correlationId）—— 不得用 correlationId 作键（P-5）。
+            pendingThreadKeys.set(pendingKeyOf(pending), threadKeyOf(envelope));
+            // 有界：只保留最近若干条（长期会话不得内存无界增长）。
+            while (pendingThreadKeys.size > 256) {
+                const oldest = pendingThreadKeys.keys().next();
+                if (oldest.done)
+                    break;
+                pendingThreadKeys.delete(oldest.value);
+            }
+        }
+    }
+    return outcome;
+}
+/**
+ * 线程键：优先 `threadId`；没有就用 `correlationId`；再没有用信封 id。
+ *
+ * 目的：保证「一条 ask 与它的 reply 落在同一个线程文件里」——否则轮次上限会各算各的，
+ * 环路防护（shouldStop）就形同虚设。
+ */
+function threadKeyOf(env) {
+    if (env.threadId)
+        return env.threadId;
+    if (env.correlationId)
+        return env.correlationId;
+    // **稳定兜底**（Minor-2）：既没 threadId 也没 correlationId 时，按**协作对**（无序）成键
+    // → 同一对端之间的往返落在同一线程 → 轮次上限（防 A→B→A 环路）不再失效。
+    return `pair:${[env.from, env.to].sort().join("~")}`;
+}
+/**
+ * pending → 线程键（回信必须落在 ask 的同一线程；ask 没带 id 时靠它兜底）。
+ *
+ * **键 = threadId（缺失时才回退 correlationId）**（P-5）：
+ * 用 correlationId 作键时，同一 correlationId 但不同 threadId 的两条 ask 会互相覆盖
+ * → 先到的 pending 的回信被记到**后者的线程**（轮次虚增 + 另一线程漏计）。
+ */
+const pendingThreadKeys = new Map();
+/** pending 的映射键：优先 threadId，缺失才回退 correlationId（P-5）。 */
+function pendingKeyOf(pending) {
+    return pending.threadId ?? pending.correlationId;
+}
+/** 回信的线程键：优先用「这条 pending 登记时的线程键」，否则退回信封自身推导。 */
+function threadKeyOfPlan(plan) {
+    return pendingThreadKeys.get(pendingKeyOf(plan.pending)) ?? threadKeyOf(plan.reply);
+}
+/**
+ * 线程日志存储（按线程键缓存；线程文件路径
+ * `<agentDir>/proactive/threads/<agentSegment(AGENT_ID)>/<threadKey>.jsonl`）。
+ *
+ * **agentId 段是必需的**（G-R1）：规格 §6.4「各接收方独立」—— 本 agent 只数**自己**记下的回信，
+ * 不得把同机其它 agent 的回信算进自己的轮次。
+ */
+function threadStoreFor(env, threadKey) {
+    const key = threadKey ?? threadKeyOf(env);
+    let store = threadStores.get(key);
+    if (!store) {
+        store = new ThreadStore({ agentDir: resolveAgentDir(), agentId: AGENT_ID, threadId: key });
+        threadStores.set(key, store);
+    }
+    return store;
+}
+/** 线程记账：ask 收到 / reply 发出各记一条（追加式日志）。 */
+function appendThreadEvent(env, type, text, threadKey) {
+    try {
+        threadStoreFor(env, threadKey).append({ type, from: env.from, correlationId: env.correlationId ?? env.id, text });
+    }
+    catch (err) {
+        console.error("[proactive] 线程记账失败:", err);
+    }
+}
+/** 线程轮次是否已达上限（达上限 → 不再发信，防 A→B→A 环路）。 */
+function threadExhausted(env, threadKey) {
+    try {
+        return threadStoreFor(env, threadKey).shouldStop(DEFAULT_MAX_ROUNDS);
+    }
+    catch (err) {
+        console.error("[proactive] 线程轮次检查失败（按未达上限处理）:", err);
+        return false;
+    }
+}
+/**
+ * peer watch 一轮：找空闲且新鲜的 peer → 询问进度（每个 peer 每个周期最多一次）。
+ *
+ * 环路防护：发送前用 `nextHop()` 递增 hop 并对照 `maxHops` —— **超过上限拒绝发送**
+ * （A→B→A 环路）；收到该 peer 的回复后 hop 归零（链路闭合）。
+ */
+export async function runPeerWatch() {
+    const registry = peerRegistry;
+    const watch = peerWatch;
+    if (!registry || !watch || !watch.enabled)
+        return;
+    const now = Date.now();
+    let peers;
+    try {
+        peers = registry.list();
+    }
+    catch (err) {
+        console.error("[proactive] peer watch 读注册表失败:", err);
+        return;
+    }
+    watch.observe(peers);
+    // 对端**重新进入忙碌**（开始新工作）→ 复位「已答 / 已停止」→ 可以再问（ASKLOOP 状态机）。
+    for (const p of peers) {
+        if (p.status === "busy")
+            askLedger?.notePeerBusy(p.agentId);
+    }
+    for (const target of watch.targets(peers)) {
+        if (target.agentId === AGENT_ID)
+            continue;
+        // 语义闭环（KK-7）：已答 / 等待中 / 退避中 / 已停止 → **不再追问**。
+        // 频率护栏只是最后一道防线，替代不了这一步。
+        if (askLedger !== undefined && !askLedger.canAsk(target.agentId, now))
+            continue;
+        // hop 计数：链路每问一次 +1；超过 maxHops → 拒绝发送（防 A→B→A 环路）。
+        // **显式带 correlationId**（ASKLOOP）：回信必须原样带回它 → 提问方才能把回信配回这条提问。
+        const correlationId = `ask-${randomUUID()}`;
+        const envelope = createEnvelope({
+            from: AGENT_ID,
+            to: target.agentId,
+            kind: "ask",
+            intent: "queue",
+            subject: "进度询问",
+            body: "在忙什么？需要帮忙吗？",
+            threadId: `peer-watch:${target.agentId}`,
+            correlationId,
+        });
+        const hopResult = nextHop({ ...envelope, hop: watch.hopFor(target.agentId) });
+        if (!hopResult.ok) {
+            console.error(`[proactive] peer watch 链路 hop 超限，拒绝询问 ${target.agentId}：${hopResult.error}`);
+            continue;
+        }
+        try {
+            const ack = await deliverToPeer(target.agentId, hopResult.envelope);
+            watch.markAsked(target.agentId);
+            watch.noteHop(target.agentId);
+            if (ack.status === "accepted" || ack.status === "duplicate") {
+                // 对端收下了 → 登记未决 ask（等它的回信 → 结局 answered / unanswered）。
+                askLedger?.recordAsk({
+                    peer: target.agentId,
+                    correlationId,
+                    threadKey: envelope.threadId,
+                    askedAt: now,
+                });
+            }
+            else {
+                // **没送达** → 结局 unreachable（不是 unanswered：它压根没被回答的机会）。
+                const event = askLedger?.noteUnreachable({
+                    peer: target.agentId,
+                    correlationId,
+                    threadKey: envelope.threadId,
+                    reason: `提问未送达（回执 ${ack.status}）`,
+                    at: now,
+                });
+                if (event)
+                    recordAskOutcome(event, envelope);
+            }
+            console.error(`[proactive] peer watch 询问 ${target.agentId}：${describeAck(ack.status, ack.error ?? ack.path, ack.queuedReason)}`);
+        }
+        catch (err) {
+            console.error("[proactive] peer watch 询问失败:", err);
+        }
+    }
+}
+/**
+ * 回执状态 → **如实**的中文说明（M5c §2.1.3）。
+ *
+ * 关键：`queued` **不是**「已送达」—— 它表示 socket 不可达、消息已降级落盘到对端邮箱，
+ * 尚未送达。写错会让人以为对端已经收到。
+ */
+export function describeAck(status, detail, queuedReason) {
+    switch (status) {
+        case "accepted":
+            return "已送达（对端已确认接收）";
+        case "duplicate":
+            return "对端判重，未重复处理";
+        case "queued":
+            return queuedReason === "peer-error"
+                ? `对端在线但本轮未接收，已落盘待其后续重试，尚未送达${detail ? `（${detail}）` : ""}`
+                : `已落盘到对端邮箱（对端当前不在线），尚未送达${detail ? `（${detail}）` : ""}`;
+        case "rejected":
+            return `被拒绝${detail ? `（${detail}）` : ""}`;
+        case "expired":
+            return "已过期（TTL 到了，未投递）";
+        case "unreachable":
+            return `对端不可达${detail ? `（${detail}）` : ""}`;
+        case "timeout":
+            return `投递超时${detail ? `（${detail}）` : ""}`;
+        default:
+            return `投递出错${detail ? `（${detail}）` : ""}`;
+    }
+}
+/**
+ * 出站投递（**唯一入口**）：`deliverCrossProcess` + 「失败不谎报」的兜底。
+ *
+ * - `accepted` / `duplicate` / `queued` → 对端已收到 / 已落盘待其上线 → 如实返回；
+ * - `error`（对端处理时抛错 / 对端进程崩了）→ **落盘到对端邮箱**并改写为 `queued`
+ *   （消息真的还在 → 回执说「已落盘待处理」，而不是谎报「已送达」）。
+ */
+async function deliverToPeer(targetAgentId, envelope) {
+    const agentDir = resolveAgentDir();
+    const ack = await deliverCrossProcess({ targetAgentId, envelope, agentDir });
+    if (ack.status !== "error") {
+        // `deliverCrossProcess` 只在「socket 不可达 / ack 超时」时返回 queued → 对端**离线**待上线。
+        return ack.status === "queued" ? { ...ack, queuedReason: "offline" } : ack;
+    }
+    try {
+        const file = writeToMailbox(targetAgentId, envelope, { agentDir });
+        // 对端**在线**但本轮没接收（处理失败 / 被推迟）→ 落盘待其后续重试
+        // （≠「对方上线后才会收到」—— P-6）。
+        return { status: "queued", id: envelope.id, path: file, error: ack.error, queuedReason: "peer-error" };
+    }
+    catch (err) {
+        console.error("[proactive] 投递失败且落盘兜底也失败（消息可能丢失）:", err);
+        return { ...ack, queuedReason: "peer-error" };
+    }
+}
+/**
+ * 回信（`kind:"reply"`）：把归因结果发给原 `from`。
+ *
+ * - 回信 `intent` = `"queue"`（**后续，不是插话**：ADR-3「默认 followUp 不打断」）；
+ * - 线程轮次已达上限 → 不再发（环路防护），只记日志；
+ * - 歧义归因 → 正文如实标注「歧义归因」（不假装确定）。
+ */
+async function sendPeerReply(plan) {
+    try {
+        const reply = plan.reply;
+        // 回信必须落在**问它的那条**线程里（ask 没带 id 时靠 pending → 线程键映射兜底）。
+        const threadKey = threadKeyOfPlan(plan);
+        if (threadExhausted(reply, threadKey)) {
+            // 达上限 → **必须通知请求方**（P-1）：不得静默拒发（请求方会永远等下去）。
+            await notifyThreadCap(reply, plan, threadKey);
+            return;
+        }
+        const ack = await deliverToPeer(reply.to, reply);
+        if (ack.status === "accepted" || ack.status === "duplicate" || ack.status === "queued") {
+            // **投递成功才记账**（Minor-4）：投递失败不记 reply 事件 → 轮次计数不虚增。
+            appendThreadEvent(reply, "reply", reply.body, threadKey);
+        }
+        else {
+            console.error(`[proactive] 回信未投递成功（不记线程 reply 事件）：${ack.status} ${ack.error ?? ""}`);
+            // 两条通道都失败 → 回信**彻底丢失** → 必须让请求方知道（P-7：不得静默丢失）。
+            await notifyReplyDeliveryFailure(reply, plan, ack, threadKey);
+        }
+        pendingThreadKeys.delete(pendingKeyOf(plan.pending));
+        if (plan.ambiguous) {
+            console.error("[proactive] 回信归因存在歧义，正文已如实标注");
+        }
+        // 回执如实区分状态（§2.1.3）：`queued` 绝不写成「已送达」。
+        console.error(`[proactive] 回信 ${reply.to}：${describeAck(ack.status, ack.error ?? ack.path, ack.queuedReason)}`);
+    }
+    catch (err) {
+        console.error("[proactive] 回信失败:", err);
+    }
+}
+/**
+ * 「已达线程轮次上限」说明的固定标记（线程日志里据此**去重**）。
+ *
+ * 去重判据必须是**持久化**的（线程日志的 note 事件）→ 进程重启后也不会重复通知同一线程。
+ */
+const CAP_NOTICE_TAG = "【已达线程轮次上限】";
+/** 上限说明**未送达**时的追加标记（未送达 → 不算「已通知」→ 允许下次再通知一次）。 */
+const CAP_NOTICE_UNDELIVERED = "（本条说明未送达";
+/**
+ * 去重键里的**请求方**标记（写进线程日志的 note 正文 → 持久化判据能区分「谁已被交代」）。
+ *
+ * X8：去重粒度 = **(线程, 请求方)** —— 同一线程上**不同请求方**各自必须被交代；
+ * 只按线程去重 → 共用一条线程兜底的其它请求方**彻底不知情**（正是要消灭的「静默吞掉」）。
+ */
+function capRequesterMark(requester) {
+    return `【请求方:${requester}】`;
+}
+/** 去重键 = (线程键, 请求方) —— 同线程同请求方只通知一次；不同请求方各自一条。 */
+function capNoticeKey(threadKey, requester) {
+    return `${threadKey}\u0000${requester}`;
+}
+/**
+ * 本进程内已成功通知过的 **(线程, 请求方)** 键（防并发重复通知；持久化判据见 `threadCapNotified`）。
+ *
+ * X8：粒度是 **(线程, 请求方)**，不是仅线程 —— 同一条线程上**不同请求方**各自必须被交代。
+ */
+const capNotifiedKeys = new Set();
+/**
+ * 这个 **(线程, 请求方)** 是否**已经成功通知过**「已达上限」？
+ *
+ * 判据 = 线程日志里存在一条 note，正文含上限标记 + **该请求方的标记**，且**不含**「未送达」标记
+ * → 跨进程重启也成立（不是内存态）；且**别的请求方**的通知不会误判成「这个请求方已被交代」。
+ */
+function threadCapNotified(env, threadKey, requester) {
+    const mark = capRequesterMark(requester);
+    try {
+        return threadStoreFor(env, threadKey)
+            .history()
+            .some((e) => e.type === "note" &&
+            (e.text ?? "").includes(CAP_NOTICE_TAG) &&
+            (e.text ?? "").includes(mark) &&
+            !(e.text ?? "").includes(CAP_NOTICE_UNDELIVERED));
+    }
+    catch (err) {
+        console.error("[proactive] 线程上限通知去重检查失败（按未通知处理）:", err);
+        return false;
+    }
+}
+/**
+ * 线程轮次已达上限 → **通知请求方**（P-1 / X7）。
+ *
+ * 为什么要通知：轮次上限是**环路防护**，但「不再回信」若**静默**发生，请求方会一直等下去
+ * （复验报告 P-1：连发 9 条提问 → 只有 4 条回信 + 零通知）。
+ *
+ * 通道（X7 修法）：**socket 优先 + 邮箱兜底**
+ * - 请求方**在线** → socket 直投（当场收到）；
+ * - 请求方**离线** → 落盘到**请求方自己的 agentId 目录**（`<agentDir>/proactive/mailbox/<请求方>/`，
+ *   语义与「落盘待上线」一致）→ 请求方上线后由它的邮箱扫描取回。
+ * 旧实现**只走 socket** → 请求方离线时 5 条通知**全部投递失败** → 它发出的 9 条提问里
+ * **5 条静默无解释**（与基准 B8「达上限后请求方可知」冲突）。
+ *
+ * **去重**（X8）：去重粒度 = **(线程, 请求方)** —— 同一请求方在同一线程上只通知一次
+ * （否则请求方邮箱里会堆一串重复说明）；**不同请求方各自必须收到交代**
+ * （只按线程去重 → 共用线程兜底的其它请求方彻底不知情 = 静默吞掉）。
+ */
+async function notifyThreadCap(reply, plan, threadKey) {
+    // **去重键 = (线程, 请求方)**（X8）：同线程同请求方只通知一次；
+    // **别的请求方不受影响** → 每个请求方都被交代（回信或通知二选一）。
+    const requester = reply.to;
+    const noticeKey = capNoticeKey(threadKey, requester);
+    if (capNotifiedKeys.has(noticeKey) || threadCapNotified(reply, threadKey, requester)) {
+        console.error(`[proactive] 线程轮次已达上限（${DEFAULT_MAX_ROUNDS} 轮往返），已通知过该请求方 ${requester}（同线程同请求方不再重复通知）`);
+        return;
+    }
+    // 先占位（防并发重复通知）；未送达时撤销 → 允许下次再通知。
+    capNotifiedKeys.add(noticeKey);
+    const store = threadStoreFor(reply, threadKey);
+    const rounds = store.rounds();
+    const body = `${CAP_NOTICE_TAG}本线程已完成 ${rounds} 轮往返（已回信 ${rounds} 条），达到上限（${DEFAULT_MAX_ROUNDS} 轮）后，` +
+        `**本线程后续提问一律不再回信**（这些提问不会再有回答，不是还在等待）。` +
+        `你在本线程的后续提问由本条一并交代，不再单独通知。` +
+        `若需继续，请另起一个话题（新的 threadId）。`;
+    const notice = createEnvelope({
+        from: AGENT_ID,
+        to: reply.to,
+        kind: "notify",
+        intent: "queue",
+        subject: "已达线程轮次上限",
+        body,
+        threadId: plan.pending.threadId,
+        correlationId: plan.pending.correlationId,
+    });
+    try {
+        // **socket 优先 + 邮箱兜底**（`deliverToPeer`：socket 不可达 → 落盘到对端邮箱 → queued）。
+        const ack = await deliverToPeer(reply.to, notice);
+        const delivered = ack.status === "accepted" || ack.status === "duplicate" || ack.status === "queued";
+        // 线程记一条 note（**不**计入轮次 —— 它不是回答；也是去重的持久化判据）。
+        // 送达时带上**请求方标记** → 持久化判据能区分「谁已被交代」（X8）。
+        appendThreadEvent(notice, "note", delivered ? `${body}${capRequesterMark(requester)}` : `${body}${CAP_NOTICE_UNDELIVERED}：${ack.status}）`, threadKey);
+        if (!delivered)
+            capNotifiedKeys.delete(noticeKey);
+        console.error(`[proactive] 线程轮次已达上限（${DEFAULT_MAX_ROUNDS} 轮往返），` +
+            `${delivered ? "已通知请求方" : "**未能**通知请求方"}：${describeAck(ack.status, ack.error ?? ack.path, ack.queuedReason)}`);
+    }
+    catch (err) {
+        capNotifiedKeys.delete(noticeKey);
+        appendThreadEvent(notice, "note", `${body}${CAP_NOTICE_UNDELIVERED}：${err instanceof Error ? err.message : String(err)}）`, threadKey);
+        console.error("[proactive] 线程轮次已达上限，通知请求方失败:", err);
+    }
+}
+/**
+ * 回信**彻底**投递失败（socket + 落盘兜底都失败）→ 通知请求方（P-7）。
+ *
+ * 否则：回信永久丢失（无重试、无落盘、无通知），请求方永远等不到回答且**不知情**。
+ * 通知本身也走 `deliverToPeer`（socket 优先、落盘兜底）；连通知都送不出去时：
+ * stderr + 线程 note 留痕（**不**冒充已送达）。
+ */
+async function notifyReplyDeliveryFailure(reply, plan, ack, threadKey) {
+    const reason = `${ack.status}${ack.error ? `：${ack.error}` : ""}`;
+    const body = `【回信未能送达】本机对本次提问的回答未能投送给请求方（${reason}）。请勿继续等待这条回答。`;
+    const notice = createEnvelope({
+        from: AGENT_ID,
+        to: reply.to,
+        kind: "notify",
+        intent: "queue",
+        subject: "回信未能送达",
+        body,
+        threadId: plan.pending.threadId,
+        correlationId: plan.pending.correlationId,
+    });
+    appendThreadEvent(notice, "note", body, threadKey);
+    try {
+        const nack = await deliverToPeer(reply.to, notice);
+        console.error(`[proactive] 回信送达失败通知（${reason}）：${describeAck(nack.status, nack.error ?? nack.path, nack.queuedReason)}`);
+    }
+    catch (err) {
+        console.error("[proactive] 回信送达失败通知发送失败（消息可能丢失）:", err);
+    }
+}
+/** 宿主消息的角色（`assistant` / `user` / 其它）。 */
+function messageRole(message) {
+    if (typeof message !== "object" || message === null)
+        return undefined;
+    const m = message;
+    return typeof m.role === "string" ? m.role : undefined;
+}
+/** 从宿主消息里取全部文本块（拼接）。 */
+function messageText(message) {
+    if (typeof message !== "object" || message === null)
+        return "";
+    const m = message;
+    if (!Array.isArray(m.content))
+        return "";
+    const parts = [];
+    for (const block of m.content) {
+        if (typeof block !== "object" || block === null)
+            continue;
+        const b = block;
+        if (b.type === "text" && typeof b.text === "string")
+            parts.push(b.text);
+    }
+    return parts.join("\n");
+}
+/**
+ * 这条宿主消息是不是**本插件自己注入**的 peer 消息？
+ *
+ * **只认来源标记**（`customType === "proactive:peer"`）—— 这是宿主侧**唯一可靠**的依据
+ * （宿主把自定义消息存成 role:"custom" 的消息，customType 原样保留）。
+ *
+ * X7（R-2）：**删掉任何基于正文内容的兜底识别**。
+ * 旧实现在这里用「正文含注入标记串」来识别「这是我们注入的」→ 用户把注入正文
+ * **原样复制**到自己的输入里（含标记串）时也被判成「自注入」→ 不记「用户发言」→
+ * 之后的回答被当成确定答案回给对端 → 回信**漏标【歧义归因】**。
+ * 现在：**正文里带标记串 = 可能是用户复制** → 按「用户发言」处理
+ * （无法区分时**宁可多标歧义**，也不漏标）。
+ */
+function isInjectedPeerMessage(message) {
+    if (typeof message !== "object" || message === null)
+        return false;
+    const m = message;
+    // ① **来源标记**（宿主保留 customType）—— 唯一可靠的「这是我们注入的」依据。
+    if (m.customType === PEER_CUSTOM_TYPE)
+        return true;
+    // ② **兜底形态**（宿主把自定义消息转成 role:"user"、丢了 customType）：
+    //    该消息的标记串必须**已被 input(source:"extension") 事件认领** → 才是我们的回声。
+    //    没被认领 → 用户可能**原样复制**了注入正文 → 按「用户发言」处理（宁可多标歧义）。
+    const text = messageText(message);
+    if (text === "")
+        return false;
+    const marker = injectionMarkers.find((mk) => mk !== "" && text.includes(mk));
+    if (marker === undefined)
+        return false;
+    if (!claimedInjectionMarkers.has(marker))
+        return false;
+    claimedInjectionMarkers.delete(marker); // 一次性：认领只对**这一条**回声有效
+    return true;
+}
+/**
+ * 这条消息里有没有**我们自己注入**的标记串？（**精确匹配标记串**本身 —— 不用任何正文启发式。）
+ *
+ * 用途**只有一个**：识别「用户把注入正文原样复制了回来」→ 记一条审计日志。
+ * 它**不**用于判定「这是我们注入的」（那会漏标歧义，见 `isInjectedPeerMessage`）。
+ */
+function containsInjectionMarker(message) {
+    const text = messageText(message);
+    if (text === "")
+        return false;
+    return injectionMarkers.some((marker) => marker !== "" && text.includes(marker));
+}
+/**
+ * 认领一次注入：宿主用 `input(source:"extension")` 事件告诉我们「这条是我们注入的」。
+ *
+ * 只认领**正文里精确出现**的标记串（不用任何启发式）；认领是**一次性**的
+ * （下一次同样的标记串出现 = 用户复制 → 按用户发言处理）。
+ */
+function claimInjectionMarker(text) {
+    if (typeof text !== "string" || text === "")
+        return;
+    for (const marker of injectionMarkers) {
+        if (marker !== "" && text.includes(marker))
+            claimedInjectionMarkers.add(marker);
+    }
+    // 有界：长期会话不得内存无界增长（认领后一直没等到回声的最老认领作废）。
+    while (claimedInjectionMarkers.size > 32) {
+        const oldest = claimedInjectionMarkers.values().next();
+        if (oldest.done)
+            break;
+        claimedInjectionMarkers.delete(oldest.value);
+    }
+}
+/** 造一个本次注入用的标记串（每次不同 → 不可混淆、不可被用户的正文碰巧命中）。 */
+function createInjectionMarker() {
+    return `${INJECTION_MARKER_PREFIX}${randomUUID()}]`;
+}
+/** 记住一次注入的标记串（有界：只留最近若干条）。 */
+function rememberInjectionMarker(marker) {
+    if (marker === "")
+        return;
+    injectionMarkers.push(marker);
+    while (injectionMarkers.length > 16)
+        injectionMarkers.shift();
+}
+/** 从宿主消息里取 assistant 的文本（拿不到就返回 undefined）。 */
+function extractAssistantText(message) {
+    if (typeof message !== "object" || message === null)
+        return undefined;
+    const m = message;
+    if (m.role !== "assistant" || !Array.isArray(m.content))
+        return undefined;
+    const parts = [];
+    for (const block of m.content) {
+        if (typeof block !== "object" || block === null)
+            continue;
+        const b = block;
+        if (b.type === "text" && typeof b.text === "string")
+            parts.push(b.text);
+    }
+    const text = parts.join("\n").trim();
+    return text === "" ? undefined : text;
+}
+/**
+ * `/proactive help` 的正文（MANUAL：产品内的人类面向手册入口）。
+ *
+ * 一屏内给出：① 命令表（**含 help 自身**）② 配置键速查（指向 README 详表）
+ * ③ 限制与最常见的 3 个故障 ④ 详细文档路径。
+ *
+ * 为什么要**逐字**写「没有 `/proactive notify` 这个命令」：
+ * 模型与用户都会拿 `kind:"notify"` 去臆造一个同名子命令 → 敲了被拒 → 误判为装坏了。
+ * 这里把幽灵命令**点名消解**。
+ */
+function formatHelp() {
+    return [
+        "proactive 命令速查（/proactive help）",
+        "",
+        "【命令】",
+        "  status               总览：开关 / 空闲判定 / 护栏限制 + 本轮为什么（没）触发",
+        "  on | off             主动性总开关（定时投递 + 空闲触发；已落盘，重启仍生效）",
+        "  idle on | off        只开关空闲触发（内存态，重启回到配置文件里的设置）",
+        "  peers                在线 peer（名字 / agentId / 忙闲 / 心跳）",
+        "  peers --all          含离线对端（带下线时间与下线原因）",
+        "  peers --idle         只看空闲的对端",
+        "  peers --name <子串>  按名字子串过滤（同名多个 → 列出全部候选，不替你挑）",
+        "  peers --detail <id>  单个对端详情（字段与 list_peers 逐字一致）",
+        "  spawn [名字]         创建一个对端会话（子进程 pi --mode rpc；本会话退出时一并终止）",
+        "  tasks                待触发任务（id / 类型 / 到期 / intent）",
+        "  cancel <id>          取消指定任务",
+        "  in <时长> <内容>     排期一次（30s / 10m / 2h / 1d；纯数字按秒计）",
+        "  at <HH:MM> <内容>    排期一次到某时刻（今天该时刻已过则顺延到明天）",
+        "  every <时长> <内容>  排期重复",
+        "  test                 强制走一次投递链路自检（不受总开关与冷却影响）",
+        "  doctor [--json]      只读体检：插件面各面状态 + 判据 + 处置建议（不打扰、不耗额度）",
+        "  progress             项目进度 + ETA：区间 + 置信度 + 归因 + 阻塞项（不给单点数字）",
+        "  tell <peer> <内容>    人侧给对端 agent 下指令（--kind ask|task|notify；缺省 ask）",
+        "  help                 本页",
+        "",
+        "【配置键速查】（详表见 <安装目录>/README.md「配置」）",
+        "  enabled               主动性总开关（默认 true）",
+        "  idleDetect            空闲检测档位：terminal / input-only / off（默认 off）",
+        "  idleTrigger.enabled   空闲触发开关（默认 false）",
+        "  idleTrigger.afterMs   空闲多久后触发（默认 600000 = 10 分钟）",
+        "  idleTrigger.intent    空闲触发的投递意图：wake / interrupt / queue / notify",
+        "  askTimeoutMs          向用户提问的超时（默认 120000 = 2 分钟）",
+        "  limits.minGapMs       两次主动触发的最短间隔（默认 300000 = 5 分钟）",
+        "  limits.maxPerHour     每小时主动次数上限（默认 6）",
+        "  limits.quietHours     静默时段 {from,to}（未设置 = 不静默）",
+        "  peerWatch.enabled     空闲时主动询问其它 peer（默认 false）",
+        "  PI_PROACTIVE_ROLE     会话角色：coordinator（协调者，会主动问）/ worker（执行者，只被问）",
+        "  PI_PROACTIVE_WATCH_PEERS  随会话的 watch 名单（agentId, 逗号分隔；空 = 不限定）",
+        "  配置文件：<agent-dir>/proactive/config.json",
+        "            （<agent-dir> = $PI_CODING_AGENT_DIR，未设置时是 ~/.pi/agent）",
+        "",
+        "【限制与最常见的 3 个故障】",
+        "  1) 不触发：① 空闲触发默认是关的 → /proactive idle on（内存态）；",
+        "     ② idleDetect 默认 off → 设 terminal（仅 TUI）或 input-only；",
+        "     ③ 总开关是关的 → /proactive on；④ 距上次主动不足 5 分钟（冷却）或本小时次数已用满；",
+        "     ⑤ 处于静默时段；⑥ 代理正在忙。逐条对照 /proactive status 末尾的判定说明。",
+        "  2) 消息 queued：只表示「已写进对端邮箱」，**尚未送达**；对端上线后才会收到 →",
+        "     不要重复发送，改查 /proactive peers 或等回执。",
+        "  3) 装完命令不存在：命令由扩展注册 → 必须在加载了本扩展的会话里用；",
+        "     装包后新开一个会话（或 /reload）再试。",
+        '  另外：没有 `/proactive notify` 这个命令 —— notify 是**消息语义**（kind:"notify"），',
+        "        不是子命令；**人侧给对端下指令**用 `/proactive tell <peer> <内容>`",
+        '        （tell 的 --kind 决定这条指令的语义：ask=要回话 / task=派活 / notify=知会）；',
+        "        /proactive quiet 同样未实现；/proactive history [peer|me] [条数] 已实现（查主动行为记录）。",
+        "",
+        "【详细文档】",
+        "  <安装目录>/README.md    安装 / 命令 / 模型工具 / 配置详表 / 故障排查（随包分发）",
+        "  pi-proactive-ops.md      运维与故障处置手册（与内测包同目录分发；",
+        "                          仓库内路径 docs/ops/pi-proactive-ops.md）",
+    ].join("\n");
+}
+/** 投递回执文案：8 种状态逐一区分，**不把 queued 说成已送达**。 */
+function receiptText(ack) {
+    switch (ack.status) {
+        case "accepted":
+            return "已送达：对端在线并已接收（accepted）。";
+        case "duplicate":
+            return "对端已处理过这条消息（duplicate）——未重复投递。";
+        case "queued":
+            // P-6：必须**区分**「对端离线待上线」与「对端在线但本轮未投递（被推迟 / 失败）」——
+            // 后者说「对方上线后才会收到」是**不实描述**（对端明明在线，且这条消息可能永远不投递）。
+            return ack.queuedReason === "peer-error"
+                ? `已落盘待重试（queued）——对端**在线**但本轮未接收（原因：${ack.error ?? "未知"}），` +
+                    `消息已写入对端邮箱待其后续重试，**尚未送达**。${ack.path ? `落盘路径：${ack.path}` : ""}`
+                : `已落盘待对方上线（queued）——消息已写入对端邮箱，对方上线后才会收到，**尚未送达**。${ack.path ? `落盘路径：${ack.path}` : ""}`;
+        case "rejected":
+            return `被拒绝（rejected）：${ack.error ?? "未知原因"}`;
+        case "expired":
+            return "消息已过期（expired）——对方不会再处理。";
+        case "error":
+            return `投递失败（error）：${ack.error ?? "未知原因"}`;
+        case "unreachable":
+            return `对端不可达（unreachable）：${ack.error ?? "端点不存在或无进程监听"}`;
+        case "timeout":
+            return `等待回执超时（timeout）：${ack.error ?? "对端未在时限内回执"}`;
+        default:
+            return `未知回执状态：${String(ack.status)}`;
+    }
+}
+/**
+ * **人侧发指令**（`/proactive tell`）的交付物。
+ *
+ * 范围（刻意**只做「发指令 + 看回信」**）：不做编排 / 任务图 / 自动分发。
+ *
+ * 走的通道 = **既有唯一出站入口** `deliverToPeer`（**不另造投递通道**）。
+ * 信封的 `from` = 本会话 agentId → 收信侧 strict 校验（注册表逐字命中 + 主机一致）照旧通过；
+ * `customType` = `proactive:human` → 收信侧**能识别**这条是人类直接下达的。
+ */
+// G12 三件套（人侧发指令这条腿）：
+// - 可观察出口 = `tellReceiptText`（回执经 `cmdCtx.ui.notify` 呈现给人）；
+// - 归因 = `parseTellCommand`（人敲的命令与参数）+ `resolveTellTarget`（发给谁：注册表解析）；
+// - 结果判定 = ack 状态本身（送达 / 落盘待上线 / 未送达，见 tellReceiptText 的三档）。
+//
+// @capability: human-tell
+// @observable: tellReceiptText
+// @attribution: parseTellCommand resolveTellTarget
+// @outcome: accepted duplicate queued rejected error
+// @checked: test:pi-proactive/tests/human-to-peer.test.ts#端到端：/proactive tell
+async function runTell(args) {
+    const parsed = parseTellCommand(args);
+    if (!parsed.ok) {
+        return { text: `proactive: ${parsed.error}`, level: "error" };
+    }
+    const registry = peerRegistry;
+    if (!registry) {
+        return { text: "proactive: 跨进程协作未初始化（session_start 尚未触发），未发送。", level: "error" };
+    }
+    const command = parsed.command;
+    // 目标解析：**同名歧义 → 拒绝 + 列出候选**（人侧不替人挑一个）。
+    const entries = registry.listAll().map((e) => ({
+        agentId: e.agentId,
+        name: e.name,
+        status: e.status,
+        lastSeen: e.lastSeen,
+    }));
+    const resolution = resolveTellTarget(entries, command.target);
+    if (!resolution.ok) {
+        return { text: `proactive: ${resolution.error}`, level: "error" };
+    }
+    const targetAgentId = resolution.agentId;
+    const envelope = buildTellEnvelope({
+        from: AGENT_ID,
+        to: targetAgentId,
+        body: command.body,
+        kind: command.kind,
+        threadId: command.threadId,
+        subject: command.subject,
+    });
+    // 唯一出站入口（既有）：在线直达 socket；不在线 → 落盘到对端邮箱（queued，**尚未送达**）。
+    const ack = await deliverToPeer(targetAgentId, envelope);
+    // 提问记账：回信要能配回来（与模型侧 message_agent 同口径）。
+    if (envelope.kind === "ask" && envelope.correlationId !== undefined) {
+        if (ack.status === "accepted" || ack.status === "duplicate") {
+            askLedger?.recordAsk({
+                peer: targetAgentId,
+                correlationId: envelope.correlationId,
+                threadKey: envelope.threadId,
+                humanOrigin: true,
+            });
+        }
+        else {
+            const event = askLedger?.noteUnreachable({
+                peer: targetAgentId,
+                correlationId: envelope.correlationId,
+                threadKey: envelope.threadId,
+                reason: `提问未送达（回执 ${ack.status}）`,
+            });
+            if (event)
+                recordAskOutcome(event, envelope);
+        }
+    }
+    const peerOnline = registry.list().some((e) => e.agentId === targetAgentId);
+    return { text: tellReceiptText(ack, peerOnline), level: "info" };
+}
+/**
+ * 人侧发指令的回信 → **人可见**的通知（不等模型转述）。
+ *
+ * 为什么多这一条：模型侧可能忽略这条 reply（不回话、不复述）→ 人就看不到答案。
+ * 这里直接通知人一次；正文太长只取前 200 字（完整内容仍在注入给模型的那条里）。
+ */
+function notifyHumanReply(envelope) {
+    try {
+        const body = envelope.body.trim();
+        const head = body.length > 200 ? `${body.slice(0, 200)}…` : body;
+        currentCtx?.ui.notify(`对端 ${envelope.from} 回信（你下发的指令）：${head}`);
+    }
+    catch (err) {
+        console.error("[proactive] 人类指令回信通知失败:", err);
+    }
+}
+/**
+ * 人侧发指令的回执（**三态分明**，queued 绝不被说成「已送达」）：
+ *
+ * 1. **已送达**（accepted / duplicate）—— 对端在线并已接收（**尚未回答**）；
+ * 2. **已落盘待其上线**（queued）—— 对端当前不在线 → 消息在对端邮箱，**尚未送达**；
+ * 3. **未送达**（rejected / error 等）—— 既没到对端，也没落到对端邮箱。
+ *
+ * 「对端当前不在线」这句来自**注册表**（事实源），不是猜的。
+ */
+function tellReceiptText(ack, peerOnline) {
+    const lines = [receiptText(ack)];
+    if (ack.status === "accepted" || ack.status === "duplicate") {
+        lines.push("这条是人类直接下达的指令：对端已收到，**尚未回答**；回答到达后会落到本会话。");
+        return lines.join("\n");
+    }
+    if (ack.status === "queued") {
+        if (!peerOnline) {
+            lines.push("对端当前**不可达**（注册表里不在线）——指令已落盘待其上线，**尚未送达**。");
+        }
+        else {
+            lines.push("对端在线但本轮未接收——指令已落盘待其重试，**尚未送达**。");
+        }
+        return lines.join("\n");
+    }
+    lines.push("**未送达**：这条指令既没到对端，也没落到对端邮箱。");
+    return lines.join("\n");
+}
+/** `message_agent` 工具的参数 schema。 */
+const messageAgentParameters = Type.Object({
+    to: Type.String({ description: "目标 agent 的名字或 agentId" }),
+    kind: Type.Optional(Type.Union([
+        Type.Literal("notify"),
+        Type.Literal("ask"),
+        Type.Literal("task"),
+        Type.Literal("reply"),
+        Type.Literal("broadcast"),
+    ], { description: "消息语义（对方要不要回我）；缺省 notify" })),
+    subject: Type.Optional(Type.String({ description: "标题" })),
+    body: Type.String({ description: "正文" }),
+    intent: Type.Optional(Type.Union([Type.Literal("wake"), Type.Literal("interrupt"), Type.Literal("queue"), Type.Literal("notify")], {
+        description: "投递意图（怎么投给对方）；缺省 wake",
+    })),
+    threadId: Type.Optional(Type.String({ description: "话题 / 会话 id（可选）" })),
+});
+/** `list_peers` 工具的参数 schema。 */
+const listPeersParameters = Type.Object({
+    name: Type.Optional(Type.String({
+        description: "名字子串（大小写敏感；也命中 agentId）。同名歧义时返回与 message_agent 报错完全一致的候选",
+    })),
+    status: Type.Optional(Type.Union([Type.Literal("online"), Type.Literal("idle"), Type.Literal("busy"), Type.Literal("offline")], {
+        description: "按在场状态过滤（online = 在线 = 空闲 ∪ 忙碌）",
+    })),
+    capability: Type.Optional(Type.String({ description: "按能力标签过滤（如 message_agent）" })),
+    includeOffline: Type.Optional(Type.Boolean({ description: "是否包含离线对端（缺省 false = 只给在线）" })),
+});
+/**
+ * 与某个对端**尚未闭环**的 ask 交互数（= `list_peers` 里的「在途任务数」）。
+ *
+ * 口径：① 本机发给它、还没收到结局的 ask（ASKLOOP 账本）；② 它发给本机、还没被回答的 ask。
+ */
+function inFlightForPeer(peerAgentId) {
+    let n = askLedger?.outstandingFor(peerAgentId) ?? 0;
+    for (const pending of peerResponder?.pendingList() ?? []) {
+        if (pending.requester === peerAgentId)
+            n += 1;
+    }
+    return n;
+}
+/**
+ * 给投递器套一层「触发原因」（cause + 判定依据）——**不改投递语义**，只补血缘。
+ *
+ * 为什么要套一层：`src/idle.ts` 与 `src/scheduler.ts` 是冻结模块（不得改动），
+ * 它们调用 `deliverToModel` 时不带 cause → 「因」只能由本层补上。
+ */
+function withTriggerCause(trigger, cause, basis) {
+    return {
+        deliverToModel: async (msg, intent, opts) => trigger.deliverToModel(msg, intent, {
+            ...opts,
+            cause: { type: cause, ...(basis !== undefined ? { basis: basis(msg) } : {}) },
+        }),
+    };
+}
+/** 空闲触发的判定依据：已空闲多久 / 阈值 / 生效档位（只放可复核的量）。 */
+function idleBasis() {
+    try {
+        return {
+            idleForMs: tracker.snapshot().idleForMs,
+            thresholdMs: config.idleTrigger.afterMs,
+            detect: effectiveIdleDetect(config.idleDetect, currentCtx?.mode),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/** 排期触发的判定依据：任务 id / 到期时刻 / 周期。 */
+function scheduleBasis(taskId) {
+    const basis = { taskId };
+    try {
+        const task = currentStore?.list().find((t) => t.id === taskId);
+        if (task !== undefined) {
+            basis.dueAt = task.dueAt;
+            if (task.intervalMs !== undefined)
+                basis.intervalMs = task.intervalMs;
+        }
+    }
+    catch {
+        // 读任务表失败不得影响投递（判定依据缺项即可）
+    }
+    return basis;
+}
+/** `/proactive status` 里的一行「最近事件」指路。 */
+function recentEventsHint() {
+    const log = currentLineage;
+    if (!log)
+        return "最近事件：事件流未初始化（session_start 尚未触发）";
+    const events = log.history({ limit: 1 });
+    if (events.length === 0)
+        return "最近事件：暂无记录（用 /proactive history 查看）";
+    const e = events[events.length - 1];
+    const result = e.result !== undefined ? ` · 结果=${e.result}` : "";
+    return `最近事件：${e.type} · cause=${e.cause}${result}（用 /proactive history 查看全部）`;
+}