@sema-agent/server 7.121.0 → 7.123.0

package/dist/config.js

@@ -13,7 +13,7 @@ import { GIT_API_KINDS, isGitApiKind } from "./git-api-kind.js";
 import { CONFIG_PROVIDER_WORDS, RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC, RESILIENCE_DEFAULTS, TASK_WRITE_FACE_ESCALATIONS, MAX_TIMER_DELAY_MS, AUTO_MODE_CLASSIFIER_TIMEOUT_BOUNDS, DRAIN_GRACE_FLOOR_MS, DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS, DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS, FIRST_BYTE_TIMEOUT_BOUNDS, FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS, fleetScopeOf } from "./config-types.js";
 import { FLEET_GENERATION_ENV, FLEET_SCOPE_ENV, SERVING_LEASE_TTL_FLOOR_MS, isCanonicalGeneration } from "@sema-agent/settings-schema/fleet";
 import { ScopeId } from "@sema-agent/settings-schema/api/scopes";
-import { centerLaneConfigured, pathBaseUrlFlaw } from "./config-center/center-request.js";
+import { centerLaneConfigured, pathBaseUrlRefusal } from "./config-center/center-request.js";
 import { resolveLocalDataRoot } from "./local-data-root.js";
 import { buildWriteProtectionPosture } from "./write-protection.js";
 import { normalizeSshFingerprint } from "./ssh-host-key.js";
@@ -28,22 +28,20 @@ import { lkgPathOverrideOf } from "./config-lkg.js";
 import { REMOTE_EXEC_PROVIDER_WORDS, executionLaneOf, executionLaneRequiredRefusal, isSingleMachineDefaultLane, laneRequiredEnv } from "./execution-lane-caps.js";
 import { MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS } from "@sema-agent/settings-schema/execution-lanes";
 import { AUTONOMY_MODES } from "./runtime-governance.js";
-import { allowLayerEntryCountIssue, describeEmptyToolSegmentEntry, describeInertRuleEntries, emptyToolSegmentEntryOf, inertRuleEntriesOf, ruleEntryListShapeOk } from "./rule-entry-list.js";
+import { allowLayerEntryCountIssue, describeInertRuleEntries, inertRuleEntriesOf, ruleEntryListShapeOk } from "./rule-entry-list.js";
 import { createCenterCredentialSource, readCenterCredentialDeclaration } from "./center-credential.js";
 import { parseCenterCredentialRenewLeadMs } from "./center-credential-renewer.js";
 import { modelProviderRefusal } from "./model-provider.js";
 import { modelRouteUrlRefusal } from "./model-route-url.js";
-import { modelRouteEndpointRefusal } from "./model-route-endpoint.js";
+import { buildHttpUrlRefusal, httpUrlFlaws } from "./url-shape.js";
+import { csvOf, envLaneTable, judgeModelRouteGap, mintedCheapId, readModelRouteEnv } from "./model-route-gap.js";
 import { displayListEntry } from "./list-entry-display.js";
 import { buildDisplaySafeUrl, redactSecrets } from "./trace/redact.js";
 import { allowlistedEnv } from "./server-secret-env.js";
 import { ENV_NAME_ALLOWLIST_KNOBS, ENV_NAME_ALLOWLIST_KNOB_NAMES, describeAllowlistPostures } from "./env-name-allowlist-knobs.js";
 export { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 function csv(name) {
-    return (process.env[name] ?? "")
-        .split(",")
-        .map((s) => s.trim())
-        .filter(Boolean);
+    return csvOf(process.env[name]);
 }
 export function parseAutonomy(raw) {
     const v = raw?.trim();
@@ -311,14 +309,6 @@ export function logConfigDiagnostics(logger) {
         }
     }
 }
