@sema-agent/server 7.102.0 → 7.103.1

package/dist/outbound-dispatcher.d.ts

@@ -0,0 +1,125 @@
+/**
+ * S-776 —— server 进程出网的**唯一**一只 dispatcher:回环目标恒直连,其余按 `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`
+ * 交给 undici `EnvHttpProxyAgent`。**一只 dispatcher、一处安装、零旋钮** —— 代理变量本身就是配置通道。
+ *
+ * ── 病(test 黑盒追出,core 直讯 09-26)────────────────────────────────────────────────────────────
+ * Node 的内建 `fetch` 不读这三只变量(Node 24 起要另开 `NODE_USE_ENV_PROXY`)。于是只能经代理出网的部署上,引擎 → 网关这一跳、
+ * 以及 server 自己所有出网跳(中心拉取 / 公告 / 凭证续签 / WebSearch / 对象存储 …)一律直连 ⇒ 网关主机名只有代理解析得了时
+ * `ENOTFOUND`、代理零命中。
+ *
+ * ── 为什么一处安装就覆盖全部(读实现得出,不是从名字推断)─────────────────────────────────────────
+ *  · 本仓的出网 fetch 座默认都是**全局** `fetch`(`fetchImpl ?? fetch` / `fetchImpl: typeof fetch = fetch`),全局 fetch 每次请求
+ *    读 undici 的全局 dispatcher 槽;
+ *  · core 的引擎传输(`@sema-agent/core` 7.33.1 `dist/brain/transport.js` 的 `hostDispatcher` / `resolveFetch`)给每次请求带 `ENGINE_DISPATCHER`,它是宿主
+ *    全局 dispatcher 的透明替身 —— **每次请求**按 handler API 版本读 `globalThis[Symbol.for("undici.globalDispatcher.2")]` / `…1`,
+ *    除逐请求的头 / 体钟外一切转发 ⇒ 本仓装一只全局 dispatcher,引擎跳同样生效,**core 零改**;
+ *  · 槽位(车OY 实测,不臆断):npm undici 7.30.0 的 `setGlobalDispatcher` **两只槽同写**(`lib/global.js` 的 `setGlobalDispatcher` 两次 `defineProperty`),所以
+ *    **一次调用**就同时覆盖 Node 20 / 22(内嵌 undici 6.24.1,读槽 1)与 Node 24(内嵌 7.10.0 / 7.29.1,读槽 1)的内建 `fetch`,
+ *    以及 core 按 handler API 选槽的那一读 —— 不需要第二只槽的安装代码。实测表(内建 `fetch()` 是否命中):Node 20.20.2 / 22.22.3 /
+ *    24.2.0 / 24.21.0 全命中,内建 fetch 交来的 handler 在四个版本上都是 v1 形(`onConnect`/`onHeaders`…),undici 7 的
+ *    `DispatcherBase.dispatch` 自己 `UnwrapHandler.unwrap` 两形都收。
+ *  · 🔴 **Bun 例外**(镜像 `CMD ["bun", "run", "src/main.ts"]` 与 `bun build --compile` 两形):`import "undici"` 在 Bun 下解析到
+ *    Bun 自带的 undici 垫片 —— `setGlobalDispatcher` 只赋一个模块变量、两只槽都不写,Bun 的原生 `fetch` 也不读 dispatcher。
+ *    Bun 的原生 fetch **自己**读 `HTTP(S)_PROXY` / `NO_PROXY`(Bun 1.3.14 实测:代理、`NO_PROXY` 精确 / 后缀 / `*` 三形都认),
+ *    但**回环不豁免**(`127.0.0.1` / `localhost` 照送代理)。本模块在那里是惰性的:安装后探槽,槽里不是我们 ⇒ 如实报
+ *    `loopbackDirect:false`,配了代理时升 warn 并指路(见 {@link installOutboundDispatcher})。
+ *
+ * ── 回环恒直连(无条件规则;对 undici 缺省的**收窄**)─────────────────────────────────────────────
+ * `EnvHttpProxyAgent` 只按 `NO_PROXY` 判豁免,**没有回环隐式豁免**(undici 7.30.0 `lib/dispatcher/env-http-proxy-agent.js` 的 `#shouldProxy`:`NO_PROXY` 空 ⇒ 恒代理)
+ * ⇒ `HTTPS_PROXY` 设了而 `NO_PROXY` 没写 localhost 时,`127.0.0.1` 上的本机网关 / 本机中心会被送进代理 —— 代理够不到本进程的回环,
+ * 那是静默全断。所以回环目标在这里**先于** `NO_PROXY` 判、恒走直连 Agent;不看拓扑、不看客户端表态、没有旋钮(旋钮 = 让运维
+ * 能把本机流量送进公司代理,没有任何部署形需要它)。判据集与 sema-cli 1.0.136 `src/utils/proxy.ts:104` `isLoopbackHost`
+ * (壳 → 本机引擎那一跳的同形修 `LoopbackDirectDispatcher`,L-587)同一集,两段一致。
+ * **unix socket**:undici 的 `socketPath` 是连接器(`Agent` / `Client` 构造)选项,不是逐请求选项 ⇒ 打 unix socket 的调用必然自带
+ * dispatcher,**结构上**不经过全局槽 —— 本模块没有、也不需要一条 unix 臂。
+ *
+ * ── boot 冻结 ────────────────────────────────────────────────────────────────────────────────────
+ * 三只变量在构造时读**一次**(与本仓其余 env 同律)。`EnvHttpProxyAgent` 自己会在每次请求比对 `process.env.NO_PROXY` 并重读 ——
+ * 显式把 `noProxy`(以及两只代理)交给它就关掉那条运行期重读(`#noProxyChanged` 在 `opts.noProxy !== undefined` 时恒假)。
+ * 读法与 undici 读 `process.env` **逐字同序**:小写优先、`??`(空串算「设了」)、`HTTPS_PROXY` 缺席 / 空 ⇒ https 目标走 `HTTP_PROXY`
+ * (`EnvHttpProxyAgent` 构造器与 `#noProxyEnv`)—— 本模块读一次、再原样交给它,undici 不再读 env,读者只有这一处。
+ *
+ * ── 代理那一跳:失败可辨认 + 不许进重连风暴(test 复测义务 srv-s776-engine-proxy-recheck ④,板 [ref];opus 修复验证轮 F1 / F2)──
+ * 接缝 = `EnvHttpProxyAgent` 公开的 `clientFactory` 选项(类型面 `ProxyAgent.Options.clientFactory`,原样交给两只 `ProxyAgent`;交给
+ * 直连 `Agent` 的那份被它的 `deepClone`(JSON 往返)丢掉,不生效)—— 它造的是**连代理的那只客户端**,每一次代理拨号(TCP / TLS 到代理 +
+ * `CONNECT` 交换)都经它的 `connect`,不多不少。{@link ProxyDialPool} 在这里把两类结局收成一只错误 {@link OutboundProxyError}:
+ *  · 拨号失败(拒连 / 解析不了 / 超时 / 代理 TLS / 收下就关 …)⇒ 包成 `OutboundProxyError`(`cause` = 原错误);
+ *  · `CONNECT` 回非 200 ⇒ 关掉那条 socket(undici 自己也是这么做的),同样包成 `OutboundProxyError`(`cause` 说出状态码)。
+ * 🔴 **包装层不铸 `code`,这是承重的两件事**:① undici 客户端在连接阶段把 `UND_ERR_SOCKET` 当可恢复错误重连(`client.js` 的 `onError`),
+ *    而 `CONNECT` 恰在连接阶段 —— 代理收下 TCP 就关(Linux 上是 FIN ⇒ `UND_ERR_SOCKET`)时,裸 `ProxyAgent` / Node 24 `NODE_USE_ENV_PROXY`
+ *    都会重连死循环(修前实测 10 s 四五万条连接、请求挂到调用方超时、abort 之后仍在涨);无 code 的错误让排队的请求当场失败。
+ *    ② core 的连接失败分类(`classifyConnectFailure`)只看链上的 `code`,无 code 的一节对它透明 —— 重试 / 切备 / 断路器的判据不变。
+ * 修前读数(装了 dispatcher、未加归因;引擎终局句 = core `describeNetworkError` 原样):代理拒连 `[network] fetch failed (connect ECONNREFUSED
+ * 127.0.0.1:1)`;代理主机解析不了 `… (getaddrinfo ENOTFOUND proxy.s776.invalid)`;CONNECT 回 403 `… (Request was cancelled. ← UND_ERR_ABORTED:
+ * Proxy response (403) !== 200 when HTTP Tunneling)` —— 都不说「经代理」。修后:`… (via outbound proxy (from HTTPS_PROXY) ←
+ * connect ECONNREFUSED 127.0.0.1:1)`(message 不带代理地址 —— 主会话 F3 裁定,见 {@link OutboundProxyError})。core 的句子一字不改(它逐层展开 cause 链,包装层就是链上多一节)。隧道建好之后的失败(目标的 TLS、
+ * 目标的响应)不经这个接缝,不冠代理 —— 那是目标的事。
+ *
+ * ── 安全轴 ───────────────────────────────────────────────────────────────────────────────────────
+ * 代理 URL 的 userinfo 是凭据(undici 把它译成 `Proxy-Authorization: Basic …`)。它只进 dispatcher,不进任何观测面:姿态
+ * ({@link buildOutboundProxyPosture})、拒启句与归因句同一把尺 {@link displayProxyUrl}(形干净只出 `scheme//host[:port]`、过全仓那一只
+ * display-safe 铸点;形不干净整只占位);姿态只上启动日志一行
+ * `outbound_proxy`,不进 `/health`、不进公告、不进租户 wire(代理那一跳失败的终局句只说「经代理 + 哪只变量」,F3 裁定)。代理变量不可用(undici 构造即拒:无 scheme、`ftp:`、带路径 / 查询)⇒
+ * **拒启**(与 Node 24 `NODE_USE_ENV_PROXY=1` 遇坏值的行为同向)—— 静默直连 = 运维以为出网走了代理而实际没有,那是出网策略面的
+ * fail-open;拒因只回显 display-safe 值。
+ */
+import { Dispatcher } from "undici";
+import type { Logger } from "./observability/logger.js";
+/**
+ * 出网代理姿态(`build*`:纯数据)—— 启动日志 `outbound_proxy` 行与配置目录共读的**同一份**投影。
+ *  · `httpProxy` / `httpsProxy`:http: / https: 目标**实际**走的代理(display-safe;`null` = 直连)。`httpsProxy` 在 `HTTPS_PROXY`
+ *    缺席 / 空时回落 `HTTP_PROXY` —— undici 的读法,不是本仓的发明;
+ *  · `noProxy`:条目原样(按 undici 的切分:逗号或空白;`null` = 未设 / 空)。
+ */
+export interface OutboundProxyPosture {
+    readonly httpProxy: string | null;
+    readonly httpsProxy: string | null;
+    readonly noProxy: readonly string[] | null;
+}
+export declare function buildOutboundProxyPosture(env?: NodeJS.ProcessEnv): OutboundProxyPosture;
+/**
+ * 目标 origin 会不会落在**本机**(回环 / 未指定地址)。入参是 dispatch 的 `origin`(`string | URL`);解析不动 ⇒ `false`
+ * (按远端处置 = 交给代理那一半,与修前方向一致)。认哪几形(与 sema-cli 1.0.136 `isLoopbackHost` 同集):
+ *  · `localhost`(含 FQDN 尾点 `localhost.`);刻意**不**认 `*.localhost` 子域(能否落到本机取决于系统解析器,不是地址本身的事实);
+ *  · IPv4 `127.0.0.0/8` 整段(WHATWG URL 先把 `127.1` / `0x7f.1` 这类写法规范成点分四段);
+ *  · IPv6 `::1`、IPv4 映射段 `::ffff:127.x.x.x`(URL 规范成 `::ffff:7fxx:xxxx` 形);
+ *  · 未指定地址 `0.0.0.0` / `::`(及映射形):作为目的地址它在本机就是「本机」,送进代理只会让代理去连它自己。
+ */
+export declare function isLoopbackOrigin(origin: string | URL | undefined): boolean;
+/**
+ * 代理那一跳失败的**唯一**错误形(`cause` = 原错误;**不铸 `code`**,理由见顶注)。`proxy` = display-safe 代理地址,`from` = 哪只变量给的。
+ * 🔴 **message 不带地址**(主会话 F3 裁定,09-26):这句经 core 的终局句进租户可见的失败原因;地址是基础设施细节,只点明「经代理 + 哪只变量」,
+ * 一条规则、不按姿态分叉。地址留在 `proxy` 属性上供进程内日志腿取;单用户运维在启动日志 `outbound_proxy` 行里有同一串可对照。根因那一节是
+ * undici 自己的错误原文(拒连 / 解析不了两形会点名代理的 host:port,与直连失败点名目标同形),本仓不改写上游错误。
+ * 字符串化(`String(err)`)带出根因:只打第一层 cause 的日志腿(如 hook 的 `String(cause)`)也读得到 `ECONNREFUSED` 这类根因;
+ * core 的 `describeNetworkError` 读的是 `.message`,不受影响、不重复。
+ */
+export declare class OutboundProxyError extends Error {
+    readonly proxy: string;
+    readonly from: string;
+    readonly name = "OutboundProxyError";
+    constructor(proxy: string, from: string, cause: unknown);
+    toString(): string;
+}
+/** 代理变量不可用的拒启码(拼法随 `config.*` 家族,出现在拒句方括号里)。 */
+export declare const OUTBOUND_PROXY_INVALID_CODE = "config.outbound_proxy_invalid";
+/**
+ * 构造(`create*`:活对象)。代理变量不可用(undici 构造即拒)⇒ **抛**,拒因点名变量、只回显 {@link displayProxyUrl} 的形
+ * (undici 自己的错误文案不转述:`ERR_INVALID_URL` 把原值挂在 `input` 上,转述即泄漏的一条路)。
+ */
+export declare function createOutboundDispatcher(env?: NodeJS.ProcessEnv): {
+    dispatcher: Dispatcher;
+    posture: OutboundProxyPosture;
+};
+/** 安装结果 = 姿态 + 这条规则在本进程**是否生效**(运行时的 fetch 读不读 undici 全局槽 —— Node 读、Bun 不读)。 */
+export interface OutboundDispatcherInstall extends OutboundProxyPosture {
+    readonly loopbackDirect: boolean;
+}
+/**
+ * 进程级安装(**幂等**:第二次调用原样返回第一次的结果,不再装)。唯二调用点:HTTP 服务的 `boot/stage-01-config.ts` 末尾
+ * (config 已载、任何出网之前)与一次性 CLI `run-local.ts` 的同一位置(它不经 stage-01)。
+ */
+export declare function installOutboundDispatcher(logger: Logger, env?: NodeJS.ProcessEnv): OutboundDispatcherInstall;
+/** 测试专用:撤回安装(槽还给装之前的那只,本只关掉),下一次 {@link installOutboundDispatcher} 重新读 env。 */
+export declare function resetOutboundDispatcherForTest(): void;
+//# sourceMappingURL=outbound-dispatcher.d.ts.map

