@botcord/daemon 0.2.52 → 0.2.53

package/dist/gateway/channels/http-types.d.ts

@@ -10,10 +10,13 @@
 export type FetchLike = (input: string, init?: {
     method?: string;
     headers?: Record<string, string>;
-    body?: string;
+    body?: BodyInit | Uint8Array | string;
     signal?: AbortSignal;
 }) => Promise<{
     status?: number;
     ok?: boolean;
+    headers?: {
+        get(name: string): string | null;
+    };
     text(): Promise<string>;
 }>;

package/dist/gateway/channels/wechat.js

@@ -1,10 +1,13 @@
+import { basename } from "node:path";
+import { readFile } from "node:fs/promises";
+import { createCipheriv, createHash, randomBytes, randomUUID, } from "node:crypto";
 import { sanitizeUntrustedContent } from "./sanitize.js";
 import { GatewayStateStore } from "./state-store.js";
 import { loadGatewaySecret } from "./secret-store.js";
 import { splitText } from "./text-split.js";
 import { wechatHeaders, WECHAT_BASE_INFO } from "./wechat-http.js";
-import { randomUUID } from "node:crypto";
 const DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
+const DEFAULT_CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
 /**
  * Replace every occurrence of `token` in `input` with `"[REDACTED]"`.
  * No-ops when token is falsy (not yet loaded).
@@ -149,6 +152,125 @@ export function createWechatChannel(opts) {
             return {};
         }
     }
+    function cdnUploadUrl(resp) {
+        if (typeof resp.upload_full_url === "string" && resp.upload_full_url.length > 0) {
+            return resp.upload_full_url;
+        }
+        if (typeof resp.upload_param === "string" && resp.upload_param.length > 0) {
+            return `${DEFAULT_CDN_BASE_URL}/upload?encrypted_query_param=${encodeURIComponent(resp.upload_param)}`;
+        }
+        return null;
+    }
+    async function uploadEncryptedMedia(trace, attachment) {
+        const raw = attachment.data ??
+            (attachment.filePath ? await readFile(attachment.filePath) : undefined);
+        if (!raw || raw.length === 0) {
+            throw new Error("wechat media upload requires non-empty attachment data or filePath");
+        }
+        const data = Buffer.from(raw);
+        const filename = attachment.filename ??
+            (attachment.filePath ? basename(attachment.filePath) : "attachment");
+        const kind = attachment.kind ?? kindFromContentType(attachment.contentType);
+        const mediaType = kind === "image" ? 1 : kind === "video" ? 2 : 3;
+        const itemType = kind === "image" ? 2 : kind === "video" ? 5 : 4;
+        const aesKey = randomBytes(16);
+        const aesKeyHex = aesKey.toString("hex");
+        const encrypted = encryptAes128Ecb(data, aesKey);
+        const filekey = `botcord-${randomUUID()}`;
+        const uploadResp = await callApi("ilink/bot/getuploadurl", {
+            filekey,
+            media_type: mediaType,
+            to_user_id: trace.fromUserId,
+            rawsize: data.length,
+            rawfilemd5: md5Hex(data),
+            filesize: encrypted.length,
+            aeskey: aesKeyHex,
+            no_need_thumb: true,
+        }, 15_000);
+        if (uploadResp.ret !== 0 && uploadResp.ret !== undefined) {
+            throw new Error(redactSecret(`wechat getuploadurl failed: ret=${uploadResp.ret}`, botToken));
+        }
+        const uploadUrl = cdnUploadUrl(uploadResp);
+        if (!uploadUrl)
+            throw new Error("wechat getuploadurl returned no upload URL");
+        const uploadResult = await fetchImpl(uploadUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/octet-stream" },
+            body: encrypted,
+            signal: AbortSignal.timeout(30_000),
+        });
+        const encryptedParam = uploadResult.headers?.get("x-encrypted-param") ??
+            uploadResult.headers?.get("X-Encrypted-Param") ??
+            (await readEncryptedParamFromBody(uploadResult));
+        if (!encryptedParam) {
+            throw new Error("wechat CDN upload returned no x-encrypted-param");
+        }
+        const media = {
+            encrypt_query_param: encryptedParam,
+            aes_key: Buffer.from(aesKeyHex, "utf8").toString("base64"),
+        };
+        if (itemType === 2) {
+            return {
+                type: itemType,
+                image_item: {
+                    media,
+                    aeskey: aesKeyHex,
+                    mid_size: data.length,
+                },
+            };
+        }
+        if (itemType === 5) {
+            return {
+                type: itemType,
+                video_item: {
+                    media,
+                    video_size: data.length,
+                    file_name: filename,
+                },
+            };
+        }
+        return {
+            type: itemType,
+            file_item: {
+                media,
+                file_name: filename,
+                md5: md5Hex(data),
+                len: data.length,
+            },
+        };
+    }
+    async function readEncryptedParamFromBody(resp) {
+        const raw = await resp.text().catch(() => "");
+        if (!raw)
+            return null;
+        try {
+            const json = JSON.parse(raw);
+            const v = json.encrypted_query_param ?? json.encrypt_query_param ?? json.upload_param;
+            return typeof v === "string" && v.length > 0 ? v : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function sendItems(trace, items) {
+        const clientId = `botcord-${randomUUID()}`;
+        const body = {
+            msg: {
+                from_user_id: "",
+                to_user_id: trace.fromUserId,
+                client_id: clientId,
+                message_type: 2, // BOT → user
+                message_state: 2, // FINISH
+                context_token: trace.contextToken,
+                item_list: items,
+            },
+        };
+        const resp = await callApi("ilink/bot/sendmessage", body, 15_000);
+        if (resp.ret !== 0 && resp.ret !== undefined) {
+            throw new Error(redactSecret(`wechat sendmessage failed: ret=${resp.ret}`, botToken));
+        }
+        return clientId;
+    }
     function extractText(msg) {
         const parts = [];
         for (const item of msg.item_list ?? []) {
@@ -398,27 +520,23 @@ export function createWechatChannel(opts) {
                 throw new Error(`wechat send: no context_token for traceId=${message.traceId ?? "<missing>"}` +
                     ` (expired or never bound — daemon does not support unsolicited replies)`);
             }
-            const chunks = splitText(message.text, splitAt);
+            const chunks = message.text.length > 0 ? splitText(message.text, splitAt) : [];
             let lastClientId = null;
             for (const chunk of chunks) {
-                const clientId = `botcord-${randomUUID()}`;
-                const body = {
-                    msg: {
-                        from_user_id: "",
-                        to_user_id: trace.fromUserId,
-                        client_id: clientId,
-                        message_type: 2, // BOT → user
-                        message_state: 2, // FINISH
-                        context_token: trace.contextToken,
-                        item_list: [{ type: 1, text_item: { text: chunk } }],
-                    },
-                };
-                const resp = await callApi("ilink/bot/sendmessage", body, 15_000);
-                if (resp.ret !== 0 && resp.ret !== undefined) {
-                    log.warn("wechat sendmessage non-zero ret", { ret: resp.ret });
-                    throw new Error(redactSecret(`wechat sendmessage failed: ret=${resp.ret}`, botToken));
+                lastClientId = await sendItems(trace, [{ type: 1, text_item: { text: chunk } }]);
+            }
+            for (const attachment of message.attachments ?? []) {
+                try {
+                    const item = await uploadEncryptedMedia(trace, attachment);
+                    lastClientId = await sendItems(trace, [item]);
+                }
+                catch (err) {
+                    log.warn("wechat media send failed", {
+                        err: redactSecret(String(err), botToken),
+                        filename: attachment.filename ?? attachment.filePath ?? "attachment",
+                    });
+                    throw err;
                 }
-                lastClientId = clientId;
             }
             const sendAt = Date.now();
             statusSnapshot = { ...statusSnapshot, lastSendAt: sendAt };
@@ -453,6 +571,21 @@ export function createWechatChannel(opts) {
     };
     return adapter;
 }
+function md5Hex(data) {
+    return createHash("md5").update(data).digest("hex");
+}
+function encryptAes128Ecb(data, key) {
+    const cipher = createCipheriv("aes-128-ecb", key, null);
+    cipher.setAutoPadding(true);
+    return Buffer.concat([cipher.update(data), cipher.final()]);
+}
+function kindFromContentType(contentType) {
+    if (contentType?.startsWith("image/"))
+        return "image";
+    if (contentType?.startsWith("video/"))
+        return "video";
+    return "file";
+}
 function sleep(ms, signal) {
     return new Promise((resolve) => {
         if (signal?.aborted) {

package/dist/gateway/types.d.ts

@@ -140,12 +140,22 @@ export type UserTurnBuilder = (message: GatewayInboundMessage) => string;
  */
 export type OutboundObserver = (message: GatewayOutboundMessage) => Promise<void> | void;
 /** Outbound reply payload passed to `ChannelAdapter.send()`. */
