toolhome 0.6.12 → 0.6.15

package/README.md

@@ -64,7 +64,7 @@ The per-server entry proxies losslessly; the aggregate virtualizes conflicting n
 
 Downstream 2026 requests stay stateless; 2025-era clients use a persistent session bound to the authenticated principal, preserving initialize capability declarations and bidirectional request semantics. Parts of the Final Tasks extension not yet registered by SDK 2.0 are filled in by an isolated compatibility layer that still speaks the official `tasks/*` wire contract.
 
-Aggregate capability lists retain results from healthy upstreams when another upstream fails. Partial responses identify failed server slugs in `_meta["toolhome/failed-servers"]`; when every eligible upstream fails, the list returns a protocol error. Cancelling a client request preserves upstream runtime status. Individual endpoints report their own upstream errors.
+Aggregate capability lists serve an upstream from its last known good snapshot when its live list fails, so a transient upstream failure never changes the catalog between pages and client continuation cursors stay valid. Those upstreams are named in `_meta["toolhome/stale-servers"]`; a live list result always wins over the snapshot. An upstream that has never listed the surface and cannot list it now is reported in `_meta["toolhome/failed-servers"]`, and when no upstream can supply any list data the list returns a protocol error. Cancelling a client request preserves upstream runtime status. Individual endpoints report their own upstream errors.
 
 Aggregated tool names use `{server_slug}_{encoded_upstream_name}`. UTF-8 bytes outside ASCII letters and digits are encoded as `-hh` (hex), so `github.search_code` becomes `github_search-5fcode`. Long names are shortened with a stable hash. Prompts retain `{server_slug}.{upstream_name}`. Unknown extension methods use `toolhome/{server_slug}/{upstream_method}` on the aggregate and pass through untouched on per-server entries. MCP Apps that use original tool names are routed by App resource context or globally unique names; use a per-server entry when names collide.
 
@@ -196,6 +196,8 @@ Discovery reads only definitions already stored on the entry: `search` makes no
 
 **Local scope.** Node-placed servers still run only on their owning machine, and the local compact catalog covers only servers placed on that node. At startup the local entry mirrors the control plane's tool visibility; if a server's projection cannot be read it stays out of the compact catalog (fail closed) until the next start or explicit refresh. Changing visibility on the control plane requires the local entry to reconnect before it takes effect.
 
+**Node label.** `toolhome mcp stdio` binds its local mirror to the node label from `--node` or `nodeId` in the CLI config, falling back to the hostname. Keep that label stable: `auth login` preserves it, and a mirror opened under a different label reports the label it belongs to instead of failing with a bare key error.
+
 **Roll back to full.** Set `TOOLHOME_MCP_TOOL_MODE=full` (or remove it) on the host, or drop `--tool-mode` from `toolhome mcp stdio`, then reconnect the client. No data migration is needed: full mode clears any compact-mirrored visibility rows so every enabled tool is exposed again.
 
 **Keep one discovery layer.** Do not nest ToolHome compact behind an upstream that already performs its own search/exec or Code Mode. Pick either ToolHome `full`/individual endpoints or the upstream's full tool list. For Cloudflare API MCP, opt out explicitly yourself with its documented `?codemode=false` URL; ToolHome never rewrites upstream URLs or query parameters, and `truncateToolResult` is a separate switch that is never changed for you.
@@ -275,6 +277,27 @@ npm run cli -- config import backup.json
 
 Backups contain plaintext secrets and deserve the same protection as the master key. `--include-secrets` requires an explicit output file to avoid leaking secrets into terminal logs, and the CLI forces `0600` after writing. Omit it for routine review.
 
