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

package/build/src/supervisor-web.js

@@ -0,0 +1,262 @@
+/**
+ * Web 监督面（**只读 · 本地优先 · 无依赖**）。
+ *
+ * 形态：`pi-proactive web [--port N] [--agent-dir D]` → Node 内置 http，**只监听 127.0.0.1**。
+ *
+ * 边界（越界即不合格）：
+ * - **只读**：没有任何写配置的入口（无表单 / 无按钮 / 无写路由；写方法一律 405）；
+ * - **单一数据源**：页面与 API 的数字全部来自 `src/supervisor-state.ts` 的**同一份聚合**
+ *   （本模块**不重算**任何指标）；
+ * - **本地优先**：绑定地址固定 `127.0.0.1`（不从其它网卡暴露）；
+ * - **无依赖**：只用 Node 内置 `http` / `fs` / `path`，前端零框架零构建（样式内联）。
+ *
+ * 页面六块：状态卡 / 联系时间线 / 托付 / 阻塞 / 预算 / 守恒灯。
+ */
+import http from "node:http";
+import { collectSupervisorState, formatBudgetLine, formatConservationLine, formatEntrustmentConservationLine, formatStatusLine, formatSupervisorSummary, } from "./supervisor-state.js";
+/** 只监听的地址（**本地优先**：默认不暴露到局域网/公网）。 */
+export const SUPERVISOR_HOST = "127.0.0.1";
+/** HTML 转义（页面内容来自本地文件，仍按不可信处理）。 */
+function esc(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/** 毫秒 → `MM-DD HH:mm:ss`（本地时区）。 */
+function fmtTime(ts) {
+    const d = new Date(ts);
+    const p = (n) => String(n).padStart(2, "0");
+    return `${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+const STYLE = `
+:root { color-scheme: light dark; }
+body { font: 14px/1.6 -apple-system, "PingFang SC", "Noto Sans CJK SC", system-ui, sans-serif; margin: 0; padding: 24px; }
+h1 { font-size: 18px; margin: 0 0 4px; }
+.sub { opacity: .65; font-size: 12px; margin-bottom: 16px; }
+.grid { display: grid; gap: 12px; grid-template-columns: repeat(auto-fit, minmax(340px, 1fr)); }
+section { border: 1px solid rgba(128,128,128,.35); border-radius: 8px; padding: 12px 14px; }
+section h2 { font-size: 14px; margin: 0 0 8px; letter-spacing: .04em; }
+table { width: 100%; border-collapse: collapse; font-size: 12.5px; }
+td, th { text-align: left; padding: 2px 6px 2px 0; vertical-align: top; }
+.k { opacity: .6; white-space: nowrap; }
+.ok { color: #1a7f37; font-weight: 600; }
+.bad { color: #b42318; font-weight: 600; }
+ul { margin: 4px 0 0; padding-left: 18px; }
+li { font-size: 12.5px; }
+details { margin-top: 8px; font-size: 12px; opacity: .8; }
+code { font-size: 11.5px; }
+`;
+/** 一行键值表。 */
+function row(key, value) {
+    return `<tr><td class="k">${esc(key)}</td><td>${value}</td></tr>`;
+}
+/** 状态卡。 */
+function renderStatus(state) {
+    const s = state.status;
+    return [
+        "<table>",
+        row("摘要", esc(formatSupervisorSummary(state))),
+        row("宿主 / 进程", esc(formatStatusLine(state))),
+        row("在不在", s.running ? '<span class="ok">在跑</span>' : `<span class="bad">不在${s.notRunningReason ? `（${esc(s.notRunningReason)}）` : ""}</span>`),
+        row("心跳时刻", s.heartbeatTs === undefined ? "—" : esc(fmtTime(s.heartbeatTs))),
+        row("上次联系", s.lastContactTs === undefined ? "从未" : esc(fmtTime(s.lastContactTs))),
+        row("值班身份", esc(s.agentId ?? "—")),
+        row("运行形态", esc(s.runMode ?? "—")),
+        row("总开关 / 联系开关", `${s.enabled === undefined ? "—" : s.enabled ? "开" : "关"} / ${s.contactEnabled === undefined ? "—" : s.contactEnabled ? "开" : "关"}`),
+        "</table>",
+    ].join("");
+}
+/** 联系时间线。 */
+function renderTimeline(state) {
+    if (state.timeline.length === 0)
+        return "<p>暂无记录</p>";
+    const rows = state.timeline
+        .slice()
+        .reverse()
+        .map((t) => {
+        const len = t.bodyLen === undefined ? "" : ` · 正文 ${t.bodyLen} 字`;
+        const digest = t.bodyDigest === undefined ? "" : ` · 摘要 ${t.bodyDigest}`;
+        const peer = t.peer === undefined ? "" : ` · 对端 ${t.peer}`;
+        return `<li><span class="k">${esc(fmtTime(t.ts))}</span> · ${esc(t.summary)}${esc(len)}${esc(digest)}${esc(peer)}</li>`;
+    })
+        .join("");
+    return `<ul>${rows}</ul>`;
+}
+/** 托付（含目标）。 */
+function renderTrusts(state) {
+    if (state.trusts.length === 0 && state.goals.length === 0)
+        return "<p>暂无托付</p>";
+    const parts = [];
+    if (state.trusts.length > 0) {
+        const rows = state.trusts
+            .map((t) => `<li>${esc(t.target)} · <span class="k">${esc(t.status)}</span>${t.needsHuman ? " · 需人决策" : ""}${t.humanReason ? ` · ${esc(t.humanReason)}` : ""}</li>`)
+            .join("");
+        parts.push(`<table><tr><th>托付</th><th>状态</th></tr></table><ul>${rows}</ul>`);
+    }
+    if (state.goals.length > 0) {
+        const rows = state.goals
+            .map((g) => `<li>${esc(g.title)} · <span class="k">${esc(g.status)}</span> · 推进 ${g.progressSteps} 步 · 行动 ${g.usedActions}/${g.maxActions}${g.humanReason ? ` · ${esc(g.humanReason)}` : ""}</li>`)
+            .join("");
+        parts.push(`<ul>${rows}</ul>`);
+    }
+    return parts.join("");
+}
+/** 阻塞。 */
+function renderBlockers(state) {
+    if (state.blockers.length === 0)
+        return '<p class="ok">无阻塞</p>';
+    const rows = state.blockers
+        .map((b) => `<li>${esc(b.title)}${b.detail ? ` · ${esc(b.detail)}` : ""}</li>`)
+        .join("");
+    return `<ul>${rows}</ul>`;
+}
+/** 预算。 */
+function renderBudget(state) {
+    return [
+        "<table>",
+        row("余量", esc(formatBudgetLine(state))),
+        row("闸门", state.budget.exhausted ? `<span class="bad">${esc(state.budget.reason ?? "已耗尽")}</span>` : '<span class="ok">未耗尽</span>'),
+        row("耗尽时降级", state.budget.degradeToObserve ? "降级为只观察" : "直接停下"),
+        row("配置", state.budget.configured ? "已读 daemon.json" : "未配置（按缺省上限显示）"),
+        "</table>",
+    ].join("");
+}
+/** 守恒灯。 */
+function renderConservation(state) {
+    const c = state.conservation;
+    return [
+        "<table>",
+        row("行为四段", esc(formatConservationLine(state))),
+        row("托付四段", esc(formatEntrustmentConservationLine(state))),
+        row("回应率", `${(c.responseRate * 100).toFixed(1)}%`),
+        row("托付闭环率", `${(c.closureRate * 100).toFixed(1)}%`),
+        row("守候时长", `${Math.round(c.watchDurationMs / 1000)} 秒`),
+        row("判定", c.equal ? '<span class="ok">四段相等（无悬空）</span>' : '<span class="bad">四段不等（有悬空）</span>'),
+        "</table>",
+    ].join("");
+}
+/** 渲染整页（**服务端渲染**：一处渲染实现 → 页面与 API 不会各说各话）。 */
+export function renderSupervisorHtml(state) {
+    return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="refresh" content="5">
+<title>pi-proactive 监督面</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<h1>pi-proactive 监督面（只读）</h1>
+<p class="sub">数据源：${esc(state.agentDir)} · 聚合于 ${esc(fmtTime(state.generatedAt))} · 本页只读，改配置请回 Pi 会话</p>
+<div class="grid">
+<section><h2>① 状态卡</h2>${renderStatus(state)}</section>
+<section><h2>② 联系时间线</h2>${renderTimeline(state)}</section>
+<section><h2>③ 托付</h2>${renderTrusts(state)}</section>
+<section><h2>④ 阻塞</h2>${renderBlockers(state)}</section>
+<section><h2>⑤ 预算</h2>${renderBudget(state)}</section>
+<section><h2>⑥ 守恒灯</h2>${renderConservation(state)}</section>
+</div>
+<details><summary>数据源路径（可折叠）</summary>
+<code>${esc(state.agentDir)}/proactive/lineage/*.jsonl</code><br>
+<code>${esc(state.agentDir)}/proactive/daemon/heartbeat.json</code><br>
+<code>${esc(state.agentDir)}/proactive/daemon/state.json</code><br>
+<code>${esc(state.agentDir)}/proactive/daemon.json</code><br>
+<code>${esc(state.agentDir)}/proactive/trust/registry.json</code>
+</details>
+</body>
+</html>
+`;
+}
+/**
+ * 启动 Web 监督面（**只监听 127.0.0.1**）。
+ *
+ * @param opts 见 {@link SupervisorWebOptions}。
+ */
+export async function startSupervisorWeb(opts = {}) {
+    const port = opts.port ?? 7799;
+    const collect = () => collectSupervisorState({
+        ...(opts.agentDir !== undefined ? { agentDir: opts.agentDir } : {}),
+        ...(opts.agentId !== undefined ? { agentId: opts.agentId } : {}),
+        ...(opts.timelineLimit !== undefined ? { timelineLimit: opts.timelineLimit } : {}),
+    });
+    const server = http.createServer((req, res) => {
+        // **只读**：只接受 GET / HEAD；其余方法一律 405（页面不提供任何写入口）。
+        const method = (req.method ?? "GET").toUpperCase();
+        if (method !== "GET" && method !== "HEAD") {
+            res.writeHead(405, { "content-type": "text/plain; charset=utf-8" });
+            res.end("只读：监督面不接受写操作\n");
+            return;
+        }
+        const url = req.url ?? "/";
+        const pathOnly = url.split("?")[0];
+        try {
+            if (pathOnly === "/" || pathOnly === "/index.html") {
+                const body = renderSupervisorHtml(collect());
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                res.end(method === "HEAD" ? undefined : body);
+                return;
+            }
+            if (pathOnly === "/api/state") {
+                const body = JSON.stringify(collect(), null, 2);
+                res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+                res.end(method === "HEAD" ? undefined : body);
+                return;
+            }
+            if (pathOnly === "/api/timeline") {
+                const state = collect();
+                const body = JSON.stringify({ timeline: state.timeline, conservation: state.conservation }, null, 2);
+                res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+                res.end(method === "HEAD" ? undefined : body);
+                return;
+            }
+            if (pathOnly === "/api/trusts") {
+                const state = collect();
+                const body = JSON.stringify({ trusts: state.trusts, goals: state.goals }, null, 2);
+                res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+                res.end(method === "HEAD" ? undefined : body);
+                return;
+            }
+            if (pathOnly === "/api/budget") {
+                const state = collect();
+                const body = JSON.stringify({ budget: state.budget, blockers: state.blockers }, null, 2);
+                res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+                res.end(method === "HEAD" ? undefined : body);
+                return;
+            }
+            res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+            res.end("没有这个页面\n");
+        }
+        catch (err) {
+            res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+            res.end(`监督面内部错误：${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        // **只监听 127.0.0.1**（不传 host → 会监听全部网卡 → 违反本地优先）。
+        server.listen(port, SUPERVISOR_HOST, () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const actualPort = typeof address === "object" && address !== null ? address.port : port;
+    let closed = false;
+    return {
+        url: `http://${SUPERVISOR_HOST}:${actualPort}`,
+        port: actualPort,
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+                // 断开残留连接，保证端口**立即**释放（否则 close 会挂住）。
+                server.closeAllConnections?.();
+            });
+        },
+    };
+}

package/build/src/task-store.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L1 内核 · 宿主无关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 不得 import 宿主包、不得出现宿主类型/字段；对外只经宿主无关接口（HostPort 一族）。
 import fs from "node:fs";
 import path from "node:path";
 import { PROACTIVE_FILE_MODE, chmodQuiet, ensureDir, proactiveDir, resolveAgentDir, writeAtomicFile, } from "./config.js";

package/build/src/thread.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L1 内核 · 宿主无关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 不得 import 宿主包、不得出现宿主类型/字段；对外只经宿主无关接口（HostPort 一族）。
 import fs from "node:fs";
 import path from "node:path";
 import { agentSegment } from "./envelope.js";

package/build/src/trigger.js

@@ -1,4 +1,5 @@
 import { digestOf } from "./lineage.js";
+import { evaluateShallowIdle, isIdleTriggerEnvelope } from "./trust-policy.js";
 /** 注入内容自带来源前缀（custom 消息在 LLM 层会变成 role:"user"，模型无法自行区分来源）。 */
 const SOURCE_PREFIX = "[来自 proactive]";
 /** 本地触发的 customType（跨进程 peer 用 "proactive:peer"，M4 才需要）。 */
@@ -87,6 +88,13 @@ export class Trigger {
         try {
             // **触发原因落盘（因）**：判定通过、决定触发的那一刻就把 cause + 判定依据写进事件流。
             this.noteTriggered(msg, cause);
+            // **空闲浅层闸门**（卡 D2）：空闲触发默认静默 —— 没有用户交代、或分数不足 → 不开口。
+            // 缺省未注入 `trustPolicy` → 闸门不生效（既有行为逐字不变）。
+            const shallow = this.evaluateShallow(msg, cause);
+            if (shallow !== undefined && !shallow.speak) {
+                this.noteDropped(msg, cause, shallow.reason);
+                return "dropped";
+            }
             if (intent === "notify") {
                 this.notifyOnly(msg.subject ?? "proactive", msg.body, msg);
                 this.noteDelivery(msg, cause, "notified");
@@ -133,6 +141,41 @@ export class Trigger {
             console.error("[proactive] notify 失败", err);
         }
     }
+    /**
+     * 空闲浅层判定（卡 D2）：**不是**空闲触发、或未注入策略 → 返回 undefined（闸门不生效）。
+     *
+     * 分量的来源（可复核）：
+     * - 价值 = `已空闲时长 / 空闲阈值`（有判定依据时）——缺依据时按 1 计（已由上游判定为可触发）；
+     * - 紧急度 = 1（空闲 = 用户不在场）；
+     * - 打断代价 = 1（浅层判定发生在护栏记账之前，此处不重复计费）。
+     */
+    evaluateShallow(msg, cause) {
+        const policy = this.deps.trustPolicy;
+        if (policy === undefined || policy.enabled === false)
+            return undefined;
+        if (!isIdleTriggerEnvelope(msg) && cause.type !== "idle")
+            return undefined;
+        const basis = cause.basis;
+        const hasRatio = basis?.idleForMs !== undefined && basis.thresholdMs !== undefined && basis.thresholdMs > 0;
+        const value = hasRatio ? (basis?.idleForMs ?? 0) / (basis?.thresholdMs ?? 1) : 1;
+        let backed = false;
+        try {
+            backed = this.deps.hasUserBacking?.() === true;
+        }
+        catch (err) {
+            console.error("[proactive] 是否有用户交代判定失败（按没有交代处理）", err);
+        }
+        return evaluateShallowIdle({
+            policy,
+            value,
+            valueSource: hasRatio ? "trust-policy: idleForMs/thresholdMs" : "trust-policy: default",
+            urgency: 1,
+            urgencySource: "trust-policy: idle",
+            interruptionCost: 1,
+            interruptionCostSource: "trust-policy: default",
+            backedByUserRequest: backed,
+        });
+    }
     /**
      * 向用户提问，并把结局分成**回答 / 用户取消（Esc）/ 超时未答**三种。
      *

package/build/src/trust-loop.js

@@ -0,0 +1,321 @@
+/**
+ * 目标驱动与自主推进的**执行环**（卡 D6 / D7）+ 人机分工（卡 D3）。
+ *
+ * 同一套循环，三档自主度（`docs/product/agentic-loop.md` §1）：
+ * ```
+ * 目标 → 候选行动 → 打分(DECIDE1) → 执行 → 结账(带归因) → 回灌目标进度
+ * 自主档位：L-B 托付（条件由用户给） / L-C 目标驱动（条件由 AI 推导）
+ *          / L-D 自主推进（目标由 AI 从账本的未竟事项里发现）
+ * ```
+ *
+ * **六条必要前提**（缺一即不得进入自主推进，`docs/product/agentic-loop.md` §2）：
+ * ```
+ * ① 目标可判定  ② 预算硬上限  ③ 权限阶梯
+ * ④ 可中止可撤销 ⑤ 可追溯      ⑥ 不越界（范围外显式请求授权）
+ * ```
+ *
+ * 红线（§6）：
+ * - 不得替人做**需要担责**的决定 → 不可逆 / 对外 / 价值取舍 → 一律 **human-gated**；
+ * - 不得**假装完成** → 未达成的目标必须显式产出「未达成 / 需人决策」记录，**不得静默结账**；
+ * - 不得在目标外动手 → 范围外 → 产出**显式请求授权**的记录（不是自动执行）。
+ *
+ * @capability: trust-loop
+ * @observable: pi-proactive/src/trust-loop.ts:advanceCandidate
+ * @attribution: pi-proactive/src/trust-loop.ts:advanceCandidate
+ * @outcome: pi-proactive/src/trust-metrics.ts:TrustMetrics
+ * @checked: test:pi-proactive/tests/trust-loop.test.ts#D6-3 执行 → 结账带归因
+ */
+import { scoreDecision } from "./idle.js";
+import { goalGap, goalSatisfied, isDecidable, } from "./trust-registry.js";
+/**
+ * 权限阶梯（护栏③）：**人的经历有效** → 需要担责的决定必须回到人手里。
+ *
+ * - `read` / `write`（可撤销）→ AI 可自主做；
+ * - `external`（对外承诺）/ `irreversible`（不可逆）/ `value-judgment`（取舍与价值排序）
+ *   → **human-gated**：只能生成待人决策的记录，**不得自动执行**。
+ */
+export function resolvePermissionTier(actionType) {
+    switch (actionType) {
+        case "read":
+            return "auto";
+        case "write":
+            return "limited";
+        default:
+            return "human-gated";
+    }
+}
+/** 六条护栏（缺一即不得进入自主推进）。 */
+export const GUARDRAILS = [
+    "goal-decidable",
+    "budget-cap",
+    "permission-ladder",
+    "abortable-revocable",
+    "traceable",
+    "in-scope",
+];
+/**
+ * 六条护栏的判定（纯函数）。
+ *
+ * @param budgetAvailable 预算是否还有余额（由调用方用登记册的预算账本判定）。
+ */
+export function checkGuardrails(goal, candidate, budgetAvailable) {
+    const violations = [];
+    if (!isDecidable(goal))
+        violations.push({ rule: "goal-decidable", detail: "目标缺可判定的完成定义" });
+    if (!budgetAvailable || goal.budget.maxActions <= goal.budget.usedActions) {
+        violations.push({ rule: "budget-cap", detail: `预算已用尽（${goal.budget.usedActions}/${goal.budget.maxActions}）` });
+    }
+    const expected = resolvePermissionTier(candidate.actionType);
+    if (candidate.permission !== expected) {
+        violations.push({ rule: "permission-ladder", detail: `权限档与动作种类不符（${candidate.permission} ≠ ${expected}）` });
+    }
+    if (goal.permission === "human-gated" && candidate.permission !== "human-gated") {
+        violations.push({ rule: "permission-ladder", detail: "目标整体要求 human-gated" });
+    }
+    if (!candidate.reversible && candidate.permission !== "human-gated") {
+        violations.push({ rule: "abortable-revocable", detail: "不可撤销的动作不得自主执行" });
+    }
+    if (candidate.reason.trim() === "" || candidate.goalId === "") {
+        violations.push({ rule: "traceable", detail: "缺归因（为什么做 / 让哪个目标更近）" });
+    }
+    if (goal.scope.length > 0 && !goal.scope.includes(candidate.scope)) {
+        violations.push({ rule: "in-scope", detail: `范围外（${candidate.scope} ∉ ${goal.scope.join("/")}）` });
+    }
+    return { ok: violations.length === 0, violations };
+}
+/**
+ * 由**目标差距**推导候选行动（卡 D6 的「候选」步）。
+ *
+ * - 完成定义缺失 → **没有候选**（不可判定的目标不许推进）；
+ * - 清单型 → 每个未完成项一个候选；指标型 → 一个候选（把指标推向目标值）。
+ */
+export function deriveCandidates(goal, opts = {}) {
+    if (!isDecidable(goal))
+        return [];
+    const threshold = opts.threshold ?? 1;
+    const observeRatio = opts.observeRatio ?? 0.5;
+    const actionType = opts.actionType ?? "write";
+    const gap = goalGap(goal);
+    const scope = goal.scope[0] ?? goal.id;
+    const value = gap.ratio;
+    const urgency = 1;
+    const interruptionCost = 1;
+    const scoring = scoreDecision({
+        value: { score: value, source: "trust-loop: goalGap.ratio" },
+        urgency: { score: urgency, source: "trust-loop: goal.open" },
+        interruptionCost: { score: interruptionCost, source: "trust-loop: default" },
+    }, threshold, observeRatio);
+    const base = {
+        goalId: goal.id,
+        actionType,
+        permission: resolvePermissionTier(actionType),
+        scope,
+        reversible: true,
+        value,
+        valueSource: "trust-loop: goalGap.ratio",
+        urgency,
+        urgencySource: "trust-loop: goal.open",
+        interruptionCost,
+        interruptionCostSource: "trust-loop: default",
+        score: scoring.score,
+        band: scoring.band,
+    };
+    if (goal.doneWhen?.type === "checklist") {
+        return goal.doneWhen.items
+            .filter((i) => !i.done)
+            .map((item) => ({
+            ...base,
+            id: `${goal.id}#${item.id}`,
+            action: item.text,
+            reason: `目标「${goal.title}」尚差：${item.text}（差距 ${gap.remaining}/${gap.total}）`,
+        }));
+    }
+    const metric = goal.doneWhen;
+    return [
+        {
+            ...base,
+            id: `${goal.id}#metric`,
+            action: `${metric.name} → ${metric.op} ${metric.target}`,
+            reason: `目标「${goal.title}」的 ${metric.name} 当前 ${metric.current}，目标 ${metric.op} ${metric.target}`,
+        },
+    ];
+}
+/**
+ * 推进一个候选行动（卡 D6 的「执行 → 结账」，卡 D7 的护栏）。
+ *
+ * 判定顺序（**顺序本身就是语义**）：
+ * 1. 目标不存在 → failed（不静默）；
+ * 2. 六条护栏 → 有违规 → blocked（**显式记录**，不执行）；
+ * 3. 权限档 = human-gated → human-gated（**不执行、不结账**，产出待人决策记录）；
+ * 4. 消耗预算（硬上限）→ 不足 → blocked；
+ * 5. 执行 → 失败 → failed（**不静默结账**）；
+ * 6. 成功 → 结账：写归因（让哪个目标前进了多少）→ 回灌进度；
+ *    目标仍**未达成** → 显式产出「未达成」记录（**不得静默结账**）。
+ */
+export async function advanceCandidate(deps, candidate) {
+    if (candidate.entrustmentId !== undefined) {
+        // 托付路径：自主推进发现的「未闭合待办」→ 走托付的知会/结账流程。
+        const e = deps.registry.getEntrustment(candidate.entrustmentId);
+        if (e === undefined) {
+            deps.lineage?.noteTrust({ stage: "blocked", entrustmentId: candidate.entrustmentId, reason: "entrustment-not-found" });
+            return { result: "failed", candidate, reason: "托付不存在" };
+        }
+        if (e.needsHuman === true) {
+            const reason = e.humanReason ?? "需要人决定";
+            deps.registry.markNeedsHuman(e.id, reason);
+            deps.lineage?.noteTrust({ stage: "human-gated", entrustmentId: e.id, goalId: e.goalId, reason });
+            return { result: "human-gated", candidate, reason };
+        }
+        if (e.status !== "arrived" && e.status !== "notified") {
+            const reason = `托付尚未到达（${e.status}）→ 不结账`;
+            deps.lineage?.noteTrust({ stage: "blocked", entrustmentId: e.id, goalId: e.goalId, reason });
+            return { result: "blocked", candidate, violations: [{ rule: "goal-decidable", detail: reason }] };
+        }
+        const closed = closeEntrustment(deps, e.id);
+        if (closed.result === "human-gated") {
+            return { result: "human-gated", candidate, reason: closed.reason ?? "需人决定" };
+        }
+        return { result: "settled", candidate, attribution: { goalId: e.goalId ?? "", progressDelta: 1 } };
+    }
+    const goal = deps.registry.getGoal(candidate.goalId);
+    if (goal === undefined) {
+        deps.lineage?.noteTrust({ stage: "blocked", goalId: candidate.goalId, reason: "goal-not-found" });
+        return { result: "failed", candidate, reason: "目标不存在" };
+    }
+    const budgetAvailable = goal.budget.usedActions < goal.budget.maxActions;
+    const report = checkGuardrails(goal, candidate, budgetAvailable);
+    if (!report.ok) {
+        const detail = report.violations.map((v) => `${v.rule}:${v.detail}`).join("；");
+        deps.lineage?.noteTrust({ stage: "blocked", goalId: goal.id, reason: detail });
+        // 范围外 / 不可判定 → 显式请求授权或人决策（**不是**自动执行）。
+        if (report.violations.some((v) => v.rule === "in-scope" || v.rule === "goal-decidable")) {
+            deps.registry.setGoalStatus(goal.id, "needs-human", `需要人授权或补充定义：${detail}`);
+        }
+        return { result: "blocked", candidate, violations: report.violations };
+    }
+    if (candidate.permission === "human-gated") {
+        const reason = `该动作需人担责（${candidate.actionType}）→ 不自动执行`;
+        deps.registry.setGoalStatus(goal.id, "needs-human", reason);
+        deps.lineage?.noteTrust({ stage: "human-gated", goalId: goal.id, reason });
+        return { result: "human-gated", candidate, reason };
+    }
+    if (!deps.registry.consumeBudget(goal.id)) {
+        const detail = `预算硬上限已到（${goal.budget.usedActions}/${goal.budget.maxActions}）`;
+        deps.lineage?.noteTrust({ stage: "blocked", goalId: goal.id, reason: detail });
+        return { result: "blocked", candidate, violations: [{ rule: "budget-cap", detail }] };
+    }
+    let result;
+    try {
+        result = deps.execute !== undefined ? await deps.execute(candidate) : { ok: true, progressDelta: 1 };
+    }
+    catch (err) {
+        const reason = `执行异常：${err instanceof Error ? err.message : String(err)}`;
+        deps.lineage?.noteTrust({ stage: "blocked", goalId: goal.id, reason });
+        return { result: "failed", candidate, reason };
+    }
+    if (!result.ok) {
+        const reason = `执行未成功：${result.result ?? "未说明"}`;
+        deps.lineage?.noteTrust({ stage: "blocked", goalId: goal.id, reason });
+        return { result: "failed", candidate, reason };
+    }
+    const delta = result.progressDelta ?? 1;
+    deps.registry.recordProgress(goal.id, delta);
+    deps.lineage?.noteTrust({ stage: "progress", goalId: goal.id, progressDelta: delta });
+    const after = deps.registry.getGoal(goal.id);
+    const satisfied = after !== undefined && goalSatisfied(after);
+    if (satisfied && after !== undefined) {
+        deps.registry.setGoalStatus(after.id, "achieved");
+        deps.lineage?.noteTrust({ stage: "progress", goalId: after.id, progressDelta: delta, reason: "goal-achieved" });
+    }
+    else {
+        // **未达成不得静默结账**：显式记一条「仍未达成」。
+        deps.lineage?.noteTrust({ stage: "progress", goalId: goal.id, progressDelta: delta, reason: "goal-not-satisfied" });
+    }
+    return { result: "settled", candidate, attribution: { goalId: goal.id, progressDelta: delta } };
+}
+/**
+ * 登记一条托付并落 `registered` 事件（**登记与账本同一处** → 不会漏段）。
+ */
+export function openEntrustment(deps, input) {
+    const e = deps.registry.registerEntrustment(input);
+    deps.lineage?.noteTrust({ stage: "registered", entrustmentId: e.id, goalId: e.goalId });
+    return e;
+}
+/**
+ * 托付到达（第二段）：状态迁移 + `arrived` 事件（同一处 → 不会漏段）。
+ */
+export function arriveEntrustment(deps, entrustmentId) {
+    const e = deps.registry.markArrived(entrustmentId);
+    if (e === undefined)
+        return undefined;
+    deps.lineage?.noteTrust({ stage: "arrived", entrustmentId: e.id, goalId: e.goalId });
+    return e;
+}
+/** 托付条件的判定（**可判定**：到点 / 状态命中）。 */
+export function evaluateEntrustmentCondition(entrustment, now, state) {
+    const c = entrustment.condition;
+    if (c.type === "at")
+        return now >= c.dueAt;
+    if (state === undefined)
+        return false;
+    return state[c.key] === c.equals;
+}
+/**
+ * 关闭一条托付（**结账**；卡 D3：需要人决定的不得自动结账）。
+ *
+ * - `needsHuman` → 产出 human-gated 记录，**不结账**；
+ * - 否则 → 结账 + 落 `settled` 事件。
+ */
+export function closeEntrustment(deps, entrustmentId) {
+    const e = deps.registry.getEntrustment(entrustmentId);
+    if (e === undefined)
+        return { result: "human-gated", reason: "托付不存在" };
+    if (e.needsHuman === true) {
+        const reason = e.humanReason ?? "需要人决定";
+        deps.registry.markNeedsHuman(entrustmentId, reason);
+        deps.lineage?.noteTrust({ stage: "human-gated", entrustmentId, goalId: e.goalId, reason });
+        return { result: "human-gated", reason };
+    }
+    const settled = deps.registry.settle(entrustmentId);
+    if (settled === undefined) {
+        const reason = `托付当前状态不可结账（${e.status}）`;
+        deps.lineage?.noteTrust({ stage: "blocked", entrustmentId, goalId: e.goalId, reason });
+        return { result: "human-gated", reason };
+    }
+    deps.lineage?.noteTrust({ stage: "settled", entrustmentId, goalId: e.goalId });
+    return { result: "settled" };
+}
+/**
+ * 自主推进的**下一步发现**（卡 D7 的 L-D）。
+ *
+ * 来源：**未竟目标**（登记册里 `open` 的目标）与**未闭合待办**（未闭合的托付）。
+ * 不是凭空生成 —— 每个候选都能指回一条账本记录。
+ */
+export function discoverNextCandidates(deps, opts = {}) {
+    const out = [];
+    for (const goal of deps.registry.listOpenGoals()) {
+        out.push(...deriveCandidates(goal, opts));
+    }
+    for (const e of deps.registry.listUnclosedEntrustments()) {
+        out.push({
+            id: `${e.id}#close`,
+            entrustmentId: e.id,
+            goalId: e.goalId ?? "",
+            action: `处理未闭合托付：${e.target}`,
+            actionType: "write",
+            permission: resolvePermissionTier("write"),
+            scope: e.id,
+            reversible: true,
+            value: 1,
+            valueSource: "trust-loop: unclosed-entrustment",
+            urgency: 1,
+            urgencySource: "trust-loop: unclosed-entrustment",
+            interruptionCost: 1,
+            interruptionCostSource: "trust-loop: default",
+            score: 1,
+            band: "trigger",
+            reason: `账本里有一条未闭合托付：${e.target}（${e.status}）`,
+        });
+    }
+    return out;
+}