@modusensus/dsh-mneme 0.13.0 → 0.14.0-beta.2

package/lib/pipeline-confirm.js

@@ -1,142 +1,142 @@
-/**
- * M.O. 的人确认层：把「本次观察到什么」变成「哪几步真的走了」。
- *
- * ## 为什么必须由人来说
- *
- * 自动归属被实测否决（详见 mneme-research 的 08/09）：
- * - 拿单条命令匹配手写步骤表，唯一归属只有 **14.2%**；非发版会话也有 4.4%，**区分力仅 3 倍**
- * - 放宽到"包含匹配"，天花板仍 14%，且大头是 `git log` / `git diff` 这类通用命令
- * - 工作流里的关键步骤 `gh pr merge --rebase` 在 21723 次调用里**出现 0 次**——
- *   说明清单本身可能与实际行为脱节
- *
- * 归到本文档的一句话：**机器猜不准，而猜错的代价是把没走过的步骤记成走过**
- * （`deriveState` 会据此把它染成 `trusted`）。所以这一步交给人。
- *
- * ## 三个设计决定
- *
- * 1. **提案不改动任何东西**。`buildProposal` 是纯函数，产出的是"给人看的待确认清单"。
- *    写账只发生在 `confirm` 之后，且只写人点过的步骤。
- * 2. **"不确定"是一个合法的答案**。人可以对某一步说"我不知道"——它既不记为走过，
- *    也不记为跳过。这与账本那边「缺字段的行不许被算成 uses」是同一条纪律：
- *    **没确认 ≠ 没发生，也 ≠ 发生**。
- * 3. **必须能报"整条流程都没走"**。人可以说"这次什么都没做"，那就是一条**零步 run**
- *    ——但账本契约要求 `run.steps` 至少一项（见 `pipeline-runs` 的校验），所以那种情况
- *    本模块如实返回 `{ kind: "nothing" }` 而不是伪造一条空 run。
- */
-
-/**
- * 造一份确认提案（纯函数，不落盘、不改任何状态）。
- *
- * 输入：
- * - `pipeline`：本次要走的流程（含 steps）
- * - `activities`：P1 产出的业务动作清单（`[{key, count, flags}]`），给人当参照
- * - `hints`：自动归属的候选（可空），**只作提示**
- *
- * 输出刻意把两类信息分开：
- * - `steps`：**流程自己的**步骤表（人在这里勾）
- * - `activities`：**观察到的**业务动作（人在这对照）
- * 两者不做自动配对——那正是被否决的那件事。
- */
-export function buildProposal({ pipeline, activities = [], hints = null } = {}) {
-  if (!pipeline || !Array.isArray(pipeline.steps)) {
-    return { ok: false, reason: "no-pipeline" };
-  }
-
-  const steps = pipeline.steps.map((s) => ({
-    id: s.id,
-    title: s.title,
-    // 步骤表里人写的 tool 原文——给对照用，不是匹配依据
-    declared: typeof s.tool === "string" ? s.tool : "",
-    // 机器给的候选提示：**只给一个次数**，不给命令行原文（原文含绝对路径）。
-    // 它只是提示，不预选——人仍然要自己说这一步做没做。
-    hintCount: Number.isFinite(hints?.[s.id]) ? hints[s.id] : 0
-  }));
-
-  return {
-    ok: true,
-    pipelineId: pipeline.id,
-    steps,
-    activities: activities.map((a) => ({ key: a.key, count: a.count, flags: a.flags || [] }))
-    // 不返回 answers 词表：命令层有自己的解析表，写死两份只会漂。
-    // 也不返回 pipelineTitle / observations：零消费者（ponytail 复核点名的两处）。
-  };
-}
-
-/**
- * 校验并归一人的回答。
- *
- * `answers` 形如 `{ "P6": "done", "V2": "notDone" }`。
- * **只认三类值**，其余一律拒——静默把非法值当"没发生"是编造的一种。
- */
-export function normalizeAnswers(answersResult, pipeline) {
-  if (!pipeline || !Array.isArray(pipeline.steps)) return { ok: false, reason: "no-pipeline" };
-  if (!answersResult || typeof answersResult !== "object" || Array.isArray(answersResult)) {
-    return { ok: false, reason: "bad-answers" };
-  }
-  const ids = new Set(pipeline.steps.map((s) => s.id));
-  const clean = {};
-  for (const [id, value] of Object.entries(answersResult)) {
-    if (!ids.has(id)) return { ok: false, reason: "unknown-step", stepId: id };
-    if (value !== "done" && value !== "notDone" && value !== "unsure") {
-      return { ok: false, reason: "bad-answer-value", stepId: id, value };
-    }
-    clean[id] = value;
-  }
-  return { ok: true, answers: clean };
-}
-
-/**
- * 把确认结果变成一条 run（**仍然不落盘**，落盘由调用方做）。
- *
- * 三种结局分得很清：
- * - `kind:"run"`：**至少一条记录**（`done` 或 `notDone`）→ 产出一条 run
- * - `kind:"nothing"`：**什么记录都没有**（全 unsure / 全没答）→ 不产 run
- * - `kind:"error"`：回答非法
- *
- * ⚠️ 一处容易写错的语义（本文档的注释最初就写错过，被测试抓出来）：
- * **「全部 notDone」不等于「零步」**。人确认"这两步这次都没做"是一条**合法且完整**的
- * 记录（两条 `skipped`），它描述的事实是"走了这条流程、但一步都没执行"。
- * 真正进 `nothing` 的只有**什么都没确认**（人没开口）——那才是没有信息可记。
- *
- * 关于 `notDone` 与 `unsure` 的差别（这是本模块最要紧的语义）：
- * - 人明确说 **notDone**（这一步这次没做）→ 记 `skipped: true`
- * - 人 **没回答**或说 **unsure** → **什么都不写**（既不 skipped 也不 uses）
- *   因为"没确认"与"确认没做"是两回事，混起来会把"忘了勾"记成"这步被跳过"，
- *   而跳过计数正是 `RETIRE_AFTER_SKIPS` 提议删步的依据——错一次就多一条错提议。
- */
-export function runFromAnswers({ pipeline, answers, by = "human", triggeredBy = "", now = () => new Date() } = {}) {
-  const normalized = normalizeAnswers(answers, pipeline);
-  if (!normalized.ok) return { kind: "error", reason: normalized.reason, stepId: normalized.stepId, value: normalized.value };
-
-  const at = new Date(now()).toISOString();
-  const steps = [];
-  for (const step of pipeline.steps) {
-    const answer = normalized.answers[step.id];
-    if (answer === "done") {
-      steps.push({ id: step.id, at, skipped: false, detoured: false, refuted: false, note: "" });
-    } else if (answer === "notDone") {
-      steps.push({ id: step.id, at, skipped: true, detoured: false, refuted: false, note: "人确认这次没做" });
-    }
-    // unsure / 无回答 → 不写任何东西（见函数头注释）
-  }
-
-  if (steps.length === 0) {
-    return {
-      kind: "nothing",
-      reason: "no-steps-confirmed",
-      // 如实回报：哪些是"人确认没做"、哪些是"没答"
-      notDone: pipeline.steps.filter((s) => normalized.answers[s.id] === "notDone").map((s) => s.id),
-      unanswered: pipeline.steps.filter((s) => normalized.answers[s.id] === undefined).map((s) => s.id),
-      unsure: pipeline.steps.filter((s) => normalized.answers[s.id] === "unsure").map((s) => s.id)
-    };
-  }
-
-  return {
-    kind: "run",
-    run: { at, by, triggeredBy, steps },
-    // 没写进账的两种原因分开报——「确认没做」与「没答」不该长得一样
-    notDone: pipeline.steps.filter((s) => normalized.answers[s.id] === "notDone").map((s) => s.id),
-    unanswered: pipeline.steps.filter((s) => normalized.answers[s.id] === undefined).map((s) => s.id),
-    unsure: pipeline.steps.filter((s) => normalized.answers[s.id] === "unsure").map((s) => s.id)
-  };
-}
+/**
+ * M.O. 的人确认层：把「本次观察到什么」变成「哪几步真的走了」。
+ *
+ * ## 为什么必须由人来说
+ *
+ * 自动归属被实测否决（详见 mneme-research 的 08/09）：
+ * - 拿单条命令匹配手写步骤表，唯一归属只有 **14.2%**；非发版会话也有 4.4%，**区分力仅 3 倍**
+ * - 放宽到"包含匹配"，天花板仍 14%，且大头是 `git log` / `git diff` 这类通用命令
+ * - 工作流里的关键步骤 `gh pr merge --rebase` 在 21723 次调用里**出现 0 次**——
+ *   说明清单本身可能与实际行为脱节
+ *
+ * 归到本文档的一句话：**机器猜不准，而猜错的代价是把没走过的步骤记成走过**
+ * （`deriveState` 会据此把它染成 `trusted`）。所以这一步交给人。
+ *
+ * ## 三个设计决定
+ *
+ * 1. **提案不改动任何东西**。`buildProposal` 是纯函数，产出的是"给人看的待确认清单"。
+ *    写账只发生在 `confirm` 之后，且只写人点过的步骤。
+ * 2. **"不确定"是一个合法的答案**。人可以对某一步说"我不知道"——它既不记为走过，
+ *    也不记为跳过。这与账本那边「缺字段的行不许被算成 uses」是同一条纪律：
+ *    **没确认 ≠ 没发生，也 ≠ 发生**。
+ * 3. **必须能报"整条流程都没走"**。人可以说"这次什么都没做"，那就是一条**零步 run**
+ *    ——但账本契约要求 `run.steps` 至少一项（见 `pipeline-runs` 的校验），所以那种情况
+ *    本模块如实返回 `{ kind: "nothing" }` 而不是伪造一条空 run。
+ */
+
+/**
+ * 造一份确认提案（纯函数，不落盘、不改任何状态）。
+ *
+ * 输入：
+ * - `pipeline`：本次要走的流程（含 steps）
+ * - `activities`：P1 产出的业务动作清单（`[{key, count, flags}]`），给人当参照
+ * - `hints`：自动归属的候选（可空），**只作提示**
+ *
+ * 输出刻意把两类信息分开：
+ * - `steps`：**流程自己的**步骤表（人在这里勾）
+ * - `activities`：**观察到的**业务动作（人在这对照）
+ * 两者不做自动配对——那正是被否决的那件事。
+ */
+export function buildProposal({ pipeline, activities = [], hints = null } = {}) {
+  if (!pipeline || !Array.isArray(pipeline.steps)) {
+    return { ok: false, reason: "no-pipeline" };
+  }
+
+  const steps = pipeline.steps.map((s) => ({
+    id: s.id,
+    title: s.title,
+    // 步骤表里人写的 tool 原文——给对照用，不是匹配依据
+    declared: typeof s.tool === "string" ? s.tool : "",
+    // 机器给的候选提示：**只给一个次数**，不给命令行原文（原文含绝对路径）。
+    // 它只是提示，不预选——人仍然要自己说这一步做没做。
+    hintCount: Number.isFinite(hints?.[s.id]) ? hints[s.id] : 0
+  }));
+
+  return {
+    ok: true,
+    pipelineId: pipeline.id,
+    steps,
+    activities: activities.map((a) => ({ key: a.key, count: a.count, flags: a.flags || [] }))
+    // 不返回 answers 词表：命令层有自己的解析表，写死两份只会漂。
+    // 也不返回 pipelineTitle / observations：零消费者（ponytail 复核点名的两处）。
+  };
+}
+
+/**
+ * 校验并归一人的回答。
+ *
+ * `answers` 形如 `{ "P6": "done", "V2": "notDone" }`。
+ * **只认三类值**，其余一律拒——静默把非法值当"没发生"是编造的一种。
+ */
+export function normalizeAnswers(answersResult, pipeline) {
+  if (!pipeline || !Array.isArray(pipeline.steps)) return { ok: false, reason: "no-pipeline" };
+  if (!answersResult || typeof answersResult !== "object" || Array.isArray(answersResult)) {
+    return { ok: false, reason: "bad-answers" };
+  }
+  const ids = new Set(pipeline.steps.map((s) => s.id));
+  const clean = {};
+  for (const [id, value] of Object.entries(answersResult)) {
+    if (!ids.has(id)) return { ok: false, reason: "unknown-step", stepId: id };
+    if (value !== "done" && value !== "notDone" && value !== "unsure") {
+      return { ok: false, reason: "bad-answer-value", stepId: id, value };
+    }
+    clean[id] = value;
+  }
+  return { ok: true, answers: clean };
+}
+
+/**
+ * 把确认结果变成一条 run（**仍然不落盘**，落盘由调用方做）。
+ *
+ * 三种结局分得很清：
+ * - `kind:"run"`：**至少一条记录**（`done` 或 `notDone`）→ 产出一条 run
+ * - `kind:"nothing"`：**什么记录都没有**（全 unsure / 全没答）→ 不产 run
+ * - `kind:"error"`：回答非法
+ *
+ * ⚠️ 一处容易写错的语义（本文档的注释最初就写错过，被测试抓出来）：
+ * **「全部 notDone」不等于「零步」**。人确认"这两步这次都没做"是一条**合法且完整**的
+ * 记录（两条 `skipped`），它描述的事实是"走了这条流程、但一步都没执行"。
+ * 真正进 `nothing` 的只有**什么都没确认**（人没开口）——那才是没有信息可记。
+ *
+ * 关于 `notDone` 与 `unsure` 的差别（这是本模块最要紧的语义）：
+ * - 人明确说 **notDone**（这一步这次没做）→ 记 `skipped: true`
+ * - 人 **没回答**或说 **unsure** → **什么都不写**（既不 skipped 也不 uses）
+ *   因为"没确认"与"确认没做"是两回事，混起来会把"忘了勾"记成"这步被跳过"，
+ *   而跳过计数正是 `RETIRE_AFTER_SKIPS` 提议删步的依据——错一次就多一条错提议。
+ */
+export function runFromAnswers({ pipeline, answers, by = "human", triggeredBy = "", now = () => new Date() } = {}) {
+  const normalized = normalizeAnswers(answers, pipeline);
+  if (!normalized.ok) return { kind: "error", reason: normalized.reason, stepId: normalized.stepId, value: normalized.value };
+
+  const at = new Date(now()).toISOString();
+  const steps = [];
+  for (const step of pipeline.steps) {
+    const answer = normalized.answers[step.id];
+    if (answer === "done") {
+      steps.push({ id: step.id, at, skipped: false, detoured: false, refuted: false, note: "" });
+    } else if (answer === "notDone") {
+      steps.push({ id: step.id, at, skipped: true, detoured: false, refuted: false, note: "人确认这次没做" });
+    }
+    // unsure / 无回答 → 不写任何东西（见函数头注释）
+  }
+
+  if (steps.length === 0) {
+    return {
+      kind: "nothing",
+      reason: "no-steps-confirmed",
+      // 如实回报：哪些是"人确认没做"、哪些是"没答"
+      notDone: pipeline.steps.filter((s) => normalized.answers[s.id] === "notDone").map((s) => s.id),
+      unanswered: pipeline.steps.filter((s) => normalized.answers[s.id] === undefined).map((s) => s.id),
+      unsure: pipeline.steps.filter((s) => normalized.answers[s.id] === "unsure").map((s) => s.id)
+    };
+  }
+
+  return {
+    kind: "run",
+    run: { at, by, triggeredBy, steps },
+    // 没写进账的两种原因分开报——「确认没做」与「没答」不该长得一样
+    notDone: pipeline.steps.filter((s) => normalized.answers[s.id] === "notDone").map((s) => s.id),
+    unanswered: pipeline.steps.filter((s) => normalized.answers[s.id] === undefined).map((s) => s.id),
+    unsure: pipeline.steps.filter((s) => normalized.answers[s.id] === "unsure").map((s) => s.id)
+  };
+}

