@modusensus/dsh-mneme 0.9.0 → 0.9.2

package/src/settings.js

@@ -31,6 +31,67 @@ function parseList(raw) {
   }
 }
 
+// persona 对象的字段白名单：写入时只挑这些键，未知字段丢弃（设计稿①：字段从简，
+// beta 收到真实反馈再加；provenance 是 v1.5 协作式人格的预留位，v1 不写管道）。
+// 读侧损坏即回空对象——同一容错口径照 parseList（坏值不抛错、面板显示为空可重写）。
+const PERSONA_FIELDS = ["name", "personality", "replyStyle", "enabled", "provenance"];
+
+function parsePersona(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+    const out = {};
+    for (const key of PERSONA_FIELDS) {
+      if (value[key] !== undefined) out[key] = value[key];
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+// 多卡模型（v1.2）：存储形为 { default: <卡>, byAgent: { <agentId>: <卡>, … } }。
+// 兼容层：v1 存的是单对象（有 PERSONA_FIELDS 键、无 default/byAgent 键），读侧
+// 判形状——单对象原样落 default 位，旧数据零迁移。byAgent 的键是 agent 身份
+// id（注入时按会话身份寻址，取不到落 default）。default 卡不可删（兜底位）。
+function parsePersonaStore(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return { default: {}, byAgent: {} };
+    }
+    // 新形：含 default 或 byAgent 键 → 按多卡解析
+    if ("default" in value || "byAgent" in value) {
+      const byAgent = {};
+      if (value.byAgent && typeof value.byAgent === "object" && !Array.isArray(value.byAgent)) {
+        for (const [agentId, card] of Object.entries(value.byAgent)) {
+          const parsed = parsePersona(JSON.stringify(card ?? {}));
+          if (Object.keys(parsed).length) byAgent[String(agentId)] = parsed;
+        }
+      }
+      return { default: parsePersona(JSON.stringify(value.default ?? {})), byAgent };
+    }
+    // 旧形：v1 单对象 → 整体作 default（字段白名单在 parsePersona 内裁）
+    return { default: parsePersona(raw), byAgent: {} };
+  } catch {
+    return { default: {}, byAgent: {} };
+  }
+}
+
+function serializePersonaStore(store) {
+  const out = {
+    default: parsePersona(JSON.stringify(store?.default ?? {})),
+    byAgent: {}
+  };
+  if (store?.byAgent && typeof store.byAgent === "object") {
+    for (const [agentId, card] of Object.entries(store.byAgent)) {
+      const parsed = parsePersona(JSON.stringify(card ?? {}));
+      if (Object.keys(parsed).length) out.byAgent[String(agentId)] = parsed;
+    }
+  }
+  return JSON.stringify(out);
+}
+
 // --- feature flags（功能开关）白名单 -----------------------------------------
 // 面板可逐项开关的后端能力。设计约束：
 // 1. 键名与类型必须和 config.js schema 同名同型，这份白名单是唯一校验源
