termdock 1.4.261 → 1.4.263

package/dist/server/routes/terminal.js

@@ -24,7 +24,7 @@ import { getPtyHostManager } from '../ptyhost/manager.js';
 import { pathValidator } from '../utils/pathValidator.js';
 import { TERMINAL, TMUX } from '../config.js';
 import { localAccessManager } from '../utils/localAccess.js';
-import { normalizeLocalAccessName, getLocaleSetting, setLocaleSetting, getContextDraftHeightSetting, setContextDraftHeightSetting, getAutoRenameAgentsSetting, setAutoRenameAgentsSetting, getAutoRenameNamerSetting, setAutoRenameNamerSetting, getAutoRenameModelsSetting, setAutoRenameModelsSetting, getAutoRenameIntervalMinutesSetting, setAutoRenameIntervalMinutesSetting, getAutoRenamePromptPreferenceSetting, setAutoRenamePromptPreferenceSetting, getAutoRenamePromptPayloadCharsSetting, setAutoRenamePromptPayloadCharsSetting, getNewSessionAgentSlugSetting, setNewSessionAgentSlugSetting, getRunningSessionButtonEnabledSetting, getAttentionButtonEnabledSetting, getCollaborationPanelsSetting, setCollaborationPanelSetting, getAndroidPanelSetting, setAndroidPanelSetting, normalizeAndroidPanel, getCollaborationFloatingGroupIdSetting, setCollaborationFloatingGroupIdSetting, getServiceSwitcherExpandedSetting, setServiceSwitcherExpandedSetting, setRunningSessionButtonEnabledSetting, setAttentionButtonEnabledSetting, getFileSortModesSetting, setFileSortModesSetting, setFileSortModeSetting, getNestedGitScanRootsSetting, setNestedGitScanRootSetting, getPinnedExplorerRootsSetting, setPinnedExplorerRootsSetting, setPinnedExplorerRootSetting, watchPinnedExplorerRootsSetting, } from '../utils/settings.js';
+import { normalizeLocalAccessName, getLocaleSetting, setLocaleSetting, getContextDraftHeightSetting, setContextDraftHeightSetting, getAutoRenameAgentsSetting, setAutoRenameAgentsSetting, getAutoRenameNamerSetting, setAutoRenameNamerSetting, getAutoRenameModelsSetting, setAutoRenameModelsSetting, getAutoRenameIntervalMinutesSetting, setAutoRenameIntervalMinutesSetting, getAutoRenamePromptPreferenceSetting, setAutoRenamePromptPreferenceSetting, getAutoRenamePromptPayloadCharsSetting, setAutoRenamePromptPayloadCharsSetting, getNewSessionAgentSlugSetting, setNewSessionAgentSlugSetting, getRunningSessionButtonEnabledSetting, getAttentionButtonEnabledSetting, getCollaborationPanelsSetting, setCollaborationPanelSetting, getAndroidPanelSetting, setAndroidPanelSetting, normalizeAndroidPanel, getCollaborationFloatingGroupIdSetting, setCollaborationFloatingGroupIdSetting, getServiceSwitcherExpandedSetting, setServiceSwitcherExpandedSetting, setRunningSessionButtonEnabledSetting, setAttentionButtonEnabledSetting, getFileSortModesSetting, setFileSortModesSetting, setFileSortModeSetting, getNestedGitScanRootsSetting, setNestedGitScanRootSetting, getPinnedExplorerRootsSetting, setPinnedExplorerRootsSetting, setPinnedExplorerRootSetting, watchPinnedExplorerRootsSetting, getActiveGitReposSetting, setActiveGitRepoSetting, } from '../utils/settings.js';
 import { loadContextDraft, saveContextDraft } from '../utils/contextDraft.js';
 import { getOnboardingServerUrl } from '../onboardingServer.js';
 import { inspectLinuxInotifyUsage, isWatchResourceExhaustion } from '../utils/fileWatchPolicy.js';
@@ -38,6 +38,7 @@ import { AgentResumeHistoryStore } from '../agent/resumeHistory.js';
 import { isTmuxRecoveryCandidate } from '../utils/tmuxRecoveryCandidate.js';
 import { AutomationStore, normalizeAutomationSchedule } from '../agent/automationStore.js';
 import { buildBracketedSubmitBytes, canDeliverPromptToAgent } from '../agent/promptDelivery.js';