+An export covers both planes — MCP servers with their placement, hosted CLIs with their runtime and allow-list, encrypted credentials, and Market provenance. `config import --mode merge` makes a restore idempotent: credentials are reused by name, records the target already holds are skipped, and `--upsert` updates them field by field. `--dry-run` shows the same per-item report without writing, and `create` (the default) still aborts on a conflict and names every clash.
+
+## Migration
+
+`toolhome migrate` copies an instance into another one — handy when a laptop instance graduates to a cloud host:
+
+```bash
+npm run cli -- migrate --to https://cloud.example.com --to-key "$TOOLHOME_CONTROL_KEY" --dry-run
+npm run cli -- migrate --to https://cloud.example.com --to-key "$TOOLHOME_CONTROL_KEY" \
+  --with-state --issue-access-key cloud
+```
+
+The order is deliberate. Market entries are reinstalled on the target first, at their pinned versions, with values harvested from the exported credentials, so the target keeps its own installation records and version tracking. The configuration import then runs in merge mode and leaves what the Market provisioned alone.
+
+Two things cannot cross on their own, and the command reports both rather than pretending otherwise:
+
+- **Access keys** are stored as digests only. Re-issue one on the target (`--issue-access-key <name>` does it and prints the harness snippet).
+- **Hosted CLI logins** live in each product's own place — `gh` in the macOS keychain, `az` in a token cache inside its state volume. `--with-state` moves the volumes; `toolhome cli adopt <slug>` extracts a local login with the CLI's own command and writes it into the target's volume. `toolhome cli sync` walks every installed entry.
+
+Binaries are not part of a migration and do not need to be: a macOS `gh` is a Mach-O binary while the gateway runs Alpine Linux, so the target rebuilds its own pinned artifact from the catalog. Per-entry outcomes are one of `adopted`, `already-authenticated`, `credential-only` (values travel with the export), `manual` (the entry names the command to run on the target), or `failed`.
+
 ## Configuration
 
 | Environment variable             | Description                                                                   | Default                 |

package/README.zh.md

@@ -64,7 +64,7 @@ ToolHome 有两个一等平面：
 
 下游 2026 请求保持无状态；2025-era 使用与认证 principal 绑定的持久 Session，保留 initialize 能力声明和双向请求语义。最终 Tasks extension 在 SDK 2.0 尚未注册的部分由隔离兼容层补齐，对外仍是官方 `tasks/*` wire contract。
 
-聚合能力列表在部分上游失败时保留健康上游的结果，并在 `_meta["toolhome/failed-servers"]` 中列出失败的服务器 slug。所有具备相应能力的上游均失败时，列表返回协议错误。客户端取消请求时保持上游运行状态。独立入口返回自身上游的错误。
+聚合能力列表在某个上游实时列举失败时改用该 Server 上次成功发现的快照，因此瞬时上游失败不会改变分页期间的目录组成，客户端的续页游标保持有效。这些上游会出现在 `_meta["toolhome/stale-servers"]` 中；实时列举结果始终优先于快照。从未成功列举过该能力、现在又失败的 Server 会出现在 `_meta["toolhome/failed-servers"]` 中；当没有任何上游能提供列表数据时，列表返回协议错误。客户端取消请求时保持上游运行状态。独立入口返回自身上游的错误。
 
 聚合工具名为 `{server_slug}_{encoded_upstream_name}`，上游名称中除 ASCII 字母与数字外的 UTF-8 字节编码为 `-hh`（十六进制），例如 `github.search_code` 映射为 `github_search-5fcode`；超长名称使用稳定哈希缩短。Prompt 名称仍为 `{server_slug}.{upstream_name}`。未知扩展方法在聚合入口使用 `toolhome/{server_slug}/{upstream_method}`；独立入口原样透传。MCP App 若使用原始工具名，ToolHome 会根据 App 资源上下文或全局唯一名称路由；存在同名歧义时应使用独立入口。
 
@@ -194,6 +194,8 @@ ToolHome 的数据面也实现 OAuth 2.1：Harness 可通过 RFC 9728 元数据
 
 **本机范围。** Node-hosted Server 仍然只在所属机器上运行，本机 compact 目录只包含放置在该 node 的 Server。启动时本机入口会镜像控制面的工具可见性；若某个 Server 的投影读取失败，它会一直排除在 compact 目录之外（fail closed），直到下次启动或显式刷新。在控制面修改可见性后，本机入口需要重新连接才会生效。
 
