agent-trellis 0.7.0 → 0.8.2

package/dist/commands/onboard.js

@@ -13,24 +13,33 @@
  * judgment is made here.
  */
 import { createInterface } from "node:readline/promises";
+import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
-import { writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { canUseInteractivePicker, runMultiSelectPicker, runSingleSelectPicker } from "../lib/terminalPicker.js";
+import { canUseInteractivePicker, runMultiSelectPicker, runSearchMultiSelectPicker, runSingleSelectPicker } from "../lib/terminalPicker.js";
 import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
-import { ALL_AGENTS } from "../core/types.js";
-import { loadCanonicalSource, removeServerYaml, upsertServerYaml, writeMcpModeYaml } from "../core/canonical.js";
+import * as kimiCodeProbe from "../probes/kimi-code.js";
+import * as zcodeProbe from "../probes/zcode.js";
+import { ALL_AGENTS, capabilityDeliveryForAgent } from "../core/types.js";
+import { loadCanonicalSource, removeServerYaml, upsertServerYaml, writeMcpModeYaml, writeMcpRoutesYaml, writeMcpRuntimeDeliveryYaml } from "../core/canonical.js";
+import { buildCapabilityInventory, parseCapabilitySelectionFile, resolveSelectedNames, selectionContains } from "../core/capabilitySelection.js";
 import { INSTALL_HINTS, collectInitReport } from "./init.js";
 import { applyMigratePlan, collectMigratePlan, printPlan as printMigratePlan } from "./migrate.js";
+import { isGatewayAgent } from "../adapters/mcpPlan.js";
+import { isInScope } from "../core/adapter.js";
+import { TRELLIS_RUNTIME_SKILL_NAME } from "../lib/builtinSkills.js";
+import { discoverNativeMemory } from "../lib/nativeMemory.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
 import { collectMcpSyncReport, printReport as printMcpSyncReport } from "./mcp.js";
 import { collectSecretsAuditReport, printReport as printSecretsAuditReport } from "./secretsAudit.js";
 import { applyMemorySync, collectMemorySyncResult, printMemorySyncResult, DEFAULT_MEMORY_SERVER_DEF, MEMORY_SERVER_NAME } from "./memory.js";
 import { collectDoctorReport, printReport as printDoctorReport, resolveKnownHostInjected } from "./doctor.js";
 import { openBackupSession } from "../lib/backup.js";
+import { applyRollbackPlan, collectRollbackPlan, loadManifest } from "./rollback.js";
 import { confirmAndInstall } from "../lib/installAgent.js";
 import { normalizeDoctorVerdict, normalizeMcpSyncVerdict, normalizeMemorySyncVerdict, normalizeMigrateVerdict, normalizeSecretsAuditVerdict, normalizeSelfVerificationVerdict, normalizeSyncVerdict, printVerdict, } from "./onboardVerdict.js";
 const PROBES = {
@@ -38,21 +47,79 @@ const PROBES = {
     codex: (homeDir) => codexProbe.probe(homeDir),
     kiro: (homeDir) => kiroProbe.probe(homeDir),
     pi: (homeDir) => piProbe.probe(homeDir),
+    "kimi-code": (homeDir) => kimiCodeProbe.probe(homeDir),
+    zcode: (homeDir) => zcodeProbe.probe(homeDir),
 };
-export async function collectOnboardSummary(homeDir = homedir()) {
+/**
+ * Scores only real source-side content. The recommendation is a hint for a
+ * first-time user, never a filter: every candidate remains selectable.
+ */
+export function migrationSourceScore(summary) {
+    return summary.skillCount + summary.mcpServerCount + (summary.hasRealInstructions ? 1 : 0);
+}
+export function recommendedMigrationSource(summaries) {
+    return summaries.reduce((best, current) => {
+        if (!best || migrationSourceScore(current) > migrationSourceScore(best))
+            return current;
+        return best;
+    }, undefined)?.agent;
+}
+export const MCP_ROUTE_OPTIONS = [
+    {
+        mode: "gateway",
+        label: "gateway（推荐：本机统一托管） — Trellis 在本机会话中运行 MCP 入口，不需要额外部署服务",
+    },
+    {
+        mode: "direct",
+        label: "direct（简单直连） — Agent 分别连接每个 MCP，适合不需要统一托管的情况",
+    },
+    {
+        mode: "hub",
+        label: "hub（已有外部 Hub 时使用） — Agent 连接一个外部 HTTP MCP 服务",
+    },
+];
+export function interactiveMcpRouteOptions(hubConfigured) {
+    return MCP_ROUTE_OPTIONS.map((option) => option.mode === "hub" && !hubConfigured
+        ? { ...option, label: "hub（暂不可选：需要先配置外部 Hub URL） — 不会自动部署 Hub", disabled: true }
+        : { ...option });
+}
+export async function collectOnboardSummary(homeDir = homedir(), workspaceDir = process.cwd()) {
     return Promise.all(ALL_AGENTS.map(async (agent) => {
         const snapshot = await PROBES[agent](homeDir);
         if (!snapshot.present) {
-            return { agent, present: false, skillCount: 0, skillNames: [], hasRealInstructions: false, mcpServerCount: 0 };
+            return { agent, present: false, skillCount: 0, skillNames: [], hasRealInstructions: false, mcpServerCount: 0, mcpServerNames: [], nativeMemoryStatus: "unsupported", nativeMemoryCount: 0, nativeMemoryNames: [], nativeMemoryDetail: "agent is not installed" };
         }
         const skillNames = snapshot.skillRoots.flatMap((root) => root.skills.map((s) => s.name));
         const hasRealInstructions = snapshot.instructionsFile !== undefined && !snapshot.instructionsFile.isSymlink;
         const mcpPlan = await collectMigratePlan(agent, homeDir, ["mcp"]);
-        return { agent, present: true, skillCount: skillNames.length, skillNames, hasRealInstructions, mcpServerCount: mcpPlan.items.length };
+        const nativeMemory = discoverNativeMemory(agent, homeDir, workspaceDir);
+        return { agent, present: true, skillCount: skillNames.length, skillNames, hasRealInstructions, mcpServerCount: mcpPlan.items.length, mcpServerNames: mcpPlan.items.map((item) => item.name), nativeMemoryStatus: nativeMemory.status, nativeMemoryCount: nativeMemory.candidates.length, nativeMemoryNames: nativeMemory.candidates.map((candidate) => candidate.displayName), nativeMemoryDetail: nativeMemory.detail };
     }));
 }
 function hasContent(s) {
-    return s.skillCount > 0 || s.hasRealInstructions || s.mcpServerCount > 0;
+    return s.skillCount > 0 || s.hasRealInstructions || s.mcpServerCount > 0 || s.nativeMemoryCount > 0;
+}
+function hasSelectedSourceContent(s, selection) {
+    if (!selection)
+        return hasContent(s);
+    const hasSkills = selection.skills !== "none" && s.skillNames.some((name) => selectionContains(selection.skills, name));
+    const hasMcp = selection.mcpServers !== "none" && s.mcpServerNames.some((name) => selectionContains(selection.mcpServers, name));
+    const hasMemory = selection.memoryMigration !== "none" && s.nativeMemoryCount > 0;
+    return hasSkills || hasMcp || hasMemory || s.hasRealInstructions;
+}
+function filterMigratePlan(plan, selection) {
+    if (!selection)
+        return plan;
+    const items = plan.items.filter((item) => {
+        if (item.kind === "skill")
+            return selectionContains(selection.skills, item.name);
+        if (item.kind === "mcp")
+            return selectionContains(selection.mcpServers, item.name);
+        if (item.kind === "memory")
+            return selection.memoryMigration !== "none";
+        return true;
+    });
+    return { ...plan, items };
 }
 const PROGRESS_STAGES = ["migrate", "sync", "mcp sync", "memory sync", "secrets audit", "doctor"];
 /** Transient status, not part of the report — printed to stderr so
@@ -74,18 +141,21 @@ function logProgress(opts, stage) {
  * (found via a real mirasim terminal session). The full names are still
  * available from `trellis doctor`/`--json`; a picker row's job is to
  * let you tell agents apart at a glance, not enumerate everything. */
-function agentSummaryLabel(s) {
-    return `${s.agent} — ${s.skillCount} skill(s), instructions: ${s.hasRealInstructions ? "yes" : "no"}, mcp: ${s.mcpServerCount}`;
+function agentSummaryLabel(s, recommendedAgent) {
+    const recommendation = s.agent === recommendedAgent ? "（推荐：可迁移内容最多）" : "";
+    const memory = s.nativeMemoryCount > 0 ? `Memory: ${s.nativeMemoryCount}` : `Memory: ${s.nativeMemoryStatus}`;
+    return `${s.agent} — Skills: ${s.skillCount}, global instructions: ${s.hasRealInstructions ? "yes" : "no"}, MCP: ${s.mcpServerCount}, ${memory} ${recommendation}`;
 }
 /** Numbered-typing fallback (trellis-onboard-interactive-picker design.md
  * D2) — used only when the terminal can't support the raw-mode picker
  * (`canUseInteractivePicker()` false). Unchanged from before that change. */
 async function promptForAgentNumbered(present) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const recommendedAgent = recommendedMigrationSource(present);
     try {
-        console.log("Multiple agents detected:");
+        console.error("检测到多个 Agent。推荐选择可迁移内容最多的 Agent 作为来源：");
         present.forEach((s, i) => {
-            console.log(`  ${i + 1}) ${agentSummaryLabel(s)}`);
+            console.error(`  ${i + 1}) ${agentSummaryLabel(s, recommendedAgent)}`);
         });
         for (let attempt = 0; attempt < 2; attempt++) {
             const answer = (await rl.question(`Choose a migration source [1-${present.length}]: `)).trim();
@@ -97,7 +167,7 @@ async function promptForAgentNumbered(present) {
                 return byIndex.agent;
             if (present.some((s) => s.agent === answer))
                 return answer;
-            console.log(`Not a valid choice: enter a number from 1-${present.length}, or one of ${present.map((s) => s.agent).join(", ")}`);
+            console.error(`Not a valid choice: enter a number from 1-${present.length}, or one of ${present.map((s) => s.agent).join(", ")}`);
         }
         throw new Error("no valid migration source chosen after 2 attempts");
     }
@@ -116,10 +186,11 @@ async function promptForAgentReal(present) {
     if (!canUseInteractivePicker()) {
         return promptForAgentNumbered(present);
     }
-    console.log("Multiple agents detected — use Up/Down (or j/k) and Enter to choose a migration source:");
-    const index = await runSingleSelectPicker(present.map(agentSummaryLabel));
+    const recommendedAgent = recommendedMigrationSource(present);
+    console.error("选择迁移来源。推荐选择可迁移内容最多的 Agent；这只决定从哪里读取，不会自动托管它：");
+    const index = await runSingleSelectPicker(present.map((summary) => agentSummaryLabel(summary, recommendedAgent)), undefined, "迁移来源");
     if (index === null) {
-        console.log("cancelled, no changes made");
+        console.error("cancelled, no changes made");
         process.exit(1);
     }
     return present[index].agent;
@@ -127,13 +198,14 @@ async function promptForAgentReal(present) {
 /** Numbered-typing fallback — unchanged from before this change (see
  * `promptForAgentNumbered`'s doc comment). */
 async function promptForManagedAgentsNumbered(candidates, alreadyManaged) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
     try {
-        console.log("Which agents should Trellis manage? (comma-separated numbers; enter for none new)");
+        console.error("选择 Trellis 要托管的 Agent（推荐选择已安装的 Agent；直接回车表示本次不新增）:");
         candidates.forEach((s, i) => {
             const status = s.present ? `present, ${s.skillCount} skill(s)` : "not installed";
             const tag = alreadyManaged.includes(s.agent) ? " [already managed]" : "";
-            console.log(`  ${i + 1}) ${s.agent} — ${status}${tag}`);
+            const recommendation = s.present ? "（推荐：已安装）" : "";
+            console.error(`  ${i + 1}) ${s.agent} — ${status}${recommendation}${tag}`);
         });
         const answer = (await rl.question("Select: ")).trim();
         return answer;
@@ -152,21 +224,23 @@ async function promptForManagedAgentsReal(candidates, alreadyManaged) {
     if (!canUseInteractivePicker()) {
         return promptForManagedAgentsNumbered(candidates, alreadyManaged);
     }
-    console.log("Which agents should Trellis manage? Up/Down (or j/k) to move, Space to toggle, Enter to confirm:");
+    console.error("选择 Trellis 要托管的 Agent。推荐选择已安装的 Agent；选择未安装的 Agent 会先请求安装确认：");
     const labels = candidates.map((s) => {
         const status = s.present ? `present, ${s.skillCount} skill(s)` : "not installed";
-        return `${s.agent} — ${status}`;
+        const recommendation = s.present ? "（推荐：已安装）" : "";
+        const managed = alreadyManaged.includes(s.agent) ? "（已托管）" : "";
+        return `${s.agent} — ${status}${recommendation}${managed}`;
     });
     const initiallyChecked = candidates.map((s) => alreadyManaged.includes(s.agent));
     const indices = await runMultiSelectPicker(labels, initiallyChecked);
     if (indices === null) {
-        console.log("cancelled, no changes made");
+        console.error("cancelled, no changes made");
         process.exit(1);
     }
     return indices.map((i) => candidates[i].agent).join(",");
 }
 /**
- * Resolves which categories (skills, instructions) to migrate from a
+ * Resolves which categories (Skills, instructions, MCP, native Memory) to migrate from a
  * resolved source (trellis-migrate-category-selection, extended to a
  * third category by trellis-onboard-mcp-memory design.md D2). Unlike the
  * two pickers above, there is no numbered-text fallback to preserve
@@ -178,17 +252,32 @@ async function promptForManagedAgentsReal(candidates, alreadyManaged) {
  * An empty result is a valid answer: "skip migrate for this run"
  * (design.md D6), left for the caller to act on.
  */
-async function resolveMigrateCategories(source, opts) {
+async function resolveMigrateCategories(source, opts, selection) {
     // Built dynamically, in skill/instructions/mcp display order — not a
-    // fixed two- or three-slot structure, so a fourth category some day
+    // fixed category structure, so future categories
     // would only need an entry here, not a rewritten branch (design.md D2).
     const candidates = [];
-    if (source.skillCount > 0)
-        candidates.push({ kind: "skill", label: "skills" });
+    if (source.skillCount > 0 && (!selection || selection.skills !== "none") && (!selection || source.skillNames.some((name) => selectionContains(selection.skills, name)))) {
+        candidates.push({ kind: "skill", label: "Skills" });
+    }
     if (source.hasRealInstructions)
-        candidates.push({ kind: "instructions", label: "instructions" });
-    if (source.mcpServerCount > 0)
-        candidates.push({ kind: "mcp", label: "mcp" });
+        candidates.push({ kind: "instructions", label: "global instructions" });
+    if (source.mcpServerCount > 0 && (!selection || selection.mcpServers !== "none") && (!selection || source.mcpServerNames.some((name) => selectionContains(selection.mcpServers, name)))) {
+        candidates.push({ kind: "mcp", label: "MCP servers" });
+    }
+    let migrateMemory = source.nativeMemoryCount > 0 && opts.memoryMigrate !== "off" && (!selection || selection.memoryMigration !== "none");
+    if (migrateMemory && opts.memoryMigrate === undefined && !opts.selectionFile && !opts.json && (opts.promptForMemoryMigration || canUseInteractivePicker())) {
+        const choice = opts.promptForMemoryMigration
+            ? await opts.promptForMemoryMigration(source.agent, source.nativeMemoryCount)
+            : await runSingleSelectPicker([
+                `迁移支持的记忆（推荐：${source.nativeMemoryCount} 项）`,
+                "暂不迁移记忆",
+            ], undefined, `选择是否从 ${source.agent} 迁移已有记忆`);
+        if (choice === null || choice === "off" || choice === 1)
+            migrateMemory = false;
+    }
+    if (migrateMemory)
+        candidates.push({ kind: "memory", label: `Memory（${source.nativeMemoryCount} 项）` });
     // The choice is only meaningful when two or more kinds are real — same
     // gate for the injected test seam as for the real picker, mirroring
     // how `promptForAgent`/`promptForManagedAgents` are only ever
@@ -198,10 +287,10 @@ async function resolveMigrateCategories(source, opts) {
             return opts.promptForMigrateCategories(source);
         }
         if (canUseInteractivePicker()) {
-            console.log(`Which categories should be migrated from ${source.agent}? Space to toggle, Enter to confirm:`);
-            const indices = await runMultiSelectPicker(candidates.map((c) => c.label), candidates.map(() => true));
+            console.error(`选择要从 ${source.agent} 迁移的内容（默认全选，推荐先完整迁移，之后再清理不需要的项）：`);
+            const indices = await runMultiSelectPicker(candidates.map((c) => `${c.label}（推荐迁移）`), candidates.map(() => true), undefined, "迁移内容");
             if (indices === null) {
-                console.log("cancelled, no changes made");
+                console.error("cancelled, no changes made");
                 process.exit(1);
             }
             return indices.map((i) => candidates[i].kind);
@@ -209,6 +298,75 @@ async function resolveMigrateCategories(source, opts) {
     }
     return candidates.map((c) => c.kind);
 }
+async function resolveInteractiveCapabilitySelection(source, opts) {
+    if (opts.json || opts.promptForMigrateCategories || !canUseInteractivePicker())
+        return undefined;
+    const skills = source.skillNames.length > 0
+        ? await runSearchMultiSelectPicker(source.skillNames, undefined, "选择要迁移的 Skills（默认全选，推荐先全部保留）")
+        : [];
+    if (skills === null) {
+        console.error("cancelled, no changes made");
+        process.exit(1);
+    }
+    const mcpServers = source.mcpServerNames.length > 0
+        ? await runSearchMultiSelectPicker(source.mcpServerNames, undefined, "选择要迁移的 MCP（默认全选，推荐先全部保留）")
+        : [];
+    if (mcpServers === null) {
+        console.error("cancelled, no changes made");
+        process.exit(1);
+    }
+    return { skills: skills ?? "none", mcpServers: mcpServers ?? "none", memories: "all", memoryMigration: "all", mcpRoutes: {}, runtimeDelivery: {} };
+}
+async function resolveInteractiveMemoryChoice(homeDir, opts) {
+    if (opts.memory !== undefined || opts.selectionFile || opts.json)
+        return undefined;
+    const current = loadCanonicalSource(homeDir).mcp.servers[MEMORY_SERVER_NAME] ? "on" : "off";
+    const canPrompt = Boolean(opts.promptForMemory) || (opts.isTTY ?? process.stdin.isTTY === true) && canUseInteractivePicker();
+    if (!canPrompt)
+        return undefined;
+    const choice = opts.promptForMemory
+        ? await opts.promptForMemory(current)
+        : (() => {
+            const options = current === "on"
+                ? ["保持开启（推荐：继续使用共享 Memory）", "关闭共享 Memory"]
+                : ["保持关闭（推荐：不改变现有环境）", "启用共享 Memory（推荐：Kimi/Pi 共享同一 graph）"];
+            return runSingleSelectPicker(options, undefined, "选择 Trellis Memory 托管方式").then((index) => {
+                if (index === null) {
+                    console.error("cancelled, no changes made");
+                    process.exit(1);
+                }
+                if (index === 0)
+                    return "keep";
+                return current === "on" ? "off" : "on";
+            });
+        })();
+    if (choice === "on" || choice === "off")
+        return choice;
+    return undefined;
+}
+async function resolveInteractiveMcpRoutes(agentIds, serverNames, hubConfigured) {
+    const routes = {};
+    for (const agent of agentIds) {
+        const options = interactiveMcpRouteOptions(hubConfigured);
+        const modeIndex = await runSingleSelectPicker(options, undefined, `选择 ${agent} 的 MCP 模式（推荐 Gateway：Trellis 本机统一托管；Hub 只用于已有外部服务）`);
+        if (modeIndex === null) {
+            console.error("cancelled, no changes made");
+            process.exit(1);
+        }
+        const mode = options[modeIndex].mode;
+        if (mode === "hub") {
+            routes[agent] = { mode };
+            continue;
+        }
+        const selected = await runSearchMultiSelectPicker(serverNames, undefined, `选择 ${agent} 的 MCP 服务器（默认全选，推荐先全部启用）`);
+        if (selected === null) {
+            console.error("cancelled, no changes made");
+            process.exit(1);
+        }
+        routes[agent] = { mode, servers: selected ?? [] };
+    }
+    return routes;
+}
 /** Shared by `--manage` and the interactive prompt's answer — same
  * grammar either way (design.md D4): a real agent id list, comma- or
  * whitespace-separated numbers referring to `candidates`' own order, or
@@ -300,6 +458,38 @@ function validateMemoryOption(memory) {
         return { error: `--memory must be "on" or "off" (got "${memory}")` };
     return { value: memory };
 }
+function validateMemoryMigrationOption(memoryMigrate) {
+    if (memoryMigrate === undefined)
+        return {};
+    if (memoryMigrate !== "on" && memoryMigrate !== "off")
+        return { error: `--memory-migrate must be "on" or "off" (got "${memoryMigrate}")` };
+    return { value: memoryMigrate };
+}
+function preflightMcpMode(mode) {
+    if (!mode)
+        return undefined;
+    if (mode.kind === "hub") {
+        try {
+            const parsed = new URL(mode.url);
+            if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+                return `Hub URL must use http:// or https:// (got "${mode.url}")`;
+            }
+        }
+        catch {
+            return `Hub URL is not valid: "${mode.url}"`;
+        }
+        return undefined;
+    }
+    if (mode.kind === "gateway") {
+        try {
+            execFileSync("which", ["trellis"], { stdio: "ignore" });
+        }
+        catch {
+            return "gateway mode requires the `trellis` executable to be available on PATH before any Agent config is changed";
+        }
+    }
+    return undefined;
+}
 function mcpModeValueOf(mcp) {
     if (mcp.gateway?.enabled)
         return "gateway";
@@ -348,6 +538,49 @@ function memoryStatusLine(memory) {
         return `memory: ${memory.current} (unchanged) — pass --memory ${memory.current === "on" ? "off" : "on"} to change`;
     return `memory: ${memory.current} (changed from ${memory.previous})`;
 }
+/** Converges explicit per-Agent route lists with the shared Memory toggle.
+ * Legacy/top-level routes without a `servers` list already expose every
+ * eligible server and need no rewrite. Hub routes are intentionally opaque:
+ * the external hub owns its upstream set. */
+export function mergeMemoryIntoExplicitRoutes(mcp, managedAgents, memoryEnabled) {
+    const routes = mcp.routes;
+    if (!routes)
+        return { mcp, changed: false };
+    const memoryServer = mcp.servers[MEMORY_SERVER_NAME];
+    const changedRoutes = { ...routes };
+    let changed = false;
+    for (const agent of managedAgents) {
+        const route = routes[agent];
+        if (!route || route.mode === "hub" || !route.servers)
+            continue;
+        const inScope = Boolean(memoryServer && memoryServer.enabled !== false && isInScope(agent, memoryServer.agents, managedAgents));
+        const nextServers = memoryEnabled && inScope
+            ? [...route.servers, ...(route.servers.includes(MEMORY_SERVER_NAME) ? [] : [MEMORY_SERVER_NAME])]
+            : route.servers.filter((name) => name !== MEMORY_SERVER_NAME);
+        if (nextServers.length === route.servers.length && nextServers.every((name, index) => name === route.servers[index]))
+            continue;
+        changedRoutes[agent] = { ...route, servers: nextServers };
+        changed = true;
+    }
+    return changed ? { mcp: { ...mcp, routes: changedRoutes }, changed } : { mcp, changed: false };
+}
+async function confirmMcpModeChange(previous, next, agents, opts) {
+    if (opts.promptForModeChange)
+        return opts.promptForModeChange(previous, next, agents);
+    if (!canUseInteractivePicker())
+        return true;
+    const affected = agents.length > 0 ? agents.join(", ") : "(none)";
+    console.error(`MCP 模式将从 ${previous} 切换到 ${next}，影响托管 Agent：${affected}`);
+    if (next === "hub")
+        console.error("Hub 模式会让 Agent 连接外部 HTTP MCP 服务；Trellis 不会自动部署该服务。");
+    if (next === "gateway")
+        console.error("Gateway 模式会由 Trellis 在本机运行 MCP 入口并托管上游连接。");
+    const choice = await runSingleSelectPicker([
+        "取消切换（推荐：保持当前模式）",
+        "确认切换",
+    ], undefined, "确认 MCP 模式切换");
+    return choice === 1;
+}
 async function resolveManagedAgents(opts, summary, alreadyManaged) {
     if (opts.manage !== undefined) {
         const parsed = parseManagedSelection(opts.manage, summary);
@@ -369,13 +602,35 @@ async function resolveManagedAgents(opts, summary, alreadyManaged) {
 function readManagedYaml(homeDir) {
     return loadCanonicalSource(homeDir).managedAgents;
 }
-function writeManagedYaml(homeDir, agents) {
-    writeFileSync(join(homeDir, ".trellis", "managed.yaml"), `agents: [${agents.join(", ")}]\n`);
+function writeManagedYaml(homeDir, agents, backup) {
+    const content = `agents: [${agents.join(", ")}]\n`;
+    const path = join(homeDir, ".trellis", "managed.yaml");
+    if (existsSync(path) && readFileSync(path, "utf-8") === content)
+        return;
+    if (backup)
+        backup.writeFile(path, content);
+    else
+        writeFileSync(path, content);
 }
 export async function collectOnboardPlan(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    await collectInitReport(homeDir);
-    const summary = await collectOnboardSummary(homeDir);
+    if (opts.dryRun && !existsSync(join(homeDir, ".trellis"))) {
+        return {
+            summary: [],
+            refusal: "dry-run does not bootstrap a missing ~/.trellis — run `trellis init` first, then re-run the preview",
+            verdict: [],
+        };
+    }
+    let capabilitySelection;
+    if (opts.selectionFile) {
+        const parsedSelection = parseCapabilitySelectionFile(opts.selectionFile);
+        if (!parsedSelection.ok)
+            return { summary: [], refusal: parsedSelection.error, verdict: [] };
+        capabilitySelection = parsedSelection.selection;
+    }
+    await collectInitReport(homeDir, { write: !opts.dryRun });
+    const workspaceDir = opts.workspaceDir ?? process.cwd();
+    const summary = await collectOnboardSummary(homeDir, workspaceDir);
     const present = summary.filter((s) => s.present);
     if (present.length === 0) {
         return { summary, installHints: { ...INSTALL_HINTS }, verdict: [] };
@@ -390,11 +645,19 @@ export async function collectOnboardPlan(opts = {}) {
     if ("error" in mcpModeValidation) {
         return { summary, refusal: mcpModeValidation.error, verdict: [] };
     }
-    const memoryValidation = validateMemoryOption(opts.memory);
-    if ("error" in memoryValidation) {
-        return { summary, refusal: memoryValidation.error, verdict: [] };
+    const explicitMemoryValidation = validateMemoryOption(opts.memory);
+    if ("error" in explicitMemoryValidation) {
+        return { summary, refusal: explicitMemoryValidation.error, verdict: [] };
+    }
+    const explicitMemoryMigrationValidation = validateMemoryMigrationOption(opts.memoryMigrate);
+    if ("error" in explicitMemoryMigrationValidation) {
+        return { summary, refusal: explicitMemoryMigrationValidation.error, verdict: [] };
     }
-    const sourceCandidates = present.filter(hasContent);
+    const modePreflightError = preflightMcpMode(mcpModeValidation.mode);
+    if (modePreflightError) {
+        return { summary, refusal: modePreflightError, verdict: [] };
+    }
+    const sourceCandidates = present.filter((candidate) => hasSelectedSourceContent(candidate, capabilitySelection));
     let source;
     let sourceReason;
     if (opts.agent) {
@@ -470,35 +733,65 @@ export async function collectOnboardPlan(opts = {}) {
         // managed set, not an abort of the rest of the flow.
     }
     const managedAgents = [...new Set([...alreadyManaged, ...resolvedNew])];
-    if (!opts.dryRun) {
-        writeManagedYaml(homeDir, managedAgents);
-    }
-    // MCP mode + memory-server resolution (design.md D5/D11) — grouped
-    // with managed-set above as "how is this machine configured"
-    // decisions resolved once per run, ahead of migrate/sync/mcp-sync/
-    // memory-sync below, which act on the result. Both flags were already
-    // validated before managed-set was even touched; omitting either
-    // resolves to "no change requested" here too (design.md D1/D12) — no
-    // writer call at all, on either a first run or a later one.
+    // Resolve all mode/memory decisions before opening the transaction. A
+    // refusal here must leave both canonical and managed state untouched.
     const canonicalForModeAndMemory = loadCanonicalSource(homeDir);
+    const interactiveMemory = await resolveInteractiveMemoryChoice(homeDir, opts);
+    const memoryValue = explicitMemoryValidation.value ?? interactiveMemory;
+    const memoryValidation = { value: memoryValue };
+    const sourceSummaryForInventory = source ? summary.find((item) => item.agent === source) : undefined;
+    const nativeMemory = sourceSummaryForInventory && sourceSummaryForInventory.nativeMemoryStatus !== "supported"
+        ? [{ name: `${source}:native`, detail: sourceSummaryForInventory.nativeMemoryDetail }]
+        : [];
+    const inventory = sourceSummaryForInventory
+        ? buildCapabilityInventory(sourceSummaryForInventory, canonicalForModeAndMemory, nativeMemory)
+        : undefined;
+    const capabilitySummary = {
+        awarenessSkill: canonicalForModeAndMemory.skills.some((skill) => skill.name === TRELLIS_RUNTIME_SKILL_NAME),
+        globalInstructions: { available: existsSync(canonicalForModeAndMemory.instructionsFile), native: true, runtimeReadable: true },
+        skills: canonicalForModeAndMemory.skills.length,
+        memories: canonicalForModeAndMemory.memories.length,
+        mcpServers: Object.keys(canonicalForModeAndMemory.mcp.servers).length,
+    };
+    const managedAgentRuntime = managedAgents.map((agent) => ({
+        agent,
+        delivery: capabilityDeliveryForAgent(agent, canonicalForModeAndMemory.mcp),
+        route: canonicalForModeAndMemory.mcp.routes?.[agent]?.mode
+            ?? (isGatewayAgent(agent, canonicalForModeAndMemory.mcp, managedAgents) ? "gateway" : canonicalForModeAndMemory.mcp.hub ? "hub" : "direct"),
+    }));
     const mcpModeResolution = resolveMcpModeChange(mcpModeValidation.mode, mcpModeValueOf(canonicalForModeAndMemory.mcp));
     const mcpMode = { current: mcpModeResolution.current, previous: mcpModeResolution.previous, changed: mcpModeResolution.changed };
     const serversYamlPath = join(homeDir, ".trellis", "mcp", "servers.yaml");
-    if (mcpModeResolution.write && !opts.dryRun) {
-        writeMcpModeYaml(serversYamlPath, mcpModeResolution.write);
-    }
     const memoryConfiguredBefore = canonicalForModeAndMemory.mcp.servers[MEMORY_SERVER_NAME] !== undefined;
     const memoryResolution = resolveMemoryToggle(memoryValidation.value, memoryConfiguredBefore, canonicalForModeAndMemory.mcp.knownHostInjected);
     if ("refusal" in memoryResolution) {
         return { summary, source, sourceReason, managedAgents, mcpMode, refusal: memoryResolution.refusal, verdict: [] };
     }
     const memory = { current: memoryResolution.current, previous: memoryResolution.previous, changed: memoryResolution.changed };
+    if (!opts.dryRun
+        && !opts.json
+        && mcpMode.changed
+        && (opts.isTTY ?? process.stdin.isTTY === true)
+        && (opts.promptForModeChange || canUseInteractivePicker())) {
+        const accepted = await confirmMcpModeChange(mcpMode.previous, mcpMode.current, managedAgents, opts);
+        if (!accepted)
+            return { summary, source, sourceReason, managedAgents, mcpMode, memory, refusal: "MCP mode change cancelled — current mode was preserved", verdict: [] };
+    }
+    // One transaction for the entire onboarding run, including canonical
+    // state. A dry run opens no session and a no-op session creates no backup.
+    const backupSession = opts.dryRun ? undefined : openBackupSession(homeDir, "onboard");
+    if (!opts.dryRun) {
+        writeManagedYaml(homeDir, managedAgents, backupSession);
+    }
+    if (mcpModeResolution.write && !opts.dryRun) {
+        writeMcpModeYaml(serversYamlPath, mcpModeResolution.write, backupSession);
+    }
     if (memory.changed && !opts.dryRun) {
         if (memory.current === "on") {
-            upsertServerYaml(serversYamlPath, MEMORY_SERVER_NAME, DEFAULT_MEMORY_SERVER_DEF);
+            upsertServerYaml(serversYamlPath, MEMORY_SERVER_NAME, DEFAULT_MEMORY_SERVER_DEF, backupSession);
         }
         else {
-            removeServerYaml(serversYamlPath, MEMORY_SERVER_NAME);
+            removeServerYaml(serversYamlPath, MEMORY_SERVER_NAME, backupSession);
         }
     }
     let migratePlan;
@@ -506,22 +799,87 @@ export async function collectOnboardPlan(opts = {}) {
     logProgress(opts, "migrate");
     if (source) {
         const sourceSummary = summary.find((s) => s.agent === source);
-        const categories = await resolveMigrateCategories(sourceSummary, opts);
+        const interactiveSelection = capabilitySelection ?? await resolveInteractiveCapabilitySelection(sourceSummary, opts);
+        const categories = await resolveMigrateCategories(sourceSummary, opts, interactiveSelection);
         if (categories.length > 0) {
-            migratePlan = await collectMigratePlan(source, homeDir, categories);
+            migratePlan = filterMigratePlan(await collectMigratePlan(source, homeDir, categories, workspaceDir), interactiveSelection);
             if (!opts.dryRun) {
-                applyMigratePlan(migratePlan, homeDir);
+                applyMigratePlan(migratePlan, homeDir, backupSession);
             }
         }
         else {
             migrateSkipped = "migrate skipped — no categories selected";
         }
     }
-    // One session for the whole chained run (trellis-backup-rollback) —
-    // `--dry-run` opens none, there's nothing either stage will write.
-    // Neither collectSyncReport nor collectMcpSyncReport finalizes a
-    // session they were handed; only this caller does, once, after both.
-    const backupSession = opts.dryRun ? undefined : openBackupSession(homeDir, "onboard");
+    const currentMcpAfterMigration = loadCanonicalSource(homeDir).mcp;
+    const migratedMcpNames = migratePlan?.items.filter((item) => item.kind === "mcp").map((item) => item.name) ?? [];
+    const availableMcpNames = [...new Set([...Object.keys(currentMcpAfterMigration.servers), ...migratedMcpNames])];
+    let requestedRoutes = capabilitySelection?.mcpRoutes;
+    const shouldPromptForRoutes = !opts.selectionFile
+        && opts.mcpMode === undefined
+        && !currentMcpAfterMigration.routes
+        && !currentMcpAfterMigration.gateway
+        && !currentMcpAfterMigration.hub
+        && managedAgents.length > 0
+        && availableMcpNames.length > 0
+        && canUseInteractivePicker();
+    if (!requestedRoutes && shouldPromptForRoutes) {
+        requestedRoutes = await resolveInteractiveMcpRoutes(managedAgents, availableMcpNames, currentMcpAfterMigration.hub !== undefined);
+    }
+    // ZCode's generic ~/.agents/skills discovery bypasses Trellis scope. Its
+    // default is therefore Runtime-first unless a capability-selection file
+    // explicitly chooses native/both, or canonical already has a choice.
+    const zcodeRuntimeRecommendation = managedAgents.includes("zcode") && currentMcpAfterMigration.runtime?.delivery?.zcode === undefined
+        ? { zcode: "mcp" }
+        : {};
+    const requestedRuntimeDelivery = {
+        ...zcodeRuntimeRecommendation,
+        ...(capabilitySelection?.runtimeDelivery ?? {}),
+    };
+    let mcpSyncOverride;
+    if ((requestedRoutes && Object.keys(requestedRoutes).length > 0) || Object.keys(requestedRuntimeDelivery).length > 0) {
+        const currentMcp = currentMcpAfterMigration;
+        const routes = requestedRoutes && Object.keys(requestedRoutes).length > 0
+            ? { ...(currentMcp.routes ?? {}), ...requestedRoutes }
+            : currentMcp.routes;
+        const delivery = Object.keys(requestedRuntimeDelivery).length > 0
+            ? { ...(currentMcp.runtime?.delivery ?? {}), ...requestedRuntimeDelivery }
+            : currentMcp.runtime?.delivery;
+        mcpSyncOverride = {
+            ...currentMcp,
+            ...(routes ? { routes } : {}),
+            ...(delivery ? { runtime: { ...(currentMcp.runtime ?? {}), delivery } } : {}),
+        };
+        if (!opts.dryRun && requestedRoutes && Object.keys(requestedRoutes).length > 0) {
+            writeMcpRoutesYaml(join(homeDir, ".trellis", "mcp", "servers.yaml"), routes ?? {}, backupSession);
+        }
+        if (!opts.dryRun && Object.keys(requestedRuntimeDelivery).length > 0) {
+            writeMcpRuntimeDeliveryYaml(join(homeDir, ".trellis", "mcp", "servers.yaml"), delivery ?? {}, backupSession);
+        }
+    }
+    // Dry-run must plan the Memory server that this transaction would write;
+    // otherwise the following mcp-sync/memory-sync stages would inspect the
+    // pre-run canonical file and falsely report an unconfigured backend. The
+    // effective view is never persisted here — real writes above still use the
+    // normal backup transaction.
+    const effectiveMcpForRun = {
+        ...(mcpSyncOverride ?? currentMcpAfterMigration),
+        servers: { ...(mcpSyncOverride ?? currentMcpAfterMigration).servers },
+    };
+    if (memory.current === "on") {
+        effectiveMcpForRun.servers[MEMORY_SERVER_NAME] = effectiveMcpForRun.servers[MEMORY_SERVER_NAME] ?? DEFAULT_MEMORY_SERVER_DEF;
+    }
+    else {
+        delete effectiveMcpForRun.servers[MEMORY_SERVER_NAME];
+    }
+    const mergedMemoryRoutes = mergeMemoryIntoExplicitRoutes(effectiveMcpForRun, managedAgents, memory.current === "on");
+    const effectiveMcpWithRoutes = mergedMemoryRoutes.mcp;
+    if (mergedMemoryRoutes.changed && !opts.dryRun && effectiveMcpWithRoutes.routes) {
+        writeMcpRoutesYaml(serversYamlPath, effectiveMcpWithRoutes.routes, backupSession);
+    }
+    // The same session now covers canonical and native writes. Neither
+    // collectSyncReport nor collectMcpSyncReport finalizes it; this caller
+    // finalizes once after every verification stage has completed.
     logProgress(opts, "sync");
     const syncReport = await collectSyncReport({ homeDir, dryRun: opts.dryRun, managedAgents, backupSession });
     // The self-verification re-plan (design.md D2b): immediately after a
@@ -533,18 +891,18 @@ export async function collectOnboardPlan(opts = {}) {
     // written, so there is nothing to verify.
     const syncVerification = opts.dryRun ? undefined : await collectSyncReport({ homeDir, dryRun: true, managedAgents });
     logProgress(opts, "mcp sync");
-    const mcpSyncReport = await collectMcpSyncReport({ homeDir, dryRun: opts.dryRun, managedAgents, backupSession });
+    const mcpSyncReport = await collectMcpSyncReport({ homeDir, dryRun: opts.dryRun, managedAgents, backupSession, mcp: effectiveMcpWithRoutes });
     const mcpSyncVerification = opts.dryRun ? undefined : await collectMcpSyncReport({ homeDir, dryRun: true, managedAgents });
-    backupSession?.finalize();
     // Independent of `managedAgents` — the shared memory server is not
     // per-agent (design.md D4, trellis-onboard-mcp-memory), unlike
     // sync/mcp-sync above. Runs unconditionally once reached; an
     // unconfigured `memory` server is a legitimate "nothing to do yet"
     // state (design.md D5), not gated on any prior step here.
     logProgress(opts, "memory sync");
-    const memorySyncResult = collectMemorySyncResult(homeDir);
+    const selectedMemoryNames = capabilitySelection ? resolveSelectedNames(capabilitySelection.memories, loadCanonicalSource(homeDir).memories.map((memory) => memory.name)) : undefined;
+    const memorySyncResult = collectMemorySyncResult(homeDir, selectedMemoryNames, effectiveMcpWithRoutes);
     if (!opts.dryRun) {
-        applyMemorySync(memorySyncResult);
+        applyMemorySync(memorySyncResult, backupSession);
     }
     // Read-only, no dryRun concept — same report either way, run last since
     // it audits the config mcp sync just wrote (or, on --dry-run, whatever
@@ -572,8 +930,27 @@ export async function collectOnboardPlan(opts = {}) {
         ...normalizeSecretsAuditVerdict(secretsAuditReport),
         ...normalizeDoctorVerdict(doctorReport, managedAgents),
     ];
+    let rollback;
+    if (!opts.dryRun && backupSession?.hasOperations()) {
+        backupSession.finalize();
+        // Doctor intentionally scans the whole machine, including unmanaged
+        // Agents and pre-existing cross-agent drift. It is informative health
+        // state, not proof that this transaction failed. Roll back only stages
+        // whose writes/on-write verification belong to this onboard run.
+        const transactionBlocked = verdict.some((item) => item.severity === "blocked" && !item.stage.startsWith("doctor"));
+        if (transactionBlocked) {
+            rollback = await collectRollbackPlan(homeDir, backupSession.runId);
+            await applyRollbackPlan(homeDir, rollback.runId, loadManifest(homeDir, rollback.runId), rollback.items);
+        }
+    }
+    else {
+        backupSession?.finalize();
+    }
     return {
         summary,
+        inventory,
+        capabilitySummary,
+        managedAgentRuntime,
         source,
         sourceReason,
         managedAgents,
@@ -587,6 +964,7 @@ export async function collectOnboardPlan(opts = {}) {
         memorySyncResult,
         secretsAuditReport,
         doctorReport,
+        rollback,
         mcpMode,
         memory,
         verdict,
@@ -604,8 +982,11 @@ async function offerToApply(opts) {
         return opts.promptToApply();
     if (!canUseInteractivePicker())
         return false;
-    console.log("");
-    const choice = await runSingleSelectPicker(["No, don't apply", "Yes, apply now"]);
+    console.error("");
+    const choice = await runSingleSelectPicker([
+        "暂不应用（推荐：先检查上面的预览）",
+        "立即应用",
+    ], undefined, "预览已完成，是否写入配置？");
     return choice === 1;
 }
 export async function runOnboard(opts = {}) {
@@ -679,6 +1060,13 @@ function printResult(result, dryRun, showStatusLine) {
                 : `${install.agent} has no npm package to install (see \`trellis init\`'s install hint) — left out of this run's managed set.`);
     }
     console.log(`Managed agents: ${result.managedAgents && result.managedAgents.length > 0 ? result.managedAgents.join(", ") : "(none)"}`);
+    if (showStatusLine && result.managedAgentRuntime?.length) {
+        console.log(`Agent delivery: ${result.managedAgentRuntime.map((item) => `${item.agent}=${item.delivery}/${item.route}`).join(", ")}`);
+    }
+    if (showStatusLine && result.capabilitySummary) {
+        const summary = result.capabilitySummary;
+        console.log(`Trellis capabilities: awareness=${summary.awarenessSkill ? "ready" : "missing"}, global instructions=${summary.globalInstructions.native ? "native" : "unavailable"} + Runtime read, Skills=${summary.skills}, Memory=${summary.memories}, MCP=${summary.mcpServers}`);
+    }
     // Informational only, never a prompt (design.md D6/D12,
     // trellis-onboard-mcp-mode) — this is what keeps `--mcp-mode`/
     // `--memory` discoverable without costing every run a keystroke.
@@ -686,6 +1074,10 @@ function printResult(result, dryRun, showStatusLine) {
     // already uses.
     if (showStatusLine && result.mcpMode) {
         console.log(mcpModeStatusLine(result.mcpMode));
+        if (result.mcpMode.changed) {
+            const affected = result.managedAgents && result.managedAgents.length > 0 ? result.managedAgents.join(", ") : "(none)";
+            console.log(`mode transition impact: ${result.mcpMode.previous} → ${result.mcpMode.current}; managed agents: ${affected}`);
+        }
     }
     if (showStatusLine && result.memory) {
         console.log(memoryStatusLine(result.memory));
@@ -725,4 +1117,10 @@ function printResult(result, dryRun, showStatusLine) {
         console.log("\nhealth scan (trellis doctor)");
         printDoctorReport(result.doctorReport);
     }
+    if (result.rollback) {
+        console.log("\nautomatic rollback");
+        const restored = result.rollback.items.filter((item) => item.action === "restore").length;
+        const conflicts = result.rollback.items.filter((item) => item.action === "conflict").length;
+        console.log(`↩️  restored ${restored} path(s), ${conflicts} rollback conflict(s); backup: ${result.rollback.runId}`);
+    }
 }