+export interface GatewayOutboundAttachment {
+    /** Local daemon-readable file path. */
+    filePath?: string;
+    /** In-memory bytes, primarily for tests and in-process tool callers. */
+    data?: Uint8Array;
+    filename?: string;
+    contentType?: string;
+    kind?: "image" | "file" | "video";
+}
 export interface GatewayOutboundMessage {
     channel: string;
     accountId: string;
     conversationId: string;
     threadId?: string | null;
     text: string;
+    attachments?: GatewayOutboundAttachment[];
     replyTo?: string | null;
     traceId?: string | null;
 }

package/dist/index.js

@@ -172,6 +172,48 @@ function pidAlive(pid) {
         return false;
     }
 }
+async function waitForPidExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!pidAlive(pid))
+            return true;
+        await delay(100);
+    }
+    return !pidAlive(pid);
+}
+async function stopExistingDaemonForRestart(pid) {
+    if (pid === process.pid)
+        return;
+    log.info("existing daemon found; restarting", { pid });
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        try {
+            unlinkSync(PID_PATH);
+        }
+        catch {
+            // ignore
+        }
+        return;
+    }
+    if (!(await waitForPidExit(pid, 5_000))) {
+        log.warn("existing daemon did not stop after SIGTERM; sending SIGKILL", { pid });
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            // ignore
+        }
+        await waitForPidExit(pid, 2_000);
+    }
+    try {
+        unlinkSync(PID_PATH);
+    }
+    catch {
+        // ignore
+    }
+}
 /**
  * Load the daemon config, auto-creating `~/.botcord/daemon/config.json`
  * with sensible defaults on first run. `--agent` (repeated) pins explicit
@@ -251,6 +293,8 @@ async function redeemInstallToken(opts) {
     const body = { install_token: opts.installToken };
     if (opts.label)
         body.label = opts.label;
+    if (opts.daemonInstanceId)
+        body.daemon_instance_id = opts.daemonInstanceId;
     const resp = await fetch(`${opts.hubUrl.replace(/\/+$/, "")}/daemon/auth/install-token`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -259,7 +303,9 @@ async function redeemInstallToken(opts) {
     });
     if (!resp.ok) {
         const text = await resp.text().catch(() => "");
-        throw new Error(`daemon install-token redeem failed: ${resp.status} ${text}`);
+        const err = new Error(`daemon install-token redeem failed: ${resp.status} ${text}`);
+        err.status = resp.status;
+        throw err;
     }
     return parseDaemonTokenResponse(await resp.json(), opts.hubUrl);
 }
@@ -330,10 +376,10 @@ async function runDeviceCodeFlow(opts) {
  * plane (legacy P0 behavior — caller may still log a warning).
  *
  * Decision tree (plan §4.4 + §6.4):
- * 1. Have existing creds and no `--relogin` → return existing record, even
- *    when a dashboard `--install-token` is present. The token is one-time and
- *    the generated install command should be safe to re-run after first login.
- * 2. No existing creds + `--install-token` → redeem the one-time dashboard ticket.
+ * 1. `--install-token` → redeem the one-time dashboard ticket. If local
+ *    user-auth exists, include its daemonInstanceId so Hub can re-authorize
+ *    the same device instead of creating a new one.
+ * 2. Have existing creds and no `--relogin` → return existing record.
  * 3. `--relogin` → device-code login.
  * 4. No creds + TTY → device-code login.
  * 5. No creds + no TTY → exit 1 with the §6.4 hint.
@@ -359,22 +405,40 @@ async function ensureUserAuthForStart(args) {
         if (labelFlag && existing.label !== labelFlag) {
             console.error(`note: --label "${labelFlag}" ignored (already logged in as "${existing.label ?? "<unset>"}"); pass --relogin to change it`);
         }
-        if (installToken) {
-            console.error("note: --install-token ignored because daemon is already logged in; pass --relogin to re-bind");
-        }
         return existing;
     }
     // Need a fresh login. Resolve hubUrl: explicit --hub > existing record > DEFAULT_HUB.
     const hubUrl = hubFlag ?? existing?.hubUrl ?? DEFAULT_HUB;
     const label = labelFlag ?? defaultLoginLabel();
     if (authAction === "install-token" && installToken) {
-        const tok = await redeemInstallToken({ hubUrl, installToken, label });
-        const record = userAuthFromTokenResponse(tok, { label });
+        let tok;
+        try {
+            tok = await redeemInstallToken({
+                hubUrl,
+                installToken,
+                label,
+                daemonInstanceId: existing?.daemonInstanceId,
+            });
+        }
+        catch (err) {
+            if (existing && !relogin && !existsSync(AUTH_EXPIRED_FLAG_PATH)) {
+                console.error(`note: --install-token could not be redeemed (${err instanceof Error ? err.message : String(err)}); reusing existing daemon auth`);
+                return existing;
+            }
+            throw err;
+        }
+        const record = userAuthFromTokenResponse(tok, {
+            label,
+            loggedInAt: existing?.daemonInstanceId && existing.daemonInstanceId === tok.daemonInstanceId
+                ? existing.loggedInAt
+                : undefined,
+        });
         saveUserAuth(record);
         clearAuthExpiredFlag();
         log.info("install-token flow: authorized", {
             userId: record.userId,
             daemonInstanceId: record.daemonInstanceId,
+            reusedExistingDaemonInstance: existing?.daemonInstanceId === record.daemonInstanceId,
             hubUrl: record.hubUrl,
             label,
         });
@@ -424,11 +488,6 @@ async function cmdStart(args) {
         relogin: args.flags.relogin === true,
         child: process.env.BOTCORD_DAEMON_CHILD === "1",
     });
-    const existing = readPid();
-    if (existing && pidAlive(existing)) {
-        console.error(`daemon already running (pid ${existing})`);
-        process.exit(1);
-    }
     // Login MUST happen before fork — once detached, stdio is gone and the
     // user can't see the device code. We also run it for explicit
     // --foreground so an interactive user can log in without the fork dance.
@@ -436,6 +495,17 @@ async function cmdStart(args) {
     // var so we don't try to re-prompt for credentials it already has.
     if (process.env.BOTCORD_DAEMON_CHILD !== "1") {
         await ensureUserAuthForStart(args);
+        const existing = readPid();
+        if (existing && pidAlive(existing)) {
+            await stopExistingDaemonForRestart(existing);
+        }
+    }
+    else {
+        const existing = readPid();
+        if (existing && existing !== process.pid && pidAlive(existing)) {
+            console.error(`daemon already running (pid ${existing})`);
+            process.exit(1);
+        }
     }
     if (background) {
         // Detached child re-exec in foreground mode. The child writes the PID

package/dist/start-auth.js

@@ -1,7 +1,7 @@
 export function resolveStartAuthAction(opts) {
-    if (opts.existing && !opts.relogin)
-        return "reuse-existing";
     if (opts.installToken)
         return "install-token";
+    if (opts.existing && !opts.relogin)
+        return "reuse-existing";
     return "device-code";
 }

package/dist/turn-text.js

@@ -40,6 +40,13 @@ function replyDeliveryHint(msg) {
         ? THIRD_PARTY_REPLY_HINT
         : NON_OWNER_REPLY_HINT;
 }
+function appendConversationFields(fields, msg) {
+    const conversationId = sanitizeSenderName(msg.conversation.id);
+    fields.push(`conversation_id: ${conversationId}`);
+    if (isThirdPartyConversation(msg.conversation.id)) {
+        fields.push(`channel: ${sanitizeSenderName(msg.channel)}`);
+    }
+}
 /**
  * Read the `raw.batch` array emitted by the BotCord channel when inbox
  * drain groups multiple messages for the same `(room, topic)`. Returns the
@@ -138,6 +145,7 @@ export function composeBotCordUserTurn(msg) {
         `from: ${sanitizedSenderLabel}`,
         `to: ${msg.accountId}`,
     ];
+    appendConversationFields(headerFields, msg);
     if (isGroup && roomTitle) {
         const safeRoom = sanitizeSenderName(roomTitle.replace(/[\r\n]+/g, " "));
         headerFields.push(`room: ${safeRoom}`);
@@ -190,6 +198,7 @@ function composeBatchedTurn(msg, batch) {
         `[BotCord Messages (${batch.length} new)]`,
         `to: ${msg.accountId}`,
     ];
+    appendConversationFields(header, msg);
     if (isGroup && roomTitle) {
         const safeRoom = sanitizeSenderName(roomTitle.replace(/[\r\n]+/g, " "));
         header.push(`room: ${safeRoom}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/daemon",
-  "version": "0.2.52",
+  "version": "0.2.53",
   "description": "BotCord local daemon — bridges Hub inbox push to local Claude Code / Codex / Gemini CLIs",
   "type": "module",
   "bin": {

package/src/__tests__/start-auth.test.ts

@@ -14,14 +14,14 @@ const existingAuth: UserAuthRecord = {
 };
 
 describe("resolveStartAuthAction", () => {
-  it("reuses existing auth even when a one-time install token is present", () => {
+  it("redeems an install token even when existing auth is available", () => {
     expect(
       resolveStartAuthAction({
         existing: existingAuth,
         relogin: false,
         installToken: "dit_expired",
       }),
-    ).toBe("reuse-existing");
+    ).toBe("install-token");
   });
 
   it("redeems an install token when no existing auth is available", () => {

package/src/__tests__/turn-text.test.ts

@@ -116,6 +116,8 @@ describe("composeBotCordUserTurn", () => {
     );
     expect(out).toContain("third-party gateway chat");
     expect(out).toContain("Reply normally in your final assistant message");
+    expect(out).toContain("conversation_id: telegram:user:7904063707");
+    expect(out).toContain("channel: gw_telegram_123");
     expect(out).not.toContain("Plain text output WILL NOT be sent");
     expect(out).not.toContain("botcord_send");
   });
@@ -219,6 +221,7 @@ describe("composeBotCordUserTurn", () => {
       }),
     );
     expect(out).toContain("[BotCord Messages (2 new)]");
+    expect(out).toContain("conversation_id: rm_team");
     expect(out).toContain("room: Ouraca");
     expect(out).toContain("mentioned: true");
     expect(out).toContain('<agent-message sender="ag_alice" sender_kind="agent">');

package/src/__tests__/wechat-channel.test.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -20,6 +20,7 @@ const SILENT_LOG: GatewayLogger = {
 interface StubResponse {
   status?: number;
   body: unknown;
+  headers?: Record<string, string>;
 }
 
 /**
@@ -35,16 +36,20 @@ function buildFetchStub(
       body: Record<string, unknown> | null,
     ) => StubResponse | Promise<StubResponse>;
   }>,
-  calls: Array<{ url: string; body: Record<string, unknown> | null }>,
+  calls: Array<{ url: string; body: any }>,
 ): FetchLike {
   const counters = new Map<string, number>();
   return async (url, init) => {
-    let parsed: Record<string, unknown> | null = null;
+    let parsed: Record<string, unknown> | Uint8Array | null = null;
     if (init?.body) {
-      try {
-        parsed = JSON.parse(init.body as string) as Record<string, unknown>;
-      } catch {
-        parsed = null;
+      if (typeof init.body === "string") {
+        try {
+          parsed = JSON.parse(init.body) as Record<string, unknown>;
+        } catch {
+          parsed = null;
+        }
+      } else if (init.body instanceof Uint8Array) {
+        parsed = init.body;
       }
     }
     calls.push({ url, body: parsed });
@@ -59,11 +64,21 @@ function buildFetchStub(
         return {
           status,
           ok: status >= 200 && status < 300,
+          headers: {
+            get(name: string) {
+              return resp.headers?.[name] ?? resp.headers?.[name.toLowerCase()] ?? null;
+            },
+          },
           text: async () => text,
         };
       }
     }
-    return { status: 404, ok: false, text: async () => "" };
+    return {
+      status: 404,
+      ok: false,
+      headers: { get: () => null },
+      text: async () => "",
+    };
   };
 }
 
@@ -409,6 +424,109 @@ describe("wechat channel adapter", () => {
     expect(calls.find((c) => c.url.includes("sendmessage"))).toBeUndefined();
   });
 
+  it("send() uploads local file attachments to WeChat CDN and sends a file_item", async () => {
+    const filePath = path.join(tmp, "report.pdf");
+    writeFileSync(filePath, "plain file bytes");
+    const calls: Array<{ url: string; body: any }> = [];
+    const fetchImpl = buildFetchStub(
+      [
+        {
+          match: "getupdates",
+          respond: (idx) => {
+            if (idx === 0) {
+              return {
+                body: {
+                  ret: 0,
+                  get_updates_buf: "c",
+                  msgs: [
+                    {
+                      message_type: 1,
+                      from_user_id: "alice@im.wechat",
+                      context_token: "ctx-file",
+                      item_list: [{ type: 1, text_item: { text: "send file" } }],
+                    },
+                  ],
+                },
+              };
+            }
+            return { body: { ret: 0, get_updates_buf: "c", msgs: [] } };
+          },
+        },
+        {
+          match: "getuploadurl",
+          respond: () => ({
+            body: {
+              ret: 0,
+              upload_full_url: "https://cdn.test/upload/report",
+            },
+          }),
+        },
+        {
+          match: "cdn.test/upload",
+          respond: () => ({
+            body: "",
+            headers: { "x-encrypted-param": "encrypted-download-token" },
+          }),
+        },
+        { match: "sendmessage", respond: () => ({ body: { ret: 0 } }) },
+      ],
+      calls,
+    );
+    const adapter = createWechatChannel({
+      id: "gw_wx_file",
+      accountId: "ag_test",
+      botToken: "tok",
+      stateFile: path.join(tmp, "state.json"),
+      fetchImpl,
+      stateDebounceMs: 0,
+      allowedSenderIds: ["alice@im.wechat"],
+    });
+    const h = startAdapter(adapter, { stopAfterEnvelopes: 1 });
+    await h.pollDone;
+    const traceId = h.envelopes[0]!.message.trace!.id;
+
+    await adapter.send({
+      log: SILENT_LOG,
+      message: {
+        channel: "gw_wx_file",
+        accountId: "ag_test",
+        conversationId: "wechat:user:alice@im.wechat",
+        text: "",
+        traceId,
+        attachments: [
+          {
+            filePath,
+            filename: "report.pdf",
+            contentType: "application/pdf",
+            kind: "file",
+          },
+        ],
+      },
+    });
+
+    const uploadRequest = calls.find((c) => c.url.includes("getuploadurl"))!;
+    expect(uploadRequest.body!.media_type).toBe(3);
+    expect(uploadRequest.body!.rawsize).toBe("plain file bytes".length);
+    expect(uploadRequest.body!.filesize).toBeGreaterThan("plain file bytes".length);
+
+    const cdnCall = calls.find((c) => c.url.includes("cdn.test/upload"))!;
+    expect(cdnCall.body).toBeInstanceOf(Uint8Array);
+    expect(Buffer.from(cdnCall.body as Uint8Array).toString("utf8")).not.toContain(
+      "plain file bytes",
+    );
+
+    const sendCall = calls.find((c) => c.url.includes("sendmessage"))!;
+    const msg = sendCall.body!.msg as Record<string, unknown>;
+    const item = (msg.item_list as Array<Record<string, unknown>>)[0]!;
+    expect(item.type).toBe(4);
+    const fileItem = item.file_item as Record<string, unknown>;
+    expect(fileItem.file_name).toBe("report.pdf");
+    expect(fileItem.len).toBe("plain file bytes".length);
+    expect((fileItem.media as Record<string, unknown>).encrypt_query_param).toBe(
+      "encrypted-download-token",
+    );
+  });
+
   it("send() splits long replies into chunks <= splitAt, preferring newline boundaries", async () => {
     const calls: Array<{ url: string; body: Record<string, unknown> | null }> = [];
     const fetchImpl = buildFetchStub(

package/src/gateway/channels/http-types.ts

@@ -12,11 +12,12 @@ export type FetchLike = (
   init?: {
     method?: string;
     headers?: Record<string, string>;
-    body?: string;
+    body?: BodyInit | Uint8Array | string;
     signal?: AbortSignal;
   },
 ) => Promise<{
   status?: number;
   ok?: boolean;
+  headers?: { get(name: string): string | null };
   text(): Promise<string>;
 }>;

package/src/gateway/channels/wechat.ts

@@ -1,3 +1,11 @@
+import { basename } from "node:path";
+import { readFile } from "node:fs/promises";
+import {
+  createCipheriv,
+  createHash,
+  randomBytes,
+  randomUUID,
+} from "node:crypto";
 import type {
   ChannelAdapter,
   ChannelSendContext,
@@ -8,15 +16,16 @@ import type {
   ChannelTypingContext,
   GatewayInboundEnvelope,
   GatewayInboundMessage,
+  GatewayOutboundAttachment,
 } from "../types.js";
 import { sanitizeUntrustedContent } from "./sanitize.js";
 import { GatewayStateStore } from "./state-store.js";
 import { loadGatewaySecret } from "./secret-store.js";
 import { splitText } from "./text-split.js";
 import { wechatHeaders, WECHAT_BASE_INFO, type FetchLike } from "./wechat-http.js";
-import { randomUUID } from "node:crypto";
 
 const DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
+const DEFAULT_CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
 
 /**
  * Replace every occurrence of `token` in `input` with `"[REDACTED]"`.
@@ -92,6 +101,11 @@ interface WechatGenericResp {
   [k: string]: unknown;
 }
 
+interface WechatUploadUrlResp extends WechatGenericResp {
+  upload_param?: string;
+  upload_full_url?: string;
+}
+
 interface TraceContext {
   contextToken: string;
   fromUserId: string;
@@ -231,6 +245,142 @@ export function createWechatChannel(opts: WechatChannelOptions): ChannelAdapter
     }
   }
 
+  function cdnUploadUrl(resp: WechatUploadUrlResp): string | null {
+    if (typeof resp.upload_full_url === "string" && resp.upload_full_url.length > 0) {
+      return resp.upload_full_url;
+    }
+    if (typeof resp.upload_param === "string" && resp.upload_param.length > 0) {
+      return `${DEFAULT_CDN_BASE_URL}/upload?encrypted_query_param=${encodeURIComponent(
+        resp.upload_param,
+      )}`;
+    }
+    return null;
+  }
+
+  async function uploadEncryptedMedia(
+    trace: TraceContext,
+    attachment: GatewayOutboundAttachment,
+  ): Promise<Record<string, unknown>> {
+    const raw =
+      attachment.data ??
+      (attachment.filePath ? await readFile(attachment.filePath) : undefined);
+    if (!raw || raw.length === 0) {
+      throw new Error("wechat media upload requires non-empty attachment data or filePath");
+    }
+    const data = Buffer.from(raw);
+    const filename =
+      attachment.filename ??
+      (attachment.filePath ? basename(attachment.filePath) : "attachment");
+    const kind = attachment.kind ?? kindFromContentType(attachment.contentType);
+    const mediaType = kind === "image" ? 1 : kind === "video" ? 2 : 3;
+    const itemType = kind === "image" ? 2 : kind === "video" ? 5 : 4;
+    const aesKey = randomBytes(16);
+    const aesKeyHex = aesKey.toString("hex");
+    const encrypted = encryptAes128Ecb(data, aesKey);
+    const filekey = `botcord-${randomUUID()}`;
+    const uploadResp = await callApi<WechatUploadUrlResp>(
+      "ilink/bot/getuploadurl",
+      {
+        filekey,
+        media_type: mediaType,
+        to_user_id: trace.fromUserId,
+        rawsize: data.length,
+        rawfilemd5: md5Hex(data),
+        filesize: encrypted.length,
+        aeskey: aesKeyHex,
+        no_need_thumb: true,
+      },
+      15_000,
+    );
+    if (uploadResp.ret !== 0 && uploadResp.ret !== undefined) {
+      throw new Error(redactSecret(`wechat getuploadurl failed: ret=${uploadResp.ret}`, botToken));
+    }
+    const uploadUrl = cdnUploadUrl(uploadResp);
+    if (!uploadUrl) throw new Error("wechat getuploadurl returned no upload URL");
+
+    const uploadResult = await fetchImpl(uploadUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/octet-stream" },
+      body: encrypted,
+      signal: AbortSignal.timeout(30_000),
+    });
+    const encryptedParam =
+      uploadResult.headers?.get("x-encrypted-param") ??
+      uploadResult.headers?.get("X-Encrypted-Param") ??
+      (await readEncryptedParamFromBody(uploadResult));
+    if (!encryptedParam) {
+      throw new Error("wechat CDN upload returned no x-encrypted-param");
+    }
+
+    const media = {
+      encrypt_query_param: encryptedParam,
+      aes_key: Buffer.from(aesKeyHex, "utf8").toString("base64"),
+    };
+    if (itemType === 2) {
+      return {
+        type: itemType,
+        image_item: {
+          media,
+          aeskey: aesKeyHex,
+          mid_size: data.length,
+        },
+      };
+    }
+    if (itemType === 5) {
+      return {
+        type: itemType,
+        video_item: {
+          media,
+          video_size: data.length,
+          file_name: filename,
+        },
+      };
+    }
+    return {
+      type: itemType,
+      file_item: {
+        media,
+        file_name: filename,
+        md5: md5Hex(data),
+        len: data.length,
+      },
+    };
+  }
+
+  async function readEncryptedParamFromBody(
+    resp: Awaited<ReturnType<FetchLike>>,
+  ): Promise<string | null> {
+    const raw = await resp.text().catch(() => "");
+    if (!raw) return null;
+    try {
+      const json = JSON.parse(raw) as Record<string, unknown>;
+      const v = json.encrypted_query_param ?? json.encrypt_query_param ?? json.upload_param;
+      return typeof v === "string" && v.length > 0 ? v : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function sendItems(trace: TraceContext, items: Record<string, unknown>[]): Promise<string> {
+    const clientId = `botcord-${randomUUID()}`;
+    const body = {
+      msg: {
+        from_user_id: "",
+        to_user_id: trace.fromUserId,
+        client_id: clientId,
+        message_type: 2, // BOT → user
+        message_state: 2, // FINISH
+        context_token: trace.contextToken,
+        item_list: items,
+      },
+    };
+    const resp = await callApi<WechatGenericResp>("ilink/bot/sendmessage", body, 15_000);
+    if (resp.ret !== 0 && resp.ret !== undefined) {
+      throw new Error(redactSecret(`wechat sendmessage failed: ret=${resp.ret}`, botToken));
+    }
+    return clientId;
+  }
+
   function extractText(msg: WechatInboundMsg): string {
     const parts: string[] = [];
     for (const item of msg.item_list ?? []) {
@@ -495,27 +645,22 @@ export function createWechatChannel(opts: WechatChannelOptions): ChannelAdapter
         );
       }
 
-      const chunks = splitText(message.text, splitAt);
+      const chunks = message.text.length > 0 ? splitText(message.text, splitAt) : [];
       let lastClientId: string | null = null;
       for (const chunk of chunks) {
-        const clientId = `botcord-${randomUUID()}`;
-        const body = {
-          msg: {
-            from_user_id: "",
-            to_user_id: trace.fromUserId,
-            client_id: clientId,
-            message_type: 2, // BOT → user
-            message_state: 2, // FINISH
-            context_token: trace.contextToken,
-            item_list: [{ type: 1, text_item: { text: chunk } }],
-          },
-        };
-        const resp = await callApi<WechatGenericResp>("ilink/bot/sendmessage", body, 15_000);
-        if (resp.ret !== 0 && resp.ret !== undefined) {
-          log.warn("wechat sendmessage non-zero ret", { ret: resp.ret });
-          throw new Error(redactSecret(`wechat sendmessage failed: ret=${resp.ret}`, botToken));
+        lastClientId = await sendItems(trace, [{ type: 1, text_item: { text: chunk } }]);
+      }
+      for (const attachment of message.attachments ?? []) {
+        try {
+          const item = await uploadEncryptedMedia(trace, attachment);
+          lastClientId = await sendItems(trace, [item]);
+        } catch (err) {
+          log.warn("wechat media send failed", {
+            err: redactSecret(String(err), botToken),
+            filename: attachment.filename ?? attachment.filePath ?? "attachment",
+          });
+          throw err;
         }
-        lastClientId = clientId;
       }
       const sendAt = Date.now();
       statusSnapshot = { ...statusSnapshot, lastSendAt: sendAt };
@@ -553,6 +698,22 @@ export function createWechatChannel(opts: WechatChannelOptions): ChannelAdapter
   return adapter;
 }
 
+function md5Hex(data: Buffer): string {
+  return createHash("md5").update(data).digest("hex");
+}
+
+function encryptAes128Ecb(data: Buffer, key: Buffer): Buffer {
+  const cipher = createCipheriv("aes-128-ecb", key, null);
+  cipher.setAutoPadding(true);
+  return Buffer.concat([cipher.update(data), cipher.final()]);
+}
+
+function kindFromContentType(contentType: string | undefined): "image" | "file" | "video" {
+  if (contentType?.startsWith("image/")) return "image";
+  if (contentType?.startsWith("video/")) return "video";
+  return "file";
+}
+
 function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   return new Promise((resolve) => {
     if (signal?.aborted) {

package/src/gateway/types.ts

@@ -172,12 +172,23 @@ export type OutboundObserver = (
 ) => Promise<void> | void;
 
 /** Outbound reply payload passed to `ChannelAdapter.send()`. */
