@sema-agent/server 7.97.0 → 7.99.0

package/dist/hosted-posture.js

@@ -1,45 +1,21 @@
 import { TASK_WRITE_FACE_ESCALATIONS } from "./config-types.js";
 import { deviceCwdHonored } from "./task-cwd.js";
-export const HOSTED_EVIDENCE_WORDS = ["require-principal", "principal-jwt", "auth-bridge-issuer"];
+export const HOSTED_EVIDENCE_WORDS = ["require-principal"];
 export function buildHostedPosture(c) {
     const evidence = [];
     if (c.requirePrincipal === true)
         evidence.push("require-principal");
-    if (c.principalJwtPubkeys.length > 0 || c.principalJwtIss !== undefined || c.principalJwtAud !== undefined)
-        evidence.push("principal-jwt");
-    if (c.authBridgeIssuer !== undefined)
-        evidence.push("auth-bridge-issuer");
     return { hosted: evidence.length > 0, evidence };
 }
-export const HOSTED_EVIDENCE_ENV_KEYS = ["PRINCIPAL_JWT_PUBKEYS", "PRINCIPAL_JWT_ISS", "PRINCIPAL_JWT_AUD", "AUTH_BRIDGE_ISSUER"];
-export function clearHostedEvidenceEnv() {
-    delete process.env.PRINCIPAL_JWT_PUBKEYS;
-    delete process.env.PRINCIPAL_JWT_ISS;
-    delete process.env.PRINCIPAL_JWT_AUD;
-    delete process.env.AUTH_BRIDGE_ISSUER;
-}
 export function hostedEvidenceNote(e) {
     switch (e) {
         case "require-principal":
             return "REQUIRE_PRINCIPAL=true (this deployment declares itself multi-tenant)";
-        case "principal-jwt":
-            return "PRINCIPAL_JWT_PUBKEYS/ISS/AUD is configured (principal identities are verified against an external issuer — a single-user turnkey box has no issuer)";
-        case "auth-bridge-issuer":
-            return "AUTH_BRIDGE_ISSUER is set explicitly (a second external SSO-JWT issuer; the registry-URL fallback is deliberately NOT read here — that fact is fleet management, not tenancy)";
     }
 }
 function hostedBecause(facts) {
     return facts.evidence.map(hostedEvidenceNote).join("; ");
 }