@@ -113,6 +174,13 @@ const FEATURE_FLAG_BOOLEANS = [
   // Issue #17（v0.8.0 A3）：strictScope 硬过滤——他 scope 完全不可见（关闭时
   // 为 A2 软隔离：降权保留可见）。
   "strictScope",
+  // Issue #471：政策轴——作用域级可逆闸门（scopeState）。与上面两个键是两条不同的
+  // 轴：那两个管「这条记忆属于谁」（事实轴），这两个管「这个作用域现在通不通」
+  // （政策轴，按作用域整体按下、跨会话存续、松开即恢复）。两级语义同
+  // writeAdmission/preInjectGate——enabled 跑判定（观察档，留审计行但照常注入）、
+  // enforce 真拦（不注入）；都默认关。点号键平铺存、合并时展开回 scopeState 对象。
+  "scopeState.enabled",
+  "scopeState.enforce",
   // 工具暴露开关（v0.8.5）：记忆已每轮自动注入，memory_search/memory_archive
   // 在慢/轻量模型上是多余往返，面板可关（默认关=行为不变）。
   "disableMemorySearch",
@@ -146,7 +214,18 @@ const FEATURE_FLAG_BOOLEANS = [
   // 决定是否注册座位（会话头图标 / 浮层 / 右栏 / 对话行卡片），服务端只负责把
   // 这个键稳定暴露出来——键若不在 effective 里，客户端静默少键、一个座位都不注册。
   // 默认关（beta、opt-in）；顶层扁平键，因此不需要 NESTED_FLAG_PATHS 条目。
-  "actionPipelineEnabled"
+  "actionPipelineEnabled",
+  // v0.9.0 第二批：M.O. 执行记账（`/mo-run` 开窗 → 窗口内命令被记成一条 run）。
+  // 与上面那个键分开：那个管「看图的座位」，这个管「往账本里写」。默认关（beta、
+  // opt-in），顶层扁平键，不需要 NESTED_FLAG_PATHS 条目。
+  "actionRunEnabled",
+  // 人格定义页（beta）：注入器渲染人格段的顶层总闸（双闸门的 config 半边；对象内
+  // 的 persona.enabled 是 per-agent 半边，存 user_settings 的 "persona" 键，见
+  // getPersona/setPersona）。默认关（beta、opt-in，老用户行为逐字节不变）；不进
+  // LIGHT_MODE_OFF——人格段是用户自写的一小段轻量常驻文本，不引入任何重型后台
+  // 路径，轻量档用户显式勾选仍然赢（同 actionPipelineEnabled 的定性）。顶层扁平
+  // 键，不需要 NESTED_FLAG_PATHS 条目。
+  "personaEnabled"
 ];
 // 整数开关的闭区间，与 config.js 里 z.natural().min().max() 对齐。
 const FEATURE_FLAG_INT_RANGES = {
@@ -403,6 +482,65 @@ export function createSettings(db) {
       setSetting("rules", JSON.stringify(list));
     },
 
+    /**
+     * Agent persona (name / personality / replyStyle + enabled gate), stored as
+     * one JSON key. v1.2 多卡：存储形 { default, byAgent }，旧 v1 单对象读作
+     * default 兼容。getPersona 返回全量多卡形（面板用）；getPersonaFor 按 agent
+     * 身份取卡（注入用），身份缺失/无卡/卡 enabled=false 均落 default。
+     */
+    getPersona() {
+      return parsePersonaStore(getSetting("persona") ?? "{}");
+    },
+    setPersona(input) {
+      // 双形兼容：单对象形 = 只更新 default、byAgent 保留（旧面板/旧调用方合并语义）；
+      // 多卡形 = 全量替换。坏体（非对象）在此不落库不抛错，保值由调用方守卫。
+      if (typeof input !== "object" || input === null || Array.isArray(input)) return;
+      if ("default" in input || "byAgent" in input) {
+        setSetting("persona", serializePersonaStore(input));
+        return;
+      }
+      const current = parsePersonaStore(getSetting("persona") ?? "{}");
+      current.default = parsePersona(JSON.stringify(input));
+      setSetting("persona", serializePersonaStore(current));
+    },
+    /** Per-agent lookup for the injector: id card → default fallback. */
+    getPersonaFor(agentId) {
+      const store = parsePersonaStore(getSetting("persona") ?? "{}");
+      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+      if (id) {
+        const card = store.byAgent[id];
+        if (card && card.enabled === true) return card;
+      }
+      return store.default;
+    },
+    /** Replace one byAgent card wholesale (panel save); default 不可经此改。 */
+    setPersonaFor(agentId, card) {
+      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+      if (!id || id === "default") return false;
+      const store = parsePersonaStore(getSetting("persona") ?? "{}");
+      const clean = parsePersona(JSON.stringify(
+        typeof card === "object" && card !== null && !Array.isArray(card) ? card : {}
+      ));
+      if (Object.keys(clean).length) store.byAgent[id] = clean;
+      else delete store.byAgent[id];
+      setSetting("persona", serializePersonaStore(store));
+      return true;
+    },
+    /** byAgent 键列表（面板卡列表用，default 不在其中）。 */
+    listPersonas() {
+      return Object.keys(parsePersonaStore(getSetting("persona") ?? "{}").byAgent);
+    },
+    /** 删一张 byAgent 卡；default 不可删（返回 false）。 */
+    removePersona(agentId) {
+      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+      if (!id || id === "default") return false;
+      const store = parsePersonaStore(getSetting("persona") ?? "{}");
+      if (!(id in store.byAgent)) return false;
+      delete store.byAgent[id];
+      setSetting("persona", serializePersonaStore(store));
+      return true;
+    },
+
     /** All custom commands, sorted by name. */
     listCommands() {
       const rows = db.prepare("SELECT * FROM custom_commands ORDER BY name ASC").all();

package/src/store.js

@@ -2,6 +2,15 @@ import { DatabaseSync } from "node:sqlite";
 import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
 import { contentHashOf } from "./content-hash.js";
+// 政策轴（issue #471）的归一化函数。刻意只取归一化，不取判定：判定（buildPausedIndex /
+// matchPausedScopes / createScopeStateGate）留在 scope-state.js，由 service 侧消费，
+// 存储层只管「一格状态怎么落」。依赖方向 store → scope-state → scope 是单向的
+// （scope.js 不 import 任何本包模块），所以不构成环。
+import {
+  normalizeScopeStateDimension,
+  normalizeScopeStateState,
+  normalizeScopeStateValue
+} from "./scope-state.js";
 
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS memories (
@@ -185,6 +194,25 @@ CREATE TABLE IF NOT EXISTS scope_changes (
 );
 CREATE INDEX IF NOT EXISTS idx_scope_changes_memory ON scope_changes(memory_id);
 
+-- scope_state: v0.9.1 政策轴（issue #471）。与 scope_changes 那条事实轴相对：
+-- scope_changes 记「某条记忆的归属被人工改过」（跟着记忆走），本表记「某个作用域
+-- 现在通不通」（跟着作用域走）。按下/松开都是单方面动作，不触碰任何记忆行，
+-- 松开即恢复——所以它是可逆的，而逐条 forget/archive 不是。
+-- dimension 只认 'agent'|'workspace'（scopeKeyOf 那两个维度）；scope_value='*'
+-- 表示该维度全局。一行一格，重复按下同一状态不刷新 decided_at（见 setScopeState）。
+-- Bookkeeping like the other audit tables: it never triggers write hooks.
+CREATE TABLE IF NOT EXISTS scope_state (
+  id           TEXT PRIMARY KEY,
+  dimension    TEXT NOT NULL,
+  scope_value  TEXT NOT NULL,
+  state        TEXT NOT NULL,               -- active | paused
+  note         TEXT,
+  decided_at   TEXT NOT NULL
+);
+-- 唯一性靠独立索引（本仓惯例：UNIQUE 不进 CREATE TABLE，见 idx_memory_provenance_link）。
+-- 它同时是 setScopeState 那条 UPSERT 的冲突目标，所以不能省。
+CREATE UNIQUE INDEX IF NOT EXISTS idx_scope_state_key ON scope_state(dimension, scope_value);
+
 -- llm_audit_logs: every background LLM call (autoDream consolidation + summary,
 -- autoSummarize compression) is recorded here — tokens in/out, duration, status
 -- and the trigger that caused it (Bug8). Failures are captured as status='error'
@@ -604,6 +632,20 @@ function toScopeChange(row) {
   };
 }
 
+// scope_state 行 → 读侧对象（issue #471）。NULL note 落 undefined，与
+// toScopeChange 同口径。
+function toScopeState(row) {
+  if (!row) return undefined;
+  return {
+    id: row.id,
+    dimension: row.dimension,
+    scope_value: row.scope_value,
+    state: row.state,
+    note: row.note ?? undefined,
+    decided_at: row.decided_at
+  };
+}
+
 function toRecallRun(row) {
   if (!row) return undefined;
   return {
@@ -835,6 +877,15 @@ export function createStore(path) {
   // 老库打开时 SCHEMA 的 CREATE TABLE 对既有表不生效，列还不存在，把索引写进 SCHEMA
   // 会直接报 no such column（与下方 llm_audit_logs.session_key 同理）。
   addColumn("memories", "content_hash", "ALTER TABLE memories ADD COLUMN content_hash TEXT");
+  // 每条向量的出身（行级 model hash，如 `qwen3.7-text-embedding-flash#17a6a0b1`）。
+  // 为什么必须行级：vector_meta 只有一个 model_hash，它记的是「最后一次成功写入
+  // 的模型」，换模型时被整表覆盖——于是上一代模型产出的向量在元数据上看起来完全
+  // 合规，实际与新模型的查询向量不可比。没有这一列，「这条向量是不是当前模型产
+  // 的」就无从判断（content_hash 是内容归一化哈希，与向量模型无关；dimension 在
+  // 同为 1024 维的模型间也区分不出来）。
+  // 存量行的值是 NULL，且**不推断**：按 updated_at 猜出的模型名会变成日后审计信
+  // 以为真的证据。NULL 一律读作「出身未知」，等价的补法是重算，不是猜。
+  addColumn("memories", "embedding_model", "ALTER TABLE memories ADD COLUMN embedding_model TEXT");
   // issue #24 块2（权重演化）：entity_relations 加 weight + source。存量关系
   // 行缺列 → 默认 manual 1.0（最保守：既有语义不因迁移而变弱）。
   addColumn("entity_relations", "weight", "ALTER TABLE entity_relations ADD COLUMN weight REAL NOT NULL DEFAULT 1.0");
@@ -1606,10 +1657,24 @@ export function createStore(path) {
     return rows.map((row) => row.content ?? "");
   }
 
-  /** Set (or clear with null) the embedding vector of a memory. */
-  function setEmbedding(id, vector) {
+  /** Set (or clear with null) the embedding vector of a memory.
+   *  `modelHash` records which model produced THIS vector (see the
+   *  embedding_model migration note). Clearing the vector clears the
+   *  provenance with it, so a NULL vector is never paired with a stale model
+   *  name; omitting modelHash leaves the column untouched (callers that
+   *  predate the column still work, their rows simply read as unknown). */
+  function setEmbedding(id, vector, modelHash) {
     const json = Array.isArray(vector) && vector.length ? JSON.stringify(vector) : null;
-    db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(json, id);
+    if (json) {
+      if (modelHash !== undefined) {
+        db.prepare("UPDATE memories SET embedding = ?, embedding_model = ? WHERE id = ?")
+          .run(json, modelHash === null ? null : String(modelHash), id);
+      } else {
+        db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(json, id);
+      }
+    } else {
+      db.prepare("UPDATE memories SET embedding = NULL, embedding_model = NULL WHERE id = ?").run(id);
+    }
     // Issue #202：单一写入口即单一失效点——重写缓存条目（向量在手上不必重解析），
     // 清空则移除，删除过的 id 不会被下一次 searchVector 的 id 集合选中。
     if (json) {
@@ -1662,6 +1727,80 @@ export function createStore(path) {
     ).all(limit);
   }
 
+  /**
+   * Rows whose vector is missing OR was produced by a different model than
+   * `modelHash` — the selector the backfill should use whenever the caller
+   * knows which model the vectors are supposed to come from.
+   *
+   * Why `needsEmbedding` alone is not enough: it only matches empty vectors,
+   * so after a model switch every vector written by the previous model stays
+   * eligible for "has a vector" forever, while its similarity to the current
+   * query embedding is meaningless. Those rows keep inflating the status
+   * card's coverage while semantic recall silently degrades.
+   *
+   * `embedding_model IS NULL` counts as stale on purpose: NULL means "written
+   * before per-row provenance existed, producing model unknown", and an
+   * unknown origin cannot be proven to match. Those rows get re-embedded
+   * rather than assumed correct.
+   *
+   * When `modelHash` is falsy (embedder unconfigured / no fingerprint yet)
+   * this degrades to the plain missing-only selector instead of re-embedding
+   * the whole table against nothing.
+   */
+  function needsEmbeddingFor(modelHash, limit = 50) {
+    if (!modelHash) return needsEmbedding(limit);
+    return db.prepare(
+      `SELECT id, title, content, embedding_model FROM memories
+       WHERE ((embedding IS NULL OR embedding = '')
+              OR embedding_model IS NULL
+              OR embedding_model != ?)
+         AND forgotten = 0 AND archived = 0
+       ORDER BY updated_at DESC LIMIT ?`
+    ).all(String(modelHash), limit);
+  }
+
+  /** True when any active row would be picked by needsEmbeddingFor(). */
+  function hasStaleEmbedding(modelHash) {
+    return needsEmbeddingFor(modelHash, 1).length > 0;
+  }
+
+  /** Per-model provenance counts over active rows ('' = unknown origin). */
+  function embeddingModelBreakdown() {
+    return db.prepare(
+      `SELECT COALESCE(embedding_model, '') AS model, count(*) AS c
+         FROM memories
+        WHERE embedding IS NOT NULL AND embedding != ''
+          AND forgotten = 0 AND archived = 0
+        GROUP BY COALESCE(embedding_model, '')`
+    ).all();
+  }
+
+  /**
+   * Per-dimension counts over active embedded rows ('' = vector that failed to
+   * parse as an array — legacy garbage rows, not a real dimension).
+   *
+   * Why per-dimension: embeddedCount() alone says "has a vector", but vectors
+   * written by a different model/dimension are not comparable with the current
+   * query embedding — searchVector skips them, so they are "present" without
+   * being "retrievable". The status card needs this split to stop reporting a
+   * coverage number that silently counts unsearchable rows.
+   */
+  function embeddingDimensionBreakdown() {
+    return db.prepare(
+      `SELECT id, embedding FROM memories
+        WHERE embedding IS NOT NULL AND embedding != ''
+          AND forgotten = 0 AND archived = 0`
+    ).all().reduce((acc, row) => {
+      let dim = "";
+      try {
+        const parsed = JSON.parse(row.embedding);
+        dim = Array.isArray(parsed) ? String(parsed.length) : "";
+      } catch { /* unparseable vector counts under "" */ }
+      acc.set(dim, (acc.get(dim) ?? 0) + 1);
+      return acc;
+    }, new Map());
+  }
+
   function search(query, { limit = 20, includeArchived = false } = {}) {
     const q = String(query).trim();
     if (!q) return [];
@@ -1718,6 +1857,11 @@ export function createStore(path) {
     for (const row of rows) {
       const v = getParsedEmbedding(row.id);
       if (!v) continue;
+      // distill-tx-embed-gap 顺带修：维度不匹配的行按维度分流，直接跳过。旧路径
+      // 喂进 cosine 不等长就 return 0，换了模型/维度的旧向量以 0 分混进结果尾部
+      // （threshold 默认 0 时照样入选），检索方拿到的分数是跨向量空间的假值。
+      // 不等长的向量对本次查询没有可比分数，跳过是唯一诚实的处置。
+      if (v.length !== vector.length) continue;
       const score = cosine(vector, v);
       if (score >= threshold) scored.push({ row: { id: row.id }, score });
     }
@@ -2538,6 +2682,66 @@ export function createStore(path) {
     return rows.map(toScopeChange);
   }
 
+  /**
+   * 政策轴（issue #471）：按下或松开一个作用域。一行一格，靠
+   * idx_scope_state_key(dimension, scope_value) 做 UPSERT——重复按下同一状态
+   * 不刷新 decided_at（CASE WHEN），因为「第一次按下的时刻」才是回执该报的东西；
+   * 状态翻转则刷新，那是一次真的决策。
+   *
+   * note 的取舍与 decided_at 相反：非空的新 note 总是覆盖旧的，空的则原样留着。
+   * 理由是这条记录里「当前通不通」由 state 那一列承担，note 是**理由**——理由被
+   * 一次不带理由的重按抹掉是净损失（用户回看时只会看到「按下过」却不知道为什么），
+   * 而「清空理由」不是一个真实需求（要改就再按一次带上新理由）。这与本仓防御段
+   * 「宁可留着也不要静默丢」的取向一致。
+   *
+   * 归一化失败（维度/值/状态任一非法）返回 undefined，由调用方拒绝——本表只存
+   * 可解释的三种枚举，与 memories 的 scope 列不同：那里脏输入落 NULL 是正当的
+   * （「未标注」本身有语义），这里落 NULL 没有任何意思，会静默变成一行永远不
+   * 生效的状态。
+   */
+  function setScopeState({ dimension, scope_value, state, note, decided_at }) {
+    const dim = normalizeScopeStateDimension(dimension);
+    const val = normalizeScopeStateValue(scope_value);
+    const st = normalizeScopeStateState(state);
+    if (!dim || !val || !st) return undefined;
+    const at = normalizeOccurredAt(decided_at) ?? nowIso();
+    const noteText = normalizeScopeText(note);
+    db.prepare(
+      `INSERT INTO scope_state (id, dimension, scope_value, state, note, decided_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(dimension, scope_value) DO UPDATE SET
+         state = excluded.state,
+         note = COALESCE(excluded.note, scope_state.note),
+         decided_at = CASE WHEN scope_state.state = excluded.state THEN scope_state.decided_at ELSE excluded.decided_at END`
+    ).run(randomUUID(), dim, val, st, noteText, at);
+    return toScopeState(
+      db.prepare("SELECT * FROM scope_state WHERE dimension = ? AND scope_value = ?").get(dim, val)
+    );
+  }
+
+  /** 政策轴状态行（单格）。 */
+  function getScopeState(dimension, scope_value) {
+    const dim = normalizeScopeStateDimension(dimension);
+    const val = normalizeScopeStateValue(scope_value);
+    if (!dim || !val) return undefined;
+    return toScopeState(
+      db.prepare("SELECT * FROM scope_state WHERE dimension = ? AND scope_value = ?").get(dim, val)
+    );
+  }
+
+  /**
+   * 政策轴状态行（全量）。不提供按维度/值过滤的参数——闸门判定要的就是全量
+   * （一次现读一次索引），过滤留到 scope-state.js 的 buildPausedIndex 里做。
+   * 排 decided_at DESC + rowid DESC 同 listScopeChanges（毫秒精度同毫秒写入
+   * 时 UUID 排序随机，回执要报「最近一次决策」就得有确定的次键）。
+   */
+  function listScopeStates({ state } = {}) {
+    const rows = state
+      ? db.prepare("SELECT * FROM scope_state WHERE state = ? ORDER BY decided_at DESC, rowid DESC").all(state)
+      : db.prepare("SELECT * FROM scope_state ORDER BY decided_at DESC, rowid DESC").all();
+    return rows.map(toScopeState);
+  }
+
   function getFailureStats({ since } = {}) {
     const clause = since ? "WHERE created_at >= ?" : "";
     const params = since ? [since] : [];
@@ -3159,6 +3363,10 @@ export function createStore(path) {
     getParsedEmbedding,
     embeddedCount,
     needsEmbedding,
+    needsEmbeddingFor,
+    hasStaleEmbedding,
+    embeddingModelBreakdown,
+    embeddingDimensionBreakdown,
     searchVector,
     saveDreamRun,
     lastDreamRunAt,
@@ -3207,6 +3415,11 @@ export function createStore(path) {
     countConflictPending,
     saveScopeChange,
     listScopeChanges,
+    // 政策轴（issue #471）：按下/松开一个作用域。纯 bookkeeping，不调
+    // incrementGeneration()——它不动任何记忆行，动它只会让所有缓存无谓失效。
+    setScopeState,
+    getScopeState,
+    listScopeStates,
     createEntity,
     findEntityByName,
     findEntityById,

package/src/summarize.js

@@ -514,8 +514,7 @@ export function createSummarizer(ctx, service, config, deps = {}) {
   const clearTimer = typeof deps.clearTimeoutFn === "function" ? deps.clearTimeoutFn : clearTimeout;
 
   // v0.9.0（M.O. 项目记忆）：蒸馏写入也要盖作用域章。此前只有 memory_save 那条工具
-  // 路径盖章（tools.js 的 memory_save 里 resolveSessionScope 到 workspaceLabel 那一段，
-  // 2026-10-13 在 :173-193），而机器提炼是写入量的绝大多数——于是「项目记忆」
+  // 路径盖章（tools.js 的 resolveSessionScope 盖章块，2026-10-14 在 :174-181），而机器提炼是写入量的绝大多数——于是「项目记忆」
   // 在库里根本不存在（全库带 scope 的行不足 3%，且带 scope 的全部来自工具路径）。
   // 这里不另造口径：同一把解析器（scope.js 的 createScopeResolver，2026-10-13 在 :24）、同一把闸门
   // （config.scopeEnabled === true）、同一对列（*_scope + *_scope_source='auto'），
@@ -888,7 +887,7 @@ export function createSummarizer(ctx, service, config, deps = {}) {
       // v0.9.0（M.O. 项目记忆）：一次窗口解析一次——同一蒸馏窗口里所有条目同属一个
       // 工作区、一个 agent 身份，逐条解析是白花钱。解析不到就落 NULL（NULL = 未标注 =
       // 全局可见），且解析器绝不抛错（scope.js 的硬约束：记忆写入不该被作用域拖挂）。
-      // 闸门与 tools.js 的 autoStamping（2026-10-13 在 :180）同一把：关着就一个字段都不加，老行为不变。
+      // 闸门与 tools.js 的 autoStamping（2026-10-14 在 :175）同一把：关着就一个字段都不加，老行为不变。
       const writeScope = config?.scopeEnabled === true
         ? resolveSessionScope({ agent: { session } })
         : null;

package/src/tools.js

@@ -7,6 +7,7 @@ import { matchesPlatform } from "./runtime/closure.js";
 import { verifyPayload } from "./runtime/verify.js";
 import { TOOL_GUIDE, CONTINUITY_TOOL_RULE } from "./guide.js";
 import { injectChildEnabled } from "./config.js";
+import { normalizeScopeStateDimension, normalizeScopeStateValue, normalizeScopeStateState } from "./scope-state.js";
 import { lastUserQuery } from "./inject.js";
 
 const TEXT_OUTPUT = (text) => [{ type: "text", text }];
@@ -500,6 +501,76 @@ export function createTools(ctx, service, config, embedder) {
       }
     }),
 
+    // #471：政策轴——作用域级可逆闸门。与 memory_forget/memory_archive 的分工：
+    // 那两个是事实轴的单条操作（改的是「这条记忆属于谁 / 还算不算数」，一条条来）；
+    // 本工具是政策轴的按作用域操作（改的是「这一路现在通不通」，跨会话存续、
+    // 松开即原样回来，一条记忆行都不动）。判断指引：整条工作线要临时静音用本工具；
+    // 单条记忆不该再被想起才用 memory_forget/memory_archive。
+    defineTool({
+      name: "set_scope_state",
+      description:
+        "Press or release the reversible scope gate for one scope (issue #471): while paused, that scope's memories stay stored and unchanged but are held back from injection and dream consolidation. " +
+        "This is not deletion and not forgetting — release with state=active and everything comes back exactly as it was, which is why it is the right tool for temporarily silencing a whole work stream rather than editing memories one by one. " +
+        "dimension is agent or workspace; scope_value is the label itself, or * for that dimension's global gate. " +
+        "Both switches (scopeState.enabled/enforce) are off by default, so setting a state has no effect on injection until the user turns them on in the panel.",
+      parameters: {
+        dimension: { type: "string", required: true, description: "Scope dimension to press: \"agent\" or \"workspace\"" },
+        scope_value: { type: "string", required: true, description: "The scope label, or \"*\" for that dimension's global gate" },
+        state: { type: "string", required: true, description: "\"paused\" presses the gate, \"active\" releases it" },
+        note: { type: "string", description: "Optional short reason, stored with the decision so the next reader knows why it was pressed" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            scope: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                dimension: { type: "string", required: true },
+                scope_value: { type: "string", required: true },
+                state: { type: "string", required: true },
+                // 理由要能读回来：不带它，下次读的人只知道「按下过」却不知道为什么。
+                // 这与库层 setScopeState 的 note 取舍是同一条理由——不带理由的重按
+                // 不抹掉旧理由，正是为了让这里读得回来。可选：从没写过就没有。
+                note: { type: "string" },
+                decided_at: { type: "string", required: true }
+              }
+            }
+          }
+        },
+        // 回执如实回显当前值（不是回显入参）：同一个状态重复按下时 decided_at 保持
+        // 首次值，回显它才看得出「这次没有真的改变什么」。
+        render: (_args, value) =>
+          TEXT_OUTPUT(
+            `Scope ${value.scope.dimension}:${value.scope.scope_value} is now ${value.scope.state} (decided at ${value.scope.decided_at}).`
+          )
+      },
+      async execute(args) {
+        const dimension = normalizeScopeStateDimension(args.dimension);
+        const scopeValue = normalizeScopeStateValue(args.scope_value);
+        const state = normalizeScopeStateState(args.state);
+        if (dimension === null) throw new Error("dimension must be \"agent\" or \"workspace\"");
+        if (scopeValue === null) throw new Error("scope_value must be a non-empty label or \"*\"");
+        if (state === null) throw new Error("state must be \"active\" or \"paused\"");
+        const row = service.setScopeState({ dimension, scope_value: scopeValue, state, note: args.note });
+        if (row === undefined) throw new Error("scope state could not be recorded");
+        return {
+          scope: {
+            dimension: row.dimension,
+            scope_value: row.scope_value,
+            state: row.state,
+            // 没写过理由时键整个不出现（而不是 note: undefined）：output schema 是
+            // 闭合的，DTO 矩阵会拿真实返回值过 validateJsonSchemaValue，留一个
+            // 值为 undefined 的键等于留个空壳。
+            ...(row.note === undefined ? {} : { note: row.note }),
+            decided_at: row.decided_at
+          }
+        };
+      }
+    }),
+
     // #230（#164 设计稿评审线）：document 型记忆注册——agent 产长文档的指针
     // 行铸造口。写入权分离：全文归 agent（管线对文件零读零写零改），库里只
     // 存摘要 + doc_path + evidence 三样；C2 比对去重、supersede 记账在