@joekytc/dsh-swarm 0.3.12 → 0.5.1

package/lib/dispatcher/model-candidates.js

@@ -1,30 +1,51 @@
+/** 单角色降级候选上限（与 config schema .max(2)、config-override 校验同口径）。 */
+const MAX_FALLBACKS = 2;
 /**
- * 模型候选链：角色创建时主模型 → fallbacks 依次静默切换。
- * primary = config.roles.models[role]；未配置回退 defaultModel。
+ * 模型候选链（四层）：
+ * ① 角色 primary（config.roles.models[role]）→ ② 降级候选（fallbacks，顺序=优先序，≤2）
+ * → ③ 全局官方兜底（config.roles.chainFallback，恒垫链尾）→ ④ 宿主默认模型（defaultModel）。
+ * 角色链全空 → 官方兜底单候选直用；官方兜底也未配 → 宿主默认模型；都无 → 空链（调用方不传 agentOptions）。
  * reasoningEffort 未指定一律 'high'。
  *
  * @returns 有序候选链（不含不可用者；可能为空 = 无任何配置）
  */
 export function buildModelCandidates(config, role, defaultModel) {
     const m = config.roles?.models?.[role];
+    const cf = config.roles?.chainFallback;
+    const officialTail = [];
+    if (cf?.provider && cf?.model) {
+        officialTail.push({ provider: cf.provider, model: cf.model, reasoningEffort: cf.reasoningEffort ?? 'high' });
+    }
     const chain = [];
     if (m?.provider && m?.model) {
         chain.push({ provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort ?? 'high' });
-        for (const f of m.fallbacks ?? []) {
+        for (const f of (m.fallbacks ?? []).slice(0, MAX_FALLBACKS)) {
             if (f?.provider && f?.model)
                 chain.push({ provider: f.provider, model: f.model, reasoningEffort: f.reasoningEffort ?? 'high' });
         }
+        chain.push(...officialTail);
     }
-    else if (defaultModel?.provider && defaultModel?.model) {
-        chain.push({ provider: defaultModel.provider, model: defaultModel.model, reasoningEffort: defaultModel.reasoningEffort ?? 'high' });
+    else {
+        // 角色链全空：官方兜底直用；未配官方兜底 → 宿主默认模型（第四层安全网）。
+        if (officialTail.length)
+            chain.push(...officialTail);
+        else if (defaultModel?.provider && defaultModel?.model) {
+            chain.push({ provider: defaultModel.provider, model: defaultModel.model, reasoningEffort: defaultModel.reasoningEffort ?? 'high' });
+        }
     }
     return chain;
 }
-/** 判定 create/resume 错误是否属于 model/provider 不可用（可静默切换下一候选）。 */
+/**
+ * 判定 create/resume 错误是否属于候选不可用（可静默切换下一候选）。
+ * 覆盖三类：provider/model 不可用（无适配器/不存在）、凭据缺失（官方账号未登录
+ * MISSING_CREDENTIAL / 登录提示——不切换会把登录态问题误判成任务失败）。
+ */
 export function isModelUnavailableError(err) {
     const msg = String(err instanceof Error ? err.message : err).toLowerCase();
     if (msg.includes('adapter'))
         return true; // no adapter registered for provider …
+    if (msg.includes('missing_credential') || msg.includes('credentials') || msg.includes('login') || msg.includes('登录'))
+        return true;
     if (msg.includes('provider') && (msg.includes('unavailable') || msg.includes('not') || msg.includes('fail')))
         return true;
     return msg.includes('model') && (msg.includes('unavailable') || msg.includes('not found') || msg.includes('no adapter'));

package/lib/dispatcher/model-chain.d.ts

@@ -0,0 +1,19 @@
+import type { KanbanConfig } from '../config.js';
+import type { AgentModelOptions } from './dispatcher.js';
+export interface ModelChainState {
+    candidates: AgentModelOptions[];
+    index: number;
+    taskId?: string;
+    comment?: (body: string) => Promise<void>;
+}
+export declare function registerModelChain(agent: object, state: ModelChainState): void;
+export declare function isSwitchableModelFailure(failure: {
+    code?: string;
+    message?: string;
+    status?: number;
+}): boolean;
+export interface ModelChainHookDeps {
+    getConfig: () => KanbanConfig;
+    log?: (line: string) => void;
+}
+export declare function installModelChainHooks(scope: unknown, deps: ModelChainHookDeps): () => void;

package/lib/dispatcher/model-chain.js

@@ -0,0 +1,110 @@
+import { buildModelCandidates } from './model-candidates.js';
+import { agentPresetSelected } from './session-events.js';
+const chainStates = new WeakMap();
+export function registerModelChain(agent, state) {
+    chainStates.set(agent, state);
+    const session = agent.session;
+    if (session && typeof session === 'object')
+        chainStates.set(session, state);
+}
+export function isSwitchableModelFailure(failure) {
+    const code = String(failure.code ?? '').toLowerCase();
+    const msg = String(failure.message ?? '').toLowerCase();
+    if (code.includes('quota'))
+        return true;
+    if (failure.status === 402 || failure.status === 429)
+        return true;
+    if (/insufficient balance|quota|rate.?limit|\b429\b/.test(msg))
+        return true;
+    if (code === 'unknown_model' || code === 'unsupported_reasoning_effort')
+        return true;
+    if (code.includes('credential') || code.includes('login'))
+        return true;
+    if (msg.includes('adapter'))
+        return true;
+    if (msg.includes('missing_credential') || msg.includes('credentials') || msg.includes('login') || msg.includes('登录'))
+        return true;
+    if (msg.includes('provider') && (msg.includes('unavailable') || msg.includes('not') || msg.includes('fail')))
+        return true;
+    return msg.includes('model') && (msg.includes('unavailable') || msg.includes('not found') || msg.includes('no adapter'));
+}
+const ROLE_IDS = new Set(['v', 'p', 'w', 'd', 'pt', 'dt']);
+function sessionEventsOf(session) {
+    const s = session;
+    if (typeof s?.snapshotEvents === 'function')
+        return s.snapshotEvents();
+    return s?.events ?? [];
+}
+function detectManualChain(agent, config) {
+    const session = agent.session;
+    const preset = agentPresetSelected(sessionEventsOf(session))
+        ?? (session?.header?.agentPreset ?? null);
+    const role = typeof preset === 'string' && preset.startsWith('kanban-') ? preset.slice('kanban-'.length) : '';
+    let state = null;
+    if (ROLE_IDS.has(role)) {
+        const m = config.roles?.models?.[role];
+        if (m?.provider && m?.model) {
+            const candidates = buildModelCandidates(config, role);
+            if (candidates.length > 0)
+                state = { candidates, index: 0 };
+        }
+    }
+    chainStates.set(agent, state);
+    return state;
+}
+function resolveState(agent, config) {
+    const session = agent.session;
+    for (const key of [agent, session]) {
+        if (key && typeof key === 'object' && chainStates.has(key))
+            return chainStates.get(key) ?? null;
+    }
+    return detectManualChain(agent, config);
+}
+export function installModelChainHooks(scope, deps) {
+    const scoped = scope;
+    const disposeRequest = scoped.on('agent/request', async (payload, next) => {
+        const resolved = (await next());
+        const agent = payload.agent;
+        if (!agent || typeof agent !== 'object')
+            return resolved;
+        const state = resolveState(agent, deps.getConfig());
+        const cur = state?.candidates[state.index];
+        if (!cur)
+            return resolved;
+        return { ...resolved, provider: cur.provider, model: cur.model, reasoningEffort: cur.reasoningEffort ?? 'high' };
+    });
+    const disposeError = scoped.on('agent/request-error', async (payload, next) => {
+        const p = payload;
+        const agent = p.agent;
+        if (!agent || typeof agent !== 'object')
+            return next();
+        const state = resolveState(agent, deps.getConfig());
+        if (!state)
+            return next();
+        if (!isSwitchableModelFailure(p.failure ?? {}))
+            return next();
+        const nextIndex = state.index + 1;
+        if (nextIndex >= state.candidates.length)
+            return next();
+        const prev = state.candidates[state.index];
+        state.index = nextIndex;
+        const cur = state.candidates[nextIndex];
+        const detail = String(p.failure?.code ?? '') + ' ' + String(p.failure?.message ?? '');
+        const line = '[model-fallback] ' + prev.provider + '/' + prev.model + ' → ' + cur.provider + '/' + cur.model
+            + '（reasoningEffort=' + (cur.reasoningEffort ?? 'high') + '）: ' + detail;
+        console.error('[dsh-swarm][debug] ' + line);
+        deps.log?.(line);
+        if (state.taskId && state.comment) {
+            try {
+                await state.comment('[model-fallback] 主模型不可用，静默切换 ' + cur.provider + '/' + cur.model
+                    + '（reasoningEffort=' + (cur.reasoningEffort ?? 'high') + '）');
+            }
+            catch { /* 证据记录失败不影响切换 */ }
+        }
+        return { kind: 'retry' };
+    });
+    return () => {
+        disposeRequest();
+        disposeError();
+    };
+}

package/lib/dispatcher/session-events.d.ts

@@ -18,6 +18,13 @@ export declare function eventType(e: {
 export declare function toolName(e: unknown): string | undefined;
 /** 取工具调用参数对象（兼容 JSON 字符串 / 对象两种落盘形态）。 */
 export declare function toolArgs(e: unknown): Record<string, unknown>;
+/** run_code 派发子调用事件名（start 与完成两种）新旧宿主双名集合：
+ *  旧宿主会话落盘为 tool/code-dispatch-start / tool/code-dispatch；
+ *  宿主 V3+ 会话格式改名为 tool/ptc-dispatch-start / tool/ptc-dispatch。
+ *  消费方（链审计器按派发子调用判定 run_code 实际写行为）双名等价命中，勿散落硬编码。 */
+export declare const RUN_CODE_DISPATCH_EVENT_TYPES: ReadonlySet<string>;
+/** 该事件是否为 run_code 派发子调用事件（start 或完成，新旧事件名皆认）。 */
+export declare function isRunCodeDispatchEvent(e: unknown): boolean;
 /** 取 assistant 消息的网关缓存回放标记（replayState.response.responseModel，如 'from-cache'）。
  *  非 assistant/message 或无标记返回 null。2026-09-04：远程网关回复缓存整包回放时由 SSE
  *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。兼容落盘（data.message）
@@ -41,6 +48,8 @@ export interface TurnEndInfo {
     message: string | null;
 }
 export declare function turnEndOf(e: unknown): TurnEndInfo | null;
+/** 会话内最后一次 agent-preset/selected 的 preset id（如 'kanban-w'）；无该事件返回 null。 */
+export declare function agentPresetSelected(events: ReadonlyArray<unknown>): string | null;
 /** 本轮增量（seq > fromSeq）内最后一轮 turn/end——拒答重试会产生第二轮，取 seq 最大者。
  *  无 turn/end（测试桩/宿主变体）→ null，调用方按「无轮信息」回退原判据，不改变既有行为。 */
 export declare function lastTurnEnd(events: ReadonlyArray<unknown>, fromSeq: number): TurnEndInfo | null;

package/lib/dispatcher/session-events.js

@@ -35,6 +35,21 @@ export function toolArgs(e) {
     }
     return {};
 }
+/** run_code 派发子调用事件名（start 与完成两种）新旧宿主双名集合：
+ *  旧宿主会话落盘为 tool/code-dispatch-start / tool/code-dispatch；
+ *  宿主 V3+ 会话格式改名为 tool/ptc-dispatch-start / tool/ptc-dispatch。
+ *  消费方（链审计器按派发子调用判定 run_code 实际写行为）双名等价命中，勿散落硬编码。 */
+export const RUN_CODE_DISPATCH_EVENT_TYPES = new Set([
+    'tool/code-dispatch-start',
+    'tool/code-dispatch',
+    'tool/ptc-dispatch-start',
+    'tool/ptc-dispatch',
+]);
+/** 该事件是否为 run_code 派发子调用事件（start 或完成，新旧事件名皆认）。 */
+export function isRunCodeDispatchEvent(e) {
+    const t = eventType(e);
+    return t !== undefined && RUN_CODE_DISPATCH_EVENT_TYPES.has(t);
+}
 /** 取 assistant 消息的网关缓存回放标记（replayState.response.responseModel，如 'from-cache'）。
  *  非 assistant/message 或无标记返回 null。2026-09-04：远程网关回复缓存整包回放时由 SSE
  *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。兼容落盘（data.message）
@@ -71,6 +86,19 @@ export function turnEndOf(e) {
         message: typeof reason?.error?.message === 'string' ? reason.error.message : null,
     };
 }
+/** 会话内最后一次 agent-preset/selected 的 preset id（如 'kanban-w'）；无该事件返回 null。 */
+export function agentPresetSelected(events) {
+    let found = null;
+    for (const e of events) {
+        if (eventType(e) !== 'agent-preset/selected')
+            continue;
+        const rec = e;
+        const p = rec?.agentPreset ?? rec?.data?.agentPreset;
+        if (typeof p === 'string')
+            found = p;
+    }
+    return found;
+}
 /** 本轮增量（seq > fromSeq）内最后一轮 turn/end——拒答重试会产生第二轮，取 seq 最大者。
  *  无 turn/end（测试桩/宿主变体）→ null，调用方按「无轮信息」回退原判据，不改变既有行为。 */
 export function lastTurnEnd(events, fromSeq) {

package/lib/dispatcher/v-orchestrator.d.ts

@@ -34,7 +34,9 @@ export declare function buildPhaseInstruction(phase: VPhase, ctx: {
     taskId?: string;
 }, kbMode: 'remote' | 'local'): string;
 interface AgentLike {
+    /** 宿主 UserMessage 要求 identified（id 必填）：缺 id 的消息会被 v4 会话校验拒读。 */
     followup(msg: {
+        id: string;
         content: {
             type: string;
             text: string;

package/lib/dispatcher/v-orchestrator.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { installRoleTools } from '../roles/toolsets.js';
 import { mountOrRecompose } from '../roles/preset-installer.js';
 import { resolveTaskParents } from '../domain/task-parents.js';
@@ -5,6 +6,7 @@ import { missingParentDelivery } from '../domain/delivery-contract.js';
 import { buildRepoSlug } from '../domain/memory.js';
 import { toolArgs, toolName, replayModel } from './session-events.js';
 import { buildModelCandidates, isModelUnavailableError } from './model-candidates.js';
+import { registerModelChain } from './model-chain.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from './workspace-attach.js';
 export const R20_PHASE_ORDER = ['p', 'pt', 'w2', 'd', 'dt', 'w3', 'summary'];
 /** 每 phase 的期望建卡（pt 由 P 交付 pt_decision.needed=true 触发；dt 固定）。 */
@@ -266,7 +268,7 @@ export class VOrchestrator {
                 'gave_up 任务说明链路已停止，建议查看对应 [blocked-final] 证据链（block 时间线 + 复核/评论时间线 + 最终原因），给出终态解释。',
                 '规则：只评论、不建卡、不改任务状态；已有 [blocked-review] 评论的任务不要重复评论。',
             ].join('\n\n');
-            agent.followup({ content: [{ type: 'text', text: context }], source: { kind: 'user' } });
+            agent.followup({ id: randomUUID(), content: [{ type: 'text', text: context }], source: { kind: 'user' } });
             await agent.whenIdle();
             return; // 本轮 V 唯一动作是阻塞复核，不再推进阶段
         }
@@ -411,7 +413,7 @@ export class VOrchestrator {
             let turnError = null;
             try {
                 agent = await this.getVAgent(orch);
-                agent.followup({ content: [{ type: 'text', text: context }], source: { kind: 'user' } });
+                agent.followup({ id: randomUUID(), content: [{ type: 'text', text: context }], source: { kind: 'user' } });
                 await agent.whenIdle();
             }
             catch (err) {
@@ -619,7 +621,7 @@ export class VOrchestrator {
         // 与 agent-runner.ts 的 installRoleTools 用法一致。
         // V 后台编排会话与 P/W/D 一致，显式设置 approval=never + sandbox=workspace-write，
         // 避免在无 preset 装配时因默认审批策略在后台无应答者而挂起（卡死调度器首轮 tick）。
-        const setup = async (agentCtx) => {
+        const setup = async (agentCtx, agent) => {
             // 思考等级强制（waterfall）：与 agent-runner 同缺陷——宿主 selection 无 create-options 覆盖层，
             // agentOptions.reasoningEffort 不被消费，V 编排会话思考等级会落回宿主默认。走 DSH agent/request
             // waterfall 逐请求强制 'high'（宿主 installModelSelection 同机制），作用域仅本 V 会话。
@@ -629,7 +631,8 @@ export class VOrchestrator {
                 const resolved = await next();
                 return { ...resolved, reasoningEffort: 'high' };
             });
-            const session = agentCtx.agent?.session;
+            // approval/sandbox 种子事件经 AgentSetup 第二参的 agent 显式直写（0.2.0 起 ctx.agent 挂载已移除）。
+            const session = agent?.session;
             session?.append?.('approval/policy', { policy: 'never', source: 'delegation' });
             session?.append?.('sandbox/mode', { mode: 'workspace-write', source: 'delegation' });
             // 对齐（2026-08-17）：V=butler·orchestrator 零执行能力——先挂 kanban-v 裁剪 preset
@@ -653,9 +656,9 @@ export class VOrchestrator {
             }
             await installRoleTools(agentCtx, 'v', { kanban: this.kanban, wiki: this.wiki });
             // setup 完整成功（mount + 工具面）后写身份标记——live 复用校验依据（同 agent-runner 组合标记机制）。
-            const vAgent = agentCtx.agent;
-            if (vAgent && typeof vAgent === 'object')
-                vSessionCompositions.set(vAgent, V_SESSION_PRESET_ID);
+            // 键 = AgentSetup 第二参的 Agent 实例（与发布后 agents.get(id) 返回同一实例）。
+            if (agent)
+                vSessionCompositions.set(agent, V_SESSION_PRESET_ID);
         };
         // 模型候选链：V 会话 create/resume 按 primary→fallbacks 静默切换；
         // V 无任务卡可 block——全候选不可用抛最后错误（wakeV 调用方按既有错误路径处理）。
@@ -695,9 +698,11 @@ export class VOrchestrator {
         if (candidates.length === 0)
             return spawnWith({});
         let lastErr = null;
-        for (const candidate of candidates) {
+        for (const [candidateIndex, candidate] of candidates.entries()) {
             try {
-                return await spawnWith({ agentOptions: candidate });
+                const spawned = await spawnWith({ agentOptions: candidate });
+                registerModelChain(spawned, { candidates, index: candidateIndex });
+                return spawned;
             }
             catch (err) {
                 lastErr = err;

package/lib/domain/config-override.d.ts

@@ -1,10 +1,16 @@
 import type { KanbanConfig } from '../config.js';
 import type { Role } from './types.js';
 export declare const ROLES: readonly Role[];
+export interface ModelFallbackInput {
+    provider?: string;
+    model?: string;
+    reasoningEffort?: string;
+}
 export interface EditableModelInput {
     provider?: string;
     model?: string;
     reasoningEffort?: string;
+    fallbacks?: ModelFallbackInput[];
 }
 export interface EditableOverride {
     wikiVault?: {
@@ -25,10 +31,16 @@ export interface EditableOverride {
         fallbackBotId?: string;
     };
 }
+export interface ModelFallbackSnapshot {
+    provider: string;
+    model: string;
+    reasoningEffort: string;
+}
 export interface EditableModelSnapshot {
     provider: string;
     model: string;
     reasoningEffort: string;
+    fallbacks: ModelFallbackSnapshot[];
 }
 export interface EditableSnapshot {
     wikiVault: {
@@ -38,6 +50,12 @@ export interface EditableSnapshot {
     roles: {
         models: Partial<Record<Role, EditableModelSnapshot>>;
     };
+    /** 官方兜底（全局）——只读投影：编辑入口在部署配置（bundle patch），面板仅展示链尾。 */
+    chainFallback: {
+        provider: string;
+        model: string;
+        reasoningEffort: string;
+    };
     reviewEngine: {
         mode: 'delegate' | 'managed';
         managed: {
@@ -51,6 +69,8 @@ export interface EditableSnapshot {
 }
 export type ConfigSource = 'override' | 'inherited';
 export type SourceMap = Record<string, ConfigSource>;
+/** 单角色降级候选上限（与 config schema .max(2)、GUI 上限同口径）。 */
+export declare const MAX_FALLBACKS = 2;
 export declare function mergeConfig(baseline: KanbanConfig, override: EditableOverride | undefined): KanbanConfig;
 export declare function computeSources(override: EditableOverride | undefined): SourceMap;
 export declare function projectEditable(effective: KanbanConfig): EditableSnapshot;

package/lib/domain/config-override.js

@@ -2,6 +2,18 @@ export const ROLES = ['v', 'p', 'w', 'd', 'pt', 'dt'];
 /** botId 形态（与 dsh-im 的 id 校验同口径）：非空时只允许 id 安全字符。 */
 const BOT_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 const MODEL_FIELDS = ['provider', 'model', 'reasoningEffort'];
+/** 单角色降级候选上限（与 config schema .max(2)、GUI 上限同口径）。 */
+export const MAX_FALLBACKS = 2;
+/** 降级候选归一化：全空行丢弃（GUI 占位行）、effort 空白补 'high'、部分填写行保留（交校验报错）。 */
+function normalizeFallbacks(list) {
+    return (list ?? [])
+        .filter((f) => (f?.provider ?? '').trim() || (f?.model ?? '').trim())
+        .map((f) => ({
+        provider: (f.provider ?? '').trim(),
+        model: (f.model ?? '').trim(),
+        reasoningEffort: f.reasoningEffort?.trim() ? f.reasoningEffort : 'high',
+    }));
+}
 export function mergeConfig(baseline, override) {
     const wiki = { ...baseline.wikiVault };
     if (override?.wikiVault?.baseUrl !== undefined)
@@ -32,12 +44,15 @@ export function mergeConfig(baseline, override) {
         // 防御：空字符串 reasoningEffort 视为"未设置"，永不覆盖 baseline/默认（读点回退 'high'）。
         if (over.reasoningEffort !== undefined && over.reasoningEffort.trim() !== '')
             cur.reasoningEffort = over.reasoningEffort;
+        if (over.fallbacks !== undefined)
+            cur.fallbacks = normalizeFallbacks(over.fallbacks);
         if (cur.provider && cur.model)
             models[role] = cur;
     }
     const imDelivery = { ...baseline.imDelivery };
     if (override?.imDelivery?.fallbackBotId !== undefined)
         imDelivery.fallbackBotId = override.imDelivery.fallbackBotId;
+    // chainFallback 只属 baseline（部署配置），override 不触碰。
     return { ...baseline, wikiVault: wiki, roles: { ...baseline.roles, models }, reviewEngine, imDelivery };
 }
 export function computeSources(override) {
@@ -51,6 +66,7 @@ export function computeSources(override) {
             const hit = override?.roles?.models?.[role]?.[f] !== undefined;
             src[`roles.models.${role}.${f}`] = hit ? 'override' : 'inherited';
         }
+        src[`roles.models.${role}.fallbacks`] = override?.roles?.models?.[role]?.fallbacks !== undefined ? 'override' : 'inherited';
     }
     src['reviewEngine.mode'] = override?.reviewEngine?.mode !== undefined ? 'override' : 'inherited';
     src['reviewEngine.managed.provider'] = override?.reviewEngine?.managed?.provider !== undefined ? 'override' : 'inherited';
@@ -62,12 +78,21 @@ export function projectEditable(effective) {
     const models = {};
     for (const role of ROLES) {
         const m = effective.roles.models?.[role];
-        if (m?.provider && m?.model)
-            models[role] = { provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort ?? 'high' };
+        if (m?.provider && m?.model) {
+            models[role] = {
+                provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort ?? 'high',
+                fallbacks: normalizeFallbacks(m.fallbacks),
+            };
+        }
     }
+    const cf = effective.roles.chainFallback;
     return {
         wikiVault: { baseUrl: effective.wikiVault.baseUrl, pagePrefix: effective.wikiVault.pagePrefix },
         roles: { models },
+        chainFallback: {
+            provider: cf?.provider ?? '', model: cf?.model ?? '',
+            reasoningEffort: cf?.reasoningEffort?.trim() ? cf.reasoningEffort : 'high',
+        },
         reviewEngine: {
             mode: effective.reviewEngine?.mode ?? 'delegate',
             managed: { provider: effective.reviewEngine?.managed?.provider ?? '', model: effective.reviewEngine?.managed?.model ?? '' },
@@ -95,6 +120,18 @@ export function validateConfig(snapshot) {
             errs.push(`roles.models.${role}.provider`);
         if (!m.model?.trim())
             errs.push(`roles.models.${role}.model`);
+        const fbs = m.fallbacks ?? [];
+        if (fbs.length > MAX_FALLBACKS)
+            errs.push(`roles.models.${role}.fallbacks`);
+        fbs.forEach((f, i) => {
+            const p = (f?.provider ?? '').trim();
+            const mm = (f?.model ?? '').trim();
+            // 全空行 = GUI 占位（合法）；部分填写 = 未完成编辑，报错阻断。
+            if (!p && !mm)
+                return;
+            if (!p || !mm)
+                errs.push(`roles.models.${role}.fallbacks.${i}`);
+        });
     }
     // 默认机器人：留空=未设默认（合法，语义为「未命中就交互」）；非空必须形如 dsh-im 的 botId。
     const fb = (snapshot.imDelivery?.fallbackBotId ?? '').trim();
@@ -124,6 +161,13 @@ export function diffOverride(baseline, snapshot) {
         const snapEffort = snap?.reasoningEffort?.trim() ? snap.reasoningEffort : undefined;
         if (snapEffort !== undefined && snapEffort !== (base?.reasoningEffort ?? 'high'))
             cur.reasoningEffort = snapEffort;
+        // 降级链按归一化后整体比较：变化才整组写入。缺字段=显式空链（清空语义）；
+        // 旧客户端兼容由 HTTP 保存口回填 effective 链，不在此特判。
+        if (snap) {
+            const snapFbs = normalizeFallbacks(snap.fallbacks);
+            if (JSON.stringify(snapFbs) !== JSON.stringify(normalizeFallbacks(base?.fallbacks)))
+                cur.fallbacks = snapFbs;
+        }
         if (Object.keys(cur).length)
             models[role] = cur;
     }

package/lib/index.js

@@ -6,6 +6,8 @@ import { installRolePresets } from './roles/preset-installer.js';
 import { installLlWikiSkill } from './roles/skill-installer.js';
 import { registerKanbanHttp } from './routes/kanban-http.js';
 import { startDispatcher } from './dispatcher/dispatcher.js';
+import { installModelChainHooks } from './dispatcher/model-chain.js';
+import { logToDispatcherLog } from './dispatcher/agent-runner.js';
 import { ConfigProvider } from './services/config-provider.js';
 import { wireImDelivery } from './services/im-delivery.js';
 export const name = 'dsh-swarm';
@@ -36,14 +38,22 @@ export function apply(ctx, config) {
     const configProvider = new ConfigProvider(ctx, config, storageDir);
     // KanbanProvider 持 ConfigProvider 引用，kb_url base 经 getter 热读取（配置面板改后无需重建）。
     const provider = new KanbanProvider(ctx, config, configProvider);
-    // 把包内角色裁剪 preset 组合安装到 $DSH_HOME/.agent-presets/（真实 API 下唯一可发现的自定义根）。
-    const installed = installRolePresets();
+    // 双路安装角色裁剪 preset：目录写 $DSH_HOME/.agent-presets/（0.1.7-rc.x 宿主发现根）+
+    // 运行时注册 agentPresets.register（0.2.0 宿主唯一生效路径）。注册等服务就绪后完成，
+    // 由 installer 如实记录「目录写 / 运行时注册」各自清单，不假阳性。
+    void installRolePresets(ctx).catch((err) => {
+        console.warn('[dsh-swarm] role preset install error: ' + String(err));
+    });
     installLlWikiSkill(); // 尽力而为：失败仅告警不阻断
-    console.info('[dsh-swarm] role presets installed: ' + (installed.length ? installed.join(',') : 'none'));
     // IM 投递（企微，2026-09-07 评审决议）：W3 收尾/链阻塞时经 dsh-im 投群。
     // imDelivery.enabled=false（默认）时事件处理器零开销早退；dshIm 服务缺失显式降级留痕。
     const disposeImDelivery = wireImDelivery(ctx, provider.service, configProvider);
     ctx.on('dispose', disposeImDelivery);
+    const disposeModelChain = installModelChainHooks(ctx, {
+        getConfig: () => configProvider.getEffective(),
+        log: (line) => logToDispatcherLog(configProvider, line),
+    });
+    ctx.on('dispose', disposeModelChain);
     // LLM 运行时延迟取用：registerKanbanHttp 内部消费（llm-catalog 枚举），接线时 llm 服务已就绪。
     const llm = () => ctx.get('llm');
     // 可选服务接线均延迟到服务可用后：

package/lib/roles/preset-installer.d.ts

@@ -1,11 +1,56 @@
 /** 包内组合目录（随包分发）。src/roles/ 与 lib/roles/ 深度一致，均经 ../../ 回到包根。 */
 export declare function packagePresetsDir(): string;
-/** $DSH_HOME/.agent-presets（agent-presets 服务 includeUserRoot 派生根；DSH_HOME 缺省 ~/.dsh）。 */
+/** $DSH_HOME/.agent-presets（0.1.7-rc.x 宿主用户预设根；DSH_HOME 缺省 ~/.dsh）。 */
 export declare function userPresetsRoot(): string;
-/** 安装角色裁剪 preset 到用户预设根；返回成功安装的 preset id 列表（空=无随包组合）。
- *  尽力而为：单 preset 写失败（用户预设根不可写等）仅告警不抛出，
- *  后续 agentPresets.mount('kanban-<role>') 失败由 runner 降级日志兜底。 */
-export declare function installRolePresets(): string[];
+/** 单条 preset 组合行（官方 PresetDefinition.plugins 行的结构面：cordis entry list）。 */
+export interface PresetPluginRow {
+    readonly id?: string;
+    readonly name: string;
+    readonly config?: unknown;
+    readonly disabled?: unknown;
+}
+/** 注册给宿主 registry 的 preset 定义（官方 PresetDefinition 的结构面）。 */
+export interface PresetDefinitionLike {
+    readonly id: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly order?: number;
+    readonly plugins: readonly PresetPluginRow[];
+}
+/** 宿主 agentPresets registry 的结构面（本插件只消费 register）。 */
+export interface PresetRegistryLike {
+    register(definition: PresetDefinitionLike): Promise<() => Promise<void>>;
+}
+/** 安装期 ctx 的最小面（只需可选 get）。 */
+export interface PresetCtxLike {
+    get?(name: string): unknown;
+}
+/** 解析包内单个 preset 的组合与元数据为宿主 registry 定义；组合缺失返回 undefined。 */
+export declare function readPresetDefinition(pkgDir: string, id: string): PresetDefinitionLike | undefined;
+/** 路径二：运行时注册全部包内 preset；返回注册成功/失败 id 列表与成功项的撤销句柄（组合缺失的 id 不计）。 */
+export declare function registerRolePresets(registry: PresetRegistryLike, ids: readonly string[], pkgDir?: string): Promise<{
+    registered: string[];
+    failed: string[];
+    disposers: Array<() => Promise<void>>;
+}>;
+/** 安装结果（如实区分两条路径，不假阳性）。 */
+export interface RolePresetInstallReport {
+    /** 目录写成功的 preset id（路径一）。 */
+    dirWritten: string[];
+    /** 运行时注册成功的 preset id（路径二；服务不可用时为空）。 */
+    runtimeRegistered: string[];
+    /** 运行时注册失败的 preset id。 */
+    runtimeFailed: string[];
+    /** 路径二实际形态：runtime=已注册；unavailable=宿主无 agentPresets 服务（仅目录写生效）。 */
+    runtimeMode: 'runtime' | 'unavailable';
+}
+/**
+ * 双路安装入口。目录写同步完成并即时留痕；运行时注册等服务就绪后完成并留痕。
+ * 返回前目录写已落盘；注册部分异步收敛（fire-and-forget 调用方须 catch）。
+ */
+export declare function installRolePresets(ctx: PresetCtxLike, opts?: {
+    registerWaitMs?: number;
+}): Promise<RolePresetInstallReport>;
 /** 角色 preset 挂载的容器面（dsh-agent-presets roster 的最小结构类型）。 */
 export interface PresetMountLike {
     mount(ctx: unknown, id: string): Promise<unknown>;