@jsonstudio/rcc 0.89.1803 → 0.89.1959

package/dist/index.d.ts

@@ -20,6 +20,7 @@ declare class RouteCodexApp {
      * Stop the RouteCodex server
      */
     stop(): Promise<void>;
+    private prepareRuntimeExitForensics;
     /**
      * Get server status
      */

package/dist/index.js

@@ -13,10 +13,65 @@ import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
 import { buildInfo } from './build-info.js';
 import { isDirectExecution } from './utils/is-direct-execution.js';
-import { parseNetstatListeningPids } from './utils/windows-netstat.js';
 import { reportRouteError } from './error-handling/route-error-hub.js';
+import { flushProcessLifecycleLogQueue, logProcessLifecycle, logProcessLifecycleSync } from './utils/process-lifecycle-logger.js';
+import { getShutdownCallerContext } from './utils/shutdown-caller-context.js';
+import { listManagedServerPidsByPort } from './utils/managed-server-pids.js';
+import { inferUngracefulPreviousExit, resolveRuntimeLifecyclePath, safeMarkRuntimeExit, safeReadRuntimeLifecycle, safeWriteRuntimeLifecycle } from './utils/runtime-exit-forensics.js';
 import { resolveRouteCodexConfigPath } from './config/config-paths.js';
 import { loadRouteCodexConfig } from './config/routecodex-config-loader.js';
+let runtimeMinimalLogFilterInstalled = false;
+function resolveBoolFromEnv(value, fallback) {
+    if (!value) {
+        return fallback;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on') {
+        return true;
+    }
+    if (normalized === '0' || normalized === 'false' || normalized === 'no' || normalized === 'off') {
+        return false;
+    }
+    return fallback;
+}
+function isMinimalRuntimeLogEnabled() {
+    return resolveBoolFromEnv(process.env.ROUTECODEX_MINIMAL_RUNTIME_LOGS ?? process.env.RCC_MINIMAL_RUNTIME_LOGS, true);
+}
+function stringifyLogArg(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function shouldSuppressRuntimeLogLine(text) {
+    if (!text) {
+        return false;
+    }
+    return (text.includes('[servertool][') ||
+        text.includes('[virtual-router]'));
+}
+function installMinimalRuntimeLogFilter() {
+    if (runtimeMinimalLogFilterInstalled || !isMinimalRuntimeLogEnabled()) {
+        return;
+    }
+    runtimeMinimalLogFilterInstalled = true;
+    const originalLog = console.log.bind(console);
+    const originalInfo = console.info.bind(console);
+    const filter = (original) => (...args) => {
+        const line = args.map(stringifyLogArg).join(' ');
+        if (shouldSuppressRuntimeLogLine(line)) {
+            return;
+        }
+        original(...args);
+    };
+    console.log = filter(originalLog);
+    console.info = filter(originalInfo);
+}
 // Polyfill CommonJS require for ESM runtime to satisfy dependencies that call require()
 let moduleRequire = null;
 try {
@@ -73,7 +128,34 @@ async function reportCliError(code, message, error, severity = 'medium', details
 }
 let lastShutdownReason = { kind: 'unknown' };
 let restartInProgress = false;
+let currentRuntimeLifecyclePath = null;
+function setCurrentRuntimeLifecyclePath(value) {
+    currentRuntimeLifecyclePath = typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function createRuntimeRunId() {
+    try {
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+    }
+    catch {
+        // ignore
+    }
+    return `run_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`;
+}
 function recordShutdownReason(reason) {
+    if (reason.kind === 'signal' && reason.signal === 'SIGKILL') {
+        logProcessLifecycleSync({
+            event: 'self_termination',
+            source: 'index.recordShutdownReason',
+            details: {
+                reason: 'self_kill_signal',
+                signal: 'SIGKILL',
+                pid: process.pid,
+                caller: resolveSignalCaller('SIGKILL')
+            }
+        });
+    }
     if (lastShutdownReason.kind === 'unknown') {
         lastShutdownReason = reason;
     }
@@ -86,10 +168,27 @@ process.on('exit', (code) => {
     };
     if (reason.kind === 'signal') {
         payload.signal = reason.signal;
+        payload.caller = resolveSignalCaller(reason.signal);
     }
     else if (reason.kind === 'uncaughtException' || reason.kind === 'startupError' || reason.kind === 'stopError') {
         payload.message = reason.message;
     }
+    if (currentRuntimeLifecyclePath) {
+        safeMarkRuntimeExit(currentRuntimeLifecyclePath, {
+            kind: reason.kind,
+            code: typeof code === 'number' ? code : null,
+            ...(reason.kind === 'signal' ? { signal: reason.signal } : {}),
+            ...(reason.kind === 'uncaughtException' || reason.kind === 'startupError' || reason.kind === 'stopError'
+                ? { message: reason.message }
+                : {}),
+            recordedAt: new Date().toISOString()
+        });
+    }
+    logProcessLifecycleSync({
+        event: 'process_exit',
+        source: 'index.process.on.exit',
+        details: payload
+    });
     // Single-line JSON for easy grep in logs
     console.log('[routecodex:shutdown]', JSON.stringify(payload));
 });
@@ -132,6 +231,32 @@ function readRecordBoolean(record, key) {
     }
     return readBoolean(record[key]);
 }
+function resolveSignalCaller(signal) {
+    const fromShutdownRoute = getShutdownCallerContext({ maxAgeMs: 10 * 60 * 1000 });
+    if (fromShutdownRoute) {
+        return {
+            callerType: 'shutdown_route_context',
+            signal,
+            ...fromShutdownRoute
+        };
+    }
+    let parentCommand = '';
+    try {
+        const ps = spawnSync('ps', ['-o', 'command=', '-p', String(process.ppid)], { encoding: 'utf8' });
+        parentCommand = String(ps.stdout || '').trim().slice(0, 1024);
+    }
+    catch {
+        parentCommand = '';
+    }
+    return {
+        callerType: 'unknown_signal_sender',
+        signal,
+        observedTs: new Date().toISOString(),
+        processPid: process.pid,
+        processPpid: process.ppid,
+        parentCommand
+    };
+}
 if (!process.env.ROUTECODEX_VERSION) {
     let resolvedVersion = 'dev';
     try {
@@ -215,6 +340,7 @@ class RouteCodexApp {
      */
     async start() {
         try {
+            installMinimalRuntimeLogFilter();
             console.log('🚀 Starting RouteCodex server...');
             console.log(`📁 Modules configuration file: ${this.modulesConfigPath}`);
             // 简化日志已移除运行时自动应用，保留 CLI 配置能力
@@ -324,6 +450,7 @@ class RouteCodexApp {
                 }
                 return value;
             };
+            this.prepareRuntimeExitForensics(bindPort);
             process.env.ROUTECODEX_PORT = String(bindPort);
             process.env.RCC_PORT = String(bindPort);
             process.env.ROUTECODEX_HTTP_HOST = bindHost;
@@ -360,6 +487,14 @@ class RouteCodexApp {
             }
             // 6. 在服务已监听的前提下初始化运行时（包括 Hub Pipeline 和 Provider OAuth）
             await this.httpServer.initializeWithUserConfig(userConfig, { providerProfiles });
+            try {
+                const routeCodexHome = path.join(homedir(), '.routecodex');
+                fsSync.mkdirSync(routeCodexHome, { recursive: true });
+                fsSync.writeFileSync(path.join(routeCodexHome, `server-${bindPort}.pid`), String(process.pid), 'utf8');
+            }
+            catch {
+                // ignore pid file write failures
+            }
             this._isRunning = true;
             // 7. 记录当前运行模式（仅 V2）
             console.log(`${buildInfo.mode === 'dev' ? '🧪 dev' : '🚢 release'} mode · 🔵 V2 dynamic pipeline active`);
@@ -424,6 +559,47 @@ class RouteCodexApp {
             process.exit(1);
         }
     }
+    prepareRuntimeExitForensics(port) {
+        try {
+            const lifecyclePath = resolveRuntimeLifecyclePath(port);
+            const previous = safeReadRuntimeLifecycle(lifecyclePath);
+            const inference = inferUngracefulPreviousExit({
+                previous,
+                currentPid: process.pid
+            });
+            if (inference.shouldReport) {
+                logProcessLifecycle({
+                    event: 'previous_ungraceful_exit_detected',
+                    source: 'index.start',
+                    details: {
+                        port,
+                        markerPath: lifecyclePath,
+                        reason: inference.reason,
+                        previousPid: previous?.pid ?? null,
+                        previousRunId: previous?.runId ?? null,
+                        previousStartedAt: previous?.startedAt ?? null,
+                        inference: 'likely_external_kill_or_forced_termination'
+                    }
+                });
+                console.warn('[routecodex:forensics] detected previous ungraceful exit on port=' + String(port) +
+                    ' (pid=' + String(previous?.pid ?? 'unknown') + ', runId=' + String(previous?.runId ?? 'unknown') + ')');
+            }
+            const currentState = {
+                runId: createRuntimeRunId(),
+                pid: process.pid,
+                port,
+                startedAt: new Date().toISOString(),
+                buildVersion: buildInfo.version,
+                buildMode: buildInfo.mode
+            };
+            if (safeWriteRuntimeLifecycle(lifecyclePath, currentState)) {
+                setCurrentRuntimeLifecyclePath(lifecyclePath);
+            }
+        }
+        catch {
+            // forensics path is best-effort and must never block startup
+        }
+    }
     /**
      * Get server status
      */
@@ -587,11 +763,30 @@ async function ensurePortAvailable(port, opts = {}) {
             }
         }
     }
-    // Fall back to SIGTERM/SIGKILL processes listening on the port (avoid self-kill by probing first)
-    const pids = await listPidsOnPort(port);
+    // Fall back to SIGTERM/SIGKILL on managed RouteCodex pid files only.
+    const pids = listManagedServerPidsByPort(port).map(String);
     if (!pids.length) {
+        const occupied = !(await canBind(port));
+        if (occupied) {
+            logProcessLifecycle({
+                event: 'port_cleanup',
+                source: 'index.ensurePortAvailable',
+                details: { port, result: 'occupied_unmanaged' }
+            });
+            throw new Error(`Port ${port} is occupied by unmanaged process; refusing blind kill. Stop process manually or call /shutdown if it is RouteCodex.`);
+        }
+        logProcessLifecycle({
+            event: 'port_cleanup',
+            source: 'index.ensurePortAvailable',
+            details: { port, result: 'no_managed_pid' }
+        });
         return;
     }
+    logProcessLifecycle({
+        event: 'port_cleanup',
+        source: 'index.ensurePortAvailable',
+        details: { port, result: 'managed_pid_found', pids }
+    });
     for (const pid of pids) {
         killPidBestEffort(Number(pid), { force: false });
     }
@@ -601,7 +796,14 @@ async function ensurePortAvailable(port, opts = {}) {
             return;
         }
     }
-    const remain = await listPidsOnPort(port);
+    const remain = listManagedServerPidsByPort(port).map(String);
+    if (remain.length) {
+        logProcessLifecycle({
+            event: 'port_cleanup',
+            source: 'index.ensurePortAvailable',
+            details: { port, result: 'force_kill', pids: remain }
+        });
+    }
     for (const pid of remain) {
         killPidBestEffort(Number(pid), { force: true });
     }
@@ -611,24 +813,67 @@ function killPidBestEffort(pid, opts) {
     if (!Number.isFinite(pid) || pid <= 0) {
         return;
     }
+    if (pid === process.pid) {
+        logProcessLifecycle({
+            event: 'kill_attempt',
+            source: 'index.ensurePortAvailable',
+            details: {
+                targetPid: pid,
+                signal: 'SKIP_SELF',
+                result: 'skipped',
+                reason: 'self_kill_guard',
+                caller: resolveSignalCaller('SELF_GUARD')
+            }
+        });
+        return;
+    }
+    const signal = opts.force ? 'SIGKILL' : 'SIGTERM';
     if (process.platform === 'win32') {
         const args = ['/PID', String(pid), '/T'];
         if (opts.force) {
             args.push('/F');
         }
+        logProcessLifecycle({
+            event: 'kill_attempt',
+            source: 'index.ensurePortAvailable',
+            details: { targetPid: pid, signal: opts.force ? 'TASKKILL_F' : 'TASKKILL', result: 'attempt' }
+        });
         try {
             spawnSync('taskkill', args, { stdio: 'ignore', encoding: 'utf8' });
+            logProcessLifecycle({
+                event: 'kill_attempt',
+                source: 'index.ensurePortAvailable',
+                details: { targetPid: pid, signal: opts.force ? 'TASKKILL_F' : 'TASKKILL', result: 'success' }
+            });
         }
-        catch {
-            // best-effort
+        catch (error) {
+            logProcessLifecycle({
+                event: 'kill_attempt',
+                source: 'index.ensurePortAvailable',
+                details: { targetPid: pid, signal: opts.force ? 'TASKKILL_F' : 'TASKKILL', result: 'failed', error }
+            });
         }
         return;
     }
+    logProcessLifecycle({
+        event: 'kill_attempt',
+        source: 'index.ensurePortAvailable',
+        details: { targetPid: pid, signal, result: 'attempt' }
+    });
     try {
-        process.kill(pid, opts.force ? 'SIGKILL' : 'SIGTERM');
+        process.kill(pid, signal);
+        logProcessLifecycle({
+            event: 'kill_attempt',
+            source: 'index.ensurePortAvailable',
+            details: { targetPid: pid, signal, result: 'success' }
+        });
     }
-    catch {
-        // best-effort
+    catch (error) {
+        logProcessLifecycle({
+            event: 'kill_attempt',
+            source: 'index.ensurePortAvailable',
+            details: { targetPid: pid, signal, result: 'failed', error }
+        });
     }
 }
 async function canBind(port) {
@@ -645,32 +890,6 @@ async function canBind(port) {
         }
     });
 }
-async function listPidsOnPort(port) {
-    if (process.platform === 'win32') {
-        try {
-            const result = spawnSync('netstat', ['-ano', '-p', 'tcp'], { encoding: 'utf8' });
-            if (result.error) {
-                return [];
-            }
-            return parseNetstatListeningPids(result.stdout || '', port).map(String);
-        }
-        catch {
-            return [];
-        }
-    }
-    return await new Promise(resolve => {
-        try {
-            const ps = spawn('lsof', ['-ti', `:${port}`]);
-            let out = '';
-            ps.stdout.on('data', d => (out += String(d)));
-            ps.on('close', () => resolve(out.split(/\s+/).map(s => s.trim()).filter(Boolean)));
-            ps.on('error', () => resolve([]));
-        }
-        catch {
-            resolve([]);
-        }
-    });
-}
 async function attemptHttpShutdown(port) {
     try {
         const controller = new AbortController();
@@ -685,9 +904,20 @@ async function attemptHttpShutdown(port) {
             signal: controller.signal
         }).catch(() => null);
         clearTimeout(timeout);
-        return !!(res && res.ok);
+        const ok = !!(res && res.ok);
+        logProcessLifecycle({
+            event: 'http_shutdown_probe',
+            source: 'index.attemptHttpShutdown',
+            details: { port, result: ok ? 'ok' : 'not_ready', status: res?.status }
+        });
+        return ok;
     }
-    catch {
+    catch (error) {
+        logProcessLifecycle({
+            event: 'http_shutdown_probe',
+            source: 'index.attemptHttpShutdown',
+            details: { port, result: 'failed', error }
+        });
         return false;
     }
 }
@@ -706,13 +936,34 @@ async function gracefulShutdown(app) {
                     ? 'reason=stopError'
                     : 'reason=unknown';
     console.log(`\n🛑 Stopping RouteCodex server gracefully... (${reasonLabel})`);
+    logProcessLifecycle({
+        event: 'graceful_shutdown',
+        source: 'index.gracefulShutdown',
+        details: {
+            reason: reasonLabel,
+            result: 'start',
+            caller: reason.kind === 'signal' ? resolveSignalCaller(reason.signal) : getShutdownCallerContext({ maxAgeMs: 10 * 60 * 1000 })
+        }
+    });
     try {
         await app.stop();
+        logProcessLifecycle({
+            event: 'graceful_shutdown',
+            source: 'index.gracefulShutdown',
+            details: { reason: reasonLabel, result: 'success' }
+        });
+        await flushProcessLifecycleLogQueue();
         process.exit(0);
     }
     catch (error) {
         await reportCliError('GRACEFUL_SHUTDOWN_FAILED', 'Error during graceful shutdown', error, 'high');
         console.error('❌ Error during graceful shutdown:', error);
+        logProcessLifecycle({
+            event: 'graceful_shutdown',
+            source: 'index.gracefulShutdown',
+            details: { reason: reasonLabel, result: 'failed', error }
+        });
+        await flushProcessLifecycleLogQueue();
         process.exit(1);
     }
 }
@@ -762,6 +1013,11 @@ async function restartSelf(app, signal) {
     }
     restartInProgress = true;
     recordShutdownReason({ kind: 'signal', signal });
+    logProcessLifecycle({
+        event: 'restart_signal_received',
+        source: 'index.restartSelf',
+        details: { signal }
+    });
     console.log(`\n🔄 Restart signal received (${signal}). Restarting RouteCodex server process...`);
     const argv = process.argv.slice(1);
     const env = { ...process.env };
@@ -790,13 +1046,20 @@ async function restartSelf(app, signal) {
     }
     try {
         const child = spawn(process.execPath, argv, { stdio: 'inherit', env });
+        logProcessLifecycle({
+            event: 'restart_spawn_child',
+            source: 'index.restartSelf',
+            details: { signal, childPid: child.pid ?? null, argv }
+        });
         console.log(`[routecodex:restart] spawned pid=${child.pid ?? 'unknown'}`);
     }
     catch (error) {
         await reportCliError('SERVER_RESTART_SPAWN_FAILED', 'Failed to spawn restarted server', error, 'critical').catch(() => { });
         console.error('❌ Failed to spawn restarted server:', error);
+        await flushProcessLifecycleLogQueue();
         process.exit(1);
     }
+    await flushProcessLifecycleLogQueue();
     process.exit(0);
 }
 /**
@@ -807,10 +1070,20 @@ async function main() {
     const app = new RouteCodexApp(modulesConfigPath);
     // Setup signal handlers for graceful shutdown
     process.on('SIGTERM', () => {
+        logProcessLifecycleSync({
+            event: 'signal_received',
+            source: 'index.main',
+            details: { signal: 'SIGTERM', caller: resolveSignalCaller('SIGTERM') }
+        });
         recordShutdownReason({ kind: 'signal', signal: 'SIGTERM' });
         void gracefulShutdown(app);
     });
     process.on('SIGINT', () => {
+        logProcessLifecycleSync({
+            event: 'signal_received',
+            source: 'index.main',
+            details: { signal: 'SIGINT', caller: resolveSignalCaller('SIGINT') }
+        });
         recordShutdownReason({ kind: 'signal', signal: 'SIGINT' });
         void gracefulShutdown(app);
     });
@@ -819,15 +1092,30 @@ async function main() {
     // - The server respawns itself (same argv), then exits.
     if (process.platform !== 'win32') {
         process.on('SIGUSR2', () => {
+            logProcessLifecycle({
+                event: 'signal_received',
+                source: 'index.main',
+                details: { signal: 'SIGUSR2' }
+            });
             void restartSelf(app, 'SIGUSR2');
         });
         process.on('SIGHUP', () => {
+            logProcessLifecycle({
+                event: 'signal_received',
+                source: 'index.main',
+                details: { signal: 'SIGHUP' }
+            });
             void restartSelf(app, 'SIGHUP');
         });
     }
     // Handle uncaught exceptions
     process.on('uncaughtException', (error) => {
         const message = error instanceof Error ? error.message : String(error ?? '');
+        logProcessLifecycle({
+            event: 'uncaught_exception',
+            source: 'index.main',
+            details: { message, error }
+        });
         recordShutdownReason({ kind: 'uncaughtException', message });
         void reportCliError('UNCAUGHT_EXCEPTION', 'Uncaught Exception', error, 'critical');
         console.error('❌ Uncaught Exception:', error);