@sema-agent/server 7.102.0 → 7.103.0

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-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/project-memory.js

@@ -3,8 +3,7 @@ import { execFile } from "node:child_process";
 import { createHmac, randomBytes } from "node:crypto";
 import hostPath, { isAbsolute, join } from "node:path";
 import { announceInstructionSource } from "./instruction-source-notice.js";
-import { recordSecretEnvScrub } from "./observability/secret-env-scrub.js";
-import { scrubServerSecrets } from "./server-secret-env.js";
+import { gitSubprocessEnv } from "./server-secret-env.js";
 import { redactSecrets } from "./trace/redact.js";
 const INSTRUCTION_FILE_CHAIN = ["CLAUDE.md", ".claude/CLAUDE.md", "AGENTS.md", ".claude/AGENTS.md"];
 const INSTRUCTION_READ_CAP = 24 * 1024;
@@ -72,11 +71,9 @@ async function readChainMember(root, rel, maxBytes, truncatedFlag) {
 }
 function git(root, args, maxBytes) {
     const safeArgs = ["-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", ...args];
-    const scrubFindings = [];
-    const scrubbedEnv = scrubServerSecrets(process.env, scrubFindings);
-    recordSecretEnvScrub("server.project-memory.git-subprocess", scrubFindings, []);
+    const env = gitSubprocessEnv({ site: "server.project-memory.git-subprocess", isolateConfig: true });
     return new Promise((res) => {
-        execFile("git", safeArgs, { cwd: root, timeout: 5000, maxBuffer: maxBytes, env: { ...scrubbedEnv, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null" } }, (err, stdout, stderr) => {
+        execFile("git", safeArgs, { cwd: root, timeout: 5000, maxBuffer: maxBytes, env }, (err, stdout, stderr) => {
             if (!err)
                 return res({ out: stdout.trim() });
             const e = err;

package/dist/run-local.js

@@ -52,6 +52,7 @@ import { createMetrics } from "./observability/metrics.js";
 import { installSecretEnvScrubRecorder } from "./observability/secret-env-scrub.js";
 import { createHostLspManager } from "./host-lsp-manager.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
+import { installOutboundDispatcher } from "./outbound-dispatcher.js";
 export function parseArgs(argv) {
     let objective;
     let root;
@@ -267,6 +268,7 @@ export async function runLocal(argv, deps = {}) {
     const memoryEngineIncident = createMemoryEngineIncidentSink({ logger, metrics });
     installSecretEnvScrubRecorder({ logger, metrics });
     logConfigDiagnostics(logger);
+    installOutboundDispatcher(logger);
     const configProvider = createConfigProvider({
         provider: config.configProvider ?? "local",
         ...(config.configLocalDir ? { localDir: config.configLocalDir } : { localDir: root }),

package/dist/server-secret-env.d.ts

@@ -1,40 +1,48 @@
 /**
- * 7.99.0 合并复审 F7(web-admin [ref] 实测;安全轴;DEBTS S-684)—— 子进程 env 交出去之前的**本仓**密钥剥除。
+ * 7.99.0 合并复审 F7(web-admin [ref] 实测;安全轴;DEBTS S-684)—— 子进程 env 交出去之前的**本仓**密钥剥除;7.103.0(车OT,
+ * S-684 残余按类收口)起也是本包**宿主子进程 env 的唯一组合点**。
  *
  * ## 病
- * 本仓两条子进程腿 —— 模型可驱动的 host shell(`inheritEnv:"scrub"` 缺省腿,`plugins/remote-env-host.ts`)与
+ * 本仓的子进程腿 —— 模型可驱动的 host shell(`inheritEnv:"scrub"` 缺省腿,`plugins/remote-env-host.ts`)与
  * project-memory 的 git 子进程(`project-memory.ts`)—— 此前只调 core 的 `scrubSecretEnv`。它按键名**形状**判
  * (`*_KEY` / `*_TOKEN` / `*_SECRET` …),而本仓自己的凭据键里有形状规则认不出的:`SERVICE_AUTH_TOKENS`(复数,
  * per-system 凭据表)、`APPROVAL_HMAC_KEYS`(直连门 HMAC 密钥集)、`OTEL_EXPORTER_OTLP_HEADERS`(常载鉴权头)⇒
- * 原样进子进程,模型选的一句 `printenv` 就读得到。
+ * 原样进子进程,模型选的一句 `printenv` 就读得到。S-684 残余(7.103.0):另外三条宿主腿连 core 的形状剥都没过 —— leader 推送的
+ * git(`leader/wire.ts`)、center-plugins 克隆的 git(`capabilities/center-plugins.ts`)、bake-runner 交给 build.sh 与主机命令的
+ * env(`bake-runner/main.ts`,连 runner 自己的 `BAKE_RUNNER_TOKEN`)。
  *
  * ## 规则(一句)
- * 本仓**知道**哪些 env 键是凭据 —— 配置目录(`config-catalog.ts`)里 `type:"secret"` 的每一行,从目录机器派生,
- * 不手抄第二份名单 —— 这些键按名剥;其余照旧交 core 按形剥。{@link scrubServerSecrets} = 目录派生剥除 ∘ core
- * `scrubSecretEnv`,本仓三条子进程腿(host shell / git 子进程 / 本地语言服务器,后者见 `host-lsp-manager.ts`)都只调它。
+ * 本包任何进程在宿主上 spawn 的子进程:env = {@link hostSubprocessEnv} = {@link scrubServerSecrets}(process.env) ∪ 部署方点名放回的键
+ * (只在运维真可能要传东西的腿上有旋钮),剥掉的键经一个登记过的 `SecretEnvScrubSite` 留痕;git 腿再叠 git 自己的两件
+ * ({@link gitSubprocessEnv})。各腿只调这两只 —— 不许再有内联拼装(类级门在 `test/secret-env-scrub-host-legs.test.ts`)。
+ *
+ * {@link scrubServerSecrets} = core `scrubSecretEnv`(按形)∘ 本仓按名两臂:
+ *  · 目录臂 —— 配置目录(`config-catalog.ts`)里 `type:"secret"` 的每一行,从目录机器派生,不手抄第二份名单;
+ *  · 名单型旋钮臂 —— `ENV_NAME_ALLOWLIST_KNOBS` 的每一只(`env-name-allowlist-knobs.ts`,表键派生):名单**原文**可能夹着一枚被错展开进来
+ *    的令牌,按凭据类对待。服务侧三只(`LSP_ENV_ALLOW` S-699 / `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV` S-713)同时是目录 secret 行,
+ *    目录臂先认;本臂接住的是**不在服务目录里**的那一只 —— bake-runner 的 `BAKE_ENV_ALLOW`(它不是服务进程的配置)。
  * core 形状规则的缺口由 core 源头修 —— 7.30.1 #1072 已补 `KEYS|TOKENS|PASSWORDS`(S-616 提货),目录臂独担的只剩
- * `OTEL_EXPORTER_OTLP_HEADERS`(`*_HEADERS` 不在形状规则射程,是边界不是缺陷票)与三只名单型旋钮 `LSP_ENV_ALLOW`(S-699)/
- * `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV`(S-713):原文可能夹着一枚被错展开进来的令牌,按凭据类登记 —— 形状规则按名判,本来就不该
- * 认它们)。本层不改 core 的判据,也不自造
- * 第二份形状规则。目录里加一个 secret 型键,三条腿当场就剥它。
+ * `OTEL_EXPORTER_OTLP_HEADERS`(`*_HEADERS` 不在形状规则射程,是边界不是缺陷票)与名单型旋钮(形状规则按名判,本来就不该认它们)。
+ * 本层不改 core 的判据,也不自造第二份形状规则。目录里加一个 secret 型键 / 叶表加一只名单型旋钮,每条腿当场就剥它。
  *
  * ## 不变的面
  * `inheritEnv:"all"`(显式全继承)与显式 allowlist 两形不经本函数,行为逐字不变;调用方显式传入的 env
  * (`cfg.env` / 单次命令的 `env`)照旧原样覆盖在剥除结果之上。
  *
- * ## 点名放行(S-699 / S-713,一只谓词三处用)
- * {@link allowlistedEnv} 是本仓「一张名单点到哪些 env 键,就把它们从源 env **原样**交给子进程」的唯一实现。三处调用:
- * host shell 的 `inheritEnv:[names]`(`plugins/remote-env-host.ts`)、本地语言服务器的 `LSP_ENV_ALLOW`(`host-lsp-manager.ts`)、
- * 沙箱带外 env 的 `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV`(`config.ts`,S-713 起;此前那里是第三份自写的循环)。三只名单型
- * 旋钮的**名单**另由 `config.ts` 的同一只解析器 `parseEnvNameAllowlist` 判形(形错拒启 / 源里没有的名按序号 warn),本函数只管取值。
- * 「点名」在三处同义:点到的键原样带值(空串值照带),密钥形也照过(点名 = 部署方显式承担);源里没有的名不产生条目。
+ * ## 点名放行(S-699 / S-713,一只谓词各处用)
+ * {@link allowlistedEnv} 是本仓「一张名单点到哪些 env 键,就把它们从源 env **原样**交给子进程」的唯一实现。调用:
+ * host shell 的 `inheritEnv:[names]`(`plugins/remote-env-host.ts`,hermetic 形)、{@link hostSubprocessEnv}(剥后放回形:本地语言服务器的
+ * `LSP_ENV_ALLOW`、bake-runner 的 `BAKE_ENV_ALLOW`)、沙箱带外 env 的 `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV`(`config.ts`,S-713 起)。
+ * 名单型旋钮的**名单**另由 `config.ts` 的同一只解析器 `parseEnvNameAllowlist` 判形(形错拒启 / 源里没有的名按序号 warn),本函数只管取值。
+ * 「点名」在各处同义:点到的键原样带值(空串值照带),密钥形也照过(点名 = 部署方显式承担);源里没有的名不产生条目。
  * 沙箱两腿不继承本进程环境:进沙箱的本进程值只有点到的键(与 host shell 的 hermetic 形同一侧)。
- * host shell 与语言服务器**只在没点到的键上**不同,这是有意保留的差别:host shell 的 `string[]` 形是 hermetic 白名单(与 core
- * `NodeExecutionEnv` 同名选项同义,没点到的一律不继承);语言服务器在 {@link scrubServerSecrets} 的结果之上放回点名键
- * (没点到的照缺省剥,`PATH` / `HOME` 这类非密钥键照常在 —— hermetic 形会让语言服务器当场找不到自己的工具链)。
- * 两处都不放宽对方:把 host shell 改成「剥后放回」= 在模型可驱动的 shell 上放宽,把语言服务器改成 hermetic = 功能当场失灵。
+ * host shell 与「剥后放回」形**只在没点到的键上**不同,这是有意保留的差别:host shell 的 `string[]` 形是 hermetic 白名单(与 core
+ * `NodeExecutionEnv` 同名选项同义,没点到的一律不继承);语言服务器 / bake-runner 在 {@link scrubServerSecrets} 的结果之上放回点名键
+ * (没点到的照缺省剥,`PATH` / `HOME` 这类非密钥键照常在 —— hermetic 形会让子进程当场找不到自己的工具链)。
+ * 两形都不放宽对方:把 host shell 改成「剥后放回」= 在模型可驱动的 shell 上放宽,把后者改成 hermetic = 功能当场失灵。
  */
 import { type SecretEnvFinding } from "@sema-agent/core";
+import { type SecretEnvScrubSite } from "./observability/secret-env-scrub.js";
 /** 目录派生臂的一条剥除记录(形同 core 的 `SecretEnvFinding`:键名 / 规则 / 置信度 / 来源;值永不携带)。
  *  `source` 用本仓自己的词 `server-config-catalog`,与 core 的 `secret-env` 分开 —— 读观测面的人要分得清
  *  「形状规则剥的」与「本仓目录点名剥的」(后者多出来的那部分正是 core 形状规则的缺口)。 */
@@ -44,16 +52,81 @@ export interface CatalogSecretEnvFinding {
     readonly confidence: "high";
     readonly source: "server-config-catalog";
 }
-/** 本仓两条子进程腿的剥除记录:core 的形状臂 ∪ 本仓的目录臂。 */
-export type ServerSecretEnvFinding = SecretEnvFinding | CatalogSecretEnvFinding;
+/** 名单型旋钮臂的一条剥除记录(形同上;`source` 用自己的词 —— 读观测面的人要分得清「目录点名剥的」与「名单型旋钮原文按凭据类剥的」)。 */
+export interface NameListKnobEnvFinding {
+    readonly key: string;
+    readonly kind: "name-list-knob";
+    readonly confidence: "high";
+    readonly source: "server-name-list-knob";
+}
+/** 随残组扣下的 git 配置组成员(codex r1 C1;见 {@link hostSubprocessEnv} 的组不变量)。它本身不是凭据 —— 是因为同组的某个成员被剥掉、
+ *  整组已不成形而一起扣下的;`kind` 单列一桶,读观测面的人分得清「剥的」与「随组扣下的」。 */
+export interface GitConfigGroupEnvFinding {
+    readonly key: string;
+    readonly kind: "git-config-group";
+    readonly confidence: "high";
+    readonly source: "server-git-config-group";
+}
+/** 本仓子进程腿的扣下记录:core 的形状臂 ∪ 本仓的目录臂 ∪ 名单型旋钮臂 ∪ 随残组扣下的 git 配置组成员。 */
+export type ServerSecretEnvFinding = SecretEnvFinding | CatalogSecretEnvFinding | NameListKnobEnvFinding | GitConfigGroupEnvFinding;
 /** 配置目录里 `type:"secret"` 的 env 名(大写 —— Windows 的 env 名不分大小写,按大写比才不会漏)。 */
 export declare const CATALOG_SECRET_ENV_NAMES: ReadonlySet<string>;
 /**
- * 先交 core 按形剥,再按目录名剥它漏下的。`findings` 是调用方持有的收集器(交给 `recordSecretEnvScrub` 留痕):
+ * 先交 core 按形剥,再按目录名、名单型旋钮名剥它漏下的。`findings` 是调用方持有的收集器(交给 `recordSecretEnvScrub` 留痕):
  * 形状臂剥掉的记 core 的 finding;目录臂只记**形状臂漏下、被目录点名剥掉**的键 —— 于是既有的形状臂计数不变,
- * 目录臂的计数恰好就是 core 形状规则的缺口读数。
+ * 目录臂的计数恰好就是 core 形状规则的缺口读数;名单型旋钮臂只记前两臂都漏下的(今天 = 不在服务目录里的 `BAKE_ENV_ALLOW`)。
+ * 各腿不直接调它 —— 经 {@link hostSubprocessEnv}(剥 + 放回 + 留痕一只口)。
  */
 export declare function scrubServerSecrets(env: NodeJS.ProcessEnv, findings: ServerSecretEnvFinding[]): NodeJS.ProcessEnv;
+/**
+ * 🔴 **宿主子进程 env 的唯一组合**(S-684 残余按类收口,7.103.0):{@link scrubServerSecrets}(process.env) ∪ `allow` 点到的键
+ * (经 {@link allowlistedEnv} 从原 env 原样放回),**最终没进子进程**的剥除键经 `site` 留痕(点名放回的键不是剥除,不计数、不披露)。
+ *
+ * 六条宿主腿都只经它(直接或经 {@link gitSubprocessEnv}):host shell 缺省 scrub 腿、project-memory / center-plugins / leader 三条 git 腿、
+ * 本地语言服务器、bake-runner 的每一只子进程组。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
+ * 它们的现场在 `SECRET_ENV_SCRUB_SITES` 里登记了 `remedy`,披露行因此是 warn + 放行名单 + 出路句);其余现场传 `[]`。
+ * 返回 `NodeJS.ProcessEnv` 形(值可能是 `undefined` 的键本来就不会进子进程);调用方显式要交的键(`LC_ALL`、`cfg.env` …)叠在它之上。
+ * 调用时机 = 每次要交 env 时现算一次(`process.env` 在本仓是 boot 期输入,各次同值;计数因此是「每组合一次」)。
+ *
+ * 🔴 **组不变量(codex r1 C1 [high])**:逐键剥除不许把一组**按组生效**的 env 剥成残组。今天的实例是 git 的 env 配置组
+ * (`GIT_CONFIG_COUNT` + `GIT_CONFIG_KEY_<i>` / `GIT_CONFIG_VALUE_<i>`):core 剥掉某个 `GIT_CONFIG_KEY_<i>`、COUNT 与 VALUE 照留 ⇒ 子进程里的
+ * git 起手就 `missing config key`、退 128(任何读配置的子命令,不只要用那条配置的)。core ≤7.33.0 形状规则的 `KEY(_<数字>)?` 后缀剥**每一个**
+ * `GIT_CONFIG_KEY_<i>`;core 7.33.1 #1129 起该族具名豁免,残组今天从**两侧**来:KEY 侧的值筛(值里是带 userinfo 的 URL —— 令牌
+ * `url.<base>.insteadOf`)剥 KEY;core 7.33.2 起 VALUE 侧的值族表(`GIT_CONFIG_VALUE_<i>` 是 `Authorization:` / `Proxy-Authorization:` /
+ * `Cookie:` 头、带 userinfo 的 URL,或 proxy 地址键下的 `user[:secret]@host` ⇒ `family-rule`)剥 VALUE。两侧的 URL userinfo 判据自 core 7.33.2
+ * 起就是**同一只**(7.33.2 = 正则 `URL_USERINFO_RE`:`//` 到 `@` 之间无 `/` `?` `#`);core 7.33.3 #1140 只改这一只判据本身,剥得更多(`://` 后到
+ * 第一个 `@` 的段:无 `/` `?` `#`,或第一个 `/` `?` `#` 之前有 `:`(段首 `[…]` 里的 `:` 不计)—— 密码里未转义的 `/` 也算;带端口的路径 `@` 过剥,
+ * core KL-1129b);core 7.33.4 #1146 再改它、不再解析 authority:值里有 `:/`、其后任意位置有 `@` 或 `%40` 即剥,proxy 地址键下值里有 `@` / `%40` 即剥
+ * —— 路径里的 `@`(`@scope` 包路径)与 scp 绝对路径带 `@`(`host:/repo@v2.git`)一并多剥(fail-closed,KL-1129b)。本不变量对哪一侧剥残的组都照样
+ * 成立(车OR / 车PA / 车PB / 车PC 提货翻钉,零改码)。
+ * 规则:交出去的组要么**源里有的成员一个不少**、要么**整组都不给**(值同扣 —— VALUE 里可能正是鉴权头);随组扣下的成员记
+ * `kind: "git-config-group"`。本层只**多扣**、从不放回 core 判掉的键(core 的判据不在这里改;`GIT_CONFIG_KEY_<i>` 是不是凭据是 core
+ * 形状规则的事,见 [ref] 登记);部署方点名放回全部 `GIT_CONFIG_KEY_<i>` 与 `GIT_CONFIG_VALUE_<i>`(有放行面的现场;core 7.33.2 起两边都可能被剥,
+ * 只放回 KEY 仍是残组)⇒ 组完整,原样交出。源里本就残缺的组不是本层
+ * 剥残的,不碰(git 对它照样报错 —— 那是部署方自己的配置)。
+ */
+export declare function hostSubprocessEnv(o: {
+    site: SecretEnvScrubSite;
+    allow: readonly string[];
+}): NodeJS.ProcessEnv;
+/** git 子进程腿的现场(闭集里名字带 `.git-` 的那几只 —— 编译期筛;它们都没有点名放行面)。 */
+export type GitSubprocessSite = Extract<SecretEnvScrubSite, `${string}.git-${string}`>;
+/**
+ * 宿主 **git 子进程**的 env:{@link hostSubprocessEnv}(site, 不放回) + `GIT_TERMINAL_PROMPT=0`(恒:凭据缺席 ⇒ 响亮失败,绝不挂在交互
+ * prompt 上 —— 服务进程没有终端)+(`isolateConfig` ⇒ `GIT_CONFIG_GLOBAL` / `GIT_CONFIG_SYSTEM` = `/dev/null`:宿主全局 / 系统 git 配置
+ * (insteadOf / credential helper / hooksPath / fsmonitor …)一概不继承)。
+ *
+ * `isolateConfig` 按腿定(三条腿各自的理由在调用点):project-memory 与 center-plugins 隔离(读仓 / 克隆不需要宿主身份);leader 推送
+ * **不**隔离 —— durable remote 的写凭据属于控制面宿主(「Coordinator's creds」),可能由宿主 git 配置里的 credential helper / insteadOf
+ * 提供,隔离会把它们一起切掉。不隔离 ≠ 不剥:helper 同样只看得到剥后的 env(读 `*_TOKEN` 形 env 的 helper 因此读不到,出路见 CHANGELOG)。
+ *
+ * ⚠️ 已知边界(不在本函数修):Apple Git 另有一层 Xcode 自带配置(`…/Xcode.app/…/git-core/gitconfig`,内含 `credential.helper=osxkeychain`),
+ * `GIT_CONFIG_SYSTEM` 盖不住、`GIT_CONFIG_NOSYSTEM=1` 才盖得住 —— 只在 macOS 开发机上,文件属 root(不可被模型种),见 [ref] 登记。
+ */
+export declare function gitSubprocessEnv(o: {
+    site: GitSubprocessSite;
+    isolateConfig: boolean;
+}): NodeJS.ProcessEnv;
 /**
  * S-699 —— **点名放行**的唯一谓词:从 `env` 里把 `names` 点到的键**原样**取出(值逐字,空串照带;源里没有的名不产生
  * 条目)。密钥形的键点到了也照取 —— 点名即部署方显式承担;要不要在这之上再叠别的基底,是调用方的事(见文件头「点名放行」节)。