@modusensus/dsh-mneme 0.9.0 → 0.9.2

package/src/pipeline-observations.js

@@ -0,0 +1,181 @@
+/**
+ * P3 的两个产出：观察旁挂（丙方案）与 tool 不符检出。
+ *
+ * ## 背景（一句话）
+ *
+ * 自动归属被实测否决（14.2%，第三方复核 74% 变体唯一），所以写账由人确认；
+ * 而人确认时说「这一步做了」，可与本次**实际观察到的业务动作**对不上——
+ * 「声明是 npm test，这次一次 npm test 都没看到」。这个矛盾是步骤表过时的信号，
+ * 就是 P3 要捕的东西（设计见 mneme-research/mo-foundations/10 号）。
+ *
+ * ## 丙方案：观察为什么不进账本、要旁挂
+ *
+ * 账本 `.runs.jsonl` 是**已发布的数据契约**（v0.9.0 发出去的形状），为 P3 加字段
+ * 是「动已发布契约」，代价与风险都不必要。所以观察走旁挂文件：
+ *
+ *     <memoryDir>/observations/<项目键>/<工作流id>.jsonl
+ *
+ * 这在这个仓库有**三次同构先例**：candidates / proposals / 本目录。
+ * 共同纪律：**项目键分桶、只增不改（append-only）、不进仓库、坏行跳过但计数**。
+ *
+ * ## 🔴 隐私
+ *
+ * 观察清单的每一项都来自 `pipeline-activities` 的产物——那一层已经**剥掉了位置参数**
+ * （完整命令行含绝对路径，路径含本机用户名）。本模块**只存 `{key, count, flags}`**，
+ * 拒收任何带命令原文的形状。这是第二道闸：即使上游改了，这里也不放行。
+ */
+
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+/** 展开 `~`；观察旁挂跟 candidates/proposals 一样是本地状态（candidates.js 的 expandHome 同构）。
+ *  config.memoryDir 的默认值是 "~/.dsh/memory"，不展开的话 readdir 在带 "~" 的字面路径上
+ *  永远落空——旁挂静默读不到，fix-step-tool 提议少一类（CodeRabbit #458 F2）。 */
+function expandHome(p) {
+  const s = String(p || "");
+  if (s === "~") return homedir();
+  if (s.startsWith("~/") || s.startsWith("~\\")) return join(homedir(), s.slice(2));
+  return s;
+}
+
+/** 观察旁挂的目录：`<memoryDir>/observations/<项目键>/`。与 candidates/proposals 同构。 */
+export function observationDir({ memoryDir, projectKey } = {}) {
+  if (!projectKey || String(projectKey).trim() === "") return null;
+  const base = expandHome(memoryDir && String(memoryDir).trim() ? memoryDir : "~/.dsh/memory");
+  return join(base, "observations", projectKey);
+}
+
+/** 观察行的形状闸：只认 {key, count}（flags 可选且必须是旗标数组）。多一个字段都拒。 */
+export function validateObservationLine(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, reason: "not-object" };
+  if (typeof raw.key !== "string" || raw.key.trim() === "") return { ok: false, reason: "bad-key" };
+  if (!Number.isInteger(raw.count) || raw.count < 1) return { ok: false, reason: "bad-count" };
+  if (raw.flags !== undefined && !Array.isArray(raw.flags)) return { ok: false, reason: "bad-flags" };
+  if (raw.command !== undefined || raw.args !== undefined || raw.segments !== undefined) {
+    // 🔴 命令原文（或其片段）不许出现在观察行里——那是位置参数泄露的口子
+    return { ok: false, reason: "forbidden-field" };
+  }
+  return { ok: true };
+}
+
+/**
+ * 落盘一次确认时的观察清单（append-only，幂等键 = confirmAt）。
+ *
+ * 返回 `{ok, file, lines}`；传 `dryRun: true` 时只校验不写（测试与预览用）。
+ */
+export function saveObservations({ dir, pipelineId, confirmAt, activities, dryRun = false } = {}) {
+  if (!dir) return { ok: false, reason: "no-dir" };
+  if (!pipelineId || typeof pipelineId !== "string") return { ok: false, reason: "no-pipeline-id" };
+  if (typeof confirmAt !== "string" || confirmAt.trim() === "") return { ok: false, reason: "no-confirm-at" };
+  if (!Array.isArray(activities)) return { ok: false, reason: "bad-activities" };
+
+  const valid = [];
+  for (const a of activities) {
+    // 🔴 先验**原始输入**再构造：多带 command/args/segments 的行要**大声拒**，
+    // 不是悄悄剥掉——静默剥离会把上游的形状 bug 藏进一次"成功"的写入里。
+    const v0 = validateObservationLine(a);
+    if (!v0.ok) return { ok: false, reason: "invalid-line:" + v0.reason, file: null, lines: 0 };
+    const line = { key: a.key, count: a.count, ...(Array.isArray(a.flags) && a.flags.length ? { flags: a.flags } : {}) };
+    valid.push(line);
+  }
+
+  const record = { contract: "mneme.observations/v1", pipelineId, confirmAt, activities: valid };
+  const file = join(dir, `${pipelineId}.jsonl`);
+
+  // 幂等：同一 confirmAt 已写过就不重复（confirm 保留待确认状态重答的场景会重放）
+  if (existsSync(file)) {
+    const seen = readFileSync(file, "utf8").split("\n").filter((l) => l.trim());
+    for (const l of seen) {
+      try { if (JSON.parse(l).confirmAt === confirmAt) return { ok: true, file, lines: 0, duplicate: true }; }
+      catch { /* 坏行：与读侧同一纪律，跳过但不出声 */ }
+    }
+  }
+
+  if (dryRun) return { ok: true, file, lines: valid.length, dryRun: true };
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(file, JSON.stringify(record) + "\n", "utf8");
+  return { ok: true, file, lines: valid.length };
+}
+
+/** 读一个工作流攒下的全部观察（按 confirmAt 升序，坏行跳过并计数）。 */
+export function loadObservations(dir, pipelineId) {
+  if (!dir || !pipelineId) return { records: [], unreadable: 0 };
+  const file = join(dir, `${pipelineId}.jsonl`);
+  if (!existsSync(file)) return { records: [], unreadable: 0 };
+  const records = [];
+  let unreadable = 0;
+  for (const l of readFileSync(file, "utf8").split("\n")) {
+    if (!l.trim()) continue;
+    try {
+      const r = JSON.parse(l);
+      if (r?.contract === "mneme.observations/v1" && Array.isArray(r.activities)) records.push(r);
+      else unreadable += 1;
+    } catch { unreadable += 1; }
+  }
+  return { records, unreadable };
+}
+
+/**
+ * 批量读多个工作流的观察，压成 readPipelineDoc 要的形状：
+ *   { [pipelineId]: { latest: { activities } } }
+ *
+ * `latest` 取最后一条记录（confirmAt 升序写入，末条即最近一次确认）。
+ * 没有观察的 id 不出现在结果里——读侧用 `?? null` 降级，不制造空壳。
+ */
+export function loadObservationsById(dir, pipelineIds) {
+  const out = {};
+  for (const id of pipelineIds || []) {
+    if (typeof id !== "string" || id.trim() === "") continue;
+    const { records, unreadable } = loadObservations(dir, id);
+    if (records.length === 0) {
+      // 有文件但全坏也如实记一条空 latest？——不。空 = 没有观察，与坏文件同形处理，
+      //  unreadable 的计数只在单工作流读取时暴露，批量视图里降级为「没有」。
+      continue;
+    }
+    const last = records[records.length - 1];
+    out[id] = { latest: { activities: last.activities }, unreadable };
+  }
+  return out;
+}
+
+/**
+ * 🔴 核心判据：从「人确认的执行集」与「本次观察到的动作」里算出 tool 不符。
+ *
+ * - `pipeline.steps[].tool`：人手写的声明（可能是 `git push`，或 `a / b` 多锚点）
+ * - `confirmedDone`：人说了 done 的 stepId 集合
+ * - `activities`：本次观察到的业务动作（`{key, count}`）——**只认 key，不认命令原文**
+ *
+ * 返回不符清单。**unsure 与没答不进判据**（那不是「做了但没看到」，是「没确认」）。
+ * `declared` 原样带出，不含路径（tool 是作者手写的，且没有经过本模块之外的清洗——
+ * 若作者把路径写进 tool，那是步骤表自己的内容，应由步骤表校验层管，不在这里扩大职责）。
+ */
+export function toolMismatches({ pipeline, confirmedDone, activities } = {}) {
+  if (!pipeline || !Array.isArray(pipeline.steps)) return { ok: false, reason: "no-pipeline", items: [] };
+  if (!(confirmedDone instanceof Set)) return { ok: false, reason: "bad-confirmed", items: [] };
+  if (!Array.isArray(activities)) return { ok: false, reason: "bad-activities", items: [] };
+
+  const seen = new Set(activities.map((a) => String(a?.key ?? "").toLowerCase()).filter(Boolean));
+  const items = [];
+  for (const step of pipeline.steps) {
+    if (!confirmedDone.has(step.id)) continue;
+    const declared = typeof step.tool === "string" ? step.tool.trim() : "";
+    if (declared === "") continue;              // 纯人判步骤（无 tool 声明）无从矛盾
+    const anchors = declared.split("/").map((t) => t.trim().toLowerCase()).filter(Boolean);
+    // 多锚点（`a / b`）任一出现即算对上——它们是作者声明的同义做法
+    const hit = anchors.some((a) => seen.has(a));
+    if (!hit) {
+      items.push({
+        stepId: step.id,
+        title: step.title,
+        declared,
+        observedTop: activities
+          .slice()
+          .sort((a, b) => (b.count ?? 0) - (a.count ?? 0))
+          .slice(0, 3)
+          .map((a) => `${a.key} ×${a.count}`)
+      });
+    }
+  }
+  return { ok: true, items };
+}

