@sema-agent/server 7.13.0 → 7.14.0

package/USAGE.md

@@ -150,6 +150,27 @@ MODEL_CODE_ROLES=default,subagent     # 不设=全中立;仅这些角色在「
 - 经 `RoleSpec.systemPrompt` 挂在**角色**上，非开发角色保持中立、全局默认 `DEFAULT_SYSTEM_PROMPT` 不变；任务自带 `systemPrompt`(或客户端注入)时仍优先。
 - **验证门**（core 1.44，opt-in）：请求体带 `verify:true`(可选 `verifyRounds`，夹到 [1,5]、默认 2)→ 任务跑完后由**独立只读对抗 verifier**(`verifier` 角色，默认=主模型)证据强制地"试图 break 它"，FAIL 则把 findings 注回同 session 续跑修复→重验，循环到 PASS 或轮数上限。结果带 `verification:{verdict,rounds,findings,evidence}`（`verdict` 看质量，`result`/`status` 仍是实现的）。**仅 `/v1/tasks`(同步)与 `/v1/runs`(异步)**——`/v1/tasks/stream` 不支持(多轮非单流，请求 verify 会 400)。verifier 工具默认 = 实现任务工具滤掉 `effect:"write"`(只读边界)。`/metrics` 加 `verifications_total{verdict}`。
 - **记忆(design/138 文件记忆引擎,2026-07-08 起唯一记忆面)**:core 注入式文件引擎——任务开始时 materialize 记忆目录(`MEMORY_ENGINE_DIR`,默认 `~/.ai-agent`),模型用**普通文件技能**读写记忆(CC `# Memory` 指令 + 派生索引;无 remember/recall 工具),任务边界 harvest 门(secret/cap 扫描)提交。单用户默认开,`MEMORY_ENGINE=off` 显式关;多租户恒关(文件基座无租户隔离,fail-closed)。旧 SQL 记忆面(`MEMORY_BACKEND`/`EMBEDDING_*`/`MEMORY_READ_LIMIT`/去重/向量检索、`GET/DELETE /v1/memory` 与 session memory 写 verb)已退役,数据不迁移——升级后对库跑一次 `scripts/drop-memory-tables.sql`。`body.memoryWrite:false` 仍是每请求只读开关(harvest 不提交)。
+  **`MEMORY_PERSISTENCE_CAPABLE`(三态,7.14.0 起)**=**部署自述**「本机能不能把用户的『记住 X』落到持久处」,与请求键 `memoryWrite` 两轴正交(后者收紧本次运行,前者是 operator 声明;任一取否即只读方向)。缺省不设=引擎按 roster 自行推断;`true`=本部署有推断看不见的持久通道(自定义 writer / 记忆 MCP / 远程执行车道与记忆根共享挂载);`false`=强制只读披露并关掉文件工具往记忆根的写通道。不认得的词拒启。
+  🔴 **`false` 自 core 5.27.0(7.14.0 提货)起还多一层——但只在 file 记忆引擎上**(`MEMORY_ENGINE_BACKEND` 未设 = 默认单机形):该会话是**受限会话**——materialize/搜索/harvest 一律按**已提交账**供给,记忆根下无事务背书的磁盘分歧既不收编也不供给,而是留盘 + 响亮点名(`restricted_divergence`,本服务把它计进 `memory_harvest_rejections_total{code}` 并 warn 一条),等下一次**非受限**会话走正常门收编。合法流程不受影响:用户手改、`git pull` 落下的删除照旧(延后,不销毁),并发的可写会话提交的变更算有事务背书。
+  ⚠️ **`MEMORY_ENGINE_BACKEND=pg|tidb` 上没有这一层**(引擎的受限视图是 file 后端的实装):那两条腿的读侧本来就走库、盘上目录只是每任务的投影工作区,不存在「读磁盘即收编」的通道,所以也无洞可堵——`false` 在它们上仍然照常买到披露、写门与零收编 harvest 三件(与后端无关)。
+  ⚠️ **口径别混**:「受限」是**会话级的这一个声明**;请求键 `memoryWrite:false` 铸出的只读**平面**(以及 org 层默认只读、双根非写面)**保持原样的 adopt-on-read**——它只是不 harvest,照旧看得见盘上的新内容。
+  ⚠️ **core 5.26.0 起,remote 执行车道上的 `# Memory` 写指令被撤**(沙箱手带够不着 host 记忆根;读与注入不变)。只有显式 `MEMORY_ENGINE_REMOTE_LANE=allow` 的部署会被打到——若该车道确实与记忆根共享挂载,`MEMORY_PERSISTENCE_CAPABLE=true` 是官方恢复路径(启动日志会点名这一条)。
+  另:记忆**没有写工具**,模型是用普通文件工具往记忆根写的——所以记忆根必须落在任务的 fs 授权边界内。结构性够不着时启动会 warn 并给出三条改法(`MEMORY_ENGINE_DIR` 挪进 workspace / 经 `additionalDirectories` 授权 / 声明 `MEMORY_PERSISTENCE_CAPABLE=false` 让披露诚实)。
+- **记忆检索的向量面(embedder,7.14.0 起)**:记忆检索有三档——`lexical`(词面 jaccard)/ `portable`(库内存向量,进程内算余弦)/ `native`(库侧向量算子)。⚠️ **没有档位旋钮**:档位是「记忆后端上限 × embedder 在不在场」**推断**出来的结果(显式选档只会造出「选了 native 却没 embedder」这类矛盾态)。**配上 embedder = 唯一的开法**,而且只在 `MEMORY_ENGINE_BACKEND=pg` 上有意义(tidb 记忆后端 v1 是词面档,file 引擎没有 embedder 接缝——两者配了 `MEMORY_EMBEDDER_*` 一律**拒启**点名)。不配 = 保持 `lexical`(默认姿态,零 warn)。
+
+  | env | 缺省 | 说明 |
+  |---|---|---|
+  | `MEMORY_EMBEDDER_ENDPOINT` | 缺省 | OpenAI 兼容服务的**基址**(`https://host/v1`)或**完整**端点(`https://host/v1/embeddings`),两种写法都收(query 原样保留,Azure 形可用)。必须是 http(s) 合法 URL 且**不得带 `user:pass@` 凭据**(会被传输层错误/日志/记忆冲突文案反复复制;要 auth 走下面的 API_KEY),否则拒启 |
+  | `MEMORY_EMBEDDER_MODEL` | 缺省 | 模型名,原样进请求体 `{model, input}` |
+  | `MEMORY_EMBEDDER_DIM` | 缺省 | 声明维度(**正整数**,如 `1024`)。必须与模型真实维度一致 |
+  | `MEMORY_EMBEDDER_TIMEOUT_MS` | `30000`(`[1000, 300000]`) | 单次 embed 的活性上限。挂死的端点会把整条记忆写入路径吊住 |
+  | `MEMORY_EMBEDDER_API_KEY` | 缺省 | 可选 Bearer(自托管 TEI/vllm/ollama 通常不需要;公有云端点需要) |
+
+  ⚠️ **半配 = 拒启**:上表前三键是一个整体,少任何一件都启动报错并**点名缺哪几键**。静默忽略的后果不是「功能缺席」而是「operator 以为向量面开着」——检索照常出结果(词面档),差异只在答案质量里,零日志。同理:只配 `TIMEOUT`/`API_KEY` 而三键不全、或 `MEMORY_ENGINE=off` 却配了 embedder,都是死旋钮,一律拒启。
+  ⚠️ **维度守卫是拒启/抛错,不是 warn**:向量列写错维度是**静默毒库**——本仓 pg 记忆表的 embedding 列是 `jsonb`(无维度约束),错长度向量既不会让 DB 报错,也不会让检索报错(那些行只是悄悄退回词面档)。所以坏 `DIM`(非正整数)启动即拒;运行期端点返回的向量长度与 `DIM` 不符,embedder **直接抛错**,绝不截断/补零。换模型/换维度前先清空 `agent_memory_engine_entry.embedding`(旧维度的向量不会被自动重算,只会一直退回词面档)。
+  ⚠️ **embedder 出故障的方向**:端点 5xx/超时会让当次记忆**写入**报一条 `io error: …` 冲突(不写坏向量),检索腿则退回词面档继续服务——即「坏了退回 lexical」,不是「坏了写坏数据」。故障有专门信号:metric `memory_embed_failed_total{backend}` + 日志 `memory_embedder_failed`(只看 PatchReport 里的冲突会把供应商故障误读成并发改动)。
+  ⚠️ **只对新写入的条目生效(没有回填腿)**:开启前就存在的记忆条目 embedding 列是空的,只有被再次写入时才会补上向量;这些行在检索里按词面档参与排序(不会被丢掉,但也享受不到向量档)。要立刻全量生效,得自己重写一遍语料。**同维度换模型是最危险的一种改法**:旧向量长度照样过门,却与新查询向量不在同一空间,排序变噪音而没有任何一层报错——本仓不存向量指纹(那要加列),所以换模型/换维度前**先清空** `agent_memory_engine_entry.embedding`。
+  📋 **档位对运维可见**:启动日志 `memory_engine_enabled` 行带 `vectorMode` 字段(取自后端实例的真值,不是配置推断)——`lexical` 在跑就必须看得见;配了 embedder 时同行还带 `embedderModel`/`embedderDim`,换模型这件事在日志里留痕。
 - **org 记忆准入(design/170 件A,7.0.0 起 BREAKING)**:`org:*` 记忆 scope 分**两个来源**——部署自证
   (env `MEMORY_SCOPE` 的 org 形 + **单用户部署**的 `projects[].defaultScopes` org 键)直通;**多租户**
   部署里由调用方 `projectId` 选中的登记簿 org 键算 **request 来源**,必须拿到授权目录的逐 principal

