@sema-agent/server 7.99.0 → 7.101.0

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/mailbox-store-sql.d.ts

@@ -12,8 +12,10 @@
  *     2026-07-25)起不再与 drop 同句**:reap 是收件人活着时的龄扫,**清箱保高水位**(删消息、清租约、盒行与
  *     next_seq 留着)——本文件 2026-09-03(车BF,codex r1 [high])才跟上;此前 reap 删盒行 ⇒ 下一条 append 从 1
  *     重铸,陈旧 ack 可删掉一条没人见过的新消息。跨进程试剂盒明钉此条。
- *  3. **ack 无 owner 守卫**(信任 claim 赢者链):`seq <= upToSeq` 删行;lease 的 `maxSeq <= upToSeq`
- *     时顺带清 lease(全量 ack = 释放)。
+ *  3. **ack 带 owner 围栏**(MB1,core 1.452 起;原「无守卫、信任 claim 赢者链」已被推翻):当前持租者才删
+ *     `seq <= upToSeq` 的行;lease 的 `maxSeq <= upToSeq` 时顺带清 lease(全量 ack = 释放)。**围栏的判决报出来**
+ *     (core 7.30.0 #1036,S-616):放行 ⇒ `{ acked: true }`(删 0 行也是 true —— 契约是「围栏放行」不是「删了几行」),
+ *     盒不在 / 无人持租 / 非持租者 ⇒ `{ acked: false }`;逐格与 core `InMemoryMailboxStore.ack` 同答。
  *  4. **lease 过期判 = 严格 `expiresAt > now` 才挡**;`releaseLease` 只在 owner 匹配时清。
  *  5. `peekCount` 含已 lease 消息(可见性 ≠ lease 态);空盒 claim = null(box 行在而消息 0 也 null)。
  *  6. **reap = SQL 全量真扫**(core File 实现只扫已加载盒 = 进程内 backstop,[ref] 确认 SQL 是全量
@@ -44,7 +46,7 @@
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import type { MailboxAppendMessage, MailboxLease, MailboxStore } from "@sema-agent/core";
+import type { MailboxAckResult, MailboxAppendMessage, MailboxLease, MailboxStore } from "@sema-agent/core";
 import { type IndexSpec } from "./ensure-index.js";
 import type { MailboxRecipientLifecycle, MailboxRecipientTombstone } from "./mailbox-recipient-lifecycle.js";
 export declare const MAILBOX_TABLE = "mailbox";
@@ -82,7 +84,7 @@ export declare class TiDBMailboxStore implements MailboxStore, MailboxRecipientL
     private tx;
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
-    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
+    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     peekCount(scope: string, handle: string): Promise<number>;
     drop(scope: string, handle: string): Promise<void>;
@@ -108,7 +110,7 @@ export declare class PgMailboxStore implements MailboxStore, MailboxRecipientLif
     private assertIdentity;
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
-    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
+    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     peekCount(scope: string, handle: string): Promise<number>;
     drop(scope: string, handle: string): Promise<void>;

package/dist/plugins/mailbox-store-sql.js

@@ -263,13 +263,14 @@ export class TiDBMailboxStore {
         });
     }
     async ack(scope, handle, owner, upToSeq) {
-        await this.tx(async (c) => {
+        return this.tx(async (c) => {
             const [rows] = (await c.query(`SELECT lease_owner FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             if (rows.length === 0 || rows[0].lease_owner == null || bufToStr(rows[0].lease_owner) !== owner)
-                return;
+                return { acked: false };
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? AND seq <= ?`, [scope, handle, upToSeq]);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
          WHERE scope_key = ? AND handle = ? AND lease_max_seq IS NOT NULL AND lease_max_seq <= ?`, [scope, handle, upToSeq]);
+            return { acked: true };
         });
     }
     async releaseLease(scope, handle, owner) {
@@ -410,13 +411,14 @@ export class PgMailboxStore {
         });
     }
     async ack(scope, handle, owner, upToSeq) {
-        await this.tx(async (c) => {
+        return this.tx(async (c) => {
             const r = (await c.query(`SELECT lease_owner FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]));
             if (r.rows.length === 0 || r.rows[0].lease_owner == null || bufToStr(r.rows[0].lease_owner) !== owner)
-                return;
+                return { acked: false };
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 AND seq <= $3`, [scope, handle, upToSeq]);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
          WHERE scope_key = $1 AND handle = $2 AND lease_max_seq IS NOT NULL AND lease_max_seq <= $3`, [scope, handle, upToSeq]);
+            return { acked: true };
         });
     }
     async releaseLease(scope, handle, owner) {

package/dist/plugins/permission-rule-store-file.js

@@ -5,6 +5,7 @@ import { performance } from "node:perf_hooks";
 import { FileDurableRulePartitionProvider, AppendLog, ensureDir, readJsonlRecords, } from "@sema-agent/core";
 import { z } from "zod";
 import { buildRulePayloadHash } from "./permission-rule-store-sql.js";
+import { createSkippedRecordSink } from "../observability/corrupt-read-seat.js";
 import { EDITED_RULE_BREADTH_WARNING_CODES, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
 import { RULE_BEHAVIORS } from "@sema-agent/core";
 const RuleScopeSchema = z.union([
@@ -140,7 +141,7 @@ export class FileRuleApprovalRecordStore {
         ensureDir(dir);
         const path = join(dir, "approvals.jsonl");
         this.gate = new CorruptionGate("permission-rule approval log", path, onError);
-        for (const raw of readJsonlRecords(path, (info) => this.gate.trip(info.reason))) {
+        for (const raw of readJsonlRecords(path, createSkippedRecordSink((info) => this.gate.trip(info.reason)))) {
             const parsed = ApprovalLineSchema.safeParse(raw);
             if (!parsed.success) {
                 const stale = StaleApprovalLineSchema.safeParse(raw);
@@ -209,7 +210,7 @@ export class FileRuleImportTicketStore {
         ensureDir(dir);
         const path = join(dir, "import-tickets.jsonl");
         this.gate = new CorruptionGate("permission-rule import-ticket log", path, onError);
-        for (const raw of readJsonlRecords(path, (info) => this.gate.trip(info.reason))) {
+        for (const raw of readJsonlRecords(path, createSkippedRecordSink((info) => this.gate.trip(info.reason)))) {
             const parsed = TicketLineSchema.safeParse(raw);
             if (!parsed.success) {
                 this.gate.trip(`a replayed record does not carry a readable shape: ${parsed.error.message}`);

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/sql-json-column.d.ts

@@ -46,11 +46,24 @@ import type { SqlDialect } from "./sql-driver.js";
  *
  * 🔴 **别名是产物的一部分,不是调用点的自由**:MySQL 协议下 `CAST(rules AS CHAR)` 的回报字段名是
  * `CAST(rules AS CHAR)` 而不是 `rules` —— 把别名留给调用点写,就等于给每一处读腿留一个「忘了写别名,
- * 行上于是没有这个键、读回恒 `undefined`」的静默洞。别名在这里一次钉死,行的键恒等于列名。
+ * 行上于是没有这个键、读回恒 `undefined`」的静默洞。别名在这里一次钉死,行的键恒等于列名(成员形
+ * {@link JsonColumnMember}:恒等于声明的小写别名)。
  *
  * 🔴 **`CAST` 不影响索引**:投影不在 `WHERE` 里;大体量列多一次文本拷贝,量级与现状同(驱动本来也解一次)。
  */
-export declare function jsonColumnText(dialect: SqlDialect, column: string): string;
+export declare function jsonColumnText(dialect: SqlDialect, column: string, member?: JsonColumnMember): string;
+/**
+ * 一列 JSON 的**一个顶层成员**(NP-3,7.100.0)—— 读腿只要文档里的一棵子树时用它,整只文档不出引擎。
+ *  · `key` = 成员名(裸标识符;进 MySQL 路径 `'$.<key>'` 与 PG 字面 `'<key>'`,所以只认裸标识符,不转义不猜);
+ *  · `as` = 行上的键(**小写**裸标识符:PG 把不带引号的别名折成小写,别的拼法会让两方言的行键不同)。
+ * 产物仍是**文本**(同一条「按文本投影、恰好解一次」),成员缺席 / 文档不是对象 ⇒ SQL NULL(两引擎同答),
+ * 所以读腿用 {@link decodeNullableJsonColumn}:NULL = 「这份文档没有这棵子树」,JSON `null` 字面 = 一个值(交形读者判)。
+ * 首个读者:`checkpoint-store-sql.ts` 的 `listPending`(运维队列 / `/v1/approvals/stream` 热读)只取 `pendingAction`。
+ */
+export interface JsonColumnMember {
+    readonly key: string;
+    readonly as: string;
+}
 /**
  * 同一只投影的**裸表达式**(不带别名)—— 给 `WHERE` / `UPDATE … WHERE` 这种**没有别名位**的地方用。
  *
@@ -68,7 +81,7 @@ export declare function jsonColumnText(dialect: SqlDialect, column: string): str
  * 子树,本函数的插值对它是一个不透明表达式。所以「误用进 SELECT 投影且没给别名」这一形没有机器门 ——
  * 误用的落点是真库上当场的 `SqlJsonColumnError("not-text")` 响亮抛(行上没有那个键 ⇒ `undefined`),不是静默。
  */
-export declare function jsonColumnTextExpr(dialect: SqlDialect, column: string): string;
+export declare function jsonColumnTextExpr(dialect: SqlDialect, column: string, memberKey?: string): string;
 /**
  * 一次读回失败的**种别**(店层码,**闭集**;运行期词表在这里,类型从它推导 —— 一张词表只有一个写者):
  *  · `not-text` —— 拿到的不是串 = **读腿漏了投影**,那是**码的问题不是数据的问题** ⇒ 响亮的程序错,

package/dist/plugins/sql-json-column.js

@@ -1,13 +1,24 @@
 import { z } from "zod";
 const COLUMN_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-export function jsonColumnText(dialect, column) {
-    return `${jsonColumnTextExpr(dialect, column)} AS ${column}`;
+export function jsonColumnText(dialect, column, member) {
+    if (member === undefined)
+        return `${jsonColumnTextExpr(dialect, column)} AS ${column}`;
+    if (!MEMBER_ALIAS_RE.test(member.as)) {
+        throw new Error(`jsonColumnText: member alias ${JSON.stringify(member.as)} must be a lower-case bare identifier — PostgreSQL folds unquoted aliases to lower case, so any other spelling would give the two dialects different row keys`);
+    }
+    return `${jsonColumnTextExpr(dialect, column, member.key)} AS ${member.as}`;
 }
-export function jsonColumnTextExpr(dialect, column) {
+const MEMBER_ALIAS_RE = /^[a-z_][a-z0-9_]*$/;
+export function jsonColumnTextExpr(dialect, column, memberKey) {
     if (!COLUMN_NAME_RE.test(column)) {
         throw new Error(`jsonColumnTextExpr: ${JSON.stringify(column)} is not a bare column identifier — refusing to splice it into SQL text`);
     }
-    return dialect === "pg" ? `${column}::text` : `CAST(${column} AS CHAR)`;
+    if (memberKey === undefined)
+        return dialect === "pg" ? `${column}::text` : `CAST(${column} AS CHAR)`;
+    if (!COLUMN_NAME_RE.test(memberKey)) {
+        throw new Error(`jsonColumnTextExpr: member ${JSON.stringify(memberKey)} is not a bare identifier — refusing to splice it into a JSON path`);
+    }
+    return dialect === "pg" ? `(${column}::jsonb -> '${memberKey}')::text` : `CAST(JSON_EXTRACT(${column}, '$.${memberKey}') AS CHAR)`;
 }
 export const SQL_JSON_COLUMN_PROBLEMS = ["not-text", "not-json", "malformed"];
 export class SqlJsonColumnError extends Error {

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=真删除、