@sema-agent/settings-schema 11.0.0 → 11.2.0

package/dist/node.d.ts

@@ -10,3 +10,5 @@ export * from "./bundle.js";
 export * from "./local-load.js";
 export * from "./scheduler-store-node.js";
 export * from "./prompts-digest.js";
+export { migrateConfigDirectory, type ConfigDirectoryIo, type ConfigDirectoryMigration, type ConfigDirectoryRefusal, type MigrateConfigDirectoryOptions } from "./config-dir-migration.js";
+export { nodeConfigDirectoryIo } from "./config-dir-io.js";

package/dist/node.js

@@ -10,3 +10,6 @@ export * from "./bundle.js";
 export * from "./local-load.js";
 export * from "./scheduler-store-node.js"; // R7 self-wake scheduler store — fs binding of the ./scheduler-store contract
 export * from "./prompts-digest.js"; // prompts 下发包的内容摘要(4.0.0 从 scheduler-store-node 搬来 —— 与调度存储无关;出口路径不变)
+// 目录形的一次性迁移(读目录 → 迁 → 整域终判 → 原子写 → 删 retired 域文件)—— 语义只此一处,命令行是它的渲染器、引擎起服调同一只。显式列名:该模块的包内私有件(出门形/拼路径)不外泄。
+export { migrateConfigDirectory } from "./config-dir-migration.js";
+export { nodeConfigDirectoryIo } from "./config-dir-io.js"; // 上面那只函数的真 I/O 绑定:node:fs + 本包唯一的原子写器(config-document 模式规则)

package/dist/one-time-migrations.d.ts