package/src/pipeline-observe.js

@@ -0,0 +1,133 @@
+/**
+ * 把宿主的会话事件，翻成归属规则认得的**观察**。
+ *
+ * ## 为什么需要这一层（接线前实测出来的事实）
+ *
+ * 会话日志里的工具调用长这样：`name:"pwsh"`，`arguments:'{"command":"npm test"}'`。
+ * 而工作流里人写的 `tool` 是**命令行**：`"npm test"`、`"git push <tag>"`。
+ * **两者不重叠**——直接拿 `name` 去比，一条都对不上（实测 400 个会话里
+ * `pwsh` 1399 次、`read` 1709 次、`glob` 183 次，而工作流写的是 npm/git/gh 命令）。
+ *
+ * 唯一能对上的是：**命令跑在哪个工具里**。所以这一层的职责就是把它抽出来——
+ * `{name:"pwsh", arguments:{command:"npm test"}}` → `{command:"npm test"}`。
+ *
+ * ## 为什么只抽「命令执行器」，其余一律不给观察
+ *
+ * 真实工作流 19 步的 `tool` 全是 shell 命令（git / gh / npm / node）。而 `read`、`write`、
+ * `glob`、`grep` 这些是**代理的日常动作**，不是任何工作流的一步。硬把
+ * `read C:\…\file.js` 拼成一个「命令行」去参与匹配，只会制造噪声——而噪声的代价是
+ * 把某一步凭空染色。所以认不出来命令执行器，就**不产观察**（返回 null），
+ * 由上游记进 skipped 桶：**「不是工作流的动作」与「认不出是哪一步」是两件事。**
+ *
+ * ## 成败的三态
+ *
+ * `tool/result` 带 `message.isError`。只认 true/false 两个值，取不到时留 `null`
+ * ——把「不知道」折叠成「失败」会给这一步打上不该有的 refuted 标记。
+ */
+
+/** 命令执行器：只有跑在这些工具里的调用，才可能是工作流写成的那种命令行。 */
+const COMMAND_TOOLS = new Set(["pwsh", "bash", "sh", "shell", "cmd", "run_command", "terminal"]);
+
+/** 参数里哪个字段是命令行。按工具名给，取不到就退回常见字段名。 */
+const COMMAND_KEYS = ["command", "cmd", "script", "commandLine"];
+
+function parseArgs(raw) {
+  if (raw === null || raw === undefined) return null;
+  if (typeof raw === "object" && !Array.isArray(raw)) return raw;
+  if (typeof raw !== "string") return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 这次工具调用是不是一条工作流命令。是就给出命令行，不是给 `null`。
+ *
+ * 返回 `{tool, command}`；`command` 已去掉首尾空白（比较由归属规则负责）。
+ */
+export function commandFromToolCall(name, args) {
+  const tool = typeof name === "string" ? name.trim() : "";
+  if (tool === "" || !COMMAND_TOOLS.has(tool.toLowerCase())) return null;
+  const parsed = parseArgs(args);
+  if (!parsed) return null;
+  for (const key of COMMAND_KEYS) {
+    const value = parsed[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      return { tool, command: value.trim() };
+    }
+  }
+  // 是命令执行器但参数里没有命令行（形状变了）：不猜，给 null。
+  return null;
+}
+
+/** `tool/result` 的成败：只认布尔，拿不到留 null（「不知道」不许折叠成「失败」）。 */
+export function outcomeOfToolResult(event) {
+  const message = event?.data?.message;
+  if (!message || typeof message !== "object") return null;
+  if (message.isError === true) return false;
+  if (message.isError === false) return true;
+  // 旧形状把 isError 挂在 content 的 tool-result 块上；两种都不认时留 null。
+  const blocks = Array.isArray(message.content) ? message.content : [];
+  const legacy = blocks.find((b) => b && b.type === "tool-result");
+  if (legacy && typeof legacy.isError === "boolean") return legacy.isError !== true;
+  return null;
+}
+
+/**
+ * 把一串会话事件配对成观察列表（纯函数，便于测试与批处理）。
+ *
+ * 配对靠 `callId`：`tool/call` 先到、`tool/result` 后到。**只有拿到结果的调用才产观察**
+ * ——结果决定了成败，而「调了但没结果」既不是成功也不是失败（可能被中断），
+ * 拿它当一次成功使用是编造。
+ *
+ * 另外两条纪律：
+ * - 认不出命令执行器的调用**直接丢**（进 `notCommands` 计数），不产观察
+ * - 有调用没结果的，如实进 `dangling`，不产观察也不假装失败
+ */
+export function pairObservations(events) {
+  const pending = new Map(); // callId -> {tool, command, at}
+  const observations = [];
+  const dangling = [];
+  let notCommands = 0;
+
+  for (const event of events || []) {
+    const type = event?.type;
+    if (type === "tool/call") {
+      const data = event.data ?? {};
+      const extracted = commandFromToolCall(data.name, data.arguments);
+      if (!extracted) {
+        notCommands += 1;
+        continue;
+      }
+      const callId = data.callId ?? null;
+      const entry = { ...extracted, at: event.at ?? null };
+      if (callId === null) {
+        // 没有 callId 就无法配对結果；不硬凑，如实记下。
+        dangling.push({ ...entry, why: "调用没有 callId，无法与结果配对" });
+        continue;
+      }
+      pending.set(callId, entry);
+      continue;
+    }
+
+    if (type === "tool/result") {
+      const callId = event?.data?.callId ?? event?.callId ?? null;
+      if (callId === null || !pending.has(callId)) continue;
+      const entry = pending.get(callId);
+      pending.delete(callId);
+      observations.push({
+        tool: entry.tool,
+        command: entry.command,
+        ok: outcomeOfToolResult(event),
+        at: entry.at
+      });
+    }
+  }
+
+  for (const entry of pending.values()) dangling.push({ ...entry, why: "调用没有等到结果" });
+
+  return { observations, dangling, notCommands };
+}

package/src/pipeline-runner.js

@@ -0,0 +1,346 @@
+/**
+ * M.O. 的**执行记录器**：把「谁在什么时候按哪条工作流走了一遍」记成一条账。
+ *
+ * ## 它在整条链里的位置
+ *
+ *     session/event → pairObservations → attributionCandidates → openRun → appendRun
+ *      （宿主事件）    （事件→观察）        （观察→哪一步）        （窗口）   （落盘）
+ *
+ * 前四段都已各自成模块并被测过。本模块是**把它们串起来的那一层**，也是唯一持有
+ * 「当前有哪些窗口开着」这个状态的地方。
+ *
+ * ## 四个刻意的取舍
+ *
+ * 1. **窗口按会话开，一个会话同时只允许一个**。一次执行是「这条流程走一遍」，不是
+ *    「同时走两条」。再开一个会被**拒**（`already-open`）而不是顶掉前一个——顶掉会让
+ *    前一次的执行悄无声息地消失，那比拒绝难查得多。
+ *
+ * 2. **事件先缓冲、到 stop 才配对**。`tool/call` 与 `tool/result` 靠 callId 配对，结果
+ *    可能比调用晚很久；边到边配会把「还没等到结果」误判成「没有这个调用」。
+ *
+ * 3. **v1 只在显式 stop 时结账**，不在回合结束时自动关。一条流程常常跨多个回合
+ *    （跑测试 → 等人点头 → 再继续），按回合关会把一次执行切成好几条半截账。
+ *    代价是忘了 stop 会一直开着——所以缓冲有上限，超了标 `truncated` 并如实写出。
+ *
+ * 4. **热路径上永不抛**。挂的是宿主每个会话事件的通道，本仓对此有明文不变量
+ *    （`continuity.js` 的「可选插件的可选能力把 agent 的一步带崩，比丢一次抢救严重
+ *    得多」）。所有异常只 `warn`，绝不让宿主的一步失败。
+ *
+ * ## 一个尚未实测的前提
+ *
+ * `session/event` 的实时通道是否**逐条**投递 `tool/call` 与 `tool/result`，我没有在
+ * 活宿主上验过（本仓现有消费者只用 `turn/end` 与压缩边缘；工具事件是从**日志文件**
+ * 读的）。事件类型联合与落盘日志都包含它们，所以同一通道应当也带——但这是**推断**，
+ * 接线后要用一次真实执行验证（开窗走一遍，看账里有没有步骤）。本模块把这件事做成
+ * 可观测的：`stop()` 的返回里给出缓冲到多少条事件，一条都没缓冲到时会有
+ * `reason:"no-observations"`，而不是写一条空账假装成功。
+ */
+
+import { loadPipelines, pipelineSources } from "./pipeline.js";
+import { appendRun } from "./pipeline-runs.js";
+import { openRun } from "./pipeline-exec.js";
+import { pairObservations } from "./pipeline-observe.js";
+import { tallyActivities } from "./pipeline-activities.js";
+import { buildProposal, runFromAnswers } from "./pipeline-confirm.js";
+import { observationDir, saveObservations, toolMismatches } from "./pipeline-observations.js";
+import { projectKey } from "./candidates.js";
+
+/** 一个窗口最多缓冲多少条会话事件。忘了 stop 时，这是内存的兜底。 */
+export const MAX_BUFFERED_EVENTS = 4000;
+
+/**
+ * 会话的工作目录。与 `scope.js` 同一口径：`session.header` 是创建时冻结的那份
+ * （含 `cwd`），**不能先读 `requestHeader()`** —— 那返回请求级模型路由头，会把
+ * `cwd` 遮蔽掉（scope.js 里记着本地 web 实测踩中过）。
+ */
+export function projectRootOf(session) {
+  const header = session?.header ?? session?.requestHeader?.()?.config ?? null;
+  const cwd = header?.cwd;
+  return typeof cwd === "string" && cwd.trim() !== "" ? cwd : null;
+}
+
+/**
+ * 默认的工作流解析：项目层优先、全局层兜底（与 `readPipelineDoc` 同一优先级）。
+ *
+ * 坏文件按 `loadPipelines` 的纪律**照抛**，由调用方兜住并如实回报——静默跳过会让
+ * 「这条流程读不出来」与「没有这条流程」长得一样。
+ */
+export function defaultResolvePipeline(projectRoot, pipelineId) {
+  for (const source of pipelineSources({ projectRoot })) {
+    const list = loadPipelines(source.dir, { scope: source.scope, label: source.label });
+    const hit = list.find((p) => p.id === pipelineId);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** 所有工作流的 id 清单（给命令的用法提示与「你指的是哪条」用）。 */
+export function listPipelineIds(projectRoot) {
+  const ids = [];
+  try {
+    for (const source of pipelineSources({ projectRoot })) {
+      for (const p of loadPipelines(source.dir, { scope: source.scope, label: source.label })) {
+        if (!ids.includes(p.id)) ids.push(p.id);
+      }
+    }
+  } catch {
+    // 清单只是提示信息，读不出来不该让命令本身失败。
+  }
+  return ids;
+}
+
+/**
+ * 造一个记录器。
+ *
+ * 除了 `ctx` 之外的所有依赖都可注入（`resolvePipeline` / `persistRun` / `now`），
+ * 这样测试不必碰真文件系统，也能精确控制时间。
+ */
+export function createExecutionRecorder({
+  ctx,
+  logger = null,
+  resolvePipeline = defaultResolvePipeline,
+  persistRun = appendRun,
+  now = () => new Date(),
+  maxBufferedEvents = MAX_BUFFERED_EVENTS,
+  // P3（丙）：观察旁挂的根目录。null = 不落旁挂（P3 静默关闭）。
+  // 与 resolvePipeline/persistRun 同款依赖注入——runner 不读 config，测试不碰真文件系统。
+  memoryDir = null
+} = {}) {
+  const windows = new Map(); // sessionId → { pipeline, projectRoot, run, events, truncated }
+  // 已结账、等人确认的会话：sessionId → { pipeline, projectRoot, proposal, stats }
+  const pending = new Map();
+
+  const unsubscribe = ctx?.on?.("session/event", (session, event) => {
+    try {
+      const id = session?.id;
+      if (!id) return;
+      const w = windows.get(id);
+      // 没有开窗 = 一个字都不记。这是整个设计的地基：漏记可接受，编造不可。
+      if (!w) return;
+      const type = event?.type;
+      if (type !== "tool/call" && type !== "tool/result") return;
+      if (w.events.length >= maxBufferedEvents) {
+        w.truncated = true;
+        return;
+      }
+      w.events.push(event);
+    } catch (error) {
+      logger?.warn?.(`dsh-mneme: 执行记录器读事件失败：${String(error)}`);
+    }
+  });
+
+  return {
+    /**
+     * 开窗。`pipelineId` 由调用方点名——**本模块不猜**「用户刚才那句话是不是意味着
+     * 开始走某条流程」。猜错会把一条从没跑过的流程记成跑过。
+     */
+    start({ session, pipelineId } = {}) {
+      const id = session?.id;
+      if (!id) return { ok: false, reason: "no-session" };
+      const open = windows.get(id);
+      if (open) return { ok: false, reason: "already-open", pipelineId: open.pipeline.id };
+
+      const projectRoot = projectRootOf(session);
+      if (!projectRoot) return { ok: false, reason: "no-project-root" };
+
+      let pipeline;
+      try {
+        pipeline = resolvePipeline(projectRoot, pipelineId);
+      } catch (error) {
+        return { ok: false, reason: "pipeline-unreadable", detail: String(error?.message ?? error) };
+      }
+      if (!pipeline) {
+        return { ok: false, reason: "pipeline-not-found", available: listPipelineIds(projectRoot) };
+      }
+
+      const run = openRun({ pipeline, by: "main", triggeredBy: String(pipelineId ?? ""), now });
+      windows.set(id, { pipeline, projectRoot, run, events: [], truncated: false });
+      return { ok: true, pipelineId: pipeline.id, steps: pipeline.steps.length };
+    },
+
+    /**
+     * 结账：**不再自动写账**，改成产出一份「请你确认哪几步走了」的提案。
+     *
+     * 这是 P2 的契约变更，理由是被实测否决的自动归属（详见 pipeline-confirm 的文件头）：
+     * 机器唯一归属只有 14.2%，而**猜错的代价是把没走过的步骤记成走过**
+     * （`deriveState` 会据此把它染成 trusted）。所以写账这一步必须有人确认。
+     *
+     * 自动归属的结果**降级成 hint**：仍然算出来，但只作提示、不预选、不落盘。
+     * 同时给出 P1 那份「观察到的业务动作清单」，让人对照着勾。
+     */
+    stop({ session } = {}) {
+      const id = session?.id;
+      if (!id) return { ok: false, reason: "no-session" };
+      const w = windows.get(id);
+      if (!w) return { ok: false, reason: "no-open-window" };
+      windows.delete(id);
+
+      const { observations, dangling, notCommands } = pairObservations(w.events);
+
+      // 自动归属只用来产 hint：唯一 exact 的那一步给出来，其余不给。
+      // 它不进账——这一版的账只有人能写。
+      const hints = {};
+      for (const observation of observations) {
+        const r = w.run.observe(observation);
+        if (r.result === "observed" && r.stepId) {
+          // hint 只记「这次见到过相近的命令」这个事实，**不存命令行原文**：
+          // 完整命令行含绝对路径（路径含本机用户名），而这条 hint 会流到命令回执里。
+          hints[r.stepId] = (hints[r.stepId] || 0) + 1;
+        }
+      }
+
+      const activityTally = tallyActivities(observations);
+      const proposal = buildProposal({
+        pipeline: w.pipeline,
+        activities: activityTally.activities,
+        hints
+      });
+
+      // 待确认状态挂在会话上：人在下一次调用里回答。
+      // stats 只留**确认阶段真的会渲染**的三个字段（ponytail 复核：另外三个零读取）。
+      pending.set(id, {
+        pipeline: w.pipeline,
+        projectRoot: w.projectRoot,
+        proposal,
+        // P3（丙）：把本次观察清单带进待确认状态。confirm 时它有三个用途：
+        // 旁挂落盘 / tool 不符检出 / 回执展示。memoryDir 为空时不带（P3 关）。
+        activities: activityTally.activities,
+        stats: {
+          truncated: w.truncated,
+          notCommands,
+          shellNoise: activityTally.shellNoise
+        }
+      });
+
+      return {
+        ok: true,
+        state: "awaiting-confirmation",
+        proposal,
+        activities: activityTally.activities,
+        shellNoise: activityTally.shellNoise,
+        bufferedEvents: w.events.length,
+        truncated: w.truncated,
+        observations: observations.length,
+        notCommands,
+        dangling: dangling.length
+      };
+    },
+
+    /**
+     * 人确认后落盘。**这是唯一会写账的入口。**
+     *
+     * `answers` 形如 `{ "P6": "done", "V2": "notDone" }`；未提到的步骤什么都不写
+     * （"没确认"不等于"没发生"，见 pipeline-confirm 的注释）。
+     */
+    confirm({ session, answers } = {}) {
+      const id = session?.id;
+      if (!id) return { ok: false, reason: "no-session" };
+      const p = pending.get(id);
+      if (!p) return { ok: false, reason: "nothing-to-confirm" };
+
+      const result = runFromAnswers({
+        pipeline: p.pipeline,
+        answers,
+        by: "human",
+        triggeredBy: String(p.pipeline.id ?? ""),
+        now
+      });
+
+      if (result.kind === "error") {
+        // 回答非法：**保留待确认状态**，让人重答，而不是把它丢掉。
+        return { ok: false, reason: result.reason, stepId: result.stepId, value: result.value, ...p.stats };
+      }
+
+      if (result.kind === "nothing") {
+        // 什么都没确认：没有信息可记，如实说，且不留一个悬着的待确认状态。
+        pending.delete(id);
+        return {
+          ok: false,
+          reason: "no-answers",
+          notDone: result.notDone,
+          unanswered: result.unanswered,
+          unsure: result.unsure,
+          ...p.stats
+        };
+      }
+
+      pending.delete(id);
+      try {
+        persistRun(p.projectRoot, p.pipeline.id, result.run);
+      } catch (error) {
+        return { ok: false, reason: "write-failed", detail: String(error?.message ?? error), ...p.stats };
+      }
+
+      // ── P3：人确认过的事实，与本次观察到的动作对一遍 ──────────────────
+      // ① tool 不符检出：人说了 done、但声明的 tool 在本次动作里没出现。
+      //    这是「步骤表可能与实际行为脱节」的信号（实测：gh pr merge --rebase 在
+      //    21723 次调用里出现 0 次）。**只报告，不改步骤表**——改表是人的动作。
+      const doneIds = new Set(result.run.steps.filter((s) => !s.skipped).map((s) => s.id));
+      let toolMismatchesResult = { ok: true, items: [] };
+      if (Array.isArray(p.activities)) {
+        toolMismatchesResult = toolMismatches({
+          pipeline: p.pipeline,
+          confirmedDone: doneIds,
+          activities: p.activities
+        });
+      }
+      // ② 观察旁挂（丙）：memoryDir 给了才落。写失败**不连累记账**——旁挂是
+      // 可再生的辅助数据（同一 run 重走一遍就有），账本才是唯一事实。
+      let observationsSaved = null;
+      if (memoryDir && Array.isArray(p.activities)) {
+        const key = projectKey(p.projectRoot);
+        const odir = observationDir({ memoryDir, projectKey: key });
+        if (odir) {
+          try {
+            observationsSaved = saveObservations({
+              dir: odir,
+              pipelineId: p.pipeline.id,
+              confirmAt: result.run.at,
+              activities: p.activities
+            });
+          } catch (error) {
+            logger?.warn?.(`dsh-mneme: 观察旁挂写入失败（不影响记账）：${String(error)}`);
+          }
+        }
+      }
+
+      return {
+        ok: true,
+        pipelineId: p.pipeline.id,
+        steps: result.run.steps.length,
+        // 三类如实分开：「确认没做」「说不知道」「压根没答」是三种不同的信息
+        notDone: result.notDone,
+        unsure: result.unsure,
+        unanswered: result.unanswered,
+        // P3 的两个产出：不符清单（人判「声明该改还是本来不必敲」）与旁挂回执
+        toolMismatches: toolMismatchesResult.ok ? toolMismatchesResult.items : [],
+        observationsSaved: observationsSaved
+          ? { ok: true, file: observationsSaved.file, lines: observationsSaved.lines, duplicate: observationsSaved.duplicate === true }
+          : { ok: false, skipped: true },
+        ...p.stats
+      };
+    },
+
+    /** 只看状态，不结账。要能分辨「窗口开着」与「等你确认」两种状态。 */
+    status({ session } = {}) {
+      const id = session?.id;
+      if (pending.has(id)) {
+        const p = pending.get(id);
+        return { open: false, awaitingConfirmation: true, pipelineId: p.pipeline.id, steps: p.proposal.steps.length, ...p.stats };
+      }
+      const w = windows.get(id);
+      if (!w) return { open: false };
+      return { ...w.run.state(), bufferedEvents: w.events.length, truncated: w.truncated };
+    },
+
+    dispose() {
+      try {
+        unsubscribe?.();
+      } catch {
+        /* 重复 dispose 不报错 */
+      }
+      windows.clear();
+      pending.clear();
+    }
+  };
+}