lark-remote 0.2.1 → 0.3.0

package/dist/connector/index.d.ts

@@ -114,7 +114,6 @@ export declare class FeishuConnector {
     }): Promise<InboundMediaPayload>;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
-    reconnect(): Promise<void>;
     /**
      * Send a message with automatic rate-limit retry (§9.5).
      * Encounters rate_limited / feishuCode 99991400|99991401（SDK 归类为
@@ -141,11 +140,30 @@ export declare class FeishuConnector {
      * The SDK resolves the reaction id internally; missing reaction is a no-op.
      */
     removeReactionByEmoji(messageId: string, emoji: string): Promise<void>;
+    /**
+     * sendFile/sendImage 共用：校验文件存在与大小上限（30MB，对齐飞书
+     * im/v1 上传 API）。noun 是消息里的小写名词（'file'/'image'）。
+     */
+    private checkUploadable;
+    /**
+     * sendFile/sendImage 共用骨架：token → 上传（流在任何失败路径销毁，P2-18）
+     * → 发送媒体消息。上传端点 / form 字段 / 响应 key / msg_type 的差异由调用方
+     * 以 uploadUrl + buildForm + keyField + msgType 表达；timeout、noKeepAliveAgent
+     * （Bun keep-alive 修复）与错误包装在此单源。label 是对外错误前缀与日志
+     * 标签（'sendFile' | 'sendImage'）。
+     */
+    private uploadAndSendMedia;
     /**
      * Upload a file to Feishu and send it to the specified chat.
      * Uses the im/v1/files upload API.
      */
     sendFile(chatId: string, filePath: string): Promise<string>;
+    /**
+     * Upload a local image file to Feishu and send it as an image message
+     * (im/v1/images + msg_type=image). Used by the clone wizard to deliver the
+     * scan-to-create QR code inline instead of as a downloadable file.
+     */
+    sendImage(chatId: string, filePath: string): Promise<string>;
     /**
      * Cached tenant_access_token for sendFile (P2-18). The token is valid ~2h;
      * fetching it on every file send wastes a round-trip and an unguarded fetch

package/dist/connector/index.js

@@ -288,12 +288,6 @@ export class FeishuConnector {
             this.isConnected = false;
         }
     }
-    async reconnect() {
-        // disconnect() swallows its own errors internally, so no try/catch needed
-        // here — it always resolves.
-        await this.disconnect();
-        await this.connect();
-    }
     /**
      * Send a message with automatic rate-limit retry (§9.5).
      * Encounters rate_limited / feishuCode 99991400|99991401（SDK 归类为
@@ -384,11 +378,10 @@ export class FeishuConnector {
         }
     }
     /**
-     * Upload a file to Feishu and send it to the specified chat.
-     * Uses the im/v1/files upload API.
+     * sendFile/sendImage 共用：校验文件存在与大小上限（30MB，对齐飞书
+     * im/v1 上传 API）。noun 是消息里的小写名词（'file'/'image'）。
      */
