@clawos-dev/clawd 0.2.254 → 0.2.256

package/dist/cli.cjs

@@ -166,6 +166,10 @@ var init_methods = __esm({
       // owner UI 授权 contact 反向操作我的设备（跨设备 exec 开关 remoteAccessAllowed）。
       // 详见 protocol/src/contact-remote-access.ts.
       "contact:setRemoteAccess",
+      // ---- contact:handshake (双向确认建联握手, spec 2026-07-22) ----
+      // device:connect 临时连接调用；被调方同步落库+broadcast 后回 ok（携带身份载荷）。
+      // 替代旧 whoami+auto-reverse 组合；whoami 对 connect-token guest 已封（旧客户端拦截）。
+      "contact:handshake",
       // ---- visitor:* (web 访客 · persona web 分享，spec 2026-06-24-persona-web-share-design) ----
       // owner-only：列出登录访问过本机 public persona 的 web 访客（零安装、飞书登录、daemon 自签
       // visitor token）。存储 ~/.clawd/visitors.json（VisitorStore），登录(exchange)即 upsert；
@@ -5367,13 +5371,13 @@ var init_schemas = __esm({
        * guest 的设备 id / 人 id / 来源全部由 connect token 的 subDevice/subOwner/provider 签名背书
        * （server 签、目标设备本地验签，不可伪造），不再接受任何自报身份。
        *
-       * selfUrl 保留：它只是"可达地址"（auto-reverse 反向连接用），不是身份——填错只影响
-       * 反向连通性，不构成伪造风险，且 url 不在 token 里（token 只签身份不签地址）。
+       * selfUrl 已废弃（spec 2026-07-22 双向确认建联）：可达地址自报移入 contact:handshake
+       * args——auth 层回归纯验票。旧客户端发来的 selfUrl 被 strip（zod 默认），无害；
+       * 旧客户端本身由 whoami 的 connect-token 拒绝路径拦截（CLIENT_OUTDATED）。
        */
-      selfUrl: external_exports.string().min(1).optional(),
       /**
        * 客户端自报的 user-agent 性质标签（诊断/展示用）。
-       * 同 selfUrl 性质的「自报事实」，非身份（决策 #16 边界）：不参与鉴权、不参与路由、
+       * 「自报事实」，非身份（决策 #16 边界）：不参与鉴权、不参与路由、
        * 任何 handler 不得据此做权限判断。name 约定命名（'clawd-desktop' / 'clawd-web' /
        * 'clawd-mobile-android' / ...），宽容未知值（将来加新客户端不动 schema）。
        * instanceId：客户端首启生成 UUID 并本地持久化——区分同种类多实例（多手机/多 desktop 同连）。
@@ -5827,6 +5831,32 @@ var init_contact = __esm({
   }
 });
 
+// ../protocol/src/contact-handshake.ts
+var ContactHandshakeArgsSchema, ContactHandshakeOkSchema;
+var init_contact_handshake = __esm({
+  "../protocol/src/contact-handshake.ts"() {
+    "use strict";
+    init_zod();
+    init_capability();
+    ContactHandshakeArgsSchema = external_exports.object({
+      selfUrl: external_exports.string().min(1)
+    });
+    ContactHandshakeOkSchema = external_exports.object({
+      type: external_exports.literal("contact:handshake:ok"),
+      owner: external_exports.object({
+        /** 被调方 deviceId（路由主键；调用方落 Contact 的主键用自己请求的 args.deviceId，此值供校验/展示） */
+        id: external_exports.string(),
+        /** 归属人（落 Contact.ownerId / provider，显示分组用） */
+        ownerId: external_exports.string(),
+        provider: external_exports.string(),
+        displayName: external_exports.string()
+      }),
+      /** 被调方授调用方的 grants（落 Contact.grants） */
+      grants: external_exports.array(GrantSchema)
+    });
+  }
+});
+
 // ../protocol/src/contact-remote-access.ts
 var ContactSetRemoteAccessArgsSchema, ContactSetRemoteAccessOkSchema, ContactRemoteAccessUpdatedFrameSchema;
 var init_contact_remote_access = __esm({
@@ -6208,7 +6238,13 @@ var init_dispatch = __esm({
       // 合法值集与 claude adapter capabilities.models[].id 一致（见 daemon
       // tools/claude.ts CLAUDE_MODEL_IDS）；handler 层做二次校验，非法值 fail-fast。
       // protocol 层保持 string 便于未来跨 tool 扩展（届时 union 收合法字面量）。
-      model: external_exports.string().min(1).optional()
+      model: external_exports.string().min(1).optional(),
+      // 可选：给新 worker session 起 label（写入 SessionFile.label，sidebar 显示）。
+      // 仅在**新开 dispatch**（dispatchId 缺席）时生效；续派（dispatchId 非空）
+      // 时 daemon 层静默丢弃（避免半途改 label 造成 sidebar 抖动）。
+      // 上限 60 字符——sidebar 显示 tolerance，卡在 dispatch 入口即可。
+      // 协议层不硬拒 sessionLabel + dispatchId 同传，保留 forward-compat。
+      sessionLabel: external_exports.string().min(1).max(60).optional()
     }).refine((v2) => v2.targetPersona !== void 0 || v2.dispatchId !== void 0, {
       message: "either targetPersona (new dispatch) or dispatchId (follow-up) is required"
     }).refine((v2) => !(v2.dispatchId !== void 0 && v2.targetDeviceId !== void 0), {
@@ -6315,6 +6351,7 @@ var init_runtime = __esm({
     init_capability();
     init_inbox();
     init_contact();
+    init_contact_handshake();
     init_contact_remote_access();
     init_peer_exec();
     init_extension();
@@ -41901,20 +41938,23 @@ var ATTACHMENT_SHARING_HINT = `## \u628A\u4EA7\u51FA\u6587\u4EF6\u5206\u4EAB\u7E
 - \u53EA\u80FD\u5206\u4EAB\u4F60\u81EA\u5DF1\u5DE5\u4F5C\u76EE\u5F55\u5185\u7684\u6587\u4EF6\uFF0C\u8D8A\u754C\u4F1A\u88AB\u62D2\u3002
 - \u88AB dispatch \u63A5\u5230\u4EFB\u52A1\u3001\u8981\u56DE\u4F20\u4EA7\u7269\u65F6\uFF1A\u628A\u7B7E\u540D URL \u5199\u8FDB \`personaDispatchComplete\` tool\uFF08\`clawd-dispatch\` MCP\uFF09\u7684 \`text\` \u91CC\uFF08\`filePaths\` \u53EA\u662F\u4F60\u672C\u673A\u7684\u7EDD\u5BF9\u8DEF\u5F84\uFF0C\u8DE8\u8BBE\u5907\u5BF9\u65B9\u6253\u4E0D\u5F00\uFF0CURL \u624D\u80FD\u6253\u5F00\uFF09\u3002`;
 
+// src/persona/no-ask-user-question-prompt.ts
+var NO_ASK_USER_QUESTION_HINT = `## \u9700\u8981\u8001\u677F\u62CD\u677F\u65F6\u600E\u4E48\u95EE
+
+\u8981\u8001\u677F\u9009\u62E9 / \u786E\u8BA4 / \u62CD\u677F\u65F6\uFF0C\u76F4\u63A5\u6B63\u6587\u5199\u95EE\u9898 + \u5217 A/B/C \u9009\u9879\u3002\u4E0D\u8981\u8C03 AskUserQuestion tool\u3002`;
+
 // src/dispatch/system-prompt.ts
 var DISPATCH_SYSTEM_PROMPT_HINT = `## \u59D4\u6D3E\u7ED9\u53E6\u4E00\u4E2A persona\uFF08dispatch\uFF09
 
-\u5F53\u7528\u6237\u6D88\u606F\u91CC\u542B \`@persona/<id>\`\uFF08\u5982 \`@persona/persona-app-builder\`\uFF09\u65F6\uFF0C**\u4F60\u5FC5\u987B**\u7ACB\u5373\u8C03 \`clawd-dispatch\` MCP server \u7684 \`personaDispatch\` tool \u59D4\u6D3E\uFF08\u5404 agent \u5BF9 MCP tool \u7684\u5C55\u793A\u540D\u4E0D\u540C\uFF0C\u5982 claude \u663E\u793A\u4E3A \`mcp__clawd-dispatch__personaDispatch\`\uFF1B\u6309\u4F60\u73AF\u5883\u91CC\u5B9E\u9645\u5217\u51FA\u7684\u540D\u5B57\u8C03\u7528\uFF09\uFF0C\u4E0D\u8981\u5C1D\u8BD5\u81EA\u5DF1\u6267\u884C\uFF1A
+\u5F53\u7528\u6237\u6D88\u606F\u91CC\u542B \`@persona/<id>\`\uFF08\u5982 \`@persona/persona-app-builder\`\uFF09\u65F6\uFF0C**\u4F60\u5FC5\u987B**\u7ACB\u5373\u8C03 \`clawd-dispatch\` MCP \u7684 \`personaDispatch\` tool \u59D4\u6D3E\uFF1A
 
 - \`targetPersona = <id>\`\uFF08@ token \u91CC\u7684 persona id\uFF09
 - \`prompt = \u53BB\u6389 @persona/<id> token \u7684\u7528\u6237\u539F\u6587\`
 
-tool \u4F1A**\u7ACB\u5373\u8FD4\u56DE** dispatchId\uFF08\u5F02\u6B65\u59D4\u6D3E\uFF09\uFF0C\u5BF9\u65B9\u4EBA\u683C\u5728\u540E\u53F0\u5E72\u6D3B\u3002\u4F60\u544A\u8BC9\u7528\u6237"\u4EFB\u52A1\u5DF2\u4EA4\u529E"\u5373\u53EF\u7ED3\u675F\u672C\u8F6E\u2014\u2014**\u4E0D\u8981\u7B49\u5F85\u3001\u4E0D\u8981\u8F6E\u8BE2**\u3002\u5BF9\u65B9\u5E72\u5B8C\u540E\uFF0C\u7ED3\u679C\u4F1A\u4F5C\u4E3A\u4E00\u6761\u65B0\u6D88\u606F\u81EA\u52A8\u6CE8\u5165\u56DE\u4F60\u7684 session\uFF0C\u4F60\u5C4A\u65F6\u518D\u7EFC\u5408\u8F6C\u8FBE\u7ED9\u7528\u6237\u3002\u60F3\u67E5\u8FDB\u5C55\u65F6\uFF08\u7528\u6237\u95EE\u8D77\uFF09\u8C03\u540C\u4E00 MCP \u7684 \`personaDispatchList\`\u3002
+\u544A\u8BC9\u7528\u6237"\u4EFB\u52A1\u5DF2\u4EA4\u529E"\u5373\u53EF\u7ED3\u675F\u672C\u8F6E\u3002\u7ED3\u679C\u4F1A\u4F5C\u4E3A\u4E00\u6761\u65B0\u6D88\u606F\u81EA\u52A8\u6CE8\u5165\u56DE\u4F60\u7684 session\uFF0C\u5C4A\u65F6\u518D\u7EFC\u5408\u8F6C\u8FBE\u7ED9\u7528\u6237\u3002\u60F3\u67E5\u8FDB\u5C55\u65F6\uFF08\u7528\u6237\u95EE\u8D77\uFF09\u8C03\u540C\u4E00 MCP \u7684 \`personaDispatchList\`\u3002
 
-- **\u4E0D\u8981**\u5C1D\u8BD5\u81EA\u5DF1\u6267\u884C\uFF08\u4F60\u4E0D\u662F\u90A3\u4E2A persona\uFF09
-- **\u4E0D\u8981** in-place \u6A21\u4EFF\u5BF9\u65B9\u4EBA\u683C \u2014\u2014 dispatch \u662F\u771F\u5207\u5230\u53E6\u4E00\u4E2A\u72EC\u7ACB session
+- **\u4E0D\u8981**\u5C1D\u8BD5\u81EA\u5DF1\u6267\u884C\uFF08\u4F60\u4E0D\u662F\u90A3\u4E2A persona\uFF09\uFF0C\u4E5F\u4E0D\u8981 in-place \u6A21\u4EFF\u5BF9\u65B9\u4EBA\u683C \u2014\u2014 dispatch \u662F\u771F\u5207\u5230\u53E6\u4E00\u4E2A\u72EC\u7ACB session
 - \u4E00\u53E5\u8BDD\u91CC\u591A\u4E2A \`@persona/<id>\` \u65F6\u9009\u7B2C\u4E00\u4E2A\uFF08tool \u4E00\u6B21\u53EA\u5904\u7406\u4E00\u4E2A target\uFF09
-- \u59D4\u6D3E\u5931\u8D25\uFF08tool_result.is_error=true\uFF09\u65F6\u5982\u5B9E\u544A\u8BC9\u7528\u6237\u539F\u56E0\uFF0C**\u4E0D\u8981\u91CD\u8BD5**
 
 ### \u7EED\u6D3E\uFF08\u540C\u4E00\u4EF6\u4E8B\u7684\u540E\u7EED\u6307\u4EE4\uFF09
 
@@ -41922,15 +41962,15 @@ tool \u4F1A**\u7ACB\u5373\u8FD4\u56DE** dispatchId\uFF08\u5F02\u6B65\u59D4\u6D3E
 
 ### \u8DE8\u8BBE\u5907\u59D4\u6D3E\uFF08remote persona\uFF09
 
-\u5F53 @ token \u5F62\u5982 \`@persona/<id>@<deviceId>\`\uFF08\u7B2C\u4E8C\u6BB5\u662F\u8054\u7CFB\u4EBA**\u8BBE\u5907\u7684 deviceId**\uFF0CUI \u9009\u8054\u7CFB\u4EBA\u65F6\u5DF2\u89E3\u6790\u597D\u586B\u5165\uFF09\u65F6\uFF0C\u662F\u628A\u4EFB\u52A1\u59D4\u6D3E\u7ED9\u90A3\u53F0\u8BBE\u5907\u4E0A\u7684 persona\u3002\u9664 targetPersona / prompt \u5916\u518D\u5E26\u4E00\u4E2A\u53C2\u6570\uFF1A
+\u5F53 @ token \u5F62\u5982 \`@persona/<id>@<deviceId>\`\uFF08\u7B2C\u4E8C\u6BB5\u662F\u8054\u7CFB\u4EBA**\u8BBE\u5907\u7684 deviceId**\uFF0CUI \u9009\u8054\u7CFB\u4EBA\u65F6\u5DF2\u89E3\u6790\u597D\u586B\u5165\uFF09\u65F6\uFF0C\u662F\u628A\u4EFB\u52A1\u59D4\u6D3E\u7ED9\u90A3\u53F0\u8BBE\u5907\u4E0A\u7684 persona\u3002\u9664 targetPersona / prompt \u5916\u518D\u5E26\uFF1A
 
 - \`targetDeviceId = <token \u7B2C\u4E8C\u6BB5\u7684 deviceId\uFF0C\u539F\u6837\u586B>\`
 
-deviceId \u76F4\u63A5\u53D6\u81EA token\uFF0C\u4E0D\u8981\u6539\u5199\u6216\u731C\u6D4B\u3002\u5BF9\u65B9\u4E0D\u53EF\u8FBE / \u76EE\u6807 persona \u672A\u516C\u5F00\u4F1A\u5728\u7ED3\u679C\u56DE\u6D41\u65F6\u62A5\u5931\u8D25\uFF0C\u7167\u5E38\u8F6C\u8FF0\u7ED9\u7528\u6237\u5373\u53EF\u3002\u5176\u4F59\u884C\u4E3A\uFF08\u79D2\u56DE dispatchId\u3001\u7ED3\u679C\u81EA\u52A8\u6CE8\u5165\u3001\u5931\u8D25\u4E0D\u91CD\u8BD5\uFF09\u4E0E\u672C\u5730\u59D4\u6D3E\u4E00\u81F4\u3002
+deviceId \u76F4\u63A5\u53D6\u81EA token\uFF0C\u4E0D\u8981\u6539\u5199\u6216\u731C\u6D4B\u3002
 
 ## \u88AB dispatch \u63A5\u5230\u4EFB\u52A1
 
-\u5982\u679C\u4F60\u7684 session \u7B2C\u4E00\u6761 user message \u662F\u4EE5 \`[Dispatched from owner \u2014 another persona session\u59D4\u6D3E\u7ED9\u4F60\u6267\u884C\u4EFB\u52A1]\` \u8D77\u5934\u7684 plain text \u4EFB\u52A1\u5305\uFF0C\u4F60\u662F\u88AB\u53E6\u4E00\u4E2A persona \u59D4\u6D3E\u6765\u5E72\u6D3B\u7684\uFF08\u4EFB\u52A1\u5305\u4E0D\u7528 \`<system-reminder>\` \u5305\u662F\u4E3A\u4E86 reducer dedup \u5DE5\u4F5C\u6B63\u5E38\uFF0C\u89C1 manager.ts buildDispatchTaskPack \u6CE8\u91CA\uFF09\uFF1A
+\u5982\u679C\u4F60\u7684 session \u7B2C\u4E00\u6761 user message \u662F\u4EE5 \`[Dispatched from owner \u2014 another persona session\u59D4\u6D3E\u7ED9\u4F60\u6267\u884C\u4EFB\u52A1]\` \u8D77\u5934\u7684 plain text \u4EFB\u52A1\u5305\uFF0C\u4F60\u662F\u88AB\u53E6\u4E00\u4E2A persona \u59D4\u6D3E\u6765\u5E72\u6D3B\u7684\uFF1A
 
 - \u4EFB\u52A1\u5728 \`Task:\` \u6BB5
 - \u539F\u4F1A\u8BDD\u7684\u5BF9\u8BDD\u5386\u53F2\u5728 \`Source conversation\` \u6BB5\u7ED9\u7684 jsonl \u8DEF\u5F84\u4E0B\uFF1B\u6309\u9700 Read \u5B83\u4E86\u89E3\u4E0A\u4E0B\u6587\uFF08\u4E0D\u5FC5\u8BFB\u5B8C\uFF09
@@ -42095,6 +42135,9 @@ function buildSpawnContext(state, deps) {
   if (daemonUrl) {
     ctx.extraSystemPrompt = (ctx.extraSystemPrompt ? ctx.extraSystemPrompt + "\n\n" : "") + ATTACHMENT_SHARING_HINT;
   }
+  if (meta?.personaMode && (file.tool ?? "claude") === "claude") {
+    ctx.extraSystemPrompt = (ctx.extraSystemPrompt ? ctx.extraSystemPrompt + "\n\n" : "") + NO_ASK_USER_QUESTION_HINT;
+  }
   if (meta?.extraSettings) {
     ctx.extraSettings = meta.extraSettings;
   }
@@ -44727,6 +44770,8 @@ var SessionManager = class {
       } : {},
       // T-20：dispatch model override 落盘（reducer spawn 路径读 SessionFile.model 生成 --model flag）
       ...args.model ? { model: args.model } : {},
+      // butler 顶部入口：dispatch 传下来的 label 落盘，sidebar 显示（否则兜底 cwd-basename）
+      ...args.label ? { label: args.label } : {},
       createdAt: now,
       updatedAt: now
     };
@@ -49384,7 +49429,10 @@ function buildPersonaDispatchHandlers(deps) {
         guestDisplayName: ctx.principal.displayName,
         // T-31: 把 A 的飞书 union_id 透传给 B（connectGuestContext 已把它挂在 principal.feishuUnionId）
         ...ctx.principal.feishuUnionId ? { guestFeishuUnionId: ctx.principal.feishuUnionId } : {},
-        ...args.model ? { model: args.model } : {}
+        ...args.model ? { model: args.model } : {},
+        // butler 顶部入口：peer daemon 若在 forwardToPeer 里传了 sessionLabel（当前
+        // 未接线，作 forward-compat 预留），这里也透给 spawnB
+        ...args.sessionLabel ? { label: args.sessionLabel } : {}
       }).then(() => logger?.info("dispatch.spawnB.ok", { dispatchId: dispatchId2 })).catch((err) => {
         const reason = err instanceof Error ? err.message : String(err);
         logger?.warn("dispatch.spawnB.failed", { dispatchId: dispatchId2, reason });
@@ -49419,7 +49467,9 @@ function buildPersonaDispatchHandlers(deps) {
       sourceSessionId,
       targetPersona,
       prompt: args.prompt,
-      ...args.model ? { model: args.model } : {}
+      ...args.model ? { model: args.model } : {},
+      // butler 顶部入口（spec 2026-07-27）：sessionLabel 落到 SessionFile.label 让 sidebar 显示
+      ...args.sessionLabel ? { label: args.sessionLabel } : {}
     }).then(() => {
       logger?.info("dispatch.spawnB.ok", { dispatchId });
     }).catch((err) => {
@@ -51058,10 +51108,7 @@ var AuthGate = class {
       st.pending = true;
       let r;
       try {
-        r = await this.opts.authenticate(
-          parsed.data.token,
-          parsed.data.selfUrl
-        );
+        r = await this.opts.authenticate(parsed.data.token);
       } finally {
         st.pending = false;
       }
@@ -51165,7 +51212,8 @@ function constantTimeEqual2(a, b2) {
 function ownerContext(ownerPrincipalId, displayName, feishuUnionId) {
   return {
     principal: makeOwnerPrincipal(ownerPrincipalId, displayName, feishuUnionId),
-    grants: [{ resource: { type: "*" }, actions: ["admin"] }]
+    grants: [{ resource: { type: "*" }, actions: ["admin"] }],
+    tokenKind: "owner"
   };
 }
 function connectGuestContext(subDevice, subOwner, provider, displayName) {
@@ -51175,6 +51223,7 @@ function connectGuestContext(subDevice, subOwner, provider, displayName) {
       resource: { ...g2.resource },
       actions: [...g2.actions]
     })),
+    tokenKind: "connect",
     ownerId: subOwner,
     provider
   };
@@ -51186,6 +51235,7 @@ function visitorGuestContext(p2) {
       resource: { ...g2.resource },
       actions: [...g2.actions]
     })),
+    tokenKind: "visitor",
     ownerId: p2.visitorId,
     provider: p2.provider
   };
@@ -51534,6 +51584,7 @@ var ContactStore = class {
 
 // src/contact/connect-remote.ts
 var crypto5 = __toESM(require("crypto"), 1);
+init_protocol();
 var HANDSHAKE_TIMEOUT_MS = 5e3;
 var RPC_TIMEOUT_MS = 5e3;
 async function connectRemote(args) {
@@ -51546,17 +51597,7 @@ async function connectRemote(args) {
     });
     ws.once("error", onError);
   });
-  ws.send(
-    JSON.stringify({
-      type: "auth",
-      token: args.token,
-      // 自动反向（spec 决策 #11）：带本机可达地址时对方反向建联系人；
-      // 缺省时省略字段（不发空串），对方 schema selfUrl 是 .min(1).optional()。
-      // 决策 #16：身份字段（selfPrincipalId/selfDisplayName/selfDeviceId）已删——
-      // 对方从 connect token 签名背书取 deviceId/ownerId/provider，不信自报。
-      ...args.selfUrl ? { selfUrl: args.selfUrl } : {}
-    })
-  );
+  ws.send(JSON.stringify({ type: "auth", token: args.token }));
   await new Promise((resolve6, reject) => {
     const onMessage = (raw) => {
       let f;
@@ -51608,7 +51649,7 @@ async function connectRemote(args) {
         }
         if (f.requestId !== requestId) return;
         ws.off("message", onMessage);
-        if (f.error || f.type?.endsWith(":error")) {
+        if (f.error || f.type === "error" || f.type?.endsWith(":error")) {
           reject(new Error(f.message ?? f.error ?? "rpc error"));
         } else {
           resolve6(f);
@@ -51623,13 +51664,14 @@ async function connectRemote(args) {
     });
   }
   return {
-    whoami: async () => {
-      const f = await call("whoami", {});
+    handshake: async (selfUrl) => {
+      const raw = await call("contact:handshake", { selfUrl });
+      const f = ContactHandshakeOkSchema.parse(raw);
       return {
         ownerId: f.owner.ownerId,
         provider: f.owner.provider,
         displayName: f.owner.displayName,
-        grants: f.capability.grants
+        grants: f.grants
       };
     },
     close: () => {
@@ -51641,43 +51683,6 @@ async function connectRemote(args) {
   };
 }
 
-// src/contact/auto-reverse.ts
-init_protocol();
-async function autoReverseContact(args) {
-  if (!args.selfUrl) return;
-  const now = args.now ?? Date.now;
-  const grants = PERSONAL_CAP_GRANTS.map((g2) => ({
-    resource: { ...g2.resource },
-    actions: [...g2.actions]
-  }));
-  const existing = args.store.get(args.deviceId) ?? void 0;
-  const base = {
-    deviceId: args.deviceId,
-    ownerId: args.ownerId,
-    provider: args.provider,
-    displayName: args.displayName,
-    remoteUrl: args.selfUrl,
-    connectToken: "",
-    grants,
-    addedAt: now(),
-    pinnedAt: existing?.pinnedAt ?? null,
-    remoteAccessAllowed: existing?.remoteAccessAllowed ?? false
-  };
-  args.store.upsert(base);
-  args.broadcast({ type: "contact:added", contact: base });
-  if (!args.exchangeToken) return;
-  let token;
-  try {
-    token = await args.exchangeToken(args.deviceId);
-  } catch {
-    return;
-  }
-  if (!token) return;
-  const upgraded = { ...base, connectToken: token };
-  args.store.upsert(upgraded);
-  args.broadcast({ type: "contact:added", contact: upgraded });
-}
-
 // src/migrations/2026-05-20-flatten-sessions.ts
 var fs36 = __toESM(require("fs"), 1);
 var path37 = __toESM(require("path"), 1);
@@ -55283,6 +55288,45 @@ function buildInboxHandlers(deps) {
 
 // src/handlers/contact.ts
 init_protocol();
+
+// src/contact/auto-reverse.ts
+init_protocol();
+function upsertPeerContact(args) {
+  const now = args.now ?? Date.now;
+  const grants = PERSONAL_CAP_GRANTS.map((g2) => ({
+    resource: { ...g2.resource },
+    actions: [...g2.actions]
+  }));
+  const existing = args.store.get(args.deviceId) ?? void 0;
+  const base = {
+    deviceId: args.deviceId,
+    ownerId: args.ownerId,
+    provider: args.provider,
+    displayName: args.displayName,
+    remoteUrl: args.selfUrl,
+    connectToken: "",
+    grants,
+    addedAt: now(),
+    pinnedAt: existing?.pinnedAt ?? null,
+    remoteAccessAllowed: existing?.remoteAccessAllowed ?? false
+  };
+  args.store.upsert(base);
+  args.broadcast({ type: "contact:added", contact: base });
+  return base;
+}
+async function backfillConnectToken(args) {
+  try {
+    const token = await args.exchangeToken(args.contact.deviceId);
+    if (!token) return;
+    const upgraded = { ...args.contact, connectToken: token };
+    args.store.upsert(upgraded);
+    args.broadcast({ type: "contact:added", contact: upgraded });
+  } catch {
+    return;
+  }
+}
+
+// src/handlers/contact.ts
 function ensureOwner(ctx) {
   if (!ctx || ctx.principal.kind !== "owner") {
     throw new ClawdError(
@@ -55342,10 +55386,49 @@ function buildContactHandlers(deps) {
       }
     };
   };
+  const handshake = async (frame, _client, ctx) => {
+    if (!ctx || ctx.tokenKind !== "connect") {
+      throw new ClawdError(
+        ERROR_CODES.VALIDATION_ERROR,
+        "contact:handshake \u4EC5\u63A5\u53D7 connect-token \u8FDE\u63A5\uFF08\u8BBE\u5907\u4E92\u8FDE\u63E1\u624B\u4E13\u7528\uFF09"
+      );
+    }
+    const { type: _t, requestId: _r, ...rest } = frame;
+    const args = ContactHandshakeArgsSchema.parse(rest);
+    const contact = upsertPeerContact({
+      store: deps.store,
+      broadcast: deps.broadcast,
+      deviceId: ctx.principal.id,
+      ownerId: ctx.ownerId ?? "",
+      provider: ctx.provider ?? "",
+      displayName: ctx.principal.displayName ?? ctx.principal.id,
+      selfUrl: args.selfUrl,
+      now: deps.now
+    });
+    void backfillConnectToken({
+      store: deps.store,
+      broadcast: deps.broadcast,
+      contact,
+      exchangeToken: deps.exchangeToken
+    });
+    return {
+      response: {
+        type: "contact:handshake:ok",
+        owner: {
+          id: deps.ownerPrincipalId,
+          ownerId: deps.ownerId,
+          provider: deps.ownerProvider,
+          displayName: deps.ownerDisplayName
+        },
+        grants: ctx.grants
+      }
+    };
+  };
   return {
     "contact:list": list,
     "contact:pin": pin,
-    "contact:remove": remove
+    "contact:remove": remove,
+    "contact:handshake": handshake
   };
 }
 
@@ -55398,6 +55481,14 @@ function buildWhoamiHandler(deps) {
     if (!ctx) {
       throw new ClawdError(ERROR_CODES.INTERNAL, "whoami: missing ConnectionContext");
     }
+    if (ctx.tokenKind === "connect") {
+      return {
+        response: {
+          type: "whoami:error",
+          message: "CLIENT_OUTDATED: \u8BF7\u5347\u7EA7\u672C\u673A clawd \u540E\u91CD\u8BD5"
+        }
+      };
+    }
     const owner = {
       ...makeOwnerPrincipal(deps.ownerPrincipalId, deps.ownerDisplayName),
       ownerId: deps.ownerId,
@@ -55504,6 +55595,13 @@ function buildDeviceHandlers(deps) {
     ensureOwner3(ctx);
     const { type: _t, requestId: _r, ...rest } = frame;
     const args = DeviceConnectArgsSchema.parse(rest);
+    const selfUrl = deps.selfUrl();
+    if (!selfUrl) {
+      throw new ClawdError(
+        ERROR_CODES.VALIDATION_ERROR,
+        "TUNNEL_REQUIRED: \u672C\u673A\u672A\u5F00 tunnel\uFF0C\u5F00\u542F\u540E\u91CD\u8BD5"
+      );
+    }
     const exchanged = await deps.exchange(args.deviceId);
     const url = args.url ?? exchanged.deviceUrl;
     if (!url) {
@@ -55514,14 +55612,7 @@ function buildDeviceHandlers(deps) {
     }
     let conn;
     try {
-      conn = await deps.connectRemote({
-        url,
-        token: exchanged.token,
-        // 自动反向（spec 决策 #11）：自报本机可达地址，让对方反向加我为联系人；
-        // 本机无 tunnel → null → connectRemote 省略 selfUrl 字段（不造假数据）。
-        // 身份不自报：对方从 token 签名背书取我的 deviceId/ownerId/provider（决策 #16）。
-        selfUrl: deps.selfUrl() ?? void 0
-      });
+      conn = await deps.connectRemote({ url, token: exchanged.token });
     } catch (e) {
       throw new ClawdError(
         ERROR_CODES.VALIDATION_ERROR,
@@ -55529,21 +55620,33 @@ function buildDeviceHandlers(deps) {
       );
     }
     try {
-      const wh = await conn.whoami();
+      let hs;
+      try {
+        hs = await conn.handshake(selfUrl);
+      } catch (e) {
+        const msg = e.message;
+        if (/unknown method|METHOD_NOT_ALLOWED/i.test(msg)) {
+          throw new ClawdError(
+            ERROR_CODES.VALIDATION_ERROR,
+            "REVERSE_UNSUPPORTED: \u5BF9\u65B9 clawd \u7248\u672C\u8FC7\u65E7\uFF0C\u8BF7\u8BA9\u5BF9\u65B9\u5347\u7EA7\u540E\u91CD\u8BD5"
+          );
+        }
+        throw e;
+      }
       const existing = deps.store.get(args.deviceId) ?? void 0;
       const contact = {
         deviceId: args.deviceId,
-        ownerId: wh.ownerId,
-        provider: wh.provider,
+        ownerId: hs.ownerId,
+        provider: hs.provider,
         // 显示名优先用调用方传的 name：公共目录点击连接带 clawd_devices.name（对外展示名，
-        // 如"公共1"）；"输入标识"连接不带 name → 回落 whoami 报的对方 owner 真名。
-        // 归属人身份不丢（ownerId/provider 仍来自 whoami 背书）。
-        displayName: args.name || wh.displayName || args.deviceId,
+        // 如"公共1"）；"输入标识"连接不带 name → 回落 handshake 报的对方 owner 真名。
+        // 归属人身份不丢（ownerId/provider 仍来自 handshake 背书）。
+        displayName: args.name || hs.displayName || args.deviceId,
         remoteUrl: url,
         // connectToken 存自包含签名 token（断线重连复用，30 天有效；
         // 过期后对方拒 TOKEN_EXPIRED → 重新 device:connect 换新票）
         connectToken: exchanged.token,
-        grants: wh.grants,
+        grants: hs.grants,
         addedAt: now(),
         pinnedAt: existing?.pinnedAt ?? null,
         remoteAccessAllowed: existing?.remoteAccessAllowed ?? false
@@ -57988,7 +58091,12 @@ function buildMethodHandlers(deps) {
     ...buildContactHandlers({
       store: deps.contactStore,
       broadcast: deps.broadcastToOwners,
-      now: () => Date.now()
+      now: () => Date.now(),
+      ownerPrincipalId: deps.ownerPrincipalId,
+      ownerDisplayName: deps.ownerDisplayName,
+      ownerId: deps.ownerId,
+      ownerProvider: deps.ownerProvider,
+      exchangeToken: deps.exchangeToken
     }),
     ...buildContactRemoteAccessHandlers({
       store: deps.contactStore,
@@ -58334,6 +58442,9 @@ var METHOD_GRANT_MAP = {
   // contact:setRemoteAccess (owner UI 配远程访问授权)：ADMIN_ANY
   //   (对齐 inbox:postMessage 的"能连上=有 auth，业务在 handler 校"模式)
   "contact:setRemoteAccess": ADMIN_ANY,
+  // contact:handshake: 能连上 = 已通过本地验票；handler 内校验 tokenKind==='connect'
+  // （visitor / owner 不允许触发反向落库）。
+  "contact:handshake": { kind: "public" },
   // ---- visitor:* (访客名单，owner-only) ----
   // owner 看完整访客名单（含没开会话的）；guest 不可调（handler 内再 assertOwner 兜底）。
   "visitor:list": ADMIN_ANY,
@@ -58986,43 +59097,10 @@ async function startDaemon(config) {
     // Task 1.7：authenticate 注入路径替代 expectedToken 单 token 比对。
     // owner 路径 constantTimeEqual 防侧信道；guest 路径走 verifyConnectToken (Ed25519).
     expectedToken: resolvedAuthToken,
-    authenticate: async (t, selfUrl) => {
-      const result = await authenticate(t, buildConnectAuthDeps());
-      if (result.ok && result.context.principal.kind === "guest") {
-        void autoReverseContact({
-          store: contactStore,
-          broadcast: (frame) => wsServer?.broadcastToOwners(frame),
-          deviceId: result.context.principal.id,
-          ownerId: result.context.ownerId ?? "",
-          provider: result.context.provider ?? "",
-          displayName: result.context.principal.displayName ?? result.context.principal.id,
-          selfUrl,
-          // 决策 #16 换票补全：用 owner 当前 jwt 换 aud=对方设备 的票（本机主动连对方用）。
-          // 现读 ownerIdentityStore（热切换后用新身份）；失败 → null → 保持空票。
-          exchangeToken: async (targetDeviceId) => {
-            const record = ownerIdentityStore.read();
-            if (!record) return null;
-            try {
-              const r = await centralExchange({
-                api: config.clawosApi ?? DEFAULT_CLAWOS_API,
-                jwt: record.ttcToken,
-                provider: record.identity.provider,
-                deviceId: targetDeviceId,
-                selfDeviceId: authFile.deviceId
-              });
-              return r.token;
-            } catch (e) {
-              logger.warn("auto-reverse exchange token failed", {
-                targetDeviceId,
-                err: e.message
-              });
-              return null;
-            }
-          }
-        });
-      }
-      return result;
-    },
+    // 纯验票（spec 2026-07-22 双向确认建联）：guest 入站 = 自包含 connect token
+    // **本地验签**（Ed25519 公钥 + aud === 本机 deviceId + 未过期），零网络调用。
+    // 反向落库不再挂在验票副作用上——落库唯一路径 = contact:handshake handler。
+    authenticate: async (t) => authenticate(t, buildConnectAuthDeps()),
     onAuthed: (h, ctx) => wsServer?.attachClientContext(h.id, ctx),
     buildOwnerContext: () => ownerContext(ownerPrincipalId, ownerDisplayName, ownerFeishuUnionId),
     closeConnection: (h, code, reason) => wsServer?.closeClient(h.id, code, reason),
@@ -59526,8 +59604,30 @@ async function startDaemon(config) {
     // cascade 接 store (list 统计 deletedInboxEvents).
     inboxManager,
     inboxStore,
-    // 联系人列表 store（device:connect / 自动反向落同一 store）
+    // 联系人列表 store（device:connect 出站 / contact:handshake 入站落同一 store）
     contactStore,
+    // contact:handshake 换票回填（spec 2026-07-22）：用 owner 当前 jwt 换 aud=对方设备 的票。
+    // 现读 ownerIdentityStore（热切换后用新身份）；失败 / 未登录 → null → 保持空票。
+    exchangeToken: async (targetDeviceId) => {
+      const record = ownerIdentityStore.read();
+      if (!record) return null;
+      try {
+        const r = await centralExchange({
+          api: config.clawosApi ?? DEFAULT_CLAWOS_API,
+          jwt: record.ttcToken,
+          provider: record.identity.provider,
+          deviceId: targetDeviceId,
+          selfDeviceId: authFile.deviceId
+        });
+        return r.token;
+      } catch (e) {
+        logger.warn("contact:handshake exchange token failed", {
+          targetDeviceId,
+          err: e.message
+        });
+        return null;
+      }
+    },
     // inbox:sendDm 用：sessionId → session 出身（复用 attachment 同款 findOwnedSessionScope）
     getSessionScope: (sid) => manager.findOwnedSessionScope(sid),
     // contact:removed broadcast；复用 capability:tokenIssued 同款通路
@@ -59692,7 +59792,9 @@ async function startDaemon(config) {
         // T-31: 把 A 的飞书 union_id stamp 到 B SessionFile，供 cc prompt 身份卡 union_id 行
         guestFeishuUnionId: args.guestFeishuUnionId,
         // T-20: 可选 model override 透到 SessionFile.model
-        ...args.model ? { model: args.model } : {}
+        ...args.model ? { model: args.model } : {},
+        // butler 顶部入口（spec 2026-07-27）：可选 label 透到 SessionFile.label（sidebar 显示）
+        ...args.label ? { label: args.label } : {}
       });
     },
     // A 角色：从 ContactStore 取 peer 可达 URL + connect token，转发到对端 daemon /rpc。