@co0ontty/wand 1.22.0 → 1.23.0

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 import process from "node:process";
 import { hasConfigFile, isPreferenceKey, loadConfigWithStorage, resolveConfigPath, saveConfig, writePreferenceToStorage, } from "./config.js";
+import { readLiveInstance, removePidfile, removeSocketFile, socketPath, writePidfile, } from "./pidfile.js";
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0] || "help";
@@ -13,12 +14,28 @@ async function main() {
         case "web": {
             const useTui = shouldUseTui();
             // web 命令下"已存在"的 ready 信息由统一的启动 banner / TUI 展示，避免重复。
-            // "Created..." 这种首次创建事件仍会输出（ensureRequiredFiles 内部判断）。
             const config = await ensureRequiredFiles(configPath, { silentReady: true });
+            // —— 单实例检测：如果已有 wand 主进程在跑，直接 attach 而不重启服务 ——
+            const live = readLiveInstance(configPath);
+            if (live) {
+                await runAttach(live, configPath, useTui);
+                break;
+            }
             const { ensureNodePtyHelperExecutable } = await import("./ensure-node-pty-helper.js");
             ensureNodePtyHelperExecutable();
             const { startServer } = await import("./server.js");
             const handle = await startServer(config, configPath);
+            // —— 注册实例：写 pidfile + 启动 IPC 服务端（TUI / banner 模式都需要） ——
+            const startedAtMs = Date.now();
+            const ipcCtx = await registerInstance(handle, configPath, startedAtMs);
+            const cleanup = async () => {
+                try {
+                    await ipcCtx.close();
+                }
+                catch { /* noop */ }
+                removePidfile(configPath);
+                removeSocketFile(configPath);
+            };
             if (useTui) {
                 const { startTui } = await import("./tui/index.js");
                 const tui = startTui({
@@ -32,6 +49,7 @@ async function main() {
                     urls: handle.urls,
                     orphanRecoveredCount: handle.orphanRecoveredCount,
                     onExit: async () => {
+                        await cleanup();
                         await handle.close();
                         process.exit(0);
                     },
@@ -42,6 +60,16 @@ async function main() {
             }
             else {
                 printStartupBanner(handle);
+                const onSignal = async () => {
+                    await cleanup();
+                    try {
+                        await handle.close();
+                    }
+                    catch { /* noop */ }
+                    process.exit(0);
+                };
+                process.on("SIGINT", () => { void onSignal(); });
+                process.on("SIGTERM", () => { void onSignal(); });
             }
             break;
         }
@@ -111,7 +139,7 @@ function printHelp() {
 
 Commands:
   wand init                 Create default files in ~/.wand/
-  wand web                  Start web console server
+  wand web                  Start web console server (or attach to running one)
   wand config:path          Print resolved config path
   wand config:show          Print current config
   wand config:set           Update a simple config value
@@ -186,6 +214,87 @@ function printStartupBanner(handle) {
     }
     process.stdout.write(lines.join("\n") + "\n");
 }
+/** 写 pidfile + 启动 IPC 服务端。返回 cleanup 用的 close()。 */
+async function registerInstance(handle, configPath, startedAtMs) {
+    const sockPath = socketPath(configPath);
+    const primary = handle.urls[0];
+    const pidInfo = {
+        pid: process.pid,
+        version: handle.version,
+        startedAt: startedAtMs,
+        url: primary ? primary.url : `${handle.httpsEnabled ? "https" : "http"}://${handle.bindAddr}`,
+        scheme: primary ? primary.scheme : (handle.httpsEnabled ? "HTTPS" : "HTTP"),
+        bindAddr: handle.bindAddr,
+        configPath: handle.configPath,
+        dbPath: handle.dbPath,
+        socket: sockPath,
+    };
+    // Windows 不开 IPC，仍然写 pidfile（attach 模式会跳过，但能给运维查 PID）
+    if (!sockPath) {
+        writePidfile(configPath, pidInfo);
+        return { close: async () => { } };
+    }
+    const { startIpcServer } = await import("./tui/ipc-server.js");
+    const { buildSnapshotData } = await import("./tui/snapshot.js");
+    const ipc = startIpcServer({
+        socketPath: sockPath,
+        snapshotProvider: () => buildSnapshotData({
+            version: handle.version,
+            url: pidInfo.url,
+            scheme: pidInfo.scheme,
+            bindAddr: handle.bindAddr,
+            configPath: handle.configPath,
+            dbPath: handle.dbPath,
+            orphanRecoveredCount: handle.orphanRecoveredCount,
+            startedAtMs,
+            pid: process.pid,
+            processManager: handle.processManager,
+            structuredSessions: handle.structuredSessions,
+        }),
+        onShutdown: async () => {
+            try {
+                await handle.close();
+            }
+            catch { /* noop */ }
+            removePidfile(configPath);
+            removeSocketFile(configPath);
+            process.exit(0);
+        },
+    });
+    writePidfile(configPath, pidInfo);
+    return {
+        close: async () => {
+            try {
+                await ipc?.close();
+            }
+            catch { /* noop */ }
+        },
+    };
+}
+/** 进入 attach 模式。 */
+async function runAttach(live, configPath, useTui) {
+    if (!live.socket) {
+        // Windows 没 socket：直接打印信息后退出
+        process.stdout.write(`[wand] detected running instance pid=${live.pid} at ${live.url}\n` +
+            `       attach mode requires unix socket which is unavailable on this platform\n`);
+        process.exit(0);
+    }
+    if (!useTui) {
+        process.stdout.write(`[wand] running instance detected (pid=${live.pid}) at ${live.url}\n` +
+            `       socket=${live.socket}\n` +
+            `       use 'wand web' from a TTY to open the attach TUI\n`);
+        process.exit(0);
+    }
+    const { startAttachTui } = await import("./tui/attach.js");
+    const tui = startAttachTui({
+        pidInfo: live,
+        configPath,
+        onExit: async () => { process.exit(0); },
+    });
+    const onSignal = () => { void tui.stop(); };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+}
 function setConfigValue(config, key, value) {
     // 偏好字段（defaultMode/defaultCwd/...）由调用方分流到 storage，这里只处理 JSON 字段。
     switch (key) {

package/dist/pidfile.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 单实例 pidfile + IPC 套接字路径。
+ *
+ * 用途：
+ * 1. `wand web` 启动时先看 pidfile 是否活着，活着则进入 attach 模式（不再重复启动服务）。
+ * 2. 主进程通过 wand.sock 暴露控制平面 IPC，attach 客户端通过它拉 snapshot / 发命令。
+ *
+ * 文件位置：均放在 configPath 的同目录（与 wand.db 一致）。
+ *
+ * 平台说明：
+ * - Linux / macOS 使用 Unix domain socket。
+ * - Windows 不支持，attach 模式直接跳过；新启的 `wand web` 仍会按老逻辑启动（端口冲突时报错）。
+ */
+export interface PidInfo {
+    pid: number;
+    version: string;
+    /** 主进程启动时间 (ms epoch)。 */
+    startedAt: number;
+    url: string;
+    scheme: "HTTP" | "HTTPS";
+    bindAddr: string;
+    configPath: string;
+    dbPath: string;
+    /** Unix socket 绝对路径；Windows 下为空字符串。 */
+    socket: string;
+}
+export declare function pidfilePath(configPath: string): string;
+export declare function socketPath(configPath: string): string;
+/** 原子写：先写到 .tmp 再 rename。 */
+export declare function writePidfile(configPath: string, info: PidInfo): void;
+/** 读取并校验。文件不存在 / 损坏 / 进程不在 → 返回 null。 */
+export declare function readPidfile(configPath: string): PidInfo | null;
+/** 通过 `kill 0` 判断 PID 是否还活着（不发送信号，只检查存在性）。 */
+export declare function isPidAlive(pid: number): boolean;
+export declare function removePidfile(configPath: string): void;
+export declare function removeSocketFile(configPath: string): void;
+/** 读取 pidfile 并校验进程是否还活着。Stale 文件会自动清理。 */
+export declare function readLiveInstance(configPath: string): PidInfo | null;

package/dist/pidfile.js

@@ -0,0 +1,117 @@
+/**
+ * 单实例 pidfile + IPC 套接字路径。
+ *
+ * 用途：
+ * 1. `wand web` 启动时先看 pidfile 是否活着，活着则进入 attach 模式（不再重复启动服务）。
+ * 2. 主进程通过 wand.sock 暴露控制平面 IPC，attach 客户端通过它拉 snapshot / 发命令。
+ *
+ * 文件位置：均放在 configPath 的同目录（与 wand.db 一致）。
+ *
+ * 平台说明：
+ * - Linux / macOS 使用 Unix domain socket。
+ * - Windows 不支持，attach 模式直接跳过；新启的 `wand web` 仍会按老逻辑启动（端口冲突时报错）。
+ */
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+export function pidfilePath(configPath) {
+    return path.resolve(path.dirname(configPath), "wand.pid");
+}
+export function socketPath(configPath) {
+    if (process.platform === "win32")
+        return "";
+    return path.resolve(path.dirname(configPath), "wand.sock");
+}
+/** 原子写：先写到 .tmp 再 rename。 */
+export function writePidfile(configPath, info) {
+    const file = pidfilePath(configPath);
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, JSON.stringify(info, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, file);
+}
+/** 读取并校验。文件不存在 / 损坏 / 进程不在 → 返回 null。 */
+export function readPidfile(configPath) {
+    const file = pidfilePath(configPath);
+    if (!existsSync(file))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const info = parsed;
+    if (typeof info.pid !== "number" ||
+        typeof info.version !== "string" ||
+        typeof info.startedAt !== "number" ||
+        typeof info.url !== "string" ||
+        typeof info.scheme !== "string" ||
+        typeof info.bindAddr !== "string" ||
+        typeof info.configPath !== "string" ||
+        typeof info.dbPath !== "string" ||
+        typeof info.socket !== "string") {
+        return null;
+    }
+    return info;
+}
+/** 通过 `kill 0` 判断 PID 是否还活着（不发送信号，只检查存在性）。 */
+export function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH = no such process；EPERM = 存在但无权限发信号，仍然算活着
+        const code = err.code;
+        return code === "EPERM";
+    }
+}
+export function removePidfile(configPath) {
+    try {
+        unlinkSync(pidfilePath(configPath));
+    }
+    catch {
+        /* noop */
+    }
+}
+export function removeSocketFile(configPath) {
+    const p = socketPath(configPath);
+    if (!p)
+        return;
+    try {
+        unlinkSync(p);
+    }
+    catch {
+        /* noop */
+    }
+}
+/** 读取 pidfile 并校验进程是否还活着。Stale 文件会自动清理。 */
+export function readLiveInstance(configPath) {
+    const info = readPidfile(configPath);
+    if (!info)
+        return null;
+    if (info.pid === process.pid)
+        return null; // 自身（防御性）
+    if (!isPidAlive(info.pid)) {
+        // stale，顺手清理
+        removePidfile(configPath);
+        removeSocketFile(configPath);
+        return null;
+    }
+    // 进程活着但 socket 不在 → 多半是异常崩溃后被某种监控拉起。视为不可用。
+    if (info.socket && !existsSync(info.socket))
+        return null;
+    return info;
+}

package/dist/tui/attach.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Attach 模式 TUI：当本机已有 wand 主进程在跑时，新启动的 `wand web` 会进入此模式。
+ *
+ * 数据来源：通过 wand.sock IPC 拉 snapshot（每秒一次），渲染同一套 layout。
+ * 日志面板：因为日志在主进程里，attach 端没法直接看；这里改成"活动流"——
+ *   监听 snapshot 差分，把会话起止 / 总数变化打到 log 面板。
+ */
+import { PidInfo } from "../pidfile.js";
+export interface AttachTuiDeps {
+    pidInfo: PidInfo;
+    configPath: string;
+    /** 退出时调用。 */
+    onExit: () => void | Promise<void>;
+}
+export interface AttachTuiHandle {
+    stop(): Promise<void>;
+}
+export declare function startAttachTui(deps: AttachTuiDeps): AttachTuiHandle;

package/dist/tui/attach.js

@@ -0,0 +1,306 @@
+/**
+ * Attach 模式 TUI：当本机已有 wand 主进程在跑时，新启动的 `wand web` 会进入此模式。
+ *
+ * 数据来源：通过 wand.sock IPC 拉 snapshot（每秒一次），渲染同一套 layout。
+ * 日志面板：因为日志在主进程里，attach 端没法直接看；这里改成"活动流"——
+ *   监听 snapshot 差分，把会话起止 / 总数变化打到 log 面板。
+ */
+import { checkUpdate, copyToClipboard, installService, installUpdate, isServiceInstalled, openInBrowser, uninstallService, } from "./commands.js";
+import { spawnSync } from "node:child_process";
+import { IpcClient } from "./ipc-client.js";
+import { buildLayout } from "./layout.js";
+import { openServicePanel } from "./service-panel.js";
+const POLL_INTERVAL_MS = 1000;
+export function startAttachTui(deps) {
+    const layout = buildLayout();
+    let active = true;
+    let stopping = false;
+    const client = new IpcClient(deps.pidInfo.socket);
+    client.start();
+    // 渲染一个"等连接"的初始 header
+    const placeholderHeader = {
+        version: deps.pidInfo.version,
+        url: deps.pidInfo.url,
+        scheme: deps.pidInfo.scheme,
+        bindAddr: deps.pidInfo.bindAddr,
+        configPath: deps.pidInfo.configPath,
+        dbPath: deps.pidInfo.dbPath,
+        orphanRecoveredCount: 0,
+        sessionCounts: { active: 0, archived: 0, total: 0 },
+        startedAtMs: deps.pidInfo.startedAt,
+        rssBytes: 0,
+        serviceInstalled: safeServiceInstalled(),
+    };
+    layout.refreshHeader(placeholderHeader);
+    layout.refreshSessions([]);
+    appendActivity(`已 attach 到主进程 PID ${deps.pidInfo.pid}`);
+    appendActivity(`URL: ${deps.pidInfo.url}`);
+    appendActivity("正在连接 IPC 套接字…", "info");
+    client.on("connect", () => {
+        appendActivity("IPC 已连接，开始轮询 snapshot", "info");
+        void pollOnce();
+    });
+    client.on("disconnect", () => {
+        appendActivity("IPC 已断开，等待重连…", "warn");
+    });
+    client.on("error", (err) => {
+        appendActivity(`IPC 错误: ${err.message}`, "error");
+    });
+    let lastSessionsKey = "";
+    let lastTotal = -1;
+    async function pollOnce() {
+        if (!active)
+            return;
+        try {
+            const snap = await client.snapshot();
+            applySnapshot(snap);
+        }
+        catch (err) {
+            // 静默失败：断开后会自动重连，下个 tick 会再试
+            if (err.message !== "ipc not connected" && err.message !== "ipc disconnected") {
+                appendActivity(`snapshot 失败: ${err.message}`, "warn");
+            }
+        }
+    }
+    function applySnapshot(snap) {
+        const h = snap.header;
+        const header = {
+            version: h.version,
+            url: h.url,
+            scheme: h.scheme,
+            bindAddr: h.bindAddr,
+            configPath: h.configPath,
+            dbPath: h.dbPath,
+            orphanRecoveredCount: h.orphanRecoveredCount,
+            sessionCounts: h.sessionCounts,
+            startedAtMs: h.startedAtMs,
+            rssBytes: h.rssBytes,
+            serviceInstalled: safeServiceInstalled(),
+        };
+        layout.refreshHeader(header);
+        layout.refreshSessions(snap.sessions);
+        // 活动流：会话集合变化时输出一行
+        const key = snap.sessions.map((s) => `${s.id}:${s.state}`).join("|");
+        if (key !== lastSessionsKey) {
+            diffActivity(snap.sessions);
+            lastSessionsKey = key;
+        }
+        if (h.sessionCounts.total !== lastTotal) {
+            if (lastTotal !== -1) {
+                appendActivity(`会话计数: ${h.sessionCounts.active} active · ${h.sessionCounts.archived} archived · ${h.sessionCounts.total} total`, "info");
+            }
+            lastTotal = h.sessionCounts.total;
+        }
+    }
+    let lastRowState = new Map();
+    function diffActivity(rows) {
+        const next = new Map();
+        for (const r of rows)
+            next.set(r.id, r.state);
+        // 新增
+        for (const [id, state] of next) {
+            if (!lastRowState.has(id)) {
+                appendActivity(`+ ${id.slice(0, 8)} ${state}`, "info");
+            }
+            else if (lastRowState.get(id) !== state) {
+                appendActivity(`~ ${id.slice(0, 8)} ${lastRowState.get(id)} → ${state}`, "info");
+            }
+        }
+        // 离开
+        for (const [id, state] of lastRowState) {
+            if (!next.has(id))
+                appendActivity(`- ${id.slice(0, 8)} ${state}`, "info");
+        }
+        lastRowState = next;
+    }
+    function appendActivity(line, level = "info") {
+        layout.appendLog({ level, line: `[attach] ${line}`, ts: Date.now() });
+    }
+    const pollTimer = setInterval(() => { void pollOnce(); }, POLL_INTERVAL_MS);
+    pollTimer.unref?.();
+    // —— 键位 —— 服务面板打开时，屏幕级快捷键让位
+    const idle = () => !layout.isServicePanelOpen();
+    layout.screen.key(["q", "Q"], () => { if (idle())
+        void stop(); });
+    layout.screen.key(["C-c"], () => { void stop(); });
+    layout.screen.key(["r"], () => {
+        if (!idle())
+            return;
+        void pollOnce();
+        layout.showToast("已请求刷新", "info", 1200);
+    });
+    layout.screen.key(["l", "L"], () => { if (idle())
+        layout.clearLogs(); });
+    layout.screen.key(["?", "h", "H"], () => { if (idle())
+        layout.toggleHelp(); });
+    // 运维快捷键 — 与本地模式行为一致，但 R 走"重启系统服务"路径
+    layout.screen.key(["g", "G"], () => { if (idle())
+        openServicePanel({ layout, configPath: deps.configPath }); });
+    layout.screen.key(["S-r"], () => { if (idle())
+        void handleRestart(); });
+    layout.screen.key(["u", "U"], () => { if (idle())
+        void handleUpdate(); });
+    layout.screen.key(["o", "O"], () => {
+        if (!idle())
+            return;
+        const r = openInBrowser(deps.pidInfo.url);
+        layout.showToast(r.message, r.ok ? "success" : "error", 2500);
+    });
+    layout.screen.key(["c", "C"], () => {
+        if (!idle())
+            return;
+        const r = copyToClipboard(deps.pidInfo.url);
+        layout.showToast(r.message, r.ok ? "success" : "error", 2500);
+    });
+    layout.screen.key(["s"], () => { if (idle())
+        void handleInstallService(); });
+    layout.screen.key(["S-s"], () => { if (idle())
+        void handleUninstallService(); });
+    async function handleRestart() {
+        const installed = safeServiceInstalled();
+        if (installed && process.platform === "linux") {
+            const ok = await layout.confirm({
+                title: "重启 wand 服务",
+                body: "将执行 systemctl --user restart wand.service。当前 attach 会话会随主进程重启被踢掉。",
+            });
+            if (!ok)
+                return;
+            layout.showToast("systemctl --user restart wand.service …", "info", 3000);
+            const r = spawnSync("systemctl", ["--user", "restart", "wand.service"], { encoding: "utf8" });
+            if (r.status === 0) {
+                layout.showToast("已请求重启，IPC 会自动重连", "success", 3000);
+            }
+            else {
+                layout.showToast(`systemctl 失败 (exit ${r.status})`, "error", 4000);
+                layout.showDetail("systemctl 输出", (r.stdout || "") + "\n" + (r.stderr || ""));
+            }
+            return;
+        }
+        if (installed && process.platform === "darwin") {
+            const ok = await layout.confirm({
+                title: "重启 wand 服务",
+                body: "将依次 launchctl unload / load com.wand.web。",
+            });
+            if (!ok)
+                return;
+            const plist = `${process.env.HOME}/Library/LaunchAgents/com.wand.web.plist`;
+            const u = spawnSync("launchctl", ["unload", plist], { encoding: "utf8" });
+            const l = spawnSync("launchctl", ["load", plist], { encoding: "utf8" });
+            const ok2 = u.status === 0 && l.status === 0;
+            layout.showToast(ok2 ? "已请求 launchd 重启" : "launchctl 调用失败", ok2 ? "success" : "error", 3500);
+            return;
+        }
+        // 没注册成服务：尝试通过 IPC 让主进程自我退出，再由用户手动重启
+        const ok = await layout.confirm({
+            title: "主进程未注册为系统服务",
+            body: "无法自动重启。要请求主进程关闭吗？关闭后请手动 `wand web` 重启。",
+        });
+        if (!ok)
+            return;
+        const accepted = await client.shutdownDaemon();
+        layout.showToast(accepted ? "已请求主进程退出" : "请求未被接受", accepted ? "success" : "warn", 3500);
+    }
+    async function handleUpdate() {
+        layout.showToast("正在检查更新…", "info", 2000);
+        const info = await runOffMicrotask(() => checkUpdate(deps.pidInfo.version));
+        if (!info.latest) {
+            layout.showToast("无法连接到 npm registry", "error", 3500);
+            return;
+        }
+        if (!info.hasUpdate) {
+            layout.showToast(`已是最新版本 (v${info.current})`, "success", 3000);
+            return;
+        }
+        const go = await layout.confirm({
+            title: "发现新版本",
+            body: `当前 v${info.current} → 最新 v${info.latest}，立即升级？升级后请按 R 重启服务。`,
+            yes: "回车 / y 安装",
+            no: "Esc / n 取消",
+        });
+        if (!go)
+            return;
+        layout.showToast("正在执行 npm install -g …", "info", 5000);
+        const r = await runOffMicrotask(() => installUpdate());
+        layout.showToast(r.message, r.ok ? "success" : "error", 5000);
+        if (r.detail)
+            layout.showDetail(r.ok ? "更新输出" : "更新失败", r.detail);
+    }
+    async function handleInstallService() {
+        if (isServiceInstalled()) {
+            layout.showToast("服务已安装，按 Shift+S 卸载", "warn", 2500);
+            return;
+        }
+        const ok = await layout.confirm({
+            title: "注册为系统服务",
+            body: process.platform === "linux"
+                ? "将写入 ~/.config/systemd/user/wand.service。"
+                : process.platform === "darwin"
+                    ? "将写入 ~/Library/LaunchAgents/com.wand.web.plist。"
+                    : "当前平台暂不支持。",
+        });
+        if (!ok)
+            return;
+        const r = await runOffMicrotask(() => installService({ configPath: deps.configPath }));
+        layout.showToast(r.message, r.ok ? "success" : "error", 5000);
+        if (r.detail)
+            layout.showDetail(r.ok ? "服务安装详情" : "服务安装失败", r.detail);
+    }
+    async function handleUninstallService() {
+        if (!isServiceInstalled()) {
+            layout.showToast("当前未安装系统服务", "warn", 2500);
+            return;
+        }
+        const ok = await layout.confirm({
+            title: "卸载系统服务",
+            body: "将禁用并删除 wand 的 systemd / launchd 配置，确认继续？",
+        });
+        if (!ok)
+            return;
+        const r = await runOffMicrotask(() => uninstallService());
+        layout.showToast(r.message, r.ok ? "success" : "error", 4000);
+        if (r.detail)
+            layout.showDetail(r.ok ? "服务卸载详情" : "服务卸载失败", r.detail);
+    }
+    async function stop() {
+        if (stopping || !active)
+            return;
+        stopping = true;
+        active = false;
+        clearInterval(pollTimer);
+        try {
+            client.close();
+        }
+        catch { /* noop */ }
+        try {
+            layout.destroy();
+        }
+        catch { /* destroyed */ }
+        try {
+            await deps.onExit();
+        }
+        catch (err) {
+            process.stderr.write(`[wand] attach TUI 退出回调失败: ${String(err)}\n`);
+        }
+    }
+    return { stop };
+}
+function safeServiceInstalled() {
+    try {
+        return isServiceInstalled();
+    }
+    catch {
+        return false;
+    }
+}
+function runOffMicrotask(fn) {
+    return new Promise((resolve, reject) => {
+        setImmediate(() => {
+            try {
+                resolve(fn());
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    });
+}