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

package/build/src/health.js

@@ -0,0 +1,734 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { defaultConfig, proactiveDir } from "./config.js";
+import { OFFLINE_ENTRY_MIN_RETENTION_MS, OFFLINE_HEARTBEAT_FACTOR, } from "./registry.js";
+import { socketPathFor } from "./socket.js";
+import { readLatestHandover } from "./daemon-config.js";
+/**
+ * 阈值表 —— **每一项都写明出处**（`thresholdSource` 里逐字引用这里的注释）。
+ *
+ * 凡「规范/源码里已有口径」的，直接引用该常量（单一真源，不复制数值）；
+ * 凡「规范没有既有阈值」的，标注为「本卡设定」—— 不假装它有历史依据。
+ */
+export const HEALTH_THRESHOLDS = {
+    /** 待处理信封数告警线：本卡设定（规范无既有邮箱堆积阈值）。 */
+    mailboxBacklogWarn: 20,
+    /** 待处理信封数严重线：本卡设定（取 warn 线的 5 倍，只用于区分严重度）。 */
+    mailboxBacklogFail: 100,
+    /** 滞留未认领阈值：取 `mailbox.ts` 的 `DEFAULT_STALE_CLAIM_MS`（1 小时）—— 同一把尺子。 */
+    mailboxStuckMs: 3_600_000,
+    /** 事件流陈旧阈值：取 `registry.ts` 的 `OFFLINE_ENTRY_MIN_RETENTION_MS`（24 小时）—— 同量级。 */
+    eventStreamStaleMs: OFFLINE_ENTRY_MIN_RETENTION_MS,
+    /** 注册表陈旧条目告警线：本卡设定（规范无既有阈值）。 */
+    registryStaleWarn: 5,
+    /** 任务表膨胀线：本卡设定（规范无既有阈值）。 */
+    taskTableBloated: 200,
+    /** 额度逼近上限的比例（≥ 该比例即告警）：本卡设定（上限的 80%）。 */
+    guardNearLimitRatio: 0.8,
+    /** 冷却下限：低于此值视为「冷却形同虚设」：本卡设定（对齐默认 5 分钟的一半量级）。 */
+    minGapMsFloor: 60_000,
+    /** 空闲阈值「合理区间」下界：本卡设定（默认 10 分钟；低于 1 分钟会频繁打扰）。 */
+    idleAfterMsSaneMin: 60_000,
+    /** 空闲阈值「合理区间」上界：本卡设定（超过 24 小时基本不会触发）。 */
+    idleAfterMsSaneMax: 24 * 3_600_000,
+};
+const HOUR_MS = 3_600_000;
+// ---------------------------------------------------------------- 只读小工具
+function readDirSafe(dir) {
+    try {
+        return fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function statSafe(file) {
+    try {
+        return fs.statSync(file);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readTextSafe(file) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function readJsonSafe(file) {
+    const raw = readTextSafe(file);
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** 读文件尾部（避免整文件读入）；返回的片段可能不是完整行 → 解析时跳过坏行。 */
+function readTail(file, maxBytes) {
+    try {
+        const fd = fs.openSync(file, "r");
+        try {
+            const size = fs.fstatSync(fd).size;
+            const start = Math.max(0, size - maxBytes);
+            const len = Math.max(0, size - start);
+            const buf = Buffer.alloc(len);
+            if (len > 0)
+                fs.readSync(fd, buf, 0, len, start);
+            return buf.toString("utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return "";
+    }
+}
+function isAgentLike(v) {
+    if (!isPlainObject(v))
+        return false;
+    return typeof v.agentId === "string" && typeof v.lastSeen === "number";
+}
+/** 进程是否还活着（`kill(pid, 0)` 只做存在性探测，不发信号、不影响对方）。 */
+function pidAlive(pid) {
+    if (typeof pid !== "number" || !Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM = 进程存在但不属于当前用户 → 仍算活着。
+        return err.code === "EPERM";
+    }
+}
+// ---------------------------------------------------------------- 版本
+/**
+ * 从「模块所在目录」向上找 package.json 取版本号。
+ * 两种落位都要认：源码态 `src/health.ts`（package.json 在上一级）与
+ * 产物态 `build/src/health.js`（package.json 在上两级）→ 两级都试。
+ */
+export function pluginVersionFrom(baseDir) {
+    for (const up of ["..", "../.."]) {
+        const pkg = readJsonSafe(path.join(baseDir, up, "package.json"));
+        if (isPlainObject(pkg) && typeof pkg.version === "string")
+            return pkg.version;
+    }
+    return "unknown";
+}
+function pluginVersion() {
+    try {
+        return pluginVersionFrom(path.dirname(fileURLToPath(import.meta.url)));
+    }
+    catch {
+        // 取不到就报未知，不抛
+        return "unknown";
+    }
+}
+function hostVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const file = require.resolve("@earendil-works/pi-coding-agent/package.json");
+        const pkg = readJsonSafe(file);
+        if (isPlainObject(pkg) && typeof pkg.version === "string")
+            return pkg.version;
+    }
+    catch {
+        // 宿主包不在插件的依赖树里（peerDependency）→ 取不到，属正常
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------- 各面采集
+/** 注册表条目（只读）：直接读文件，不走 `Registry.listAll()`（它会改名备份坏文件 = 写副作用）。 */
+function readRegistryEntries(agentsDir) {
+    const out = [];
+    for (const name of readDirSafe(agentsDir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const parsed = readJsonSafe(path.join(agentsDir, name));
+        if (isAgentLike(parsed))
+            out.push(parsed);
+    }
+    return out;
+}
+/** 条目是否「已不在场」（离线判定 = 3 个心跳周期；与 registry.ts 的 isExpired 同口径）。 */
+function entryExpired(entry, now) {
+    if (now < entry.lastSeen)
+        return true;
+    return now - entry.lastSeen > entry.heartbeatMs * OFFLINE_HEARTBEAT_FACTOR;
+}
+/** GC 会删掉的条目（不在场 **且** 超保留窗）—— 与 `sweepStaleEntries()` 同判据。 */
+function beyondRetention(entry, now) {
+    const online = entry.status !== "offline" && !entryExpired(entry, now);
+    if (online)
+        return false;
+    const age = now - entry.lastSeen;
+    const threshold = Math.max(entry.heartbeatMs * OFFLINE_HEARTBEAT_FACTOR, OFFLINE_ENTRY_MIN_RETENTION_MS);
+    return age > threshold;
+}
+/** 邮箱采样（只读）：收件箱里的信封 = 待处理；`failed/` = 失败归档。 */
+function readMailbox(mailboxDir, now) {
+    let pending = 0;
+    let oldestPendingAgeMs = null;
+    let failedArchived = 0;
+    let stuckUnclaimed = 0;
+    for (const inbox of readDirSafe(mailboxDir)) {
+        if (inbox === "claims")
+            continue; // claim 锁目录，不是收件箱
+        const inboxDir = path.join(mailboxDir, inbox);
+        const st = statSafe(inboxDir);
+        if (!st?.isDirectory())
+            continue;
+        for (const name of readDirSafe(inboxDir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            const file = path.join(inboxDir, name);
+            const fst = statSafe(file);
+            if (!fst?.isFile())
+                continue;
+            pending += 1;
+            const age = now - fst.mtimeMs;
+            if (oldestPendingAgeMs === null || age > oldestPendingAgeMs)
+                oldestPendingAgeMs = age;
+            if (age > HEALTH_THRESHOLDS.mailboxStuckMs)
+                stuckUnclaimed += 1;
+        }
+        const failedDir = path.join(inboxDir, "failed");
+        for (const name of readDirSafe(failedDir)) {
+            if (name.endsWith(".json"))
+                failedArchived += 1;
+        }
+    }
+    return { pending, oldestPendingAgeMs, failedArchived, stuckUnclaimed };
+}
+/**
+ * 端点采样（只读）。
+ *
+ * 僵尸端点的判据：**端点文件在，但没有「活着的监听者」**。
+ * 监听者是否存在，用插件自己的注册表事实判定（不连接对端 socket —— 连接对端是一次
+ * **对外交互**，与「巡检不得打扰」冲突）：
+ * - 端点文件找不到对应注册表条目 → 没有监听者（孤儿端点文件）；
+ * - 条目已 offline / 心跳过期（3×心跳，registry.ts 的离线判定）/ 进程 pid 已不存在 → 没有监听者。
+ *
+ * 保守性：只在这三种**确定没有监听者**的情形下报僵尸；宁可漏报也不误报。
+ */
+function readEndpoints(agentDir, runDir, entries, now) {
+    const sockFiles = readDirSafe(runDir).filter((n) => n.endsWith(".sock"));
+    const byPath = new Map();
+    for (const entry of entries) {
+        byPath.set(socketPathFor(entry.agentId, agentDir), entry);
+    }
+    const zombiePaths = [];
+    for (const name of sockFiles) {
+        const full = path.join(runDir, name);
+        const entry = byPath.get(full);
+        if (entry === undefined) {
+            zombiePaths.push(full); // 没有任何注册表条目对应 → 没人监听
+            continue;
+        }
+        if (entry.status === "offline" || entryExpired(entry, now) || !pidAlive(entry.pid)) {
+            zombiePaths.push(full);
+        }
+    }
+    return { total: sockFiles.length, zombie: zombiePaths.length, zombiePaths };
+}
+/** 事件流采样（只读）：扫 `lineage/*.jsonl`。 */
+function readEvents(lineageDir, now) {
+    const files = readDirSafe(lineageDir).filter((n) => n.endsWith(".jsonl"));
+    let lastTs = null;
+    let deliveredThisHour = 0;
+    let lastDeliveredAt = null;
+    for (const name of files) {
+        const file = path.join(lineageDir, name);
+        const text = readTail(file, 4 * 1024 * 1024);
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                continue; // 半截行（追加撕裂）→ 跳过
+            }
+            if (!isPlainObject(parsed))
+                continue;
+            const ts = typeof parsed.ts === "number" ? parsed.ts : undefined;
+            if (ts === undefined)
+                continue;
+            if (lastTs === null || ts > lastTs)
+                lastTs = ts;
+            if (parsed.type === "delivered") {
+                if (ts > now - HOUR_MS)
+                    deliveredThisHour += 1;
+                if (lastDeliveredAt === null || ts > lastDeliveredAt)
+                    lastDeliveredAt = ts;
+            }
+        }
+    }
+    return {
+        exists: files.length > 0,
+        lastEventAgeMs: lastTs === null ? null : now - lastTs,
+        streams: files.length,
+        deliveredThisHour,
+        lastDeliveredAt,
+    };
+}
+/** 任务表采样（只读）：`tasks.json` 是数组；坏文件 → 视为空表。 */
+function readTasks(tasksFile) {
+    const parsed = readJsonSafe(tasksFile);
+    if (!Array.isArray(parsed))
+        return { count: 0, totalFireCount: 0 };
+    let totalFireCount = 0;
+    for (const item of parsed) {
+        if (isPlainObject(item) && typeof item.fireCount === "number")
+            totalFireCount += item.fireCount;
+    }
+    return { count: parsed.length, totalFireCount };
+}
+/** 配置采样（只读）+ 合法性判定。 */
+function readConfig(configFile) {
+    const def = defaultConfig();
+    const raw = readJsonSafe(configFile);
+    const sample = {
+        exists: raw !== undefined,
+        idleDetect: def.idleDetect,
+        afterMs: def.idleTrigger.afterMs,
+        minGapMs: def.limits.minGapMs,
+        maxPerHour: def.limits.maxPerHour,
+        issues: [],
+    };
+    if (!isPlainObject(raw)) {
+        if (raw !== undefined)
+            sample.issues.push("config.json 不是合法 JSON（已按默认配置解读）");
+        return sample;
+    }
+    const detect = raw.idleDetect;
+    if (typeof detect === "string") {
+        if (!["terminal", "input-only", "off"].includes(detect)) {
+            sample.issues.push(`idleDetect 非法：「${detect}」（允许 terminal | input-only | off）`);
+        }
+        else {
+            sample.idleDetect = detect;
+        }
+    }
+    const idleTrigger = isPlainObject(raw.idleTrigger) ? raw.idleTrigger : undefined;
+    if (idleTrigger !== undefined && typeof idleTrigger.afterMs === "number") {
+        sample.afterMs = idleTrigger.afterMs;
+    }
+    const limits = isPlainObject(raw.limits) ? raw.limits : undefined;
+    if (limits !== undefined) {
+        if (typeof limits.minGapMs === "number")
+            sample.minGapMs = limits.minGapMs;
+        if (typeof limits.maxPerHour === "number")
+            sample.maxPerHour = limits.maxPerHour;
+    }
+    return sample;
+}
+// ---------------------------------------------------------------- 主入口
+/**
+ * 采集插件面健康快照（**纯读**）。
+ *
+ * @param agentDir agent 根目录（`$PI_CODING_AGENT_DIR` 或 `~/.pi/agent`）
+ */
+export function collectHealth(agentDir, opts) {
+    const now = opts?.now ?? Date.now();
+    const root = proactiveDir(agentDir);
+    const layout = [];
+    const push = (name, p, optional = false) => {
+        const st = statSafe(p);
+        layout.push({
+            name,
+            path: p,
+            exists: st !== undefined,
+            shape: st === undefined ? "missing" : st.isDirectory() ? "dir" : "file",
+            optional,
+        });
+    };
+    push("config.json", path.join(root, "config.json"));
+    push("agents/", path.join(root, "agents"));
+    push("mailbox/", path.join(root, "mailbox"));
+    push("run/", path.join(root, "run"));
+    push("processed/", path.join(root, "processed"));
+    push("threads/", path.join(root, "threads"));
+    push("lineage/（事件流）", path.join(root, "lineage"), true);
+    const installed = statSafe(root)?.isDirectory() === true;
+    const entries = installed ? readRegistryEntries(path.join(root, "agents")) : [];
+    const mailbox = installed ? readMailbox(path.join(root, "mailbox"), now) : { pending: 0, oldestPendingAgeMs: null, failedArchived: 0, stuckUnclaimed: 0 };
+    const endpoints = installed ? readEndpoints(agentDir, path.join(root, "run"), entries, now) : { total: 0, zombie: 0, zombiePaths: [] };
+    const events = installed ? readEvents(path.join(root, "lineage"), now) : { exists: false, lastEventAgeMs: null, streams: 0, deliveredThisHour: 0, lastDeliveredAt: null };
+    const tasks = installed ? readTasks(path.join(root, "tasks.json")) : { count: 0, totalFireCount: 0 };
+    const config = readConfig(path.join(root, "config.json"));
+    const handoverFile = readLatestHandover(agentDir);
+    const handover = {
+        exists: handoverFile !== undefined,
+        path: handoverFile?.path ?? null,
+        date: handoverFile?.date ?? null,
+        content: handoverFile?.content ?? null,
+    };
+    const registryOfflineBeyondRetention = entries.filter((e) => beyondRetention(e, now)).length;
+    let oldestEntryAgeMs = null;
+    for (const e of entries) {
+        const age = now - e.lastSeen;
+        if (oldestEntryAgeMs === null || age > oldestEntryAgeMs)
+            oldestEntryAgeMs = age;
+    }
+    const limitsSource = events.exists
+        ? `近似值：guard 计数是**进程内状态、不落盘**，巡检读不到；此处按事件流里本小时「已记账(delivered)」的事件数近似（deferred/dropped 不计）。`
+        : `不可得：guard 计数是**进程内状态、不落盘**，且事件流不存在 → 巡检无法读出已用次数（只有上限可从配置读出）。`;
+    const used = events.exists ? events.deliveredThisHour : null;
+    const cooldownRemainingMs = used !== null && events.lastDeliveredAt !== null && config.minGapMs !== null
+        ? Math.max(0, config.minGapMs - (now - events.lastDeliveredAt))
+        : null;
+    const report = {
+        agentDir,
+        generatedAt: now,
+        pluginVersion: pluginVersion(),
+        hostVersion: hostVersion(),
+        layout,
+        registry: {
+            entries: entries.length,
+            offlineBeyondRetention: registryOfflineBeyondRetention,
+            oldestEntryAgeMs,
+        },
+        mailbox,
+        endpoints,
+        events: { exists: events.exists, lastEventAgeMs: events.lastEventAgeMs, streams: events.streams },
+        tasks,
+        limits: {
+            limit: config.maxPerHour ?? defaultConfig().limits.maxPerHour,
+            used,
+            cooldownRemainingMs,
+            source: limitsSource,
+        },
+        config: {
+            exists: config.exists,
+            valid: config.issues.length === 0,
+            idleDetect: config.idleDetect,
+            afterMs: config.afterMs,
+            minGapMs: config.minGapMs,
+            maxPerHour: config.maxPerHour,
+            issues: config.issues,
+        },
+        handover,
+        findings: [],
+        overall: "ok",
+    };
+    report.findings = buildFindings(report, { installed });
+    report.findings.push(handoverFinding(report));
+    report.overall = worstStatus(report.findings);
+    return report;
+}
+function worstStatus(findings) {
+    if (findings.some((f) => f.status === "fail"))
+        return "fail";
+    if (findings.some((f) => f.status === "warn"))
+        return "warn";
+    return "ok";
+}
+const STATUS_LABEL = { ok: "ok", warn: "warn", fail: "fail" };
+/** 由实测值派生体检结论（**判定逻辑只在这里**；shell / doctor 都只消费结论）。 */
+function buildFindings(report, ctx) {
+    const out = [];
+    const T = HEALTH_THRESHOLDS;
+    // ---- 布局
+    if (!ctx.installed) {
+        out.push({
+            id: "layout.installed",
+            label: "插件面目录",
+            status: "fail",
+            value: `缺失：${proactiveDir(report.agentDir)}`,
+            criterion: "插件落盘根目录必须存在",
+            thresholdSource: "实现口径：config.ts 的 proactiveDir()（插件的所有落盘面都在其下）",
+            advice: "确认 pi-proactive 已安装且至少跑过一次会话（插件在 session_start 时建立落盘目录）。",
+            alertKind: "PLUGIN_NOT_LOADED",
+        });
+    }
+    else {
+        const missing = report.layout.filter((l) => !l.exists && !l.optional);
+        out.push({
+            id: "layout.required",
+            label: "落盘布局",
+            status: missing.length === 0 ? "ok" : "warn",
+            value: missing.length === 0
+                ? `必需项齐全（${report.layout.filter((l) => !l.optional).length} 项）`
+                : `缺少：${missing.map((m) => m.name).join("、")}`,
+            criterion: "config.json / agents/ / mailbox/ / run/ / processed/ / threads/ 必须存在",
+            thresholdSource: "实现口径：各模块的落盘路径（registry.ts / mailbox.ts / socket.ts / thread.ts）",
+            advice: missing.length === 0 ? "无需处置。" : "缺失项通常是插件尚未在该 agent 下跑过会话；跑一次即可补齐。",
+        });
+        const eventsDir = report.layout.find((l) => l.name.startsWith("lineage"));
+        out.push({
+            id: "layout.events",
+            label: "事件流目录",
+            status: eventsDir?.exists ? "ok" : "warn",
+            value: eventsDir?.exists ? `存在（${eventsDir.path}）` : `缺失：${eventsDir?.path ?? ""}`,
+            criterion: "事件流目录（lineage/）存在 → 有可核对的血缘记录",
+            thresholdSource: "实现口径：lineage.ts 的 append() 落盘路径",
+            advice: eventsDir?.exists ? "无需处置。" : "事件流未初始化：跑一次会话（session_start）后会生成；期间的额度用量巡检读不到。",
+        });
+    }
+    // 插件面目录都不存在 → 其余各项**无从谈起**（报了也是噪声）：只保留 PLUGIN_NOT_LOADED。
+    if (!ctx.installed)
+        return out;
+    // ---- 注册表
+    const reg = report.registry;
+    out.push({
+        id: "registry.stale",
+        label: "注册表陈旧条目",
+        status: reg.offlineBeyondRetention > T.registryStaleWarn ? "warn" : "ok",
+        value: `条目 ${reg.entries} 个 · 超保留窗 ${reg.offlineBeyondRetention} 个 · 最老条目年龄 ${reg.oldestEntryAgeMs === null ? "—" : formatAge(reg.oldestEntryAgeMs)}`,
+        criterion: `不在场（offline 或心跳过期 > 3×心跳）且超保留窗（max(3×心跳, 24h)）的条目 > ${T.registryStaleWarn} 个即告警`,
+        thresholdSource: "实现口径：registry.ts 的 sweepStaleEntries()（离线判定 3×心跳、保留窗 OFFLINE_ENTRY_MIN_RETENTION_MS=24h）；条目数阈值 5 为本卡设定",
+        advice: reg.offlineBeyondRetention > T.registryStaleWarn
+            ? "多为崩溃残留：插件每小时 GC 一次；若持续增长，检查是否有进程被 kill -9（心跳停摆但 status 仍停在线）。"
+            : "无需处置。",
+        alertKind: "REGISTRY_STALE",
+    });
+    // ---- 邮箱
+    const mb = report.mailbox;
+    out.push({
+        id: "mailbox.backlog",
+        label: "邮箱待处理堆积",
+        status: mb.pending > T.mailboxBacklogFail ? "fail" : mb.pending > T.mailboxBacklogWarn ? "warn" : "ok",
+        value: `待处理 ${mb.pending} 封 · 最老一封 ${mb.oldestPendingAgeMs === null ? "—" : formatAge(mb.oldestPendingAgeMs)} · 失败归档 ${mb.failedArchived} 封`,
+        criterion: `待处理信封 > ${T.mailboxBacklogWarn} 告警、> ${T.mailboxBacklogFail} 严重`,
+        thresholdSource: "本卡设定（规范无既有邮箱堆积阈值）；单轮投递上限 50 封取自 mailbox.ts 的 DEFAULT_MAX_ENVELOPES_PER_SCAN",
+        advice: mb.pending > T.mailboxBacklogWarn
+            ? "堆积说明收件方没有在消费：确认该 agent 的会话是否还在运行（收件方离线时消息会一直排队）。"
+            : "无需处置。",
+        alertKind: "MAILBOX_BACKLOG",
+    });
+    out.push({
+        id: "mailbox.stuck",
+        label: "邮箱滞留未认领",
+        status: mb.stuckUnclaimed > 0 ? "warn" : "ok",
+        value: `滞留 ${mb.stuckUnclaimed} 封（收件箱里放超过 1 小时仍未被认领）`,
+        criterion: `收件箱里滞留超过 ${formatAge(T.mailboxStuckMs)} 仍未被认领的信封 > 0 即告警`,
+        thresholdSource: "实现口径：mailbox.ts 的 DEFAULT_STALE_CLAIM_MS（认领锁失效时长 = 1 小时），同一把尺子",
+        advice: mb.stuckUnclaimed > 0
+            ? "收件方长时间不消费：检查其会话是否卡死/已退出；滞留信封在对方上线后仍会被取回（不丢）。"
+            : "无需处置。",
+        alertKind: "MAILBOX_STUCK",
+    });
+    // ---- 端点
+    const ep = report.endpoints;
+    out.push({
+        id: "endpoints.zombie",
+        label: "端点僵尸",
+        status: ep.zombie > 0 ? "warn" : "ok",
+        value: `端点 ${ep.total} 个 · 僵尸 ${ep.zombie} 个${ep.zombiePaths.length > 0 ? `（${ep.zombiePaths.map((p) => path.basename(p)).join("、")}）` : ""}`,
+        criterion: "端点文件存在、但没有活着的监听者（无对应注册表条目 / 条目已离线或心跳过期 / 进程已不存在）→ 僵尸",
+        thresholdSource: "实现口径：registry.ts 的离线判定（3×心跳）与 socket.ts 的端点路径推导；**不连接对端 socket**（连接 = 对外交互，与只读巡检冲突）",
+        advice: ep.zombie > 0
+            ? "僵尸端点会被对端启动时的「端点已被占用/僵尸端点清理」逻辑自动清掉；持续出现说明有进程反复异常退出。"
+            : "无需处置。",
+        alertKind: "ENDPOINT_DEAD",
+    });
+    // ---- 事件流
+    const ev = report.events;
+    out.push({
+        id: "events.stale",
+        label: "事件流新鲜度",
+        status: ev.exists && ev.lastEventAgeMs !== null && ev.lastEventAgeMs > T.eventStreamStaleMs ? "warn" : "ok",
+        value: ev.exists
+            ? `最后一条事件距今 ${ev.lastEventAgeMs === null ? "—" : formatAge(ev.lastEventAgeMs)}（事件流 ${ev.streams} 个）`
+            : "无事件流",
+        criterion: `事件流存在且最后一条事件距今 > ${formatAge(T.eventStreamStaleMs)} 即告警`,
+        thresholdSource: "阈值取 registry.ts 的 OFFLINE_ENTRY_MIN_RETENTION_MS（24h）同量级（本卡设定）；事件流路径取 lineage.ts",
+        advice: ev.exists && ev.lastEventAgeMs !== null && ev.lastEventAgeMs > T.eventStreamStaleMs
+            ? "长时间没有新的主动投递/协作记录：确认插件是否还在该会话里工作（事件流只追加，不会自己清理）。"
+            : "无需处置。",
+        alertKind: "EVENT_STREAM_STALE",
+    });
+    // ---- 任务表
+    out.push({
+        id: "tasks.size",
+        label: "任务表规模",
+        status: report.tasks.count > T.taskTableBloated ? "warn" : "ok",
+        value: `任务 ${report.tasks.count} 个 · fireCount 累计 ${report.tasks.totalFireCount}`,
+        criterion: `任务数 > ${T.taskTableBloated} 即告警`,
+        thresholdSource: "本卡设定（规范无既有任务表上限）；fireCount 读自 tasks.json（task-store.ts 的落盘格式）",
+        advice: report.tasks.count > T.taskTableBloated
+            ? "任务表只增不减（用完需手动 /proactive cancel）：用 /proactive tasks 列出并清理过期任务。"
+            : "无需处置。",
+        alertKind: "TASKTABLE_BLOATED",
+    });
+    // ---- 额度 / 冷却
+    const lim = report.limits;
+    const ratio = lim.used !== null && lim.limit > 0 ? lim.used / lim.limit : null;
+    out.push({
+        id: "limits.guard",
+        label: "主动额度 / 冷却",
+        status: ratio !== null && ratio >= T.guardNearLimitRatio ? "warn" : "ok",
+        value: lim.used === null
+            ? `本小时已用 不可得 · 上限 ${lim.limit} 次/小时 · 冷却剩余 不可得`
+            : `本小时已用 ${lim.used}/${lim.limit} 次 · 冷却剩余 ${lim.cooldownRemainingMs === null ? "不可得" : formatAge(lim.cooldownRemainingMs)}`,
+        criterion: `本小时已用次数 ≥ 上限的 ${Math.round(T.guardNearLimitRatio * 100)}% 即告警`,
+        thresholdSource: `上限取配置 limits.maxPerHour（默认 6，config.ts 的 defaultConfig()）；比例 80% 为本卡设定；已用次数为**近似值**（${lim.source}）`,
+        advice: ratio !== null && ratio >= T.guardNearLimitRatio
+            ? "接近上限：主动投递会被护栏 drop（本小时不再触发）。需要放宽就调大配置里的 limits.maxPerHour。"
+            : "无需处置。",
+        alertKind: "GUARD_NEAR_LIMIT",
+    });
+    // ---- 配置
+    const cfg = report.config;
+    const afterBad = cfg.afterMs !== null && (cfg.afterMs < T.idleAfterMsSaneMin || cfg.afterMs > T.idleAfterMsSaneMax);
+    const gapBad = cfg.minGapMs !== null && cfg.minGapMs < T.minGapMsFloor;
+    const relation = cfg.minGapMs !== null && cfg.afterMs !== null
+        ? cfg.minGapMs >= cfg.afterMs
+            ? `冷却(${cfg.minGapMs}ms) ≥ 空闲阈值(${cfg.afterMs}ms)`
+            : `冷却(${cfg.minGapMs}ms) < 空闲阈值(${cfg.afterMs}ms)`
+        : "—";
+    out.push({
+        id: "config.valid",
+        label: "配置有效性",
+        status: cfg.issues.length > 0 ? "fail" : afterBad || gapBad ? "warn" : "ok",
+        value: `idleDetect=${cfg.idleDetect} · afterMs=${cfg.afterMs ?? "—"} · minGapMs=${cfg.minGapMs ?? "—"} · maxPerHour=${cfg.maxPerHour ?? "—"} · ${relation}${cfg.issues.length > 0 ? ` · 问题：${cfg.issues.join("；")}` : ""}`,
+        criterion: `idleDetect 必须是 terminal|input-only|off；afterMs 落在 [${formatAge(T.idleAfterMsSaneMin)}, ${formatAge(T.idleAfterMsSaneMax)}]；minGapMs ≥ ${formatAge(T.minGapMsFloor)}`,
+        thresholdSource: "取值集合来自 types.ts 的 IdleDetect；区间为本卡设定（默认 afterMs=600000、minGapMs=300000 见 config.ts 的 defaultConfig()）",
+        advice: cfg.issues.length > 0
+            ? "改 <agent-dir>/proactive/config.json（非法项会被忽略并回落默认值，文件不会被覆盖）。"
+            : afterBad || gapBad
+                ? "阈值过于极端：空闲触发会过密或永不到点；建议回到默认量级（10 分钟 / 5 分钟）。"
+                : "无需处置。",
+        alertKind: cfg.issues.length > 0 ? "CONFIG_INVALID" : undefined,
+    });
+    return out;
+}
+/** 毫秒 → 人可读时长。 */
+export function formatAge(ms) {
+    const v = Math.max(0, Math.round(ms / 1000));
+    if (v < 60)
+        return `${v}s`;
+    const m = Math.floor(v / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h${m % 60 ? `${m % 60}m` : ""}`;
+    const d = Math.floor(h / 24);
+    return `${d}d${h % 24 ? `${h % 24}h` : ""}`;
+}
+/**
+ * 由体检结论派生巡检告警（**唯一真源**）。
+ *
+ * `scripts/team-health.sh` 只把这些告警塞进既有 pending 队列 —— 不在 shell 里重写判定。
+ */
+export function pluginAlerts(report) {
+    const out = [];
+    for (const f of report.findings) {
+        if (!f.alertKind)
+            continue;
+        if (f.status === "ok")
+            continue;
+        out.push({ alertType: f.alertKind, severity: f.status, evidence: `${f.label}：${f.value}｜判据：${f.criterion}｜建议：${f.advice}` });
+    }
+    return out;
+}
+/**
+ * 交班摘要的体检结论（**信息项**：没有交班摘要不算坏 —— 没启用常驻值班是正常状态）。
+ */
+function handoverFinding(report) {
+    const h = report.handover;
+    if (!h.exists) {
+        return {
+            id: "daemon.handover",
+            label: "交班摘要",
+            status: "ok",
+            value: "无交班摘要（未启用常驻值班属正常）",
+            criterion: "常驻值班每次停机/交班会写 `proactive/handover/<date>.md`；没有该文件 = 没有发生过值班交班",
+            thresholdSource: "实现口径：daemon-config.ts 的 writeHandoverSummary()",
+            advice: "需要 7×24 值班时安装常驻进程（tools/daemon-install.sh），并先打开预算上限。",
+        };
+    }
+    const firstLine = (h.content ?? "").split("\n").find((l) => l.trim() !== "") ?? "";
+    return {
+        id: "daemon.handover",
+        label: "交班摘要",
+        status: "ok",
+        value: `${h.date} · ${firstLine.trim()}`,
+        criterion: "最近一次交班摘要存在且可读",
+        thresholdSource: `实现口径：${h.path ?? "proactive/handover/<date>.md"}`,
+        advice: "看完整摘要：直接打开上面的文件（夜里做了什么 / 花了多少 / 为什么 + 待人工确认队列）。",
+    };
+}
+/** `/proactive doctor` 的人看输出（一屏：状态 + 实测值 + 判据 + 处置建议）。 */
+export function formatHealthReport(report) {
+    const lines = [];
+    lines.push(`proactive doctor · ${report.pluginVersion}（宿主 ${report.hostVersion ?? "未知"}）· agentDir=${report.agentDir} · 总体=${STATUS_LABEL[report.overall]}`);
+    for (const f of report.findings) {
+        lines.push(`[${STATUS_LABEL[f.status]}] ${f.label}：${f.value}`);
+        lines.push(`      判据：${f.criterion}`);
+        lines.push(`      依据：${f.thresholdSource}`);
+        if (f.status !== "ok")
+            lines.push(`      建议：${f.advice}`);
+    }
+    if (report.handover.exists && report.handover.content !== null) {
+        lines.push("");
+        lines.push("—— 最近交班摘要 ——");
+        for (const line of report.handover.content.split("\n")) {
+            if (line.trim() === "")
+                continue;
+            lines.push(line);
+        }
+    }
+    lines.push("（本命令只读：不注入、不提问、不排期、不写文件、不消耗主动额度）");
+    return lines.join("\n");
+}
+/** 机器可读输出（`--json`）。 */
+export function healthToJson(report) {
+    return JSON.stringify({ report, alerts: pluginAlerts(report) }, null, 2);
+}
+// ---------------------------------------------------------------- CLI（供巡检脚本消费）
+//
+// `node --experimental-strip-types pi-proactive/src/health.ts --json [--agent-dir <dir>]`
+//
+// **被 import 时不做任何事**（只有作为主模块启动才输出）→ 扩展 import 本文件零副作用。
+function isMainModule() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return path.resolve(entry) === path.resolve(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule()) {
+    const argv = process.argv.slice(2);
+    let agentDir = process.env.PI_CODING_AGENT_DIR ?? "";
+    let asJson = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--json")
+            asJson = true;
+        else if (arg === "--agent-dir") {
+            i += 1;
+            agentDir = argv[i] ?? "";
+        }
+    }
+    if (!agentDir)
+        agentDir = path.join(os.homedir(), ".pi", "agent");
+    const report = collectHealth(agentDir);
+    if (asJson) {
+        process.stdout.write(`${healthToJson(report)}\n`);
+    }
+    else {
+        process.stdout.write(`${formatHealthReport(report)}\n`);
+    }
+}