pi-proactive 0.2.0-beta.2 → 0.2.0-beta.3

package/build/src/trust-metrics.js

@@ -0,0 +1,236 @@
+/**
+ * 信任层的**指标与守恒等式**（卡 D1 的四段闭环 + 卡 D4 的三项指标）。
+ *
+ * 口径唯一源：**只读事件流**（`src/lineage.ts` 的 JSONL）——
+ * 不读登记册、不读内存状态 → 指标可由第三方**独立复算**（同一份账本 → 同一组数）。
+ *
+ * 三项指标（承 `docs/product/assistant-trust-model.md` §4 的口径）：
+ * ```
+ * 回应率      = answered / delivered          （它主动的 → 我回应的）
+ * 托付闭环率  = settled / registered           （托付 → 到达 → 知会 → 结账）
+ * 守候时长    = 平均(知会时刻 − 登记时刻)      （我不用守着的时间）
+ * ```
+ *
+ * 守恒等式（每条托付一条链，**不得跳段、不得重复**）：
+ * ```
+ * registered → arrived → notified → settled
+ * 每条链缺一段 → 记一条违规（少一段 = 红）
+ * 聚合等式：登记数 = 结账数 + 撤销数 + 在途数（重复登记 / 悬空都会破坏它）
+ * ```
+ *
+ * @capability: trust-metrics
+ * @observable: pi-proactive/src/trust-metrics.ts:computeTrustMetrics
+ * @attribution: pi-proactive/src/trust-metrics.ts:computeTrustMetrics
+ * @outcome: pi-proactive/src/trust-metrics.ts:ConservationReport
+ * @checked: test:pi-proactive/tests/trust-metrics.test.ts#D4-1 三项指标可从事件流算出
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** 托付链的阶段顺序（**不得跳段**）。 */
+const CHAIN = ["registered", "arrived", "notified", "settled"];
+/** 只取信任层事件（`type === "trust"`）。 */
+function trustEvents(events) {
+    const out = [];
+    for (const e of events) {
+        if (e.type !== "trust" || e.trust === undefined)
+            continue;
+        const id = e.trust.entrustmentId;
+        if (id === undefined || id === "")
+            continue;
+        out.push({ id, stage: e.trust.stage, ts: e.ts, event: e });
+    }
+    return out;
+}
+/**
+ * 托付四段的守恒等式。
+ *
+ * 判据（可机检、能红）：
+ * - 每条托付的阶段链必须是 `registered → arrived → notified → settled` 的**子序列**；
+ * - **跳段即违规**（例如有 `settled` 却没有 `notified` → 「少一段」→ 红）；
+ * - **重复即违规**（同一阶段两条 → 记一条；聚合等式也会因此失衡）；
+ * - 聚合等式：`登记数 == 结账数 + 撤销数 + 在途数`。
+ */
+export function evaluateEntrustmentConservation(events) {
+    const rows = trustEvents(events);
+    const byEntrustment = new Map();
+    for (const r of rows) {
+        const list = byEntrustment.get(r.id) ?? [];
+        list.push({ stage: r.stage, ts: r.ts });
+        byEntrustment.set(r.id, list);
+    }
+    const violations = [];
+    let registered = 0;
+    let arrived = 0;
+    let notified = 0;
+    let settled = 0;
+    let revoked = 0;
+    let humanGated = 0;
+    let inFlight = 0;
+    for (const [id, list] of byEntrustment) {
+        list.sort((a, b) => a.ts - b.ts);
+        const stages = list.map((l) => l.stage);
+        const countOf = (s) => stages.filter((x) => x === s).length;
+        registered += countOf("registered");
+        arrived += countOf("arrived");
+        notified += countOf("notified");
+        settled += countOf("settled");
+        revoked += countOf("revoked");
+        humanGated += countOf("human-gated");
+        // 重复阶段（去重失效 → 清单里同一件事出现两次）。
+        for (const s of CHAIN) {
+            if (countOf(s) > 1)
+                violations.push(`${id}: 重复阶段 ${s} ×${countOf(s)}`);
+        }
+        // 起始阶段必须是登记。
+        if (countOf("registered") === 0)
+            violations.push(`${id}: 缺阶段 registered`);
+        // 跳段检查：出现了靠后的阶段，就必须有它前面的阶段。
+        for (let i = 1; i < CHAIN.length; i += 1) {
+            const s = CHAIN[i];
+            if (countOf(s) === 0)
+                continue;
+            for (let j = 0; j < i; j += 1) {
+                const prev = CHAIN[j];
+                if (countOf(prev) === 0)
+                    violations.push(`${id}: 缺阶段 ${prev}（但已有 ${s}）`);
+            }
+        }
+        // 顺序检查：阶段必须按链的顺序出现（时间序）。
+        const orderIdx = new Map(CHAIN.map((s, i) => [s, i]));
+        let last = -1;
+        for (const s of stages) {
+            const idx = orderIdx.get(s);
+            if (idx === undefined)
+                continue; // revoked / human-gated 不在主链上
+            if (idx < last)
+                violations.push(`${id}: 阶段乱序 ${s}`);
+            last = Math.max(last, idx);
+        }
+        // 撤销与结账互斥。
+        if (countOf("settled") > 0 && countOf("revoked") > 0)
+            violations.push(`${id}: 同时结账与撤销`);
+        // 终态判定：在途 = 既没结账也没撤销。
+        if (countOf("settled") === 0 && countOf("revoked") === 0)
+            inFlight += 1;
+    }
+    const equationHolds = registered === settled + revoked + inFlight;
+    if (!equationHolds) {
+        violations.push(`聚合等式不成立：登记 ${registered} ≠ 结账 ${settled} + 撤销 ${revoked} + 在途 ${inFlight}`);
+    }
+    return {
+        registered,
+        arrived,
+        notified,
+        settled,
+        revoked,
+        humanGated,
+        inFlight,
+        equationHolds,
+        violations,
+        balanced: violations.length === 0 && equationHolds,
+    };
+}
+/**
+ * 三项指标（回应率 / 托付闭环率 / 守候时长）+ 守恒等式。
+ *
+ * 全部从**事件流**算 → 可由第三方用同一份账本复算。
+ */
+export function computeTrustMetrics(events) {
+    let delivered = 0;
+    let answered = 0;
+    for (const e of events) {
+        if (e.type === "delivered" && e.result === "delivered")
+            delivered += 1;
+        if (e.type === "answered")
+            answered += 1;
+    }
+    const conservation = evaluateEntrustmentConservation(events);
+    // 守候时长：登记 → 知会（同一托付的第一条 registered 与 notified）。
+    const firstRegistered = new Map();
+    const firstNotified = new Map();
+    for (const e of events) {
+        if (e.type !== "trust" || e.trust === undefined)
+            continue;
+        const id = e.trust.entrustmentId;
+        if (id === undefined)
+            continue;
+        if (e.trust.stage === "registered" && !firstRegistered.has(id))
+            firstRegistered.set(id, e.ts);
+        if (e.trust.stage === "notified" && !firstNotified.has(id))
+            firstNotified.set(id, e.ts);
+    }
+    let totalMs = 0;
+    let count = 0;
+    for (const [id, at] of firstNotified) {
+        const from = firstRegistered.get(id);
+        if (from === undefined)
+            continue;
+        totalMs += Math.max(0, at - from);
+        count += 1;
+    }
+    const rate = (n, d) => (d === 0 ? 0 : n / d);
+    return {
+        responseRate: { numerator: answered, denominator: delivered, value: rate(answered, delivered) },
+        entrustmentClosureRate: { numerator: conservation.settled, denominator: conservation.registered, value: rate(conservation.settled, conservation.registered) },
+        watchDuration: { averageMs: count === 0 ? 0 : totalMs / count, totalMs, count },
+        conservation,
+    };
+}
+/**
+ * 读一个目录下的全部事件流文件（`*.jsonl`）→ 事件列表。
+ *
+ * 坏行跳过（不抛错）——与 `src/lineage.ts` 的读方口径一致。
+ */
+export function readLineageEvents(dir) {
+    let files;
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    for (const f of files) {
+        let raw;
+        try {
+            raw = fs.readFileSync(path.join(dir, f), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of raw.split("\n")) {
+            if (line.trim().length === 0)
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed?.ts === "number" && typeof parsed?.type === "string")
+                    events.push(parsed);
+            }
+            catch {
+                // 坏行跳过
+            }
+        }
+    }
+    return events;
+}
+/**
+ * CLI：打印指标 JSON（供 `scripts/team/progress-snapshot.sh` 调用 → **同一份实现算指标**，
+ * 避免「脚本里另写一套口径」导致漂移）。
+ *
+ * 用法：`node --experimental-strip-types pi-proactive/src/trust-metrics.ts --dir <lineageDir>`
+ */
+export function main(argv) {
+    const idx = argv.indexOf("--dir");
+    const dir = idx >= 0 ? argv[idx + 1] : undefined;
+    if (dir === undefined) {
+        console.error("用法：trust-metrics.ts --dir <lineageDir>");
+        return 2;
+    }
+    const metrics = computeTrustMetrics(readLineageEvents(dir));
+    console.log(JSON.stringify(metrics));
+    return 0;
+}
+const invokedDirectly = process.argv[1] !== undefined && process.argv[1].endsWith("trust-metrics.ts");
+if (invokedDirectly) {
+    process.exitCode = main(process.argv.slice(2));
+}

