termdock 1.4.260 → 1.4.262

package/dist/server/utils/crashForensics.js

@@ -0,0 +1,227 @@
+/**
+ * 进程内崩溃取证：进程在"运行中挂了"时，至少留下一份能说清原因的记录。
+ *
+ * 现状是反过来的——全仓没有 uncaughtException/unhandledRejection 处理，
+ * 而 `~/.termdock/server.log` 连时间戳都没有；挂掉之后没人知道为什么。
+ *
+ * 职责边界：这里只负责**记录**，不负责重启（那是 supervisor 的事，见 supervisor.ts）。
+ * 两者故意解耦：supervisor 覆盖不了"进程还在但内部已错乱"，进程内处理器覆盖不了
+ * SIGKILL/OOM——两边各自记录，缺一边都不完整。
+ *
+ * 所有写盘都走 `writeJsonLogSync`：崩溃路径上事件循环已经停了，
+ * 排队中的异步写永远不会落盘。
+ */
+import fs from 'fs';
+import { getTermdockLogPath, writeJsonLogSync } from './serverLogger.js';
+import { RUNTIME_METRICS_PATH, TERMDOCK_DIR } from './termdockState.js';
+import { getTermdockVersion } from './version.js';
+const CRASH_LOG_NAME = 'crash.log';
+const LOG_TAIL_MAX_LINES = 40;
+const LOG_TAIL_MAX_BYTES = 64 * 1024;
+const CRASH_LOG_TAIL_LINES = 60;
+const CRASH_LOG_TAIL_BYTES = 64 * 1024;
+const RUNTIME_TAIL_MAX_SAMPLES = 3;
+const RUNTIME_TAIL_MAX_BYTES = 32 * 1024;
+const RUNTIME_TAIL_SCAN_LINES = 200;
+/**
+ * RSS 逼近这个值就标注 oomSuspect。与 runtimeMonitor 的 PROCESS_RSS_HIGH 临界阈值一致。
+ * 这只是**启发式**：OOM killer 杀进程发的是普通 SIGKILL，和任意一次 kill -9 在信号上
+ * 无法区分。它给出的是一份"当时内存有多高"的旁证，不是结论。
+ */
+export const OOM_SUSPECT_RSS_BYTES = 1024 ** 3;
+/** 从文件尾部倒着读，最多 maxBytes，再按行切。避免为了 40 行读整个 2 MiB 日志。 */
+function readTailLines(filePath, maxLines, maxBytes) {
+    let fd = null;
+    try {
+        const stat = fs.statSync(filePath, { throwIfNoEntry: false });
+        if (!stat?.isFile() || stat.size === 0)
+            return [];
+        const readBytes = Math.min(stat.size, maxBytes);
+        fd = fs.openSync(filePath, 'r');
+        const buffer = Buffer.allocUnsafe(readBytes);
+        fs.readSync(fd, buffer, 0, readBytes, stat.size - readBytes);
+        const text = buffer.toString('utf8');
+        const lines = text.split('\n');
+        // 起点若不是文件开头，首行大概率是被切断的半行，丢掉。
+        if (readBytes < stat.size)
+            lines.shift();
+        return lines.filter((line) => line.length > 0).slice(-maxLines);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* 已在错误路径上 */ }
+        }
+    }
+}
+/**
+ * crash.log 尾部的记录（已解析，从旧到新）。解析不了的行直接跳过——
+ * 崩溃现场写到一半被打断是常态，不能因为一行坏数据就让整份证据作废。
+ */
+export function readCrashLogTail(maxLines = CRASH_LOG_TAIL_LINES, crashLogPath = getTermdockLogPath(CRASH_LOG_NAME)) {
+    return readTailLines(crashLogPath, maxLines, CRASH_LOG_TAIL_BYTES).flatMap((line) => {
+        try {
+            const entry = JSON.parse(line);
+            return entry && typeof entry === 'object' ? [entry] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** server.log 尾部若干行，给人看的那一面（内容原样，不做解析）。 */
+export function readServerLogTail(maxLines = LOG_TAIL_MAX_LINES, logDirectory = TERMDOCK_DIR) {
+    return readTailLines(getTermdockLogPath('server.log', logDirectory), maxLines, LOG_TAIL_MAX_BYTES);
+}
+/**
+ * runtime-metrics.log 尾部若干条运行指标。样本里**没有 pid**，所以只能按时间戳过滤，
+ * 并用 uptimeSeconds 交叉印证是不是同一世代。
+ */
+export function readRuntimeTail(sinceTimestamp, maxSamples = RUNTIME_TAIL_MAX_SAMPLES, metricsPath = RUNTIME_METRICS_PATH) {
+    const lines = readTailLines(metricsPath, RUNTIME_TAIL_SCAN_LINES, RUNTIME_TAIL_MAX_BYTES);
+    return lines.flatMap((line) => {
+        try {
+            const sample = JSON.parse(line);
+            if (!Number.isFinite(sample.timestamp))
+                return [];
+            if (sinceTimestamp !== undefined && sample.timestamp < sinceTimestamp)
+                return [];
+            return [{
+                    timestamp: sample.timestamp,
+                    uptimeSeconds: sample.uptimeSeconds ?? 0,
+                    rssBytes: sample.rssBytes ?? 0,
+                    eventLoopDelayP99Ms: sample.eventLoopDelayP99Ms ?? 0,
+                    activeConnections: sample.activeConnections ?? 0,
+                }];
+        }
+        catch {
+            return [];
+        }
+    }).slice(-maxSamples);
+}
+export function isOomSuspect(samples) {
+    const last = samples.at(-1);
+    return Boolean(last && last.rssBytes >= OOM_SUSPECT_RSS_BYTES);
+}
+function describeError(error) {
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message, stack: error.stack };
+    }
+    if (error === undefined)
+        return null;
+    return { name: 'NonError', message: String(error) };
+}
+/** 组装一条完整现场：进程身份 + 退出信息 + 错误 + server.log 尾部 + 运行指标尾部。 */
+export function collectCrashEvidence(options) {
+    const runtimeTail = readRuntimeTail(options.startedAt, undefined, options.runtimeMetricsPath);
+    return {
+        role: options.role,
+        event: options.event,
+        version: options.version ?? null,
+        uptimeMs: options.startedAt !== undefined ? Date.now() - options.startedAt : null,
+        exitCode: options.exitCode ?? null,
+        signal: options.signal ?? null,
+        oomSuspect: isOomSuspect(runtimeTail),
+        error: describeError(options.error),
+        ...(options.extra ?? {}),
+        runtimeTail,
+        logTail: readServerLogTail(undefined, options.logDirectory),
+    };
+}
+function defaultRecord(entry) {
+    writeJsonLogSync(CRASH_LOG_NAME, entry);
+}
+/**
+ * 安装全局崩溃取证。返回的 `recordIncident` 供调用方记录已知的异常事件。
+ *
+ * 注意 `unhandledRejection`：装上监听器就等于**接管了 Node 默认的 crash-on-unhandled-rejection**。
+ * 对一台会话服务器，这是有意的政策——一个没人 await 的 promise 不该干掉整台服务；
+ * 真卡死了还有 supervisor 的健康探测兜底。代价是坏不变量可能带病存续，
+ * 所以这里记录得足够响（crash.log + stderr），任何一条都不该被忽略。
+ */
+export function installCrashForensics(options) {
+    const record = options.record ?? defaultRecord;
+    const log = options.log ?? ((message, error) => console.error(message, error ?? ''));
+    const exit = options.exit ?? ((code) => process.exit(code));
+    // 崩溃处理器自己抛异常会再次进入处理器，这是经典死循环；守卫必须是闭包级的。
+    let recording = false;
+    // uncaughtException 已经记过一条完整的，退出处理器不要再记一条重复的。
+    let fatalRecorded = false;
+    const recordIncident = (event, extra = {}) => {
+        if (recording)
+            return;
+        recording = true;
+        try {
+            const { extra: nested, ...fields } = extra;
+            record(collectCrashEvidence({
+                role: options.role,
+                event,
+                startedAt: options.startedAt,
+                version: options.version,
+                ...fields,
+                extra: { ...(options.context?.() ?? {}), ...(nested ?? {}) },
+            }));
+        }
+        catch {
+            // 取证失败绝不能变成第二个故障。
+        }
+        finally {
+            recording = false;
+        }
+    };
+    const handlers = {
+        onUncaughtException: (error) => {
+            fatalRecorded = true;
+            recordIncident('uncaught-exception', { error });
+            log('[termdock] uncaught exception:', error);
+            exit(1);
+        },
+        onUnhandledRejection: (reason) => {
+            recordIncident('unhandled-rejection', { error: reason });
+            log('[termdock] unhandled rejection (service keeps running):', reason);
+        },
+        onExit: (code) => {
+            if (code === 0 || fatalRecorded)
+                return;
+            // 这里事件循环已经停了：只能同步写。
+            recordIncident('exit-nonzero', { exitCode: code });
+        },
+    };
+    const installed = options.install !== false;
+    if (installed) {
+        process.on('uncaughtException', handlers.onUncaughtException);
+        process.on('unhandledRejection', handlers.onUnhandledRejection);
+        process.on('exit', handlers.onExit);
+    }
+    return {
+        recordIncident,
+        handlers,
+        dispose: () => {
+            if (!installed)
+                return;
+            process.off('uncaughtException', handlers.onUncaughtException);
+            process.off('unhandledRejection', handlers.onUnhandledRejection);
+            process.off('exit', handlers.onExit);
+        },
+    };
+}
+/**
+ * supervisor 断链时由服务侧记录。**不自杀**：服务本身是健康的，
+ * 丢监督好过丢服务。界面红点靠这条记录来提示"现在没人看着它了"。
+ */
+export function recordSupervisorLost(detail) {
+    writeJsonLogSync(CRASH_LOG_NAME, {
+        role: 'server',
+        event: 'supervisor-lost',
+        detail,
+        version: getTermdockVersion(),
+        serverPid: process.pid,
+        uptimeMs: Math.round(process.uptime() * 1_000),
+    });
+}
+export { CRASH_LOG_NAME };

package/dist/server/utils/healthProbe.js

@@ -0,0 +1,92 @@
+/**
+ * 服务就绪/存活探测。CLI 首次拉起服务、supervisor 长期盯守都走这里，
+ * 避免"启动时怎么判活着"和"运行时怎么判活着"长出两套标准。
+ *
+ * 从 cli.ts 原样搬出（waitForHealth / DAEMON_START_TIMEOUT_MS），额外拆出
+ * 单次探测 probeHealthOnce() 供 supervisor 的卡死判定复用——原来的实现是
+ * 写死在循环里的，无法单独调用。
+ */
+import fs from 'fs';
+import http from 'http';
+import https from 'https';
+/** 等 daemon 子进程响应 /health 的上限。 */
+export const DAEMON_START_TIMEOUT_MS = 10_000;
+/** 单次 /health 请求的 socket 超时。 */
+export const HEALTH_PROBE_TIMEOUT_MS = 2_000;
+/**
+ * 单次探测。注意它同时是"存活"信号：事件循环若卡死，请求根本不会被应答，
+ * 于是以 timeout 收场——这正是 supervisor 判 wedge 需要的语义。
+ * 自签 HTTPS 通过 caPath 放行；没给 caPath 就不做证书校验（与原实现一致）。
+ */
+export async function probeHealthOnce(healthUrl, caPath, timeoutMs = HEALTH_PROBE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        try {
+            const transport = healthUrl.startsWith('https:') ? https : http;
+            const req = transport.get(healthUrl, {
+                ca: caPath ? fs.readFileSync(caPath) : undefined,
+                rejectUnauthorized: Boolean(caPath),
+                timeout: timeoutMs,
+            }, (res) => {
+                let data = '';
+                res.setEncoding('utf8');
+                res.on('data', (chunk) => { data += chunk; });
+                res.on('end', () => {
+                    const status = res.statusCode ?? 0;
+                    if (status < 200 || status >= 300) {
+                        finish({ ok: false, failure: 'bad-status', detail: `HTTP ${status}` });
+                        return;
+                    }
+                    if (!data.includes('"status":"ok"')) {
+                        finish({ ok: false, failure: 'bad-body', detail: data.slice(0, 200) });
+                        return;
+                    }
+                    finish({ ok: true });
+                });
+                res.on('error', (error) => {
+                    finish({ ok: false, failure: 'unreachable', detail: error.message });
+                });
+            });
+            req.on('error', (error) => {
+                finish({ ok: false, failure: 'unreachable', detail: error.message });
+            });
+            req.on('timeout', () => {
+                req.destroy();
+                finish({ ok: false, failure: 'timeout' });
+            });
+        }
+        catch (error) {
+            finish({
+                ok: false,
+                failure: 'unreachable',
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+}
+/**
+ * 轮询直到就绪、超时或进程死亡。语义与搬迁前完全一致：
+ * 先等 isReady() 翻真，再要求 /health 应答且 isAlive() 仍成立。
+ */
+export async function waitForHealth(healthUrl, caPath, timeoutMs, isReady, isAlive) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isAlive())
+            return false;
+        if (!isReady()) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            continue;
+        }
+        const probe = await probeHealthOnce(healthUrl, caPath);
+        if (probe.ok && isAlive())
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    return false;
+}

package/dist/server/utils/ptySpawnBackoff.js

@@ -1,3 +1,4 @@
+import { backoffDelayMs } from './backoff.js';
 /** Shared across WebSockets and sessions: PTYs/FDs are process-wide resources. */
 export class PtySpawnDeferredError extends Error {
     retryAfterMs;
@@ -28,7 +29,7 @@ export class PtySpawnBackoff {
         }
         catch (error) {
             this.failures = Math.min(this.failures + 1, 6);
-            this.retryAt = this.now() + Math.min(30_000, 1000 * 2 ** (this.failures - 1));
+            this.retryAt = this.now() + backoffDelayMs(this.failures);
             throw error; // Preserve errno and the original diagnostic in the real failure log.
         }
     }

package/dist/server/utils/serverHealth.js

@@ -0,0 +1,126 @@
+/**
+ * 「服务最近出过什么事」——给界面红点与设置面板用的只读快照。
+ *
+ * 数据源是 **crash.log**，不是 supervisor.json：crash.log 由两个角色一起写
+ * （supervisor 记子进程怎么死的，服务自己记 uncaughtException / supervisor-lost），
+ * 因此在**没有监督者**的部署里同样有内容。supervisor.json 只补两样它才知道的事：
+ * 谁在盯着、重启了几次、当前处于哪个阶段。
+ *
+ * 这个模块只读不写（dismiss 除外），且绝不抛异常：它服务于"出事了怎么告诉用户"，
+ * 自己再炸一次就太难看了。
+ */
+import { INCIDENT_DISMISSED_PATH, readJsonFile, writeJsonStateAtomic, } from './termdockState.js';
+import { readCrashLogTail } from './crashForensics.js';
+import { getSupervisorStatus } from './supervisorClient.js';
+/**
+ * 值得用户知道的事件。刻意排除 `stop`（是用户自己停的）、
+ * `update-restart` / `manual-restart`（我们自己发起的，成功了就没什么可说）。
+ */
+const NOTABLE_EVENTS = new Set([
+    'startup-failure',
+    'crash',
+    'crash-native',
+    'killed',
+    'wedge',
+    'port-conflict',
+    'gave-up',
+    'exit-zero-unexpected',
+    'terminated-externally',
+    'supervisor-lost',
+    'uncaught-exception',
+    'unhandled-rejection',
+    'exit-nonzero',
+]);
+function pickString(value) {
+    return typeof value === 'string' ? value : null;
+}
+function pickNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/** 把一条 crash.log 记录投影成界面要的形状。缺字段一律降级为 null，不猜。 */
+export function toIncident(entry) {
+    const event = pickString(entry.event);
+    if (!event)
+        return null;
+    const parsed = pickString(entry.ts) ? Date.parse(entry.ts) : Number.NaN;
+    return {
+        at: Number.isFinite(parsed) ? parsed : 0,
+        event,
+        detail: pickString(entry.detail) ?? '',
+        role: pickString(entry.role) ?? 'unknown',
+        exitCode: pickNumber(entry.exitCode),
+        signal: pickString(entry.signal),
+        uptimeMs: pickNumber(entry.uptimeMs),
+        version: pickString(entry.version),
+        oomSuspect: entry.oomSuspect === true,
+        restartCount: pickNumber(entry.restartCount),
+    };
+}
+/** 最新一条值得注意的事件（没有就返回 null）。 */
+export function findLatestNotableIncident(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const incident = toIncident(entries[index]);
+        if (incident && NOTABLE_EVENTS.has(incident.event))
+            return incident;
+    }
+    return null;
+}
+function readDismissal(path) {
+    const record = readJsonFile(path);
+    return typeof record?.dismissedAt === 'number' ? record.dismissedAt : null;
+}
+function projectSupervisor(state, alive) {
+    if (!state)
+        return null;
+    return {
+        pid: state.pid,
+        alive,
+        phase: state.phase,
+        restarts: state.restarts,
+        consecutiveCrashes: state.consecutiveCrashes,
+    };
+}
+export function buildServerHealthState(options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const crashLogPath = options.crashLogPath;
+    const dismissedPath = options.dismissedPath ?? INCIDENT_DISMISSED_PATH;
+    let incident = null;
+    try {
+        incident = findLatestNotableIncident(readCrashLogTail(undefined, crashLogPath));
+    }
+    catch {
+        // 取证读取失败不该让界面也挂掉：没有消息就是没有消息。
+    }
+    let supervisor = null;
+    try {
+        const status = getSupervisorStatus(options.supervisorStatePath);
+        supervisor = projectSupervisor(status?.state ?? null, status?.alive ?? false);
+    }
+    catch {
+        supervisor = null;
+    }
+    const dismissedAt = readDismissal(dismissedPath);
+    return {
+        supervised: process.env.TERMDOCK_SUPERVISED === '1',
+        supervisor,
+        incident,
+        dismissedAt,
+        attention: Boolean(incident && incident.at > (dismissedAt ?? 0)),
+        generatedAt: now(),
+    };
+}
+/** 「知道了」：把当前这条记成已被确认，红点随之消失。 */
+export function dismissServerHealth(options = {}) {
+    const before = buildServerHealthState(options);
+    if (before.incident) {
+        try {
+            writeJsonStateAtomic(options.dismissedPath ?? INCIDENT_DISMISSED_PATH, {
+                dismissedAt: before.incident.at,
+            });
+        }
+        catch {
+            // 写不进去就等于没确认，红点会再出现——比谎报"已读"好。
+        }
+    }
+    return buildServerHealthState(options);
+}

package/dist/server/utils/serverLogger.js

@@ -1,7 +1,6 @@
 import fs from 'fs';
-import os from 'os';
 import path from 'path';
-const TERMDOCK_DIR = path.join(os.homedir(), '.termdock');
+import { TERMDOCK_DIR } from './termdockState.js';
 const MIB = 1024 * 1024;
 const DEFAULT_MAX_BYTES = 4 * MIB;
 const SERVER_LOG_MAX_BYTES = 2 * MIB;
@@ -10,6 +9,7 @@ const LOG_MAINTENANCE_INTERVAL_MS = 10 * 60 * 1000;
 const MANAGED_LOG_NAMES = [
     'access.log',
     'client.log',
+    'crash.log',
     'diff-trace.log',
     'errors.log',
     'fs-io.log',
@@ -138,8 +138,8 @@ function enqueueWrite(filePath, line, maxBytes) {
         .catch(() => undefined);
     writeChains.set(filePath, next);
 }
-export function getTermdockLogPath(name) {
-    return path.join(TERMDOCK_DIR, name);
+export function getTermdockLogPath(name, directory = TERMDOCK_DIR) {
+    return path.join(directory, name);
 }
 export function writeJsonLog(name, entry, maxBytes = DEFAULT_MAX_BYTES) {
     const filePath = getTermdockLogPath(name);
@@ -150,6 +150,29 @@ export function writeJsonLog(name, entry, maxBytes = DEFAULT_MAX_BYTES) {
     }) + '\n';
     enqueueWrite(filePath, line, maxBytes);
 }
+/**
+ * 同步写一条 JSONL。**只给崩溃取证用**，不要拿它写常规日志：它绕过写队列与轮转，
+ * 会阻塞事件循环。
+ *
+ * 存在的理由：`writeJsonLog` 走 `fs.promises.appendFile`，而 `process.on('exit')`
+ * 里事件循环已经停了，排队的异步写永远不会落盘——崩溃现场会静默消失。
+ * 因此这里既不能 await 也不能 rotate，只能直接 append。
+ */
+export function writeJsonLogSync(name, entry) {
+    try {
+        const filePath = getTermdockLogPath(name);
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            pid: process.pid,
+            ...entry,
+        }) + '\n';
+        fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+        fs.appendFileSync(filePath, line, { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        // 已经在崩溃/退出路径上，写不进去也不能再抛一次。
+    }
+}
 export function writeTextLog(name, line, maxBytes = DEFAULT_MAX_BYTES) {
     const filePath = getTermdockLogPath(name);
     enqueueWrite(filePath, `${line.replace(/\n$/, '')}\n`, maxBytes);

package/dist/server/utils/supervisorClient.js

@@ -0,0 +1,151 @@
+/**
+ * launcher（`td` / `td --status` / `td --stop`）看向 supervisor 的那一侧。
+ *
+ * 与 supervisor.ts 分开是为了单向依赖：supervisor 是独立入口，不能反过来
+ * 依赖 CLI 的进程；CLI 只是它的客户端。
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { isProcessRunning, readJsonFile, SUPERVISOR_STATE_PATH } from './termdockState.js';
+import { isSupervisorState } from './supervisorProtocol.js';
+import { STOP_GRACE_MS } from './termdockState.js';
+/** supervisor.js 与 cli.js 同目录，所以从本模块（dist/server/utils/）回退一级。 */
+export function resolveSupervisorScript() {
+    return fileURLToPath(new URL('../supervisor.js', import.meta.url));
+}
+export function readSupervisorState() {
+    const state = readJsonFile(SUPERVISOR_STATE_PATH);
+    return isSupervisorState(state) ? state : null;
+}
+/**
+ * 读出 supervisor 状态，并单独给出"它现在还活着吗"。
+ *
+ * **进程死了也不删状态文件**：`gave-up` 正是它死的原因，那份记录就是结论本身；
+ * 别的 phase 下进程没了则意味着"supervisor 自己崩了，服务现在无人监督"——
+ * 两件事都必须能被告知用户。陈旧的判断交给调用方（它才知道自己在问什么），
+ * 真正的清理留给 `td --stop`。
+ */
+export function getSupervisorStatus(statePath = SUPERVISOR_STATE_PATH) {
+    const raw = readJsonFile(statePath);
+    if (!isSupervisorState(raw))
+        return null;
+    return { state: raw, alive: isProcessRunning(raw.pid) };
+}
+/**
+ * 起一个 detached 的 supervisor，并等它把子进程的结局告诉我们。
+ *
+ * 与旧实现的关键差别：这里**会等结果**。旧 `node -e` bridge 是发射后不管，
+ * 新进程起没起来只有用户下次访问才知道。
+ */
+export function spawnSupervisor(options) {
+    return new Promise((resolve) => {
+        const args = [
+            resolveSupervisorScript(),
+            '--health-url', options.healthUrl,
+            '--child', options.childEntry,
+        ];
+        if (options.healthCaPath)
+            args.push('--health-ca', options.healthCaPath);
+        if (options.version)
+            args.push('--version', options.version);
+        args.push('--', ...options.childArgs);
+        let child;
+        try {
+            child = spawn(process.execPath, args, {
+                detached: true,
+                stdio: ['ignore', options.logFileFd, options.logFileFd, 'ipc'],
+            });
+        }
+        catch (error) {
+            resolve({ ok: false, reason: 'spawn-failed', detail: error.message });
+            return;
+        }
+        let settled = false;
+        let spawnError = null;
+        // 拿到结局就断开 IPC 并 unref：supervisor 继续跑，launcher 可以退出。
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (child.connected)
+                child.disconnect();
+            child.unref();
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            finish({ ok: false, reason: 'timeout', detail: `no ready within ${options.readyTimeoutMs}ms` });
+        }, options.readyTimeoutMs);
+        child.on('error', (error) => {
+            spawnError = error;
+            finish({ ok: false, reason: 'spawn-failed', detail: error.message });
+        });
+        child.on('message', (message) => {
+            if (!message || typeof message !== 'object' || !('type' in message))
+                return;
+            const typed = message;
+            if (typed.type === 'termdock-ready') {
+                finish({ ok: true, pid: child.pid });
+            }
+            else if (typed.type === 'termdock-startup-failed') {
+                finish({ ok: false, reason: typed.reason, detail: typed.detail });
+            }
+        });
+        child.on('exit', (code, signal) => {
+            finish({
+                ok: false,
+                reason: 'supervisor-exited',
+                detail: spawnError?.message ?? `exited (code ${code ?? 'unknown'}, signal ${signal ?? 'none'})`,
+            });
+        });
+    });
+}
+/**
+ * 停 supervisor：它是唯一该被停的东西，子进程由它负责。
+ *
+ * 先发 SIGTERM 让它自己收拾（杀子进程、删状态、退出 0）；宽限期到了还在，
+ * 才 SIGKILL。**不**在这里直接杀子进程——那会让它变成"意外死亡"从而被重启。
+ */
+export async function stopSupervisor(pid, graceMs = STOP_GRACE_MS) {
+    if (!isProcessRunning(pid)) {
+        try {
+            fs.rmSync(SUPERVISOR_STATE_PATH, { force: true });
+        }
+        catch { /* nothing to clean */ }
+        return true;
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return true;
+    }
+    const deadline = Date.now() + graceMs;
+    while (isProcessRunning(pid) && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (isProcessRunning(pid)) {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    try {
+        fs.rmSync(SUPERVISOR_STATE_PATH, { force: true });
+    }
+    catch { /* nothing to clean */ }
+    return !isProcessRunning(pid);
+}
+/** `td --restart`：让 supervisor 重启子进程，但继续监督。 */
+export function signalSupervisorRestart(pid) {
+    try {
+        process.kill(pid, 'SIGHUP');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export { SUPERVISOR_STATE_PATH };