@sema-agent/server 7.100.0 → 7.101.0

package/dist/observability/secret-env-scrub.d.ts

@@ -1,11 +1,32 @@
 import type { ServerSecretEnvFinding } from "../server-secret-env.js";
 import type { Logger } from "./logger.js";
 import type { Metrics } from "./metrics.js";
+/**
+ * 一个剥除现场的登记:`note` = 这条腿上泄漏意味着什么;`remedy` = 部署方能不能自己把某个被剥的键放回来。
+ *
+ * 🔴 S-699:`remedy` 在场与否决定披露行的**级别**,规则一句 —— **有出路的现场用 warn,并把出路句与当前放行名单写进同一行**;
+ * 没有出路的现场是纯保护留痕,照旧 info。理由:没有出路的剥除(模型可驱动的 shell、git 钩子)是本服务替部署方做的决定,
+ * 读者只需要知道它生效了;有出路的剥除(语言服务器)可能让一件功能静默变差(补全 / 诊断缺了私有 registry 的依赖),
+ * 那是部署方要自己决定的事 —— 看不见 = 无从归因。出路句不带任何值。
+ */
+export interface SecretEnvScrubSiteSpec {
+    readonly note: string;
+    readonly remedy: string | null;
+}
 /** 登记过的剥除现场。闭集:未登记的 site 传不进 {@link recordSecretEnvScrub}(编译期拒,同 FAIL_OPEN_TAGS 纪律)。 */
 export declare const SECRET_ENV_SCRUB_SITES: {
-    readonly "server.remote-env-host.inherit-scrub": "模型可驱动的 host shell 继承 env(`inheritEnv:\"scrub\"` 默认腿)——这条腿上的一次泄漏等于把编排器的脑钥/仓库令牌交给模型选的命令";
-    readonly "server.project-memory.git-subprocess": "project-memory 读仓叙事时的 git 子进程 env —— 仓内的钩子/凭证助手会以本进程身份运行";
-    readonly "server.lsp.spawn-env": "宿主车道本地语言服务器子进程 env(core 7.30.1 #1073 的 `NodeLspManagerOptions.env`)—— 语言服务器会执行仓里的代码(构建脚本/插件/工作区配置),一次泄漏等于把本进程的凭据交给仓";
+    readonly "server.remote-env-host.inherit-scrub": {
+        readonly note: "模型可驱动的 host shell 继承 env(`inheritEnv:\"scrub\"` 默认腿)——这条腿上的一次泄漏等于把编排器的脑钥/仓库令牌交给模型选的命令";
+        readonly remedy: null;
+    };
+    readonly "server.project-memory.git-subprocess": {
+        readonly note: "project-memory 读仓叙事时的 git 子进程 env —— 仓内的钩子/凭证助手会以本进程身份运行";
+        readonly remedy: null;
+    };
+    readonly "server.lsp.spawn-env": {
+        readonly note: "宿主车道本地语言服务器子进程 env(core 7.30.1 #1073 的 `NodeLspManagerOptions.env`)—— 语言服务器会执行仓里的代码(构建脚本/插件/工作区配置),一次泄漏等于把本进程的凭据交给仓";
+        readonly remedy: `LSP_ENV_ALLOW=NAME,NAME \u70B9\u540D\u653E\u884C(\u539F\u6837\u4EA4\u7ED9\u8BED\u8A00\u670D\u52A1\u5668,\u90E8\u7F72\u65B9\u663E\u5F0F\u627F\u62C5;${string});\u503C\u4E0D\u8FDB\u65E5\u5FD7`;
+    };
 };
 /** 词表键推导的闭集类型。 */
 export type SecretEnvScrubSite = keyof typeof SECRET_ENV_SCRUB_SITES;
