@sema-agent/server 7.96.0 → 7.98.0

package/dist/memory-scope.d.ts

@@ -1,5 +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[];
 /**
@@ -11,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 错。产出处响亮拒,错误可分类。
@@ -30,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
@@ -40,10 +84,13 @@ export declare function memoryScopeFor(config: ServiceConfig, principal?: string
  * (`MEMORY_ENGINE_REMOTE_LANE=allow`, e.g. ssh to a host on the same NFS mount).
  *
  * Pure posture probe (memoryEngineBackendFor consumes it; main.ts logs it): `undefined` = no plane split
- * (no remote lane, or the `host` lane), `dark` = split + fail-closed, `forced` = split + operator override.
+ * (the lane's file plane IS this worker's fs — `in-process` / `host`), `dark` = split + fail-closed, `forced` =
+ * split + operator override.
+ * S-602: the plane question reads the lane-caps table (`hostFilePlane`) — it used to be the hand-written synonym
+ * `lane === undefined || lane === "host"` (fold-ban gate D, R3); readings are unchanged lane by lane.
  */
 export declare function memoryEngineRemoteLanePosture(config: ServiceConfig): {
-    lane: string;
+    lane: ExecutionLane;
     posture: "dark" | "forced";
 } | undefined;
 /**
@@ -180,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,
@@ -215,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

@@ -1,6 +1,8 @@
 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:",
@@ -25,9 +27,28 @@ 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 = config.remoteExec?.provider;
-    if (lane === undefined || lane === "host")
+    const lane = executionLaneOf(config.remoteExec?.provider);
+    if (executionLaneCaps(lane).hostFilePlane === "supported")
         return undefined;
     return { lane, posture: config.memoryEngineRemoteLaneAllowed === true ? "forced" : "dark" };
 }
@@ -96,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/fail-open.d.ts

@@ -281,6 +281,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "S-287(`plugins/ensure-index.ts` 的 PG 臂):这口 PG **协议**面不认 `CREATE INDEX CONCURRENTLY`。今天唯一的真消费者是**仓内离线镜像的手搓 `PgQueryFn` 假件**(`pg-mem` 不是本仓依赖,`test/memory-embedder-fingerprint.test.ts` 头注已为此记过一次档,这里不重复那个错)。判据是**能力面**不是名字,且**只认阳性信号**:SQLSTATE ∈ {`0A000` feature_not_supported、`42601` syntax_error},或错误**完全不带 `code`**(= 不是驱动也不是服务端给的错误)⇒ 判「不认」,回退成普通 `CREATE INDEX IF NOT EXISTS`;**带任何其它 `code` 的一律原样抛** —— SQLSTATE 的 `55P03`/`57014`/`23505`/`42501`/`25001` 与 libuv 的 `ECONNRESET`/`EPIPE`/`ETIMEDOUT` 都在这一侧(⚠️ 不要按「5 位大写」的形状去分这两族:`EPIPE` 恰好也是 5 位大写)。放行的最坏后果 = 这一次建索引持表级 `SHARE` 锁阻塞该表的写(纯**性能/可用性**面,索引本身照样建成、语义零差别),而能走到这条臂的面**按定义**不是生产 PG。计数非零 = 有一口本以为是真 PG 的部署其实不认 CONCURRENTLY,运维要去看它到底是什么。detail = `<表>.<索引名>`。";
     };
+    readonly "server.assistant-inbox.objective-ctx-corrupt": {
+        readonly cls: "F";
+        readonly note: "S-609(`routes/approvals-assistant.ts` 的 `GET /v1/assistant/inbox`):某一行的续跑上下文(checkpoint_ctx)读出来是**坏体**(店的拒绝契约 `StoreCorruptError`;local = 档不是 JSON / 信封不合形,SQL = 列是合法 JSON 但不是一只对象)⇒ **这一行**的 `objective` 落 `null`,列表其余照常。放行的最坏后果 = inbox 上这一张卡不显示它属于哪个任务(纯展示位;这一格不参与任何决裁、续跑或门判 —— 续跑腿与 plan_review 门对同一行各自走读口、坏体一律响亮 500)。不放行的代价是整只 `summaries.map` 抛出 ⇒ 一行坏体打掉整个用户的 inbox。故 F 类;必须留痕,因为修前那句 `.catch(() => null)` 让「坏体」与「本来就没有」同形无痕(detail = 读口转述的 `where`,人拿它去修那一行)。缺席(行不在 / 店抖动)**不**记本 tag:那是读口的刻意保守,不是失败开放。";
+    };
 };
 /** 词表键推导的闭集类型——未登记的 tag 传不进 {@link recordFailOpen}(编译期拒)。 */
 export type FailOpenTag = keyof typeof FAIL_OPEN_TAGS;

package/dist/observability/fail-open.js

