@bolloon/bolloon-agent 0.4.32 → 0.5.0

package/dist/agents/goal-flywheel/types.js

@@ -0,0 +1,329 @@
+/**
+ * goal-flywheel/types.ts — 「Goal 长期执行飞轮」**接口冻结层** (2026-09-25)
+ *
+ * 这一层**只有类型与文档**, 没有实现, 不改任何现有调用方。
+ * 目的: 把已经存在但没收敛的能力, 收敛成一个**长期执行飞轮**的可复用接口面 ——
+ * 而不是再造一个更大的 Agent 平台。
+ *
+ * 飞轮 (一轮的目标生命周期):
+ *   目标 → 判断下一步 → 自主决定节奏 → 执行或派遣 → 监控阻塞 → 动态注入新要求
+ *        → 汇总结果 → 写入 Memory → 形成 Skill 改进候选 → 下一次直接复用
+ *
+ * 与既有模块的关系 (刻意不重复、不冲突):
+ *   - `goal-store.ts` 的 `GoalContinuation` 是**已有**的调度元数据 (nextAction/wakeAt/…)。
+ *     本文件**不重复定义**它, 而是给出**冻结超集** `GoalContinuationRecord`
+ *     (机器继续记录) —— 见 §7。两者必须结构兼容, 由 `goal-flywheel-types.test.ts` 钉住。
+ *   - `skill-writer.ts` 的 `SkillCandidate` 是 run-end 的**文本候选** (name/description/body)。
+ *     本飞轮的 Skill 改进候选是**更强的结构** (必须有输入输出 schema/失败边界/证据/批准),
+ *     因此刻意命名为 `SkillImprovementCandidate` —— **不是同一个东西**, 见 §4。
+ *   - `contacts/policy.ts` 的 `BlockKind` 是**联系方式策略域**的拒绝原因;
+ *     本文件 §6 的 `BlockKind` 是**长期执行域**的阻塞类型。同名不同域, 永不合并。
+ *   - `Watchdog/heartbeat` 只看进程存活; 本文件的 `BlockRecord` 看的是**任务有没有卡住**。
+ *
+ * 硬底线 (不是"任务节奏", 而是安全线): 单 Run 时间上限 · 单 Goal 预算上限 ·
+ * 无进展熔断阈值 —— 见 `HardLimits`。**不再以「第几轮」作为继续依据**。
+ */
+export const RISK_LEVELS = ['low', 'medium', 'high'];
+// ============================================================================
+// §1. P0 — 节奏由进展决定 (ContinuationDecision)
+// ============================================================================
+/** 长期执行的状态: 它描述"为什么下一步是它", 不描述"跑了第几轮" */
+export const CONTINUATION_STATES = [
+    'progressing', // 有新的可核验进展
+    'blocked', // 被阻塞 (见 BlockRecord)
+    'waiting_external', // 等外部回话 (事件或 wakeAt 唤醒)
+    'waiting_agent', // 等子 Agent / 另一个执行者回报
+    'needs_decision', // 需要人做一个取舍
+    'no_progress', // 连续无新证据 / 无新完成判据 → stalled
+    'completed', // 判据全满足且有证据
+    'failed', // 判据不可能再满足 (不是"这次没跑好")
+];
+/** 每个 Run 结束必须产出的**唯一决策** (Agent 提, Supervisor 采用) */
+export const CONTINUATION_DECISIONS = [
+    'continue', // 有进展 → 直接开下一个 Run
+    'wait', // 等外部/等时间 → 挂 wakeAt 或等事件
+    'delegate', // 需要另一个 Agent/能力 → 签 AgentWorkContract
+    'ask_human', // 需要人决定 (判据 / 预算 / 权限 / 取舍)
+    'complete', // 判据全满足且有证据
+    'fail', // 不可能再满足 (附原因)
+    'pause', // 人主动暂停 (不是自动决策)
+];
+/** Agent 判断"继续没有价值"时, 必须交出的理由 (由 Supervisor 负责真的停) */
+export const STOP_REASONS = [
+    'no_value_continuing', // 继续也改变不了结果
+    'objective_unreachable', // 客观不可能 (缺条件/缺权限/物理限制)
+    'duplicate_work', // 与已完成的工作重复
+    'out_of_scope', // 超出了目标范围
+];
+// ============================================================================
+// §2. P1 — 强制收尾飞轮 (四类产物)
+// ============================================================================
+/**
+ * Run 结束的**固定顺序** (成功 / 失败 / 中断恢复后的 Run **都必须走**):
+ *   主执行结束 → 读完整步骤与证据 → Final Review → 提取事实/教训/Skill 候选
+ *   → 写 Memory → 写 Skill Candidate → 更新 Goal continuation → 用户汇报 → 决定是否继续
+ */
+export const RUN_CLOSURE_STEPS = [
+    'run_ended',
+    'read_full_steps_and_evidence',
+    'final_review',
+    'extract_facts_lessons_and_candidates',
+    'write_memory',
+    'write_skill_candidate',
+    'update_goal_continuation',
+    'user_report',
+    'continuation_decision',
+];
+/** 收尾产物的四类 (缺任何一类 = 收尾未完成) */
+export const CLOSURE_ARTIFACTS = [
+    'facts', // 发生了什么 / 哪些证据已确认 / 哪些只是推测
+    'lessons', // 什么方法有效 / 失败 / 下次改什么
+    'skill_candidates', // 仅当: 重复出现 + 可复用 + 边界清晰 + 输入输出明确 + 有真实成功证据
+    'next_step', // 下次先做什么 / 为何 / 等什么 / 需哪个 Agent 与 Skill
+];
+// ============================================================================
+// §3. P1b — Memory 分层
+// ============================================================================
+export const MEMORY_LAYERS = [
+    'run_fact', // 每次可自动写
+    'lesson', // 需 Review 判为可复用
+    'decision', // 涉用户偏好或重要取舍, 必须保留来源
+    'skill_signal', // 只生成候选, 不许直接成 Skill
+    'temporary', // 任务结束自动过期归档
+];
+/** 事实的确定性: 已确认 vs 推测 (推测**永不**当证据用) */
+export const ASSERTION_KINDS = ['confirmed', 'inferred'];
+// ============================================================================
+// §4. P1b — Skill 改进候选与更新流程
+// ============================================================================
+/** Skill 更新流程 (固定 8 步; 自动更新**不得**覆盖正在执行的 snapshot) */
+export const SKILL_UPDATE_FLOW = [
+    'run_evidence',
+    'review_extract_candidate',
+    'compare_with_existing_skill',
+    'validate_candidate',
+    'draft_new_version',
+    'run_skill_acceptance',
+    'approve',
+    'write_content_hash_and_change_reason',
+];
+/**
+ * **防 Skill 垃圾**: 命中任意一条 → 不得成为正式 Skill。
+ * (一次偶然成功不得直接成正式 Skill)
+ */
+export const SKILL_JUNK_REASONS = [
+    'single_success', // 只成功一次
+    'no_io_schema', // 无明确输入输出
+    'temp_path_dependency', // 依赖临时路径
+    'no_failure_boundary', // 无失败边界
+    'unverifiable_result', // 结果不可验证
+    'one_line_experience', // 只是一句经验
+    'duplicate_of_existing', // 与已有重复
+];
+export const SKILL_CANDIDATE_STATUSES = [
+    'draft',
+    'pending_review',
+    'approved',
+    'rejected',
+    'promoted',
+];
+/** 父负责做的事 */
+export const PARENT_RESPONSIBILITIES = [
+    'decompose_goal',
+    'assign_work',
+    'merge_results',
+    'final_judgement',
+    'report_to_user',
+];
+/** 子负责做的事 */
+export const CHILD_RESPONSIBILITIES = [
+    'single_clear_subgoal',
+    'only_contract_allowed_tools',
+    'periodic_heartbeat',
+    'report_blocks_proactively',
+    'structured_result',
+];
+/** 子 Agent **不得**做的事 (越界即判失败, 由父/监控层拦) */
+export const CHILD_PROHIBITIONS = [
+    'mutate_parent_goal_state',
+    'expand_own_budget',
+    'spawn_unbounded_subtasks',
+    'mark_unverified_as_complete',
+    'rewrite_success_criteria',
+];
+export const WORK_REPORT_STATUSES = [
+    'completed',
+    'partial',
+    'blocked',
+    'failed',
+    'cancelled',
+];
+export const CHECK_VERDICTS = ['pass', 'fail', 'unknown'];
+// ============================================================================
+// §6. P3 — 阻塞监控 (WorkMonitor / BlockRecord)
+// ============================================================================
+/**
+ * 长期执行域的阻塞类型。
+ * 与 `contacts/policy.ts` 的 `BlockKind` (联系方式策略拒绝原因) **同名不同域**, 永不合并。
+ */
+export const BLOCK_KINDS = [
+    'no_heartbeat', // 子 Agent 不发心跳了
+    'waiting_dependency', // 等依赖 (另一个 work / 外部服务)
+    'repeated_failure', // 反复失败
+    'no_progress', // 活着但没进展
+    'tool_blocked', // 工具/资源被阻
+    'budget_blocked', // 预算用尽 (硬底线)
+    'permission_blocked', // 权限不足
+    'runner_unavailable', // 没有可用执行器 (只诊断, 不假装跑过)
+    'external_timeout', // 外部等待超时
+    'report_missing', // 报告不完整 / 根本没回
+];
+/** 谁该处理这个阻塞 */
+export const BLOCK_OWNERS = ['parent', 'child', 'external', 'system', 'user'];
+/** 处理动作 (监控层可选的动作集, 不自动绕过 Harness) */
+export const BLOCK_RESOLUTION_ACTIONS = [
+    'send_adjustment', // 先发一次调整指令
+    'replace_child', // 停掉并替换执行者
+    'takeover', // 父接管 (先查 lease)
+    'request_report', // 要求补齐报告
+    'escalate_parent', // 上报父
+    'change_plan', // 允许父改计划
+    'wait_dependency', // 继续等 (挂 escalationAt)
+    'needs_human', // 转人工
+];
+/**
+ * 用户可见的**六类**状态 (其余内部状态不外露):
+ *   正在执行 / 等待外部回复 / 子 Agent 被阻塞 / 暂时没有进展 / 需要你决定 / **已结束**
+ *
+ * 第 6 类 (`ended`) 是 2026-09-25 接线时补的: 前五类里没有"已结束", 于是 P1 的收尾汇报只能
+ * 借用 `executing` —— 把一个**已经结束**的目标显示成"正在执行"正是 P3/P4 要防的假象。
+ * 补法只有一种: 改冻结层 + 单独一个提交 (见 `goal-flywheel-types.test.ts` 的计数门)。
+ */
+export const USER_VISIBLE_STATES = [
+    'executing',
+    'waiting_external_reply',
+    'child_blocked',
+    'no_progress',
+    'needs_your_decision',
+    // 2026-09-25 新增 (第 6 类): 目标已结束 (completed / failed / abandoned) ——
+    //   "已结束"必然需要人接一下 (接受结论 / 重试 / 立新目标), 但**不许**说成"正在执行"。
+    'ended',
+];
+/** 用户态文案 (只暴露六类, 不出现 lease/reducer/retry counter 这类内部词) */
+export const USER_VISIBLE_STATE_LABELS = {
+    executing: { zh: '正在执行', en: 'Executing' },
+    waiting_external_reply: { zh: '等待外部回复', en: 'Waiting for an external reply' },
+    child_blocked: { zh: '子 Agent 被阻塞', en: 'A sub-agent is blocked' },
+    no_progress: { zh: '暂时没有进展', en: 'Temporarily no progress' },
+    needs_your_decision: { zh: '需要你决定', en: 'Your decision is needed' },
+    ended: { zh: '已结束', en: 'Ended' },
+};
+// ============================================================================
+// §7. P4 / P4b — 新要求注入 (GoalChangeRequest) 与两份输出
+// ============================================================================
+/** 变更分类 */
+export const CHANGE_KINDS = [
+    'clarification', // 补充说明 (不改判据)
+    'priority_change', // 优先级变化
+    'success_criteria_change', // 完成判据变化 (必须增版本号)
+    'budget_change', // 预算变化 (扩大不许 Agent 自动批)
+    'permission_change', // 权限变化
+    'scope_expansion', // 扩大范围
+    'scope_reduction', // 缩小范围
+    'abort', // 撤销 / 终止
+];
+export const CHANGE_SOURCES = ['user', 'agent', 'external', 'system'];
+/** `user_revocation` 优先级最高 (用户明确撤销压过一切) */
+export const CHANGE_PRIORITIES = ['user_revocation', 'high', 'normal', 'low'];
+export const CHANGE_STATUSES = [
+    'received',
+    'triaged',
+    'needs_approval',
+    'scheduled_next_run',
+    'applied',
+    'rejected',
+    'superseded',
+];
+export const CHANGE_SCOPE_KINDS = [
+    'goal',
+    'run',
+    'criteria',
+    'budget',
+    'permission',
+    'child_work',
+];
+/** 新要求注入的固定规则 (写进类型, 不靠记忆) */
+export const GOAL_CHANGE_RULES = [
+    'user_revocation_wins', // 用户明确撤销优先级最高
+    'agent_cannot_approve_budget', // 扩预算不得由 Agent 自动批准
+    'criteria_change_bumps_version', // 改完成判据必须增版本号
+    'history_not_rewritten', // 当前 Run 历史不可被新要求改写 (只影响后续)
+    'children_receive_new_version', // 子 Agent 必须收到变更版本
+];
+/** 长期执行生命周期状态 (与 goal-store 的 GoalStatus 同域; 这里作为冻结面重列一次) */
+export const GOAL_LIFECYCLE_STATES = [
+    'active',
+    'recovering',
+    'retry_wait',
+    'awaiting_external',
+    'stalled',
+    'paused',
+    'needs_human',
+    'completed',
+    'failed',
+    'abandoned',
+];
+/** 只有这几个状态可以"结束" (其余必须回答下一步) */
+export const GOAL_TERMINAL_STATES = ['completed', 'failed', 'abandoned'];
+/** 汇报里**允许出现**的字段名 (与 MUST_NOT_EXPOSE_FIELDS 无交集) */
+export const USER_REPORT_FIELDS = [
+    'conclusion',
+    'completed',
+    'evidence',
+    'remaining',
+    'blockReasons',
+    'nextStep',
+    'willContinue',
+    'expectedResumeAt',
+    'visibleState',
+];
+/** 汇报里**不得出现**的内部字段 (只给用户看结论与下一步) */
+export const MUST_NOT_EXPOSE_FIELDS = [
+    'lease',
+    'reducer',
+    'internal_status',
+    'retry_counter',
+    'worker_owner',
+];
+// ============================================================================
+// §8. P5 — 统一长周期验收 (后续阶段跑; 本轮只冻结用例清单)
+// ============================================================================
+export const LONG_RUN_ACCEPTANCE_CASES = [
+    // 正例
+    'self_terminate_by_evidence', // 不设最大轮次, 按证据自行结束
+    'no_progress_circuit_breaker', // 无进展自动熔断
+    'child_block_detected_and_handled', // 子 Agent 被阻塞被发现/接管/升级
+    'user_change_effective_next_run', // 用户中途注入新要求 → 下一 Run 生效
+    'run_end_writes_memory_and_candidate', // Run 结束自动写 Memory + Skill Candidate
+    'auto_resume_by_wake_at_or_event', // 汇报后按 wakeAt/事件自动继续
+    // 强负例
+    'evidence_less_child_report_blocks_goal', // 漂亮但无证据 → 父 Goal **不完成**
+    'single_success_never_promotes_skill', // 只有一次偶然成功 → **不得**自动晋升正式 Skill
+];
+// ============================================================================
+// §9. 本轮**不做** (写进类型面, 防止被"顺手实现")
+// ============================================================================
+export const FLYWHEEL_NON_GOALS = [
+    'unbounded_autonomous_agent_swarms',
+    'auto_spawn_many_subagents',
+    'multi_level_recursive_delegation',
+    'agent_run_its_own_agent_marketplace',
+    'auto_write_every_result_as_skill',
+    'auto_overwrite_formal_skills',
+    'evidence_less_smart_scoring',
+    'complex_pm_dashboards',
+    'multiple_task_databases',
+    'a_second_workflow_engine',
+    'fixed_round_count_masquerading_as_long_run',
+    'running_forever_instead_of_real_progress',
+];

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

