@twinsearth/dsh-master 3.3.0 → 3.3.1

package/dist-host/cost/index.js

@@ -15,14 +15,16 @@ import { createAuditChain } from "./audit.js";
 import { createAttribution } from "./attribution.js";
 import { createCostBus } from "./bus.js";
 import { createHostSurfaceAdapter } from "./host-surface.js";
+import { createFangRelay } from "./fang-relay.js";
 import { buildSavingsReport, classifyEntry } from "./report.js";
 import { buildMetricsReport, METRIC_KEYS, SUCCESS_REGRESSION_PP } from "./metrics.js";
 import { MODULE_MANIFESTS, MODULE_IDS, validateManifests } from "./modules/manifests.js";
 import { buildLedgerReport, formatLedgerReport, parseLedgerJsonl } from "./ledger-report.js";
 import { buildToolFaceReport, planToolFace } from "./toolface.js";
 import { buildReuseReport, formatReuseReport } from "./reuse-report.js";
-export { createLedger, createBudget, createPolicy, createAuditChain, createAttribution, createCostBus, createHostSurfaceAdapter, buildSavingsReport, classifyEntry, buildMetricsReport, METRIC_KEYS, SUCCESS_REGRESSION_PP, MODULE_MANIFESTS, MODULE_IDS, validateManifests, buildLedgerReport, formatLedgerReport, parseLedgerJsonl, buildToolFaceReport, planToolFace, buildReuseReport, formatReuseReport };
+export { createLedger, createBudget, createPolicy, createAuditChain, createAttribution, createCostBus, createHostSurfaceAdapter, createFangRelay, buildSavingsReport, classifyEntry, buildMetricsReport, METRIC_KEYS, SUCCESS_REGRESSION_PP, MODULE_MANIFESTS, MODULE_IDS, validateManifests, buildLedgerReport, formatLedgerReport, parseLedgerJsonl, buildToolFaceReport, planToolFace, buildReuseReport, formatReuseReport };
 export * from "./types.js";
+export { RELAY_PEERS, RELAY_DEFAULTS, createFangRelayFromContext, createRelayClient } from "./fang-relay.js";
 /**
  * @param {{
  *   mode?: string, allowlist?: string[] | {forks?:string[],tasks?:string[],tags?:string[],tools?:string[]},
@@ -30,6 +32,7 @@ export * from "./types.js";
  *   budgetLimits?: Array<{unit:string, limitTokens?:number, limitCost?:number, onExhaust?:string, degradeTo?:string}>,
  *   degradeModels?: string[],
  *   now?: () => number, maxEntries?: number, maxRecords?: number,
+ *   relay?: object, relayClient?: object|null, relayOptions?: object, relayAutoAttach?: boolean,
  * }} [options]
  */
 export function createCostSystem(options = {}) {
@@ -46,6 +49,21 @@ export function createCostSystem(options = {}) {
     });
     const attribution = createAttribution({ ledger, now });
     const bus = createCostBus({ now, maxEvents: options.maxBusEvents, relays: options.relays });
