@bolloon/bolloon-agent 0.4.32 → 0.5.0

package/dist/agents/goal-flywheel/wiring/contract.js

@@ -0,0 +1,270 @@
+/**
+ * wiring/contract.ts — 接缝 ③「这一步该派给谁, 回报算不算完成?」  (**M3 独占**)
+ *
+ * 归属: `seams.ts` 的 `SEAM_ROSTER` 里 `id: 'contract'`, `stage: 'M3'`。
+ * M3 只准改本文件 + `wiring/monitor.ts` + 声明的 `wiringPoints`
+ * (`goal-flywheel/work-contract.ts` · `subagent-manager.ts`)。
+ *
+ * ## 这条接缝钉住的冻结规则
+ *
+ * **规则 ⑤ 子 Agent 不能直接改 Goal**。
+ * 钉法: 派活与收回报**都只经过父侧** (`issueWork` / `acceptReport` / `dispatchWorker`), 且接缝自己做三件事:
+ *   ① 拒绝 `caller='child_agent'` 的派活 (子不许派生无限子任务);
+ *   ② 回报一律先过 `validateChildReport` + `acceptsAsComplete` —— **漂亮但没有逐条证据的
+ *      回报不算完成** (P5 强负例 7); 子 Agent 侧因此没有任何写 Goal 的路径;
+ *   ③ **派前必须有工作合同** (M3 新增): `dispatchWorker` 是"签合同 + 交给派遣器"的**唯一**入口 ——
+ *      合同签不出来 (缺判据 / 缺目标 / deadline 早于 now / 金额没币种 / 没注入签发面) 就**不派**,
+ *      而且派遣端口**一次都不调**。今天 `SubAgentManager` 的旧形状是"签合同失败 → 记个 error 照样派出去",
+ *      那正是"派前必须有合同"被绕过的地方 (本文件 + `subagent-manager.ts` 一起堵)。
+ *
+ * ## 为什么接缝自己带 P2 的核验口径 (`realReportVerdict` / `createContractSeamFromLogic`)
+ *
+ * 接缝只依赖三样东西: 本目录 `seams.ts` 的接口 · `../types.js` 的冻结类型 · **自己那个阶段**的实现模块。
+ * P2 的实现模块就是 `../work-contract.js` (纯函数, 零 I/O)。把它接进来意味着:
+ *   · 判定口径**全仓一份** —— 接缝不重新实现"算不算完成", 而是直接调真 P2 的那两个函数;
+ *   · 接缝可以**独立于 M0 组合层**使用 (测试与其它宿主只需注入落盘/读盘这两个端口),
+ *     而不是"必须有 `goal-flywheel-wiring.ts` 才能用"。
+ * 落盘/读盘仍按参数注入 (接缝不做 I/O, 与 `../work-contract.js` 的边界一致)。
+ */
+import { acceptsAsComplete, issueWorkContract, validateChildReport, } from '../work-contract.js';
+import { refuse } from './seams.js';
+export const CONTRACT_SEAM_ID = 'contract';
+/**
+ * 派活的拒绝码 (接缝自己的闭集)。
+ *
+ * 刻意**不**复用 `FrozenRule`: 六条冻结规则说的是"责任人是谁", 而这里是"这一步做不成的原因"。
+ * 把 `contract_invalid` 硬说成某条冻结规则 = 编一个规则号, 那会让日志与门都开始说谎。
+ * 只有真的越界 (`caller_not_allowed`) 才附 `refusal` (它确实违反规则 ⑤)。
+ */
+export const CONTRACT_REFUSAL_CODES = [
+    'caller_not_allowed',
+    'no_criteria',
+    'contract_invalid',
+    'no_dispatch_port',
+    'dispatch_failed',
+];
+// ============================================================================
+// §0. 与真 P2 模块的唯一耦合点 (判定口径全仓一份)
+// ============================================================================
+/** 用真 `issueWorkContract` 签发 —— 合同不合法时抛带 `issues` 的 `WorkContractError` (接缝抓它转成结构化拒绝) */
+export function realIssueContract(input) {
+    return issueWorkContract({
+        goalId: input.goalId,
+        parentRunId: input.parentRunId,
+        childAgentId: input.childAgentId,
+        capability: input.capability,
+        objective: input.objective,
+        inputs: input.inputs ?? {},
+        allowedTools: input.allowedTools ?? [],
+        budget: input.budget,
+        deadline: input.deadline ?? null,
+        successCriteria: input.successCriteria,
+        now: input.now,
+        issuedBy: input.issuedBy ?? 'supervisor',
+    });
+}
+/** 用真 `validateChildReport` + `acceptsAsComplete` 核验 —— 接缝不另写一套"算不算完成" */
+export function realReportVerdict(contract, report) {
+    const validation = validateChildReport(contract, report);
+    const verdict = acceptsAsComplete(contract, report);
+    return {
+        outcome: verdict.accepted ? 'accepted' : 'incomplete',
+        accepted: verdict.accepted,
+        reason: verdict.reason,
+        missingFields: validation.missingFields,
+        missingEvidence: validation.missingEvidence,
+        violation: validation.violation,
+    };
+}
+/**
+ * 从**真 P2 逻辑** + 两个存储端口拼一条接缝 (M3 的自带适配器)。
+ *
+ * 为什么需要它: `createContractSeam` 要求宿主自己注入 `issue`/`accept` (M0 组合层注入的是
+ * `dispatchChildWork` / `handleChildReport`)。这条工厂让**其它宿主** (测试 / CLI / Web)
+ * 也能用同一条接缝, 而判定口径仍是 `../work-contract.js` 那一份 —— 不会出现"第二份判定"。
+ *
+ * 注意 `persistContract`: 合同**必须先落盘再派出** —— 子拿到合同的依据是盘上那份,
+ * 而不是父内存里那句口头约定 (否则子回报时核心验的是"合同存不存在"就永远对不上)。
+ */
+export function createContractSeamFromLogic(ports) {
+    return createContractSeam({
+        issue: async (input) => {
+            const contract = realIssueContract(input);
+            await ports.persistContract(contract);
+            return contract;
+        },
+        accept: async (input) => {
+            const contract = await ports.loadContract({ goalId: input.goalId, workId: input.workId });
+            if (!contract) {
+                return {
+                    outcome: 'no_contract', accepted: false,
+                    reason: `没有找到合同 ${input.workId} → 没有合同的回报不核验也不接受`,
+                    missingFields: [], missingEvidence: [], violation: null,
+                };
+            }
+            return realReportVerdict(contract, input.report);
+        },
+        dispatch: ports.dispatch,
+    });
+}
+// ============================================================================
+// §1. 合同与派遣的边界判定 (纯函数 —— 接线层 / SubAgentManager 直接复用, 不重写一套)
+// ============================================================================
+/**
+ * 换人必须重签合同 (M3)。
+ *
+ * 合同把 `childAgentId` 钉死了 (`validateChildReport` 要求 `report.childAgentId === contract.childAgentId`),
+ * 所以"把同一份合同指给另一个子 Agent"不是改个字段: 新子回报必然对不上合同 → 旧的合规判定直接失效
+ * (要么假红, 要么被人放宽判据 —— 两条都是两套事实)。
+ * 结论: **换人 = 换合同**。本函数是那条规则的唯一判据。
+ */
+export function childMatchesContract(contract, childAgentId) {
+    const next = String(childAgentId ?? '').trim();
+    if (!next)
+        return { ok: false, reason: '新执行者没有 id —— 合同无法绑定到具体执行者 (换人必须重签)' };
+    if (next === contract.childAgentId) {
+        return { ok: true, reason: `执行者未变 (${next}), 合同 ${contract.workId} 仍然有效` };
+    }
+    return {
+        ok: false,
+        reason: `合同 ${contract.workId} 绑定的执行者是 ${contract.childAgentId}, 不是 ${next} `
+            + '—— 换人必须重签合同 (否则新子 Agent 的回报与合同对不上, 合规判定失效)',
+    };
+}
+// ============================================================================
+// §2. 接缝本体
+// ============================================================================
+function errText(e) {
+    return String(e?.message || e).slice(0, 400);
+}
+/** 抓签发失败的结构化原因 (WorkContractError 带 issues; 其它错误只带 message) */
+function issueFailure(input, e) {
+    const issues = e?.issues;
+    if (Array.isArray(issues) && issues.length > 0) {
+        return {
+            code: 'contract_invalid',
+            reason: `合同不合法, 拒签也拒派 (${input.capability} → ${input.childAgentId}): ${issues.join('; ')}`,
+        };
+    }
+    return { code: 'contract_invalid', reason: `合同签发失败, 拒派: ${errText(e)}` };
+}
+export function createContractSeam(deps) {
+    return {
+        id: CONTRACT_SEAM_ID,
+        stage: 'M3',
+        async issueWork(input) {
+            if (input.caller === 'child_agent') {
+                return refuse('child_cannot_mutate_goal', `拒绝: 子 Agent (${input.childAgentId}) 想给「${input.capability}」派活 —— `
+                    + '子 Agent 不许派生无限子任务, 也不许改父 Goal 的派遣面 (CHILD_PROHIBITIONS.spawn_unbounded_subtasks)');
+            }
+            if (!input.successCriteria?.length) {
+                return refuse('child_cannot_mutate_goal', '拒绝: 合同没有成功判据 —— 子 Agent 会自己定义"算完成"');
+            }
+            return deps.issue(input);
+        },
+        async acceptReport(input) {
+            if (!input.workId) {
+                return refuse('child_cannot_mutate_goal', '拒绝: 没有 workId 的回报无法对合同核验 → 不接受为完成');
+            }
+            const verdict = await deps.accept({ goalId: input.goalId, workId: input.workId, report: input.report, now: input.now });
+            // 无证据的漂亮回报: 显式拒绝, 并说清缺什么 (不许静默降级成"完成")
+            if (verdict.outcome === 'incomplete' && !verdict.reason) {
+                return { ...verdict, reason: '报告不完整 → 不接受为完成 (缺字段/缺证据)' };
+            }
+            return verdict;
+        },
+        /**
+         * 派前必须有工作合同 (M3 唯一派遣入口)。
+         *
+         * 顺序固定 (便于复现与断言):
+         *   ① 权限: 子 Agent 不许派活 → 拒 (附冻结规则 ⑤, 端口零调用);
+         *   ② 判据: 没有成功判据 → 拒 (没有"完成"的定义, 派出去只能扯皮);
+         *   ③ 派遣面: 没注入 `dispatch` → 拒 (**不假装派过**);
+         *   ④ 签合同: 真签 (`deps.issue`)。签不出 → 拒, 派遣端口**零调用** (这是"派前必须有合同"的硬点);
+         *   ⑤ 真派: 调 `dispatch`。端口抛错 / 回 `dispatched:false` → 如实拒绝 + 把人叫上 (不静默降级成"派出去了")。
+         *
+         * 合同**先落盘再派出**由 `deps.issue` 的宿主保证 (M0: `dispatchChildWork` 先写 goal-works/ 再写 pendingReports)。
+         */
+        async dispatchWorker(input) {
+            if (input.caller === 'child_agent') {
+                return {
+                    ok: false,
+                    code: 'caller_not_allowed',
+                    reason: `拒绝派遣: 调用者是子 Agent (${input.childAgentId} → 「${input.capability}」) —— `
+                        + '子 Agent 不许派生无限子任务 (CHILD_PROHIBITIONS.spawn_unbounded_subtasks)',
+                    refusal: refuse('child_cannot_mutate_goal', '子 Agent 不许派生无限子任务 / 不许改父 Goal 的派遣面'),
+                    detail: 'no_dispatch: 未签发合同, 派遣端口零调用',
+                    contract: null,
+                };
+            }
+            if (!input.successCriteria?.length) {
+                return {
+                    ok: false,
+                    code: 'no_criteria',
+                    reason: `拒绝派遣「${input.capability}」: 合同没有成功判据 —— 没有"完成"的定义就不许派 `
+                        + '(子 Agent 会自己定义"算完成")',
+                    refusal: null,
+                    detail: 'no_dispatch: 未签发合同, 派遣端口零调用',
+                    contract: null,
+                };
+            }
+            const dispatch = deps.dispatch;
+            if (typeof dispatch !== 'function') {
+                return {
+                    ok: false,
+                    code: 'no_dispatch_port',
+                    reason: `拒绝派遣「${input.capability}」: 宿主没有注入派遣面 (端口缺失) —— 拿不到"真派出去了"的事实, `
+                        + '不许把签发当成已派遣',
+                    refusal: null,
+                    detail: 'no_dispatch: 未签发合同, 派遣端口零调用',
+                    contract: null,
+                };
+            }
+            let contract;
+            try {
+                contract = await deps.issue(input);
+            }
+            catch (e) {
+                const fail = issueFailure(input, e);
+                return {
+                    ok: false,
+                    code: fail.code,
+                    reason: fail.reason,
+                    refusal: null,
+                    detail: 'no_dispatch: 合同没签成, 派遣端口零调用',
+                    contract: null,
+                };
+            }
+            try {
+                const receipt = await dispatch({ contract, caller: input.caller, now: input.now });
+                if (receipt?.dispatched !== true) {
+                    return {
+                        ok: false,
+                        code: 'dispatch_failed',
+                        reason: `合同 ${contract.workId} 已签发, 但派遣端口回"没派出去": ${receipt?.detail ?? '(端口没给原因)'}`,
+                        refusal: null,
+                        detail: `dispatched=false (workId=${contract.workId})`,
+                        contract,
+                    };
+                }
+                return {
+                    ok: true,
+                    contract,
+                    dispatched: true,
+                    detail: receipt.detail,
+                    receipt: receipt.receipt ?? null,
+                };
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    code: 'dispatch_failed',
+                    reason: `合同 ${contract.workId} 已签发, 但派遣端口抛错: ${errText(e)}`,
+                    refusal: null,
+                    detail: `dispatch 抛错: ${errText(e)}`,
+                    contract,
+                };
+            }
+        },
+    };
+}

