cotutor 0.4.0 → 0.4.2

package/dist/app/cli/serve.js

@@ -22,6 +22,7 @@ import { AUTO_BOOKKEEP_EVERY_MS, autoBookkeep } from "../../runtime/auto-bookkee
 import { USER_CERT_DIR, expandPath, loadWorkspace } from "../workspace.js";
 export { siteUrl };
 /** 证书路径:cotutor.json 的 server.https 优先(相对 workspace 根),否则机器级 ~/.config/cotutor/certs/;都没有 → null */
+const BAILIAN_RECHECK_MS = 120_000;
 export function httpsFiles(ws) {
     const h = ws.config.server.https;
     if (h)
@@ -126,6 +127,10 @@ export async function serveWorkspace(opts = {}) {
     }, AUTO_BOOKKEEP_EVERY_MS);
     timer.unref();
     server.once('close', () => clearInterval(timer));
+    // 嘴连不上时隔一阵再试:充上钱、网回来了,没人点也会恢复,孩子端和图标跟着好
+    const recheck = setInterval(() => { void ctx.bailian.recheck().catch(() => undefined); }, BAILIAN_RECHECK_MS);
+    recheck.unref();
+    server.once('close', () => clearInterval(recheck));
     if (opts.awake !== false) {
         const stop = holdAwake(() => liveUpgrade.openCalls() > 0 || Object.keys(ctx.ws.config.tutors).some((t) => ctx.runner.running(t) !== null));
         server.once('close', stop);

package/dist/app/cli/service.d.ts

@@ -28,6 +28,34 @@ export declare function earlyLogHint(platform: ServicePlatform, s: {
 }): string;
 /** 看护进程的日志(Windows):serve 退了几次、起来之前的输出 */
 export declare const KEEPER_LOG = "keeper.log";
+/**
+ * launchctl bootout 发完信号就回,进程还没退;这时 bootstrap 报 5: Input/output error,服务就停在那儿了(2026-11-07 实测重装 12 次失败 10 次)。
+ * 等它真的卸下来再往下走。launchd 最多等进程 20 秒(ExitTimeOut 缺省),再不走它自己会杀。
+ */
+export declare function launchdUnload(host: Pick<ServiceHost, 'run'>, target: string, waitMs?: number): Promise<void>;
+/** 装上;刚卸下的那一下还可能报错,隔一秒再试几次,真的不行才算不行 */
+export declare function launchdLoad(host: Pick<ServiceHost, 'run' | 'uid'>, file: string, tries?: number): Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * 写进服务文件、登录项的 node。Homebrew 的 process.execPath 是带版本号的路径(实测 /opt/homebrew/Cellar/node/26.12.1_1/bin/node),
+ * brew upgrade 清掉旧版后,服务和图标下次登录都起不来,连报警的都没了;opt/<formula> 这个链接 brew 一直维护。别的管理器(nvm、asdf)不会自己删旧版,不动。
+ */
+export declare function stableNode(execPath: string, exists?: (p: string) => boolean): string;
+/**
+ * service install 之后开不开家长端:只有这个孩子第一次装时开,下一步就是填百炼、扫码。
+ * 别的启动都不开:登录、崩溃重起、升级、重启都不是人要看页面;放进 serve 的话,一直崩就隔 10 秒开一个标签页。
+ * ssh 进来的不开:没人看,macOS 的 open 还会开到那台电脑的屏幕上。Linux 要有图形会话。--open 是人明说的,重装也开;--no-open 最大
+ */
+export declare function opensAfterInstall(o: {
+    firstTime: boolean;
+    open: boolean;
+    noOpen: boolean;
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+}): boolean;
 /**
  * 看护进程(Windows;cotutor service run):起 serve,非 0 隔 10 秒再起,0 不起(端口被占着);同 launchd 的 KeepAlive、systemd 的 Restart=on-failure。
  * 给 serve 带上 COTUTOR_SERVICE(mode 算后台服务、端口被占以 0 退);返回退出码
@@ -108,6 +136,18 @@ export interface Health {
     calls?: number;
     /** 百炼配了没有(托盘:没配算有事要处理) */
     bailian?: boolean;
+    /** 跑起来以后百炼出的问题(欠费、key 失效、连不上);没有 → null(machine/bailian.ts) */
+    bailianTrouble?: {
+        kind: string;
+        message: string;
+        fix: string;
+        why?: string;
+        blocked?: boolean;
+    } | null;
+    /** npm 上比在跑的这份新的版本;没有 → null(machine/update.ts) */
+    latest?: string | null;
+    /** 那个版本写的更新说明 */
+    latestNotes?: string[];
     configError?: string | null;
     /** 问到的是 https 还是 http(这边加的,不是服务回的) */
     scheme?: 'https' | 'http';

package/dist/app/cli/service.js

@@ -88,6 +88,51 @@ export function earlyLogHint(platform, s) {
 export const KEEPER_LOG = 'keeper.log';
 const KEEPER_LOG_MAX = 5 * 1024 * 1024;
 const KEEPER_RESTART_MS = 10_000;
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
+/**
+ * launchctl bootout 发完信号就回,进程还没退;这时 bootstrap 报 5: Input/output error,服务就停在那儿了(2026-11-07 实测重装 12 次失败 10 次)。
+ * 等它真的卸下来再往下走。launchd 最多等进程 20 秒(ExitTimeOut 缺省),再不走它自己会杀。
+ */
+export async function launchdUnload(host, target, waitMs = 25_000) {
+    await host.run('launchctl', ['bootout', target]);
+    const until = Date.now() + waitMs;
+    while ((await host.run('launchctl', ['print', target])).code === 0 && Date.now() < until)
+        await sleep(200);
+}
+/** 装上;刚卸下的那一下还可能报错,隔一秒再试几次,真的不行才算不行 */
+export async function launchdLoad(host, file, tries = 5) {
+    let r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+    for (let i = 1; i < tries && r.code !== 0; i++) {
+        await sleep(1000);
+        r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+    }
+    return r;
+}
+/**
+ * 写进服务文件、登录项的 node。Homebrew 的 process.execPath 是带版本号的路径(实测 /opt/homebrew/Cellar/node/26.12.1_1/bin/node),
+ * brew upgrade 清掉旧版后,服务和图标下次登录都起不来,连报警的都没了;opt/<formula> 这个链接 brew 一直维护。别的管理器(nvm、asdf)不会自己删旧版,不动。
+ */
+export function stableNode(execPath, exists = existsSync) {
+    const m = /^(.*)\/Cellar\/(node(?:@\d+)?)\/[^/]+\/bin\/node$/.exec(execPath);
+    if (!m)
+        return execPath;
+    const opt = `${m[1]}/opt/${m[2]}/bin/node`;
+    return exists(opt) ? opt : execPath;
+}
+/**
+ * service install 之后开不开家长端:只有这个孩子第一次装时开,下一步就是填百炼、扫码。
+ * 别的启动都不开:登录、崩溃重起、升级、重启都不是人要看页面;放进 serve 的话,一直崩就隔 10 秒开一个标签页。
+ * ssh 进来的不开:没人看,macOS 的 open 还会开到那台电脑的屏幕上。Linux 要有图形会话。--open 是人明说的,重装也开;--no-open 最大
+ */
+export function opensAfterInstall(o) {
+    if (o.noOpen)
+        return false;
+    if (o.open)
+        return true;
+    if (!o.firstTime || o.env.SSH_CONNECTION || o.env.SSH_TTY)
+        return false;
+    return o.platform !== 'linux' || Boolean(o.env.DISPLAY || o.env.WAYLAND_DISPLAY);
+}
 /**
  * 看护进程(Windows;cotutor service run):起 serve,非 0 隔 10 秒再起,0 不起(端口被占着);同 launchd 的 KeepAlive、systemd 的 Restart=on-failure。
  * 给 serve 带上 COTUTOR_SERVICE(mode 算后台服务、端口被占以 0 退);返回退出码
@@ -253,7 +298,7 @@ export async function installService(host, root, opts = {}) {
     const logDir = serviceLogDir(host, name);
     // Windows 上跑的是看护进程,它再起 serve(那边没有 launchd / systemd 替你拉起)
     const run = platform === 'win32' ? ['service', 'run'] : ['serve'];
-    const spec = { name, label, root, logDir, path: host.env.PATH ?? '/usr/bin:/bin', args: [opts.node ?? process.execPath, opts.bin ?? binPath(), ...run, '--workspace', root, '--log-dir', logDir] };
+    const spec = { name, label, root, logDir, path: host.env.PATH ?? '/usr/bin:/bin', args: [opts.node ?? stableNode(process.execPath), opts.bin ?? binPath(), ...run, '--workspace', root, '--log-dir', logDir] };
     const file = fileOf(host, name);
     await mkdir(serviceDir(host), { recursive: true });
     await mkdir(logDir, { recursive: true });
@@ -270,9 +315,9 @@ export async function installService(host, root, opts = {}) {
     }
     else if (platform === 'darwin') {
         // 先卸下旧的(没装过会报错,不管),再装上;bootstrap 会按 RunAtLoad 马上起
-        await host.run('launchctl', ['bootout', `gui/${host.uid}/${label}`]);
+        await launchdUnload(host, `gui/${host.uid}/${label}`);
         await writeFile(file, launchdPlist(spec));
-        const r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+        const r = await launchdLoad(host, file);
         if (r.code !== 0)
             throw new UsageError(`launchctl bootstrap 没成:${(r.stderr || r.stdout).trim()}`);
     }
@@ -332,10 +377,10 @@ export async function controlService(host, root, what) {
         const loaded = (await host.run('launchctl', ['print', target])).code === 0;
         if (what === 'stop') {
             if (loaded)
-                await host.run('launchctl', ['bootout', target]);
+                await launchdUnload(host, target);
             return s;
         }
-        const r = loaded ? await host.run('launchctl', what === 'restart' ? ['kickstart', '-k', target] : ['kickstart', target]) : await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, s.file]);
+        const r = loaded ? await host.run('launchctl', what === 'restart' ? ['kickstart', '-k', target] : ['kickstart', target]) : await launchdLoad(host, s.file);
         if (r.code !== 0)
             throw new UsageError(`launchctl 没成:${(r.stderr || r.stdout).trim()}`);
         return s;

package/dist/app/cli/tray-run.js

@@ -6,7 +6,16 @@ import { mkdirSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { realHost } from "./service.js";
 import { realTrayDeps, runTray, trayDir, trayNote, traySupported, writeTrayFiles } from "./tray.js";
-const version = () => JSON.parse(readFileSync(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8')).version;
+const readVersion = () => JSON.parse(readFileSync(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8')).version;
+let installed = readVersion();
+/** 每轮重读:npm 升级时这个进程一直开着,只记起来那一刻的就会误报。装到一半读不到就用上次的 */
+const version = () => {
+    try {
+        installed = readVersion();
+    }
+    catch { /* 下一轮再读 */ }
+    return installed;
+};
 export async function main(argv) {
     const host = realHost();
     if (!traySupported(host.platform)) {
@@ -27,7 +36,7 @@ export async function main(argv) {
     process.on('unhandledRejection', fatal('没接住的 Promise 错误'));
     const file = await writeTrayFiles(host.platform, dir);
     note(`起来了,node ${process.versions.node},pid ${process.pid}`);
-    const code = await runTray(realTrayDeps(host, dir, file, version()));
+    const code = await runTray(realTrayDeps(host, dir, file, version));
     note(`退出 ${code}`);
     process.exit(code);
 }

package/dist/app/cli/tray.d.ts

@@ -1,3 +1,15 @@
+/**
+ * 托盘图标(macOS 菜单栏、Windows 任务栏;Linux 没做,GNOME 缺省不显示托盘):家长不开终端也看得到服务好不好、点得开家长端。
+ * 三层:
+ *   node 进程(cotutor tray run,tray-run.ts 是它的轻入口):隔几秒问每个后台服务的 /api/health,判断状态,决定显示什么、要不要通知;这里全是能测的 TS。
+ *   显示脚本(tray-mac.ts 的 JXA、tray-windows.ts 的 PowerShell,都是系统自带、不用签名):只管画和回报点击,不判断。
+ *   登录项:macOS 一个 LaunchAgent,Windows 一条 Run 项 + wscript 隐藏启动器;service install 时一起装(--no-tray 不装,cotutor tray off 关掉并记住)。
+ * 为什么不放在 serve 里:服务挂了图标也没了,就说不出「没在跑」;多个孩子时一台电脑也只该有一个图标。
+ * 为什么不用 npm 的托盘库、Electron:见 docs/wip;systray2 只有 x86 的 Mac 二进制且没签名,Electron 要多下一百多 MB。
+ * 状态:正常只有 logo(和菜单栏别的图标一样单色);有事才出状态点,橙 = 要处理,红 = 没在跑(logo 同时变淡)。正常 → 有事、→ 没在跑时通知一次,恢复不通知。
+ * 「退出 cotutor」= 停掉所有后台服务并退出图标,下次登录自己回来;正开着电话时先问一声。
+ */
+import { type SpawnOptions } from 'node:child_process';
 import { type Health, type InstalledService, type ServiceHost } from './service.ts';
 import { HELPER_NO_SESSION, TRAY_AUMID, TRAY_LABEL, TRAY_RUN_VALUE } from './tray-ids.ts';
 export { HELPER_NO_SESSION, TRAY_AUMID, TRAY_LABEL, TRAY_RUN_VALUE };
@@ -45,6 +57,8 @@ export interface TrayRow {
     issues: number;
     fix: TrayFix | null;
     calls: number;
+    /** npm 上有比装的新的版本 → 版本号;不算有事,不出状态点 */
+    update: string | null;
 }
 export type TrayEntry = {
     kind: 'info';
@@ -89,7 +103,7 @@ export declare class TrayModel {
     private readonly o;
     constructor(o: {
         platform: NodeJS.Platform;
-        version: string;
+        version: () => string;
     });
     /** 刚点了启动、重启:这一阵问不到是正常的 */
     expect(name: string, now: number): void;
@@ -100,6 +114,8 @@ export declare class TrayModel {
     private healthy;
     private placeholder;
 }
+/** 有新版本的通知:每个版本最多一次,记在托盘目录,重起、重新登录不再弹 */
+export declare function updateNote(version: string, platform: NodeJS.Platform): TrayNote;
 /** 这一轮显示什么 */
 export declare function trayShow(rows: TrayRow[]): TrayShow;
 export interface HelperMessage {
@@ -115,7 +131,11 @@ export interface TrayHelper {
 }
 export interface TrayDeps {
     platform: NodeJS.Platform;
-    version: string;
+    /** 现在装的是哪个版本:每轮问,程序可能刚被 npm 换了 */
+    version(): string;
+    /** 已经通知过的新版本 */
+    updateSeen(): string | null;
+    setUpdateSeen(version: string): void;
     now(): number;
     list(): Promise<InstalledService[]>;
     /** 读 cotutor.json:孩子叫什么、哪个端口 */
@@ -155,7 +175,16 @@ export declare function spawnTrayHelper(platform: NodeJS.Platform, file: string,
     message(m: HelperMessage): void;
     exit(code: number | null): void;
 }): TrayHelper;
-/** 打开地址或目录(Windows 不弹黑窗口) */
+/**
+ * 打开地址或目录用什么命令。windowsHide 不弹黑窗口。
+ * detached 不能省:Windows 上非 detached 的子进程在「父进程退出就杀」的 job 里(libuv),cotutor open、service install 起完马上退,cmd 还没把地址交给浏览器就被一起杀了。
+ * 退出码是 0、地址也打印了,就是没打开,也不报错(2026-11-07 真机);托盘进程一直开着,所以光点图标看不出来。
+ */
+export declare function openCommand(platform: NodeJS.Platform, target: string): {
+    cmd: string;
+    args: string[];
+    options: SpawnOptions;
+};
 export declare function openTarget(platform: NodeJS.Platform, target: string): void;
 /** 日志:一个文件,过 1 MB 换一次,只留上一份 */
 export declare function trayNote(dir: string): (text: string) => void;
@@ -165,7 +194,7 @@ export declare function inspectService(s: InstalledService): Promise<{
     port: number;
 }>;
 /** 真的依赖,给 runTray */
-export declare function realTrayDeps(host: ServiceHost, dir: string, file: string, version: string): TrayDeps;
+export declare function realTrayDeps(host: ServiceHost, dir: string, file: string, version: () => string): TrayDeps;
 /** 登录项跑的命令 */
 export declare const trayArgs: (host: HostPaths, o?: {
     node?: string;
@@ -201,5 +230,7 @@ export declare function ensureTray(host: ServiceHost, o?: {
     node?: string;
     bin?: string;
 }): Promise<'unsupported' | 'off' | 'started' | 'later'>;
+/** service restart 时:图标进程也换上新代码(升级后跑的就是这条)。没开图标的不动,不能把 --no-tray 的装回来 */
+export declare function refreshTray(host: ServiceHost): Promise<boolean>;
 /** 服务卸完了:图标也撤(不算家长说不要,以后再装服务还会带上) */
 export declare function dropTrayIfNoServices(host: ServiceHost): Promise<boolean>;

package/dist/app/cli/tray.js

@@ -10,16 +10,17 @@
  * 「退出 cotutor」= 停掉所有后台服务并退出图标,下次登录自己回来;正开着电话时先问一声。
  */
 import { spawn } from 'node:child_process';
-import { appendFileSync, existsSync, renameSync, statSync } from 'node:fs';
+import { appendFileSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { DEFAULT_PORT } from "../../shared/default-port.js";
 import { UsageError } from "../../shared/errors.js";
 import { siteUrl } from "../../shared/site-url.js";
+import { isNewer } from "../../shared/upgrade.js";
 import { portHolder } from "./port-holder.js";
 import { RUN_KEY, STARTUP_APPROVED_KEY, encodeLauncher, parseProcs, psArgs, runValue, startupDisabled, winCommandLine } from "./service-windows.js";
-import { binPath, controlService, listServices, parseLaunchctlPrint, probeHealth, wscriptPath, xml } from "./service.js";
+import { binPath, controlService, listServices, parseLaunchctlPrint, probeHealth, wscriptPath, xml, launchdLoad, launchdUnload, stableNode } from "./service.js";
 import { macTrayIcons, windowsTrayIcons } from "./tray-icons.js";
 import { HELPER_NO_SESSION, TRAY_AUMID, TRAY_LABEL, TRAY_RUN_VALUE } from "./tray-ids.js";
 import { MAC_TRAY_SCRIPT } from "./tray-mac.js";
@@ -64,6 +65,8 @@ export function issuesOf(p, o) {
         out.push({ text: 'vault 不在了:看看 cotutor.json 的 paths.vault', fix: { kind: 'open', target: p.root } });
     if (h.bailian === false)
         out.push({ text: '还没填百炼:老师们到不了', fix: { kind: 'open', target: url } });
+    else if (h.bailianTrouble)
+        out.push({ text: h.bailianTrouble.message, fix: { kind: 'open', target: url } });
     if (h.version && h.version !== o.version)
         out.push({ text: `在跑的是 ${h.version},装的是 ${o.version}:重启一下`, fix: { kind: 'restart' } });
     return out;
@@ -73,6 +76,7 @@ const rank = (l) => (l === 'bad' ? 2 : l === 'warn' ? 1 : 0);
 export class TrayModel {
     mem = new Map();
     last = 0;
+    // 版本每轮问:npm 升级时这个进程一直开着,记死了就把「都对了」报成「要重启」,把真要重启的放过去
     o;
     constructor(o) { this.o = o; }
     /** 刚点了启动、重启:这一阵问不到是正常的 */
@@ -128,7 +132,8 @@ export class TrayModel {
     }
     healthy(p, now) {
         const h = p.health;
-        const issues = issuesOf(p, this.o);
+        const installed = this.o.version();
+        const issues = issuesOf(p, { platform: this.o.platform, version: installed });
         const started = Date.parse(h.started);
         const running = h.mode === 'foreground' ? '在终端里跑,关了终端就停' : `已运行 ${uptimeText(Number.isNaN(started) ? now : started, now)}`;
         return {
@@ -141,10 +146,12 @@ export class TrayModel {
             issues: issues.length,
             fix: issues[0]?.fix ?? null,
             calls: h.calls ?? 0,
+            // 和装的比,不只和在跑的比:程序已经换上新版、只差重启时,再说「有新版本」就错了
+            update: isNewer(h.latest, installed) ? h.latest : null,
         };
     }
     placeholder(p, level, detail) {
-        return { name: p.name, kid: p.kid, logDir: p.logDir, level, url: null, detail, issues: 0, fix: null, calls: 0 };
+        return { name: p.name, kid: p.kid, logDir: p.logDir, level, url: null, detail, issues: 0, fix: null, calls: 0, update: null };
     }
 }
 const titleOf = (r, multi) => {
@@ -152,9 +159,14 @@ const titleOf = (r, multi) => {
         return r.level === 'ok' ? 'cotutor 正常' : r.level === 'warn' ? `有 ${r.issues} 件事要处理` : r.level === 'bad' ? '后台服务没在跑' : 'cotutor 正在启动';
     return `${r.kid} · ${r.level === 'ok' ? '正常' : r.level === 'warn' ? `有 ${r.issues} 件事要处理` : r.level === 'bad' ? '没在跑' : '正在启动'}`;
 };
+// 点通知回不到这里(Mac 的来源是系统的脚本程序;Windows 的 PowerShell 5.1 接不了 WinRT 的事件),只能请家长去点图标
+const iconHint = (platform) => (platform === 'darwin' ? '点菜单栏的 cotutor 图标看看' : '点任务栏的 cotutor 图标看看');
+/** 有新版本的通知:每个版本最多一次,记在托盘目录,重起、重新登录不再弹 */
+export function updateNote(version, platform) {
+    return { type: 'notify', title: `cotutor 有新版本 ${version}`, body: iconHint(platform) };
+}
 function noteFor(r, multi, platform) {
-    // 点通知回不到这里(Mac 的来源是系统的脚本程序;Windows 的 PowerShell 5.1 接不了 WinRT 的事件),只能请家长去点图标
-    const hint = platform === 'darwin' ? '点菜单栏的 cotutor 图标看看' : '点任务栏的 cotutor 图标看看';
+    const hint = iconHint(platform);
     const who = multi ? r.kid : 'cotutor ';
     if (r.level === 'bad')
         return { type: 'notify', title: `${who}${multi ? '的' : ''}后台服务没在跑`, body: `孩子的平板现在打不开,${hint}` };
@@ -190,6 +202,12 @@ export function trayShow(rows) {
             act('logs', '看日志');
         menu.push({ kind: 'sep' });
     }
+    // 版本是这台电脑的事,几个孩子也只说一行;点了去家长端,升级的命令写在那里
+    const newer = rows.find((r) => r.update);
+    if (newer) {
+        menu.push({ kind: 'action', id: `update:${newer.name}`, title: `有新版本 ${newer.update},看怎么升级` });
+        menu.push({ kind: 'sep' });
+    }
     menu.push({ kind: 'action', id: 'quit', title: '退出 cotutor' });
     return { type: 'show', icon: level === 'starting' ? 'ok' : level, tip: worst ? titleOf(worst, multi) : 'cotutor', menu };
 }
@@ -269,7 +287,7 @@ export function runTray(d) {
             const r = rows.find((x) => x.name === id.slice(at + 1));
             if (!r)
                 return;
-            if (what === 'open' && r.url)
+            if ((what === 'open' || what === 'update') && r.url)
                 d.open(r.url);
             else if (what === 'logs' && r.logDir)
                 d.open(r.logDir);
@@ -368,6 +386,13 @@ export function runTray(d) {
                     helper?.send(n);
                     d.note(`通知:${n.title}`);
                 }
+                const newer = rows.find((x) => x.update)?.update;
+                if (newer && helper && newer !== d.updateSeen()) {
+                    const n = updateNote(newer, d.platform);
+                    helper.send(n);
+                    d.setUpdateSeen(newer);
+                    d.note(`通知:${n.title}`);
+                }
             }
             catch (err) {
                 d.note(`这一轮出错:${String(err)}`);
@@ -446,10 +471,18 @@ export function spawnTrayHelper(platform, file, dir, note, on) {
         close() { child.stdin?.end(); },
     };
 }
-/** 打开地址或目录(Windows 不弹黑窗口) */
-export function openTarget(platform, target) {
+/**
+ * 打开地址或目录用什么命令。windowsHide 不弹黑窗口。
+ * detached 不能省:Windows 上非 detached 的子进程在「父进程退出就杀」的 job 里(libuv),cotutor open、service install 起完马上退,cmd 还没把地址交给浏览器就被一起杀了。
+ * 退出码是 0、地址也打印了,就是没打开,也不报错(2026-11-07 真机);托盘进程一直开着,所以光点图标看不出来。
+ */
+export function openCommand(platform, target) {
     const [cmd, args] = platform === 'darwin' ? ['/usr/bin/open', [target]] : platform === 'win32' ? ['cmd', ['/c', 'start', '', target]] : ['xdg-open', [target]];
-    const child = spawn(cmd, args, { stdio: 'ignore', windowsHide: true });
+    return { cmd: cmd, args: args, options: { stdio: 'ignore', windowsHide: true, detached: true } };
+}
+export function openTarget(platform, target) {
+    const { cmd, args, options } = openCommand(platform, target);
+    const child = spawn(cmd, args, options);
     child.on('error', () => undefined);
     child.unref();
 }
@@ -482,9 +515,21 @@ export async function inspectService(s) {
 /** 真的依赖,给 runTray */
 export function realTrayDeps(host, dir, file, version) {
     const note = trayNote(dir);
+    const seenFile = join(dir, 'update-seen');
     return {
         platform: host.platform,
         version,
+        updateSeen: () => { try {
+            return readFileSync(seenFile, 'utf8').trim() || null;
+        }
+        catch {
+            return null;
+        } },
+        // 写不了就当没记住:最坏多弹一次
+        setUpdateSeen: (v) => { try {
+            writeFileSync(seenFile, `${v}\n`);
+        }
+        catch { /* 见上 */ } },
         note,
         now: () => Date.now(),
         list: () => listServices(host),
@@ -497,7 +542,7 @@ export function realTrayDeps(host, dir, file, version) {
     };
 }
 /** 登录项跑的命令 */
-export const trayArgs = (host, o = {}) => [o.node ?? process.execPath, o.bin ?? binPath(), 'tray', 'run', '--dir', trayDir(host)];
+export const trayArgs = (host, o = {}) => [o.node ?? stableNode(process.execPath), o.bin ?? binPath(), 'tray', 'run', '--dir', trayDir(host)];
 /** macOS 的 LaunchAgent:登录就起,崩了拉起,以 0 退(点了退出)不拉 */
 export function trayPlist(args, dir, path) {
     const str = (v) => `<string>${xml(v)}</string>`;
@@ -555,9 +600,9 @@ export async function installTray(host, o = {}) {
     }
     const file = plistFile(host);
     await mkdir(join(host.home, 'Library', 'LaunchAgents'), { recursive: true });
-    await host.run('launchctl', ['bootout', `gui/${host.uid}/${TRAY_LABEL}`]);
+    await launchdUnload(host, `gui/${host.uid}/${TRAY_LABEL}`);
     await writeFile(file, trayPlist(args, dir, host.env.PATH ?? '/usr/bin:/bin'));
-    const r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+    const r = await launchdLoad(host, file);
     return { file, started: r.code === 0 };
 }
 /** 卸掉:停下、删登录项。remember = 家长说不要(以后 service install 也不再装) */
@@ -608,6 +653,15 @@ export async function ensureTray(host, o = {}) {
         return 'off';
     return (await installTray(host, o)).started ? 'started' : 'later';
 }
+/** service restart 时:图标进程也换上新代码(升级后跑的就是这条)。没开图标的不动,不能把 --no-tray 的装回来 */
+export async function refreshTray(host) {
+    if (!traySupported(host.platform))
+        return false;
+    if (!(await trayStatus(host)).installed)
+        return false;
+    await installTray(host);
+    return true;
+}
 /** 服务卸完了:图标也撤(不算家长说不要,以后再装服务还会带上) */
 export async function dropTrayIfNoServices(host) {
     if (!traySupported(host.platform))

package/dist/app/cli/update-cmd.d.ts

@@ -0,0 +1,38 @@
+import { type Release } from '../machine/update.ts';
+import { type Health } from './service.ts';
+export interface UpdateService {
+    name: string;
+    kid: string;
+    root: string;
+    port: number;
+    node: string;
+    health: Health | null;
+}
+export interface UpdateDeps {
+    current: string;
+    /** 从仓库跑的:版本跟着 git 走,npm 不管 */
+    fromRepo: boolean;
+    nodeVersion: string;
+    release(): Promise<Release | null>;
+    services(): Promise<UpdateService[]>;
+    health(port: number): Promise<Health | null>;
+    npm(spec: string, registry: string | null): Promise<{
+        code: number;
+        out: string;
+    }>;
+    /** 现在装着的版本:读文件,npm 刚换过 */
+    installed(): string | null;
+    /** 跑新的 bin */
+    cli(args: string[]): Promise<{
+        code: number;
+        out: string;
+    }>;
+    /** 没有后台服务时,在终端里跑 serve 的那个孩子 */
+    workspace(): string | null;
+    stableNode(path: string): string;
+    print(line: string): void;
+}
+export declare function runUpdate(d: UpdateDeps, o?: {
+    anyway?: boolean;
+}): Promise<number>;
+export declare function realUpdateDeps(workspace: () => string | null): UpdateDeps;