-function firstSetEnv(...names) {
-    for (const n of names) {
-        const v = process.env[n];
-        if (v !== undefined && v !== "")
-            return v;
-    }
-    return undefined;
-}
 function clampEnvWithWarn(name, fallback, min, max = Number.POSITIVE_INFINITY) {
     const n = numEnv(name, fallback);
     const used = Math.min(max, Math.max(min, n));
@@ -951,44 +941,37 @@ export function isRosterGateArmed(configCenter) {
     return configCenter !== undefined && !configCenter.dryRun && process.env.CONFIG_REQUIRE_ROSTER === "true";
 }
 function parseModelDomain() {
-    const gatewayBaseUrl = firstSetEnv("MODEL_GATEWAY_BASEURL");
-    const modelId = env("MODEL_ID", "");
-    const explicitProvider = process.env.MODEL_PROVIDER;
-    if (explicitProvider !== undefined && explicitProvider !== "") {
-        const refusal = modelProviderRefusal(explicitProvider);
+    const route = readModelRouteEnv(process.env);
+    const gatewayBaseUrl = route.gatewayBaseUrl;
+    const modelId = route.mainId;
+    if (route.providerSource === "explicit") {
+        const refusal = modelProviderRefusal(route.provider);
         if (refusal !== undefined) {
             throw new Error(refusal);
         }
     }
     for (const [envKey, raw, knob] of [
         ["MODEL_GATEWAY_BASEURL", gatewayBaseUrl ?? "", "MODEL_API_KEY"],
-        ...csv("MODEL_GATEWAY_FALLBACK_URLS").map((u, i) => [`MODEL_GATEWAY_FALLBACK_URLS[${i}]`, u, "MODEL_API_KEY"]),
-        ["ANTHROPIC_BASE_URL", firstSetEnv("ANTHROPIC_BASE_URL") ?? "", "ANTHROPIC_API_KEY"],
+        ...route.gatewayFallbackUrls.map((u, i) => [`MODEL_GATEWAY_FALLBACK_URLS[${i}]`, u, "MODEL_API_KEY"]),
+        ["ANTHROPIC_BASE_URL", route.anthropicBaseUrl ?? "", "ANTHROPIC_API_KEY"],
     ]) {
         const refusal = modelRouteUrlRefusal(envKey, raw, knob);
         if (refusal !== undefined) {
             throw new Error(refusal);
         }
     }
-    const inferredAnthropicBaseUrl = firstSetEnv("ANTHROPIC_BASE_URL");
-    const inferredAnthropicCred = firstSetEnv("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN");
-    const provider = (() => {
-        if (explicitProvider !== undefined && explicitProvider !== "")
-            return explicitProvider;
-        if (inferredAnthropicBaseUrl && inferredAnthropicCred) {
-            CONFIG_NOTICES.push({
-                level: "warn",
-                event: "model_provider_inferred",
-                fields: {
-                    provider: "anthropic",
-                    baseUrl: buildDisplaySafeUrl(inferredAnthropicBaseUrl),
-                    hint: "MODEL_PROVIDER is unset but an explicit ANTHROPIC base URL + credential are configured — inferred provider=anthropic (set MODEL_PROVIDER explicitly to override)",
-                },
-            });
-            return "anthropic";
-        }
-        return "gateway";
-    })();
+    const provider = route.provider;
+    if (route.providerSource === "inferred") {
+        CONFIG_NOTICES.push({
+            level: "warn",
+            event: "model_provider_inferred",
+            fields: {
+                provider: "anthropic",
+                baseUrl: buildDisplaySafeUrl(route.anthropicBaseUrl),
+                hint: "MODEL_PROVIDER is unset but an explicit ANTHROPIC base URL + credential are configured — inferred provider=anthropic (set MODEL_PROVIDER explicitly to override)",
+            },
+        });
+    }
     const extraBody = buildExtraBody();
     const thinkingDefault = parseDefaultThinking(process.env.MODEL_DEFAULT_THINKING);
     const envCompatDeclared = buildModelCompat({
@@ -1020,35 +1003,40 @@ function parseModelDomain() {
         ...(envCompat ? { compat: envCompat } : {}),
         ...(extraBody ? { extraBody } : {}),
     };
-    const cheapId = process.env.MODEL_CHEAP_ID;
-    if (cheapId && modelId === "") {
-        CONFIG_NOTICES.push({
-            level: "warn",
-            event: "model_cheap_slot_without_main",
-            fields: { hint: "MODEL_CHEAP_ID is set but MODEL_ID is not — the env cheap slot derives from the env main model, so it is not minted; the catalog (config.d/models.json or the config center) serves the roles. Set MODEL_ID to use the env slots, or unset MODEL_CHEAP_ID to silence this line." },
-        });
-    }
-    const cheapIsMain = cheapId !== undefined && cheapId !== "" && modelId !== "" && cheapId === modelId;
-    if (cheapIsMain) {
-        CONFIG_NOTICES.push({
-            level: "warn",
-            event: "config_env_entry_cheap_same_as_main",
-            fields: {
-                env: "MODEL_CHEAP_ID",
-                model: modelId,
-                hint: `MODEL_CHEAP_ID names the same model as MODEL_ID ("${modelId}") — the env cheap slot is the main gateway under a different id, ` +
-                    `so the same id IS the main model: no cheap slot is minted and subagent / summarize stay on the main model (roles -> default); ` +
-                    `any other MODEL_CHEAP_* key set here describes that slot and is not applied. Set MODEL_CHEAP_ID to a different (cheaper) model ` +
-                    `id to run those roles cheap, or declare two differently-named entries in config.d/models.json to give one upstream id a second ` +
-                    `shape (price / reasoning / window); unset MODEL_CHEAP_ID to silence this line.`,
-            },
-        });
+    const cheapSlot = route.cheapSlot;
+    switch (cheapSlot.kind) {
+        case "without_main":
+            CONFIG_NOTICES.push({
+                level: "warn",
+                event: "model_cheap_slot_without_main",
+                fields: { hint: "MODEL_CHEAP_ID is set but MODEL_ID is not — the env cheap slot derives from the env main model, so it is not minted; the catalog (config.d/models.json or the config center) serves the roles. Set MODEL_ID to use the env slots, or unset MODEL_CHEAP_ID to silence this line." },
+            });
+            break;
+        case "same_as_main":
+            CONFIG_NOTICES.push({
+                level: "warn",
+                event: "config_env_entry_cheap_same_as_main",
+                fields: {
+                    env: "MODEL_CHEAP_ID",
+                    model: modelId,
+                    hint: `MODEL_CHEAP_ID names the same model as MODEL_ID ("${modelId}") — the env cheap slot is the main gateway under a different id, ` +
+                        `so the same id IS the main model: no cheap slot is minted and subagent / summarize stay on the main model (roles -> default); ` +
+                        `any other MODEL_CHEAP_* key set here describes that slot and is not applied. Set MODEL_CHEAP_ID to a different (cheaper) model ` +
+                        `id to run those roles cheap, or declare two differently-named entries in config.d/models.json to give one upstream id a second ` +
+                        `shape (price / reasoning / window); unset MODEL_CHEAP_ID to silence this line.`,
+                },
+            });
+            break;
+        case "absent":
+        case "minted":
+            break;
     }
-    const cheapModel = cheapId && modelId !== "" && !cheapIsMain
+    const cheapMintedId = mintedCheapId(cheapSlot);
+    const cheapModel = cheapMintedId !== undefined
         ? {
             ...model,
-            id: cheapId,
-            name: cheapId,
+            id: cheapMintedId,
+            name: cheapMintedId,
             input: ((v) => (v === undefined ? model.input : v ? ["text", "image"] : ["text"]))(parseBoolWord("MODEL_CHEAP_VISION", process.env.MODEL_CHEAP_VISION)),
             ...buildModelCostKey(buildCostOrAbsent({
                 input: costEnv("MODEL_CHEAP_COST_INPUT", "declares-zero"),
@@ -1092,9 +1080,7 @@ function parseModelDomain() {
         }
         noticeAutoCompactAboveWindow("cheap", "MODEL_CHEAP_AUTO_COMPACT_TOKENS", cheapModel);
     }
-    const models = modelId === "" ? {} : { default: model, [model.id]: model };
-    if (cheapModel)
-        models[cheapModel.id] = cheapModel;
+    const models = envLaneTable(modelId, model, cheapModel);
     const gatewayApiKey = process.env.MODEL_API_KEY;
     if (gatewayBaseUrl === undefined && gatewayApiKey !== undefined && gatewayApiKey !== "") {
         CONFIG_NOTICES.push({
@@ -1128,13 +1114,13 @@ function parseModelDomain() {
     const degradeOn = parseDegradeOn(csv("MODEL_DEGRADE_ON"));
     return {
         ...(gatewayBaseUrl !== undefined ? { gatewayBaseUrl, gatewayApiKey } : {}),
-        gatewayFallbackUrls: csv("MODEL_GATEWAY_FALLBACK_URLS"),
+        gatewayFallbackUrls: route.gatewayFallbackUrls,
         ...(process.env.GATEWAY_MAX_RETRIES ? { gatewayMaxRetries: numEnvBounded("GATEWAY_MAX_RETRIES", "2", 0, 20) } : {}),
-        anthropic: firstSetEnv("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN")
+        anthropic: route.anthropicRouteMounted
             ? {
-                apiKey: firstSetEnv("ANTHROPIC_API_KEY"),
-                authToken: firstSetEnv("ANTHROPIC_AUTH_TOKEN"),
-                baseUrl: firstSetEnv("ANTHROPIC_BASE_URL"),
+                apiKey: route.anthropicApiKey,
+                authToken: route.anthropicAuthToken,
+                baseUrl: route.anthropicBaseUrl,
                 version: process.env.ANTHROPIC_VERSION,
                 cacheBreakpoints: boolEnv("ANTHROPIC_CACHE_BREAKPOINTS", true),
                 ...(process.env.ANTHROPIC_MAX_RETRIES ? { maxRetries: numEnv("ANTHROPIC_MAX_RETRIES", "2") } : {}),
@@ -1154,6 +1140,7 @@ function parseModelDomain() {
         modelApiKeyEnv: {},
         modelApiKeys: {},
         modelRefusals: {},
+        droppedCatalogEntries: [],
         modelQuotaWeights: {},
         tiers: {},
         projects: {},
@@ -1227,9 +1214,7 @@ function uncompilableRuleGuidance(name, behavior, pathBases) {
     const issue = issues[0];
     if (issue === undefined)
         return undefined;
-    return (`${issue.code} — core's rule grammar cannot compile this name (${issue.message}), so a table keyed by it matches nothing. ` +
-        `Tool names carry no backslashes and are far shorter than the 512-character rule cap; check the spelling, and use ` +
-        `mcp__<server>__* / a2a__<peer>__* for "every tool on that peer"`);
+    return `${issue.code} — core's rule grammar cannot compile this entry: ${issue.message}`;
 }
 function findUnmatchableToolNames(names, opts) {
     const out = [];
@@ -1273,9 +1258,6 @@ export function approvalGrantRefusal(names) {
     const over = allowLayerEntryCountIssue(APPROVAL_GRANT_ENV, names);
     if (over !== undefined)
         return `${over.message} — refusing to start rather than running with a truncated list`;
-    const empty = emptyToolSegmentEntryOf(names);
-    if (empty !== undefined)
-        return `${describeEmptyToolSegmentEntry(APPROVAL_GRANT_ENV, empty)} — refusing to start rather than running without it`;
     const inert = inertRuleEntriesOf(names, "allow");
     if (inert.length > 0)
         return `${describeInertRuleEntries(APPROVAL_GRANT_ENV, inert)} — the engine would grant nothing for ${inert.length === 1 ? "it" : "them"}; refusing to start rather than running with an allow rule that never takes effect`;
@@ -1376,7 +1358,7 @@ function parseApprovalDomain(ctx) {
             const trimmed = raw.trim();
             if (trimmed === "" || trimmed.toLowerCase() === "off")
                 return [];
-            return trimmed.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+            return csvOf(trimmed);
         })(process.env.SENSITIVE_WRITE_PATTERNS),
         ...((decision) => (decision === undefined ? {} : { writeProtectedPaths: decision }))(parseWriteProtectedTableEnv(process.env.WRITE_PROTECTED_EXTRA, process.env.WRITE_PROTECTED_TABLE_REPLACE)),
         ...((raw) => {
@@ -1564,16 +1546,11 @@ function parseMemoryEmbedder(ctx) {
     if (endpoint === undefined || model === undefined || dimRaw === undefined) {
         throw new Error(`MEMORY_EMBEDDER_* is half-configured — missing ${missing.join(", ")}. The memory vector plane needs all three of MEMORY_EMBEDDER_ENDPOINT, MEMORY_EMBEDDER_MODEL, MEMORY_EMBEDDER_DIM; refusing to start rather than silently running lexical-only retrieval while the deployment believes vectors are on (#228).`);
     }
-    if (!URL.canParse(endpoint)) {
-        throw new Error(`MEMORY_EMBEDDER_ENDPOINT="${buildDisplaySafeUrl(endpoint)}" is not a valid URL (expected e.g. https://embeddings.example.com/v1 — the OpenAI-compatible base, or the full .../embeddings endpoint)`);
-    }
-    const parsedEndpoint = new URL(endpoint);
-    const proto = parsedEndpoint.protocol;
-    if (proto !== "http:" && proto !== "https:") {
-        throw new Error(`MEMORY_EMBEDDER_ENDPOINT="${buildDisplaySafeUrl(endpoint)}" must be http(s) (got "${proto}") — the embedder leg is an HTTP POST to an OpenAI-compatible /embeddings face`);
-    }
-    if (parsedEndpoint.username !== "" || parsedEndpoint.password !== "") {
-        throw new Error("MEMORY_EMBEDDER_ENDPOINT must not carry credentials in the URL (user:password@host) — URL userinfo leaks into transport errors, logs and memory conflict reports. Use MEMORY_EMBEDDER_API_KEY (sent as a Bearer header) instead.");
+    const endpointFlaws = httpUrlFlaws(endpoint, ["userinfo"]);
+    if (endpointFlaws.length > 0) {
+        throw new Error(`${buildHttpUrlRefusal("MEMORY_EMBEDDER_ENDPOINT", endpoint, endpointFlaws)} — the embedder leg is an HTTP POST to an OpenAI-compatible /embeddings face ` +
+            `(expected e.g. https://embeddings.example.com/v1 — the OpenAI-compatible base, or the full .../embeddings endpoint); ` +
+            `credentials in the URL leak into transport errors, logs and memory conflict reports, so use MEMORY_EMBEDDER_API_KEY (sent as a Bearer header) instead.`);
     }
     const dimensions = Number(dimRaw);
     if (!Number.isSafeInteger(dimensions) || dimensions < 1) {
@@ -1832,7 +1809,7 @@ function parseAuthDomain(ctx) {
         authToken: process.env.SERVICE_AUTH_TOKEN,
         authTokens,
         allowUnauthedWrites: boolEnv("ALLOW_UNAUTHED_WRITES", false),
-        corsOrigins: (process.env.CORS_ORIGIN ?? "").split(",").map((s) => s.trim()).filter(Boolean),
+        corsOrigins: csv("CORS_ORIGIN"),
         principalHeader: headerNameEnv("PRINCIPAL_HEADER", "x-agent-principal"),
         requirePrincipal,
         autonomy: parseAutonomy(process.env.AUTONOMY),
@@ -2017,7 +1994,7 @@ function parseOrchestrationDomain(ctx) {
             ? {
                 repoRoot: process.env.WORKTREE_REPO_ROOT,
                 ...(process.env.WORKTREE_ALLOWED_ROOTS
-                    ? { allowedRoots: process.env.WORKTREE_ALLOWED_ROOTS.split(",").map((s) => s.trim()).filter(Boolean) }
+                    ? { allowedRoots: csv("WORKTREE_ALLOWED_ROOTS") }
                     : {}),
                 ...(process.env.WORKTREE_BASE_COMMIT ? { commit: process.env.WORKTREE_BASE_COMMIT } : {}),
             }
@@ -2101,7 +2078,7 @@ function parseLimitsHttpDomain() {
         workspaceFileMaxBytes: optFinitePositiveEnv("WORKSPACE_FILE_MAX_BYTES") ?? 8 * 1024 * 1024,
         attachmentMaxBytes: clampEnvWithWarn("ATTACHMENT_MAX_BYTES", String(32 * 1024 * 1024), LIMITS_HTTP_FLOORS.attachmentMaxBytes),
         ...(process.env.ATTACHMENT_MIME_ALLOWLIST
-            ? { attachmentMimeAllowlist: process.env.ATTACHMENT_MIME_ALLOWLIST.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean) }
+            ? { attachmentMimeAllowlist: csv("ATTACHMENT_MIME_ALLOWLIST").map((s) => s.toLowerCase()) }
             : {}),
         attachmentUnboundTtlMs: clampEnvWithWarn("ATTACHMENT_UNBOUND_TTL_MS", String(24 * 3600 * 1000), LIMITS_HTTP_FLOORS.attachmentUnboundTtlMs),
         infraCostRates: {
@@ -2196,7 +2173,7 @@ function parseIntegrationsDomain(ctx) {
     const fleetAdvertiseAddress = parseFleetAdvertiseAddress(process.env.FLEET_ADVERTISE_ADDRESS);
     fleetFenceLaneOf({ ...fleetGeneration, configCenter, ...fleetAdvertiseAddress });
     return {
-        pluginsAllowHosts: (process.env.PLUGINS_ALLOW_HOSTS ?? "github.com").split(",").map((h) => h.trim()).filter(Boolean),
+        pluginsAllowHosts: csvOf(process.env.PLUGINS_ALLOW_HOSTS ?? "github.com"),
         configBootFetchBudgetMs: clampEnvWithWarn("CONFIG_BOOT_FETCH_BUDGET_MS", "1500", 0),
         gitApiBaseUrl: process.env.GIT_API_BASEURL,
         gitApiToken: process.env.GIT_API_TOKEN,
@@ -2249,10 +2226,10 @@ function parseFleetScope(raw) {
 function parseFleetAdvertiseAddress(raw) {
     if (raw === undefined || raw === "")
         return {};
-    const why = pathBaseUrlFlaw(raw);
-    if (why !== undefined) {
-        throw fleetEnvRefusal("advertise_address_invalid", `env FLEET_ADVERTISE_ADDRESS ${why} (an http(s) base URL, e.g. "http://10.0.0.5:8090"); got ${JSON.stringify(buildDisplaySafeUrl(raw))} — ` +
-            `the fleet center rejects any other shape on every announce. Unset it if this engine does not announce itself.`);
+    const refusal = pathBaseUrlRefusal("env FLEET_ADVERTISE_ADDRESS", raw);
+    if (refusal !== undefined) {
+        throw fleetEnvRefusal("advertise_address_invalid", `${refusal} — it must be an http(s) base URL such as "http://10.0.0.5:8090": the fleet center rejects any other shape on every announce. ` +
+            `Unset it if this engine does not announce itself.`);
     }
     return { fleetAdvertiseAddress: raw };
 }
@@ -2280,7 +2257,8 @@ function parseFleetLeaseOutageMaxMs(raw) {
         const shown = raw.length > 40 ? `${raw.slice(0, 40)}…(${raw.length} chars)` : raw;
         throw new Error(`env FLEET_LEASE_OUTAGE_MAX_MS=${JSON.stringify(shown)} must be a whole number of milliseconds ≥ ${SERVING_LEASE_TTL_FLOOR_MS} (the serving-lease TTL floor; ` +
             `decimal digits only; unset = ${FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS}, 24 h). It bounds how long this engine keeps taking new submissions after its serving ` +
-            `lease expired with the center unreachable — "0" and "infinite" are not values (the tolerance must be bounded and non-trivial). Refusing to boot.`);
+            `lease expired with the center unreachable, and how far from now a drain request's deadlineAt may be — "0" and "infinite" are not values ` +
+            `(the bound must be finite and non-trivial). Refusing to boot.`);
     }
     return n;
 }
@@ -2293,9 +2271,9 @@ function parseFleetLeaseFailClosed(raw, requirePrincipal) {
 function parseCenterBaseUrl(name, raw, role) {
     if (raw === undefined || raw === "")
         return undefined;
-    const why = pathBaseUrlFlaw(raw);
-    if (why !== undefined)
-        throw new Error(`env ${name} ${why}; got ${JSON.stringify(buildDisplaySafeUrl(raw))}. ${role}`);
+    const refusal = pathBaseUrlRefusal(`env ${name}`, raw);
+    if (refusal !== undefined)
+        throw new Error(`${refusal}. ${role}`);
     return raw;
 }
 function parseConfigCenter(baseUrl, requirePrincipal, liveBaseUrl, webBaseUrl) {
@@ -2322,20 +2300,13 @@ function parseA2aServe() {
             `and that address is the operator's to declare (it is NOT derived from the request Host header: an anonymous discovery caller must not decide what our public card advertises). ` +
             `Set A2A_SERVE_URL to this deployment's externally reachable /v1/a2a URL (e.g. "https://agent.example.com/v1/a2a").`);
     }
-    let parsed;
-    try {
-        parsed = new URL(rawUrl);
-    }
-    catch {
-        parsed = undefined;
-    }
-    if (parsed === undefined || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
-        throw new Error(`A2A_SERVE_URL must be a parseable http(s) URL (e.g. "https://agent.example.com/v1/a2a"); got ${JSON.stringify(buildDisplaySafeUrl(rawUrl))}`);
-    }
-    if (parsed.username !== "" || parsed.password !== "") {
-        throw new Error(`A2A_SERVE_URL must not carry userinfo (credentials before "@") — it is published verbatim on the ANONYMOUSLY readable agent card, so those credentials would be handed to every discovery caller. ` +
-            `Inbound authentication on this endpoint is header-shaped (a service credential), not URL-embedded; strip the userinfo and keep the secret in the caller's headers.`);
+    const urlFlaws = httpUrlFlaws(rawUrl, ["userinfo"]);
+    if (urlFlaws.length > 0) {
+        throw new Error(`${buildHttpUrlRefusal("A2A_SERVE_URL", rawUrl, urlFlaws)} — it is published verbatim on the ANONYMOUSLY readable agent card as this deployment's JSON-RPC endpoint ` +
+            `(e.g. "https://agent.example.com/v1/a2a"), so it must be a plain http(s) address and must not hand credentials to every discovery caller: ` +
+            `inbound authentication on this endpoint is header-shaped (a service credential), not URL-embedded.`);
     }
+    const parsed = new URL(rawUrl);
     const a2aCredentialScan = redactSecrets(parsed.href);
     if (a2aCredentialScan !== parsed.href) {
         throw new Error(`A2A_SERVE_URL carries something the credential-redaction law recognizes (${a2aCredentialScan}) — this address is published VERBATIM on the ANONYMOUSLY readable agent card (the card's url is a functional address: peers fetch it, so it is never rewritten for display), ` +
@@ -2400,7 +2371,7 @@ const STORE_GROUP_KEYS = [
 ];
 const MODEL_PLANE_GROUP_KEYS = [
     "gatewayBaseUrl", "gatewayApiKey", "gatewayFallbackUrls", "gatewayMaxRetries", "anthropic", "resilience", "model", "envModel", "models",
-    "modelApiKeyEnv", "modelApiKeys", "modelRefusals", "modelQuotaWeights", "tiers", "projects", "roles", "atModelAllowlist", "cascadeLadder", "degrade",
+    "modelApiKeyEnv", "modelApiKeys", "modelRefusals", "droppedCatalogEntries", "modelQuotaWeights", "tiers", "projects", "roles", "atModelAllowlist", "cascadeLadder", "degrade",
 ];
 const APPROVAL_GROUP_KEYS = [
     "approvalRequire", "approvalDeny", "approvalTimeoutSec", "approvalAutoBudget", "approvalNeverAuto", "approvalGrant",
@@ -2539,15 +2510,9 @@ export function loadConfig() {
         throw new Error(laneRequiredRefusal);
     }
     {
-        const envLaneDispatchable = !isRosterGateArmed(integrations.configCenter);
-        const refusal = modelRouteEndpointRefusal({
-            gatewayBaseUrl: modelPlane.gatewayBaseUrl,
-            gatewayFallbackUrls: modelPlane.gatewayFallbackUrls,
-            anthropic: modelPlane.anthropic,
-            models: envLaneDispatchable ? modelPlane.models : {},
-        });
-        if (refusal !== undefined) {
-            throw new Error(refusal);
+        const routeGap = judgeModelRouteGap(process.env, { envLaneDispatchable: !isRosterGateArmed(integrations.configCenter) });
+        if (routeGap.gap !== "none") {
+            throw new Error(routeGap.reason);
         }
     }
     EXEC_LANE_NOTICE = buildExecLaneNotice(orchestration.remoteExec);

package/dist/fleet/drain-entry.d.ts

@@ -8,6 +8,12 @@
  *     非编排路径 = 停止信号(SIGTERM)/ SIGHUP 升级 / 附着租约自退,动作号由引擎自铸({@link ENGINE_DRAIN_CAUSES})。全部汇到同一只入口。
  *  2. **期限在进入那一拍定死**:请求带的 `deadlineAt` 原样;引擎自起的排空 = 起点 + 此刻的排空窗(`drainGraceMs`)。之后改窗(中心热改
  *     `limits.drainGraceMs`)不动在跑的期限 —— 排空驱动读的是期限,不是窗。
+ *     请求带的期限有**准入上界** = 进入那一拍 + `config.fleetLeaseOutageMaxMs`(`T_max`,env `FLEET_LEASE_OUTAGE_MAX_MS`,`loadConfig` 无条件
+ *     解析、缺省 24 h,成员与非成员同读):一台实例「活着而不服务」最长多久本就由这一席定义(服务租约失联后最多再接单多久,
+ *     `fleet/serving-lease.ts`),排空口不另立第二个数。上界由调用方随入参声明({@link DrainEntry.deadlineBoundMs};排空口声明它,引擎自起的
+ *     排空不声明 —— 那些期限由引擎自己的窗定,拒了就是不排空),**由入口判**:只有这一发会进入排空时才判(已在排空 / 硬停已在进行 ⇒ 期限
+ *     不会被采用,照规则 3 回执);越界 ⇒ 零状态变化,入口答 {@link DrainDeadlineRefusal}(排空口 400 `request.field_invalid`)。「会不会
+ *     采用这只期限」只有入口一处判 —— 调用方不另读 `draining` 去猜。已过的期限不越界(进入即到期:在飞为零当拍硬停,否则下一拍)。
  *  3. **幂等**:已在排空 ⇒ 不重置,回执 `already_draining` 带**第一次**的动作 / 起点 / 期限(不论这次的动作号是否相同)。
  *  4. **身份**:逐字段比,任一不符 ⇒ 409 `conflict.fleet_identity`,零状态变化。
  *     · `scope`:两侧都经 {@link fleetScopeOf} 读成值(缺席 = settings-schema 的缺省 scope,线上任何一处缺席的 scope 都读成它)再严格相等。
@@ -46,25 +52,39 @@ export declare function leaseDrainActionId(generation: string): LeaseDrainAction
 export declare const DRAIN_CAUSE_COUNTS_AS_FIRST_STOP_SIGNAL: {
     readonly [C in EngineDrainCause]: boolean;
 };
-/** 入口的入参:动作号 + 期限(epoch ms)。 */
+/** 入口的入参:动作号 + 期限(epoch ms)+ 调用方声明的期限准入上界(规则 2)。 */
 export interface DrainEntry {
     readonly actionId: string;
     readonly deadlineAt: number;
+    /** 期限的准入上界(ms):这一发会进入排空而 `deadlineAt − 进入那一拍 > 它` ⇒ 入口零状态变化,答 {@link DrainDeadlineRefusal}。
+     *  排空口传 `config.fleetLeaseOutageMaxMs`;引擎自起的排空(停止信号 / 租约被拒 / 附着租约自退)不传。 */
+    readonly deadlineBoundMs?: number;
 }
+/** 入口拒了这只期限(规则 2):越过调用方声明的上界,什么都没变。 */
+export interface DrainDeadlineRefusal {
+    readonly state: "deadline_beyond_bound";
+    readonly boundMs: number;
+}
+/** 入口的答:契约回执(进入 / 已在排空),或期限越界的拒(只在调用方声明了上界时出现)。按 `state` 穷举。 */
+export type DrainEntryAnswer = DrainReceipt | DrainDeadlineRefusal;
 /**
  * 引擎与 HTTP 面共享的排空盒子(装配层建一只,`createHttpServer` 与收尾链各自往上装读口 / 入口)。
  *  · `draining` / `since` / `actionId` / `deadlineAt` —— **只由** {@link enter} 整组写入(排空事实 = 契约 `EngineDraining`);
  *  · `enter` —— 唯一入口(收尾链装;缺席 = 这个进程没有收尾链,如嵌入宿主 / 测试夹具);
  *  · `yieldInflight` —— 让出本副本在飞的可抢占腿(`createHttpServer` 装);
- *  · 其余四只是既有的读口(在飞数 / 活性时钟 / 附着流),语义见 `http/server.ts`。
+ *  · `endSubscriptions` —— 关掉本副本打开着的只读订阅流(发一帧 `draining` 终帧再关;`createHttpServer` 装,S-1281)。订阅流不是在飞的工作
+ *    (不进 `inflight`),排空不等它;收尾链在排空进入那一拍与硬停起点各调一次(排空期间新开的订阅在硬停那一拍收);
+ *  · 其余四只是既有的读口(在飞数 / 活性时钟 / 附着流),语义见 `http/server.ts`。`inflight` 只数**工作**(run 腿 / 计费提交 / HITL 应答 /
+ *    admission 期的普通请求),只读订阅只进 `attachedStreams`(S-1281)。
  */
 export interface DrainState {
     draining: boolean;
     since?: number;
     actionId?: string;
     deadlineAt?: number;
-    enter?: (entry: DrainEntry) => DrainReceipt;
+    enter?: (entry: DrainEntry) => DrainEntryAnswer;
     yieldInflight?: () => void;
+    endSubscriptions?: () => void;
     inflight?: () => number;
     lastActivityAt?: () => number;
     attachedStreams?: () => number;
@@ -72,6 +92,11 @@ export interface DrainState {
 }
 /** 排空盒子里的排空事实(三键齐才是;入口整组写,所以「缺一」只出现在手搭的夹具上)。 */
 export declare function drainingFactOf(s: Pick<DrainState, "draining" | "since" | "actionId" | "deadlineAt">): EngineDraining | undefined;
+/**
+ * 规则 2 的准入上界:期限离进入那一拍(本引擎的挂钟)超过 `boundMs` ⇔ 越界。恰好等于上界不越界;已过的期限不越界。入口判它
+ * (`boot/shutdown.ts` 的 enterDrain,在「已在排空 / 硬停已在进行」两臂之后)。
+ */
+export declare function drainDeadlineBeyondBound(deadlineAt: number, now: number, boundMs: number): boolean;
 /** 本进程的身份。`scope` 已读成值(`config.fleetScope`);其余三项与 `/health` 上读到的同一份。 */
 export interface EngineIdentity {
     readonly scope: string;

package/dist/fleet/drain-entry.js

@@ -13,6 +13,9 @@ export const DRAIN_CAUSE_COUNTS_AS_FIRST_STOP_SIGNAL = {
 export function drainingFactOf(s) {
     return s.draining && s.actionId !== undefined && s.since !== undefined && s.deadlineAt !== undefined ? { actionId: s.actionId, since: s.since, deadlineAt: s.deadlineAt } : undefined;
 }
+export function drainDeadlineBeyondBound(deadlineAt, now, boundMs) {
+    return deadlineAt - now > boundMs;
+}
 export const DRAIN_IDENTITY_FIELDS = ["scope", "worker", "expectedGeneration", "instanceId"];
 export function drainIdentityMismatches(req, self) {
     return DRAIN_IDENTITY_FIELDS.filter((f) => {

package/dist/fleet/engine-signal.d.ts

@@ -5,7 +5,7 @@
  *
  *  1. **一只铸点,三个出口**:{@link mintEngineSignal} 是「引擎此刻自己说自己什么」的唯一来源。`GET /health`(诊断面)、
  *     `GET /readyz`(就绪探针)与 fleet 心跳(`fleet-client.ts`)各读它**一次**,再按各自的出口形投影;没有出口另算一遍
- *     就绪 / 重启 / 代际 / 租约。
+ *     就绪 / 排空 / 重启 / 代际 / 租约 / 世代账,也没有出口绕过它去读 `deps` 上的这些输入。
  *  2. **就绪**仍只有一只谓词(`http/readiness.ts` 的 `readinessOf`),铸点把它的判决原样带上(`verdict`)。`/readyz` 200 ⇔
  *     `ready ∧ ¬draining ∧ leaseState ≠ denied` —— 后两项不是新判据:`draining` 本来就是就绪原因,而租约被拒**同一拍**经
  *     唯一的排空入口进入排空(`fleet/serving-lease.ts`),所以「被拒 ⇒ 排空 ⇒ 不就绪」是构造出来的,不靠第二只谓词。
@@ -15,21 +15,25 @@
  *     是安全可重启的,扣着的片不阻止它们);被扣的片为空(只差发布重试)⇒ 不是重启事实,不铸(契约 `RestartSignal.reasons` 至少一词;
  *     那一形的面只有每拍一行运维 warn + 计数)。「扣着」在两出口上只有这一种读法(7.120.x 的 `/health.modelPlaneDeferred` 本版删除)。
  *     合成只在 {@link buildRestartSignal} 一处,`restartState()` 是它唯一的调用方 —— 两个出口读的是同一只取值口。
- *  4. **代际与实例**:`generation` = env `FLEET_GENERATION` 的回声(规范十进制串;非规范在 boot 拒启,见 `config.ts`);
- *     缺席 ⇔ 非 fleet 成员。`instanceId` = 本进程起步自铸的那一只(`boot/stage-03` 的 uuidv7),不读 env。
- *  5. **出口方言**(契约 `EngineSignal` 与今天两出口的既有形两处不同:`draining` 是布尔、`/health` 就绪时不带 `ready` —— 契约包
- *     自己的 `EngineSignal` 头注写明了这两处;世代账两键 settings-schema 9.0.0 起契约也是数,与引擎同形)—— 两出口**照旧**用 8.0 方言。心跳体的类型
- *     **就是**契约 `InstanceAnnouncement`(中心按它 `safeParse`;8.2.0 起它类型化 `generation` / `leaseState` / `leaseUntil`),没有
- *     契约外的键:世代账(`configTargetVersion` / `configAppliedVersion`)契约心跳形没有座位,只上 `/health`。新增的键
- *     (`generation` / `leaseState` / `leaseUntil`、`restart.withheld`)只在 fleet 成员 / 扣着的候选在场时出现 ⇒ 非 fleet 部署的
- *     两出口逐字节同 7.120.0。方言收口归契约包下一个 major(布尔 `draining` 对退役、两出口整只承载 `EngineSignal`)与中心提货之后,
- *     由引擎同版翻转 —— 不在本层另造第二方言。
+ *  4. **代际**:`generation` = env `FLEET_GENERATION` 的回声(规范十进制串;非规范在 boot 拒启,见 `config.ts`);缺席 ⇔ 非 fleet 成员。
+ *     **身份不是引擎态**:`instanceId`(本进程起步自铸的那一只,`boot/stage-03` 的 uuidv7)是体的身份,只在两出口体的**顶层**说一次,
+ *     铸点不读它、契约形里不重复它。
+ *  5. **两形一读(展开 / 收缩)**:两出口今天各发两形 —— 嵌套键 {@link ENGINE_SIGNAL_KEY}(契约 `EngineSignal` 整只,{@link buildEngineSignal}),
+ *     与 8.0 扁平方言(布尔 `draining` + `drainingSince`、`/health` 就绪时不带 `ready`、`restart`、成员三键、`/health` 的世代账)。两形读的是
+ *     **同一次**铸点读数里的**同一个字段**,投影全在本模块({@link buildEngineSignal} / {@link heartbeatReadinessKeys} / {@link healthDrainingKeys} /
+ *     {@link fleetMembershipKeys} / {@link healthConfigLedgerKeys}),出口文件不拼引擎态的键。排空在两形上读的都是排空**事实**(`EngineDraining`,
+ *     三键齐才在),不是就绪原因 —— 所以「`engineSignal.draining` 在场 ⇔ 扁平 `draining` 为真、`drainingSince` = `engineSignal.draining.since`」
+ *     是构造出来的,不靠「唯一入口整组写四键」这条运行时不变量(那条不变量只管就绪原因与事实一致)。
+ *     心跳体 = 契约 `InstanceAnnouncement` + 嵌套键这一只:契约包 10.x 的心跳形还没有它的座位,10.x 中心按默认 strip 解析丢掉它、照收心跳;
+ *     世代账扁平两键契约心跳形没有座位,只上 `/health`(嵌套形里有,两出口都带)。非 fleet 部署的扁平键与 7.122.0 逐字同。
+ *     收缩:扁平布尔对(`draining` / `drainingSince`)settings-schema 12.0.0 从契约形删、本引擎 7.124.0+ 删发(届时删它们的投影);嵌套键名在
+ *     契约包自有这只常量的那一版提货时改读它。
  *  6. **租约四态的词表属主是契约包**(`LeaseState`):本模块的读数型 {@link ServingLeaseView} 按它逐词对齐(下面的编译期断言两向钉),
  *     契约加一个词 ⇒ 本仓编译红,不会悄悄多出一个本仓读不出的态。
  *
- * 模块形:纯函数(只值 import 契约包与 `http/readiness.ts`)—— `http/` 与 `fleet-client.ts` 都读它,不许长出回环。
+ * 模块形:纯函数(契约包只 import 型;值 import 只有两只纯叶 `http/readiness.ts` 与 `fleet/drain-entry.ts`)—— `http/` 与 `fleet-client.ts` 都读它,不许长出回环。
  */
-import type { EngineDraining, InstanceAnnouncement, LeaseState, RestartSignal } from "@sema-agent/settings-schema/fleet";
+import type { EngineDraining, EngineSignal, InstanceAnnouncement, LeaseState, RestartSignal } from "@sema-agent/settings-schema/fleet";
 import { type ReadinessInputs, type ReadinessVerdict } from "../http/readiness.js";
 /**
  * 租约此刻的读数(租约客户端交出;纯数据)。态的词表 = 契约 `LeaseState`(四词的语义在契约注里:`none` 不生效 / `granted` 持有 /
@@ -94,9 +98,16 @@ export declare function configHandoffMissing(ledger: ConfigHandoffLedger): boole
 /** `configHandoff` 的**唯一**合成点(纯):缺着 ⇒ `{ state: "missing", version: 应用着的那一代, since }`;否则缺席。`since` 由持账方锁存(发现缺着的那一拍)。
  *  `build*` = 纯数据;config-center 的 `configHandoffState()` 是唯一调用方。 */
 export declare function buildConfigHandoff(ledger: ConfigHandoffLedger, since: number | undefined): ConfigHandoff | undefined;
+/** 世代账的一次读数(config-center 的 `configApplyState()` 交出的那一份里本模块读的五键;`/health` 扁平五键与嵌套形的两键读同一份)。 */
+export interface ConfigLedgerReading {
+    readonly configTargetVersion: number;
+    readonly configAppliedVersion: number;
+    readonly configTargetOrdinal: number;
+    readonly configAppliedOrdinal: number;
+    readonly configApplyStaleMs?: number;
+}
 /** 铸点读的输入 —— `ServiceDeps` 上的同名键(HTTP 面与心跳读的是**同一个**对象)。 */
 export interface EngineSignalInputs extends ReadinessInputs {
-    readonly instanceId?: string;
     /** `config.fleetGeneration` = env `FLEET_GENERATION` 的回声(boot 已判规范;缺席 ⇔ 非 fleet 成员)。 */
     readonly config?: {
         readonly fleetGeneration?: string;
@@ -108,34 +119,54 @@ export interface EngineSignalInputs extends ReadinessInputs {
     };
     readonly restartState?: () => RestartSignal | undefined;
     readonly servingLease?: () => ServingLeaseView;
-    readonly configApplyState?: () => {
-        readonly configTargetVersion: number;
-        readonly configAppliedVersion: number;
-    } | undefined;
+    readonly configApplyState?: () => ConfigLedgerReading | undefined;
 }
 /** 铸出的信号(纯数据)。 */
 export interface EngineSignalFacts {
     /** 就绪判(`readinessOf` 原样)。 */
     readonly verdict: ReadinessVerdict;
-    /** 在场 ⇔ 排空中(契约 `EngineDraining`:动作 / 起点 / 期限)。 */
+    /** 在场 ⇔ 排空中(契约 `EngineDraining`:动作 / 起点 / 期限)—— 两出口两形读排空的唯一字段(规则 5)。 */
     readonly draining?: EngineDraining;
     readonly restart?: RestartSignal;
     readonly generation?: string;
-    readonly instanceId?: string;
     readonly lease: ServingLeaseView;
-    readonly configTargetVersion?: number;
-    readonly configAppliedVersion?: number;
+    /** 世代账的那一次读数(未接线 ⇒ 缺席)。 */
+    readonly configApply?: ConfigLedgerReading;
 }
 /** **唯一**铸点(活判,每次调用现读输入)。 */
 export declare function mintEngineSignal(deps: EngineSignalInputs): EngineSignalFacts;
+/**
+ * 两出口体上嵌套引擎信号的键名(规则 5;两出口同一只拼法)。契约包 10.x 没有这只常量(它的心跳形也没有这一座位);契约包自有它的那一版
+ * 提货时,本常量删、改读契约包的。
+ */
+export declare const ENGINE_SIGNAL_KEY = "engineSignal";
+/** 体上的嵌套引擎信号:键 {@link ENGINE_SIGNAL_KEY},值 = 契约 `EngineSignal`。 */
+export type EngineSignalCarrier = {
+    readonly [ENGINE_SIGNAL_KEY]: EngineSignal;
+};
+/**
+ * 契约形 `EngineSignal` 的**唯一**投影(规则 5;两出口同调,同一次读数 ⇒ 同值同序)。键序照契约形:`ready` 恒说;`draining` = 排空事实;
+ * `restart` = 取值口交出的那个对象;成员三键 = {@link fleetMembershipKeys};世代账两键 = 同一次读数。身份不在这里(规则 4)。`build*` = 纯数据。
+ */
+export declare function buildEngineSignal(s: EngineSignalFacts): EngineSignal;
 /**
  * fleet 成员身份三键的**唯一**投影(两出口同调,同值同序):`generation` / `leaseState` / `leaseUntil`。
  * 在场律:非 fleet 成员(无 `generation`)⇒ 空对象(两出口逐字节同 7.120.0);成员 ⇒ `generation` + `leaseState` 恒在,
  * `leaseUntil` 只在 `granted`。
  */
 export declare function fleetMembershipKeys(s: EngineSignalFacts): FleetMembershipKeys;
-/** 出口的 8.0 方言布尔 `draining`(心跳 `InstanceAnnouncement.draining` / `/health.draining`):就绪原因含排空。 */
-export declare function drainingFlag(s: EngineSignalFacts): boolean;
+/** 心跳的 8.0 扁平方言 `ready` / `draining`(恒带,`false` 也带):`ready` = 就绪判,`draining` = 排空事实在场(规则 5,与嵌套形读同一个字段)。 */
+export declare function heartbeatReadinessKeys(s: EngineSignalFacts): Pick<InstanceAnnouncement, "ready" | "draining">;
+/** `/health` 的 8.0 扁平排空对:只在排空中带 —— `draining: true` + `drainingSince` = 排空事实的 `since`(规则 5,与嵌套形读同一个字段)。 */
+export declare function healthDrainingKeys(s: EngineSignalFacts): {
+    readonly draining?: true;
+    readonly drainingSince?: number;
+};
+/**
+ * `/health` 的世代账扁平键(未接线 ⇒ 全缺席):target / applied 两版本(与嵌套形同一次读数)+ 两只收货序数(进程内单调,「见过多少代 / 停在哪一代」
+ * 的推进判据)+ `configApplyStaleMs`(两者持续不等的时长,收敛即缺席)。只上 `/health`(契约心跳形没有这些座位)。
+ */
+export declare function healthConfigLedgerKeys(s: EngineSignalFacts): Partial<ConfigLedgerReading>;
 /**
  * `/health.restartRequired`(冗余顶层布尔,壳读它决定要不要问用户重启)的投影:在场 ⇔ 有**可执行**的重启信号
  * (`restart` 在场且未被扣)—— 与 7.120.0 的读数逐字同(那时被扣的候选根本不出 `restart`)。