@sema-agent/server 7.131.0 → 7.133.0

package/dist/web-admin-client/apply-effective.js

@@ -64,7 +64,27 @@ export function mutateInPlace(target, source) {
     Object.assign(target, source);
 }
 const appliedGeneration = new WeakMap();
-const envRolesBaseline = new WeakMap();
+const envModelPlane = new WeakMap();
+function envModelPlaneOf(config) {
+    let snap = envModelPlane.get(config);
+    if (snap === undefined) {
+        snap = {
+            models: { ...config.models },
+            model: config.envModel,
+            modelApiKeyEnv: { ...config.modelApiKeyEnv },
+            modelApiKeys: { ...config.modelApiKeys },
+            modelRefusals: { ...config.modelRefusals },
+            droppedCatalogEntries: [...config.droppedCatalogEntries],
+            quotaWeights: { ...config.modelQuotaWeights },
+            roles: { ...config.roles },
+            activeTiers: { ...config.tiers },
+            atMention: config.atMention,
+            infoLine: {},
+        };
+        envModelPlane.set(config, snap);
+    }
+    return snap;
+}
 function stageAtMention(raw, usableNames, logger) {
     const read = readAtMention(raw);
     if (read === undefined) {
@@ -172,7 +192,7 @@ function commitStaged(config, staged) {
         config.droppedCatalogEntries = mp.droppedCatalogEntries;
         mutateInPlace(config.modelQuotaWeights, mp.quotaWeights);
         mutateInPlace(config.models, mp.models);
-        config.model = config.models.default;
+        config.model = mp.model;
         mutateInPlace(config.roles, mp.roles);
         mutateInPlace(config.tiers, mp.activeTiers);
         config.atMention = mp.atMention;
@@ -227,7 +247,38 @@ function modelPlaneGroupReport(group) {
     };
 }
 const ROLE_BINDING_UNAVAILABLE_HINT = "tasks resolving this role fail: alias/tier expansion cannot mint this name; the engine refuses it loud — bind the role to a usable model, or make the entry usable (see the entry's own warn)";
+export const NO_CENTER_EFFECTIVE = deepFreeze({ version: 0, updatedAt: "", models: { models: [], roles: {} }, mcp: { servers: [] } });
+export const isNoCenterEffective = (eff) => eff === NO_CENTER_EFFECTIVE;
+function deepFreeze(v) {
+    if (v !== null && typeof v === "object") {
+        for (const x of Object.values(v))
+            deepFreeze(x);
+        Object.freeze(v);
+    }
+    return v;
+}
+function stageEnvModelPlane(config) {
+    if (servedModelTableLeg(config) === "env")
+        return { stages: {} };
+    const snap = envModelPlane.get(config);
+    if (snap === undefined)
+        throw new Error("applyEffective: the center model plane is in force but no env snapshot was taken — the model plane was written outside applyEffective, so the no-center tier has no baseline to return to");
+    return {
+        stages: {
+            models: {
+                ...snap,
+                modelApiKeyEnv: { ...snap.modelApiKeyEnv },
+                modelApiKeys: { ...snap.modelApiKeys },
+                modelRefusals: { ...snap.modelRefusals },
+                droppedCatalogEntries: [...snap.droppedCatalogEntries],
+                infoLine: { source: "no-center-baseline", default: snap.model.id, roles: Object.keys(snap.roles), tiers: [], atMention: snap.atMention.mode },
+            },
+        },
+    };
+}
 function stageModelPlane(config, eff, logger, sealedKeys) {
+    if (isNoCenterEffective(eff))
+        return stageEnvModelPlane(config);
     const enabled = (eff.models?.models ?? []).filter((m) => m.enabled !== false);
     const verdict = judgeCatalogEntries(enabled, { anthropicRouteMounted: config.anthropic !== undefined }, eff.models?.droppedCatalogEntries);
     if (enabled.length === 0 && verdict.malformed.length === 0 && verdict.dropped.every((row) => row.identity?.enabled === false))
@@ -293,8 +344,7 @@ function stageModelPlane(config, eff, logger, sealedKeys) {
                     quotaWeights[m.id] = qw;
             }
         }
-        if (!envRolesBaseline.has(config))
-            envRolesBaseline.set(config, { ...config.roles });
+        const envPlane = envModelPlaneOf(config);
         const centerRoles = {};
         for (const [role, tgt] of Object.entries(eff.models.roles ?? {})) {
             if ("model" in tgt)
@@ -302,7 +352,7 @@ function stageModelPlane(config, eff, logger, sealedKeys) {
             else if ("select" in tgt)
                 centerRoles[role] = { select: tgt.select };
         }
-        const roles = { ...envRolesBaseline.get(config), ...centerRoles };
+        const roles = { ...envPlane.roles, ...centerRoles };
         const activeTiers = {};
         for (const [tier, target] of Object.entries(resolveActiveTiers(eff.models) ?? {})) {
             if (models[target] !== undefined) {
@@ -365,6 +415,7 @@ function stageModelPlane(config, eff, logger, sealedKeys) {
         const defaultModel = models.default;
         const plane = {
             models,
+            model: defaultModel,
             modelApiKeyEnv,
             modelApiKeys,
             modelRefusals: { ...verdict.refused },

package/dist/web-admin-client/candidate-gate.d.ts

@@ -2,7 +2,7 @@
  * 配置候选的**唯一判官**:一份候选(中心有效视图,或本地 `config.d` 读出的那份)能不能收 —— 只有这一种判法。
  *
  * 判据(三件,任一即拒;每条拒因带成因词,闭集 {@link CandidateRejectReason}):读腿交出的 `domainErrors`(某个域读不懂 / 拼错键 / 坏文件:那个域已落
- * schema 缺省)与 prompts 面的判形(`validatePromptsDomain`;坏形的 pack 会让 core 在每个任务的装配期抛)—— 成因 `domain_invalid`;读腿交出的
+ * schema 缺省)与 prompts 面的判官(`judgePromptsWire`:契约包的 wire 形再交引擎 verify —— 中心层只有一种形)—— 成因 `domain_invalid`;读腿交出的
  * `retiredDomains`(带事实的退役域文档,契约包的墓碑;拒句点名退役版本与一次性迁移)—— 成因 `retired_domain`。任一 ⇒ `rejected`:
  * **整份候选不收**,一个域都不应用。退役域此前在读腿整包抛、走「源不可达」那条臂(版本读不到、没有拒判行、刷新拍算失败);现在读腿只交数据,
  * 坏候选只有本判官一种判法。
@@ -22,11 +22,11 @@
  * `domains` 排序去重:收集器的顺序没有承诺,它是拒行去重键的一部分(同一份候选、同一组坏域只响一次)。`errors` 原样逐条
  * (读腿的诊断在前、prompts 在后)—— 那是可操作的诊断,不是键。纯函数:不改入参,不读环境。
  *
- * **判官交值**:`clean` 判决带着 prompts 面的已判形值(`prompts`;候选不带 prompts 键 ⇒ `undefined`)。采纳 prompts 的各处(起服 / 刷新 /
- * 迟到起服 / LKG 起服 / `run-local`)直接用这一份值,不再自己判第二遍 —— `validatePromptsDomain` 在 src 里只有本判官一个调用点
+ * **判官交值**:`clean` 判决带着 prompts 面的判官结论(`prompts` = 引擎 verify 过的发布形 artifact;候选不带 prompts 键 ⇒ `undefined`)。采纳 prompts 的各处
+ * (起服 / 刷新 / 迟到起服 / LKG 起服 / `run-local`)直接用这一份值,不再自己判第二遍 —— `judgePromptsWire` 在 src 里只有本判官一个调用点
  * (盘上 LKG 的读回复判也经本判官,`config-lkg.ts`)。
  */
-import { type PromptsDomainFaces } from "../prompts-domain-validate.js";
+import type { PublishedPromptArtifact } from "@sema-agent/core";
 import type { EffectiveConfig } from "./types.js";
 /** 读腿交出的一条域级诊断(与 `FetchEffectiveResult.domainErrors` 同形;error 文案已在产出边界脱敏)。 */
 export interface CandidateDomainError {
@@ -46,10 +46,10 @@ export interface ConfigCandidateRead {
     readonly retiredDomains?: readonly CandidateDomainError[];
 }
 export type ConfigCandidateVerdict = 
-/** `prompts` = 候选 prompts 面的已判形值(候选不带 prompts 键 ⇒ `undefined` = 撤回中心包、内置提示词服务)。 */
+/** `prompts` = 候选的中心层(引擎 verify 过的发布形 artifact;候选不带 prompts 键 ⇒ `undefined` = 撤下中心层、内置提示词服务)。 */
 {
     readonly verdict: "clean";
-    readonly prompts: PromptsDomainFaces | undefined;
+    readonly prompts: PublishedPromptArtifact | undefined;
 } | {
     readonly verdict: "rejected";
     readonly domains: readonly string[];

package/dist/web-admin-client/candidate-gate.js

@@ -1,14 +1,14 @@
-import { validatePromptsDomain } from "../prompts-domain-validate.js";
+import { judgePromptsWire } from "../prompts-domain-validate.js";
 export function judgeConfigCandidate(r) {
     const prompts = r.effective.prompts;
-    const promptsGate = prompts === undefined ? undefined : validatePromptsDomain(prompts);
+    const promptsGate = prompts === undefined ? undefined : judgePromptsWire(prompts);
     const errors = [
         ...(r.domainErrors ?? []).map((de) => ({ domain: de.domain, error: de.error, reason: "domain_invalid" })),
         ...(promptsGate !== undefined && !promptsGate.ok ? [{ domain: "prompts", error: promptsGate.error, reason: "domain_invalid" }] : []),
         ...(r.retiredDomains ?? []).map((rd) => ({ domain: rd.domain, error: rd.error, reason: "retired_domain" })),
     ];
     if (errors.length === 0)
-        return { verdict: "clean", prompts: promptsGate?.ok ? promptsGate.value : undefined };
+        return { verdict: "clean", prompts: promptsGate?.ok ? promptsGate.artifact : undefined };
     return { verdict: "rejected", domains: [...new Set(errors.map((e) => e.domain))].sort(), errors };
 }
 export function buildCandidateRejectedFields(r, verdict, leg, ctx) {

package/dist/web-admin-client/facade.d.ts

@@ -48,7 +48,7 @@
  * importers to update, which was done in the same commit.
  */
 export { fetchEffective, fetchPrincipalCaps, fetchPrincipalOrgMemory, WebAdminHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./http-client.js";
-export { mutateInPlace, applyEffective, type ApplyReport, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, type ModelPlaneDomain, type ModelPlaneOf, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
+export { mutateInPlace, applyEffective, NO_CENTER_EFFECTIVE, isNoCenterEffective, type ApplyReport, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, type ModelPlaneDomain, type ModelPlaneOf, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
 export { restartReasons, modelPlaneChanged, type RestartSlice, type RestartSliceCtx, type EngineRestartSignal, } from "./restart-signal.js";
 export { applySkillsManifest, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
 export { applyCenterReadFace, buildReadFaceBaseline, buildReadFaceSwapCandidate, restoreReadFaceBaseline, CENTER_READ_FACE_LIVE_KEYS, type CenterReadFaceApply, type CenterReadFaceReport, type ReadFaceBaseline, type ReadFaceSeat } from "./read-face.js";

package/dist/web-admin-client/facade.js

@@ -1,5 +1,5 @@
 export { fetchEffective, fetchPrincipalCaps, fetchPrincipalOrgMemory, WebAdminHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./http-client.js";
-export { mutateInPlace, applyEffective, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
+export { mutateInPlace, applyEffective, NO_CENTER_EFFECTIVE, isNoCenterEffective, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
 export { restartReasons, modelPlaneChanged, } from "./restart-signal.js";
 export { applySkillsManifest, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
 export { applyCenterReadFace, buildReadFaceBaseline, buildReadFaceSwapCandidate, restoreReadFaceBaseline, CENTER_READ_FACE_LIVE_KEYS } from "./read-face.js";

package/dist/web-admin-client/http-client.js

@@ -1,6 +1,5 @@
 import { createHash } from "node:crypto";
 import { readEffectiveWire, PrincipalCapsWire } from "@sema-agent/settings-schema";
-import { centerPromptsFromEffective } from "../prompts-domain-validate.js";
 import { separateRetiredDomains, splitFoldedReadWarnings, withDroppedCatalogEntries } from "./read-warnings.js";
 import { CENTER_PULL_TIMEOUT_MS, centerFetch } from "./center-request.js";
 import { answerStillCurrent } from "../center-credential.js";
@@ -13,11 +12,6 @@ export async function fetchEffective(center, etag, fetchImpl = fetch, worker) {
     const warnings = [];
     const { body, retiredDomains } = separateRetiredDomains(await res.json());
     const wire = readEffectiveWire(body, (w) => warnings.push(w));
-    const centerPrompts = centerPromptsFromEffective(wire);
-    if (centerPrompts === undefined)
-        delete wire.prompts;
-    else
-        wire.prompts = centerPrompts;
     const { domainErrors, droppedEntries, droppedCatalogEntries, unreadFiles } = splitFoldedReadWarnings(warnings, "center");
     const effective = withDroppedCatalogEntries(wire, droppedCatalogEntries);
     return {

package/dist/web-admin-client/read-face.js

@@ -1,4 +1,5 @@
 import { compileReadDeny, isSwappableDepSeat, resolveReadDenyBuiltins } from "@sema-agent/core";
+import { readReadDenyEntry } from "../read-deny-entry.js";
 export function buildReadFaceBaseline(config) {
     return {
         ...(config.readFace !== undefined ? { readFace: config.readFace } : {}),
@@ -44,15 +45,10 @@ function normalizeDenyPatterns(raw) {
     if (!Array.isArray(raw))
         throw new ReadFaceDomainError("readFace.denyPatterns must be an array of \"pattern\" strings or {pattern, caseSensitive?} objects");
     return raw.map((it, i) => {
-        if (typeof it === "string")
-            return { pattern: it, caseSensitive: false };
-        if (typeof it !== "object" || it === null || typeof it.pattern !== "string") {
-            throw new ReadFaceDomainError(`readFace.denyPatterns[${i}] must be a string or an object with a string 'pattern'`);
-        }
-        const cs = it.caseSensitive;
-        if (cs !== undefined && typeof cs !== "boolean")
-            throw new ReadFaceDomainError(`readFace.denyPatterns[${i}].caseSensitive must be boolean when present`);
-        return { pattern: it.pattern, caseSensitive: cs === true };
+        const read = readReadDenyEntry(it);
+        if (!read.ok)
+            throw new ReadFaceDomainError(`readFace.denyPatterns[${i}]${read.after}`);
+        return read.entry;
     });
 }
 function assertFace(raw) {

package/dist/web-admin-client/read-warnings.d.ts

@@ -70,6 +70,19 @@ export type UnreadConfigFile = {
     readonly why: "not-a-domain" | "non-portable-domain";
     readonly domain?: string;
 };
+/**
+ * `config.d` 里一份**被读**的文件中、本地读腿结构上**不读**的一键(本服务铸,不是契约告警):今天只有 `prompts.json` 的 `workers` —— 本地腿没有
+ * worker 身份,中心层的唯一选择读法(`promptArtifactFor`)对它恒以 `null` 读,只交 `artifact`。写了不生效要响:调用方在采纳路径上一键一行 `config_unread_key`
+ * (与 `config_unread_file` 同频:起服与之后每次采纳一份变了的候选),不判拒。
+ */
+export type UnreadConfigKey = {
+    readonly file: string;
+    readonly domain: string;
+    readonly key: string;
+    readonly names: readonly string[];
+};
+/** `config_unread_key` 一行的体(纯数据;起服 / 刷新 / 迟到起服与 `run-local` 同一体):`dir` = 本地读腿的配置根。 */
+export declare function buildUnreadConfigKeyFields(k: UnreadConfigKey, dir: string | undefined): Record<string, unknown>;
 /** `config_unread_file` 一行的体(纯数据;起服 / 刷新 / 迟到起服与 `run-local` 同一体):`dir` = 本地读腿的配置根。 */
 export declare function buildUnreadConfigFileFields(f: UnreadConfigFile, dir: string | undefined): Record<string, unknown>;
 /** 逐条丢弃面的一行(两条读腿的 `droppedEntries` 同形,`config_entry_dropped` 日志行读它):`entry` = 被丢那条的出门形坐标(`models.1`),

package/dist/web-admin-client/read-warnings.js

@@ -22,6 +22,16 @@ export function separateRetiredDomains(body) {
     }
     return findings.length === 0 ? { body, retiredDomains: [] } : { body: rest, retiredDomains: findings };
 }
+export function buildUnreadConfigKeyFields(k, dir) {
+    return {
+        ...(dir !== undefined ? { dir } : {}),
+        file: k.file,
+        domain: k.domain,
+        key: k.key,
+        names: k.names,
+        note: "the local config read has no worker identity, so this key is never read — prompts.json `workers` entries are not delivered, only `artifact` is; put the artifact this engine should run under `artifact` (or remove the key if it is meant for the center)",
+    };
+}
 export function buildUnreadConfigFileFields(f, dir) {
     return {
         ...(dir !== undefined ? { dir } : {}),

package/dist/web-admin-client/skills-mcp.d.ts

@@ -18,6 +18,9 @@ export type SkillBodySource = Pick<ConfigProvider, "fetchSkillContent" | "skillB
  * hash, deduped in memory (same hash read once). A skill whose body is absent at the source or fails to read (incl. the
  * remote transport's hash check) is NOT installed — exactly one `web_admin_skill_failed` warn names it (`reason`:
  * `body_absent` | `read_failed`), the baseline of that name (if any) stays, and boot is never blocked.
+ * 🔴 **「正文在场」只有一条判据:非空串**({@link skillBodyPresent})。配置源答 `undefined`(没有这个 hash)与答 `""`(空正文)同为缺席 ⇒ `body_absent`:
+ * 一条空正文的技能是**惰性无提示**(名册里有它、模型调用回空、零行日志),不是「装了个什么都不说的技能」。本地腿尤其:settings-schema 把缺省的 `content`
+ * 补成 `""`,本地配置源因此**永远答得出**(空串)—— 没有这一条,`body_absent` 臂只在中心形上可达。本地 / 中心 / 盘缓存三个来源同过这一只判据。
  * Restart-to-apply: this runs at boot, before `buildScenarios` bakes skills into scenarios.
  */
 export declare function applySkillsManifest(baseline: LoadedSkill[], manifest: {

package/dist/web-admin-client/skills-mcp.js

@@ -2,10 +2,12 @@ import { readMcpSourceLabel } from "../mcp-source-label.js";
 import { readMcpToolFaces } from "../mcp-tool-faces.js";
 import { skillContentHash } from "@sema-agent/settings-schema";
 import { readMcpToolAxes } from "@sema-agent/core";
-import { CONTENT_ORIGIN_WORDS, describeBadContentOrigin, isContentOriginWord } from "../mcp-content-origin.js";
-import { noteMcpAssertionHeaderNotSent } from "../mcp-assertion-header.js";
+import { MCP_CONTENT_ORIGINS, describeBadContentOrigin, describeBadWireName, isContentOriginWord, isUsableWireName } from "@sema-agent/settings-schema";
+import { noteMcpAssertionHeaderNotSent, sentMcpAssertionHeaderMember, withholdsMcpAssertionHeader } from "../mcp-assertion-header.js";
 import { SHA256_HEX_RE } from "../digest-form.js";
-import { describeBadWireName, isUsableWireName } from "../wire-name-bound.js";
+function skillBodyPresent(body) {
+    return body !== undefined && body !== "";
+}
 export async function applySkillsManifest(baseline, manifest, bodies, logger) {
     const diskCacheDir = bodies.skillBodyCacheDir;
     const { promises: fsp } = await import("node:fs");
@@ -19,7 +21,7 @@ export async function applySkillsManifest(baseline, manifest, bodies, logger) {
         try {
             const text = await fsp.readFile(joinPath(diskCacheDir, hex), "utf8");
             if (skillContentHash(text) === hash)
-                return text;
+                return skillBodyPresent(text) ? text : undefined;
             logger?.warn("web_admin_skill_cache_corrupt", { hash, note: "on-disk body fails its own hash — ignored, re-reading from the config source" });
         }
         catch {
@@ -53,8 +55,8 @@ export async function applySkillsManifest(baseline, manifest, bodies, logger) {
                 content = await diskRead(m.contentHash);
             if (content === undefined) {
                 const answered = await bodies.fetchSkillContent(m.contentHash);
-                if (answered === undefined) {
-                    logger?.warn("web_admin_skill_failed", { name: m.name, hash: m.contentHash, reason: "body_absent", note: "the config source holds no body for this hash — this entry is NOT installed; the baseline skill of this name (if any) stays" });
+                if (!skillBodyPresent(answered)) {
+                    logger?.warn("web_admin_skill_failed", { name: m.name, hash: m.contentHash, reason: "body_absent", note: "the config source holds no body for this hash (absent, or an empty string) — this entry is NOT installed; the baseline skill of this name (if any) stays" });
                     continue;
                 }
                 content = answered;
@@ -109,7 +111,7 @@ export function resolveMcpServers(mcp, logger) {
                 logger?.warn("web_admin_mcp_content_class_invalid", {
                     server: s.name,
                     value: describeBadContentOrigin(s.contentOrigin),
-                    allowed: CONTENT_ORIGIN_WORDS,
+                    allowed: MCP_CONTENT_ORIGINS,
                     note: "declaration DROPPED — this server's tools keep the pre-378 default (external content, session gets marked). Fix the center entry; the server itself still mounts.",
                 });
         }
@@ -147,11 +149,11 @@ export function resolveMcpServers(mcp, logger) {
             const headers = resolveRefs(s.transport.headerRefs, s.name, "header", logger);
             if (headers === null)
                 continue;
-            if (s.transport.assertionHeader !== undefined)
+            if (withholdsMcpAssertionHeader(s.transport.assertionHeader))
                 noteMcpAssertionHeaderNotSent(logger, s.name);
             out.push({
                 scenarios: s.scenarios ?? [],
-                spec: { name: s.name, transport: { kind: "http", url: s.transport.url, ...(Object.keys(headers).length ? { headers } : {}), ...(s.transport.principalHeader ? { principalHeader: s.transport.principalHeader } : {}) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces, ...toolAxes },
+                spec: { name: s.name, transport: { kind: "http", url: s.transport.url, ...(Object.keys(headers).length ? { headers } : {}), ...(s.transport.principalHeader ? { principalHeader: s.transport.principalHeader } : {}), ...sentMcpAssertionHeaderMember(s.transport.assertionHeader) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces, ...toolAxes },
             });
         }
     }

package/dist/web-admin-client/types.d.ts

@@ -371,9 +371,8 @@ export interface EffectiveConfig {
      *  这条腿对本部署不存在,四键仍由 env / 引擎默认独占。restart-to-apply(boot 期被 `createRunnerDeps`
      *  捕获),改动经 `read-face` restart 片通告。 */
     readFace?: CenterReadFace;
-    /** prompts 域(additive key;双轴 wire=registry-core `EffectivePromptsWire` 或 legacy 平铺形——
-     *  server 侧判形/采用全在 capabilities/center-prompts.ts `validatePromptsDomain`,本 interface 只
-     *  声明键位存在(unknown:候选门是唯一解释者,这里不复刻形)。 */
+    /** prompts 域(中心层;wire 形只有一种 = 契约包 `EffectivePromptsWire` `{ schemaVersion: 2, artifact }`)—— 判法只在候选判官一处
+     *  (`prompts-domain-validate.ts` 的 `judgePromptsWire`,经 `judgeConfigCandidate`),本 interface 只声明键位存在(unknown:判官是唯一解释者,这里不复刻形)。 */
     prompts?: unknown;
 }
 /** (stage7 P5,registry-core 0.8 `execution` 域): the center-resolved per-principal execution

package/dist/workspace-cache.d.ts

@@ -39,6 +39,41 @@ export declare function workspaceCacheClaimOf(spaceKey: string): {
     name: string;
     label: string;
 };
+/**
+ * The directories of the sandbox image the cache volume must never hide — a CLOSED set of path prefixes: a mount that is one of them,
+ * sits under one, or is an ancestor of one (a volume mounted there shadows everything the image keeps at that path) refuses boot.
+ *  - the system roots every image has (`/bin` `/boot` `/dev` `/etc` `/lib` `/lib64` `/proc` `/root` `/run` `/sbin` `/sys` `/usr` `/var`);
+ *  - `/tmp` — the adapter's own scratch (the snapshot archive, the background-job directories);
+ *  - `/opt/sema` — the image's package-source hook the pod start runs;
+ *  - `/home/sandbox` — the sandbox user's home in the images this lane ships.
+ * One reading: the workspace mount is the set's one dynamic member (`K8S_MOUNT_PATH`); config reads both through {@link mountsOverlap}.
+ */
+export declare const WORKSPACE_CACHE_MOUNT_RESERVED: readonly ["/bin", "/boot", "/dev", "/etc", "/home/sandbox", "/lib", "/lib64", "/opt/sema", "/proc", "/root", "/run", "/sbin", "/sys", "/tmp", "/usr", "/var"];
+/** The reserved directory a cache mount collides with (at / under / above it), or `undefined`. `mount` is absolute and normalized. */
+export declare function reservedMountCollision(mount: string): (typeof WORKSPACE_CACHE_MOUNT_RESERVED)[number] | undefined;
+/** The most spaces a {@link CacheMissMemory} holds at once (a process serving more spaces than this forgets the oldest first). */
+export declare const CACHE_MISS_MEMORY_CAP = 1024;
+/** A cache volume that could not be had for a pod and cost a wait: its claim did not bind in time, or it bound and the pod carrying it did not become ready. */
+export interface CacheMissRecord {
+    readonly reason: "claim_unbound" | "claim_unmountable";
+    readonly detail: string;
+}
+/**
+ * The process's memory of cache volumes that could not be had — per space, for a window the caller states: a run that waited out a volume the cluster could not
+ * bind says so here, and the next runs of that space inside the window start without it at once (no claim request, no pod waiting on it) instead of each paying the
+ * whole wait again. A cache is regenerable, so "not asked for a while" costs only builds that re-download. Keyed by the claim's one-way digest (never the space key
+ * itself); bounded ({@link CACHE_MISS_MEMORY_CAP}: expired entries go first, then the oldest). One per deployment, held by the per-run binding — never process-global.
+ */
+export interface CacheMissMemory {
+    /** `spaceKey`'s volume could not be had: remembered for `windowMs` from now. */
+    remember(spaceKey: string, miss: CacheMissRecord, windowMs: number): void;
+    /** Inside the window ⇒ the remembered miss; otherwise `undefined` (and the entry is dropped). */
+    recall(spaceKey: string): CacheMissRecord | undefined;
+    /** Entries held (expired ones that were not read again included). */
+    size(): number;
+}
+/** A fresh {@link CacheMissMemory} (`now` = the clock, epoch ms; a test hands its own). */
+export declare function createCacheMissMemory(now?: () => number): CacheMissMemory;
 /** Does the cache mount overlap the workspace mount (equal, or one inside the other)? Both are absolute, normalized paths. */
 export declare function mountsOverlap(a: string, b: string): boolean;
 export {};

package/dist/workspace-cache.js

@@ -23,6 +23,42 @@ export function workspaceCacheClaimOf(spaceKey) {
     const digest = createHash("sha256").update(spaceKey).digest("hex").slice(0, 20);
     return { name: `ws-cache-${digest}`, label: digest };
 }
+export const WORKSPACE_CACHE_MOUNT_RESERVED = ["/bin", "/boot", "/dev", "/etc", "/home/sandbox", "/lib", "/lib64", "/opt/sema", "/proc", "/root", "/run", "/sbin", "/sys", "/tmp", "/usr", "/var"];
+export function reservedMountCollision(mount) {
+    return WORKSPACE_CACHE_MOUNT_RESERVED.find((dir) => mountsOverlap(mount, dir));
+}
+export const CACHE_MISS_MEMORY_CAP = 1024;
+export function createCacheMissMemory(now = Date.now) {
+    const held = new Map();
+    const keyOf = (spaceKey) => workspaceCacheClaimOf(spaceKey).label;
+    return {
+        remember(spaceKey, miss, windowMs) {
+            const at = now();
+            const key = keyOf(spaceKey);
+            held.delete(key);
+            held.set(key, { miss, until: at + windowMs });
+            if (held.size <= CACHE_MISS_MEMORY_CAP)
+                return;
+            for (const [k, e] of held)
+                if (e.until <= at)
+                    held.delete(k);
+            while (held.size > CACHE_MISS_MEMORY_CAP)
+                held.delete(held.keys().next().value);
+        },
+        recall(spaceKey) {
+            const key = keyOf(spaceKey);
+            const e = held.get(key);
+            if (e === undefined)
+                return undefined;
+            if (e.until <= now()) {
+                held.delete(key);
+                return undefined;
+            }
+            return e.miss;
+        },
+        size: () => held.size,
+    };
+}
 export function mountsOverlap(a, b) {
     const inside = (x, y) => x === y || x.startsWith(y.endsWith("/") ? y : `${y}/`);
     return inside(a, b) || inside(b, a);

package/dist/workspace-space.d.ts

@@ -71,8 +71,9 @@ export declare const WORKSPACE_SNAPSHOT_EXCLUDE_INVALID = "config.workspace_snap
  * space snapshot and the park suspend share it). Unset / empty ⇒ no table (the upload command is what it always was).
  *
  * The item form is CLOSED: plain relative path segments — no leading `/`, no `.` / `..` / empty segment (`./x`, `a//b`, a
- * trailing `/`), no whitespace, no quote characters, no control characters. Tar wildcards inside a segment (`*.log`) are items
- * like any other. A project's `.gitignore` is NOT read (a second grammar, per project, not equivalent to tar's). Items are
+ * trailing `/`), no whitespace, no quote characters, no control characters, and no whole wildcard (an item made only of `*` / `?`
+ * names no path: `*` would exclude every top-level entry and the snapshot would be empty). Tar wildcards inside a segment (`*.log`)
+ * are items like any other. A project's `.gitignore` is NOT read (a second grammar, per project, not equivalent to tar's). Items are
  * trimmed (the CSV separator's spacing is not part of an item); a bad item refuses boot naming its position — the value is a
  * path pattern, never a secret, so it is echoed.
  */

package/dist/workspace-space.js

@@ -30,6 +30,8 @@ function snapshotExcludeItemProblem(item) {
         return "not a plain path (it holds whitespace, a quote or a control character)";
     if (item.startsWith("/"))
         return "absolute (a leading /) — items are relative to the workspace root";
+    if (/^[*?]+$/.test(item))
+        return "a whole wildcard (only `*` / `?` — it names no path and would leave the snapshot without any top-level entry)";
     const segments = item.split("/");
     if (segments.includes(".."))
         return "escaping the workspace (a .. segment)";

package/docs/DEVICE-EXECUTOR-PROTOCOL.md

@@ -20,7 +20,8 @@ dials the device, so the device needs no inbound port, no public address and no
 (this deployment has no device lane) or an object `{ enabled: true, protocolVersion, maxInflightPerDevice,
 wsPath, management }`. Read `wsPath` from there rather than hardcoding it: the path is part of the wire
 contract and reading it means a future path change is not a cross-repo break. `protocolVersion` tells you
-which version the server speaks before you spend a handshake finding out.
+which protocol **revision** the server speaks before you spend a handshake finding out (§2.1: the revision decides
+which `errorCode` words the server accepts from you).
 
 ---
 
@@ -144,6 +145,13 @@ The server sends `challenge` immediately on open. From the moment the socket ope
 the handshake completes, **frames are capped at `maxPreAuthFrameBytes` (4096 bytes)** and a malformed
 pre-auth frame closes the connection outright.
 
+**Which revision to declare.** `challenge.protocolVersion` is the highest protocol revision this server speaks
+(`DEVICE_MIN_PROTOCOL_VERSION` is the lowest it accepts, §2.1). Put the highest revision *you* implement that is
+not above `challenge.protocolVersion` into `hello.protocolVersion` — the same integer you sign (§1.3) — and emit
+only the `errorCode` words of that revision (the revision table in §2.1). Nothing is renegotiated after `hello`:
+the revision you declared is the contract for the whole connection. If the highest revision you implement is below
+`DEVICE_MIN_PROTOCOL_VERSION`, the server answers `helloReject: protocol_version_unsupported` (§1.4).
+
 ### 1.3 The `hello` signature (byte-exact — do not improvise)
 
 Sign with the device private key over exactly these bytes:
@@ -245,18 +253,32 @@ backoff, exponential to a 60 s ceiling, jittered — except for `revoked`, which
 
 `helloAck` carries:
 
+<!-- closed-set: DEVICE_HELLO_ACK_BOUNDS -->
+
 | Field | Form | Meaning |
 |---|---|---|
 | `ok` | always `true` | — |
-| `heartbeatIntervalMs` | integer ms | how often you should send `heartbeat` (deployment default 15000) |
-| `maxInflight` | integer | how many instructions the server will have outstanding on this device at once (deployment default 4) |
+| `heartbeatIntervalMs` | `integer ms ≥ 1` | how often you should send `heartbeat` (deployment default 15000) |
+| `maxInflight` | `integer ≥ 1` | how many instructions the server will have outstanding on this device at once (deployment default 4) |
 | `gen` | **canonical decimal string** (`"7"`, never `7`, never `"07"`) | the connection generation. Stamp it on every frame you send |
 | `pendingInstructions` | `string[]` | instruction ids the server still considers in flight for you — see §5 R2 |
 | `chunkWatermarks` | `{ [instructionId]: number }` | per instruction, the highest **contiguous** `streamSeq` the server has already accepted. `-1` means "nothing accepted yet" |
-| `reconnectGraceMs` | integer ms | the reconnect grace **in force on this server** (R4): how long in-flight work survives a dropped socket. Deployment-tunable, default 120000 |
-| `cancelGraceMs` | integer ms | the cancel grace in force (R11): how long after a `cancel` is delivered the server waits for your terminal `result`. Default 10000 |
-| `chunkGapTimeoutMs` | integer ms | the chunk-gap timeout in force (R8): how long the server waits for a missing `streamSeq` before failing the instruction. Default 30000 |
-| `executionCeilingGraceMs` | integer ms | the grace added to an instruction's `timeoutMs` before the server gives up and settles it as outcome-unknown (R12: the ceiling is `timeoutMs + executionCeilingGraceMs`). Default 30000 |
+| `reconnectGraceMs` | `integer ms ≥ 0` | the reconnect grace **in force on this server** (R4): how long in-flight work survives a dropped socket. Deployment-tunable, default 120000 |
+| `cancelGraceMs` | `integer ms ≥ 0` | the cancel grace in force (R11): how long after a `cancel` is delivered the server waits for your terminal `result`. Default 10000 |
+| `chunkGapTimeoutMs` | `integer ms ≥ 0` | the chunk-gap timeout in force (R8): how long the server waits for a missing `streamSeq` before failing the instruction. Default 30000 |
+| `executionCeilingGraceMs` | `integer ms ≥ 0` | the grace added to an instruction's `timeoutMs` before the server gives up and settles it as outcome-unknown (R12: the ceiling is `timeoutMs + executionCeilingGraceMs`). Default 30000 |
+
+**Bounds.** The six numeric fields above are validated by the server when it starts: a deployment whose knob (or
+embedding option) is outside its row's range refuses to boot — the value is never clamped and never replaced by a
+default — so a `helloAck` on the wire is always in range, and every number in it is the value the server's own
+timers and slot counts are armed with. Every `ms` field is also at most `2147483647` (the largest delay a
+timer can hold; a larger value would be silently collapsed to 1 ms); `maxInflight` has no ceiling beyond an
+integer JSON represents exactly (at most `9007199254740991`). A `0` grace means "no grace": that timer
+fires at once. An executor that reads a value outside its row's range must treat it as a protocol violation — the executor-side twin
+of the server's `bad_shape` refusal (§2.4): close the connection and reconnect with backoff — and must **not** read the
+out-of-range value as the default.
+`deviceHelloAckNumberFlaw` (from `@sema-agent/server/device-protocol`) is the same check the server applies.
+The *absence* of one of the four grace fields is a different case, described below, and still means "not told".
 
 The four grace fields are the values the server's own timers are armed with — not documentation defaults. Size
 your reconnect backoff ceiling, your `cancel` answer deadline, your retransmission cadence and your own
@@ -314,8 +336,8 @@ base64 inside JSON fields.
 | Constant | Value | Meaning |
 |---|---|---|
 | `DEVICE_WS_PATH` | `/v1/device/ws` | the upgrade path (prefer the `wsPath` from `/v1/capabilities`) |
-| `DEVICE_PROTOCOL_VERSION` | `1` | the version this server speaks |
-| `DEVICE_MIN_PROTOCOL_VERSION` | `1` | the lowest version it accepts; below it, a loud `helloReject` — never a silent downgrade |
+| `DEVICE_PROTOCOL_VERSION` | `2` | the protocol revision this server speaks (the highest it accepts) |
+| `DEVICE_MIN_PROTOCOL_VERSION` | `1` | the lowest revision it accepts; below it (or above the highest), a loud `helloReject` — never a silent downgrade |
 | `DEVICE_HELLO_DOMAIN_TAG` | `sema.device.hello.v1` | the handshake signature domain tag (§1.3) |
 
 <!-- closed-set: DEVICE_WS_LIMITS -->
@@ -330,6 +352,29 @@ base64 inside JSON fields.
 Note the asymmetry: the transport cap is 1 MiB, and the 4096-byte pre-auth cap is applied **after** the
 frame has been reassembled. Keep `hello` small; it is not a place for long `supports` prose.
 
+#### Protocol revisions and the `errorCode` set
+
+The protocol revision is the only thing an executor can read *before* it sends `hello` (the `challenge` frame
+carries it), so the set of `errorCode` words the server accepts from you is a function of the revision, not a
+separate list. The table gives, per revision, the words **added** at that revision; the set at revision *N* is
+the union of the rows up to *N*, and the full set at the current revision is the §3.3 table.
+
+<!-- closed-set: DEVICE_OUTCOME_ERROR_CODES_BY_REVISION -->
+
+| Revision | `errorCode` words added at this revision |
+|---|---|
+| `1` | `aborted`, `already_exists`, `auth_failed`, `callback_error`, `invalid`, `is_directory`, `not_directory`, `not_found`, `not_supported`, `outcome_unknown`, `permission_denied`, `precondition_failed`, `shell_unavailable`, `spawn_error`, `suspended`, `target_unavailable`, `timeout`, `transport_lost`, `unknown` |
+| `2` | `liveness_no_output` |
+
+Rules: adding a frame or a field is additive and does not raise the revision; adding a word to a closed set the
+server *accepts from you* (today: the `errorCode` set) raises `DEVICE_PROTOCOL_VERSION` and adds a row here; a
+released row never changes. Declare a revision as §1.2 says and send only the words of that revision: an executor
+that declared revision 1 never sends `liveness_no_output` (the server does not police this per connection — it
+decodes every connection against the current revision's full set — but a word above your declared revision is outside
+your contract). The same sets are importable:
+`DEVICE_OUTCOME_ERROR_CODES_BY_REVISION` and `deviceOutcomeErrorCodesAt(revision)` from
+`@sema-agent/server/device-protocol`.
+
 ### 2.2 Device → server frames
 
 <!-- closed-set: DEVICE_FRAME_TYPES -->
@@ -515,6 +560,9 @@ a moment ago. If you omit `created`, the consumer reports the weaker of the two
 
 `message` is required on the failure arm and is shown to the model — make it specific.
 
+This is the full set at the current revision (`2`); the revision table in §2.1 says which revision each word arrived
+with, and an executor sends only the words of the revision it declared (§1.2).
+
 <!-- closed-set: DEVICE_OUTCOME_ERROR_CODES -->
 
 | `errorCode` | Use it when |
@@ -525,6 +573,7 @@ a moment ago. If you omit `created`, the consumer reports the weaker of the two
 | `callback_error` | a callback/hook on the device side failed (exec family) |
 | `invalid` | the arguments do not make sense for this target (e.g. `readLink` on a non-symlink) |
 | `is_directory` | a file operation hit a directory |
+| `liveness_no_output` | **you** killed the command because it produced no output for your own silence window (a hung command); the wall-clock budget `timeoutMs` running out stays `timeout`. The frame has no field for the window length — do not invent one |
 | `not_directory` | a directory operation hit a non-directory |
 | `not_found` | the path does not exist |
 | `not_supported` | you do not implement this face (prefer simply not declaring it) |
@@ -539,10 +588,16 @@ a moment ago. If you omit `created`, the consumer reports the weaker of the two
 | `transport_lost` | a transport the device itself depends on went away |
 | `unknown` | none of the above |
 
-Two codes carry load-bearing semantics upstream and must not be used loosely:
+Three codes carry load-bearing semantics upstream and must not be used loosely:
 
 - `timeout` is treated as **retryable**. Use it only when you actually killed the work and know it is
   dead. If you are not sure the command is dead, use `outcome_unknown`.
+- `liveness_no_output` is the same kind of word — the command ran, you killed it, **retryable** — with a
+  different cause: it names the silence, `timeout` names the wall-clock budget. They are two different
+  numbers and the model is told a different sentence for each, so report the bound that actually fired.
+  The same rule applies: use it only when you actually killed the work and know it is dead; if you are
+  not sure, use `outcome_unknown`. On a file instruction it is a protocol violation (a file operation has
+  no silence window) and the server reads it as `unknown`.
 - `outcome_unknown` is never auto-retried, anywhere. It is the honest answer for "the command may have
   already run and I cannot confirm". Choosing `timeout`/`transport_lost` instead invites a second
   execution of a command that already had side effects.