@sema-agent/server 7.99.0 → 7.101.0

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

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

@@ -3,6 +3,7 @@ import { TiDBSessionStorage } from "./tidb-session-storage.js";
 import { decodeSessionEventPayload } from "./session-event-payload.js";
 import { jsonColumnText } from "./sql-json-column.js";
 import { escapeLike } from "./sql-escape.js";
+import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { assertPlacementAdmission, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
@@ -183,6 +184,19 @@ export class TiDBSessionStore {
         const [r] = await this.pool.query("UPDATE session_meta SET title = ? WHERE session_id = ? AND title IS NULL", [title, sessionId]);
         return r.affectedRows > 0;
     }
+    async readInstructionSource(sessionId) {
+        const [rows] = await this.pool.query({ sql: "SELECT instruction_source FROM session_meta WHERE session_id = ?", timeout: BASELINE_IO_DEADLINE_MS }, [sessionId]);
+        return decodeInstructionSource(rows[0]?.instruction_source);
+    }
+    async recordInstructionSource(sessionId, expected, source) {
+        const next = encodeInstructionSource(source);
+        if (expected.recorded) {
+            await this.pool.query({ sql: "UPDATE session_meta SET instruction_source = ? WHERE session_id = ? AND instruction_source = ?", timeout: BASELINE_IO_DEADLINE_MS }, [next, sessionId, encodeInstructionSource(expected.source)]);
+        }
+        else {
+            await this.pool.query({ sql: "UPDATE session_meta SET instruction_source = ? WHERE session_id = ? AND instruction_source IS NULL", timeout: BASELINE_IO_DEADLINE_MS }, [next, sessionId]);
+        }
+    }
     async fork(sourceId, owner) {
         const [metaRows] = await this.pool.query("SELECT leaf_id FROM session_meta WHERE session_id = ?", [sourceId]);
         if (!metaRows[0])

package/dist/plugins/web-search.d.ts

@@ -4,7 +4,9 @@
  * backend here is what makes `assembleFullBodyTools({ webSearch })` actually mount the WebSearch tool.
  *
  * Multi-provider, picked by `WEB_SEARCH_PROVIDER`:
- *   - `brave`   — Brave Web Search API (GET, `X-Subscription-Token` header)
+ *   - `brave`   — Brave Web Search API (GET, `X-Subscription-Token` header); with `WEB_SEARCH_ENDPOINT` set to a
+ *                 Brave-compatible gateway's full search URL (e.g. a self-hosted Nólë gateway, S-669) the same leg
+ *                 serves that backend — no new provider word, `capabilities.webSearch.backend` still reads `brave`
  *   - `tavily`  — Tavily Search API (POST, `Authorization: Bearer`, native include/exclude_domains)
  *   - `searxng` — a self-hosted SearXNG instance (GET `?format=json`, no auth)
  *
@@ -137,23 +139,10 @@ export interface WebSearchBackend {
 export declare function setWebSearchBadPayloadObserver(fn: ((provider: string) => void) | undefined): void;
 /**
  * Build the `WebSearchConfig` (a `search` fn + `maxResults`) for `assembleFullBodyTools({ webSearch })`. The API key
- * stays captured in this closure — it is never surfaced to the model or the tool args.
+ * stays captured in this closure — it is never surfaced to the model or the tool args. Every error a leg throws leaves
+ * through {@link redactedBackendFailure} (S-716 ③).
  */
 export declare function createWebSearchBackend(cfg: WebSearchBackendConfig): WebSearchBackend;
-/**
- * `WEB_SEARCH_SEARXNG_PARAMS` / `settings.webSearch.searxngParams` 的解析 —— SearXNG 实例侧参数
- * (`engines=` / `language=` 等)。
- *
- * 🔴 [ref] cli 逐串直证:3.18.0 我加了 `searxngParams` 字段和消费点,**却没开任何配置入口** ——
- * 两条门都没有位置填它,于是我在 [ref] 说的「这条是给你们的」是句空话。单测直接构造
- * `WebSearchBackendConfig` 传进去,**天然跳过了配置入口这一层**,于是「能力在」与「配得进」之间
- * 断开,而两边的绿都是真的。判据:**按消费端实际能填的那个入口验,不是按自己构造的对象验。**
- *
- * 形状:`k=v` 用 `;` 分隔(`engines=bing,duckduckgo;language=zh-CN`)——值里本来就常含逗号,
- * 所以分隔符取 `;` 而不是 `,`。整串解析不出任何一对 ⇒ **返回 undefined,键整个不铸**
- * (不产出空对象:空对象会让下游以为「配了但是空的」,与本仓「缺席就要缺席得干净」同源)。
- */
-export declare function parseSearxngParams(raw: unknown): Record<string, string> | undefined;
 /**
  * #81④ 探活门控 —— **默认 OFF**,显式开才探。
  *
@@ -165,14 +154,46 @@ export declare function parseSearxngParams(raw: unknown): Record<string, string>
  * 而猜错的方向是「凭空出网」。缺席要缺席得干净,含糊也一样。
  */
 export declare function shouldProbeWebSearchOnBoot(env?: NodeJS.ProcessEnv): boolean;
-/** Parse the deployment env into a backend config; `undefined` when no provider is set (⇒ WebSearch not assembled). */
+/** env 载体形错的机读码(拼法随 `config.<族>_invalid` 既有族,如 `config.model_provider_invalid`)。码按**规则**
+ *  命名、不按键名 —— 键名逐字在拒因里。 */
+export declare const WEB_SEARCH_CONFIG_INVALID_CODE = "config.web_search_invalid";
+/**
+ * `WEB_SEARCH_PROVIDER` 这一格的判官(provider 字段的 env 载体):缺席 / 词表外 ⇒ `undefined`(= 不装配,缺席语义)。
+ *
+ * 🔴 **读面只问这一只**(codex R1-F2):`config-catalog` 的 `WEB_SEARCH_PROVIDER` 行要的是「装配了哪只后端」这一格,
+ * 不是整份配置。首版它调的是 {@link webSearchConfigFromEnv} —— 那只对旁的 `WEB_SEARCH_*` 形错**抛**(拒启);嵌入式
+ * `createHttpServer` 不走 stage-07,形错的环境可以活在一只跑着的 server 里,于是读 provider 这一格就把整张目录打成
+ * 500。形错拒启归装配点(stage-07 / run-local 调整份解析),读面不替装配点再判一遍。
+ */
+export declare function webSearchProviderFromEnv(env?: NodeJS.ProcessEnv): WebSearchProvider | undefined;
+/**
+ * 部署 env ⇒ 后端配置。`WEB_SEARCH_PROVIDER` 缺席 / 词表外 ⇒ `undefined`(WebSearch 不装配,**不**读其余旋钮 ——
+ * 不消费的键不判);其余 `WEB_SEARCH_*` 任一形错 ⇒ **抛**(拒启,见 {@link envValue})。
+ */
 export declare function webSearchConfigFromEnv(env?: NodeJS.ProcessEnv): WebSearchBackendConfig | undefined;
 /**
- * Parse an UNTRUSTED per-request `body.settings.webSearch` (the user's shell settings — `{provider, apiKey?, endpoint?,
- * maxResults?}`) into a backend config. Returns `undefined` for a missing/invalid provider — NEVER throws, so a bad
- * per-request config falls back to the deployment-env backend rather than failing the task. 🔒 The CALLER gates this to
- * the single-user host lane (a per-request `endpoint`/`apiKey` is a capability config; on multi-tenant a tenant could
- * point `searxng` at an internal URL = SSRF, so multi-tenant uses ONLY the deployment-env backend — [ref] axis).
+ * 每请求 `body.settings.webSearch` 的判决 —— 受理面与装配点**同问这一只**:
+ *  · `absent`    —— 没带(或 `null`)⇒ 用部署后端;
+ *  · `honored`   —— 每个字段形对,且 `provider` 点名了一只本部署会说的后端 ⇒ 这次调用用它;
+ *  · `malformed` —— 任一字段形错 ⇒ 受理面 400 `request.field_invalid`(`issue` 逐字点名字段)。
+ * **`provider` 缺席或不在词表里也是形错**(S-199 主会话改判,codex 验修 V1 [high]):一段 `settings.webSearch` 就是
+ * 调用方在点名目的地(`endpoint` / `apiKey` 都挂在它点名的那只后端上),认不出就拒,不静默换成部署后端 —— 改判前
+ * 这一形回落部署后端,`{provider:"searx", endpoint:<私有地址>}` 的查询于是发到了部署配的后端。env 腿的同一只
+ * {@link isWebSearchProvider} 守卫对**部署**的词表外答「不装配」,那是部署自己的缺席,不是换别人的目的地。
+ * 规则集因此只剩三态,没有「形对但不采纳」这一臂。
+ *
+ * 🔒 采纳与否是**调用方**的事:装配点把整条腿闸在单用户车道(每请求 `endpoint`/`apiKey` 是能力配置;多租上一个
+ * 租户把 `searxng` 指向内网地址就是 SSRF,所以多租只认部署 env 的后端)。受理面的形判**不分车道**(与
+ * `settings.hooks` 同姿势:形在受理面判,采不采纳在装配点决定)。
  */
-export declare function webSearchConfigFromSettings(raw: unknown): WebSearchBackendConfig | undefined;
+export type RequestWebSearchVerdict = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "honored";
+    readonly config: WebSearchBackendConfig;
+} | {
+    readonly kind: "malformed";
+    readonly issue: string;
+};
+export declare function judgeRequestWebSearch(raw: unknown): RequestWebSearchVerdict;
 //# sourceMappingURL=web-search.d.ts.map

package/dist/plugins/web-search.js

@@ -1,8 +1,10 @@
 import { createSearxngSearchBackend } from "@sema-agent/core";
+import { isHierarchicalUrl, redactSecrets } from "../trace/redact.js";
 export const WEB_SEARCH_PROVIDERS = ["brave", "tavily", "searxng"];
 function isWebSearchProvider(word) {
     return WEB_SEARCH_PROVIDERS.includes(word);
 }
+const providerWord = (raw) => raw.trim().toLowerCase();
 export function projectWebSearchCapability(provider) {
     return provider === undefined ? { backend: "none" } : { backend: provider };
 }
@@ -26,6 +28,10 @@ function withTimeout(signal, ms) {
 async function errorText(res) {
     return (await res.text().catch(() => "")).slice(0, 200);
 }
+async function httpFailure(provider, res) {
+    const body = await errorText(res);
+    return new Error(`${provider} search failed: HTTP ${res.status}${body ? ` — ${body}` : ""}`);
+}
 let onBadPayload;
 export function setWebSearchBadPayloadObserver(fn) {
     onBadPayload = fn;
@@ -62,7 +68,7 @@ async function braveSearch(fetchImpl, cfg, query, max, signal) {
     url.searchParams.set("count", String(Math.min(20, max)));
     const res = await fetchImpl(url, { headers: { Accept: "application/json", "X-Subscription-Token": cfg.apiKey }, signal });
     if (!res.ok)
-        throw new Error(`brave search failed (${res.status}): ${await errorText(res)}`);
+        throw await httpFailure("brave", res);
     const data = (await res.json());
     return normalize(data.web?.results, (r) => ({ title: r.title, url: r.url, snippet: r.description }), max, "brave");
 }
@@ -74,14 +80,14 @@ async function tavilySearch(fetchImpl, cfg, query, max, signal, opts) {
         body.include_domains = opts.allowedDomains.slice(0, 300);
     if (opts?.blockedDomains?.length)
         body.exclude_domains = opts.blockedDomains.slice(0, 150);
-    const res = await fetchImpl(cfg.endpoint || TAVILY_BASE, {
+    const res = await fetchImpl(new URL(cfg.endpoint || TAVILY_BASE), {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
         body: JSON.stringify(body),
         signal,
     });
     if (!res.ok)
-        throw new Error(`tavily search failed (${res.status}): ${await errorText(res)}`);
+        throw await httpFailure("tavily", res);
     const data = (await res.json());
     return normalize(data.results, (r) => ({ title: r.title, url: r.url, snippet: r.content }), max, "tavily");
 }
@@ -110,6 +116,11 @@ async function searxngSearch(fetchImpl, cfg, query, max, signal, timeoutMs, opts
     }
     return normalize(rows, (r) => ({ title: r.title, url: r.url, snippet: r.snippet }), max, "searxng");
 }
+function redactedBackendFailure(e) {
+    const text = e instanceof Error ? e.message : String(e);
+    const safe = redactSecrets(text);
+    return safe === text ? e : new Error(safe);
+}
 export function createWebSearchBackend(cfg) {
     const fetchImpl = cfg.fetchImpl ?? fetch;
     const maxResults = Math.max(1, Math.min(20, cfg.maxResults ?? DEFAULT_MAX_RESULTS));
@@ -126,70 +137,170 @@ export function createWebSearchBackend(cfg) {
                 case "searxng": return await searxngSearch(fetchImpl, cfg, q, maxResults, sig, timeoutMs, opts);
             }
         }
+        catch (e) {
+            throw redactedBackendFailure(e);
+        }
         finally {
             done();
         }
     };
     return { search, maxResults };
 }
-export function parseSearxngParams(raw) {
-    if (typeof raw === "object" && raw !== null) {
-        const entries = Object.entries(raw);
-        if (entries.length === 0 || entries.some(([, v]) => typeof v !== "string"))
-            return undefined;
-        return Object.fromEntries(entries);
-    }
-    if (typeof raw !== "string")
-        return undefined;
-    const out = {};
-    for (const pair of raw.split(";")) {
-        const i = pair.indexOf("=");
-        if (i <= 0)
-            continue;
-        const k = pair.slice(0, i).trim();
-        const v = pair.slice(i + 1).trim();
-        if (k && v)
-            out[k] = v;
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
 export function shouldProbeWebSearchOnBoot(env = process.env) {
     const raw = env.WEB_SEARCH_PROBE_ON_BOOT?.trim().toLowerCase();
     return raw === "true" || raw === "1";
 }
-export function webSearchConfigFromEnv(env = process.env) {
-    const provider = env.WEB_SEARCH_PROVIDER?.trim().toLowerCase();
-    if (provider === undefined || !isWebSearchProvider(provider))
-        return undefined;
-    const searxngParams = parseSearxngParams(env.WEB_SEARCH_SEARXNG_PARAMS);
-    const maxRaw = Number(env.WEB_SEARCH_MAX_RESULTS ?? "");
-    const timeoutRaw = Number(env.WEB_SEARCH_TIMEOUT_MS ?? "");
+const ABSENT = { ok: true };
+const valueOf = (j) => (j.ok ? j.value : undefined);
+const isBlank = (s) => s.trim() === "";
+function judgeText(raw) {
+    if (raw === undefined || raw === null)
+        return ABSENT;
+    if (typeof raw !== "string")
+        return { ok: false, issue: "must be a string" };
+    return isBlank(raw) ? ABSENT : { ok: true, value: raw };
+}
+const ENDPOINT_FORM = "must be an absolute URL with a scheme and a host, such as https://search.example.com (a bare host or host:port is not one)";
+const ENDPOINT_USERINFO = "must not carry userinfo (user or user:password before the host)";
+function judgeEndpoint(raw) {
+    if (raw === undefined || raw === null)
+        return ABSENT;
+    if (typeof raw !== "string")
+        return { ok: false, issue: ENDPOINT_FORM };
+    if (isBlank(raw))
+        return ABSENT;
+    if (!isHierarchicalUrl(raw))
+        return { ok: false, issue: ENDPOINT_FORM };
+    const url = new URL(raw);
+    return url.username !== "" || url.password !== "" ? { ok: false, issue: ENDPOINT_USERINFO } : { ok: true, value: raw };
+}
+const COUNT_FORM = "must be a number ≥ 1";
+function judgeCount(raw) {
+    if (raw === undefined || raw === null)
+        return ABSENT;
+    return typeof raw === "number" && Number.isFinite(raw) && raw >= 1 ? { ok: true, value: Math.floor(raw) } : { ok: false, issue: COUNT_FORM };
+}
+function envNumber(raw) {
+    return raw === undefined || isBlank(raw) ? undefined : Number(raw.trim());
+}
+const SEARXNG_PARAM_NAME = /^[A-Za-z0-9_.-]+$/;
+const SEARXNG_PARAMS_FORM = 'must be an object of parameter name → non-empty string, or a "name=value;name=value" string';
+const paramIssue = (entry, problem) => ({ ok: false, issue: `${SEARXNG_PARAMS_FORM} — entry #${entry} ${problem}` });
+function judgeSearxngParams(raw) {
+    if (raw === undefined || raw === null)
+        return ABSENT;
+    const params = [];
+    if (typeof raw === "string") {
+        const segments = raw.split(";");
+        for (const [i, seg] of segments.entries()) {
+            if (isBlank(seg))
+                continue;
+            const eq = seg.indexOf("=");
+            if (eq < 0)
+                return paramIssue(i + 1, 'has no "="');
+            params.push({ entry: i + 1, name: seg.slice(0, eq).trim(), value: seg.slice(eq + 1).trim() });
+        }
+    }
+    else if (typeof raw === "object" && !Array.isArray(raw)) {
+        const entries = Object.entries(raw);
+        for (const [i, [k, v]] of entries.entries()) {
+            if (typeof v !== "string")
+                return paramIssue(i + 1, "has a value that is not a string");
+            params.push({ entry: i + 1, name: k, value: v.trim() });
+        }
+    }
+    else {
+        return { ok: false, issue: `${SEARXNG_PARAMS_FORM} — got ${Array.isArray(raw) ? "an array" : `a ${typeof raw}`}` };
+    }
+    const firstEntryOf = new Map();
+    for (const p of params) {
+        if (!SEARXNG_PARAM_NAME.test(p.name))
+            return paramIssue(p.entry, 'has a name that is not a parameter name (letters, digits, "_", "-", ".")');
+        if (p.value === "")
+            return paramIssue(p.entry, "has an empty value");
+        const first = firstEntryOf.get(p.name);
+        if (first !== undefined)
+            return paramIssue(p.entry, `repeats the name of entry #${first}`);
+        firstEntryOf.set(p.name, p.entry);
+    }
+    return params.length === 0 ? ABSENT : { ok: true, value: Object.fromEntries(params.map((p) => [p.name, p.value])) };
+}
+function assembleBackendConfig(provider, f) {
     return {
         provider,
-        ...(env.WEB_SEARCH_API_KEY ? { apiKey: env.WEB_SEARCH_API_KEY } : {}),
-        ...(env.WEB_SEARCH_ENDPOINT ? { endpoint: env.WEB_SEARCH_ENDPOINT } : {}),
-        ...(searxngParams ? { searxngParams } : {}),
-        ...(Number.isFinite(maxRaw) && maxRaw > 0 ? { maxResults: Math.floor(maxRaw) } : {}),
-        ...(Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? { timeoutMs: Math.floor(timeoutRaw) } : {}),
+        ...(f.apiKey !== undefined ? { apiKey: f.apiKey } : {}),
+        ...(f.endpoint !== undefined ? { endpoint: f.endpoint } : {}),
+        ...(f.searxngParams !== undefined ? { searxngParams: f.searxngParams } : {}),
+        ...(f.maxResults !== undefined ? { maxResults: f.maxResults } : {}),
+        ...(f.timeoutMs !== undefined ? { timeoutMs: f.timeoutMs } : {}),
     };
 }
-export function webSearchConfigFromSettings(raw) {
-    if (!raw || typeof raw !== "object")
+export const WEB_SEARCH_CONFIG_INVALID_CODE = "config.web_search_invalid";
+function envValue(key, j) {
+    if (!j.ok) {
+        throw new Error(`env ${key} ${j.issue} [${WEB_SEARCH_CONFIG_INVALID_CODE}] — fix it or unset it (an empty value counts as unset). ` +
+            "WebSearch reads its WEB_SEARCH_* knobs only when WEB_SEARCH_PROVIDER names a backend, and every knob it reads must be well-formed: " +
+            "a malformed value used to be absorbed silently (garbage parameters sent to the search instance, or a quiet fall-back to a default nobody chose).");
+    }
+    return j.value;
+}
+export function webSearchProviderFromEnv(env = process.env) {
+    const raw = env.WEB_SEARCH_PROVIDER;
+    const word = raw === undefined ? undefined : providerWord(raw);
+    return word !== undefined && isWebSearchProvider(word) ? word : undefined;
+}
+export function webSearchConfigFromEnv(env = process.env) {
+    const provider = webSearchProviderFromEnv(env);
+    if (provider === undefined)
         return undefined;
+    return assembleBackendConfig(provider, {
+        apiKey: envValue("WEB_SEARCH_API_KEY", judgeText(env.WEB_SEARCH_API_KEY)),
+        endpoint: envValue("WEB_SEARCH_ENDPOINT", judgeEndpoint(env.WEB_SEARCH_ENDPOINT)),
+        searxngParams: envValue("WEB_SEARCH_SEARXNG_PARAMS", judgeSearxngParams(env.WEB_SEARCH_SEARXNG_PARAMS)),
+        maxResults: envValue("WEB_SEARCH_MAX_RESULTS", judgeCount(envNumber(env.WEB_SEARCH_MAX_RESULTS))),
+        timeoutMs: envValue("WEB_SEARCH_TIMEOUT_MS", judgeCount(envNumber(env.WEB_SEARCH_TIMEOUT_MS))),
+    });
+}
+const SETTINGS_WEB_SEARCH_FORM = "settings.webSearch must be an object { provider, apiKey?, endpoint?, searxngParams?, maxResults? }";
+const providerIssue = (shape) => ({
+    ok: false,
+    issue: `must name one of ${WEB_SEARCH_PROVIDERS.join(" | ")} (${shape}) — it names where this request's searches go, so an unknown or missing provider is refused rather than replaced by this deployment's own backend`,
+});
+function judgeRequestProvider(raw) {
+    if (raw === undefined || raw === null)
+        return providerIssue("it is missing");
+    if (typeof raw !== "string")
+        return providerIssue("it is not a string");
+    const word = providerWord(raw);
+    return isWebSearchProvider(word) ? { ok: true, value: word } : providerIssue("it is not one of them");
+}
+export function judgeRequestWebSearch(raw) {
+    if (raw === undefined || raw === null)
+        return { kind: "absent" };
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return { kind: "malformed", issue: SETTINGS_WEB_SEARCH_FORM };
     const s = raw;
-    const provider = typeof s.provider === "string" ? s.provider.trim().toLowerCase() : "";
-    if (!isWebSearchProvider(provider))
-        return undefined;
-    const max = typeof s.maxResults === "number" && Number.isFinite(s.maxResults) && s.maxResults > 0 ? Math.floor(s.maxResults) : undefined;
+    const provider = judgeRequestProvider(s.provider);
+    if (!provider.ok)
+        return { kind: "malformed", issue: `settings.webSearch.provider ${provider.issue}` };
+    const fields = {
+        apiKey: judgeText(s.apiKey),
+        endpoint: judgeEndpoint(s.endpoint),
+        searxngParams: judgeSearxngParams(s.searxngParams),
+        maxResults: judgeCount(s.maxResults),
+    };
+    for (const [field, j] of Object.entries(fields)) {
+        if (!j.ok)
+            return { kind: "malformed", issue: `settings.webSearch.${field} ${j.issue}` };
+    }
     return {
-        provider,
-        ...(typeof s.apiKey === "string" && s.apiKey ? { apiKey: s.apiKey } : {}),
-        ...(typeof s.endpoint === "string" && s.endpoint ? { endpoint: s.endpoint } : {}),
-        ...(() => {
-            const p = parseSearxngParams(s.searxngParams);
-            return p ? { searxngParams: p } : {};
-        })(),
-        ...(max ? { maxResults: max } : {}),
+        kind: "honored",
+        config: assembleBackendConfig(provider.value, {
+            apiKey: valueOf(fields.apiKey),
+            endpoint: valueOf(fields.endpoint),
+            searxngParams: valueOf(fields.searxngParams),
+            maxResults: valueOf(fields.maxResults),
+        }),
     };
 }
 //# sourceMappingURL=web-search.js.map

package/dist/project-memory.d.ts

@@ -1,5 +1,6 @@
 import { type PlatformPath } from "node:path";
 import type { ProjectMemoryLoad } from "@sema-agent/core";
+import { type InstructionSourceSeat } from "./instruction-source-notice.js";
 interface ProjectMemoryCtx {
     cwd: string;
     handsEnabled: boolean;
@@ -46,6 +47,13 @@ export declare function instructionChainCoordinates(absPath: string, p?: Platfor
  * (mid-run file edits surface via the probe as tail attachments, never a silently re-rendered prefix).
  * `phase: "post-compact"` forces a re-read (core re-renders the prefix there anyway). No entry for
  * sessionless one-shot runs. (post-clear never arrives from core — [ref] — so it is not a cache key here.)
+ *
+ * S-690 — source-change notice: with `instructionSource` wired, every prepare of a non-subagent session that WALKED the
+ * instruction chain hands the chain member it selected (`null` = none) to {@link announceInstructionSource}, which
+ * compares it with the session's persisted baseline. A prepare stopped by a pre-walk gate (hands-less, a cwd that is not
+ * an absolute local directory) is "not applicable", not "none" — it never reaches the mint (O6, see `LoadOutcome`). The member is the one the snapshot carries — a cache hit answers the cached pick, so
+ * the notice follows what the model actually reads, not the disk (a same-process edit changes nothing until the
+ * snapshot is re-read: restart, post-compact, or a new session).
  */
 export declare function makeLoadProjectMemory(opts: {
     logger?: {
@@ -54,6 +62,8 @@ export declare function makeLoadProjectMemory(opts: {
     maxBytes?: number;
     /** TEST-ONLY: shrink the snapshot-cache bound so the settle-time trim is observable without 256 sessions. */
     cacheMax?: number;
+    /** S-690: the baseline store + notice exit. Absent ⇒ no source-change notice (the session store has no baseline face). */
+    instructionSource?: InstructionSourceSeat;
 }): (ctx: ProjectMemoryCtx) => Promise<string | null | ProjectMemoryLoad>;
 /**
  * ② The `RunnerDeps.probeInstructionSources` seam: re-fingerprint the declared instruction files mid-run so

package/dist/project-memory.js

@@ -2,6 +2,7 @@ import { promises as fs, constants as fsConstants } from "node:fs";
 import { execFile } from "node:child_process";
 import { createHmac, randomBytes } from "node:crypto";
 import hostPath, { isAbsolute, join } from "node:path";
+import { announceInstructionSource } from "./instruction-source-notice.js";
 import { recordSecretEnvScrub } from "./observability/secret-env-scrub.js";
 import { scrubServerSecrets } from "./server-secret-env.js";
 import { redactSecrets } from "./trace/redact.js";
@@ -41,6 +42,7 @@ function instructionHash(raw) {
     return `hmac-sha256:${createHmac("sha256", INSTRUCTION_HASH_KEY).update(raw).digest("hex")}`;
 }
 const ABSENT_HASH = null;
+const NOT_APPLICABLE = { walked: false, answer: null };
 export function instructionChainCoordinates(absPath, p = hostPath) {
     const candidates = INSTRUCTION_FILE_CHAIN.filter((rel) => absPath.endsWith(p.sep + rel.split("/").join(p.sep))).sort((a, b) => b.length - a.length);
     for (const rel of candidates) {
@@ -72,7 +74,7 @@ function git(root, args, maxBytes) {
     const safeArgs = ["-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", ...args];
     const scrubFindings = [];
     const scrubbedEnv = scrubServerSecrets(process.env, scrubFindings);
-    recordSecretEnvScrub("server.project-memory.git-subprocess", scrubFindings);
+    recordSecretEnvScrub("server.project-memory.git-subprocess", scrubFindings, []);
     return new Promise((res) => {
         execFile("git", safeArgs, { cwd: root, timeout: 5000, maxBuffer: maxBytes, env: { ...scrubbedEnv, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null" } }, (err, stdout, stderr) => {
             if (!err)
@@ -90,17 +92,24 @@ export function makeLoadProjectMemory(opts) {
     const gitCap = 8 * 1024;
     const cache = new Map();
     const CACHE_MAX = opts.cacheMax ?? 256;
+    const seat = opts.instructionSource;
     return async (ctx) => {
+        const outcome = await loadOutcome(ctx);
+        if (seat && ctx.sessionId && !ctx.isSubagent && outcome.walked)
+            await announceInstructionSource(seat, ctx.sessionId, outcome.instructionFile);
+        return outcome.answer;
+    };
+    async function loadOutcome(ctx) {
         if (!ctx.handsEnabled)
-            return null;
+            return NOT_APPLICABLE;
         if (!isAbsolute(ctx.cwd))
-            return null;
+            return NOT_APPLICABLE;
         let root;
         try {
             root = await fs.realpath(ctx.cwd);
         }
         catch {
-            return null;
+            return NOT_APPLICABLE;
         }
         const cacheKey = ctx.sessionId && !ctx.isSubagent ? `${ctx.sessionId}\u0000${root}` : undefined;
         if (cacheKey) {
@@ -144,11 +153,11 @@ export function makeLoadProjectMemory(opts) {
             });
         }
         return load;
-    };
+    }
     async function doLoad(ctx, root) {
         const st = await fs.stat(root).catch(() => null);
         if (!st?.isDirectory())
-            return null;
+            return NOT_APPLICABLE;
         const claudeTrunc = { v: false };
         let claudeRaw = null;
         let hitFile;
@@ -202,28 +211,33 @@ export function makeLoadProjectMemory(opts) {
                 parts.push(`## Working tree\n${status.out.split("\n").slice(0, 40).join("\n")}`);
             gitNarrative = parts.join("\n\n");
         }
+        const instructionFile = hitFile ?? null;
         const sections = [];
         if (claude && hitFile)
             sections.push(`# ${hitFile}\n${claude}`);
         if (gitNarrative)
             sections.push(gitNarrative);
         if (sections.length === 0)
-            return null;
+            return { walked: true, answer: null, instructionFile };
         const redacted = redactSecrets(sections.join("\n\n"));
         const capped = capUtf8(redacted, totalCap);
         opts.logger?.debug?.("project_memory_loaded", { cwd: root, bytes: Buffer.byteLength(capped, "utf8"), isSubagent: ctx.isSubagent, gitOk, ...(gitDropReason ? { gitDropReason } : {}), claudeTruncated, ...(hitFile ? { instructionFile: hitFile } : {}), ...(ctx.phase ? { phase: ctx.phase } : {}), cacheSize: cache.size });
         if (!capped)
-            return null;
+            return { walked: true, answer: null, instructionFile };
         if (hitFile && hitHash) {
             return {
-                content: capped,
-                instructionSources: [
-                    ...INSTRUCTION_FILE_CHAIN.slice(0, hitIndex).map((rel) => ({ path: join(root, rel), contentHash: ABSENT_HASH })),
-                    { path: join(root, hitFile), contentHash: hitHash },
-                ],
+                walked: true,
+                answer: {
+                    content: capped,
+                    instructionSources: [
+                        ...INSTRUCTION_FILE_CHAIN.slice(0, hitIndex).map((rel) => ({ path: join(root, rel), contentHash: ABSENT_HASH })),
+                        { path: join(root, hitFile), contentHash: hitHash },
+                    ],
+                },
+                instructionFile,
             };
         }
-        return capped;
+        return { walked: true, answer: capped, instructionFile };
     }
 }
 export function makeProbeInstructionSources() {

package/dist/run-local.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { type Brain, type OnAsk, type TaskSpec } from "@sema-agent/core";
+import { type AskRequest, type Brain, type TaskSpec } from "@sema-agent/core";
 import { type ApprovalBaselineConfigView, type DeploymentGovernanceConfigView } from "./deployment-governance.js";
 import { type ServiceConfig } from "./config.js";
 import { type Logger } from "./observability/logger.js";
@@ -77,9 +77,12 @@ export interface LocalGovernanceConfigView extends DeploymentGovernanceConfigVie
  * 叠上部署治理段(autonomy / commandPolicy / MANUAL_MODE_SHELL_GATE / 守卫集)。本函数一条 policy 都不
  * 自己合成。
  *
- * · **审批基线 = adjudicated allow-all**:一次性 CLI 没有 durable 审批设施(没有 `/decide` 腿可赎回),
- *   所以 `createApprovalBaselinePolicy` 走 durable 缺席那一臂。它是一条**在场的** effect-aware 策略
- *   (满足 core 的 `hasEffectAwareGate`),运维照旧用 `AUTONOMY` / `commandPolicy` / 守卫集在其上收紧。
+ * · **审批基线 = live 席**({@link RUN_LOCAL_APPROVAL_SEAT},S-694):一次性 CLI 没有 durable 审批设施(没有
+ *   `/decide` 腿可赎回),但**有**一只活 onAsk 席({@link createLocalApprover})。三张审批名单因此与 HTTP 腿
+ *   **同一只**策略执法(`createDurableAskPolicy`:deny ⇒ 拒;require / never-auto ⇒ ask ⇒ 那只席当场服),
+ *   不叠 durable 问答门。修前本腿不传席 ⇒ 落 allow-all 臂 ⇒ 名单在 CLI 上无声空转 —— [ref] 件一把「没有
+ *   durable 赎回腿」等同成了「ask 无处可服」,可件三同窗装上的正是那只服 ask 的席。运维照旧用
+ *   `AUTONOMY` / `commandPolicy` / 守卫集在其上收紧。
  * · **裁决 env 恒 host 形,锚 `workspaceDir`**:run-local 的手就跑在这台机器的这个目录上
  *   (`--workspace` / config.d workdir / cwd 三选一,调用方已解析好),所以 `cwd` 恒在场 —— 相对形写目标
  *   由 core 按 `rootPath` 解析进真身裁决,构造口的词法补层(沙箱腿那条)在这里自动不铺。
@@ -122,27 +125,26 @@ export interface LocalApproverIo {
  * ⛔ **不在 toolPolicy 层做 ask→deny 映射**:core 自己就有 headless auto-deny 的语义与文案,在策略层
  * 复刻一份 = 同源谎(两处判据日后各改各的)。裁决归 core,座位归这里。
  *
+ * 🔴 S-694 起本席也服**三张审批名单**产的 ask(审批基线取 live 席,见 {@link RUN_LOCAL_APPROVAL_SEAT}):
+ * `APPROVAL_REQUIRE` / `APPROVAL_NEVER_AUTO` 命中 ⇒ 策略 `ask` ⇒ 落到这里。`AskRequest` 不带是哪条声明产的
+ * ask(core 把 `matchedAskRule` 刻意留在闸内、不上请求),所以无 TTY 拒句**列出**可能产门的全部旋钮,
+ * `APPROVAL_DENY` 也点名(它当场拒、不经本席 —— 运维排查「为什么这只工具不跑」时要在同一句里看到它)。
+ *
  * 🔴 非 TTY 臂答 `false`(真 deny),**绝不答 `"unavailable"`**:后者被 core 读成「席位够不到」并**改道
  * `suspendAsk`**(dist `core/hooks.js` 的 `approverUnavailable` 重投)。今天本腿无店 ⇒ 那条改道无处
  * 可去(fail-closed 拒),但这一条仍是本席的契约:答案是「不批」,不是「找不到人」。
  */
-export declare function createLocalApprover(io: LocalApproverIo): OnAsk;
-/** 默认的 TTY 问人器:一问一答,回答写 **stderr**(stdout 是任务结果的专用管道,别污染它)。
- *  streams 可注入=EOF/abort 两臂测得动(默认 process.stdin/stderr)。
- *
- *  🔴 决断三臂(codex 验收轮 high,红先修):`readline/promises` 的 `question` 在输入流 EOF/close 时
- *  **不决**(promise 悬挂)——Ctrl-D、关闭的 stdin、任务取消都会把 runLocal 永久挂住,文件后端的锁
- *  跟着被拖住,下一次同 root 调用直接卡死。三臂全部 fail-closed 决 false:
- *   · `signal` abort(core `OnAsk` 递进来的取消,含预先 aborted);
- *   · readline `close`(输入流 end/close 时 readline 自关);
- *   · `question` 自身 reject(abort throw / 流错误)。 */
+/** 本席的形:core `OnAsk` 的函数臂(`"allow"` / `"deny"` 两个字面臂本席从不用),答案恒是布尔 —— 结构上可赋给 `OnAsk`。 */
+export type LocalApprover = (req: AskRequest, signal?: AbortSignal) => Promise<boolean>;
+export declare function createLocalApprover(io: LocalApproverIo): LocalApprover;
 export declare function promptYesNoOnTty(prompt: string, signal?: AbortSignal, streams?: {
     input: NodeJS.ReadableStream;
     output: NodeJS.WritableStream;
 }): Promise<boolean>;
 /**
  * Boot the engine in LOCAL mode, run ONE task to completion, print the result. Returns the process exit
- * code (0 = completed, 1 = the task did not complete / a fatal error, 2 = bad usage / unmet env). Pure of
+ * code (0 = completed its work, 1 = the task did not complete — including a `completed` run that a person stopped,
+ * see {@link personStopOf} — / a fatal error, 2 = bad usage / unmet env). Pure of
  * `process.exit` so a test can assert the code; `main()` applies it.
  */
 export declare function runLocal(argv: string[], deps?: RunLocalDeps): Promise<number>;