@@ -0,0 +1,288 @@
+/**
+ * wiring/change.ts — 接缝 ⑤「人中途改了什么要求, 用户该看到哪一类状态?」  (**M4 独占**)
+ *
+ * 归属: `seams.ts` 的 `SEAM_ROSTER` 里 `id: 'change'`, `stage: 'M4'`。
+ * M4 只准改本文件 + 声明的 `wiringPoints` (`goal-flywheel/goal-change.ts` · `web/server.ts`)。
+ *
+ * ## 这条接缝要回答的四件事 (以前只回答第四件)
+ *
+ * ```
+ * 用户/外部在目标**跑着的时候**提要求
+ *   ① 原话逐字入档了吗?          → 没原文 / 被改写过 → 拒绝 (原话就是证据)
+ *   ② 在跑的这一轮怎么办?        → 撤销 = 停; 其余 = 让这一轮跑完, 只影响后续 Run (规则 4)
+ *   ③ 在跑的子 Agent 怎么办?     → 规则 5: 逐 workId 一份下发内容, 必须先 ack 再继续
+ *   ④ 用户该看到哪一类状态?      → 有待决定的变更 → `needs_your_decision` (只升不降)
+ * ```
+ *
+ * ## 为什么"在跑的 Run 要停"这件事归这条接缝
+ *
+ * 用户撤销的语义是"别再继续了"。撤销落到 Goal 上 (`abandoned`) 之后, **在飞的 Run 并不会自己
+ * 发现** —— 执行器只在每一轮循环开头读一次自己 Run 记录的状态 (`paused` / `aborted` 就自行停下,
+ * 轮内不打断)。所以"停"必须由**注入变更的那一方**写进 Run 记录: 除了这条接缝, 没有第二个人
+ * 知道"用户刚刚撤销了"。写状态用的是**既有的外部控制面原语**(与 `POST /api/runs/:id/abort`
+ * 同一条路), 不是新造一条停止通道 —— 否则就是第二套事实。
+ *
+ * ## 两条边界 (接缝的自律)
+ *
+ * · **判定在 `goal-change.ts` (纯函数), 副作用在接线层** —— 接缝自己不读盘/不写盘/不读钟:
+ *   "在跑的 Run 是谁"由宿主注入 (`runningRun`), "怎么停"由宿主注入 (`stopRunningRun`)。
+ *   宿主没注入 → 接缝返回 `stopped: false` + 结构化原因, **绝不假装停过** (也不偷偷放行)。
+ * · **只升不降**: 变更对用户可见态的影响只有"抬成 `needs_your_decision`"这一种, 绝不把
+ *   `ended` / `child_blocked` / `no_progress` 降级成"正在执行"。已结束的目标上, 待批的变更
+ *   已经没有生效对象 → 不许把 `ended` 抬成"需要你决定"。
+ */
+import { nextStatusFor, planChangeInjection, userOnlyChangeKind } from '../goal-change.js';
+import { refuse } from './seams.js';
+export const CHANGE_SEAM_ID = 'change';
+/** 只有人能做"撤销/缩范围"这类动作 */
+export const USER_ONLY_CHANGE_KINDS = ['abort', 'scope_reduction'];
+/** `applyChange` 的三个 outcome (宿主返回别的值 = 接线坏了, 抛错而不是当没看见) */
+export const CHANGE_OUTCOMES = ['next_run', 'pending_approval', 'rejected'];
+/** 变更记录状态里"还在等一个人拍板"的那些 → 用户可见态必须说"需要你决定" */
+export const DECISION_PENDING_STATUSES = ['needs_approval', 'triaged'];
+/**
+ * 变更驱动的用户可见态覆盖 —— **只升不降**。
+ *
+ * 为什么必须有这一条: 目标在跑 (`executing`) 时用户提了一条"要加权限"的要求, 它被正确判成
+ * `needs_approval` 等待人批准 —— 但界面上仍然是"正在执行", 于是没有人知道这里有东西卡在
+ * 等人。设计稿 §8 的第五类状态 (`needs_your_decision`) 正是为这一刻存在的。
+ *
+ * 不覆盖的情形也有理由: `ended` (目标已结束, 待批的变更已经没有生效对象)。
+ * `base === null` = 基础态**读不到**: 有待拍板的变更时仍抬成"需要你决定" (有人必须看一眼这件事
+ * 与基础态无关); 没有待拍板的变更时返回 `null` —— 不编一个态出来。
+ */
+export function changeVisibleState(input) {
+    const waiting = input.changes.filter((c) => DECISION_PENDING_STATUSES.includes(String(c.status)));
+    if (waiting.length === 0) {
+        return {
+            state: input.base,
+            elevated: false,
+            reason: input.base === null
+                ? '基础可见态读不到, 且没有等拍板的变更 → 不断言 (不把"读不到"说成"正在执行")'
+                : '没有等拍板的变更 → 用户可见态不变',
+        };
+    }
+    const ids = waiting.map((c) => c.changeId).slice(0, 3).join(', ');
+    if (input.base === 'ended') {
+        return {
+            state: 'ended',
+            elevated: false,
+            reason: `目标已结束 → 不把 ${waiting.length} 条变更 (${ids}) 抬成"需要你决定" (已结束的目标上没有生效对象)`,
+        };
+    }
+    if (input.base === 'needs_your_decision') {
+        return {
+            state: 'needs_your_decision',
+            elevated: false,
+            reason: `本来就是"需要你决定", 另等 ${waiting.length} 条变更拍板 (${ids})`,
+        };
+    }
+    return {
+        state: 'needs_your_decision',
+        elevated: true,
+        reason: `${waiting.length} 条变更等你决定 (${ids}) → 覆盖 "${input.base ?? '读不到的基础态'}" `
+            + '(否则界面会一直显示"正在执行", 没人知道有东西在等人)',
+    };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// 接缝实例
+// ────────────────────────────────────────────────────────────────────────────
+/** 在跑的 Run 的事实: 宿主当场传入 > 依赖注入 > 不知道 (undefined) */
+async function resolveRunningRun(deps, input) {
+    if (input.runningRun !== undefined)
+        return input.runningRun;
+    if (!deps.runningRun)
+        return undefined;
+    try {
+        return await deps.runningRun(input.goalId);
+    }
+    catch {
+        // 探测失败 = 事实缺失 (不是"没有在跑的 Run"): 上层拿到 factsMissing 后不做任何断言
+        return undefined;
+    }
+}
+/**
+ * 在跑的子 Agent 工作的事实: 调用方当场传入 > 依赖注入 > 没给 (`undefined`)。
+ *
+ * `undefined` 的语义与"宿主没传这份事实"**完全一致** —— 接缝不在这里另立一套
+ * "事实缺失"标记 (`ChangeInjectionPlan` 没有这个字段, 那是 M4 纯函数的既定口径);
+ * 探针抛错 (读盘失败) 也按"没给"处理并返回 undefined, 绝不编出几个 workId 来。
+ */
+async function resolveLiveWorkIds(deps, input) {
+    if (input.liveWorkIds !== undefined)
+        return input.liveWorkIds;
+    if (!deps.liveWorkIds)
+        return undefined;
+    try {
+        const ids = await deps.liveWorkIds(input.goalId);
+        return Array.isArray(ids) ? ids : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 基础用户可见态 (读不到就返回 null + 原因)。
+ *
+ * 为什么必须容错: 入档本身**已经成功**了 (原话落档 + 判定 + 下一 Run 指令)。这时如果读可见态
+ * 抛错, 整个人口会 500 —— 人会以为"没提上去"而重提一遍 (重复变更)。所以读不到就读不到:
+ * 如实返回 null, 让视图说"读不到", 而不是把已经生效的变更报成失败。
+ */
+async function resolveBaseVisible(deps, input) {
+    try {
+        return { base: await deps.visibleState(input), reason: null };
+    }
+    catch (err) {
+        return { base: null, reason: `用户可见态读不到 (${String(err?.message || err).slice(0, 120)})` };
+    }
+}
+function dedupeChanges(list) {
+    const byId = new Map();
+    for (const c of list)
+        byId.set(String(c.changeId), c);
+    return [...byId.values()];
+}
+export function createChangeSeam(deps) {
+    async function applyRunBoundary(input) {
+        const b = input.plan.runBoundary;
+        if (b.action === 'let_finish') {
+            return {
+                action: 'let_finish',
+                stopped: false,
+                runId: b.runId,
+                runStatus: null,
+                reason: `不需要停动作 (在跑的 Run 继续跑完): ${b.reason}`,
+            };
+        }
+        const runStatus = b.runStatus === 'paused' || b.runStatus === 'aborted' ? b.runStatus : 'paused';
+        if (!b.runId) {
+            return {
+                action: 'stop_running_run',
+                stopped: false,
+                runId: null,
+                runStatus,
+                reason: '计划要求停 Run, 但没有 runId → 拒绝凭空停一个 Run (拿不到对象就不动手)',
+            };
+        }
+        const stop = input.stop ?? deps.stopRunningRun;
+        if (!stop) {
+            return {
+                action: 'stop_running_run',
+                stopped: false,
+                runId: b.runId,
+                runStatus,
+                reason: `计划要求停 Run ${b.runId} (→${runStatus}), 但宿主没有注入停 Run 的执行器 → **没有停**`
+                    + ' (需要主线在 M0 的 createChangeSeam 注入 stopRunningRun, 或由入口按参数传入; 本接缝不做 I/O, 也不假装停过)',
+            };
+        }
+        const res = await stop({ goalId: input.plan.goalId, runId: b.runId, runStatus, reason: b.reason, now: input.now });
+        return {
+            action: 'stop_running_run',
+            stopped: !!res?.ok,
+            runId: b.runId,
+            runStatus,
+            reason: res?.ok
+                ? `已把 Run ${b.runId} 置为 ${runStatus}: 执行器下一轮循环读到后自行停下 (轮内不打断, 已发生的步骤不改写)`
+                : `停 Run ${b.runId} 被拒绝: ${res?.reason || '执行器没给原因 (不静默当成功)'}`,
+        };
+    }
+    return {
+        id: CHANGE_SEAM_ID,
+        stage: 'M4',
+        async ingestChange(input) {
+            const raw = String(input.instruction ?? '');
+            // ① 原话是证据: 没有原文就不许往下走 (一句"理解"不能代替人说过的话)
+            if (!raw.trim()) {
+                return refuse('child_cannot_mutate_goal', '拒绝: 变更没有原文 —— 不许用一句"理解"代替人说过的话');
+            }
+            // ② 只有人能撤销 / 缩小意图 (设计稿「意图的落位」纪律 2)。
+            //    判据 = 真实分诊 (`userOnlyChangeKind`), 不再只认字面关键词:
+            //    "别继续做了 / abort this / 只做第一条" 这些说法现在也认得出来。
+            const userOnly = userOnlyChangeKind(raw);
+            if (userOnly && input.source !== 'user') {
+                return refuse('only_goal_reducer_changes_goal_state', `拒绝: ${input.source} 想提「${userOnly}」类变更 —— 只有人能撤销/缩小意图 `
+                    + '(Agent 不得因为"执行起来方便"就替人改意图)');
+            }
+            const out = await deps.ingest({ ...input, instruction: raw });
+            if (!out?.request || !out?.application) {
+                throw new Error('[change 接缝] 宿主没有返回变更记录/生效判定 (接缝不替它编一份)');
+            }
+            if (!CHANGE_OUTCOMES.includes(String(out.application.outcome))) {
+                throw new Error(`[change 接缝] 宿主返回的 outcome 非法: "${String(out.application.outcome)}" (合法: ${CHANGE_OUTCOMES.join('/')})`);
+            }
+            // ③ 规则 4 是**宿主契约**: 记录必须标着"只影响后续 Run"。违反 = 接线坏了 → 抛错, 不假绿。
+            if (out.request.appliesToFutureRunsOnly !== true) {
+                throw new Error('[change 接缝] 宿主返回的变更记录没标 appliesToFutureRunsOnly —— 规则 4: 已发生的 Run 历史不可被新要求改写');
+            }
+            // ④ 原话必须逐字入档: 被改写过的"原话"不是证据
+            if (out.request.instruction !== raw) {
+                return refuse('child_cannot_mutate_goal', '拒绝: 变更记录里的 instruction 与用户原话不一致 (原话必须逐字入档)');
+            }
+            // ⑤ 正在运行的 Goal: 拿事实 → 判定 (纯函数) → 按判定执行 (宿主注入的执行器)
+            const runningRun = await resolveRunningRun(deps, input);
+            const liveWorkIds = await resolveLiveWorkIds(deps, input);
+            const plan = planChangeInjection({
+                request: out.request,
+                application: out.application,
+                runningRun,
+                liveWorkIds,
+            });
+            const runBoundary = await applyRunBoundary({ plan, now: input.now });
+            // ⑥ 规则 5: 逐 workId 一份下发内容 (计划里已经算好; 这里只补"要不要先补全影响面")
+            const childDelivery = {
+                directives: plan.childDirectives,
+                workIds: plan.liveWorkIds,
+                scopeMissing: plan.childScopeMissing,
+                blocked: plan.childScopeMissing,
+                mustAck: true,
+                note: plan.childScopeMissing
+                    ? `在跑的 ${plan.liveWorkIds.length} 个子 Agent 必须收到变更版本, 但这条变更没点明影响面 → 下发前先用 scopeChangeToWork 补全 (不许静默漏发)`
+                    : plan.childDirectives.length
+                        ? `已为 ${plan.childDirectives.length} 个在跑的子 Agent 各生成一份下发内容 (每个都必须先 ack 再继续)`
+                        : '没有在跑的子 Agent 需要下发 (子 Agent 条款仍在下一 Run 指令里)',
+            };
+            // ⑦ 用户可见态: 有待拍板的变更 → "需要你决定" (只升不降; 基础态读不到也不编一个态出来)
+            const observed = await resolveBaseVisible(deps, { goalId: input.goalId, now: input.now });
+            const recorded = await deps.pending(input.goalId).catch(() => []);
+            const visible = changeVisibleState({
+                base: observed.base,
+                // 新入档这条用它自己的真实结论 (宿主回传的 request.status 停在分诊那一刻, 不是终态)
+                changes: dedupeChanges([
+                    ...recorded,
+                    { changeId: out.request.changeId, kind: out.request.kind, status: nextStatusFor(out.application.outcome) },
+                ]),
+            });
+            return {
+                request: out.request,
+                classification: out.application,
+                application: out.application,
+                instructionVerbatim: raw,
+                plan,
+                runBoundary,
+                childDelivery,
+                visibleState: visible.state,
+                visibleReason: observed.reason ? `${visible.reason}; ${observed.reason}` : visible.reason,
+                needsDisambiguation: out.request.status === 'received' || !out.request.interpreted,
+            };
+        },
+        applyRunBoundary,
+        nextRunDirective(goalId) {
+            return deps.nextRunDirective(goalId);
+        },
+        async markConsumed(goalId, runIndex, now) {
+            if (!Number.isInteger(runIndex) || runIndex < 0) {
+                throw new Error(`[change 接缝] markConsumed 的 runIndex 必须是 >=0 的整数 (收到 ${String(runIndex)}) —— 版本下发的记账不许记在一个不存在的 Run 序号上`);
+            }
+            await deps.markConsumed(goalId, runIndex, now);
+        },
+        async visibleState(input) {
+            const observed = await resolveBaseVisible(deps, { goalId: input.goalId, now: input.now });
+            const recorded = await deps.pending(input.goalId).catch(() => []);
+            // 基础态读不到且没有待拍板的变更 → null (不编一个态出来)
+            return changeVisibleState({ base: observed.base, changes: recorded }).state;
+        },
+        pendingChanges(goalId) {
+            return deps.pending(goalId);
+        },
+    };
+}