package/build/src/trust-notify.js

@@ -0,0 +1,73 @@
+/**
+ * 通道判定（纯函数）。
+ *
+ * - 空闲 → `wake`（用户不在 → 直接起一轮）；
+ * - 忙 → `queue`（排队，不打断正在做的事）；
+ * - 需人立刻决定（urgent）→ `interrupt`（担责的事不能等）。
+ */
+export function resolveTrustChannels(input) {
+    const session = input.urgent ? "interrupt" : input.idle ? "wake" : "queue";
+    // 设备级通知**一律发**（托付达成 = 用户明确交代过的事 → 值得一条设备通知；
+    // 会话通道决定「什么时候起一轮」，设备通道决定「用户不在电脑前也能收到」）。
+    const channels = [`session-${session}`, "device"];
+    return { session, device: true, channels };
+}
+/**
+ * 托付知会器。
+ *
+ * 幂等：同一条托付**只**知会一次（第二次 → `duplicate`，不再投递、不再落事件）。
+ */
+export class TrustNotifier {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 知会一条**已到达**的托付。
+     *
+     * 顺序：查状态（已知会 → 重复，返回）→ 投递（会话 + 设备）→ 标记知会 → 落 `notified` 事件。
+     * 需要人决定的托付 → **不投递**（只产出 human-gated 记录）：担责的事不代劳。
+     */
+    async notifyEntrustment(entrustmentId, opts = {}) {
+        const e = this.deps.registry.getEntrustment(entrustmentId);
+        if (e === undefined)
+            return { entrustmentId, delivered: false, reason: "not-found", channels: [] };
+        if (e.status === "notified" || e.status === "settled") {
+            return { entrustmentId, delivered: false, reason: "duplicate", channels: [] };
+        }
+        if (e.status !== "arrived") {
+            return { entrustmentId, delivered: false, reason: "not-arrived", channels: [] };
+        }
+        if (e.needsHuman === true) {
+            const reason = e.humanReason ?? "需要人决定";
+            this.deps.registry.markNeedsHuman(entrustmentId, reason);
+            this.deps.lineage?.noteTrust({ stage: "human-gated", entrustmentId, goalId: e.goalId, reason });
+            return { entrustmentId, delivered: false, reason: "needs-human", channels: [] };
+        }
+        const plan = resolveTrustChannels({ idle: opts.idle ?? true, urgent: opts.urgent ?? false });
+        const title = "托付达成";
+        const body = `${e.target} —— 条件已满足。`;
+        const channels = [];
+        if (this.deps.deliverSession !== undefined) {
+            await this.deps.deliverSession({ title, body, intent: plan.session });
+            channels.push(`session-${plan.session}`);
+        }
+        if (plan.device && this.deps.notifyDevice !== undefined) {
+            this.deps.notifyDevice(title, body);
+            channels.push("device");
+        }
+        const marked = this.deps.registry.markNotified(entrustmentId);
+        if (marked === undefined) {
+            return { entrustmentId, delivered: false, reason: "duplicate", channels };
+        }
+        const waitedMs = marked.notifiedAt !== undefined && marked.createdAt !== undefined ? marked.notifiedAt - marked.createdAt : undefined;
+        this.deps.lineage?.noteTrust({
+            stage: "notified",
+            entrustmentId,
+            goalId: e.goalId,
+            channel: channels.join("+"),
+            ...(waitedMs !== undefined ? { waitedMs } : {}),
+        });
+        return { entrustmentId, delivered: true, channels };
+    }
+}

