@sema-agent/server 7.101.1 → 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/parked-decide.d.ts

@@ -9,7 +9,9 @@
  * 行永 parked、生命周期分叉)。
  */
 import type { HostDecision } from "./host-decision.js";
-import type { BackgroundAgentRecord, BackgroundAgentStore, CheckpointStore, QuestionAnswer, ResumeOutcome, TaskRegistry, ToolSpec, WorkflowRun, WorkflowRunStore } from "@sema-agent/core";
+import type { BackgroundAgentRecord, BackgroundAgentStore, CheckpointStore, QuestionAnswer, ResumeOutcome, TaskRegistry, WorkflowRun, WorkflowRunStore } from "@sema-agent/core";
+import type { ParkedReviveSurfaceFactory } from "./parked-revive-surface.js";
+import type { RebuiltInheritedGate } from "./boot/parked-revive-gate.js";
 import { type WorkflowRunParkKey, type WorkflowAgentSessionIndex } from "./orchestration/workflow-agent-session-index.js";
 export interface ParkedAgentMatch {
     handle: string;
@@ -112,9 +114,13 @@ export interface ParkedDecideDeps {
     checkpointStore: Pick<CheckpointStore, "get">;
     /** 与 reaper/scenarios 同一个 registry(claim/rollback 的 CAS 与 in-memory handle 收敛在同处)。 */
     registry: Pick<TaskRegistry, "claimParkedAgent" | "rollbackParkedClaim">;
-    /** boot 期从生产装配(buildScenarios)取的裸 Agent ToolSpec——与 spawn 用同一装配路径,
-     *  subRunner/bg opts/checkpointStore 同实例天然成立([ref] 设计稿 §4)。 */
-    reviveTool: ToolSpec;
+    /** #1110(core 7.32.0):按**行**解析赎回面 —— 驱动哪一只 Agent 工具(生产装配,与 spawn 同源:subRunner / bg opts /
+     *  checkpointStore 同实例,[ref] 设计稿 §4),以及与它同出一张列表的继承座 `mountsCallerTool`(一层行才有;属主与全部判据
+     *  在 `parked-revive-surface.ts`)。修前是 boot 期的一只裸 Agent 工具、从不交座 ⇒ 7.32.0 起停在继承工具上的 allow 恒 422。 */
+    reviveSurface: ParkedReviveSurfaceFactory;
+    /** #1110 codex r1 [high]:会话属主面(`sessionStorage.ownerOf`)—— 赎回腿在 claim 前读**根会话现在**的属主交给赎回面(属主换人 / 会话
+     *  已不在 ⇒ 不交座)。缺席 = 本部署无属主面 ⇒ 读数缺席 ⇒ 不交座(fail-closed)。读抛 ⇒ 原样上抛(claim 之前,没有东西要回滚)。 */
+    sessionOwnerOf?: (sessionId: string) => Promise<string | null | undefined>;
     /** revive args 的 `subagent_type` 成员性判定集([ref] Q1 修正:非 roster 成员必须省略,否则
      *  unknown subagent_type 拒;字面比对 general-purpose 在 roster 撞名时会错省)。缺省空集=恒省略。 */
     knownAgentTypes?: ReadonlySet<string>;
@@ -130,7 +136,7 @@ export interface ParkedDecideDeps {
      *  「席位必须同步」是那个文件此前自设的约束、不是结构事实。 */
     rebuildInheritedGate?: (row: BackgroundAgentRecord, identity: {
         principal: string | undefined;
-    }) => Promise<unknown>;
+    }) => Promise<RebuiltInheritedGate | undefined>;
     warn?: (event: string, fields: Record<string, unknown>) => void;
 }
 export interface ParkedDecideRequest {

package/dist/parked-decide.js

@@ -149,6 +149,8 @@ export async function decideParkedAgent(deps, req, match) {
         return { status: 409, body: { error: "parked row carries no agent name — the revive path requires a named agent (row damaged?)", errorCode: "decide.row_unrevivable", taskId: match.handle } };
     }
     const inheritedGate = deps.rebuildInheritedGate ? await deps.rebuildInheritedGate(row, { principal: decodeCheckpointScope(req.scope) }) : undefined;
+    const rootOwner = row.rootSessionId !== undefined && deps.sessionOwnerOf ? await deps.sessionOwnerOf(row.rootSessionId) : undefined;
+    const surface = deps.reviveSurface(row, { principal: decodeCheckpointScope(req.scope), ...(rootOwner !== undefined ? { rootOwner } : {}) });
     const stores = { agentStore: deps.agentStore, checkpointStore: deps.checkpointStore };
     const claim = await deps.registry.claimParkedAgent(stores, match.handle, { scope: row.scope, owner: row.owner });
     if (!claim.ok) {
@@ -180,6 +182,7 @@ export async function decideParkedAgent(deps, req, match) {
     const outcome = buildParkedResumeOutcome(req);
     const ctx = {
         toolCallId: `drv-${ticket.claimId}`,
+        ...(surface.mountsCallerTool !== undefined ? { mountsCallerTool: surface.mountsCallerTool } : {}),
         reviveClaim: {
             row: { ...ticket.row, parkClaimId: ticket.claimId },
             rev: ticket.reservedRev,
@@ -211,7 +214,7 @@ export async function decideParkedAgent(deps, req, match) {
     defaultSubagentTailBus.forgetHandle(match.handle);
     let receipt;
     try {
-        receipt = await deps.reviveTool.execute(mintReviveArgs(row, deps.knownAgentTypes ?? new Set()), ctx);
+        receipt = await surface.reviveTool.execute(mintReviveArgs(row, deps.knownAgentTypes ?? new Set()), ctx);
     }
     catch (e) {
         const disp = await rollback("execute_threw");

package/dist/parked-revive-surface.d.ts

@@ -0,0 +1,47 @@
+/**
+ * #1110(core 7.32.0)—— `/decide` parked 赎回腿的**赎回面**:驱动哪一只 Agent 工具,以及交不交继承座
+ * `ToolExecuteContext.mountsCallerTool`。
+ *
+ * core 7.32.0 起 Agent 子代按**身份**继承场景层工具(bundle 交给 Agent 的 `inheritedTools` ∩ 父 run 的 `spec.tools`),由宿主
+ * **自己**驱动 `execute` 的一方(本腿)必须交座,否则 fail-closed:复活的子代什么都不继承,而停在一只**继承工具**上的 `allow` 在消费
+ * 审批之前被拒(`parked_resume.startup_failed` ⇒ `parked-decide.ts` 的 422 臂,审批留 pending;`deny` 照常结)。
+ *
+ * 规则(core [ref] / unreleased-1110 原话,一条):**座建在那条行的根会话解析出来的同一张列表上,赎回工具取自同一张列表**。
+ *  · 列表 = 内建 default 场景工厂按行的根会话重解一次(`defaultScenario({}, principal, { sessionId: root })`)—— 与生产 resolve-spec
+ *    给那个会话的 run 组 `spec.tools` 的同一只工厂、同一个会话分区(任务清单店 `taskListStoreFor(root)` 与领队那一张是同一张;
+ *    多租户的 WebFetch 过滤同样生效 ⇒ 子代同样拿不到)。座 = `(t) => tools.includes(t)`(身份判:同名副本不算)。
+ *  · **禁**用 boot 期单例填座:那只 bundle 没有会话,它的任务清单是一张私有表 —— 填了座,每个会话 / 租户的复活队友都会共用它。
+ *  · **根会话现在还属于这张卡的租户**才填座(codex r1 [high]):任务清单店只按会话 id 分区,而会话 id 由调用方自选、删后可被别人重领 ——
+ *    根会话删了(或换了主人)之后赎回一张旧卡,按 id 重解出来的是**新主人**的清单。属主读数由赎回腿在 claim 前读(`identity.rootOwner`,
+ *    读自会话属主面;缺席 = 会话已不在 / 读不出),与卡的权威 principal 逐字相等才填;否则不交座(fail-closed:子代不继承,继承工具上的
+ *    allow 回 422、审批待决,deny 照结)。根删除时把子孙的 parked 卡一并围栏 / 过期 = 另车(会话化身轴,[ref] 同族)。
+ *  · 只对**一层**行填座(`rootSessionId` 在场且 = `parentSessionId`:派它的 run 就是根会话的 run,列表正是那个 run 的挂载)。更深的行
+ *    (孙代:派它的是一个子代,它的挂载是继承裁剪后的子集,行上读不出来)不填 —— 用 boot 期那只裸 Agent、无座 = core 的 fail-closed 臂;
+ *    行上带继承组成是 core #1112(7.32.x)的半场,到货再改读行。
+ * 近似如实记:重解的列表是**部署缺省**那一份,读不回那一 run 的逐请求差异(`settings.webSearch` 后端、center overlay 场景)——
+ * 座只判 bundle 实例的成员性,继承面是 `[...web, ...scaffolds]`,那两项差异不改变谁在面内。
+ */
+import { type BackgroundAgentRecord, type ToolSpec } from "@sema-agent/core";
+import type { Scenario } from "./capabilities/scenarios.js";
+/** 一次赎回用的面:驱动的 Agent 工具 + (一层行时)与它同出一张列表的继承座。 */
+export interface ParkedReviveSurface {
+    readonly reviveTool: ToolSpec;
+    /** 缺席 = 不交座(core fail-closed:复活的子代不继承任何场景层工具)。 */
+    readonly mountsCallerTool?: (tool: ToolSpec) => boolean;
+}
+/**
+ * 按行解析赎回面的入参身份:`principal` = 权威 principal(取 checkpoint 的 scope 列,不取行上有损的 `row.scope`);`rootOwner` = 行的根会话
+ * **现在**的属主(赎回腿在 claim 前读会话属主面;`null` = 匿名会话,缺席 = 会话已不在 / 读不出 / 本部署无属主面)。
+ */
+export interface ParkedReviveSurfaceIdentity {
+    readonly principal: string | undefined;
+    readonly rootOwner?: string | null;
+}
+/** 按行解析赎回面。 */
+export type ParkedReviveSurfaceFactory = (row: BackgroundAgentRecord, identity: ParkedReviveSurfaceIdentity) => ParkedReviveSurface;
+/**
+ * 赎回面工厂。入参 = **内建** default 场景工厂(stage-07 在 center overlay 盖名之前取的那一只;赎回要的是与 spawn 同源的生产装配)。
+ * 内建 bundle 里没有 Agent 工具 ⇒ `undefined`(park 本就不可达,赎回腿不接线)。
+ */
+export declare function createParkedReviveSurface(defaultScenario: Scenario): ParkedReviveSurfaceFactory | undefined;
+//# sourceMappingURL=parked-revive-surface.d.ts.map

package/dist/parked-revive-surface.js

@@ -0,0 +1,20 @@
+import { DEFAULT_SUBAGENT_TOOL_NAME } from "@sema-agent/core";
+const agentOf = (tools) => tools.find((t) => t.name === DEFAULT_SUBAGENT_TOOL_NAME);
+export function createParkedReviveSurface(defaultScenario) {
+    const bootTool = agentOf(defaultScenario({}).tools);
+    if (bootTool === undefined)
+        return undefined;
+    return (row, identity) => {
+        const root = row.rootSessionId;
+        if (root === undefined || row.parentSessionId !== root)
+            return { reviveTool: bootTool };
+        if (identity.rootOwner === undefined || (identity.rootOwner ?? undefined) !== identity.principal)
+            return { reviveTool: bootTool };
+        const tools = defaultScenario({}, identity.principal, { sessionId: root }).tools;
+        const reviveTool = agentOf(tools);
+        if (reviveTool === undefined)
+            return { reviveTool: bootTool };
+        return { reviveTool, mountsCallerTool: (t) => tools.includes(t) };
+    };
+}
+//# sourceMappingURL=parked-revive-surface.js.map

package/dist/plugins/background-shell-support.d.ts

@@ -21,7 +21,7 @@
  * re-read by byte cursor on each poll (path ①). Both are expressed through {@link BackgroundShellDriver}.
  */
 import { BackgroundShellError } from "@sema-agent/core";
-import type { BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions, Result } from "@sema-agent/core";
+import type { BackgroundHardKillOutcome, BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions, Result } from "@sema-agent/core";
 import { StringDecoder } from "node:string_decoder";
 /** Per-端 background capability bounds, surfaced as `backgroundCapabilities` on the env ([ref] §3.1/§3.6).
  *
@@ -105,6 +105,13 @@ export interface BackgroundShellDriver<S> {
     kill(state: S): Promise<void>;
     /** Best-effort cleanup of ONE shell's transport resources (kill + remove temp dirs/handles). Should not throw. */
     disposeOne(state: S): Promise<void>;
+    /**
+     * S-745(core 7.32.0 #1107)—— **可选**的同步硬收一枪(`BackgroundShellCapability.killBackgroundNow` 的 driver 半场)。
+     * 只有**本机有进程组可发**的 driver 实现它(今天只有 host 车道);远端 / 沙箱车道留空 ⇒ 座位根本不挂出来,core 对那些行
+     * 答 `no_pgid` 并派普通 kill。契约(core `docs/background-process-lifetime.md`):同步(无 TERM、无定时器、无 await)、
+     * 幂等、永不抛、只对**证明得了还是自己的** pid 发信号(观察到退出 ⇒ `already_gone`,一枪都不发)。
+     */
+    killNow?(state: S): BackgroundHardKillOutcome;
 }
 export declare class BackgroundShellManager<S> {
     private readonly driver;
@@ -154,6 +161,18 @@ export declare class BackgroundShellManager<S> {
     private register;
     poll(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
     kill(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
+    /**
+     * S-745 —— 座位 `killBackgroundNow(shellId)` 的 manager 半场:**同步**、永不抛。
+     *  · 不是本 env 的 shell(未知 / 伪造 / 已被驱逐的终态行)⇒ `already_gone`(core 契约「or not its shell」);
+     *  · driver 不实现 {@link BackgroundShellDriver.killNow} ⇒ `no_pgid`(没有同步硬收可落;实现座位的 env 才会走到这里);
+     *  · driver 答出三词之外 ⇒ `no_pgid`(没有落地,可重试)。driver 的座位按契约**永不抛**(host 的那只由构造保证:只读子进程句柄
+     *    + `hardKillGroupNow` 自己吞 `kill` 的拒因);万一抛了,本函数**不吞** —— 异常原样上抛给 core 的注册表,由它读成 `no_pgid` 并记
+     *    `SEMA_DEBUG_SHUTDOWN` 取证行(core 契约:「A seat that throws … reads no_pgid」),不在这里再写一只静默兜底;
+     *  · 落地 `killed` 且条目还在 `running` ⇒ 条目结算 `killed` + 清 BG 超时墙(与 {@link kill} 的记账同一形:这一枪是**我们**
+     *    打的,之后迟到的 `close` 不再把它改判成 `exited`)。条目状态**不参与**判「该不该发」:软梯子会先把条目翻成 `killed`
+     *    再等宽限(屏蔽 TERM 的组此刻还活着),所以「该不该发」只由 driver 读子进程句柄判。
+     */
+    killNow(shellId: BackgroundShellId): BackgroundHardKillOutcome;
     /** Kill + clean up EVERY shell. Best-effort, MUST NOT throw, idempotent ([ref] §3.7).
      *
      *  core `except` 契约(background-shell.d.ts:core runtask 尾调 `{except: keepAlive}`):

package/dist/plugins/background-shell-support.js

@@ -216,6 +216,32 @@ export class BackgroundShellManager {
         }
         return ok(undefined);
     }
+    killNow(shellId) {
+        const entry = this.shells.get(shellId);
+        if (!entry)
+            return "already_gone";
+        const seat = this.driver.killNow;
+        if (seat === undefined)
+            return "no_pgid";
+        const outcome = seat.call(this.driver, entry.state);
+        switch (outcome) {
+            case "killed":
+                if (entry.status === "running") {
+                    entry.status = "killed";
+                    if (entry.timer)
+                        clearTimeout(entry.timer);
+                }
+                return "killed";
+            case "already_gone":
+            case "no_pgid":
+                return outcome;
+            default: {
+                const unreachable = outcome;
+                void unreachable;
+                return "no_pgid";
+            }
+        }
+    }
     async dispose(opts) {
         const keep = opts?.except?.length ? new Set(opts.except) : undefined;
         const doomed = [];

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

@@ -23,7 +23,7 @@
  * structural tests only on mac/Linux; behavior-level bite happens on the first Windows-runner green.
  */
 import type { ChildProcess } from "node:child_process";
-import { killProcessTree } from "@sema-agent/core";
+import { killProcessTree, type BackgroundHardKillOutcome } from "@sema-agent/core";
 export declare const IS_WIN32: boolean;
 export interface HostShell {
     shell: string;
@@ -59,8 +59,23 @@ 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)。⚠️ 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 可能已经是别人的):本函数只管打出去的那一枪。永不抛。
+ */
+export declare function hardKillGroupNow(pid: number): BackgroundHardKillOutcome;
 /**
  * SOFT kill (design D2 — the bg KillShell/timeout-wall first rung; the caller owns the grace→hard escalation
  * timer, unchanged). POSIX = `process.kill(-pid, "SIGTERM")` byte-identical (throws on dead group — the caller

package/dist/plugins/host-platform.js

@@ -46,6 +46,17 @@ export function killTreeHard(pid) {
     }
     process.kill(-pid, "SIGKILL");
 }
+export function hardKillGroupNow(pid) {
+    if (IS_WIN32)
+        return "no_pgid";
+    try {
+        process.kill(-pid, "SIGKILL");
+        return "killed";
+    }
+    catch (err) {
+        return err.code === "ESRCH" ? "already_gone" : "no_pgid";
+    }
+}
 export function killTreeSoft(pid) {
     if (IS_WIN32) {
         signalProcessTree(pid, "SIGTERM");

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

@@ -1,6 +1,10 @@
-import { FileError, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundPoll, type BackgroundSpawnOptions } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundHardKillOutcome, type BackgroundPoll, type BackgroundSpawnOptions } from "@sema-agent/core";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
+/** SIGTERM → grace → SIGKILL (no host isolation). 🔴 宽限的**唯一属主**:本 driver 的 `kill` 梯子用它排升级定时器;会话级收敛
+ *  (`background-session-reap.ts#reapSessionBackgroundHard`,DELETE 与停止口)在软面之后、硬面之前**等同一只**(车OL O1 —— 硬面不许把
+ *  这把梯子的用户面宽限取消),不另抄数。启动期读一次;`0` 被 `numEnvOr` 读作缺席(回落 1000),要几乎不等写 `1`。 */
+export declare const HOST_BG_KILL_GRACE_MS: number;
 /** Construction config for {@link RemoteHostExecutionEnv}. */
 export interface HostEnvConfig {
     /**
@@ -242,6 +246,15 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     private adoptRunningExec;
     pollBackground(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
     killBackground(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
+    /**
+     * S-745(core 7.32.0 #1107)—— `BackgroundShellCapability.killBackgroundNow` 座位:退出边界 / 会话收敛的**同步硬收**面经它对
+     * 本 env 的一行发**一枪组 SIGKILL**(pid 不出 env,调用方只握不透明的 shellId)。同步、永不抛、幂等;答 `killed` /
+     * `already_gone` / `no_pgid`(win32 恒 `no_pgid`)。从没起过 shell 的 env(`_bgManager` 未建)⇒ 这个 id 不是本 env 的 ⇒
+     * `already_gone`;**不**顺手新建 manager(拆除路径上不造东西,与 `disposeBackgroundShells` 同一条)。
+     * 本仓只有 host 车道实现它:e2b / k8s·kata / local-docker / ssh / device / adb 没有本机进程组可发,留空 ⇒ core 每行 `no_pgid`
+     * 并派普通 kill(车道矩阵钉:`test/background-hard-kill-s745.test.ts`)。
+     */
+    killBackgroundNow(shellId: BackgroundShellId): BackgroundHardKillOutcome;
     disposeBackgroundShells(opts?: {
         except?: readonly BackgroundShellId[];
     }): Promise<void>;