+import { buildServerHealthState, dismissServerHealth } from '../utils/serverHealth.js';
 import { collaborationRoutes } from '../agent/collaborationRoutes.js';
 import { extrasFromBody } from '../agent/collaborationProtocol.js';
 import { CollaborationStore } from '../agent/collaborationStore.js';
@@ -292,10 +293,43 @@ watchPinnedExplorerRootsSetting((pinnedExplorerRoots) => {
     });
 });
 let serverRestartScheduled = false;
+/**
+ * supervision 通道是否真的还在。
+ *
+ * `TERMDOCK_SUPERVISED` 只说明"出生时有人管"，`process.connected` 才是"此刻还管得着"——
+ * supervisor 自己崩掉之后子进程是被故意留下来继续服务的（丢监督好过丢服务），
+ * 那种情况下如果还按受管路径走，就会变成"报告完意图就自杀，而没人接盘"，
+ * 比旧 bridge 还糟。所以两个条件必须同时成立。
+ */
+function supervisionChannelOpen() {
+    return process.env.TERMDOCK_SUPERVISED === '1' && process.connected === true;
+}
 function requestServerRestartAfterUpdate() {
     if (serverRestartScheduled)
         return;
     serverRestartScheduled = true;
+    if (supervisionChannelOpen()) {
+        // 只说"我要重启"，不说"怎么重启"：重启用哪条命令、PATH 里是谁、要验证什么，
+        // 全是 supervisor 的事，而它每次都用 realpath 后的 entry 重新读盘。
+        // 用 IPC 而不是标记文件，是因为意图会随进程死亡一起消失，不可能过期后被误读。
+        try {
+            process.send?.({ type: 'termdock-intent', intent: 'restart-after-update' });
+        }
+        catch {
+            // 通道刚好断了：照样退，supervisor 会把这次退出当成崩溃重启，
+            // 结果同样是"服务带着新版本回来"，只是 crash.log 里的事件名不同。
+        }
+        const exitTimer = setTimeout(() => {
+            process.kill(process.pid, 'SIGTERM');
+        }, 750);
+        exitTimer.unref?.();
+        return;
+    }
+    // —— 以下为未受管路径（`--foreground` / Electron / 外部进程管理器）——
+    // 发射后不管：不验证新进程是否起来、不重试、失败也不回滚，
+    // 「更新后服务没起来」正是这个形状造成的。没有监督者时别无选择，
+    // 但它不再是默认路径——受管启动会走上面的分支。
+    //
     // The bridge is detached before this process exits. It waits for the old
     // PID to release the port, then resolves `termdock` from PATH again so an
     // npm-replaced global binary is used instead of the old loaded file.
@@ -6170,6 +6204,7 @@ async function getSettingsPayload() {
         serviceSwitcherExpanded: getServiceSwitcherExpandedSetting(),
         fileSortModes: getFileSortModesSetting(),
         nestedGitScanRoots: getNestedGitScanRootsSetting(),
+        activeGitRepos: getActiveGitReposSetting(),
         pinnedExplorerRoots: getPinnedExplorerRootsSetting(),
         localAccess: {
             ...localAccess,
@@ -6191,9 +6226,17 @@ router.get('/update', (_req, res) => {
 });
 router.post('/update/check', async (_req, res) => {
     try {
-        res.json(desktopRuntimeOwner
-            ? await desktopRuntimeOwner.checkForUpdates()
-            : await npmAutoUpdateManager.checkNow());
+        if (desktopRuntimeOwner) {
+            res.json(await desktopRuntimeOwner.checkForUpdates());
+            return;
+        }
+        // npm 查询加全局安装动辄二三十秒，而加密传输对 30s 内收不到任何回包就判超时，
+        // 客户端会弹「服务响应超时」——更新其实装完了。检查照常跑，进度与结果都由控制
+        // WS 的 update-state 广播推送，这里立刻回当前状态（通常是 checking）即可。
+        void npmAutoUpdateManager.checkNow().catch((error) => {
+            console.warn(`[auto-update] ${error instanceof Error ? error.message : String(error)}`);
+        });
+        res.status(202).json(npmAutoUpdateManager.getState());
     }
     catch (error) {
         res.status(503).json({ error: error instanceof Error ? error.message : String(error) });
@@ -6210,6 +6253,14 @@ router.post('/update/restart', async (_req, res) => {
         res.status(409).json({ error: error instanceof Error ? error.message : String(error) });
     }
 });
+// 「服务最近出过什么事」：红点与设置面板的唯一数据源。
+// 只读快照，不含任何可变更操作——所以不需要 CSRF，和 GET /update 同档。
+router.get('/server-health', (_req, res) => {
+    res.json(buildServerHealthState());
+});
+router.post('/server-health/dismiss', (_req, res) => {
+    res.status(202).json(dismissServerHealth());
+});
 router.put('/settings', async (req, res) => {
     const body = req.body ?? {};
     let pinnedExplorerRootsChanged = false;
@@ -6343,6 +6394,28 @@ router.put('/settings', async (req, res) => {
         }
         setNestedGitScanRootSetting(preference.rootPath, preference.enabled);
     }
+    if (body.activeGitRepo && typeof body.activeGitRepo === 'object') {
+        const preference = body.activeGitRepo;
+        const contextKey = preference.contextKey;
+        const repoRoot = preference.repoRoot;
+        // The context key is the client's layout — session id plus workspace root,
+        // or a split-workspace id — so it is validated by shape only. `null` is the
+        // explicit "every repository", which clears the entry.
+        const validContextKey = typeof contextKey === 'string'
+            && contextKey.length > 0
+            && contextKey.length <= 4300
+            && !/[\u0000-\u001f\u007f]/.test(contextKey.split('\u0000').join(''));
+        const validRepoRoot = repoRoot === null
+            || (typeof repoRoot === 'string'
+                && repoRoot.length > 0
+                && repoRoot.length <= 4096
+                && (repoRoot.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(repoRoot)));
+        if (!validContextKey || !validRepoRoot) {
+            res.status(400).json({ error: 'Invalid active git repository preference', code: 'ACTIVE_GIT_REPO_INVALID' });
+            return;
+        }
+        setActiveGitRepoSetting(contextKey, repoRoot ?? null);
+    }
     if (body.pinnedExplorerRoots && typeof body.pinnedExplorerRoots === 'object' && !Array.isArray(body.pinnedExplorerRoots)) {
         setPinnedExplorerRootsSetting(body.pinnedExplorerRoots);
         pinnedExplorerRootsChanged = true;
@@ -8180,6 +8253,9 @@ export function handleControlWebSocket(ws, clientId) {
                 type: 'update-state',
                 state: desktopRuntimeOwner?.getState() ?? npmAutoUpdateManager.getState(),
             }));
+            // 服务健康快照：崩溃时服务自己已经死了、推不出任何东西，所以"红点"这件事
+            // 只能靠客户端重连时的这一发。客户端断线重连的既有逻辑正好覆盖了那个时刻。
+            ws.send(JSON.stringify({ type: 'server-health', state: buildServerHealthState() }));
         }
         catch {
             controlClients.delete(clientId);

package/dist/server/supervisor.js

@@ -0,0 +1,525 @@
+#!/usr/bin/env node
+/**
+ * termdock supervisor — 盯住服务子进程，挂了就重启，并把原因记下来。
+ *
+ * 它解决的是两件今天无人负责的事：
+ *  1. 自动更新后新进程没起来（旧实现是发射后不管的 `node -e` bridge，不验证、不重试）；
+ *  2. 运行中崩溃（全仓没有 uncaughtException 处理，server.log 连时间戳都没有）。
+ *
+ * 形态：一个**独立进程**，不是服务内的自重启。自重启活不过 SIGKILL/OOM，
+ * 而那两种恰恰是最需要被兜住的。
+ *
+ * 架构：
+ * ```
+ * td / setsid          (launcher，短命)
+ *  └─ supervisor       (detached 或前台，stdio 指向 server.log + ipc)
+ *      └─ server       (同进程组，stdio 同样指向 server.log + ipc)
+ * ```
+ * 子进程刻意**不 detached**：同进程组便于整组 kill。但 supervisor 自己死掉时
+ * 不连坐杀服务——丢监督好过丢服务。
+ *
+ * Standalone entry: 只依赖 node stdlib + utils/ 下几个轻量模块，
+ * **绝不 import cli.ts / entry.ts**（那会拖进整个服务运行时）。
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { backoffDelayMs } from './utils/backoff.js';
+import { installCrashForensics, isOomSuspect, readRuntimeTail, readServerLogTail } from './utils/crashForensics.js';
+import { probeHealthOnce, HEALTH_PROBE_TIMEOUT_MS } from './utils/healthProbe.js';
+import { writeJsonLogSync } from './utils/serverLogger.js';
+import { SUPERVISOR_STATE_VERSION, classifyChildExit, isReadyMessage, isServerIntentMessage, shouldGiveUp, } from './utils/supervisorProtocol.js';
+import { SUPERVISOR_STATE_PATH, STOP_GRACE_MS, isProcessRunning, removeJsonState, writeJsonStateAtomic, } from './utils/termdockState.js';
+export const DEFAULT_SUPERVISOR_TIMING = {
+    readyTimeoutMs: 30_000,
+    healthIntervalMs: 30_000,
+    healthProbeTimeoutMs: HEALTH_PROBE_TIMEOUT_MS,
+    wedgeFailures: 3,
+    killGraceMs: STOP_GRACE_MS,
+    restartDelayMs: 250,
+    crashResetMs: 60_000,
+    maxConsecutiveCrashes: 5,
+    backoffBaseMs: 1_000,
+    backoffMaxMs: 30_000,
+};
+/**
+ * 节奏可以由 `TERMDOCK_SUPERVISOR_TIMING`（JSON）覆盖。
+ *
+ * 存在的理由之一是测试：崩溃循环用例要么等 5 次真实退避（1+2+4+8+16 = 31s），
+ * 要么把节奏变成可注入的。顺带它也是生产上的调参口子（探测密度、退避上限）。
+ * 只接受**正数**：0 会让 setInterval 空转。
+ */
+export function resolveTimingFromEnv(env = process.env) {
+    const raw = env.TERMDOCK_SUPERVISOR_TIMING;
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        process.stderr.write('[supervisor] TERMDOCK_SUPERVISOR_TIMING is not valid JSON; using defaults\n');
+        return {};
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return {};
+    const source = parsed;
+    const overrides = {};
+    for (const key of Object.keys(DEFAULT_SUPERVISOR_TIMING)) {
+        const value = source[key];
+        if (typeof value === 'number' && Number.isFinite(value) && value > 0)
+            overrides[key] = value;
+    }
+    return overrides;
+}
+export function defaultSpawnChild(config) {
+    const child = spawn(process.execPath, [config.childEntry, '--foreground', ...config.childArgs], {
+        detached: false,
+        stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+        env: {
+            ...process.env,
+            TERMDOCK_SUPERVISED: '1',
+            // 给子进程一个能指名道姓的 pid：它的 disconnect 处理器要靠这个说清
+            // "是谁丢下了我"，`ps` 里也能直接认出来。
+            TERMDOCK_SUPERVISOR_PID: String(process.pid),
+        },
+    });
+    // spawn 失败（ENOENT / EACCES）只会在 'error' 里出现，不会走 'exit'。
+    // 旧实现两个 spawn 都没挂 error 处理，于是"启动失败"表现为"什么都没发生"。
+    return child;
+}
+export function defaultNotifyLauncher(message) {
+    if (process.connected)
+        process.send?.(message);
+}
+export function defaultLog(message) {
+    // 走 stderr：它和子进程的 stdout/stderr 是同一个 fd（server.log），
+    // 于是 `tail -f ~/.termdock/server.log` 能同时看到服务和监督者的叙述。
+    process.stderr.write(`${new Date().toISOString()} ${message}\n`);
+}
+/**
+ * 监督一台服务。返回对象由入口按需驱动；测试直接调 handlers。
+ *
+ * 这里不装全局进程处理器——入口（main）负责那些，本函数只管状态机。
+ */
+export function createSupervisor(config, deps) {
+    const timing = { ...DEFAULT_SUPERVISOR_TIMING, ...(config.timing ?? {}) };
+    const now = deps.now ?? (() => Date.now());
+    const supervisorStartedAt = now();
+    let child = null;
+    let childPid = null;
+    let childStartedAt = 0;
+    let becameReady = false;
+    /** 本世代的 IPC 意图，随每次 spawn 重置 */
+    let intent = null;
+    let portConflict = false;
+    let wedgeKill = false;
+    let stopRequested = false;
+    let restartRequested = false;
+    let consecutiveCrashes = 0;
+    let restarts = 0;
+    let lastIncident = null;
+    let lastHealthOkAt = null;
+    let healthFailures = 0;
+    let phase = 'starting';
+    let readyTimer = null;
+    let healthTimer = null;
+    let crashResetTimer = null;
+    let restartTimer = null;
+    let stopping = false;
+    const clearTimers = () => {
+        for (const timer of [readyTimer, healthTimer, crashResetTimer, restartTimer]) {
+            if (timer)
+                clearTimeout(timer);
+        }
+        readyTimer = null;
+        healthTimer = null;
+        crashResetTimer = null;
+        restartTimer = null;
+    };
+    const persistState = () => {
+        deps.writeState({
+            version: SUPERVISOR_STATE_VERSION,
+            pid: process.pid,
+            serverPid: childPid,
+            phase,
+            startedAt: supervisorStartedAt,
+            restarts,
+            consecutiveCrashes,
+            lastIncident,
+        });
+    };
+    const setPhase = (next) => {
+        phase = next;
+        persistState();
+    };
+    function startChild() {
+        intent = null;
+        portConflict = false;
+        wedgeKill = false;
+        restartRequested = false;
+        becameReady = false;
+        healthFailures = 0;
+        childStartedAt = now();
+        setPhase('starting');
+        let errored = null;
+        const spawned = deps.spawnChild(config);
+        child = spawned;
+        childPid = spawned.pid ?? null;
+        spawned.on('error', (error) => {
+            errored = error;
+            deps.log(`[supervisor] failed to spawn child: ${error.message}`);
+            // 抢在 'exit' 之前记下原因；真正的出口统一走 handleExit。
+            portConflict = false;
+            handleExit(null, null, error);
+        });
+        spawned.on('message', (message) => {
+            if (isReadyMessage(message)) {
+                becameReady = true;
+                lastHealthOkAt = now();
+                if (readyTimer) {
+                    clearTimeout(readyTimer);
+                    readyTimer = null;
+                }
+                setPhase('running');
+                armCrashReset();
+                deps.log(`[supervisor] server ready (pid ${childPid ?? 'unknown'}, restarts ${restarts})`);
+                // 透传给 launcher：`td` 后台模式等的就是这个，而不是自己盲等 10 秒。
+                deps.notifyLauncher({ type: 'termdock-ready' });
+                return;
+            }
+            if (isServerIntentMessage(message)) {
+                intent = message.intent;
+                deps.log(`[supervisor] server declared intent: ${message.intent}`);
+            }
+        });
+        spawned.on('exit', (code, signal) => {
+            if (errored)
+                return;
+            handleExit(code, signal, null);
+        });
+        readyTimer = setTimeout(() => {
+            if (becameReady || stopping)
+                return;
+            deps.log(`[supervisor] server did not become ready within ${timing.readyTimeoutMs}ms; restarting`);
+            wedgeKill = false;
+            killChild('SIGTERM');
+        }, timing.readyTimeoutMs);
+        armHealthProbe();
+    }
+    /** 连续健康运行满 crashResetMs 就把崩溃计数清零——否则一天里零星崩 5 次也会被判"放弃"。 */
+    function armCrashReset() {
+        if (crashResetTimer)
+            clearTimeout(crashResetTimer);
+        const generation = childPid;
+        crashResetTimer = setTimeout(() => {
+            if (childPid !== generation || !becameReady)
+                return;
+            if (consecutiveCrashes !== 0) {
+                deps.log(`[supervisor] server stayed healthy for ${timing.crashResetMs}ms; clearing crash counter`);
+            }
+            consecutiveCrashes = 0;
+            persistState();
+        }, timing.crashResetMs);
+    }
+    /**
+     * 健康探测。卡死的事件循环不会应答任何请求，所以"超时"就是"卡死"，
+     * 不需要额外的心跳协议。
+     */
+    function armHealthProbe() {
+        if (healthTimer)
+            clearInterval(healthTimer);
+        healthTimer = setInterval(() => {
+            if (stopping || !becameReady || !child)
+                return;
+            void deps.probe(config.healthUrl, config.healthCaPath, timing.healthProbeTimeoutMs).then((result) => {
+                if (stopping || !child)
+                    return;
+                if (result.ok) {
+                    healthFailures = 0;
+                    lastHealthOkAt = now();
+                    return;
+                }
+                healthFailures += 1;
+                deps.log(`[supervisor] health probe failed (${healthFailures}/${timing.wedgeFailures}): ${result.failure ?? 'unknown'}`);
+                if (healthFailures < timing.wedgeFailures)
+                    return;
+                healthFailures = 0;
+                wedgeKill = true;
+                deps.log('[supervisor] server looks wedged; killing it so it can be restarted');
+                killChild('SIGTERM');
+            });
+        }, timing.healthIntervalMs);
+    }
+    function killChild(signal) {
+        if (!child)
+            return;
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // 进程可能刚退出，'exit' 会跟上。
+            return;
+        }
+        if (signal !== 'SIGTERM' || !childPid)
+            return;
+        const targetPid = childPid;
+        const deadline = now() + timing.killGraceMs;
+        const escalate = setInterval(() => {
+            if (childPid !== targetPid || !isProcessRunning(targetPid)) {
+                clearInterval(escalate);
+                return;
+            }
+            if (now() >= deadline) {
+                clearInterval(escalate);
+                deps.log(`[supervisor] child ${targetPid} ignored SIGTERM; sending SIGKILL`);
+                try {
+                    child?.kill('SIGKILL');
+                }
+                catch { /* already gone */ }
+            }
+        }, Math.max(100, Math.min(1_000, timing.killGraceMs / 4)));
+        // 该 interval 不该拖住 supervisor 的退出。
+        escalate.unref?.();
+    }
+    function handleExit(code, signal, spawnError) {
+        // 停止请求不做提前返回：它要走的是分类表里的 `stop` 分支（记录 + 删状态 + 退出 0）。
+        // 这里若直接 return，`--stop` 就会在 crash.log 里留下一段无法解释的空白。
+        if (healthTimer) {
+            clearInterval(healthTimer);
+            healthTimer = null;
+        }
+        if (readyTimer) {
+            clearTimeout(readyTimer);
+            readyTimer = null;
+        }
+        if (crashResetTimer) {
+            clearTimeout(crashResetTimer);
+            crashResetTimer = null;
+        }
+        const uptimeMs = now() - childStartedAt;
+        const exitedPid = childPid;
+        child = null;
+        childPid = null;
+        const runtimeTail = readRuntimeTail(childStartedAt);
+        const oomSuspect = isOomSuspect(runtimeTail);
+        const observation = {
+            intent,
+            exitCode: code,
+            signal,
+            becameReady,
+            supervisorStopRequested: stopRequested,
+            restartRequested,
+            wedge: wedgeKill,
+            portConflict,
+            oomSuspect,
+        };
+        const decision = classifyChildExit(observation);
+        // 计数先于记录：crash.log 里的 `consecutiveCrashes` 应当读作
+        // "算上这一次的第几次"，否则五连崩会记成 0/1/2/3/4，而 gave-up 那条写 5。
+        if (decision.resetBackoff)
+            consecutiveCrashes = 0;
+        else if (decision.countAsCrash)
+            consecutiveCrashes += 1;
+        lastIncident = {
+            at: now(),
+            event: decision.event,
+            detail: spawnError ? `failed to spawn: ${spawnError.message}` : decision.detail,
+            exitCode: code,
+            signal,
+            uptimeMs,
+            version: config.version ?? null,
+            oomSuspect,
+            restartCount: restarts,
+        };
+        recordIncident(decision, observation, {
+            serverPid: exitedPid,
+            uptimeMs,
+            runtimeTail,
+            spawnError: spawnError?.message ?? null,
+        });
+        // 第一世代就没起来：立刻告诉 launcher，别让它空等到超时。
+        // 之后 supervisor 仍会按退避继续重试，所以只说"这次没起来"，不说"放弃了"。
+        if (restarts === 0 && !becameReady && !stopRequested) {
+            deps.notifyLauncher({
+                type: 'termdock-startup-failed',
+                reason: spawnError ? 'spawn-failed' : decision.event,
+                detail: spawnError ? spawnError.message : decision.detail,
+            });
+        }
+        if (!decision.restart) {
+            deps.log(`[supervisor] server ${decision.event} (${decision.detail}); not restarting`);
+            setPhase('stopped');
+            deps.clearState();
+            deps.exit(0);
+            return;
+        }
+        if (shouldGiveUp(consecutiveCrashes, timing.maxConsecutiveCrashes)) {
+            lastIncident.detail = `${lastIncident.detail} — gave up after ${consecutiveCrashes} consecutive crashes`;
+            deps.log(`[supervisor] ${consecutiveCrashes} consecutive crashes; giving up. Service is NOT running.`);
+            recordApplicationGaveUp();
+            setPhase('gave-up');
+            deps.exit(1);
+            return;
+        }
+        restarts += 1;
+        const delayMs = decision.event === 'update-restart' || decision.event === 'manual-restart'
+            ? timing.restartDelayMs
+            : backoffDelayMs(consecutiveCrashes, { baseMs: timing.backoffBaseMs, maxMs: timing.backoffMaxMs });
+        setPhase('restarting');
+        deps.log(`[supervisor] restarting server in ${delayMs}ms (event=${decision.event}, restarts=${restarts})`);
+        restartTimer = setTimeout(() => {
+            restartTimer = null;
+            if (stopping)
+                return;
+            startChild();
+        }, delayMs);
+    }
+    function recordApplicationGaveUp() {
+        deps.recordIncident({
+            role: 'supervisor',
+            event: 'gave-up',
+            detail: `gave up after ${consecutiveCrashes} consecutive crashes`,
+            version: config.version ?? null,
+            restarts,
+            lastIncident,
+            restartCommand: config.version ? `npm i -g termdock@${config.version}` : null,
+        });
+    }
+    function recordIncident(decision, observation, extra) {
+        deps.recordIncident({
+            role: 'supervisor',
+            event: decision.event,
+            detail: decision.detail,
+            exitCode: observation.exitCode,
+            signal: observation.signal,
+            version: config.version ?? null,
+            supervisorPid: process.pid,
+            restartCount: restarts,
+            consecutiveCrashes,
+            lastHealthOkAt,
+            ...extra,
+            logTail: readServerLogTail(),
+        });
+    }
+    /** launcher 发的停止请求：杀子进程、删状态、退出。收尾统一走 handleExit 的 `stop` 分支。 */
+    function stop() {
+        if (stopping)
+            return;
+        stopping = true;
+        stopRequested = true;
+        clearTimers();
+        if (!child) {
+            deps.clearState();
+            deps.exit(0);
+            return;
+        }
+        killChild('SIGTERM');
+        // 兜底：子进程迟迟不退（僵尸、收不到信号）也不能让 --stop 挂住。
+        setTimeout(() => {
+            deps.clearState();
+            deps.exit(0);
+        }, timing.killGraceMs + 1_000).unref?.();
+    }
+    /** `td --restart`：不发停止请求，只让子进程重启一次。 */
+    function restart() {
+        if (stopping || !child)
+            return;
+        restartRequested = true;
+        deps.log('[supervisor] manual restart requested');
+        killChild('SIGTERM');
+    }
+    return {
+        phase: () => phase,
+        start: () => { startChild(); },
+        stop,
+        restart,
+    };
+}
+/** 供 CLI 复用的 supervisor 入口地址（与 cli.js 同目录）。 */
+export function resolveSupervisorEntry() {
+    return fileURLToPath(new URL('./supervisor.js', import.meta.url));
+}
+function parseArgs(argv) {
+    const separator = argv.indexOf('--');
+    const own = separator >= 0 ? argv.slice(0, separator) : argv;
+    const childArgs = separator >= 0 ? argv.slice(separator + 1) : [];
+    const value = (flag) => {
+        const index = own.indexOf(flag);
+        return index >= 0 ? own[index + 1] : undefined;
+    };
+    const healthUrl = value('--health-url');
+    const childEntry = value('--child');
+    if (!healthUrl || !childEntry)
+        return null;
+    return {
+        healthUrl,
+        healthCaPath: value('--health-ca'),
+        version: value('--version'),
+        childEntry,
+        childArgs,
+    };
+}
+/**
+ * 以**当前进程**作为 supervisor 启动监督（装全局处理器 + 信号处理 + 开跑）。
+ *
+ * 两条入口共用：`supervisor.js` 独立入口（`td` 后台模式 spawn 它），
+ * 以及 `td --supervise`（cli.ts 进程自己当 supervisor，给 setsid/systemd 用）。
+ */
+export function runSupervisor(config, overrides = {}) {
+    const forensics = installCrashForensics({ role: 'supervisor', version: config.version ?? null });
+    const handle = createSupervisor(config, {
+        spawnChild: defaultSpawnChild,
+        probe: probeHealthOnce,
+        recordIncident: (entry) => writeJsonLogSync('crash.log', entry),
+        log: defaultLog,
+        exit: (code) => {
+            forensics.dispose();
+            process.exit(code);
+        },
+        now: () => Date.now(),
+        writeState: (state) => writeJsonStateAtomic(SUPERVISOR_STATE_PATH, state),
+        clearState: () => removeJsonState(SUPERVISOR_STATE_PATH),
+        notifyLauncher: defaultNotifyLauncher,
+        ...overrides,
+    });
+    const stop = () => { handle.stop(); };
+    process.on('SIGTERM', stop);
+    process.on('SIGINT', stop);
+    process.on('SIGHUP', () => handle.restart());
+    // launcher 断了不该影响监督：它已经拿到了 ready/失败，之后 supervisor 自己活着。
+    process.on('disconnect', () => { });
+    handle.start();
+    return handle;
+}
+function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (!parsed) {
+        process.stderr.write('Usage: supervisor --health-url <url> --child <entry> [--health-ca <path>] [--version <v>] -- [child args]\n');
+        process.exit(2);
+    }
+    // realpath 一次，之后每次重启都用这个绝对路径：既绕开 `npm i -g` 删建符号链接
+    // 窗口里的 ENOENT，也消除"重启落到了另一个安装"的歧义（PATH 按名字找会）。
+    let childEntry;
+    try {
+        childEntry = fs.realpathSync(parsed.childEntry);
+    }
+    catch (error) {
+        process.stderr.write(`[supervisor] child entry is not readable: ${parsed.childEntry} (${error.message})\n`);
+        process.exit(2);
+        return;
+    }
+    runSupervisor({
+        childEntry,
+        childArgs: parsed.childArgs,
+        healthUrl: parsed.healthUrl,
+        healthCaPath: parsed.healthCaPath,
+        version: parsed.version,
+        timing: resolveTimingFromEnv(),
+    });
+}
+const isDirectExecution = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isDirectExecution) {
+    main();
+}

package/dist/server/utils/backoff.js

@@ -0,0 +1,15 @@
+/**
+ * 指数退避。PTY 创建冷却与 supervisor 的崩溃重启共用同一套曲线，
+ * 免得两处各写一遍 `min(30_000, 1000 * 2 ** (n - 1))` 再各自跑偏。
+ */
+/**
+ * 第 `failures` 次失败后应等待多久。failures 从 1 起算
+ * （0 或负数按第 1 次处理），因此返回 baseMs 而不是它的一半。
+ */
+export function backoffDelayMs(failures, options = {}) {
+    const baseMs = options.baseMs ?? 1_000;
+    const maxMs = options.maxMs ?? 30_000;
+    const cap = options.cap ?? 6;
+    const attempt = Math.max(1, Math.min(failures, cap));
+    return Math.min(maxMs, baseMs * 2 ** (attempt - 1));
+}