@bolloon/bolloon-agent 0.4.33 → 0.5.1

package/dist/ios/server.js

@@ -13,10 +13,17 @@ import { registerJudgmentsRoutes } from './routes-judgments.js';
 import { registerLlmConfigRoutes } from './routes-llm-config.js';
 import { registerExternalEngineRoutes } from './routes-external-engines.js';
 import { registerTaskRoutes } from './routes-tasks.js';
+// 2026-09-19: 联系方式 / 人工批准 / 手机—桌面配对 路由
+import { registerContactRoutes } from './routes-contacts.js';
+// 2026-09-25: 手机端「任务协作」(入群 / 发公告 / 看飞轮进度) 路由 —— 高风险动作由设备签名把关
+import { registerMobileTaskRoutes } from './routes-mobile-tasks.js';
 // 2026-09-13: 微支付信息服务 (x402) 路由
 import { registerX402InfoRoutes } from './routes-x402-info.js';
+// 2026-09-22: P5 链上索引 (只读: status/stats/timeline/events 增量) 路由
+import { registerChainIndexRoutes } from './routes-chain-index.js';
 import { loadPeerTier, recordInteraction, tierLabel } from '../social/dunbar-tier.js';
 import { registerHearthRoutes } from './routes-hearth.js';
+import { registerOnchainTradeRoutes } from './routes-onchain-trade.js';
 import { loadOrCreateAgentIdentity } from '../agents/agent-identity.js';
 // 2026-07-06: 类型抽到 ./server-types.ts (channel / session / task / sse client / iroh info / paths)
 import { SESSION_CACHE_PATH, SHARED_SESSION_PATH, IPFS_ENDPOINT, } from './server-types.js';
@@ -1530,6 +1537,11 @@ async function getAgentForChannel(channelId, channelDid, channelName, channelDid
         usePivotLoop: true,
     }, true); // forceNew: true 强制创建新实例
     channelSessions.set(sessionKey, session);
+    // 2026-09-16: 标记运行表面 — 落盘 run 记录里能区分 web 运行 (CLI 默认 cli)
+    try {
+        session.setRunSurface?.('web');
+    }
+    catch { /* 老 session 无此方法则忽略 */ }
     if (channelDid) {
         console.log(`[Agent] 新建频道 ${channelId} session, DID = ${channelDid}, sessionId = ${currentSessionId}`);
     }
@@ -1626,6 +1638,104 @@ export async function createWebServer(port = 3000, options = {}) {
     catch (err) {
         console.warn('[createWebServer] bootstrap 失败 (非致命):', err);
     }
+    // 2026-09-16: 孤儿运行对账 — 上次进程留下的 running 记录改判 interrupted。
+    // 不做这步的话, 刷新/重启后 UI 会显示"还在跑"的幽灵运行 (最典型的假状态)。
+    try {
+        const { reconcileOrphans } = await import('../agents/run-store.js');
+        const rec = await reconcileOrphans();
+        if (rec.interrupted.length) {
+            console.log(`[runs] 对账: ${rec.interrupted.length} 条上次中断的运行已标 interrupted (${rec.interrupted.slice(0, 3).join(', ')}${rec.interrupted.length > 3 ? '…' : ''})`);
+        }
+        if (rec.stillRunning.length)
+            console.log(`[runs] 存活运行: ${rec.stillRunning.length} 条`);
+    }
+    catch (err) {
+        console.warn('[runs] 对账失败 (非致命):', err?.message);
+    }
+    // 2026-09-16 (M2-B): ExecutionSupervisor —— 长期执行层。
+    //   页面关掉、进程重启后由它把 Goal 继续下去; 跨进程排他靠 Goal lease (不是内存状态)。
+    //   Harness 管"这一段能不能安全执行", Supervisor 管"这个目标还要不要继续执行"。
+    if (process.env.BOLLOON_SUPERVISOR !== '0') {
+        try {
+            const { getSupervisor } = await import('../agents/execution-supervisor.js');
+            const { runSupervisorHost } = await import('../agents/supervisor-host.js');
+            const tickMs = Number(process.env.BOLLOON_SUPERVISOR_TICK_MS) || 30_000;
+            const leaseMs = Number(process.env.BOLLOON_SUPERVISOR_LEASE_MS) || 90_000;
+            // 执行器**在每次执行前解析** (不写死): web 宿主按 Goal 的 channelId 找 channel agent。
+            // 解析不出来 → 只诊断不执行, 且不写任何 Goal 状态。
+            const resolver = async (req) => {
+                const goal = req.goal;
+                if (!goal?.channelId) {
+                    return { ok: false, kind: 'none', reason: 'Goal 没有 channelId: 无法在 web 进程内解析执行器' };
+                }
+                const agent = await getAgentForChannel(goal.channelId, goal.agentId || '', undefined, undefined);
+                if (!agent)
+                    return { ok: false, kind: 'none', reason: 'channel agent 不可用' };
+                const runner = async (r) => {
+                    if (r.kind === 'resume' && r.prevRunId && typeof agent.resumeRun === 'function') {
+                        const res = await agent.resumeRun(r.prevRunId);
+                        return { runId: r.prevRunId, status: res?.ok ? 'done' : 'failed', error: res?.ok ? undefined : res?.reason };
+                    }
+                    // 跨预算继续: 新 Run 必须挂在同一个 Goal 下 (setGoalId), 并带上上一个 Run 的非幂等守卫
+                    agent.setGoalId?.(goal.goalId);
+                    agent.setContinuationGuards?.(r.guards || []);
+                    const reply = await agent.prompt(r.instruction);
+                    // 注意: prompt 收尾会清空 currentRunId → 必须读 lastRunId (否则会拿上一条 run 做决策)
+                    const runId = agent.getLastRunId?.() || agent.getRunId?.();
+                    return { runId, status: 'done', reply: typeof reply === 'string' ? reply.slice(0, 500) : undefined };
+                };
+                return { ok: true, runner, kind: 'web' };
+            };
+            // 2026-09-16 (M4): 初始化未就绪 → Supervisor 只诊断 (不解析执行器, 不执行任何 Goal)
+            let setupReadyForSupervisor = false;
+            try {
+                const { getSetupGateCached } = await import('../setup/setup-store.js');
+                const g = await getSetupGateCached();
+                setupReadyForSupervisor = g.gate === 'ready';
+                if (!setupReadyForSupervisor)
+                    console.warn(`[supervisor] 初始化未就绪 (${g.gate}, 阶段 ${g.state.stage}) → 只诊断, 不执行 Goal`);
+            }
+            catch {
+                console.warn('[supervisor] 初始化状态不可读 → 只诊断, 不执行 Goal');
+            }
+            const sup = getSupervisor({
+                tickIntervalMs: tickMs,
+                leaseTtlMs: leaseMs,
+                maxPerTick: Number(process.env.BOLLOON_SUPERVISOR_MAX_PER_TICK) || 1,
+                log: (m) => console.log(m),
+                onEvent: (e) => { try {
+                    broadcast({ type: 'supervisor', ...e });
+                }
+                catch { /* UI 广播失败不影响调度 */ } },
+                resolver: setupReadyForSupervisor ? resolver : undefined,
+            });
+            // 宿主层: 跨进程单 tick 互斥 + 宿主身份/心跳落盘 + 优雅停止
+            const host = await runSupervisorHost({
+                supervisor: sup,
+                tickIntervalMs: tickMs,
+                leaseTtlMs: leaseMs,
+                runnerKind: 'web',
+                log: (m) => console.log(m),
+            });
+            global.__bolloonSupervisorHost = host;
+            console.log(`[supervisor] 长期执行层已启动 (owner=${host.state.owner}, worker=${host.state.workerId}, tick=${tickMs}ms, lease=${leaseMs}ms)`);
+            const stopHost = (sig) => { void host.stop(`signal:${sig}`).finally(() => process.exit(0)); };
+            process.once('SIGINT', () => stopHost('SIGINT'));
+            process.once('SIGTERM', () => stopHost('SIGTERM'));
+        }
+        catch (err) {
+            // 启动失败必须可观测 (不许静默降级成长时间不执行)
+            const msg = `[supervisor] 启动失败: ${err?.message || err}`;
+            console.error(msg);
+            try {
+                broadcast({ type: 'supervisor', kind: 'startup_failed', message: msg });
+            }
+            catch { /* ignore */ }
+        }
+    }
+    else {
+        console.log('[supervisor] 长期执行层已关闭 (BOLLOON_SUPERVISOR=0)');
+    }
     // 2026-08-03 (Context OS P5): 初始化资产层 12+3 目录 (幂等, 每层 README 声明职责边界)
     try {
         const { ensureContextOsDirs } = await import('../bootstrap/context-os.js');
@@ -2439,6 +2549,19 @@ export async function createWebServer(port = 3000, options = {}) {
                     console.log(`[cron] 调度器已启动 (每 ${Math.round((Number(process.env.BOLLOON_CRON_HEARTBEAT_MS) || 60_000) / 1000)}s 一轮, tick 带锁 + DND)`);
                 // 暴露给 /message 使用 (主任务闸门)
                 global.__bolloonMainTask = { enterMainTask, exitMainTask };
+                // 2026-09-16: 运行失速巡检 (每 60s) — running 但长时间没新进展的运行标 stalled,
+                //   让 UI/CLI 能说"这个运行卡住了", 而不是永远转圈 (crash 由启动时对账兜底)。
+                setInterval(() => {
+                    void (async () => {
+                        try {
+                            const { superviseRuns } = await import('../agents/run-store.js');
+                            const r = await superviseRuns();
+                            if (r.stalled.length)
+                                console.warn(`[runs] 失速巡检: ${r.stalled.length} 条运行标 stalled (${r.stalled.slice(0, 3).join(', ')})`);
+                        }
+                        catch { /* 巡检失败不影响主流程 */ }
+                    })();
+                }, 60_000);
             }
             catch (cronErr) {
                 console.warn('[cron] 调度器启动失败 (non-fatal):', cronErr?.message);
@@ -2805,6 +2928,15 @@ ${goalDesc}
     }
     app.get('/', serveStaticHtml('index.html', 'index.html not found; please run `npm run build:web`', 'index'));
     app.get('/api-config', serveStaticHtml('api-config.html', 'api-config.html not found; please run `npm run build:web`', 'api-config'));
+    // 2026-09-22 (P7): 链上浏览器页面 (只读索引的网页入口)
+    //   /explorer 与 /chain 两个别名都指向同一个静态页 (explorer.html + chain-explorer.js);
+    //   页面只调 /api/chain/index/*, 不碰任何写接口。
+    {
+        const serveExplorer = serveStaticHtml('explorer.html', 'explorer.html not found; please run `npm run build:web`', 'explorer');
+        app.get('/explorer', serveExplorer);
+        app.get('/chain', serveExplorer);
+        registerChainIndexRoutes(app);
+    }
     // 2026-07-01 (v0.2.5): 输入验证 + 健康检查 API
     //   - POST /api/validate-input: 前端发送前预校验, 避免后端 reject
     //   - GET  /api/health: liveness probe + validators 清单
@@ -2832,6 +2964,737 @@ ${goalDesc}
             res.status(400).json({ ok: false, severity: 'block', reason: e?.message ?? 'parse error' });
         }
     });
