@xiaobuyu/nodesign 0.0.6 → 0.0.8

package/server/engine/agent/hooks.js

@@ -46,6 +46,7 @@
 import {
   makePreToolUseAgentForceForegroundHandler,
   makePreToolUseGrepContentDefaultHandler,
+  makePreToolUseActorStamp,
 } from './hooks/pre-defaults.js';
 import {
   makePreToolUseGetPendingChangesProtocolInjector,
@@ -63,6 +64,13 @@ import {
   makePreToolUseBashStarterFilesFallback,
 } from './hooks/pre-starter-files.js';
 import { makePreToolUseBoardNeighborhoodInjector } from './hooks/pre-board-neighborhood.js';
+import { makePreToolUseBoardDirtyInjector } from './hooks/pre-board-dirty.js';
+import { makePreToolUseUnknownParamsProbe } from './hooks/pre-unknown-params.js';
+import { makePreToolUseSendMessageRecipientGuard } from './hooks/pre-peer-guard.js';
+import { createRoleRoster } from './cast.js';
+import { makePostToolUseFailureRoleRelease, makeSubagentStopRoleNotice, makeSubagentStartRoleAlias } from './hooks/resident-role-lifecycle.js';
+import { makePostToolUseBeatWrite, makePostToolUseBeatHandoff, makeStopBeatGate } from './hooks/beat-gate.js';
+import { makePostToolUseSlotAliasHandler } from './hooks/slot-alias.js';
 import { makePreToolUsePerformanceLogGuard } from './hooks/pre-performance-log-guard.js';
 import { makePreToolUseWorkspaceScopeGuard } from './hooks/pre-workspace-scope-guard.js';
 import { PROJECTS_DATA_ROOT } from '../../projects/workspace.js';
@@ -84,7 +92,6 @@ import {
   makePostToolUseScreenshotHandler,
   makePostToolUseExportHandler,
   makePostToolUseGenerateImageRegenWatchdog,
-  makePostToolUseStyleAnchorNudge,
 } from './hooks/post-guidance.js';
 import { makePostToolUseCanvasValidationHandler } from './hooks/canvas-validate.js';
 import { makePostToolUseSiteValidationHandler } from './hooks/site-validate.js';
@@ -100,7 +107,14 @@ import { makePostToolUseSubagentReportRecovery } from './hooks/post-subagent-rep
  * @param {string} [deps.projectId]
  * @returns {Partial<Record<string, Array<{ matcher?: string, hooks: Function[], timeout?: number }>>>}
  */
-export function createHooks({ ctx, workspaceRoot, sharedRoot, sessionId, projectId } = {}) {
+export function createHooks({ ctx, workspaceRoot, sharedRoot, sessionId, projectId, roleRoster: injected = null } = {}) {
+  // 常驻角色名册：**一个会话一份**（闭包级，不是全局表）。派发时登记、收件人闸按它放行。
+  // 两个 handler 必须拿同一个引用 —— 各建各的等于闸永远看到空名册，症状是所有角色
+  // 都寄不出信（fail-closed，至少不静默漏）。见 cast.js createRoleRoster 的头注释。
+  // 名册由 session-loop 建好传进来（cast_role 也要用同一份 —— 它记"这一回合造的角色"，
+  // 派发闸据此拦掉本回合内注定失败的派发）。没传就自建，单测/脚本直接调时仍成立。
+  const roleRoster = injected || createRoleRoster();
+
   return assertHooksWellFormed({
     // ── P0+ stage 1（不动）──
 
@@ -139,10 +153,31 @@ export function createHooks({ ctx, workspaceRoot, sharedRoot, sessionId, project
     }, {
       matcher: 'Task|Agent',
       hooks: [
-        makePreToolUseAgentForceForegroundHandler(),
+        makePreToolUseAgentForceForegroundHandler({ roster: roleRoster, workspaceRoot, ctx }),
         // vision-checker 派遣 prompt 模板首次注入（仅当 subagent_type='vision-checker'）
         makePreToolUseTaskVisionCheckerDispatchInjector(),
       ],
+    }, {
+      // SendMessage 收件人闸：只放行 main / 本项目常驻角色 / 本会话 agentId。
+      // 这个工具的另一半寻址空间是**同机其他 Claude 会话**（探针实测 ListAgents
+      // 列得出来），跨会话寄信 = 一个用户的 agent 给另一个人的 agent 递指令。
+      // SDK 的 crossSessionInbound 只管收不管发，发这侧得自己拦。见 pre-peer-guard.js
+      matcher: 'SendMessage',
+      hooks: [makePreToolUseSendMessageRecipientGuard({ roster: roleRoster })],
+    }, {
+      // 板上写入的署名：工具执行前把「这次是谁调的」记下来（MCP handler 自己拿不到
+      // agent 身份，hook 拿得到）。常驻角色写的板书要署它的名，不能全算主 agent 头上。
+      // 见 agent/actor-trail.js —— 权威是 harness 盖的章，不是角色文件里的自称。
+      //
+      // ⛔ 这里曾是手写工具名单，漏过两次，两次症状都是「闸装着、判据永远落 'agent'」：
+      //   - 08-26 漏 await_user/check_inbox/read_board → 整条收件箱回路在生产里是死的
+      //   - 08-28 审出漏场务四件 → 对真角色恒拒（它们永远被当成主控）
+      //   （两族工具 08-29 随编排收敛一起退役，教训留着：通配挂法就是从这两次来的）
+      // 手写名单和「写死表家族」同病：加新工具必漏。改成全量盖章 —— 盖章本身只是往
+      // 500 容量的 LRU Map 记一条，多盖无副作用，凡是可能用 byOf 的工具永远在闸内。
+      // 装配层有测试钉着（hooks-assembly.test.js）：别再收窄回名单。
+      matcher: 'mcp__nodesign__.*',
+      hooks: [makePreToolUseActorStamp()],
     }, {
       // ⚠️ Grep 的输入改写只许有这一个 handler——两个各返回 updatedInput 会互相抹掉
       matcher: 'Grep',
@@ -191,6 +226,16 @@ export function createHooks({ ctx, workspaceRoot, sharedRoot, sessionId, project
       // UserPromptSubmit 的全图摘要截断后，这里做精确补充。每个文件一个会话只注一次。
       matcher: 'Read|Edit|Write',
       hooks: [makePreToolUseBoardNeighborhoodInjector({ workspaceRoot, projectId })],
+    }, {
+      // 板上动静（2026-08-29 纸范式刀 4）：用户回合中途拖动/搬家/擦组，agent 下一次
+      // 摸板前插话（按会话恰好一次，台账在 lib/board-dirty.js）。
+      matcher: 'mcp__nodesign__(write_on_board|edit_board|read_board|board_batch|open_sheet|organize_board|look_at_board)',
+      hooks: [makePreToolUseBoardDirtyInjector({ projectId, sessionId })],
+    }, {
+      // 未知参数探针（2026-08-30）：zod 把 schema 里没有的键静默 strip 掉，工具自己
+      // 看不见 —— 只有钩子拿得到原始 tool_input。挂全部 nodesign 工具。
+      matcher: 'mcp__nodesign__.*',
+      hooks: [makePreToolUseUnknownParamsProbe()],
     }, {
       matcher: 'Write',
       hooks: [
@@ -205,9 +250,11 @@ export function createHooks({ ctx, workspaceRoot, sharedRoot, sessionId, project
       ],
     }],
 
-    // Stop —— agent 准备结束 query 时触发，发自检事件给前端
+    // Stop —— agent 准备结束 query 时触发，发自检事件给前端。
+    // 第二个是演出模式的收尾闸：这一拍既没给按钮也没交给角色就不许收工
+    // （08-28 真会话的头号病：写完两千字正文玩家没有任何把手）。
     Stop: [{
-      hooks: [makeStopReflectionHandler({ ctx, workspaceRoot })],
+      hooks: [makeStopReflectionHandler({ ctx, workspaceRoot }), makeStopBeatGate({ sessionId, projectId })],
     }],
 
     // PostCompact —— compact 后把摘要写入 spec.json 长期记忆
@@ -232,6 +279,18 @@ export function createHooks({ ctx, workspaceRoot, sharedRoot, sessionId, project
     // PostToolUse —— 按 MCP 工具名分别注 additionalContext，引导 agent 利用
     // 工具结果。matcher 字段是 SDK 标准（与 PreToolUse 'Bash' 同语义）。
     PostToolUse: [
+      // 演员位实例学名（2026-08-28 重构）：hook input 没有实例名字段，名字只在
+      // 派发/唤醒的 tool_result 里露面 —— 从那里学 agentId→实例名（slot-alias.js）。
+      // 收件箱、板书署名、退场标记全靠这张表把 rp-actor 解析回具体角色。
+      {
+        matcher: 'Task|Agent|SendMessage',
+        hooks: [makePostToolUseSlotAliasHandler(), makePostToolUseBeatHandoff({ sessionId, projectId })],
+      },
+      // 收尾闸的另一半：主持人往画布上写了什么、带没带按钮（见 hooks/beat-gate.js）
+      {
+        matcher: 'mcp__nodesign__write_on_board|mcp__nodesign__board_batch',
+        hooks: [makePostToolUseBeatWrite({ sessionId, projectId })],
+      },
       // Edit/Write 后干掉 tool_response.originalFile：FileEditOutput/FileWriteOutput
       // 默认含完整原文件（sdk-tools.d.ts:2270, 2328），这是上下文累积大头。
       // canvas.html 25KB 一次 Edit ≈ 6k tokens，30 turn 累积可达 180k+ → 触发 256k 上限。
@@ -294,28 +353,35 @@ export function createHooks({ ctx, workspaceRoot, sharedRoot, sessionId, project
           makePostToolUseSiteValidationHandler({ workspaceRoot }),
         ],
       },
-      // record_decision 一般**不注** additionalContext（"继续主任务"那种跟 SDK
-      // preset 重复，agent 自己懂）。唯一例外是"锚定风格"这一笔：那是项目级
-      // 长期资产该落盘的时刻，而品牌档案 / 项目指引这两处 SDK 不知道。
-      {
-        matcher: 'mcp__nodesign__record_decision',
-        hooks: [makePostToolUseStyleAnchorNudge({ sharedRoot })],
-      },
+      // （record_decision 及其 style-anchor nudge 2026-08-24 整条目拆除 ——
+      //  风格落盘的提醒并进 auto-memory 的追加指导（session-loop 的
+      //  CLAUDE_COWORK_MEMORY_EXTRA_GUIDELINES）。删的是**整个 {matcher, hooks}
+      //  条目**，空壳条目会让 SDK initialize 静默灭门，见 assertHooksWellFormed。）
     ],
 
     // PostToolUseFailure —— 任意工具失败时统一处理：emit 事件 + 给 agent
     // 注入恢复建议（避免重试同样的错）。
     PostToolUseFailure: [{
       hooks: [makePostToolUseFailureHandler({ ctx, projectId, sessionId })],
+    }, {
+      // 常驻角色派发失败 → 把名字从名册里撤回。claim 在 PreToolUse（派发**之前**），
+      // 不撤的话这个名字整个会话被 brick，而且收件人闸会对一个并不存在的 agent 放行
+      // （裸名回落全机解析 = H1 那个洞在窄窗口里重开）。见 resident-role-lifecycle.js
+      matcher: 'Task|Agent',
+      hooks: [makePostToolUseFailureRoleRelease({ roster: roleRoster })],
     }],
 
     // SubagentStart / SubagentStop —— 主动捕子代理生命周期。当前只 emit 事件
     // 给上层观察；不阻塞流程。stage 2 真接通子代理时这里加调度逻辑。
     SubagentStart: [{
-      hooks: [makeSubagentStartHandler({ ctx })],
+      // 第二个 handler 是署名的正门：agent_id ↔ 角色名在起飞这一刻绑定
+      // （见 resident-role-lifecycle.js；旧的"从 tool_result 抠 id"已退役）
+      hooks: [makeSubagentStartHandler({ ctx, sessionId }), makeSubagentStartRoleAlias({ projectId })],
     }],
     SubagentStop: [{
-      hooks: [makeSubagentStopHandler({ ctx })],
+      // 常驻角色退场时补一句「怎么把它叫回来」给主控。放在通用 emit 之后：
+      // 那个只 emit 事件不返输出，两者不抢 systemMessage。见 resident-role-lifecycle.js
+      hooks: [makeSubagentStopHandler({ ctx, sessionId }), makeSubagentStopRoleNotice({ projectId })],
     }],
   });
 }

package/server/engine/agent/isolation.js

@@ -25,6 +25,7 @@ import os from 'node:os';
 import fs from 'node:fs/promises';
 import { platform } from '../../runtime/platform.js';
 import { autoModeSettings } from './auto-mode-rules.js';
+import { MCP_ALLOW_RULE } from '../mcp/server-name.js';
 
 /**
  * 会话要用的缓存/临时目录一次备齐（2026-08-19 从 session-loop 下沉）。
@@ -129,7 +130,15 @@ export function buildIsolationOptions({ cwdRoot, sharedRoot, npmCacheDir, agentT
           // 没有它 Bash 的 tmp 只读：venv 静默失败、pip --user EROFS、npm 装不上
           ...(agentTmpDir ? [agentTmpDir] : []),
         ],
-        denyWrite: ['/etc', '/usr', '/bin', '/sbin', '/private/etc'],
+        // ⛔ 角色文件不许模型写（2026-08-26）：它是派发闸的判据本身，模型能改就等于
+        // 自己给自己发工具权限（TOCTOU + 解析器分歧两条绕法，详见
+        // hooks/pre-workspace-scope-guard.js 那段注释）。
+        // 这半只管 Bash —— Write/Edit 是进程内工具**不进 bwrap**，那半在上面那道闸。
+        // 正门 cast_role 走服务端 fs，不经沙盒，照写不误。
+        denyWrite: [
+          '/etc', '/usr', '/bin', '/sbin', '/private/etc',
+          ...(cwdRoot ? [path.join(cwdRoot, '.claude', 'agents')] : []),
+        ],
         // 数据根整个盖住、再用 allowRead 给自己的工作区开天窗。
         // ⚠️ 口径要准（08-18 上生产时实测纠正）：`ls 数据根` **看得见别的项目的
         // 目录名**（沙盒里实测列出了另一个 pid），拦住的是**进去读**——
@@ -149,7 +158,21 @@ export function buildIsolationOptions({ cwdRoot, sharedRoot, npmCacheDir, agentT
       },
     },
     settings: {
-      permissions: { deny: platform.protectedPathRules({ dataRoot }) },
+      permissions: {
+        deny: platform.protectedPathRules({ dataRoot }),
+        // 本平台自己的 MCP 工具整服务放行，不过 auto 模式分类器（2026-08-25 用户拍板）。
+        //
+        // 为什么：这些工具是我们自己写的，每一件的边界在服务端**已经**有闸
+        //   —— 出网走 ssrf-guard，publish_site / 本地产线走 owner + 档位闸，
+        //   生图走额度闸，路径走 permissions.deny + 沙盒。让一个模型分类器
+        //   再判一遍 `read_board` 安不安全，既判不出新东西，还多一次外部依赖。
+        // 真实账：真用户会话里分类器**从没拦下过一次真越界**（唯一那条是
+        //   Stage 2 classifier error 误伤 deliver_files 交稿），却因为自身不可用
+        //   挡掉过 8 个会话的正经活（08-24 一天 15 次）。闸门的净效用是负的。
+        // Bash **不在**名单里：它跑的是任意命令，语义判断正是分类器的本职。
+        //   内置的 Read/Write/Edit/WebFetch 等也照旧不动。
+        allow: [MCP_ALLOW_RULE],
+      },
       // auto 模式的分类器规则（只在开了 auto 时注入，省得白占 settings）。
       // ⚠️ 按节替换不是追加 —— 为什么只覆盖 environment / hard_deny 两节，
       // 见 auto-mode-rules.js 文件头。

package/server/engine/agent/memory-config.js

@@ -0,0 +1,87 @@
+/**
+ * agent/memory-config.js — auto-memory 的产品化配置（2026-08-24 记忆体系改版）
+ *
+ * 记忆两层的分工（用户拍板）：
+ *   - `记忆/`（工作区根下，画布可见）：SDK auto-memory 的家。提示词、写入、
+ *     MEMORY.md 索引加载、权限放行全跟 autoMemoryDirectory 一个值走（二进制 yh()，
+ *     08-24 探明）。用户看得到每一条、也可能直接改。
+ *   - 根 `CLAUDE.md`：人工筛选的项目档案（指引/风格/习惯），SDK 每会话
+ *     确定性全量注入（settingSources 'project' 原生行为，根目录与 .claude/ 两处都读）。
+ *
+ * ⚠️ EXTRA_GUIDELINES 是**追加**不是替换：SDK 自己的记忆合同（frontmatter 契约、
+ * 两步写入、200 行索引上限与截断提醒）原样保留。别换成 CLAUDE_COWORK_MEMORY_GUIDELINES
+ * 整段替换 —— 那会把截断提醒一起抹掉，而截断逻辑仍在跑，索引爆了没人说话。
+ */
+
+import path from 'node:path';
+
+/** 记忆目录名（工作区根相对）。画布可见是设计要求，不是巧合。 */
+export const MEMORY_DIR_NAME = '记忆';
+
+export function memoryDirFor(sharedRoot) {
+  return path.join(sharedRoot, MEMORY_DIR_NAME);
+}
+
+/** 追加进 SDK 记忆提示末尾的产品口径（env CLAUDE_COWORK_MEMORY_EXTRA_GUIDELINES） */
+export const MEMORY_EXTRA_GUIDELINES = [
+  'This memory directory (记忆/) is VISIBLE on the user\'s canvas — they can read',
+  'every file and may edit them between sessions; treat edits as ground truth.',
+  'Keep file names as short English kebab-case slugs (the SDK contract), but write',
+  'descriptions and content in the user\'s language (中文 for this product).',
+  'When a style decision is settled (palette / fonts / materials / art direction),',
+  'record it as a `type: project` memory right away — style anchors are the most',
+  'expensive thing to lose between sessions.',
+  'Hard constraints and curated project guidance live in the workspace-root',
+  'CLAUDE.md (deterministically injected every session) — put lasting rules there',
+  '(with the user\'s consent), and put evolving facts here.',
+].join(' ');
+
+/**
+ * 把我们的 settings 跟 isolationOptions.settings **深合并**成 SDK 的最终 settings。
+ *
+ * ⛔ 存在的理由（08-24 案）：08-15 起 buildIsolationOptions 的返回值里也有
+ * settings 键，query options 里对象展开写在后面，把独立写的 settings 整个覆盖 ——
+ * autoMemoryEnabled / autoMemoryDirectory / skipWebFetchPreflight 八天没送到
+ * SDK 手里（agent 照 SDK 默认路径写记忆被沙盒拒、~/.claude 下堆了 187 个空目录）。
+ * 「两处同名键静默互吞」没有任何报错，出口断言在这里兜。
+ */
+export function mergeAgentSettings(isolationSettings, extra = {}) {
+  // ⚠️ 这个第二参是**显式白名单**（它存在的理由就是防 settings 互吞）。所以它有一个
+  // 结构性陷阱：往调用点里塞一个这里没解构的新键 = 那个键被静默丢弃，零症状。
+  // 2026-08-26 真踩：`crossSessionInbound: 'refuse'`（跨会话入向闸）在调用点写得好好的，
+  // 到了 SDK 手里根本不存在 —— 修互吞案的函数自己吞了新键。
+  // 所以未知键**当场炸**：白名单的代价必须由加键的人当场付，不能由线上静默付。
+  const { skipWebFetchPreflight, sharedRoot, crossSessionInbound, ...unknown } = extra;
+  const unknownKeys = Object.keys(unknown);
+  if (unknownKeys.length) {
+    throw new Error(
+      `[memory-config] mergeAgentSettings 收到不认识的键：${unknownKeys.join(', ')} —— `
+      + '这个第二参是显式白名单，加新键要同时改这里的解构和下面的出口断言，别指望它透传',
+    );
+  }
+
+  const settings = {
+    ...isolationSettings,
+    skipWebFetchPreflight,
+    // 跨会话入向（2026-08-26）：实测——不是推断——Nodesign 的每个会话都会以 cwd
+    // 派生的名字注册进**本机 peer 名册**（生产上正在跑的用户会话当时显示为
+    // `shared-6d`），同机任何一个 Claude 会话 ListAgents 都看得见、都能按名字寄信。
+    // SDK 默认「权限模式相同就自动投递」（bypass↔bypass），而我们正是
+    // bypassPermissions → 本机任何 bypass 会话都能把文本注进用户会话的上下文。
+    // 出向那侧我们自己拦（hooks/pre-peer-guard.js），入向只有这一个旋钮。
+    // ⛔ 别写 'hold'：那是「存起来等人批准」，而服务端没有人在批。
+    ...(crossSessionInbound ? { crossSessionInbound } : {}),
+    ...(sharedRoot ? {
+      autoMemoryEnabled: true,
+      autoMemoryDirectory: memoryDirFor(sharedRoot),
+    } : {}),
+  };
+  if (sharedRoot && !settings.autoMemoryDirectory) {
+    throw new Error('[memory-config] settings.autoMemoryDirectory 被吞了 —— 检查 settings 合并处');
+  }
+  // 出口断言按「传进来的每个键都要在出口活着」逐条对，不是只看一个样本键
+  if (crossSessionInbound && settings.crossSessionInbound !== crossSessionInbound) {
+    throw new Error('[memory-config] settings.crossSessionInbound 被吞了 —— 跨会话入向闸会静默失效');
+  }
+  return settings;
+}

package/server/engine/agent/model-context.js

@@ -28,34 +28,43 @@
  * Opus 价虚高 30×）。repriceUsageDeltas 把 usage key 还原成 appModel、按行内
  * prices 重算 costUsd。行没填 prices = 沿用 SDK 虚价（接真流量前必须填价）。
  *
- * ⚠️ 硬约束：一个 sdkAlias 不能被两个 API 模型共用 —— 反查靠它，撞了整条
- * 路由和记账都错。模块加载断言兜底。
+ * ## sdkAlias 两种写法（08-25 起）
+ *
+ * - **不写（默认）**：派生时补上共用别名 SHARED_SDK_ALIAS，只按 id 进反查表，
+ *   靠会话级路由分辨（session-routes.resolveSessionWire）。加新行不用考虑别名。
+ * - **显式写 = 独占坑位**：alias 三种形态都进反查表，没会话也能按 alias 反查。
+ *   ⚠️ 硬约束只对这种成立：一个独占 sdkAlias 不能被两个 API 模型共用 ——
+ *   反查靠它，撞了整条路由和记账都错。模块加载断言兜底。
  */
 
 import { can, localGenApproved, DENIAL } from '../../auth/tier.js';
 import { platform } from '../../runtime/platform.js';
-import { UPSTREAMS_BUILTIN, MODELS_BUILTIN, BRANDS } from './model-table.js';
+import { UPSTREAMS_BUILTIN, MODELS_BUILTIN, BRANDS, SHARED_SDK_ALIAS } from './model-table.js';
 import { loadLocalConfig } from '../../runtime/local-config.js';
 
-export { BRANDS };
+export { BRANDS, SHARED_SDK_ALIAS };
 
 // ── 内置表 + 用户插槽合并（08-22）──
-// 外部行（runtime/local-config.js）全部共用这一个 sdkAlias：表内唯一空着的 1M 订阅名。全表反查分不出它们，
-// 靠 ingress/session-routes.js 会话优先路由（一个会话只认自己那行）。所以外部行**不进 WIRE_LOOKUP 的 alias 键**，
-// 只按 id 可查；没注册会话的请求用这个 alias 发过来一律 502（探针要带会话前缀）。
-export const EXTERNAL_SDK_ALIAS = 'claude-sonnet-4-6[1m]';
 const external = loadLocalConfig();
 export const UPSTREAMS = Object.freeze({ ...UPSTREAMS_BUILTIN, ...external.upstreams });
-/** 配置条目 → 表行（字段名一一对应，见 local-config.js 文件头） */
+/** 配置条目 → 表行（字段名一一对应，见 local-config.js 文件头；sdkAlias 不许手填 = 永远走下面的共用别名默认） */
 function toExternalRow(m) {
   const { id, label, desc, brand, window, uncensored, upstream, wireModel, fastModel, ...api } = m;
   return Object.freeze({
     id, window, brand, external: true, ...(uncensored ? { uncensored: true } : {}),
     select: Object.freeze({ label, desc }),
-    api: Object.freeze({ upstream, wireModel, sdkAlias: EXTERNAL_SDK_ALIAS, fastModel: fastModel || id, ...api }),
+    api: Object.freeze({ upstream, wireModel, fastModel: fastModel || id, ...api }),
   });
 }
-const MODELS = Object.freeze([...MODELS_BUILTIN, ...external.models.map(toExternalRow)]);
+// sdkAlias 可选（08-25 固化）：API 行不写 = 补上共用别名 SHARED_SDK_ALIAS（内置行、外部插槽同一条路）。
+// 共用别名的行**不进 WIRE_LOOKUP 的 alias 键**，只按 id 可查，靠 ingress/session-routes.js 会话优先路由
+// 分辨（一个会话只认自己那行和自己的 fast 行）；没注册会话的请求用这个 alias 发过来一律 502（探针要带
+// 会话前缀）。独占别名的行才显式写 sdkAlias，语义见 model-table.js 字段说明。
+function withDefaultAlias(row) {
+  if (!row.api || row.api.sdkAlias) return row;
+  return Object.freeze({ ...row, api: Object.freeze({ ...row.api, sdkAlias: SHARED_SDK_ALIAS }) });
+}
+const MODELS = Object.freeze([...MODELS_BUILTIN, ...external.models.map(toExternalRow)].map(withDefaultAlias));
 /** 外部插槽被整条丢掉的原因（启动日志一份、GET /api/local/config 一份，同一个数组） */
 export const MODEL_CONFIG_ERRORS = external.errors;
 
@@ -79,16 +88,25 @@ for (const row of MODELS) {
   if (BY_ID.has(row.id)) throw new Error(`[model-context] 模型 id 重复：${row.id}`);
   BY_ID.set(row.id, row);
 }
+// 共用别名的本体必须始终是表内一条订阅 Claude 行：它是「不写 sdkAlias」的默认值，哪怕此刻没行在用，
+// 删掉/改坏那条订阅行也要当场炸，不能等到下一条新行加进来才发现 SDK 不认识、窗口查不到。
+{
+  const shared = BY_ID.get(SHARED_SDK_ALIAS);
+  if (!shared || shared.api) throw new Error(`[model-context] SHARED_SDK_ALIAS（${SHARED_SDK_ALIAS}）必须是表内订阅模型行 —— 它是 sdkAlias 不写时的默认值`);
+}
 for (const row of MODELS) {
   try { checkRow(row); } catch (err) {
     if (!row.external) throw err;
     BY_ID.delete(row.id); MODEL_CONFIG_ERRORS.push({ where: `models (${row.id})`, message: err.message }); continue;
   }
   if (!row.api) continue;
-  const keys = row.external ? [row.id] : [row.id, row.api.sdkAlias, row.api.sdkAlias.replace(/\[1m\]$/i, '')];
+  // 共用别名的行（sdkAlias 没写、派生时补的默认值）只按 id 进反查表：那个别名同时属于好几行，
+  // 全表反查分不出谁是谁，只有会话知道（session-routes.resolveSessionWire 主行优先）。
+  const sharesAlias = row.api.sdkAlias === SHARED_SDK_ALIAS;
+  const keys = sharesAlias ? [row.id] : [row.id, row.api.sdkAlias, row.api.sdkAlias.replace(/\[1m\]$/i, '')];
   for (const k of keys) {
     const prev = WIRE_LOOKUP.get(k);
-    if (prev && prev !== row) throw new Error(`[model-context] wire 名撞车：'${k}' 同时属于 ${prev.id} 和 ${row.id}（一个 sdkAlias 不能共用）`);
+    if (prev && prev !== row) throw new Error(`[model-context] wire 名撞车：'${k}' 同时属于 ${prev.id} 和 ${row.id}（独占 sdkAlias 不能共用；不想独占就别写 sdkAlias，让它走共用别名）`);
     WIRE_LOOKUP.set(k, row);
   }
 }
@@ -168,7 +186,7 @@ export function isModelLockedFor(user, appModel) {
 }
 
 /**
- * 这个用户没选过时用哪个：表里标 `default: true` 的行（08-21 = ox-alpha），它对该用户
+ * 这个用户没选过时用哪个：表里标 `default: true` 的行（08-26 起 = minimax-m3），它对该用户
  * 不可选时退到第一个可选的。前端 picker 与新会话的兜底都问这条，不再各自硬编码。
  */
 export function defaultModelFor(user) {
@@ -177,19 +195,76 @@ export function defaultModelFor(user) {
 }
 
 /**
- * 会话中途从 openai-chat 行（Ox）切到别的通路要拦（08-21 fable 评审 P3）：转换层合成的 thinking 块
- * 没有 signature，CLI 会把它们原样回传给 Anthropic → 400 invalid signature。返回拒绝理由或 null。
+ * 会话中途从 openai-chat 行（Ox / DeepSeek）切到别的通路要拦（08-21 fable 评审 P3）：转换层合成的
+ * thinking 块没有 signature，CLI 会把它们原样回传给说 Anthropic 协议的那一头 → 400 invalid signature。
+ * 返回拒绝理由或 null。
+ *
+ * ⚠️ 拦的是**协议方向**不是"要不要 Claude"：08-25 接了 MiniMax（Anthropic 原生透传）之后，
+ * 从 Ox 切到 MiniMax 同样是这条路，所以话里不许再写死"换到 Claude"。
  */
 export function crossLaneSwitchReason(fromModel, toModel) {
   if (!fromModel || !toModel || fromModel === toModel) return null;
   const from = resolveWireModel(fromModel);
   const to = resolveWireModel(toModel);
   if (from?.protocol === 'openai-chat' && to?.protocol !== 'openai-chat') {
-    return '这个会话是在 Ox（免费）上开的，它的思考记录换到 Claude 会被拒收。想用 Claude 请新开一个会话';
+    const fromLabel = BY_ID.get(from.appModel)?.select?.label || from.appModel;
+    return `这个会话是在 ${fromLabel} 上开的，它的思考记录换到别的模型会被拒收。想换模型请新开一个会话`;
   }
   return null;
 }
 
+/**
+ * **运行中**热切模型（POST /runs/:runId/model）额外要拦的一条：订阅 ↔ API 跨通路。
+ *
+ * 决定一条会话走订阅还是走 API 的是**起 query 那一刻注入的 env**（BASE_URL / API_KEY，
+ * 见 session-loop 的 route 分支），而 env 是 per-query 的，`setModel` 改不动它。所以跑到
+ * 一半跨通路切的真实后果是：
+ *   - 订阅会话切到 API 行 → binary 手里没有 ingress 地址，会拿着 ~/.claude 的 OAuth 把
+ *     **alias 名**（那都是真实存在的 Claude 模型）打到 anthropic.com —— 界面写着"免费"，
+ *     烧的是订阅额度。⛔ 这是要花真钱的那种错。
+ *   - API 会话切回订阅行 → 那个名字进了 ingress 反查不到，兜底到本会话的 fast 行，
+ *     等于"切了没生效"。
+ * 两边都不是用户想要的，所以运行中一律拒绝，让人等这轮跑完（PUT /sessions/:sid/model
+ * 那条等空闲重启 query，换的是新 env，不受这条限制）。
+ *
+ * 与 crossLaneSwitchReason 是两条**正交**的闸：那条管协议（openai-chat 的思考块没
+ * signature），这条管通路（env 定死在起 query 那一刻）。
+ */
+export function hotSwitchLaneReason(fromModel, toModel) {
+  if (!fromModel || !toModel || fromModel === toModel) return null;
+  const from = resolveModelRoute(fromModel).mode;
+  const to = resolveModelRoute(toModel).mode;
+  if (from === to) return null;
+  return to === 'api'
+    ? '这一轮是用订阅模型开的，跑到一半换不成 API 模型 —— 网关地址和钥匙在起这一轮时就定死了，硬切会拿订阅额度去跑。等这轮跑完再换，或者新开一个会话'
+    : '这一轮是用 API 模型开的，跑到一半换不回订阅模型 —— 同样是网关地址起这一轮时就定死了。等这轮跑完再换，或者新开一个会话';
+}
+
+/**
+ * **换模型该不该拒**（null = 放行）。三条写模型的路共用这一个判断：turn.js 的 body.model、
+ * sessions.js 的 PUT /model、turn-model-switch.js 的运行中热切。
+ *
+ * 收成一份是因为 08-21 装的那条协议闸在两处都没真工作过（08-25 发现）：sessions.js 那份把闸写在
+ * applySessionModel **之后**、又拿 apply 之后的模型当 from，等于自己跟自己比，恒返 null；turn.js 那份
+ * 带着 `override &&`，跑在全局默认上的会话整个逃过检查。同一个判断散成三份手写代码就是这个下场 ——
+ * 这个仓库为「同一件事有多个实例」付过最贵的学费。
+ *
+ * @param {object} p
+ * @param {string} p.from        **改之前**的有效模型（⚠️ 不是刚写进去的那个 —— 那正是旧 bug）
+ * @param {string} p.to          要换成的模型（清覆盖时传全局默认那一行，别传 null）
+ * @param {boolean} [p.hasHistory] 这个会话跑过没有。没跑过就没有历史，协议闸不该拦（拦了只是让人换不了模型）
+ * @param {boolean} [p.running]  当前有没有正在跑的 query。跑着的话 env 已经定死，额外过通路闸
+ * @returns {string|null} 给用户看的拒绝理由
+ */
+export function modelSwitchRejection({ from, to, hasHistory = true, running = false }) {
+  if (!from || !to || from === to) return null;
+  if (hasHistory) {
+    const why = crossLaneSwitchReason(from, to);
+    if (why) return why;
+  }
+  return running ? hotSwitchLaneReason(from, to) : null;
+}
+
 /** 免费行（API 行且四价全 0）：金额配额对它无意义，turn.js 改走按轮次的免费闸 */
 export function modelIsFree(appModel) {
   const p = BY_ID.get(appModel)?.api?.prices;
@@ -307,6 +382,11 @@ export function resolveWireModel(bodyModel) {
     // 预算 + 单发最长挂起（实测 185 秒）必须 < 600 秒（配了断言，见 upstream-truncation.test.js）。
     emptyRetries: Number.isFinite(row.api.emptyRetries) ? row.api.emptyRetries : null,
     retryBudgetMs: Number.isFinite(row.api.retryBudgetMs) ? row.api.retryBudgetMs : null,
+    // 上游要的额外顶层 body 字段（今天只有 merge 的 `vendor` 点名，见表里那行）。
+    // ⚠️ **这一份配置有两个读者**，因为两条腿各自序列化 body：Anthropic 透传在 transformForUpstream
+    // 里 Object.assign 到 parsed，openai-chat 在 toOpenAIChatRequest 里合进 out。加第三条腿要记得
+    // 带上它 —— 漏了不会报错，只是点名静默失效（model-ingress.test.js 两条腿各有一条断言）
+    bodyExtra: row.api.bodyExtra || null,
   };
 }
 
@@ -332,9 +412,13 @@ export function repriceUsageDeltas(deltas, sessionAppModel) {
   // helper 用 config 默认 Claude 名发的请求）必然被 ingress 的会话 fast 兜底
   // 承接 —— 归到 fastModel 头上是精确归因，不是猜测。
   const fastRow = BY_ID.get(sessionRow.api.fastModel);
+  // ⭐ 会话优先，跟入口路由同一个次序（session-routes.resolveSessionWire）：SDK 报的 usage key 是
+  // **本会话的 sdkAlias**，而共用别名（SHARED_SDK_ALIAS）根本不在 WIRE_LOOKUP 里 —— 只按全表反查的话
+  // 主行那笔账会整个落到 fastModel 头上（计量按模型分组就全错了，钱对了数不对）。
+  const sessionNames = new Set(wireNamesOf(sessionRow.id));
   const out = {};
   for (const [key, d] of Object.entries(deltas)) {
-    const row = WIRE_LOOKUP.get(key) || fastRow;
+    const row = (sessionNames.has(key) ? sessionRow : WIRE_LOOKUP.get(key)) || fastRow;
     const appKey = row ? row.id : key;
     const p = row?.api?.prices;
     const repriced = p ? {