+**节点标识。** `toolhome mcp stdio` 会把本地镜像绑定到 `--node` 或 CLI 配置里的 `nodeId`，都没有时退回主机名。请保持该标识稳定：`auth login` 会保留它；若镜像是用别的标识建立的，启动时会直接说明它属于哪个节点标识，而不是只报一个密钥错误。
+
 **回退到 full。** 在 Host 上把 `TOOLHOME_MCP_TOOL_MODE` 设回 `full`（或删除该变量），或去掉 `toolhome mcp stdio --tool-mode`，然后重新连接客户端。无需数据迁移：full 会清除 compact 镜像写入的可见性行，重新暴露全部启用工具。
 
 **定义稳定。** 聚合 `tools/list` 输出规范化后的对象键顺序，数组保持原顺序，因此仅等价 schema 对象的键顺序变化时，序列化字节完全一致。把工具定义放在模型请求前部的客户端可以复用前缀；真实的定义变化仍会改变字节。独立入口保持上游原始键顺序。
@@ -261,6 +263,27 @@ npm run cli -- config import backup.json
 
 备份文件包含明文 Secret，应使用与主密钥同等级别的保护。为避免 Secret 意外进入终端日志，`--include-secrets` 必须同时提供目标文件；CLI 会在写入后强制设置 `0600`。日常审阅可省略 `--include-secrets`。
 
+导出覆盖两个平面：MCP 服务器（含放置位置）、Hosted CLI（含运行方式与允许列表）、加密凭据，以及 Market 台账。`config import --mode merge` 让恢复变得幂等：凭据按名称复用，目标已有的记录跳过，加 `--upsert` 才逐字段更新；`--dry-run` 返回同样的逐条报告但不写入；默认的 `create` 模式仍然在冲突时中止并列出全部冲突项。
+
+## 迁移
+
+`toolhome migrate` 把一个实例复制到另一个实例，适合把笔记本上的实例搬到云端主机：
+
+```bash
+npm run cli -- migrate --to https://cloud.example.com --to-key "$TOOLHOME_CONTROL_KEY" --dry-run
+npm run cli -- migrate --to https://cloud.example.com --to-key "$TOOLHOME_CONTROL_KEY" \
+  --with-state --issue-access-key cloud
+```
+
+步骤顺序是刻意的。先在目标实例按 pin 住的版本重装 Market 条目，所需的取值从导出的凭据里提取，因此目标实例保留自己的安装台账和版本追踪；随后配置导入以 merge 模式执行，不动 Market 已经建好的记录。
+
+有两样东西无法自行跨实例，命令会如实列出而不是假装完成：
+
+- **access key** 只存摘要。在目标实例重新签发（`--issue-access-key <name>` 会签发并打印 harness 片段）。
+- **Hosted CLI 的登录态**存放在各产品自己的位置——`gh` 在 macOS 钥匙串，`az` 在其状态卷内的令牌缓存。`--with-state` 搬运状态卷；`toolhome cli adopt <slug>` 用该 CLI 自己的命令在本机提取登录态并写进目标实例的卷；`toolhome cli sync` 遍历所有已安装条目。
+
+二进制不参与迁移，也不需要参与：macOS 上的 `gh` 是 Mach-O 可执行文件，而 gateway 运行 Alpine Linux，目标实例会按 catalog 重建自己的 pin 版本制品。逐条结果是 `adopted`、`already-authenticated`、`credential-only`（取值随导出一起走）、`manual`（条目会给出目标端要执行的命令）或 `failed`。
+
 ## 配置
 
 | 环境变量                         | 说明                                              | 默认值                  |