package/dist/boot/coordinators.js

@@ -24,7 +24,8 @@ export function createLiveCoordinators(ctx) {
     // seam (1.290 sync-ask leg). Present ⇒ a policy `ask` on a LIVE streaming leg becomes a `tool_approval` frame the
     // shell renders as the CC three-choice card, answered via POST /v1/tool-approvals/:id/respond.
     // [1535] 正名(旧文「background/workflow ⇒ headless auto-deny stands」已过时):宿主 sync 腿现同时装
-    // `spec.onAsk = boundAsk(ctx)`(server.ts 装配点)——core 继承链把闭包冻给委派子代,**bg/嵌套子代的
+    // `spec.onAsk = boundAsk(ctx)`(装配点在 `http/routes/tasks.ts`,design/158 A9 从 server.ts 拆出后
+    // 的全树唯一装配点)——core 继承链把闭包冻给委派子代,**bg/嵌套子代的
     // ask 浮到宿主 live 流**(带 sourceTaskId);真正无宿主流的腿(durable-submit/headless resume)才留
     // 「unavailable → durable park;无 park 设施 core fail-closed deny」。durable 部署 G1 语义不变。
     // [1.294 G1] durable 姿势必须在 runnerDeps 字面量之前可判(onAsk 的「在场性」本身就是 core suspendAsk 的

package/dist/boot/memory-boundary.d.ts

@@ -0,0 +1,84 @@
+/**
+ * #214 记忆边界不变式(板 [3492]② 立案,[3521] 裁1 与 core #151 同窗)—— 启动期把「结构性写不进的记忆
+ * 部署形」说出来。
+ *
+ * 病根(test 仓 [3479] 实测,[3490]② 定位):core 的记忆工具面是 `memory_search`/`memory_get` 两只**只读**
+ * 工具;**写**记忆没有专用工具 —— 模型用 fs 工具往记忆根写文件,harvest 再从那里收编。于是整条链的成立
+ * 条件是「记忆根落在该次任务的 fs 授权边界之内」。server 把根交给 core(`RunnerDeps.memoryEngineDir`)
+ * 之后,没有任何一处保证这一点,也没有任何一处说过「这台部署的记忆写面够不着」。默认根是
+ * `~/.ai-agent`(或 `AGENT_DATA_DIR`),默认围栏是任务 cwd —— 两者天然不相交:用户说「记住 X」,模型照
+ * 提示词去 Write,拿回一个 `path_not_in_root`,而回执早就发出去了。
+ *
+ * 判据形态 = **纯函数 + 启动 warn,不拒启**。理由是诚实:共享挂载 / bind mount / operator 自己把根塞进
+ * `additionalDirectories`,都是真实可行的部署形,而我方在 boot 期看不全。看得全的是「按我们自己接的线,
+ * 这条链**结构上**走不通」——那句必须说出来。围栏根算不出来时**不说话**(判不了就闭嘴,别把猜测当告警)。
+ *
+ * ⚠️ 这不是 fail-open 的托词:真正的 fail-closed 归属面在别处(多租户记忆整体 dark、remote lane 默认 dark)。
+ * 本模块判的是「已经决定要开记忆」之后的**可达性**,而可达性的证据一半在部署环境里,不在进程里。
+ *
+ * ── 指路:声明 `false` 之后引擎那边发生什么(core 5.27.0,[3612] F2;#231 提货批)────────────────────
+ * 本模块两条 warn 的收尾句都在劝 operator 表态(`MEMORY_PERSISTENCE_CAPABLE=true|false`)。表 `false`
+ * 之后的语义自 core 5.27.0 起**不止是披露**:该会话成为**受限会话** —— materialize/search/harvest 按
+ * 已提交账(ledger + shadow)供给,磁盘上无事务背书的分歧既不收编也不供给,而是留盘 + 响亮点名
+ * (`restricted_divergence`,`HarvestRejectionCode` 新成员;server 侧把它计进
+ * `memory_harvest_rejections_total{code}` + 一条 warn,见 `boot/runner-deps.ts` 的 harvest 报告站点),
+ * 等下一次非受限会话走正常门收编。
+ * ⚠️ **这一层只在 file 记忆引擎上**(受限视图 = `FileMemoryEngineBackend` 的实装,`materialize` 取它是
+ * `?? this.backend` 的可选 seam):`MEMORY_ENGINE_BACKEND=pg|tidb` 的两条腿读侧走库、盘上只是每任务投影,
+ * 没有「读磁盘即收编」的通道,`false` 在它们上仍买到披露/写门/零收编 harvest 三件。
+ * ⚠️ **口径别混**:受限 = **会话级 verdict 单键**(declared-false 那一个键);`writeScope:null` 的只读
+ * **平面**(请求键 `memoryWrite:false` 的 per-run 暂停 / org 层默认只读 / 双根非写面)**保持 adopt-on-read
+ * 原样**。受限是会话的**声明**,永远不是平面的**结构**。
+ *
+ * ── 本仓的 `adoptionRestricted` 消费位:**没有**(记档,免下次重找)──────────────────────────────────
+ * core 5.27.0 同批 additive 两件:`MemoryEngine.materialize` 第三参 `opts?.adoptionRestricted` 与
+ * `MemorySessionHandle.adoptionRestricted` 读面。本仓**两件都不碰**,而且是结构性的:记忆引擎由 core 的
+ * runner 自己驱动(我方只交 `RunnerDeps.memoryBackend` / `memoryEngineDir`),`grep -rn "\.materialize("
+ * src test` 零命中 ⇒ 没有调用点可以传第三参,也没有 handle 可读。受限判据因此**只能**从
+ * `TaskSpec.memoryPersistenceCapable` 一条路进去(`boot/resolve-spec.ts` 直通),我方显式**不铸**受限会话、
+ * 也**不投**这个读面(硬造一个消费点 = 造给自己看的 wire 键)。哪天真要在诊断面露它,先有消费方需求。
+ */
+/** boot 期可知的全部事实。每一位都必须由调用点从真配置/真装配结果取,禁在本模块内重算(重算=第二真源)。 */
+export interface MemoryWriteBoundaryFacts {
+    /** 记忆引擎的根(`memoryEngine.root`)。`undefined` = 引擎未接 ⇒ 本判据整体不适用。 */
+    memoryRoot: string | undefined;
+    /** 执行车道名,只进文案(`config.remoteExec?.provider ?? "in-process"`)。 */
+    lane: string;
+    /** 该车道的文件工具是否跑在**本机** fs 上(in-process / `REMOTE_EXEC=host`)。false = 沙箱盘,与记忆根分平面。
+     *  ⚠️ 这一位管的是**文件平面**,与下面的 `coreRemoteExecutionEnv` 是**两根轴**,别合并(codex round2
+     *  [medium] 就是把它们当成一根轴的后果):`host` 车道的文件平面就是本机(这一位 true),但 core 眼里它
+     *  仍是 remote(那一位也 true)。 */
+    hostSemanticsLane: boolean;
+    /** core 的 `isRemoteExecutionEnv` 对本部署执行环境的判决 —— 判别位 = `REMOTE_EXEC` 有没有设(**含
+     *  `host`**:core 的判别是鸭子类型,`remote-env-host.ts` 把那几件全实现了,亲验坐实)。
+     *  5.26.0 的 r13/r14 收窄按的是**这一位**,不是文件平面:凡 core 判 remote,`# Memory` 写指令一律撤,
+     *  除非声明 `memoryPersistenceCapable: true`。 */
+    coreRemoteExecutionEnv: boolean;
+    /** 部署声明 `MEMORY_PERSISTENCE_CAPABLE`(三态)。两极都让本模块闭嘴,但理由不同 —— 见各臂注释。 */
+    declaredCapable: boolean | undefined;
+    /** boot 期算得出的文件工具围栏根。空数组 = 算不出(每任务临时目录 / 未配 workspace)⇒ 不判。 */
+    containmentRoots: readonly string[];
+}
+/** 一条启动告警:`tag` 进日志事件名(可被运维按名过滤/告警),`detail` 是给人读的整句(含恢复路径)。 */
+export interface MemoryWriteBoundaryWarning {
+    tag: "memory_root_outside_write_boundary" | "memory_remote_lane_write_instruction_dropped";
+    detail: string;
+}
+/**
+ * 判两件事,互斥(remote 上不叠 host 的围栏话 —— 围栏根本不在这台机器上,说了是噪音):
+ *
+ * ① **remote 车道**(只可能因为 `MEMORY_ENGINE_REMOTE_LANE=allow` 才在这里还有引擎):core 5.26.0 的
+ *    r13/r14 收窄把 `# Memory` 写指令在 remote executionEnv 上撤了(沙箱手带够不着 host 记忆根),
+ *    官方恢复路径是声明 `memoryPersistenceCapable: true`。未声明 ⇒ 点名 warn,把恢复旋钮写进句子里。
+ * ② **host 车道**:记忆根不在任何一个已知围栏根内 ⇒ 模型被教着往一个 fs 工具够不到的路径写。
+ *
+ * 两极声明都让本模块闭嘴,但理由不同,别合并:
+ *  · `true` = operator 自证有推断看不见的持久通道(共享挂载 / 自定义 writer),我们的结构判断本就不该
+ *    压过部署方对自己环境的声明;
+ *  · `false` = operator 已经承认「本机存不下」,引擎据此改口披露只读 —— 再 warn 一次是把已知情的事
+ *    当新闻报。
+ */
+export declare function buildMemoryWriteBoundaryAudit(facts: MemoryWriteBoundaryFacts): {
+    warnings: MemoryWriteBoundaryWarning[];
+};
+//# sourceMappingURL=memory-boundary.d.ts.map

package/dist/boot/memory-boundary.js

@@ -0,0 +1,110 @@
+/**
+ * #214 记忆边界不变式(板 [3492]② 立案,[3521] 裁1 与 core #151 同窗)—— 启动期把「结构性写不进的记忆
+ * 部署形」说出来。
+ *
+ * 病根(test 仓 [3479] 实测,[3490]② 定位):core 的记忆工具面是 `memory_search`/`memory_get` 两只**只读**
+ * 工具;**写**记忆没有专用工具 —— 模型用 fs 工具往记忆根写文件,harvest 再从那里收编。于是整条链的成立
+ * 条件是「记忆根落在该次任务的 fs 授权边界之内」。server 把根交给 core(`RunnerDeps.memoryEngineDir`)
+ * 之后,没有任何一处保证这一点,也没有任何一处说过「这台部署的记忆写面够不着」。默认根是
+ * `~/.ai-agent`(或 `AGENT_DATA_DIR`),默认围栏是任务 cwd —— 两者天然不相交:用户说「记住 X」,模型照
+ * 提示词去 Write,拿回一个 `path_not_in_root`,而回执早就发出去了。
+ *
+ * 判据形态 = **纯函数 + 启动 warn,不拒启**。理由是诚实:共享挂载 / bind mount / operator 自己把根塞进
+ * `additionalDirectories`,都是真实可行的部署形,而我方在 boot 期看不全。看得全的是「按我们自己接的线,
+ * 这条链**结构上**走不通」——那句必须说出来。围栏根算不出来时**不说话**(判不了就闭嘴,别把猜测当告警)。
+ *
+ * ⚠️ 这不是 fail-open 的托词:真正的 fail-closed 归属面在别处(多租户记忆整体 dark、remote lane 默认 dark)。
+ * 本模块判的是「已经决定要开记忆」之后的**可达性**,而可达性的证据一半在部署环境里,不在进程里。
+ *
+ * ── 指路:声明 `false` 之后引擎那边发生什么(core 5.27.0,[3612] F2;#231 提货批)────────────────────
+ * 本模块两条 warn 的收尾句都在劝 operator 表态(`MEMORY_PERSISTENCE_CAPABLE=true|false`)。表 `false`
+ * 之后的语义自 core 5.27.0 起**不止是披露**:该会话成为**受限会话** —— materialize/search/harvest 按
+ * 已提交账(ledger + shadow)供给,磁盘上无事务背书的分歧既不收编也不供给,而是留盘 + 响亮点名
+ * (`restricted_divergence`,`HarvestRejectionCode` 新成员;server 侧把它计进
+ * `memory_harvest_rejections_total{code}` + 一条 warn,见 `boot/runner-deps.ts` 的 harvest 报告站点),
+ * 等下一次非受限会话走正常门收编。
+ * ⚠️ **这一层只在 file 记忆引擎上**(受限视图 = `FileMemoryEngineBackend` 的实装,`materialize` 取它是
+ * `?? this.backend` 的可选 seam):`MEMORY_ENGINE_BACKEND=pg|tidb` 的两条腿读侧走库、盘上只是每任务投影,
+ * 没有「读磁盘即收编」的通道,`false` 在它们上仍买到披露/写门/零收编 harvest 三件。
+ * ⚠️ **口径别混**:受限 = **会话级 verdict 单键**(declared-false 那一个键);`writeScope:null` 的只读
+ * **平面**(请求键 `memoryWrite:false` 的 per-run 暂停 / org 层默认只读 / 双根非写面)**保持 adopt-on-read
+ * 原样**。受限是会话的**声明**,永远不是平面的**结构**。
+ *
+ * ── 本仓的 `adoptionRestricted` 消费位:**没有**(记档,免下次重找)──────────────────────────────────
+ * core 5.27.0 同批 additive 两件:`MemoryEngine.materialize` 第三参 `opts?.adoptionRestricted` 与
+ * `MemorySessionHandle.adoptionRestricted` 读面。本仓**两件都不碰**,而且是结构性的:记忆引擎由 core 的
+ * runner 自己驱动(我方只交 `RunnerDeps.memoryBackend` / `memoryEngineDir`),`grep -rn "\.materialize("
+ * src test` 零命中 ⇒ 没有调用点可以传第三参,也没有 handle 可读。受限判据因此**只能**从
+ * `TaskSpec.memoryPersistenceCapable` 一条路进去(`boot/resolve-spec.ts` 直通),我方显式**不铸**受限会话、
+ * 也**不投**这个读面(硬造一个消费点 = 造给自己看的 wire 键)。哪天真要在诊断面露它,先有消费方需求。
+ */
+import { resolve } from "node:path";
+/** 词法包含判定:`child` 是否落在 `root` 之内(含相等)。纯词法,不碰 fs —— boot 期这些路径可能还没被
+ *  创建,而 `realpath` 会把「同一棵树的两种写法」这个我们**不想**放过的差别悄悄抹平。
+ *  先过 `resolve` 折掉 `.`/`..`/重复分隔符(codex 复审:`/srv/ws/../mem` 不该被读成落在 `/srv/ws` 里),
+ *  再按 `root + "/"` 前缀判,所以 `/srv/workspace-2` 不会被 `/srv/workspace` 吃掉。 */
+function isInside(child, root) {
+    const c = resolve(child);
+    const r = resolve(root);
+    return c === r || c.startsWith(r === "/" ? "/" : `${r}/`);
+}
+/**
+ * 判两件事,互斥(remote 上不叠 host 的围栏话 —— 围栏根本不在这台机器上,说了是噪音):
+ *
+ * ① **remote 车道**(只可能因为 `MEMORY_ENGINE_REMOTE_LANE=allow` 才在这里还有引擎):core 5.26.0 的
+ *    r13/r14 收窄把 `# Memory` 写指令在 remote executionEnv 上撤了(沙箱手带够不着 host 记忆根),
+ *    官方恢复路径是声明 `memoryPersistenceCapable: true`。未声明 ⇒ 点名 warn,把恢复旋钮写进句子里。
+ * ② **host 车道**:记忆根不在任何一个已知围栏根内 ⇒ 模型被教着往一个 fs 工具够不到的路径写。
+ *
+ * 两极声明都让本模块闭嘴,但理由不同,别合并:
+ *  · `true` = operator 自证有推断看不见的持久通道(共享挂载 / 自定义 writer),我们的结构判断本就不该
+ *    压过部署方对自己环境的声明;
+ *  · `false` = operator 已经承认「本机存不下」,引擎据此改口披露只读 —— 再 warn 一次是把已知情的事
+ *    当新闻报。
+ */
+export function buildMemoryWriteBoundaryAudit(facts) {
+    const { memoryRoot, lane, hostSemanticsLane, coreRemoteExecutionEnv, declaredCapable, containmentRoots } = facts;
+    if (memoryRoot === undefined)
+        return { warnings: [] }; // 引擎未接
+    if (declaredCapable !== undefined)
+        return { warnings: [] }; // 部署已表态(两极,理由见头注)
+    // ① 写指令被撤 —— 判据是 **core 的 remote 判决**,不是文件平面(codex round2 [medium],已核真:
+    // `REMOTE_EXEC=host` 的文件平面是本机,但 core 照样判它 remote 并撤掉写指令。按文件平面分腿会让
+    // 这一形整个静默 —— 恰恰是最容易被忽略的那台机器:记忆看着是开的,写指令没了,没人说过一句)。
+    if (coreRemoteExecutionEnv) {
+        const plane = hostSemanticsLane
+            ? `the model's file tools DO run on this worker's filesystem, but core classifies this execution environment as ` +
+                `remote (it exposes the remote-env surface), so the instruction is withheld anyway`
+            : `the model's file tools write the SANDBOX filesystem while the memory root (${memoryRoot}) lives on this worker`;
+        return {
+            warnings: [
+                {
+                    tag: "memory_remote_lane_write_instruction_dropped",
+                    detail: `the memory engine is wired over the "${lane}" execution lane and ${plane}. ` +
+                        `Since core 5.26.0 the "# Memory" WRITE instruction is withheld on a remote execution environment, so this ` +
+                        `deployment reads memory but no longer teaches the model how to save into it. If this lane genuinely reaches ` +
+                        `the memory root, declare it: MEMORY_PERSISTENCE_CAPABLE=true restores the write instruction. If it does not, ` +
+                        `MEMORY_PERSISTENCE_CAPABLE=false makes the read-only state explicit to the model instead of leaving it silent.`,
+                },
+            ],
+        };
+    }
+    if (containmentRoots.length === 0)
+        return { warnings: [] }; // 围栏根算不出 ⇒ 不判(见头注)
+    if (containmentRoots.some((root) => isInside(memoryRoot, root)))
+        return { warnings: [] };
+    return {
+        warnings: [
+            {
+                tag: "memory_root_outside_write_boundary",
+                detail: `the memory engine root (${memoryRoot}) is outside every file-tool containment root known at boot ` +
+                    `(${containmentRoots.join(", ")}). Memory has no write TOOL — the model saves by writing files into that root — ` +
+                    `so a "remember this" turn will be answered with a save the file tools structurally refuse (path_not_in_root). ` +
+                    `Fix it in one of three ways: point MEMORY_ENGINE_DIR at a path under the workspace, hand the root to tasks via ` +
+                    `additionalDirectories, or declare MEMORY_PERSISTENCE_CAPABLE=false so the model is told up front that this ` +
+                    `deployment cannot save instead of receipting a write that never lands.`,
+            },
+        ],
+    };
+}
+//# sourceMappingURL=memory-boundary.js.map

package/dist/boot/resolve-spec.js

@@ -26,6 +26,7 @@ import { SessionEnvironmentSelection, selectEnvironmentTool } from "../capabilit
 import { sendUserFileTool } from "../capabilities/send-user-file-tool.js";
 import { gateScenarioRequest, mergeUserSkills, selectScenario } from "../capabilities/scenarios.js";
 import { toolPolicyForHands } from "../capabilities/hands-lane.js";
+import { shouldDiscloseNoPersistentMemory, withNoPersistentMemoryNotice } from "../capabilities/memory-notice.js";
 import { applyLongtailDefer } from "../capabilities/tool-defer.js";
 import { assertGuardPatternsUsable, buildOnlySensitiveBaselineWarning, createApprovalBaselinePolicy, createDeploymentGovernanceInputs } from "../deployment-governance.js";
 import { acceptShellScratchpadDir, buildEnvFacts, egressForRemoteExec, ensureScratchpadDir, resumeFactsForLane } from "../env-facts.js";
@@ -741,6 +742,18 @@ export function createResolveSpec(ctx) {
             // 件A origin 盖章(#148 件3④):部署形态维随 requirePrincipal——多租户下登记簿种子(projectId
             // 选定)按 request 盖章走 core 准入门,单用户一律 deployment(v4 §1 N2;零 org 键=整键缺席零迁移)。
             memory: memoryEngine ? memorySpecForRequest(auth?.memoryScope, body.memoryWrite, s4DefaultScopes, { multiTenant: config.requirePrincipal === true }) : undefined,
+            // #217(core 5.26.0 提货):部署对「本机能不能把用户的『记住 X』落到持久处」的自我声明,env
+            // `MEMORY_PERSISTENCE_CAPABLE` 三态直通。**部署面旋钮,不开请求键**——恢复 remote lane 的
+            // `# Memory` 写指令是「这条执行车道与记忆根共享挂载」这个部署事实,归 operator 不归调用方表态
+            // (operator-knob 律:部署级旋钮禁挂客户端表态派生腿)。与请求键 `memoryWrite` 两轴正交:后者是
+            // per-run 收紧(writeScope:null),前者是部署声明;任一取否方向即只读方向,客户端永远撑不开
+            // 部署声明的 `false`(core 自己也把 declared false 当 FLOOR:委派转发 tighten-only)。
+            // 三态的 absent 腿 = **整键缺席**(core:「absent = 各自推断」),所以走条件展开而不是赋 undefined。
+            // 🔴 core 5.27.0([3612] F2)起,`false` 还让这次会话成为**受限会话**:按已提交账供给,磁盘上
+            // 无事务背书的分歧不收编不供给(留盘 + `restricted_divergence` 点名)。**受限是会话级的这一个键**,
+            // 与上面 `memoryWrite:false` 铸出的 `writeScope:null` **只读平面**不是一回事 —— 那条平面照旧
+            // adopt-on-read(暂停的只是 harvest)。两轴各自的完整口径见 `config-types.ts` 的字段注。
+            ...(config.memoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: config.memoryPersistenceCapable } : {}),
             // Scenario-provided capabilities (e.g. code-review = repo tools + reviewer subagents + prompt).
             // RFC A2: the SelectEnvironment tool rides after the scenario's tools (spec.tools is ADDITIVE to core's
             // built-in roster — prepare-task mounts first-party tools separately). Only when the image chain is live.
@@ -1066,6 +1079,24 @@ export function createResolveSpec(ctx) {
         if (governed.handsReadOnly === true && Array.isArray(governed.tools)) {
             governed = { ...governed, tools: stripDelegationTools(governed.tools) };
         }
+        // #217(core 5.26.0 提货,板 [3499]②/[3521]④ 两次点名的 server 接线半场):零记忆面部署形把 core 的
+        // `NO_PERSISTENT_MEMORY_NOTICE` 组进 system prompt(core 导出但**不注入** —— 「组装归宿主」,同
+        // MEMORY_SAFETY 姿势)。判别式与 provider 分腿装配的全部理由在 capabilities/memory-notice.ts。
+        // 🔴 位置即契约:必须在 governance+settings 折完之后 —— `handsReadOnly` 是判别式的一位输入,而它可能
+        // 由 autonomy(governance 拍)或 permissionMode:plan(settings 拍)才被点亮;在阶段④判会漏掉这两条腿。
+        if (shouldDiscloseNoPersistentMemory({
+            memory: governed.memory,
+            declaredCapable: config.memoryPersistenceCapable,
+            hands: gated.hands,
+            handsReadOnly: governed.handsReadOnly === true,
+            excludeTools: governed.excludeTools,
+            // core 的 `isRemoteExecutionEnv` 是鸭子类型判别,我方**所有** `REMOTE_EXEC` 车道(含 `host` ——
+            // remote-env-host.ts 实现了 suspendVM/workspaceHandle/execStream,亲验)都满足它。判别位因此是
+            // 「provider 有没有设」;未设 = in-process(core 拿 StubExecutionEnv,非 remote)。
+            remoteExecutionEnv: config.remoteExec !== undefined,
+        })) {
+            governed = { ...governed, promptProvider: withNoPersistentMemoryNotice(governed.promptProvider) };
+        }
         return { governed, scratchpadDir, hostSemanticsLane };
     };
     /** 阶段⑥(image·envFacts·router):吃 阶段⑤的 governed + scratchpadDir/hostSemanticsLane + 场景名,吐**最终**

package/dist/boot/runner-deps.js

@@ -253,6 +253,13 @@ export function createRunnerDeps(ctx) {
         //  有写路径),这条是纯文档只读面,共享内容永不进注入块/索引、永不落模型可写盘、永不被 harvest。)
         // S3-TOB 复审 F-9(operator 可观测底座):harvest 报告 → metrics(拒收/incident/patch 计数从此可见;
         // core swallow-guard 保证 throwing consumer 不伤边界)。
+        // #231(core 5.27.0 提货,codex 复审 [medium] 验真后修):**拒收码进遥测**。此前本站点只读
+        // `ok`/`incident`/`patches` 三件,而受限会话(`memoryPersistenceCapable:false`)对磁盘分歧的处置
+        // 走的是 `report.inboundFindings`(`ok` 仍是 true、`incident` 缺席)⇒ core 承诺的「响亮点名」在
+        // 我方这一侧**一条日志一个计数都没有**:运维看不到本机上有多少字节因为受限而没被收编。逐 code
+        // 计数(词表是 core 的 `HarvestRejectionCode` 闭集,基数天然有界)+ 一条 warn。
+        // ⚠️ **不打路径**:记忆根下的文件名是用户内容(core 已把逐条 reason 通告给模型那一侧),运维面
+        // 只需要「哪一类、多少条」。计数用 `??` 兜住旧引擎缺席的两个数组(additive 字段,不是 fail-open 分支)。
         onMemoryHarvestReport: memoryEngine
             ? (report, info) => {
                 metrics.inc("memory_harvest_total", { ok: String(report.ok), phase: info.phase, incident: report.incident?.kind ?? "none" });
@@ -260,6 +267,18 @@ export function createRunnerDeps(ctx) {
                     metrics.inc("memory_harvest_patches_total", { phase: info.phase }, (report.patches.add ?? 0) + (report.patches.update ?? 0));
                 if (report.incident)
                     logger.warn("memory_harvest_incident", { kind: report.incident.kind, phase: info.phase });
+                const byCode = new Map();
+                for (const r of [...(report.rejections ?? []), ...(report.inboundFindings ?? [])])
+                    byCode.set(r.code, (byCode.get(r.code) ?? 0) + 1);
+                for (const [code, count] of byCode)
+                    metrics.inc("memory_harvest_rejections_total", { phase: info.phase, code }, count);
+                if (byCode.size > 0) {
+                    logger.warn("memory_harvest_rejections", {
+                        phase: info.phase,
+                        // 逐 code 计数(排序固定,便于日志 diff);内容/路径一律不进这条线。
+                        codes: [...byCode].sort(([a], [b]) => (a < b ? -1 : 1)).map(([code, count]) => `${code}=${count}`).join(","),
+                    });
+                }
                 // 142-S2.5-W1: 成功 harvest 真有 patch 落地 = 本地记忆变了 ⇒ fire-and-forget 一轮同步
                 // (trigger 自带 inflight 节流:上一轮在飞则跳过,漏掉的变更下一轮全量补上)。
                 if (memorySyncRunner && report.ok && (report.patches?.add ?? 0) + (report.patches?.update ?? 0) > 0)

package/dist/boot/stores.js

@@ -15,6 +15,7 @@
 import { join } from "node:path";
 import { FileBackgroundAgentStore, FileMailboxStore, FileRosterStore, FileUsageWindowStore, InMemoryUsageWindowStore } from "@sema-agent/core";
 import { createMemorySyncRunner, createMemorySyncTransport } from "../memory-sync-client.js";
+import { memoryEmbedderFor } from "../plugins/memory-embedder.js";
 import { PgMemoryEngineBackend, ensurePgMemoryEngineSchema } from "../plugins/memory-engine-pg.js";
 import { TiDBMemoryEngineBackend, ensureTiDBMemoryEngineSchema } from "../plugins/memory-engine-tidb.js";
 import { PgMemoryHistoryStore, PgMemorySyncStore, ensurePgMemoryHistorySchema, ensurePgMemorySyncSchema } from "../plugins/memory-sync-store-pg.js";
@@ -29,6 +30,8 @@ import { PgTaskAttachmentStore, TiDBTaskAttachmentStore, ensurePgTaskAttachmentS
 import { createSessionStore } from "../plugins/session-store.js";
 import { assertCloudSnapshotBlobPosture, openStoreBackendWithFallback } from "../plugins/store-backend.js";
 import { memoryEngineBackendFor, memoryEngineRemoteLanePosture } from "../memory-scope.js";
+import { assertToolResultProvenanceSchema } from "../plugins/tool-result-store-sql.js";
+import { buildMemoryWriteBoundaryAudit } from "./memory-boundary.js";
 export async function openStores(ctx) {
     const { config, logger, metrics, localRoot } = ctx;
     // One shared SQL store backend for L1 + L2 (TiDB/MySQL or PostgreSQL per DB_BACKEND). Owned here.
@@ -51,6 +54,20 @@ export async function openStores(ctx) {
     // S5 review LOW-1: always render the series (0 = healthy) — gauge absence is indistinguishable from
     // "old build without this metric", which breaks `== 0`-style alert rules.
     metrics.setGauge("store_backend_degraded", storeBackendDegraded ? 1 : 0);
+    // #119 升级前置断言(core 5.26.0 提货):`CREATE TABLE IF NOT EXISTS` 对**存量** tool_result 是空操作 ⇒
+    // 没删表就升上来的部署,出处两列与加宽的 ref 列都不在,而每一次 offload 写都会撞 unknown column、被
+    // core 的失败臂吞成一条内联占位(服务照跑、工具产物全丢)。判据与恢复动作见
+    // assertToolResultProvenanceSchema 的头注。
+    // 🔴 位置:**不在** `ensureSchema` 里 —— 那条通道的契约是「只发 CREATE」(test/ensure-schema.test.ts 的
+    // 运行时门),一条只读探针进去也算破例。放在 DDL 之后、任何路由装配之前,拒启的意义仍在(还没开始服务)。
+    {
+        const mysqlPool = backend?.mysqlPool?.();
+        const pgPool = backend?.pgPool?.();
+        if (pgPool)
+            await assertToolResultProvenanceSchema(async (sql) => ({ rows: (await pgPool.query(sql)).rows }), "pg");
+        else if (mysqlPool)
+            await assertToolResultProvenanceSchema(async (sql) => ({ rows: (await mysqlPool.query(sql))[0] }), "tidb");
+    }
     // S21 (SILENT-FALLBACK P1): MINIO_* partially set silently falls back to SQL-blob snapshots. Warn on the
     // partial config and always render which backend blobs actually use.
     {
@@ -100,16 +117,44 @@ export async function openStores(ctx) {
                 }
             },
         });
+        // #228:检索档位(lexical|portable|native)是「后端上限 × embedder 在场」的**推断结果**,不是旋钮
+        // ([3590] 裁①)。下面两支各自从**实例的 getter** 读真值——不在这里自己推断,推断出的档与实际跑的档
+        // 一旦分家,启动日志就成了另一句谎([3606]①:lexical 在跑必须运维可见)。
+        let vectorMode;
         if (dialect === "pg") {
             const pool = backend?.pgPool();
             if (!pool)
                 throw new Error("MEMORY_ENGINE_BACKEND=pg requires DB_BACKEND=pg (the memory engine binds the same PG pool) — refusing to start half-configured");
             const q = async (text, params) => { const r = await pool.query(text, params); return { rows: r.rows }; };
+            // ⚠️ 维度守卫的**位置**(诚实记档,不编造对表):这里 ensure schema 不传 `memoryVector`,即 embedding
+            // 列是 `jsonb`(portable 档),schema 侧**没有维度**可与 MEMORY_EMBEDDER_DIM 对表。boot 期能做的
+            // 只有「DIM 是正整数」(config.ts parseMemoryEmbedder);真正的维度守卫在写入路径两处:
+            // ① 本仓 embedder 拿到长度不符的响应直接抛(绝不截断/补零);
+            // ② `PgMemoryEngineBackend.embeddingParam` 对长度不符的向量返回 null,该行退回词面档、不写坏向量。
             await ensurePgMemoryEngineSchema(q);
             await ensurePgMemoryHistorySchema(q);
             await ensurePgMemorySyncSchema(q); // 142-S2.5: sync_cursors(+push_queue)同池 ensure,幂等
             memorySyncCursors = new PgMemorySyncStore(q);
-            const pgMem = new PgMemoryEngineBackend(q, { history: countedHistorySink(new PgMemoryHistoryStore(q)) });
+            // #228:配了 MEMORY_EMBEDDER_*(config 层已把半配/坏值/错后端全拒掉)⇒ 注入,vectorMode 由 lexical
+            // 升到 portable;没配 ⇒ undefined,逐字保持改前行为。
+            // onFailure(codex 复审 F2):embed 抛出去之后,applyPatches 的外层 catch 会把它折成一条
+            // `io error: …` **冲突**(core 的冲突词表把它讲成「并发改动」),search 那腿则直接退回词面档 ——
+            // 两条路都不会在部署面留下「向量供应商挂了」的信号。这条腿就是那个信号(抛照抛,只是被看见)。
+            const embedder = memoryEmbedderFor(config, {
+                onFailure: (err) => {
+                    metrics.inc("memory_embed_failed_total", { backend: dialect });
+                    logger.warn("memory_embedder_failed", {
+                        model: config.memoryEmbedder?.model,
+                        err: String(err).slice(0, 300),
+                        note: "memory writes for this batch report an io-error conflict and retrieval falls back to the lexical floor until the embedder recovers",
+                    });
+                },
+            });
+            const pgMem = new PgMemoryEngineBackend(q, {
+                history: countedHistorySink(new PgMemoryHistoryStore(q)),
+                ...(embedder !== undefined ? { embedder } : {}),
+            });
+            vectorMode = pgMem.vectorMode;
             // 工作面根:DB 形态下 memory/ 目录=per-worker ephemeral 物化区(丢了重建,控制面同);
             // 复用 localDataRoot 下独立子树,绝不与 File backend 的持久 memory/ 混写。
             memoryEngine = { backend: pgMem, root: join(config.localDataRoot ?? localRoot, "memory-work") };
@@ -122,9 +167,24 @@ export async function openStores(ctx) {
             await ensureTiDBMemoryHistorySchema(pool);
             await ensureTiDBMemorySyncSchema(pool); // 142-S2.5: sync_cursors(+push_queue)同池 ensure,幂等
             memorySyncCursors = new TiDBMemorySyncStore(pool);
-            memoryEngine = { backend: new TiDBMemoryEngineBackend(pool, { history: countedHistorySink(new TiDBMemoryHistoryStore(pool)) }), root: join(config.localDataRoot ?? localRoot, "memory-work") };
+            // tidb 记忆后端 v1 无向量档(传 embedder 它自己 fail-loud 拒);config 层已保证 MEMORY_EMBEDDER_*
+            // 只可能与 pg 后端同时在场,所以这一支不注入,恒 lexical。
+            const tidbMem = new TiDBMemoryEngineBackend(pool, { history: countedHistorySink(new TiDBMemoryHistoryStore(pool)) });
+            vectorMode = tidbMem.vectorMode;
+            memoryEngine = { backend: tidbMem, root: join(config.localDataRoot ?? localRoot, "memory-work") };
         }
-        logger.info("memory_engine_enabled", { enabled: true, backend: dialect, multiTenant: config.requirePrincipal === true, workRoot: memoryEngine.root });
+        // embedder 身份(model + dim)一并自报(codex 复审 F1 的**部分**缓解,记档):本仓没有向量指纹列
+        // (要加列 = 动 SQL,超出 #228 单),所以「同维度换模型 ⇒ 旧向量与新查询向量不同空间、排序变噪音」
+        // 这件事在库里查不出来;能做的是把当前跑的模型写进启动日志,让换模型这件事在运维面留痕(USAGE 里
+        // 的对应纪律:换模型/换维度前先清 `agent_memory_engine_entry.embedding`)。
+        logger.info("memory_engine_enabled", {
+            enabled: true,
+            backend: dialect,
+            vectorMode,
+            ...(config.memoryEmbedder !== undefined ? { embedderModel: config.memoryEmbedder.model, embedderDim: config.memoryEmbedder.dimensions } : {}),
+            multiTenant: config.requirePrincipal === true,
+            workRoot: memoryEngine.root,
+        });
     }
     else {
         memoryEngine = memoryEngineBackendFor(config);
@@ -139,6 +199,36 @@ export async function openStores(ctx) {
             });
         }
     }
+    // #214 记忆边界不变式([3492]② 立案):记忆没有写工具 —— 模型是用 fs 工具往记忆根写文件的,所以整条
+    // 「记住 X」链的成立条件是**记忆根落在该次任务的 fs 授权边界内**。判据本体(含为什么是 warn 不是拒启、
+    // 为什么围栏根未知时闭嘴)在 boot/memory-boundary.ts;这里只负责把 boot 期的真事实喂进去。
+    // 围栏根的口径与 resolve-spec 的 fs 写门同源:host 语义车道才有本机围栏可谈 —— `REMOTE_EXEC` 未设的
+    // in-process 形,手就在本进程 cwd 跑;显式 `host` 形取 operator 配的 workspaceBase(没配 = 每任务临时
+    // 目录,boot 期不可知 ⇒ 空数组 ⇒ 不判)。其它车道一律非 host 语义,走 remote 那一臂。
+    {
+        const lane = config.remoteExec?.provider;
+        const hostSemanticsLane = lane === undefined || lane === "host";
+        // core 的 remote 判决(与文件平面是两根轴):`isRemoteExecutionEnv` 是鸭子类型,我方**所有**
+        // REMOTE_EXEC 车道(含 `host` —— remote-env-host.ts 实现了 suspendVM/workspaceHandle/execStream,
+        // 亲验)都满足;未设 provider = in-process(core 拿 StubExecutionEnv)。
+        const coreRemoteExecutionEnv = config.remoteExec !== undefined;
+        // 🔴 codex 复审(medium,已核真):`REMOTE_EXEC=host` 的 `workspaceBase` **不是**任务围栏 —— host
+        // factory 每任务在它下面另铸一个 `sema-host-*` 子目录,而且调用方的 per-session cwd 还能整个换掉它。
+        // 拿 workspaceBase 当围栏,会把「记忆根是真任务目录的**兄弟**」这一形误判成「在围栏内」而闭嘴 ——
+        // 恰恰是本判据要抓的那种坏部署。所以 host 腿一律报**未知**(空数组 ⇒ 不判),只有 in-process 腿
+        // (手就在本进程 cwd 上跑,boot 期这一位是真的)才给围栏根。宁可少说,不可说错。
+        const containmentRoots = lane === undefined ? [process.cwd()] : [];
+        const audit = buildMemoryWriteBoundaryAudit({
+            memoryRoot: memoryEngine?.root,
+            lane: lane ?? "in-process",
+            hostSemanticsLane,
+            coreRemoteExecutionEnv,
+            declaredCapable: config.memoryPersistenceCapable,
+            containmentRoots,
+        });
+        for (const w of audit.warnings)
+            logger.warn(w.tag, { detail: w.detail, lane: lane ?? "in-process", root: memoryEngine?.root ?? null });
+    }
     // RosterStore(agent-team S1 server 半场,[1070]① 提货单;core 1.316 `RunnerDeps.rosterStore`):
     // 具名子 agent 持久名册。形态跟 StoreBackend:tidb/pg=SQL twins(语义三条+真双库验证,
     // roster-store-sql.ts 顶注);local=core FileRosterStore(dataRoot 下 roster.json,core 自带原子写/

package/dist/capabilities/memory-notice.d.ts

@@ -0,0 +1,83 @@
+/**
+ * #217(板 [3499]②/[3521]④ 两次点名的 server 接线半场)—— 零记忆面部署形的**持久记忆披露**。
+ *
+ * 病(core [3479] 实测,#148 立案):一台没有任何持久记忆面的部署,用户说「请记住 X」,模型回一句
+ * 「已经记住了」——落盘处并不存在。用户带着「这条事实已入库」的信念离开,下一次会话才发现是空的。
+ *
+ * core 5.26.0 的分工:引擎**能自证**只读的两态(engine 侧 `writeScope:null` / runner 侧 `handsReadOnly`)
+ * 由引擎自动挂 `MEMORY_READONLY_NOTICE`;而「整台部署根本没有记忆面」这一形 core 只导出文本
+ * (`NO_PERSISTENT_MEMORY_NOTICE`)、**不注入** —— 逐字原文:「A deployment that composes its own prompt
+ * should include this block exactly when no memory face is mounted」。组装归宿主,与 `MEMORY_SAFETY`
+ * 同姿势。本模块就是那半场。
+ *
+ * ⚠️ 两条边界,越界即双重注入/假话:
+ *  · **engine 在场就不是我们的座位**。哪怕 `memoryWrite:false`(writeScope null)——那恰恰是引擎自己
+ *    挂只读披露的状态,server 再叠一句口径不同的「你没有持久记忆」= 同一件事两种说法同框。
+ *  · **推断到「有落盘路」就闭嘴**。判别式与 core 的 `rosterCanPersist` 同口径(已知落盘路 = 挂载且未
+ *    排除的文件写工具 / 可写 shell)。`excludeTools:["Write"]` **不算**无写通道(Bash/Edit 仍可写)—— 本
+ *    判别式压根不读工具名单,读的是**手带表态**(`hands`/`handsReadOnly`),所以这条负控是构造性成立的:
+ *    请求面摘一个工具名改不动部署级的手带事实。
+ */
+import { type PromptProvider, type TaskSpec } from "@sema-agent/core";
+import type { ScenarioHands } from "./hands-lane.js";
+/**
+ * 「已知落盘路」的工具名闭集 —— 与 core 的 `rosterCanPersist` 同口径:**文件写工具**(Write/Edit/
+ * NotebookEdit)或**可写 shell**(Bash)。刻意**不是** `HAND_TOOL_EFFECTS` 里 effect=write 的全集:
+ * core 逐字裁过「a generic write-effect tool does NOT count — a mail sender's side effect is not a
+ * memory store」,`TaskStop` 就是那种(有写副作用、不是落盘路)。
+ *
+ * 名字会漂,所以配一道防漂移钉(test/no-persistent-memory-notice.test.ts):每个名字必须在 core 的
+ * `HAND_TOOL_EFFECTS` 里且 effect 为 `write` —— core 改名/改档位当场红,而不是让这里静默失配成
+ * 「没有一个写工具被排除」(fail-open 方向)。
+ */
+export declare const KNOWN_PERSISTENCE_TOOL_NAMES: readonly ["Write", "Edit", "NotebookEdit", "Bash"];
+/** 披露段在 `prompt.assembled` 清单里的段 id(`core/` 命名空间是 core 保留的,部署段一律自家前缀)。 */
+export declare const NO_PERSISTENT_MEMORY_SECTION_ID = "sema/memory.no-persistent";
+/** 判别式的全部输入 —— 每一位都是**部署/装配期事实**,没有一位来自请求体的自我表态。 */
+export interface MemoryFaceFacts {
+    /** 本次任务最终的 `TaskSpec.memory`。`undefined` = 这一腿根本没有引擎记忆面(引擎未接、多租户 dark、
+     *  remote lane 平面分裂 fail-closed……三条路殊途同归:core 不会 prepare 记忆,也就不会挂任何披露)。 */
+    memory: TaskSpec["memory"];
+    /** 部署声明 `MEMORY_PERSISTENCE_CAPABLE`(三态)。`true` = operator 自证有推断看不见的持久通道
+     *  (自定义 writer / MCP 记忆服务)⇒ 披露会变成假话,撤回;`false` = 强制披露;缺席 ⇒ 走推断。 */
+    declaredCapable: boolean | undefined;
+    /** 本请求命中场景的手带表态(#196 判别位)。`none` = 该场景跑在不挂 `executionEnvFactory` 的 Runner 上,
+     *  core 的手带 band(Bash/Edit/Write/…)整批不 mount。 */
+    hands: ScenarioHands;
+    /** 折完 governance+settings 后的最终 `handsReadOnly`(plan 模式 / autonomy 收窄)。手带只剩读腿。 */
+    handsReadOnly: boolean;
+    /** 折完之后的最终 `TaskSpec.excludeTools`(roster 真卸载,不是延迟披露)。**全部**已知落盘路都被排掉
+     *  ⇒ 手带在场也等于没有写通道 —— core 的 `rosterCanPersist` 也是按排除后的 roster 算的,这里跟上。 */
+    excludeTools: readonly string[] | undefined;
+    /** 本部署的执行环境在 core 眼里算不算 **remote**(`isRemoteExecutionEnv`)。判别位 = `REMOTE_EXEC` 有没有
+     *  设 —— 注意 `host` 也算:core 的判别是**鸭子类型**(`workspaceHandle`/`execStream`/`suspendVM`/…),
+     *  而我方的 `remote-env-host.ts` 这几件全实现,亲验坐实。
+     *  为什么这一位必须进判别式(codex 复审 round2 [high],已核真):core 的 `rosterCanPersist` 在
+     *  `handsEnabled && isRemoteExecutionEnv` 时把 Write/Edit/NotebookEdit/Bash **全部不算**落盘路(沙箱盘
+     *  每任务即焚,够不着 host 记忆根)。而 server 在任何 remote 车道上默认让记忆引擎 dark —— 两件事合起来
+     *  正是**最常见的云部署形**:引擎不在、手带在,却一份持久面都没有。漏了这一位,那台机器就继续给
+     *  「已经记住了」的幻觉式回执 —— 恰恰是 #148 立案要消灭的形态。 */
+    remoteExecutionEnv: boolean;
+}
+/**
+ * 该不该把 `NO_PERSISTENT_MEMORY_NOTICE` 组进本次任务的 system prompt。
+ *
+ * 优先序(每一条都有独立理由,不是同一条判据的三种写法):
+ *  ① engine 在场 ⇒ **否**(引擎的座位,见文件头注);
+ *  ② 部署显式声明 ⇒ 声明说了算(`true` 撤回 / `false` 强制)—— operator 的部署事实压过我们的推断,
+ *     与 core 对 `memoryPersistenceCapable` 的处置同向;
+ *  ③ 否则推断:有已知落盘路(手带在场且不是只读)⇒ 否;没有 ⇒ 是。
+ */
+export declare function shouldDiscloseNoPersistentMemory(facts: MemoryFaceFacts): boolean;
+/**
+ * 把披露段组进一个 prompt provider,**按 provider 自己的钩子形分腿**(换形会改段身份与 append 座位):
+ *  · typed(`stableBlocks`)⇒ 追加一条 `behavior` 声明。**不能**用 `identity`:那个 slot 会替换 role base。
+ *  · string(`stableSystem`)⇒ 接在 role 层文本之后(落进 `core/role.base` 段)。
+ *  · 两个钩子都没有(= core 会用 `defaultPromptProvider`)⇒ **自铸 role 层**。这里绝不能去包
+ *    `defaultPromptProvider.stableSystem` —— 它返回的是 `composeConstitution(...)` 的**整装** prompt,
+ *    装配器的迁移卫探到三锚(CYBER_RISK/URL_SAFETY/`# Harness`)就走 pass-through 臂,那条臂的段子集
+ *    没有 `core/role.append`,调用方的 append rider 会被静默丢掉。自铸的是 core 自己那一句
+ *    `userSystemPrompt ?? DEFAULT_SYSTEM_PROMPT`(引用常量,不复制字节)。
+ */
+export declare function withNoPersistentMemoryNotice(provider: PromptProvider | undefined): PromptProvider;
+//# sourceMappingURL=memory-notice.d.ts.map