@bolloon/bolloon-agent 0.4.33 → 0.5.1

package/dist/agents/execution-supervisor.js

@@ -12,8 +12,21 @@
  * 但**事实来源永远是持久化记录** (GoalStore / RunStore / lease 文件), 不是内存状态。
  */
 import * as os from 'os';
-import { listRunnableGoals, claimGoal, heartbeatGoal, releaseGoal, readGoal, setContinuation, bumpContinuationAttempts, evaluateGoalCompletion, completeGoalIfEligible, addEvidence, } from './goal-store.js';
-import { readRun, reconcileOrphans, superviseRuns, buildContinuationPlan, RESUMABLE_STATUSES, } from './run-store.js';
+import { listRunnableGoals, claimGoal, heartbeatGoal, releaseGoal, readGoal, setContinuation, bumpContinuationAttempts, evaluateGoalCompletion, addEvidence, } from './goal-store.js';
+// 2026-09-26 (P7 接线): 长期任务的模型策略 —— 「下一个 Run 用哪一份模型」的唯一决定函数,
+//   以及「这次失败换模型能解决吗」的唯一判定函数 (Supervisor 不再自己看失败类别猜)。
+import { resolveNextRunModel, supervisorMaySwitchModel, parseGoalModelPolicy, formatModelDecision, isTerminalRunStatus, } from './model-policy.js';
+import { readRun, reconcileOrphans, superviseRuns, buildContinuationPlan, recordModelSwitch, RESUMABLE_STATUSES, } from './run-store.js';
+// 2026-09-25 (飞轮接线): P0–P4 的七个模块经**唯一**适配层接进真实执行路径
+//   (节奏由进展决定 · Run 收尾必过 closeRun · 子 Agent 走工作合同 · 阻塞监控 · 变更注入 · 用户可见态)
+// 2026-09-25 (串行收口): 四条线各自报"只有主线能加"的钩子在这里补齐 ——
+//   ① 节奏判定走 **M1 接缝的事实路径** (`preflightGoalStep`, 不再直连 `decideGoalStep`);
+//   ② Skill 试用在**候选产出处**开 (`closeGoalRun` 内部) / 在**下一条 Run 成功点**结算;
+//   ③ 阻塞巡检走 **M3 的统一巡检** (`flywheelSeams().monitor.sweepAll`, 不再自己拼一条循环);
+//   ④ 撤销走 **M4 的 change 接缝** (`ingestRequirement`, 非 web 宿主也能真停住在跑的 Run)。
+import { claimedTerminalKindForRun, closeRunOnce, dispatchChildWork, flywheelSeams, flywheelTickNote, ingestRequirementViaSeam, installRunTerminalHook, isRefusal, markChangesConsumed, mergeGoalOutcome, nextRunChangeDirective, pendingContractDigest, preflightGoalStep, settleSkillTrialsForRun, } from './goal-flywheel-wiring.js';
+// 2026-09-25 (M0 接线冻结, 规则 ②): Goal 状态只有一个写入出口
+import { reduceGoalState } from './goal-state-reducer.js';
 /** 自动继续的退避 (attempts → 等待毫秒)。0 次 = 立刻。 */
 export function continuationBackoffMs(attempts) {
     const steps = [0, 15_000, 60_000, 5 * 60_000, 15 * 60_000];
@@ -86,13 +99,19 @@ export function decideGoalOutcome(goal, run, opts = {}) {
         case 'failed':
         case 'needs_human': {
             const cls = run.errorClass || 'unknown';
+            // ★ 2026-09-26 (P7 接线): 这次失败"换一个模型能不能解决"由**唯一判定函数**回答, 不再由
+            //   Supervisor 这边看类别自己猜。结论照实写进 reason (含策略模式与理由), 但**不改写**任何
+            //   在跑的 Run —— 真正换模型发生在下一个 Run 的决定里 (`resolveNextRunModel`, 见 runGoal)。
+            const policyMode = parseGoalModelPolicy(goal.modelPolicy).policy.mode;
+            const modelVerdict = supervisorMaySwitchModel({ mode: policyMode, errorClass: run.errorClass });
+            const modelHint = `; 模型: 策略=${policyMode} · ${modelVerdict.reason}`;
             const needsHuman = ['auth', 'persist_failed', 'corrupt_state', 'policy_denied', 'repeat_failure', 'bad_args', 'no_such_tool'].includes(cls)
                 || attempts >= maxAttempts;
             if (needsHuman) {
                 return {
                     goalStatus: 'needs_human',
                     continuation: { ...base, autoContinue: false, wakeReason: 'needs_human', attempts },
-                    reason: `${cls} 需要人工介入${attempts >= maxAttempts ? ` (自动继续已试 ${attempts} 次)` : ''}`,
+                    reason: `${cls} 需要人工介入${attempts >= maxAttempts ? ` (自动继续已试 ${attempts} 次)` : ''}${modelHint}`,
                 };
             }
             const wait = continuationBackoffMs(attempts);
@@ -104,7 +123,7 @@ export function decideGoalOutcome(goal, run, opts = {}) {
                     wakeAt: new Date(now + wait).toISOString(),
                     attempts: attempts + 1,
                 },
-                reason: `可恢复错误 ${cls}: 第 ${attempts + 1} 次自动继续, ${Math.round(wait / 1000)}s 后唤醒`,
+                reason: `可恢复错误 ${cls}: 第 ${attempts + 1} 次自动继续, ${Math.round(wait / 1000)}s 后唤醒${modelHint}`,
             };
         }
         case 'recovering':
@@ -197,6 +216,11 @@ export class ExecutionSupervisor {
         this.tickCount++;
         const report = { ...this.emptyReport(), tick: this.tickCount };
         try {
+            // 0. (2026-09-25, M0 接线冻结) 把"Run 终止 → 唯一责任链"的钩子装上:
+            //    崩溃恢复 / 失速这两条终止路径由 run-store 判出, 由接线层收尾 (规则 ④)。
+            await installRunTerminalHook().catch((err) => {
+                report.errors.push(`Run 终止钩子安装失败: ${err?.message || err}`);
+            });
             // 1. 对账孤儿 (进程死了的 run) —— 只在启动后第一次做, 之后靠 tick 的常规巡检
             if (!this.reconciledOnce) {
                 report.reconciled = await reconcileOrphans();
@@ -249,8 +273,102 @@ export class ExecutionSupervisor {
             // 2. 扫描可执行 Goal
             const { runnable, skipped } = await listRunnableGoals({ now: this.now(), owner: this.owner });
             report.skipped = skipped;
-            // 3. 逐个推进 (每个 Goal: 抢 lease → 执行 → 决策 → 释放 lease)
+            const nowIso = new Date(this.now()).toISOString();
+            // 2.5 (2026-09-25, 飞轮接线 P3 + 串行收口): 阻塞巡检 —— **不看进程存活, 看任务是否卡住**
+            //   走 M3 的**统一巡检** (`flywheelSeams().monitor.sweepAll`): 一次调用 = 所有待回报 Goal 的
+            //   结论 (有界 + 失败留痕 + 每格带用户可见态)。之前 supervisor 自己拼了一条
+            //   `listGoalsWithPendingWork → collectWorkBlocks → applyBlockHandling` 的循环 —— 那是
+            //   第二套巡检实现 (`sweepAll` 才是 M3 的门面), 于是 M3 的"统一巡检"在真路径上从来没有调用方。
+            let monitorView = null;
+            try {
+                const view = await flywheelSeams().monitor.sweepAll({
+                    caller: 'supervisor',
+                    now: nowIso,
+                    runnerAvailable: this.canExecute,
+                });
+                if (isRefusal(view)) {
+                    // 拒绝不是"没有阻塞": 如实记进 errors, 不许静默当成巡检通过
+                    report.errors.push(`阻塞巡检被拒: ${view.reason}`);
+                }
+                else {
+                    monitorView = view;
+                    report.monitor = view;
+                    for (const cell of view.goals) {
+                        for (const a of cell.handling?.actions ?? []) {
+                            report.blocks.push({ goalId: cell.goalId, workId: a.workId, kind: a.kind, action: a.action, note: a.note });
+                        }
+                        if (cell.error)
+                            report.errors.push(`阻塞巡检 goal=${cell.goalId}: ${cell.error}`);
+                    }
+                    const acted = view.goals.filter((c) => (c.handling?.actions.length ?? 0) > 0);
+                    for (const c of acted) {
+                        this.log(`[supervisor] goal=${c.goalId} 阻塞巡检: ${(c.handling?.actions ?? []).map((a) => `${a.kind}→${a.action}`).join(', ')}`);
+                    }
+                    const escalated = [...new Set(view.escalated)];
+                    if (escalated.length) {
+                        // 巡检未完成 (silentRisk) 与"交人"是两回事: 前者是巡检自身没查成, 后者是任务真的卡住
+                        const why = view.silentRisk
+                            ? `巡检未完成 (silentRisk=true, 一个 Goal 都没查成): ${escalated.join(', ')}`
+                            : `子 Agent 工作升级到人: ${escalated.join(', ')}`;
+                        this.emit({ kind: 'needs_human', goalId: view.goals[0]?.goalId, message: why });
+                        this.log(`[supervisor] 阻塞巡检 → 交人: ${why}`);
+                    }
+                    if (view.takeovers.length)
+                        this.log(`[supervisor] 父接管子工作 (无心跳 + 执行权空闲 + 合同允许): ${view.takeovers.join(', ')}`);
+                    if (view.requests.length)
+                        this.log(`[supervisor] 阻塞巡检要求补齐: ${view.requests.join(', ')}`);
+                    if (view.errors.length && !escalated.length)
+                        report.errors.push(`阻塞巡检 (接缝自检): ${view.errors.join(' | ')}`);
+                }
+            }
+            catch (err) {
+                report.errors.push(`阻塞巡检: ${err?.message || err}`);
+            }
+            // 3. 逐个推进 (每个 Goal: 节奏判定 → 抢 lease → 执行 → 收尾 → 决策 → 释放 lease)
             for (const goal of runnable.slice(0, this.maxPerTick)) {
+                // 3.1 (P0 + M1 串行收口) 节奏由进展决定: 走 **M1 接缝的事实路径**
+                //     (`readFacts` 读 Goal/Run/进展/无进展连击 → 接缝用 P0 自己判 + 上限归因)。
+                //     事实拿不到时接缝内部才回落到旧注入口径, 并在 `step.source` 上如实标出来。
+                let step = null;
+                try {
+                    const pre = await preflightGoalStep({
+                        goalId: goal.goalId, now: nowIso, maxRetries: this.maxRetries, writeRecord: true,
+                    });
+                    if (pre && isRefusal(pre)) {
+                        // 接缝真拒 (caller 不是 supervisor / 没有 goalId) → 如实记, 不静默跳过
+                        report.errors.push(`${goal.goalId}: 节奏判定被拒: ${pre.reason}`);
+                    }
+                    else {
+                        step = pre;
+                    }
+                }
+                catch (err) {
+                    report.errors.push(`${goal.goalId}: 节奏判定失败 ${err?.message || err}`);
+                }
+                if (step) {
+                    // 阻塞结论复用**同一 tick 的统一巡检**结果 (没有那一格才自己读): 一条 tick 里不查第二遍
+                    const swept = monitorView?.goals.find((c) => c.goalId === goal.goalId)?.blocks ?? null;
+                    report.flywheel.push(await flywheelTickNote({ goalId: goal.goalId, step, now: nowIso, blocks: swept }).catch(() => ({
+                        goalId: goal.goalId,
+                        decision: step.decision?.decision ?? 'first_run',
+                        state: step.decision?.state ?? 'progressing',
+                        runnable: step.runnable,
+                        reason: step.reason,
+                        noProgressStreak: step.noProgressStreak,
+                        visibleState: 'executing',
+                        nextAction: step.decision?.nextAction ?? '(首个 Run)',
+                        source: step.source,
+                        basis: step.basis,
+                        caps: step.caps,
+                    })));
+                    if (!step.runnable) {
+                        report.skipped.push({ goalId: goal.goalId, reason: `飞轮: ${step.reason}` });
+                        await this.applyFlywheelStop(goal.goalId, step, nowIso).catch((err) => {
+                            report.errors.push(`${goal.goalId}: 飞轮停写失败 ${err?.message || err}`);
+                        });
+                        continue;
+                    }
+                }
                 const claimed = await claimGoal(goal.goalId, { owner: this.owner, ttlMs: this.leaseTtlMs });
                 if (!claimed.ok) {
                     report.skipped.push({ goalId: goal.goalId, reason: claimed.reason || 'claim 失败' });
@@ -259,7 +377,7 @@ export class ExecutionSupervisor {
                 report.claimed.push(goal.goalId);
                 const leaseId = claimed.lease.leaseId;
                 try {
-                    const res = await this.runGoal(goal, leaseId, report);
+                    const res = await this.runGoal(goal, leaseId, report, step);
                     report.executed.push(res);
                 }
                 catch (err) {
@@ -288,10 +406,58 @@ export class ExecutionSupervisor {
             payments: { scanned: 0, reconciled: [], awaitingPayment: [], mustNotRepay: [], closed: [], goalsWoken: [], goalsFlagged: [], errors: [] },
             supervised: { stalled: [], failed: [] },
             claimed: [], executed: [], skipped: [], errors: [], dryRun: !this.runner,
+            flywheel: [], blocks: [], monitor: null, skillTrials: [], skillTrialOpenings: [], closures: [], workContracts: [],
         };
     }
+    /**
+     * 飞轮说"不该跑"时, 该不该把"停"写进 Goal?
+     *
+     * 只有**明确要求停**的决策才写 (fail / pause / 无进展熔断 / 硬底线 / 阻塞):
+     * 这些是"停就是停"的判断, 不写下去的话下一个 tick 还会来问一遍 (且用户看不到原因)。
+     * 其余 `ask_human` (例如"本轮没有新证据, 未到熔断阈值 → 需要人定夺") 只**跳过本轮**、
+     * 不动状态: 那属于"没有继续的资格", 由运输层(退避/等外部)与人决定 ——
+     * 这样既不会用轮次冒充节奏, 也不会把一次没证据的 Run 直接判死。
+     */
+    async applyFlywheelStop(goalId, step, now) {
+        const d = step.decision;
+        if (!d)
+            return;
+        const hardLine = /硬底线/.test(step.reason);
+        const stop = d.decision === 'fail'
+            || d.decision === 'pause'
+            || (d.decision === 'ask_human' && (d.state === 'no_progress' || d.state === 'blocked'))
+            || hardLine;
+        if (!stop)
+            return;
+        const status = d.decision === 'fail' ? 'failed' : d.decision === 'pause' ? 'paused' : 'needs_human';
+        // 规则 ②: 状态与 continuation 都经 Goal reducer 写 (终态保护 / 完成门也在这里, 不全仓各写一遍)
+        const applied = await reduceGoalState({
+            goalId,
+            intent: 'flywheel_stop',
+            now,
+            by: this.owner,
+            stopStatus: status,
+            reason: d.reason,
+            decisionId: d.decisionId,
+            nextAction: d.nextAction,
+            unresolvedItems: d.unresolvedItems,
+        });
+        if (!applied.ok) {
+            this.log(`[supervisor] goal=${goalId} 飞轮判停写不进 Goal (不掩盖): ${applied.reason}`);
+        }
+        this.emit({ kind: status === 'needs_human' ? 'needs_human' : status, goalId, message: d.reason });
+        this.log(`[supervisor] goal=${goalId} 飞轮判停 → ${status}: ${d.reason}`
+            + `${applied.applied.length ? ` [${applied.applied.join(', ')}]` : ''}`);
+    }
     /** 认领后执行一个 Goal: 决定 resume 还是开新 Run → 跑 → 决策 Goal 状态 */
-    async runGoal(goal, leaseId, report) {
+    async runGoal(goal, leaseId, report, 
+    /**
+     * ★ 2026-09-25 (串行收口): 主循环**这一刻**已经落定的节奏判定 (3.1 的结果)。
+     * 传下来的理由: 「同一条 tick 里事实只读一次」。以前门禁自己又 `preflightGoalStep()` 了一遍,
+     * 于是同一次事实读留痕翻倍、而且门禁看到的是**另一个时刻**的事实 —— 与
+     * `flywheelTickNote` 复用统一巡检结论 (`blocks`) 是同一条纪律。
+     */
+    tickStep = null) {
         // 乐观并发检查: 认领后重新读一次 —— 若这个 Goal 在我扫描之后已被别的 worker 推进
         //   (状态/当前 run/run 列表/continuation 变了), 就让路。否则同一个状态版本会被两个 worker 各跑一次。
         const freshGoal = await readGoal(goal.goalId);
@@ -302,11 +468,21 @@ export class ExecutionSupervisor {
         }
         // 到点唤醒 (2-C.3): 这条 Goal 之前是 retry_wait —— 现在唤醒它, 旧的 wakeAt/wakeReason 必须清掉,
         //   否则下一轮 tick 还会把它当"等时间"重复跳过 (或留下过期的等待事实)。
+        // ★ M5-⑦ (2026-09-25 真跑): **状态也要一起拉回 `active`** —— 旧写法只清 continuation, `goal.status`
+        //   仍停在 `retry_wait`; 这条 Run 跑完后的收尾判定读到 stale 的 `retry_wait` → 判 `wait`, 合并规则
+        //   再把"等"落成 `awaiting_external` (wakeAt 已清空 ⇒ 只能靠事件唤醒) ⇒ **刚有进展的目标被挂起来,
+        //   没人会再跑它** (P6-③ 时钟用例阴性对照判红 + 临时探针复现)。走唯一漏斗 (规则 ②)。
         if (goal.continuation?.wakeReason === 'retry_wait' || goal.status === 'retry_wait') {
-            await setContinuation(goal.goalId, { wakeReason: 'active', wakeAt: undefined });
+            await reduceGoalState({
+                goalId: goal.goalId,
+                intent: 'scheduled_wake',
+                now: new Date(this.now()).toISOString(),
+                by: this.owner,
+                reason: `到点唤醒 (wakeAt=${goal.continuation?.wakeAt ?? '-'} 已到) → 回到可继续, 清 wakeAt 并拉回 active`,
+            });
             report.skipped.push({ goalId: goal.goalId, reason: `到点唤醒: 已清 wakeAt (第 ${(goal.continuation?.attempts || 0) + 1} 次自动继续)` });
             this.emit({ kind: 'retry_woke', goalId: goal.goalId, message: `到点唤醒, 第 ${(goal.continuation?.attempts || 0) + 1} 次自动继续` });
-            this.log(`[supervisor] goal=${goal.goalId} retry_wait 到点 → 唤醒并清 wakeAt`);
+            this.log(`[supervisor] goal=${goal.goalId} retry_wait 到点 → 唤醒 (状态拉回 active) 并清 wakeAt`);
         }
         // ★ 2026-09-18 (M2 收口): `bolloon task` 建的目标走**同一个恢复决策函数**
         //   (`decideTaskRecovery`) —— CLI `task --resume` 与 Supervisor 不再各判一次。
@@ -333,9 +509,68 @@ export class ExecutionSupervisor {
         const prevRun = prevRunId ? await readRun(prevRunId) : null;
         const plan = prevRunId ? await buildContinuationPlan(prevRunId).catch(() => null) : null;
         const guards = plan?.replayGuards || [];
-        const instruction = plan
+        // ★ 2026-09-26 (P7 接线): 下一个 Run 该用**哪一份**模型配置 —— 唯一决定函数 `resolveNextRunModel`。
+        //   它自己走完四步: ① 读 Goal 策略 (记录上的 modelPolicy 优先, 没有才读 sidecar);
+        //   ② 定稿配置 (auto → 最新 Global 默认; pinned → 固定三元组; session → 会话绑定);
+        //   ③ 按**失败类别**判定能不能挑备用模型 (内部就是 `supervisorMaySwitchModel`);
+        //   ④ 跨 Run 非幂等守卫照带 (模型换了也不重做副作用), 并把这次决定写成 Run 事件。
+        //   它算的是**下一条** Run: 在跑的那条 Run 的快照一个字都不动 (旧 Run 可追溯)。
+        //
+        //   ⚠ **事件落点** (接线时真跑逼出来的, 不是设计洁癖): P7 自己文档里的事实边界是
+        //   「本层算出来的只用于①下一个 Run 的启动快照 ②切换事件 —— **它不回头改老 Run**」,
+        //   飞轮规则 ⑦ (`goal-flywheel-wiring.test.ts`) 更是**逐字节**钉住「已发生的 Run 记录不被改写」。
+        //   而决定函数的事件缺省落点是 `prevRunId` —— 上一条 Run **已经收尾**时, 那条写入等于
+        //   往历史记录上追加一格 (真跑实测: `updatedAt`/`modelSwitches`/`harness` 全变 ⇒ 判红)。
+        //   所以分两种, 都说清: 上一条 Run **还活着** → 事件就写它 (它是当事 Run, 也是缺省);
+        //   **已收尾** → 它是历史, 决定"只算不写", 等新 Run 起来后把同一条决定记到**新 Run 自己**的
+        //   账本上 (`RunModelSwitchEvent.to` 的语义本来就是"这个 Run **或下一个 Run** 该用的那一份")。
+        const prevIsHistory = prevRun ? isTerminalRunStatus(prevRun.status) : true;
+        let modelResolution = null;
+        try {
+            // 备用候选: 只有上一个 Run 是**模型相关失败**时才值得去凑 (凑法在切换入口里, 只挑现在真能用的)
+            const fallbackCandidates = prevRun?.errorClass
+                ? await (async () => {
+                    const ms = await import('../llm/model-selection.js');
+                    return await ms.usableFallbackCandidates(prevRun.modelConfig ?? null);
+                })().catch(() => [])
+                : [];
+            modelResolution = await resolveNextRunModel({
+                goalId: goal.goalId,
+                // 上一条 Run 已收尾 = 历史 → 不给事件落点 (P7 契约里"只算不写"的那一档), 免得往历史追加
+                ...(prevIsHistory ? {} : { prevRunId: prevRunId || undefined }),
+                policy: goal.modelPolicy,
+                errorClass: prevRun?.errorClass,
+                ...(fallbackCandidates.length ? { fallbackCandidates } : {}),
+            });
+        }
+        catch (err) {
+            // 算不出来**不猜**: 下一句日志说清, 执行器按自己的默认启动 (Run 记录里因此没有模型快照)
+            this.log(`[supervisor] goal=${goal.goalId} 下一个 Run 的模型决定算不出来 (按无快照启动): ${String(err?.message || err).slice(0, 160)}`);
+        }
+        const nextModelConfig = modelResolution?.startRunModelConfig;
+        if (modelResolution) {
+            this.log(`[supervisor] goal=${goal.goalId} 下一个 Run 模型: ${formatModelDecision(modelResolution.decision)}`
+                + `; 策略来源=${modelResolution.policyOrigin}`
+                + `${modelResolution.startRunModelConfig ? `; 启动快照 hash=${modelResolution.startRunModelConfig.configHash}` : '; 没有可信快照 → 不写快照'}`
+                + `; 事件=${modelResolution.event.ok
+                    ? `已写(Run ${modelResolution.event.onRunId || '-'})`
+                    : prevIsHistory && modelResolution.startRunModelConfig
+                        ? '等新 Run 起来后写在它自己的账本上 (上一条 Run 已收尾 = 历史, 不许改写)'
+                        : `未写(${modelResolution.event.reason || '原因未明'})`}`);
+        }
+        // 2026-09-25 (飞轮接线 P4 / P2): 下一个 Run 必须真的读到**同一份**事实 ——
+        //   ① 权威 continuation 的 nextAction (飞轮收尾写下的"下一步是什么");
+        //   ② 已生效的新要求 (变更注入: 只影响后续 Run, 不改写历史);
+        //   ③ 还在等回报的子 Agent 工作合同 (规则 5: 子必须拿到同一份合同)。
+        const continuationHint = goal.continuation?.nextAction ? `\n飞轮下一步 (权威 continuation): ${goal.continuation.nextAction}` : '';
+        const changeHint = await nextRunChangeDirective(goal.goalId).catch(() => null);
+        const contractHint = await pendingContractDigest(goal.goalId).catch(() => null);
+        const instruction = (plan
             ? `继续这个目标 (不要重头开始):\n目标: ${plan.objective || goal.objective}\n已完成 ${plan.completedSteps.length} 步; 下一步: ${plan.nextAction}`
-            : `开始执行这个目标:\n目标: ${goal.objective}${goal.successCriteria.length ? `\n完成判据: ${goal.successCriteria.join('; ')}` : ''}`;
+            : `开始执行这个目标:\n目标: ${goal.objective}${goal.successCriteria.length ? `\n完成判据: ${goal.successCriteria.join('; ')}` : ''}`)
+            + continuationHint
+            + (changeHint ? `\n${changeHint}` : '')
+            + (contractHint ? `\n${contractHint}` : '');
         const kind = !prevRun ? 'first_run'
             : RESUMABLE_STATUSES.includes(prevRun.status) ? 'resume'
                 : 'continue_new_run';
@@ -348,7 +583,7 @@ export class ExecutionSupervisor {
         if (!runner && this.resolver) {
             let res;
             try {
-                res = await this.resolver({ goal, kind, prevRunId, instruction, guards });
+                res = await this.resolver({ goal, kind, prevRunId, instruction, guards, ...(nextModelConfig ? { modelConfig: nextModelConfig } : {}) });
             }
             catch (err) {
                 res = { ok: false, kind: 'none', reason: `resolver 抛错: ${String(err?.message || err).slice(0, 140)}` };
@@ -367,12 +602,37 @@ export class ExecutionSupervisor {
             return { goalId: goal.goalId, status: 'unresolved' };
         }
         // 2026-09-16 (2-G.2): 执行前技能就绪门禁 —— 缺/未启用/损坏/漂移 → 不启动 Run, Goal → needs_human
+        //
+        // ★ 2026-09-25 (P5 验收修复): 飞轮这一步的裁决是 **delegate** (缺能力 → 派给子 Agent 并签工作合同)
+        //   时, **本地技能门禁不适用** —— 这一步本来就不由本节点执行, 能力由子 Agent 凭合同交付。
+        //   原来一律拦成 `blocked_by_skills`, 于是"缺能力 → 派活"这条链在真路径上永远走不到,
+        //   `dispatchIfDelegate` 成了死代码 (P5 ★①②③ 实测: 合同一份都没签发)。
+        //   其余裁决 (continue/first_run/...) 照旧: 技能不就绪照样不启动 Run (门禁没有放松)。
+        let flywheelDelegates = false;
+        let flywheelCapability = '';
+        // 与 3.1 **同一份**判定 (而且是**同一次**事实读): 主循环算好的 `tickStep` 直接沿用 ——
+        // 旧写法在这里又 `preflightGoalStep()` 了一遍 (判定口径同, 但事实读了两遍、时刻也不同)。
+        // `tickStep === null` (主循环没判成 / 门禁被单独调用) → 按"没有裁决"处理 (fail-closed, 照旧拦)。
+        {
+            flywheelDelegates = tickStep?.decision?.decision === 'delegate';
+            flywheelCapability = tickStep?.decision?.requiredCapability || '';
+        }
         try {
-            const { ensureGoalSkillsReady, blockGoalOnSkills } = await import('./skill-readiness.js');
+            const { ensureGoalSkillsReady, blockGoalOnSkills, recordSkillReadiness } = await import('./skill-readiness.js');
             const ready = await ensureGoalSkillsReady(goal);
             for (const d of ready.degradations)
                 this.log(`[supervisor] goal=${goal.goalId} 技能降级: ${d}`);
-            if (!ready.ok) {
+            if (!ready.ok && flywheelDelegates) {
+                // 本地缺的能力由子 Agent 提供: 记清楚"放过门禁的原因", 不静默。
+                // 这里**不进** report.skipped —— 门禁放过 = 本轮**真跑**了 (Run + 之后的合同签发),
+                // 记成 skipped 会与事实相反。
+                await recordSkillReadiness(goal.goalId, ready).catch(() => { });
+                const why = `飞轮裁决=delegate (缺能力「${flywheelCapability || '-'}」) → 本地技能门禁不适用, `
+                    + `本轮照跑(不拦)并改为签发工作合同交给子 Agent; 本地缺: ${ready.reason || ''}`;
+                this.log(`[supervisor] goal=${goal.goalId} 技能门禁对 delegate 放行: ${why}`);
+                this.emit({ kind: 'skill_gate_waived_for_delegate', goalId: goal.goalId, message: why });
+            }
+            else if (!ready.ok) {
                 await blockGoalOnSkills(goal.goalId, ready);
                 report.skipped.push({ goalId: goal.goalId, reason: `技能未就绪: ${ready.reason}` });
                 this.emit({ kind: 'needs_human', goalId: goal.goalId, message: ready.reason || '技能未就绪' });
@@ -398,7 +658,7 @@ export class ExecutionSupervisor {
         let result;
         const t0 = Date.now();
         try {
-            result = await runner({ goal, kind, prevRunId, instruction, guards });
+            result = await runner({ goal, kind, prevRunId, instruction, guards, ...(nextModelConfig ? { modelConfig: nextModelConfig } : {}) });
         }
         catch (err) {
             result = { error: err?.message || String(err) };
@@ -406,6 +666,30 @@ export class ExecutionSupervisor {
         finally {
             clearInterval(hb);
         }
+        // ★ 2026-09-26 (P7 接线): 决定"只算不写"的那一档, 把同一条决定**补写进它真正生效的那条 Run**。
+        //   为什么不写在算决定的那一刻: 那时新 Run 还没有 id, 而唯一的现成落点是已经收尾的上一条 Run
+        //   —— 那是历史 (`prevIsHistory` 分支就是为了不碰它)。落点等执行器报回 runId 再定, 事实不丢。
+        const runIdOfThisRun = result.runId && result.runId !== prevRunId ? result.runId : null;
+        if (modelResolution && nextModelConfig && runIdOfThisRun && !modelResolution.event.ok
+            && prevIsHistory && (await readRun(runIdOfThisRun).catch(() => null))) {
+            const d = modelResolution.decision;
+            const from = prevRun?.modelConfig ?? null;
+            // 同口径 = 同一份 `configHash` 就是同一份 (P7 的 configHash 契约), 别自己另立一套
+            const outcome = (d.conflict && d.conflict.length) ? 'conflict'
+                : (from && from.configHash === nextModelConfig.configHash) ? 'frozen' : 'switched';
+            const w = await recordModelSwitch(runIdOfThisRun, {
+                to: nextModelConfig,
+                from,
+                outcome,
+                mode: (d.mode === 'auto' || d.mode === 'pinned' || d.mode === 'session' ? d.mode : 'unknown'),
+                source: d.source,
+                reason: `${d.reason}; 事件落在新 Run (上一条 Run 已收尾 = 历史, 不许改写)`.slice(0, 400),
+                guardsCarried: guards.length,
+                goalId: goal.goalId,
+            });
+            this.log(`[supervisor] goal=${goal.goalId} 模型决定补写在新 Run ${runIdOfThisRun} 的账本上: `
+                + `${w.ok ? `outcome=${outcome}` : `写不进去 (${w.reason || '原因未明'})`}`);
+        }
         // Run 结束 → Goal 决策 (确定性 reducer, 落盘)
         const finalRunId = result.runId || prevRunId;
         const finalRun = finalRunId ? await readRun(finalRunId) : null;
@@ -434,55 +718,311 @@ export class ExecutionSupervisor {
         }
         // 重新读一次 Goal: Run 期间判据可能已被满足 (否则会拿旧快照判决)
         const goalForDecision = (await readGoal(goal.goalId)) || goal;
-        const decision = decideGoalOutcome(goalForDecision, finalRun, { now: this.now(), maxAttempts: this.maxRetries, lastRunStatus: finalRun?.status });
-        await this.applyDecision(goal, decision, finalRun);
-        this.emit({ kind: 'goal_decision', goalId: goal.goalId, runId: finalRunId, message: `${finalRun?.status || result.status || '?'} → ${decision.goalStatus}: ${decision.reason}` });
-        this.log(`[supervisor] goal=${goal.goalId} run=${finalRunId || '-'} ${finalRun?.status || result.status || '?'} → goal=${decision.goalStatus} (${decision.reason}) ${Date.now() - t0}ms`);
+        const legacy = decideGoalOutcome(goalForDecision, finalRun, { now: this.now(), maxAttempts: this.maxRetries, lastRunStatus: finalRun?.status });
+        // ★ 2026-09-25 (飞轮接线 P1): Run 结束**必过收尾飞轮** —— 正常 / 失败 / 中断恢复都走同一条
+        //   9 步流水线 (写 Memory · 生成 Skill 候选 · 更新 continuation · 生成用户汇报)。
+        //   飞轮决策是权威 (是否继续), 既有 reducer 退化为运输层 (退避/wakeAt/attempts) —— 见 mergeGoalOutcome。
+        let closureDecision = null;
+        let merged = {
+            goalStatus: legacy.goalStatus,
+            continuation: legacy.continuation,
+            reason: legacy.reason,
+            flywheelStop: false,
+            roundsOverridden: false,
+        };
+        /** 本轮收尾要派遣的能力 (定状态之后才签合同 —— 顺序见下方注释) */
+        let capabilityWanted = null;
+        if (finalRun) {
+            try {
+                const closureRes = await closeRunOnce({
+                    goalId: goal.goalId,
+                    runId: finalRun.runId,
+                    caller: 'supervisor',
+                    now: new Date(this.now()).toISOString(),
+                    finalReview: this.finalReviewText(finalRun, result),
+                    maxRetries: this.maxRetries,
+                    // ★ 串行收口: 把**申明**的终止原因透传下去 (超时 / 权限·支付·工具失败 / 子阻塞 / 人工停)
+                    //   —— 只由 Run 事实推导的话回执里只剩笼统的 failure。这里给的就是从该 Run 事实推出来的那一个
+                    //   (`claimedTerminalKindForRun` 只在事实足够具体时给更细的类别, 且必须与该状态相容)。
+                    terminalKind: claimedTerminalKindForRun(finalRun),
+                });
+                if (isRefusal(closureRes)) {
+                    // 说不清是哪条 Run 的收尾 → 如实记, 不当收过 (也不编一份产物)
+                    report.errors.push(`${goal.goalId}: 收尾被拒: ${closureRes.reason}`);
+                    this.emit({ kind: 'run_closure_refused', goalId: goal.goalId, runId: finalRun.runId, message: closureRes.reason });
+                }
+                else if (!closureRes.outcome) {
+                    report.errors.push(`${goal.goalId}: ${closureRes.reason}`);
+                    this.emit({ kind: 'run_closure_facts_missing', goalId: goal.goalId, runId: finalRun.runId, message: closureRes.reason });
+                }
+                else {
+                    const view = closureRes.outcome;
+                    closureDecision = view.decision;
+                    merged = mergeGoalOutcome({
+                        legacy,
+                        flywheel: { decision: view.decision, continuation: view.continuation },
+                        run: finalRun,
+                        pendingReports: goalForDecision.continuation?.pendingReports ?? [],
+                        now: new Date(this.now()).toISOString(),
+                    });
+                    report.closures.push({
+                        goalId: goal.goalId,
+                        runId: finalRun.runId,
+                        steps: view.steps,
+                        decision: view.decision.decision,
+                        memories: view.memories,
+                        candidates: view.candidates,
+                        // ★ 串行收口 ②(入口): 这次收尾**开出**的 Skill 试用逐条登记 (结构化面, 与
+                        //   `skillTrialOpenings` 同一份事实) —— 候选写出来了但没开试用, 这里就短一截, 一眼可见
+                        trials: [...(view.trials ?? [])].map((t) => ({ ...t, goalId: goal.goalId, runId: finalRun.runId })),
+                        reportPath: view.reportPath,
+                        decisionRecordPath: view.decisionRecordPath,
+                    });
+                    // ★ 串行收口 ②(入口): 候选产出处开出的试用 —— 逐个登记 (候选写了但没开试用 = 数组短了, 一眼可见)
+                    for (const t of view.trials ?? []) {
+                        report.skillTrialOpenings.push({ ...t, goalId: goal.goalId, runId: finalRun.runId });
+                        if (t.ok)
+                            this.log(`[supervisor] goal=${goal.goalId} Skill 试用开出: ${t.skillName} (候选 ${t.candidateId})`);
+                        else
+                            this.log(`[supervisor] goal=${goal.goalId} Skill 试用未开 (卡在 ${t.refusal?.stage ?? '?'}): ${t.skillName} — ${t.refusal?.reason ?? ''}`);
+                    }
+                    this.emit({
+                        kind: 'run_closure',
+                        goalId: goal.goalId,
+                        runId: finalRun.runId,
+                        message: `收尾 ${view.steps} 步 → ${view.decision.decision}`
+                            + `${closureRes.alreadyClosed ? ' [幂等: 这次收尾由 Runner 先做, 事实读回]' : ''}`
+                            + ` (memory ${view.memories} · skill 候选 ${view.candidates} · 用户汇报 ${view.userReport.visibleState})`,
+                    });
+                }
+            }
+            catch (err) {
+                // 收尾失败**不掩盖**: 如实记进 errors, 但仍按运输层决策收口 (不许因为收尾炸了就不写状态)
+                report.errors.push(`${goal.goalId}: Run 收尾失败: ${err?.message || err}`);
+                this.emit({ kind: 'run_closure_failed', goalId: goal.goalId, runId: finalRun.runId, message: String(err?.message || err) });
+            }
+            // ★ 串行收口 ②: **下一条 Run 的成功点**结算 Skill 试用 (通道 ⑥ 的真调用方)。
+            //   顺序在这里的理由: 试用的兑现证据 = "另一条 Run 成功 + 它的证据面点名了这个 Skill",
+            //   所以必须在这条 Run 的结局**已知**之后 (收尾写下的证据面正好是它的输入)。
+            //   不成功 → 回退 (rolled_back) 且**不提升**; 成功但证据面没点名 → 留在试用位 (无证据不算复用)。
+            //   只写记录 (校验+快照+可回退), 永不写 skills/ —— 见 settleSkillTrialsForRun 的纪律。
+            try {
+                const settled = await settleSkillTrialsForRun({
+                    goalId: goal.goalId,
+                    runId: finalRun.runId,
+                    runStatus: String(finalRun.status ?? ''),
+                    now: new Date(this.now()).toISOString(),
+                    approvedBy: 'supervisor',
+                });
+                for (const s of settled) {
+                    report.skillTrials.push({ ...s, runId: finalRun.runId });
+                    if (s.promoted) {
+                        this.log(`[supervisor] goal=${goal.goalId} Skill 试用提升: ${s.skillName} → ${s.toVersion} (候选 ${s.candidateId})`);
+                        this.emit({ kind: 'skill_trial_promoted', goalId: goal.goalId, runId: finalRun.runId, message: s.reason });
+                    }
+                    else if (s.status !== 'trialing') {
+                        this.log(`[supervisor] goal=${goal.goalId} Skill 试用回退 (不提升): ${s.skillName} — ${s.reason}`);
+                        this.emit({ kind: 'skill_trial_rolled_back', goalId: goal.goalId, runId: finalRun.runId, message: s.reason });
+                    }
+                }
+            }
+            catch (err) {
+                // 结算失败不掩盖 (也不影响 Run 的收口): 如实记进 errors
+                report.errors.push(`${goal.goalId}: Skill 试用结算失败: ${err?.message || err}`);
+            }
+            // P2: 飞轮说"这一步该派活" → **必发工作合同** (不是发一句话)
+            //   能力来源 (权威顺序): ① 这次收尾决策点名的能力 ② continuation 上记的 requiredAgent
+            //   ③ **本轮跑之前**飞轮裁决=delegate 时点名的能力 (且本地**仍然**缺它) ——
+            //      收尾决策只拿得到 Run 的结果, 拿不到"目标声明的能力本地有没有"这条输入,
+            //      所以"缺能力 → 派活"必须能回落到 preflight 的结论; 否则它永远只在判定层成立、
+            //      在动作层消失 (P5 ★① 实测: 技能门禁放行之后, 合同还是一份都签不出来)。
+            const stillMissing = (await readGoal(goal.goalId))?.continuation?.skillReadiness;
+            const stillMissingCap = !!flywheelCapability && stillMissing?.ok === false
+                && (stillMissing.missing ?? []).includes(flywheelCapability);
+            capabilityWanted = closureDecision?.requiredCapability
+                || merged.continuation.requiredAgent
+                || (stillMissingCap ? flywheelCapability : null);
+            // 变更注入的"版本已下发"记账 (新要求只影响后续 Run; 记下它被第几个 Run 读到)
+            await markChangesConsumed(goal.goalId, goalForDecision.runs.length).catch(() => null);
+        }
+        await this.applyDecision(goal, merged, finalRun);
+        // ★ 合同必须在**状态写完之后**签发 (P5 ★① 实测的顺序缺陷):
+        //   `applyDecision` 是整份 continuation 的覆盖写 (`setContinuation(decision.continuation)`),
+        //   而 `dispatchChildWork` 会把"等这份回报"写进 `continuation.pendingReports` ——
+        //   先签发再写状态 ⇒ 刚登记的 pendingReports 立刻被覆盖成空, 父 Goal 上不留痕,
+        //   阻塞巡检再次没有输入 (与修复前一样"空转")。顺序: 定状态 → 签合同。
+        if (finalRun && capabilityWanted && merged.goalStatus !== 'completed' && !merged.flywheelStop) {
+            await this.dispatchIfDelegate(goal.goalId, finalRun, report, capabilityWanted).catch((err) => {
+                report.errors.push(`${goal.goalId}: 派遣合同失败: ${err?.message || err}`);
+            });
+        }
+        this.emit({ kind: 'goal_decision', goalId: goal.goalId, runId: finalRunId, message: `${finalRun?.status || result.status || '?'} → ${merged.goalStatus}: ${merged.reason}` });
+        this.log(`[supervisor] goal=${goal.goalId} run=${finalRunId || '-'} ${finalRun?.status || result.status || '?'} → goal=${merged.goalStatus} (${merged.reason})`
+            + `${merged.roundsOverridden ? ' [飞轮覆盖轮次上限]' : ''} ${Date.now() - t0}ms`);
         return { goalId: goal.goalId, runId: finalRunId, status: finalRun?.status || result.status, error: result.error };
     }
+    /**
+     * Run 收尾用的 Final Review 文本 (P1 的输入契约, 见 run-closure.ts 文件头):
+     *   ① 宿主/验收可用 `BOLLOON_RUN_FINAL_REVIEW` 注入结构化评审 (评审人 + 事实 + 教训 + 候选);
+     *   ② 否则用执行器这次给的回执文本 —— 散文**也能收尾** (评论非结构化只影响"是否产出教训/候选",
+     *      不会让收尾整条跳过)。
+     */
+    finalReviewText(run, result) {
+        const injected = process.env.BOLLOON_RUN_FINAL_REVIEW;
+        if (injected && injected.trim())
+            return injected;
+        const parts = [
+            result.reply,
+            run.summary,
+            run.error,
+        ].filter((s) => typeof s === 'string' && s.trim().length > 0);
+        return parts.join('\n');
+    }
+    /** 飞轮要求派遣 (decision=delegate) → 签发工作合同并把"等回报"写进 continuation */
+    async dispatchIfDelegate(goalId, run, report, capability = '') {
+        if (!capability)
+            return;
+        const goal = await readGoal(goalId);
+        if (!goal)
+            return;
+        const nextAction = goal.continuation?.nextAction || `把需要「${capability}」的子目标派出去`;
+        const contract = await dispatchChildWork({
+            goalId,
+            parentRunId: run.runId,
+            // 合同只锁"能力", 具体派给谁由执行器解析 (这里如实写能力名, 不假装知道某个 agent 的 id)
+            childAgentId: capability,
+            capability,
+            objective: nextAction,
+            inputs: { goalObjective: goal.objective, successCriteria: goal.successCriteria },
+            allowedTools: [],
+            budget: { maxSteps: null, maxDurationMs: run.budget?.deadlineMs ?? null, maxAmount: null, currency: null },
+            deadline: null,
+            successCriteria: goal.successCriteria.length ? goal.successCriteria : [nextAction],
+            issuedBy: this.owner,
+        });
+        this.log(`[supervisor] goal=${goalId} 已签发工作合同 workId=${contract.workId} (能力「${capability}」, ${contract.successCriteria.length} 条判据, 必带证据 ${contract.requiredEvidence.length} 条)`);
+        this.emit({ kind: 'work_contract_issued', goalId, runId: run.runId, message: `workId=${contract.workId} 能力=${capability}` });
+        report.workContracts.push({ goalId, workId: contract.workId, capability });
+    }
     /** 把决策写进 Goal (+ 证据同步 + 完成出口), 并写下一次唤醒信息 */
     async applyDecision(goal, decision, run) {
-        const { updateGoal } = await import('./goal-store.js');
         // 证据同步: Run 的成功步骤 → Goal 证据 (长期执行的判据要有据可依)
         if (run) {
             const ev = run.steps.filter((s) => s.ok).slice(-5).map((s) => `${run.runId}/${s.tool}: ${String(s.summary || '(完成)').slice(0, 120)}`);
             if (ev.length)
                 await addEvidence(goal.goalId, ev).catch(() => null);
         }
-        // 唯一完成出口: 只有经 completeGoalIfEligible 才能把 Goal 判成 completed
-        if (decision.goalStatus === 'completed') {
-            // 完成门 (判据存在 + 已确认 + 全满足 + 有证据 + 无未解决项 + 最近 Run 健康)
-            const r = await completeGoalIfEligible(goal.goalId);
-            if (!r.ok) {
-                // 完成门拒绝 → 如实退回 active, 并保留原因 (不许装作完成)
-                await setContinuation(goal.goalId, { ...decision.continuation, wakeReason: 'active', autoContinue: true });
-                await updateGoal(goal.goalId, { status: 'active' });
-                this.log(`[supervisor] goal=${goal.goalId} 完成门拒绝: ${r.reason}`);
-                return;
-            }
-            if (decision.continuation.wakeReason !== 'completed')
-                await setContinuation(goal.goalId, decision.continuation);
-            this.emit({ kind: 'goal_completed', goalId: goal.goalId, runId: run?.runId, message: decision.reason });
+        // 规则 ②: 唯一落盘出口。完成门 (completed 必须过 completeGoalIfEligible) 也在 reducer 里,
+        //   门拒绝 → 退回 active 并保留原因 (不许装作完成)。
+        const applied = await reduceGoalState({
+            goalId: goal.goalId,
+            intent: 'closure_outcome',
+            now: new Date(this.now()).toISOString(),
+            by: this.owner,
+            outcome: {
+                goalStatus: decision.goalStatus,
+                continuation: decision.continuation,
+                reason: decision.reason,
+            },
+            runId: run?.runId ?? null,
+        });
+        if (applied.gateRejected) {
+            this.log(`[supervisor] goal=${goal.goalId} 完成门拒绝: ${applied.gateRejected}`);
+        }
+        if (!applied.ok) {
+            this.log(`[supervisor] goal=${goal.goalId} 决策写不进 Goal (不掩盖): ${applied.reason}`);
+            return;
+        }
+        if (applied.status === 'completed') {
+            this.emit({ kind: 'goal_completed', goalId: goal.goalId, runId: run?.runId, message: applied.reason });
             return;
         }
-        if (decision.goalStatus !== goal.status)
-            await updateGoal(goal.goalId, { status: decision.goalStatus });
-        await setContinuation(goal.goalId, decision.continuation);
-        if (decision.continuation.wakeReason === 'needs_human') {
+        if (decision.continuation.wakeReason === 'needs_human' || applied.status === 'needs_human') {
             this.emit({ kind: 'needs_human', goalId: goal.goalId, message: decision.reason });
         }
     }
-    /** 外部事件到达 → 给对应 Goal 清除等待并加速唤醒 (2-E 第 4 类的入口) */
+    /**
+     * 外部事件到达 → 给对应 Goal 清除等待并加速唤醒 (2-E 第 4 类的入口)
+     * 手动唤醒 (CLI `/wake` / `POST /api/goals/:id/wake`): 人明确说"外部条件我已经满足了"。
+     *
+     * ★ 2026-09-25 (P5 验收修复): 原来只清等待事实、**不改 goal.status** —— `listRunnableGoals`
+     *   又按 `status === 'awaiting_external'` 直接跳过, 于是"唤醒"成了空操作:
+     *   接口回话 `woke:true`, 目标却仍然醒不过来 (真 tick executed=0)。
+     *   真事件路径 (`deliverExternalEvent`) 本来就把状态拉回 `active` —— 两条唤醒路径必须一致。
+     *
+     * 只拉**等待类**状态: 终态与人已判定的状态 (completed/failed/abandoned/paused/needs_human)
+     * 不动 —— 唤醒是"外部条件到了", 不是绕过人的决定。
+     */
     async notifyExternal(goalId) {
         const g = await readGoal(goalId);
         if (!g)
             return false;
         if (g.continuation?.wakeReason !== 'awaiting_external' && !g.continuation?.needsExternal)
             return false;
-        await setContinuation(goalId, { wakeReason: 'active', needsExternal: undefined, autoContinue: true, wakeAt: undefined });
+        // 等待类的 continuation.state 也要拉回 `active` (与 goal.status 同步): 界面只读 continuation
+        //   (`toUserVisibleState`), 留着 `awaiting_external` 的话页面仍显示"等待外部回复" ——
+        //   与"已唤醒、下一次 tick 会推进它"自相矛盾 (真 DOM 就是这么读到的)。
+        const wasWaiting = ['awaiting_external', 'retry_wait'].includes(String(g.continuation?.state));
+        await setContinuation(goalId, {
+            wakeReason: 'active', needsExternal: undefined, autoContinue: true, wakeAt: undefined,
+            ...(wasWaiting ? { state: 'active' } : {}),
+        });
+        if (g.status === 'awaiting_external') {
+            // 规则 ②: 唤醒也是一种 Goal 状态变更 → 走 Goal reducer, 不在调用方手写 updateGoal
+            await reduceGoalState({
+                goalId,
+                intent: 'manual_wake',
+                now: new Date().toISOString(),
+                by: 'human',
+                reason: '人工唤醒 (外部条件已满足)',
+            }).catch(() => null);
+        }
         await bumpContinuationAttempts(goalId); // 记一次唤醒 (可观测)
         return true;
     }
+    /**
+     * ★ 2026-09-25 (串行收口 ④): **非 web 路径**提一条新要求/撤销 —— CLI 与宿主进程都走它。
+     *
+     * 为什么要挂在 Supervisor 上: 撤销 (用户说"别继续做了") 的语义是"停住在跑的 Run + 只影响后续 Run",
+     * 而这件事**只有一个正确做法** (M4 的 change 接缝: 判定 + 事实注入 + 停止原语)。以前只有
+     * `/api/goals/:id/requirement` 那条 HTTP 路由会走到它 —— 于是 CLI / 宿主直接调 `ingestGoalChange`
+     * 时, 在跑的 Run **停不下来** (接缝拿到的是 `factsMissing=true`, 只能如实说"不知道"）。
+     *
+     * 这里就是那个入口: 读事实 (`runningRun` / 在跑的子 Agent) → 接缝判定 → 真停 Run (`setRunStatus`)。
+     * 返回值原样透出接缝视图 (含 `runBoundary.stopped` 与逐 workId 的下发内容), 拒绝也原样透出。
+     */
+    async ingestRequirement(goalId, instruction, by = 'human') {
+        const now = new Date(this.now()).toISOString();
+        const view = await ingestRequirementViaSeam({
+            goalId,
+            instruction,
+            source: 'user',
+            recordedBy: `cli:${by}`,
+            caller: 'human', // 人提的变更: 只有人能提撤销/缩范围
+            now,
+        });
+        if (view === null)
+            return { ok: false, reason: `变更无法入档 (goal=${goalId})` };
+        if (isRefusal(view))
+            return { ok: false, reason: view.reason };
+        const b = view.runBoundary;
+        const note = b.action === 'stop_running_run'
+            ? (b.stopped
+                ? `在跑的 Run ${b.runId} 已写 ${b.runStatus} (执行器下一轮自行停下)`
+                : `判定要停 Run ${b.runId}, 但停止动作没落到记录上: ${b.reason}`)
+            : b.reason;
+        this.emit({ kind: 'requirement_ingested', goalId, message: `${view.request.kind} (${view.plan.outcome}) — ${note}` });
+        this.log(`[supervisor] goal=${goalId} 变更入档: ${view.request.kind} → ${view.plan.outcome}; ${note}`);
+        return {
+            ok: true,
+            kind: view.request.kind,
+            outcome: view.plan.outcome,
+            stopped: b.stopped,
+            runId: b.runId,
+            visibleState: view.visibleState,
+            note,
+        };
+    }
 }
 /** 单例 (Web/CLI 共享同一个进程内调度器; 跨进程靠 lease 排他) */
 let singleton = null;