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

package/build/src/daemon.js

@@ -0,0 +1,892 @@
+/**
+ * DAEMON7：常驻值班循环（headless · 非交互会话）。
+ *
+ * 六环（brief-v4 §10.3 / 任务卡 §2）：
+ *   ① 在场   → 本文件的值班循环（读 TaskStore → 到点执行 → 记账 → 等待）；
+ *   ② 预算   → `src/daemon-config.ts` 的预算面 + 本文件 `budgetStatus()`（**硬上限**，超限不执行）；
+ *   ③ 闸门   → `classifyAction()`（auto / limited / human-gated；不可逆 → 确认队列，**绝不自动执行**）；
+ *   ④ 执行   → **复用** `Scheduler`（到期判定 + 认领 + 结果处置）与 `TaskStore`（不复制调度逻辑）；
+ *   ⑤ 记账   → `src/lineage.ts` 的统一事件流（**只调用不修改**）+ 本文件的值班状态流水；
+ *   ⑥ 交班   → `src/daemon-config.ts` 的交班摘要（写文件）+ `src/health.ts` 的 doctor 段可读。
+ *
+ * 自愈与残留清理（brief-v4 OP-1）：崩溃恢复（未完成认领 → 清理且**不重放**）、死 socket 清理、临时文件清理。
+ *
+ * 成本硬约束（brief-v4 §10.4）：默认**关闭**（`config.enabled=false`）→ 不花钱；
+ * **动作数**是硬上限；token 只做估算（口径见 `TOKEN_ESTIMATE_NOTE`）。
+ *
+ * G12 四件套（主动能力声明 —— 代码侧声明，与 `scripts/merge-gate.sh` 的台账二选一）：
+// @capability: daemon-duty
+// @observable: pi-proactive/src/daemon.ts:writeHandover
+// @attribution: pi-proactive/src/daemon.ts:classifyAction
+// @outcome: pi-proactive/src/daemon-config.ts:buildHandoverSummary
+// @checked: test:pi-proactive/tests/daemon.test.ts#值班循环
+ */
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// G12 四件套（**主动联系**能力 —— 代码侧声明）：
+// @capability: daemon-contact
+// @observable: pi-proactive/src/daemon.ts:writeHeartbeat
+// @attribution: pi-proactive/src/daemon-contact.ts:decideContact
+// @outcome: pi-proactive/src/daemon-config.ts:appendContactEntry
+// @checked: test:pi-proactive/tests/daemon-contact.test.ts#目标判定
+import { proactiveDir, resolveAgentDir, ensureDir, writeAtomicFile } from "./config.js";
+import { Scheduler } from "./scheduler.js";
+import { TaskStore } from "./task-store.js";
+import { Lineage } from "./lineage.js";
+import { appendContactAudit, appendContactEntry, buildHandoverSummary, classifyAction, dayKey, estimateTokenUnits, heartbeatPath, loadDaemonConfig, loadDaemonState, MAX_ACTION_LOG, formatContactList, readContactEntries, saveDaemonState, writeHandoverSummary, } from "./daemon-config.js";
+import { decideContact } from "./daemon-contact.js";
+import { detectHost } from "./daemon-host.js";
+import { buildContactPayload, selectNotifyChannels } from "./notify.js";
+import { Registry } from "./registry.js";
+import { createEnvelope } from "./envelope.js";
+import { deliverCrossProcess } from "./socket.js";
+const HOUR_MS = 3_600_000;
+/** 心跳间隔（ms）：外部验证「它还活着」的刷新周期。 */
+const HEARTBEAT_INTERVAL_MS = 5_000;
+/** 动作标题的最大长度（截断后的标题进流水与交班摘要）。 */
+const MAX_TITLE_LEN = 60;
+/** 创建干跑执行器。 */
+export function createDryRunExecutor(opts) {
+    const now = opts?.now ?? Date.now;
+    const calls = [];
+    return {
+        calls,
+        recordsLineage: false,
+        async deliver(msg, intent, o) {
+            calls.push({
+                at: now(),
+                envelopeId: msg.id,
+                intent,
+                body: msg.body,
+                ...(o.task !== undefined ? { taskId: o.task.id } : {}),
+            });
+            return "delivered";
+        },
+    };
+}
+/**
+ * 常驻值班进程。
+ *
+ * 生命周期：`start()` → 值班循环（定时 tick + 维护）→ `stop()`（停循环 + 写交班摘要 + 落盘）。
+ *
+ * 异常隔离：tick 整体 try/catch —— 宿主/守护进程的单次异常不得让整个值班进程死掉。
+ */
+export class Daemon {
+    agentId;
+    agentDir;
+    config;
+    executor;
+    now;
+    log;
+    store;
+    lineage;
+    scheduler;
+    state;
+    timer;
+    /** 心跳定时器（独立于 tick 周期 → 「它还活着」的证据始终新鲜）。 */
+    heartbeatTimer;
+    lastSweepAt = 0;
+    lastHandoverDay = "";
+    stopped = false;
+    /** 常驻宿主（herdr / launchd / systemd）—— 写进心跳，外部可查。 */
+    hostKind;
+    /** 设备通知通道（注入点；缺省 → 自动挑）。 */
+    notifyChannels;
+    constructor(opts) {
+        this.agentId = opts.config.agentId;
+        this.agentDir = opts.agentDir;
+        this.config = opts.config;
+        this.executor = opts.executor;
+        this.now = opts.now ?? Date.now;
+        this.log = opts.logger ?? ((msg) => console.warn(`[proactive-daemon] ${msg}`));
+        this.store = opts.store ?? new TaskStore({ agentDir: this.agentDir, agentId: this.agentId, now: this.now });
+        this.lineage =
+            opts.lineage ?? new Lineage({ agentDir: this.agentDir, agentId: this.agentId, now: this.now });
+        this.state = loadDaemonState(this.agentDir, this.now());
+        this.hostKind = opts.hostKind ?? detectHost().hostKind;
+        this.notifyChannels = opts.notifyChannels;
+        this.scheduler = new Scheduler({
+            store: this.store,
+            trigger: { deliverToModel: (msg, intent, o) => this.handleDelivery(msg, intent, o) },
+            agentId: this.agentId,
+            now: this.now,
+            tickIntervalMs: this.config.tickIntervalMs,
+            logger: this.log,
+            // 7×24 真跑总开关（默认关闭 → 不投递任何任务 → 不花钱）。
+            enabled: () => this.config.enabled,
+        });
+    }
+    /** 当前值班状态（只读快照）。 */
+    get stateView() {
+        return this.state;
+    }
+    /** 任务表（只读引用；供测试构造任务）。 */
+    get taskStore() {
+        return this.store;
+    }
+    /** 起值班循环（幂等）。 */
+    async start() {
+        if (this.timer !== undefined)
+            return;
+        await this.recoverAfterCrash();
+        this.timer = setInterval(() => {
+            void this.tick();
+        }, this.config.tickIntervalMs);
+        // 心跳独立于 tick（tick 可能 30 秒一次 → 外部验证「还活着」不该等那么久）。
+        this.heartbeatTimer = setInterval(() => {
+            this.writeHeartbeat();
+        }, HEARTBEAT_INTERVAL_MS);
+        this.heartbeatTimer.unref?.();
+        // 立刻写一次心跳：**监督器靠心跳判活**（等 5s 才有心跳 → 接管会慢 5s；更糟的是
+        // 两个监督器可能同时判定「没有心跳」→ 双开值班进程）。
+        this.writeHeartbeat();
+        this.log(`值班循环已启动（agent=${this.agentId} · tick=${this.config.tickIntervalMs}ms · enabled=${this.config.enabled} · dryRun=${this.config.dryRun}）`);
+    }
+    /** 停值班循环（幂等）：停循环 → 写交班摘要 → 落盘。 */
+    async stop() {
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (this.heartbeatTimer !== undefined) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+        this.scheduler.stop();
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.writeHandover();
+        this.saveState();
+        this.log("值班循环已停止（已写交班摘要）");
+    }
+    /** 执行一次值班 tick（到期判定 → 执行 → 记账 → 维护）。 */
+    async tick(now = this.now()) {
+        if (this.stopped)
+            return;
+        try {
+            await this.scheduler.tick(now);
+        }
+        catch (err) {
+            this.log(`tick 失败（已隔离）：${errText(err)}`);
+        }
+        try {
+            this.refreshBudgetWindow(now);
+            await this.maintenance(now);
+        }
+        catch (err) {
+            this.log(`维护失败（已隔离）：${errText(err)}`);
+        }
+        // 心跳（**外部可验证「它还活着」**：文件里的 ts 随 tick 前进）。
+        this.writeHeartbeat(now);
+        // 主动联系（7×24 助理的硬需求：它**主动找我**）。
+        try {
+            await this.maybeContact(now);
+        }
+        catch (err) {
+            this.log(`主动联系失败（已隔离）：${errText(err)}`);
+        }
+    }
+    /**
+     * 写心跳文件（`<agentDir>/proactive/daemon/heartbeat.json`）。
+     *
+     * 为什么单独一个文件：安装脚本要**外部可验证**「它真的起来了」——
+     * 进程在 + 心跳在更新 + 单元已加载，三条证据缺一不可。
+     */
+    writeHeartbeat(now = this.now()) {
+        const file = heartbeatPath(this.agentDir);
+        const body = {
+            ts: now,
+            pid: process.pid,
+            agentId: this.agentId,
+            host: this.hostKind,
+            runMode: this.config.dryRun ? "dry-run" : "live",
+            enabled: this.config.enabled,
+            contactEnabled: this.config.contact.enabled,
+        };
+        try {
+            ensureDir(path.dirname(file));
+            writeAtomicFile(file, `${JSON.stringify(body, null, 2)}\n`, { durable: true });
+        }
+        catch {
+            // 心跳写失败不影响值班（它只是可观测证据，不是业务数据）
+        }
+        return file;
+    }
+    /**
+     * 主动联系（**它主动找我**）。
+     *
+     * 顺序固定：总开关 → 预算硬上限 → 决策（目标 / 频次 / 每日上限）→ 会话投递 →
+     * 设备级通知（去重策略）→ 记账 → 落清单。
+     *
+     * 不变量：**只联系已登记会话**；找不到目标 → **不联系**（只留可查记录）。
+     */
+    async maybeContact(now = this.now()) {
+        if (!this.config.enabled)
+            return;
+        const cfg = this.config.contact;
+        if (!cfg.enabled)
+            return;
+        const budget = this.budgetStatus(now);
+        if (budget.exhausted) {
+            this.log(`主动联系被预算挡住：${budget.reason}`);
+            return;
+        }
+        const registry = new Registry({ agentDir: this.agentDir, now: this.now });
+        const decision = decideContact({
+            config: cfg,
+            entries: registry.listAll(),
+            recent: readContactEntries(this.agentDir),
+            now,
+            selfAgentId: this.agentId,
+        });
+        if (decision.action !== "contact" || decision.target === undefined) {
+            // **可查记录**：不联系也要留下「为什么没联系」（用户能查）。
+            appendContactAudit(this.agentDir, { ts: now, reason: decision.reason });
+            this.log(`主动联系跳过：${decision.reason}`);
+            return;
+        }
+        const target = decision.target;
+        const eventId = decision.eventId ?? `c-${now}-${target.agentId}`;
+        const payload = buildContactPayload({ ...cfg.payload, why: this.contactWhy() });
+        const channels = [];
+        // ① 会话投递（**只投给已登记会话**）。
+        let sessionStatus = "failed";
+        try {
+            const envelope = createEnvelope({
+                from: this.agentId,
+                to: target.agentId,
+                kind: "notify",
+                intent: "notify",
+                body: payload.body ?? "",
+                subject: payload.title,
+            });
+            const ack = await deliverCrossProcess({
+                targetAgentId: target.agentId,
+                envelope,
+                agentDir: this.agentDir,
+            });
+            sessionStatus = ack.status;
+            if (ack.status === "accepted" || ack.status === "duplicate")
+                channels.push("session");
+        }
+        catch (err) {
+            sessionStatus = `error: ${errText(err)}`;
+        }
+        // ② 设备级通知（`fallback` = 会话没送达才发 → **双通道去重**，用户不被打扰两次）。
+        if (cfg.deviceNotify === "always" || !channels.includes("session")) {
+            const deviceChannels = this.notifyChannels ?? selectNotifyChannels({ channels: ["herdr", "osx", "linux"] });
+            for (const channel of deviceChannels) {
+                const res = await channel.send(payload);
+                if (res.ok) {
+                    channels.push("device");
+                    break;
+                }
+            }
+        }
+        // ③ 记账（**联系也算一次动作** → 预算硬上限不被绕过）。
+        this.countAction("limited", payload.body ?? "", channels.includes("session") ? "delivered" : "notified");
+        this.pushAction({
+            ts: now,
+            title: `主动联系 ${target.agentId}`,
+            tier: "limited",
+            outcome: channels.length > 0 ? "executed" : "failed",
+            reason: `${decision.reason} · 通道=${channels.join("+") || "无"} · 会话投递=${sessionStatus}`,
+            tokenUnits: 0,
+        });
+        // ④ 落清单（**同一事件只一条**：两条通道用同一个 eventId）。
+        appendContactEntry(this.agentDir, {
+            eventId,
+            ts: now,
+            outcome: channels.includes("session")
+                ? channels.includes("device")
+                    ? "both"
+                    : "session"
+                : channels.includes("device")
+                    ? "device"
+                    : "failed",
+            channels,
+            targetAgentId: target.agentId,
+            payload,
+            reason: `会话投递=${sessionStatus}`,
+        });
+        this.saveState();
+        this.log(`已主动联系 ${target.agentId}（通道：${channels.join("+") || "无"}）`);
+    }
+    /** 「为什么找你」的现实理由（有排队动作就说实话；否则用配置里的模板）。 */
+    contactWhy() {
+        const queued = this.state.queue.length;
+        if (queued > 0)
+            return `有 ${queued} 个动作在等你确认`;
+        return this.config.contact.payload.why;
+    }
+    /**
+     * 崩溃恢复（**幂等**）：死 socket、过期任务认领、半成品执行、临时文件。
+     *
+     * 半成品的处置口径：**清理且不重放** —— 不可逆动作宁可漏做一次，也不可重做一次。
+     */
+    async recoverAfterCrash() {
+        const now = this.now();
+        const report = {
+            deadSocketsRemoved: [],
+            staleClaimsRemoved: 0,
+            abandonedExecutions: [],
+            tempFilesRemoved: [],
+        };
+        report.deadSocketsRemoved = await sweepDeadSockets(this.agentDir, this.config.staleSocketMs, now);
+        try {
+            report.staleClaimsRemoved = this.store.sweepStaleClaims();
+        }
+        catch {
+            report.staleClaimsRemoved = 0;
+        }
+        for (const [key, rec] of Object.entries(this.state.executions)) {
+            if (rec.status === "claimed" && now - rec.ts > this.config.staleExecutionMs) {
+                delete this.state.executions[key];
+                report.abandonedExecutions.push(key);
+                this.pushAction({
+                    ts: now,
+                    taskId: rec.taskId || undefined,
+                    title: `崩溃前未完成的执行 ${key}`,
+                    tier: "limited",
+                    outcome: "failed",
+                    reason: "崩溃残留（认领未完成）→ 已清理且**不重放**（宁可漏做不可重做）",
+                    tokenUnits: 0,
+                });
+            }
+        }
+        report.tempFilesRemoved = sweepTempFiles(this.agentDir, this.config.staleExecutionMs, now);
+        this.saveState();
+        if (report.deadSocketsRemoved.length > 0 ||
+            report.abandonedExecutions.length > 0 ||
+            report.tempFilesRemoved.length > 0 ||
+            report.staleClaimsRemoved > 0) {
+            this.log(`崩溃恢复：死 socket ${report.deadSocketsRemoved.length} 个 · 过期认领 ${report.staleClaimsRemoved} 个 · 半成品执行 ${report.abandonedExecutions.length} 个 · 临时文件 ${report.tempFilesRemoved.length} 个`);
+        }
+        return report;
+    }
+    /** 写交班摘要（返回文件路径）。 */
+    writeHandover(now = this.now()) {
+        const summary = buildHandoverSummary(this.state, now, this.agentId, this.config.budget);
+        const file = writeHandoverSummary(this.agentDir, summary);
+        this.lastHandoverDay = summary.date;
+        return file;
+    }
+    /** 预算判定（**硬上限**）。 */
+    budgetStatus(now = this.now()) {
+        this.refreshBudgetWindow(now);
+        const b = this.state.budget;
+        const cfg = this.config.budget;
+        const status = {
+            hourCount: b.hourCount,
+            dayCount: b.dayCount,
+            limitedDayCount: b.limitedDayCount,
+            tokenUnits: b.tokenUnits,
+            exhausted: false,
+        };
+        if (b.hourCount >= cfg.maxActionsPerHour) {
+            status.exhausted = true;
+            status.reason = `每小时动作上限已满（${b.hourCount}/${cfg.maxActionsPerHour}）`;
+        }
+        else if (b.dayCount >= cfg.maxActionsPerDay) {
+            status.exhausted = true;
+            status.reason = `每日动作上限已满（${b.dayCount}/${cfg.maxActionsPerDay}）`;
+        }
+        else if (b.tokenUnits >= cfg.maxTokenUnitsPerDay) {
+            status.exhausted = true;
+            status.reason = `每日 token 估算上限已满（${b.tokenUnits}/${cfg.maxTokenUnitsPerDay}，估算口径非实测）`;
+        }
+        return status;
+    }
+    // ---- 内部实现 ----
+    /**
+     * 一次投递的**唯一**决策点（预算 → 幂等 → 闸门 → 执行 → 记账）。
+     *
+     * 顺序是刻意的：**先判预算再判闸门**（预算耗尽时连「要不要执行」都不必问 → 省判定）；
+     * **幂等在执行前**（同一触发周期只执行一次）。
+     */
+    async handleDelivery(msg, intent, opts) {
+        const now = this.now();
+        const task = this.findTask(msg.id);
+        const prompt = task?.prompt ?? msg.body;
+        const title = titleOf(prompt);
+        const cls = classifyAction(prompt, this.config.permissions);
+        const key = task !== undefined ? `${task.id}@${task.dueAt}` : `${msg.id}@${msg.createdAt}`;
+        // ---- ① 幂等：同一触发周期只执行一次 ----
+        const prev = this.state.executions[key];
+        if (prev !== undefined) {
+            this.pushAction({
+                ts: now,
+                ...(task !== undefined ? { taskId: task.id } : {}),
+                title,
+                tier: cls.tier,
+                outcome: "skipped-duplicate",
+                reason: `幂等：同一触发周期已执行过（台账 ${key}）→ 本次不重复执行`,
+                tokenUnits: 0,
+            });
+            this.noteDropped(msg, task, `幂等：同一触发周期已执行过（${key}）`);
+            return "deferred";
+        }
+        // ---- ② 预算（硬上限）：超限 → 不执行 + 降级为只观察 + 记账 ----
+        const budget = this.budgetStatus(now);
+        if (budget.exhausted) {
+            const reason = `${budget.reason} → 不执行，降级为只观察`;
+            if (this.config.budget.degradeToObserveWhenExhausted) {
+                this.pushAction({
+                    ts: now,
+                    ...(task !== undefined ? { taskId: task.id } : {}),
+                    title,
+                    tier: cls.tier,
+                    outcome: "observe-only",
+                    reason,
+                    tokenUnits: 0,
+                });
+                this.noteDropped(msg, task, reason);
+                return "deferred";
+            }
+            // 不降级 → 直接停掉这个任务（不是静默停摆：记账 + 事件流里有原因）。
+            this.pushAction({
+                ts: now,
+                ...(task !== undefined ? { taskId: task.id } : {}),
+                title,
+                tier: cls.tier,
+                outcome: "observe-only",
+                reason: `${budget.reason} → 不执行（未开启降级观察，任务被停用）`,
+                tokenUnits: 0,
+            });
+            this.noteDropped(msg, task, `${budget.reason} → 任务被停用`);
+            return "dropped";
+        }
+        // ---- ③ 闸门：不可逆 → 绝不自动执行（进确认队列）----
+        let gate = cls;
+        if (cls.tier === "limited" && budget.limitedDayCount >= this.config.budget.maxLimitedActionsPerDay) {
+            gate = {
+                tier: "human-gated",
+                reason: `limited 档每日上限已满（${budget.limitedDayCount}/${this.config.budget.maxLimitedActionsPerDay}）→ 降级为人工确认`,
+                matched: cls.matched,
+            };
+        }
+        if (gate.tier === "human-gated") {
+            const queued = this.enqueue({
+                ts: now,
+                ...(task !== undefined ? { taskId: task.id } : {}),
+                title,
+                prompt,
+                reason: `${gate.reason} → 不可逆动作，绝不自动执行（已入人工确认队列）`,
+            });
+            this.pushAction({
+                ts: now,
+                ...(task !== undefined ? { taskId: task.id } : {}),
+                title,
+                tier: gate.tier,
+                outcome: "queued",
+                reason: `${gate.reason} → 人工确认队列 #${queued.id}`,
+                tokenUnits: 0,
+            });
+            this.noteDropped(msg, task, `${gate.reason} → 已入人工确认队列（未执行）`);
+            return "deferred";
+        }
+        // ---- ④ 执行（先认领 → 执行 → 记账）----
+        this.state.executions[key] = { key, ts: now, status: "claimed", taskId: task?.id ?? msg.id };
+        this.saveState();
+        let outcome;
+        try {
+            outcome = await this.executor.deliver(msg, intent, {
+                ...(task !== undefined ? { task: task } : {}),
+                dryRun: this.config.dryRun,
+            });
+        }
+        catch (err) {
+            outcome = "failed";
+            this.log(`执行异常：${errText(err)}`);
+        }
+        if (outcome === "delivered" || outcome === "notified") {
+            this.state.executions[key] = { key, ts: now, status: "done", taskId: task?.id ?? msg.id };
+            this.countAction(cls.tier, prompt, outcome);
+            this.pushAction({
+                ts: now,
+                ...(task !== undefined ? { taskId: task.id } : {}),
+                title,
+                tier: cls.tier,
+                outcome: "executed",
+                reason: `档位=${cls.tier}（${cls.reason}）→ 已执行（${outcome}）`,
+                tokenUnits: outcome === "delivered" ? estimateTokenUnits(prompt) : 0,
+            });
+            if (this.executor.recordsLineage !== true) {
+                this.lineage.noteDelivery({
+                    cause: "schedule",
+                    result: outcome,
+                    envelopeId: msg.id,
+                    ...(task !== undefined ? { taskId: task.id } : {}),
+                    bodyLen: prompt.length,
+                    reason: `档位=${cls.tier}`,
+                });
+            }
+            this.saveState();
+            return outcome;
+        }
+        // 未成功 → 释放认领（允许下一周期重试；台账不留半成品）。
+        delete this.state.executions[key];
+        this.pushAction({
+            ts: now,
+            ...(task !== undefined ? { taskId: task.id } : {}),
+            title,
+            tier: cls.tier,
+            outcome: "failed",
+            reason: `执行未成功（${outcome}）→ 下一周期重试`,
+            tokenUnits: 0,
+        });
+        if (this.executor.recordsLineage !== true) {
+            this.lineage.noteDelivery({
+                cause: "schedule",
+                result: outcome,
+                envelopeId: msg.id,
+                ...(task !== undefined ? { taskId: task.id } : {}),
+                reason: `执行未成功（${outcome}）`,
+            });
+        }
+        this.saveState();
+        return outcome;
+    }
+    /** 找任务（按 id）。 */
+    findTask(id) {
+        try {
+            return this.store.list().find((t) => t.id === id);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** 记一次「被拦下」（事件流 → `/proactive history` 可见）。 */
+    noteDropped(msg, task, reason) {
+        this.lineage.noteDropped({
+            cause: "schedule",
+            reason,
+            envelopeId: msg.id,
+            ...(task !== undefined ? { taskId: task.id } : {}),
+        });
+    }
+    /** 入人工确认队列（**落盘** → 早间交班时呈现）。 */
+    enqueue(entry) {
+        const id = `q${entry.ts}-${this.state.queue.length + 1}`;
+        const queued = { id, ...entry };
+        this.state.queue.push(queued);
+        this.saveState();
+        return queued;
+    }
+    /** 记一次动作（流水；上限 `MAX_ACTION_LOG`）。 */
+    pushAction(record) {
+        this.state.actions.push(record);
+        if (this.state.actions.length > MAX_ACTION_LOG) {
+            this.state.actions.splice(0, this.state.actions.length - MAX_ACTION_LOG);
+        }
+    }
+    /** 计数（动作数 = 尝试执行的次数；token 只在真的投递出去时估算）。 */
+    countAction(tier, prompt, outcome) {
+        const b = this.state.budget;
+        b.hourCount += 1;
+        b.dayCount += 1;
+        if (tier === "limited")
+            b.limitedDayCount += 1;
+        if (outcome === "delivered")
+            b.tokenUnits += estimateTokenUnits(prompt);
+    }
+    /**
+     * 刷新预算窗口。
+     *
+     * **时钟漂移保护**：时钟往回跳时**不重置**计数（否则回拨一天就能绕过每日上限）；
+     * 往前跳则正常开新窗口。
+     */
+    refreshBudgetWindow(now) {
+        const b = this.state.budget;
+        const drift = now < this.state.lastSeenAt;
+        if (!drift) {
+            if (now - b.hourWindowStart >= HOUR_MS) {
+                b.hourWindowStart = now;
+                b.hourCount = 0;
+            }
+            const dk = dayKey(now);
+            if (dk !== b.dayKey) {
+                b.dayKey = dk;
+                b.dayCount = 0;
+            }
+            if (dk !== b.limitedDayKey) {
+                b.limitedDayKey = dk;
+                b.limitedDayCount = 0;
+            }
+            if (dk !== b.tokenDayKey) {
+                b.tokenDayKey = dk;
+                b.tokenUnits = 0;
+            }
+        }
+        if (now > this.state.lastSeenAt)
+            this.state.lastSeenAt = now;
+    }
+    /** 维护（死 socket 清理 + 交班）。 */
+    async maintenance(now) {
+        if (now - this.lastSweepAt >= HOUR_MS) {
+            this.lastSweepAt = now;
+            const removed = await sweepDeadSockets(this.agentDir, this.config.staleSocketMs, now);
+            if (removed.length > 0)
+                this.log(`清理死 socket ${removed.length} 个`);
+        }
+        const today = dayKey(now);
+        if (today !== this.lastHandoverDay && new Date(now).getHours() === this.config.handoverHour) {
+            const file = this.writeHandover(now);
+            this.log(`已写交班摘要：${file}`);
+        }
+    }
+    /** 落盘值班状态。 */
+    saveState() {
+        saveDaemonState(this.agentDir, this.state);
+    }
+}
+/** 动作标题（截断 + 压空白）。 */
+function titleOf(text) {
+    const flat = (text ?? "").replace(/\s+/g, " ").trim();
+    return flat.length > MAX_TITLE_LEN ? `${flat.slice(0, MAX_TITLE_LEN)}…` : flat;
+}
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * 清理**死 socket**：`run/` 下 socket 文件在，但**没有活着的监听者** → 删掉。
+ *
+ * 判据（两条，任一命中即判死）：
+ * ① mtime 超过阈值（`staleSocketMs`）→ 判死（长期没人接管的端点）；
+ * ② 探测连接被拒（`ECONNREFUSED` / `ENOENT`）→ 判死（文件在但没人监听）。
+ *
+ * 探测用短超时（默认 300ms）→ 不会挂住；**判不出来时保留**（宁可漏清也不误删活着的端点）。
+ */
+export async function sweepDeadSockets(agentDir, staleSocketMs, now = Date.now(), opts) {
+    const runDir = path.join(proactiveDir(agentDir), "run");
+    let names;
+    try {
+        names = fs.readdirSync(runDir);
+    }
+    catch {
+        return [];
+    }
+    const removed = [];
+    for (const name of names) {
+        if (!name.endsWith(".sock"))
+            continue;
+        const file = path.join(runDir, name);
+        let mtimeMs = 0;
+        try {
+            mtimeMs = fs.statSync(file).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (now - mtimeMs > staleSocketMs) {
+            if (unlinkQuiet(file))
+                removed.push(file);
+            continue;
+        }
+        const alive = await isSocketAlive(file, opts?.probeTimeoutMs ?? 300);
+        if (alive === false && unlinkQuiet(file))
+            removed.push(file);
+    }
+    return removed;
+}
+/**
+ * socket 是否有人监听（`true` = 活着；`false` = 死；`undefined` = 判不出来 → 保守保留）。
+ */
+export async function isSocketAlive(file, timeoutMs = 300) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(v);
+        };
+        let socket;
+        try {
+            socket = net.connect({ path: file });
+        }
+        catch {
+            resolve(undefined);
+            return;
+        }
+        const timer = setTimeout(() => {
+            socket.destroy();
+            finish(undefined);
+        }, timeoutMs);
+        timer.unref?.();
+        socket.on("connect", () => {
+            clearTimeout(timer);
+            socket.destroy();
+            finish(true);
+        });
+        socket.on("error", () => {
+            clearTimeout(timer);
+            finish(false);
+        });
+    });
+}
+/** 删文件（失败不算错）。 */
+function unlinkQuiet(file) {
+    try {
+        fs.unlinkSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 清理临时文件（`*.tmp`，超过阈值才删；避免删掉正在写的）。 */
+export function sweepTempFiles(agentDir, staleMs, now = Date.now()) {
+    const roots = [proactiveDir(agentDir), path.join(proactiveDir(agentDir), "daemon")];
+    const removed = [];
+    for (const root of roots) {
+        let names;
+        try {
+            names = fs.readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!name.endsWith(".tmp"))
+                continue;
+            const file = path.join(root, name);
+            try {
+                const st = fs.statSync(file);
+                if (!st.isFile())
+                    continue;
+                if (now - st.mtimeMs <= staleMs)
+                    continue;
+                if (unlinkQuiet(file))
+                    removed.push(file);
+            }
+            catch {
+                // 读不到就跳过
+            }
+        }
+    }
+    return removed;
+}
+/**
+ * 启动常驻值班进程（**不含**信号处理；CLI 负责装 SIGTERM/SIGINT）。
+ *
+ * 默认 `enabled=false`（成本硬约束）→ 值班循环在跑但不投递任何任务。
+ */
+export async function runDaemon(opts = {}) {
+    const agentDir = opts.agentDir ?? resolveAgentDir();
+    const agentId = resolveDaemonAgentId();
+    const loaded = loadDaemonConfig(agentDir, agentId);
+    for (const notice of loaded.notices)
+        console.error(`[proactive-daemon] ${notice}`);
+    const config = opts.config ?? loaded.config;
+    const daemon = new Daemon({
+        agentDir,
+        config,
+        executor: opts.executor ?? createDryRunExecutor({ now: opts.now }),
+        ...(opts.now !== undefined ? { now: opts.now } : {}),
+        ...(opts.logger !== undefined ? { logger: opts.logger } : {}),
+    });
+    await daemon.start();
+    return {
+        daemon,
+        stop: () => daemon.stop(),
+    };
+}
+/**
+ * 稳定身份（**跨重启连续**）。
+ *
+ * - 显式 `PI_PROACTIVE_AGENT_ID` → 用它（brief-v4 §10.2：身份稳定不必等 ARCH-1）；
+ * - 否则 `employee#<host>#pi-proactive-daemon`（常驻员工的可读身份）。
+ */
+export function resolveDaemonAgentId(env = process.env) {
+    const explicit = env.PI_PROACTIVE_AGENT_ID?.trim();
+    if (explicit !== undefined && explicit !== "")
+        return explicit;
+    // host 取自环境（避免在此引入 os 依赖；launchd/systemd 都会给 HOSTNAME）。
+    const host = env.HOSTNAME?.trim() || "localhost";
+    return `employee#${host}#pi-proactive-daemon`;
+}
+// ---------------------------------------------------------------- CLI
+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;
+    }
+}
+/**
+ * CLI：`node --experimental-strip-types pi-proactive/src/daemon.ts [--agent-dir <dir>] [--once] [--handover] [--enable]`
+ *
+ * **永远干跑**：CLI 没有宿主 → 不可能真的调模型；真跑需要宿主注入执行器（`DaemonExecutor`）。
+ * `--enable` 只打开「允许投递到执行器」，仍走干跑执行器 → **不会花钱**。
+ */
+if (isMainModule()) {
+    const argv = process.argv.slice(2);
+    let agentDir = process.env.PI_CODING_AGENT_DIR ?? "";
+    let once = false;
+    let handoverOnly = false;
+    let enable = false;
+    let contactOnce = false;
+    let listContacts = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--agent-dir") {
+            i += 1;
+            agentDir = argv[i] ?? "";
+        }
+        else if (arg === "--once")
+            once = true;
+        else if (arg === "--handover")
+            handoverOnly = true;
+        else if (arg === "--enable")
+            enable = true;
+        else if (arg === "--contact-once")
+            contactOnce = true;
+        else if (arg === "--list-contacts")
+            listContacts = true;
+    }
+    if (!agentDir)
+        agentDir = resolveAgentDir();
+    const agentId = resolveDaemonAgentId();
+    const loaded = loadDaemonConfig(agentDir, agentId);
+    for (const notice of loaded.notices)
+        console.error(`[proactive-daemon] ${notice}`);
+    const config = loaded.config;
+    if (enable)
+        config.enabled = true;
+    const daemon = new Daemon({
+        agentDir,
+        config,
+        executor: createDryRunExecutor(),
+    });
+    if (listContacts) {
+        console.log(formatContactList(readContactEntries(agentDir)));
+    }
+    else if (contactOnce) {
+        // 主动联系一次（**手动触发**；决策与投递路径与值班循环完全一致）。
+        await daemon.maybeContact();
+        console.log(`联系记录：\n${formatContactList(readContactEntries(agentDir))}`);
+    }
+    else if (handoverOnly) {
+        console.log(daemon.writeHandover());
+    }
+    else if (once) {
+        await daemon.tick();
+        await daemon.stop();
+    }
+    else {
+        await daemon.start();
+        const shutdown = () => {
+            void daemon.stop().then(() => process.exit(0));
+        };
+        process.on("SIGTERM", shutdown);
+        process.on("SIGINT", shutdown);
+    }
+}