@@ -16,8 +37,10 @@ interface Sink {
 /**
  * 记一次剥除。**总不抛** —— 观测本身绝不能变成故障(同 `recordFailOpen` / reapers 的判据)。
  * `findings` 为空(这一次没丢任何 key)时什么也不做:那不是事件,是常态。
+ * `findings` 只许装**最终没进子进程**的键 —— 点名放回的键不是剥除(不计数、不披露)。
+ * `allowed` = 这一次生效的点名放行名单(S-699),只在有出路的现场(`remedy` 在场)写进披露行;没有放行面的腿传 `[]`。
  */
-export declare function recordSecretEnvScrub(site: SecretEnvScrubSite, findings: readonly ServerSecretEnvFinding[]): void;
+export declare function recordSecretEnvScrub(site: SecretEnvScrubSite, findings: readonly ServerSecretEnvFinding[], allowed: readonly string[]): void;
 /** 装配层把 logger/metrics 接上(main.ts,与 `installFailOpenRecorder` 同一处)。装配前累计的次数在此补进 metrics。 */
 export declare function installSecretEnvScrubRecorder(deps: Sink): void;
 /** 已留驻的「现场×键」条数(测试/诊断读面)。恒 ≤ {@link DISCLOSED_CAP}。 */

package/dist/observability/secret-env-scrub.js

@@ -1,8 +1,18 @@
 import { summarizeRedactions } from "@sema-agent/core";
+import { describeAllowlistPostures } from "../env-name-allowlist-knobs.js";
 export const SECRET_ENV_SCRUB_SITES = {
-    "server.remote-env-host.inherit-scrub": "模型可驱动的 host shell 继承 env(`inheritEnv:\"scrub\"` 默认腿)——这条腿上的一次泄漏等于把编排器的脑钥/仓库令牌交给模型选的命令",
-    "server.project-memory.git-subprocess": "project-memory 读仓叙事时的 git 子进程 env —— 仓内的钩子/凭证助手会以本进程身份运行",
-    "server.lsp.spawn-env": "宿主车道本地语言服务器子进程 env(core 7.30.1 #1073 的 `NodeLspManagerOptions.env`)—— 语言服务器会执行仓里的代码(构建脚本/插件/工作区配置),一次泄漏等于把本进程的凭据交给仓",
+    "server.remote-env-host.inherit-scrub": {
+        note: "模型可驱动的 host shell 继承 env(`inheritEnv:\"scrub\"` 默认腿)——这条腿上的一次泄漏等于把编排器的脑钥/仓库令牌交给模型选的命令",
+        remedy: null,
+    },
+    "server.project-memory.git-subprocess": {
+        note: "project-memory 读仓叙事时的 git 子进程 env —— 仓内的钩子/凭证助手会以本进程身份运行",
+        remedy: null,
+    },
+    "server.lsp.spawn-env": {
+        note: "宿主车道本地语言服务器子进程 env(core 7.30.1 #1073 的 `NodeLspManagerOptions.env`)—— 语言服务器会执行仓里的代码(构建脚本/插件/工作区配置),一次泄漏等于把本进程的凭据交给仓",
+        remedy: `LSP_ENV_ALLOW=NAME,NAME 点名放行(原样交给语言服务器,部署方显式承担;${describeAllowlistPostures()});值不进日志`,
+    },
 };
 const SCRUB_COUNTER = "secret_env_scrubbed_total";
 const DISCLOSED_CAP = 512;
@@ -31,7 +41,7 @@ function drainToMetrics() {
         }
     }
 }
