@xingjisoft/neutrino 0.3.0 → 0.4.1

package/dist/app.js

@@ -4,18 +4,20 @@ import { InputReader } from "./terminal/input.js";
 import { Renderer } from "./terminal/renderer.js";
 import { installCrashGuard, writeCrashLog } from "./terminal/restore.js";
 import { defaultState } from "./state.js";
-import { loadConfig, saveConfig } from "./config.js";
+import { findConfiguredModel, intensityForModel, loadConfig, saveConfig } from "./config.js";
 import { C } from "./colors.js";
 import { applySelection, orderLinePoints, rowCells, rowSelectionText, selectionText, } from "./selection.js";
 import { offsetFromThumbTop, scrollbarGeometry } from "./ui.js";
 import { copyToClipboard } from "./clipboard.js";
+import { openInBrowser, proModeUrl } from "./browser.js";
 import { ChatScreen } from "./screens/chat.js";
 import { HistoryScreen } from "./screens/history.js";
 import { AgentSelectScreen } from "./screens/agentSelect.js";
 import { ModelSelectScreen } from "./screens/modelSelect.js";
 import { SettingsScreen } from "./screens/settings.js";
 import { StartScreen } from "./screens/start.js";
-import { startWebServer } from "./web/server.js";
+import { configureBackgroundService, readBackgroundStatus, isProcessAlive, runningBackground, startBackgroundService, stopBackgroundService, } from "./background.js";
+import { startTerminalBridge } from "./web/terminalBridge.js";
 const CURSOR_BLINK_MS = 530;
 const TOAST_MS = 1600;
 const INTERRUPT_WINDOW_MS = 1500;
