@sema-agent/server 7.150.0 → 7.152.0

package/dist/orchestration/workflow-park-decision.js

@@ -5,6 +5,14 @@ import { approvalPayloadFingerprint } from "../plugins/approval-payload-fingerpr
 import { createObjectColumnReader, isJsonObject } from "../plugins/sql-json-column.js";
 import { replayJsonlGuarded } from "../observability/corrupt-read-seat.js";
 import { FENCE_LANDED } from "../plugins/store-contracts.js";
+import { heldParksOf, readRunParks } from "./workflow-agent-session-index.js";
+import { recordWriterOf } from "./workflow-notify-journal.js";
+export function holderFenceAdmits(run, d, restated) {
+    const parks = readRunParks(run);
+    if (parks === undefined || !heldParksOf(d.runId, parks).some((p) => p.token === d.token))
+        return "not_held";
+    return restated ? "restated" : "land";
+}
 function seatName(v) {
     if (v === undefined)
         return "none";
@@ -14,7 +22,8 @@ function seatName(v) {
 export function parkDecisionStoreRefusal(seats) {
     const wanted = seats.workflowAgentSessionIndex !== undefined ? seats.runStore : undefined;
     const decisions = seats.workflowParkDecisions;
-    if (decisions?.claims === wanted)
+    const recordWriter = seats.workflowRunStore === undefined ? undefined : recordWriterOf(seats.workflowRunStore);
+    if (decisions?.claims === wanted && (decisions === undefined || decisions.records === recordWriter))
         return undefined;
     const pair = `run store: ${seatName(seats.runStore)}; workflow park decision store: ${decisions === undefined ? "none" : `${seatName(decisions)} bound to ${seatName(decisions.claims)}`}`;
     if (decisions === undefined) {
@@ -27,9 +36,14 @@ export function parkDecisionStoreRefusal(seats) {
             "a decision store is only read and written by that lane, which needs both the park index and the run store the decisions are fenced by; " +
             "wire the lane (park index and run store) or drop the decision store; refusing to start rather than keep a store no lane fences");
     }
-    return (`the workflow park decision store is not bound to this server's run store (${pair}) — ` +
-        "its writes are fenced by the run store it was built on, so a different run store means decisions recorded where the session claims are not checked; " +
-        "take runStore and workflowParkDecisions from the same store backend (run() and workflowParkDecisions()); refusing to start rather than record decisions the session claim cannot fence");
+    if (decisions.claims !== wanted) {
+        return (`the workflow park decision store is not bound to this server's run store (${pair}) — ` +
+            "its writes are fenced by the run store it was built on, so a different run store means decisions recorded where the session claims are not checked; " +
+            "take runStore and workflowParkDecisions from the same store backend (run() and workflowParkDecisions()); refusing to start rather than record decisions the session claim cannot fence");
+    }
+    return (`the workflow park decision store is not bound to the workflow record store this server writes run records through (workflow record writer: ${seatName(recordWriter)}; decision store's record fence: ${seatName(decisions.records)}) — ` +
+        "while the run that holds a card is running, a decision row is written in the same atomic step that checks the run's record still reads running and still holds the card, so the fence must be the store every record write goes through; " +
+        "pass the record store the workflow run store wraps to the store backend's workflowParkDecisions(); refusing to start rather than record decisions a run's end cannot be ordered against");
 }
 export function parkDecisionFingerprint(outcome, restatement) {
     const payload = approvalPayloadFingerprint({
@@ -76,13 +90,15 @@ function readRow(raw) {
 const LEDGER_LINE_SHAPE = { what: "a workflow park decision row", read: readRow };
 export class LocalWorkflowParkDecisionStore {
     claims;
+    records;
     fsyncEnabled;
     ledgerPath;
     gate;
     rows = new Map();
     log;
-    constructor(claims, root, fsyncEnabled = true) {
+    constructor(claims, records, root, fsyncEnabled = true) {
         this.claims = claims;
+        this.records = records;
         this.fsyncEnabled = fsyncEnabled;
         if (root === undefined) {
             this.ledgerPath = undefined;
@@ -92,14 +108,37 @@ export class LocalWorkflowParkDecisionStore {
         const dir = join(root, "workflow-park-decisions");
         ensureDir(dir);
         this.ledgerPath = join(dir, "decisions.jsonl");
-        const { records, gate } = replayJsonlGuarded(this.ledgerPath, "workflow-park-decisions", LEDGER_LINE_SHAPE);
-        this.gate = gate;
-        for (const d of records)
+        const replayed = replayJsonlGuarded(this.ledgerPath, "workflow-park-decisions", LEDGER_LINE_SHAPE);
+        this.gate = replayed.gate;
+        for (const d of replayed.records)
             this.rows.set(d.token, d);
     }
-    async record(decision) {
+    async record(decision, condition) {
+        this.gate?.assertUsable();
+        let superseded = false;
+        const held = this.claims.whileHoldingClaim(decision.hostSessionId, decision.deliveredTaskId, () => {
+            if (condition !== undefined && this.rows.get(decision.token)?.fingerprint !== condition.expect) {
+                superseded = true;
+                return FENCE_LANDED;
+            }
+            return this.landNow(decision);
+        });
+        return held && !superseded;
+    }
+    async recordForRunningHolder(decision, request) {
         this.gate?.assertUsable();
-        return this.claims.whileHoldingClaim(decision.hostSessionId, decision.deliveredTaskId, () => this.landNow(decision));
+        const fenced = await this.records.whileRunning(decision.runId, (run) => {
+            const admits = holderFenceAdmits(run, decision, request.restated);
+            if (admits !== "land")
+                return admits;
+            const existing = this.rows.get(decision.token);
+            if (existing === undefined) {
+                this.landNow(decision);
+                return "stands";
+            }
+            return existing.fingerprint === decision.fingerprint ? "stands" : "other_decision";
+        });
+        return fenced.running ? fenced.value : "not_running";
     }
     landNow(decision) {
         if (this.ledgerPath !== undefined) {

package/dist/orchestration/workflow-park-holder.d.ts

@@ -0,0 +1,65 @@
+/**
+ * **持有进程的拉取腿**:跑着一条持有停驻卡的 workflow run 的进程,在维护拍上读这些卡的决定行,把立住的决定在本地交给引擎(`redeemWorkflowParks`)。
+ *
+ * ## 为什么需要它
+ * 持有卡的 run 仍读作 `running` 时,决断落成一条决定行(记录栅栏,律的属主 = `workflow-park-decision.ts` 文件头)。引擎只收本进程里那条 run 的决定 ——
+ * 决断恰落在跑那条 run 的进程上 ⇒ 当场交(`/decide` 的本进程快路);落在别的副本上 ⇒ 行在库里,**没有任何一条本地事件**会把它交给持有进程。
+ * ⇒ 持有进程自己回头看行:搭维护拍(`REAP_INTERVAL_SEC`),不新开定时器族、不按副本路由(与审批族悬挂 ask 的跨副本执行通知同一条裁定)。
+ *
+ * ## 两件
+ *  · {@link HeldParksHere} —— **本进程执行器视图**:哪几条 run 的执行器在本进程里跑、它们此刻持有哪些 token。journaling 装饰器在本进程引擎每一笔**落成**的记录写上
+ *    刷新它(`parks[]` 里 `parkedBy === runId` 的条目);**只在执行器收场时删**(引擎的观察通道走完)。写抛 / CAS 输 / `parks[]` 读不出 ⇒ 不删、保留上一份 token
+ *    (引擎吞掉记录写失败照跑,「本进程写成功过」不等于执行器的寿命)。视图只选候选,判官是决定行 + 卡状态 + 引擎。
+ *  · {@link createWorkflowParkHolderPull} —— 拉取腿:每条候选 (run, token) 一次决定行主键读;有行 ⇒ 与起跑读者同一只逐行判(`deliverableEntryOf`:卡仍 pending ∧ 当下持有者
+ *    是这条 run)⇒ 在本地交给引擎;答词按 `holderPullDisposition` 处置(交上了 / 下一拍 / 交给收场送达)。每拍有帽、有墙钟预算、整数偏移轮转(与审批族悬挂轮询共用
+ *    {@link boundedRotation});截断那一拍响亮。每一读带期限,读失败 ⇒ 本拍跳过这条、F 类留痕(`server.workflow-park-holder.read-failed`)、下拍再来。
+ * 本进程没有执行中的持有停驻 run ⇒ 一拍零店读。
+ */
+import type { CheckpointToken, WorkflowRun, WorkflowRunStore } from "@sema-agent/core";
+import { type HeldWorkflowParkDecisionSources } from "../parked-decide.js";
+import { type WorkflowAgentSessionIndex } from "./workflow-agent-session-index.js";
+import type { WorkflowParkDecisionStore } from "./workflow-park-decision.js";
+/** 视图里的一条 run:它的 scope 与它此刻持有的 token(上一笔落成的写读出的那一份)。 */
+export interface HeldParkRun {
+    readonly runId: string;
+    readonly scope: string;
+    readonly tokens: readonly CheckpointToken[];
+}
+/**
+ * 本进程执行器视图(见文件头)。`ended` = 「这条 run 的执行器在本进程里收场了」的读法(缺省 = 引擎观察通道走完;测试换成可控的那一只)。
+ * 登记是惰性的:一条 run 第一次有一笔落成的写持有 token 时才登记并挂收场;此前它不在视图里(没有持有停驻就没有可拉的东西)。
+ */
+export declare class HeldParksHere {
+    private readonly ended;
+    private readonly runs;
+    constructor(ended?: (runId: string, scope: string) => Promise<void>);
+    /** journaling 装饰器在本进程引擎的一笔**落成**的记录写之后调(put 落成 / update CAS 赢)。`parks[]` 读不出 ⇒ 保留上一份(不删)。 */
+    noteLanded(runId: string, run: WorkflowRun): void;
+    /** 此刻的候选(快照;顺序 = 登记序)。 */
+    candidates(): HeldParkRun[];
+}
+/** 拉取腿每拍的帽与墙钟预算(审批族悬挂轮询同一尺度:常态几条,帽与预算是退化态的护栏)。每读期限与悬挂轮询的点读同值。 */
+export declare const HOLDER_PULL_MAX_PER_TICK = 64;
+export declare const HOLDER_PULL_BUDGET_MS = 5000;
+export declare const HOLDER_PULL_READ_TIMEOUT_MS = 2000;
+export interface WorkflowParkHolderPullDeps {
+    readonly held: HeldParksHere;
+    readonly decisions: WorkflowParkDecisionStore;
+    readonly checkpointStore: NonNullable<HeldWorkflowParkDecisionSources["checkpointStore"]>;
+    readonly workflowAgentSessionIndex: WorkflowAgentSessionIndex;
+    readonly workflowRunStore: Pick<WorkflowRunStore, "get">;
+    readonly warn?: (event: string, fields: Record<string, unknown>) => void;
+    readonly now?: () => number;
+}
+/** 一拍的读数:`polled` = 真去读了决定行的候选数;`delivered` / `nextBeat` / `left` = 有可交付行的候选按处置计;`backlog` / `truncated` = 帽与预算截断。 */
+export interface HolderPullTally {
+    readonly polled: number;
+    readonly delivered: number;
+    readonly nextBeat: number;
+    readonly left: number;
+    readonly backlog: number;
+    readonly truncated: boolean;
+}
+/** 拉取腿(维护拍调;调用方守 in-flight,拍间不叠)。 */
+export declare function createWorkflowParkHolderPull(deps: WorkflowParkHolderPullDeps): () => Promise<HolderPullTally>;
+//# sourceMappingURL=workflow-park-holder.d.ts.map

package/dist/orchestration/workflow-park-holder.js

@@ -0,0 +1,98 @@
+import { boundedRotation } from "../bounded-rotation.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { deliverableEntryOf, holderPullDisposition, redeemHere, runChannelEnded } from "../parked-decide.js";
+import { heldParksOf, readRunParks } from "./workflow-agent-session-index.js";
+export class HeldParksHere {
+    ended;
+    runs = new Map();
+    constructor(ended = runChannelEnded) {
+        this.ended = ended;
+    }
+    noteLanded(runId, run) {
+        const parks = readRunParks(run);
+        if (parks === undefined)
+            return;
+        const tokens = heldParksOf(runId, parks).map((p) => p.token);
+        if (this.runs.has(runId)) {
+            this.runs.set(runId, { runId, scope: run.scope, tokens });
+            return;
+        }
+        if (tokens.length === 0)
+            return;
+        const entry = { runId, scope: run.scope, tokens };
+        this.runs.set(runId, entry);
+        const drop = () => void this.runs.delete(runId);
+        void this.ended(runId, run.scope).then(drop, (err) => {
+            recordFailOpen("server.workflow-park-holder.read-failed", `step=channel runId=${runId} err=${err instanceof Error ? err.message : String(err)}`);
+            drop();
+        });
+    }
+    candidates() {
+        return [...this.runs.values()];
+    }
+}
+export const HOLDER_PULL_MAX_PER_TICK = 64;
+export const HOLDER_PULL_BUDGET_MS = 5_000;
+export const HOLDER_PULL_READ_TIMEOUT_MS = 2_000;
+function within(p, ms, what) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} did not answer within ${ms}ms`)), ms);
+        timer.unref?.();
+    });
+    p.catch(() => undefined);
+    return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+}
+export function createWorkflowParkHolderPull(deps) {
+    const cursor = { offset: 0 };
+    const sources = { checkpointStore: deps.checkpointStore, workflowAgentSessionIndex: deps.workflowAgentSessionIndex, workflowRunStore: deps.workflowRunStore };
+    return async () => {
+        const items = deps.held.candidates().flatMap((r) => r.tokens.map((token) => ({ runId: r.runId, scope: r.scope, token })));
+        let delivered = 0;
+        let nextBeat = 0;
+        let left = 0;
+        const { visited, backlog, truncated } = await boundedRotation([{ items, cursor }], { maxPerTick: HOLDER_PULL_MAX_PER_TICK, budgetMs: HOLDER_PULL_BUDGET_MS }, async ({ runId, scope, token }) => {
+            let row;
+            try {
+                row = await within(deps.decisions.get(token), HOLDER_PULL_READ_TIMEOUT_MS, "workflow park decision read");
+            }
+            catch (err) {
+                recordFailOpen("server.workflow-park-holder.read-failed", `step=decision runId=${runId} err=${err instanceof Error ? err.message : String(err)}`);
+                return;
+            }
+            if (row === null)
+                return;
+            let deliverable;
+            try {
+                deliverable = await within(deliverableEntryOf(sources, row), HOLDER_PULL_READ_TIMEOUT_MS, "workflow park card read");
+            }
+            catch (err) {
+                recordFailOpen("server.workflow-park-holder.read-failed", `step=card runId=${runId} err=${err instanceof Error ? err.message : String(err)}`);
+                return;
+            }
+            if (deliverable.kind !== "deliverable" || deliverable.entry.runId !== runId)
+                return;
+            const disposition = holderPullDisposition(await redeemHere(runId, scope, { token, outcome: row.outcome }), runId);
+            switch (disposition) {
+                case "delivered":
+                    delivered++;
+                    return;
+                case "next_beat":
+                    nextBeat++;
+                    return;
+                case "left":
+                    left++;
+                    return;
+                default: {
+                    const unhandled = disposition;
+                    throw new Error(`unhandled holder pull disposition: ${String(unhandled)}`);
+                }
+            }
+        }, deps.now);
+        if (truncated) {
+            deps.warn?.("workflow_park_holder_pull_truncated", { polled: visited, delivered, backlog, maxPerTick: HOLDER_PULL_MAX_PER_TICK, budgetMs: HOLDER_PULL_BUDGET_MS, resumeFromOffset: cursor.offset });
+        }
+        return { polled: visited, delivered, nextBeat, left, backlog, truncated };
+    };
+}
+//# sourceMappingURL=workflow-park-holder.js.map

package/dist/orchestration/workflow-record-fence.d.ts

@@ -0,0 +1,36 @@
+/**
+ * **workflow 记录的进程内记录栅栏**(local 后端:File / InMemory 记录店;SQL 孪生是 `SqlWorkflowRunStore.whileRunning` 的行锁事务)。
+ *
+ * ## 为什么在基店外包一层
+ * 持有一张停驻卡的 run 仍读作 `running` 时,决定行落在「这条 run 的记录仍在跑、仍持有这张卡」的原子段里(律的属主 = `workflow-park-decision.ts` 文件头)。
+ * 这一段要与这条 run 的**每一笔**记录写串行 —— 否则「判出在跑 → 落行」之间插进引擎的终态写,run 收场送达读不到这一行,决定被丢在已收场的 run 上。
+ * 本服务的记录写者有两个:引擎(经 journaling 装饰器 `JournalingWorkflowRunStore`)与 notify 门的收养翻转(`WorkflowNotifyGate.recover` 经基店翻 `running → failed`);
+ * core File 店的锁是它私有的。⇒ 互斥不能只放在 journaling 装饰器上:放在**基店外的这一只装饰器**里,两只写者都经它写,它就是本进程全部记录写者的同一只互斥。
+ *
+ * ## 律
+ * 按 runId 互斥:`put` / `update` / {@link FencedWorkflowRecordStore.whileRunning} 对同一条 run 一个接一个(先到先走);读(`get` / `listByScope`)与收割(只删终态行)
+ * 不进互斥(本装饰器不出按会话删那一口:与它所在的 journaling 装饰器同一个答案)。`whileRunning` 的 `fn` 是同步的(型上不许把写挪到段外),段里不许再经本店写同一条 run(会自锁)。
+ * 互斥只排同一进程里的写;SQL 后端的跨副本串行由行锁担(那里没有本装饰器)。
+ */
+import type { WorkflowRun, WorkflowRunStore } from "@sema-agent/core";
+import type { InProcessRecordFence, RecordFenced } from "./workflow-park-decision.js";
+export declare class FencedWorkflowRecordStore implements WorkflowRunStore, InProcessRecordFence {
+    private readonly inner;
+    /** runId → 这条 run 上最后一段的落定(链尾);链空了就摘掉(有界 = 此刻有段在排的 run 数)。 */
+    private readonly tails;
+    constructor(inner: WorkflowRunStore);
+    /** 同一条 run 上的段一个接一个:等前一段落定(成败都算落定)再走本段。 */
+    private serial;
+    put(id: string, run: WorkflowRun): Promise<void>;
+    update(id: string, scope: string, run: WorkflowRun, expect?: {
+        rev: number;
+    }): Promise<boolean>;
+    whileRunning<T>(runId: string, fn: (run: WorkflowRun) => T): Promise<RecordFenced<T>>;
+    get(id: string): Promise<WorkflowRun | null>;
+    listByScope(...args: Parameters<WorkflowRunStore["listByScope"]>): ReturnType<WorkflowRunStore["listByScope"]>;
+    reap(scope: string, now: number, opts?: {
+        maxAgeMs?: number;
+        keep?: number;
+    }): Promise<number>;
+}
+//# sourceMappingURL=workflow-record-fence.d.ts.map

package/dist/orchestration/workflow-record-fence.js

@@ -0,0 +1,42 @@
+export class FencedWorkflowRecordStore {
+    inner;
+    tails = new Map();
+    constructor(inner) {
+        this.inner = inner;
+    }
+    serial(runId, segment) {
+        const before = this.tails.get(runId) ?? Promise.resolve();
+        const result = before.then(segment);
+        const tail = result.then(() => undefined, () => undefined);
+        this.tails.set(runId, tail);
+        void tail.then(() => {
+            if (this.tails.get(runId) === tail)
+                this.tails.delete(runId);
+        });
+        return result;
+    }
+    put(id, run) {
+        return this.serial(id, () => this.inner.put(id, run));
+    }
+    update(id, scope, run, expect) {
+        return this.serial(id, () => this.inner.update(id, scope, run, expect));
+    }
+    whileRunning(runId, fn) {
+        return this.serial(runId, async () => {
+            const run = await this.inner.get(runId);
+            if (run === null || run.status !== "running")
+                return { running: false };
+            return { running: true, value: fn(run) };
+        });
+    }
+    get(id) {
+        return this.inner.get(id);
+    }
+    listByScope(...args) {
+        return this.inner.listByScope(...args);
+    }
+    reap(scope, now, opts) {
+        return this.inner.reap(scope, now, opts);
+    }
+}
+//# sourceMappingURL=workflow-record-fence.js.map

package/dist/outbound-dispatcher.d.ts

@@ -163,18 +163,45 @@ export declare function createOutboundDispatcher(env?: NodeJS.ProcessEnv): {
     env: OutboundProxyEnv;
 };
 /**
- * 建连期失败码 —— **闭集**(码 → 给运维的一句读法)。只收**只可能**在建立连接时出现的码:undici 的建连截止
+ * 建连失败**类** —— 闭集(三类),说「这一次建连失败的出路在哪一头」,由 {@link OUTBOUND_CONNECT_FAILURE_CODES} 的每个码各认一类(`failureClass`):
+ *  · `refused`     —— 对端把连接拒了(那个地址上没人监听 / 防火墙复位):出路在**地址那一头**(服务在不在、地址配得对不对);
+ *  · `unresolved`  —— 主机名解析不了(地址写错,或 DNS / VPN 不通):出路在**地址写法与名字解析**;
+ *  · `unreachable` —— 建连没在时限内完成 / 无路由 / 网络不可达:出路在**网络路径**(VPN / 代理)。
+ * 建连失败的出路取自这三类上的一张表({@link MODEL_UNREACHABLE_REMEDIES},选句 {@link connectFailureRemedyOf}):用户面通告 `server.model_unreachable`
+ * (`model-unreachable-notice.ts`)与运维日志 `outbound_connect_failed` 的 `hint` 同读它,都不另写码 → 类的映射。
+ */
+export type OutboundConnectFailureClass = "refused" | "unresolved" | "unreachable";
+/**
+ * 建连期失败码 —— **闭集**(码 → { 失败类,给运维的一句读法 })。只收**只可能**在建立连接时出现的码:undici 的建连截止
  * (`UND_ERR_CONNECT_TIMEOUT`,TCP + TLS 没在传输层的建连时限内完成)与 OS 的拒连 / 解析不了 / 无路由。可能出现在**已建立**
  * 连接上的码(`ECONNRESET` / `ETIMEDOUT` / `UND_ERR_SOCKET`)刻意不收 —— 它们判不出「够不着」,收进来就会把一次中途断流
- * 说成「模型不可达、去查 VPN」。加一个码 = 加一行并写明它为什么只可能在建连时出现。
+ * 说成「模型不可达、去查 VPN」。加一个码 = 加一行并写明它为什么只可能在建连时出现、它属哪一失败类(类缺 ⇒ 编译红)。
  */
 export declare const OUTBOUND_CONNECT_FAILURE_CODES: {
-    readonly UND_ERR_CONNECT_TIMEOUT: "the TCP + TLS connect did not complete within the transport's connect deadline";
-    readonly ECONNREFUSED: "the peer actively refused the connection (nothing listening there, or a firewall reset it)";
-    readonly ENOTFOUND: "the host name did not resolve";
-    readonly EAI_AGAIN: "the DNS lookup failed temporarily";
-    readonly EHOSTUNREACH: "there is no route to the host";
-    readonly ENETUNREACH: "the network is unreachable";
+    readonly UND_ERR_CONNECT_TIMEOUT: {
+        readonly failureClass: "unreachable";
+        readonly reading: "the TCP + TLS connect did not complete within the transport's connect deadline";
+    };
+    readonly ECONNREFUSED: {
+        readonly failureClass: "refused";
+        readonly reading: "the peer actively refused the connection (nothing listening there, or a firewall reset it)";
+    };
+    readonly ENOTFOUND: {
+        readonly failureClass: "unresolved";
+        readonly reading: "the host name did not resolve";
+    };
+    readonly EAI_AGAIN: {
+        readonly failureClass: "unresolved";
+        readonly reading: "the DNS lookup failed temporarily";
+    };
+    readonly EHOSTUNREACH: {
+        readonly failureClass: "unreachable";
+        readonly reading: "there is no route to the host";
+    };
+    readonly ENETUNREACH: {
+        readonly failureClass: "unreachable";
+        readonly reading: "the network is unreachable";
+    };
 };
 export type OutboundConnectFailureCode = keyof typeof OUTBOUND_CONNECT_FAILURE_CODES;
 /** 一次建连失败的事实(纯数据:日志行、诊断段、模型调用结局同一份)。`proxyInUse` = 这一跳走的代理**变量名**(不打值),直连 ⇒ `null`。 */
@@ -183,6 +210,42 @@ export interface OutboundConnectFailure {
     readonly code: OutboundConnectFailureCode;
     readonly proxyInUse: string | null;
 }
+/**
+ * 一个码的失败类({@link OutboundConnectFailureClass});闭集之外的码 ⇒ `undefined`(调用方必须处置这一臂,不是静默的一类)。纯函数、不抛。
+ * 类型上到不了 `undefined`(`OutboundConnectFailure.code` 是闭集型),但读者收 `string`:手造的失败事实、将来码型变宽,都落在这一臂上而不是 `undefined.failureClass` 抛。
+ */
+export declare function connectFailureClassOf(code: string): OutboundConnectFailureClass | undefined;
+/**
+ * 一次建连失败的**出路** —— 同一件事的两种写法:`advice` 是给人读的一句(用户面通告的正文末句),`remedy` 是短句(通告的 `detail.remedy`,
+ * 也是运维日志 `outbound_connect_failed` 的 `hint` 尾句)。三张脸读**同一行**,不各写各的。
+ */
+export interface ConnectFailureRemedy {
+    readonly advice: string;
+    readonly remedy: string;
+}
+/**
+ * **失败类上的一张闭表**(键集 = {@link OutboundConnectFailureClass},加一类不补一行 ⇒ 编译红)。行说的是**模型端点**(端点地址、模型网关地址配置):
+ * 用户面通告只为模型调用铸,运维日志只在失败的请求属一次模型调用时读类行。契约附录 D.3 与 USAGE 列的就是这三行
+ * (`test/model-unreachable-notice.test.ts` 的「文书与表同源」一格读本表对文书)。
+ */
+export declare const MODEL_UNREACHABLE_REMEDIES: {
+    readonly refused: {
+        readonly advice: "Check that a service is listening at that address and that the model gateway address is configured correctly.";
+        readonly remedy: "check that a service is listening at the model endpoint address; check the model gateway address configuration";
+    };
+    readonly unresolved: {
+        readonly advice: "Check that the model gateway address is written correctly in the configuration and that DNS (and the VPN, if one is in use) can resolve it.";
+        readonly remedy: "check the model gateway address configuration; check DNS / VPN";
+    };
+    readonly unreachable: ConnectFailureRemedy;
+};
+/**
+ * 选句 —— **唯一一处**(用户面通告与运维日志 `hint` 同调),规则先到先得:
+ *  ① 失败的请求不属一次模型调用(`request: "other"`:中心、工具、MCP …)⇒ 通用句(类行说的是模型端点与网关地址配置,对别的主机不成立);
+ *  ② 这一跳走了代理(`proxyInUse` 非空)⇒ 通用句(拒连 / 解析不了可能是**代理**那一头的事,出路仍是「查 VPN / 代理」);
+ *  ③ 否则按失败类读闭表;码不在闭集里(类型上到不了,读者收 `string`)⇒ 通用句 —— 声明的未分类臂,不抛、不静默。
+ */
+export declare function connectFailureRemedyOf(failure: OutboundConnectFailure, request: "model_call" | "other"): ConnectFailureRemedy;
 /** 一只请求错误的建连期失败码与它走的代理变量名(`undefined` = 不是建连失败)。原句不在这里 —— 它只给运维日志。 */
 export declare function classifyOutboundConnectFailure(error: unknown): {
     readonly code: OutboundConnectFailureCode;

package/dist/outbound-dispatcher.js

@@ -339,14 +339,55 @@ export function createOutboundDispatcher(env = process.env) {
     return { dispatcher: new OutboundDispatcher(new Agent(), proxied), posture: postureOf(v), env: v };
 }
 export const OUTBOUND_CONNECT_FAILURE_CODES = {
-    UND_ERR_CONNECT_TIMEOUT: "the TCP + TLS connect did not complete within the transport's connect deadline",
-    ECONNREFUSED: "the peer actively refused the connection (nothing listening there, or a firewall reset it)",
-    ENOTFOUND: "the host name did not resolve",
-    EAI_AGAIN: "the DNS lookup failed temporarily",
-    EHOSTUNREACH: "there is no route to the host",
-    ENETUNREACH: "the network is unreachable",
+    UND_ERR_CONNECT_TIMEOUT: { failureClass: "unreachable", reading: "the TCP + TLS connect did not complete within the transport's connect deadline" },
+    ECONNREFUSED: { failureClass: "refused", reading: "the peer actively refused the connection (nothing listening there, or a firewall reset it)" },
+    ENOTFOUND: { failureClass: "unresolved", reading: "the host name did not resolve" },
+    EAI_AGAIN: { failureClass: "unresolved", reading: "the DNS lookup failed temporarily" },
+    EHOSTUNREACH: { failureClass: "unreachable", reading: "there is no route to the host" },
+    ENETUNREACH: { failureClass: "unreachable", reading: "the network is unreachable" },
 };
 const isConnectFailureCode = (c) => typeof c === "string" && Object.hasOwn(OUTBOUND_CONNECT_FAILURE_CODES, c);
+export function connectFailureClassOf(code) {
+    return isConnectFailureCode(code) ? OUTBOUND_CONNECT_FAILURE_CODES[code].failureClass : undefined;
+}
+const NETWORK_PATH_REMEDY = {
+    advice: "Check the VPN / proxy; if the proxy changed since the server started, restart it (proxy settings are read once at startup).",
+    remedy: "check VPN / proxy; restart if the proxy changed since boot",
+};
+export const MODEL_UNREACHABLE_REMEDIES = {
+    refused: {
+        advice: "Check that a service is listening at that address and that the model gateway address is configured correctly.",
+        remedy: "check that a service is listening at the model endpoint address; check the model gateway address configuration",
+    },
+    unresolved: {
+        advice: "Check that the model gateway address is written correctly in the configuration and that DNS (and the VPN, if one is in use) can resolve it.",
+        remedy: "check the model gateway address configuration; check DNS / VPN",
+    },
+    unreachable: NETWORK_PATH_REMEDY,
+};
+export function connectFailureRemedyOf(failure, request) {
+    switch (request) {
+        case "other":
+            return NETWORK_PATH_REMEDY;
+        case "model_call":
+            break;
+        default: {
+            const unhandled = request;
+            throw new Error(`connectFailureRemedyOf: unhandled request kind ${String(unhandled)}`);
+        }
+    }
+    if (failure.proxyInUse !== null)
+        return NETWORK_PATH_REMEDY;
+    const failureClass = connectFailureClassOf(failure.code);
+    switch (failureClass) {
+        case undefined:
+            return NETWORK_PATH_REMEDY;
+        case "refused":
+        case "unresolved":
+        case "unreachable":
+            return MODEL_UNREACHABLE_REMEDIES[failureClass];
+    }
+}
 function scanConnectFailure(error) {
     const queue = [error];
     let proxyInUse = null;
@@ -438,7 +479,7 @@ function startConnectObserver(logger, nowMs) {
             ...(found.proxyHop !== null ? { proxyHop: found.proxyHop } : {}),
             proxyReadAtMs: current.proxyReadAtMs,
             sinceBootMs: Math.round(process.uptime() * 1000),
-            hint: `${OUTBOUND_CONNECT_FAILURE_CODES[failure.code]} — ${failure.proxyInUse !== null ? `this hop went through the proxy from ${failure.proxyInUse} (read once at boot)` : "this hop was a direct connection"}; if the VPN / proxy changed since boot, restart the server so it re-reads HTTP(S)_PROXY / NO_PROXY`,
+            hint: `${OUTBOUND_CONNECT_FAILURE_CODES[failure.code].reading} — ${failure.proxyInUse !== null ? `this hop went through the proxy from ${failure.proxyInUse} (read once at boot)` : "this hop was a direct connection"}; ${connectFailureRemedyOf(failure, call !== undefined ? "model_call" : "other").remedy}`,
         });
         if (call !== undefined)
             call.last = { kind: "connect_failed", failure };

package/dist/owner-faces.d.ts

@@ -52,7 +52,7 @@ export interface Caller {
     readonly principalRequired: boolean;
     readonly multiTenant: boolean;
 }
-/** 单机形下 core 写侧 `spec.principal ?? "default"` 铸出的租户键(壳随请求带的那一个):`j4` 一格的调用方条件。它是单机形的真租户键,不是哨兵。 */
+/** 单机形下 core 写侧给匿名任务落的那一格租户键(壳随请求带的那一个;换算 = `engine-identity.ts` 的 `engineScopeOf`):`j4` 一格的调用方条件。它是单机形的真租户键,不是哨兵。 */
 export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
 /**
  * 🔴 **调用方与行属主之间唯一的桥**:两个品牌在类型上不可比(`Subject === DurableOwnerKey` 编译红),只在这里按字节比。调用方一侧是**主体**(分区键):
@@ -77,7 +77,7 @@ export declare function ownerKeyOf(persisted: string | null): DurableOwnerKey |
  */
 export declare function ownerCellOf(owner: string | null | undefined): SessionOwnerCell | undefined;
 /**
- * **收纯串的协议内部口**的主体读法(恢复管线;不是铸点):活登记的应答口 / 按问读口(`tool-approval.ts` 协调器)、活问的应答口(`elicitation.ts` / `question.ts`)、
+ * **收纯串的协议内部口**的主体读法(恢复管线;不是铸点):活登记的按问读口 / 决断口的停驻赎回席(`tool-approval.ts` 协调器)、活问的应答口(`elicitation.ts` / `question.ts`)、
  * 迟到决定的赎回席(`http/approval-sweeps.ts`)、停驻完成收件箱的排空门、peer 目录席 —— 这几扇口经纯串收「上游已铸的那一只主体」(HTTP 路由层的 `gatedSubject`
  * 读数、续跑腿交来的 run 属主、引擎交来的 scope)。串就是一只已落成字节的属主键,按 {@link ownerKeyOf} → `partsOf` 恢复(坏形的 `_scn:` 串响亮抛),
  * 不重判保留前缀 / 在册 / 宽度(那三判只在外部管线)。公开面改收 `Subject` 品牌是另一车(这几扇口的测试调用面数以百计)。