+    // 2026-09-16: 运行记录 (持久化 harness) — 当前 + 历史 agent 运行。跨重载可读。
+    // 2026-09-18: 智能体工具执行轨迹 + 本机 P2P 信息 (与小工具/名片交换用, 结构化)
+    // 2026-09-18 (Phase 4): 交易审计 — 里程碑 / 争议 / 责任 / 事件链 一眼可查
+    app.get('/api/x402/transactions', async (_req, res) => {
+        try {
+            const { listTransactions } = await import('../agents/x402/transaction-store.js');
+            const { aggregateMilestones } = await import('../agents/x402/milestone-settlement.js');
+            const txs = await listTransactions();
+            res.json({
+                count: txs.length,
+                transactions: txs.map((t) => ({
+                    transactionId: t.transactionId, status: t.status, settlementFact: t.settlementFact,
+                    itemId: t.itemId, amount: t.amount, currency: t.currency, network: t.network,
+                    paymentMode: t.paymentMode, chainSettled: t.chainSettled === true, txHash: t.txHash,
+                    milestones: t.milestones?.length ? aggregateMilestones(t.milestones) : null,
+                    disputed: !!t.dispute, disputeResolved: t.dispute?.resolution?.decision || null,
+                    responsibility: t.responsibility?.type || null,
+                    partial: t.settlementFact === 'partially_settled',
+                })),
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    app.get('/api/x402/transactions/:id', async (req, res) => {
+        try {
+            const { readTransaction, replayTransaction } = await import('../agents/x402/transaction-store.js');
+            const { aggregateMilestones, milestoneGoalEligibility } = await import('../agents/x402/milestone-settlement.js');
+            const rec = await readTransaction(req.params.id);
+            if (!rec)
+                return res.status(404).json({ error: '交易不存在' });
+            res.json({
+                transaction: rec,
+                milestones: rec.milestones?.length ? { list: rec.milestones, aggregate: aggregateMilestones(rec.milestones) } : null,
+                dispute: rec.dispute || null,
+                responsibility: rec.responsibility || null,
+                goalEligibility: milestoneGoalEligibility(rec, { executionOk: rec.execution?.ok === true, goalCriteriaHit: rec.goalCriteriaMet === true }),
+                replay: await replayTransaction(req.params.id),
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    app.get('/api/trace', async (req, res) => {
+        try {
+            const { listRuns } = await import('../agents/run-store.js');
+            const { runToTraceJson } = await import('../agents/trace-export.js');
+            const runs = await listRuns({ limit: Number(req.query.limit) || 20 });
+            res.json({ runs: runs.map((r) => runToTraceJson(r)) });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    app.get('/api/trace/:runId', async (req, res) => {
+        try {
+            const { readRun } = await import('../agents/run-store.js');
+            const { runToTraceText, runToTraceJson } = await import('../agents/trace-export.js');
+            const run = await readRun(req.params.runId);
+            if (!run)
+                return res.status(404).json({ error: 'run 不存在' });
+            if (String(req.query.format || 'json') === 'text') {
+                res.type('text/plain; charset=utf-8').send(runToTraceText(run));
+                return;
+            }
+            res.json(runToTraceJson(run));
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    app.get('/api/p2p/info', async (_req, res) => {
+        try {
+            const { getLocalP2pInfo, formatP2pInfoJson } = await import('../agents/p2p-info.js');
+            const info = await getLocalP2pInfo();
+            res.type('application/json').send(formatP2pInfoJson(info));
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // 2026-09-16 (2-F/2-H): 判据 (criteria) + 长期执行面板 API —— CLI/Web 读同一份 Goal 事实
+    app.get('/api/goals/:id/criteria', async (req, res) => {
+        try {
+            const { longTermStatus } = await import('../agents/goal-criteria.js');
+            const { readGoal } = await import('../agents/goal-store.js');
+            const g = await readGoal(req.params.id);
+            if (!g)
+                return res.status(404).json({ error: 'goal 不存在' });
+            const st = await longTermStatus(req.params.id);
+            res.json({ goalId: g.goalId, objective: g.objective, status: g.status, successCriteria: g.successCriteria, completedCriteria: g.completedCriteria, criteriaSource: g.criteriaSource, criteriaConfirmed: g.criteriaConfirmed === true, criteriaVersion: g.criteriaVersion, proposedCriteria: g.proposedCriteria || null, unresolvedItems: g.unresolvedItems, evidence: (g.evidence || []).slice(-10), longTerm: st });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    app.post('/api/goals/:id/criteria', async (req, res) => {
+        try {
+            const { confirmCriteria, proposeForGoal } = await import('../agents/goal-criteria.js');
+            const { readGoal } = await import('../agents/goal-store.js');
+            const g = await readGoal(req.params.id);
+            if (!g)
+                return res.status(404).json({ error: 'goal 不存在' });
+            const criteria = Array.isArray(req.body?.criteria) ? req.body.criteria.map((c) => String(c)) : undefined;
+            if (req.body?.propose === true) {
+                const p = await proposeForGoal(req.params.id);
+                return res.json({ ok: p.ok, proposed: p.criteria, needsHuman: !!p.needsHuman, reason: p.reason || null });
+            }
+            // 默认: 确认 (可同时改内容)
+            const r = await confirmCriteria(req.params.id, { criteria, by: 'web' });
+            res.status(r.ok ? 200 : 409).json({ ok: r.ok, reason: r.reason || null, criteria: r.goal?.successCriteria, criteriaVersion: r.goal?.criteriaVersion });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // 长期执行面板 (纯静态页, 直接打已有 API; 未 ready 时 chat 路由本来就 503)
+    app.get('/goals', (_req, res) => {
+        res.type('html').send(`<!doctype html><meta charset="utf-8"><title>Bolloon 长期执行</title>
+<style>body{font-family:system-ui,-apple-system,"PingFang SC",sans-serif;max-width:1000px;margin:32px auto;padding:0 16px;line-height:1.55;color:#181818}
+h1{font-size:20px}h2{font-size:15px;margin-top:22px}table{border-collapse:collapse;width:100%;font-size:13px}th,td{border-bottom:1px solid #eee;padding:6px 8px;text-align:left;vertical-align:top}
+.ok{color:#0a7d32}.bad{color:#b00020}.dim{color:#666}button{font-size:12px;padding:4px 8px;margin-right:4px}code{background:#f6f6f6;padding:1px 4px;border-radius:4px}</style>
+<h1>长期执行面板</h1>
+<p class="dim">数据 = <code>/api/goals</code> · <code>/api/runs</code> · <code>/api/goals/:id/criteria</code> · <code>/api/supervisor</code> (与 CLI 同一份事实)</p>
+<div id="sup"></div>
+<h2>目标 (Goals)</h2><table id="goals"><thead><tr><th>goalId</th><th>状态</th><th>判据</th><th>下一动作</th><th>Runs</th><th>操作</th></tr></thead><tbody></tbody></table>
+<h2>运行 (Runs, 最近 20)</h2><table id="runs"><thead><tr><th>runId</th><th>goalId</th><th>状态</th><th>步数</th><th>恢复</th><th>操作</th></tr></thead><tbody></tbody></table>
+<pre id="log" class="dim"></pre>
+<script>
+const log = (m) => { document.getElementById('log').textContent = typeof m === 'string' ? m : JSON.stringify(m, null, 1); };
+async function j(u){ const r = await fetch(u); return await r.json(); }
+async function view(id){
+  const c = await j('/api/goals/'+id+'/criteria');
+  log(c);
+}
+async function act(id, what){
+  if (what === 'confirm') { const r = await fetch('/api/goals/'+id+'/criteria',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({})}); log(await r.json()); }
+  else if (what === 'propose') { const r = await fetch('/api/goals/'+id+'/criteria',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({propose:true})}); log(await r.json()); }
+  else if (what === 'wake') { const r = await fetch('/api/goals/'+id+'/wake',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({force:true})}); log(await r.json()); }
+  else if (what === 'resume') { const r = await fetch('/api/runs/'+id+'/resume',{method:'POST'}); log(await r.json()); }
+  else if (what === 'pause') { const r = await fetch('/api/runs/'+id+'/pause',{method:'POST'}); log(await r.json()); }
+  else if (what === 'abort') { const r = await fetch('/api/runs/'+id+'/abort',{method:'POST'}); log(await r.json()); }
+  refresh();
+}
+async function req(id){
+  const text = prompt('新要求 (原话逐字入档; 只影响后续 Run, 不改写已发生的历史。若说"撤销/别继续做了", 在跑的这一轮会在下一次循环停下):');
+  if (!text) return;
+  const r = await fetch('/api/goals/'+id+'/requirement',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({text})});
+  log(await r.json()); refresh();
+}
+async function refresh(){
+  try {
+    const sup = await j('/api/supervisor');
+    document.getElementById('sup').innerHTML = '<b>Supervisor</b> owner='+(sup.state?.owner||'-')+' worker='+(sup.state?.workerId||'-')+' ticks='+(sup.ticks||0)+
+      ' <span class="dim">lease='+(sup.leaseTtlMs||'-')+'ms tick='+(sup.tickIntervalMs||'-')+'ms</span>';
+  } catch(e){ document.getElementById('sup').textContent = 'supervisor 不可用: '+e; }
+  const gs = await j('/api/goals');
+  const labels = gs.visibleLabels || {};
+  const visMap = {}; (gs.goals || []).forEach((g, i) => { visMap[g.goalId] = (gs.visible || [])[i]; });
+  const gtb = document.querySelector('#goals tbody'); gtb.innerHTML = '';
+  for (const g of (gs.goals || [])) {
+    let crit = g.successCriteria?.length ? (g.completedCriteria?.length||0)+'/'+g.successCriteria.length : '<span class="bad">无判据</span>';
+    const src = g.criteriaSource ? ' <span class="dim">('+g.criteriaSource+(g.criteriaConfirmed?'✓':'?')+')</span>' : '';
+    const tr = document.createElement('tr');
+    const vis = (visMap[g.goalId]) || (g.continuation ? 'executing' : 'executing');
+    const visZh = (labels[vis] && labels[vis].zh) || vis;
+    const pend = (gs.pendingChanges||[])[(gs.goals||[]).indexOf(g)];
+    const pendZh = pend ? ' <span class="bad">('+pend+' 条变更等你决定)</span>' : '';
+    tr.innerHTML = '<td><code>'+g.goalId+'</code></td><td>'+visZh+pendZh+' <span class="dim">('+vis+')</span></td><td>'+crit+src+'</td><td class="dim">'+
+      ((g.continuation&&(g.continuation.nextAction||g.continuation.wakeReason))||'-')+'</td><td>'+((g.runs||[]).length)+'</td>'+
+      '<td><button onclick="view(\\''+g.goalId+'\\')">详情</button><button onclick="act(\\''+g.goalId+'\\',\\'confirm\\')">确认判据</button><button onclick="act(\\''+g.goalId+'\\',\\'propose\\')">提候选</button><button onclick="act(\\''+g.goalId+'\\',\\'wake\\')">唤醒</button><button onclick="req(\\''+g.goalId+'\\')">新要求</button></td>';
+    gtb.appendChild(tr);
+  }
+  const rs = await j('/api/runs');
+  const rtb = document.querySelector('#runs tbody'); rtb.innerHTML = '';
+  for (const r of (rs.runs || []).slice(-20).reverse()) {
+    const tr = document.createElement('tr');
+    tr.innerHTML = '<td><code>'+String(r.runId).slice(0,14)+'</code></td><td class="dim">'+(r.goalId||'-')+'</td><td>'+r.status+'</td><td>'+((r.steps||[]).length)+'</td><td>'+((r.recovery||[]).length)+'</td>'+
+      '<td><button onclick="act(\\''+r.runId+'\\',\\'resume\\')">resume</button><button onclick="act(\\''+r.runId+'\\',\\'pause\\')">pause</button><button onclick="act(\\''+r.runId+'\\',\\'abort\\')">abort</button></td>';
+    rtb.appendChild(tr);
+  }
+}
+refresh(); setInterval(refresh, 5000);
+</script>`);
+    });
+    // 2026-09-16 (Phase 4): Onboard API —— 与 CLI 共用同一条执行器 (src/setup/onboard.ts)
+    //   页面只负责"提交本步输入", 阶段判定/校验/真实验证/原子提交/门禁全在服务端同一份事实里。
+    const setupState = async () => {
+        const { evaluateSetup } = await import('../setup/setup-store.js');
+        const { nextStepInfo } = await import('../setup/onboard.js');
+        const ev = await evaluateSetup();
+        const next = ev.gate === 'ready' ? null : await nextStepInfo(ev.state).catch(() => null);
+        return { gate: ev.gate, stage: ev.state.stage, readiness: ev.state.readiness, readinessWhy: ev.state.readinessWhy,
+            allow: ev.state.allow, completed: ev.state.completed, inputs: ev.state.inputs, checks: ev.state.checks,
+            lastError: ev.state.lastError || null, actions: ev.state.actions, reasons: ev.reasons, nextStep: next };
+    };
+    app.get('/api/setup', async (_req, res) => {
+        try {
+            res.json(await setupState());
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200), gate: 'blocked' });
+        }
+    });
+    // 跑一步 (answers 按顺序喂给执行器; oneShot: 一步失败就返回, 不阻塞)
+    const runSetupStep = async (req, res, mode) => {
+        try {
+            const { runOnboard, ScriptedIO } = await import('../setup/onboard.js');
+            const answers = Array.isArray(req.body?.answers) ? req.body.answers.map((x) => String(x ?? '')) : [];
+            const io = new ScriptedIO(answers);
+            const r = await runOnboard({ mode, io, oneShot: true, targets: req.body?.targets });
+            res.json({ ...(await setupState()), ok: r.ok, failedStage: r.failedStage || null, errorClass: r.errorClass || null,
+                message: r.message || null, steps: r.steps, stepLog: io.log.slice(-40), summary: r.summary });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err).slice(0, 200), gate: 'blocked' });
+        }
+    };
+    app.post('/api/setup/start', async (_req, res) => { try {
+        res.json(await setupState());
+    }
+    catch (err) {
+        res.status(500).json({ error: String(err) });
+    } });
+    app.post('/api/setup/step', async (req, res) => runSetupStep(req, res, 'resume'));
+    app.post('/api/setup/resume', async (req, res) => runSetupStep(req, res, 'resume'));
+    app.post('/api/setup/test', async (req, res) => runSetupStep(req, res, 'test'));
+    app.post('/api/setup/repair', async (req, res) => runSetupStep(req, res, 'repair'));
+    app.post('/api/setup/reconfigure', async (req, res) => runSetupStep(req, res, 'reconfigure'));
+    app.post('/api/setup/commit', async (_req, res) => {
+        try {
+            const { refreshSetupState } = await import('../setup/setup-store.js');
+            const ev = await refreshSetupState({});
+            const { describeSetup } = await import('../setup/setup-store.js');
+            res.json({ ...(await setupState()), ok: ev.gate === 'ready', summary: describeSetup(ev) });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
+    app.post('/api/setup/identity', async (req, res) => runSetupStep({ body: { answers: [req.body?.name] } }, res, 'resume'));
+    app.post('/api/setup/provider', async (req, res) => runSetupStep({ body: { answers: [req.body?.provider] } }, res, 'resume'));
+    // 首启页面 (零依赖, 直接打这些 API; 未 ready 时所有对话路由都是 503)
+    app.get('/setup', (_req, res) => {
+        res.type('html').send(`<!doctype html><meta charset="utf-8"><title>Bolloon 初始化</title>
+<style>body{font-family:system-ui,-apple-system,"PingFang SC",sans-serif;max-width:760px;margin:40px auto;padding:0 16px;line-height:1.6}
+h1{font-size:20px}pre{background:#f6f6f6;padding:12px;border-radius:8px;white-space:pre-wrap}
+.ok{color:#0a7d32}.bad{color:#b00020}input,select,button{font-size:15px;padding:8px;margin:4px 0}
+.row{margin:10px 0}small{color:#666}</style>
+<h1>Bolloon 初始化</h1>
+<div id="state">加载中…</div>
+<div class="row" id="form"></div>
+<div class="row"><button onclick="run('step')">提交这一步</button>
+<button onclick="run('test')">重新测试连通性/运行时</button>
+<button onclick="run('repair')">修复/迁移配置</button>
+<button onclick="fetchState()">刷新</button></div>
+<pre id="log"></pre>
+<script>
+async function fetchState(){
+  const r = await fetch('/api/setup'); const s = await r.json();
+  const ready = s.gate==='ready';
+  document.getElementById('state').innerHTML =
+    '<b>阶段</b>: '+s.stage+' &nbsp; <b>门禁</b>: <span class="'+(ready?'ok':'bad')+'">'+s.gate+'</span><br>'+
+    '<b>就绪度</b>: basic '+s.readiness.basic+' · agent '+s.readiness.agent+' · durable '+s.readiness.durable+' · network '+s.readiness.network+'<br>'+
+    '<small>已完成: '+(s.completed.join(' → ')||'(无)')+'</small><br>'+
+    '<small>下一步: '+(s.actions[0]||'')+'</small>'+
+    (s.lastError?'<br><small class="bad">上次错误 ['+s.lastError.errorClass+'] '+s.lastError.message+'</small>':'');
+  const f = document.getElementById('form');
+  const n = s.nextStep;
+  if(!n){ f.innerHTML='<b class="ok">✅ 已就绪, 可以进入对话</b>'; window.currentNeeds=null; return; }
+  window.currentNeeds=n.needs;
+  if(n.needs==='provider'){
+    f.innerHTML='<div>'+n.question+'</div><select id="v">'+ (n.choices||[]).map(c=>'<option value="'+c.value+'">'+c.label+(c.hint?' — '+c.hint:'')+'</option>').join('') +'</select>';
+  } else if(n.needs==='credential'){
+    f.innerHTML='<div>'+n.question+'</div><input id="v" type="password" placeholder="API key (不会回显)" autocomplete="off">';
+  } else if(n.needs==='none'){
+    f.innerHTML='<div>'+n.question+' (点上面按钮执行)</div>';
+  } else {
+    f.innerHTML='<div>'+n.question+'</div><input id="v" value="'+(n.defaultValue||'')+'">';
+  }
+}
+async function run(ep){
+  const v=document.getElementById('v'); const n=window.currentNeeds;
+  const answers = (n==='credential'||n==='name'||n==='model'||n==='provider') && v ? [v.value] : [];
+  if(v) v.value='';                       // key 立即从 DOM 里清掉
+  const r = await fetch('/api/setup/'+ep,{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({answers})});
+  const j = await r.json();
+  document.getElementById('log').textContent = (j.log||[]).join('\n') + '\n' + (j.summary||'');
+  fetchState();
+}
+fetchState();
+</script>`);
+    });
+    // 2026-09-16 (M1/M3): 初始化状态 —— CLI 与 Web 读同一份事实 (setup-state.json + 各领域 store)
+    app.get('/api/setup', async (_req, res) => {
+        try {
+            const { evaluateSetup, describeSetup, resolveBolloonHome } = await import('../setup/setup-store.js');
+            const ev = await evaluateSetup({ light: false });
+            res.json({ gate: ev.gate, stage: ev.state.stage, readiness: ev.state.readiness, allow: ev.state.allow, completed: ev.state.completed, inputs: ev.state.inputs, lastError: ev.state.lastError, reasons: ev.reasons, nextActions: ev.nextActions, summary: describeSetup(ev), bolloonHome: resolveBolloonHome() });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200), gate: 'blocked' });
+        }
+    });
+    // 2026-09-16 (2-G.1): Skills Manager —— 与 CLI `/skills` `/skill` 读同一份事实 (skills-registry.json + 技能目录)
+    app.get('/api/skills', async (_req, res) => {
+        try {
+            const { getSkillsManager } = await import('../agents/skills-manager.js');
+            const sm = getSkillsManager();
+            const skills = await sm.view();
+            res.json({ count: skills.length, registryPath: (await import('../agents/skills-manager.js')).registryPath(), skills, health: await sm.health() });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    app.get('/api/skills/health', async (_req, res) => {
+        try {
+            const { getSkillsManager } = await import('../agents/skills-manager.js');
+            res.json(await getSkillsManager().health());
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    app.get('/api/skills/:name', async (req, res) => {
+        try {
+            const { getSkillsManager } = await import('../agents/skills-manager.js');
+            const s = await getSkillsManager().inspect(String(req.params.name));
+            if (!s) {
+                res.status(404).json({ error: `没有这个技能: ${req.params.name}` });
+                return;
+            }
+            res.json({ skill: s });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    app.post('/api/skills/import', async (req, res) => {
+        try {
+            const ref = String(req.body?.ref || '').trim();
+            if (!ref) {
+                res.status(400).json({ error: '要 body {ref: "bolloon://skill/<cid>" | "ipfs://<cid>" | "<cid>"}' });
+                return;
+            }
+            const { getSkillsManager } = await import('../agents/skills-manager.js');
+            const r = await getSkillsManager().import(ref, { force: !!req.body?.force });
+            if (!r.ok) {
+                res.status(409).json({ error: r.error });
+                return;
+            }
+            res.json({ ok: true, name: r.name, version: r.version, skill: r.skill });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // enable / disable / approve / validate / quarantine (Express 5 不支持内联正则, 显式写开)
+    for (const action of ['enable', 'disable', 'approve', 'validate', 'quarantine']) {
+        app.post(`/api/skills/:name/${action}`, async (req, res) => {
+            try {
+                const { getSkillsManager } = await import('../agents/skills-manager.js');
+                const sm = getSkillsManager();
+                const name = String(req.params.name);
+                const r = action === 'approve' ? await sm.approve(name, 'web')
+                    : action === 'quarantine' ? await sm.quarantine(name, String(req.body?.reason || 'web 手动隔离'))
+                        : action === 'enable' ? await sm.enable(name)
+                            : action === 'disable' ? await sm.disable(name)
+                                : await sm.validate(name);
+                if (!r.ok && !r.skill) {
+                    res.status(409).json({ error: r.reason || r.issues || '操作未完成' });
+                    return;
+                }
+                res.json({ ok: r.ok, name, action, skill: r.skill, issues: r.issues });
+            }
+            catch (err) {
+                res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+            }
+        });
+    }
+    // 2026-09-16 (M2-B): 长期执行层诊断 + 手动推进 —— 与 CLI /supervise 读同一份持久化记录
+    app.get('/api/supervisor', async (_req, res) => {
+        try {
+            const { getSupervisor } = await import('../agents/execution-supervisor.js');
+            const { readSupervisorState, supervisorStatePath } = await import('../agents/supervisor-host.js');
+            const { wakeReport, listRunnableGoals } = await import('../agents/goal-store.js');
+            const { goalVisibleState } = await import('../agents/goal-flywheel-wiring.js');
+            const { runnable, skipped } = await listRunnableGoals({ now: Date.now() });
+            res.json({
+                supervisor: getSupervisor().status(),
+                /** 宿主身份/心跳 (谁在跑、跑到哪、上次有没有好好停) */
+                host: await readSupervisorState(),
+                hostStatePath: supervisorStatePath(),
+                wake: await wakeReport(),
+                // 2026-09-25 (飞轮接线 §7): 用户可见态 (六类) —— 界面不得自己造第二套映射
+                wakeVisible: await Promise.all((await wakeReport()).map(async (r) => {
+                    try {
+                        return { goalId: r.goalId, visible: await goalVisibleState({ goalId: r.goalId }) };
+                    }
+                    catch {
+                        return { goalId: r.goalId, visible: r.visible };
+                    }
+                })),
+                runnable: runnable.map((g) => ({ goalId: g.goalId, objective: g.objective, status: g.status })),
+                skipped,
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // 手动踢一个调度周期 (调试/验收用; 不改变任何"事实来源")
+    app.post('/api/supervisor/tick', async (_req, res) => {
+        if (!(await setupGate(res)))
+            return;
+        try {
+            const { getSupervisor } = await import('../agents/execution-supervisor.js');
+            const report = await getSupervisor().tickOnce();
+            res.json({ ok: true, report });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // 2026-09-16 (2-E 第 4 类): 外部事件到达 → 唤醒在等它的 Goal (不重发已成功的请求)
+    app.post('/api/goals/:goalId/wake', async (req, res) => {
+        const goalId = String(req.params.goalId);
+        try {
+            const { getSupervisor } = await import('../agents/execution-supervisor.js');
+            const { readGoal, setContinuation } = await import('../agents/goal-store.js');
+            const g = await readGoal(goalId);
+            if (!g) {
+                res.status(404).json({ error: `goal 不存在: ${goalId}` });
+                return;
+            }
+            const woke = await getSupervisor().notifyExternal(goalId);
+            if (!woke) {
+                // 没在等外部事件也要如实回答 (可能它其实在等人/在跑), 但允许显式加急
+                if (req.body?.force) {
+                    await setContinuation(goalId, { wakeReason: 'active', autoContinue: true, wakeAt: undefined, needsExternal: undefined });
+                    res.json({ ok: true, goalId, woke: false, forced: true, note: `原状态 ${g.status} (不在等外部事件), 已按 force 加急` });
+                    return;
+                }
+                res.status(409).json({ error: `Goal 不在等外部事件 (status=${g.status}, wakeReason=${g.continuation?.wakeReason || '无'})`, force_hint: '加 body {"force":true} 可强制加急' });
+                return;
+            }
+            res.json({ ok: true, goalId, woke: true, note: '已唤醒: 下一次 Supervisor tick 会推进它' });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // 2026-09-25 (飞轮接线 P4 / M4 深化): 新要求注入 —— 原话逐字入档 + 分诊 + 版本; 只影响**后续** Run。
+    //   当前 Run 不被历史改写 (规则 4): 本路由只写 Goal 上的变更记录与下一 Run 的指令。
+    //   ★ M4: 这里还要回答"**正在跑的 Goal** 会发生什么" —— 撤销 → 在跑的这一轮必须停
+    //     (走既有外部控制面原语 `setRunStatus`, 与 /api/runs/:id/abort 同一条路; 执行器只在需要时才注入,
+    //      判定本身在 change 接缝里, 本路由不自己判)。事实 (在跑的 Run / 在跑的子 Agent) 由本路由读出来喂进去。
+    app.post('/api/goals/:goalId/requirement', async (req, res) => {
+        const goalId = String(req.params.goalId);
+        try {
+            const { readGoal } = await import('../agents/goal-store.js');
+            const { readRun } = await import('../agents/run-store.js');
+            const { flywheelSeams } = await import('../agents/goal-flywheel-wiring.js');
+            const { isRefusal } = await import('../agents/goal-flywheel/wiring/index.js');
+            const { USER_VISIBLE_STATE_LABELS } = await import('../agents/goal-flywheel/types.js');
+            const text = String(req.body?.text ?? '').trim();
+            if (!text) {
+                res.status(400).json({ error: '缺少 text (新要求的原话)' });
+                return;
+            }
+            const goal = await readGoal(goalId);
+            if (!goal) {
+                res.status(404).json({ error: `goal 不存在: ${goalId}` });
+                return;
+            }
+            // 在跑的 Run 的事实 (读不到记录 = 没有可停的对象; 绝不因为"读不到"去停一个不存在的 Run)
+            const runRec = goal.currentRunId ? await readRun(goal.currentRunId).catch(() => null) : null;
+            // 在跑的子 Agent = 已签合同还没回报的那些 (规则 5: 它们必须先收到变更版本)
+            const liveWorkIds = (goal.continuation?.pendingReports ?? []).map((p) => p.workId).filter(Boolean);
+            const now = new Date().toISOString();
+            const seam = flywheelSeams().change;
+            const view = await seam.ingestChange({
+                goalId,
+                instruction: text,
+                source: 'user',
+                recordedBy: 'web',
+                now,
+                runningRun: runRec ? { runId: runRec.runId, status: String(runRec.status) } : null,
+                liveWorkIds,
+                caller: 'human',
+            });
+            if (isRefusal(view)) {
+                res.status(409).json({ ok: false, refused: true, rule: view.rule, reason: view.reason, goalId });
+                return;
+            }
+            // 计划说要停, 而接缝自己没执行器 (M0 尚未注入 stopRunningRun) → 入口按计划把停落到真 Run 上:
+            //   执行器 = 既有的 setRunStatus (与 /api/runs/:id/abort 同一个原语, 不新造停止通道)。
+            let boundary = view.runBoundary;
+            if (boundary.action === 'stop_running_run' && !boundary.stopped) {
+                const { setRunStatus } = await import('../agents/run-store.js');
+                boundary = await seam.applyRunBoundary({
+                    plan: view.plan,
+                    now,
+                    stop: async (i) => {
+                        const r = await setRunStatus(i.runId, i.runStatus, { error: `变更注入 (${i.goalId}): ${String(i.reason).slice(0, 120)}` });
+                        return { ok: !!r.ok, reason: r.reason || '' };
+                    },
+                });
+            }
+            const bumped = view.plan.outcome === 'next_run' && view.request.kind === 'success_criteria_change'
+                ? view.plan.criteriaVersion
+                : null;
+            res.json({
+                ok: true,
+                goalId,
+                changeId: view.request.changeId,
+                kind: view.request.kind,
+                outcome: view.plan.outcome,
+                status: view.request.status,
+                /** 只有"用户 + 改判据"才 +1 (规则 3); 其余一律 null */
+                criteriaVersionBumpedTo: bumped,
+                criteriaVersion: view.plan.criteriaVersion,
+                /** 下一 Run 真的会读到的指令 (写进 continuation.nextAction) */
+                nextRunDirective: view.plan.nextRunDirective,
+                /** ★ 正在运行的 Goal: 在跑的这一轮停不停 (停不了也会如实说) */
+                runBoundary: boundary,
+                appliesToFutureRunsOnly: view.plan.appliesToFutureRunsOnly,
+                /** 规则 5: 在跑的子 Agent 各拿一份下发内容, 且必须先 ack */
+                childDelivery: {
+                    count: view.childDelivery.directives.length,
+                    workIds: view.childDelivery.workIds,
+                    mustAck: view.childDelivery.mustAck,
+                    scopeMissing: view.childDelivery.scopeMissing,
+                    blocked: view.childDelivery.blocked,
+                    note: view.childDelivery.note,
+                },
+                /** 用户可见态 (六类之一): 有待拍板的变更 → "需要你决定"; null = 基础态读不到 (不编) */
+                visibleState: view.visibleState,
+                visibleZh: view.visibleState ? (USER_VISIBLE_STATE_LABELS[view.visibleState]?.zh || view.visibleState) : null,
+                visibleReason: view.visibleReason,
+                /** 一个 kind 装不下多个意图 → 已入档但不生效, 需拆开重提 */
+                needsDisambiguation: view.needsDisambiguation,
+                /** 流程留痕 (接收→记录→判影响→摘要→评估当前Run→必要时停→重规划→写入下一Run) */
+                steps: view.plan.steps,
+                changeArchive: {
+                    authoritative: 'goal.goalChanges (Goal 记录 = 权威; 界面/下一次 Run 读它)',
+                    mirror: '~/.bolloon/goal-changes/<goalId>.json (镜像, 由接线层写)',
+                },
+                note: view.plan.outcome === 'rejected'
+                    ? '未生效 (见 outcome): 已如实入档, 不会偷偷生效'
+                    : '已生效: 只影响后续 Run, 已发生的 Run 记录不被改写',
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // 2026-09-16 (M5): 运行列表 —— Web 与 CLI 读同一份 run 事实 (~/.bolloon/runs)
+    app.get('/api/runs', async (req, res) => {
+        try {
+            const { listRuns, formatRunLine } = await import('../agents/run-store.js');
+            const status = String(req.query?.status || '').trim();
+            const limit = Number(req.query?.limit || 20);
+            const runs = await listRuns({ status: status ? status : undefined, limit });
+            res.json({
+                count: runs.length,
+                runs,
+                lines: runs.map(formatRunLine),
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // 2026-09-16 (M5): 单个 run + 停止原因/checkpoint/最近步骤/recovery/harness 事件 (两端同一份事实)
+    app.get('/api/runs/:runId', async (req, res) => {
+        try {
+            const { readRun } = await import('../agents/run-store.js');
+            const run = await readRun(String(req.params.runId));
+            if (!run) {
+                res.status(404).json({ error: `run 不存在: ${req.params.runId}` });
+                return;
+            }
+            const goal = run.goalId ? await (await import('../agents/goal-store.js')).readGoal(run.goalId) : null;
+            res.json({ run, goal, checkpoint: run.checkpoint, steps: run.steps, recovery: run.recovery, harness: run.harness || [] });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // 2026-09-16 (M5): 继续 interrupted/stalled/paused/needs_human/awaiting_external 的运行 —— 真从 checkpoint 继续
+    app.post('/api/runs/:runId/resume', async (req, res) => {
+        const runId = String(req.params.runId);
+        try {
+            const { readRun, RESUMABLE_STATUSES } = await import('../agents/run-store.js');
+            const run = await readRun(runId);
+            if (!run) {
+                res.status(404).json({ error: `run 不存在: ${runId}` });
+                return;
+            }
+            // 先做只读校验: 不可恢复的状态明确拒绝 (不假装"已开始"), 避免前端以为在跑
+            if (!RESUMABLE_STATUSES.includes(run.status)) {
+                res.status(409).json({ error: `状态 ${run.status} 不可恢复 (可恢复: ${RESUMABLE_STATUSES.join('/')})` });
+                return;
+            }
+            if (!run.channelId) {
+                res.status(400).json({ error: '该 run 没有 channelId, 无法在 web 端恢复 (请在 CLI 用 /resume)' });
+                return;
+            }
+            const agent = await getAgentForChannel(run.channelId);
+            if (!agent?.resumeRun) {
+                res.status(409).json({ error: '该 channel 的 agent 不支持 resumeRun' });
+                return;
+            }
+            // 异步执行: resume 可能跑几分钟; 状态从 /api/runs/:runId 读 (recovering → running → done/failed)
+            void agent.resumeRun(runId).then((r) => {
+                if (!r?.ok)
+                    console.warn(`[runs] resume ${runId} 失败:`, r?.reason);
+            }).catch((err) => console.warn(`[runs] resume ${runId} 异常:`, err?.message));
+            res.json({ ok: true, accepted: true, runId, note: '已开始恢复; 状态请读 GET /api/runs/:runId' });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // 2026-09-16 (M5): 人工批准 —— needs_human 的运行经人确认后继续 (= 带批准的 resume)
+    app.post('/api/runs/:runId/approve', async (req, res) => {
+        const runId = String(req.params.runId);
+        try {
+            const { readRun, recordRecovery } = await import('../agents/run-store.js');
+            const run = await readRun(runId);
+            if (!run) {
+                res.status(404).json({ error: `run 不存在: ${runId}` });
+                return;
+            }
+            if (run.status !== 'needs_human') {
+                res.status(409).json({ error: `只有 needs_human 的运行需要批准 (当前 ${run.status})` });
+                return;
+            }
+            await recordRecovery(runId, { errorClass: run.errorClass || 'unknown', message: '人工批准后继续', action: 'resume' });
+            if (!run.channelId) {
+                res.status(400).json({ error: '该 run 没有 channelId, 请在 CLI 用 /approve' });
+                return;
+            }
+            const agent = await getAgentForChannel(run.channelId, run.channelId, run.agentId, {});
+            if (!agent?.resumeRun) {
+                res.status(409).json({ error: '该 channel 的 agent 不支持 resumeRun' });
+                return;
+            }
+            void agent.resumeRun(runId).catch((err) => console.warn(`[runs] approve ${runId} 异常:`, err?.message));
+            res.json({ ok: true, accepted: true, runId, approved: true });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    // 2026-09-16 (M5): 暂停 / 中止 —— 只改 run 状态; 运行中的 agent 会在下一次循环检查时如实停下
+    //   (Express 5 的 path-to-regexp 不再支持 `:action(a|b)` 内联正则, 所以两条写开)
+    for (const [suffix, to] of [['pause', 'paused'], ['abort', 'aborted']]) {
+        app.post(`/api/runs/:runId/${suffix}`, async (req, res) => {
+            const runId = String(req.params.runId);
+            try {
+                const { setRunStatus } = await import('../agents/run-store.js');
+                const r = await setRunStatus(runId, to, { error: `外部请求 (${suffix})` });
+                if (!r.ok) {
+                    res.status(409).json({ error: r.reason || '状态迁移被拒绝' });
+                    return;
+                }
+                res.json({ ok: true, runId, status: to, note: '运行中的 agent 会在下一轮循环检查时停下 (轮内不打断)' });
+            }
+            catch (err) {
+                res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+            }
+        });
+    }
+    // 2026-09-16 (M2): 目标 (Goal) —— 目标事实来源; runId → goalId → objective/successCriteria 反查链
+    app.get('/api/goals', async (req, res) => {
+        try {
+            const { listGoals, formatGoalLine } = await import('../agents/goal-store.js');
+            const status = String(req.query?.status || '').trim();
+            const goals = await listGoals({ status: status ? status : undefined, limit: Number(req.query?.limit || 30) });
+            // 2026-09-25 (飞轮接线): 界面只认 `toUserVisibleState` 映射的**六类**用户可见态 ——
+            //   内部状态 (retry_wait / stalled / recovering) 不再直接上屏。
+            // ★ M4: 再过一遍**变更驱动**的覆盖 —— 有待拍板的新要求 (`needs_approval`) 时必须是
+            //   "需要你决定", 否则界面一直显示"正在执行", 没人知道有东西卡在等人 (只升不降)。
+            const { toUserVisibleState } = await import('../agents/goal-flywheel/work-monitor.js');
+            const { changeVisibleState } = await import('../agents/goal-flywheel/wiring/change.js');
+            const { collectWorkBlocks } = await import('../agents/goal-flywheel-wiring.js');
+            const { USER_VISIBLE_STATE_LABELS } = await import('../agents/goal-flywheel/types.js');
+            const visible = await Promise.all(goals.map(async (g) => {
+                try {
+                    const base = toUserVisibleState(g.continuation ? { ...g.continuation } : null, await collectWorkBlocks({ goalId: g.goalId }), null, 
+                    // ★ M5-⑥ (2026-09-25): 界面认 Goal **本体**的终态 —— 完不成这一步的话, 一份落后的
+                    //   continuation 就能把"已完成"的目标显示成"正在执行" (界面比系统更乐观)。
+                    String(g.status ?? '') || null);
+                    // 这里 base 一定读得到 (读不到就是上面的 catch) → 覆盖结果为 null 时回落 base 本身
+                    // (不是编一个态: base 是这一步刚刚读出来的真态)
+                    return changeVisibleState({ base, changes: g.goalChanges ?? [] }).state ?? base;
+                }
+                catch {
+                    return 'executing';
+                }
+            }));
+            res.json({
+                count: goals.length, goals, lines: goals.map(formatGoalLine),
+                visible, visibleZh: visible.map((v) => USER_VISIBLE_STATE_LABELS[v]?.zh || v), visibleLabels: USER_VISIBLE_STATE_LABELS,
+                /** 待拍板的变更 (界面/CLI 用同一份事实说清"你在等什么") */
+                pendingChanges: goals.map((g) => (g.goalChanges ?? []).filter((c) => c.status === 'needs_approval' || c.status === 'triaged').length),
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
+    app.get('/api/goals/:goalId', async (req, res) => {
+        try {
+            const { readGoal, evaluateGoalCompletion } = await import('../agents/goal-store.js');
+            const goal = await readGoal(String(req.params.goalId));
+            if (!goal) {
+                res.status(404).json({ error: `goal 不存在: ${req.params.goalId}` });
+                return;
+            }
+            res.json({ goal, completion: evaluateGoalCompletion(goal) });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err?.message || err).slice(0, 200) });
+        }
+    });
     // 2026-08-13 (Phase E1): Agent 服务 Registry — 发现层 (OrbitDB 去中心化 + 本地 fallback)
     app.get('/api/registry', async (_req, res) => {
         try {
@@ -3889,7 +4752,29 @@ ${goalDesc}
             console.log(`[SSE] 客户端断开 channelId=${channelId || '(broadcast)'}, 剩余=${sseClients.size}`);
         });
     });
+    // 2026-09-16 (M4): agent 执行硬门禁 —— 未 ready 时这些路由 503 + 结构化初始化状态 (Web 只显示初始化页)
+    const setupGate = async (res) => {
+        try {
+            const { getSetupGateCached } = await import('../setup/setup-store.js');
+            const { gate, state } = await getSetupGateCached();
+            if (gate === 'ready')
+                return true;
+            res.status(503).json({
+                error: `初始化未就绪 (${gate}, 阶段 ${state.stage}) — 请先完成初始化`,
+                gate, stage: state.stage, readiness: state.readiness,
+                nextActions: state.actions, lastError: state.lastError || null,
+            });
+            return false;
+        }
+        catch (err) {
+            // fail-closed: 连门禁都读不出来 → 不放行
+            res.status(503).json({ error: `初始化状态不可读 (fail-closed): ${String(err?.message || err).slice(0, 160)}`, gate: 'blocked' });
+            return false;
+        }
+    };
     app.post('/message', async (req, res) => {
+        if (!(await setupGate(res)))
+            return;
         const { text, channelId, channelDid, attachments } = req.body;
         if (!text) {
             return res.status(400).json({ error: 'No text provided' });
@@ -6082,8 +6967,15 @@ ${goalDesc}
     });
     // 2026-07-06: Task Queue API 抽到 ./routes-tasks.ts
     registerTaskRoutes(app, { broadcast, getAgentForChannel });
+    // 2026-09-19: 社交身份 API (DID + 已验证联系方式 + 联系能力 + 权限 + 证据)
+    //   只返回脱敏值; 明文联系方式不进 Run/prompt/Git
+    registerContactRoutes(app, {});
+    // 2026-09-25: 手机端「任务协作」API (入群 / 发公告 / 看飞轮进度)
+    //   手机只做 输入·展示待发内容·设备签名; 执行回到桌面, 调用与 CLI 同一批函数 (同一份 store 与协议)
+    registerMobileTaskRoutes(app, {});
     // 2026-09-13: 微支付信息服务 (x402) — 发布 / 402 收款 / 买方代付 / 验真
     registerX402InfoRoutes(app);
+    registerOnchainTradeRoutes(app);
     // 2026-07-06: LLM/Video/Audio 配置路由抽到 ./routes-llm-config.ts
     registerLlmConfigRoutes(app);
     // 2026-07-22: 外部编码智能体 (codex/claude-code/opencode/openclaw/hermes/实验 API)
@@ -7501,6 +8393,35 @@ ${goalDesc}
         console.warn('[24h] Failed to load heartbeat modules:', err);
     }
     // 健康检查端点
+    // 2026-09-18: 网络脉冲公开只读投影 (给 bolloon-UI 网关页; 无认证, 短缓存, 只有聚合)
+    //   永远不返回原始事件 / registry / DID / peerId / IP / 钱包 / 任务正文。
+    app.get('/api/public/network/progress', async (req, res) => {
+        try {
+            const np = await import('../agents/network-pulse.js');
+            const snap = await np.getNetworkPulse({});
+            // agent_sites = 本节点**显式发布**的公开指针 (IPNS); 没发布就是空数组, 不猜
+            const body = JSON.stringify({ ...snap, status: np.snapshotStatus(snap), agent_sites: np.readAgentSites() });
+            const { createHash } = await import('crypto');
+            const etag = '"' + createHash('sha256').update(body).digest('hex').slice(0, 32) + '"';
+            res.setHeader('Cache-Control', 'public, max-age=15, stale-while-revalidate=15');
+            res.setHeader('ETag', etag);
+            if (req.headers['if-none-match'] === etag) {
+                res.status(304).end();
+                return;
+            }
+            res.type('application/json').send(body);
+        }
+        catch (e) {
+            // 观察层不可用 → 如实 unavailable (不是 500 空体, 也不是"网络为空")
+            try {
+                const np = await import('../agents/network-pulse.js');
+                res.type('application/json').send(JSON.stringify(await np.getNetworkPulse({ unavailable: true })));
+            }
+            catch {
+                res.status(503).json({ status: 'unavailable', error: 'network pulse unavailable' });
+            }
+        }
+    });
     app.get('/api/health', async (req, res) => {
         try {
             if (!healthMonitor) {