@@ -89,9 +91,17 @@ export class App {
     // its own (streamed output, a resize) can still carry the anchor along.
     selOffset = null;
     resizeHandler = () => this.onResize();
-    webHandle = null;
+    webService = null;
+    webStarting = null;
+    terminalBridge = null;
+    backgroundChanges = Promise.resolve();
+    webTray = true;
     /** Where the web UI lives; kept even while it is switched off. */
     webOptions = { port: 8765, auth: true };
+    /** Offer the background-residency prompt when this process mounts the UI. */
+    webPromptBackground = true;
+    /** True while a click is bringing the Web console up, so double clicks are safe. */
+    proOpening = false;
     constructor() {
         this.width = process.stdout.columns || 80;
         this.height = process.stdout.rows || 24;
@@ -116,30 +126,159 @@ export class App {
         const config = loadConfig();
         this.state.selectedProvider = String(config.selected_provider ?? this.state.selectedProvider);
         this.state.selectedModelName = String(config.selected_model ?? this.state.selectedModelName);
-        this.state.selectedIntensity = String(config.selected_intensity ?? this.state.selectedIntensity);
         this.state.selectedModelUrl = String(config.selected_model_url ?? this.state.selectedModelUrl);
         this.state.selectedModelApiKey = String(config.selected_model_api_key ?? this.state.selectedModelApiKey);
         this.state.selectedModelStreaming = Boolean(config.selected_model_streaming ?? true);
+        // The saved intensity can predate a model's `intensity` limits (or the
+        // selected model itself can have been hand-edited since); start from a
+        // level this exact model accepts.
+        const model = findConfiguredModel(this.state.selectedProvider, this.state.selectedModelName);
+        this.state.selectedIntensity = intensityForModel(model, config.selected_intensity ?? config.default_intensity ?? this.state.selectedIntensity, config.default_intensity);
     }
     /**
      * Remember where the browser UI should listen. Called at startup even when
      * the console is disabled, so Settings can mount it later without guessing.
+     * `backgroundPrompt` is false when the console is meant to run detached.
      */
-    configureWeb(port, host, auth) {
+    configureWeb(port, host, auth, backgroundPrompt = true, tray = true) {
         this.webOptions = { port, host, auth };
+        this.webPromptBackground = backgroundPrompt;
+        this.webTray = tray;
+    }
+    /**
+     * Adopt a Web console that another process owns. No socket is opened here:
+     * the terminal only records the address, so Settings and the Pro button can
+     * reach it later.
+     */
+    attachBackground(status) {
+        this.webService = status;
+        this.webOptions = { port: status.port, host: status.host, auth: status.auth_required };
+        this.state.webUrl = status.url;
+        this.state.webBackground = status.resident;
     }
     /**
      * Mount the browser UI on the given port. Safe to call once; subsequent calls
      * return the already-running server.
      */
     async enableWeb(port, host, auth = true) {
-        if (this.webHandle)
-            return this.webHandle;
+        if (this.webService)
+            return this.webService;
+        if (this.webStarting)
+            return this.webStarting;
         this.webOptions = { port, host, auth };
-        const handle = await startWebServer({ port, host, auth });
-        this.webHandle = handle;
-        this.state.webUrl = handle.url;
-        return handle;
+        this.webStarting = (async () => {
+            const bridge = await startTerminalBridge();
+            let started = null;
+            try {
+                const result = await startBackgroundService({
+                    port, host, auth, tray: this.webTray, resident: loadConfig().background === true,
+                    ownerPid: process.pid, prompt: this.webPromptBackground,
+                });
+                if (!result.ok)
+                    throw new Error(result.error);
+                if (result.started)
+                    started = result.status;
+                if (result.status.lifetime_supported === false) {
+                    // Keep an older resident service reachable while its current tasks
+                    // finish; it cannot accept live lifetime changes until restarted.
+                    bridge.close();
+                    this.attachBackground(result.status);
+                    return result.status;
+                }
+                const status = await configureBackgroundService(result.status, {
+                    ownerPid: process.pid, bridge: { url: bridge.url, token: bridge.token },
+                });
+                this.terminalBridge = bridge;
+                this.attachBackground(status);
+                return status;
+            }
+            catch (error) {
+                bridge.close();
+                if (started) {
+                    const current = readBackgroundStatus();
+                    if (current && current.owner_pids.every(owner => owner === process.pid)) {
+                        await stopBackgroundService(started);
+                    }
+                }
+                throw error;
+            }
+        })();
+        try {
+            return await this.webStarting;
+        }
+        finally {
+            this.webStarting = null;
+        }
+    }
+    /**
+     * The address the console is reachable at right now: the local socket, the
+     * detached service, or nothing.
+     */
+    currentWebUrl() {
+        return this.webService ? this.state.webUrl : null;
+    }
+    syncWebStatus() {
+        if (!this.webService)
+            return false;
+        const status = readBackgroundStatus();
+        if (!status && isProcessAlive(this.webService.pid))
+            return false;
+        if (!status || status.pid !== this.webService.pid || !isProcessAlive(status.pid)) {
+            this.terminalBridge?.close();
+            this.terminalBridge = null;
+            this.webService = null;
+            this.state.webUrl = null;
+            this.state.webBackground = false;
+            return true;
+        }
+        const changed = this.state.webUrl !== status.url || this.state.webBackground !== status.resident;
+        this.attachBackground(status);
+        return changed;
+    }
+    /**
+     * Start the Web console when it is not up yet. Returns the URL to open.
+     */
+    async ensureWebConsole() {
+        this.syncWebStatus();
+        const existing = this.currentWebUrl();
+        if (existing)
+            return existing;
+        const status = await this.enableWeb(this.webOptions.port, this.webOptions.host, this.webOptions.auth);
+        return status.url;
+    }
+    /** Change the existing worker's lifetime without moving its conversations. */
+    setBackgroundResidency(enabled) {
+        const task = this.backgroundChanges.then(async () => {
+            try {
+                this.syncWebStatus();
+                const existing = this.webService ? null : runningBackground();
+                if (existing)
+                    await this.enableWeb(existing.port, existing.host, existing.auth_required);
+                if (!enabled && !this.webService) {
+                    saveConfig({ ...loadConfig(), background: false });
+                }
+                else {
+                    await this.ensureWebConsole();
+                    if (this.webService?.lifetime_supported === false) {
+                        throw new Error("Restart the console to update background residency.");
+                    }
+                    const status = await configureBackgroundService(this.webService, { resident: enabled, ownerPid: process.pid });
+                    this.attachBackground(status);
+                }
+                this.showToast(enabled
+                    ? "Background residency on: browser tasks keep running after this terminal closes"
+                    : "Background residency off: the console follows this terminal");
+                this.render();
+                return { ok: true };
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                this.showToast(`Background residency failed: ${error}`, "top");
+                return { ok: false, error };
+            }
+        });
+        this.backgroundChanges = task.then(() => undefined, () => undefined);
+        return task;
     }
     /**
      * Start or stop the browser UI while the terminal keeps running. Returns a
@@ -148,28 +287,59 @@ export class App {
      */
     async setWebConsole(enabled) {
         if (enabled) {
-            if (this.webHandle)
-                return { ok: true };
             try {
-                await this.enableWeb(this.webOptions.port, this.webOptions.host, this.webOptions.auth);
-                this.showToast(`Web console: ${this.state.webUrl}`);
+                const url = await this.ensureWebConsole();
+                this.showToast(`Web console: ${url}`);
                 return { ok: true };
             }
             catch (err) {
                 const error = err instanceof Error ? err.message : String(err);
-                this.state.webUrl = null;
                 this.showToast(`Web console failed: ${error}`, "top");
                 return { ok: false, error };
             }
         }
-        const handle = this.webHandle;
-        this.webHandle = null;
+        if (this.webStarting)
+            await this.webStarting.catch(() => { });
+        if (this.webService) {
+            const stopped = await stopBackgroundService(this.webService);
+            if (!stopped.ok) {
+                this.showToast(`Web console could not be stopped: ${stopped.error}`, "top");
+                return { ok: false, error: stopped.error };
+            }
+        }
+        this.terminalBridge?.close();
+        this.terminalBridge = null;
+        this.webService = null;
         this.state.webUrl = null;
+        this.state.webBackground = false;
         this.render();
-        await handle?.close();
         this.showToast("Web console stopped");
         return { ok: true };
     }
+    /**
+     * Open the browser console's Pro workspace, bringing the console up first
+     * when it is not running yet. This runs from a mouse handler, so it never
+     * throws and never waits on the browser: failures become a toast and the TUI
+     * keeps rendering.
+     */
+    async openProMode() {
+        if (this.proOpening)
+            return;
+        this.proOpening = true;
+        try {
+            const url = await this.ensureWebConsole();
+            const target = proModeUrl(url);
+            openInBrowser(target);
+            this.showToast(`Opening Pro mode: ${target}`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.showToast(`Pro mode failed: ${message}`, "top");
+        }
+        finally {
+            this.proOpening = false;
+        }
+    }
     async start() {
         // Installed before anything touches the terminal: from here on, a crash
         // restores mouse tracking, raw mode and the alternate screen instead of
@@ -181,7 +351,8 @@ export class App {
         process.on("SIGINT", () => this.handleInterrupt());
         process.on("SIGTERM", () => this.quit());
         this.sizeTimer = setInterval(() => {
-            if (this.syncSize())
+            const webChanged = this.syncWebStatus();
+            if (this.syncSize() || webChanged)
                 this.render();
         }, 200);
         this.repaintTimer = setInterval(() => this.renderer.repaint(), REPAINT_MS);
@@ -763,16 +934,17 @@ export class App {
         this.render();
     }
     setModelConfig(providerName, model, intensity) {
+        const config = loadConfig();
+        const level = intensityForModel(model, intensity, config.default_intensity);
         this.state.selectedProvider = providerName;
         this.state.selectedModelName = model.name;
         this.state.selectedModelUrl = model.url;
         this.state.selectedModelApiKey = model.api_key ?? "";
         this.state.selectedModelStreaming = model.supports_streaming ?? true;
-        this.state.selectedIntensity = intensity;
-        const config = loadConfig();
+        this.state.selectedIntensity = level;
         config.selected_provider = providerName;
         config.selected_model = model.name;
-        config.selected_intensity = intensity;
+        config.selected_intensity = level;
         config.selected_model_url = model.url;
         config.selected_model_api_key = model.api_key ?? "";
         config.selected_model_streaming = model.supports_streaming ?? true;
@@ -798,8 +970,9 @@ export class App {
             this.state.selectedProvider = data.provider;
         if (data.model)
             this.state.selectedModelName = data.model;
-        if (data.intensity)
-            this.state.selectedIntensity = data.intensity;
+        if (data.intensity) {
+            this.state.selectedIntensity = intensityForModel(findConfiguredModel(this.state.selectedProvider, this.state.selectedModelName), data.intensity, loadConfig().default_intensity);
+        }
         this.pushScreen(screen);
     }
     openModelConfig() {
@@ -859,7 +1032,7 @@ export class App {
         catch {
             // Terminal restoration has already run, even if stdin is unusable.
         }
-        void this.webHandle?.close();
+        this.terminalBridge?.close();
         process.exit(exitCode);
     }
 }

package/dist/background.js

@@ -0,0 +1,358 @@
+/**
+ * Background residency.
+ *
+ * A background Neutrino is the ordinary Web console running in a detached
+ * process, with no terminal attached. Conversations started from the browser
+ * are owned by that process. With residency off, it follows the terminals that
+ * opened it; with residency on, it survives them. Changing that lifetime never
+ * moves or restarts a conversation. Terminal conversations stay local.
+ *
+ * The service is discovered through a small status file under `~/.neutrino`
+ * (`background.json`). It carries the process id, the address it bound and a
+ * random management token; the token protects the stop/ping endpoints from
+ * other local processes. The file is short-lived and removed on every clean
+ * shutdown, so a stale file is detected by checking the pid.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { NEUTRINO_DIR } from "./config.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const BACKGROUND_STATUS_FILE = path.join(NEUTRINO_DIR, "background.json");
+export const BACKGROUND_LOG_FILE = path.join(NEUTRINO_DIR, "background.log");
+const START_TIMEOUT_MS = 12_000;
+const STOP_TIMEOUT_MS = 5_000;
+const LOG_LIMIT_BYTES = 256 * 1024;
+function ensureDir() {
+    fs.mkdirSync(NEUTRINO_DIR, { recursive: true });
+}
+/** True for a positive, ordinary process id. */
+function isPid(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+/** Validate a status file (or an HTTP response) before trusting it. */
+export function parseBackgroundStatus(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const data = value;
+    if (!isPid(data.pid))
+        return null;
+    if (typeof data.port !== "number" || !Number.isSafeInteger(data.port) || data.port < 1 || data.port > 65535)
+        return null;
+    if (typeof data.host !== "string" || data.host.trim() === "")
+        return null;
+    if (typeof data.url !== "string" || !/^https?:\/\//i.test(data.url))
+        return null;
+    if (data.auth_required !== undefined && typeof data.auth_required !== "boolean")
+        return null;
+    if (typeof data.token !== "string" || data.token.length < 16)
+        return null;
+    if (typeof data.started_at !== "string" || data.started_at === "")
+        return null;
+    if (data.resident !== undefined && typeof data.resident !== "boolean")
+        return null;
+    if (data.owner_pids !== undefined && (!Array.isArray(data.owner_pids) || !data.owner_pids.every(isPid)))
+        return null;
+    return {
+        pid: data.pid,
+        port: data.port,
+        host: data.host,
+        url: data.url.replace(/\/+$/, ""),
+        // A status written by an older build predates the flag; the console asked
+        // for a password then, which is still the safe reading.
+        auth_required: data.auth_required !== false,
+        token: data.token,
+        started_at: data.started_at,
+        // Older services were always resident and had no terminal owners.
+        resident: data.resident !== false,
+        owner_pids: Array.isArray(data.owner_pids) ? data.owner_pids : [],
+        lifetime_supported: typeof data.resident === "boolean" && Array.isArray(data.owner_pids),
+    };
+}
+/** The saved status, including a stale file from a process that no longer runs. */
+export function readBackgroundStatus() {
+    try {
+        return parseBackgroundStatus(JSON.parse(fs.readFileSync(BACKGROUND_STATUS_FILE, "utf-8")));
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `pid` is a live process. Permission errors still mean "alive". */
+export function isProcessAlive(pid) {
+    if (!isPid(pid))
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** The running background service, or null when there is none. */
+export function runningBackground() {
+    const status = readBackgroundStatus();
+    if (!status)
+        return null;
+    if (isProcessAlive(status.pid))
+        return status;
+    clearBackgroundStatus(status.pid);
+    return null;
+}
+/** Write the status file atomically so another process never reads half of it. */
+export function writeBackgroundStatus(status) {
+    ensureDir();
+    const temp = `${BACKGROUND_STATUS_FILE}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify(status, null, 2), { encoding: "utf-8", mode: 0o600 });
+    fs.renameSync(temp, BACKGROUND_STATUS_FILE);
+}
+/**
+ * Remove the status file. With `pid`, only remove it when it still belongs to
+ * that process, so one service can never delete another's registration.
+ */
+export function clearBackgroundStatus(pid) {
+    try {
+        if (pid !== undefined) {
+            const current = readBackgroundStatus();
+            if (current && current.pid !== pid)
+                return;
+        }
+        fs.rmSync(BACKGROUND_STATUS_FILE, { force: true });
+    }
+    catch {
+        // A status file we cannot remove is retried by the next liveness check.
+    }
+}
+/** Append a diagnostic line, rotating the file instead of letting it grow. */
+export function backgroundLog(message) {
+    try {
+        ensureDir();
+        const line = `[${new Date().toISOString()}] ${message}\n`;
+        try {
+            if (fs.statSync(BACKGROUND_LOG_FILE).size > LOG_LIMIT_BYTES) {
+                fs.writeFileSync(BACKGROUND_LOG_FILE, line, "utf-8");
+                return;
+            }
+        }
+        catch {
+            // No log yet.
+        }
+        fs.appendFileSync(BACKGROUND_LOG_FILE, line, "utf-8");
+    }
+    catch {
+        // Diagnostics must never break the service.
+    }
+}
+/** The last few log lines, for a failed start message. */
+export function backgroundLogTail(lines = 6) {
+    try {
+        return fs.readFileSync(BACKGROUND_LOG_FILE, "utf-8").trimEnd().split(/\r?\n/).slice(-lines).join("\n");
+    }
+    catch {
+        return "";
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Can a client connect to the listening socket yet? */
+function canConnect(port, host) {
+    return new Promise((resolve) => {
+        const target = host === "0.0.0.0" || host === "" ? "127.0.0.1"
+            : host === "::" || host === "[::]" ? "::1"
+                : host;
+        const socket = net.connect({ port, host: target });
+        let settled = false;
+        const done = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(500);
+        socket.once("connect", () => done(true));
+        socket.once("timeout", () => done(false));
+        socket.once("error", () => done(false));
+    });
+}
+/** The CLI entry point, used by the detached child. */
+function cliEntry() {
+    // Always the built CLI next to this module. `process.argv[1]` belongs to the
+    // caller (a test, the terminal UI, a wrapper) and must not be re-executed.
+    const bundled = path.join(__dirname, "bin.js");
+    if (fs.existsSync(bundled))
+        return bundled;
+    const entry = process.argv[1];
+    if (entry && fs.existsSync(entry))
+        return path.resolve(entry);
+    return bundled;
+}
+/**
+ * Start the detached console, or reuse the one already running.
+ *
+ * The child writes the same status file we poll here, so "the address is
+ * reachable" and "the file names this exact process" both have to hold before
+ * the start counts as successful. The random token in the env is what proves
+ * the file was written by *our* child rather than an older instance.
+ */
+export async function startBackgroundService(options) {
+    const existing = runningBackground();
+    if (existing) {
+        if (existing.auth_required !== options.auth) {
+            return { ok: false, error: "the running Web console uses a different password setting" };
+        }
+        if (options.host && existing.host !== options.host) {
+            return { ok: false, error: `the running Web console is bound to ${existing.host}, not ${options.host}` };
+        }
+        if (options.strictPort && options.port !== null && existing.port !== options.port) {
+            return { ok: false, error: `the running Web console uses port ${existing.port}, not ${options.port}` };
+        }
+        // An older detached service is already resident. Reuse it without trying
+        // to register an owner through an endpoint that does not exist yet.
+        if (existing.lifetime_supported === false)
+            return { ok: true, status: existing, started: false };
+        const update = {};
+        if (options.ownerPid && !existing.owner_pids.includes(options.ownerPid))
+            update.ownerPid = options.ownerPid;
+        if (options.resident !== false && !existing.resident)
+            update.resident = true;
+        try {
+            const status = Object.keys(update).length ? await configureBackgroundService(existing, update) : existing;
+            return { ok: true, status, started: false };
+        }
+        catch (error) {
+            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    if (options.resident === false && (!options.ownerPid || !isProcessAlive(options.ownerPid))) {
+        return { ok: false, error: "a non-resident Web console needs a running terminal" };
+    }
+    clearBackgroundStatus();
+    const token = randomBytes(32).toString("hex");
+    const port = options.port ?? 8765;
+    const args = [cliEntry(), "background", "run", "--port", String(port)];
+    if (options.host)
+        args.push("--host", options.host);
+    if (!options.auth)
+        args.push("--no-auth");
+    if (options.tray === false)
+        args.push("--no-tray");
+    let child;
+    try {
+        child = spawn(process.execPath, args, {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+            env: {
+                ...process.env,
+                NEUTRINO_BACKGROUND_TOKEN: token,
+                NEUTRINO_BACKGROUND_RESIDENT: options.resident === false ? "0" : "1",
+                NEUTRINO_BACKGROUND_OWNER: options.ownerPid ? String(options.ownerPid) : "",
+                NEUTRINO_BACKGROUND_PROMPT: options.prompt ? "1" : "0",
+            },
+        });
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    child.once("error", (error) => backgroundLog(`spawn failed: ${error.message}`));
+    child.unref();
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (child.exitCode !== null) {
+            const tail = backgroundLogTail();
+            return {
+                ok: false,
+                error: `the background service exited with code ${child.exitCode}${tail ? `: ${tail}` : ""}`,
+            };
+        }
+        const status = readBackgroundStatus();
+        if (status && status.token === token && isProcessAlive(status.pid) && await canConnect(status.port, status.host)) {
+            return { ok: true, status, started: true };
+        }
+        await sleep(100);
+    }
+    // Don't leave a half-started service behind; it has no registration yet.
+    if (child.pid && isProcessAlive(child.pid)) {
+        try {
+            process.kill(child.pid, "SIGTERM");
+        }
+        catch { /* Already gone. */ }
+    }
+    const tail = backgroundLogTail();
+    return {
+        ok: false,
+        error: `the background service did not become reachable${tail ? `: ${tail}` : `; see ${BACKGROUND_LOG_FILE}`}`,
+    };
+}
+/** Apply a lifetime change to the process that already owns the conversations. */
+export async function configureBackgroundService(status, update) {
+    const response = await fetch(`${status.url}/api/background/configure`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${status.token}`, "Content-Type": "application/json" },
+        body: JSON.stringify(update),
+        signal: AbortSignal.timeout(5000),
+    });
+    const data = await response.json();
+    if (!response.ok)
+        throw new Error(data.error || "could not update background residency");
+    const updated = parseBackgroundStatus(data);
+    if (!updated || updated.pid !== status.pid || updated.token !== status.token) {
+        throw new Error("the Web console returned an invalid background status");
+    }
+    return updated;
+}
+/** Stop the detached service, politely first and by signal if it is stuck. */
+export async function stopBackgroundService(expected) {
+    const status = runningBackground();
+    if (!status) {
+        if (!expected)
+            clearBackgroundStatus();
+        return { ok: true, stopped: false };
+    }
+    if (expected && (status.pid !== expected.pid || status.token !== expected.token)) {
+        return { ok: false, stopped: false, error: "the Web console changed before it could be stopped" };
+    }
+    let requested = false;
+    try {
+        const response = await fetch(`${status.url}/api/background/stop`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${status.token}` },
+            signal: AbortSignal.timeout(2500),
+        });
+        requested = response.ok;
+    }
+    catch {
+        // The process may already be gone, or its socket may be wedged.
+    }
+    if (!requested) {
+        try {
+            process.kill(status.pid, "SIGTERM");
+        }
+        catch { /* Already gone. */ }
+    }
+    const deadline = Date.now() + STOP_TIMEOUT_MS;
+    while (Date.now() < deadline && isProcessAlive(status.pid))
+        await sleep(100);
+    if (isProcessAlive(status.pid)) {
+        try {
+            process.kill(status.pid, "SIGKILL");
+        }
+        catch { /* Already gone. */ }
+        const hardDeadline = Date.now() + 1500;
+        while (Date.now() < hardDeadline && isProcessAlive(status.pid))
+            await sleep(100);
+    }
+    const alive = isProcessAlive(status.pid);
+    if (!alive)
+        clearBackgroundStatus(status.pid);
+    return alive
+        ? { ok: false, stopped: false, error: `background service ${status.pid} did not stop` }
+        : { ok: true, stopped: true };
+}