@sema-agent/settings-schema 14.6.0 → 14.7.0

package/dist/worker-row-verdict.js

@@ -8,19 +8,69 @@
  */
 import { formatConfigPath, outgoingPath } from "./config-fns.js";
 import { issuePath } from "./issue-path.js";
+import { guardedSafeParse } from "./own-key-read.js";
+import { jsonShapeOf } from "./plain-json-object.js";
 import { WorkersConfig } from "./types.js";
 /** 每一形的拒句主语 —— 穷举映射型:加一形不补这里即编译红。 */
 const SUBJECT = {
     stored: "the stored worker",
     migrated: "after migration the worker",
 };
+/** 输入的「类型名」(zod 的 `invalid_type` 句子里 `received` 后面那个词):typeof / array / null,**从不读 `constructor`**。形状只问座位;数恒答 `number`
+ *  (非有限的数到不了这里:{@link safeIssueMessage} 把它交还 zod 自己的句子)。 */
+function receivedWord(input) {
+    switch (typeof input) {
+        case "number":
+            return "number";
+        case "object": {
+            const shape = jsonShapeOf(input);
+            switch (shape) {
+                case "null":
+                    return "null";
+                case "array":
+                    return "array";
+                case "plain":
+                case "non_plain_object":
+                case "uninspectable":
+                case "primitive":
+                    return "object";
+                default: {
+                    const unhandled = shape;
+                    throw new Error(`receivedWord: unhandled shape ${String(unhandled)}`);
+                }
+            }
+        }
+        default:
+            return typeof input;
+    }
+}
+/**
+ * zod 的 `invalid_type` 句子(`Invalid input: expected <类型>, received <类型>`)—— 与 zod 自己的话**逐字同**(对每种 JSON 值;`test/migration-row-verdict-14.7.0` 逐值对着 zod 的原句核,升级 zod 改措辞即红),
+ * 区别只有一处:zod 对「原型不是 Object.prototype 的对象」读 `input.constructor.name` 当类型名 —— 原型不是 `Object.prototype` 的(隔离原型)行快照上,用户写的**自有 `constructor` 键**就成了类型名:
+ * 整次调用抛(`constructor.name` 是个对象)、用户文本进拒因(`received hello world`)、句子变样。这里不读 constructor。别的 issue 不管(返回 `undefined` ⇒ 沿用 zod 的 / 包自己写的句子)。
+ * 只给本文件的终判调用(`safeParse` 的 `error` 参数);它在 schema 自带的句子之后、zod 内置句子之前生效。
+ */
+export function safeIssueMessage(issue) {
+    if (issue.code !== "invalid_type")
+        return undefined;
+    // 非有限的数(`NaN` / `±Infinity` —— JSON 写不出 `NaN`;`±Infinity` 只由溢出的数字字面量如 `1e400` 解析出来)的类型名 zod 自己怎么说各版本不同:不抢,交还 zod 自己的句子(它不读 constructor)
+    if (typeof issue.input === "number" && !Number.isFinite(issue.input))
+        return undefined;
+    const expected = issue.expected === "nan" ? "NaN" : String(issue.expected);
+    return `Invalid input: expected ${expected}, received ${receivedWord(issue.input)}`;
+}
 /** 一只单行域里的 issue 路径 → 相对那一行(去掉 `["workers", 0]` 前缀;不在那一行下的 issue 原样)。 */
 function rowRelative(path) {
     return path[0] === "workers" && path[1] === 0 ? path.slice(2) : path;
 }
 /** 一行的终判:读得进 ⇒ `undefined`;读不进 ⇒ 第一条 issue 的路径(相对该行)+ 拒句(见文件头)。 */
 export function workerRowVerdict(row, form) {
-    const verdict = WorkersConfig.safeParse({ workers: [row] });
+    // 校验过程抛(会抛的 getter / 陷阱:读侧交进来的是调用方的活对象;zod 4.6 首读 `error` 时拼句子抛 —— 被污染的运行时、另一 realm 的怪形值)⇒ 这一行判「读不出」
+    // (定句,不含任何用户文本),不抛出调用。首读 `error` 与 `safeParse` 同在一只守护里(`guardedSafeParse`),两版 zod 同答
+    const judged = guardedSafeParse(() => WorkersConfig.safeParse({ workers: [row] }, { error: (iss) => safeIssueMessage(iss) }));
+    if (!judged.ok)
+        return { field: [], reason: `${SUBJECT[form]} is not a valid WorkerSpec — a value could not be read during validation` };
+    const verdict = judged.value;
     if (verdict.success)
         return undefined;
     const issues = verdict.error.issues;

package/dist/workers-rows.js

@@ -15,29 +15,57 @@
  * web-admin 在列表里标红点名 `field` / `reason`。拒因只点名字段、不回显值。
  */
 import { outgoingPath, redactSecrets } from "./config-fns.js";
+import { appendOwn, dataDescriptor, ownDeclaredValueOf, ownElementsOf, ownEntriesOf } from "./own-key-read.js";
 import { isJsonArray, isPlainJsonObject } from "./plain-json-object.js";
 import { workerRowVerdict } from "./worker-row-verdict.js";
+/**
+ * 扣下坏行后的文档:调用方文档的其余自有键 + 换掉的 `workers`。**不对调用方的整份文档做展开**(`{ ...raw }` 会对它做 `[[OwnPropertyKeys]]` + 逐键 `[[Get]]`:无关键上会抛的 getter / `ownKeys` 陷阱
+ * 把嵌入方自己抛的值带出调用)—— 其余键经内核的 `ownEntriesOf` 读(整容器律:每个自有串键一份描述符、只从描述符取值,全或无):**其余键里只要有一个读不成纯数据**(访问器 / 隐藏键)
+ * 或整份读不出(`ownKeys` / `getOwnPropertyDescriptor` 陷阱抛)⇒ 其余键**一个都不带出**,只剩 `workers`;符号键从不带出(内核只认串键)。workers 域只有 `workers` 一个键,
+ * 其余键本来就是未知键(读侧剥掉、只进未知键告警),所以这一答只影响那条告警点名哪些键。交出的是寻常对象。
+ */
+function withWorkers(raw, kept) {
+    const doc = {};
+    const entries = ownEntriesOf(raw);
+    // 键序同展开(`{ ...raw, workers: kept }`):`workers` 留在它原来的位置
+    if (entries.ok)
+        for (const [key, value] of entries.value)
+            Object.defineProperty(doc, key, dataDescriptor(key === "workers" ? kept : value));
+    if (!Object.hasOwn(doc, "workers"))
+        Object.defineProperty(doc, "workers", dataDescriptor(kept));
+    return doc;
+}
 /**
  * 逐行读一份 workers 域**原始**文档(`{ workers: [...] }`)。不是这个形 ⇒ 原样返回、零扣下(判形是 `parseDomain` 的事)。
  * 规则见文件头。
  */
 export function readWorkersRows(raw) {
-    if (!isPlainJsonObject(raw) || !isJsonArray(raw.workers))
+    // 读调用方的对象一律经内核(一份描述符里取值,不问 `get` 陷阱;原型链上被污染的 `workers` / `name` 不是文档里写着的):
+    //  · `workers` 键与每行的 `name` —— 严归类(逐键一次描述符,键缺席时再问一次 `has`;访问器 / 隐藏键 ⇒ 读不成纯数据);
+    //  · `workers` 数组的元素 —— 按校验器解析数组的读法(内核的 `ownElementsOf`:只看下标键,数据下标取值、隐藏下标照读、访问器下标调它自己的 getter 一次;挂在数组上的非下标键不看)。
+    // `workers` 读不成纯数据 / 元素读不出(结构陷阱抛、下标的 getter 抛)⇒ 「不是这个形」,原样放行交整域读侧判(不按条丢:丢一行 = 对账方把那只 worker 当作已撤销);行的 `name` 读不出 ⇒ 「认不出名字」,该行原样留在 doc
+    if (!isPlainJsonObject(raw))
+        return { doc: raw, held: [] };
+    const workers = ownDeclaredValueOf(raw, "workers");
+    if (!workers.ok || !isJsonArray(workers.value))
+        return { doc: raw, held: [] };
+    const rows = ownElementsOf(workers.value);
+    if (!rows.ok)
         return { doc: raw, held: [] };
-    const rows = raw.workers;
     const kept = [];
     const held = [];
-    rows.forEach((row, index) => {
-        if (!isPlainJsonObject(row) || typeof row.name !== "string") {
-            kept.push(row); // 认不出名字:整域读侧判
-            return;
+    for (const [index, row] of rows.value) {
+        const name = isPlainJsonObject(row) ? ownDeclaredValueOf(row, "name") : undefined;
+        if (!isPlainJsonObject(row) || name === undefined || !name.ok || typeof name.value !== "string") {
+            appendOwn(kept, row); // 认不出名字:整域读侧判(这一读口的追加都走定义语义:`push` 会被继承的数字键 setter 吞掉)
+            continue;
         }
         const v = workerRowVerdict(row, "stored");
         // 坐标与拒因都走出门那一道:issue 路径里的 Record 键是用户写的(例:一个不合法的 env 键名可能就是粘错位置的凭据)。
         if (v === undefined)
-            kept.push(row);
+            appendOwn(kept, row);
         else
-            held.push({ name: row.name, index, field: outgoingPath(v.field), reason: redactSecrets(v.reason), original: row });
-    });
-    return held.length === 0 ? { doc: raw, held } : { doc: { ...raw, workers: kept }, held };
+            appendOwn(held, { name: name.value, index, field: outgoingPath(v.field), reason: redactSecrets(v.reason), original: row });
+    }
+    return held.length === 0 ? { doc: raw, held } : { doc: withWorkers(raw, kept), held };
 }

package/dist/zod-unwrap.d.ts

@@ -9,3 +9,9 @@ import { z } from "zod";
  *  不是变换的那一侧。两侧都是 schema 的管道(`a.pipe(b)`)不是包装:到此为止(按它本身的形判,认不出就不抢救)。
  *  `.refine()` / `.superRefine()` 在 zod 4 里不是包装层(判据挂在同一只 schema 上),无须展开。 */
 export declare function unwrapSchema(schema: z.ZodType): z.ZodType;
+/** 剥一层包装:`wrapper` = `.optional()` 一类(`.unwrap()`);`preprocess` = `z.preprocess(f, schema)`(变换在**输入**侧,先于里面的 schema);`postprocess` = `.transform(f)`(变换在输出侧)。不是包装 ⇒ `undefined`。
+ *  `unwrapSchema` 把三种都一视同仁地剥掉(「条目能不能单独解析」与变换无关);要区分的读者(按声明键投影:输入侧的变换会看到整个值,投影不了)用它。 */
+export declare function unwrapOnce(cur: z.ZodType): {
+    readonly next: z.ZodType;
+    readonly via: "wrapper" | "preprocess" | "postprocess";
+} | undefined;

package/dist/zod-unwrap.js

@@ -12,14 +12,21 @@ export function unwrapSchema(schema) {
     let cur = schema;
     // 有界:包装层数是 schema 作者写出来的常数,8 层远超实际(防被畸形 schema 拖住)。
     for (let i = 0; i < 8; i++) {
-        if (cur instanceof z.ZodOptional || cur instanceof z.ZodNullable || cur instanceof z.ZodDefault || cur instanceof z.ZodPrefault || cur instanceof z.ZodCatch)
-            cur = cur.unwrap();
-        else if (cur instanceof z.ZodPipe && cur.in instanceof z.ZodTransform)
-            cur = cur.out;
-        else if (cur instanceof z.ZodPipe && cur.out instanceof z.ZodTransform)
-            cur = cur.in;
-        else
+        const step = unwrapOnce(cur);
+        if (step === undefined)
             return cur;
+        cur = step.next;
     }
     return cur;
 }
+/** 剥一层包装:`wrapper` = `.optional()` 一类(`.unwrap()`);`preprocess` = `z.preprocess(f, schema)`(变换在**输入**侧,先于里面的 schema);`postprocess` = `.transform(f)`(变换在输出侧)。不是包装 ⇒ `undefined`。
+ *  `unwrapSchema` 把三种都一视同仁地剥掉(「条目能不能单独解析」与变换无关);要区分的读者(按声明键投影:输入侧的变换会看到整个值,投影不了)用它。 */
+export function unwrapOnce(cur) {
+    if (cur instanceof z.ZodOptional || cur instanceof z.ZodNullable || cur instanceof z.ZodDefault || cur instanceof z.ZodPrefault || cur instanceof z.ZodCatch)
+        return { next: cur.unwrap(), via: "wrapper" };
+    if (cur instanceof z.ZodPipe && cur.in instanceof z.ZodTransform)
+        return { next: cur.out, via: "preprocess" };
+    if (cur instanceof z.ZodPipe && cur.out instanceof z.ZodTransform)
+        return { next: cur.in, via: "postprocess" };
+    return undefined;
+}

package/docs/API-SURFACE.md

@@ -4,9 +4,9 @@
 > 每次全量重算并逐名比对 —— 加 / 删 / 改形一个导出而不重生成本档 ⇒ 红。导出面的每次变动因此以本档的 diff 出现在评审里。
 > 形:`value` = 运行期拿得到的值;`type` = 只在类型层;`value+type` = 同名的值与类型(zod schema 与它推出的类型)。
 
-子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1365 个(同名在多条子路径上各计一次)。
+子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1396 个(同名在多条子路径上各计一次)。
 
-## `.`(680)
+## `.`(708)
 
 - `ABSOLUTE_HOST_PATH_MAX` — value
 - `ACCESS_TOKEN_TTL_SECONDS` — value
@@ -56,7 +56,9 @@
 - `ConfigChangeHookInput` — value
 - `ConfigPath` — type
 - `ConfigReader` — type
+- `CredentialHandleAnswer` — value+type
 - `CredentialParamName` — type
+- `CredentialResolveRequest` — value+type
 - `CrossSessionInboundSetting` — value
 - `CrossSessionInboundSettingValue` — type
 - `CrossSessionInboundValue` — type
@@ -151,6 +153,7 @@
 - `FEEDBACK_DESCRIPTION_MAX_CHARS` — value
 - `FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS` — value
 - `FEEDBACK_V1_PATH` — value
+- `FLEET_ADVERTISE_ADDRESS_ENV` — value
 - `FLEET_GENERATION_ENV` — value
 - `FLEET_LIVE_PATHS` — value
 - `FLEET_PATHS` — value
@@ -280,7 +283,9 @@
 - `OAuthErrorCode` — type
 - `OAuthErrorResponse` — value+type
 - `PARSE_TRANSPARENT_KEYS` — value
+- `PATH_BASE_URL_FORBIDDEN_PARTS` — value
 - `PLUGIN_ORIGIN` — value
+- `PRINCIPAL_INC_CLAIM` — value
 - `PRINCIPAL_MAX_LENGTH` — value
 - `PRIVATE_KEY_PEM_HEADER` — value
 - `PROBE_CPU_CORES_MAX` — value
@@ -316,6 +321,7 @@
 - `PreModelSwitchHookInput` — value+type
 - `PreToolUseHookInput` — value
 - `PrincipalCapsWire` — value+type
+- `PrincipalIncarnation` — value+type
 - `PrincipalOrgMemoryWire` — value+type
 - `ProjectContextItem` — value+type
 - `ProjectContextItemKind` — type
@@ -377,6 +383,13 @@
 - `RostersConfig` — value+type
 - `RoutingVerdict` — type
 - `SAFETY_MERGE_SPEC` — value
+- `SANDBOX_GIT_MAX_ORIGINS` — value
+- `SANDBOX_GIT_ORIGIN_REASONS` — value
+- `SANDBOX_GIT_ORIGIN_STATES` — value
+- `SANDBOX_GIT_ORIGIN_VERDICTS` — value
+- `SANDBOX_GIT_PERMANENCE` — value
+- `SANDBOX_GIT_REFUSALS` — value
+- `SANDBOX_GIT_REFUSAL_ERRORS` — value
 - `SCOPES_V1_PATHS` — value
 - `SCOPE_CLAIM` — value
 - `SCOPE_ID_REGEX` — value
@@ -403,6 +416,19 @@
 - `SUBMIT_IDEMPOTENCY_KEY` — value
 - `SafetyMergeCategory` — type
 - `SafetyMergeMember` — type
+- `SandboxGitConfig` — value+type
+- `SandboxGitConnectUrl` — value+type
+- `SandboxGitCredentialAnswer` — value+type
+- `SandboxGitCredentialRefusal` — value+type
+- `SandboxGitCredentialRequest` — value+type
+- `SandboxGitOrigin` — value+type
+- `SandboxGitOriginAnswer` — value+type
+- `SandboxGitOriginEntry` — value+type
+- `SandboxGitOriginList` — value+type
+- `SandboxGitOriginReason` — type
+- `SandboxGitOriginState` — type
+- `SandboxGitPermanence` — type
+- `SandboxGitRefusalError` — type
 - `ScenarioAssignments` — value+type
 - `ScenarioConfig` — value+type
 - `ScenarioEntry` — value+type
@@ -589,6 +615,7 @@
 - `isRetiredDomainName` — value
 - `isRole` — value
 - `isRoutable` — value
+- `isSandboxGitOrigin` — value
 - `isSchedulerRecord` — value
 - `isStringArray` — value
 - `isStringRecord` — value
@@ -619,6 +646,7 @@
 - `parseSchedulerStore` — value
 - `parseWebAdminCredentialFile` — value
 - `parseWebAdminSessionUrl` — value
+- `pathBaseUrlFlaws` — value
 - `pickInstance` — value
 - `projectWarning` — value
 - `promptArtifactFor` — value
@@ -1256,7 +1284,7 @@
 - `interpolateHookEnvVars` — value
 - `stopAttributionText` — value
 
-## `./fleet`(83)
+## `./fleet`(84)
 
 - `AggregatedPrincipalUsage` — type
 - `CapabilityReading` — type
@@ -1280,6 +1308,7 @@
 - `ENGINE_SIGNAL_KEY` — value
 - `EngineDraining` — value+type
 - `EngineSignal` — value+type
+- `FLEET_ADVERTISE_ADDRESS_ENV` — value
 - `FLEET_GENERATION_ENV` — value
 - `FLEET_LIVE_PATHS` — value
 - `FLEET_PATHS` — value
@@ -1368,7 +1397,7 @@
 - `nextPollInterval` — value
 - `normalizeUserCode` — value
 
-## `./api/auth-bridge`(21)
+## `./api/auth-bridge`(23)
 
 - `AUTH_BRIDGE_ALGS` — value
 - `AUTH_BRIDGE_ERROR_CODES` — value
@@ -1379,7 +1408,9 @@
 - `DEFAULT_JWKS_REFRESH_MIN_INTERVAL_SEC` — value
 - `DEFAULT_OFFLINE_GRACE_SEC` — value
 - `JwksCacheSnapshot` — type
+- `PRINCIPAL_INC_CLAIM` — value
 - `PRINCIPAL_MAX_LENGTH` — value
+- `PrincipalIncarnation` — value+type
 - `VerifiedIdentity` — value+type
 - `VerifierConfig` — value+type
 - `VerifierConfigInput` — type

package/docs/CONSUMER-INTEGRATION.md

@@ -7,6 +7,8 @@
 > S-570 收车档;3.0.0 之后的下一次真实改动,请同一批把这份文档也带上,别再停摆。**7.0.0**(M-R2 WorkerSpec 结构块)的
 > 三方迁移句在 §0.2,`remoteExec` 删 `remote-docker` 在 §5。**8.0.0**(一致性门第四条腿 + 表态律 + CLI `--check`)在 §0.3。
 > **11.0.0** 的持久面(`runtime` 域退役、读侧兼容臂退役、一次性迁移族 `./one-time-migrations`)在 §0.4。
+> **14.7.0** 的沙箱 git 凭据平面(取值口 wire 型、有效配置块 `sandboxGit`、`VerifiedIdentity.principalInc`)在 §12。
+> **14.7.0** 的路径基址判官(`PATH_BASE_URL_FORBIDDEN_PARTS` / `pathBaseUrlFlaws`)与公告地址 env 名(`FLEET_ADVERTISE_ADDRESS_ENV`)在 §13。
 
 ---
 
@@ -236,6 +238,7 @@ server 直接拒启,不是静默降级。上一代 `SEMA_REGISTRY_*` 八名(`URL
   命令行 `migrate` 与这只函数同一份实现;写盘用的就是本包那一只原子写器(契约文档新建 0o644、已有的沿用原模式、符号链接保留)。
   手里已有存量文档原文、不经目录的消费方(例:命令行壳按层读 `settings` 里的 models 域,要的是「引擎起服那一次迁移之后这份文档整域读不读得进」)调同一个内核的同步口 `migrateConfigDocuments(docs, { documents })`(14.5.0,`./node`):
   同一个闭集的无 io 形(`refused` ⇒ 引擎同样不写回、整域落缺省;**反向不成立** —— 引擎对整个目录一判,别的文档被拒也会让整目录不写,单层单域的 `noop` / `migrated` 不保证引擎那一次放行;`docs` 是壳的写手要的迁移后那一份)。一层一次调用;**别自己把 `migrateStoredDocuments` 与 `parseDomain` 按这个顺序再组装一遍**。
+- **路径基址判官与公告地址**:「别人要往它后面拼路径的基址」座位(中心基址三席、公告地址、会话链接基址)的禁用成分集 `PATH_BASE_URL_FORBIDDEN_PARTS` 与判官 `pathBaseUrlFlaws` 在本包,公告地址的 env 名是 `FLEET_ADVERTISE_ADDRESS_ENV`;**别手写 env 名、别手抄那三个词** —— 两方读法见 §13。
 - **会话网页链接**:要给用户一个 web-admin 里的会话链接,调 `webAdminSessionUrl(webBaseUrl, { worker, sessionId })`(`webBaseUrl` 取引擎 `/health` 自报的人用界面根 URL,
   `worker` 取引擎向 web-admin 登记用的 worker 名),得到 `<webBaseUrl>/chat?agent=<worker>&session=<sessionId>`;**别按地址形手拼** —— 路由属于 web-admin,模板与读回的
   `parseWebAdminSessionUrl(link)` 同在本包,路径与参数名只此一份。两位必填:只带 `session` 的链接会落到页面自己挑的 worker 上、可能找不到会话。
@@ -283,3 +286,178 @@ server 直接拒启,不是静默降级。上一代 `SEMA_REGISTRY_*` 八名(`URL
   这份档里重复展开。
 - 今天真接了这道门的:server(`wire` + `localRoot` 两条读腿)、管理面(`domains` 往返腿,钉在 6.x);cli 显式拒接 kit 读腿
   (壳不走上游 effective 读腿),client-core 零 import。8.0.0 起两家接线方都要对四条腿逐条表态(§0.3)。
+
+## 12. 沙箱 git 凭据平面(14.7.0 起)—— web-admin 与 server 两方的读法
+
+沙箱里的 git 用**成员本人**的凭据:凭据住在 web-admin 的凭据库,引擎的数据面按 run 的身份向取值口取,只在该成员自己的沙箱里经代理使用,永不进模型可读的容器。
+本节说**本包发什么、两方各自怎么读**。本包只有**形与词表**(纯、浏览器安全,零 IO);鉴权、委托、活表复核、行 MAC、租约与续期都是两方自己的事(§12.9 逐条列出)。
+
+### 12.1 本包发什么
+
+| 件 | 在哪 | 是什么 |
+|---|---|---|
+| `isSandboxGitOrigin` · `SandboxGitOrigin` · `SandboxGitOriginList` · `SANDBOX_GIT_MAX_ORIGINS` | 主桶(`src/sandbox-git.ts`) | origin 的规范形判官与 zod 形;一个 origin 就是它自己的 WHATWG origin |
+| `SandboxGitConfig` · `SandboxGitOriginEntry` · `SandboxGitConnectUrl` | 主桶 | 有效配置块 `sandboxGit` 的形 |
+| `SandboxGitCredentialRequest` · `CredentialHandleAnswer` · `CredentialResolveRequest` · `SandboxGitCredentialAnswer` · `SandboxGitOriginAnswer` · `SandboxGitCredentialRefusal` | 主桶(`src/api/credentials.ts`,不开子路径) | 取值口两步的 wire 型 |
+| `SANDBOX_GIT_ORIGIN_VERDICTS` → `SANDBOX_GIT_ORIGIN_STATES` · `SANDBOX_GIT_ORIGIN_REASONS`;`SANDBOX_GIT_REFUSALS` → `SANDBOX_GIT_REFUSAL_ERRORS`;`SANDBOX_GIT_PERMANENCE` | 主桶 | 三张词表(每个词只在 `src/api/credentials.ts` 里拼一次;状态词、原因词、错误词表与类型全由表派生) |
+| `PRINCIPAL_INC_CLAIM`(`"sub_inc"`) · `PrincipalIncarnation` · `VerifiedIdentity.principalInc` | 主桶与 `./api/auth-bridge` | 令牌里的化身号声明 |
+| `EffectiveWire.sandboxGit?: unknown` | 主桶(`types`) | `/effective` 载荷上的非域顶层键,逐字承运 |
+
+全部是加性(新导出 / 可选键),既有导出对既有输入的答案不变。
+
+### 12.2 有效配置块 `sandboxGit`
+
+```json
+{
+  "sandboxGit": {
+    "origins": [
+      { "origin": "https://git.example.com:9999", "connectUrl": "https://console.example.com/connect/git" },
+      { "origin": "http://git.legacy.example:8080", "connectUrl": "https://console.example.com/connect/git" }
+    ]
+  }
+}
+```
+
+- **非域顶层键**:web-admin 按部署登记册**投影**,不是存储域 —— `buildEffective` 不产它、`FileConfigStore` 没有 `sandboxGit.json`(单机模式没有这个平面)。**可选、无默认**:键缺席 = 这个部署没有投影这一块。
+- `readEffectiveWire` 对它走 open-world:**逐字承运,不校验、不丢**(`EffectiveWire.sandboxGit` 是 `unknown`)。**判它的唯一座位是 `SandboxGitConfig`**:消费方在用之前对 `wire.sandboxGit` 跑 `safeParse`。
+- `origins` ≤ 16(`SANDBOX_GIT_MAX_ORIGINS`)、按 `origin` 两两不同,空表合法;解析剥未知键(前向兼容)。
+- **规范形只有一条律**:`origin` 逐字等于 `new URL(origin).origin`,且 scheme ∈ {http, https}。小写 host、去缺省端口(443 / 80)、无尾斜杠、无 userinfo / 路径 / 查询 / 片段都是它的推论 ——
+  凡 WHATWG 会改写的串(大写、缺省端口、IPv4 简写、百分号编码的 host、前后空白……)都不是规范形。**origin 不表达子路径部署**:`https://host/gitea` 不是 origin,判官拒;本包没有「削成 origin」的规范化器(把运维写的路径静默削掉会把凭据送到他没写的地方)。
+- 🔴 **块里 http origin 可读**。它为什么送不出凭据是**逐 origin 应答里的一个词**(§12.4 第 1 行 `insecure_transport`)与能力读数里的一个词,不是块的校验拒:块若因一个 http origin 整块不可读,同块里的 https origin 一并失效,「逐 origin 说拒因」就无从谈起。
+  http origin 只配路由、永不取值,是 server 的事。
+- `connectUrl` = 控制台「连接 Gitea(git)」页的绝对 **https** URL(`SandboxGitConnectUrl`:`NON_SECRET_URL_NO_MIGRATION` 的判据 + https)。
+
+### 12.3 取值口两步(wire 型)
+
+```
+① POST /api/v1/credentials/handles   请求 SandboxGitCredentialRequest   → 200 CredentialHandleAnswer { handle, expiresAt }
+② POST /api/v1/credentials/resolve    请求 CredentialResolveRequest { handle } → 200 SandboxGitCredentialAnswer
+                                                                             → 非 2xx 体 SandboxGitCredentialRefusal { error, permanence, message }
+```
+
+```json
+{ "kind": "sandbox_git", "principal": "alice", "principalInc": "<化身号>", "scope": "team-android",
+  "origins": ["https://git.example.com:9999"], "sid": "<会话 id,审计标签>" }
+```
+
+- `kind` 是字面量 `"sandbox_git"`;`principal` 的长度界同令牌 `sub`(`PRINCIPAL_MAX_LENGTH`);`principalInc` 就是 `PrincipalIncarnation`(与令牌 `sub_inc`、`VerifiedIdentity.principalInc` 是**同一只 schema 对象**);
+  `scope` 非空串(与 `readTokenScope` 读令牌声明同一条规则);`origins` 1–16 个、规范形、两两不同 —— **http origin 也收**(中心对它答判定序第 1 行,请求形不抢先拒)。
+- 应答(200)里的 `principal` / `principalInc` / `scope` 是请求的**回显**;`answeredAt`(应答时刻)、`cacheUntil`(句柄到期)与 `active` 行里的 `expiresAt` 是**同一只钟**(中心的)给的毫秒:收方只该用它们的**差**,不拿它们和自己的钟比。
+- 每个 origin 一行 `SandboxGitOriginAnswer`,按 `state` 判别。`active` 独有 `credentialId` `version` `username` `secret` `expiresAt`(OAuth 令牌:到期毫秒;个人访问令牌:`null`);`needs_reauth` 行带 `credentialId`;其余只有 `origin` / `state` / `reason`。
+  **解析一律剥未知键**,`secret` 只在 `active` 臂的形里 —— 别的臂收到也剥掉。`secret` 是应答里唯一的秘密位;`credentialId` / `version` / `auditId` 是不带值的审计位,日志里记它们、不记 `secret`。
+
+### 12.4 逐 origin 判定序表(`SANDBOX_GIT_ORIGIN_VERDICTS`,11 行,序即判定序)
+
+每个 origin 独立判,**首条命中即答**,一个 origin 的结果不影响别的 origin。`state` 六词、`reason` 十词都由这张表派生。
+
+| 序 | 条件(什么事实命中) | `state` | `reason` |
+|---|---|---|---|
+| 1 | origin 的 scheme 不是 `https` | `insecure_transport` | `not_https` |
+| 2 | 本部署本 scope 的登记册里没有这个 origin 的 git 应用 | `not_offered` | `not_in_registry` |
+| 3 | 选行键下没有行 | `not_connected` | `no_row` |
+| 4 | 行 `status = revoked`(吊销后无密文、留作审计锚的行) | `not_connected` | `revoked` |
+| 5 | 行 `status = revoking` | `needs_reauth` | `revoking` |
+| 6 | 行 `status = suspended` | `needs_reauth` | `suspended` |
+| 7 | 行 `status = needs_reauth` | `needs_reauth` | `row_needs_reauth` |
+| 8 | 行 `active`,但行 MAC 或解密 AAD 校验不过 | `needs_reauth` | `integrity_failed` |
+| 9 | 行 `active`、OAuth、剩余寿命 < 600 s,单飞刷新得上游 `invalid_grant` 或其余 4xx(`invalid_grant` 时行同时置 `needs_reauth`) | `needs_reauth` | `refresh_rejected` |
+| 10 | 同 9,刷新遇网络错 / 5xx / 超时,且现令牌剩余 < 60 s | `temporarily_unavailable` | `refresh_unavailable` |
+| 11 | 其余(行 `active`;不需刷新,或刷新成功,或刷新暂不可用但现令牌剩余 ≥ 60 s) | `active` | — |
+
+选行键 = (scope, 属主键 = 主体 + 化身号, `sandbox_git`, origin);「条件」列是 web-admin 的判定逻辑,**不进运行期表**(本包不知道行状态、登记册、MAC)。状态 × 原因的配对由表定:`SandboxGitOriginAnswer` 每个状态一个臂,臂里 `reason` 的值域 = 表里该状态的行,原因贴在不属于它的状态上一律拒(状态 × 原因的整个叉积里,恰好表里那 10 对加上无原因的 `active` 被收下)。
+
+### 12.5 整次拒答表(`SANDBOX_GIT_REFUSALS`)
+
+体 = `{ "error", "permanence", "message" }`。`permanence` 两词:`terminal` = 不按定时重试;`transient` = 退避重试。**一个错误词的 permanence 是固定的**,拒体里再带一份只为收方不必查表 —— 两处不一致是畸形应答(`SandboxGitCredentialRefusal` 拒)。
+
+| `error` | HTTP | `permanence` | 说明 |
+|---|---|---|---|
+| `caller_not_admitted` | 401 / 403 | terminal | 调用方不是被承认的舰队 worker |
+| `scope_mismatch` | 403 | terminal | 请求的 scope 不等于调用方凭据的 scope |
+| `incarnation_mismatch` | 403 | terminal | 请求的化身号不等于该主体当前的化身号 |
+| `request_invalid` | 400 | terminal | 请求形不合(含 `principalInc` 缺或空) |
+| `principal_not_live` | 403 | terminal | 主体活表复核不过 |
+| `delegation_required` | 403 | terminal | 没有活的委托 |
+| `vault_disabled` | 503 | terminal | 凭据库关着 |
+| `vault_frozen` | 503 | terminal | 凭据库冻结 |
+| `handle_invalid` | 401 | transient | 句柄验不过 / 已用 / 已过期 |
+| `vault_unavailable` | 503 | transient | 凭据库暂不可用 |
+
+收方怎么处置某个词(例如哪些 terminal 可由用户动作恢复、哪些不可恢复)是收方的状态机,不在本包里。**错误词不在闭集 ⇒ 畸形应答,不是「当 transient 重试」。**
+
+### 12.6 `VerifiedIdentity.principalInc` 与令牌声明 `sub_inc`
+
+同名主体删号重建之后是**另一个人**:`sub` 只命名一个槽位,化身号才区分「同一个名字」与「同一个人」。
+
+- `toVerifiedIdentity` 读声明 `PRINCIPAL_INC_CLAIM`(`sub_inc`):**在场且是非空串 ⇒ `identity.principalInc` 原样**(不 trim、不折大小写);**缺席 ⇒ 读出形里不铸键**(从不读成 `0` / 空串 / 别的占位);
+  **在场而不是非空串(数字含 0 / 空串 / `null` / 布尔 / 对象 / 数组)⇒ 该令牌 `malformed`**(与 `sub`、`iat` 同律:声明形是垃圾,不降级成缺席 —— 降级会把坏掉的签发方读成「没有化身号」)。
+- **缺化身号不是本契约的拒**:读方要化身号而令牌没有时,答什么是读方的事(server 把它记成「化身号未记录」,取值一律不放)。
+- 行为面唯一变化:此前令牌带了 `sub_inc` 声明也被忽略;从本版起它在场而形不对就拒。
+
+### 12.7 web-admin 做什么
+
+- **铸令牌**:用 `PRINCIPAL_INC_CLAIM` 铸 `sub_inc`(值 = 会话建立时绑定的化身号,非空串)。「会话化身 = 用户行当前化身」的签发不变量是 web-admin 的,不是本包的。
+- **投影 `sandboxGit`**:`origin` 必须已经是规范形(`isSandboxGitOrigin`),`connectUrl` 是 https;自己的出口先 `SandboxGitConfig.parse` 再发,拒掉的是运维配置的问题,不要静默改写。
+- **收请求**:`SandboxGitCredentialRequest.safeParse` 不过 ⇒ `request_invalid`。
+- **答应答**:按 `SANDBOX_GIT_ORIGIN_VERDICTS` 的序逐 origin 判,首条命中即答;用 `SandboxGitCredentialAnswer.parse` 过一遍再发(臂的键集错了在自己这里红,不要等收方判畸形)。
+- **答拒**:`permanence` 取自 `SANDBOX_GIT_REFUSALS[error].permanence`,HTTP 状态取表里该词的状态集之一。
+
+### 12.8 server 做什么
+
+- **读块**:`wire.sandboxGit` 缺席 ⇒ 没有这一块;在场 ⇒ `SandboxGitConfig.safeParse`,不过 ⇒ 当作没有任何 origin,并响亮说(坐标可记,拒句不回显值)。http origin 只配路由、永不取值。
+- **读令牌**:`toVerifiedIdentity` 之后用 `identity.principalInc`;缺 ⇒ 化身号未记录(本契约不拒令牌)。
+- **发请求 / 收应答**:`SandboxGitCredentialRequest` 构造后再发;应答先 `SandboxGitCredentialAnswer.safeParse`,**再**核逐条对应与回显(§12.9);`secret` 只存在于 `active` 行,日志里不出现。
+- **收拒**:体过 `SandboxGitCredentialRefusal` 才算认得;`permanence` 读表(或读体 —— 二者已被形保证相等)。
+- **时刻**:`answeredAt` / `cacheUntil` / `expiresAt` 只取差;不拿它们和 server 自己的钟比。
+
+### 12.9 本包不做的(如实)
+
+- **应答与请求的逐条对应 / 回显相等**(`origins` 同序同长、`principal` / `principalInc` / `scope` 等于请求)是收方在 `safeParse` 之后要核的事,不在形里。
+- **租约算术与续期状态机**(`cacheUntil` / `expiresAt` − `answeredAt` 的差、封顶、重试退避、「踢」)、哪些 terminal 词可恢复,都是 server 自己的。
+- **取值口的另两种凭据**(`model` / `mcp_static`)的请求与应答形不在本节:它们落地时与 `sandbox_git` 形并成按 `kind` 判别的联合,`sandbox_git` 形不动(`kind` 字面量已经在)。`CredentialHandleAnswer` / `CredentialResolveRequest` 与种类无关,三种共用。
+- **两个端点的路径常量**不在包里(上面的路径是文字,不是导出)。
+- **调用方鉴权、委托、活表复核、行 MAC、冻结**:全是 web-admin 的。
+- **一致性门**:没有新腿 —— `sandboxGit` 是 wire 专属键,走 §11 里 T4 那一条(open-world 逐字承运),既有语料的读数不变。新增两条语料(`c84` 合格块含一个 http origin、`c85` 不合格块):wire 腿都要把块**逐字承运、不出告警**,判它是消费方用 `SandboxGitConfig` 的事 —— 你的 wire 读腿若校验后丢掉坏块,跑语料时会在 `c85` 上红。
+
+## 13. 路径基址判官与公告地址 `FLEET_ADVERTISE_ADDRESS`(14.7.0 起)—— web-admin 编排器与 server 两方的读法
+
+有一种座位的值是「别人要往它后面拼路径的基址」:中心基址三席(`WEB_ADMIN_ENV.url` / `liveUrl` / `webUrl`,值 `SEMA_WEB_ADMIN_URL` / `SEMA_WEB_ADMIN_LIVE_URL` / `SEMA_WEB_ADMIN_WEB_URL`)、
+fleet 成员对中心公告的可达地址(`FLEET_ADVERTISE_ADDRESS`,中心往它后面拼路径)、会话网页链接的基址(`webAdminSessionUrl` 的第一个参数)。这种座位有同一条规则:
+不许带凭据,也不许带 query / fragment(`http://x?a=1` 拼上 `/v1/…` 是 `http://x?a=1/v1/…`);路径前缀放行(要拼的路径接在前缀后面)。
+本节说**本包发什么、两方各自怎么读**。本包只有**判这种座位的那一只判官、它禁用的成分集与公告地址的 env 名**(纯、浏览器安全,零 IO);值从哪来、占位怎么展开、地址是不是真打得到,都是两方自己的事(§13.4)。
+
+### 13.1 本包发什么
+
+| 件 | 是什么 |
+|---|---|
+| `PATH_BASE_URL_FORBIDDEN_PARTS` | 「后面要拼路径的基址」座位禁用的 URL 成分,闭集、冻结、判序:`userinfo` · `query` · `fragment`(**策略集,独立于判官词表 `HTTP_URL_PARTS`**:词表说 URL 有哪些成分,本集说这种座位禁哪些;今天碰巧同三词,但不由词表派生,词表加词时要显式裁);这种座位的策略只此一张,没有第二份抄本;包根 |
+| `pathBaseUrlFlaws(url)` | = `httpUrlFlaws(url, PATH_BASE_URL_FORBIDDEN_PARTS)`(本包唯一的 URL 形判官,不另写判法)。合格 ⇒ `[]`;否则按判序交回规则词(`not-http-url` / `userinfo` / `query` / `fragment`),词的规则句取 `httpUrlRule(词)`;答案只有词,不含值的任何片段;包根 |
+| `FLEET_ADVERTISE_ADDRESS_ENV` | 公告地址的 env 名 `"FLEET_ADVERTISE_ADDRESS"`(字面量类型),与 `FLEET_GENERATION_ENV` / `FLEET_SCOPE_ENV` 同文件同形;写的一方和读的一方都 import,不各自拼;包根与 `./fleet` |
+
+本包自己的 `webAdminSessionUrl` 已改读这一只判官(读数逐字不变)。判官今天的答案(逐行钉在 `test/path-base-url-forbids-14.7.0.test.ts`):
+
+- `http://$(POD_IP):8090` ⇒ `[]`(占位在主机位:`$` `(` `)` 都是合法主机码点);`http://10.0.0.5:8090`、`http://[fd00::1]:8090`、`https://worker.example.com` ⇒ `[]`。
+- `http://[$(POD_IP)]:8090` ⇒ `["not-http-url"]`:方括号里必须是 IPv6 字面量,占位不是 —— **判占位展开之后的值**,不判模板。
+- 路径前缀 `http://10.0.0.5:8090/prefix` ⇒ `[]`(路径不在禁用集里:要拼的路径接在前缀后面)。
+- `…?a=1`(含空 `?`)⇒ `["query"]`;`…#f`(含空 `#`)⇒ `["fragment"]`;`http://user:pw@host`(只有用户名也算)⇒ `["userinfo"]`;三件齐 ⇒ 三个词,按判序。
+- `127.0.0.1:8121`(缺 scheme)、`ftp://x:1`、`file:///etc/passwd`、`data:…`、空串 ⇒ 含 `not-http-url`(`fetch` 认 `file://` / `data:`,配错的地址不许变成读本地文件)。
+
+### 13.2 web-admin 编排器做什么
+
+- **渲染**:往成员 env 写公告地址时,键名取 `FLEET_ADVERTISE_ADDRESS_ENV`,不手写字面量。k8s 后端写 `http://$(POD_IP):<端口>` 这种形,`$(POD_IP)` 由部署后端展开。
+- **发出前判**:对**展开之后**的值调 `pathBaseUrlFlaws`,长度非 0 就是渲染器自己的配置问题 —— 拒掉并点名规则词(规则句取 `httpUrlRule`),不要静默改写(例如悄悄削掉 query):改写会把地址送到运维没写的地方。
+- **不手抄集**:不要在编排器里再写一遍 `["userinfo", "query", "fragment"]` 或自己的 URL 判法;集与判官只有本包这一份,它与引擎起服时判的是同一个答案。给用户铸会话链接用 `webAdminSessionUrl`,它判基址用的也是这一只。
+
+### 13.3 server 做什么
+
+- **读 env**:`process.env[FLEET_ADVERTISE_ADDRESS_ENV]`;不手写字面量。缺席或空串(compose 的 `${NAME:-}` 常态)⇒ 没声明地址 —— 这个读法是 server 的,不在判官里(判官对 `""` 答 `not-http-url`)。
+- **判**:非空值调 `pathBaseUrlFlaws`;长度非 0 ⇒ 拒启。运维旋钮律:无条件解析,没接中心的机器也判,形错的值不躺着等哪天生效。拒句点名没过的规则(`httpUrlRule`),**不回显值**(值里可能有凭据)。
+- **中心基址三席同一只**:`WEB_ADMIN_ENV.url` / `liveUrl` / `webUrl` 的值(起服时与请求期)和公告地址都调 `pathBaseUrlFlaws`;server 里原先本地的禁用集副本与公告地址 env 名字面量改读本包后删除,不留第二份。判官读数与改前逐字相同(词与判官同一只)。
+
+### 13.4 本包不做的(如实)
+
+- **占位展开**(`$(POD_IP)` 等):是部署后端的事,不是本包的;判官看到的永远是一个字符串。
+- **可达性**:地址真不真打得到是运维的话,判官只判形;引擎不自猜可达地址。
+- **缺席 / 空串的处置**:见 §13.3 —— 读的一方自己答。
+- **座位名册**:一个值算不算「后面要拼路径的基址」是读它的一方的事;本包给的是判这种座位的那一只判官,不维护座位清单(§13 开头列的是今天已知的读者)。
+- **不进保留 env 名表**:`FLEET_ADVERTISE_ADDRESS` 与 generation / scope 两只不同 —— 那两只只有渲染器能写,所以进 `RESERVED_WORKER_ENV`;公告地址是运维可以声明的值(渲染器也可以写),`worker.env` 设它照旧不被拒。

package/llms-full.txt

@@ -1,6 +1,6 @@
 <!--
 llms-full.txt — 自包含全文 · 消费方(使用者)视角 · @sema-agent/settings-schema
-重写日期: 2026-10-24 | 包版本: 14.6.0
+重写日期: 2026-10-25 | 包版本: 14.7.0
 生成方式: 无生成脚本——按当前树 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版。
 证据约定: 每条"它怎么工作"的断言附 (文件: 符号) 坐标,刻意不用行号(行号逐版腐烂;符号名由
 typecheck 与 test/package-surface.test.ts、test/docs-hygiene.test.ts 等常驻门钉住)。无证据推断显式标【推断】。
@@ -297,8 +297,8 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
 - `httpHookAllowlists`(src/http-hook-allowlists.ts):类目行 `SAFETY_MERGE_SPEC.httpHookAllowlists`(denyFirst / global / setNarrower / resolver / closed)。
   `HTTP_HOOK_ALLOWLIST_KEYS`;片段 `HttpHookAllowlistSettings`;层 `HttpHookAllowlistLayer = { source: SettingsSource, 两张名单? }`(只带源名,不带档);
   层读法 `readHttpHookAllowlistLayer(source, settings)` → `{ layer, malformed }`(坏形 ⇒ `[]` 并点名);
-  `httpHookUrlVerdict(url, layers, workspace)` → `undefined` | `HttpHookUrlBlock{ list:"allowedHttpHookUrls", rule:"empty"|"url", sources }`:每张**准入**名单
-  (准入 ⇔ `layerAdmission(源, 工作区读数, "httpHookAllowlists") === "admitted"` —— 源表定档、类目行定地板;闭集外的源 / 读数 RangeError)都须放行 = 跨层取交;
+  `httpHookUrlVerdict(url, layers, workspace)`(`layers` 的每一层经读器同一只读法读 —— 读器交出的 `read.layer`、手造的寻常层、本 realm 的 `JSON.parse` 出来的层同答;读不出 `source`〔缺席 / 只靠继承 / 不一致 / 非串〕的层当坏形层全拦、判决词 `malformed` 不点名;源读得出而名单读不出 ⇒ `malformed` 点名那一层;`empty` 只给真空名单)→ `undefined` | `HttpHookUrlBlock{ list:"allowedHttpHookUrls", rule:"malformed"|"empty"|"url", sources }`:每张**准入**名单
+  (准入 ⇔ `layerAdmission(源, 工作区读数, "httpHookAllowlists") === "admitted"` —— 源表定档、类目行定地板;闭集外的源 / 读数 RangeError)都须放行 = 跨层取交;名单、`hookVars`、`layers` 都只认朴素数组(原型恒等于本 realm 的 `Array.prototype`〔另一个 realm 的数组按坏形,先 JSON 往返〕、`constructor` / `filter` / `flatMap` / `Symbol.iterator` 是本 realm 的内建、自有键只有下标与 `length`;子类等一律按坏形);
   `httpHookEnvVarsAllowed(hookVars, layers, workspace)` = hook 自己的 allowedEnvVars ∩ 每张准入名单。与 CC 差:拼接 → 取交、任意层 → 准入层(SS-CCD-06 / 07)。
 - `mcpServerPolicyVerdict(server, layers)`(src/mcp-server-policy.ts)→ `undefined` | `McpPolicyBlock{ name, list, rule, target, written, sources }`;闭集 `MCP_SERVER_LIST_KEYS` /
   `MCP_POLICY_RULES`(name / command / url / empty)。层 `McpPolicyLayer = { source: SettingsSource, … }`(只带源名)。拒绝绝对优先、各层都算(名字 → 命令整数组 → URL 拒绝出口);
@@ -430,6 +430,7 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
   `HEARTBEAT_REPLY_CAPABILITIES_KEY = "capabilities"`(`WebAdminCapabilities` 的唯一载体 = 心跳 2xx 答复体的这个键,键查找在 `readCapabilityReading` 里;位按调用方凭证答,共享令牌看不到 `servingLease`);
   env 名常量 `FLEET_GENERATION_ENV` = `"FLEET_GENERATION"`(进 `RESERVED_WORKER_ENV`;渲染器与引擎共用,不各自拼;实例身份 `instanceId`(体的顶层)是引擎每进程自铸的,无 env 名)、
   `FLEET_SCOPE_ENV` = `"FLEET_SCOPE"`(8.3.0,8.3.1 注改真;成员所属租户 scope,与该成员 per-worker 令牌绑定的 scope 同值,渲染器写、引擎读作自身身份的 scope、只用来比对 `DrainRequest.scope`(请求不带 scope ⇒ 读成默认 scope)、不从令牌格式反推;续租 / 心跳的 scope 由凭证定、不取这只 env,两者同值是渲染器的义务;缺席 = 默认 scope `GLOBAL_SCOPE`;同样进 `RESERVED_WORKER_ENV`);
+  14.7.0 additive(公告地址 env 名;`.` 与 `./fleet`):env 名常量 `FLEET_ADVERTISE_ADDRESS_ENV` = `"FLEET_ADVERTISE_ADDRESS"`(成员对中心公告的可达基址,中心往它后面拼路径;渲染的一方与读的一方都 import,不各自拼;**不**进 `RESERVED_WORKER_ENV`——运维可经 `worker.env` 声明;它的判官见 4.10d);
   派发(`DISPATCH_STRATEGIES` round-robin|least-inflight|consistent-hash、`DispatchPolicy`、`pickInstance`、
   `SUBMIT_IDEMPOTENCY_KEY`);配额租约(`QuotaLease`/`leaseRemaining`/`leaseExhausted`/`shouldRenewLease`/
   `reconcileLease`);用量上报(`UsageEntry`/`UsageReport`/`aggregateUsage`/`QuotaResetEvent`)。
@@ -453,7 +454,8 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
   四个消费仓对现包名自始至终零 import —— 仅 sdk 的同源锚测试经退役包名 `registry-core` 的冻结版仍取它)。`api/scopes` 同理持有 `SCOPES_V1_PATHS`/`SCOPE_CLAIM`。
 - `api/auth-bridge`:worker 验 web-admin 签发用户 JWT 的契约——RS256-only、JWKS(`WEB_ADMIN_JWKS_PATH`,
   kid-miss 强刷 + ≥60s 节流)、时钟偏移 60s(exp / nbf / iat 同一个容忍)、24h 离线宽限后 fail-closed;`VerifierConfig`/`VerifiedIdentity`
-  (携 `scope?` 与 `iat?`:签发时刻整数秒原样带出,缺席不铸键,在场而非非负整数 ⇒ 该令牌 malformed)/`AuthBridgeErrorCode` + 纯判定 `shouldForceJwksRefresh`/`jwksWithinOfflineGrace`/
+  (携 `scope?`、`iat?` 与 `principalInc?`:`iat` 签发时刻整数秒原样带出,缺席不铸键,在场而非非负整数 ⇒ 该令牌 malformed;`principalInc`(14.7.0)= 令牌声明 `PRINCIPAL_INC_CLAIM`(`"sub_inc"`)的化身号,
+  非空串原样,缺席不铸键(从不读成 0),在场而非非空串 ⇒ 该令牌 malformed;`PrincipalIncarnation` 是所有化身号字段共读的那一只 schema)/`AuthBridgeErrorCode` + 纯判定 `shouldForceJwksRefresh`/`jwksWithinOfflineGrace`/
   `classifyTimeClaims`/`toVerifiedIdentity`/`looksLikeJwt`。
 - `api/scopes`:多租户 scope 契约——`Scope`/`ScopeMember`(viewer<editor<publisher<admin)、保留
   `GLOBAL_SCOPE="global"`、JWT `scope` claim(缺席=global);判定纯函数 `resolveTokenScope`/`canSwitchScope`/
@@ -489,6 +491,23 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
   `retiredEnvRefusal(env)`(纯,读传入的 env;码 `RETIRED_ENV_REFUSAL_CODE` = `config.env_key_retired`;只点名键不回显值);
   目录 wire 投影 `buildRetiredEnvWire()`。引擎起服 / 壳起本机引擎 / web-admin 渲染 worker env 判同一张表。
 
+--- 4.10c 沙箱 git 凭据平面(src/sandbox-git.ts + src/api/credentials.ts,主 barrel,不开子路径;14.7.0) ---
+- 沙箱里的 git 用成员本人的凭据:数据面向 web-admin 的凭据取值口按 run 身份申领句柄、凭句柄兑换。本包只有形与词表,零 IO。
+- origin 规范形:`isSandboxGitOrigin(raw)` —— 串逐字等于 `new URL(raw).origin` 且 scheme ∈ {http, https}(小写 host、去缺省端口、无尾斜杠、无 userinfo / 路径 / 查询 / 片段都是这一个等式的推论;origin 不表达子路径部署,无「削成 origin」的规范化器);
+  zod 形 `SandboxGitOrigin` / `SandboxGitOriginList`(≤ `SANDBOX_GIT_MAX_ORIGINS` = 16、两两不同、空表合法)。
+- 有效配置块 `sandboxGit`:`SandboxGitConfig` = `{ origins: [{ origin, connectUrl }] }`(`connectUrl` 过 `SandboxGitConnectUrl` = 非秘密 https URL)。`/effective` 载荷上的**非域顶层键**,可选、无默认;`readEffectiveWire` 逐字承运(`EffectiveWire.sandboxGit` 是 `unknown`),
+  消费方用 `SandboxGitConfig` 判。块里 http origin 可读(它的拒因是逐 origin 应答里的 `insecure_transport`,不是块的校验拒)。
+- 取值口 wire(`kind: "sandbox_git"`):`SandboxGitCredentialRequest`(申领)/ `CredentialHandleAnswer` / `CredentialResolveRequest`(与种类无关)/ `SandboxGitCredentialAnswer`(每 origin 一行 `SandboxGitOriginAnswer`,按 `state` 判别;
+  `secret` 只在 `active` 臂,别的臂剥掉;`needs_reauth` 行必带 `credentialId`)/ `SandboxGitCredentialRefusal`(`{ error, permanence, message }`,`permanence` 必须等于拒答表里这一行的)。解析一律剥未知键。
+- 三张词表,各一张、每个词只在 `src/api/credentials.ts` 里拼一次:`SANDBOX_GIT_ORIGIN_VERDICTS`(逐 origin 判定序表 11 行,序即判定序;`SANDBOX_GIT_ORIGIN_STATES` 六词、`SANDBOX_GIT_ORIGIN_REASONS` 十词与应答臂的原因值域由它派生)·
+  `SANDBOX_GIT_REFUSALS`(十个整次拒答词 → HTTP 状态集 + `permanence`;`SANDBOX_GIT_REFUSAL_ERRORS` 由它派生)· `SANDBOX_GIT_PERMANENCE`(`terminal` / `transient`)。两方各自怎么读:`docs/CONSUMER-INTEGRATION.md` §12。
+
+--- 4.10d 「后面要拼路径的基址」座位判官(src/url-shape.ts,主 barrel;14.7.0) ---
+- 一种座位的值是别人要往它后面拼路径的基址(中心基址三席、成员对中心公告的地址 `FLEET_ADVERTISE_ADDRESS_ENV`、会话链接的基址):不许带凭据 / query / fragment,路径前缀放行。
+- `PATH_BASE_URL_FORBIDDEN_PARTS`:这种座位禁用的 URL 成分,闭集、冻结、判序 `userinfo` · `query` · `fragment`(策略集,独立于判官词表 `HTTP_URL_PARTS`:词表说 URL 有哪些成分,本集说这种座位禁哪些;今天碰巧同三词,不由词表派生,词表加词时要显式裁)。
+- `pathBaseUrlFlaws(url)` = `httpUrlFlaws(url, PATH_BASE_URL_FORBIDDEN_PARTS)`:`[]` = 合格,否则按判序交回规则词(`not-http-url` / `userinfo` / `query` / `fragment`),不含值的片段;
+  判占位展开之后的值(`http://$(POD_IP):8090` 过,`http://[$(POD_IP)]:8090` 拒);`webAdminSessionUrl` 也读它。占位展开、可达性、缺席 / 空串的处置不在本包;两方读法见 `docs/CONSUMER-INTEGRATION.md` §13。
+
 --- 4.11 Node-only(`./node`:file-store / file-edit / bundle / local-load / scheduler-store-node / 目录迁移) ---
 - `loadLocalConfig(root, {onWarning}?)` → `LocalConfig { effective, remoteExec, env, requiredEnv, warnings }`。
 - `loadRemoteExec(root)`(三态,§8 T3)、`writeRemoteExec`(校验+原子写)、`remoteExecPath`、`loadEnvFile`

package/llms.txt

@@ -1,6 +1,6 @@
 <!--
 llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
-重写日期: 2026-10-24 | 包版本: 14.6.0
+重写日期: 2026-10-25 | 包版本: 14.7.0
 生成方式: 无生成脚本——按当前树的 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版;
 每条断言附证据坐标(文件:符号),刻意不用行号(行号随每版腐烂,符号名由 typecheck/test 钉住)。
 刷新触发: package.json 版号变更(test/docs-hygiene.test.ts D 组钉「包版本:」与 package.json 相等、
@@ -110,7 +110,7 @@ llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
   http/https/ws/wss 且 `ws+unix:` 套接字段逐字、解析不出的模式不放、解码出的字面 `*` 不当通配)/ `urlDenyPatternMatches`(⊇ `g9` ∪ 整串 glob)。
   偏离登 `docs/CC-DIVERGENCE.md`。(src/url-pattern.ts)
 - **http hook 两张名单**(13.0.0):类目 `SAFETY_MERGE_SPEC.httpHookAllowlists`(地板 global);`readHttpHookAllowlistLayer(source, settings)`(坏形读成 `[]`)·
-  `httpHookUrlVerdict(url, layers, workspace)` → `HttpHookUrlBlock{list, rule, sources}` 或 `undefined`(每张准入名单都须放行 = 跨层取交)·
+  `httpHookUrlVerdict(url, layers, workspace)`(`layers` 的每一层经读器同一只读法读 —— 读器交出的 `read.layer`、手造的寻常层、本 realm 的 `JSON.parse` 出来的层同答;另一个 realm 的数组按坏形全拦)→ `HttpHookUrlBlock{list, rule, sources}` 或 `undefined`(每张准入名单都须放行 = 跨层取交)·
   `httpHookEnvVarsAllowed(hookVars, layers, workspace)`(取交);准入 ⇔ `layerAdmission(源, 工作区读数, "httpHookAllowlists") === "admitted"`。
   (src/http-hook-allowlists.ts)
 - **MCP 名单判决**(13.0.0):`mcpServerPolicyVerdict(server, layers)` → `McpPolicyBlock{name, list, rule, target, written, sources}` 或 `undefined`;
@@ -141,6 +141,7 @@ llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
   判官只读信号:`judgeReadiness(signal)` / `judgeRoutability(row, nowMs)` → `{ routable }` 或 `{ routable:false, code ∈ NOT_ROUTABLE_CODES, why }`,
   `isReadyForTraffic` / `isRoutable` 是它们的布尔形;没有信号(旧引擎)= `no-engine-signal`,不可路由;布尔对 `draining` / `drainingSince` 标 `@deprecated`、本包零读点、退役已登记;
   8.3.0 additive:env 名常量 `FLEET_SCOPE_ENV`(`"FLEET_SCOPE"`,成员所属租户 scope,渲染器写、引擎读;缺席 = 默认 scope `GLOBAL_SCOPE`;进保留 env 名表);
+  14.7.0 additive:公告地址 env 名常量 `FLEET_ADVERTISE_ADDRESS_ENV`(`"FLEET_ADVERTISE_ADDRESS"`)+「后面要拼路径的基址」座位的禁用成分集 `PATH_BASE_URL_FORBIDDEN_PARTS`(`userinfo` / `query` / `fragment`)+ 判官 `pathBaseUrlFlaws(url)`(= `httpUrlFlaws` 配这一集;判展开之后的值;`webAdminSessionUrl` 也读它);
   9.0.0 BREAKING:`readCenterCapabilities` 删,换三态读器 `readCapabilityReading(reply): CapabilityReading`(`declared` | `undeclared` | `unreadable`;键在场而形坏 ≠ 没宣告)、`EngineSignal.configTargetVersion` / `configAppliedVersion` 由串改数)、**scheduler-store 契约**(自唤醒
   存储形 + node 绑定)、**auth / auth-bridge / scopes / wire** 契约(RFC 8628 设备流、RS256 JWKS 鉴权桥、
   多租户 scope)。(src/fleet.ts;src/scheduler-store*.ts;src/api/*.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "14.6.0",
+  "version": "14.7.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-web-admin, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",