package/dist/server/cli/adopt.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Hand a locally authenticated platform CLI over to a ToolHome instance.
+ *
+ * A hosted CLI's login state belongs to the product, not to ToolHome: `gh` keeps
+ * its token in the macOS keychain, `az` in a token cache, others in a container
+ * volume on the target. Each catalog entry therefore declares how its state
+ * moves, and this walks that declaration once per entry. The extracted secret is
+ * written to the target's stdin and never printed, logged or returned.
+ */
+export interface ControlApi {
+    request(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<unknown>;
+    execStream(slug: string, input: {
+        argv: string[];
+        stdin?: string | null;
+        timeoutMs?: number;
+    }, onFrame: (frame: {
+        type: string;
+        data?: string;
+    }) => void, signal?: AbortSignal): Promise<{
+        code: number | null;
+        result: string;
+    }>;
+}
+export interface LocalCommandResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type LocalRunner = (command: string, args: string[]) => Promise<LocalCommandResult>;
+export interface AdoptOutcome {
+    slug: string;
+    status: 'adopted' | 'already-authenticated' | 'credential-only' | 'manual' | 'undeclared' | 'failed';
+    detail?: string;
+}
+export interface AdoptOptions {
+    slugs?: string[];
+    dryRun?: boolean;
+    force?: boolean;
+    runLocal?: LocalRunner;
+    log?: (line: string) => void;
+}
+export declare function adoptCliCredentials(target: ControlApi, options?: AdoptOptions): Promise<AdoptOutcome[]>;
+//# sourceMappingURL=adopt.d.ts.map

package/dist/server/cli/adopt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.d.ts","sourceRoot":"","sources":["../../../src/cli/adopt.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5F,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EACpE,OAAO,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,EACzD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAE3F,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,uBAAuB,GAAG,iBAAiB,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,CAAC;IACrG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAyBD,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,YAAY,EAAE,CAAC,CAkHzB"}

package/dist/server/cli/adopt.js

@@ -0,0 +1,170 @@
+import { z } from 'zod';
+const localStateSchema = z
+    .object({
+    extract: z.object({ command: z.string(), args: z.array(z.string()) }).optional(),
+    import: z.object({ args: z.array(z.string()) }).optional(),
+    verify: z.object({ args: z.array(z.string()), expect: z.string() }).optional(),
+    target: z.string().optional(),
+    credentialOnly: z.boolean().optional(),
+    manual: z.string().optional(),
+})
+    .passthrough();
+const entrySchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    plane: z.enum(['mcp', 'cli']),
+    installed: z.boolean().default(false),
+    localState: localStateSchema.optional(),
+})
+    .passthrough();
+const statusSchema = z.object({ loggedIn: z.boolean() }).passthrough();
+export async function adoptCliCredentials(target, options = {}) {
+    const runLocal = options.runLocal ?? defaultRunner;
+    const log = options.log ?? (() => { });
+    const catalog = z
+        .array(entrySchema)
+        .parse(await target.request('GET', '/api/v1/market'))
+        .filter((entry) => entry.plane === 'cli' && entry.installed);
+    const wanted = options.slugs === undefined ? catalog : catalog.filter((entry) => options.slugs.includes(entry.id));
+    const outcomes = [];
+    for (const entry of wanted) {
+        const state = entry.localState;
+        if (state === undefined) {
+            outcomes.push({
+                slug: entry.id,
+                status: 'undeclared',
+                detail: 'this catalog entry declares no local-state policy',
+            });
+            continue;
+        }
+        if (state.manual !== undefined) {
+            outcomes.push({ slug: entry.id, status: 'manual', detail: state.manual });
+            continue;
+        }
+        if (state.credentialOnly === true || state.extract === undefined || state.import === undefined) {
+            outcomes.push({
+                slug: entry.id,
+                status: 'credential-only',
+                detail: 'authenticates from credential values, which already travel with the configuration',
+            });
+            continue;
+        }
+        if (!options.force && (await authenticationState(target, entry.id, state.verify)) === 'yes') {
+            outcomes.push({ slug: entry.id, status: 'already-authenticated' });
+            continue;
+        }
+        if (options.dryRun === true) {
+            outcomes.push({
+                slug: entry.id,
+                status: 'adopted',
+                detail: `would run \`${state.extract.command} ${state.extract.args.join(' ')}\` and send the result to ${state.target ?? entry.id}`,
+            });
+            continue;
+        }
+        let secret;
+        try {
+            const extracted = await runLocal(state.extract.command, state.extract.args);
+            if (extracted.code !== 0 || extracted.stdout.trim() === '') {
+                outcomes.push({
+                    slug: entry.id,
+                    status: 'failed',
+                    detail: extracted.stderr.trim() !== ''
+                        ? `local extraction failed: ${extracted.stderr.trim().split('\n')[0]}`
+                        : `local extraction returned nothing (exit ${String(extracted.code)})`,
+                });
+                continue;
+            }
+            secret = extracted.stdout.trim();
+        }
+        catch (error) {
+            outcomes.push({
+                slug: entry.id,
+                status: 'failed',
+                detail: `local extraction failed: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            continue;
+        }
+        let stderr = '';
+        try {
+            await target.execStream(entry.id, { argv: state.import.args, stdin: `${secret}\n` }, (frame) => {
+                if (frame.type === 'stderr' && frame.data !== undefined)
+                    stderr += frame.data;
+            });
+        }
+        catch (error) {
+            outcomes.push({
+                slug: entry.id,
+                status: 'failed',
+                detail: error instanceof Error ? error.message : String(error),
+            });
+            continue;
+        }
+        const confirmed = await authenticationState(target, entry.id, state.verify);
+        if (confirmed === 'no') {
+            outcomes.push({
+                slug: entry.id,
+                status: 'failed',
+                detail: stderr.trim() !== ''
+                    ? `the target rejected the credential: ${stderr.trim().split('\n')[0]}`
+                    : 'the target still reports no login state',
+            });
+            continue;
+        }
+        log(`${entry.id}: credential accepted`);
+        outcomes.push({
+            slug: entry.id,
+            status: 'adopted',
+            detail: confirmed === 'unknown'
+                ? 'handed over, but this entry reports no login state to confirm it'
+                : state.verify === undefined
+                    ? 'reported by the status probe'
+                    : `verified with \`${state.verify.args.join(' ')}\``,
+        });
+    }
+    return outcomes;
+}
+/**
+ * Ask the target whether the credential works: yes, no, or it cannot say.
+ *
+ * A `status` probe answers `loggedIn` only when the product prints that marker,
+ * and most platform CLIs do not (`gh --version` says nothing about login), so an
+ * entry can declare a `verify` command instead. A probe that reports no markers
+ * is inconclusive — never evidence of failure, and never a reason to skip an
+ * upload that is still needed.
+ */
+async function authenticationState(target, slug, verify) {
+    if (verify !== undefined) {
+        let stdout = '';
+        await target.execStream(slug, { argv: verify.args }, (frame) => {
+            if (frame.type === 'stdout' && frame.data !== undefined)
+                stdout += frame.data;
+        });
+        return stdout.includes(verify.expect) ? 'yes' : 'no';
+    }
+    const status = statusSchema.parse(await target.request('GET', `/cli/${slug}/status`));
+    if (status.loggedIn)
+        return 'yes';
+    return status.installed === true && status.version === null ? 'unknown' : 'no';
+}
+const defaultRunner = async (command, args) => {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (error) => {
+            resolve({ code: null, stdout, stderr: error.message });
+        });
+        child.on('close', (code) => {
+            resolve({ code, stdout, stderr });
+        });
+    });
+};
+//# sourceMappingURL=adopt.js.map