-export function recordSecretEnvScrub(site, findings) {
+export function recordSecretEnvScrub(site, findings, allowed) {
     if (findings.length === 0)
         return;
     try {
@@ -49,12 +59,17 @@ export function recordSecretEnvScrub(site, findings) {
         const fresh = findings.filter((f) => !disclosed.has(`${site}${SEP}${f.key}`)).slice(0, room);
         if (fresh.length === 0)
             return;
-        logger.info("secret_env_scrubbed", {
+        const spec = SECRET_ENV_SCRUB_SITES[site];
+        const fields = {
             site,
-            note: SECRET_ENV_SCRUB_SITES[site],
+            note: spec.note,
             keys: fresh.map((f) => f.key),
             summary: summarizeRedactions(fresh),
-        });
+        };
+        if (spec.remedy === null)
+            logger.info("secret_env_scrubbed", fields);
+        else
+            logger.warn("secret_env_scrubbed", { ...fields, allowed: [...allowed], hint: spec.remedy });
         for (const f of fresh)
             disclosed.add(`${site}${SEP}${f.key}`);
     }

package/dist/plugins/caching-session-store.d.ts

@@ -2,6 +2,7 @@ import type { AcquiredSession, PlacedSessionRow, RetentionDeclaration, SessionPl
 import type { SessionListItem } from "../security.js";
 import type { StagingHandle } from "../session-sync-kernel.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
+import type { InstructionSourceStore } from "../instruction-source-notice.js";
 export interface CachingOptions {
     /** Idle seconds a woken session is kept warm. 0 disables caching (pure passthrough). */
     ttlSec: number;
@@ -64,6 +65,11 @@ export declare class CachingSessionStore implements SessionStore {
     /** Write-once auto-title (SQL twins + local sidecar carry it; pure pass-through). */
     readonly setTitleIfNull?: (sessionId: string, title: string) => Promise<boolean>;
     readonly probeTitle?: (sessionId: string) => Promise<"none" | "untitled" | "titled">;
+    /** S-690 —— 换源通告的基线面(`session_meta.instruction_source` / local sidecar),纯转发、不经暖缓存。
+     *  🔴 必须转发(与 retention / placements 同一条教训):默认 `SESSION_CACHE_TTL_SEC=300` 把真店包进本类,
+     *  而装配点按「店上两个方法都在」判席 —— 不转发 = 默认部署上换源通告**静默不发**,且没有任何一处报错。 */
+    readonly readInstructionSource?: InstructionSourceStore["readInstructionSource"];
+    readonly recordInstructionSource?: InstructionSourceStore["recordInstructionSource"];
     /** E18 — delegate the leaf read straight to inner (a cache-bypassing single SELECT; the resume-at turn-capture
      *  reads the DURABLE leaf, not a possibly-stale cached view — same discipline as the §0.5 repo ops above). */
     readonly getLeafId?: (sessionId: string) => Promise<string | null>;

package/dist/plugins/caching-session-store.js

@@ -13,6 +13,8 @@ export class CachingSessionStore {
     noteTaskRun;
     setTitleIfNull;
     probeTitle;
+    readInstructionSource;
+    recordInstructionSource;
     getLeafId;
     getHead;
     exportEntries;
@@ -51,6 +53,10 @@ export class CachingSessionStore {
             this.setTitleIfNull = ownerAware.setTitleIfNull.bind(inner);
         if (ownerAware.probeTitle)
             this.probeTitle = ownerAware.probeTitle.bind(inner);
+        if (ownerAware.readInstructionSource)
+            this.readInstructionSource = ownerAware.readInstructionSource.bind(inner);
+        if (ownerAware.recordInstructionSource)
+            this.recordInstructionSource = ownerAware.recordInstructionSource.bind(inner);
         if (ownerAware.fork)
             this.fork = ownerAware.fork.bind(inner);
         if (ownerAware.noteTaskRun)

package/dist/plugins/local-session-store.d.ts

@@ -1,5 +1,6 @@
 import { type AcquiredSession, type SessionStore, type SessionRepo, type SessionTreeEntry } from "@sema-agent/core";
 import type { SessionSummary } from "./store-contracts.js";
+import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 export declare class LocalSessionStore implements SessionStore {
     private readonly repo;
@@ -50,36 +51,19 @@ export declare class LocalSessionStore implements SessionStore {
     private lastWarnAt;
     /** Absolute path to the lastActivity JSON sidecar, or undefined when not persisting (in-memory-only deployment). */
     private readonly sidecarPath?;
-    /** Auto-title map + its own LIGHT sidecar (`session-titles.json`). Separate file from the
-     *  lastActivity sidecar ON PURPOSE (that format is a #10 clobber area); titles are write-once + ultra-low-rate
-     *  (one per session, ever), so a plain read-modify-write with tmp+rename per write is enough — no debounce.
-     *
-     *  🔴 CROSS-INSTANCE (fixed 2026-07-25, blackboard [ref] — core's "per-instance state" defect class):
-     *  these three used to be INSTANCE fields, which is exactly the shape core described — «the backend is shared
-     *  more widely than the object, but the state and the lock hang off the object». Two `LocalSessionStore`s over
-     *  the SAME dataDir each held their own `titles` map and their own write chain, so a real concurrency probe
-     *  (`test/file-stores-cross-instance-concurrency.test.ts`) showed **BOTH winning** the write-once IS-NULL gate
-     *  (`wins=2`): each checked its own map, both saw absent, both returned `true`, and the second whole-map
-     *  snapshot silently clobbered the first title. That is core's A-class (CAS double-win) and B-class
-     *  (lost update) stacked. Fix per core's prescription: state + lock live at MODULE level, keyed by the resolved
-     *  sidecar path, so any number of instances over one dataDir collapse to a single authority.
-     *  Sharing key = the resolved path; NO sidecar (in-memory deployment) ⇒ no shared backend exists ⇒ that case
-     *  keeps genuinely per-instance state (see {@link titleState}). */
-    private readonly titleSidecarPath?;
-    /** Per-instance fallback used ONLY when there is no sidecar path (nothing is shared, so nothing to collapse). */
-    private readonly ownTitleState;
+    /** Auto-title map (`session-titles.json`). Separate file from the lastActivity sidecar ON PURPOSE (that format is a
+     *  #10 clobber area); titles are write-once + ultra-low-rate (one per session, ever). Cross-instance sharing: see
+     *  {@link SidecarStringMap}. */
+    private readonly titles;
+    /** S-690 — instruction-source baselines (`session-instruction-sources.json`): the chain member the session's previous
+     *  run selected, encoded like the SQL twins' `session_meta.instruction_source` column ('' = none; missing key = never
+     *  recorded). Its own file for the same reason titles have theirs: one small map per concern, no format coupling. */
+    private readonly instructionSources;
     /** @param repo     the core SessionRepo this store projects into the §0.5 SessionStore shape.
      *  @param dataDir  the SAME data dir the file-backed repo persists under (LocalBackend passes `fileBackend.root`).
      *                  When given, lastActivity is persisted to `<dataDir>/session-last-activity.json` so it survives a
      *                  restart (the file-backed deployment); omit it for the in-memory deployment (nothing survives). */
     constructor(repo: SessionRepo, dataDir?: string);
-    /** 该实例应当使用的 title 状态:有 sidecar ⇒ 按路径共享的那份;无 sidecar ⇒ 自己那份(无共享后端)。 */
-    private get titleState();
-    /** Lazy one-shot hydrate of the persisted titles (mirrors ensureLoaded's posture: missing file silent, torn warn). */
-    private ensureTitlesLoaded;
-    /** Chained snapshot write of the titles sidecar (the chain guarantees the LAST rename carries the
-     *  NEWEST map state: each link re-snapshots the SHARED map at write time, so an overtaken writer is harmless). */
-    private persistTitles;
     /** Cheap pre-LLM probe (local twin). The map write needs no session_meta row, so there is
      *  no "none" (register-lag) dimension here — two states only. */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
@@ -87,6 +71,15 @@ export declare class LocalSessionStore implements SessionStore {
      *  (small) map via a SERIALIZED tmp+rename snapshot; a write failure keeps the in-memory title (degrades to
      *  re-title after restart). */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /** S-690 —— 换源通告的基线读(local 孪生;三态读法与 SQL 两孪生的 `session_meta.instruction_source` 同一只编解码)。 */
+    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
+    /**
+     * S-690 —— CAS 覆写基线(契约见 `InstructionSourceStore`:期望值不符 ⇒ 不写;**没落盘 ⇒ 回滚内存再抛**,与 SQL 孪生
+     * 「要么提交要么抛」同形 —— 修前写失败只 warn、内存照样前进,同来源的后续 run 在相等比较上短路、再也不重写,重启后
+     * 比的是一份过期的盘,codex che-NM r1 [medium])。CAS 判定、落盘、失败回滚**整段在写链的一节里**(`commit`):下一节
+     * 开始之前内存已回到盘上那份,判定永远不会建立在一个没落过盘的值上(codex che-NM r2 [medium])。
+     */
+    recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
     /** Best-effort, one-shot hydrate of the persisted lastActivity map (no-op when not persisting / no sidecar yet). A
      *  read/parse error degrades to an empty map (createdAt ordering) rather than failing the list — the picker still
      *  works, just without restart-persisted recency. Memoized so concurrent listSessions share one read. */
@@ -121,6 +114,8 @@ export declare class LocalSessionStore implements SessionStore {
      * ENOENT(首次启动没有这份档)在调用点就被排除,压根到不了这里。
      */
     private refuseSidecar;
+    /** `which` 点名是哪一只边档(S-690 起有三只 —— 此前这句恒写 lastActivity,title 边档的失败也被报成「recency 降级」)。
+     *  节流仍是本实例一只。 */
     private warnSidecar;
     acquire(sessionId?: string, opts?: {
         requireExisting?: boolean;

package/dist/plugins/local-session-store.js

@@ -5,6 +5,7 @@ import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlso
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
 import { decodeJsonColumn, readStringRecordColumn } from "./sql-json-column.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
+import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, } from "../session-sync-kernel.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isNotFound = (e) => e instanceof SessionError && e.code === "not_found";
@@ -27,87 +28,131 @@ function userText(entry) {
     }
     return null;
 }
-const TITLE_STATE_BY_PATH = new Map();
-export class LocalSessionStore {
-    repo;
-    retention = UNMANAGED_RETENTION;
-    pending = new Map();
-    owners = new Map();
-    lastActivity = new Map();
-    lastTaskRun = new Map();
-    stagings = new Map();
-    loaded;
-    flushTimer;
-    writeChain = Promise.resolve();
-    dirty = false;
-    writeSeq = 0;
-    lastWarnAt = 0;
-    sidecarPath;
-    titleSidecarPath;
-    ownTitleState = { titles: new Map(), writeChain: Promise.resolve() };
-    constructor(repo, dataDir) {
-        this.repo = repo;
-        this.sidecarPath = dataDir ? join(dataDir, "session-last-activity.json") : undefined;
-        this.titleSidecarPath = dataDir ? resolve(join(dataDir, "session-titles.json")) : undefined;
-        if (this.titleSidecarPath && !TITLE_STATE_BY_PATH.has(this.titleSidecarPath)) {
-            TITLE_STATE_BY_PATH.set(this.titleSidecarPath, { titles: new Map(), writeChain: Promise.resolve() });
-        }
-    }
-    get titleState() {
-        return this.titleSidecarPath ? TITLE_STATE_BY_PATH.get(this.titleSidecarPath) : this.ownTitleState;
-    }
-    async ensureTitlesLoaded() {
-        if (!this.titleSidecarPath)
-            return;
-        const st = this.titleState;
+const SIDECAR_DEGRADES = { lastActivity: "recency", title: "auto-title", "instruction-source": "instruction-source baseline" };
+const SIDECAR_MAP_STATE_BY_PATH = new Map();
+class SidecarStringMap {
+    path;
+    label;
+    onUnreadable;
+    onWriteFailed;
+    own = { entries: new Map(), writeChain: Promise.resolve() };
+    constructor(path, label, onUnreadable, onWriteFailed) {
+        this.path = path;
+        this.label = label;
+        this.onUnreadable = onUnreadable;
+        this.onWriteFailed = onWriteFailed;
+        if (path && !SIDECAR_MAP_STATE_BY_PATH.has(path))
+            SIDECAR_MAP_STATE_BY_PATH.set(path, { entries: new Map(), writeChain: Promise.resolve() });
+    }
+    get state() {
+        return this.path ? SIDECAR_MAP_STATE_BY_PATH.get(this.path) : this.own;
+    }
+    ensureLoaded() {
+        const path = this.path;
+        if (!path)
+            return Promise.resolve();
+        const st = this.state;
         if (!st.loaded) {
-            const path = this.titleSidecarPath;
             st.loaded = (async () => {
                 try {
-                    const parsed = decodeJsonColumn(await readFile(path, "utf8"), readStringRecordColumn, "session-titles.json (the local title sidecar)");
-                    for (const [id, t] of Object.entries(parsed)) {
-                        if (!st.titles.has(id))
-                            st.titles.set(id, t);
+                    const parsed = decodeJsonColumn(await readFile(path, "utf8"), readStringRecordColumn, this.label);
+                    for (const [id, v] of Object.entries(parsed)) {
+                        if (!st.entries.has(id))
+                            st.entries.set(id, v);
                     }
                 }
                 catch (e) {
                     if (e?.code !== "ENOENT")
-                        this.refuseSidecar(path, "LocalSessionStore title sidecar", e);
+                        this.onUnreadable(path, e);
                 }
             })();
         }
         return st.loaded;
     }
-    persistTitles() {
-        if (!this.titleSidecarPath)
-            return Promise.resolve();
-        const path = this.titleSidecarPath;
-        const st = this.titleState;
-        st.writeChain = st.writeChain.then(async () => {
+    persist() {
+        return this.commit(() => () => undefined);
+    }
+    commit(change) {
+        const path = this.path;
+        const st = this.state;
+        const link = st.writeChain.then(async () => {
+            const undo = change(st.entries);
+            if (undo === undefined || !path)
+                return true;
             try {
                 const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-                await writeFile(tmp, JSON.stringify(Object.fromEntries(st.titles)), "utf8");
+                await writeFile(tmp, JSON.stringify(Object.fromEntries(st.entries)), "utf8");
                 await rename(tmp, path);
+                return true;
             }
             catch (e) {
-                this.warnSidecar("write", e);
+                undo();
+                this.onWriteFailed(e);
+                return false;
             }
         });
-        return st.writeChain;
+        st.writeChain = link.then(() => undefined);
+        return link;
+    }
+}
+export class LocalSessionStore {
+    repo;
+    retention = UNMANAGED_RETENTION;
+    pending = new Map();
+    owners = new Map();
+    lastActivity = new Map();
+    lastTaskRun = new Map();
+    stagings = new Map();
+    loaded;
+    flushTimer;
+    writeChain = Promise.resolve();
+    dirty = false;
+    writeSeq = 0;
+    lastWarnAt = 0;
+    sidecarPath;
+    titles;
+    instructionSources;
+    constructor(repo, dataDir) {
+        this.repo = repo;
+        this.sidecarPath = dataDir ? join(dataDir, "session-last-activity.json") : undefined;
+        const sidecar = (file, which) => new SidecarStringMap(dataDir ? resolve(join(dataDir, file)) : undefined, `${file} (the local ${which} sidecar)`, (path, e) => this.refuseSidecar(path, `LocalSessionStore ${which} sidecar`, e, which), (e) => this.warnSidecar("write", e, which));
+        this.titles = sidecar("session-titles.json", "title");
+        this.instructionSources = sidecar("session-instruction-sources.json", "instruction-source");
     }
     async probeTitle(sessionId) {
-        await this.ensureTitlesLoaded();
-        return this.titleState.titles.has(sessionId) ? "titled" : "untitled";
+        await this.titles.ensureLoaded();
+        return this.titles.state.entries.has(sessionId) ? "titled" : "untitled";
     }
     async setTitleIfNull(sessionId, title) {
-        await this.ensureTitlesLoaded();
-        const st = this.titleState;
-        if (st.titles.has(sessionId))
+        await this.titles.ensureLoaded();
+        const entries = this.titles.state.entries;
+        if (entries.has(sessionId))
             return false;
-        st.titles.set(sessionId, title);
-        await this.persistTitles();
+        entries.set(sessionId, title);
+        await this.titles.persist();
         return true;
     }
+    async readInstructionSource(sessionId) {
+        await this.instructionSources.ensureLoaded();
+        return decodeInstructionSource(this.instructionSources.state.entries.get(sessionId));
+    }
+    async recordInstructionSource(sessionId, expected, source) {
+        await this.instructionSources.ensureLoaded();
+        const committed = await this.instructionSources.commit((entries) => {
+            const before = entries.get(sessionId);
+            if (!sameInstructionSourceBaseline(decodeInstructionSource(before), expected))
+                return undefined;
+            entries.set(sessionId, encodeInstructionSource(source));
+            return () => {
+                if (before === undefined)
+                    entries.delete(sessionId);
+                else
+                    entries.set(sessionId, before);
+            };
+        });
+        if (!committed)
+            throw new Error("LocalSessionStore: instruction-source sidecar write failed — baseline not recorded");
+    }
     async ensureLoaded() {
         if (!this.sidecarPath)
             return;
@@ -165,16 +210,16 @@ export class LocalSessionStore {
         if (this.dirty)
             await this.doFlush();
     }
-    refuseSidecar(path, what, e) {
+    refuseSidecar(path, what, e, which = "lastActivity") {
         quarantineUnreadableSidecar(path, what, e instanceof Error ? e.message : String(e));
-        this.warnSidecar("read", e);
+        this.warnSidecar("read", e, which);
     }
-    warnSidecar(op, e) {
+    warnSidecar(op, e, which = "lastActivity") {
         const now = Date.now();
         if (now - this.lastWarnAt < 60_000)
             return;
         this.lastWarnAt = now;
-        console.warn(`LocalSessionStore: lastActivity sidecar ${op} failed (recency persistence degraded): ${e instanceof Error ? e.message : String(e)}`);
+        console.warn(`LocalSessionStore: ${which} sidecar ${op} failed (${SIDECAR_DEGRADES[which]} persistence degraded): ${e instanceof Error ? e.message : String(e)}`);
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
@@ -271,7 +316,7 @@ export class LocalSessionStore {
     }
     async listSessions(opts) {
         await this.ensureLoaded();
-        await this.ensureTitlesLoaded();
+        await this.titles.ensureLoaded();
         const metas = await this.repo.list();
         const all = [];
         for (const meta of metas) {
@@ -291,7 +336,7 @@ export class LocalSessionStore {
                 lastStatus: "",
                 lastRunId: lastRun?.taskId ?? null,
                 ...(lastRun?.runId !== undefined ? { lastTaskRunId: lastRun.runId } : {}),
-                title: this.titleState.titles.get(meta.id) ?? null,
+                title: this.titles.state.entries.get(meta.id) ?? null,
             });
         }
         const qlc = opts.q?.toLowerCase();
@@ -404,9 +449,11 @@ export class LocalSessionStore {
         this.owners.delete(sessionId);
         this.lastActivity.delete(sessionId);
         this.lastTaskRun.delete(sessionId);
-        await this.ensureTitlesLoaded();
-        if (this.titleState.titles.delete(sessionId))
-            await this.persistTitles();
+        for (const map of [this.titles, this.instructionSources]) {
+            await map.ensureLoaded();
+            if (map.state.entries.delete(sessionId))
+                await map.persist();
+        }
         this.scheduleFlush();
         return true;
     }

package/dist/plugins/pg-session-storage.d.ts

@@ -3,6 +3,7 @@ import type { Pool, PoolClient } from "pg";
 import type { SessionSummary } from "./store-contracts.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
+import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import { type IndexSpec } from "./ensure-index.js";
 /**
  * PG-dialect DDL for the L1 session log, translated from tidb-pool.ts SCHEMA_STATEMENTS:
@@ -113,6 +114,12 @@ export declare class PgSessionStore implements SessionStore {
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
     /** @see TiDBSessionStore.setTitleIfNull — the PG twin (write-once auto-title). */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /** @see TiDBSessionStore.readInstructionSource — the PG twin. */
+    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
+    /** @see TiDBSessionStore.recordInstructionSource — the PG twin (same CAS predicate, same per-query timeout; node-pg's
+     *  `query_timeout` rejects AND pg-pool destroys that client, so a lock-stuck baseline write does not keep a pooled
+     *  connection). */
+    recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
     /** @see TiDBSessionStore.fork — copy the WHOLE durable history (full session_event log, compaction floor bypassed,
      *  NOT wake's bounded tail) to a NEW uuidv7 session, re-seq dense from 0, ids/parents verbatim, owner=caller. */
     fork(sourceId: string, owner: string | null): Promise<string | null>;

package/dist/plugins/pg-session-storage.js

@@ -9,9 +9,13 @@ import { assertPlacementAdmission, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS,
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "./sql-errors.js";
+import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
 import { ensureIndexes } from "./ensure-index.js";
 const isDupKey = isPgUniqueViolation;
+function baselineQuery(text, values) {
+    return { text, values, query_timeout: BASELINE_IO_DEADLINE_MS };
+}
 export const PG_SESSION_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS session_meta (
      session_id  VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -23,6 +27,8 @@ export const PG_SESSION_SCHEMA = [
      -- Write-once auto-title (setTitleIfNull / probeTitle): NULL = "untitled", i.e. still claimable; the
      -- three-state probe distinguishes it from "no such session". PG twin of the TiDB COLUMN_MIGRATIONS leg.
      title       VARCHAR(120) COLLATE "C",
+     -- instruction_source(S-690):换源通告的基线 —— TiDB 孪生同名同宽,三态读法(NULL / '' / 链成员相对路径)见那里的列注。
+     instruction_source VARCHAR(64) COLLATE "C",
      -- #292 C18(core 5.48.0 design/323)subagent 转录持久化 —— placement 元组(TiDB 孪生同名同宽,
      -- 语义与六条义务见 src/plugins/session-placement.ts 顶注):创建时一次落行、first-write 不可变;
      -- placement_kind 在场 ⇒ 住在 placement 分区(不上宿主枚举 / claim 形 acquire 恒拒 / release=真删除 /
@@ -348,6 +354,19 @@ export class PgSessionStore {
         const res = await this.pool.query("UPDATE session_meta SET title = $1 WHERE session_id = $2 AND title IS NULL", [title, sessionId]);
         return (res.rowCount ?? 0) > 0;
     }
+    async readInstructionSource(sessionId) {
+        const res = await this.pool.query(baselineQuery("SELECT instruction_source FROM session_meta WHERE session_id = $1", [sessionId]));
+        return decodeInstructionSource(res.rows[0]?.instruction_source);
+    }
+    async recordInstructionSource(sessionId, expected, source) {
+        const next = encodeInstructionSource(source);
+        if (expected.recorded) {
+            await this.pool.query(baselineQuery("UPDATE session_meta SET instruction_source = $1 WHERE session_id = $2 AND instruction_source = $3", [next, sessionId, encodeInstructionSource(expected.source)]));
+        }
+        else {
+            await this.pool.query(baselineQuery("UPDATE session_meta SET instruction_source = $1 WHERE session_id = $2 AND instruction_source IS NULL", [next, sessionId]));
+        }
+    }
     async fork(sourceId, owner) {
         const metaRes = await this.pool.query("SELECT leaf_id FROM session_meta WHERE session_id = $1", [sourceId]);
         if (!metaRes.rows[0])

package/dist/plugins/remote-env-host.d.ts

@@ -37,7 +37,9 @@ export interface HostEnvConfig {
      *  `SERVICE_AUTH_TOKENS` / `APPROVAL_HMAC_KEYS` slip the shape rule)
      *  so a model-driven shell can't `printenv DEEPSEEK_API_KEY` and exfiltrate orchestrator secrets — keeps PATH/HOME/
      *  locale/build (low breakage). `"all"` = inherit everything (explicit opt-out, trusted local dev). A `string[]` =
-     *  strict allowlist. `env`/per-command `options.env` ALWAYS pass through verbatim. */
+     *  strict (hermetic) allowlist via `allowlistedEnv` — the repo's one "named keys pass verbatim" predicate, shared with
+     *  the local language server's `LSP_ENV_ALLOW` (S-699; that leg puts named keys back ON TOP of the scrub instead).
+     *  `env`/per-command `options.env` ALWAYS pass through verbatim. */
     inheritEnv?: "scrub" | "all" | string[];
     /** @deprecated use {@link inheritEnv}. `true`→`"all"`, `false`→`[]` (hermetic). Ignored if `inheritEnv` is set. */
     inheritProcessEnv?: boolean;

package/dist/plugins/remote-env-host.js

@@ -11,7 +11,7 @@ import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeS
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
 import { recordSecretEnvScrub } from "../observability/secret-env-scrub.js";
-import { scrubServerSecrets } from "../server-secret-env.js";
+import { allowlistedEnv, scrubServerSecrets } from "../server-secret-env.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
@@ -1306,15 +1306,12 @@ export class RemoteHostExecutionEnv {
         if (mode === "all")
             base = { ...process.env };
         else if (Array.isArray(mode)) {
-            base = {};
-            for (const k of mode)
-                if (process.env[k] !== undefined)
-                    base[k] = process.env[k];
+            base = allowlistedEnv(mode, process.env);
         }
         else {
             const findings = [];
             base = scrubServerSecrets(process.env, findings);
-            recordSecretEnvScrub("server.remote-env-host.inherit-scrub", findings);
+            recordSecretEnvScrub("server.remote-env-host.inherit-scrub", findings, []);
         }
         if (this.cfg.env)
             Object.assign(base, this.cfg.env);

package/dist/plugins/tidb-pool.js

@@ -58,6 +58,11 @@ export const SCHEMA_STATEMENTS = [
      -- title: auto-generated session title (cheap-model one-liner at first submit; write-once via
      -- setTitleIfNull — the user-facing RENAME layer lives BFF-side as a label overlay, not here).
      title       VARCHAR(120) NULL,
+     -- instruction_source(S-690):本会话**上一次 run** 选中的项目指令文件 = 换源通告(instructions.source_changed)
+     -- 的基线。NULL = 还没有任何 run 记过(首 run 只写不发);'' = 记过、那一次没有项目指令文件;其余 = 链成员相对路径
+     -- (CLAUDE.md / .claude/CLAUDE.md / AGENTS.md / .claude/AGENTS.md)。服务端元数据:不进模型上下文、不进 wire
+     -- 会话面;住在会话行上 ⇒ 随会话删除 / 留存清扫一起消失,fork 出的新行为 NULL(新会话首 run 同样只写不发)。
+     instruction_source VARCHAR(64) NULL,
      -- #292 C18(core 5.48.0 design/323)subagent 转录持久化 —— placement 元组,**创建时一次落行、
      -- first-write 不可变**(register 的 ON DUPLICATE 臂永不重写这六列)。判别位 = placement_kind:
      -- 在场 ⇒ 该会话住在 placement 分区里(不上宿主枚举、claim 形 acquire 恒拒、release=真删除、

package/dist/plugins/tidb-session-store.d.ts

@@ -12,6 +12,7 @@
  */
 import { type AcquiredSession, type PlacedSessionRow, type SessionPlacement, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
+import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import type { SessionSummary } from "./store-contracts.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
@@ -115,6 +116,18 @@ export declare class TiDBSessionStore implements SessionStore {
     /** Write-once auto-title: lands ONLY when title IS NULL (a concurrent/prior title wins;
      *  the user-facing rename layer is BFF-side). Returns whether this call set it. */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /**
+     * S-690 —— 换源通告的基线读(一行 PK SELECT;列的三态读法见 `tidb-pool.ts` 的列注)。行不在 ⇒ 读作「没记过」
+     * (loader 跑在 acquire 之后,行恒在;不在 = 被带外删了,没有下一 run 可比)。
+     */
+    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
+    /**
+     * S-690 —— CAS 覆写基线(期望值 = 调用方读到的那一份;不符 ⇒ 0 行、不抛 —— 契约见 `InstructionSourceStore`)。
+     * **不**碰 `updated_at`(那是会话活动时刻,留存腿按它判龄;记基线不是一次会话活动)。
+     * 两条基线查询都带每查询超时(`BASELINE_IO_DEADLINE_MS`,mysql2 的 `{sql, timeout}` 形):被行锁卡住的写由查询自己
+     * 在期限内拒。⚠️ mysql2 的超时是客户端侧的 —— 拒之后那条连接仍被挂着的命令占到服务端结束(S-9 同形,如实披露)。
+     */
+    recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
     /**
      * E17 — fork a session: copy its WHOLE durable history to a NEW uuidv7 session owned by `owner`, mirroring
      * core's `PgSessionRepo.fork`. Entry ids / parent links are per-session and copy VERBATIM; only `seq` is