package/build/src/trust-policy.js

@@ -0,0 +1,58 @@
+/**
+ * 主动性策略：**空闲触发降级为默认浅层**（卡 D2）。
+ *
+ * 依据 `docs/product/assistant-trust-model.md` §3：
+ * > 空闲触发只是**默认浅层用法**（应默认静默、能等就等）；主动性的真正来源是**用户的托付**。
+ *
+ * 判据（两条闸门，缺一即不开口）：
+ * 1. **有用户交代**：没有任何托付 / 未竟目标支撑 → 不开口（默认静默）；
+ * 2. **确有价值**：DECIDE1 分数低于阈值 → 不开口（不产生无价值打扰）。
+ *
+ * 分数**复用 DECIDE1**（`src/idle.ts:scoreDecision` —— 同一把尺子，不另立公式），
+ * 输入的三个分量各自带**来源**（可复核「这个数从哪来」）。
+ *
+ * @capability: trust-shallow-idle
+ * @observable: pi-proactive/src/trust-policy.ts:evaluateShallowIdle
+ * @attribution: pi-proactive/src/trust-policy.ts:evaluateShallowIdle
+ * @outcome: pi-proactive/src/trigger.ts:Trigger
+ * @checked: test:pi-proactive/tests/trust-policy.test.ts#D2-4 接线实证
+ */
+import { scoreDecision } from "./idle.js";
+/** 浅层策略的缺省值（**默认静默**）。 */
+export const DEFAULT_SHALLOW_IDLE_POLICY = {
+    enabled: true,
+    requireUserBacking: true,
+    threshold: 1,
+    observeRatio: 0.5,
+};
+/**
+ * 浅层空闲判定（纯函数）。
+ *
+ * - **默认静默**：没有用户交代 → `speak=false`（reason = `no-backing`）；
+ * - **不产生无价值打扰**：分数 < 阈值 → `speak=false`（reason = `below-threshold`）；
+ * - 两条都过 → `speak=true`（reason = `speak`）。
+ */
+export function evaluateShallowIdle(input) {
+    const scoring = scoreDecision({
+        value: { score: input.value, source: input.valueSource },
+        urgency: { score: input.urgency, source: input.urgencySource },
+        interruptionCost: { score: input.interruptionCost, source: input.interruptionCostSource },
+    }, input.policy.threshold, input.policy.observeRatio);
+    if (input.policy.requireUserBacking && !input.backedByUserRequest) {
+        return { speak: false, reason: "no-backing", score: scoring.score };
+    }
+    if (scoring.band !== "trigger") {
+        return { speak: false, reason: "below-threshold", score: scoring.score };
+    }
+    return { speak: true, reason: "speak", score: scoring.score };
+}
+/**
+ * 这条信封是不是**空闲触发**（`src/idle.ts:buildIdleEnvelope` 造出来的）。
+ *
+ * 为什么用信封标记而不是 `cause`：既有空闲路径**没有**把 `cause:"idle"` 传给投递层
+ * （`src/idle.ts` 的 `fireIdle` → `deliverToModel` 不带 cause）→ 投递层只能靠信封自身
+ * 的确定性标记识别（`id` 前缀 + `subject`），两者都由 `buildIdleEnvelope` 固定生成。
+ */
+export function isIdleTriggerEnvelope(msg) {
+    return msg.id.startsWith("idle-") || msg.subject === "空闲触发";
+}