package/dist/server/cli/adopt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../../src/cli/adopt.ts"],"names":[],"mappings":"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"}

package/dist/server/cli/main.js

@@ -12,6 +12,8 @@ import { stdioTransportSchema } from '../domain/models.js';
 import { launchEnvironment, spawnStdioServer } from '../node/launch.js';
 import { prepareLocalGateway, startLocalGateway } from '../node/local-gateway.js';
 import { readNodeStatus } from '../node/status.js';
+import { adoptCliCredentials } from './adopt.js';
+import { migrateConfiguration } from './migrate.js';
 function packageVersion() {
     let directory = dirname(fileURLToPath(import.meta.url));
     for (;;) {
@@ -90,6 +92,62 @@ cli
     .command('add <file>')
     .description('Register a hosted CLI from a JSON file or - for stdin')
     .action(run((client, file) => client.request('POST', '/api/v1/clis', readJson(file))));
+cli
+    .command('adopt [slug]')
+    .description('Move a locally authenticated CLI login into this ToolHome instance')
+    .option('--to <url>', 'target instance URL (default: the configured instance)')
+    .option('--to-key <key>', 'target Control Key')
+    .option('--dry-run', 'report what would be handed over without doing it')
+    .option('--force', 'hand the credential over even when the instance already has a login')
+    .action(run(async (client, slug, options) => {
+    const target = targetClient(client, options);
+    return adoptCliCredentials(target, {
+        ...(slug === undefined ? {} : { slugs: [slug] }),
+        dryRun: options.dryRun === true,
+        force: options.force === true,
+        log: (line) => process.stderr.write(`${line}\n`),
+    });
+}));
+cli
+    .command('export-state <slug>')
+    .description('Write a hosted CLI container volume to a file (or - for stdout)')
+    .requiredOption('--volume <name>', 'declared volume name, e.g. toolhome-gh-cli-state')
+    .option('--to <url>', 'instance URL (default: the configured instance)')
+    .option('--to-key <key>', 'Control Key for --to')
+    .action(run(async (client, slug, options) => {
+    const exported = z
+        .object({ archive: z.string(), bytes: z.number() })
+        .parse(await targetClient(client, options).request('GET', `/api/v1/clis/${encodeURIComponent(slug)}/state?volume=${encodeURIComponent(options.volume)}`, undefined, 120_000));
+    return exported;
+}));
+cli
+    .command('import-state <slug> <file>')
+    .description('Replace a hosted CLI container volume from a file written by export-state')
+    .requiredOption('--volume <name>', 'declared volume name, e.g. toolhome-gh-cli-state')
+    .option('--to <url>', 'instance URL (default: the configured instance)')
+    .option('--to-key <key>', 'Control Key for --to')
+    .action(run(async (client, slug, file, options) => {
+    const body = readJson(file);
+    if (typeof body.archive !== 'string') {
+        throw new Error('The file must be the output of `toolhome cli export-state`');
+    }
+    return targetClient(client, options).request('POST', `/api/v1/clis/${encodeURIComponent(slug)}/state?volume=${encodeURIComponent(options.volume)}`, { archive: body.archive }, 120_000);
+}));
+cli
+    .command('sync')
+    .description('Adopt every locally authenticated CLI this instance has installed')
+    .option('--to <url>', 'target instance URL (default: the configured instance)')
+    .option('--to-key <key>', 'target Control Key')
+    .option('--dry-run', 'report what would be handed over without doing it')
+    .option('--force', 'hand credentials over even when the instance already has a login')
+    .action(run(async (client, options) => {
+    const target = targetClient(client, options);
+    return adoptCliCredentials(target, {
+        dryRun: options.dryRun === true,
+        force: options.force === true,
+        log: (line) => process.stderr.write(`${line}\n`),
+    });
+}));
 cli
     .command('update <id> <file>')
     .description('Update a hosted CLI from a JSON file or - for stdin')
@@ -232,9 +290,15 @@ mcp
         if (stopped)
             return;
         stopped = true;
+        // Closing waits on children, the recorder and the local mirror; bound it,
+        // because a shutdown that hangs leaves a process holding node.sqlite that
+        // only SIGKILL can remove — the client has already given up by then.
+        const deadline = setTimeout(() => process.exit(0), 5_000);
+        deadline.unref();
         // Children first: they leak if the process exits before they are reaped.
         await gateway.close().catch(() => undefined);
         await handle.close().catch(() => undefined);
+        clearTimeout(deadline);
         process.exit(0);
     };
     process.stdin.on('end', () => void stop());
@@ -391,7 +455,16 @@ config
 }));
 config
     .command('import <file>')
