ec-web 0.0.1 → 0.0.3

package/README.md

@@ -1,5 +1,17 @@
-# ec-web
+# EC Web
 
-This package name is reserved for the EvolCore web console.
+Web console and monitoring dashboard for EvolCore.
 
-The complete web console will replace this placeholder in a future release.
+## Install
+
+```bash
+npm install -g ec-web
+```
+
+## Run
+
+```bash
+ec-web --home /path/to/runtime-home
+```
+
+Use `ec watch web` when EC Web is managed by the main daemon.

package/dist/debug-log.js

@@ -0,0 +1,7 @@
+let _writer = null;
+export function setDebugLog(writer) { _writer = writer; }
+export function dlog(line) { if (_writer)
+    try {
+        _writer(line);
+    }
+    catch { } }

package/dist/fs-utils.js

@@ -0,0 +1,189 @@
+/**
+ * 文件系统工具层（独立版）— 内联自 evolcore session-fs-store + watch-msg 数据层。
+ *
+ * 只包含 watch-web 实际用到的函数，无任何 npm 依赖。
+ */
+import fs from 'fs';
+import path from 'path';
+import { resolvePaths } from './paths.js';
+// ── 编解码（与 evolcore encodeSegment / decodeDirSegment 一致）──
+const UNSAFE_CHARS_RE = /[<>:"/\\|?*\x00-\x1F%]/g;
+export function encodeSegment(s) {
+    return s.replace(UNSAFE_CHARS_RE, ch => '%' + ch.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0'));
+}
+export function decodeDirSegment(seg) {
+    return seg.replace(/%([0-9A-Fa-f]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+/** 与 evolcore cross-platform.ts encodePath 一致（CC transcript 目录名） */
+export function encodePath(p) {
+    const isWindows = process.platform === 'win32';
+    const norm = isWindows ? p.replace(/\\/g, '/') : p;
+    return encodeURIComponent(norm).replace(/%2F/gi, '-').replace(/%3A/gi, '-').replace(/^-/, '');
+}
+export function scanChatDirs(sessionsDir) {
+    const results = [];
+    let channelTypes;
+    try {
+        channelTypes = fs.readdirSync(sessionsDir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const ct of channelTypes) {
+        if (!ct.isDirectory())
+            continue;
+        const channelType = ct.name;
+        const ctDir = path.join(sessionsDir, channelType);
+        let level2;
+        try {
+            level2 = fs.readdirSync(ctDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        if (channelType === 'aun') {
+            for (const selfEnc of level2) {
+                if (!selfEnc.isDirectory())
+                    continue;
+                const selfAID = decodeDirSegment(selfEnc.name);
+                const selfDir = path.join(ctDir, selfEnc.name);
+                let peers;
+                try {
+                    peers = fs.readdirSync(selfDir, { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                for (const peerEnc of peers) {
+                    if (!peerEnc.isDirectory() || peerEnc.name.startsWith('_'))
+                        continue;
+                    results.push({
+                        dirPath: path.join(selfDir, peerEnc.name),
+                        channelType,
+                        channelId: decodeDirSegment(peerEnc.name),
+                        selfAID,
+                    });
+                }
+            }
+        }
+        else {
+            for (const chanEnc of level2) {
+                if (!chanEnc.isDirectory())
+                    continue;
+                results.push({
+                    dirPath: path.join(ctDir, chanEnc.name),
+                    channelType,
+                    channelId: decodeDirSegment(chanEnc.name),
+                    selfAID: '',
+                });
+            }
+        }
+    }
+    return results;
+}
+export function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readAllJsonlLines(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8')
+            .split('\n')
+            .filter(Boolean)
+            .map(l => { try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        } })
+            .filter((x) => x !== null);
+    }
+    catch {
+        return [];
+    }
+}
+export function isTransientProtocolMessage(entry) {
+    if (!entry)
+        return false;
+    const transient = (value) => {
+        const type = value?.trim().toLowerCase();
+        if (!type)
+            return false;
+        return [
+            'status', 'event', 'events', 'task.status', 'activity', 'thought',
+            'handoff_state', 'handoff_result',
+        ].includes(type)
+            || ['menu.', 'status.', 'event.', 'events.', 'task.status.', 'activity.']
+                .some(prefix => type.startsWith(prefix));
+    };
+    return transient(entry.payloadType) || transient(entry.msgType);
+}
+export function getSessionsAunDir() {
+    return path.join(resolvePaths().sessionsDir, 'aun');
+}
+export function listLocalAids(aunDir) {
+    try {
+        return fs.readdirSync(aunDir, { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .map(e => decodeDirSegment(e.name));
+    }
+    catch {
+        return [];
+    }
+}
+export function listPeers(aunDir, localAid) {
+    const aidDir = path.join(aunDir, encodeSegment(localAid));
+    try {
+        return fs.readdirSync(aidDir, { withFileTypes: true })
+            .filter(e => e.isDirectory() && !e.name.startsWith('_'))
+            .map(e => decodeDirSegment(e.name));
+    }
+    catch {
+        return [];
+    }
+}
+export function readMessages(aunDir, localAid, peerId) {
+    return readAllJsonlLines(path.join(aunDir, encodeSegment(localAid), encodeSegment(peerId), 'messages.jsonl')).filter(m => !isTransientProtocolMessage(m));
+}
+function readPeerName(aunDir, localAid, peerId) {
+    return readJsonFile(path.join(aunDir, encodeSegment(localAid), encodeSegment(peerId), 'active.json'))?.metadata?.peerName ?? null;
+}
+export function loadAidInfo(aunDir, aid) {
+    const peers = listPeers(aunDir, aid);
+    let totalIn = 0, totalOut = 0;
+    for (const peer of peers) {
+        for (const m of readMessages(aunDir, aid, peer)) {
+            if (m.dir === 'in')
+                totalIn++;
+            else
+                totalOut++;
+        }
+    }
+    return { aid, totalIn, totalOut, peerCount: peers.length };
+}
+export function loadPeerInfos(aunDir, localAid) {
+    return listPeers(aunDir, localAid).map(peerId => {
+        const msgs = readMessages(aunDir, localAid, peerId);
+        let inbound = 0, outbound = 0, lastAt = 0;
+        for (const m of msgs) {
+            if (m.dir === 'in')
+                inbound++;
+            else
+                outbound++;
+            if (m.ts > lastAt)
+                lastAt = m.ts;
+        }
+        return { peerId, peerName: readPeerName(aunDir, localAid, peerId), inbound, outbound, lastAt };
+    }).sort((a, b) => b.lastAt - a.lastAt);
+}
+export function loadAllMessages(aunDir, localAid) {
+    const all = [];
+    for (const peer of listPeers(aunDir, localAid))
+        all.push(...readMessages(aunDir, localAid, peer));
+    all.sort((a, b) => a.ts - b.ts);
+    return all.length > 1000 ? all.slice(-1000) : all;
+}

package/dist/index.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * ec-web — EvolCore 监控面板独立程序。
+ *
+ * 用法:
+ *   ec-web [--port 42705] [--home <EVOLCORE_HOME>]
+ *
+ * 通过 EVOLCORE_HOME 定位 evolcore 数据目录，启动 HTTP+WS 服务，浏览器配对码登录。
+ * 与 evolcore daemon 通过 IPC socket（live 状态）+ 文件系统（历史数据）旁路通信。
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+// ── 解析参数 ──
+const argv = process.argv.slice(2);
+let port;
+let home;
+for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--port' || a === '-p')
+        port = Number(argv[++i]);
+    else if (a === '--home' || a === '-h')
+        home = argv[++i];
+    else if (a === '--help') {
+        process.stdout.write(`ec-web — EvolCore 监控面板\n\n用法:\n  ec-web [--port 42705] [--home <EVOLCORE_HOME>]\n\n选项:\n  --port, -p   监听端口（默认 42705，占用则自动 +1）\n  --home       当前运行时数据目录（现阶段默认读 EVOLCORE_HOME 或 ~/.evolcore）\n`);
+        process.exit(0);
+    }
+}
+// --home 优先级最高：写入环境变量，paths.ts 读取
+if (home)
+    process.env.EVOLCORE_HOME = path.resolve(home);
+// 延迟到环境变量设置后再导入（paths.ts 缓存 root）
+const { resolvePaths } = await import('./paths.js');
+const { startWatchWebServer } = await import('./server.js');
+const p = resolvePaths();
+// 校验 home 目录存在
+if (!fs.existsSync(p.root)) {
+    process.stderr.write(`❌ EVOLCORE_HOME 不存在: ${p.root}\n   用 --home 指定正确路径，或设置 EVOLCORE_HOME 环境变量。\n`);
+    process.exit(1);
+}
+const useColor = !!process.stdout.isTTY;
+const RST = useColor ? '\x1b[0m' : '';
+const DIM = useColor ? '\x1b[2m' : '';
+const BOLD = useColor ? '\x1b[1m' : '';
+const CYAN = useColor ? '\x1b[36m' : '';
+const GREEN = useColor ? '\x1b[32m' : '';
+const YELLOW = useColor ? '\x1b[33m' : '';
+const logLine = (line) => {
+    const t = new Date();
+    const ts = `${String(t.getHours()).padStart(2, '0')}:${String(t.getMinutes()).padStart(2, '0')}:${String(t.getSeconds()).padStart(2, '0')}`;
+    process.stdout.write(`${DIM}${ts}${RST} ${line}\n`);
+};
+// 调试日志文件
+const logFile = path.join(p.logs, 'watch-web.log');
+try {
+    fs.mkdirSync(p.logs, { recursive: true });
+    fs.writeFileSync(logFile, `# ecweb debug log\n# started ${new Date().toISOString()} pid=${process.pid}\n`);
+}
+catch { }
+const fileLog = (line) => {
+    const t = new Date();
+    const ts = `${String(t.getHours()).padStart(2, '0')}:${String(t.getMinutes()).padStart(2, '0')}:${String(t.getSeconds()).padStart(2, '0')}.${String(t.getMilliseconds()).padStart(3, '0')}`;
+    try {
+        fs.appendFileSync(logFile, `${ts} ${line.replace(/\x1b\[[0-9;]*m/g, '')}\n`);
+    }
+    catch { }
+};
+const log = (line) => { logLine(line); fileLog(line); };
+// 单实例保护：
+// 1) 按 instance 文件杀掉登记在册的旧 ecweb 进程
+const { writeEcweb, removeEcweb, cleanupEcwebs, cleanupEcwebByPort } = await import('./process-utils.js');
+const killedWebs = cleanupEcwebs();
+for (const r of killedWebs)
+    logLine(`${YELLOW}↺ 已清理旧 ecweb 进程 PID ${r.pid}（端口 ${r.port}）${RST}`);
+// 2) 兜底：按端口杀掉 instance 文件已丢失的孤儿进程（杀不掉的僵尸）
+const WATCH_WEB_PORT = port ?? 42705;
+const killedByPort = cleanupEcwebByPort(WATCH_WEB_PORT);
+for (const pid of killedByPort)
+    logLine(`${YELLOW}↺ 已强占端口 ${WATCH_WEB_PORT}：杀掉占用进程 PID ${pid}${RST}`);
+if (killedWebs.length > 0 || killedByPort.length > 0) {
+    // 给 OS 释放端口的时间
+    await new Promise(r => setTimeout(r, 400));
+}
+let handle;
+try {
+    handle = await startWatchWebServer({ port, log });
+}
+catch (e) {
+    process.stderr.write(`❌ 启动失败: ${e?.message || e}\n`);
+    process.exit(1);
+}
+// 注册 instance 文件
+writeEcweb(handle.port);
+// 列出访问地址
+const ifaces = os.networkInterfaces();
+const lanIps = [];
+for (const list of Object.values(ifaces)) {
+    for (const ni of list || []) {
+        if (ni.family === 'IPv4' && !ni.internal)
+            lanIps.push(ni.address);
+    }
+}
+process.stdout.write(`\n${BOLD}${CYAN}EC Web — EvolCore${RST}  ${DIM}(home: ${p.root})${RST}\n\n`);
+process.stdout.write(`  ${BOLD}配对码:${RST}  ${GREEN}${BOLD}${handle.pairingCode}${RST}  ${DIM}(5 分钟内有效，配对后 token 缓存 30 天，有访问自动续期)${RST}\n\n`);
+process.stdout.write(`  ${BOLD}本机:${RST}    http://localhost:${handle.port}\n`);
+for (const ip of lanIps)
+    process.stdout.write(`  ${BOLD}局域网:${RST}  http://${ip}:${handle.port}\n`);
+if (handle.displaced) {
+    process.stdout.write(`\n  ${YELLOW}⚠ 端口 ${WATCH_WEB_PORT} 被非 watch 进程占用，已切换到 ${handle.port}${RST}\n`);
+}
+process.stdout.write(`\n  ${DIM}绑定 0.0.0.0，远程可访问。Ctrl-C 退出。${RST}\n`);
+process.stdout.write(`  ${DIM}调试日志: ${logFile}${RST}\n\n`);
+let cleaningUp = false;
+const cleanup = () => {
+    if (cleaningUp)
+        return; // 幂等：raw 模式下连按 Ctrl-C/q 不应重复触发
+    cleaningUp = true;
+    logLine(`${YELLOW}退出中…${RST}`);
+    removeEcweb();
+    // 兜底：close() 万一卡住也强制退出，避免进程挂死
+    const force = setTimeout(() => process.exit(0), 2000);
+    force.unref();
+    handle.close().finally(() => process.exit(0));
+};
+process.on('exit', () => removeEcweb());
+process.on('SIGINT', cleanup);
+process.on('SIGTERM', cleanup);
+if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('data', (key) => {
+        // Ctrl-C (0x03) 或 q 退出
+        if (key[0] === 0x03 || key.toString() === 'q') {
+            cleanup();
+        }
+    });
+}

package/dist/ipc-client.js

@@ -0,0 +1,40 @@
+/**
+ * evolcore IPC client（独立版）— 通过 Unix socket / 命名管道查询运行中的 daemon。
+ *
+ * 协议：newline-delimited JSON，一问一答即断。
+ * 与 evolcore src/ipc.ts 的 ipcQuery 一致；连不上返回 null（daemon 未运行）。
+ *
+ * watch 用到的只读查询：aun-aids / aun-aid-stats / status / evolagent.list / ping
+ */
+import net from 'net';
+export function ipcQuery(socketPath, cmd, timeoutMs = 3000) {
+    return new Promise((resolve) => {
+        const conn = net.connect(socketPath);
+        let buf = '';
+        const timer = setTimeout(() => {
+            conn.destroy();
+            resolve(null);
+        }, timeoutMs);
+        conn.on('connect', () => {
+            conn.write(JSON.stringify(cmd) + '\n');
+        });
+        conn.on('data', (data) => {
+            buf += data.toString();
+            const idx = buf.indexOf('\n');
+            if (idx !== -1) {
+                clearTimeout(timer);
+                try {
+                    resolve(JSON.parse(buf.slice(0, idx)));
+                }
+                catch {
+                    resolve(null);
+                }
+                conn.destroy();
+            }
+        });
+        conn.on('error', () => {
+            clearTimeout(timer);
+            resolve(null);
+        });
+    });
+}

package/dist/paths.js

@@ -0,0 +1,55 @@
+/**
+ * evolcore 路径解析（独立版）。
+ *
+ * watch 进程只需要 EVOLCORE_HOME 根目录，所有地址从它派生。
+ * 逻辑与 evolcore src/paths.ts 对齐，但不依赖 evolcore 代码。
+ *
+ * 根目录解析优先级：
+ *   1. --home 命令行参数（由 index.ts 写入 process.env.EVOLCORE_HOME）
+ *   2. EVOLCORE_HOME 环境变量
+ *   3. cwd/agents/defaults.json 存在 → cwd（开发模式）
+ *   4. ~/.evolcore
+ */
+import path from 'path';
+import os from 'os';
+import fs from 'fs';
+import crypto from 'crypto';
+const isWindows = process.platform === 'win32';
+let _root = null;
+export function resolveRoot() {
+    if (_root)
+        return _root;
+    if (process.env.EVOLCORE_HOME) {
+        _root = process.env.EVOLCORE_HOME;
+    }
+    else if (fs.existsSync(path.join(process.cwd(), 'agents', 'defaults.json'))) {
+        _root = process.cwd();
+    }
+    else {
+        _root = path.join(os.homedir(), '.evolcore');
+    }
+    return _root;
+}
+/** socket 路径派生：与 evolcore resolveInstanceSocketPath 完全一致 */
+function resolveInstanceSocketPath(root) {
+    if (isWindows) {
+        const hash = crypto.createHash('sha1').update(root).digest('hex').slice(0, 12);
+        return `\\\\.\\pipe\\daemon-${hash}`;
+    }
+    return path.join(root, 'data', 'instance', 'daemon.sock');
+}
+export function resolvePaths() {
+    const root = resolveRoot();
+    return {
+        root,
+        sessionsDir: path.join(root, 'data', 'sessions'),
+        instanceDir: path.join(root, 'data', 'instance'),
+        dataDir: path.join(root, 'data'),
+        logs: path.join(root, 'logs'),
+        socket: resolveInstanceSocketPath(root),
+    };
+}
+/** CC（Claude Code / Agent SDK）transcript 根目录 */
+export function ccProjectsDir() {
+    return path.join(os.homedir(), '.claude', 'projects');
+}

package/dist/process-utils.js

@@ -0,0 +1,241 @@
+/**
+ * 进程工具（独立版）— 内联自 evolcore cross-platform + process-introspect + instance-registry。
+ *
+ * 只包含 ecweb 单实例保护实际用到的函数，无任何 evolcore 代码依赖。
+ * 关键不变量：杀进程前用启动时间比对防 PID 复用，按端口兜底时只杀确认是 ecweb 的进程。
+ */
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { resolvePaths } from './paths.js';
+const isWindows = process.platform === 'win32';
+const isMacOS = process.platform === 'darwin';
+/** 启动时间容差：2 秒（覆盖 macOS 秒级精度 + 时钟漂移） */
+const START_TIME_TOLERANCE_MS = 2000;
+// ── 进程存活 / 终止 ──
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+function killPid(pid) {
+    if (isWindows) {
+        try {
+            spawnSync('taskkill', ['/PID', String(pid), '/F'], { windowsHide: true });
+        }
+        catch { }
+    }
+    else {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { }
+    }
+}
+// ── 启动时间（PID 复用检测）──
+export function getProcessStartTime(pid) {
+    try {
+        if (isWindows)
+            return getStartTimeWindows(pid);
+        if (isMacOS)
+            return getStartTimeMacOS(pid);
+        return getStartTimeLinux(pid);
+    }
+    catch {
+        return null;
+    }
+}
+function startTimeMatches(recorded, actual) {
+    if (actual === null)
+        return false;
+    return Math.abs(recorded - actual) < START_TIME_TOLERANCE_MS;
+}
+function getStartTimeLinux(pid) {
+    let stat;
+    try {
+        stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const tail = stat.slice(stat.lastIndexOf(')') + 2);
+    const starttimeJiffies = parseInt(tail.split(' ')[19], 10);
+    if (isNaN(starttimeJiffies))
+        return null;
+    let uptimeSec;
+    try {
+        uptimeSec = parseFloat(fs.readFileSync('/proc/uptime', 'utf-8').split(' ')[0]);
+    }
+    catch {
+        return null;
+    }
+    const clkTck = 100; // 几乎所有 Linux 为 100
+    const bootMs = Date.now() - uptimeSec * 1000;
+    return Math.round(bootMs + (starttimeJiffies / clkTck) * 1000);
+}
+function getStartTimeMacOS(pid) {
+    const r = spawnSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf-8', timeout: 3000 });
+    const out = (r.stdout || '').trim();
+    if (!out)
+        return null;
+    const ms = Date.parse(out);
+    return isNaN(ms) ? null : ms;
+}
+function getStartTimeWindows(pid) {
+    const r = spawnSync('wmic', ['process', 'where', `ProcessId=${pid}`, 'get', 'CreationDate', '/value'], { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    const m = (r.stdout || '').match(/CreationDate=(\d{14})/);
+    if (!m)
+        return null;
+    const s = m[1]; // yyyymmddHHMMSS
+    const ms = Date.parse(`${s.slice(0, 4)}-${s.slice(4, 6)}-${s.slice(6, 8)}T${s.slice(8, 10)}:${s.slice(10, 12)}:${s.slice(12, 14)}`);
+    return isNaN(ms) ? null : ms;
+}
+// ── 端口 → PID ──
+export function findPidByPort(port) {
+    const pids = new Set();
+    try {
+        if (isWindows) {
+            const result = spawnSync('netstat', ['-ano', '-p', 'TCP'], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+            for (const line of (result.stdout || '').split('\n')) {
+                if (!/LISTENING/i.test(line))
+                    continue;
+                const m = line.match(/[:\]](\d+)\s+\S+\s+LISTENING\s+(\d+)/i);
+                if (m && parseInt(m[1], 10) === port) {
+                    const pid = parseInt(m[2], 10);
+                    if (!isNaN(pid) && pid !== process.pid)
+                        pids.add(pid);
+                }
+            }
+        }
+        else {
+            const out = spawnSync('lsof', ['-ti', `tcp:${port}`, '-sTCP:LISTEN'], { encoding: 'utf-8' }).stdout || '';
+            for (const l of out.split('\n')) {
+                const pid = parseInt(l.trim(), 10);
+                if (!isNaN(pid) && pid !== process.pid)
+                    pids.add(pid);
+            }
+        }
+    }
+    catch { }
+    return [...pids];
+}
+function readCmdline(pid) {
+    if (isWindows) {
+        try {
+            const result = spawnSync('wmic', ['process', 'where', `ProcessId=${pid}`, 'get', 'CommandLine', '/value'], { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+            const m = (result.stdout || '').match(/CommandLine=([^\r\n]+)/);
+            return m ? m[1].trim() : '';
+        }
+        catch {
+            return '';
+        }
+    }
+    try {
+        return fs.readFileSync(`/proc/${pid}/cmdline`, 'utf-8').replace(/\0/g, ' ').trim();
+    }
+    catch {
+        try {
+            const r = spawnSync('ps', ['-p', String(pid), '-o', 'args='], { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] });
+            return r.stdout?.trim() || '';
+        }
+        catch {
+            return '';
+        }
+    }
+}
+// ── instance 文件读写 ──
+function instanceDir() {
+    return resolvePaths().instanceDir;
+}
+function isEcwebInstanceFile(file) {
+    return /^(ecweb|watch-web)-\d+\.json$/.test(file);
+}
+function ecwebFile(pid) {
+    return path.join(instanceDir(), `ecweb-${pid}.json`);
+}
+export function writeEcweb(port) {
+    const dir = instanceDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const startedAt = getProcessStartTime(process.pid) ?? Date.now();
+    const record = { pid: process.pid, startedAt, startedAtIso: new Date(startedAt).toISOString(), port };
+    const filePath = ecwebFile(process.pid);
+    const tmp = filePath + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(record, null, 2));
+    fs.renameSync(tmp, filePath);
+    return filePath;
+}
+export function removeEcweb(pid) {
+    const target = pid ?? process.pid;
+    const dir = instanceDir();
+    for (const prefix of ['ecweb', 'watch-web']) {
+        try {
+            fs.unlinkSync(path.join(dir, `${prefix}-${target}.json`));
+        }
+        catch { }
+    }
+}
+function safeParseJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 杀掉所有非自己 PID 的存活 ecweb 进程并清理文件。
+ * 兼容清理迁移前遗留的 watch-web-*.json。
+ * 用启动时间比对防 PID 复用。返回被杀的记录列表。
+ */
+export function cleanupEcwebs() {
+    const dir = instanceDir();
+    if (!fs.existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const killed = [];
+    for (const file of files) {
+        if (!isEcwebInstanceFile(file))
+            continue;
+        const filePath = path.join(dir, file);
+        const record = safeParseJson(filePath);
+        if (record?.pid && record.pid !== process.pid) {
+            if (isProcessRunning(record.pid) && startTimeMatches(record.startedAt, getProcessStartTime(record.pid))) {
+                killPid(record.pid);
+                killed.push(record);
+            }
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { }
+        }
+    }
+    return killed;
+}
+/**
+ * 兜底：按端口找占用进程，确认是 ecweb 进程后 SIGKILL。
+ * 用于清理 instance 文件已丢失的孤儿进程（杀不掉的僵尸）。返回被杀的 PID 列表。
+ */
+export function cleanupEcwebByPort(port) {
+    const killed = [];
+    for (const pid of findPidByPort(port)) {
+        if (pid === process.pid || !isProcessRunning(pid))
+            continue;
+        const cmdline = readCmdline(pid);
+        // 只杀确认是 ecweb 的进程，避免误杀别人占的端口
+        if (/ecweb|dist[\\/]index\.js/i.test(cmdline)) {
+            killPid(pid);
+            killed.push(pid);
+        }
+    }
+    return killed;
+}