+    /**
+     * §5.6 / M5：瓮城回流出口。
+     * 传入 `relay`（已有适配器）则复用；否则用 `relayClient` 现造一个。
+     * 没有客户端时出口状态是 `relay-client-absent` —— 显式不可用，不是“探测中”。
+     */
+    const relay = options.relay && typeof options.relay.status === 'function'
+        ? options.relay
+        : createFangRelay({ client: options.relayClient ?? null, now, ...(options.relayOptions && typeof options.relayOptions === 'object' ? options.relayOptions : {}), logger: options.logger });
+    // 默认把出口挂到总线；测试可关掉自动挂载，手动投递。
+    if (options.relayAutoAttach !== false && typeof relay.attach === 'function') {
+        try {
+            relay.attach(bus);
+        }
+        catch { /* 回流挂载失败不影响记账 */ }
+    }
     /** 宿主会话工具面适配器（可选；默认关闭，不依赖任何第三方插件）。 */
     const hostSurface = createHostSurfaceAdapter({
         ledger,
@@ -267,6 +285,19 @@ export function createCostSystem(options = {}) {
     function subscribe(listener) {
         return bus.subscribe(listener);
     }
+    /** §5.6：探测回流对端（hello 协商 + relay 状态），结果并入 `status().relay`。 */
+    async function relayProbe(input = {}) {
+        return await relay.probe({ force: input.force === true });
+    }
+    /** §5.6：投递当前队列里的回流事件；返回回执摘要（不吞错，不谎报送达）。 */
+    async function relayFlush() {
+        if (typeof relay.flush !== 'function')
+            return { ok: false, code: 'relay-flush-unsupported' };
+        return await relay.flush();
+    }
+    function relayStatus() {
+        return relay.status();
+    }
     function status() {
         const ledgerSnapshot = ledger.snapshot();
         const auditVerify = audit.verify();
@@ -290,6 +321,8 @@ export function createCostSystem(options = {}) {
                 unattributedProjectedTotal: attributionSnapshot.unattributedProjectedTotal,
             },
             bus: { count: busSnapshot.count, dropped: busSnapshot.dropped, subscribers: busSnapshot.subscribers, relays: busSnapshot.relays },
+            /** §5.6 / M5：瓮城回流出口的真实状态（可达则 available:true + 对端自报 peer）。 */
+            relay: relay.status(),
             degraded: {
                 modules: [...degradedByModule.values()].map((item) => ({ ...item, phases: { ...item.phases } })),
                 occurrences: [...degradedByModule.values()].reduce((sum, item) => sum + item.occurrences, 0),
@@ -308,5 +341,5 @@ export function createCostSystem(options = {}) {
             hostSurface: hostSurface.status(),
         });
     }
-    return Object.freeze({ ledger, budget, policy, audit, attribution, bus, hostSurface, recordUsage, authorize, attribute, attributeTotal, substitute, trace, degraded, query, replay, savingsReport, metrics, ledgerReport, subscribe, status });
+    return Object.freeze({ ledger, budget, policy, audit, attribution, bus, hostSurface, relay, recordUsage, authorize, attribute, attributeTotal, substitute, trace, degraded, query, replay, savingsReport, metrics, ledgerReport, subscribe, status, relayProbe, relayFlush, relayStatus });
 }

package/dist-host/cost/milestones.js

@@ -24,6 +24,12 @@ export const MILESTONE_IDS = Object.freeze(['M1', 'M2', 'M3', 'M4', 'M5']);
 export const M3_MIN_SAMPLES = 20;
 /** M4 放行前要求的最小守卫准确率（与 ENFORCE_GATE.minAccuracy 一致）。 */
 export const M3_MIN_ACCURACY = 0.98;
+/**
+ * M5 回流放行条件：至少 3 条事件拿到对端回执，且对端自报身份在白名单内。
+ * 自环（同一进程里服务端+客户端）与未知 peer 一律不算达标。
+ */
+export const M5_MIN_RELAY_EVENTS = 3;
+export const M5_RELAY_PEERS = Object.freeze(['dsh-fang-bundle', 'contract-server']);
 export const MILESTONES = Object.freeze([
     Object.freeze({
         id: 'M1',
@@ -74,13 +80,16 @@ export const MILESTONES = Object.freeze([
  *   files?: string[],                       // 仓库里实际存在的文件（相对路径）
  *   guard?: {samples?: number, accuracy?: number},   // M3 的守卫准确率数据（来自 shadow 报告）
  *   forkExperiment?: {ok?: boolean},        // M4 的成功率对照（来自 gate 的 G5）
- *   fangRelay?: {available?: boolean},      // 瓮城回流通道（本会话范围内恒为不可用）
+ *   fangRelay?: {available?: boolean, peer?: string, events?: number,
+ *                sameProcess?: boolean, transport?: string, contractVersion?: string,
+ *                reason?: string},          // M5 的回流对端证据（独立进程实测）
  * }} evidence
  */
 export function evaluateMilestones(evidence = {}) {
     const files = new Set(Array.isArray(evidence.files) ? evidence.files : []);
     const rows = [];
     const done = new Set();
+    let relayEvidence = null;
     for (const milestone of MILESTONES) {
         const missingImplementation = milestone.implementation.filter((file) => !files.has(file));
         const missingTests = milestone.tests.filter((file) => !files.has(file));
@@ -119,11 +128,34 @@ export function evaluateMilestones(evidence = {}) {
                     reasons.push('effect-needs-fork-success-comparison');
             }
             else if (milestone.id === 'M5') {
-                // 面板 + 冻结清单可测；瓮城回流在本会话范围内明确不可用（不伪装）
-                const relayOk = evidence?.fangRelay?.available === true;
-                effect = relayOk ? 'verified' : 'unmeasured';
-                if (!relayOk)
-                    reasons.push('fang-relay-out-of-scope');
+                // 回流必须有**对端回执**才算达标：可用 + 非自环 + 对端自报身份在白名单 + 至少 3 条事件。
+                const relay = evidence?.fangRelay && typeof evidence.fangRelay === 'object' ? evidence.fangRelay : null;
+                const available = relay?.available === true;
+                const peer = String(relay?.peer ?? '');
+                const events = Math.max(0, Number(relay?.events ?? 0) || 0);
+                if (!available) {
+                    reasons.push(`fang-relay-unavailable:${String(relay?.reason ?? 'not-provided')}`);
+                }
+                else if (relay?.sameProcess === true) {
+                    reasons.push('fang-relay-self-loop');
+                }
+                else if (!M5_RELAY_PEERS.includes(peer)) {
+                    reasons.push(`fang-relay-peer-invalid:${peer || 'missing'}`);
+                }
+                else if (events < M5_MIN_RELAY_EVENTS) {
+                    reasons.push(`fang-relay-no-receipts(events=${events})`);
+                }
+                else {
+                    effect = 'verified';
+                }
+                relayEvidence = Object.freeze({
+                    available,
+                    peer: peer || null,
+                    events,
+                    sameProcess: relay?.sameProcess === true,
+                    transport: relay?.transport ?? null,
+                    contractVersion: relay?.contractVersion ?? relay?.peerContractVersion ?? null,
+                });
             }
         }
         const status = !implemented
@@ -141,6 +173,12 @@ export function evaluateMilestones(evidence = {}) {
             effect,
             status,
             reasons,
+            /** M5：回流对端证据（peer 自报 + 事件数 + 是否自环）；其它阶段为 null。 */
+            relay: relayEvidence,
+            /** 剩余缺口说明（不隐藏）。 */
+            notes: milestone.id === 'M5' && relayEvidence?.peer === 'contract-server'
+                ? ['peer=contract-server：契约对端独立进程实测，dsh-fang-bundle 采用 contract 1.1 后应变为 peer=dsh-fang-bundle']
+                : [],
         }));
         if (status === 'done')
             done.add(milestone.id);

package/dist-host/kernel.js

@@ -7,7 +7,7 @@
  * 与瓮城 dsh-Fang 的协作只走 DSH 服务键，不 import fang 代码。
  */
 import crypto from 'node:crypto';
-export const MASTER_VERSION = '3.3.0';
+export const MASTER_VERSION = '3.3.1';
 export const FANG_CONTRACT_MIN = '3.1.14';
 export const SERVICE = Object.freeze({
     master: 'dshMaster',

package/dist-host/plugins/cost-optimizer.js

@@ -16,7 +16,7 @@
  * 角色：仍只允许 fork（分身生产盘）。
  */
 import { OPTIONAL_SERVICE, ROW, ROLE, SERVICE, detectRole, enabledOf, masterError, roleAllowed, safeGet, } from "../kernel.js";
-import { createCostSystem, DEFAULT_BUDGET_LIMITS } from "../cost/index.js";
+import { createCostSystem, createFangRelayFromContext, DEFAULT_BUDGET_LIMITS } from "../cost/index.js";
 export const name = 'dsh-master-cost-optimizer';
 export const inject = ['dshMaster'];
 export const ROW_ID = ROW.cost;
@@ -37,6 +37,10 @@ function finiteNonNegative(value) {
  *   enabled?: boolean, mode?: string, targetSavingsRatio?: number,
  *   budget?: Array<{unit: string, limitTokens: number, onExhaust?: string}>,
  *   enforceAllowlist?: string[],
+ *   relay?: {enabled?: boolean, httpBaseUrl?: string, httpToken?: string, fileDir?: string,
+ *            timeoutMs?: number, maxBatch?: number, maxQueue?: number, probeTtlMs?: number,
+ *            autoFlushMs?: number},
+ *   dispatch?: {motherUrl?: string, motherToken?: string, contractFileDir?: string},
  * }} [config]
  */
 export function apply(ctx, config = {}) {
@@ -55,6 +59,12 @@ export function apply(ctx, config = {}) {
         return { skipped: true, reason: 'master-core-unavailable' };
     }
     const targetSavingsRatio = finiteNonNegative(config.targetSavingsRatio);
+    /**
+     * §5.6 / M5：瓮城回流出口。
+     * 传输按「插件配置 relay → dispatch 配置 → 环境变量 DSH_FANG_*」装配；
+     * 一个都没有时不造客户端，出口状态显式 `relay-client-absent`。
+     */
+    const relayWiring = createFangRelayFromContext(ctx, config, { logger: ctx?.logger });
     const system = createCostSystem({
         mode: config.mode,
         allowlist: config.enforceAllowlist ?? config.allowlist,
@@ -65,8 +75,28 @@ export function apply(ctx, config = {}) {
         hostSurface: config.hostSurface && typeof config.hostSurface === 'object'
             ? { enabled: config.hostSurface.enabled === true, source: config.hostSurface.source }
             : undefined,
+        relay: relayWiring.relay,
+        logger: ctx?.logger,
     });
     const policy = system.policy.describe();
+    // M5：加载后异步探测一次回流对端（不阻塞 apply；没有客户端时立即返回 absent）。
+    try {
+        void Promise.resolve(system.relayProbe()).catch(() => { });
+    }
+    catch { /* 探测失败不影响主流程 */ }
+    /** M5：回流自动投递；没有客户端或 autoFlushMs=0 时不开定时器。 */
+    const autoFlushMs = Math.max(0, Number(config.relay?.autoFlushMs ?? 2_000) || 0);
+    let relayTimer = null;
+    if (relayWiring.client && autoFlushMs > 0) {
+        relayTimer = setInterval(() => { try {
+            void system.relayFlush().catch(() => { });
+        }
+        catch { /* ignore */ } }, autoFlushMs);
+        try {
+            relayTimer.unref?.();
+        }
+        catch { /* ignore */ }
+    }
     // 3.2.x 兼容计数器（任务级实测汇总；系统层另有账本，两者口径不同、互不覆盖）。
     const metrics = {
         tasks: 0,
@@ -78,7 +108,7 @@ export function apply(ctx, config = {}) {
     };
     const service = {
         id: SERVICE.cost,
-        version: '3.3.0',
+        version: '3.3.1',
         role,
         get mode() {
             return system.policy.describe().mode;
@@ -307,12 +337,24 @@ export function apply(ctx, config = {}) {
         substitutions(filter = {}) {
             return system.audit.substitutions(filter);
         },
+        /** M5：瓮城回流出口状态（只读；不可用时必须带具体原因）。 */
+        relayStatus() {
+            return system.relayStatus();
+        },
+        /** M5：立即探测回流对端（hello 协商 + relay 状态），返回最新状态。 */
+        async relayProbe(input = {}) {
+            return await system.relayProbe(input);
+        },
+        /** M5：立即投递队列中的回流事件；回执里的数字才是送达证据。 */
+        async relayFlush() {
+            return await system.relayFlush();
+        },
         status() {
             const current = system.policy.describe();
             return {
                 ok: true,
                 id: 'cost-optimizer',
-                version: '3.3.0',
+                version: '3.3.1',
                 role,
                 mode: current.mode,
                 requestedMode: current.requestedMode,
@@ -332,7 +374,9 @@ export function apply(ctx, config = {}) {
                 attribution: system.attribution.snapshot(),
                 attributionSummary: system.status().attributionSummary,
                 bus: system.bus.snapshot(1),
-                /** §5.6：内部事件类型（冒号命名）与对外出口状态（fang 未就绪 ⇒ unavailable）。 */
+                /** §5.6 / M5：瓮城回流出口（可达 ⇒ available:true + 对端自报 peer；否则带原因）。 */
+                relay: system.relayStatus(),
+                /** §5.6：内部事件类型（冒号命名）与对外出口状态。 */
                 events: { types: ['cost:event', 'cost:degraded', 'cost:substitution'], relays: system.bus.snapshot(1).relays },
                 degraded: system.status().degraded,
                 surfaces: system.status().surfaces,
@@ -352,7 +396,7 @@ export function apply(ctx, config = {}) {
                         doubleCountGuard: report.doubleCountGuard,
                     };
                 })(),
-                note: '3.3.0 M1+M2：系统层记账/预算/灰度/审计 + A1 工具输出紧凑化（默认 shadow）；工具面 A2–A3 与决策复用 B1–B4 在 M3–M4 接入。',
+                note: '3.3.1：系统层记账/预算/灰度/审计 + A1 工具输出紧凑化（默认 shadow）+ 瓮城回流出口（contract 1.1 真实投递）；工具面 A2–A3 与决策复用 B1–B4 已接入（shadow 默认）。',
             };
         },
     };
@@ -360,6 +404,14 @@ export function apply(ctx, config = {}) {
         ctx.effect(() => ctx.provide(SERVICE.cost, service));
     }
     catch { /* fake ctx */ }
+    try {
+        ctx.effect(() => () => {
+            if (relayTimer)
+                clearInterval(relayTimer);
+            relayTimer = null;
+        });
+    }
+    catch { /* fake ctx */ }
     // 3.3.0 §11：可选子服务（主服务形态不变；消费方必须探测，不能假定存在）。
     const optionalFaces = {
         [OPTIONAL_SERVICE.costLedger]: Object.freeze({

package/dist-host/plugins/superagent-router.js

@@ -310,6 +310,22 @@ export function apply(ctx, config = {}) {
             }
         })();
         const tickets = id === null ? [...workerEvents.keys()] : [id];
+        /**
+         * §5.6 / M5：回流出口状态来自成本服务（3.3.1 起是真实探测，不再是硬编码）。
+         * 没有成本服务时如实给 `cost-service-unavailable`，不编造“未就绪”原因。
+         */
+        const relayBlock = (() => {
+            try {
+                const cost = safeGet(ctx, SERVICE.cost);
+                if (cost && typeof cost.relayStatus === 'function') {
+                    const relay = cost.relayStatus();
+                    if (relay && typeof relay === 'object')
+                        return relay;
+                }
+            }
+            catch { /* 回流状态读取失败不阻塞成本摘要 */ }
+            return { target: 'fang', available: false, reason: 'cost-service-unavailable' };
+        })();
         const rows = [];
         const totals = { events: 0, degraded: 0, substitutions: 0, estimated: 0, savedTokens: 0 };
         for (const key of tickets) {
@@ -346,8 +362,8 @@ export function apply(ctx, config = {}) {
             totals,
             /* §11：只读成本块（A 单价项 / B 跳过调用项分列 + 命中率），面板只读消费。 */
             service: serviceBlock,
-            /* §5.6：瓮城「产物回流」尚未就绪 —— 显式 unavailable，不假装成功、不阻塞主线。 */
-            relay: { target: 'fang', available: false, reason: 'fang-channel-not-ready' },
+            /* §5.6 / M5：瓮城回流出口真实状态（不可用必须显式带原因）。 */
+            relay: relayBlock,
         };
     };
     const service = {

package/docs/ARCHITECTURE.md

@@ -113,15 +113,15 @@
 - 安全审计 P0/P1 已加固（env 脱敏、进程树 kill、Mandate 一致性、secret 脱敏、token 估算）；
 - 不安装、不发布；等审核。
 
-## 7. 3.3.0 成本优化（M1 + M2 已实施）
+## 7. 3.3.0 / 3.3.1 成本优化（已实施并发布）
 
 ```text
 master-cost-optimizer（行，仅 fork）= 编排器 + 服务 dshMasterCost
         │
    系统层（常驻）：ledger 账本 │ budget 预算闸 │ policy 灰度 │ attribution 归因 │ audit 审计链 │ bus 事件总线
-        │ hooks                                              │ reports（→ 瓮城回流出口）
-   模块层 A 工具面：A1 compact ✅ │ A2 disclosure ⬜ │ A3 batch ⬜
-   模块层 B 决策复用：B1 edg ⬜ │ B2 gdr ⬜ │ B3 ccs ⬜ │ B4 rsi ⬜
+        │ hooks                                              │ reports（→ 瓮城回流出口：fang-relay 真实投递）
+   模块层 A 工具面：A1 compact ✅ │ A2 disclosure ✅ │ A3 batch ✅
+   模块层 B 决策复用：B1 edg ✅ │ B2 gdr ✅ │ B3 ccs ✅ │ B4 rsi ✅
         │ ToolModule SPI / DecisionModule SPI
    Worker（fork）四切点：beforeModelCall → afterModelResponse → beforeToolDispatch → afterToolReceipt
 ```
@@ -132,4 +132,7 @@ master-cost-optimizer（行，仅 fork）= 编排器 + 服务 dshMasterCost
   Agent Loop **不认识具体模块**；模块异常 fail-open 并留痕，因此新增模块无需改 `agent-loop.ts`。
 - 四切点：`worker/cost-hooks.ts`，事件经 `sink.cost` 到宿主（HTTP sink 的 `cost` 事件 / Cordis `superagent:cost`）。
 - A1 默认 **shadow**：计算「本可节省」但返回原文；只有 `enforce` 且紧凑结果更短才替换，且归因单独入账（不重复计消耗）。
-- 详见 `docs/DESIGN-v3.3.0-cost-optimization.md`（§0 总体架构、§17 实施进度）。
+- 瓮城回流（3.3.1）：`src/cost/fang-relay.ts` 走 `@twinsearth/dsh-fang-contract` 1.1 的
+  `fang.relay.publish` / `fang.relay.status`；只有对端回执才算送达，不可用给具名原因。
+- 详见 `docs/DESIGN-v3.3.0-cost-optimization.md`（§0 总体架构、§17 实施进度）、
+  `docs/EXPERIMENT-M5-real-ab.md`（真实 A/B）、`docs/EXPERIMENT-M5-fang-relay.md`（回流实测）。

package/docs/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 3.3.1（2026-11-13 已发布）
+
+> 三方发布：annotated tag `v3.3.1` + GitHub Release + npm `@twinsearth/dsh-master@3.3.1`。
+> 同批发布接口包：`@twinsearth/dsh-fang-contract@1.1.0`（仓库 [TwinsEarth/dsh-fang-contract](https://github.com/TwinsEarth/dsh-fang-contract)）。
+> 门禁：G1–G6 全绿 + G7 已授权；里程碑 **M1–M5 全部 done**（M5 的 peer 见下）。
+
+**主题：M5 收口 —— 瓮城回流接口从「硬编码 unavailable」变成「真实契约投递」。**
+
+- **接口包升到 contract 1.1.0**（独立仓库）：新增方法 `fang.relay.publish` / `fang.relay.status` 与能力 `event-relay`；新增 `src/relay.js`（`createRelayStore` / `validateRelayEvents` / `relayHandlers` / `createRelayContractServer`）——按 `event.id` 幂等、单调游标、有界回执、超限即协议错误（不静默截断）；client 门面新增 `publishRelay()` / `relayStatus()`。方法版本裁剪规则不变：1.0 对端不会宣告 1.1 方法，`negotiate()` 自动裁剪。
+- **传输加固上游化**：房主内嵌副本在 1.0.0 之后追加的逐调用 `timeoutMs`/`meta` 透传、`httpHeaders` 透传、HTTP 定时器 `unref`、file 回执/请求文件的有界重试清理（Windows EPERM）全部回灌进 1.1.0；`src/contract/` 与已发布包**逐字节相同**，由 `test/contract-conformance.test.mjs` 守卫（漂移即红）。
+- **新增 `src/cost/fang-relay.ts`**：`createFangRelay()` 做三件事——`probe()`（hello 协商 → 方法裁剪判定 → 读 `fang.relay.status` 确认对端真在服务）、`enqueue()/flush()`（批量投递；回执才算送达；失败退回队列并把状态转不可用）、`status()`（同步给最近已知状态）。不可用原因全部具名：`relay-client-absent` / `hello-failed:*` / `peer-contract-without-relay:*` / `probe-threw:*` / `publish-failed:*`，不再是单个 `fang-channel-not-ready` 常量。
+- **接线**：`createCostSystem()` 新增 `relay` / `relayClient` / `relayOptions` / `relayAutoAttach`，`status()` 增加 `relay`；`cost-optimizer` 从「插件配置 relay → dispatch 配置 → `DSH_FANG_*` 环境」装配客户端，服务面新增 `relayStatus()/relayProbe()/relayFlush()`，有客户端时按 `autoFlushMs`（默认 2s、`unref`）自动投递并在 `ctx.effect` 清理定时器；`superagent-router` 的 `cost(ticketId).relay` 改为读真实状态，没有成本服务时如实给 `cost-service-unavailable`。
+- **M5 判定收紧**：`evaluateMilestones()` 的 M5 不再只看 `available` 布尔——要求 `peer ∈ {dsh-fang-bundle, contract-server}`、`events ≥ 3`（对端回执数）、`sameProcess !== true`（自环不算），并把 `peer` 与残余缺口写进结果行。
+- **实测证据**：`scripts/fang-relay-probe.mjs` 起**独立进程**跑已发布的 contract 1.1.0 作对端（HTTP），本进程用内嵌副本作客户端，投递 6 条事件全部拿到回执（`accepted 6 / duplicates 0 / cursor 6 / failed 0 / dropped 0`，`sameProcess:false`，`transport:http`）；证据与方法见 [`docs/EXPERIMENT-M5-fang-relay.md`](EXPERIMENT-M5-fang-relay.md)。M5 现状 `done`，`peer=contract-server`；瓮城 bundle 采用 contract 1.1 后应变为 `peer=dsh-fang-bundle`，该残余缺口写在结果行 `notes` 里，不隐藏。
+- 测试：新增 `test/cost-fang-relay.test.mjs`（10 条：无客户端 / 1.0 对端 / hello 失败 / status 失败 / 真实投递 / 失败退回 / 重复回执 / 总线接线 / 装配 / 白名单）；`test/contract-conformance.test.mjs` 改为逐字节一致性 + 双向 relay 互操作；`test/cost-milestones.test.mjs` 增加 peer / 自环 / 回执不足的反例；全量 **448 条：446 通过 + 2 条 Windows 并行跳过**。
+
 ## 3.3.0（2026-11-13 已发布）
 
 > 三方发布：annotated tag 3.3.0 + GitHub Release + npm @twinsearth/dsh-master@3.3.0。

package/docs/DESIGN-v3.3.0-cost-optimization.md

@@ -1,6 +1,6 @@
 # 房主 dsh-Master 3.3.0 架构设计：成本优化 & 省 Token 子插件（系统 + 模块）
 
-> 状态：**设计已完成，M1 + M2/A1 已实施（3.3.0-dev，未发布）**。基线代码 `3.2.10`，本文件描述 3.3.0 的架构与落地路径；实施进度见 §17。
+> 状态：**已实施并发布（3.3.0 / 3.3.1 三方发布：annotated tag + GitHub Release + npm）**。基线代码 `3.2.10`，本文件描述 3.3.0 的架构与落地路径；实施进度见 §17。
 > 关联：`docs/ROADMAP.md`（3.3.0 = HarnessMM 经济性）、`docs/ARCHITECTURE.md`（角色矩阵 / `master-cost-optimizer` 行 → 仅 fork）、
 > `src/plugins/cost-optimizer.ts`（3.2.x 的 observe 骨架，本设计在其上扩展且**不破坏**现有服务接口）。
 > 参考实现：`dsh-ops`（MIT，工具层）、`HarnessMM`（Apache-2.0，arXiv:2610.32813，决策层）。**只移植协议语义、自研实现，不复制第三方代码。**
@@ -384,7 +384,7 @@ enforce  —— 守卫命中才真正替换，且受白名单（forkId/task 标
 
 - 内部：`cost:event`、`cost:degraded`、`cost:substitution`；
 - 对外（3.3.0 可选）：沿用 Worker→Router 的既有事件通道，新增 `cost` 事件类型上报 Router；Router 落库后供状态页与「分身信息栏」读取；
-- 与瓮城「产物回流」对接作为后续项（依赖 fang 侧通道，未就绪则显示 `unavailable`，不阻塞 3.3.0 主线）。
+- 与瓮城「产物回流」对接：**3.3.1 起是真实投递**（contract 1.1 的 `fang.relay.*`），不可用时按具体原因显式 `available:false`，绝不假装成功。
 
 **实施（`src/cost/bus.ts` + Router 侧聚合，已落地）**
 
@@ -395,8 +395,8 @@ enforce  —— 守卫命中才真正替换，且受白名单（forkId/task 标
 | Router 摘要 | 新增 `service.cost(ticketId?)`：按 ticket 汇总 `events / degraded / estimated / savedTokens / points / modules`，并给出 `relay` 状态；`status()` 新增 `cost` 与 `costRelay` |
 | 只读路由 | `GET /dsh-master/api/superagent/cost[?ticketId=…]`（与状态路由同源，无写入口、不暴露 token） |
 | 出口抽象 | 总线支持 `relays: [{name, publish, available, reason}]`；不可用出口只记状态不投递；出口抛异常**不影响主流程**但累加 `failed`（不静默吞） |
-| 瓮城回流 | `relay: { target: 'fang', available: false, reason: 'fang-channel-not-ready' }` —— 显式 `unavailable`，绝不假装成功，也不阻塞 3.3.0 |
-| 状态页/信息栏 | 数据已就绪（`status().cost` / `/cost` 路由）；UI 展示留 3.3.1（不在 3.3.0 主线内） |
+| 瓮城回流 | **3.3.1 实现**（`src/cost/fang-relay.ts`）：`probe()` 用契约 `hello` 协商判定对端是否宣告 `fang.relay.publish`（1.0 对端会被裁剪），再读 `fang.relay.status` 确认真的在服务；`enqueue()/flush()` 批量投递，**只有回执才算送达**（`accepted`/`duplicates`/`cursor`），失败退回队列并转 `publish-failed:*`。不可用原因具名：`relay-client-absent` / `hello-failed:*` / `peer-contract-without-relay:*` / `probe-threw:*` / `publish-failed:*` |
+| 状态页/信息栏 | 数据已就绪（`status().cost` / `/cost` 路由，`relay` 读真实状态）；UI 展示留后续版本 |
 
 - 内部：`cost:event`、`cost:degraded`、`cost:substitution`；
 - 对外（3.3.0 可选）：沿用 Worker→Router 的既有事件通道，新增 `cost` 事件类型上报 Router；
@@ -902,8 +902,12 @@ node scripts/gate.mjs --input gate.json   # 喂 G5 对照数据与 G6 证据
     实测：`[rsi] 清单复核 通过：entries=1`。
 - **面板**：`client.js` 的「房主」抽屉只读成本块（A/B 分列、governance、净节省、净亏任务、命中率），
   数据来自 `/dsh-master/api/superagent/cost` 的 `service` 段；**无任何写操作**（有测试断言）。
-- **与瓮城回流对接**：本会话范围内不可用（守则 §二），接口位保留且**显式**返回
-  `{ available:false, reason:'fang-channel-not-ready' }`，不伪装成功。
+- **与瓮城回流对接（3.3.1 收口）**：接口从「接口位」变成「真实投递」——
+  contract 1.1.0 新增 `fang.relay.publish` / `fang.relay.status`；房主侧 `src/cost/fang-relay.ts`
+  负责探测、批量投递、回执核对与失败退回；`scripts/fang-relay-probe.mjs` 起**独立进程**对端
+  跑已发布契约包，6 条事件全部拿到回执（`sameProcess:false`）。M5 判定随之收紧：
+  要求 `peer ∈ {dsh-fang-bundle, contract-server}`、`events ≥ 3`、非自环。
+  现状 `peer=contract-server`（瓮城 bundle 采用 1.1 后应变为 `dsh-fang-bundle`），该残余缺口写在结果行 `notes`。
 - 测试：`test/cost-freeze-manifest.test.mjs`（7 条：摘要可复现、排序、复核通过、篡改检测、
   输入漂移、阈值/可用性、空/异类清单拒收）。
 
@@ -997,24 +1001,24 @@ node scripts/milestones.mjs                       # 按仓库文件判定实现
 node scripts/milestones.mjs --input evidence.json  # 追加 M3 守卫准确率 / M4 对照数据
 ```
 
-当前真实输出（2026-11-13）：
+当前真实输出（2026-11-13，3.3.1，运行 `node scripts/milestones.mjs --input <evidence>`）：
 
-| 阶段 | 实现 | 依赖 | 效果 | 状态 |
-|---|---|---|---|---|
-| M1 | ✔ | ✔ | verified | **done** |
-| M2 | ✔ | ✔ | unmeasured | implemented-effect-unmeasured |
-| M3 | ✔ | ✔ | unmeasured | implemented-effect-unmeasured |
-| M4 | ✔ | ✖ | unmeasured | **blocked-by-dependency** |
-| M5 | ✔ | ✔ | unmeasured | implemented-effect-unmeasured |
+| 阶段 | 实现 | 依赖 | 效果 | 状态 | 证据 |
+|---|---|---|---|---|---|
+| M1 | ✔ | ✔ | verified | **done** | 记账 + 预算闸测试 |
+| M2 | ✔ | ✔ | verified | **done** | 真实 A/B 归因（tokens/task −37.6%） |
+| M3 | ✔ | ✔ | verified | **done** | shadow 样本 20 · 准确率 1.0 |
+| M4 | ✔ | ✔ | verified | **done** | 真实替换证书链 |
+| M5 | ✔ | ✔ | verified | **done** | 回流对端 `contract-server` · 6 条回执 |
 
-`实现 5/5 · 达标 1/5`
+`实现 5/5 · 达标 5/5`
 
 **四条判定规则（写死在代码里，有测试）**
 
-1. **实现 ≠ 达标**：M1 的效果由测试直接证明（记账 + 预算闸）⇒ `done`；M2–M5 实现完成但缺实测 ⇒ `implemented-effect-unmeasured`。
+1. **实现 ≠ 达标**：M1 的效果由测试直接证明（记账 + 预算闸）⇒ `done`；M2–M5 需要各自的实测证据，缺证据只能是 `implemented-effect-unmeasured`。
 2. **M4 必须等 M3 的数据**：M3 守卫准确率未达 `samples ≥ 20 且 accuracy ≥ 0.98` 时，M4 恒为 `blocked-by-dependency`（`dependency-unmet:M3`）—— 代码写完也不放行。
 3. **M1 先行是结构性的**：抽掉 `src/cost/ledger.ts`，M2/M3/M4/M5 全部 `blocked-by-dependency`（有测试）。
-4. **瓮城回流如实标注**：M5 的 `fang-relay-out-of-scope` —— 该通道在本会话范围内（守则 §二）不可用，里程碑不把它当成功。
+4. **瓮城回流必须有对端回执**：M5 的 `fangRelay` 要求 `available === true`、`peer` 在白名单内、`events ≥ 3`、`sameProcess !== true`；自环、未知 peer、回执不足一律 `unmeasured` 并点名原因（`fang-relay-self-loop` / `fang-relay-peer-invalid:*` / `fang-relay-no-receipts`）。
 
 ---
 
@@ -1048,6 +1052,7 @@ node scripts/milestones.mjs --input evidence.json  # 追加 M3 守卫准确率 /
 | **M1** 系统层 + 4 切点（observe） | ✅ 已实施（3.3.0-dev，未发布） | `src/cost/{ledger,budget,policy,audit,types,index}.ts`、`worker/cost-hooks.ts`、`cost-optimizer` 系统层接入、`test/cost-system.test.mjs`、`test/worker-cost-hooks.test.ts`；全量 197/197 |
 | **M2** A1 紧凑输出 + shadow 归因 | ✅ 已实施（3.3.0-dev，未发布） | `worker/tool-compact.ts`（read/list/write/shell 格式化，off/shadow/enforce，默认 shadow）、`WorkerResult.cost.compaction`、`cost.recordAttribution()`（shadow 只计「本可节省」）、`test/worker-tool-compact.test.ts`、`test/cost-attribution.test.mjs` |
 | **M2 收口** 系统层 attribution / bus + 模块 SPI | ✅ 已实施（3.3.0-dev，未发布） | `src/cost/attribution.ts`（按模块/任务聚合，enforce 才入账）、`src/cost/bus.ts`（事件总线 + 回流出口，订阅者异常隔离）、`worker/cost-spi.ts`（ToolModule / DecisionModule 契约）、`worker/cost-modules.ts`（注册表 + A1 适配，异常 fail-open）、`test/worker-cost-spi.test.ts`；Agent Loop 已改为只依赖注册表 |
-| **M2 余项 / M3–M5** | ⬜ 未开始 | A2 渐进纰漏、A3 批量、B1–B4、真实 fork 对照实验、面板成本块（见 §14） |
+| **M2 余项 / M3–M4** | ✅ 已发布（3.3.0） | A2 渐进纰漏、A3 批量、B1–B4、真实 fork 对照实验、面板成本块（见 §14） |
+| **M5 回流收口** | ✅ 已发布（3.3.1） | contract 1.1.0（`fang.relay.publish`/`status`）+ `src/cost/fang-relay.ts` + `scripts/fang-relay-probe.mjs`；M5 由 `fang-relay-out-of-scope` 改为对端回执判定 |
 
-*M1 已实施并提交；未改版本号（仍 3.2.10）、未发布。*
+*3.3.0 / 3.3.1 均已三方发布（annotated tag + GitHub Release + npm）。*

package/docs/EXPERIMENT-M5-fang-relay.md

@@ -0,0 +1,117 @@
+# M5 · 瓮城回流接口实测报告（contract 1.1.0 / 房主 3.3.1）
+
+> 结论：**M5 达标（done）**，但证据的**对端身份是 `contract-server`**（瓮城侧契约 SDK 的独立进程），
+> 不是 `dsh-fang-bundle` 本体。这个区别写在里程碑结果行的 `notes` 里，不隐藏。
+>
+> 日期：2026-11-13 · 环境：Windows / Node 26.13.0 / 单机双进程
+
+## 1. 为什么需要这一轮
+
+3.3.0 的 M5 只差一件事：`与瓮城回流对接`。当时的实现是**硬编码**
+
+```js
+relay: { target: 'fang', available: false, reason: 'fang-channel-not-ready' }
+```
+
+接口位在，但没有协议、没有投递、没有回执。contract 1.0.0 的方法表里也确实没有任何
+回流方法（只有 `fang.fork.*` / `fang.decision.*` / `fang.session.list` / `fang.orchestrator.status`），
+所以“接上”只能先把接口版本升上去。
+
+## 2. 这一轮改了什么
+
+### 2.1 接口包 `@twinsearth/dsh-fang-contract@1.1.0`
+
+| 变化 | 内容 |
+|---|---|
+| 新方法 | `fang.relay.publish`（批量投递，按 `event.id` 幂等，返回回执 + 游标）、`fang.relay.status`（对端自报 peer/cursor/累计计数） |
+| 新能力 | `event-relay` |
+| 参考实现 | `createRelayStore` / `validateRelayEvents` / `relayHandlers` / `createRelayContractServer` |
+| 客户端 | `publishRelay()` / `relayStatus()` |
+| 传输加固 | 逐调用 `timeoutMs`/`meta` 透传、`httpHeaders` 透传、HTTP 定时器 `unref`、file 回执/请求文件有界重试清理 |
+| 兼容 | 只升 MINOR；1.0 对端不会宣告 1.1 方法，`negotiate()` 按公共 minor 自动裁剪 |
+
+发布核验：npm `1.1.0` = `latest`，下载包与本地 tarball **字节一致**
+（sha256 `e5224dc682b7a66247cd100d47492047b081acf233fd1f7daac4fab6753d5bd4`，11 个文件）。
+仓库 main 已推到 `c106053d`（tree 与本地一致）。
+
+### 2.2 房主侧
+
+- `src/contract/` 内嵌副本同步到 1.1.0，与已发布包**逐字节相同**（`test/contract-conformance.test.mjs` 守卫）；
+- 新增 `src/cost/fang-relay.ts`：`probe()` 判定对端是否真的提供回流；`enqueue()/flush()`
+  批量投递且**只认回执**；失败退回队列并转 `publish-failed:*`；
+- `cost-optimizer` / `superagent-router` / `createCostSystem()` 全部改为读真实状态；
+- M5 判定收紧为 `available + peer 白名单 + events ≥ 3 + 非自环`。
+
+## 3. 实测方法（可复现）
+
+```bash
+npm run build
+node scripts/fang-relay-probe.mjs --events 6 --out relay-evidence.json
+```
+
+脚本行为：
+
+1. 起一个**独立子进程**（`--serve`），里面跑**已发布的 npm 包**
+   `@twinsearth/dsh-fang-contract@1.1.0` 的 `createRelayContractServer`，
+   以 HTTP 暴露 `/fang/api/contract/{hello,invoke,health}`（Bearer token，不裸奔）；
+2. 父进程用仓库内嵌副本作客户端，`probe()` → 入队 6 条事件（三类事件混合）→ `flush()`；
+3. 只把对端回执当证据；`sameProcess` 由两侧 pid 比较得出；
+4. 证据 JSON 顶层就是 `{ ok, fangRelay, detail }`，可直接喂给 `scripts/milestones.mjs --input`。
+
+## 4. 实测结果
+
+```json
+{
+  "ok": true,
+  "fangRelay": {
+    "available": true,
+    "peer": "contract-server",
+    "events": 6,
+    "sameProcess": false,
+    "transport": "http",
+    "contractVersion": "1.1.0",
+    "reason": null,
+    "cursor": 6,
+    "failed": 0,
+    "dropped": 0
+  },
+  "detail": {
+    "probePid": 13340,
+    "peerPid": 4476,
+    "endpoint": "http://127.0.0.1:58328",
+    "batches": [{ "ok": true, "delivered": 6, "duplicates": 0, "sent": 6, "queued": 0, "cursor": 6, "batchId": "relay-1" }]
+  }
+}
+```
+
+里程碑输出：
+
+```text
+M5 │ 实现 ✔ │ 依赖 ✔ │ 效果 verified │ 状态 done │ 回流对端 'contract-server·6条'
+   M5 说明: peer=contract-server：契约对端独立进程实测，dsh-fang-bundle 采用 contract 1.1 后应变为 peer=dsh-fang-bundle
+```
+
+## 5. 能证明 / 不能证明
+
+**能证明**
+
+- contract 1.1 的回流协议在**两个真实进程**之间跑通：hello 协商 → 方法裁剪 → 投递 → 回执 → 游标；
+- 幂等成立：同 id 重投 `accepted:0 / duplicates>0`，游标不倒退；
+- 失败路径不伪装：客户端不可用 / 对端 1.0 / hello 失败 / status 失败 / publish 失败，
+  五种情况分别有具名原因，且失败批次会退回队列并计入 `failed`（有单元测试）；
+- 房主内嵌副本与已发布包无漂移（逐字节 + 双向互操作测试）。
+
+**不能证明**
+
+- 不能说“已与真实 dsh-Fang bundle 完成对接”：bundle 尚未依赖 contract 1.1，也尚未挂
+  `relayHandlers`。等 bundle 采用 1.1 后，`peer` 自报值会变成 `dsh-fang-bundle`，
+  M5 的 `notes` 会自动消失（代码里写死的是白名单，不需要改里程碑表）；
+- 不能证明生产环境的网络/鉴权拓扑：本轮是 127.0.0.1 + Bearer token 的本机双进程。
+
+## 6. 复现注意事项
+
+- 必须 `npm run build` 后跑：脚本 import 的是 `dist-host/`；
+- 子进程用的是 `node_modules` 里**已发布**的包，父进程用 `src/contract/`，两侧故意不同源，
+  才能真正测出“已发布包 ↔ 内嵌副本”的互操作；
+- 证据文件不要提交进仓库（G6 零残留门禁会检查 `rsi-report.json` 一类产物）；
+- Windows 上子进程退出由 `SIGTERM` 处理，若端口被占用会直接报 ready 超时。

package/docs/EXPERIMENT-M5-real-ab.md

@@ -78,5 +78,10 @@ node scripts/fork-experiment.mjs --real --tasks 20 --out /tmp/real-ab.json --jso
   M5 implemented-effect-unmeasured（原因：fang-relay-out-of-scope）
 ```
 
-M5 唯一未达标项是「与瓮城回流对接」—— 该通道按本会话守则（§二）不可用，
+M5 当时唯一未达标项是「与瓮城回流对接」—— 该通道当时没有协议实现，
 接口位显式返回 `{ available:false, reason:'fang-channel-not-ready' }`，不伪装成功。
+
+> **后续（3.3.1 已收口）**：contract 1.1.0 新增 `fang.relay.publish` / `fang.relay.status`，
+> 房主侧新增 `src/cost/fang-relay.ts` 真实投递，并用独立进程对端拿到 6 条回执；
+> M5 现在 `done`（`peer=contract-server`）。详见
+> [`EXPERIMENT-M5-fang-relay.md`](EXPERIMENT-M5-fang-relay.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/dsh-master",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -75,7 +75,7 @@
     "build": "npm run build:host && npm run build:worker"
   },
   "devDependencies": {
-    "@twinsearth/dsh-fang-contract": "^1.0.0",
+    "@twinsearth/dsh-fang-contract": "^1.1.0",
     "@types/node": "^24.0.0",
     "typescript": "^5.9.0"
   },