@@ -254,6 +254,10 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "S-287(`plugins/ensure-index.ts` 的 PG 臂):这口 PG **协议**面不认 `CREATE INDEX CONCURRENTLY`。今天唯一的真消费者是**仓内离线镜像的手搓 `PgQueryFn` 假件**(`pg-mem` 不是本仓依赖,`test/memory-embedder-fingerprint.test.ts` 头注已为此记过一次档,这里不重复那个错)。判据是**能力面**不是名字,且**只认阳性信号**:SQLSTATE ∈ {`0A000` feature_not_supported、`42601` syntax_error},或错误**完全不带 `code`**(= 不是驱动也不是服务端给的错误)⇒ 判「不认」,回退成普通 `CREATE INDEX IF NOT EXISTS`;**带任何其它 `code` 的一律原样抛** —— SQLSTATE 的 `55P03`/`57014`/`23505`/`42501`/`25001` 与 libuv 的 `ECONNRESET`/`EPIPE`/`ETIMEDOUT` 都在这一侧(⚠️ 不要按「5 位大写」的形状去分这两族:`EPIPE` 恰好也是 5 位大写)。放行的最坏后果 = 这一次建索引持表级 `SHARE` 锁阻塞该表的写(纯**性能/可用性**面,索引本身照样建成、语义零差别),而能走到这条臂的面**按定义**不是生产 PG。计数非零 = 有一口本以为是真 PG 的部署其实不认 CONCURRENTLY,运维要去看它到底是什么。detail = `<表>.<索引名>`。"
     },
+    "server.assistant-inbox.objective-ctx-corrupt": {
+        cls: "F",
+        note: "S-609(`routes/approvals-assistant.ts` 的 `GET /v1/assistant/inbox`):某一行的续跑上下文(checkpoint_ctx)读出来是**坏体**(店的拒绝契约 `StoreCorruptError`;local = 档不是 JSON / 信封不合形,SQL = 列是合法 JSON 但不是一只对象)⇒ **这一行**的 `objective` 落 `null`,列表其余照常。放行的最坏后果 = inbox 上这一张卡不显示它属于哪个任务(纯展示位;这一格不参与任何决裁、续跑或门判 —— 续跑腿与 plan_review 门对同一行各自走读口、坏体一律响亮 500)。不放行的代价是整只 `summaries.map` 抛出 ⇒ 一行坏体打掉整个用户的 inbox。故 F 类;必须留痕,因为修前那句 `.catch(() => null)` 让「坏体」与「本来就没有」同形无痕(detail = 读口转述的 `where`,人拿它去修那一行)。缺席(行不在 / 店抖动)**不**记本 tag:那是读口的刻意保守,不是失败开放。",
+    },
 };
 export function failOpenTagForDroppedFrame(frameType) {
     switch (frameType) {

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

package/dist/run-local.d.ts

@@ -47,10 +47,20 @@ export declare function parseArgs(argv: string[]): RunLocalArgs;
 export declare class UsageError extends Error {
 }
 /**
- * The model GATEWAY pre-flight (mirrors the doctor message): the engine cannot run a real
- * task without (a) a gateway base URL that ends in `/v1` and (b) the gateway/model API key resolvable from
- * env. We surface a "you still need to set: …" list rather than letting the first brain call crash with a
- * cryptic auth/connect error. Returns a list of missing items (empty = OK).
+ * The model GATEWAY pre-flight (mirrors the doctor message): the engine cannot run a real task through a
+ * declared gateway without the gateway/model API key resolvable from env. We surface a "you still need to
+ * set: …" list rather than letting the first brain call crash with a cryptic auth error. Returns a list of
+ * missing items (empty = OK).
+ *
+ * 🔴 S-623:这里**不再**判网关 base URL。「配置能派发到的每一条 openai 路由都解析到显式端点」是 `loadConfig()`
+ * 那一层的拒启判据(`model-route-endpoint.ts`,本入口在预检之前就调 `loadConfig()` —— 没设网关的配置根本走不到
+ * 这里),原来那条臂(a)是它的一份更弱的手抄:注释要求「本机用户必须指向自己的网关」,判据却只查 `/v1` 后缀,
+ * 旧的出厂缺省值恰好以 `/v1` 结尾 ⇒ 缺省值照样过(本仓自己也被骗)。`/v1` 后缀本身也一并删,理由三条:
+ *  ① 同一个问题两个判官 —— `serve` 从不要求 `/v1`,同一份 .env 在 `serve` 起得来、在 `run-local` 被拒;
+ *  ② 它会误拒真实存在的 OpenAI 兼容端点(DeepSeek 根路径直接服务 `/chat/completions`,本仓
+ *     `src/bench/s1/live-deps.ts` 用的正是 `https://api.deepseek.com`;Gemini 的兼容面 `…/v1beta/openai`、Azure 的
+ *     `…/openai/deployments/<name>` 也都不以 `/v1` 结尾);
+ *  ③ 规则集只许变小:端点判据只有 loadConfig 那一只。
  *
  * NOTE: with an injected mock `brain` the gateway is irrelevant (no real call is made), so the caller skips
  * this check in that case — the check is about a REAL run, not the assembly.