package/lib/pipeline-exec.js

@@ -1,174 +1,174 @@
-/**
- * M.O. 的**执行窗口**：一次 run 从「有人决定按这条工作流走一遍」开始记账，到这一遍结束为止。
- *
- * ## 为什么是「窗口」而不是「自动观察一切」
- *
- * 这是本模块存在的核心理由，也是接线前必须先想清楚的一件事：
- *
- * 宿主钩子（`tools/pre-execute` 等）能看到「这次调了什么工具」，但它**看不到「正在走哪条
- * 工作流」**。工作流的 `trigger` 字段是人话（`{kind:"phrase", value:"发版"}`），今天没有任何
- * 代码消费它；想靠它自动判定「用户说这句话就意味着开始走某条流程」，只能猜——而猜错的代价
- * 是把一条**从没跑过的流程**记成跑过。那正是本仓反复防的「伪造正面证据」。
- *
- * 所以窗口的边界由**显式动作**划：有人（或按人指令的 agent）说明「现在按 X 走一遍」，窗口才开；
- * 窗口内的工具调用才可能被记账；窗口一关就 flush 成一条 run。**窗口之外发生的一切一个字都不记**
- * ——漏记账是可接受的，编造账不是。
- *
- * ## 一次观察有三种结局，必须分开
- *
- * - **归属成功**：写进这次 run 的 `steps`
- * - **归属不了**：进 `unattributed`。它在图上是「没走这条路的痕迹」，即绕开的候选——
- *   但它**还没被确认**是这条流程的一步，所以不进 `steps`
- * - **归属有歧义**：进 `ambiguous`，**不猜**，留给人消歧
- *
- * 三者分开报的纪律与账本那边一致：**「认不出来」与「没做」必须长得不一样**，
- * 否则一份全是 unattributed 的账会被读成「这次什么也没做」。
- *
- * ## 唯一没被记下来的东西：失败
- *
- * 账本契约要求一条 run 至少有一个步骤（`run.steps 至少要有一条`），所以「开了窗口、
- * 一步都没走成」目前**落不成账**。这是已知缺口，本模块如实返回 `reason:"no-steps"`，
- * 不伪造一条空 run 去凑。要真正表示失败，得先改账本契约（让零步 run 合法）。
- */
-
-import { attributionCandidates } from "./pipeline-attribution.js";
-
-/** 一次观察被拒的三种原因；调用方据此决定要不要请人消歧。 */
-export const OBSERVED = "observed";
-export const UNATTRIBUTED = "unattributed";
-export const AMBIGUOUS = "ambiguous";
-
-function toIso(value) {
-  if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
-  const ms = typeof value === "number" ? value : Date.parse(String(value));
-  if (!Number.isFinite(ms)) throw new Error("时间必须能解析成 ISO");
-  return new Date(ms).toISOString();
-}
-
-/**
- * 开一个记录窗口。
- *
- * `pipeline` 是这次要走的**那一条**工作流（由调用方点名，不由本模块猜）。
- * `by` / `triggeredBy` 落进 run 的描述字段：账本里「谁做的」「为什么这次会跑」要有出处。
- */
-export function openRun({ pipeline, by = "main", triggeredBy = "", now = () => new Date() } = {}) {
-  if (!pipeline || !Array.isArray(pipeline.steps)) {
-    throw new Error("openRun 需要一条工作流（含 steps）");
-  }
-
-  const startedAt = toIso(now());
-  /** stepId → { at, refuted, repeats }；同一步在一个窗口里只计一次，重复的进 repeats。 */
-  const steps = new Map();
-  const unattributed = [];
-  const ambiguous = [];
-  let observations = 0;
-  let closed = null;
-
-  /** 记下一步。同一步重复出现时不重复计数（`tallyRuns` 按 run 计数，重复会让 uses 虚高）。 */
-  function record(stepId, at, refuted) {
-    const existing = steps.get(stepId);
-    if (existing) {
-      existing.repeats += 1;
-      // 任何一次失败都算被推翻过——「跑砸过一次」不该被后来的成功抹掉。
-      if (refuted) existing.refuted = true;
-      return existing;
-    }
-    const entry = { id: stepId, at, refuted, repeats: 0 };
-    steps.set(stepId, entry);
-    return entry;
-  }
-
-  return {
-    /**
-     * 观察一次工具动作。
-     *
-     * `stepId` 是**人确认过的归属**：给了就直接记，不再走匹配（人说了算）。
-     * 不给则按归属规则自动判——只有 `exact` 且唯一时才自动记账；
-     * 多候选或只有 weak 一律进 `ambiguous`，**绝不自选一条**。
-     */
-    observe(observation, { stepId = null, at = null } = {}) {
-      if (closed) return { accepted: false, result: "run-closed" };
-      observations += 1;
-      const when = toIso(at ?? now());
-      const failed = observation && observation.ok === false;
-
-      if (stepId) {
-        record(stepId, when, failed);
-        return { accepted: true, result: OBSERVED, stepId, resolved: "explicit" };
-      }
-
-      const candidates = attributionCandidates(observation, pipeline);
-      if (candidates.length === 0) {
-        unattributed.push({ observation, at: when });
-        return { accepted: false, result: UNATTRIBUTED };
-      }
-
-      const exact = candidates.filter((c) => c.confidence === "exact");
-      if (candidates.length === 1 && exact.length === 1) {
-        record(exact[0].stepId, when, failed);
-        return { accepted: true, result: OBSERVED, stepId: exact[0].stepId, resolved: "exact" };
-      }
-
-      // 弱匹配、多候选都走这里：图省事挑一条就是替人做决定，而挑错的代价是染色错误的一步。
-      ambiguous.push({ observation, at: when, candidates });
-      return { accepted: false, result: AMBIGUOUS, candidates };
-    },
-
-    /** 只看状态，不结账。给「这一遍走到哪了」这种实时查询用。 */
-    state() {
-      return {
-        open: closed === null,
-        pipelineId: pipeline.id,
-        startedAt,
-        observations,
-        recorded: [...steps.values()].map((s) => s.id),
-        unattributed: unattributed.length,
-        ambiguous: ambiguous.length
-      };
-    },
-
-    /**
-     * 结账：产出一条**还没落盘**的 run（落盘由调用方做 `appendRun`，本模块不碰文件系统）。
-     *
-     * `steps` 里只有**真被观察到**的步骤。没观察到的步骤既不写 `skipped` 也不写 `used`——
-     * 缺席不等于跳过（可能是归属没认出来），把它写成跳过就是编造。它们进 `unobserved`，
-     * 让人自己看。
-     */
-    close() {
-      if (closed) return closed;
-      const runSteps = [...steps.values()].map((s) => ({
-        id: s.id,
-        at: s.at,
-        skipped: false,
-        detoured: false,
-        refuted: s.refuted === true,
-        note: s.repeats > 0 ? `这一步在窗口内被观察到 ${s.repeats + 1} 次，只计一次` : ""
-      }));
-      const observedIds = new Set(runSteps.map((s) => s.id));
-      const unobserved = pipeline.steps.map((s) => s.id).filter((id) => !observedIds.has(id));
-
-      const base = {
-        startedAt,
-        endedAt: toIso(now()),
-        pipelineId: pipeline.id,
-        observations,
-        unattributed,
-        ambiguous,
-        unobserved
-      };
-
-      if (runSteps.length === 0) {
-        // 契约要求至少一步，所以这一步落不成账。如实说，不伪造。
-        closed = { ...base, run: null, reason: "no-steps" };
-        return closed;
-      }
-
-      closed = {
-        ...base,
-        run: { at: startedAt, by, triggeredBy, steps: runSteps },
-        reason: null
-      };
-      return closed;
-    }
-  };
-}
+/**
+ * M.O. 的**执行窗口**：一次 run 从「有人决定按这条工作流走一遍」开始记账，到这一遍结束为止。
+ *
+ * ## 为什么是「窗口」而不是「自动观察一切」
+ *
+ * 这是本模块存在的核心理由，也是接线前必须先想清楚的一件事：
+ *
+ * 宿主钩子（`tools/pre-execute` 等）能看到「这次调了什么工具」，但它**看不到「正在走哪条
+ * 工作流」**。工作流的 `trigger` 字段是人话（`{kind:"phrase", value:"发版"}`），今天没有任何
+ * 代码消费它；想靠它自动判定「用户说这句话就意味着开始走某条流程」，只能猜——而猜错的代价
+ * 是把一条**从没跑过的流程**记成跑过。那正是本仓反复防的「伪造正面证据」。
+ *
+ * 所以窗口的边界由**显式动作**划：有人（或按人指令的 agent）说明「现在按 X 走一遍」，窗口才开；
+ * 窗口内的工具调用才可能被记账；窗口一关就 flush 成一条 run。**窗口之外发生的一切一个字都不记**
+ * ——漏记账是可接受的，编造账不是。
+ *
+ * ## 一次观察有三种结局，必须分开
+ *
+ * - **归属成功**：写进这次 run 的 `steps`
+ * - **归属不了**：进 `unattributed`。它在图上是「没走这条路的痕迹」，即绕开的候选——
+ *   但它**还没被确认**是这条流程的一步，所以不进 `steps`
+ * - **归属有歧义**：进 `ambiguous`，**不猜**，留给人消歧
+ *
+ * 三者分开报的纪律与账本那边一致：**「认不出来」与「没做」必须长得不一样**，
+ * 否则一份全是 unattributed 的账会被读成「这次什么也没做」。
+ *
+ * ## 唯一没被记下来的东西：失败
+ *
+ * 账本契约要求一条 run 至少有一个步骤（`run.steps 至少要有一条`），所以「开了窗口、
+ * 一步都没走成」目前**落不成账**。这是已知缺口，本模块如实返回 `reason:"no-steps"`，
+ * 不伪造一条空 run 去凑。要真正表示失败，得先改账本契约（让零步 run 合法）。
+ */
+
+import { attributionCandidates } from "./pipeline-attribution.js";
+
+/** 一次观察被拒的三种原因；调用方据此决定要不要请人消歧。 */
+export const OBSERVED = "observed";
+export const UNATTRIBUTED = "unattributed";
+export const AMBIGUOUS = "ambiguous";
+
+function toIso(value) {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+  const ms = typeof value === "number" ? value : Date.parse(String(value));
+  if (!Number.isFinite(ms)) throw new Error("时间必须能解析成 ISO");
+  return new Date(ms).toISOString();
+}
+
+/**
+ * 开一个记录窗口。
+ *
+ * `pipeline` 是这次要走的**那一条**工作流（由调用方点名，不由本模块猜）。
+ * `by` / `triggeredBy` 落进 run 的描述字段：账本里「谁做的」「为什么这次会跑」要有出处。
+ */
+export function openRun({ pipeline, by = "main", triggeredBy = "", now = () => new Date() } = {}) {
+  if (!pipeline || !Array.isArray(pipeline.steps)) {
+    throw new Error("openRun 需要一条工作流（含 steps）");
+  }
+
+  const startedAt = toIso(now());
+  /** stepId → { at, refuted, repeats }；同一步在一个窗口里只计一次，重复的进 repeats。 */
+  const steps = new Map();
+  const unattributed = [];
+  const ambiguous = [];
+  let observations = 0;
+  let closed = null;
+
+  /** 记下一步。同一步重复出现时不重复计数（`tallyRuns` 按 run 计数，重复会让 uses 虚高）。 */
+  function record(stepId, at, refuted) {
+    const existing = steps.get(stepId);
+    if (existing) {
+      existing.repeats += 1;
+      // 任何一次失败都算被推翻过——「跑砸过一次」不该被后来的成功抹掉。
+      if (refuted) existing.refuted = true;
+      return existing;
+    }
+    const entry = { id: stepId, at, refuted, repeats: 0 };
+    steps.set(stepId, entry);
+    return entry;
+  }
+
+  return {
+    /**
+     * 观察一次工具动作。
+     *
+     * `stepId` 是**人确认过的归属**：给了就直接记，不再走匹配（人说了算）。
+     * 不给则按归属规则自动判——只有 `exact` 且唯一时才自动记账；
+     * 多候选或只有 weak 一律进 `ambiguous`，**绝不自选一条**。
+     */
+    observe(observation, { stepId = null, at = null } = {}) {
+      if (closed) return { accepted: false, result: "run-closed" };
+      observations += 1;
+      const when = toIso(at ?? now());
+      const failed = observation && observation.ok === false;
+
+      if (stepId) {
+        record(stepId, when, failed);
+        return { accepted: true, result: OBSERVED, stepId, resolved: "explicit" };
+      }
+
+      const candidates = attributionCandidates(observation, pipeline);
+      if (candidates.length === 0) {
+        unattributed.push({ observation, at: when });
+        return { accepted: false, result: UNATTRIBUTED };
+      }
+
+      const exact = candidates.filter((c) => c.confidence === "exact");
+      if (candidates.length === 1 && exact.length === 1) {
+        record(exact[0].stepId, when, failed);
+        return { accepted: true, result: OBSERVED, stepId: exact[0].stepId, resolved: "exact" };
+      }
+
+      // 弱匹配、多候选都走这里：图省事挑一条就是替人做决定，而挑错的代价是染色错误的一步。
+      ambiguous.push({ observation, at: when, candidates });
+      return { accepted: false, result: AMBIGUOUS, candidates };
+    },
+
+    /** 只看状态，不结账。给「这一遍走到哪了」这种实时查询用。 */
+    state() {
+      return {
+        open: closed === null,
+        pipelineId: pipeline.id,
+        startedAt,
+        observations,
+        recorded: [...steps.values()].map((s) => s.id),
+        unattributed: unattributed.length,
+        ambiguous: ambiguous.length
+      };
+    },
+
+    /**
+     * 结账：产出一条**还没落盘**的 run（落盘由调用方做 `appendRun`，本模块不碰文件系统）。
+     *
+     * `steps` 里只有**真被观察到**的步骤。没观察到的步骤既不写 `skipped` 也不写 `used`——
+     * 缺席不等于跳过（可能是归属没认出来），把它写成跳过就是编造。它们进 `unobserved`，
+     * 让人自己看。
+     */
+    close() {
+      if (closed) return closed;
+      const runSteps = [...steps.values()].map((s) => ({
+        id: s.id,
+        at: s.at,
+        skipped: false,
+        detoured: false,
+        refuted: s.refuted === true,
+        note: s.repeats > 0 ? `这一步在窗口内被观察到 ${s.repeats + 1} 次，只计一次` : ""
+      }));
+      const observedIds = new Set(runSteps.map((s) => s.id));
+      const unobserved = pipeline.steps.map((s) => s.id).filter((id) => !observedIds.has(id));
+
+      const base = {
+        startedAt,
+        endedAt: toIso(now()),
+        pipelineId: pipeline.id,
+        observations,
+        unattributed,
+        ambiguous,
+        unobserved
+      };
+
+      if (runSteps.length === 0) {
+        // 契约要求至少一步，所以这一步落不成账。如实说，不伪造。
+        closed = { ...base, run: null, reason: "no-steps" };
+        return closed;
+      }
+
+      closed = {
+        ...base,
+        run: { at: startedAt, by, triggeredBy, steps: runSteps },
+        reason: null
+      };
+      return closed;
+    }
+  };
+}