-    async sendFile(chatId, filePath) {
-        // Check file existence first with proper error handling
+    checkUploadable(filePath, noun) {
         let stat;
         try {
             stat = fs.statSync(filePath);
@@ -396,33 +389,32 @@ export class FeishuConnector {
         catch (err) {
             const code = err.code;
             if (code === 'ENOENT') {
-                throw new Error(`Cannot access file: file not found (${filePath})`, { cause: err });
+                throw new Error(`Cannot access ${noun}: file not found (${filePath})`, { cause: err });
             }
-            throw new Error(`Cannot access file: ${err.message}`, { cause: err });
+            throw new Error(`Cannot access ${noun}: ${err.message}`, { cause: err });
         }
-        // Check file size limit (30MB, aligned with Feishu im/v1/files API)
         if (stat.size > MAX_FILE_UPLOAD_SIZE) {
-            throw new Error(`File too large (${(stat.size / 1_000_000).toFixed(1)}MB), exceeds ${MAX_FILE_UPLOAD_SIZE / (1024 * 1024)}MB limit`);
+            const nounCap = noun.charAt(0).toUpperCase() + noun.slice(1);
+            throw new Error(`${nounCap} too large (${(stat.size / 1_000_000).toFixed(1)}MB), exceeds ${MAX_FILE_UPLOAD_SIZE / (1024 * 1024)}MB limit`);
         }
-        const fileName = displayName(filePath);
-        // P2-18: capture the read stream so it can be destroyed on any failure
-        // path. Without this, a token/upload/send failure leaks the fd (axios
-        // only closes the stream when it fully consumes it on success).
+    }
+    /**
+     * sendFile/sendImage 共用骨架：token → 上传（流在任何失败路径销毁，P2-18）
+     * → 发送媒体消息。上传端点 / form 字段 / 响应 key / msg_type 的差异由调用方
+     * 以 uploadUrl + buildForm + keyField + msgType 表达；timeout、noKeepAliveAgent
+     * （Bun keep-alive 修复）与错误包装在此单源。label 是对外错误前缀与日志
+     * 标签（'sendFile' | 'sendImage'）。
+     */
+    async uploadAndSendMedia(chatId, filePath, label, uploadUrl, buildForm, keyField, msgType) {
         let fileStream = null;
         try {
-            // P2-18: tenant_access_token cache. Avoid re-fetching on every file send
-            // (token is valid ~2h); validate data.code before trusting the token.
+            // P2-18: tenant_access_token cache（~2h），避免每次发送都取 token。
             const accessToken = await this.getTenantAccessToken();
-            // Upload file
-            const form = new FormData();
             fileStream = fs.createReadStream(filePath);
-            form.append('file', fileStream);
-            form.append('file_name', fileName);
-            form.append('file_type', 'stream');
-            // P2-18: timeout on the upload (large file, slow link) — 120s.
-            // httpsAgent: noKeepAlive — prevents Bun from reusing a server-RST'd
-            // keep-alive socket (ECONNRESET after ~30s; see noKeepAliveAgent docs).
-            const uploadResp = await axios.post('https://open.feishu.cn/open-apis/im/v1/files', form, {
+            const form = buildForm(fileStream);
+            // P2-18: timeout 120s（大文件慢链路）；httpsAgent: noKeepAlive 防止
+            // Bun 复用已被服务端 RST 的 keep-alive socket（ECONNRESET after ~30s）。
+            const uploadResp = await axios.post(uploadUrl, form, {
                 headers: {
                     ...form.getHeaders(),
                     Authorization: `Bearer ${accessToken}`,
@@ -431,15 +423,14 @@ export class FeishuConnector {
                 httpsAgent: noKeepAliveAgent,
             });
             if (uploadResp.data.code !== 0) {
-                throw new Error(`File upload failed: ${uploadResp.data.msg}`);
+                throw new Error(`Upload failed: ${uploadResp.data.msg}`);
             }
-            const fileKey = uploadResp.data.data.file_key;
-            // Send file message. P2-18: timeout 30s.
-            // httpsAgent: noKeepAlive — same Bun keep-alive fix as upload above.
+            const mediaKey = uploadResp.data.data[keyField];
+            // P2-18: timeout 30s；noKeepAlive 同上。
             const sendResp = await axios.post('https://open.feishu.cn/open-apis/im/v1/messages', {
                 receive_id: chatId,
-                msg_type: 'file',
-                content: JSON.stringify({ file_key: fileKey }),
+                msg_type: msgType,
+                content: JSON.stringify({ [keyField]: mediaKey }),
             }, {
                 headers: {
                     'Content-Type': 'application/json; charset=utf-8',
@@ -450,7 +441,7 @@ export class FeishuConnector {
                 httpsAgent: noKeepAliveAgent,
             });
             if (sendResp.data.code !== 0) {
-                throw new Error(`File message failed: ${sendResp.data.msg}`);
+                throw new Error(`Media message failed: ${sendResp.data.msg}`);
             }
             return sendResp.data.data.message_id;
         }
@@ -464,12 +455,39 @@ export class FeishuConnector {
                     /* already destroyed */
                 }
             }
-            // Log the error but throw a formatted error to prevent unhandled rejection
             const errorInfo = this.formatError(err);
-            getLogger().error('[feishu] sendFile failed:', errorInfo);
-            throw new Error(`sendFile failed: ${errorInfo}`, { cause: err });
+            getLogger().error(`[feishu] ${label} failed:`, errorInfo);
+            throw new Error(`${label} failed: ${errorInfo}`, { cause: err });
         }
     }
+    /**
+     * Upload a file to Feishu and send it to the specified chat.
+     * Uses the im/v1/files upload API.
+     */
+    async sendFile(chatId, filePath) {
+        this.checkUploadable(filePath, 'file');
+        return this.uploadAndSendMedia(chatId, filePath, 'sendFile', 'https://open.feishu.cn/open-apis/im/v1/files', (stream) => {
+            const form = new FormData();
+            form.append('file', stream);
+            form.append('file_name', displayName(filePath));
+            form.append('file_type', 'stream');
+            return form;
+        }, 'file_key', 'file');
+    }
+    /**
+     * Upload a local image file to Feishu and send it as an image message
+     * (im/v1/images + msg_type=image). Used by the clone wizard to deliver the
+     * scan-to-create QR code inline instead of as a downloadable file.
+     */
+    async sendImage(chatId, filePath) {
+        this.checkUploadable(filePath, 'image');
+        return this.uploadAndSendMedia(chatId, filePath, 'sendImage', 'https://open.feishu.cn/open-apis/im/v1/images', (stream) => {
+            const form = new FormData();
+            form.append('image_type', 'message');
+            form.append('image', stream);
+            return form;
+        }, 'image_key', 'image');
+    }
     /**
      * Cached tenant_access_token for sendFile (P2-18). The token is valid ~2h;
      * fetching it on every file send wastes a round-trip and an unguarded fetch

package/dist/index.js

@@ -15,7 +15,8 @@ import { buildCardActionFullValue } from './router/card-action-payload.js';
 import { Bridge } from './bridge/index.js';
 import { initLogger, getLogger } from './logger/index.js';
 import { StartupContactStore, sendStartupHello } from './startup-contact.js';
-import { OwnerBinder, formatPinGuidance } from './binder.js';
+import { OwnerBinder, formatBindGuidance } from './binder.js';
+import { CloneSession } from './clone.js';
 import { InstanceAlreadyRunningError, InstanceLock } from './instance-lock.js';
 import { spawnReplacementBridge, waitForPreviousInstance } from './restart.js';
 import { checkLatestVersion, isNewer, runInstallLatest, formatUpdateHint } from './update/index.js';
@@ -26,6 +27,14 @@ import { newSessionButton, resumeCompactButton, agentDisplayName } from './card/
 import path from 'node:path';
 import fs from 'node:fs';
 import { silentlyUnlink } from './common/fs.js';
+/**
+ * /stop 命令别名单源：普通消息的停止分支与 clone 活跃期拦截的排除条件
+ * 共用同一判定，防止将来加别名时两处漂移。
+ */
+function isStopCommand(text) {
+    const t = text.trim().toLowerCase();
+    return t === '/stop' || t === '/t';
+}
 /** Send auto-resume card for a restored session */
 async function sendAutoResumeCard(connector, contact, cwd, session, state, compactSupported = false) {
     if (!contact.userId)
@@ -280,7 +289,7 @@ function initializeRunner(config, configDir, cliArgs) {
     return { agentRegistry, sessionReaderRegistry };
 }
 /** Setup message and card action handlers. */
-function setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config) {
+function setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config, cloneSession) {
     // 入站媒体（图片/文件）：先认证后下载（P1 review 修复）。
     // connector 只上报"媒体到达"，这里先过 owner + enabled 闸门，通过后才
     // 下载——未认证/关闭配置时不会发生任何网络下载或内存/磁盘占用。
@@ -324,13 +333,10 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         })().catch((err) => logger.error('[media] inbound media download/save failed:', err));
     });
     connector.setMessageHandler((msg) => {
-        // 绑定/授权闸门：仅 owner 放行；非 owner 静默丢弃；未绑定时要求 PIN 认领
+        // 绑定/授权闸门：仅 owner 放行；非 owner 静默丢弃；未绑定时首条消息（任意内容）认领
         const decision = binder.classify(msg.userId, msg.content, msg.chatId);
         if (decision.kind === 'rejected')
             return;
-        // 未绑定且 PIN 错误：完全静默丢弃（不回复、不提醒）
-        if (decision.kind === 'pin_wrong')
-            return;
         if (decision.kind === 'bind_success') {
             // First-run onboarding: set default cwd + send welcome + Help card.
             // setCwd is synchronous (outside the async closure) so that the user's
@@ -385,12 +391,23 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         bridge.flushMediaNotifications(msg.userId, msg.chatId);
         // Add Typing reaction to indicate "still alive"
         void connector.addReaction(msg.messageId, 'Typing');
+        // 复制分身流程活跃期：一切消息先经 clone 状态机（stop 命令除外，保留其
+        // 绕队列停止能力），不转发 coding agent、不进命令分发、不展开别名。
+        if (cloneSession.isActive() && !isStopCommand(msg.content)) {
+            void cloneSession
+                .handleMessage(msg.content, {
+                userId: msg.userId,
+                chatId: msg.chatId,
+                messageId: msg.messageId,
+            })
+                .catch((err) => logger.error('[clone] message handling failed:', err));
+            return;
+        }
         // 别名展开：命令分发前对消息做一次 $name 展开（不递归）。
         // `!` / `/` 开头的消息不会进入展开路径（$PATH、$HOME 等 shell 变量不受影响），
         // 未知 $xxx 原样透传；展开结果若以 `/` 开头会自然落入命令路径。
         const content = router.expandAliasMessage(msg.content);
-        const trimmedLower = content.trim().toLowerCase();
-        if (trimmedLower === '/stop' || trimmedLower === '/t') {
+        if (isStopCommand(content)) {
             void (async () => {
                 const stopped = await bridge.interruptCurrentRun({
                     userId: msg.userId,
@@ -619,10 +636,10 @@ async function main() {
     const connector = new FeishuConnector(config);
     const startupContactStore = new StartupContactStore(path.join(configDir, 'startup-contact.json'));
     const binder = new OwnerBinder(startupContactStore);
-    if (binder.pendingPin) {
-        // 未绑定：控制台（stderr）展示 PIN。守护模式下被 watchdog 重定向到 daemon 日志
-        console.error(formatPinGuidance(binder.pendingPin));
-        logger.info('[binder] awaiting first binding (PIN printed to stderr)');
+    if (!binder.isBound()) {
+        // 未绑定：控制台（stderr）引导任意消息绑定。守护模式下被 watchdog 重定向到日志
+        console.error(formatBindGuidance());
+        logger.info('[binder] awaiting first binding (any first private message binds)');
     }
     else {
         logger.info(`[binder] bound to owner openId=${binder.boundOpenId()}`);
@@ -637,6 +654,11 @@ async function main() {
         agentRegistry,
         sessionReaderRegistry,
     });
+    const cloneSession = new CloneSession({
+        connector,
+        configPath: path.join(configDir, 'config.yaml'),
+        configDir,
+    });
     const router = new CommandRouter({
         sessionStore,
         bridge,
@@ -648,8 +670,9 @@ async function main() {
         sessionReaderRegistry,
         devMode: cliArgs.dev,
         updateCachePath: path.join(configDir, 'update-cache.json'),
+        cloneSession,
     });
-    setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config);
+    setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config, cloneSession);
     try {
         await connector.connect();
     }

package/dist/platform/command.d.ts

@@ -1,5 +1,7 @@
 import type { LaunchSpec } from './types.js';
 export type { LaunchSpec } from './types.js';
+/** 判断一个已命中的 bash.exe 是否只是 WSL 启动器（而非 Git Bash）。 */
+export declare function isWslBashLauncher(file: string): boolean;
 export interface ResolveOptions {
     platform?: NodeJS.Platform;
     /** PATH 环境变量注入（测试用）；默认 process.env.PATH */

package/dist/platform/command.js

@@ -18,6 +18,33 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { currentPlatform, isWin32 } from './select.js';
 const DEFAULT_PATHEXT = ['.exe', '.bat', '.cmd'];
+/**
+ * win32 的「假 bash」：`%SystemRoot%\system32\bash.exe`（SysWOW64 同理）不是
+ * Git Bash，而是 WSL 启动器（wsl.exe 的 bash 别名）。PATH 里 system32 通常
+ * 排在 Git\cmd 之前，按目录顺序命中它会把整条 `!` 命令丢进 WSL 发行版执行：
+ * 工作目录变成 /mnt/d/...、node 变成 WSL 里装的那个版本。实测本机 WSL node
+ * 为 v12，加载 dist/index.js 的 ES2022 语法（?? / ?.）直接
+ * `SyntaxError: Unexpected token '?'`，`!lark-remote -v` 因此失败。
+ *
+ * 因此解析 `bash` 时必须跳过它，继续在 PATH 中找真正的 Git Bash。
+ *
+ * 判定只看两层目录名（`<...>\system32\bash.exe`）：Git Bash 装在
+ * `<Git>\bin` / `<Git>\usr\bin`，不会叫 system32；反过来把真正的 Git Bash
+ * 装在名为 system32 的目录里也可以忽略。
+ */
+const WSL_BASH_PARENT_DIRS = ['system32', 'syswow64'];
+/** 判断一个已命中的 bash.exe 是否只是 WSL 启动器（而非 Git Bash）。 */
+export function isWslBashLauncher(file) {
+    const normalized = file.replaceAll('/', '\\').toLowerCase();
+    if (path.win32.basename(normalized) !== 'bash.exe')
+        return false;
+    return WSL_BASH_PARENT_DIRS.includes(path.win32.basename(path.win32.dirname(normalized)));
+}
+/** 查询目标是 bash（`bash` 或显式 `bash.exe`）时才走上面的特例。 */
+function isBashQuery(name) {
+    const lower = name.toLowerCase();
+    return lower === 'bash' || lower === 'bash.exe';
+}
 /**
  * 缓存 TTL：probe 层（runner/probe.ts）5 分钟，本层更短——bridge 运行期间
  * 用户新装/卸载 agent（典型场景：按 /config 不可用提示去安装）后，最迟
@@ -56,17 +83,42 @@ function existsWin32(file) {
         return posixForm;
     return null;
 }
+/**
+ * Git for Windows 只把 `Git\cmd` 放进 PATH（里面没有 bash.exe），真正的
+ * bash 在 `Git\bin\bash.exe` / `Git\usr\bin\bash.exe`。PATH 里只暴露 cmd
+ * 目录时，从 cmd 反推安装根再找 bash。
+ */
+function resolveBashFromGitCmdDir(pathEnv) {
+    for (const dir of listPathDirs(pathEnv, 'win32')) {
+        if (path.win32.basename(dir).toLowerCase() !== 'cmd')
+            continue;
+        const root = path.win32.dirname(dir);
+        for (const rel of ['bin\\bash.exe', 'usr\\bin\\bash.exe']) {
+            const found = existsWin32(path.win32.join(root, rel));
+            if (found)
+                return { kind: 'direct', file: found };
+        }
+    }
+    return null;
+}
 function resolveWin32(name, pathEnv, pathExt) {
     const hasExtension = /\.[A-Za-z0-9]+$/.test(name);
+    const bashQuery = isBashQuery(name);
     for (const dir of listPathDirs(pathEnv, 'win32')) {
         const candidates = hasExtension ? [name] : pathExt.map((ext) => name + ext);
         for (const candidate of candidates) {
             const found = existsWin32(path.win32.join(dir, candidate));
+            if (!found)
+                continue;
+            // WSL 启动器不是 Git Bash：跳过，继续找后面的 PATH 目录
+            if (bashQuery && isWslBashLauncher(found))
+                continue;
             // .cmd/.bat 垫片命中即报告垫片路径本身；执行语义由 cross-spawn 负责
-            if (found)
-                return { kind: 'direct', file: found };
+            return { kind: 'direct', file: found };
         }
     }
+    if (bashQuery)
+        return resolveBashFromGitCmdDir(pathEnv);
     return null;
 }
 function resolvePosix(name, pathEnv) {

package/dist/restart.d.ts

@@ -8,6 +8,23 @@
  */
 /** Env var telling a replacement child which parent pid to wait for before acquiring the instance lock. */
 export declare const RESTART_WAIT_PID_ENV = "LARK_REMOTE_RESTART_WAIT_PID";
+/**
+ * Spawn a detached bridge process (shared by /restart replacement and /clone
+ * new-instance) whose early output — before the child's own file logger
+ * initializes — lands on logFilePath. Returns the child pid, or null when
+ * spawn failed synchronously / no pid; filesystem errors (unwritable log
+ * dir) propagate. Caller picks throw-vs-degrade semantics.
+ *
+ * Two disciplines live here so every caller inherits them for free:
+ * - windowsHide: win32 detached children would flash a console window (§3.7);
+ * - the 'error' handler is attached BEFORE the pid check — a failed spawn
+ *   emits 'error' asynchronously (ENOENT/EACCES), and the synchronous pid
+ *   check throws/returns first, so attaching after would leave the 'error'
+ *   event unhandled → uncaughtException kills the parent.
+ */
+export declare function spawnDetachedBridge(args: string[], logFilePath: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+}): number | null;
 /**
  * Spawn a detached replacement bridge with the same executable and argv
  * (including --config-dir) and return its pid. The caller is expected to

package/dist/restart.js

@@ -15,6 +15,41 @@ import { sleep } from './common/sleep.js';
 export const RESTART_WAIT_PID_ENV = 'LARK_REMOTE_RESTART_WAIT_PID';
 const WAIT_TIMEOUT_MS = 20_000;
 const POLL_MS = 100;
+/**
+ * Spawn a detached bridge process (shared by /restart replacement and /clone
+ * new-instance) whose early output — before the child's own file logger
+ * initializes — lands on logFilePath. Returns the child pid, or null when
+ * spawn failed synchronously / no pid; filesystem errors (unwritable log
+ * dir) propagate. Caller picks throw-vs-degrade semantics.
+ *
+ * Two disciplines live here so every caller inherits them for free:
+ * - windowsHide: win32 detached children would flash a console window (§3.7);
+ * - the 'error' handler is attached BEFORE the pid check — a failed spawn
+ *   emits 'error' asynchronously (ENOENT/EACCES), and the synchronous pid
+ *   check throws/returns first, so attaching after would leave the 'error'
+ *   event unhandled → uncaughtException kills the parent.
+ */
+export function spawnDetachedBridge(args, logFilePath, opts) {
+    fs.mkdirSync(path.dirname(logFilePath), { recursive: true });
+    const out = fs.openSync(logFilePath, 'a');
+    try {
+        const child = spawnProcess(process.execPath, args, {
+            cwd: process.cwd(),
+            env: opts?.env ?? process.env,
+            detached: true,
+            windowsHide: true,
+            stdio: ['ignore', out, out],
+        });
+        child.on('error', () => { });
+        if (child.pid === undefined)
+            return null;
+        child.unref();
+        return child.pid;
+    }
+    finally {
+        fs.closeSync(out);
+    }
+}
 /**
  * Spawn a detached replacement bridge with the same executable and argv
  * (including --config-dir) and return its pid. The caller is expected to
@@ -22,29 +57,13 @@ const POLL_MS = 100;
  * startup failures (before the file logger initializes) are not lost.
  */
 export function spawnReplacementBridge(logsDir) {
-    fs.mkdirSync(logsDir, { recursive: true });
-    const out = fs.openSync(path.join(logsDir, 'restart-child.log'), 'a');
-    const child = spawnProcess(process.execPath, process.argv.slice(1), {
-        cwd: process.cwd(),
+    const pid = spawnDetachedBridge(process.argv.slice(1), path.join(logsDir, 'restart-child.log'), {
         env: { ...process.env, [RESTART_WAIT_PID_ENV]: String(process.pid) },
-        detached: true,
-        // win32：detached 继任者默认会闪控制台窗口（§3.7）
-        windowsHide: true,
-        stdio: ['ignore', out, out],
     });
-    // Late spawn errors (e.g. binary removed mid-run) must not crash the
-    // exiting parent via an unhandled 'error' event. Attach BEFORE the pid
-    // check — a failed spawn emits 'error' asynchronously (ENOENT/EACCES),
-    // and the pid check below throws synchronously first, so attaching after
-    // the throw would leave the 'error' event unhandled → uncaughtException
-    // → the old bridge exits despite having promised to stay alive.
-    child.on('error', () => { });
-    fs.closeSync(out);
-    if (child.pid === undefined) {
+    if (pid === null) {
         throw new Error('spawn replacement bridge failed: no pid');
     }
-    child.unref();
-    return child.pid;
+    return pid;
 }
 /**
  * On startup, if this process was spawned as a restart replacement, wait for

package/dist/router/index.d.ts

@@ -2,6 +2,7 @@ import type { SessionStore, SessionReaderRegistry } from '../session/index.js';
 import type { AppConfig } from '../config/index.js';
 import type { Bridge } from '../bridge/index.js';
 import type { AgentBinding } from '../bridge/queue-manager.js';
+import type { CloneSession } from '../clone.js';
 import { type VersionCheckResult, type InstallResult } from '../update/index.js';
 interface CommandContext {
     userId: string;
@@ -125,6 +126,8 @@ export declare class CommandRouter {
     private devMode;
     /** Cache file for version checks (<configDir>/update-cache.json). */
     private updateCachePath?;
+    /** 复制分身状态机（/clone 入口 + 活跃期消息拦截）。 */
+    private cloneSession?;
     /** Injected update functions (for testability; defaults to real implementation). */
     private updateFns;
     /** /config 卡片编辑暂存区（public：测试直接读取断言，替代 as unknown as）。 */
@@ -177,6 +180,8 @@ export declare class CommandRouter {
         devMode?: boolean;
         /** Version check cache path (<configDir>/update-cache.json). */
         updateCachePath?: string;
+        /** 复制分身状态机（/clone；index.ts 构造注入，未注入时命令回报不可用）。 */
+        cloneSession?: CloneSession;
         /** Override update functions for testability. */
         updateFns?: {
             checkLatestVersion?: (opts?: {
@@ -455,6 +460,11 @@ export declare class CommandRouter {
      * Flow: check version → if newer, install → report success (no auto-restart).
      */
     private cmdUpdate;
+    /**
+     * /clone [name] — 复制分身：进入 clone 状态机（发二维码、等扫码、自动绑定）。
+     * 全程由 CloneSession 自己经 connector 发消息（含二维码图片），故返回 null。
+     */
+    private cmdClone;
     private cmdNew;
     private cmdCd;
     private readSessionDisplayState;
@@ -548,7 +558,6 @@ export declare class CommandRouter {
      * Paginates with ACTIVE_PAGE_SIZE (default 20) items per page.
      */
     private buildActiveCardFromMemory;
-    private cmdReconnect;
     private cmdConfig;
     /**
      * DSH /config 卡片构建前异步预取模型/预设目录（§4.2 动态清单）。