-export function hostedPrincipalRefusal(c) {
-    const facts = buildHostedPosture(c);
-    if (!facts.hosted || c.requirePrincipal === true)
-        return undefined;
-    return (`this deployment looks HOSTED/multi-tenant (${hostedBecause(facts)}) but REQUIRE_PRINCIPAL is not set — ` +
-        `an absent principal takes the single-user "default" amnesty, which would list every ownerless session to every caller ` +
-        `and open the single-user capability grants (settings.hooks / settings.env / cwd / additionalDirectories) to all of them. ` +
-        `Set REQUIRE_PRINCIPAL=true (and OPERATOR_PRINCIPALS for the operator-only routes), or remove the hosted-deployment configuration if this really is a single-user box.`);
-}
 export const HOST_POSTURE_REFUSED_CODE = "request.host_posture_refused";
 function hostPostureDeclarationsHonored(c) {
     if (deviceCwdHonored(c))

package/dist/memory-scope.d.ts

@@ -1,6 +1,7 @@
 import { FileMemoryEngineBackend, type TaskSpec } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
 import { type ExecutionLane } from "./execution-lane-caps.js";
+import { type MemoryProjectKey } from "./project-identity.js";
 /** 前缀词表本体(供门/诊断读;判定一律走 {@link isV2ScopeKey},别在别处重写 startsWith 链)。 */
 export declare const V2_SCOPE_PREFIXES: readonly string[];
 /**
@@ -12,17 +13,22 @@ export declare const V2_SCOPE_PREFIXES: readonly string[];
  * 校验点 fail-loud。
  */
 export declare function isV2ScopeKey(key: string): boolean;
-/** Resolve the memory scope for a request ([ref] S1 — the file-based memory engine is the only plane).
+/** Resolve the memory scope for a request —— {@link memoryScopeFor} 的三形(按实现逐臂写;S-512 合并前主会话点名:
+ *  旧版这里写「多租户恒 `undefined` ⇒ 记忆暗」,与下面 DB 后端那一臂正好相反,test [ref] 就是被这句带偏的)。
  *
- *  SINGLE-USER (REQUIRE_PRINCIPAL !== "true"): ONE shared scope — `config.memoryScope` (default "local"),
- *  regardless of any principal label the caller self-reports (a single-user worker's `anon:*` / ad-hoc
- *  principals are surface labels, not isolation identities — keying memory by them would split the one
- *  user's memory across surfaces). Explicit `MEMORY_SCOPE` wins (it IS config.memoryScope).
- *
- *  MULTI-TENANT (REQUIRE_PRINCIPAL=true): always `undefined` ⇒ no `spec.memory` ⇒ memory is DARK,
- *  fail-closed. The engine's file basement carries NO tenant isolation (one shared directory tree), so
- *  handing tenants per-principal scopes over it would be a cross-tenant bleed surface; until a
- *  tenant-isolated backend exists, multi-tenant memory is off by construction. */
+ *  ① SINGLE-USER(`requirePrincipal !== true`):返回**全局层** `config.memoryScope`(缺省 "local";显式
+ *     `MEMORY_SCOPE` 就是它),与调用方自报的 principal 标签无关(单用户 worker 的 `anon:*` / 临时 principal
+ *     是面上的标签,不是隔离身份 —— 按它们键控会把一个用户的记忆拆散到各个面)。🔴 S-512([ref] ①)起它只是
+ *     **读列表的第二层**,不是写家:写家是该任务的**项目层**,由 {@link memoryProjectKeyFor} 按任务根派生、经
+ *     {@link memorySpecForRequest} 的 `projectKey` 位铸进 spec(读 = [项目, 本 scope],`writeScope` 显式 = 项目)。
+ *     本函数在授权期调(还不知道任务根),所以项目层不在这里。
+ *  ② MULTI-TENANT + DB 后端(`requirePrincipal === true` ∧ `memoryEngineBackend` ∈ {`pg`, `tidb`}):按**验过的**
+ *     principal 铸 v2 typed 键 —— 无 projectId ⇒ `user:<tenant>`(core `formatUserScope`),有形状合法的
+ *     projectId ⇒ `proj:<tenant>/<projectId>`(core `formatProjScope`);principal 缺席(匿名 run)⇒ `undefined`
+ *     (无记忆)。scope 列是租户分区,授权就是「验过的 principal 进、一个租户的 scope 出」这一绑定;身份永远不来自
+ *     body(projectId 只挑盘)。本形**不**按项目根键控(同一租户跨项目共用 `user:` 层是另一件事,S-626,待设计与裁定)。
+ *  ③ MULTI-TENANT + file 后端:`undefined` ⇒ 没有 `spec.memory` ⇒ 记忆**暗**,fail-closed —— file 引擎底座是一棵共享
+ *     目录树、没有租户隔离,在它上面给租户按 principal 发 scope 就是跨租户串盘面。 */
 /** R5(批γ):memory scope 列宽(两方言 VARCHAR(190) 同宽)。principal 上限 190 **字符**在
  *  security.ts 把身份轴守住了,但 `formatUserScope`/`formatProjScope` 的段编码(百分号转义)会
  *  **膨胀**——非 ASCII principal 编码后可超列宽,此前落裸 SQL 错。产出处响亮拒,错误可分类。
@@ -31,6 +37,43 @@ export declare function isV2ScopeKey(key: string): boolean;
  *  只再导出——旧 import 路径(本文件)逐字不变,`memoryScopeFor` 的产出处消费点也不变。 */
 export { MEMORY_SCOPE_COLUMN_CHARS, assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
 export declare function memoryScopeFor(config: ServiceConfig, principal?: string, projectId?: string): string | undefined;
+/**
+ * S-512 / [ref] ① —— 这一请求的**项目身份声明**(`TaskSpec.memory.projectKey`)的唯一属主。
+ *
+ * **一条规则,与车道无关**(主会话 09-23 裁 ②):项目根 = spec 解析出的**真任务根**(`boot/resolve-spec.ts`
+ * 的 `realTaskRootOf`,S-177 属主;run-local 腿 = 它的 `workspaceDir`)。本进程读得到这个根 ⇒ 求 canonical
+ * 项目根并铸 `repo:` 键(in-process 车道的真任务根是 `process.cwd()`,读得到,所以照常铸 —— 它的语义就是
+ * 「项目 = 任务根指向的地方」,不需要另一个词);读不到(根在沙箱/设备盘上,或 host 车道会话没登记 cwd、
+ * spec 期还不知道根)⇒ 调用方传 `undefined` ⇒ `{ absent: "unreadable" }`,core 铸 operator 通知
+ * `memory.project_scope_absent`,写照常落全局层 —— **响亮**,不是静默落 `local`。
+ *
+ * 🔴 **写家只落复制路径覆盖得到的层**(7.98.0 合并复审 F1,主会话裁「统一规则,不做特判」):写家 = 读列表里、本部署
+ * **每一条已配置的复制路径都覆盖到**的最具体的一层。项目层不在覆盖面里 ⇒ 本任务**不按项目键控**,写家落全局层,
+ * 读列表与 7.97.0 同形 —— 否则开了 `MEMORY_SYNC_*` 的部署会把新记忆写进一个同步腿从不碰的层(静默不同步)。
+ * 覆盖面只经 {@link memoryReplicationCoverage} 求(调用点零 `if (memorySync)`);以后项目层同步落地,只改覆盖面的
+ * 来源,本规则不动。让位由启动通知 `memory_project_scope_yields_to_sync` 说出来(`config.ts` 记忆域,读同一只覆盖面)。
+ * 缺席声明(`{ absent }`)不受覆盖面影响:它本来就写全局层,通知说的是「为什么没有项目层」。
+ *
+ * 返回 `undefined` 只有三形,都不是「忘了」:
+ *  · 多租户(`requirePrincipal`)—— 项目层键控在多租户上另立(S-406 §3;principal 形 `user:`/`proj:` 不变);
+ *  · 记忆面暗(`scope` 缺席)—— 没有 spec 可铸,也就不读盘;
+ *  · 本任务的项目层不在复制覆盖面里(见上)—— 让位给全局层。
+ */
+export declare function memoryProjectKeyFor(config: Pick<ServiceConfig, "requirePrincipal" | "memorySync">, scope: string | undefined, taskRoot: string | undefined): MemoryProjectKey | undefined;
+/**
+ * 本部署记忆的**复制覆盖面** —— 唯一属主(7.98.0 合并复审 F1)。「复制路径」= 把某一层记忆搬出本机的腿;今天只有一条:
+ * TOC 同步客户端腿(`MEMORY_SYNC_*`,`memory-sync-client.ts`),它只同步**一层**(`config.memorySync.scope`,core
+ * `syncMemoryScope` 按 `scope ===` 取条目)。没有复制路径 ⇒ `unreplicated`(没有哪一层会被复制落下)。
+ */
+export type MemoryReplicationCoverage = {
+    readonly kind: "unreplicated";
+} | {
+    readonly kind: "scopes";
+    readonly scopes: readonly string[];
+};
+export declare function memoryReplicationCoverage(config: Pick<ServiceConfig, "memorySync">): MemoryReplicationCoverage;
+/** 覆盖面是否含这一层(`unreplicated` 含一切)。 */
+export declare function replicationCovers(coverage: MemoryReplicationCoverage, scope: string): boolean;
 /**
  * N0 (通宵测试 2026-07-09,三重坐实 e2b+kata+代码): the file memory engine (core [ref]) materializes and
  * harvests via `node:fs` on the WORKER's local fs, while a remote exec lane routes the model's file tools to
@@ -184,7 +227,14 @@ onIncident?: (err: Error & {
  * harvest 不提交)· `memoryCapture:"off"` = 采集面关(挂、读、本会话内容永不进长期记忆)· `memory:"off"` =
  * **整面关**(`enabled:false`,这一次连记忆面都不挂)。后两者从 `declarations` 进(键名与 wire 逐字同名)。
  */
-export declare function memorySpecForRequest(scope: string | undefined, memoryWrite: boolean | undefined, defaultScopes?: string[], 
+export declare function memorySpecForRequest(scope: string | undefined, 
+/** S-512 / [ref] ①:本请求的项目身份声明({@link memoryProjectKeyFor} 的产物)。**必填位**(不是可选参数):
+ *  每个铸点都得写出一个值 —— `undefined` 只合法地表示「本任务不按项目键控」(多租户 / 记忆暗 / 项目层不在复制覆盖面里)。
+ *  · `{ scope: repoKey }` ⇒ 读 = `[repoKey, scope, ...extras]`、`writeScope` **显式** = `repoKey`(core 缺省取末层
+ *    = 全局层,不钉就是 M-03 本身;core 另有 `config.memory_write_scope_mismatch` 兜这一向);
+ *  · `{ absent }` ⇒ 读 = `[scope, ...extras]`、`writeScope` 显式 = `scope`(全局层),core 铸 `memory.project_scope_absent`;
+ *  · 两形都把声明原样落 `TaskSpec.memory.projectKey`(core 的生效面回显它)。 */
+projectKey: MemoryProjectKey | undefined, memoryWrite: boolean | undefined, defaultScopes?: string[], 
 /** [ref] 件A([ref] 件3④):origin 盖章的部署形态维(N2)。`multiTenant=true`(requirePrincipal)
  *  ⇒ 登记簿 defaultScopes 的 org 键按 **request** 盖章(条目由调用方 projectId 选定=caller 可影响的
  *  选择器,core 准入门据此过目录判决);单用户 ⇒ 一律 deployment(operator 登记簿条目归 deployment,
@@ -219,6 +269,7 @@ declarations?: {
     scopeOrigins?: Record<string, "deployment" | "request">;
     capture?: "off";
     enabled?: false;
+    projectKey?: MemoryProjectKey;
 } | undefined;
 /**
  * 「这一腿挂不挂记忆面」的**唯一属主**(合并复审 车HF F1,2026-09-18):与 core `prepareMemory` 的判据同源 ——

package/dist/memory-scope.js

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { FileMemoryEngineBackend, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope, normalizeMemorySpec } from "@sema-agent/core";
 import { executionLaneCaps, executionLaneOf } from "./execution-lane-caps.js";
 import { assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
+import { projectKeyForTaskRoot } from "./project-identity.js";
 const V2_SCOPE_PREFIX_BY_KIND = {
     user: "user:",
     org: "org:",
@@ -26,6 +27,25 @@ export function memoryScopeFor(config, principal, projectId) {
     }
     return config.memoryScope;
 }
+export function memoryProjectKeyFor(config, scope, taskRoot) {
+    if (config.requirePrincipal === true || scope === undefined)
+        return undefined;
+    const declared = projectKeyForTaskRoot(taskRoot);
+    if (declared.scope !== undefined && !replicationCovers(memoryReplicationCoverage(config), declared.scope))
+        return undefined;
+    return declared;
+}
+export function memoryReplicationCoverage(config) {
+    return config.memorySync === undefined ? { kind: "unreplicated" } : { kind: "scopes", scopes: [config.memorySync.scope] };
+}
+export function replicationCovers(coverage, scope) {
+    switch (coverage.kind) {
+        case "unreplicated":
+            return true;
+        case "scopes":
+            return coverage.scopes.includes(scope);
+    }
+}
 export function memoryEngineRemoteLanePosture(config) {
     const lane = executionLaneOf(config.remoteExec?.provider);
     if (executionLaneCaps(lane).hostFilePlane === "supported")
@@ -97,12 +117,21 @@ export function memoryEngineBackendFor(config, fallbackRoot, onIncident) {
         root: plane.root,
     };
 }
-export function memorySpecForRequest(scope, memoryWrite, defaultScopes, originPolicy, declarations) {
+export function memorySpecForRequest(scope, projectKey, memoryWrite, defaultScopes, originPolicy, declarations) {
     if (!scope)
         return undefined;
+    const projectScope = projectKey?.scope;
+    if (projectScope !== undefined && projectScope === scope) {
+        throw new Error(`memory project scope ${JSON.stringify(projectScope)} equals the global memory scope (MEMORY_SCOPE) — the project layer and the global layer would be one directory. ` +
+            "Set MEMORY_SCOPE to a name outside the server-minted project-key family (see src/project-identity.ts).");
+    }
     const isV2 = isV2ScopeKey;
-    const extras = (defaultScopes ?? []).filter((s, i, arr) => typeof s === "string" && s.length > 0 && s !== scope && arr.indexOf(s) === i);
-    const layered = extras.length > 0 ? { scopes: [scope, ...extras], writeScope: scope } : { scopes: [scope] };
+    const extras = (defaultScopes ?? []).filter((s, i, arr) => typeof s === "string" && s.length > 0 && s !== scope && s !== projectScope && arr.indexOf(s) === i);
+    const layered = projectKey !== undefined
+        ? { scopes: projectScope !== undefined ? [projectScope, scope, ...extras] : [scope, ...extras], writeScope: projectScope ?? scope, projectKey }
+        : extras.length > 0
+            ? { scopes: [scope, ...extras], writeScope: scope }
+            : { scopes: [scope] };
     const v2 = isV2(scope) || extras.some(isV2) ? { scopeContract: "v2" } : {};
     const stamped = {};
     if (originPolicy !== undefined) {

package/dist/model-provider.d.ts

@@ -74,4 +74,17 @@ export declare function modelBrainLane(provider: ModelProvider): ModelBrainLane;
  * 在这里加一个 throw 会让一次热发布打死在跑的副本,方向反了。
  */
 export declare function catalogBrainLane(provider: string | undefined): ModelBrainLane;
+/**
+ * 🔴 S-623 —— 一条目录条目在**本部署**上真正落哪条 brain 腿(= `createBrain` 的组装事实,不是词面)。
+ *
+ * `createBrain` 只在 anthropic 路由**装上**(`ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 在场 ⇒
+ * `config.anthropic` 在场)时才铸 `createRoutingBrain({anthropic}, {fallback: gatewayStack})`;没装时整台机器
+ * 只有网关栈这一只 brain,**一切**条目(包括 `provider:"anthropic"` 的)都落 openai 兼容腿 ——
+ * `apply-effective.ts` 那条 `sema_registry_model_no_brain` warn 说的「mis-routes to the gateway brain」即此。
+ *
+ * 所以「这条路由要不要一个 openai 端点」的判据必须同时看词与装配:词判 {@link catalogBrainLane},
+ * 装配判路由在不在。本函数是这一合取的**唯一**写法 —— 端点判官(`model-route-endpoint.ts`)、降级腿与
+ * 启动摘要(`brain.ts`)都调它,不再各写一个 `=== "anthropic" && config.anthropic`。
+ */
+export declare function dispatchBrainLane(provider: string | undefined, anthropicRouteMounted: boolean): ModelBrainLane;
 //# sourceMappingURL=model-provider.d.ts.map

package/dist/model-provider.js

@@ -23,4 +23,7 @@ export function modelBrainLane(provider) {
 export function catalogBrainLane(provider) {
     return isModelProvider(provider) ? modelBrainLane(provider) : "gateway";
 }
+export function dispatchBrainLane(provider, anthropicRouteMounted) {
+    return anthropicRouteMounted && catalogBrainLane(provider) === "anthropic" ? "anthropic" : "gateway";
+}
 //# sourceMappingURL=model-provider.js.map

package/dist/model-route-endpoint.d.ts

@@ -0,0 +1,82 @@
+/**
+ * S-623 —— **openai 兼容路由的有效端点**:解析规则与「解析不到」的拒因,唯一属主。
+ *
+ * ## 病(事实,主会话 09-23 12:40 亲核 + cli L-589 真案)
+ * `MODEL_GATEWAY_BASEURL` 曾有一个出厂缺省(本机 8000 端口的 `/v1`)。缺省值在读入那一步就把「来源」抹掉了:
+ * 只设 `MODEL_ID` + key 的隔离配置照常起,第一次模型调用才在 core 的 `describeNetworkError` 里炸成
+ * `fetch failed (connect ECONNREFUSED …:8000)` —— core 不知道、也不该知道那个端点是缺省值;compose 的
+ * `${MODEL_GATEWAY_BASEURL:-}` 透传空串 ⇒ 落到**容器自身回环**,恒错;本仓 `run-local` 的预检注释写着「本机
+ * 用户必须指向自己的网关」,判据却只查 `/v1` 后缀,缺省值照样过。紧邻的 `MODEL_ID` 自 3.0.0 起同病同治
+ * (「旧缺省让每个外部部署都炸在离根因最远的地方」)。
+ *
+ * ## 规则(一句)
+ * **`MODEL_GATEWAY_BASEURL` 没有出厂缺省;配置能派发到的每一条 openai 兼容路由,都必须解析到一个显式配置的
+ * base URL(路由自己的 `baseUrl`,或显式设了的网关),否则拒。** 附带一条同类:备用网关
+ * (`MODEL_GATEWAY_FALLBACK_URLS`)是主网关的镜像,没有主就没有镜像 ⇒ 拒。
+ *
+ * ## 执法点(判据只在这里,执法点在调用处 —— 与 S-475 `gateway-url-userinfo` 同形)
+ *  · boot:`config.ts` 九域解析之后的跨域不变量区(锚 `CROSS-INVARIANT:model-route-endpoint`)⇒ 拒启;严格名册
+ *    布防(`isRosterGateArmed`)时 env 腿是占位、从不被派发 ⇒ 不判它(备用网关那一条照判);
+ *  · 热路径:`config-center/apply-effective.ts` 的模型面 stage ⇒ 候选整批拒、上一代继续服务;
+ *  · run-local:配置源解析完之后按真要派发的表再判一次(`run-local.ts`,7.98.0 合并复审 F2)—— 本入口没有名册门,
+ *    loadConfig 对严格名册布防的占位豁免在这里兑现不了;没布防时恒惰性;
+ *  · 登记:`config-invariants.ts` 的 `model-route-endpoint` 条(表的「不许有表外不变量」职责);
+ *  · 派发面:titler / hook 选模型(`hooks/hook-llm.ts`)与降级腿 / 启动摘要(`brain.ts`)求有效端点时调
+ *    {@link openaiRouteBaseUrl},不再各写一个 `model.baseUrl || gatewayBaseUrl`。
+ *
+ * ## 三问
+ *  · **谁需要**:忘设端点的本机 / 隔离配置用户与 compose 直用者(cli L-589)—— 他们今天起得来、第一次调用才炸;
+ *  · **谁受伤**:隐式依赖本机 8000 网关(如 vLLM 缺省端口)的部署,从「照常起」变成「拒启」;
+ *  · **补偿**:显式写一行 —— 拒因原样给出这一行({@link LOCAL_GATEWAY_HINT})。
+ *
+ * 依赖纪律:本文件是**叶**(只引 provider 词表与目录缺省别名),`config.ts` / `config-invariants.ts` /
+ * `brain.ts` / `hooks/hook-llm.ts` 都可以安全引它。
+ */
+import type { Model } from "@sema-agent/core";
+/** 机读码(拼法随 `config.*` 家族,按**规则**命名不按键名):一条 openai 路由解析不到端点。 */
+export declare const MODEL_ROUTE_ENDPOINT_MISSING_CODE = "config.model_route_endpoint_missing";
+/** 同族第二码:备用网关设了、主网关没设。与上一码分开是因为出路不同(补主网关 / 撤备用 vs 补主网关 / 给条目 baseUrl)。 */
+export declare const GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE = "config.gateway_fallback_without_primary";
+/**
+ * 拒因给出的**本机网关显式写法**。`src/` 里本机 8000 那个字面的**唯一**住处 —— 源码门钉在
+ * `test/config-gateway-endpoint-required.test.ts` ⑧(出现在别处 = 有人又在铸缺省)。
+ */
+export declare const LOCAL_GATEWAY_HINT = "MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1";
+/**
+ * **一条 openai 兼容路由的有效 base URL** —— 路由自己的 `baseUrl` 胜,否则显式设了的网关;都没有 ⇒ `undefined`。
+ *
+ * 与 core 请求期的解析(`resolveRequestRoot(model.baseUrl, config.baseUrl)`,entry 胜、declared 次之)
+ * 同序同尺;区别只在这里**没有**第三档 —— 本仓不给 core 递任何「车道缺省」,缺席就是缺席。
+ */
+export declare function openaiRouteBaseUrl(routeBaseUrl: string | undefined, gatewayBaseUrl: string | undefined): string | undefined;
+/** 派发面用的单条形(titler / hook 选模型):有效端点,或一句可以原样交给运维的拒因。 */
+export type OpenaiRouteEndpoint = {
+    readonly ok: true;
+    readonly baseUrl: string;
+} | {
+    readonly ok: false;
+    readonly refusal: string;
+};
+/** 单条 openai 路由的有效端点 / 拒因(拒因与部署级判据是**同一只**铸点 {@link routeEndpointMissingRefusal})。 */
+export declare function resolveOpenaiRouteEndpoint(routeName: string, routeBaseUrl: string | undefined, gatewayBaseUrl: string | undefined): OpenaiRouteEndpoint;
+/** 部署级判据读的切面(`ServiceConfig` 与 `CrossInvariantView` 都结构满足)。 */
+export interface ModelRouteEndpointView {
+    readonly gatewayBaseUrl?: string;
+    readonly gatewayFallbackUrls: readonly string[];
+    /** 在场 = anthropic 路由装上(`createBrain` 同判)。只读在场性。 */
+    readonly anthropic?: object;
+    readonly models: Readonly<Record<string, Pick<Model, "baseUrl" | "provider">>>;
+}
+/**
+ * **部署级判据**:这份配置能派发到的每一条 openai 兼容路由都解析得到端点吗?`undefined` = 是。
+ *
+ * 判序即语义:
+ *  ① 备用网关设了、主网关没设 ⇒ `config.gateway_fallback_without_primary`(备用是主的镜像,这一条与条目无关,先说);
+ *  ② 逐条目:按 {@link dispatchBrainLane} 落 openai 腿、且 {@link openaiRouteBaseUrl} 解析不到 ⇒ 收集名字,
+ *     一句话**全部点名**(运维一次改完,而不是改一个撞下一个)。
+ *
+ * `default` 键是目录里另一条的别名(env 腿 `{default: m, [m.id]: m}`、center 腿 `models.default = models[picked]`),
+ * 与别的键指同一只对象时不重复点名;只有它一个键时(手搓夹具)照样点名 `default`。
+ */
+export declare function modelRouteEndpointRefusal(view: ModelRouteEndpointView): string | undefined;
+//# sourceMappingURL=model-route-endpoint.d.ts.map

package/dist/model-route-endpoint.js

@@ -0,0 +1,55 @@
+import { dispatchBrainLane } from "./model-provider.js";
+import { DEFAULT_MODEL_REF } from "./model-select.js";
+export const MODEL_ROUTE_ENDPOINT_MISSING_CODE = "config.model_route_endpoint_missing";
+export const GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE = "config.gateway_fallback_without_primary";
+export const LOCAL_GATEWAY_HINT = "MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1";
+function declared(url) {
+    return url !== undefined && url.trim() !== "" ? url : undefined;
+}
+export function openaiRouteBaseUrl(routeBaseUrl, gatewayBaseUrl) {
+    return declared(routeBaseUrl) ?? declared(gatewayBaseUrl);
+}
+export function resolveOpenaiRouteEndpoint(routeName, routeBaseUrl, gatewayBaseUrl) {
+    const baseUrl = openaiRouteBaseUrl(routeBaseUrl, gatewayBaseUrl);
+    return baseUrl !== undefined ? { ok: true, baseUrl } : { ok: false, refusal: routeEndpointMissingRefusal([`"${routeName}"`]) };
+}
+export function modelRouteEndpointRefusal(view) {
+    const gateway = declared(view.gatewayBaseUrl);
+    if (gateway === undefined && view.gatewayFallbackUrls.length > 0) {
+        return (`env MODEL_GATEWAY_FALLBACK_URLS is set but MODEL_GATEWAY_BASEURL is not [${GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE}] — ` +
+            "the fallback URLs are mirrors of the primary gateway (same provider, same account, same key scope), tried only " +
+            "after the primary fails; with no primary there is nothing to fail over from, and MODEL_GATEWAY_BASEURL has no " +
+            `factory default. Set MODEL_GATEWAY_BASEURL to the primary gateway (for one on this machine: ${LOCAL_GATEWAY_HINT}), ` +
+            "or unset MODEL_GATEWAY_FALLBACK_URLS.");
+    }
+    const anthropicMounted = view.anthropic !== undefined;
+    const entries = Object.entries(view.models ?? {});
+    const unresolved = [];
+    for (const [name, m] of entries) {
+        if (name === DEFAULT_MODEL_REF && entries.some(([k, other]) => k !== name && other === m))
+            continue;
+        if (dispatchBrainLane(m.provider, anthropicMounted) !== "gateway")
+            continue;
+        if (openaiRouteBaseUrl(m.baseUrl, gateway) !== undefined)
+            continue;
+        unresolved.push(m.provider === "anthropic"
+            ? `"${name}" (provider "anthropic", but no Anthropic route is mounted — ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN are unset — so it falls to the openai-compatible lane)`
+            : `"${name}"`);
+    }
+    return unresolved.length > 0 ? routeEndpointMissingRefusal(unresolved) : undefined;
+}
+function routeEndpointMissingRefusal(quotedNames) {
+    const one = quotedNames.length === 1;
+    const subject = one ? `model ${quotedNames[0]} rides` : `models ${quotedNames.join(", ")} ride`;
+    return (`${subject} the openai-compatible lane but ${one ? "resolves" : "resolve"} to no endpoint ` +
+        `[${MODEL_ROUTE_ENDPOINT_MISSING_CODE}] — ${one ? "it has no" : "none has a"} baseUrl of its own, and MODEL_GATEWAY_BASEURL is unset. ` +
+        "MODEL_GATEWAY_BASEURL has no factory default: the former silent placeholder (this machine's port 8000) let such a " +
+        "deployment start fine and then fail on the first model call, far from the cause (\"fetch failed … ECONNREFUSED\", or " +
+        "a container dialling its own loopback when compose passes an empty value). " +
+        `Set it explicitly — for a gateway on this machine: ${LOCAL_GATEWAY_HINT} — or give ${one ? "that model" : "each named model"} its own baseUrl in the catalog. ` +
+        "(A model defined by MODEL_ID / MODEL_CHEAP_ID has no baseUrl of its own: it needs the gateway, or MODEL_PROVIDER=anthropic " +
+        "with ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN. It is judged at boot even when a catalog will replace it later — it is what this " +
+        "process serves whenever no catalog lands: the config source unreachable, a refused candidate, or zero enabled models — unless " +
+        "CONFIG_REQUIRE_ROSTER=true on a remote registry declares it a placeholder that is never served.)");
+}
+//# sourceMappingURL=model-route-endpoint.js.map

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

@@ -1,28 +1,4 @@
-/**
- * [ref]([ref])—— **密钥形 env 剥除的留痕面**(core D1 `scrubSecretEnv` 的可观测半场)。
- *
- * ## 它解决的问题
- * `scrubSecretEnv` 是本仓两条 shell/子进程腿的**安全默认**:模型可驱动的 shell(`inheritEnv:"scrub"`)与
- * git 子进程(钩子/凭证助手)拿到的 env 里,`*_KEY`/`*_TOKEN`/`*_SECRET`/`*_PASSWORD`… 一律先丢掉。
- * 两处都以**单参形**调用,于是「这一次到底丢了哪些 key、按哪条规则(suffix-rule / exact-name)、置信度多少」
- * **零留痕** —— 部署方既证明不了保护生效过,也发现不了它悄悄不生效了(词表漂移 / 一个新的密钥命名法从
- * 规则的缝里穿过去 / 某条腿被改成 `inheritEnv:"all"`)。core 早就把收集口开好了(`findings?:
- * SecretEnvFinding[]`,d.ts 原话:the VALUE is never carried — this record is meant to be loggable),
- * 缺的只是本仓这半场。本模块就是那半场,**不是**一个新的执法面:它一个字节也不改变剥除行为。
- *
- * ## 形(照 `fail-open.ts` 的仓内先例)
- *  1. **计数(逐次)** —— `secret_env_scrubbed_total{site,kind,confidence}`;
- *  2. **结构化披露(每 site×key 一次)** —— 首次在某条腿上丢掉某个 key 时一条 `info`,之后同 key 只走计数。
- *     不是「每 site 一次」:一个**新**的密钥形 key 后来才出现(部署加了一个凭证)时,那才是最该看见的一行。
- * 值永不进任何一件(core 的 finding 本身就不携带值)。
- *
- * ## 为什么是进程级自由函数而不是注入
- * 与 `recordFailOpen` 同因:两个调用点都在**没有 logger/metrics 句柄**的深处
- * (`plugins/remote-env-host.ts` 的 `mergeEnv` 全文零观测通道;`project-memory.ts` 的 `git()` 是个自由函数)。
- * 装配层用 {@link installSecretEnvScrubRecorder} 把句柄接上,装配之前命中的次数不会丢(计数照常累加,
- * install 时一次性补进 metrics),披露行则在下一次命中时补发(未成功披露的 key 不进 `disclosed` 集)。
- */
-import { type SecretEnvFinding } from "@sema-agent/core";
+import type { ServerSecretEnvFinding } from "../server-secret-env.js";
 import type { Logger } from "./logger.js";
 import type { Metrics } from "./metrics.js";
 /** 登记过的剥除现场。闭集:未登记的 site 传不进 {@link recordSecretEnvScrub}(编译期拒,同 FAIL_OPEN_TAGS 纪律)。 */
@@ -40,7 +16,7 @@ interface Sink {
  * 记一次剥除。**总不抛** —— 观测本身绝不能变成故障(同 `recordFailOpen` / reapers 的判据)。
  * `findings` 为空(这一次没丢任何 key)时什么也不做:那不是事件,是常态。
  */
-export declare function recordSecretEnvScrub(site: SecretEnvScrubSite, findings: readonly SecretEnvFinding[]): void;
+export declare function recordSecretEnvScrub(site: SecretEnvScrubSite, findings: readonly ServerSecretEnvFinding[]): void;
 /** 装配层把 logger/metrics 接上(main.ts,与 `installFailOpenRecorder` 同一处)。装配前累计的次数在此补进 metrics。 */
 export declare function installSecretEnvScrubRecorder(deps: Sink): void;
 /** 已留驻的「现场×键」条数(测试/诊断读面)。恒 ≤ {@link DISCLOSED_CAP}。 */

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

@@ -62,7 +62,7 @@ export function recordSecretEnvScrub(site, findings) {
 }
 export function installSecretEnvScrubRecorder(deps) {
     sink = { ...deps };
-    deps.metrics?.counter(SCRUB_COUNTER, "secret-pattern env entries dropped before spawning a child process, by site/rule/confidence (core scrubSecretEnv findings)");
+    deps.metrics?.counter(SCRUB_COUNTER, "secret env entries dropped before spawning a child process, by site/rule/confidence (core scrubSecretEnv shape rule + server config-catalog secret names)");
     drainToMetrics();
 }
 export function secretEnvScrubDisclosedSize() {
@@ -76,6 +76,6 @@ export function resetSecretEnvScrubRecorderForTest(deps = {}) {
     pushed = new Map();
     disclosed = new Set();
     sink = { ...deps };
-    deps.metrics?.counter(SCRUB_COUNTER, "secret-pattern env entries dropped before spawning a child process, by site/rule/confidence (core scrubSecretEnv findings)");
+    deps.metrics?.counter(SCRUB_COUNTER, "secret env entries dropped before spawning a child process, by site/rule/confidence (core scrubSecretEnv shape rule + server config-catalog secret names)");
 }
 //# sourceMappingURL=secret-env-scrub.js.map

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

@@ -33,6 +33,8 @@ export interface HostEnvConfig {
     commandTimeoutMs?: number;
     /** Shell-child env policy (D1; mirrors core's `NodeExecutionEnv`). Default `"scrub"`: inherit the worker's
      *  `process.env` but DROP secret-pattern keys (core's `scrubSecretEnv` — `*_KEY`/`*_TOKEN`/`*_SECRET`/`*_PASSWORD`…)
+     *  AND every env name the server's config catalog types as `secret` (`server-secret-env.ts`; 7.99.0 F7 —
+     *  `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. */
@@ -386,7 +388,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     private fsReady;
     /** Base env (process.env when inheriting) merged with the adapter's secret env, then per-command overrides win. */
     /** D1 secure default = `"scrub"`: inherit `process.env` minus secret-pattern keys (core's `scrubSecretEnv`, single
-     *  source of truth). `"all"` = full inherit (opt-out); a `string[]` = strict allowlist. Legacy `inheritProcessEnv`
+     *  source of the shape rule) minus the config catalog's `secret`-typed names (`scrubServerSecrets`, 7.99.0 F7). `"all"` = full inherit (opt-out); a `string[]` = strict allowlist. Legacy `inheritProcessEnv`
      *  maps `true`→`"all"` / `false`→`[]`. */
     private inheritMode;
     private mergeEnv;

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

@@ -9,8 +9,9 @@ import { armPipeDestroyGrace, numEnvOr, SYMLINK_CHAIN_MAX_HOPS } from "./remote-
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
-import { FileError, ExecutionError, RemoteExecutionError, scrubSecretEnv, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
+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 { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
@@ -1312,7 +1313,7 @@ export class RemoteHostExecutionEnv {
         }
         else {
             const findings = [];
-            base = scrubSecretEnv(process.env, findings);
+            base = scrubServerSecrets(process.env, findings);
             recordSecretEnvScrub("server.remote-env-host.inherit-scrub", findings);
         }
         if (this.cfg.env)

package/dist/project-identity.d.ts

@@ -0,0 +1,29 @@
+import type { TaskSpec } from "@sema-agent/core";
+/** core 的项目身份声明席(`TaskSpec.memory.projectKey`)—— 从 core 类型派生,不另写一份。 */
+export type MemoryProjectKey = NonNullable<NonNullable<TaskSpec["memory"]>["projectKey"]>;
+/** 本仓会说的缺席词。`not_git` 刻意排除:裁 D 起非 git 目录按目录键控,不是缺席(core 闭集仍收它,本仓不铸)。 */
+export type ProjectIdentityAbsentReason = Exclude<Extract<MemoryProjectKey, {
+    absent: unknown;
+}>["absent"], "not_git">;
+/** 一个任务根的项目身份:canonical 项目根,或说得出理由的缺席。 */
+export type ProjectIdentity = {
+    readonly root: string;
+} | {
+    readonly absent: ProjectIdentityAbsentReason;
+};
+/**
+ * 任务根 → 项目身份([ref] 四例;见文件头)。纯文件系统读,零子进程。
+ * `taskRoot` 必须是**本进程读得到**的路径(调用方按车道判:根在沙箱/设备盘上就别调,直接给 `unreadable`)。
+ *
+ * 一次向上走,规则三条按优先序:最近的 `.git`(① ② ③)> 链上最近的裸仓布局(④ bare)> 非 git 按目录键控(④)。
+ */
+export declare function resolveProjectIdentity(taskRoot: string): ProjectIdentity;
+/** 本仓**唯一**的 `repo:` 键铸点([ref] ①:`repo:` + sha256 hex 前 24;`root` 为 realpath 字符串,不加尾斜杠、不折大小写)。 */
+export declare function mintRepoScopeKey(projectRoot: string): string;
+/**
+ * 任务根 → core 声明席 `TaskSpec.memory.projectKey`。
+ * `taskRoot === undefined` = 调用方**此刻不知道**任务根在本机哪里(根在沙箱/设备盘上;或 host 车道会话没登记 cwd、
+ * 手落在 factory 现铸的临时目录)⇒ `unreadable` —— 「我看不到」,不是「这里没有项目」。
+ */
+export declare function projectKeyForTaskRoot(taskRoot: string | undefined): MemoryProjectKey;
+//# sourceMappingURL=project-identity.d.ts.map

package/dist/project-identity.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+const UNREADABLE = { absent: "unreadable" };
+const BARE = { absent: "bare" };
+function isMissing(err) {
+    const code = err?.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+function statFact(p) {
+    try {
+        const st = statSync(p);
+        return { ok: st.isDirectory() ? "dir" : st.isFile() ? "file" : "other" };
+    }
+    catch (err) {
+        return isMissing(err) ? "missing" : "unreadable";
+    }
+}
+function readTextFact(p) {
+    try {
+        return { ok: readFileSync(p, "utf8").trim() };
+    }
+    catch (err) {
+        return isMissing(err) ? "missing" : "unreadable";
+    }
+}
+function realpathFact(p) {
+    try {
+        return { ok: realpathSync.native(p) };
+    }
+    catch (err) {
+        return isMissing(err) ? "missing" : "unreadable";
+    }
+}
+function isBareRepoLayout(dir) {
+    if (basename(dir) === ".git")
+        return false;
+    const head = statFact(join(dir, "HEAD"));
+    const objects = statFact(join(dir, "objects"));
+    const refs = statFact(join(dir, "refs"));
+    return typeof head === "object" && head.ok === "file" && typeof objects === "object" && objects.ok === "dir" && typeof refs === "object" && refs.ok === "dir";
+}
+function identityOfGitFile(dir) {
+    const pointer = readTextFact(join(dir, ".git"));
+    if (typeof pointer !== "object" || !pointer.ok.startsWith("gitdir:"))
+        return UNREADABLE;
+    const raw = pointer.ok.slice("gitdir:".length).trim();
+    if (raw === "")
+        return UNREADABLE;
+    const gitDirFact = realpathFact(resolve(dir, raw));
+    if (typeof gitDirFact !== "object")
+        return UNREADABLE;
+    const gitDir = gitDirFact.ok;
+    const commonText = readTextFact(join(gitDir, "commondir"));
+    if (commonText === "missing")
+        return { root: dir };
+    if (commonText === "unreadable")
+        return UNREADABLE;
+    const commonFact = realpathFact(resolve(gitDir, commonText.ok));
+    if (typeof commonFact !== "object")
+        return UNREADABLE;
+    const common = commonFact.ok;
+    if (dirname(gitDir) !== join(common, "worktrees"))
+        return UNREADABLE;
+    const back = readTextFact(join(gitDir, "gitdir"));
+    if (typeof back !== "object")
+        return UNREADABLE;
+    const backFact = realpathFact(resolve(gitDir, back.ok));
+    if (typeof backFact !== "object" || backFact.ok !== join(dir, ".git"))
+        return UNREADABLE;
+    return { root: basename(common) !== ".git" ? common : dirname(common) };
+}
+function canonicalTaskRoot(taskRoot) {
+    const rest = [];
+    for (let p = resolve(taskRoot);;) {
+        const fact = realpathFact(p);
+        if (typeof fact === "object")
+            return { canonical: rest.length > 0 ? join(fact.ok, ...rest) : fact.ok, existing: fact.ok };
+        if (fact === "unreadable")
+            return "unreadable";
+        const parent = dirname(p);
+        if (parent === p)
+            return "unreadable";
+        rest.unshift(basename(p));
+        p = parent;
+    }
+}
+export function resolveProjectIdentity(taskRoot) {
+    const root = canonicalTaskRoot(taskRoot);
+    if (root === "unreadable")
+        return UNREADABLE;
+    let sawBareLayout = false;
+    for (let dir = root.existing;;) {
+        const dotGit = statFact(join(dir, ".git"));
+        if (dotGit === "unreadable")
+            return UNREADABLE;
+        if (typeof dotGit === "object") {
+            if (dotGit.ok === "dir")
+                return { root: dir };
+            if (dotGit.ok === "file")
+                return identityOfGitFile(dir);
+        }
+        if (!sawBareLayout && isBareRepoLayout(dir))
+            sawBareLayout = true;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return sawBareLayout ? BARE : { root: root.canonical };
+        dir = parent;
+    }
+}
+export function mintRepoScopeKey(projectRoot) {
+    return `repo:${createHash("sha256").update(projectRoot, "utf8").digest("hex").slice(0, 24)}`;
+}
+export function projectKeyForTaskRoot(taskRoot) {
+    if (taskRoot === undefined)
+        return { absent: "unreadable" };
+    const id = resolveProjectIdentity(taskRoot);
+    return "root" in id ? { scope: mintRepoScopeKey(id.root) } : { absent: id.absent };
+}
+//# sourceMappingURL=project-identity.js.map