package/dist/agents/goal-flywheel/wiring/index.js

@@ -0,0 +1,26 @@
+/**
+ * goal-flywheel/wiring/index.ts — 接线接缝的对外入口 (M0)
+ *
+ * 只做转发: 接缝名册在 `seams.ts` (M0 冻结), 五个接缝实现各归各的阶段文件。
+ * 这里**不定义任何函数** —— 与 `../index.ts` 同一纪律 (转发行, 不夹带实现)。
+ *
+ * M1–M4 各自只 import 自己那个接缝文件; 想拿到接缝实例请走 M0 接线层
+ * (`src/agents/goal-flywheel-wiring.ts` 的 `flywheelSeams()`), 它负责注入真依赖。
+ */
+export { DEFAULT_ALLOW, FROZEN_RULES, FROZEN_RULE_TEXT, FUNNEL_ALIASES, FUNNEL_CALL_RE, FUNNEL_ENTRY, SCANNED_SOURCES, SEAM_IDS, SEAM_MODULES, SEAM_ROSTER, SKILL_CHANNEL_EVIDENCE, TERMINAL_PATHS, WIRING_CALLERS, WIRING_STAGES, canRunStagesInParallel, filesOfStage, isRefusal, refuse, seamModuleOf, seamOf, seamRosterViolations, scanChildCannotMutateGoal, scanFunnelAliases, scanOnlyCloseRunCloses, scanOnlyGoalReducerWritesState, scanOnlySupervisorDecides, scanSkillChannel, scanTerminalPaths, stageOf, } from './seams.js';
+export { CONTINUATION_SEAM_ID, RHYTHM_BASIS_TEXT, SAFETY_CAPS, SAFETY_CAP_TEXT, SEAM_CAP_DEFAULTS, SEAM_RHYTHM_REQUIRED, SEAM_ROUNDS_AS_RHYTHM, bindingCaps, createContinuationSeam, judgeInjectedOutcome, judgeLegacyStop, planRhythm, rhythmicDecision, safetyCapsFrom, scanContinuationSeamRhythm, } from './continuation.js';
+export { CLOSURE_IDEMPOTENCY_NOTE, CLOSURE_SEAM_ID, CLOSURE_TERMINAL_KINDS, auditClosureOutcome, auditTerminalCoverage, closureTerminalKindFor, createClosureSeam, probeClosureArtifacts, terminalKindAccepts, terminalRegistryCoverage, } from './closure.js';
+export { CONTRACT_SEAM_ID, CONTRACT_REFUSAL_CODES, childMatchesContract, createContractSeam, createContractSeamFromLogic, realIssueContract, realReportVerdict, } from './contract.js';
+export { INTERNAL_VISIBLE_WORDS, MONITOR_SEAM_ID, MONITOR_SWEEP_DEFAULT_LIMIT, MONITOR_SWEEP_MAX_LIMIT, USER_FACING_STATES, createMonitorSeam, createVisibleStateProbe, describeVisibleState, isUserVisibleState, scanInternalLeak, userFacingState, } from './monitor.js';
+export { CHANGE_SEAM_ID, USER_ONLY_CHANGE_KINDS, changeVisibleState, createChangeSeam, } from './change.js';
+// ---------------------------------------------------------------------------
+// 跨阶段的**纯函数面** (2026-09-25 串行收口): 接缝与宿主都用的判定/归一化在这里一并转发 ——
+// 宿主与界面要的是"同一份口径", 不该各自深入阶段目录再 import 一遍 (M3 报的"index 补导"的完整形态)。
+//
+// 转发的是**同一个函数对象**, 不是同名的壳: 见 `goal-flywheel-m0-serial-hooks.test.ts` ⑥ 的恒等断言。
+// 尤其 `toUserVisibleState` / `normalizeContinuationRecord` —— 工作监控与 web 路由直传**部分**
+// continuation 时必须读同一份归一化 (2026-09-25 跨阶段真问题 ①)。
+// ---------------------------------------------------------------------------
+export { normalizeContinuationRecord, toUserVisibleState, } from '../work-monitor.js';
+export { planChangeInjection } from '../goal-change.js';
+export { USER_VISIBLE_STATES } from '../types.js';

