@sema-agent/server 7.88.1 → 7.89.0

package/dist/boot/stage-06-runners.js

@@ -7,7 +7,7 @@ import { redactSecrets } from "../trace/redact.js";
 import { hasServiceAuth } from "../http/server.js";
 import { workflowModelAllowlistFor } from "../task-workflow.js";
 import { backendOwnsControlPlane } from "../memory-operator-faces.js";
-import { createHookLlm } from "../hooks/hook-llm.js";
+import { createHookLlm, buildHookFailureText } from "../hooks/hook-llm.js";
 import { assertRetentionLaneWirable } from "./retention-lane.js";
 import { assertConsolidationDriverWirable, buildConsolidationValveAudit, createMemoryConsolidationFaces, resolveConsolidationDriverSeat } from "./memory-consolidation.js";
 import { createPerModelAuthSeat } from "./side-query-lane.js";
@@ -132,7 +132,7 @@ export function runStage06(ctx) {
     const runnerTierFrozen = Object.keys(config.tiers).length > 0;
     const { hookModelFor, hookLlm } = createHookLlm({ config, getKeyResolver: () => configCenter.getKeyResolver(), metrics });
     const hookAgentRunner = new Runner({ ...runnerDeps, sessionStore: new TtlSessionStore({ defaultTtlDays: 1 / 24 }) });
-    const hookAgent = async ({ prompt, model, timeoutMs, system }) => {
+    const agentHookCall = async ({ prompt, model, timeoutMs, system }) => {
         const pick = hookModelFor(model);
         if (!pick.ok)
             return pick;
@@ -150,7 +150,7 @@ export function runStage06(ctx) {
             metrics.inc("hook_llm_calls_total", { type: "agent" });
             if (result.terminal.kind !== "completed") {
                 const plane = terminalProjection(result.terminal);
-                return { ok: false, error: `hook agent ${plane.status}: ${clipHookErr(plane.errorMessage)}` };
+                return { ok: false, error: `hook agent ${plane.status}: ${plane.errorMessage ?? ""}` };
             }
             return { ok: true, text: result.result ?? "" };
         }
@@ -158,6 +158,10 @@ export function runStage06(ctx) {
             return { ok: false, error: String(e) };
         }
     };
+    const hookAgent = async (opts) => {
+        const out = await agentHookCall(opts);
+        return out.ok ? out : { ...out, error: clipHookErr(buildHookFailureText(out.error)) };
+    };
     const clipHookErr = (s) => (s ?? "").slice(0, 300);
     const titleCapable = sessionStore;
     const sessionTitler = config.sessionAutoTitle && titleCapable.setTitleIfNull && titleCapable.probeTitle

package/dist/brain.js

@@ -3,7 +3,7 @@ import { normalizeBaseUrl } from "@sema-agent/core";
 import { buildDefaultResilience } from "./config-types.js";
 import { resolveModelApiKey } from "./key-resolver.js";
 import { catalogBrainLane } from "./model-provider.js";
-import { buildDisplaySafeUrl } from "./trace/redact.js";
+import { buildDisplaySafeUrl, redactSecrets } from "./trace/redact.js";
 function isOffDeploymentRoot(baseUrl, config) {
     if (!baseUrl)
         return false;
@@ -158,7 +158,7 @@ export function brainSummary(config) {
             const verdict = adjudicateModelRoute({ id: target.id, baseUrl: target.baseUrl }, resolveRouteCredential({ ...(config.gatewayApiKey ? { configApiKey: config.gatewayApiKey } : {}) }), { baseUrl: degradeDeclaredRoot(target.baseUrl, config) });
             return verdict.ok
                 ? { reactiveDegradeRoutePairing: `ok:${verdict.posture}`, reactiveDegradeRouteRefusal: null }
-                : { reactiveDegradeRoutePairing: `broken:${verdict.code}`, reactiveDegradeRouteRefusal: routeRefusalText(verdict) };
+                : { reactiveDegradeRoutePairing: `broken:${verdict.code}`, reactiveDegradeRouteRefusal: redactSecrets(routeRefusalText(verdict)) };
         })()),
     };
 }

package/dist/capabilities/center-plugins.d.ts

@@ -1,5 +1,15 @@
 import type { Logger } from "../observability/logger.js";
 import { type LoadedSkill } from "./skills.js";
+/**
+ * 声明面的 `source.url` 长度上限(S-483)—— **界在声明关口,不在每个出口各切一刀**。
+ *
+ * 由来:出口上原有一刀 `.slice(0, 80)`,而它做了两件坏事(① 把 display-safe 铸点的 `«redacted…»` 记号截成
+ * 半只;② 与同一条 URL 在别处的处置成了两把尺)。删掉它之后,这个 **center 下发**值在日志行与
+ * `failures[]` 回执上就再没有界 —— 于是界回到它该在的地方:**声明被接收的那一刻**(与 hook 条目的 url
+ * 同形 —— `parseHooksConfig` 用 `MAX_HOOK_COMMAND_CHARS` 在解析期就拒)。2048 = URL 的事实上限
+ * (同一个数在 `http/routes/sessions.ts` 的对端 endpoint 读面上也在用);超界的 git clone URL 不存在真部署。
+ */
+export declare const MAX_PLUGIN_SOURCE_URL_CHARS = 2048;
 /** 缺省 clone host 白名单(契约条款 1;国内镜像走本名单加 https 镜像域,不开 http 口)。 */
 export declare const DEFAULT_PLUGIN_ALLOW_HOSTS: readonly string[];
 /** wire 上的插件声明(registry-core PluginSpec 的宽读形——本模块只消费不裁决,未知键忽略)。 */

package/dist/capabilities/center-plugins.js

@@ -3,8 +3,17 @@ import { promisify } from "node:util";
 import { promises as fsp, realpathSync, existsSync, readFileSync, lstatSync, statSync } from "node:fs";
 import { join, resolve, isAbsolute, sep } from "node:path";
 import { assertConfined, loadSkills } from "./skills.js";
+import { buildDisplaySafeUrl, redactSecrets } from "../trace/redact.js";
 const execFileP = promisify(execFile);
+export const MAX_PLUGIN_SOURCE_URL_CHARS = 2048;
 export const DEFAULT_PLUGIN_ALLOW_HOSTS = ["github.com"];
