@hirey/hi-mcp-server 0.1.19 → 0.1.25

package/dist/server.js

@@ -1,26 +1,96 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import { createServer } from 'node:http';
 import path from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+// 从 package.json 实时读 version，避免源里 hardcoded 版本号跟实际 publish 版本号长期 drift
+// (历史上一直挂着 0.1.7 但实际 npm 上是 0.1.19，导致 mcp-server 自报 version 跟 npm 不一致)。
+const __pkgJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+const pkgJson = JSON.parse(fsSync.readFileSync(__pkgJsonPath, 'utf8'));
 import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { AGENT_GATEWAY_EVENT_TOPICS, normalizeAgentEndpointList, normalizeAgentInstallationDeliveryDeclaration, normalizeAgentSubscriptionList, normalizeText, } from '@hirey/hi-agent-contracts';
+import { AGENT_GATEWAY_EVENT_TOPICS, normalizeAgentEndpointList, normalizeAgentInstallationDeliveryDeclaration, normalizeAgentSubscriptionList, normalizeText, INSTALL_WELCOME_ONBOARDING_KIND, INSTALL_WELCOME_ONBOARDING_INSTRUCTION, DEFAULT_INTENT_OPTIONS, } from '@hirey/hi-agent-contracts';
 import { createHiAgentClients, exchangeHiAgentClientCredentialsToken, HiAgentGatewayClient, HiAgentPlatformClient, } from '@hirey/hi-agent-sdk';
-import { readState, resolveCanonicalOpenClawStateDir, resolveDefaultStateDir, resolveLegacyStateFiles, resolveStateFile, validateOpenClawStateDir, updateState, normalizeStateProfile, } from './state.js';
+import { composeSubjectScopedProfile, quarantineStaleIdentityIfNeeded, readState, resolveCanonicalOpenClawStateDir, resolveDefaultStateDir, resolveLegacyStateFiles, resolveStateFile, validateOpenClawStateDir, updateState, normalizeStateProfile, } from './state.js';
 import { looksLikeOpenClawSessionKey, validateOpenClawSessionKey, } from './openclaw-session-key.js';
 import { buildInstallReceiverCommandArgv, } from './receiver-command.js';
 import { applyReceiverRuntimeSnapshot, receiverConfigMaterialEquals, } from './receiver-config-material.js';
 import { resolveInstallDefaultReplyDeliveryContext, resolveInstallRouteMissingPolicy, } from './defaultReplyRoute.js';
 import { resolveInstallDisplayName } from './installDefaults.js';
+import { buildAuthorizationServerMetadataAlias, buildOAuthVerifier, buildProtectedResourceMetadata, buildWwwAuthenticateChallenge, getCurrentRequestAuth, requestAuthStorage, verifyRequestBearer, } from './oauthRequestAuth.js';
+// Hosts that hi-mcp-server can claim a first-class identity for. Everything
+// outside this set normalizes down to `generic`. We carry the wider list here
+// (not the narrow openclaw/generic split) so install state + telemetry can
+// distinguish a Codex install from a Claude Code install from a bare generic
+// MCP host, even though the install flow itself only branches on openclaw.
+const KNOWN_HOST_KINDS = new Set([
+    'openclaw',
+    'generic',
+    'codex',
+    'claude_code',
+    'claude_chat',
+    'claude_cowork',
+    'claude_desktop',
+    'chatgpt_app',
+]);
 const CAPABILITY_CACHE_TTL_MS = 30_000;
 const RECEIVER_STOP_TIMEOUT_MS = 3_000;
 const RECEIVER_STOP_POLL_MS = 100;
 const resolvedProfile = normalizeStateProfile(process.env.HI_MCP_PROFILE);
+const requestToolSurfaceStorage = new AsyncLocalStorage();
+const CHATGPT_APP_TOOL_NAMES = new Set([
+    'listing_taxonomy',
+    'agent_listings',
+    'matching_sessions',
+    'pairings',
+    'thread_meetings',
+    'faq_search',
+    'faq_get',
+    'content_render',
+    'content_get',
+]);
+const CAPABILITY_TOOL_OUTPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        ok: { type: 'boolean' },
+        capability_id: { type: 'string' },
+        tool_name: { type: 'string' },
+        result: {
+            type: ['object', 'array', 'string', 'number', 'boolean', 'null'],
+            description: 'Tool-specific result payload returned by Hi.',
+        },
+    },
+    required: ['ok', 'capability_id', 'tool_name', 'result'],
+    additionalProperties: false,
+};
+function normalizeToolSurface(input) {
+    const value = normalizeText(input).toLowerCase().replace(/[\s-]+/g, '_');
+    if (['chatgpt', 'chatgpt_app', 'chatgpt_apps', 'openai_app', 'apps'].includes(value)) {
+        return 'chatgpt_app';
+    }
+    return 'full';
+}
+function effectiveToolSurface() {
+    return requestToolSurfaceStorage.getStore() || config.toolSurface;
+}
+function isToolVisibleOnSurface(toolName) {
+    if (effectiveToolSurface() === 'full')
+        return true;
+    return CHATGPT_APP_TOOL_NAMES.has(toolName);
+}
+function readListEnv(name, fallback) {
+    const raw = normalizeText(process.env[name]);
+    if (!raw)
+        return fallback;
+    return raw.split(/[,\s]+/).map((x) => x.trim()).filter(Boolean);
+}
 const config = {
     host: normalizeText(process.env.HI_MCP_HOST) || '127.0.0.1',
     port: Number(process.env.HI_MCP_PORT || 8788),
@@ -28,6 +98,19 @@ const config = {
     stateDir: normalizeText(process.env.HI_MCP_STATE_DIR) || resolveDefaultStateDir(resolvedProfile),
     platformBaseUrl: normalizeText(process.env.HI_PLATFORM_BASE_URL),
     transport: normalizeText(process.env.HI_MCP_TRANSPORT).toLowerCase() === 'stdio' ? 'stdio' : 'http',
+    toolSurface: normalizeToolSurface(process.env.HI_MCP_TOOL_SURFACE),
+    authMode: normalizeText(process.env.HI_MCP_AUTH_MODE).toLowerCase() === 'oauth' ? 'oauth' : 'local',
+    // HI_MCP_OAUTH_RESOURCE accepts a single URL or a comma/whitespace-separated
+    // list. First entry is the primary. Old single-value deployments continue
+    // to work unchanged (a 1-element array).
+    oauthMcpResources: readListEnv('HI_MCP_OAUTH_RESOURCE', []),
+    oauthAuthorizationServer: normalizeText(process.env.HI_MCP_OAUTH_AUTHORIZATION_SERVER),
+    // Backwards-compat: when HI_MCP_OAUTH_ISSUER is not set, fall back to
+    // HI_MCP_OAUTH_AUTHORIZATION_SERVER so older single-tenant smoke setups
+    // (where AS URL == JWT issuer == same host) keep working.
+    oauthIssuer: normalizeText(process.env.HI_MCP_OAUTH_ISSUER)
+        || normalizeText(process.env.HI_MCP_OAUTH_AUTHORIZATION_SERVER),
+    oauthScopesSupported: readListEnv('HI_MCP_OAUTH_SCOPES', ['hi.read', 'hi.write', 'hi.events']),
 };
 let capabilityCache = null;
 function assertConfig() {
@@ -37,6 +120,20 @@ function assertConfig() {
     if (!Number.isFinite(config.port) || config.port <= 0) {
         throw new Error('invalid_hi_mcp_port');
     }
+    if (config.authMode === 'oauth') {
+        if (config.transport !== 'http') {
+            throw new Error('oauth_auth_mode_requires_http_transport');
+        }
+        if (config.oauthMcpResources.length === 0) {
+            throw new Error('missing_hi_mcp_oauth_resource');
+        }
+        if (!config.oauthIssuer) {
+            throw new Error('missing_hi_mcp_oauth_issuer');
+        }
+        if (!config.oauthAuthorizationServer) {
+            throw new Error('missing_hi_mcp_oauth_authorization_server');
+        }
+    }
 }
 function jsonText(value) {
     return JSON.stringify(value, null, 2);
@@ -97,7 +194,7 @@ function controlTools() {
                 type: 'object',
                 properties: {
                     display_name: { type: 'string', description: '首次安装且当前 profile 还没有 identity 时使用的人类可读名称。省略时会按 host_kind 使用稳定默认值：OpenClaw 为 `OpenClaw Hi Agent`，generic 为 `Hi Agent`。' },
-                    host_kind: { type: 'string', description: "可选：'openclaw'|'generic'。默认 generic。" },
+                    host_kind: { type: 'string', description: "可选。已知：'openclaw' | 'generic' | 'codex' | 'claude_code' | 'claude_chat' | 'claude_cowork' | 'claude_desktop' | 'chatgpt_app'。默认 generic。仅 'openclaw' 触发本地 receiver / hooks 适配；其他值按远程 / pull 形态走，但仍会保留在 install state 里用于 doctor + telemetry。" },
                     agent_kind: { type: 'string', description: '首次 register 时可选的 agent_kind。默认 external。' },
                     replace_existing_state: { type: 'boolean', description: '首次 register 且本地已有 state 时，是否允许覆盖本地持久化身份。' },
                     migrate_legacy_state: { type: 'boolean', description: '默认 true。若 canonical state 为空，则尝试一次已知 legacy state 迁移。' },
@@ -122,6 +219,10 @@ function controlTools() {
                     default_reply_thread_id: { type: 'string', description: '可选：default continuation route 的 thread_id。' },
                     subscribe_default_topics: { type: 'boolean', description: '是否自动补齐 Hi 官方默认事件订阅。默认 true。' },
                     run_doctor: { type: 'boolean', description: '默认 true。安装完成后自动跑一次 hi_agent_doctor。' },
+                    metadata: {
+                        type: 'object',
+                        description: '首次 register 时透传给 hi-platform 写入 agents.metadata_json 的自定义字段。常见用法：渠道归因 `{"channel_code":"..."}`——用户被某邀请落地页提供的 prompt 里带了 channel_code，必须**原样保留**透传给本工具，不要丢弃也不要修改其值。',
+                    },
                 },
             },
         },
@@ -148,6 +249,14 @@ function controlTools() {
                 },
             },
         },
+        {
+            name: 'hi_agent_state_resync',
+            description: '把本地持久化 identity 拉回 remote canonical（/me + /installation 当前真值）。专为 server-side admin consolidate / mergeAgents 之后 client local state 还停在 merge 前快照的场景兜底；只刷 agent_id / display_name / delivery_capabilities，不动 installation_id 和长期凭证（client_id / client_secret 等）。看到 hi_agent_doctor 报 `agent_identity_split` blocker 时调这个工具，不要再调 hi_agent_register（会再造孤儿）。',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
         {
             name: 'hi_agent_register',
             description: '按 Hi 官方 register -> token -> activate 主线创建一个新的 external agent installation，并把长期凭证持久化到本地 state。',
@@ -189,6 +298,25 @@ function controlTools() {
                 },
             },
         },
+        {
+            name: 'hi_agent_claim_export',
+            description: '导出一个一次性、短过期的"重挂凭单"（claim token），用于把另一台新设备挂回**当前这个 agent**（同一身份）。要求当前 agent 已绑定手机号（=工作区所有权证明；没绑会 403，请先用 phone_binding 绑定）。返回的 claim_token 像密码一样——谁 redeem 谁就接入这个 agent，只发给你自己的其它设备。典型场景：换电脑 / 重装 / 凭证丢了，不想变成一个新的空 agent、也不想重新绑手机时——在老设备上 export，到新设备上调 hi_agent_claim_redeem，就能继续用同一个 agent（listings / 会话 / 对端回复都在）。',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'hi_agent_claim_redeem',
+            description: '在一台**新设备 / 新安装**上消费另一台设备用 hi_agent_claim_export 导出的 claim_token，把当前这台安装重挂到那个 agent——之后你就是同一个 agent（之前的 listings、会话、对端回复都在，可直接接着回复）。一次性使用，用过即作废；过期 / 被吊销 / 已用过都会被拒。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    claim_token: { type: 'string', description: '老设备 hi_agent_claim_export 返回的一次性凭单 secret。' },
+                },
+                required: ['claim_token'],
+            },
+        },
         {
             name: 'hi_agent_installation_get',
             description: '读取当前 installation 的正式 persisted state，包括 delivery_capabilities。',
@@ -320,7 +448,7 @@ function controlTools() {
         },
         {
             name: 'hi_agent_events_wait',
-            description: '用 claim/poll 等待下一批 durable events，适合没有 live push 的 MCP-first 宿主。',
+            description: '用 claim/poll 等待下一批 durable events，适合没有 live push 的 MCP-first 宿主。\n\n**宿主无 push channel 时（典型如 Codex CLI）**：用户结束当前 turn 后没有任何 background process 会把 Hi 事件投递给 LLM —— 对方 agent 的 reply、meeting 确认、listing reaction 都只会静静躺在 Hi outbox 里等下次 claim/wait。这种宿主上发起任何 outreach 后（pairings.contact_target / matching_sessions.contact_match / thread_meetings.start / agent_listings.upsert），都应当主动建议用户开一条 scheduled drain：Codex 用户可以用 thread automation（每 N 分钟唤回当前 thread）或外置 cron + `codex exec "drain my Hi inbox via hi_agent_events_wait then ack"`；其它 MCP-first 宿主同理。如果用户没设这种轮询，对方的回复就会一直被 silent-suppress 在 outbox 里直到用户主动问起，体验上等同于"消息丢了"。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -388,21 +516,91 @@ async function createBootstrapClients() {
         gateway,
     };
 }
