specrails-desktop 2.0.0

package/server/dist/index.js

@@ -0,0 +1,586 @@
+"use strict";
+// Note: the pkg-binary native-addon hijacks (better_sqlite3.node, node-pty, pty.node)
+// used to live here but had to move to an esbuild `banner.js` in scripts/build-sidecar.mjs
+// so they run BEFORE esbuild's top-of-bundle `require('node-pty')` statement.
+// See the banner in that script for the actual patches.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const http_1 = __importDefault(require("http"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const express_1 = __importDefault(require("express"));
+const ws_1 = require("ws");
+const project_registry_1 = require("./project-registry");
+const desktop_router_1 = require("./desktop-router");
+const project_router_1 = require("./project-router");
+const docs_router_1 = require("./docs-router");
+const auth_1 = require("./auth");
+const ws_routing_1 = require("./ws-routing");
+const terminal_manager_1 = require("./terminal-manager");
+const terminal_shell_integration_1 = require("./terminal-shell-integration");
+const feature_flags_1 = require("./feature-flags");
+const mobile_1 = require("./mobile");
+const telemetry_receiver_1 = require("./telemetry-receiver");
+const telemetry_compactor_1 = require("./telemetry-compactor");
+const path_resolver_1 = require("./path-resolver");
+// Side-effect import: registers every bundled ProviderAdapter (claude, codex,
+// future providers) so `getAdapter`/`hasAdapter`/`listAdapters` are populated
+// before any manager constructs a project context. See
+// openspec/changes/add-multi-provider-support/specs/multi-provider-architecture/spec.md.
+require("./providers");
+const inheritedPathBeforeResolve = (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean).length;
+(0, path_resolver_1.resolveStartupPath)();
+const TERMINAL_PANEL_ENABLED = process.env.SPECRAILS_TERMINAL_PANEL !== 'false';
+const BROWSER_CAPTURE_ENABLED = (0, feature_flags_1.isBrowserCaptureEnabled)();
+// Read package.json version once at startup
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const PKG_VERSION = (() => {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('../package.json').version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+// ─── Desktop app watchdog ─────────────────────────────────────────────────────
+// When running as a Tauri sidecar, the parent Tauri process passes its PID via
+// --parent-pid=<pid>. We poll every 3 seconds and exit if the parent is gone,
+// preventing orphaned server processes after an app crash.
+const parentPidArg = process.argv.find((a) => a.startsWith('--parent-pid='));
+if (parentPidArg) {
+    const parentPid = parseInt(parentPidArg.split('=')[1], 10);
+    if (!isNaN(parentPid)) {
+        // Poll at 1s (not 3s): on a self-update relaunch the Tauri host exits and the
+        // freshly-launched instance needs port 4200 freed fast. The old 3s latency
+        // raced the new instance's startup port check and produced "port already in
+        // use". Faster detection + a graceful exit shrinks that window.
+        const watchdog = setInterval(() => {
+            try {
+                // signal 0 = existence check only, does not actually send a signal
+                process.kill(parentPid, 0);
+            }
+            catch {
+                // Parent process is gone — shut down GRACEFULLY (tree-kill child rails,
+                // PTYs, remove the PID file, release the port) instead of a bare
+                // process.exit(0) that orphans children and leaks the PID file.
+                clearInterval(watchdog);
+                void shutdown();
+            }
+        }, 1000);
+    }
+}
+// ─── Parse CLI args ───────────────────────────────────────────────────────────
+let port = 4200;
+for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i] === '--port' && process.argv[i + 1]) {
+        port = parseInt(process.argv[++i], 10);
+    }
+}
+// ─── PID file management ──────────────────────────────────────────────────────
+const PID_DIR = path_1.default.join(os_1.default.homedir(), '.specrails');
+const PID_FILE = path_1.default.join(PID_DIR, 'manager.pid');
+function writePidFile() {
+    try {
+        fs_1.default.mkdirSync(PID_DIR, { recursive: true });
+        fs_1.default.writeFileSync(PID_FILE, String(process.pid), 'utf-8');
+    }
+    catch {
+        // Non-fatal
+    }
+}
+function removePidFile() {
+    try {
+        fs_1.default.unlinkSync(PID_FILE);
+    }
+    catch {
+        // Non-fatal
+    }
+}
+// ─── Express + WebSocket setup ────────────────────────────────────────────────
+const app = (0, express_1.default)();
+// Host-header validation (H-08) — first barrier, anti DNS-rebinding.
+// Implementation in auth.ts (unit-tested there); index.ts is coverage-excluded.
+app.use(auth_1.hostValidationMiddleware);
+// ─── CORS — allow only localhost origins (CRIT-02) ────────────────────────────
+// Tauri's desktop WebView exposes two different origin formats:
+//   - macOS / Linux: tauri://localhost
+//   - Windows WebView2: http://tauri.localhost (virtual-host mapping on the
+//     custom scheme; shows up as a regular http origin from the fetch layer)
+const ALLOWED_ORIGIN_PATTERN = /^(https?:\/\/(localhost|127\.0\.0\.1|tauri\.localhost)(:\d+)?|tauri:\/\/localhost)$/;
+function isAllowedBrowserOrigin(origin) {
+    return origin === undefined || ALLOWED_ORIGIN_PATTERN.test(origin);
+}
+function corsMiddleware(req, res, next) {
+    const origin = req.headers['origin'];
+    if (origin) {
+        if (ALLOWED_ORIGIN_PATTERN.test(origin)) {
+            res.setHeader('Access-Control-Allow-Origin', origin);
+            res.setHeader('Vary', 'Origin');
+        }
+        else {
+            // Non-localhost origin — reject with 403
+            res.status(403).json({ error: 'Forbidden: cross-origin requests not allowed' });
+            return;
+        }
+    }
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Desktop-Token');
+    res.setHeader('Access-Control-Max-Age', '600');
+    if (req.method === 'OPTIONS') {
+        res.sendStatus(204);
+        return;
+    }
+    next();
+}
+app.use(corsMiddleware);
+// ─── Body size limit (MED-02) ─────────────────────────────────────────────────
+app.use(express_1.default.json({ limit: '1mb' }));
+const server = http_1.default.createServer(app);
+const wsServerOptions = {
+    noServer: true,
+    // Cap inbound frame size (H-10). Shared by the main, terminal and browser WS
+    // servers. Terminal/browser input frames (keystrokes, control JSON, pastes)
+    // are tiny; 1 MB tolerates a large bracketed paste while bounding the memory
+    // a single malicious frame can force the sidecar to buffer.
+    maxPayload: 1024 * 1024,
+    handleProtocols: (protocols) => {
+        if (protocols.has('specrails-desktop'))
+            return 'specrails-desktop';
+        // Backward compatibility for clients that only offer the auth carrier.
+        for (const protocol of protocols) {
+            if (protocol.startsWith('desktop-token.'))
+                return protocol;
+        }
+        return false;
+    },
+};
+const wss = new ws_1.WebSocketServer(wsServerOptions);
+const terminalWss = new ws_1.WebSocketServer(wsServerOptions);
+const browserWss = new ws_1.WebSocketServer(wsServerOptions);
+const clients = new Map();
+// 8 MB: a healthy client drains far faster than we produce; crossing this means
+// the socket is stalled. Dropping an event is safe — clients reconcile via the
+// REST polling paths — and far better than an unbounded memory leak.
+const WS_BACKPRESSURE_LIMIT_BYTES = 8 * 1024 * 1024;
+const TERMINAL_WS_RE = /^\/ws\/terminal\/([0-9a-f-]+)$/i;
+const BROWSER_WS_RE = /^\/ws\/browser\/([0-9a-f-]+)$/i;
+function rejectUpgrade(socket, status, reason) {
+    socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\n\r\n`);
+    socket.destroy();
+}
+function authorizeUpgrade(request) {
+    const origin = request.headers.origin;
+    if (!isAllowedBrowserOrigin(origin))
+        return 'forbidden';
+    const provided = (0, auth_1.tokenFromUpgradeRequest)(request);
+    if (!provided || !(0, auth_1.safeEqual)(provided, (0, auth_1.loadOrGenerateToken)()))
+        return 'unauthorized';
+    return 'ok';
+}
+function broadcast(msg) {
+    const data = JSON.stringify(msg);
+    // Project-scoped messages carry a projectId; app-level messages do not.
+    const msgProjectId = msg.projectId;
+    for (const [client, state] of clients) {
+        if (client.readyState !== ws_1.WebSocket.OPEN)
+            continue;
+        // H-09: route project-scoped messages only to matching/undeclared subscribers.
+        if (!(0, ws_routing_1.shouldDeliverToSubscriber)(msgProjectId, state.subscribedProjectId))
+            continue;
+        // H-10: drop for a back-pressured client instead of growing its buffer.
+        if (client.bufferedAmount > WS_BACKPRESSURE_LIMIT_BYTES)
+            continue;
+        client.send(data);
+    }
+    // Fan a copy to the Mobile Gateway's in-process bus (no-op when no phone is
+    // attached). publish() swallows mobile-side errors so the main loop is safe.
+    (0, mobile_1.getMobileEventBus)().publish(msg);
+}
+// ─── Health endpoint state (populated by the Super-mode bootstrap below) ─────
+let _getProjectCount = () => 0;
+/** Captured by the Super-mode bootstrap block so graceful shutdown can tear down every
+ *  project's spawners (rail/chat children) instead of orphaning them. */
+let _registry = null;
+/** The mobile companion gateway (off by default); torn down on shutdown. */
+let _mobileGateway = null;
+server.on('upgrade', (request, socket, head) => {
+    const urlStr = request.url ?? '/';
+    const auth = authorizeUpgrade(request);
+    if (auth === 'forbidden')
+        return rejectUpgrade(socket, 403, 'Forbidden');
+    if (auth === 'unauthorized')
+        return rejectUpgrade(socket, 401, 'Unauthorized');
+    // Terminal PTY WebSocket endpoint: /ws/terminal/:id?projectId=...
+    const pathOnly = urlStr.split('?')[0];
+    const termMatch = pathOnly.match(TERMINAL_WS_RE);
+    if (termMatch) {
+        if (!TERMINAL_PANEL_ENABLED)
+            return rejectUpgrade(socket, 404, 'Not Found');
+        let parsed;
+        try {
+            parsed = new URL(urlStr, 'http://localhost');
+        }
+        catch {
+            return rejectUpgrade(socket, 400, 'Bad Request');
+        }
+        const projectId = parsed.searchParams.get('projectId');
+        const sessionId = termMatch[1];
+        const tm = (0, terminal_manager_1.getTerminalManager)();
+        const session = tm.getUnsafe(sessionId);
+        if (!session) {
+            // The session may have died right after POST /terminals returned (e.g. a
+            // shell that failed to acquire a controlling tty). If we have a tombstone,
+            // upgrade just long enough to tell the client WHY, then close — otherwise
+            // the client sees a bare 404 and a silent dead terminal.
+            if (projectId) {
+                const tomb = tm.getTombstone(sessionId, projectId);
+                if (tomb) {
+                    terminalWss.handleUpgrade(request, socket, head, (ws) => {
+                        try {
+                            ws.send(JSON.stringify({ type: 'exit', code: tomb.code, signal: tomb.signal, early: tomb.early }));
+                        }
+                        catch { /* ignore */ }
+                        try {
+                            ws.close(1000, tomb.early ? 'pty_exit_early' : 'pty_exit');
+                        }
+                        catch { /* ignore */ }
+                    });
+                    return;
+                }
+            }
+            return rejectUpgrade(socket, 404, 'Not Found');
+        }
+        if (!projectId || session.projectId !== projectId)
+            return rejectUpgrade(socket, 403, 'Forbidden');
+        terminalWss.handleUpgrade(request, socket, head, (ws) => {
+            const meta = tm.attach(sessionId, ws);
+            if (!meta) {
+                // Lost the race: the pty exited between the getUnsafe check and attach.
+                const tomb = tm.getTombstone(sessionId, projectId);
+                if (tomb) {
+                    try {
+                        ws.send(JSON.stringify({ type: 'exit', code: tomb.code, signal: tomb.signal, early: tomb.early }));
+                    }
+                    catch { /* ignore */ }
+                }
+                try {
+                    ws.close(1000, tomb?.early ? 'pty_exit_early' : 'pty_exit');
+                }
+                catch { /* ignore */ }
+                return;
+            }
+            ws.on('message', (data, isBinary) => {
+                if (isBinary) {
+                    tm.write(sessionId, data);
+                    return;
+                }
+                try {
+                    const txt = data.toString('utf8');
+                    const msg = JSON.parse(txt);
+                    if (msg?.type === 'resize' && typeof msg.cols === 'number' && typeof msg.rows === 'number') {
+                        tm.resize(sessionId, msg.cols, msg.rows);
+                    }
+                    else if (msg?.type === 'write' && typeof msg.data === 'string') {
+                        tm.write(sessionId, msg.data);
+                    }
+                }
+                catch { /* ignore malformed control */ }
+            });
+            ws.on('close', () => tm.detach(sessionId, ws));
+            ws.on('error', () => tm.detach(sessionId, ws));
+        });
+        return;
+    }
+    // Embedded-browser screencast WebSocket: /ws/browser/:id?projectId=...
+    // Frames stream server→client as binary; client→server are JSON control
+    // messages (input/navigate). Kept off the shared /ws so high-rate screencast
+    // throughput can't starve the project event stream (mirrors the terminal WS).
+    const browserMatch = pathOnly.match(BROWSER_WS_RE);
+    if (browserMatch) {
+        if (!BROWSER_CAPTURE_ENABLED)
+            return rejectUpgrade(socket, 404, 'Not Found');
+        let parsed;
+        try {
+            parsed = new URL(urlStr, 'http://localhost');
+        }
+        catch {
+            return rejectUpgrade(socket, 400, 'Bad Request');
+        }
+        const projectId = parsed.searchParams.get('projectId');
+        const sessionId = browserMatch[1];
+        if (!projectId)
+            return rejectUpgrade(socket, 400, 'Bad Request');
+        const mgr = _registry?.getContext(projectId)?.browserCaptureManager;
+        const session = mgr?.getSession(sessionId);
+        if (!mgr || !session)
+            return rejectUpgrade(socket, 404, 'Not Found');
+        browserWss.handleUpgrade(request, socket, head, (ws) => {
+            const client = ws;
+            void mgr.attach(sessionId, client).then((meta) => {
+                if (!meta) {
+                    // Session died between the upgrade check and attach — tell the client
+                    // explicitly instead of leaving a silent, frame-less socket open.
+                    try {
+                        ws.close(1000, 'session_closed');
+                    }
+                    catch { /* ignore */ }
+                }
+            });
+            ws.on('message', (data, isBinary) => {
+                if (isBinary)
+                    return; // browser inbound is JSON control only
+                try {
+                    const msg = JSON.parse(data.toString('utf8'));
+                    if (msg.type === 'input' && msg.event) {
+                        void mgr.handleInput(sessionId, msg.event);
+                    }
+                    else if (msg.type === 'navigate') {
+                        void mgr.navigate(sessionId, msg.action ?? 'goto', msg.url);
+                    }
+                    else if (msg.type === 'probe' && Number.isFinite(msg.x) && Number.isFinite(msg.y) && msg.x >= 0 && msg.y >= 0) {
+                        // Hover-to-select: resolve the element under the cursor and reply with
+                        // its rect so the client can draw a highlight box.
+                        void mgr.probeElement(sessionId, { x: msg.x, y: msg.y }).then((probe) => {
+                            try {
+                                ws.send(JSON.stringify({ type: 'hover', rect: probe?.rect ?? null, selector: probe?.selector ?? null, path: probe?.path ?? null }));
+                            }
+                            catch { /* drop */ }
+                        });
+                    }
+                }
+                catch { /* ignore malformed control */ }
+            });
+            ws.on('close', () => mgr.detach(sessionId, client));
+            ws.on('error', () => mgr.detach(sessionId, client));
+        });
+        return;
+    }
+    // Default: main event WebSocket.
+    wss.handleUpgrade(request, socket, head, (ws) => {
+        wss.emit('connection', ws, request);
+    });
+});
+// ─── Docs portal (available in all modes) ────────────────────────────────────
+// Loopback-only (H-04): docs are unauthenticated by design (no token needed to
+// read them), so a loopback guard is the only thing standing between them and
+// the network the day the bind changes.
+app.use('/api/docs', auth_1.requireLoopback, (0, docs_router_1.createDocsRouter)());
+// ─── Auth — protect all /api/* except /api/health and /api/token ─────────────
+// (CRIT-01) Token is served publicly so the local client can bootstrap itself.
+app.get('/api/health', (_req, res) => {
+    res.json({
+        status: 'ok',
+        version: PKG_VERSION,
+        uptime: Math.floor(process.uptime()),
+        projects: _getProjectCount(),
+        mode: 'super',
+    });
+});
+// Loopback-only (H-03): this is the most sensitive endpoint — it hands out the
+// master token, which grants terminals/spawn/fs/admin. It must stay public (no
+// token) so the local client can bootstrap. Two complementary guards protect it:
+// `requireLoopback` rejects a non-local PEER (matters if the bind ever changes
+// from 127.0.0.1), and the Host-header guard above rejects DNS-rebinding (where
+// the peer IS loopback — the victim's own browser — but the Host is the
+// attacker's domain). Neither alone is sufficient; together they close both.
+app.get('/api/token', auth_1.requireLoopback, (_req, res) => {
+    res.json({ token: (0, auth_1.loadOrGenerateToken)() });
+});
+app.use('/api', auth_1.requireAuth);
+// ─── WebSocket rate limiting helper (LOW-03) ──────────────────────────────────
+const WS_MAX_MESSAGES_PER_MINUTE = 120;
+const WS_MAX_MESSAGE_BYTES = 65_536; // 64 KB
+function applyWsRateLimiting(ws) {
+    let messageCount = 0;
+    const resetTimer = setInterval(() => { messageCount = 0; }, 60_000);
+    ws.on('message', (data) => {
+        const size = typeof data === 'string' ? Buffer.byteLength(data) : data.byteLength;
+        if (size > WS_MAX_MESSAGE_BYTES) {
+            ws.close(1009, 'Message too large');
+            return;
+        }
+        messageCount++;
+        if (messageCount > WS_MAX_MESSAGES_PER_MINUTE) {
+            ws.close(1008, 'Rate limit exceeded');
+        }
+    });
+    ws.on('close', () => {
+        clearInterval(resetTimer);
+    });
+}
+// ─── Super-mode bootstrap ─────────────────────────────────────────────────────
+{
+    const registry = new project_registry_1.ProjectRegistry(broadcast, undefined, port);
+    registry.loadAll();
+    _registry = registry;
+    _getProjectCount = () => registry.listContexts().length;
+    // OTLP/JSON receiver — INTENTIONALLY UNAUTHENTICATED (H-01/H-02). The spawned
+    // claude/codex CLIs post telemetry here with no auth header (queue-manager sets
+    // OTEL_EXPORTER_OTLP_ENDPOINT but no OTEL_EXPORTER_OTLP_HEADERS), so it cannot
+    // be put behind requireAuth. It is also NOT covered by `app.use('/api', ...)`
+    // — that middleware is path-scoped to /api, and /otlp is a sibling path (the
+    // old comment here claiming otherwise was wrong). It is protected instead by
+    // `requireLoopback` (children always connect via 127.0.0.1) + the loopback bind.
+    app.use('/otlp', auth_1.requireLoopback, (0, telemetry_receiver_1.createTelemetryRouter)(registry));
+    // Run telemetry compaction at startup after registry is hydrated
+    (0, telemetry_compactor_1.runCompactionForAll)(registry).catch((err) => {
+        console.error('[telemetry-compactor] startup compaction error:', err);
+    });
+    // ─── Mobile companion gateway (off by default; boot if previously enabled) ──
+    // Second HTTPS+WSS listener in THIS process; the main server stays loopback.
+    // The control plane is desktop-only: loopback + (via /api below) requireAuth.
+    // Mounted before the /api desktop router so its sub-path is unambiguous.
+    const mobileGateway = new mobile_1.MobileGateway({ desktopDb: registry.desktopDb, desktopPort: port, broadcast });
+    _mobileGateway = mobileGateway;
+    app.use('/api/mobile', auth_1.requireLoopback, (0, mobile_1.createMobileAdminRouter)({
+        gateway: mobileGateway,
+        desktopDb: registry.desktopDb,
+        broadcast,
+    }));
+    if (mobileGateway.isEnabledSetting()) {
+        mobileGateway.start().catch((err) => console.error('[mobile-gateway] boot start failed:', err));
+    }
+    // App-level routes. CRITICAL mount order: the desktop router is mounted at
+    // '/api' BEFORE the project router below so its exact routes (e.g.
+    // GET /api/projects, DELETE /api/projects/:id) are handled here, while
+    // everything else under /api/projects/:projectId/* falls through to the
+    // project router.
+    app.use('/api', (0, desktop_router_1.createDesktopRouter)(registry, broadcast));
+    // Per-project routes under /api/projects/:projectId/*
+    app.use('/api/projects', (0, project_router_1.createProjectRouter)(registry));
+    // Return 410 Gone for the old per-project hook endpoint in Super mode
+    app.post('/hooks/events', (_req, res) => {
+        res.status(410).json({
+            error: 'In Super mode, use /api/projects/:projectId/hooks/events',
+        });
+    });
+    wss.on('connection', (ws) => {
+        const state = { subscribedProjectId: null };
+        clients.set(ws, state);
+        applyWsRateLimiting(ws);
+        // H-09: honor an optional `{ type: 'subscribe', projectId }` control frame so
+        // a connection can scope itself to one project's events. Anything else on the
+        // inbound channel is ignored (the main event WS is otherwise server→client).
+        ws.on('message', (data) => {
+            const txt = typeof data === 'string' ? data : data.toString('utf8');
+            const frame = (0, ws_routing_1.parseSubscribeFrame)(txt);
+            if (frame.subscribe)
+                state.subscribedProjectId = frame.projectId;
+        });
+        // Send app state init
+        const projects = registry.listContexts().map((ctx) => ctx.project);
+        ws.send(JSON.stringify({
+            type: 'desktop.projects',
+            projects,
+            timestamp: new Date().toISOString(),
+        }));
+        ws.on('close', () => {
+            clients.delete(ws);
+        });
+    });
+}
+// ─── Global async error handler ────────────────────────────────────────────────
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+app.use((err, _req, res, _next) => {
+    console.error('[unhandled error]', err);
+    if (!res.headersSent) {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+// ─── Serve built React client (production) ────────────────────────────────────
+const clientDist = path_1.default.resolve(__dirname, '../../client/dist');
+if (fs_1.default.existsSync(clientDist)) {
+    app.use(express_1.default.static(clientDist));
+    app.get(/^(?!\/api|\/hooks).*/, (_req, res) => {
+        res.sendFile(path_1.default.join(clientDist, 'index.html'));
+    });
+}
+// ─── Start server ─────────────────────────────────────────────────────────────
+server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+        console.error(`[error] Port ${port} is already in use. Is another manager instance running?`);
+        console.error(`[error] Try stopping it first: specrails-desktop stop`);
+        process.exit(1);
+    }
+    throw err;
+});
+server.listen(port, '127.0.0.1', () => {
+    console.log(`specrails web manager running on http://127.0.0.1:${port}`);
+    writePidFile();
+    // Sweep stale shell-integration shim directories left behind by previous runs.
+    try {
+        const removed = (0, terminal_shell_integration_1.cleanupStaleShimDirs)();
+        if (removed > 0)
+            console.log(`[terminal-shell-integration] cleaned ${removed} stale shim dirs`);
+    }
+    catch { /* best effort */ }
+    void (0, path_resolver_1.augmentPathFromLoginShell)().then(() => {
+        const diag = (0, path_resolver_1.getPathDiagnostic)();
+        const augmented = diag.pathSegments.length - inheritedPathBeforeResolve;
+        const source = process.stdin.isTTY ? 'terminal' : 'gui';
+        console.log(`[path-resolver] inherited=${inheritedPathBeforeResolve} augmented=${Math.max(0, augmented)} loginShell=${diag.loginShellStatus} source=${source}`);
+    });
+});
+// ─── Clean shutdown ───────────────────────────────────────────────────────────
+let shuttingDown = false;
+async function shutdown() {
+    // Idempotent: the watchdog, SIGTERM and SIGINT can all race into here.
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    removePidFile();
+    try {
+        _registry?.shutdown();
+    }
+    catch { /* ignore */ }
+    try {
+        await (0, terminal_manager_1.getTerminalManager)().shutdown();
+    }
+    catch { /* ignore */ }
+    try {
+        await _mobileGateway?.stop();
+    }
+    catch { /* ignore */ }
+    try {
+        wss.close();
+    }
+    catch { /* ignore */ }
+    try {
+        terminalWss.close();
+    }
+    catch { /* ignore */ }
+    try {
+        browserWss.close();
+    }
+    catch { /* ignore */ }
+    // Force-close lingering keep-alive / WebSocket sockets so server.close()'s
+    // callback actually fires. The persistent /ws client connection and terminal
+    // sockets would otherwise hold the server open, stalling the port release that
+    // a relaunching desktop instance is waiting on. (Node 18.2+.)
+    try {
+        ;
+        server.closeAllConnections?.();
+    }
+    catch { /* ignore */ }
+    // Hard-exit fallback in case server.close() still hangs.
+    const forceExit = setTimeout(() => process.exit(0), 3000);
+    forceExit.unref?.();
+    server.close(() => {
+        clearTimeout(forceExit);
+        process.exit(0);
+    });
+}
+process.on('SIGTERM', () => { void shutdown(); });
+process.on('SIGINT', () => { void shutdown(); });
+// Last-resort PID-file cleanup for paths that bypass shutdown() (hard crash,
+// uncaught exception). 'exit' handlers must be synchronous.
+process.on('exit', () => {
+    try {
+        fs_1.default.unlinkSync(PID_FILE);
+    }
+    catch { /* best effort */ }
+});