+export interface GatewayOutboundAttachment {
+  /** Local daemon-readable file path. */
+  filePath?: string;
+  /** In-memory bytes, primarily for tests and in-process tool callers. */
+  data?: Uint8Array;
+  filename?: string;
+  contentType?: string;
+  kind?: "image" | "file" | "video";
+}
+
 export interface GatewayOutboundMessage {
   channel: string;
   accountId: string;
   conversationId: string;
   threadId?: string | null;
   text: string;
+  attachments?: GatewayOutboundAttachment[];
   replyTo?: string | null;
   traceId?: string | null;
 }

package/src/index.ts

@@ -231,6 +231,44 @@ function pidAlive(pid: number): boolean {
   }
 }
 
+async function waitForPidExit(pid: number, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!pidAlive(pid)) return true;
+    await delay(100);
+  }
+  return !pidAlive(pid);
+}
+
+async function stopExistingDaemonForRestart(pid: number): Promise<void> {
+  if (pid === process.pid) return;
+  log.info("existing daemon found; restarting", { pid });
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    try {
+      unlinkSync(PID_PATH);
+    } catch {
+      // ignore
+    }
+    return;
+  }
+  if (!(await waitForPidExit(pid, 5_000))) {
+    log.warn("existing daemon did not stop after SIGTERM; sending SIGKILL", { pid });
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // ignore
+    }
+    await waitForPidExit(pid, 2_000);
+  }
+  try {
+    unlinkSync(PID_PATH);
+  } catch {
+    // ignore
+  }
+}
+
 /**
  * Load the daemon config, auto-creating `~/.botcord/daemon/config.json`
  * with sensible defaults on first run. `--agent` (repeated) pins explicit
@@ -323,9 +361,11 @@ async function redeemInstallToken(opts: {
   hubUrl: string;
   installToken: string;
   label?: string;
+  daemonInstanceId?: string;
 }): Promise<DaemonTokenResponse> {
   const body: Record<string, unknown> = { install_token: opts.installToken };
   if (opts.label) body.label = opts.label;
+  if (opts.daemonInstanceId) body.daemon_instance_id = opts.daemonInstanceId;
   const resp = await fetch(`${opts.hubUrl.replace(/\/+$/, "")}/daemon/auth/install-token`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -334,7 +374,9 @@ async function redeemInstallToken(opts: {
   });
   if (!resp.ok) {
     const text = await resp.text().catch(() => "");
-    throw new Error(`daemon install-token redeem failed: ${resp.status} ${text}`);
+    const err = new Error(`daemon install-token redeem failed: ${resp.status} ${text}`);
+    (err as unknown as { status?: number }).status = resp.status;
+    throw err;
   }
   return parseDaemonTokenResponse(await resp.json(), opts.hubUrl);
 }
@@ -418,10 +460,10 @@ async function runDeviceCodeFlow(opts: {
  * plane (legacy P0 behavior — caller may still log a warning).
  *
  * Decision tree (plan §4.4 + §6.4):
- * 1. Have existing creds and no `--relogin` → return existing record, even
- *    when a dashboard `--install-token` is present. The token is one-time and
- *    the generated install command should be safe to re-run after first login.
- * 2. No existing creds + `--install-token` → redeem the one-time dashboard ticket.
+ * 1. `--install-token` → redeem the one-time dashboard ticket. If local
+ *    user-auth exists, include its daemonInstanceId so Hub can re-authorize
+ *    the same device instead of creating a new one.
+ * 2. Have existing creds and no `--relogin` → return existing record.
  * 3. `--relogin` → device-code login.
  * 4. No creds + TTY → device-code login.
  * 5. No creds + no TTY → exit 1 with the §6.4 hint.
@@ -452,9 +494,6 @@ async function ensureUserAuthForStart(args: ParsedArgs): Promise<UserAuthRecord
         `note: --label "${labelFlag}" ignored (already logged in as "${existing.label ?? "<unset>"}"); pass --relogin to change it`,
       );
     }
-    if (installToken) {
-      console.error("note: --install-token ignored because daemon is already logged in; pass --relogin to re-bind");
-    }
     return existing;
   }
 
@@ -463,13 +502,37 @@ async function ensureUserAuthForStart(args: ParsedArgs): Promise<UserAuthRecord
   const label = labelFlag ?? defaultLoginLabel();
 
   if (authAction === "install-token" && installToken) {
-    const tok = await redeemInstallToken({ hubUrl, installToken, label });
-    const record = userAuthFromTokenResponse(tok, { label });
+    let tok: DaemonTokenResponse;
+    try {
+      tok = await redeemInstallToken({
+        hubUrl,
+        installToken,
+        label,
+        daemonInstanceId: existing?.daemonInstanceId,
+      });
+    } catch (err) {
+      if (existing && !relogin && !existsSync(AUTH_EXPIRED_FLAG_PATH)) {
+        console.error(
+          `note: --install-token could not be redeemed (${err instanceof Error ? err.message : String(err)}); reusing existing daemon auth`,
+        );
+        return existing;
+      }
+      throw err;
+    }
+    const record = userAuthFromTokenResponse(tok, {
+      label,
+      loggedInAt:
+        existing?.daemonInstanceId && existing.daemonInstanceId === tok.daemonInstanceId
+          ? existing.loggedInAt
+          : undefined,
+    });
     saveUserAuth(record);
     clearAuthExpiredFlag();
     log.info("install-token flow: authorized", {
       userId: record.userId,
       daemonInstanceId: record.daemonInstanceId,
+      reusedExistingDaemonInstance:
+        existing?.daemonInstanceId === record.daemonInstanceId,
       hubUrl: record.hubUrl,
       label,
     });
@@ -527,12 +590,6 @@ async function cmdStart(args: ParsedArgs): Promise<void> {
     child: process.env.BOTCORD_DAEMON_CHILD === "1",
   });
 
-  const existing = readPid();
-  if (existing && pidAlive(existing)) {
-    console.error(`daemon already running (pid ${existing})`);
-    process.exit(1);
-  }
-
   // Login MUST happen before fork — once detached, stdio is gone and the
   // user can't see the device code. We also run it for explicit
   // --foreground so an interactive user can log in without the fork dance.
@@ -540,6 +597,16 @@ async function cmdStart(args: ParsedArgs): Promise<void> {
   // var so we don't try to re-prompt for credentials it already has.
   if (process.env.BOTCORD_DAEMON_CHILD !== "1") {
     await ensureUserAuthForStart(args);
+    const existing = readPid();
+    if (existing && pidAlive(existing)) {
+      await stopExistingDaemonForRestart(existing);
+    }
+  } else {
+    const existing = readPid();
+    if (existing && existing !== process.pid && pidAlive(existing)) {
+      console.error(`daemon already running (pid ${existing})`);
+      process.exit(1);
+    }
   }
 
   if (background) {

package/src/start-auth.ts

@@ -7,7 +7,7 @@ export function resolveStartAuthAction(opts: {
   relogin: boolean;
   installToken?: string;
 }): StartAuthAction {
-  if (opts.existing && !opts.relogin) return "reuse-existing";
   if (opts.installToken) return "install-token";
+  if (opts.existing && !opts.relogin) return "reuse-existing";
   return "device-code";
 }

package/src/turn-text.ts

@@ -76,6 +76,17 @@ function replyDeliveryHint(msg: GatewayInboundMessage): string {
     : NON_OWNER_REPLY_HINT;
 }
 
+function appendConversationFields(
+  fields: string[],
+  msg: GatewayInboundMessage,
+): void {
+  const conversationId = sanitizeSenderName(msg.conversation.id);
+  fields.push(`conversation_id: ${conversationId}`);
+  if (isThirdPartyConversation(msg.conversation.id)) {
+    fields.push(`channel: ${sanitizeSenderName(msg.channel)}`);
+  }
+}
+
 /** Minimal shape of one batched inbound entry. Matches the BotCord channel
  * `BatchedInboxRaw.batch[]` elements but expressed structurally so the
  * composer doesn't import channel internals. */
@@ -205,6 +216,7 @@ export function composeBotCordUserTurn(msg: GatewayInboundMessage): string {
     `from: ${sanitizedSenderLabel}`,
     `to: ${msg.accountId}`,
   ];
+  appendConversationFields(headerFields, msg);
   if (isGroup && roomTitle) {
     const safeRoom = sanitizeSenderName(roomTitle.replace(/[\r\n]+/g, " "));
     headerFields.push(`room: ${safeRoom}`);
@@ -267,6 +279,7 @@ function composeBatchedTurn(
     `[BotCord Messages (${batch.length} new)]`,
     `to: ${msg.accountId}`,
   ];
+  appendConversationFields(header, msg);
   if (isGroup && roomTitle) {
     const safeRoom = sanitizeSenderName(roomTitle.replace(/[\r\n]+/g, " "));
     header.push(`room: ${safeRoom}`);