@modusensus/dsh-mneme 0.8.16 → 0.9.1

package/src/pipeline-command.js

@@ -0,0 +1,279 @@
+/**
+ * M.O. 的**开窗命令**：`/mo-run`。
+ *
+ * ## 为什么需要一条命令，而不是让插件自己判断
+ *
+ * 「哪条工作流正在被走」这件事**没法自动判**：工作流的 `trigger` 字段是人话
+ * （`{kind:"phrase", value:"发版"}`），拿它去匹配用户消息只能猜，而猜错会把一条
+ * **从没跑过的流程**记成跑过、还把节点染成可信。所以窗口的边界由**显式动作**划，
+ * 这条命令就是那个动作。
+ *
+ * 与仓库里既有的 `commands.js`（用户自定义指令）不同：那条路只把文本转发给模型，
+ * 不持有状态；这一条要真的开/关一个窗口，所以单独成模块。
+ *
+ * ## 三个子命令
+ *
+ * - `/mo-run start <pipeline-id>` —— 开窗。之后这个会话里的命令执行才可能被记账
+ * - `/mo-run stop` —— 结账并落盘
+ * - `/mo-run status` —— 只看「走到哪了」，不结账
+ *
+ * ## 为什么把结果文本说这么细
+ *
+ * 命令的回执是这个功能**唯一的对外窗口**（面板那一侧还没做）。它必须能回答：
+ * 开的哪条、走了几步、有多少条认不出来、为什么没写账。含糊其辞的回执会让使用者
+ * 以为「跑成功了」，而实际可能一条观察都没认出来——那正是这个功能最该避免的事。
+ */
+
+import { STR } from "./lang.js";
+
+/** 命令名与用法。名字走本仓的 `COMMAND_NAME` 约定：小写字母起头。 */
+export const MO_RUN_COMMAND = "mo-run";
+
+/**
+ * 解析 `/mo-run` 后面的原始输入。
+ *
+ * 五个子命令：
+ * - `start <id>`：开窗
+ * - `stop`：结账，**产出待确认清单**（P2 起不再自动落盘）
+ * - `confirm <答案>`：人确认哪几步走了 → 这才写账
+ * - `status`：看状态（不带参数时的默认，最安全）
+ *
+ * `confirm` 的答案格式刻意做成**最短的两种**，避免让人背语法：
+ * - `/mo-run confirm P6 V2` —— 这几步做了（空格分隔）
+ * - `/mo-run confirm P6:* V2:-` —— 带标记：`*` 做了、`-` 没做、`?` 不确定
+ *
+ * 没提到的步骤**什么都不写**（既不是"做了"也不是"没做"）——见 pipeline-confirm 的注释。
+ */
+export function parseMoRunInput(rawInput) {
+  const text = typeof rawInput === "string" ? rawInput.trim() : "";
+  if (text === "") return { action: "status" }; // 不带参数 = 看状态，最安全
+  const [verb, ...rest] = text.split(/\s+/u);
+  const arg = rest.join(" ").trim();
+  switch ((verb ?? "").toLowerCase()) {
+    case "start":
+      return { action: "start", pipelineId: arg };
+    case "stop":
+      return { action: "stop" };
+    case "confirm":
+      return { action: "confirm", answers: parseConfirmArg(arg) };
+    case "status":
+      return { action: "status" };
+    default:
+      return { action: "help", unknown: verb };
+  }
+}
+
+/**
+ * `confirm` 的参数 → `{ stepId: "done"|"notDone"|"unsure" }`。
+ *
+ * 两种写法都收：
+ * - `P6`        → done（最常用，直接列做了哪几步）
+ * - `P6:*` / `P6:-` / `P6:?` → done / notDone / unsure
+ *
+ * 解析不了的一律**不放进结果**（宁可少答，不可猜答案）——非法值会在
+ * `runFromAnswers` 那一层被拒，这里只负责拆分。
+ */
+export function parseConfirmArg(arg) {
+  const answers = {};
+  if (typeof arg !== "string" || arg.trim() === "") return answers;
+  for (const token of arg.split(/[\s,]+/u)) {
+    if (token === "") continue;
+    const [idPart, markPart] = token.split(":", 2);
+    const id = idPart.trim();
+    if (id === "") continue;
+    if (markPart === undefined || markPart.trim() === "") {
+      answers[id] = "done";
+      continue;
+    }
+    const mark = markPart.trim();
+    if (mark === "*") answers[id] = "done";
+    else if (mark === "-") answers[id] = "notDone";
+    else if (mark === "?") answers[id] = "unsure";
+    // 其它标记：不放进结果（不是"没做"，是"没答"）
+  }
+  return answers;
+}
+
+/**
+ * 把「本次观察到哪些业务动作」渲染成几行。
+ *
+ * 这是这一版回执的**主菜**：自动归属的命中率实测只有 14%，所以回执不再声称
+ * "我替你对上了哪几步"，而是如实列出"这一遍你干了什么"，由人决定它对不对得上。
+ *
+ * 只显示 `动词 子命令 ×次数`（可带旗标）——**位置参数在分桶层就被丢弃了**，
+ * 因为完整命令行含绝对路径（路径含本机用户名），而这条回执会显示在界面上。
+ * 那也是 pipeline-activities.js 存在的第二个理由。
+ */
+function renderActivities(activities, t, maxRows = 12) {
+  if (!Array.isArray(activities) || activities.length === 0) return "";
+  const rows = activities.slice(0, maxRows).map((a) => {
+    // 键在没有子命令时用的是第一个旗标（`node --test`）——那种情况下别再把同一个旗标
+    // 追加一遍，否则会渲染成 `node --test --test`（端到端复验时抓到的重复）。
+    const shown = (a.flags || []).filter((f) => !a.key.endsWith(f));
+    const flags = shown.length ? ` ${shown.join(" ")}` : "";
+    return `  ${a.key}${flags} ×${a.count}`;
+  });
+  const more = activities.length > maxRows ? `\n  …另有 ${activities.length - maxRows} 种` : "";
+  return `${t.activities(activities.length)}\n${rows.join("\n")}${more}`;
+}
+
+/**
+ * 把一次 `stop()` 的结果翻成人话。
+ *
+ * P2 起 `stop` **不再写账**，而是产出一份待确认清单。所以这里的重点从
+ * "记了几步"变成"**请你确认哪几步走了**"——并给出步骤表与观察到的动作，供人对照。
+ */
+function describeStop(result, language) {
+  const t = STR.moRunStop[language];
+  const activityBlock = renderActivities(result.activities, t);
+
+  if (result.ok && result.state === "awaiting-confirmation") {
+    const prop = result.proposal;
+    const lines = prop.steps.map((s, i) => {
+      const hint = s.hintCount ? `  ← 本次看到 ${s.hintCount} 条相近命令` : "";
+      return `  ${i + 1}. ${s.id}  ${s.title}${s.declared ? `  [${s.declared}]` : ""}${hint}`;
+    });
+    const parts = [t.awaiting(prop.pipelineId, prop.steps.length)];
+    parts.push(lines.join("\n"));
+    if (activityBlock) parts.push(activityBlock);
+    // 「这条命令不是动作」与「没归属上」是两件事，混在一起会让人以为工具坏了
+    if (result.shellNoise) parts.push(t.shellNoise(result.shellNoise));
+    if (result.notCommands) parts.push(t.notCommands(result.notCommands));
+    if (result.truncated) parts.push(t.truncated);
+    parts.push(t.confirmHow(prop.steps.map((s) => s.id).slice(0, 3).join(" ")));
+    return parts.filter(Boolean).join("\n");
+  }
+
+  if (result.ok) {
+    const parts = [t.ok(result.pipelineId, result.steps)];
+    if (activityBlock) parts.push(activityBlock);
+    if (result.truncated) parts.push(t.truncated);
+    return parts.filter(Boolean).join("\n");
+  }
+
+  switch (result.reason) {
+    case "no-open-window":
+      return t.noWindow;
+    case "write-failed":
+      return t.writeFailed(result.detail);
+    default:
+      return t.failed(result.reason);
+  }
+}
+
+/** 把一次 `confirm()` 的结果翻成人话。 */
+function describeConfirm(result, language) {
+  const t = STR.moRunConfirm[language];
+  if (result.ok) {
+    const parts = [t.ok(result.pipelineId, result.steps)];
+    if (result.notDone?.length) parts.push(t.notDone(result.notDone.join("、")));
+    if (result.unsure?.length) parts.push(t.unsure(result.unsure.join("、")));
+    if (result.unanswered?.length) parts.push(t.unanswered(result.unanswered.join("、")));
+    // P3 的核心产出：你说这步做了，但声明的命令这次一次都没出现。
+    // 三种可能（声明该改 / 本来不必敲 / 记错了）必须由人判——系统只负责把矛盾摆出来。
+    if (result.toolMismatches?.length) {
+      const rows = result.toolMismatches.map((m) => {
+        const seen = m.observedTop?.length ? `；本次实际看到 ${m.observedTop.join("、")}` : "；本次没有可对照的动作";
+        return `  ${m.stepId}（${m.title}）：声明 ${m.declared}，本次未出现${seen}`;
+      });
+      parts.push(t.mismatch(result.toolMismatches.length, rows.join("\n")));
+    }
+    // 旁挂回执：给不给只取决于 memoryDir 是否配置——静默关闭是设计，不是失败
+    if (result.observationsSaved?.ok) {
+      parts.push(t.obsSaved(result.observationsSaved.file));
+    }
+    return parts.filter(Boolean).join("\n");
+  }
+  switch (result.reason) {
+    case "nothing-to-confirm":
+      return t.nothingToConfirm;
+    case "no-answers":
+      // 说了"没做"是记录；什么都没说不是——这条区分很重要。
+      return t.noAnswers(result.notDone?.length ?? 0, result.unsure?.length ?? 0, result.unanswered?.length ?? 0);
+    case "bad-answer-value":
+      return t.badValue(result.stepId, result.value);
+    case "unknown-step":
+      return t.unknownStep(result.stepId);
+    case "write-failed":
+      return t.writeFailed(result.detail);
+    default:
+      return t.failed(result.reason);
+  }
+}
+
+function describeStart(result, language) {
+  const t = STR.moRunStart[language];
+  if (result.ok) return t.ok(result.pipelineId, result.steps);
+  switch (result.reason) {
+    case "already-open":
+      return t.alreadyOpen(result.pipelineId);
+    case "pipeline-not-found":
+      return t.notFound(result.available?.length ? result.available.join("、") : t.noneAvailable);
+    case "pipeline-unreadable":
+      return t.unreadable(result.detail);
+    case "no-project-root":
+      return t.noProject;
+    case "no-session":
+      return t.noSession;
+    default:
+      return t.failed(result.reason);
+  }
+}
+
+function describeStatus(status, language) {
+  const t = STR.moRunStatus[language];
+  if (status.awaitingConfirmation) return t.awaiting(status.pipelineId, status.steps ?? 0);
+  if (!status.open) return t.closed;
+  return t.open(status, status.recorded.join("、") || t.none);
+}
+
+/**
+ * 造命令的 handler。
+ *
+ * handler 的返回值走 DSH 的 CommandResult 契约：**只作 UI 回执，不会进模型上下文**。
+ * 这个功能的目的是记账，不是给模型派活，所以不需要 `agent.followup`。
+ */
+export function createMoRunHandler({ recorder, language = () => "zh" } = {}) {
+  return (invocation) => {
+    const lang = language();
+    try {
+      const parsed = parseMoRunInput(invocation?.rawInput);
+      const session = invocation?.agent?.session;
+
+      if (parsed.action === "help") {
+        return { kind: "success", text: STR.moRunUsage[lang] };
+      }
+      if (parsed.action === "start") {
+        if (!parsed.pipelineId) return { kind: "error", text: STR.moRunUsage[lang] };
+        return { kind: "success", text: describeStart(recorder.start({ session, pipelineId: parsed.pipelineId }), lang) };
+      }
+      if (parsed.action === "stop") {
+        return { kind: "success", text: describeStop(recorder.stop({ session }), lang) };
+      }
+      if (parsed.action === "confirm") {
+        const result = recorder.confirm({ session, answers: parsed.answers });
+        return { kind: result.ok ? "success" : "error", text: describeConfirm(result, lang) };
+      }
+      return { kind: "success", text: describeStatus(recorder.status({ session }), lang) };
+    } catch (error) {
+      // 命令是用户主动触发的动作，不是热路径；出错就如实回报，但绝不把异常抛进宿主。
+      return { kind: "error", text: STR.moRunUsage[lang] };
+    }
+  };
+}
+
+/**
+ * 注册命令。**默认关**：只有旗标打开才注册——beta 功能必须 opt-in，老用户行为不变。
+ *
+ * 返回 disposer（与仓库其它注册点一致）；没注册时返回 null。
+ */
+export function registerMoRunCommand({ ctx, recorder, enabled, language = () => "zh" }) {
+  if (enabled !== true) return null;
+  if (typeof ctx?.commands?.register !== "function") return null;
+  return ctx.commands.register({
+    name: MO_RUN_COMMAND,
+    description: STR.moRunDescription[language()],
+    input: { hint: STR.moRunInputHint[language()] },
+    handler: createMoRunHandler({ recorder, language })
+  });
+}

package/src/pipeline-confirm.js

@@ -0,0 +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)
+  };
+}

package/src/pipeline-exec.js

@@ -0,0 +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;
+    }
+  };
+}