+// Per-subject record of "this process has just quarantined a stale identity
+// belonging to <subject_id>". In OAuth multi-tenant HTTP mode we MUST NOT
+// share a single notice across subjects — A's quarantine notice would
+// otherwise leak A's issuer / previous_agent_id / previous_installation_id
+// out through B's hi_agent_status response. In stdio / single-tenant mode
+// there's exactly one operator and we keep the historic single-notice
+// behaviour (keyed under the bare `config.profile`).
+const quarantineNoticeBySubject = new Map();
+function noticeKeyForCurrentSubject() {
+    if (config.authMode !== 'oauth')
+        return config.profile;
+    const auth = getCurrentRequestAuth();
+    return auth?.subjectId ? `subject:${auth.subjectId}` : config.profile;
+}
+// Effective profile for state I/O. In OAuth multi-tenant HTTP mode, each
+// /mcp request carries a verified bearer with a `sub` claim — we derive a
+// per-subject suffix so two OAuth callers never share a state file.
+//
+// Fail-closed: if OAuth mode is active but the request auth is somehow not
+// in scope (e.g. a tool handler escapes the AsyncLocalStorage frame via a
+// stray setTimeout / unawaited promise), we throw rather than silently
+// falling back to `config.profile` (which would write into the shared
+// single-tenant file — exactly the cross-tenant leak this isolation aims
+// to prevent). stdio / local single-tenant mode never has request auth, so
+// it cleanly falls back to `config.profile` and the historic single-file
+// layout.
+function effectiveStateProfile() {
+    if (config.authMode !== 'oauth')
+        return config.profile;
+    const auth = getCurrentRequestAuth();
+    if (!auth?.subjectId) {
+        throw new Error('oauth_state_io_outside_request_auth_scope');
+    }
+    return composeSubjectScopedProfile(config.profile, auth.subjectId);
+}
 async function loadPersistedState() {
-    return await readState({
+    const profile = effectiveStateProfile();
+    const raw = await readState({
         stateDir: config.stateDir,
-        profile: config.profile,
+        profile,
     });
+    const { state, quarantined } = await quarantineStaleIdentityIfNeeded({
+        stateDir: config.stateDir,
+        profile,
+        currentPlatformBaseUrl: config.platformBaseUrl,
+        state: raw,
+        logStderr: (line) => process.stderr.write(`${line}\n`),
+    });
+    if (quarantined) {
+        quarantineNoticeBySubject.set(noticeKeyForCurrentSubject(), quarantined);
+    }
+    return state;
+}
+// peek 不消费，让 install / status / doctor 调用期间的所有响应都能 surface 一次同样的
+// quarantine event；mcp 进程退出后 in-memory 通知自然丢掉。In OAuth multi-tenant
+// HTTP mode the notice is scoped to the current request's subject so other
+// subjects never see this subject's quarantine details.
+export function peekQuarantineNotice() {
+    return quarantineNoticeBySubject.get(noticeKeyForCurrentSubject()) || null;
 }
 async function persistState(updater) {
     return await updateState({
         stateDir: config.stateDir,
-        profile: config.profile,
+        profile: effectiveStateProfile(),
         updater,
     });
 }
 async function createAuthorizedClients() {
     let state = await loadPersistedState();
+    // OAuth mode: the inbound /mcp request already carries a verified bearer
+    // bound to a Codex / Claude Code installation. Replay it verbatim to
+    // downstream Hi services and skip the disk identity entirely — there is
+    // no "current installation on this process" when running multi-tenant.
+    const requestAuth = config.authMode === 'oauth' ? getCurrentRequestAuth() : null;
+    if (requestAuth) {
+        const clients = await createHiAgentClients({
+            platformBaseUrl: config.platformBaseUrl,
+            token: requestAuth.bearer,
+        });
+        return {
+            state,
+            accessToken: requestAuth.bearer,
+            ...clients,
+        };
+    }
     if (!state.identity)
         throw new Error('missing_agent_identity');
     const token = await exchangeHiAgentClientCredentialsToken({
@@ -433,11 +631,25 @@ async function createAuthorizedClients() {
 function resolveCurrentStateFile() {
     return resolveStateFile({
         stateDir: config.stateDir,
-        profile: config.profile,
+        profile: effectiveStateProfile(),
     });
 }
 function normalizeHostKind(raw) {
-    return normalizeText(raw).toLowerCase() === 'openclaw' ? 'openclaw' : 'generic';
+    const value = normalizeText(raw).toLowerCase().replace(/-/g, '_');
+    if (!value)
+        return 'generic';
+    // Aliases for host strings users may type without underscores.
+    if (value === 'claudecode')
+        return 'claude_code';
+    if (value === 'claudechat' || value === 'claude')
+        return 'claude_chat';
+    if (value === 'claudedesktop')
+        return 'claude_desktop';
+    if (value === 'claudecowork' || value === 'cowork')
+        return 'claude_cowork';
+    if (value === 'chatgpt' || value === 'chatgptapp')
+        return 'chatgpt_app';
+    return KNOWN_HOST_KINDS.has(value) ? value : 'generic';
 }
 function normalizeReceiverTransport(raw) {
     return normalizeText(raw).toLowerCase() === 'stream' ? 'stream' : 'claim';
@@ -463,6 +675,17 @@ function buildInstallRuntimeState(current, patch) {
 }
 async function maybeMigrateLegacyState() {
     const targetStateFile = resolveCurrentStateFile();
+    // Legacy single-tenant state migration is unsafe in OAuth multi-tenant mode:
+    // the legacy candidate files (e.g. `~/.openclaw/hi/default.json`) are
+    // un-scoped per subject, so copying one into a new OAuth subject's
+    // subject-scoped state file would re-introduce the cross-tenant identity
+    // leak we just closed in commit ab8c41d (every fresh OAuth subject on first
+    // install would inherit whatever identity the legacy single-tenant install
+    // had left on disk). Stdio / local single-tenant mode keeps the historic
+    // migration behaviour because there it's exactly the operator's own state.
+    if (config.authMode === 'oauth') {
+        return { migrated: false, from: null, to: targetStateFile };
+    }
     try {
         await fs.access(targetStateFile);
         return { migrated: false, from: null, to: targetStateFile };
@@ -628,7 +851,7 @@ function buildDefaultReplyRoute(args, options = {}) {
         requireOpenClawSessionKey: options.requireOpenClawSessionKey,
     });
     const deliveryContext = resolveInstallDefaultReplyDeliveryContext({
-        hostKind: options.hostKind === 'openclaw' ? 'openclaw' : 'generic',
+        hostKind: options.hostKind || 'generic',
         hasSessionKey: !!sessionKey,
         defaultReplyChannel: args.default_reply_channel,
         defaultReplyTo: args.default_reply_to,
@@ -803,6 +1026,14 @@ async function startDetachedReceiver(args) {
 function buildDoctorSummary(args) {
     const installState = stateInstallSnapshot(args.state.runtime);
     const remoteInstallation = args.remote?.installation;
+    const remoteMe = args.remote?.me;
+    // OAuth 多租户模式下没有本地 state.identity；connected/activated 完全靠 remote probe
+    // 推。OpenClaw 路径反过来——本地 identity 才是 truth，没远端响应也能算 connected。
+    const remoteConnected = !!(normalizeText(remoteMe?.agent?.agent_id)
+        && normalizeText(remoteMe?.agent?.status || 'active').toLowerCase() !== 'disabled'
+        && normalizeText(remoteInstallation?.installation?.status || 'active').toLowerCase() !== 'disabled');
+    const connected = !!args.state.identity || remoteConnected;
+    const activated = !!(remoteInstallation?.installation?.activated_at || args.state.identity?.activated_at);
     const deliveryDeclaration = remoteInstallation?.installation?.delivery_capabilities
         || args.state.identity?.delivery_capabilities
         || null;
@@ -824,8 +1055,9 @@ function buildDoctorSummary(args) {
         state_dir: config.stateDir,
         state_file: resolveCurrentStateFile(),
         canonical_openclaw_state_dir: resolveCanonicalOpenClawStateDir(config.profile),
-        connected: !!args.state.identity,
-        activated: !!(remoteInstallation?.installation?.activated_at || args.state.identity?.activated_at),
+        quarantined_stale_identity: peekQuarantineNotice(),
+        connected,
+        activated,
         event_path: deliveryDeclaration?.preferred || (localReceiverEnabled ? 'local_receiver' : 'claim_ack'),
         receiver_config_path: installState.receiver_config_path,
         receiver_running: isProcessAlive(installState.receiver_pid),
@@ -913,6 +1145,22 @@ async function diagnoseOpenClawHookBasePathMismatch(args) {
     };
 }
 async function handleRegister(args) {
+    // 2026-05：OAuth 多租户模式（Codex / Claude Code 走 /mcp）下，bearer 已经在 hi-auth
+    // 那一层通过 ensureRemoteOAuthAgentConnection 自动 provision 了 agent + installation
+    // （见 hi-agent-gateway agentPlatform.ts:ensureRemoteOAuthAgentConnection）。再走
+    // gateway.register 会 mint 一个新 installation_id 当 auth_principal，造出一条
+    // 跟当前 bearer 不挂钩的孤儿 agent ——本地 state 写了它但 bearer 永远 resolve 回旧 agent。
+    // 用户感知到的就是"local identity 跟 /me 不一致 → 我的数据没了"。
+    //
+    // OAuth 模式正确做身份切换的路径：admin 调 /internal/agents/:source/consolidate-into
+    // 让 installation 原子改绑到 target；客户端跑 hi_agent_state_resync 让 local state
+    // 跟上 remote。绝对不要在 OAuth 路径下再走 register。
+    if (config.authMode === 'oauth' && getCurrentRequestAuth()) {
+        return fail('hi_agent_register_not_allowed_in_oauth_mode', {
+            hint: 'OAuth bearer 已经通过 ensureRemoteOAuthAgentConnection 自动 provision 了 agent；再 register 会造孤儿（local agent_id 跟 bearer 解析出的 agent_id 永远不一致）。需要切换身份请 admin 调 /internal/agents/:source/consolidate-into；客户端本地 state 出 drift 请用 hi_agent_state_resync。',
+            profile: config.profile,
+        });
+    }
     const current = await loadPersistedState();
     if (current.identity && args.replace_existing_state !== true) {
         return fail('agent_state_already_exists', {
@@ -968,6 +1216,108 @@ async function handleRegister(args) {
         persisted_profile: config.profile,
     });
 }
+// 2026-05：在 server-side agent_installations.agent_id 被 admin consolidate / mergeAgents
+// 改绑之后，把本地 state.identity 拉回 remote canonical。bearer 不动、installation_id 不动、
+// 长期凭证（client_id / client_secret 等）不动——只刷三个被 merge 改过的字段：agent_id、
+// display_name、delivery_capabilities。专门给 hi_agent_doctor 报 agent_identity_split blocker
+// 之后兜底用，不需要服务端配合的轻量 client-side fix。
+//
+// 跟 hi_agent_connect 的区别：connect 是 "把当前 installation 绑到另一个 agent"，会调
+// gateway.connect 走 mutation 路径——不该在已经 merge 完的 installation 上重复发起。
+// 这里只读 /me + /installation，纯 client-side 文件 patch，不进 hi-platform 写路径，
+// 也不会跟正在跑的 admin merge 冲突。
+//
+// OAuth 模式下 state.identity 永远是 null（bearer 决定身份），调用时直接 no-op 报回当前
+// remote view——不应该阻断，让 LLM 在 OAuth 路径下也能用它做"确认我现在到底是谁"探查。
+async function handleStateResync(_args) {
+    const { gateway } = await createAuthorizedClients();
+    const [me, installation] = await Promise.all([
+        gateway.me(),
+        gateway.getInstallation(),
+    ]);
+    const remoteAgentId = normalizeText(me?.agent?.agent_id) || null;
+    const remoteInstallationId = normalizeText(installation.installation?.installation_id) || null;
+    const remoteAgentDisplayName = normalizeText(me?.agent?.display_name) || null;
+    const remoteAgentKind = normalizeText(me?.agent?.agent_kind) || null;
+    const remoteDeliveryCapabilities = installation.installation?.delivery_capabilities || null;
+    const remoteActivatedAt = normalizeText(installation.installation?.activated_at) || null;
+    if (!remoteAgentId || !remoteInstallationId) {
+        return fail('state_resync_remote_unreadable', {
+            hint: 'gateway.me / getInstallation 没回出 canonical IDs；可能是 bearer 还没 provision agent，跑 hi_agent_install 先。',
+        });
+    }
+    // OAuth 多租户模式（Codex / Claude Code 走 /mcp）：state.identity 故意是 null，
+    // 每条请求的真身份由 bearer 决定。即使 disk 上有残留 identity（不该有但理论可能），
+    // 也不要 patch——把 disk 改成"当前 bearer 解析出的 agent"在多租户下是错的（下一条
+    // 请求可能是另一个 subject）。直接报当前 remote view 让 caller 知道现在 bearer
+    // 落在哪个 agent。
+    if (config.authMode === 'oauth') {
+        return ok({
+            ok: true,
+            patched: false,
+            reason: 'oauth_multitenant_no_disk_identity',
+            remote: {
+                agent_id: remoteAgentId,
+                installation_id: remoteInstallationId,
+                display_name: remoteAgentDisplayName,
+                agent_kind: remoteAgentKind,
+            },
+        });
+    }
+    const before = await loadPersistedState();
+    const beforeIdentity = before.identity;
+    const beforeAgentId = beforeIdentity?.agent_id || null;
+    const beforeInstallationId = beforeIdentity?.installation_id || null;
+    // 非 OAuth 模式下到这里 state.identity 不应该是 null——createAuthorizedClients 在
+    // 没有 disk identity 时已经 throw missing_agent_identity 提前结束。保险起见还是检查一遍。
+    if (!beforeIdentity) {
+        return fail('state_resync_no_local_identity', {
+            hint: '非 OAuth 模式下 local state 还没 identity，先跑 hi_agent_install。',
+        });
+    }
+    const agentIdDrift = beforeAgentId !== remoteAgentId;
+    const installationIdDrift = beforeInstallationId !== remoteInstallationId;
+    if (!agentIdDrift && !installationIdDrift) {
+        return ok({
+            ok: true,
+            patched: false,
+            reason: 'no_drift',
+            identity: { agent_id: beforeAgentId, installation_id: beforeInstallationId },
+        });
+    }
+    // installation_id drift 在 client_credentials 模式下意味着客户端凭证完全错位——
+    // client_id / client_secret 还认旧 installation 的 token，但 server 把 installation
+    // 重新绑给了另一个 (auth_principal, auth_issuer) tuple，那 bearer 自己就拉不到 /me。
+    // 这种情况 resync 救不了，得走 hi_agent_install 重建凭证。
+    if (installationIdDrift) {
+        return fail('state_resync_installation_id_drift_unrecoverable', {
+            local_installation_id: beforeInstallationId,
+            remote_installation_id: remoteInstallationId,
+            hint: '本地 installation_id 跟 /me 拿到的 installation 不一致——这说明 client_credentials 凭证已经不再认得当前 installation。resync 只能修 agent_id drift（merge 场景）。需要重新走 hi_agent_install。',
+        });
+    }
+    await persistState((current) => ({
+        ...current,
+        identity: current.identity
+            ? {
+                ...current.identity,
+                agent_id: remoteAgentId,
+                display_name: remoteAgentDisplayName || current.identity.display_name,
+                agent_kind: remoteAgentKind || current.identity.agent_kind,
+                activated_at: remoteActivatedAt || current.identity.activated_at,
+                delivery_capabilities: remoteDeliveryCapabilities || current.identity.delivery_capabilities,
+            }
+            : current.identity,
+        runtime: { ...current.runtime, updated_at: new Date().toISOString() },
+    }));
+    return ok({
+        ok: true,
+        patched: true,
+        reason: 'agent_id_resynced_from_remote',
+        before: { agent_id: beforeAgentId, installation_id: beforeInstallationId },
+        after: { agent_id: remoteAgentId, installation_id: remoteInstallationId },
+    });
+}
 async function handleConnect(args) {
     const { gateway, state } = await createAuthorizedClients();
     const connected = await gateway.connect({
@@ -1029,14 +1379,124 @@ async function handleActivate(args) {
         contract: activated.contract,
     });
 }
+// claim-token re-attach (2026-06)：登录后"重挂凭单"。export 在已绑手机的 agent 上签发一个一次性
+// 短过期凭单；redeem 在另一台新设备上消费它，把这台设备挂回同一个 agent。直接打 gateway 的
+// /v1/agents/claim/* （与 connect/activate 同一 registry base），复用当前请求/凭证换来的 bearer。
+function claimGatewayBaseUrl(clients) {
+    const wk = clients.wellKnown;
+    return (wk?.platform?.registry_base_url || wk?.registry_base_url || config.platformBaseUrl);
+}
+async function handleClaimExport(_args) {
+    const clients = await createAuthorizedClients();
+    const res = await fetch(`${claimGatewayBaseUrl(clients)}/v1/agents/claim/export`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${clients.accessToken}`, 'content-type': 'application/json' },
+        body: '{}',
+    });
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok)
+        return fail(String(data?.error || 'claim_export_failed'), data);
+    return ok(data);
+}
+async function handleClaimRedeem(args) {
+    const claimToken = normalizeText(args.claim_token);
+    if (!claimToken)
+        return fail('missing_claim_token');
+    const clients = await createAuthorizedClients();
+    const res = await fetch(`${claimGatewayBaseUrl(clients)}/v1/agents/claim/redeem`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${clients.accessToken}`, 'content-type': 'application/json' },
+        body: JSON.stringify({ claim_token: claimToken }),
+    });
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok)
+        return fail(String(data?.error || 'claim_redeem_failed'), data);
+    // identity 已在服务端重挂到 data.agent_id；本地 client_credentials 不变，下次调用按 principal
+    // 自然解析到新 agent，无需改本地 state。
+    return ok(data);
+}
 async function handleStatus(args) {
     const state = await loadPersistedState();
+    const requestAuth = config.authMode === 'oauth' ? getCurrentRequestAuth() : null;
+    if (requestAuth) {
+        const auth = {
+            subject: requestAuth.subjectId,
+            issuer: normalizeText(requestAuth.claims?.iss),
+            audience: requestAuth.claims?.aud ?? null,
+            client_id: normalizeText(requestAuth.claims?.client_id) || null,
+            scope: normalizeText(requestAuth.claims?.scope) || null,
+        };
+        try {
+            const { gateway } = await createAuthorizedClients();
+            const [me, installation, endpoints, subscriptions] = await Promise.all([
+                gateway.me(),
+                gateway.getInstallation(),
+                gateway.listEndpoints(),
+                gateway.listSubscriptions(),
+            ]);
+            const remoteAgent = isPlainObject(me?.agent) ? me.agent : null;
+            const remoteInstallation = isPlainObject(installation?.installation)
+                ? installation.installation
+                : null;
+            const connected = normalizeText(remoteAgent?.agent_id) !== ''
+                && normalizeText(remoteAgent?.status || 'active') !== 'disabled'
+                && normalizeText(remoteInstallation?.installation_id) !== ''
+                && normalizeText(remoteInstallation?.status || 'active') !== 'disabled';
+            const activated = connected && (normalizeText(remoteInstallation?.activated_at) !== ''
+                || normalizeText(remoteInstallation?.status) === 'active');
+            return ok({
+                ok: true,
+                mode: 'remote_oauth',
+                profile: config.profile,
+                state_dir: config.stateDir,
+                state_file: resolveCurrentStateFile(),
+                auth,
+                quarantined_stale_identity: peekQuarantineNotice(),
+                summary: {
+                    connected,
+                    activated,
+                    receiver_config_path: null,
+                    receiver_running: false,
+                    event_path: remoteInstallation?.delivery_capabilities?.preferred || null,
+                },
+                state,
+                remote: {
+                    me,
+                    installation,
+                    endpoints,
+                    subscriptions,
+                },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return ok({
+                ok: true,
+                mode: 'remote_oauth',
+                profile: config.profile,
+                state_dir: config.stateDir,
+                state_file: resolveCurrentStateFile(),
+                auth,
+                quarantined_stale_identity: peekQuarantineNotice(),
+                summary: {
+                    connected: false,
+                    activated: false,
+                    receiver_config_path: null,
+                    receiver_running: false,
+                },
+                reason: 'remote_oauth_installation_unavailable',
+                detail: message || 'unknown_error',
+                state,
+            });
+        }
+    }
     if (args.include_remote !== true || !state.identity) {
         return ok({
             ok: true,
             profile: config.profile,
             state_dir: config.stateDir,
             state_file: resolveCurrentStateFile(),
+            quarantined_stale_identity: peekQuarantineNotice(),
             summary: {
                 connected: !!state.identity,
                 activated: !!state.identity?.activated_at,
@@ -1058,6 +1518,7 @@ async function handleStatus(args) {
         profile: config.profile,
         state_dir: config.stateDir,
         state_file: resolveCurrentStateFile(),
+        quarantined_stale_identity: peekQuarantineNotice(),
         summary: {
             connected: !!state.identity,
             activated: !!installation.installation?.activated_at,
@@ -1090,7 +1551,13 @@ async function handleDoctor(args) {
         session_key: null,
     };
     let openClawStateDirValidation = null;
-    if (!state.identity) {
+    // OAuth 多租户模式（Codex / Claude Code 走 /mcp）下，state.identity 故意是 null —— 真
+    // 身份由请求 bearer 决定，没有"per-process 单一 identity"概念（见 createAuthorizedClients
+    // 注释）。doctor 在这种模式下 fallback 走 remote probe 判断 connected/activated，不再把
+    // state.identity 缺失算 blocker，否则每次 hi_agent_install 末尾跑 doctor 都会拿到
+    // `missing_agent_identity` 的假阳性，把刚成功的 OAuth install 标成 fail。
+    const oauthDoctorAuth = config.authMode === 'oauth' ? getCurrentRequestAuth() : null;
+    if (!state.identity && !oauthDoctorAuth) {
         blockers.push('missing_agent_identity');
     }
     if (installState.host_kind === 'openclaw') {
@@ -1107,7 +1574,9 @@ async function handleDoctor(args) {
             }
         }
     }
-    if (includeRemote && state.identity) {
+    // OAuth 模式下 state.identity 是 null 也照样有真身份（bearer 在 request 上），所以
+    // 这里的 gate 用 "有 oauth bearer 或者有本地 identity" 表示"能拿到远端".
+    if (includeRemote && (state.identity || oauthDoctorAuth)) {
         try {
             const { gateway } = await createAuthorizedClients();
             const [me, installation, endpoints, subscriptions] = await Promise.all([
@@ -1122,6 +1591,23 @@ async function handleDoctor(args) {
                 endpoints: endpoints.endpoints,
                 subscriptions: subscriptions.subscriptions,
             };
+            // 2026-05：身份分叉检测。server-side admin consolidate / agentMerge 之后，
+            // agent_installations.agent_id 会被改成 target；但本地 state.identity.agent_id
+            // 还是 merge 前快照——客户端没机制知道自己被合并掉了。表现是 LLM 看到 "我以为
+            // 是 ag_X 但 /me 说我是 ag_Y" 然后开始反复 reset / re-login / 再造孤儿。
+            //
+            // 这里把三个 agent_id 都拉出来对比，任何一对不一致就直接 blocker。提示客户端
+            // 调 hi_agent_state_resync 把本地刷成 remote canonical（不是新 register，那会
+            // 再造一个孤儿）。OAuth 模式下 state.identity 永远是 null，这条 blocker 自动跳过。
+            const localAgentId = normalizeText(state.identity?.agent_id) || null;
+            const remoteMeAgentId = normalizeText(me?.agent?.agent_id) || null;
+            const remoteInstallationAgentId = normalizeText(installation.installation?.agent_id) || null;
+            if (localAgentId && remoteMeAgentId && localAgentId !== remoteMeAgentId) {
+                blockers.push(`agent_identity_split:local=${localAgentId},remote_me=${remoteMeAgentId},remote_installation=${remoteInstallationAgentId || 'unknown'}`);
+            }
+            else if (remoteMeAgentId && remoteInstallationAgentId && remoteMeAgentId !== remoteInstallationAgentId) {
+                warnings.push(`remote_agent_id_mismatch:me=${remoteMeAgentId},installation=${remoteInstallationAgentId}`);
+            }
             const declaration = installation.installation.delivery_capabilities || null;
             const defaultReplyRoute = isPlainObject(declaration?.default_reply_route)
                 ? declaration.default_reply_route
@@ -1239,8 +1725,27 @@ async function handleInstall(args) {
         ? await maybeMigrateLegacyState()
         : { migrated: false, from: null, to: resolveCurrentStateFile() };
     let state = await loadPersistedState();
+    // OAuth 多租户模式（Codex / Claude Code 远程 MCP）下，agent 在 `codex mcp login hi`
+    // 这一步就已经被 ensureRemoteOAuthAgentConnection 建好 + 激活了——/mcp 请求带过来的
+    // bearer 已经绑到一条真实存在的 active agent。再走 handleRegister 会在 hi-platform
+    // 多开一条 agent 记录（partial install / activated_at=null），admin panel 看到的就是
+    // "Hi OAuth agent xxx + Codex Hi Agent xxx" 两条；同时邀请归因（channel_code）会被
+    // 写到那条 ghost 上，真正在用的 OAuth agent 完全没有 inviter 归属。
+    //
+    // 修复：OAuth 模式下跳过 handleRegister / handleActivate，把 metadata（含
+    // channel_code）顺到下面那次 gateway.updateInstallation 调用里。gateway
+    // 的 updateAgentInstallation 会把 installation metadata 里的 channel_code
+    // 提升到 agents.metadata_json，admin 现有归因 query 不动也能拿到。
+    const oauthInstallAuth = config.authMode === 'oauth' ? getCurrentRequestAuth() : null;
+    // Snapshot the identity BEFORE handleRegister/handleActivate run so that if
+    // the trailing gateway.updateInstallation call fails, we can roll back to
+    // the actual pre-install baseline. Capturing it any later (e.g. just before
+    // updateInstallation) is a no-op rollback on fresh installs — the snapshot
+    // would be the already-persisted just-registered identity, and the retry
+    // would short-circuit register and loop on the same updateInstallation 404.
+    const preInstallIdentitySnapshot = state.identity;
     let registerPayload = null;
-    if (!state.identity) {
+    if (!oauthInstallAuth && !state.identity) {
         const displayName = resolveInstallDisplayName({
             explicitDisplayName: args.display_name,
             hostKind,
@@ -1249,6 +1754,10 @@ async function handleInstall(args) {
             display_name: displayName,
             agent_kind: normalizeText(args.agent_kind) || undefined,
             replace_existing_state: args.replace_existing_state === true,
+            // metadata 必须透传到 register：渠道归因（如 channel_code）走这条路径
+            // 落进 hi-platform 的 agents.metadata_json，被 admin panel 反查邀请人。
+            // 历史 bug：之前这里漏了 metadata，导致 hi_agent_install 的入参直接被吞。
+            metadata: isPlainObject(args.metadata) ? args.metadata : undefined,
         });
         if (registerResult.isError)
             return registerResult;
@@ -1257,11 +1766,57 @@ async function handleInstall(args) {
             : null;
         state = await loadPersistedState();
     }
+    // Helper: roll the on-disk identity back to whatever we held BEFORE this
+    // hi_agent_install turn touched anything. Used by any failure between
+    // handleRegister/handleActivate/updateInstallation and a successful end —
+    // each of those steps can throw if the gateway 404s (the
+    // sub-vs-installation_subject contract mismatch in OAuth multi-tenant mode
+    // means the just-registered installation isn't visible to the bearer that
+    // tries to mutate it). On a fresh install preInstallIdentitySnapshot is
+    // null, so rollback clears identity and the next install retry starts
+    // cleanly from register. On a re-install we restore the prior identity.
+    async function rollbackInstallIdentity() {
+        try {
+            await persistState((current) => ({
+                ...current,
+                identity: preInstallIdentitySnapshot,
+                runtime: { ...current.runtime, updated_at: new Date().toISOString() },
+            }));
+            return true;
+        }
+        catch (rollbackError) {
+            process.stderr.write(`[hi-mcp] install rollback failed: ${String(rollbackError)}\n`);
+            return false;
+        }
+    }
+    function buildInstallStepFailure(stepName, errorMessage, rolledBack) {
+        return fail('install_step_failed', {
+            step: stepName,
+            cause: errorMessage,
+            rolled_back_local_identity: rolledBack,
+            hint: `${stepName} failed against the gateway; local identity has been ${rolledBack ? 'restored to its pre-install baseline' : 'left in an inconsistent state — clear with hi_agent_reset before retrying'}. Any gateway-side agent / installation rows created earlier this turn become orphans (tracked as a TODO in the multi-tenant install path).`,
+        });
+    }
     let activatePayload = null;
-    if (state.identity && !state.identity.activated_at) {
-        const activateResult = await handleActivate({});
-        if (activateResult.isError)
-            return activateResult;
+    // OAuth 模式同样跳过 activate —— OAuth agent 在 token 兑换那一刻就是 active 的，
+    // 再走一遍 /v1/agents/activate 既无意义也会拿不到 state.identity 一路 throw。
+    if (!oauthInstallAuth && state.identity && !state.identity.activated_at) {
+        let activateResult;
+        try {
+            activateResult = await handleActivate({});
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const rolledBack = await rollbackInstallIdentity();
+            return buildInstallStepFailure('activate', message, rolledBack);
+        }
+        if (activateResult.isError) {
+            const rolledBack = await rollbackInstallIdentity();
+            const innerErr = isPlainObject(activateResult.structuredContent)
+                ? activateResult.structuredContent.error
+                : undefined;
+            return buildInstallStepFailure('activate', String(innerErr || 'activate_failed'), rolledBack);
+        }
         activatePayload = isPlainObject(activateResult.structuredContent)
             ? activateResult.structuredContent
             : null;
@@ -1292,9 +1847,46 @@ async function handleInstall(args) {
         routeMissingPolicy,
         defaultReplyRoute,
     });
-    const updatedInstallation = await gateway.updateInstallation({
-        delivery_capabilities: desiredDeliveryCapabilities,
-    });
+    let mergedInstallMetadata = null;
+    if (oauthInstallAuth && isPlainObject(args.metadata) && Object.keys(args.metadata).length > 0) {
+        // gateway 的 updateAgentInstallation 把 metadata 当作"整字段 patch"——给了就替换、
+        // 不给就保留——见 mergeInstallationMetadata。OAuth installation 上本来就有
+        // {provisioned_by, oauth_client_id, oauth_scope, oauth_audience} 这些 bookkeeping
+        // 字段（ensureRemoteOAuthAgentConnection 写的），直接 PUT {channel_code: X} 会把它们
+        // 全冲掉。所以这里先拉一次 installation 把现有 metadata 取出来，再浅合并写回。
+        try {
+            const existingInstallation = await gateway.getInstallation();
+            const existing = isPlainObject(existingInstallation?.installation?.metadata)
+                ? existingInstallation.installation.metadata
+                : {};
+            mergedInstallMetadata = { ...existing, ...args.metadata };
+        }
+        catch (error) {
+            // 拉不到现有 installation 不应该阻断 install——退化成只写 caller 传的 metadata，
+            // 最坏情况只是 oauth bookkeeping 字段被清空，gateway 仍然能从 agent_installations 行
+            // 重新推导身份。channel_code 仍然落到 installation 上，归因 query 不受影响。
+            process.stderr.write(`[hi-mcp] failed to fetch existing installation metadata before update: ${String(error)}\n`);
+            mergedInstallMetadata = { ...args.metadata };
+        }
+    }
+    let updatedInstallation;
+    try {
+        // OAuth 路径下把 install metadata（含 channel_code 渠道归因）顺过来 ——
+        // 不再走 register，更新存量 OAuth installation 的 metadata 是唯一落点。
+        // gateway 端 updateAgentInstallation 会把白名单键（channel_code）再 promote 到
+        // agents.metadata_json，admin panel 的归因 query 沿用原路径。
+        // OpenClaw 路径下，metadata 已经在 handleRegister 里写过 agent + installation 了，
+        // 这里就不再重复透传，避免把 install metadata patch 成空 / 覆盖既有值。
+        updatedInstallation = await gateway.updateInstallation({
+            delivery_capabilities: desiredDeliveryCapabilities,
+            ...(mergedInstallMetadata ? { metadata: mergedInstallMetadata } : {}),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const rolledBack = await rollbackInstallIdentity();
+        return buildInstallStepFailure('update_installation', message, rolledBack);
+    }
     await persistState((current) => ({
         ...current,
         identity: current.identity
@@ -1416,18 +2008,84 @@ async function handleInstall(args) {
             include_remote: true,
             probe_delivery: enableLocalReceiver,
         });
+    // 2026-05：post-install welcome onboarding。
+    //
+    // 业界 SaaS / 对话式 AI onboarding 共识（Build context, Ask intent EARLY, Show populated
+    // state preview, Single clear next action）+ 我们 prod 数据观察（10 个新装 owner 里只有
+    // 一半发了 friendship listing，剩下一半实际意图是招聘 / 找房 / 合伙人）共同推出的同步
+    // welcome 路径——install 末尾立即把"问 owner 想找什么样的人"的 instruction + 跨频道
+    // recent_activity preview + intent_options 选项嵌入工具 result。
+    //
+    // 同步路径的目的是让**新装**用户一气呵成不依赖 push 链路（push worker 5-15 秒才扫到）。
+    // **存量**用户由 platform 端 bootstrapOnboardingFanOutWorker 异步覆盖；两路 dedup 信号
+    // 是 owner listing 状态（push instruction 里明确要求收到时先调 agent_listings.list）。
+    //
+    // 失败 fail-soft：拉 recent_activity 的 capability 调用任何环节失败都不影响 install
+    // 主流程返回 ok（welcome 是 instruction + intent_options 为核心，recent_activity 只是
+    // populated state 增强）。welcome.recent_activity_error 字段把失败原因留给 LLM 知道。
+    let welcome = null;
+    try {
+        // 仅在 doctor pass 之后才做 welcome：identity 没建好 / installation 没激活时
+        // 调 capability 必然 401/403，没意义且会污染 install result。
+        const doctorBody = doctor?.structuredContent;
+        const doctorOk = !!(doctorBody && doctorBody.ok && doctorBody.activated);
+        if (doctorOk) {
+            let recentActivity = [];
+            let recentActivityError = null;
+            try {
+                const { platform } = await createAuthorizedClients();
+                const callResult = await platform.callCapability('hi.agent-listings', {
+                    action: 'browse_recent',
+                    limit: 8,
+                });
+                const items = callResult?.result?.items;
+                if (Array.isArray(items)) {
+                    recentActivity = items
+                        .filter((it) => it && typeof it === 'object')
+                        .map((it) => ({
+                        listing_id: String(it.listing_id || ''),
+                        listing_type_id: String(it.listing_type_id || ''),
+                        published_by_agent_id: String(it.published_by_agent_id || ''),
+                        target_preview_text: String(it.target_preview_text || ''),
+                        listing_created_at: String(it.listing_created_at || ''),
+                    }))
+                        .filter((it) => it.listing_id && it.target_preview_text);
+                }
+                else {
+                    recentActivityError = 'browse_recent_returned_no_items_array';
+                }
+            }
+            catch (err) {
+                recentActivityError = String(err?.message || err || 'browse_recent_failed').slice(0, 240);
+            }
+            welcome = {
+                kind: INSTALL_WELCOME_ONBOARDING_KIND,
+                instruction_to_llm: INSTALL_WELCOME_ONBOARDING_INSTRUCTION,
+                recent_activity: recentActivity,
+                intent_options: [...DEFAULT_INTENT_OPTIONS],
+                ...(recentActivityError ? { recent_activity_error: recentActivityError } : {}),
+            };
+        }
+    }
+    catch {
+        // welcome 整体失败也 fail-soft：install 主流程返回 ok=true，welcome=null 让 LLM
+        // fallback 到自然行为（拿到 install ok 后给 owner 一句"装好了"），不阻断 install。
+        welcome = null;
+    }
     return ok({
         ok: true,
         profile: config.profile,
         state_dir: config.stateDir,
         state_file: resolveCurrentStateFile(),
         migrated_legacy_state: migration,
+        quarantined_stale_identity: peekQuarantineNotice(),
         register: registerPayload,
         activate: activatePayload,
         installation: updatedInstallation,
         subscriptions: subscriptionsPayload,
         receiver: receiverPayload,
         doctor: doctor?.structuredContent || null,
+        welcome,
     });
 }
 async function handleReset(args) {
@@ -1654,7 +2312,7 @@ async function handleEventsWait(args) {
 async function handleCapabilityTool(name, args) {
     const { platform } = await createAuthorizedClients();
     const capabilities = await loadCapabilities();
-    const capability = capabilities.find((item) => item.tool_name === name);
+    const capability = capabilities.find((item) => item.tool_name === name && isToolVisibleOnSurface(item.tool_name));
     if (!capability)
         return fail('unknown_hi_capability_tool', { name });
     const out = await platform.callCapability(capability.capability_id, args);
@@ -1662,8 +2320,8 @@ async function handleCapabilityTool(name, args) {
         ok: true,
         capability_id: capability.capability_id,
         tool_name: capability.tool_name,
-        result: out.result,
-    }, jsonText(out));
+        result: out.result ?? null,
+    });
 }
 async function handleControlTool(name, args) {
     switch (name) {
@@ -1677,10 +2335,16 @@ async function handleControlTool(name, args) {
             return await handleReset(args);
         case 'hi_agent_register':
             return await handleRegister(args);
+        case 'hi_agent_state_resync':
+            return await handleStateResync(args);
         case 'hi_agent_connect':
             return await handleConnect(args);
         case 'hi_agent_activate':
             return await handleActivate(args);
+        case 'hi_agent_claim_export':
+            return await handleClaimExport(args);
+        case 'hi_agent_claim_redeem':
+            return await handleClaimRedeem(args);
         case 'hi_agent_installation_get':
             return await handleInstallationGet();
         case 'hi_agent_installation_update':
@@ -1707,11 +2371,78 @@ async function handleControlTool(name, args) {
             return fail('unknown_control_tool', { name });
     }
 }
+// MCP tool annotations for hi-mcp-server's hi_agent_* control tools.
+// OpenAI Apps SDK review hard-requires readOnlyHint/openWorldHint/
+// destructiveHint on every tool surfaced by an MCP server; Missing on any
+// of these blocks Submit. Business tools get their annotations from the
+// hi-platform public capability catalog (forwarded below); the control
+// tools are defined locally here so the annotations live here too.
+//
+// Semantics:
+//   readOnlyHint:    only reads server state, no mutation
+//   openWorldHint:   reaches outside Hi's own systems (real people via SMS/
+//                    webhook, real phone calls, third-party APIs, etc.)
+//   destructiveHint: effect is non-reversible (data wipe, message that can't
+//                    be unsent). Only meaningful when readOnlyHint=false.
+const CONTROL_TOOL_ANNOTATIONS = {
+    // Pure local-state reads. Even include_remote:true is a read-only GET
+    // against the gateway.
+    hi_agent_status: { readOnlyHint: true, openWorldHint: false, destructiveHint: false, title: 'Hi agent status' },
+    // Creates a new agent identity, writes local state, optionally starts a
+    // local receiver. All effects stay inside Hi infrastructure.
+    hi_agent_install: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Hi agent install' },
+    // Diagnostic. probe_delivery sends a synthetic test event targeting the
+    // agent's own configured route; not third-party-visible.
+    hi_agent_doctor: { readOnlyHint: true, openWorldHint: false, destructiveHint: false, title: 'Hi agent doctor' },
+    // Wipes local persisted identity + state. Non-recoverable for this profile.
+    hi_agent_reset: { readOnlyHint: false, openWorldHint: false, destructiveHint: true, title: 'Hi agent reset' },
+    // Creates a brand new agent + installation at the gateway. Additive.
+    hi_agent_register: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Hi agent register' },
+    // Reads gateway /me + /installation and patches local state.identity to match.
+    // Pure local-state write; no gateway mutation. Idempotent.
+    hi_agent_state_resync: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Hi agent state resync' },
+    // Binds local profile to an existing remote agent_id. Additive.
+    hi_agent_connect: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Hi agent connect' },
+    // Activates the installation. Additive.
+    hi_agent_activate: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Hi agent activate' },
+    hi_agent_claim_export: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Claim export' },
+    hi_agent_claim_redeem: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Claim redeem' },
+    hi_agent_installation_get: { readOnlyHint: true, openWorldHint: false, destructiveHint: false, title: 'Installation get' },
+    hi_agent_installation_update: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Installation update' },
+    hi_agent_endpoints_list: { readOnlyHint: true, openWorldHint: false, destructiveHint: false, title: 'Endpoints list' },
+    hi_agent_endpoints_upsert: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Endpoints upsert' },
+    hi_agent_subscriptions_list: { readOnlyHint: true, openWorldHint: false, destructiveHint: false, title: 'Subscriptions list' },
+    hi_agent_subscriptions_upsert: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Subscriptions upsert' },
+    // Sends a test event through the configured delivery profile, which may
+    // hit a public webhook URL the operator registered. Treat as open-world.
+    hi_agent_test_delivery: { readOnlyHint: false, openWorldHint: true, destructiveHint: false, title: 'Test delivery' },
+    // Acquires a queue lease on the durable event queue. Changes server-side
+    // lease state but not externally observable / not destructive.
+    hi_agent_events_claim: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Events claim' },
+    // Read a claimed event's payload. Pure read.
+    hi_agent_event_fetch: { readOnlyHint: true, openWorldHint: false, destructiveHint: false, title: 'Event fetch' },
+    // Advances persisted cursor + marks events consumed. Not destructive
+    // (consumer-side commit is expected normal operation).
+    hi_agent_events_ack: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Events ack' },
+    // Long-poll claim + optional auto-ack. Changes queue state via ack.
+    hi_agent_events_wait: { readOnlyHint: false, openWorldHint: false, destructiveHint: false, title: 'Events wait' },
+};
 async function listTools() {
     const capabilities = await loadCapabilities();
+    const toolSurface = effectiveToolSurface();
+    const controlSurfaceTools = toolSurface === 'chatgpt_app' ? [] : controlTools();
+    const capabilitySurfaceTools = capabilities.filter((capability) => isToolVisibleOnSurface(capability.tool_name));
     return [
-        ...controlTools(),
-        ...capabilities.map((capability) => ({
+        ...controlSurfaceTools.map((tool) => ({
+            ...tool,
+            // Annotations are required by OpenAI Apps SDK review. Default to a
+            // conservative "false / false / false" if a control tool ever gets
+            // added here without an entry in CONTROL_TOOL_ANNOTATIONS, so review
+            // still passes (the human reviewer can audit the conservative fallback).
+            annotations: CONTROL_TOOL_ANNOTATIONS[tool.name]
+                || { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        })),
+        ...capabilitySurfaceTools.map((capability) => ({
             name: capability.tool_name,
             title: capability.title || capability.tool_name,
             description: capability.description || capability.tool_name,
@@ -1719,13 +2450,19 @@ async function listTools() {
             inputSchema: isPlainObject(capability.parameters)
                 ? capability.parameters
                 : { type: 'object', properties: {} },
+            outputSchema: CAPABILITY_TOOL_OUTPUT_SCHEMA,
+            // Business tools get their annotations from hi-platform's catalog
+            // (set in hi-platform/src/mcp/schema/tools.ts). Fall back to a
+            // conservative default for any capability missing them.
+            annotations: capability.annotations
+                || { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
         })),
     ];
 }
 function createMcpServer() {
     const server = new Server({
         name: 'hi-mcp-server',
-        version: '0.1.7',
+        version: pkgJson.version,
     }, {
         capabilities: {
             tools: {},
@@ -1741,6 +2478,12 @@ function createMcpServer() {
         const name = normalizeText(request.params.name);
         const args = normalizeRecord(request.params.arguments);
         try {
+            if (!isToolVisibleOnSurface(name)) {
+                return fail('tool_not_available_on_surface', {
+                    name,
+                    tool_surface: effectiveToolSurface(),
+                });
+            }
             const controlToolNames = new Set(controlTools().map((tool) => tool.name));
             return controlToolNames.has(name)
                 ? await handleControlTool(name, args)
@@ -1752,13 +2495,171 @@ function createMcpServer() {
     });
     return server;
 }
+async function handleMcpRequest(req, res) {
+    const server = createMcpServer();
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+    });
+    try {
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+        res.on('close', () => {
+            void transport.close().catch(() => undefined);
+            void server.close().catch(() => undefined);
+        });
+    }
+    catch (error) {
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: normalizeText(error?.message) || 'internal_server_error',
+                },
+                id: null,
+            });
+        }
+    }
+}
 async function runHttpServer() {
     const app = createMcpExpressApp({ host: config.host });
+    // CORS — every request gets permissive headers + preflight short-circuit.
+    // Why: claude.ai's web connector (and other browser-based MCP UIs) talks
+    // to /mcp from a https://claude.ai origin. Without these the browser
+    // silently drops responses; the connector reports a generic "Couldn't
+    // reach the MCP server" error even though the server is reachable.
+    // Bearer-auth-only, no cookies, so wildcard origin is safe (we cannot
+    // combine `*` with credentials, which we never set).
+    // WWW-Authenticate MUST be in Expose-Headers so browser JS can read the
+    // RFC 9728 resource_metadata hint on a 401 and start the OAuth flow.
+    app.use((req, res, next) => {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, Accept, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID');
+        res.setHeader('Access-Control-Expose-Headers', 'WWW-Authenticate, Mcp-Session-Id, Mcp-Protocol-Version');
+        res.setHeader('Access-Control-Max-Age', '86400');
+        res.setHeader('Vary', 'Origin');
+        if (req.method === 'OPTIONS') {
+            res.status(204).end();
+            return;
+        }
+        next();
+    });
+    // RFC 9728 — Protected Resource Metadata. Codex / Claude Code discover
+    // the Authorization Server from here after the first 401 challenge.
+    // Public surface, no auth, cached briefly.
+    //
+    // Multi-host: each configured resource URL gets its own PRM payload so a
+    // request that arrives via mcp.hirey.ai sees `resource:
+    // "https://mcp.hirey.ai/mcp"` while a request via the legacy
+    // hi.hirey.ai alias sees `resource: "https://hi.hirey.ai/mcp"`. The
+    // alternative — a single PRM advertising the canonical URL on the alias
+    // host — fails RFC 9728 §3.3 strict clients (Codex included) because the
+    // resource URL no longer matches the host that served the metadata.
+    const protectedResourceMetadataPath = '/.well-known/oauth-protected-resource';
+    const oauthResourceTable = config.authMode === 'oauth'
+        ? config.oauthMcpResources.map((resourceUrl) => {
+            const trimmed = resourceUrl.replace(/\/+$/, '');
+            const baseNoMcp = trimmed.replace(/\/mcp$/, '');
+            const host = new URL(resourceUrl).host.toLowerCase();
+            return {
+                resource: resourceUrl,
+                host,
+                protectedResourceMetadataUrl: `${baseNoMcp}${protectedResourceMetadataPath}`,
+                metadata: buildProtectedResourceMetadata({
+                    resource: resourceUrl,
+                    authorizationServer: config.oauthAuthorizationServer,
+                    scopes: config.oauthScopesSupported,
+                    resourceDocumentationUrl: `${config.platformBaseUrl.replace(/\/+$/, '')}/docs/mcp`,
+                }),
+            };
+        })
+        : [];
+    // Pick the resource entry whose hostname matches the inbound request, so
+    // a 401 challenge served on mcp.hirey.ai points back at
+    // mcp.hirey.ai/.well-known/oauth-protected-resource. Falls back to the
+    // primary (index 0) when the request host isn't in the table — that path
+    // matters for direct cluster-internal probes and dev curl calls without
+    // a Host header.
+    function resolveOAuthResource(req) {
+        if (oauthResourceTable.length === 0)
+            return null;
+        const hostHeader = String(req.headers.host || '').toLowerCase().split(':')[0];
+        return oauthResourceTable.find((e) => e.host === hostHeader) || oauthResourceTable[0];
+    }
+    if (config.authMode === 'oauth') {
+        app.get(protectedResourceMetadataPath, (req, res) => {
+            const entry = resolveOAuthResource(req);
+            if (!entry) {
+                res.status(503).json({ error: 'oauth_resource_unconfigured' });
+                return;
+            }
+            res.setHeader('Cache-Control', 'public, max-age=300');
+            res.json(entry.metadata);
+        });
+        const authorizationServerMetadataAlias = buildAuthorizationServerMetadataAlias({
+            issuer: config.oauthIssuer,
+            authorizationServer: config.oauthAuthorizationServer,
+            scopes: config.oauthScopesSupported,
+            serviceDocumentationUrl: `${config.oauthAuthorizationServer.replace(/\/+$/, '')}/docs/oauth`,
+        });
+        for (const metadataPath of [
+            '/.well-known/oauth-authorization-server',
+            '/.well-known/oauth-authorization-server/mcp',
+            '/.well-known/oauth-authorization-server/mcp/chatgpt',
+            '/mcp/.well-known/oauth-authorization-server',
+            '/mcp/chatgpt/.well-known/oauth-authorization-server',
+        ]) {
+            app.get(metadataPath, (_req, res) => {
+                res.setHeader('Cache-Control', 'public, max-age=300');
+                res.json(authorizationServerMetadataAlias);
+            });
+        }
+    }
+    // Per-request OAuth verifier — JWKS is cached inside the closure so we
+    // pay the network round trip once, not per request. Skipped entirely in
+    // 'local' mode so stdio + legacy installs incur zero overhead.
+    const oauthVerifier = config.authMode === 'oauth'
+        ? buildOAuthVerifier({
+            // JWT `iss` check — must match what hi-auth signs into tokens. In
+            // prod this is the legacy issuer (hi.hirey.ai) so OpenClaw and
+            // every other client_credentials caller keep working. Discovery
+            // metadata can live on a different host (oauthAuthorizationServer).
+            issuer: config.oauthIssuer,
+            // Audience check accepts ANY of the configured resource URLs.
+            // jose.jwtVerify with array audience matches if at least one is
+            // present in the token's `aud` claim (RFC 7519 §4.1.3).
+            audience: config.oauthMcpResources,
+        })
+        : null;
+    function send401(req, res, description, error = 'invalid_token') {
+        if (config.authMode === 'oauth') {
+            const entry = resolveOAuthResource(req);
+            const challenge = buildWwwAuthenticateChallenge({
+                protectedResourceMetadataUrl: entry?.protectedResourceMetadataUrl || '',
+                scope: config.oauthScopesSupported,
+                error,
+                errorDescription: description,
+            });
+            res.setHeader('WWW-Authenticate', challenge);
+        }
+        res.status(401).json({
+            jsonrpc: '2.0',
+            error: {
+                code: -32001,
+                message: error,
+                ...(description ? { data: { description } } : {}),
+            },
+            id: null,
+        });
+    }
     app.get('/healthz', (_req, res) => {
         res.json({
             ok: true,
             profile: config.profile,
             transport: config.transport,
+            auth_mode: config.authMode,
+            tool_surface: config.toolSurface,
         });
     });
     // readiness 必须确认上游 discovery 可达；否则 pod 虽然活着，但实际上没法服务真实 MCP 请求。
@@ -1769,6 +2670,8 @@ async function runHttpServer() {
                 ok: true,
                 profile: config.profile,
                 transport: config.transport,
+                auth_mode: config.authMode,
+                tool_surface: config.toolSurface,
                 registry_base_url: wellKnown.platform.registry_base_url,
             });
         }
@@ -1779,52 +2682,61 @@ async function runHttpServer() {
             });
         }
     });
-    app.post('/mcp', async (req, res) => {
-        const server = createMcpServer();
-        const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: undefined,
+    function runMcpRequest(req, res, toolSurface) {
+        requestToolSurfaceStorage.run(toolSurface, () => {
+            void handleMcpRequest(req, res);
         });
-        try {
-            await server.connect(transport);
-            await transport.handleRequest(req, res, req.body);
-            res.on('close', () => {
-                void transport.close().catch(() => undefined);
-                void server.close().catch(() => undefined);
-            });
-        }
-        catch (error) {
-            if (!res.headersSent) {
-                res.status(500).json({
-                    jsonrpc: '2.0',
-                    error: {
-                        code: -32603,
-                        message: normalizeText(error?.message) || 'internal_server_error',
-                    },
-                    id: null,
-                });
+    }
+    async function handleMcpPost(req, res, toolSurface = null) {
+        // OAuth-mode bearer enforcement. Stdio path and 'local' HTTP path keep
+        // the existing single-tenant disk identity model untouched.
+        if (config.authMode === 'oauth' && oauthVerifier) {
+            const outcome = await verifyRequestBearer(req, oauthVerifier);
+            if (!outcome.ok) {
+                return send401(req, res, outcome.description);
             }
+            requestAuthStorage.run(outcome.auth, () => {
+                runMcpRequest(req, res, toolSurface);
+            });
+            return;
         }
+        runMcpRequest(req, res, toolSurface);
+    }
+    // Dedicated ChatGPT App / Apps SDK review surface. Keep `/mcp` as the
+    // full Codex/OpenClaw/Claude-compatible endpoint so existing remote MCP
+    // users do not lose onboarding and event tools.
+    app.post('/mcp/chatgpt', async (req, res) => {
+        await handleMcpPost(req, res, 'chatgpt_app');
     });
-    app.get('/mcp', (_req, res) => {
-        res.status(405).json({
-            jsonrpc: '2.0',
-            error: {
-                code: -32000,
-                message: 'Method not allowed.',
-            },
-            id: null,
-        });
+    app.post('/mcp', async (req, res) => {
+        await handleMcpPost(req, res);
     });
-    app.delete('/mcp', (_req, res) => {
+    // A GET/DELETE to the MCP endpoint targets a protected resource. When the
+    // request is unauthenticated in oauth mode, answer with the 401 +
+    // WWW-Authenticate challenge — same as the POST path — so a client that
+    // probes the endpoint via GET (rather than an initialize POST) can still
+    // discover the OAuth protected-resource metadata, instead of bouncing off a
+    // bare 405 that hides the auth requirement. The streamable-HTTP transport is
+    // stateless and only serves POST, so an *authenticated* GET/DELETE still
+    // legitimately gets 405 (method not allowed for this transport).
+    const methodNotAllowed = (res) => {
         res.status(405).json({
             jsonrpc: '2.0',
-            error: {
-                code: -32000,
-                message: 'Method not allowed.',
-            },
+            error: { code: -32000, message: 'Method not allowed.' },
             id: null,
         });
-    });
+    };
+    const challengeOrMethodNotAllowed = async (req, res) => {
+        if (config.authMode === 'oauth' && oauthVerifier) {
+            const outcome = await verifyRequestBearer(req, oauthVerifier);
+            if (!outcome.ok) {
+                return send401(req, res, outcome.description);
+            }
+        }
+        methodNotAllowed(res);
+    };
+    app.get(['/mcp', '/mcp/chatgpt'], challengeOrMethodNotAllowed);
+    app.delete(['/mcp', '/mcp/chatgpt'], challengeOrMethodNotAllowed);
     const httpServer = createServer(app);
     await new Promise((resolve) => {
         httpServer.listen(config.port, config.host, () => resolve());