@@ -9,6 +9,12 @@ export type WireRetirementId = (typeof WIRE_RETIREMENT_IDS)[number];
 export interface OneTimeMigrationWindow {
     /** 数据迁移 id(闭集 `ONE_TIME_MIGRATION_IDS`)或 wire 删码位 id(闭集 {@link WIRE_RETIREMENT_IDS});两集合起来每个 id 恰一行。 */
     readonly id: OneTimeMigrationId | WireRetirementId;
+    /** 旧形在读侧的待遇(闭集,每词一义;「读写两面遇旧形一律响亮拒,拒句点名迁移 id」这条律的例外只在这一格里写):
+     *   · `refused`           — 读写两面拒,拒句点名本行 id(经 `migrationSignpost` 铸;钉:每个 `refused` 行的 id 在 `src/` 至少一处铸点,
+     *                           且非 `refused` 行零铸点);
+     *   · `rewritten-on-read` — 读时改写、不拒(SS-M3:调度店的下一个写者落盘),没有拒句可点名;
+     *   · `not-stored`        — 没有存储形(wire 删码位),谈不上拒。 */
+    readonly oldForm: "refused" | "rewritten-on-read" | "not-stored";
     /** 引入这条迁移的版本。 */
     readonly introducedIn: string;
     /** 该版本在 npm 上的发布日(UTC 日历日 YYYY-MM-DD)。`null` = 未发布形,由抬 `package.json` 到 `introducedIn` 的发布准备提交回填。 */

package/dist/one-time-migrations.js

@@ -33,6 +33,7 @@ import { outgoingPath, redactSecrets } from "./config-fns.js";
 import { LANE_ENV_OWNER, STORE_ENV_KEYS, isLaneEnvKey } from "./execution-lane-index.js";
 import { EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, STORE_BACKENDS } from "./execution-lanes.js";
 import { INTEGER } from "./integer.js";
+import { RUNTIME_LIFT_TARGETS } from "./runtime-lift-targets.js";
 import { DOMAIN_SCHEMAS, HOSTS_ARRAY_MAX, HOST_NAME_MAX, NON_SECRET_URL, isDomainName, isRetiredDomainName } from "./types.js";
 import { workerRowVerdict } from "./worker-row-verdict.js";
 import { unwrapSchema } from "./zod-unwrap.js";
@@ -45,6 +46,7 @@ export const WIRE_RETIREMENT_IDS = ["SS-W1"];
 export const ONE_TIME_MIGRATIONS = [
     {
         id: "SS-M1",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -60,6 +62,7 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M2",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -71,6 +74,7 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M3",
+        oldForm: "rewritten-on-read",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -83,6 +87,7 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M4",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -95,6 +100,7 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M5",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -104,6 +110,7 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M6",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -115,17 +122,19 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M7",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
         rewrites: "every NON_SECRET_URL seat in a domain document (derived from the domain schemas, not listed by hand — today models.models[].baseUrl, " +
             "mcp.servers[].transport.url, execution.sessionMirror.engineUrl, workers.workers[].coords.gitApiBaseUrl): `#` and everything after it are removed " +
             "(a fragment never goes on the wire)",
-        removal: "the next major after the window: delete the SS-M7 step and its schema walk",
+        removal: "the next major after the window: delete the SS-M7 step and its schema walk; the NON_SECRET_URL fragment rule loses its SS-M7 clause",
         afterRemoval: "the NON_SECRET_URL shape judge, which refuses a fragment (`#` included) on read and write",
     },
     {
         id: "SS-M9",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -139,6 +148,7 @@ export const ONE_TIME_MIGRATIONS = [
     {
         // 一条 wire 位的删码登记,不是数据迁移(id 在 WIRE_RETIREMENT_IDS,不在收据闭集)。
         id: "SS-W1",
+        oldForm: "not-stored",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -257,7 +267,7 @@ function stepRuntimeDomain(out, coverage, receipts) {
     }
     if (!isPlainObject(raw))
         return refuse("the stored runtime document is not a JSON object — the scope does not read today either; fix it by hand");
-    if (coverage === "partial" && !(has(out, "governance") && has(out, "limits"))) {
+    if (coverage === "partial" && !RUNTIME_LIFT_TARGETS.every((target) => has(out, target))) {
         return refuse("a runtime document migrates only together with its scope's governance and limits documents (coverage \"scope\") — on its own there is no telling whether governance was ever set");
     }
     const parsed = RUNTIME_10X.safeParse(raw);

package/dist/previous-web-admin-env.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 上一代 web-admin 连接名(`SEMA_REGISTRY_*`)—— **包内私有**(不进主桶、不进 exports 表):上一代名字面只在这里写一次,
+ * 两个读者各取所需:墓碑表 `RETIRED_ENVS`(旧名 → `WEB_ADMIN_ENV` 同键的现名)与保留 env 名表(渲染器在改名窗里对还读上一代名的引擎
+ * 仍写的三名)。键与 {@link WEB_ADMIN_ENV} 同键 —— 现名与上一代名按键配对,去向从 `WEB_ADMIN_ENV` 取、不手抄。
+ *
+ * 断言令牌(`assertionToken` / `assertionTokenFile`)是上一代之后才有的两键,没有上一代名;映射型 `Exclude` 掉它们,所以 `WEB_ADMIN_ENV`
+ * 日后再加键时,这里必须当场表态(有上一代名就写,没有就加进 `Exclude`)—— 否则编译红。
+ */
+import { WEB_ADMIN_ENV } from "./web-admin-env.js";
+/** 有上一代名的键(= `WEB_ADMIN_ENV` 去掉断言令牌两键)。 */
+export type PreviousWebAdminEnvKey = Exclude<keyof typeof WEB_ADMIN_ENV, "assertionToken" | "assertionTokenFile">;
+/** 上一代名,按 `WEB_ADMIN_ENV` 的键配对。 */
+export declare const PREVIOUS_WEB_ADMIN_ENV: {
+    readonly [K in PreviousWebAdminEnvKey]: string;
+};

package/dist/previous-web-admin-env.js

@@ -0,0 +1,20 @@
+/**
+ * 上一代 web-admin 连接名(`SEMA_REGISTRY_*`)—— **包内私有**(不进主桶、不进 exports 表):上一代名字面只在这里写一次,
+ * 两个读者各取所需:墓碑表 `RETIRED_ENVS`(旧名 → `WEB_ADMIN_ENV` 同键的现名)与保留 env 名表(渲染器在改名窗里对还读上一代名的引擎
+ * 仍写的三名)。键与 {@link WEB_ADMIN_ENV} 同键 —— 现名与上一代名按键配对,去向从 `WEB_ADMIN_ENV` 取、不手抄。
+ *
+ * 断言令牌(`assertionToken` / `assertionTokenFile`)是上一代之后才有的两键,没有上一代名;映射型 `Exclude` 掉它们,所以 `WEB_ADMIN_ENV`
+ * 日后再加键时,这里必须当场表态(有上一代名就写,没有就加进 `Exclude`)—— 否则编译红。
+ */
+import { WEB_ADMIN_ENV } from "./web-admin-env.js";
+/** 上一代名,按 `WEB_ADMIN_ENV` 的键配对。 */
+export const PREVIOUS_WEB_ADMIN_ENV = {
+    url: "SEMA_REGISTRY_URL",
+    token: "SEMA_REGISTRY_TOKEN",
+    tokenFile: "SEMA_REGISTRY_TOKEN_FILE",
+    worker: "SEMA_REGISTRY_WORKER",
+    liveUrl: "SEMA_REGISTRY_LIVE_URL",
+    webUrl: "SEMA_REGISTRY_WEB_URL",
+    dryRun: "SEMA_REGISTRY_DRY_RUN",
+    adminToken: "SEMA_REGISTRY_ADMIN_TOKEN",
+};

package/dist/remote-exec.js

@@ -28,7 +28,7 @@
  */
 import { z } from "zod";
 import { INTEGER } from "./integer.js";
-import { ENV_NAME, K8S_QUANTITY, NON_SECRET_URL, TCP_PORT, containsSecretToken, hasNul } from "./types.js";
+import { ENV_NAME, K8S_QUANTITY, NON_SECRET_URL_NO_MIGRATION, TCP_PORT, containsSecretToken, hasNul } from "./types.js";
 import { retiredLaneWordRefusal } from "./execution-lanes.js";
 /** A non-empty exec-bound string (an image / path / shell / arg the adapter feeds to spawn()/fs). Rejects a NUL
  *  byte uniformly — a NUL validates here but makes Node throw at spawn/boot (fail-OPEN → runtime crash). R20. */
@@ -84,7 +84,7 @@ export const RemoteExecSpec = z.discriminatedUnion("provider", [
         /** Sandbox container image (service: K8S_SANDBOX_IMAGE). Required so a run is reproducible. */
         image: execStr,
         /** Kube API URL (service: K8S_API_URL); absent → in-cluster service account. NO embedded credentials. */
-        apiUrl: NON_SECRET_URL.optional(),
+        apiUrl: NON_SECRET_URL_NO_MIGRATION.optional(),
         /** env-NAME holding the kube bearer token (service: K8S_TOKEN). NEVER the token. */
         tokenEnv: ENV_NAME.optional(),
         /** env-NAME holding the base64 CA cert (service: K8S_CA_CERT_B64). NEVER the cert bytes. */
@@ -102,7 +102,7 @@ export const RemoteExecSpec = z.discriminatedUnion("provider", [
          *  "all three of endpoint/access/secret required" gate). */
         s3Snapshot: z
             .object({
-            endpoint: NON_SECRET_URL, // S3/MinIO endpoint — creds go in accessKeyEnv/secretKeyEnv, never the URL
+            endpoint: NON_SECRET_URL_NO_MIGRATION, // S3/MinIO endpoint — creds go in accessKeyEnv/secretKeyEnv, never the URL
             bucket: execStr.optional(),
             accessKeyEnv: ENV_NAME,
             secretKeyEnv: ENV_NAME,

package/dist/retired-envs.js

@@ -2,8 +2,8 @@
  * 退役 env 名的**墓碑表** —— 一张表,本包是它的唯一属主:引擎(server)起服时按它拒启、目录 wire 的 `retired[]` 由它投影,
  * 壳在起本机引擎之前、web-admin 在给 worker 渲染 env 之前读同一张(谁都不再手抄、不再从别人的构建产物里正则抽)。
  *
- * **进表的判据(一条):没有任何受支持的引擎还读这个名。** 一个名字还被在跑的引擎当活旋钮读时就进表,等于让照旧配置的部署拒启 ——
- * 改名的那一版只登记现名,旧名等引擎换读现名之后的那一版再进表。
+ * **进表的判据(一条):没有带着本表的引擎还读这个名。** 更老的引擎内带的是更老的契约版本,看不见这张表,它们读不读某个名由它们自己的版本定;
+ * 一个名字只要还有带着本表的引擎把它当活旋钮读,进表就等于让照旧配置的部署拒启 —— 改名的那一版只登记现名,旧名等引擎换读现名之后的那一版再进表。
  *
  * 🪦 **墓碑是永久的响亮拒,不设到期**。一行墓碑就是那句拒启句本身,成本一行;删掉它 = 旧名重新被悄悄忽略。
  * ⇒ 本表只增不减,**唯一的删除条件是这个名字要被赋予新含义**:那一次提交同时删掉这一行,并在发布说明里写明旧名改作何用。
@@ -25,6 +25,7 @@
  *
  * 行形 = 字面元组(第三元是族词),一行一个旧名。纯数据 + 纯函数,零 IO,browser-safe。
  */
+import { PREVIOUS_WEB_ADMIN_ENV } from "./previous-web-admin-env.js";
 import { WEB_ADMIN_ENV } from "./web-admin-env.js";
 /** 墓碑拒启码(机读;拒句方括号里)。 */
 export const RETIRED_ENV_REFUSAL_CODE = "config.env_key_retired";
@@ -38,6 +39,16 @@ export const RETIRED_ENVS = [
     ["TIDB_DATABASE", "MYSQL_DATABASE", "renamed"],
     ["TIDB_POOL_SIZE", "MYSQL_POOL_SIZE", "renamed"],
     ["ANTHROPIC_BASEURL", "ANTHROPIC_BASE_URL", "renamed"],
+    // web-admin 连接名上一代的 `SEMA_REGISTRY_*` 八名,直指同键的现名(一跳;旧名取上一代名表、去向取 `WEB_ADMIN_ENV`,本行不写任何这类字面)。
+    // 引擎换读现名之后才进表:读侧同代要求 —— 引擎至少是换读现名的那一版,更老的引擎仍把它们当活旋钮读。
+    [PREVIOUS_WEB_ADMIN_ENV.url, WEB_ADMIN_ENV.url, "renamed"],
+    [PREVIOUS_WEB_ADMIN_ENV.token, WEB_ADMIN_ENV.token, "renamed"],
+    [PREVIOUS_WEB_ADMIN_ENV.tokenFile, WEB_ADMIN_ENV.tokenFile, "renamed"],
+    [PREVIOUS_WEB_ADMIN_ENV.worker, WEB_ADMIN_ENV.worker, "renamed"],
+    [PREVIOUS_WEB_ADMIN_ENV.liveUrl, WEB_ADMIN_ENV.liveUrl, "renamed"],
+    [PREVIOUS_WEB_ADMIN_ENV.webUrl, WEB_ADMIN_ENV.webUrl, "renamed"],
+    [PREVIOUS_WEB_ADMIN_ENV.dryRun, WEB_ADMIN_ENV.dryRun, "renamed"],
+    [PREVIOUS_WEB_ADMIN_ENV.adminToken, WEB_ADMIN_ENV.adminToken, "renamed"],
     // web-admin 连接名两代前的 `CONFIG_CENTER_*` / `REGISTRY_ADMIN_TOKEN`,直指现名(一跳)。
     ["CONFIG_CENTER_URL", WEB_ADMIN_ENV.url, "renamed"],
     ["CONFIG_CENTER_TOKEN", WEB_ADMIN_ENV.token, "renamed"],

package/dist/retired-form.d.ts

@@ -9,9 +9,14 @@
  * 墓碑留下 —— 到那时拒句里的迁移 id 由删码那一车改写(登记表那一行的 `removal` 点名了这件事)。
  */
 import { z } from "zod";
-/** 迁移命令行的唯一拼写:`npx` 全名形 —— 没装本包的运维粘贴即可跑(裸 bin 名在没装本包的机器上是 `command not found`)。参数是一个 `config.d` 目录。 */
+/** 迁移命令行的唯一拼写:`npx` 全名形 —— 没装本包的运维粘贴即可跑(裸 bin 名在没装本包的机器上是 `command not found`)。参数是一个 `config.d` 目录。
+ *  印出命令的地方只有下面两只:带目录占位的模板 {@link MIGRATE_COMMAND_TEMPLATE}(USAGE、迁移指路句)与带真路径的 {@link migrateCommandFor}(指路到某个具体目录)。 */
 export declare const MIGRATE_COMMAND: "npx @sema-agent/settings-schema migrate";
-/** 拒句尾的迁移指路:存量由哪一条一次性迁移改写、两种跑法(子路径的函数 / 目录命令)。`before` = 旧形不再合法的那一版。
+/** 命令加目录占位 —— 用法行与迁移指路句里印的形。`<config.d directory>` 是元变量(读者替换成自己的目录),不是参数,所以不引用。 */
+export declare const MIGRATE_COMMAND_TEMPLATE: "npx @sema-agent/settings-schema migrate <config.d directory>";
+/** 指到某个具体目录的命令:路径过 `shellQuote`(含空格 / 特殊字符才加引号)—— 印出来的句子可以直接粘贴去跑。 */
+export declare function migrateCommandFor(configDir: string): string;
+/** 拒句尾的迁移指路:存量由哪一条一次性迁移改写、两种跑法(子路径的函数 / 目录命令;目录是 `config.d` 目录本身,不是它的上一层)。`before` = 旧形不再合法的那一版。
  *  刻意短:它挂在 zod issue 句尾,读侧逐条容错时每一条被丢的条目都要过一遍出门脱敏。 */
 export declare function migrationSignpost(migration: string, before: string): string;
 /** 一个retired 形的整句:`<form> was retired in <版本> — now <今天住哪>; <指路>`。 */

package/dist/retired-form.js

@@ -9,12 +9,20 @@
  * 墓碑留下 —— 到那时拒句里的迁移 id 由删码那一车改写(登记表那一行的 `removal` 点名了这件事)。
  */
 import { z } from "zod";
-/** 迁移命令行的唯一拼写:`npx` 全名形 —— 没装本包的运维粘贴即可跑(裸 bin 名在没装本包的机器上是 `command not found`)。参数是一个 `config.d` 目录。 */
+import { shellQuote } from "./shell-quote.js";
+/** 迁移命令行的唯一拼写:`npx` 全名形 —— 没装本包的运维粘贴即可跑(裸 bin 名在没装本包的机器上是 `command not found`)。参数是一个 `config.d` 目录。
+ *  印出命令的地方只有下面两只:带目录占位的模板 {@link MIGRATE_COMMAND_TEMPLATE}(USAGE、迁移指路句)与带真路径的 {@link migrateCommandFor}(指路到某个具体目录)。 */
 export const MIGRATE_COMMAND = "npx @sema-agent/settings-schema migrate";
-/** 拒句尾的迁移指路:存量由哪一条一次性迁移改写、两种跑法(子路径的函数 / 目录命令)。`before` = 旧形不再合法的那一版。
+/** 命令加目录占位 —— 用法行与迁移指路句里印的形。`<config.d directory>` 是元变量(读者替换成自己的目录),不是参数,所以不引用。 */
+export const MIGRATE_COMMAND_TEMPLATE = `${MIGRATE_COMMAND} <config.d directory>`;
+/** 指到某个具体目录的命令:路径过 `shellQuote`(含空格 / 特殊字符才加引号)—— 印出来的句子可以直接粘贴去跑。 */
+export function migrateCommandFor(configDir) {
+    return `${MIGRATE_COMMAND} ${shellQuote(configDir)}`;
+}
+/** 拒句尾的迁移指路:存量由哪一条一次性迁移改写、两种跑法(子路径的函数 / 目录命令;目录是 `config.d` 目录本身,不是它的上一层)。`before` = 旧形不再合法的那一版。
  *  刻意短:它挂在 zod issue 句尾,读侧逐条容错时每一条被丢的条目都要过一遍出门脱敏。 */
 export function migrationSignpost(migration, before) {
-    return `data stored before ${before}: run the one-time migration ${migration} (@sema-agent/settings-schema/one-time-migrations, or ${MIGRATE_COMMAND} <dir>)`;
+    return `data stored before ${before}: run the one-time migration ${migration} (@sema-agent/settings-schema/one-time-migrations, or ${MIGRATE_COMMAND_TEMPLATE})`;
 }
 export function retiredFormSentence(form, t) {
     return `${form} was retired in ${t.retiredIn} — now ${t.now}; ${migrationSignpost(t.migration, t.retiredIn)}`;

package/dist/runtime-lift-targets.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):一次性迁移 SS-M1 把 retired 的 `runtime` 域迁出时**写入的目标域** —— 治理三闸去 `governance`,五个限额键去 `limits`。
+ * SS-M1 要判「目标域从未设过」还是「设过、设过的赢」,所以它需要同时看见这两份文档:`coverage: "scope"` 的意思就是「缺席的域从未设过」,
+ * 而 `"partial"` 只在两份都给了的时候才迁(否则拒)。谁要把一组文档按「覆盖面」交给 SS-M1(目录迁移),覆盖面含这两个域才算一个 scope;一个域也不能少 ——
+ * 少了,迁出的旧值会覆盖覆盖面外已有的那份。一处写名字,SS-M1 的偏集检查与目录迁移的覆盖面判定都读它;一道钉拿真跑 SS-M1 的读数核这个常量。
+ */
+export declare const RUNTIME_LIFT_TARGETS: readonly ["governance", "limits"];

package/dist/runtime-lift-targets.js

@@ -0,0 +1,7 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):一次性迁移 SS-M1 把 retired 的 `runtime` 域迁出时**写入的目标域** —— 治理三闸去 `governance`,五个限额键去 `limits`。
+ * SS-M1 要判「目标域从未设过」还是「设过、设过的赢」,所以它需要同时看见这两份文档:`coverage: "scope"` 的意思就是「缺席的域从未设过」,
+ * 而 `"partial"` 只在两份都给了的时候才迁(否则拒)。谁要把一组文档按「覆盖面」交给 SS-M1(目录迁移),覆盖面含这两个域才算一个 scope;一个域也不能少 ——
+ * 少了,迁出的旧值会覆盖覆盖面外已有的那份。一处写名字,SS-M1 的偏集检查与目录迁移的覆盖面判定都读它;一道钉拿真跑 SS-M1 的读数核这个常量。
+ */
+export const RUNTIME_LIFT_TARGETS = ["governance", "limits"];

package/dist/scheduler-store-node.d.ts

@@ -9,9 +9,10 @@ import { type SchedulerParseWarning, type SchedulerReadOptions, type SchedulerRe
  */
 export declare function loadSchedulerStore(path: string, opts: SchedulerReadOptions): SchedulerStoreRead;
 /**
- * Persist ATOMICALLY: `mkdir -p` the parent, write a uniquely-named `.tmp` sibling (mode 0o600 — owner-only, the
- * records may carry principal/session identifiers), then `rename` over the target (atomic on POSIX, so a
- * concurrent reader never sees a partial file). Throws on IO failure (caller maps to a domain error).
+ * Persist ATOMICALLY: `mkdir -p` the parent, then the package's one atomic writer (`./atomic-write`: a uniquely-named `.tmp`
+ * sibling, then `rename` over the target — atomic on POSIX, so a concurrent reader never sees a partial file). The file mode
+ * is the `scheduler-store` class's (0o600 — owner-only, the records may carry principal/session identifiers; every save
+ * restores it). Throws on IO failure (caller maps to a domain error).
  */
 export declare function saveSchedulerStore(path: string, records: SchedulerRecord[]): void;
 /** A filesystem-backed {@link SchedulerStore} bound to a path (convenience for the daemon/backend constructors).

package/dist/scheduler-store-node.js

@@ -6,9 +6,9 @@
  *
  * Store path = caller-supplied; both sides agree on `SEMA_CONFIG_DIR` → `~/.sema/scheduled_tasks.json`.
  */
-import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { writeFileAtomic } from './atomic-write.js';
 import { parseSchedulerStore, serializeSchedulerStore } from './scheduler-store.js';
 /**
  * Load the durable store. A MISSING file (ENOENT) ⇒ no records, no warnings (first-run/never-written case); any OTHER
@@ -31,15 +31,14 @@ export function loadSchedulerStore(path, opts) {
     return parseSchedulerStore(text, opts);
 }
 /**
- * Persist ATOMICALLY: `mkdir -p` the parent, write a uniquely-named `.tmp` sibling (mode 0o600 — owner-only, the
- * records may carry principal/session identifiers), then `rename` over the target (atomic on POSIX, so a
- * concurrent reader never sees a partial file). Throws on IO failure (caller maps to a domain error).
+ * Persist ATOMICALLY: `mkdir -p` the parent, then the package's one atomic writer (`./atomic-write`: a uniquely-named `.tmp`
+ * sibling, then `rename` over the target — atomic on POSIX, so a concurrent reader never sees a partial file). The file mode
+ * is the `scheduler-store` class's (0o600 — owner-only, the records may carry principal/session identifiers; every save
+ * restores it). Throws on IO failure (caller maps to a domain error).
  */
 export function saveSchedulerStore(path, records) {
     mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.${randomBytes(6).toString('hex')}.tmp`;
-    writeFileSync(tmp, serializeSchedulerStore(records), { mode: 0o600 });
-    renameSync(tmp, path); // atomic over the target
+    writeFileAtomic(path, serializeSchedulerStore(records), 'scheduler-store');
 }
 /** A filesystem-backed {@link SchedulerStore} bound to a path (convenience for the daemon/backend constructors).
  *

package/dist/shell-quote.d.ts

@@ -0,0 +1 @@
+export declare function shellQuote(arg: string): string;

package/dist/shell-quote.js

@@ -0,0 +1,14 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):**一只** shell 引用 —— 命令行印出来、要让人粘贴去跑的命令里,路径一律过它。
+ *
+ * POSIX 单引号规则:整串包进 `'…'`,串里的 `'` 写成 `'\''`(结束引号 + 转义的引号 + 重新开引号);单引号里除 `'` 外一切字面,所以 `$` / 反引号 / 反斜杠 / 空格 /
+ * 换行都不再被 shell 解释。**只有安全字符集里的串原样返回、不加引号**:ASCII 字母数字与 `_ @ + : , . / -`。其余一律引用 —— 包括行首的 `~`(否则被展开成家目录)、
+ * `=`(zsh 里行首 `=cmd` 展开成命令路径)、`%`、通配符与非 ASCII(保守:引用永远安全,多包一层引号不会让命令失效)。空串写成 `''`(否则命令少一个参数)。
+ * 目标是 POSIX shell(sh / bash / zsh);Windows cmd.exe 不认单引号,不在范围内。
+ */
+const SHELL_SAFE = /^[A-Za-z0-9_@+:,./-]+$/;
+export function shellQuote(arg) {
+    if (SHELL_SAFE.test(arg))
+        return arg;
+    return `'${arg.replaceAll("'", "'\\''")}'`;
+}

package/dist/types.d.ts

@@ -62,10 +62,18 @@ export declare function urlQueryFragmentHasSecret(u: URL): boolean;
 /** A URL handed to `fetch` that carries no credential: judged by THE URL shape judge ({@link httpUrlFlaws}, `./url-shape`) — a
  *  hierarchical http(s) URL with neither userinfo nor a fragment (an empty `#` included, 11.0.0) — and with no secret-shaped value
  *  in its path or query ({@link urlQueryFragmentHasSecret}). One issue per flaw, its message the judge's rule sentence (no value
- *  echoed); `params.flaw` carries the rule word.
+ *  echoed; a fragment's also names its migration, {@link nonSecretUrlSentence}); `params.flaw` carries the rule word.
+ *
+ *  This is the seat of every URL in a stored DOMAIN document (models `baseUrl`, mcp `url`, `sessionMirror.engineUrl`, workers
+ *  `gitApiBaseUrl`). A URL outside the domain documents — `remote-exec.json`'s endpoints, the web-admin credential envelope's
+ *  `issuer` — uses {@link NON_SECRET_URL_NO_MIGRATION}.
  *
  *  The value is kept EXACTLY as written: nothing here trims or normalizes it (zod's own `.url()` would hand back a rewritten string). */
 export declare const NON_SECRET_URL: z.ZodString;
+/** {@link NON_SECRET_URL}'s judge for a seat no one-time migration reaches (not a domain document): identical rules and rule
+ *  sentences, but a fragment's refusal carries no migration signpost — pointing at a migration that cannot rewrite the value would
+ *  send the operator to a command that does nothing for it. */
+export declare const NON_SECRET_URL_NO_MIGRATION: z.ZodString;
 /** Validate a free-form `extraBody`: returns true = UNSAFE (reject). A GETTER-FREE, descriptor-based, bounded
  *  walk that rejects — WITHOUT ever invoking a getter (a malicious getter could throw a secret-bearing message,
  *  or return different values across the validate vs persist JSON.stringify calls) — anything that isn't plain

package/dist/types.js

@@ -24,6 +24,7 @@ import { isLoopbackAuthHost } from "./loopback.js";
 import { httpUrlFlaws, httpUrlRule } from "./url-shape.js"; // 11.0.0: THE URL shape judge // 11.0.0: the one narrow「本机」predicate (auth relaxation)
 import { secretScanForms } from "./secret-scan.js"; // package-private normalization — the one set of forms both scanners read (not in the barrel)
 import { WEB_ADMIN_ENV } from "./web-admin-env.js"; // the three connection keys the config renderer writes are reserved worker env
+import { PREVIOUS_WEB_ADMIN_ENV } from "./previous-web-admin-env.js"; // the previous generation's names of those three (the renderer still writes them for engines that read them)
 import { retiredEnvRefusal } from "./retired-envs.js"; // the worker env write gate asks the retired-env tombstone table too (one table, one refusal sentence)
 import { Sha256Digest } from "./sha256.js"; // the one `sha256:<hex>` digest form
 import { EXECUTION_LANES, EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS, retiredLaneWordRefusal } from "./execution-lanes.js"; // 7.0.0 M-R2: the lane / store vocabulary (one exported table)
@@ -168,20 +169,52 @@ export function urlQueryFragmentHasSecret(u) {
  *  after it is dropped with it — the engine and server refuse a model route root that carries one, so a stored one only fails
  *  later, on the worker). A query is a legitimate request parameter (`?api-version=…`) and stays. */
 const NON_SECRET_URL_FORBIDS = ["userinfo", "fragment"];
+/** The refusal sentence of one flaw at a {@link NON_SECRET_URL} seat: the judge's rule sentence, and — for the one flaw that stored data
+ *  can carry from before 11.0.0 (a fragment) at a seat the one-time migration reaches — the signpost to the migration that strips
+ *  it, joined the way the other signposted refusals join it (`<rule>; <signpost>`). Closed over the judge's flaw words: a new word is
+ *  a compile error here. */
+function nonSecretUrlSentence(flaw, reachedByMigration) {
+    switch (flaw) {
+        case "fragment":
+            return reachedByMigration ? `${httpUrlRule(flaw)}; ${migrationSignpost("SS-M7", "11.0.0")}` : httpUrlRule(flaw);
+        case "not-http-url":
+        case "userinfo":
+        case "query":
+            return httpUrlRule(flaw);
+        default: {
+            const unhandled = flaw;
+            throw new Error("nonSecretUrlSentence: unhandled flaw word", { cause: unhandled });
+        }
+    }
+}
+/** One judge, two seat kinds — the only difference is the fragment refusal's migration signpost. `reachedByMigration` = the seat sits in a
+ *  stored domain document, which the one-time migration SS-M7 rewrites (it finds its seats by this schema's identity, so "carries the
+ *  signpost" and "is rewritten by SS-M7" cannot drift apart). */
+function createNonSecretUrl(reachedByMigration) {
+    return z.string().superRefine((s, ctx) => {
+        const flaws = httpUrlFlaws(s, NON_SECRET_URL_FORBIDS);
+        for (const flaw of flaws)
+            ctx.addIssue({ code: "custom", message: nonSecretUrlSentence(flaw, reachedByMigration), params: { flaw } });
+        if (flaws.length === 0 && urlQueryFragmentHasSecret(new URL(s))) {
+            ctx.addIssue({ code: "custom", message: "must not carry a secret-shaped value in its path or query — secrets go in the *Env (env-NAME) fields" });
+        }
+    });
+}
 /** A URL handed to `fetch` that carries no credential: judged by THE URL shape judge ({@link httpUrlFlaws}, `./url-shape`) — a
  *  hierarchical http(s) URL with neither userinfo nor a fragment (an empty `#` included, 11.0.0) — and with no secret-shaped value
  *  in its path or query ({@link urlQueryFragmentHasSecret}). One issue per flaw, its message the judge's rule sentence (no value
- *  echoed); `params.flaw` carries the rule word.
+ *  echoed; a fragment's also names its migration, {@link nonSecretUrlSentence}); `params.flaw` carries the rule word.
+ *
+ *  This is the seat of every URL in a stored DOMAIN document (models `baseUrl`, mcp `url`, `sessionMirror.engineUrl`, workers
+ *  `gitApiBaseUrl`). A URL outside the domain documents — `remote-exec.json`'s endpoints, the web-admin credential envelope's
+ *  `issuer` — uses {@link NON_SECRET_URL_NO_MIGRATION}.
  *
  *  The value is kept EXACTLY as written: nothing here trims or normalizes it (zod's own `.url()` would hand back a rewritten string). */
-export const NON_SECRET_URL = z.string().superRefine((s, ctx) => {
-    const flaws = httpUrlFlaws(s, NON_SECRET_URL_FORBIDS);
-    for (const flaw of flaws)
-        ctx.addIssue({ code: "custom", message: httpUrlRule(flaw), params: { flaw } });
-    if (flaws.length === 0 && urlQueryFragmentHasSecret(new URL(s))) {
-        ctx.addIssue({ code: "custom", message: "must not carry a secret-shaped value in its path or query — secrets go in the *Env (env-NAME) fields" });
-    }
-});
+export const NON_SECRET_URL = createNonSecretUrl(true);
+/** {@link NON_SECRET_URL}'s judge for a seat no one-time migration reaches (not a domain document): identical rules and rule
+ *  sentences, but a fragment's refusal carries no migration signpost — pointing at a migration that cannot rewrite the value would
+ *  send the operator to a command that does nothing for it. */
+export const NON_SECRET_URL_NO_MIGRATION = createNonSecretUrl(false);
 /** Validate a free-form `extraBody`: returns true = UNSAFE (reject). A GETTER-FREE, descriptor-based, bounded
  *  walk that rejects — WITHOUT ever invoking a getter (a malicious getter could throw a secret-bearing message,
  *  or return different values across the validate vs persist JSON.stringify calls) — anything that isn't plain
@@ -1613,13 +1646,22 @@ const WorkerSecretRefs = z.object({
  *  · **删** `MEMORY_BACKEND`(引擎从不读的死名,渲染器不再产出)与 `TIDB_*` 族(引擎的墓碑名,见之拒启;结构字段不再产出它们)。
  *    MYSQL_* / PG_* 两族归 `runtime.store.db` + `secretRefs.dbPasswordEnv`。
  *
- * `env` / `secretEnv` 的写闸问**两张表**,各答一个问题:本表答「这个现名归哪个结构字段」(拒句指路到那个字段);墓碑表 `RETIRED_ENVS`
- * (`./retired-envs`)答「这个旧名已退役」(拒句就是墓碑句 `retiredEnvRefusal` 本身,引擎起服、壳、web-admin 读同一张表同一句)。墓碑名不进本表。
+ * `env` / `secretEnv` 的写闸问**两张表**,各答一个问题,互相独立:
+ *  · 本表答「规格作者可不可以自己设这个名」—— 不可以:它归某个结构字段,或归渲染器 / 编排器写,或与渲染器 / 编排器写的名互斥(拒句指路到那个写位);
+ *  · 墓碑表 `RETIRED_ENVS`(`./retired-envs`)答「带着墓碑表的引擎还读不读这个名」—— 不读、见之拒启(拒句就是墓碑句 `retiredEnvRefusal` 本身,引擎起服、壳、web-admin 读同一张表同一句)。
+ * 两个问题的读者不同,答案可以同时为「是」。换名窗里就是这样:更老的引擎内带更老的契约、看不见墓碑表,仍读上一代名,渲染器因此对它们仍写上一代的 URL / WORKER / TOKEN
+ * (TOKEN_FILE 与 TOKEN 互斥,同组同入)—— 这四名对第一个问题答「不可以自设」(本表),对第二个问题答「不读」(墓碑表),写闸交两句:墓碑句在前、保留句在后,各说各的事。
+ * 这是**窗期**形。窗关 —— 渲染器不再对任何目标引擎写上一代名、此后没有引擎要读它们 —— 这四名离开本表,两表回到零交集,那才是终态;窗期交集是个写死的闭集,
+ * 有钉盯着,窗关时那一钉翻回零交集。
  *
- * 11.0.0:本表与 `RETIRED_ENVS` 的旧名集合零交集 —— `ANTHROPIC_BASEURL`(墓碑名)换成现名 `ANTHROPIC_BASE_URL`;渲染器写的 web-admin 连接三键
- * 入表,同 fleet 成员身份两键的「渲染器写、不可配」。**规则一条:渲染器写的名字是保留名**(运维不可在 `env` / `secretEnv` 里自写)。改名窗里渲染器
- * 按目标引擎版本写名,对还读上一代名的引擎写的是 `SEMA_REGISTRY_URL` / `SEMA_REGISTRY_WORKER` / `SEMA_REGISTRY_TOKEN`,所以这三名与现名三键同一组、
- * 同一句拒(指路同一处)。老三名在引擎换读现名的那一版随之搬去墓碑表(同一提交);保留表与墓碑表零交集的钉会逼这一步。
+ * 11.0.0:`ANTHROPIC_BASEURL`(墓碑名)换成现名 `ANTHROPIC_BASE_URL`;渲染器写的 web-admin 连接三键入表,同 fleet 成员身份两键的「渲染器写、不可配」。
+ * **规则一条:渲染器写的名字是保留名**(运维不可在 `env` / `secretEnv` 里自写)。改名窗里渲染器按目标引擎版本写名,对还读上一代名的引擎写的是
+ * 上一代的 URL / WORKER / TOKEN 三名({@link PREVIOUS_WEB_ADMIN_ENV}),所以这三名与现名三键同一组、保留句同一句(指路同一处)。
+ * 上一代八名都是墓碑(引擎换读现名之后,新引擎见之拒启);其中上面几名因窗期而同时留在本表,另外几名(LIVE_URL / WEB_URL / DRY_RUN / ADMIN_TOKEN)没有谁写、也不与谁互斥,只是墓碑。
+ *
+ * 两把凭证的文件键与断言令牌值键也是保留名(同一条规则):断言令牌(`wat_`)的值键归编排器注入;两个文件键(主凭证 `tokenFile`、断言令牌 `assertionTokenFile`)
+ * 只给不经编排器的手接引擎、由运维直设,不经 worker 规格。文件键与同一份凭证的值键互斥(`judgeWebAdminCredentialDeclaration`:一对里两个都设 ⇒ 拒启),
+ * 规格里写了任一个就与注入撞,拒句点名各自的出路({@link WEB_ADMIN_ASSERTION_SEAT}、{@link WEB_ADMIN_OPERATOR_FILE_SEAT});上一代的 `tokenFile` 与老三名同组同入。
  */
 /** web-admin 连接三键的唯一写位(渲染器;没有 WorkerSpec 字段)—— 现名与上一代名指路同一句。 */
 const WEB_ADMIN_CONNECTION_SEAT = {
@@ -1627,6 +1669,12 @@ const WEB_ADMIN_CONNECTION_SEAT = {
     worker: "(set by the config renderer from the worker's name — not configurable)",
     token: "(set by the config renderer from the worker's pull token — not configurable)",
 };
+/** web-admin 凭证的出路:值键由编排器注入;文件键由运维直设(只给不经编排器的手接引擎),不进 worker 规格。没有 WorkerSpec 字段能写它们。
+ *  两把凭证(主凭证 `token` / `tokenFile`、断言令牌 `assertionToken` / `assertionTokenFile`)同一条规则 —— 文件键与同一份凭证的值键互斥,所以文件键同一句出路。 */
+const WEB_ADMIN_ASSERTION_SEAT = {
+    token: "(injected by the orchestrator from the worker's assertion token — not configurable)",
+};
+const WEB_ADMIN_OPERATOR_FILE_SEAT = "(set directly by the operator on a hand-wired engine that is not managed by the orchestrator — never in a worker spec — not configurable)";
 const RESERVED_ENV_FIELD = Object.freeze({
     PORT: "(fixed at 8090 — not configurable)", MODEL_PROVIDER: "model.provider", MODEL_ID: "model.modelId",
     MODEL_REASONING: "model.reasoning", MODEL_CHEAP_ID: "model.cheapId", MODEL_MAX_TOKENS: "model.maxTokens",
@@ -1650,9 +1698,14 @@ const RESERVED_ENV_FIELD = Object.freeze({
     [FLEET_SCOPE_ENV]: "(set by the config renderer from the worker's scope — not configurable)",
     // ── web-admin 连接三键:渲染器给每台 worker 写 web-admin 根 URL、worker 名与该 worker 的拉取令牌 —— 没有 WorkerSpec 字段能写它们;
     //    现名与渲染器对老引擎写的上一代名同一组(见表头注)
-    [WEB_ADMIN_ENV.url]: WEB_ADMIN_CONNECTION_SEAT.url, SEMA_REGISTRY_URL: WEB_ADMIN_CONNECTION_SEAT.url,
-    [WEB_ADMIN_ENV.worker]: WEB_ADMIN_CONNECTION_SEAT.worker, SEMA_REGISTRY_WORKER: WEB_ADMIN_CONNECTION_SEAT.worker,
-    [WEB_ADMIN_ENV.token]: WEB_ADMIN_CONNECTION_SEAT.token, SEMA_REGISTRY_TOKEN: WEB_ADMIN_CONNECTION_SEAT.token,
+    [WEB_ADMIN_ENV.url]: WEB_ADMIN_CONNECTION_SEAT.url, [PREVIOUS_WEB_ADMIN_ENV.url]: WEB_ADMIN_CONNECTION_SEAT.url,
+    [WEB_ADMIN_ENV.worker]: WEB_ADMIN_CONNECTION_SEAT.worker, [PREVIOUS_WEB_ADMIN_ENV.worker]: WEB_ADMIN_CONNECTION_SEAT.worker,
+    [WEB_ADMIN_ENV.token]: WEB_ADMIN_CONNECTION_SEAT.token, [PREVIOUS_WEB_ADMIN_ENV.token]: WEB_ADMIN_CONNECTION_SEAT.token,
+    // ── web-admin 凭证的文件键与断言令牌值键:文件键由运维直设、与同一份凭证的值键互斥 —— 规格里写任一个都与注入撞(主凭证与断言令牌同一规则)。
+    //    上一代的 TOKEN_FILE 与老三名同组同入(换名窗里还读上一代名的引擎读它)。
+    [WEB_ADMIN_ENV.tokenFile]: WEB_ADMIN_OPERATOR_FILE_SEAT, [PREVIOUS_WEB_ADMIN_ENV.tokenFile]: WEB_ADMIN_OPERATOR_FILE_SEAT,
+    [WEB_ADMIN_ENV.assertionToken]: WEB_ADMIN_ASSERTION_SEAT.token,
+    [WEB_ADMIN_ENV.assertionTokenFile]: WEB_ADMIN_OPERATOR_FILE_SEAT,
     REQUIRE_EXECUTION_LANE: "runtime.execution.lane (the renderer emits REQUIRE_EXECUTION_LANE=true for every declared lane)",
     ...Object.fromEntries([...LANE_ENV_OWNER].map(([name, owner]) => [name, laneEnvSeat(name, owner)])),
 });

package/dist/web-admin-credential.d.ts

@@ -32,7 +32,7 @@ export declare const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND: "user-session";
  *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
  *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
  *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
- *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL}(http(s)、有 host、userinfo 与
+ *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
  *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
  */
 export declare const WebAdminCredentialEnvelope: z.ZodObject<{

package/dist/web-admin-credential.js

@@ -21,7 +21,7 @@
  */
 import { z } from "zod";
 import { looksLikeJwt } from "./api/auth-bridge.js";
-import { NON_SECRET_URL } from "./types.js";
+import { NON_SECRET_URL_NO_MIGRATION } from "./types.js";
 import { WEB_ADMIN_ENV } from "./web-admin-env.js";
 /** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
 export const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND = "user-session";
@@ -50,7 +50,7 @@ const TokenString = z.string().regex(TOKEN_CHARS, "must be a token: printable AS
  *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
  *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
  *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
- *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL}(http(s)、有 host、userinfo 与
+ *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
  *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
  */
 export const WebAdminCredentialEnvelope = z
@@ -59,7 +59,7 @@ export const WebAdminCredentialEnvelope = z
     accessToken: TokenString.refine(looksLikeJwt, "must be a JWT (three dot-separated segments) — a worker pull token never goes into an envelope"),
     refreshToken: TokenString,
     expiresAt: RFC3339_DATE_TIME,
-    issuer: NON_SECRET_URL,
+    issuer: NON_SECRET_URL_NO_MIGRATION,
 })
     .strict();
 /** 信封自己的字段名(schema 的键 —— reason 里只许出现这几个名字,不许出现用户写的键)。 */

package/dist/web-admin-env.d.ts

@@ -17,7 +17,8 @@
  *  · `adminToken` —— 引擎以管理身份写 web-admin 时用的令牌(起服上报执行公钥)。
  *
  * 渲染器给每台 worker 写的三键(`url` / `worker` / `token`)同时是 worker env 的**保留名**(`RESERVED_WORKER_ENV`):运维在 worker 规格的
- * `env` 里写它们,会与渲染器写的值打架。
+ * `env` 里写它们,会与渲染器写的值打架。断言令牌的值键 `assertionToken` 也是保留名(由编排器注入);两把凭证的文件键(`tokenFile` / `assertionTokenFile`)同样是保留名:
+ * 只给不经编排器的手接引擎、由运维直设,与同一份凭证的值键互斥,规格里写任一个都与注入撞。
  */
 export declare const WEB_ADMIN_ENV: {
     readonly url: "SEMA_WEB_ADMIN_URL";

package/dist/web-admin-env.js

@@ -17,7 +17,8 @@
  *  · `adminToken` —— 引擎以管理身份写 web-admin 时用的令牌(起服上报执行公钥)。
  *
  * 渲染器给每台 worker 写的三键(`url` / `worker` / `token`)同时是 worker env 的**保留名**(`RESERVED_WORKER_ENV`):运维在 worker 规格的
- * `env` 里写它们,会与渲染器写的值打架。
+ * `env` 里写它们,会与渲染器写的值打架。断言令牌的值键 `assertionToken` 也是保留名(由编排器注入);两把凭证的文件键(`tokenFile` / `assertionTokenFile`)同样是保留名:
+ * 只给不经编排器的手接引擎、由运维直设,与同一份凭证的值键互斥,规格里写任一个都与注入撞。
  */
 export const WEB_ADMIN_ENV = {
     url: "SEMA_WEB_ADMIN_URL",

package/dist/web-admin-session-url.d.ts

@@ -0,0 +1,17 @@
+/** 一个会话在 web-admin 里的坐标:它在哪台 worker 上、会话 id 是什么。 */
+export interface WebAdminSessionTarget {
+    readonly worker: string;
+    readonly sessionId: string;
+}
+/**
+ * 铸一个会话的绝对网页链接。`webBaseUrl` 必须是干净的绝对 http(s) 基址(无 userinfo / query / fragment;可带路径前缀;尾斜杠折掉);
+ * `worker` 与 `sessionId` 必填,逐位 `encodeURIComponent`(含 `&` `#` `=` `?` 的 id 不会串位)。坏输入一律抛,不铸半截链接;
+ * 含孤立代理项的串(坏 UTF-16)由 `encodeURIComponent` 抛 `URIError`,不静默替换。
+ */
+export declare function webAdminSessionUrl(webBaseUrl: string, target: WebAdminSessionTarget): string;
+/**
+ * {@link webAdminSessionUrl} 的配对解析:从一个链接读回 `worker` / `sessionId`。输入可以是绝对 URL 串、相对串(`/chat?…`)、`URL` 或
+ * `URLSearchParams`(聊天页读当前地址栏的形)。**宽读**:缺的那一位不出现在结果里(空值等于缺席);重复参数取第一个(同 `searchParams.get`);
+ * 路径与别的查询参数不看。串解析不出来(不是 URL)⇒ 抛 `TypeError`,不静默当成「没有参数」。
+ */
+export declare function parseWebAdminSessionUrl(link: string | URL | URLSearchParams): Partial<WebAdminSessionTarget>;