+function wireTypeWord(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "array";
+    return typeof v;
+}
 export function validatePluginDecl(decl, allowHosts) {
     const name = typeof decl.name === "string" && decl.name !== "" ? decl.name : "(unnamed)";
     if (decl.enabled === false)
@@ -16,8 +25,14 @@ export function validatePluginDecl(decl, allowHosts) {
     if (kind !== "git")
         return { ok: false, name, reason: `unsupported source.kind ${String(kind)}` };
     const url = decl.source?.url;
-    if (typeof url !== "string" || !/^https:\/\//i.test(url)) {
-        return { ok: false, name, reason: `plugin source must be an https:// URL (contract: https-only; got ${String(url).slice(0, 80)})` };
+    if (typeof url !== "string") {
+        return { ok: false, name, reason: `plugin source.url must be a string (got ${wireTypeWord(url)})` };
+    }
+    if (url.length > MAX_PLUGIN_SOURCE_URL_CHARS) {
+        return { ok: false, name, reason: `plugin source url exceeds ${MAX_PLUGIN_SOURCE_URL_CHARS} chars (got ${url.length}) — a clone URL that long is a declaration error, and it would ride every log line and failure receipt verbatim` };
+    }
+    if (!/^https:\/\//i.test(url)) {
+        return { ok: false, name, reason: `plugin source must be an https:// URL (contract: https-only; got ${buildDisplaySafeUrl(url)})` };
     }
     let host;
     try {
@@ -140,13 +155,14 @@ export async function applyCenterPlugins(baseline, eff, opts) {
         }
         catch (err) {
             await fsp.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+            const safeErr = redactSecrets(err instanceof Error ? err.message : String(err));
             if (existsSync(liveDir)) {
-                opts.logger?.warn("center_plugin_fetch_failed_lkg", { plugin: v.name, error: err instanceof Error ? err.message : String(err) });
+                opts.logger?.warn("center_plugin_fetch_failed_lkg", { plugin: v.name, error: safeErr });
                 out.lkgUsed.push(v.name);
             }
             else {
-                opts.logger?.warn("center_plugin_fetch_failed", { plugin: v.name, error: err instanceof Error ? err.message : String(err) });
-                out.failures.push({ plugin: v.name, reason: `fetch failed: ${err instanceof Error ? err.message : String(err)}` });
+                opts.logger?.warn("center_plugin_fetch_failed", { plugin: v.name, error: safeErr });
+                out.failures.push({ plugin: v.name, reason: `fetch failed: ${safeErr}` });
                 continue;
             }
         }

package/dist/config-catalog.js

@@ -55,7 +55,7 @@ export const CONFIG_CATALOG = [
     r("ALLOW_UNAUTHED_WRITES", "auth", "boolean", "无 service token 时仍接受任务提交(本地开发逃生口;缺省 fail-closed 拒提交)", { staticDefault: "false", danger: SEC, configKey: "allowUnauthedWrites" }),
     r("ANTHROPIC_API_KEY", "modelPlane", "secret", "Anthropic 协议路线的 x-api-key 凭据(与 AUTH_TOKEN 二选一,AUTH_TOKEN 优先;与 BASE_URL 同在时可推断 provider)", { danger: [...SEC, ...BILL] }),
     r("ANTHROPIC_AUTH_TOKEN", "modelPlane", "secret", "Anthropic 兼容生态的 Bearer 凭据(设了则不发 x-api-key)", { danger: [...SEC, ...BILL] }),
-    r("ANTHROPIC_BASE_URL", "modelPlane", "url", "Anthropic 协议路线 base URL(与凭据同在且 MODEL_PROVIDER 未设 ⇒ 推断 provider=anthropic 并 boot notice;S-475:带 userinfo 拒启,机读码 `config.gateway_url_userinfo`)"),
+    r("ANTHROPIC_BASE_URL", "modelPlane", "url", "Anthropic 协议路线 base URL(与凭据同在且 MODEL_PROVIDER 未设 ⇒ 推断 provider=anthropic 并 boot notice;S-475:带 userinfo 拒启,机读码 `config.gateway_url_userinfo`;S-483:解析不动/不透明形拒启,机读码 `config.model_route_url_invalid`)"),
     r("ANTHROPIC_CACHE_BREAKPOINTS", "modelPlane", "boolean", "Anthropic 路线 prompt-cache breakpoints 开关", { staticDefault: "true" }),
     r("ANTHROPIC_MAX_RETRIES", "modelPlane", "number", "Anthropic 路线 SDK 每次调用重试上限", { derivedDefaultNote: "缺席 ⇒ 不传引擎,core/SDK 默认当家" }),
     r("ANTHROPIC_VERSION", "modelPlane", "string", "Anthropic API version 头(缺省由 SDK 定)"),
@@ -72,7 +72,7 @@ export const CONFIG_CATALOG = [
     r("ATTACHMENT_ORPHAN_GRACE_MS", "limitsHttp", "number", "附件孤儿对象 GC 宽限(ms;0=关本腿,坏值回默认+warn)", { staticDefault: "3600000", danger: DATA, center: cLimits("attachmentOrphanGraceMs") }),
     r("ATTACHMENT_UNBOUND_TTL_MS", "limitsHttp", "number", "未绑定附件的 TTL(ms)", { staticDefault: String(24 * 3600 * 1000), danger: DATA, configKey: "attachmentUnboundTtlMs", center: cLimits("attachmentUnboundTtlMs") }),
     r("AUTH_BRIDGE_AUDIENCE", "auth", "string", "registry SSO-JWT 验签期望 aud", { danger: SEC }),
-    r("AUTH_BRIDGE_ISSUER", "auth", "string", "registry SSO-JWT issuer(auth bridge 的开关之一)", { danger: SEC, derivedDefaultNote: "缺席 ⇒ 用 configCenter.baseUrl(配了 center 即默认开桥)" }),
+    r("AUTH_BRIDGE_ISSUER", "auth", "url", "registry SSO-JWT issuer(auth bridge 的开关之一)", { danger: SEC, derivedDefaultNote: "缺席 ⇒ 用 configCenter.baseUrl(配了 center 即默认开桥)" }),
     r("AUTH_BRIDGE_JWKS_URL", "auth", "url", "registry SSO-JWT 的 JWKS 地址(缺省从 issuer 派生)", { danger: SEC }),
     r("AUTONOMY", "auth", "enum", "运维 autonomy 模式,tighten-only 叠到每个 TaskSpec(read-only/plan ⇒ 只读手,ask ⇒ 恒 shellGate);center 腿热且 non-sticky", { danger: SEC, enumValues: ["read-only", "ask", "plan", "auto"], configKey: "autonomy", center: cGov("autonomy") }),
     r("AUTO_MODE_CLASSIFIER_FALLBACK", "approval", "enum", "auto 分类器席答不出裁决时的梯子(main=主模型代判 / none=只留分类器那一级,整条拒)", { enumValues: ["main", "none"], danger: SEC, derivedDefaultNote: "未设/空串 ⇒ 不铸键,跟随引擎缺省 main(core 7.18.0 起;空串按未设,与其余词表旋钮同判);none = 7.77.0 及以前的行为逐字;词表外的值启动期拒启。权限轴放宽,升级须知见 DEPLOY-PREREQS", configKey: "autoModeClassifierFallback" }),
@@ -282,8 +282,8 @@ export const CONFIG_CATALOG = [
     r("MODEL_EXTRA_BODY", "modelPlane", "opaque", "生成参数直通 JSON(top_k/logit_bias 等;必须静态 —— 前缀缓存键序)", { danger: SEC }),
     r("MODEL_FIRST_TOKEN_TIMEOUT_MS", "modelPlane", "number", "首 token 超时(ms;0=关 —— 开流不吐字的唯一看门狗;自托管长 prefill 后端按此档留足)", { staticDefault: String(RESILIENCE_DEFAULTS.firstTokenTimeoutMs.value) }),
     r("MODEL_FREQUENCY_PENALTY", "modelPlane", "number", "frequency_penalty 直通(压过 EXTRA_BODY 同键)"),
-    r("MODEL_GATEWAY_BASEURL", "modelPlane", "url", "openai 兼容网关 base URL(默认 localhost 占位 —— 公开分发不烤内网坐标;S-475:带 userinfo 拒启,机读码 `config.gateway_url_userinfo` —— WHATWG 禁止用带凭据的 URL 构造 fetch Request,凭据放 MODEL_API_KEY)", { staticDefault: "http://127.0.0.1:8000/v1", configKey: "gatewayBaseUrl", center: cModels("models[].baseUrl") }),
-    r("MODEL_GATEWAY_FALLBACK_URLS", "modelPlane", "url", "网关故障转移地址表(CSV;S-475:**逐项**判 userinfo,任一项带 ⇒ 拒启,机读码 `config.gateway_url_userinfo`)", { configKey: "gatewayFallbackUrls" }),
+    r("MODEL_GATEWAY_BASEURL", "modelPlane", "url", "openai 兼容网关 base URL(默认 localhost 占位 —— 公开分发不烤内网坐标;S-475:带 userinfo 拒启,机读码 `config.gateway_url_userinfo` —— WHATWG 禁止用带凭据的 URL 构造 fetch Request,凭据放 MODEL_API_KEY;S-483:解析不动/不透明形拒启,机读码 `config.model_route_url_invalid`)", { staticDefault: "http://127.0.0.1:8000/v1", configKey: "gatewayBaseUrl", center: cModels("models[].baseUrl") }),
+    r("MODEL_GATEWAY_FALLBACK_URLS", "modelPlane", "url", "网关故障转移地址表(CSV;S-475:**逐项**判 userinfo,任一项带 ⇒ 拒启,机读码 `config.gateway_url_userinfo`;S-483:逐项判可解析性,机读码 `config.model_route_url_invalid`)", { configKey: "gatewayFallbackUrls" }),
     r("MODEL_ID", "modelPlane", "string", "主模型 id(3.0.0 起无出厂缺省,缺 ⇒ 拒启指路)", { configKey: "model", resolve: (c) => c.model.id, center: cModels("models[].id") }),
     r("MODEL_IDLE_TIMEOUT_MS", "modelPlane", "number", "流中静默看门狗(ms;0=关)", { staticDefault: String(RESILIENCE_DEFAULTS.idleTimeoutMs.value) }),
     r("MODEL_MAX_TOKENS", "modelPlane", "number", "主模型输出上限", { derivedDefaultNote: "缺席 ⇒ min(32000, contextWindow)", resolve: (c) => c.model.maxTokens ?? null, center: cModels("models[].maxTokens") }),

package/dist/config-center/apply-effective.js

@@ -203,7 +203,7 @@ function stageEffective(config, eff, logger, opts) {
                 if (ok)
                     logger?.warn("sema_registry_model_base_url", { model: m.name, baseUrl: buildDisplaySafeUrl(rawBaseUrl), hint: "registry-directed gateway override — this model's key authenticates AGAINST THIS URL" });
                 else {
-                    logger?.warn("sema_registry_model_base_url_rejected", { model: m.name, baseUrl: buildDisplaySafeUrl(String(rawBaseUrl)).slice(0, 120), hint: "only http(s) URLs are honored — falling back to the boot-env gateway" });
+                    logger?.warn("sema_registry_model_base_url_rejected", { model: m.name, baseUrl: buildDisplaySafeUrl(String(rawBaseUrl)), hint: "only http(s) URLs are honored — falling back to the boot-env gateway" });
                     safeUrl = undefined;
                 }
             }

package/dist/config.js

@@ -1334,12 +1334,12 @@ function parseMemoryEmbedder(ctx) {
         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="${endpoint}" is not a valid URL (expected e.g. https://embeddings.example.com/v1 — the OpenAI-compatible base, or the full .../embeddings 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="${endpoint}" must be http(s) (got "${proto}") — the embedder leg is an HTTP POST to an OpenAI-compatible /embeddings face`);
+        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.");
@@ -1966,12 +1966,18 @@ function parseA2aServe() {
         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(rawUrl)}`);
+        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 a2aDisplaySafe = buildDisplaySafeUrl(rawUrl);
+    if (a2aDisplaySafe !== parsed.href) {
+        throw new Error(`A2A_SERVE_URL carries something the credential-redaction law recognizes (${a2aDisplaySafe}) — 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), ` +
+            `so it must not carry credentials of ANY shape: no userinfo, no credential-named query parameter (api_key/token/…), no token-shaped path segment or parameter value. ` +
+            `Keep A2A_SERVE_URL to scheme://host[:port][/path] and move the secret into the caller's headers.`);
+    }
     return {
         name: env("A2A_SERVE_NAME", "sema-server"),
         ...(process.env.A2A_SERVE_DESCRIPTION ? { description: process.env.A2A_SERVE_DESCRIPTION } : {}),

package/dist/hooks/hook-llm.d.ts

@@ -24,6 +24,31 @@ export type HookModelPick = {
     ok: false;
     error: string;
 };
+/**
+ * 🔴 **hook 失败展示文本的唯一铸点**(S-494;`build*` = 返回纯数据的一只纯函数)。
+ *
+ * 病(codex 对 7.88.1/7.88.2 的补审抓出,存量泄漏,本车红先复现):这一族失败文本是**拼**出来的 ——
+ * 料有四种:core 的路由拒绝文案(`routeRefusalText` 的 `fixHint` 逐字带 `config.baseUrl` 的值)、
+ * 原生 `fetch` 的**构造期异常正文**(WHATWG:`…includes credentials: <整条 URL>`,口令逐字)、
+ * 它的 `cause`、per-model key 解析错。改前只有**两个 URL 位**走了 display-safe 铸点 —— 那是名单制:
+ * 组装料换一种(异常正文、cause)就漏,而它的出口是 `hook_runner` 的 `hook_llm_failed` warn 与
+ * `noteHookFailure` 的 stderr 位。⇒ 把尺放到**出口**:整段组装完了过**一次**律,规则从「N 个 URL 位」
+ * 减到「一只出口」(那两个 display-safe 调用随之删)。
+ *
+ * 用的是自由文本那一条律({@link redactSecrets})—— `buildDisplaySafeUrl` 是它加两道 URL 专属闸的
+ * **已知是一条 URL** 的那个特例,而这里的料是自由文本(一段异常正文里可能一个 URL 都没有,也可能有三个)。
+ * 同一张名表、同一批记号,不是第二把尺。
+ *
+ * 🔴 **脱敏器抛 ⇒ 响亮扣下**(不回原串、不 fail-open):文案形与 7.88.1 的
+ * `fail-open.ts` `renderDetail` 逐字同族(`[… withheld: redactor threw <Name>]`)—— 运维丢掉的是细节、
+ * 不是「这次失败了」这件事,而一个字节的原串都不会漏出去。
+ *
+ * 🚧 **已知射程边界(登记,另车修在源头)**:自由文本律对**非规范拼法**的 URL
+ * (`https:alice:pw@h/v1` 省了 `//`、authority 里夹 tab)认不出结构 ⇒ 那两形若出现在料里(目录下发的
+ * `models[].baseUrl` 今天原样存,`apply-effective.ts` 只校验 `protocol`)仍会原样。修在源头 =
+ * 目录 baseUrl 落库前归一成 `new URL(raw).href`(S-483 收车档未闭环项),不是在这里再加一把尺。
+ */
+export declare function buildHookFailureText(raw: string): string;
 /** The live object `createHookLlm` produces — model-pick resolution + the direct completion call, both capturing the hot-refreshed keyResolver/fetchImpl in closure. */
 export interface HookLlm {
     hookModelFor: (requested?: string) => HookModelPick;

package/dist/hooks/hook-llm.js

@@ -1,6 +1,16 @@
 import { adjudicateModelRoute, normalizeBaseUrl, resolveRouteCredential, routeRefusalText } from "@sema-agent/core";
 import { matchCatalogModel } from "../model-select.js";
-import { buildDisplaySafeUrl } from "../trace/redact.js";
+import { redactSecrets } from "../trace/redact.js";
+export function buildHookFailureText(raw) {
+    if (raw === "")
+        return raw;
+    try {
+        return redactSecrets(raw);
+    }
+    catch (err) {
+        return `[hook failure text withheld: redactor threw ${err instanceof Error ? err.name : typeof err}]`;
+    }
+}
 export function createHookLlm(deps) {
     const { config, metrics } = deps;
     const anthropicRouteBaseUrl = () => config.anthropic ? config.anthropic.baseUrl || "https://api.anthropic.com" : undefined;
@@ -48,7 +58,7 @@ export function createHookLlm(deps) {
         if ((verdict.posture === "unpinned" || verdict.posture === "keyless") && normalizeBaseUrl(pick.baseUrl) !== normalizeBaseUrl(declaredRoot)) {
             return {
                 ok: false,
-                error: `hook model "${pick.catalogRef}" points at ${buildDisplaySafeUrl(pick.baseUrl)}, which this deployment did not declare as its own endpoint, ` +
+                error: `hook model "${pick.catalogRef}" points at ${pick.baseUrl}, which this deployment did not declare as its own endpoint, ` +
                     `and no per-model credential resolved — refusing to send the prompt there (it embeds user content; an unauthenticated ` +
                     `request still hands that content to whoever operates that URL)`,
             };
@@ -56,7 +66,7 @@ export function createHookLlm(deps) {
         return { ok: true, credential };
     };
     const fetchImpl = deps.fetchImpl ?? fetch;
-    const hookLlm = async ({ prompt, model, timeoutMs, system, maxOutputTokens }) => {
+    const callLlm = async ({ prompt, model, timeoutMs, system, maxOutputTokens }) => {
         const pick = hookModelFor(model);
         if (!pick.ok)
             return pick;
@@ -126,13 +136,17 @@ export function createHookLlm(deps) {
             const cause = e?.cause;
             return {
                 ok: false,
-                error: ac.signal.aborted ? "hook llm timeout" : `hook llm request to ${buildDisplaySafeUrl(pick.baseUrl)} failed: ${String(e)}${cause ? ` (${String(cause)})` : ""}`,
+                error: ac.signal.aborted ? "hook llm timeout" : `hook llm request to ${pick.baseUrl} failed: ${String(e)}${cause ? ` (${String(cause)})` : ""}`,
             };
         }
         finally {
             clearTimeout(t);
         }
     };
+    const hookLlm = async (opts) => {
+        const out = await callLlm(opts);
+        return out.ok ? out : { ...out, error: buildHookFailureText(out.error) };
+    };
     return { hookModelFor, hookLlm };
 }
 //# sourceMappingURL=hook-llm.js.map

package/dist/hooks/hook-runner.js

@@ -3,7 +3,7 @@ import { hostShell, resolveHostShell } from "../plugins/host-platform.js";
 import { HooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_EVENT_OWNER, } from "@sema-agent/settings-schema/hooks";
 import { boundedNoticeText } from "../fleet/fleet-bus.js";
 import { recordFailOpen } from "../observability/fail-open.js";
-import { redactSecrets } from "../trace/redact.js";
+import { redactSecrets, buildDisplaySafeUrl } from "../trace/redact.js";
 import { ccPromptSystemFor, wrapCondition, parseCcVerdict, CC_EVALUATOR_MAX_OUTPUT_TOKENS } from "./cc-stop-prompt.js";
 import { ccAgentHookSystemFor } from "./cc-agent-hook-prompt.js";
 import { renderBranchTranscript } from "./branch-transcript.js";
@@ -495,7 +495,7 @@ async function runHttpHook(entry, payload, ctx) {
             if (trimmed === "")
                 return { code: 0, stdout: "{}", stderr: "", timedOut: false };
             if (!parseHookStdout(body)) {
-                ctx.logger.warn("hook_http_non_json_response", { url: clip(entry.url, 300), preview: clip(trimmed, 200) });
+                ctx.logger.warn("hook_http_non_json_response", { url: buildDisplaySafeUrl(entry.url), preview: clip(trimmed, 200) });
                 noteHookFailure(ctx, {
                     event: eventOfPayload(payload),
                     entry,

package/dist/http/routes/session-sync.js

@@ -6,6 +6,7 @@ import { exportSessionManifest, fileHistoryImportFace, replayFileHistory, replay
 import { classifySyncRelationshipByIds, SyncConflictError } from "../../session-sync-kernel.js";
 import { isUuidShape } from "../../security.js";
 import { sendJson, sendError, msg } from "../send.js";
+import { buildDisplaySafeUrl } from "../../trace/redact.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 const SYNC_BLOB_MAX_BYTES = 64 * 1024 * 1024;
 const SYNC_NDJSON_LINE_MAX_BYTES = 8 * 1024 * 1024;
@@ -194,7 +195,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     void deps.sessionMirrorRuling(auditPrincipal).then((mirror) => {
                         if (mirror?.required) {
                             deps.metrics?.inc("session_mirror_required_push_total");
-                            deps.logger?.info("session_mirror_required_push_observed", { principal: auditPrincipal, engineUrl: mirror.engineUrl, sessionId });
+                            deps.logger?.info("session_mirror_required_push_observed", { principal: auditPrincipal, engineUrl: buildDisplaySafeUrl(mirror.engineUrl), sessionId });
                         }
                     }).catch(() => { });
                 }

package/dist/model-route-url.d.ts

@@ -1,9 +1,25 @@
 /** 机读码(拼法随 `config.<键名蛇形>_*` 既有族:`config.model_provider_invalid` / `config.retention_policy_invalid`)。 */
 export declare const GATEWAY_URL_USERINFO_CODE = "config.gateway_url_userinfo";
-/** 这个 URL 带 userinfo(用户名或密码任一非空)吗?解析不动 ⇒ `false`(「不是 URL」由别的门管,本条只判凭据位)。 */
-export declare function urlCarriesUserinfo(raw: string): boolean;
+/** 同族第二码(S-483 座⑨):这一位根本不是一个层级式绝对 URL。三根键共用一码,与上面那只同纪律
+ *  (码按**规则**命名,不按键名 —— 键名已经逐字在拒因文案里点过了)。 */
+export declare const MODEL_ROUTE_URL_INVALID_CODE = "config.model_route_url_invalid";
 /**
- * 模型路由 base URL 的拒因(`undefined` = 这一位合法)。
+ * 模型路由 base URL 的拒因(`undefined` = 这一位合法)—— **这三根键的唯一判官**。
+ *
+ * 两臂,顺序即语义,**两臂都经 display-safe 铸点**:
+ *  ① **不是一个层级式绝对 URL** ⇒ `config.model_route_url_invalid`;
+ *  ② 是,但带 userinfo ⇒ `config.gateway_url_userinfo`。
+ *
+ * 🔴 ① 为什么必须在这里、而不是「由别的门管」(S-483 座⑨,与 ME/A2A 两座**同病镜像**):本函数此前先问
+ * 凭据位、并把「解析不动」读成**没有**凭据(`urlCarriesUserinfo` 的 `return false`),旁注写着「不是 URL 由
+ * 别的门管」—— 而 config 层对这三根**没有**那道门(`config.ts` 与 `config-invariants.ts` 只调本函数)。
+ * 于是半写 userinfo `http://user:pass@`(`URL.canParse` 假)与 `alice:pw@host:8000`(不透明 URL,
+ * `username`/`password` 恒空)两形被当「无凭据」放行,一路到 brain 装配期才由 core 拒;core 那一臂
+ * 今天不回显原值 —— 但**「恰好不漏」不是防线**,而且拒启点越晚,运维越读不出是哪根旋钮配错了。
+ * ⇒ 判据改成与铸点**同一只** {@link isHierarchicalUrl}:两处再也不可能各判各的。
+ *
+ * 🚧 **未闭环(不在本车射程)**:层级式但**非 http(s)** 的形(`ftp://h/v1`,不带 userinfo)今天仍放行 ——
+ * `fetch` 对它同样必然失败,但那是第三条臂、是一次新的行为面拒启,按三问另开车(S-483 收车档已登记)。
  *
  * 拒因四件齐:**码** + **哪个 env 键** + **洗过的 URL**(host/port/path 逐字,userinfo 与凭据参数成记号 ——
  * 运维要靠 host 认出是哪一条路由,而密码一个字节都不许进启动错误)+ **出路一句**(点名真实旋钮)。

package/dist/model-route-url.js

@@ -1,13 +1,18 @@
-import { buildDisplaySafeUrl } from "./trace/redact.js";
+import { buildDisplaySafeUrl, isHierarchicalUrl } from "./trace/redact.js";
 export const GATEWAY_URL_USERINFO_CODE = "config.gateway_url_userinfo";
-export function urlCarriesUserinfo(raw) {
-    if (raw === "" || !URL.canParse(raw))
-        return false;
-    const u = new URL(raw);
-    return u.username !== "" || u.password !== "";
-}
+export const MODEL_ROUTE_URL_INVALID_CODE = "config.model_route_url_invalid";
 export function modelRouteUrlRefusal(envKey, raw, credentialKnob) {
-    if (!urlCarriesUserinfo(raw))
+    if (raw === "")
+        return undefined;
+    if (!isHierarchicalUrl(raw)) {
+        return (`env ${envKey} is not a parseable absolute URL (${buildDisplaySafeUrl(raw)}) [${MODEL_ROUTE_URL_INVALID_CODE}] — ` +
+            "a model-route base URL is consumed by fetch, which requires an absolute hierarchical URL " +
+            "(scheme://host[:port][/path]); half-written forms like \"http://user:pass@\" and opaque forms like " +
+            "\"host:8000\" are not one, and they also hide any credentials they carry from every credential-position check. " +
+            `Set ${envKey} to a full scheme://host URL (and put the credential in ${credentialKnob}, never in the URL).`);
+    }
+    const u = new URL(raw);
+    if (u.username === "" && u.password === "")
         return undefined;
     return (`env ${envKey} carries credentials in the URL userinfo (${buildDisplaySafeUrl(raw)}) [${GATEWAY_URL_USERINFO_CODE}] — ` +
         "WHATWG forbids constructing a fetch Request from a URL with credentials, so EVERY model call on this route " +

package/dist/plugins/remote-env-adb.d.ts

@@ -84,6 +84,8 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
      *  同姿态的 ssh 腿早有先例(`remote-env-ssh.ts`「destroy 后一律不复活,显式 connect/reconnect 同禁」),
      *  五条兄弟腿全部 fail-closed,只有 adb 例外 —— 补齐它。 */
     private destroyed;
+    /** 在飞的那一次懒连接(单飞记忆)——见 {@link ensureConnected}。settle 即清,**不缓存败诺**。 */
+    private connectPromise?;
     /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
     readonly homeDir?: string | undefined;
     private readonly cfg;
@@ -99,6 +101,17 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /**
+     * 懒连接:**首次调用任一面**(exec / execStream / 文件面)时自动 `connect()`(含重试策略),在飞的
+     * 那一次由全部调用者共用,失败**不缓存**(下一次调用重新试),`destroyed` 是终态不复活。
+     *
+     * 🔴 为什么这条必须在 adapter 里:core 的 task/run 车道**没有任何人**替 adapter 调 `connect()` ——
+     * 工厂铸出 env 就直接用它的 exec/文件面(本仓亲核:`src/` 里对执行环境的 `.connect()` 只有 bench 与
+     * 生命周期面自己)。所以一条「设了未连闸、又不自连」的腿,它的每一次工具调用都被自家的闸挡回;
+     * 那不是 adb 特有语义,而是与 ssh([ref] 同一实红点)/ k8s / e2b / local-docker / device 不均匀。
+     * 未连时的错误文案因此从「call connect() first」(这条车道上没人能照做)换成**真试过之后**的拒因。
+     */
+    private ensureConnected;
     private connectOnce;
     suspendVM(_options?: VmLifecycleOptions): Promise<{
         ok: true;

package/dist/plugins/remote-env-adb.js

@@ -13,6 +13,12 @@ const unsupported = (op) => ({
     ok: false,
     error: new RemoteExecutionError("unsupported", `${op} is not supported on an ADB device (real hardware — not snapshotable; capabilities.suspendable=false)`),
 });
+function lazyConnectExecError(e) {
+    return e.code === "aborted" ? new ExecutionError("aborted", e.message, e) : new ExecutionError("shell_unavailable", `ADB lazy-connect failed: ${e.message}`, e);
+}
+function lazyConnectFileError(e, absPath) {
+    return e.code === "aborted" ? new FileError("aborted", e.message, absPath, e) : new FileError("unknown", `ADB lazy-connect failed: ${e.message}`, absPath, e);
+}
 const isTcp = (serial) => /:\d+$/.test(serial);
 export function isAdbTransportLost(stderr) {
     return /device offline|device '.*' not found|no devices\/emulators found|connection reset|protocol fault|device disconnected/i.test(stderr);
@@ -22,6 +28,7 @@ export class RemoteAdbExecutionEnv {
     cwd;
     connected = false;
     destroyed = false;
+    connectPromise;
     homeDir;
     cfg;
     spawnFn;
@@ -57,6 +64,25 @@ export class RemoteAdbExecutionEnv {
         const once = this.injectedConnectOnce ?? ((s) => this.connectOnce(s));
         return withRetry((_attempt) => once(config?.abortSignal), policy, { signal: config?.abortSignal });
     }
+    async ensureConnected() {
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "ADB env destroyed — no lazy reconnect after teardown") };
+        if (this.connected)
+            return { ok: true };
+        const started = this.connectPromise ?? this.connect();
+        this.connectPromise = started;
+        try {
+            const r = await started;
+            return r.ok ? { ok: true } : { ok: false, error: r.error };
+        }
+        catch (err) {
+            return { ok: false, error: new RemoteExecutionError("connect_failed", `adb lazy-connect threw: ${err instanceof Error ? err.message : String(err)}`) };
+        }
+        finally {
+            if (this.connectPromise === started)
+                this.connectPromise = undefined;
+        }
+    }
     async connectOnce(signal) {
         if (signal?.aborted)
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
@@ -121,8 +147,9 @@ export class RemoteAdbExecutionEnv {
         return this.destroy();
     }
     async exec(command, options) {
-        if (!this.connected)
-            return { ok: false, error: new ExecutionError("shell_unavailable", "ADB device not connected — call connect() first") };
+        const ready = await this.ensureConnected();
+        if (!ready.ok)
+            return { ok: false, error: lazyConnectExecError(ready.error) };
         const wrapped = this.withCwdEnv(command, options?.cwd, options?.env);
         const r = await this.adb(this.deviceShellArgs(wrapped), {
             signal: options?.abortSignal,
@@ -139,8 +166,11 @@ export class RemoteAdbExecutionEnv {
         return ok(r.value);
     }
     async *execStream(command, options) {
-        if (!this.connected)
-            throw new RemoteExecutionError("connect_failed", "ADB device not connected — call connect() first");
+        const ready = await this.ensureConnected();
+        if (!ready.ok)
+            throw ready.error;
+        if (this.destroyed)
+            throw new RemoteExecutionError("connect_failed", "execution env already destroyed");
         const wrapped = this.withCwdEnv(command, options?.cwd, options?.env);
         const child = this.spawnFn(this.cfg.adbPath, this.deviceShellArgs(wrapped), { stdio: ["ignore", "pipe", "pipe"] });
         const queue = [];
@@ -255,15 +285,16 @@ export class RemoteAdbExecutionEnv {
     async joinPath(parts) {
         return ok(path.posix.join(...parts));
     }
-    fsGate(p) {
+    async fsGate(p) {
         if (this.destroyed)
             return { ok: false, error: new FileError("unknown", "execution env already destroyed", this.resolve(p)) };
-        if (!this.connected)
-            return { ok: false, error: new FileError("unknown", "ADB device not connected — call connect() first", this.resolve(p)) };
+        const ready = await this.ensureConnected();
+        if (!ready.ok)
+            return { ok: false, error: lazyConnectFileError(ready.error, this.resolve(p)) };
         return undefined;
     }
     async readBinaryFile(p, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -290,7 +321,7 @@ export class RemoteAdbExecutionEnv {
         return ok(lines);
     }
     async writeFile(p, content, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -379,6 +410,8 @@ export class RemoteAdbExecutionEnv {
         return this.posixFs.createTempFile(options);
     }
     adb(args, opts) {
+        if (this.destroyed)
+            return Promise.resolve({ ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") });
         return new Promise((resolve) => {
             let settled = false;
             let forceSettleTimer;

package/dist/plugins/remote-env-device.d.ts

@@ -118,6 +118,8 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
     writeFileExclusive?: (path: string, content: string | Uint8Array, abortSignal?: AbortSignal) => Promise<Result<void, FileError>>;
     writeFileGuarded?: (path: string, content: string | Uint8Array, expect: WriteExpectation, abortSignal?: AbortSignal) => Promise<Result<WriteReceipt, FileError>>;
     private connected;
+    /** 在飞的那一次准入(单飞记忆)——见 {@link admitShared}。settle 即清,**不缓存败诺**。 */
+    private connectPromise?;
     /** 拆除是**终态**(六条兄弟腿同纪律:destroy 之后 connect/exec/读面一律 fail-closed,不复活)。 */
     private destroyed;
     constructor(cfg: DeviceEnvConfig);
@@ -154,7 +156,8 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
     joinPath(parts: string[]): Promise<Result<string, FileError>>;
     workspaceHandle(): WorkspaceHandle;
     /**
-     * 不建连接:做**准入 + 取活连接**(文件头「唯一范式差」)。
+     * 不建连接:做**准入 + 取活连接**(文件头「唯一范式差」)。**显式**入口 —— 首次调用任一面时
+     * {@link ensureConnected} 会自动走同一条路(单飞共享),所以这里重复调用是幂等的。
      *
      * 🔴 **绝不换设备**:准入解出的 deviceId 与本 env 铸造时钉住的那一台不符 ⇒ typed
      * `device.identity_mismatch`(lane 是身份不是偏好,§4.5 步 2)。这一格正是 park 赎回期换绑/吊销的
@@ -167,6 +170,27 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /**
+     * 准入的**单飞**入口:在飞的那一次由全部等待者共用(显式 `connect()` 与任意面的懒连接共享同一次),
+     * settle 后记忆即清 —— 成功由 `connected` 位挡住重入,失败让下一次调用重新试(**不缓存败诺**,
+     * 与 k8s/ssh/e2b 三腿逐字同纪律)。
+     */
+    private admitShared;
+    /**
+     * 懒连接:**首次调用任一面**(exec / execStream / 文件面)时自动走一次准入。
+     *
+     * 🔴 为什么这条必须在 adapter 里(而不是「谁用谁先 connect」):task/run 车道**没有任何人**会替
+     * adapter 调 `connect()` —— 工厂铸出 env 就直接用它的 exec/文件面(本仓亲核:`src/` 里对执行环境的
+     * `.connect()` 只有 bench 与生命周期面自己)。所以一条「设了未连闸、又不自连」的腿,它的每一次工具
+     * 调用都被自家的闸挡回,而设备侧一条指令帧都收不到。e2b(首用建 VM)/ k8s(`connectPromise ??=`)/
+     * ssh(single-flight join)/ local-docker 四腿早就是懒连接;本腿从此同形,`connect()` 的语义
+     * (准入 + 取活连接 + 保护面对拍)一个字不动,只是触发时机与兄弟一致。
+     *
+     * 返回 `undefined` = 可以往下走;否则是**三币种**的失败行,由调用面翻成自己那种货币。
+     */
+    private ensureConnected;
+    /** `connect()` 的**本体**(准入 + 身份等值 + 保护面对拍)。失败以三币种形返回,见 {@link DeviceAdmissionFailure}。 */
+    private admit;
     /** 控制面重连(core 在 transport 重挂时调)——语义与 connect 逐字同一条:重新准入 + 身份等值。 */
     reconnect(_sessionToken: SessionToken): Promise<{
         ok: true;
@@ -203,11 +227,23 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
      */
     destroy(): Promise<void>;
     cleanup(): Promise<void>;
-    /** 终态/未连接的 fail-closed 门(exec 面)。 */
+    /**
+     * 终态 fail-closed + **懒连接**门(exec 面)。未连 ⇒ 先走一次准入,失败按 exec 货币报**准入自己的**
+     * 拒因(不再吐一句「call connect() first」—— 这条车道上没有任何人能照做)。
+     */
     private shellGate;
-    /** 终态/未连接的 fail-closed 门(文件面)。 */
+    /** 终态 fail-closed + **懒连接**门(文件面)。语义与 {@link shellGate} 逐字同一条,只换货币。 */
     private fsGate;
     private timeoutMsFor;
+    /**
+     * 投递漏斗。**终态复核就在这里**,不在门上(codex 对抗复审 r1 [high],判真后收)。
+     *
+     * 🔴 为什么门上那一次不够:门是 `async`,所以调用方从门返回到这里之间**让出过执行权** —— 一次
+     * `destroy()` 可以整个跑完再让调用方恢复,于是门读到的「未拆除」在投递那一刻已经过期(懒连接把门
+     * 变成异步的那一刻就开了这个窗;`connected` 快路径也一样让出)。本函数的函数体到 `hub.dispatch(input)`
+     * 之间**没有任何 await**,所以它是投递前最后一个同步点 —— 闸要放在真正不可回退的那一格上。
+     * 三个面各自把这一态翻成自己的货币(穷举 switch,加臂 = 编译红)。
+     */
     private dispatch;
     /**
      * 三态结果 → 文件面的 `Result`。

package/dist/plugins/remote-env-device.js

@@ -99,6 +99,17 @@ const DEVICE_REJECT_TO_REMOTE_ERROR = {
 function rejectText(reject) {
     return `[${reject.code}] ${reject.message}`;
 }
+const ENV_TERMINAL = { kind: "env_terminal" };
+const ENV_TERMINAL_MESSAGE = "execution env already destroyed";
+function failureFor(code, message) {
+    return { remote: DEVICE_REJECT_TO_REMOTE_ERROR[code], exec: DEVICE_REJECT_TO_EXEC_ERROR[code], file: DEVICE_REJECT_TO_FILE_ERROR[code], message };
+}
+const ADMISSION_DESTROYED = {
+    remote: "connect_failed",
+    exec: "shell_unavailable",
+    file: "unknown",
+    message: "execution env already destroyed",
+};
 function assertPosixDevicePlatform(os, deviceId) {
     switch (os) {
         case "darwin":
@@ -118,6 +129,7 @@ export class RemoteDeviceExecutionEnv {
     writeFileExclusive;
     writeFileGuarded;
     connected = false;
+    connectPromise;
     destroyed = false;
     constructor(cfg) {
         this.cfg = cfg;
@@ -172,18 +184,61 @@ export class RemoteDeviceExecutionEnv {
         };
     }
     async connect(config) {
-        if (this.destroyed)
-            return { ok: false, error: new RemoteExecutionError("connect_failed", "device env destroyed — create a fresh env instead of reviving") };
         if (config?.abortSignal?.aborted === true)
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
-        const admitted = await this.cfg.enrollment.admitSession({ rootSessionId: this.cfg.rootSessionId, requester: this.cfg.owner });
+        const admitted = await this.admitShared();
+        if (admitted.ok)
+            return ok(admitted.value);
+        return { ok: false, error: new RemoteExecutionError(admitted.failure.remote, admitted.failure.message) };
+    }
+    async admitShared() {
+        const inflight = this.connectPromise;
+        if (inflight !== undefined)
+            return inflight;
+        const started = this.admit();
+        this.connectPromise = started;
+        try {
+            return await started;
+        }
+        finally {
+            if (this.connectPromise === started)
+                this.connectPromise = undefined;
+        }
+    }
+    async ensureConnected() {
+        if (this.destroyed)
+            return ADMISSION_DESTROYED;
+        if (this.connected)
+            return undefined;
+        const admitted = await this.admitShared();
+        return admitted.ok ? undefined : admitted.failure;
+    }
+    async admit() {
+        if (this.destroyed) {
+            return { ok: false, failure: { ...ADMISSION_DESTROYED, message: "device env destroyed — create a fresh env instead of reviving" } };
+        }
+        let admitted;
+        try {
+            admitted = await this.cfg.enrollment.admitSession({ rootSessionId: this.cfg.rootSessionId, requester: this.cfg.owner });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                failure: {
+                    remote: "connect_failed",
+                    exec: "target_unavailable",
+                    file: "transport_lost",
+                    message: `[device.admission_unavailable] the device admission read failed, so this session's device could not be confirmed (fail-closed): ${err instanceof Error ? err.message : String(err)}`,
+                },
+            };
+        }
         if (!admitted.ok) {
-            return { ok: false, error: new RemoteExecutionError(DEVICE_REJECT_TO_REMOTE_ERROR[admitted.reject.code], rejectText(admitted.reject)) };
+            return { ok: false, failure: failureFor(admitted.reject.code, rejectText(admitted.reject)) };
         }
         if (admitted.value.deviceId !== this.cfg.deviceId) {
             return {
                 ok: false,
-                error: new RemoteExecutionError("auth_failed", `[${DEVICE_ERROR_CODES.IDENTITY_MISMATCH}] this session is now bound to a different device (${admitted.value.deviceId}) than the one this environment was minted for — refusing to silently re-target; re-initiate the work on the currently bound device (device lane identity, v2 §4.5/§3)`),
+                failure: failureFor("device.identity_mismatch", `[${DEVICE_ERROR_CODES.IDENTITY_MISMATCH}] this session is now bound to a different device (${admitted.value.deviceId}) than the one this environment was minted for — refusing to silently re-target; re-initiate the work on the currently bound device (device lane identity, v2 §4.5/§3)`),
             };
         }
         {
@@ -191,12 +246,20 @@ export class RemoteDeviceExecutionEnv {
             if (gained.length > 0) {
                 return {
                     ok: false,
-                    error: new RemoteExecutionError("connect_failed", `[device.capability_drift] this environment was minted while the device's protective write primitives (${gained.join(", ")}) were not observable, ` +
-                        "so they are absent from its filesystem face — core would read that absence as \"the backend has no such primitive\" and fall back to a NON-atomic write, " +
-                        "silently re-opening the TOCTOU window guarded writes exist to close (#157). Refusing this connect; the per-task factory will mint a correctly-shaped env on retry."),
+                    failure: {
+                        remote: "connect_failed",
+                        exec: "shell_unavailable",
+                        file: "not_supported",
+                        message: `[device.capability_drift] this environment was minted while the device's protective write primitives (${gained.join(", ")}) were not observable, ` +
+                            "so they are absent from its filesystem face — core would read that absence as \"the backend has no such primitive\" and fall back to a NON-atomic write, " +
+                            "silently re-opening the TOCTOU window guarded writes exist to close (#157). Refusing this connect; the per-task factory will mint a correctly-shaped env on retry.",
+                    },
                 };
             }
         }
+        if (this.destroyed) {
+            return { ok: false, failure: { ...ADMISSION_DESTROYED, message: "device env destroyed while admitting — create a fresh env instead of reviving" } };
+        }
         this.connected = true;
         return ok(this.workspaceHandle());
     }
@@ -226,24 +289,28 @@ export class RemoteDeviceExecutionEnv {
     async cleanup() {
         return this.destroy();
     }
-    shellGate() {
+    async shellGate() {
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
-        if (!this.connected)
-            return { ok: false, error: new ExecutionError("shell_unavailable", "device env not connected — call connect() first") };
+        const failure = await this.ensureConnected();
+        if (failure)
+            return { ok: false, error: new ExecutionError(failure.exec, failure.message) };
         return undefined;
     }
-    fsGate(p) {
+    async fsGate(p) {
         if (this.destroyed)
             return { ok: false, error: new FileError("unknown", "execution env already destroyed", this.resolve(p)) };
-        if (!this.connected)
-            return { ok: false, error: new FileError("unknown", "device env not connected — call connect() first", this.resolve(p)) };
+        const failure = await this.ensureConnected();
+        if (failure)
+            return { ok: false, error: new FileError(failure.file, failure.message, this.resolve(p)) };
         return undefined;
     }
     timeoutMsFor(seconds) {
         return seconds != null && Number.isFinite(seconds) && seconds > 0 ? Math.ceil(seconds * 1000) : this.cfg.execTimeoutMs;
     }
     dispatch(kind, args, opts) {
+        if (this.destroyed)
+            return Promise.resolve(ENV_TERMINAL);
         const input = {
             rootSessionId: this.cfg.rootSessionId,
             requester: this.cfg.owner,
@@ -262,6 +329,8 @@ export class RemoteDeviceExecutionEnv {
     }
     fileOutcome(res, absPath, take) {
         switch (res.kind) {
+            case "env_terminal":
+                return { ok: false, error: new FileError("unknown", ENV_TERMINAL_MESSAGE, absPath) };
             case "rejected":
                 return { ok: false, error: new FileError(DEVICE_REJECT_TO_FILE_ERROR[res.reject.code], rejectText(res.reject), absPath) };
             case "never_started":
@@ -277,7 +346,7 @@ export class RemoteDeviceExecutionEnv {
         return { ok: false, error: new FileError("unknown", `device returned a "${got}" outcome for an operation that requires "${want}" — protocol violation`, absPath) };
     }
     async exec(command, options) {
-        const gated = this.shellGate();
+        const gated = await this.shellGate();
         if (gated)
             return gated;
         let stdout = "";
@@ -301,6 +370,8 @@ export class RemoteDeviceExecutionEnv {
             },
         });
         switch (res.kind) {
+            case "env_terminal":
+                return { ok: false, error: new ExecutionError("shell_unavailable", ENV_TERMINAL_MESSAGE) };
             case "rejected":
                 return { ok: false, error: new ExecutionError(DEVICE_REJECT_TO_EXEC_ERROR[res.reject.code], rejectText(res.reject)) };
             case "never_started":
@@ -321,8 +392,11 @@ export class RemoteDeviceExecutionEnv {
     async *execStream(command, options) {
         if (this.destroyed)
             throw new RemoteExecutionError("connect_failed", "execution env already destroyed");
-        if (!this.connected)
-            throw new RemoteExecutionError("connect_failed", "device env not connected — call connect() first");
+        {
+            const failure = await this.ensureConnected();
+            if (failure)
+                throw new RemoteExecutionError(failure.remote, failure.message);
+        }
         const queue = [];
         let queuedBytes = 0;
         let done = false;
@@ -434,7 +508,7 @@ export class RemoteDeviceExecutionEnv {
         }
     }
     async exists(p, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -448,7 +522,7 @@ export class RemoteDeviceExecutionEnv {
         });
     }
     async canonicalPath(p, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -462,7 +536,7 @@ export class RemoteDeviceExecutionEnv {
         });
     }
     async fileInfo(p, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -476,7 +550,7 @@ export class RemoteDeviceExecutionEnv {
         });
     }
     async doReadLink(p, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -492,7 +566,7 @@ export class RemoteDeviceExecutionEnv {
         });
     }
     async readBinaryFile(p, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -508,7 +582,7 @@ export class RemoteDeviceExecutionEnv {
         return this.fileOutcome(res, abs, (o) => (o.kind === "read" ? ok(new Uint8Array(Buffer.concat(parts))) : this.wrongOutcome("read", o.kind, abs)));
     }
     async readTextFile(p, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -524,7 +598,7 @@ export class RemoteDeviceExecutionEnv {
         return this.fileOutcome(res, abs, (o) => (o.kind === "read" ? ok(Buffer.concat(parts).toString("utf8")) : this.wrongOutcome("read", o.kind, abs)));
     }
     async readTextLines(p, options) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -547,7 +621,7 @@ export class RemoteDeviceExecutionEnv {
         });
     }
     async listDir(p, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -567,7 +641,7 @@ export class RemoteDeviceExecutionEnv {
         return this.doWrite("appendFile", p, content, undefined, abortSignal);
     }
     async doWrite(kind, p, content, _unused, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -590,7 +664,7 @@ export class RemoteDeviceExecutionEnv {
         });
     }
     async doGuardedWrite(p, content, expect, abortSignal) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -615,7 +689,7 @@ export class RemoteDeviceExecutionEnv {
         return false;
     }
     async createDir(p, options) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -623,7 +697,7 @@ export class RemoteDeviceExecutionEnv {
         return this.fileOutcome(res, abs, (o) => (o.kind === "void" ? ok(undefined) : this.wrongOutcome("void", o.kind, abs)));
     }
     async remove(p, options) {
-        const gated = this.fsGate(p);
+        const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
@@ -631,14 +705,14 @@ export class RemoteDeviceExecutionEnv {
         return this.fileOutcome(res, abs, (o) => (o.kind === "void" ? ok(undefined) : this.wrongOutcome("void", o.kind, abs)));
     }
     async createTempDir(prefix = "tmp-", abortSignal) {
-        const gated = this.fsGate(this.cwd);
+        const gated = await this.fsGate(this.cwd);
         if (gated)
             return gated;
         const res = await this.dispatch("createTempDir", { prefix }, { timeoutMs: this.cfg.execTimeoutMs, ...(abortSignal === undefined ? {} : { signal: abortSignal }) });
         return this.fileOutcome(res, this.cwd, (o) => (o.kind === "write" ? ok(o.canonicalPath) : this.wrongOutcome("write", o.kind, this.cwd)));
     }
     async createTempFile(options) {
-        const gated = this.fsGate(this.cwd);
+        const gated = await this.fsGate(this.cwd);
         if (gated)
             return gated;
         const res = await this.dispatch("createTempFile", { ...(options?.prefix === undefined ? {} : { prefix: options.prefix }), ...(options?.suffix === undefined ? {} : { suffix: options.suffix }) }, { timeoutMs: this.cfg.execTimeoutMs, ...(options?.abortSignal === undefined ? {} : { signal: options.abortSignal }) });
@@ -666,6 +740,8 @@ function toWireExpectation(e) {
 }
 function streamFailure(res) {
     switch (res.kind) {
+        case "env_terminal":
+            return new RemoteExecutionError("connect_failed", ENV_TERMINAL_MESSAGE);
         case "rejected":
             return new RemoteExecutionError(DEVICE_REJECT_TO_REMOTE_ERROR[res.reject.code], rejectText(res.reject));
         case "never_started":

package/dist/trace/redact.d.ts

@@ -136,6 +136,26 @@ export declare function redactDeep(value: unknown): unknown;
  * owner-scoped, so this preview is only ever shown to the ask's own principal (or an operator inspecting it).
  */
 export declare function redactedPreview(value: unknown, cap?: number): string | null;
+/**
+ * **这一位是不是一个层级式绝对 URL**(有 authority 的那一族)—— 本铸点与**模型路由三键拒启**
+ * (`model-route-url.ts` 第一臂)共用的**同一只**判据:两处曾各判各的,而 `URL.canParse` 单独为真的
+ * **不透明** URL 恰好是「凭据位看不见」的那一形。
+ *
+ * ⚠️ **射程如实**(车JC 复审去幻觉轮:此处原文写的是「本仓唯一判据」,亲读证伪)—— 仓里另有两处仍用
+ * 裸 `URL.canParse` 回答同一个问题,且**刻意不在本批射程内**(改它们各是一次新的行为面拒启,按三问另开车):
+ *  · `config.ts` 的 `GIT_API_BASEURL`(`parseGitApiKind`):无协议闸 ⇒ 不透明形今天过门(拒因经本铸点,
+ *    所以不回显凭据;可用性由 `fetch` 那侧决定);
+ *  · `config-catalog.ts` 的 `stripUrlUserinfo`(url 型行的回显尺):不透明形 `href === 原串` ⇒ **原样回显**
+ *    (登记为未闭环 —— 它等 core `displayUrlOf` 落地后与 catalog wire 行为面一起改,表态制点名 web-admin)。
+ *
+ * 🔴 谓词写成 `URL.canParse` 而不是 try/catch:这一臂**不是兜底**(兜底才归静默降级那张表管),它是判据本身 ——
+ * 「不是一个层级式 URL」是一个可判的状态,用异常当控制流只会让它看起来像一次意外。
+ * 🔴 「解析得动」**不够**:`new URL("alice:hunter2@gw.internal:8000")` 是合法的**不透明** URL(`alice:` 当 scheme,
+ * 与 `mailto:` 同族)—— 它没有 authority,URL 律的锚(`scheme://`)对它不成立,`username`/`password` 恒空,
+ * 直接回原串就是密码明文(红先实测)。闸取「**层级式** URL」:`href` 以 `<protocol>//` 起头 ⇒ 有 authority
+ * ⇒ 三个凭据位都在律的射程内。
+ */
+export declare function isHierarchicalUrl(raw: string): boolean;
 /**
  * 🔴 **配置型 URL 上日志 / 诊断面的唯一 display-safe 铸点**(S-475 件B;`build*` = 返回纯数据的一只纯函数)。
  *

package/dist/trace/redact.js

@@ -1712,14 +1712,18 @@ export function redactedPreview(value, cap = 2000) {
     s = redactSecrets(s, { json: true });
     return s.length > cap ? `${s.slice(0, cap)}…[truncated]` : s;
 }
+export function isHierarchicalUrl(raw) {
+    if (!URL.canParse(raw))
+        return false;
+    const u = new URL(raw);
+    return u.href.startsWith(`${u.protocol}//`);
+}
 export function buildDisplaySafeUrl(raw) {
     if (raw === "")
         return "";
-    if (!URL.canParse(raw))
+    if (!isHierarchicalUrl(raw))
         return DISPLAY_SAFE_URL_TOKEN;
     const u = new URL(raw);
-    if (!u.href.startsWith(`${u.protocol}//`))
-        return DISPLAY_SAFE_URL_TOKEN;
     return redactSecrets(u.href);
 }
 //# sourceMappingURL=redact.js.map

package/docs/DEVICE-EXECUTOR-PROTOCOL.md

@@ -166,6 +166,29 @@ Sign with the device private key over exactly these bytes:
 Any deviation — a different tag, a missing length prefix, a differently-encoded epoch — makes **every**
 handshake fail with `auth_failed`, with no hint as to which half is wrong. Get this right first.
 
+#### `epoch` is a byte-exact key: exactly which strings are accepted
+
+`epoch` is a 26-character **upper-case** Crockford base32 ULID whose first character is `0`–`7`. Crockford's
+alphabet is case-insensitive on paper; this protocol is **not**, on purpose: the same `epoch` string is also the
+key the server compares when fencing connection generations and leases, so two spellings of one ULID would let
+one connection be counted as two. That is worse than a failed handshake, so the decoder stays strict.
+
+The two entry points reject differently — if you call the low-level decoder yourself, check for `null`:
+
+| Input | `decodeUlid16(...)` | `buildHelloSignaturePayload({ epoch })` |
+|---|---|---|
+| valid, e.g. `01J8ZQ4T9X7M3K5N6P8R0S2V4W` | 16 bytes | payload |
+| lower-case, e.g. `01j8zq4t9x…` | `null` | throws `Error: device-ws: epoch must be a 26-char Crockford ULID (got "…")` |
+| first character `8`, `9`, `A` … `Z` (128-bit overflow) | `null` | throws |
+| 25 characters (or 27) | `null` | throws |
+| contains an excluded letter `I`, `L`, `O`, `U` | `null` | throws |
+
+The discriminating case, if you want to prove your own decoder judges the right thing: a `Z` as the **last**
+character is accepted (it is just the value 31), while a `Z` as the **first** character is rejected (overflow).
+A decoder that rejects "any Z" is wrong. Remember that a bad signature is answered with `auth_failed` and nothing
+else — the server does not say which half was wrong — so run the vector below and these rejection cases against
+your implementation before the first live handshake.
+
 #### Importable source of truth and a fixed test vector
 
 You do not have to transcribe the byte layout. From `@sema-agent/server` 7.88.0 the executor-facing part of the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.88.1",
+  "version": "7.89.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -59,7 +59,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.23.4",
+    "@sema-agent/core": "7.23.5",
     "@sema-agent/settings-schema": "3.0.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",