package/dist/outbound-dispatcher.js

@@ -0,0 +1,211 @@
+import { Agent, Dispatcher, EnvHttpProxyAgent, getGlobalDispatcher, Pool, setGlobalDispatcher } from "undici";
+import { isIP } from "node:net";
+import { buildDisplaySafeUrl, DISPLAY_SAFE_URL_TOKEN } from "./trace/redact.js";
+function readOutboundProxyEnv(env = process.env) {
+    return {
+        httpProxy: env.http_proxy ?? env.HTTP_PROXY ?? "",
+        httpsProxy: env.https_proxy ?? env.HTTPS_PROXY ?? "",
+        noProxy: env.no_proxy ?? env.NO_PROXY ?? "",
+    };
+}
+function isCleanProxyUrl(raw) {
+    return /^[a-z][a-z0-9+.-]*:\/\/[^/?#\\]+\/?$/i.test(raw) && URL.canParse(raw) && new URL(raw).host !== "";
+}
+function displayProxyUrl(raw) {
+    if (!isCleanProxyUrl(raw))
+        return DISPLAY_SAFE_URL_TOKEN;
+    const u = new URL(raw);
+    return buildDisplaySafeUrl(`${u.protocol}//${u.host}`);
+}
+function postureOf(v) {
+    const shown = (raw) => (raw === "" ? null : displayProxyUrl(raw));
+    const entries = v.noProxy.split(/[,\s]/).filter((e) => e !== "");
+    return { httpProxy: shown(v.httpProxy), httpsProxy: shown(v.httpsProxy || v.httpProxy), noProxy: entries.length > 0 ? entries : null };
+}
+export function buildOutboundProxyPosture(env = process.env) {
+    return postureOf(readOutboundProxyEnv(env));
+}
+export function isLoopbackOrigin(origin) {
+    if (origin === undefined)
+        return false;
+    const text = String(origin);
+    if (!URL.canParse(text))
+        return false;
+    let host = new URL(text).hostname.toLowerCase();
+    if (host.startsWith("[") && host.endsWith("]"))
+        host = host.slice(1, -1);
+    host = host.replace(/\.+$/, "");
+    if (host === "localhost")
+        return true;
+    const family = isIP(host);
+    if (family === 4)
+        return host.startsWith("127.") || host === "0.0.0.0";
+    if (family !== 6)
+        return false;
+    if (host === "::1" || host === "::")
+        return true;
+    const mapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+    if (mapped === null)
+        return false;
+    const hi = Number.parseInt(mapped[1], 16);
+    const lo = Number.parseInt(mapped[2], 16);
+    return hi >> 8 === 127 || (hi === 0 && lo === 0);
+}
+class OutboundDispatcher extends Dispatcher {
+    direct;
+    proxied;
+    constructor(direct, proxied) {
+        super();
+        this.direct = direct;
+        this.proxied = proxied;
+    }
+    dispatch(options, handler) {
+        return (isLoopbackOrigin(options.origin) ? this.direct : this.proxied).dispatch(options, handler);
+    }
+    close(callback) {
+        const done = Promise.all([this.direct.close(), this.proxied.close()]).then(() => undefined);
+        if (callback === undefined)
+            return done;
+        void done.then(callback, callback);
+    }
+    destroy(errOrCallback, callback) {
+        const cb = typeof errOrCallback === "function" ? errOrCallback : callback;
+        const err = typeof errOrCallback === "function" ? null : (errOrCallback ?? null);
+        const done = Promise.all([this.direct.destroy(err), this.proxied.destroy(err)]).then(() => undefined);
+        if (cb === undefined)
+            return done;
+        void done.then(cb, cb);
+    }
+}
+export class OutboundProxyError extends Error {
+    proxy;
+    from;
+    name = "OutboundProxyError";
+    constructor(proxy, from, cause) {
+        super(`via outbound proxy (from ${from})`, { cause });
+        this.proxy = proxy;
+        this.from = from;
+    }
+    toString() {
+        let root = this.cause;
+        for (let depth = 0; root instanceof Error && root.cause instanceof Error && depth < 4; depth++)
+            root = root.cause;
+        return `${this.name}: ${this.message} ← ${root instanceof Error ? root.message : String(root)}`;
+    }
+}
+const PROXY_CONNECT_DEADLINE_MS = 10_000;
+const dialDeadlines = new WeakMap();
+function clearDialDeadline(socket) {
+    clearTimeout(dialDeadlines.get(socket));
+    dialDeadlines.delete(socket);
+}
+class ProxyDialPool extends Pool {
+    shown;
+    from;
+    constructor(origin, options, shown, from) {
+        super(origin, options);
+        this.shown = shown;
+        this.from = from;
+    }
+    connect(options, callback) {
+        if (callback === undefined) {
+            return super.connect(options).then((data) => {
+                const refused = this.refusal(data);
+                if (refused !== undefined)
+                    throw refused;
+                return data;
+            }, (err) => {
+                throw new OutboundProxyError(this.shown, this.from, err);
+            });
+        }
+        super.connect(options, (err, data) => callback(err !== null ? new OutboundProxyError(this.shown, this.from, err) : (this.refusal(data) ?? null), data));
+    }
+    refusal(data) {
+        clearDialDeadline(data.socket);
+        if (data.statusCode === 200)
+            return undefined;
+        data.socket.on("error", () => undefined).destroy();
+        return new OutboundProxyError(this.shown, this.from, new Error(`proxy answered CONNECT with HTTP ${String(data.statusCode)}`));
+    }
+}
+function withDialDeadline(options) {
+    const inner = Reflect.get(options, "connect");
+    if (typeof inner !== "function")
+        return { ...options };
+    const connect = (opts, callback) => {
+        const expiresAt = performance.now() + PROXY_CONNECT_DEADLINE_MS;
+        Reflect.apply(inner, undefined, [
+            opts,
+            (err, socket) => {
+                if (err === null && socket !== null) {
+                    const expire = () => void socket.destroy(new Error(`proxy did not answer CONNECT within ${String(PROXY_CONNECT_DEADLINE_MS)} ms`));
+                    dialDeadlines.set(socket, setTimeout(expire, Math.max(0, expiresAt - performance.now())));
+                    socket.once("close", () => clearDialDeadline(socket));
+                    callback(null, socket);
+                }
+                else
+                    callback(err ?? new Error("proxy connector returned neither a socket nor an error"), null);
+            },
+        ]);
+    };
+    return { ...options, connect };
+}
+function createProxyClientFactory(v) {
+    const vars = [["HTTP_PROXY", v.httpProxy], ["HTTPS_PROXY", v.httpsProxy]].filter(([, raw]) => raw !== "" && URL.canParse(raw));
+    return (origin, options) => {
+        const same = vars.filter(([, raw]) => new URL(raw).href === origin.href);
+        const raw = same[0]?.[1] ?? origin.href;
+        return new ProxyDialPool(origin, withDialDeadline(options), displayProxyUrl(raw), same.length > 0 ? same.map(([name]) => name).join("/") : "proxy variable");
+    };
+}
+export const OUTBOUND_PROXY_INVALID_CODE = "config.outbound_proxy_invalid";
+export function createOutboundDispatcher(env = process.env) {
+    const v = readOutboundProxyEnv(env);
+    const shown = (name, raw) => `${name}=${raw === "" ? "(unset)" : `"${displayProxyUrl(raw)}"`}`;
+    const refuse = (code) => new Error(`[${OUTBOUND_PROXY_INVALID_CODE}] the outbound proxy variables are not usable by the HTTP transport (${code}): ${shown("HTTP_PROXY/http_proxy", v.httpProxy)}, ${shown("HTTPS_PROXY/https_proxy", v.httpsProxy)} — ` +
+        `write the proxy as a full URL (http://host:port or https://host:port; userinfo allowed, no path or query), or unset it for this process`);
+    if ([v.httpProxy, v.httpsProxy].some((raw) => raw.includes("://") && !isCleanProxyUrl(raw)))
+        throw refuse("ambiguous-url");
+    let proxied;
+    try {
+        proxied = new EnvHttpProxyAgent({ httpProxy: v.httpProxy, httpsProxy: v.httpsProxy, noProxy: v.noProxy, clientFactory: createProxyClientFactory(v) });
+    }
+    catch (err) {
+        throw refuse(err instanceof Error && "code" in err && typeof err.code === "string" ? err.code : "invalid");
+    }
+    return { dispatcher: new OutboundDispatcher(new Agent(), proxied), posture: postureOf(v) };
+}
+const GLOBAL_DISPATCHER_SLOTS = [Symbol.for("undici.globalDispatcher.1"), Symbol.for("undici.globalDispatcher.2")];
+let installed;
+export function installOutboundDispatcher(logger, env = process.env) {
+    if (installed !== undefined)
+        return installed.result;
+    const prior = getGlobalDispatcher();
+    const { dispatcher, posture } = createOutboundDispatcher(env);
+    setGlobalDispatcher(dispatcher);
+    const loopbackDirect = GLOBAL_DISPATCHER_SLOTS.every((slot) => Reflect.get(globalThis, slot) === dispatcher);
+    const result = { ...posture, loopbackDirect };
+    const runtime = process.versions.bun !== undefined ? `bun ${process.versions.bun}` : `node ${process.versions.node}`;
+    if (!loopbackDirect && (posture.httpProxy !== null || posture.httpsProxy !== null)) {
+        logger.warn("outbound_proxy", {
+            ...result,
+            runtime,
+            note: "this runtime's fetch does not read the undici global dispatcher: it applies HTTP(S)_PROXY / NO_PROXY itself and does NOT exempt loopback targets — list localhost,127.0.0.1,::1 in NO_PROXY so local gateways / centers are not sent to the proxy",
+        });
+    }
+    else {
+        logger.info("outbound_proxy", { ...result, runtime });
+    }
+    installed = { dispatcher, prior, result };
+    return result;
+}
+export function resetOutboundDispatcherForTest() {
+    if (installed === undefined)
+        return;
+    const { dispatcher, prior } = installed;
+    installed = undefined;
+    if (prior !== undefined)
+        setGlobalDispatcher(prior);
+    void dispatcher.close().catch(() => undefined);
+}
+//# sourceMappingURL=outbound-dispatcher.js.map

package/dist/plugins/host-platform.d.ts

@@ -59,13 +59,18 @@ export declare function spawnGroupOptions(): {
  * INCLUDING the throw on a dead group (ESRCH): every call site already wraps in its own try/catch with its own
  * fallback (e.g. `child.kill("SIGKILL")`), and that structure must not change.
  * win32 = core `signalProcessTree(pid,"SIGKILL")` → `taskkill /F /T` (never throws — fire-and-forget spawn).
+ * 不返回「落地」证据(S-769 车PA):POSIX 组信号「任一成员收到即成功」,返回成功证明不了组里没有打不着的活成员 —— 这一枪之后
+ * 「这个组还在不在」只由观察回答(同步硬收座 {@link hardKillGroupNow} 的 ESRCH、node 收割组长),不由这里推断。
  */
 export declare function killTreeHard(pid: number): void;
 /**
  * S-745(core 7.32.0 #1107)—— **同步组硬收的一枪**:后台 driver 的 `killBackgroundNow` 座位用它(梯子的「组 SIGKILL」那一级,
  * 不经 TERM、不挂定时器)。读数是 core 座位闭集里的三词,判据只看 `kill` 系统调用自己的结局:
  *  · POSIX:`kill(-pid, SIGKILL)` 落地 ⇒ `killed`;`ESRCH`(这个组已经没有进程)⇒ `already_gone`;其余拒因(`EPERM` 一族)⇒
- *    `no_pgid`(没有落地,调用方可重试;core 随即派普通 kill);
+ *    `no_pgid`(没有落地,调用方可重试;core 随即派普通 kill)。⚠️ S-769 读数:darwin 对「组里只剩还没被 node 收割的僵尸」也答 `EPERM`
+ *    (linux 答成功)。本函数**不**替它改判:EPERM 同样是「组里还有无权发信号的活成员」的答复,只看组长分不开这两形(codex r1 C1 [high]
+ *    验真:组长已死未收割 + 活后代被拒 ⇒ 改判就把真被拒读成已不在)。落地也**不**等于「组已空」(组信号任一成员收到即成功,车PA)——
+ *    所以 `already_gone` 只有 ESRCH 这一个来源;梯子那一枪先落地、组长还没收割的那一拍,darwin 上如实答 `no_pgid`(未确认),linux 答 `killed`;
  *  · win32 ⇒ 恒 `no_pgid`(core 契约:win32 无同步硬收 —— 没有进程组,树杀要一个延后的发现步,同步 `taskkill` 会杀掉启动器而
  *    留下 Git Bash 的作业组、却自称 `killed`)。
  * 「这个 pid 还是不是我的」由**调用方**先判(观察到退出 ⇒ 不许再发,pid 可能已经是别人的):本函数只管打出去的那一枪。永不抛。

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

@@ -149,6 +149,11 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
         stderr: string;
         exitCode: number;
     }, ExecutionError>>;
+    /** 文件面探针的 exec(车PL 验修 ③):只用绝对路径,**不进工作目录**、没有 cwd 守卫 —— 工作目录进不去时探针照样答真话(`permission_denied` /
+     *  `not_found` 由命令自己的 stderr 归),core 的 `isDeadCwd` 不会把「进不去」读成「没了」。 */
+    private fsExec;
+    /** buffered exec 的唯一体:`call` 定了整串、stderr 的 started 行剥法与收口(`remote-shell.ts` `createCwdGuardedCall`)。 */
+    private execCall;
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
     absolutePath(p: string): Promise<Result<string, FileError>>;
     joinPath(parts: string[]): Promise<Result<string, FileError>>;
@@ -230,11 +235,13 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
      *   远端退出码与分流的那根旗标,即「一条以 `-x` 开头的命令能静默把本修关回去」。真机验证 `--` 之后的
      *   参数原样落到设备 shell(`adb shell -T -- '-x'` ⇒ 设备答 `/system/bin/sh: -c: requires an argument`)。
      *
-     * 命令永远是**最后一个**参数,整条包在一个 argv 元素里(设备侧 `sh -c` 收全串,与 `withCwdEnv` 的
-     * `cd … && …` 前缀语义一致)。
+     * 命令永远是**最后一个**参数,整条包在一个 argv 元素里 —— 设备侧 `sh -c` 收全串,即 {@link buildCwdEnvCommand} /
+     * {@link createCwdGuardedCall} 组出的那一串(带工作目录时含 cwd 守卫前缀:cd 失败 ⇒ 整条不跑)。
      */
     private deviceShellArgs;
-    private withCwdEnv;
+    /** 本腿只定工作目录(缺省 cwd 规则 + 绝对化);串的形状归 {@link buildCwdEnvCommand} / {@link createCwdGuardedCall}(S-410:cwd 不可用 ⇒ 命令不跑;
+     *  车PL:buffered `exec` 上守卫触发 ⇒ `spawn_error`)。 */
+    private workingDirOf;
 }
 /**
  * `ExecutionEnvFactory` for the ADB backend — one fresh (unconnected) env per task against the same device

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

@@ -2,7 +2,7 @@ import path from "node:path";
 import os from "node:os";
 import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
-import { shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
+import { buildCwdEnvCommand, createCwdGuardedCall, shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
@@ -147,15 +147,21 @@ export class RemoteAdbExecutionEnv {
         return this.destroy();
     }
     async exec(command, options) {
+        return this.execCall(createCwdGuardedCall("adb", command, this.workingDirOf(options?.cwd), options?.env), options);
+    }
+    fsExec(command, abortSignal) {
+        return this.execCall(createCwdGuardedCall("adb", command, undefined, undefined), { abortSignal });
+    }
+    async execCall(call, options) {
         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), {
+        const r = await this.adb(this.deviceShellArgs(call.command), {
             signal: options?.abortSignal,
             timeoutMs: options?.timeout != null ? options.timeout * 1000 : this.cfg.commandTimeoutMs,
             onStdout: options?.onStdout,
             onStderr: options?.onStderr,
+            stderrFilter: call,
         });
         if (!r.ok)
             return { ok: false, error: r.error };
@@ -163,7 +169,7 @@ export class RemoteAdbExecutionEnv {
             this.connected = false;
             return { ok: false, error: new ExecutionError("transport_lost", `adb transport lost mid-command: ${r.value.stderr.trim().slice(0, 200)} — reconnect + retry per idempotency`) };
         }
-        return ok(r.value);
+        return call.settle(ok(r.value));
     }
     async *execStream(command, options) {
         const ready = await this.ensureConnected();
@@ -171,7 +177,7 @@ export class RemoteAdbExecutionEnv {
             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 wrapped = buildCwdEnvCommand(command, this.workingDirOf(options?.cwd), options?.env, "raw").command;
         const child = this.spawnFn(this.cfg.adbPath, this.deviceShellArgs(wrapped), { stdio: ["ignore", "pipe", "pipe"] });
         const queue = [];
         let finished = false;
@@ -327,7 +333,7 @@ export class RemoteAdbExecutionEnv {
         const abs = this.resolve(p);
         const dir = path.posix.dirname(abs);
         if (dir && dir !== "." && dir !== "/") {
-            const mk = await this.exec(`mkdir -p ${shellQuote(dir)}`, { abortSignal });
+            const mk = await this.fsExec(`mkdir -p ${shellQuote(dir)}`, abortSignal);
             if (!mk.ok)
                 return { ok: false, error: fileErrorFromExec(mk.error, dir) };
             if (mk.value.exitCode !== 0)
@@ -374,7 +380,7 @@ export class RemoteAdbExecutionEnv {
     posixFsInst;
     get posixFs() {
         return (this.posixFsInst ??= createPosixShellFs({
-            run: (cmd, abortSignal) => this.exec(cmd, { abortSignal }),
+            run: (cmd, abortSignal) => this.fsExec(cmd, abortSignal),
             resolve: (p) => this.resolve(p),
             tempDir: () => this.cwd,
         }));
@@ -456,14 +462,19 @@ export class RemoteAdbExecutionEnv {
                     outTail.push(d);
                 opts?.onStdout?.(d.toString());
             });
-            child.stderr.on("data", (d) => {
-                errBuf.push(d);
-                opts?.onStderr?.(d.toString());
-            });
+            const takeStderr = (bytes) => {
+                if (bytes.length === 0)
+                    return;
+                errBuf.push(bytes);
+                opts?.onStderr?.(bytes.toString());
+            };
+            child.stderr.on("data", (d) => takeStderr(opts?.stderrFilter ? opts.stderrFilter.filterStderr(d) : d));
             child.on("error", (e) => finish({ ok: false, error: new ExecutionError("spawn_error", `adb spawn failed (is '${this.cfg.adbPath}' installed?): ${e.message}`, e) }));
             child.on("close", (code, signal) => {
                 if (forceSettleTimer)
                     clearTimeout(forceSettleTimer);
+                if (opts?.stderrFilter)
+                    takeStderr(opts.stderrFilter.endStderr());
                 const err = errBuf.result();
                 const stderr = markTruncated(err.text, err.droppedBytes);
                 const exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 0);
@@ -481,16 +492,9 @@ export class RemoteAdbExecutionEnv {
     deviceShellArgs(command) {
         return ["-s", this.cfg.serial, "shell", "-T", "--", command];
     }
-    withCwdEnv(command, cwd, env) {
-        const parts = [];
+    workingDirOf(cwd) {
         const dir = cwd ?? this.cwd;
-        if (dir)
-            parts.push(`cd ${shellQuote(this.resolve(dir))} &&`);
-        if (env)
-            for (const [k, v] of Object.entries(env))
-                parts.push(`export ${k}=${shellQuote(v)};`);
-        parts.push(command);
-        return parts.join(" ");
+        return dir ? this.resolve(dir) : undefined;
     }
 }
 export function adbExecutionEnvFactory(config) {

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

@@ -10,8 +10,7 @@ import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
-import { recordSecretEnvScrub } from "../observability/secret-env-scrub.js";
-import { allowlistedEnv, scrubServerSecrets } from "../server-secret-env.js";
+import { allowlistedEnv, hostSubprocessEnv } from "../server-secret-env.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
@@ -335,14 +334,9 @@ export class RemoteHostExecutionEnv {
                     await fs.rm(state.dir, { recursive: true, force: true }).catch(() => { });
             },
             killNow(state) {
-                if (state.hardKilled === true)
-                    return "already_gone";
                 if (state.child.exitCode !== null || state.child.signalCode !== null)
                     return "already_gone";
-                const outcome = hardKillGroupNow(state.pid);
-                if (outcome === "killed")
-                    state.hardKilled = true;
-                return outcome;
+                return hardKillGroupNow(state.pid);
             },
         };
     }
@@ -1322,9 +1316,7 @@ export class RemoteHostExecutionEnv {
             base = allowlistedEnv(mode, process.env);
         }
         else {
-            const findings = [];
-            base = scrubServerSecrets(process.env, findings);
-            recordSecretEnvScrub("server.remote-env-host.inherit-scrub", findings, []);
+            base = hostSubprocessEnv({ site: "server.remote-env-host.inherit-scrub", allow: [] });
         }
         if (this.cfg.env)
             Object.assign(base, this.cfg.env);

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

@@ -245,6 +245,11 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
             shellId: string;
         };
     }, ExecutionError>>;
+    /** 文件面探针的 exec(车PL 验修 ③):只用绝对路径,**不进工作目录**、没有 cwd 守卫 —— 工作目录进不去时探针照样答真话(`permission_denied` /
+     *  `not_found` 由命令自己的 stderr 归),core 的 `isDeadCwd` 不会把「进不去」读成「没了」。 */
+    private fsExec;
+    /** buffered exec 的唯一体:`call` 定了整串、stderr 的 started 行剥法与收口(`remote-shell.ts` `createCwdGuardedCall`)。 */
+    private execCall;
     /**
      * LSP surface (lsp/manager.ts `isLspCapable` duck-type, [ref] §13.1): cluster-internal address for a
      * port on the sandbox pod. The E2B counterpart returns a public proxy host; a pod has none — the WORKER
@@ -333,7 +338,9 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     }): Promise<Result<string, FileError>>;
     /** exec with the data-transfer bound (large reads/writes legitimately run longer than a control op). */
     private execData;
-    private withCwdEnv;
+    /** 本腿只定工作目录(缺省 cwd 规则 + 绝对化);串的形状归 {@link buildCwdEnvCommand} / {@link createCwdGuardedCall}(S-410:cwd 不可用 ⇒ 命令不跑;
+     *  车PL:buffered `exec` 上守卫触发 ⇒ `spawn_error`)。 */
+    private workingDirOf;
 }
 /**
  * `ExecutionEnvFactory` for the k8s pod-sandbox backend — one fresh (unconnected) env per task; the pod is