package/build/src/trust-registry.js

@@ -0,0 +1,323 @@
+/**
+ * 托付与目标的**登记册**（信任层的事实源 · 卡 D1/D6）。
+ *
+ * 为什么要有登记册：托付（"盯着 X"）与目标（"把发布流程跑通"）若只存在于对话里，
+ * 就**无法查、无法撤、无法结账** → 主动性的价值无从证明。登记册把二者变成
+ * **有状态、可查、可撤销**的记录，每次状态变化都落成**只追加**的事件（`src/lineage.ts`）。
+ *
+ * 设计要点（对齐 `docs/product/agentic-loop.md` 与 `docs/product/assistant-trust-model.md`）：
+ * - **托付 = 目标 + 条件**（L-B 是 L-C 的一个实例）：托付带一个**可判定**的到达条件；
+ * - **目标必须可判定完成**：`doneWhen` 缺失或不可判定 → 目标**不得**进入自主推进（护栏①）；
+ * - **状态机是显式的**：托付 `active → arrived → notified → settled`（或 `revoked`）；
+ *   目标 `open → achieved | abandoned | needs-human` —— 「需人决策」是**一等状态**，
+ *   不允许被静默折叠成「完成」；
+ * - **落盘是原子的**：临时文件 + rename（避免半截 JSON 读坏整个登记册）；
+ * - **不越界**：目标带 `scope`（范围标签）—— 自主推进只能改变范围内的状态。
+ *
+ * 落盘位置：`<agentDir>/proactive/trust/registry.json`（与邮箱 / 线程 / 事件流同族目录）。
+ *
+ * @capability: trust-entrust
+ * @observable: pi-proactive/src/trust-registry.ts:TrustRegistry
+ * @attribution: pi-proactive/src/trust-registry.ts:TrustRegistry.registerEntrustment
+ * @outcome: pi-proactive/src/trust-metrics.ts:ConservationReport
+ * @checked: test:pi-proactive/tests/trust-registry.test.ts#D1-2 四段闭环成立
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { ensureDir, writeAtomicFile } from "./config.js";
+/** 登记册文件格式版本。 */
+export const REGISTRY_SCHEMA_VERSION = 1;
+/** 目标是否**可判定完成**（护栏①的判据）。 */
+export function isDecidable(goal) {
+    const d = goal.doneWhen;
+    if (d === undefined)
+        return false;
+    if (d.type === "checklist")
+        return d.items.length > 0;
+    return Number.isFinite(d.target);
+}
+/** 目标是否**已达成**（按完成定义判定，缺省定义 → 未达成）。 */
+export function goalSatisfied(goal) {
+    const d = goal.doneWhen;
+    if (d === undefined)
+        return false;
+    if (d.type === "checklist")
+        return d.items.length > 0 && d.items.every((i) => i.done);
+    if (d.op === ">=")
+        return d.current >= d.target;
+    if (d.op === "<=")
+        return d.current <= d.target;
+    return d.current === d.target;
+}
+/** 目标差距（还差多少 / 哪些没做完）—— 候选行动的来源。 */
+export function goalGap(goal) {
+    const d = goal.doneWhen;
+    if (d === undefined)
+        return { remaining: 1, total: 1, ratio: 1, items: [] };
+    if (d.type === "checklist") {
+        const undone = d.items.filter((i) => !i.done);
+        return {
+            remaining: undone.length,
+            total: d.items.length,
+            ratio: d.items.length === 0 ? 1 : undone.length / d.items.length,
+            items: undone.map((i) => i.text),
+        };
+    }
+    const span = Math.abs(d.target - d.current);
+    const step = span === 0 ? 1 : Math.max(1, Math.abs(d.target));
+    return { remaining: span, total: step, ratio: Math.min(1, span / step), items: [`${d.name} → ${d.op} ${d.target}`] };
+}
+/**
+ * 托付与目标的登记册（单一事实源）。
+ *
+ * 状态迁移全部走**显式方法**（`markArrived` / `markNotified` / `settle` / `revoke`），
+ * 不允许调用方直接改状态 → 状态机只有一处实现，事件流与登记册不会漂移。
+ */
+export class TrustRegistry {
+    agentDir;
+    ownerAgentId;
+    now;
+    goals = [];
+    entrustments = [];
+    /** 载入时的坏数据计数（读不动的记录被跳过，不抛错）。 */
+    stale = 0;
+    constructor(opts) {
+        this.agentDir = opts.agentDir;
+        this.ownerAgentId = opts.agentId;
+        this.now = opts.now ?? Date.now;
+        this.load();
+    }
+    /** 登记册文件绝对路径。 */
+    path() {
+        return path.join(this.agentDir, "proactive", "trust", "registry.json");
+    }
+    /** 载入登记册（文件缺失 → 空册；坏记录 → 跳过并计数，绝不抛错）。 */
+    load() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.path(), "utf8");
+        }
+        catch {
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.stale += 1;
+            return;
+        }
+        const file = parsed;
+        this.goals = Array.isArray(file.goals) ? file.goals.filter((g) => g && typeof g.id === "string") : [];
+        this.entrustments = Array.isArray(file.entrustments)
+            ? file.entrustments.filter((e) => e && typeof e.id === "string")
+            : [];
+    }
+    /** 落盘（临时文件 + rename → 原子；失败不抛错，只记日志）。 */
+    save() {
+        const file = this.path();
+        const payload = { schemaVersion: REGISTRY_SCHEMA_VERSION, goals: this.goals, entrustments: this.entrustments };
+        try {
+            ensureDir(path.dirname(file));
+            writeAtomicFile(file, `${JSON.stringify(payload, null, 2)}\n`);
+        }
+        catch (err) {
+            console.error("[proactive] 托付登记册落盘失败", err);
+        }
+    }
+    /** 载入时跳过的坏记录数（审计用）。 */
+    staleRecords() {
+        return this.stale;
+    }
+    // ---- 目标 ----
+    /** 登记一个目标（**完成定义缺省 = 不可判定** → 由护栏拦住自主推进）。 */
+    registerGoal(input) {
+        const at = this.now();
+        const goal = {
+            id: input.id ?? randomUUID(),
+            title: input.title,
+            ...(input.doneWhen !== undefined ? { doneWhen: input.doneWhen } : {}),
+            status: "open",
+            scope: input.scope ?? [],
+            budget: { maxActions: input.maxActions ?? 8, usedActions: 0 },
+            permission: input.permission ?? "auto",
+            progressSteps: 0,
+            createdAt: at,
+            updatedAt: at,
+        };
+        this.goals = [...this.goals.filter((g) => g.id !== goal.id), goal];
+        this.save();
+        return goal;
+    }
+    /** 取目标（不存在 → undefined）。 */
+    getGoal(id) {
+        return this.goals.find((g) => g.id === id);
+    }
+    /** 全部目标（按登记顺序）。 */
+    listGoals() {
+        return [...this.goals];
+    }
+    /** 未竟目标（`open`；自主推进的发现来源之一）。 */
+    listOpenGoals() {
+        return this.goals.filter((g) => g.status === "open");
+    }
+    /** 勾选清单项 / 更新指标当前值（完成定义的推进）。 */
+    updateDoneWhen(goalId, update) {
+        const goal = this.getGoal(goalId);
+        if (goal === undefined || goal.doneWhen === undefined)
+            return undefined;
+        if (goal.doneWhen.type === "checklist" && update.itemId !== undefined) {
+            goal.doneWhen.items = goal.doneWhen.items.map((i) => i.id === update.itemId ? { ...i, done: update.itemDone === true } : i);
+        }
+        if (goal.doneWhen.type === "metric" && update.metricCurrent !== undefined) {
+            goal.doneWhen.current = update.metricCurrent;
+        }
+        goal.updatedAt = this.now();
+        this.save();
+        return goal;
+    }
+    /** 归因推进：这次行动让目标前进了 `delta` 步（可追溯⑤的载体）。 */
+    recordProgress(goalId, delta) {
+        const goal = this.getGoal(goalId);
+        if (goal === undefined)
+            return undefined;
+        goal.progressSteps += delta;
+        goal.updatedAt = this.now();
+        this.save();
+        return goal;
+    }
+    /** 消耗预算（护栏②）：超出上限 → 返回 false（调用方必须停）。 */
+    consumeBudget(goalId, amount = 1) {
+        const goal = this.getGoal(goalId);
+        if (goal === undefined)
+            return false;
+        if (goal.budget.usedActions + amount > goal.budget.maxActions)
+            return false;
+        goal.budget.usedActions += amount;
+        goal.updatedAt = this.now();
+        this.save();
+        return true;
+    }
+    /**
+     * 设置目标状态。
+     *
+     * `needs-human` **必须**带原因（否则就是「静默结账」的变体 → 违反红线）。
+     */
+    setGoalStatus(goalId, status, humanReason) {
+        const goal = this.getGoal(goalId);
+        if (goal === undefined)
+            return undefined;
+        if (status === "needs-human" && (humanReason === undefined || humanReason.trim() === "")) {
+            return undefined;
+        }
+        goal.status = status;
+        if (status === "needs-human")
+            goal.humanReason = humanReason;
+        goal.updatedAt = this.now();
+        this.save();
+        return goal;
+    }
+    // ---- 托付 ----
+    /** 登记一条托付（"盯着 X"）。 */
+    registerEntrustment(input) {
+        const at = this.now();
+        const e = {
+            id: input.id ?? randomUUID(),
+            target: input.target,
+            condition: input.condition,
+            status: "active",
+            ...(input.goalId !== undefined ? { goalId: input.goalId } : {}),
+            ...(input.needsHuman !== undefined ? { needsHuman: input.needsHuman } : {}),
+            ...(input.humanReason !== undefined ? { humanReason: input.humanReason } : {}),
+            createdAt: at,
+        };
+        this.entrustments = [...this.entrustments.filter((x) => x.id !== e.id), e];
+        this.save();
+        return e;
+    }
+    /** 取托付（不存在 → undefined）。 */
+    getEntrustment(id) {
+        return this.entrustments.find((e) => e.id === id);
+    }
+    /** 全部托付。 */
+    listEntrustments() {
+        return [...this.entrustments];
+    }
+    /** 未闭合托付（`active` / `arrived` / `notified` —— 自主推进的发现来源之二）。 */
+    listUnclosedEntrustments() {
+        return this.entrustments.filter((e) => e.status === "active" || e.status === "arrived" || e.status === "notified");
+    }
+    /** 到达（第二段）：条件已满足。 */
+    markArrived(id) {
+        const e = this.getEntrustment(id);
+        if (e === undefined || e.status !== "active")
+            return undefined;
+        e.status = "arrived";
+        e.arrivedAt = this.now();
+        this.save();
+        return e;
+    }
+    /**
+     * 知会（第三段）。
+     *
+     * **幂等**：已 `notified` 的托付再调用 → 返回 undefined（不重复知会、不重复落事件）。
+     * （双通道去重的账本侧：通知器与登记册任一方被重复调用都不会产生第二次知会。）
+     */
+    markNotified(id) {
+        const e = this.getEntrustment(id);
+        if (e === undefined || e.status !== "arrived")
+            return undefined;
+        e.status = "notified";
+        e.notifiedAt = this.now();
+        this.save();
+        return e;
+    }
+    /**
+     * 结账（第四段）。
+     *
+     * **需要人决定的托付不得自动结账**（D3）→ `needsHuman` 的托付调用本方法 → 返回 undefined。
+     */
+    settle(id) {
+        const e = this.getEntrustment(id);
+        if (e === undefined)
+            return undefined;
+        if (e.needsHuman === true)
+            return undefined;
+        if (e.status !== "notified" && e.status !== "arrived")
+            return undefined;
+        e.status = "settled";
+        e.settledAt = this.now();
+        this.save();
+        return e;
+    }
+    /** 撤销（任何时候可撤 —— 护栏④）。 */
+    revoke(id) {
+        const e = this.getEntrustment(id);
+        if (e === undefined || e.status === "settled" || e.status === "revoked")
+            return undefined;
+        e.status = "revoked";
+        e.revokedAt = this.now();
+        this.save();
+        return e;
+    }
+    /**
+     * 标记「需人决策」（human-gated）。
+     *
+     * 记录**原因**；托付**不**被结账（保持 `arrived`/`notified`）→ 可查、可继续。
+     */
+    markNeedsHuman(id, reason) {
+        const e = this.getEntrustment(id);
+        if (e === undefined)
+            return undefined;
+        e.needsHuman = true;
+        e.humanReason = reason;
+        this.save();
+        return e;
+    }
+    /** 本 agent id（事件流用）。 */
+    get agentId() {
+        return this.ownerAgentId;
+    }
+}