package/dist/agents/goal-flywheel/wiring/monitor.js

@@ -0,0 +1,254 @@
+/**
+ * wiring/monitor.ts — 接缝 ④「有谁卡住了, 该谁动手?」  (**M3 独占**)
+ *
+ * 归属: `seams.ts` 的 `SEAM_ROSTER` 里 `id: 'monitor'`, `stage: 'M3'`。
+ * M3 只准改本文件 + `wiring/contract.ts` + 声明的 `wiringPoints` (`goal-flywheel/work-monitor.ts`)。
+ *
+ * ## 这条接缝钉住的冻结规则
+ *
+ * **规则 ④ 的"子 Agent 被阻塞"那一类终止路径必须经过收尾漏斗**。
+ * Watchdog 只看进程存活; 这条接缝看的是"任务卡住了没有"。它只做三件事:
+ *   ① **统一巡检** (`sweepAll` / `sweep`): 一次把**所有**待回报 Goal 的阻塞查清楚 (有界, 不静默);
+ *   ② **按计划处理** (`handle`): 处置动作交给宿主执行 —— 接缝自己**永不自动绕过 Harness**;
+ *   ③ **用户可见态** (`visibleState` / `createVisibleStateProbe`): 只暴露冻结层的闭集, 内部词不外泄。
+ *
+ * 阻塞升级到人 → Goal 的状态变更**不在这里直接写**, 而是交给 Goal reducer
+ * (规则 ②), 由接线层在 `handle` 之后调用。本文件因此没有任何 Goal 写入面。
+ *
+ * ## M3 的两处深化 (为什么不是"又一个透传壳")
+ *
+ *   1. **统一监控**: 真实 tick 里"逐个 Goal 巡检"是散在各处的循环 (`execution-supervisor.ts` 那段
+ *      `listGoalsWithPendingWork` → `collectWorkBlocks` → `applyBlockHandling`)。`sweepAll` 把这条循环
+ *      收成**一次调用**: 有界扫描 + 每个 Goal 一份结论 + **失败必须留痕** (`errors[]`),
+ *      不许"某个 Goal 巡检抛错 → 这一轮当它不存在"。
+ *   2. **用户只看到闭集**: `createVisibleStateProbe` 以前是**裸透传** (`return deps.visible(input)`),
+ *      端口给什么就往外说什么 —— 于是"用户视野只有这几类"只是端口自觉。现在它**逐值校验闭集**
+ *      (`USER_VISIBLE_STATES`), 闭集外的值 / 端口抛错一律**拒绝**并说清原因, 而不是把内部词
+ *      顺手暴露给用户。
+ *
+ * ### 五类还是六类 (如实说明, 不改冻结层)
+ *
+ * 设计稿 §8 写的是"用户可见只暴露**五类**": 正在执行 / 等待外部回复 / 子 Agent 被阻塞 /
+ * 暂时没有进展 / 需要你决定。冻结层 (`types.ts`) 在 2026-09-25 接线时**追加了第 6 类** `ended`
+ * (理由: 前五类里没有"已结束", 已结束的目标只能借用 `executing` 或 `needs_your_decision`,
+ * 那正是 P3/P4 要防的假象)。改冻结层要单独一个提交 + 更新类型计数门, **不归 M3**。
+ * 所以本接缝按**冻结闭集** (五类 + `ended`) 钉住: 断言"返回值只能是闭集里的值"是硬的,
+ * 断言"闭集有几个值"留给冻结层 (`goal-flywheel-types.test.ts` 的计数门)。
+ */
+import { USER_VISIBLE_STATES, USER_VISIBLE_STATE_LABELS, } from '../types.js';
+// 自己那个阶段的实现模块 (P3, 纯函数): "用户该看到哪一类"的判定只有一份
+import { normalizeContinuationRecord, toUserVisibleState } from '../work-monitor.js';
+import { refuse } from './seams.js';
+export const MONITOR_SEAM_ID = 'monitor';
+/** 统一巡检的默认/上限 (有界: 不许在 tick 里无界扫盘) */
+export const MONITOR_SWEEP_DEFAULT_LIMIT = 20;
+export const MONITOR_SWEEP_MAX_LIMIT = 200;
+function errText(e) {
+    return String(e?.message || e).slice(0, 300);
+}
+// ============================================================================
+// §1. 用户可见面: 闭集校验 + 内部词扫描 (纯函数, 可被门/变异验证复用)
+// ============================================================================
+/**
+ * 一个 continuation 决策是否长得像 `ContinuationDecision` (只做形状检查, 不猜内容)。
+ * 用它把 `decision?: unknown` 安全地喂给真 P3 判定: 不像就传 null (宁可少一层精化, 不许瞎 cast)。
+ */
+function isDecisionLike(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const d = x;
+    return typeof d.decision === 'string' || typeof d.state === 'string';
+}
+/** 用户可见态的**闭集** (冻结层唯一事实来源; 本文件不另立一份) */
+export const USER_FACING_STATES = USER_VISIBLE_STATES;
+export function isUserVisibleState(x) {
+    return typeof x === 'string' && USER_FACING_STATES.includes(x);
+}
+/**
+ * **不该出现在用户视野里**的内部词 (设计 §8 的名单 + 同义写法)。
+ *
+ * 为什么连 `retry_count` / `leaseOwner` 这种代码标识也扫: 界面拼字符串时最常干的事就是
+ * 把内部字段名顺手带出去 (`lease owner=worker-3`), 只扫中文词会漏掉这一类。
+ */
+export const INTERNAL_VISIBLE_WORDS = [
+    'lease',
+    'leaseOwner',
+    'lease_until',
+    'reducer',
+    'internal status',
+    'retry counter',
+    'retryCounter',
+    'retry_count',
+    'worker owner',
+    'workerOwner',
+    'attempts',
+    '抢租约',
+    '租约',
+    '内部状态',
+    '重试计数',
+];
+/** 扫出文本里出现的内部词 (空数组 = 干净)。大小写不敏感; 只报词, 不改文本。 */
+export function scanInternalLeak(text) {
+    const s = String(text ?? '');
+    if (!s)
+        return [];
+    const lower = s.toLowerCase();
+    const hits = [];
+    for (const w of INTERNAL_VISIBLE_WORDS) {
+        if (lower.includes(w.toLowerCase()))
+            hits.push(w);
+    }
+    return hits;
+}
+/** 闭集里的一个状态 → 用户看到的**全部**内容 (只有这三样, 没有内部字段) */
+export function userFacingState(state) {
+    if (!isUserVisibleState(state)) {
+        return refuse('only_supervisor_decides_continuation', `拒绝: 用户可见态 ${JSON.stringify(state) ?? String(state)} 不在冻结闭集里 `
+            + `(${USER_FACING_STATES.join(' / ')}) —— 用户可见态是 continuation 的投影, 不许第三方编一个状态出来`);
+    }
+    const labels = USER_VISIBLE_STATE_LABELS[state];
+    return { state, zh: labels.zh, en: labels.en };
+}
+// ============================================================================
+// §2. 接缝本体
+// ============================================================================
+export function createMonitorSeam(deps) {
+    // 可见面来源: 宿主注入的 `visible` 优先; 否则用**真 P3** 的判定 (注入的 continuation 是它的输入)。
+    // 两条路都不通 ⇒ 探针会如实拒绝 (不编一个"正在执行")。
+    const visiblePort = deps.visible ?? (deps.continuationOf
+        ? async (input) => {
+            const raw = await deps.continuationOf(input.goalId);
+            // 盘上的 continuation 允许缺字段 (goal-store 的 `pendingReports?` 是 optional; `setContinuation`
+            // 又是部分覆盖) —— 归一化只有**一份**实现 (`work-monitor.normalizeContinuationRecord`),
+            // 判定层(`toUserVisibleState`)自己也调它; 这里用同一个函数是为了让"接缝这一路也没传半份记录"可读。
+            const continuation = normalizeContinuationRecord(raw);
+            const decision = isDecisionLike(input.decision) ? input.decision : null;
+            return toUserVisibleState(continuation, input.blocks ?? [], decision);
+        }
+        : undefined);
+    const visibleOrRefuse = createVisibleStateProbe({ visible: visiblePort });
+    return {
+        id: MONITOR_SEAM_ID,
+        stage: 'M3',
+        async sweep(input) {
+            if (!input.goalId) {
+                return refuse('all_terminal_paths_pass_close_run', '拒绝: 阻塞巡检没有 goalId → 拿到的是"谁都不卡"的假结论');
+            }
+            return deps.collect({ goalId: input.goalId, now: input.now, runnerAvailable: input.runnerAvailable });
+        },
+        async handle(input) {
+            if (!input.blocks?.length)
+                return { actions: [], escalated: [], takeovers: [], requests: [] };
+            return deps.handle({ goalId: input.goalId, blocks: input.blocks, now: input.now });
+        },
+        pendingGoals(limit) {
+            return deps.goalsWithPendingWork(limit);
+        },
+        /**
+         * 统一监控 (M3): 一次调用 = 所有待回报 Goal 的阻塞结论。
+         *
+         * 纪律:
+         *   · **子 Agent 不许巡检别人的阻塞**: `caller='child_agent'` → 拒 (规则 ⑤, 一条都不查);
+         *   · **有界**: `limit` 夹在 [1, 200] (默认 20) —— tick 里扫盘不许无界;
+         *   · **不静默**: 单个 Goal 巡检/处置抛错 → 该 Goal 的 `error` 与顶层 `errors[]` 都留痕,
+         *     而不是"这一轮它不存在"。全失败时 `silentRisk=true` 并要求交人;
+         *   · 没有阻塞的 Goal **也占一格** (它有待回报工作 → 用户看到的是"等待外部回复", 不是"没人管")。
+         */
+        async sweepAll(input) {
+            if (input.caller === 'child_agent') {
+                return refuse('child_cannot_mutate_goal', '拒绝: 子 Agent 不许巡检/处置其它执行者的阻塞 —— 巡检与处置是父/调度器的责任面');
+            }
+            const limit = Math.min(Math.max(Math.floor(input.limit ?? MONITOR_SWEEP_DEFAULT_LIMIT) || 1, 1), MONITOR_SWEEP_MAX_LIMIT);
+            const view = {
+                goals: [], blockCount: 0, escalated: [], takeovers: [], requests: [],
+                visibleCounts: {}, errors: [], silentRisk: false,
+            };
+            let pending = [];
+            try {
+                const raw = await deps.goalsWithPendingWork(limit);
+                pending = Array.isArray(raw) ? raw.filter((g) => !!g?.goalId).slice(0, limit) : [];
+                if (!Array.isArray(raw))
+                    view.errors.push('待回报 Goal 清单不是数组 (宿主 bug) —— 无法巡检, 不许当成"没有阻塞"');
+            }
+            catch (e) {
+                view.errors.push(`取待回报 Goal 清单失败: ${errText(e)}`);
+                view.silentRisk = true;
+                return view; // 拿不到事实就如实报 (不是"巡检过了, 没问题")
+            }
+            for (const g of pending) {
+                const cell = { goalId: g.goalId, blocks: [], handling: null, visibleState: null, error: null };
+                try {
+                    const blocks = await deps.collect({ goalId: g.goalId, now: input.now, runnerAvailable: input.runnerAvailable });
+                    cell.blocks = Array.isArray(blocks) ? blocks : [];
+                    if (cell.blocks.length > 0) {
+                        cell.handling = await deps.handle({ goalId: g.goalId, blocks: cell.blocks, now: input.now });
+                        view.escalated.push(...(cell.handling?.escalated ?? []));
+                        view.takeovers.push(...(cell.handling?.takeovers ?? []));
+                        view.requests.push(...(cell.handling?.requests ?? []));
+                    }
+                    const vis = await visibleOrRefuse({ goalId: g.goalId, blocks: cell.blocks, now: input.now });
+                    if (vis && typeof vis === 'object' && vis.ok === false) {
+                        // 可见面拒绝 → 这一格如实留痕 (不是静默给个"正在执行")
+                        cell.error = vis.reason;
+                        view.errors.push(`goal=${g.goalId} 可见态: ${vis.reason}`);
+                    }
+                    else if (vis) {
+                        cell.visibleState = vis;
+                        view.visibleCounts[cell.visibleState] = (view.visibleCounts[cell.visibleState] ?? 0) + 1;
+                    }
+                    view.blockCount += cell.blocks.length;
+                }
+                catch (e) {
+                    cell.error = errText(e);
+                    view.errors.push(`goal=${g.goalId} 巡检失败: ${cell.error}`);
+                }
+                view.goals.push(cell);
+            }
+            const inspected = view.goals.filter((c) => c.error === null).length;
+            if (pending.length > 0 && inspected === 0) {
+                view.silentRisk = true;
+                view.escalated.push(...pending.map((g) => `巡检未完成: ${g.goalId}`));
+            }
+            return view;
+        },
+        async visibleState(input) {
+            return visibleOrRefuse({ goalId: input.goalId, blocks: input.blocks, decision: input.decision, now: input.now });
+        },
+    };
+}
+/**
+ * 用户可见态探针: 只回答"用户该看到哪一类", 且**只**能是冻结闭集里的值。
+ *
+ * 硬化的三件事 (旧版是 `return deps.visible(input)` 的裸透传):
+ *   ① **闭集校验**: 端口给出闭集外的值 (或 undefined / null / 对象) → 拒绝 + 说清收到了什么 ——
+ *      用户视野的假象比"什么都不显示"更贵;
+ *   ② **端口抛错不吞**: 原文进拒绝理由 (不静默降级成 `executing`);
+ *   ③ **缺端口 = 拒**: 没有可见面来源就不编一个状态 (旧版会直接 `TypeError`)。
+ *
+ * 返回值用冻结类型 + `userFacingState` 的文案; 调用方拿到的就是用户看到的东西。
+ */
+export function createVisibleStateProbe(deps) {
+    return async (input) => {
+        if (typeof deps.visible !== 'function') {
+            return refuse('only_supervisor_decides_continuation', '拒绝: 没有注入用户可见面 (拿不到权威 continuation 的投影) —— 不许编一个状态给用户');
+        }
+        let raw;
+        try {
+            raw = await deps.visible(input);
+        }
+        catch (e) {
+            return refuse('only_supervisor_decides_continuation', `拒绝: 用户可见面抛错 (${errText(e)}) —— 不静默降级成"正在执行"`);
+        }
+        const view = userFacingState(raw);
+        if (view.ok === false)
+            return view;
+        return view.state;
+    };
+}
+/**
+ * 给界面用的**唯一**文案出口: 状态 → `{state, zh, en}` (闭集外的值直接拒绝)。
+ * 界面不许自己拼状态名, 也不许把内部字段带出去 (见 `scanInternalLeak`)。
+ */
+export function describeVisibleState(state) {
+    return userFacingState(state);
+}