-    .action(run((client, file) => client.request('POST', '/api/v1/config/import', readJson(file))));
+    .description('Apply a configuration export; --mode merge keeps records the target already has')
+    .option('--mode <mode>', 'create or merge', 'create')
+    .option('--upsert', 'update records the target already has (merge mode)')
+    .option('--dry-run', 'report what would change without writing anything')
+    .action(run((client, file, options) => client.request('POST', '/api/v1/config/import', {
+    ...readJson(file),
+    mode: options.mode,
+    upsert: options.upsert === true,
+    dryRun: options.dryRun === true,
+})));
 config
     .command('import-harness <file>')
     .description('Import a harness mcpServers config (Claude Desktop / Cursor JSON); secrets become encrypted credentials')
@@ -402,6 +475,41 @@ config
     preview: options.preview ?? false,
     ...(options.upsert ? { mode: 'upsert' } : {}),
 })));
+program
+    .command('migrate')
+    .description('Copy this instance into another ToolHome instance (both planes)')
+    .requiredOption('--to <url>', 'target instance URL')
+    .requiredOption('--to-key <key>', 'target Control Key')
+    .option('--planes <planes>', 'mcp, cli or both', 'mcp,cli')
+    .option('--dry-run', 'report what would change without writing to the target')
+    .option('--with-state', 'move each hosted CLI state volume, including its login')
+    .option('--reset-oauth-clients', 'clear OAuth client registrations bound to this origin')
+    .option('--issue-access-key <name>', 'issue an MCP Access Key on the target and print it')
+    .action(run(async (client, options) => {
+    const planes = options.planes
+        .split(',')
+        .map((plane) => plane.trim())
+        .filter((plane) => plane !== '');
+    for (const plane of planes) {
+        if (plane !== 'mcp' && plane !== 'cli') {
+            throw new Error(`Unknown plane "${plane}"; use mcp, cli or both`);
+        }
+    }
+    const connection = resolveConnection(program.opts());
+    const target = new ControlClient(new URL(options.to), options.toKey);
+    const report = await migrateConfiguration(client, target, {
+        planes: { mcp: planes.includes('mcp'), cli: planes.includes('cli') },
+        dryRun: options.dryRun === true,
+        withState: options.withState === true,
+        resetOauthClients: options.resetOauthClients === true,
+        ...(options.issueAccessKey === undefined
+            ? {}
+            : { accessKeyName: options.issueAccessKey }),
+        log: (line) => process.stderr.write(`${line}\n`),
+    });
+    process.stderr.write(`source ${connection.url} → target ${options.to}\n`);
+    return report;
+}));
 const endpoint = program.command('endpoint').description('Print standard MCP endpoints');
 endpoint
     .command('aggregate')
@@ -531,8 +639,15 @@ auth
     .action((options) => {
     const url = options.url ?? program.opts().url;
     if (!url)
-        throw new Error('required option \'--url <url>\' not specified');
-    const value = localConfigSchema.parse({ url, controlKey: options.controlKey });
+        throw new Error("required option '--url <url>' not specified");
+    // Logging in replaces the connection settings only: the node label decides
+    // the local mirror's key, and dropping it silently broke `mcp stdio`.
+    const existing = loadLocalConfig();
+    const value = localConfigSchema.parse({
+        url,
+        controlKey: options.controlKey,
+        ...(existing?.nodeId === undefined ? {} : { nodeId: existing.nodeId }),
+    });
     const path = configPath();
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
@@ -572,6 +687,14 @@ function run(action) {
         }
     };
 }
+/** Reuse the connection the command already resolved unless the caller names another instance. */
+function targetClient(client, options) {
+    if (options.to === undefined)
+        return client;
+    if (options.toKey === undefined)
+        throw new Error('--to-key is required with --to');
+    return new ControlClient(new URL(options.to), options.toKey);
+}
 function resolveConnection(options) {
     const stored = loadLocalConfig();
     return localConfigSchema.parse({