@xingjisoft/neutrino 0.4.0 → 0.4.1

package/dist/bin.js

@@ -3,7 +3,10 @@ import process from "node:process";
 import { App } from "./app.js";
 import { loadConfig } from "./config.js";
 import { installCrashGuard } from "./terminal/restore.js";
-import { startWebServer } from "./web/server.js";
+import { webUrls } from "./web/server.js";
+import { runningBackground, startBackgroundService, stopBackgroundService, } from "./background.js";
+import { runWebService } from "./web/service.js";
+import { openInBrowser } from "./browser.js";
 const DEFAULT_WEB_PORT = 8765;
 /** Binding here makes the UI reachable from every interface. */
 const WILDCARD_HOST = "0.0.0.0";
@@ -35,6 +38,11 @@ Usage:
   neutrino                     Start the terminal UI (with the web UI).
   neutrino --lan               Start both, reachable from other devices.
   neutrino web [--port <port>] Start only the web UI (serves saved history).
+  neutrino background start    Run the web UI in the background; conversations
+                               started there survive the terminal/CLI exiting.
+  neutrino background stop     Stop the background service.
+  neutrino background status   Show whether it is running and where.
+  neutrino background open     Open its console in the default browser.
 
 Options:
   -p, --port <port>   Web UI port. Default: ${DEFAULT_WEB_PORT}
@@ -43,12 +51,16 @@ Options:
                       devices on your LAN or VPN.
       --no-web        Do not start the web UI with the terminal UI.
       --no-auth       Serve without password login.
+      --no-tray       Do not show the Windows notification-area icon of the
+                      background service.
       --web-port <n>  Deprecated alias for --port while the TUI runs.
   -h, --help          Show this help.
 
 Environment:
   NEUTRINO_WEB_PORT   Same as --port in either mode.
   NEUTRINO_WEB_HOST   Same as --host.
+  NEUTRINO_NO_TRAY    Set to 1 to keep the background service out of the
+                      Windows notification area.
 
 The web UI starts by default alongside the terminal UI on loopback. Turn it
 off for one run with --no-web, or permanently in Settings → Web console. It can
@@ -58,6 +70,13 @@ on, and off, in the browser's Settings → Web access; the choice is saved for t
 next launch, while --host/--lan win for the current one. Log in with the
 permanent password (default: 114514). Change it in Settings. --no-auth disables
 password login.
+
+Background residency is off by default. Turn it on in Settings → Background
+(shared by the regular and Pro workspaces). Switching it takes effect immediately,
+including for browser tasks already running. The background service keeps
+running when this terminal closes, so tasks started
+from the browser are not interrupted. Stop it with 'neutrino background stop',
+the tray icon, or Settings → Web console in the terminal.
 `);
 }
 /** Read the value that follows a flag, so `--host` alone is an error. */
@@ -68,13 +87,28 @@ function requireValue(argv, index, flag) {
     }
     return value;
 }
+const BACKGROUND_ACTIONS = new Set(["run", "start", "stop", "status", "open"]);
 function parseArgs(argv) {
-    const options = { mode: "tui", port: null, lan: false, noWeb: false, noAuth: false };
+    const options = {
+        mode: "tui", backgroundAction: null, port: null, lan: false, noWeb: false, noAuth: false, noTray: false,
+    };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "web") {
             options.mode = "web";
         }
+        else if (arg === "background") {
+            options.mode = "background";
+            options.backgroundAction = "status";
+            const next = argv[i + 1];
+            if (next && !next.startsWith("-")) {
+                if (!BACKGROUND_ACTIONS.has(next)) {
+                    throw new Error(`unknown background action "${next}"`);
+                }
+                options.backgroundAction = next;
+                i += 1;
+            }
+        }
         else if (arg === "--port" || arg === "-p") {
             options.port = parsePort(argv[++i]);
         }
@@ -102,6 +136,25 @@ function parseArgs(argv) {
         else if (arg === "--no-auth") {
             options.noAuth = true;
         }
+        else if (arg === "--no-tray") {
+            options.noTray = true;
+        }
+        else if (arg === "--start") {
+            options.mode = "background";
+            options.backgroundAction = "start";
+        }
+        else if (arg === "--stop") {
+            options.mode = "background";
+            options.backgroundAction = "stop";
+        }
+        else if (arg === "--status") {
+            options.mode = "background";
+            options.backgroundAction = "status";
+        }
+        else if (arg === "--open") {
+            options.mode = "background";
+            options.backgroundAction = "open";
+        }
         else if (arg === "--help" || arg === "-h") {
             printHelp();
             process.exit(0);
@@ -116,31 +169,64 @@ function parseArgs(argv) {
     if (options.noWeb && options.mode === "web") {
         throw new Error("--no-web cannot be used with the 'web' command");
     }
+    if (options.noWeb && options.mode === "background") {
+        throw new Error("--no-web cannot be used with the 'background' command");
+    }
     if (options.noWeb && (options.port !== null || options.host !== undefined || options.lan)) {
         throw new Error("use either --no-web or web UI options, not both");
     }
     return options;
 }
-/** Print every address a client can open, plus what it takes to open one. */
-function reportAccess(handle) {
-    process.stdout.write(`Neutrino web UI listening on ${handle.host}:${handle.port}\n`);
-    const multiple = handle.urls.length > 1;
+/** Print where an already-running detached console can be opened. */
+function reportBackgroundAccess(status, started) {
+    process.stdout.write(`Neutrino ${status.resident ? "background " : ""}Web console ${started ? "started" : "already running"} `
+        + `(pid ${status.pid}) on ${status.host}:${status.port}\n`);
+    const { urls } = webUrls(status.host, status.port);
+    const multiple = urls.length > 1;
     process.stdout.write(multiple ? "Open the address that matches your device:\n" : "Open:\n");
-    for (const url of handle.urls)
+    for (const url of urls)
         process.stdout.write(`  ${url}\n`);
-    const wildcard = handle.host === "0.0.0.0" || handle.host === "::";
-    if (wildcard && !handle.urls.some((url) => !url.includes("//127.0.0.1:"))) {
-        // Bound to every interface, yet nothing outside this machine is reachable:
-        // usually Wi-Fi is off, the VPN is down, or the only adapters left are
-        // virtual ones we deliberately hide.
+    if ((status.host === "0.0.0.0" || status.host === "::")
+        && !urls.some((url) => !url.includes("//127.0.0.1:"))) {
         process.stdout.write("note: no reachable network address found, so only this machine can connect.\n");
     }
-    if (handle.authRequired) {
-        process.stdout.write("Sign in with your permanent Web password (default: 114514). Change it in Settings.\n");
+    if (status.auth_required) {
+        process.stdout.write("Sign in with your permanent Web password (default: 114514).\n");
     }
     else {
         process.stdout.write("Password login is disabled.\n");
     }
+    if (status.resident) {
+        process.stdout.write("It keeps running after this terminal exits. Stop it with 'neutrino background stop'"
+            + (process.platform === "win32" ? " or the tray icon" : "") + ".\n");
+    }
+}
+/**
+ * The detached service itself (`neutrino background run`).
+ *
+ * It owns the Web console and every browser conversation for as long as the
+ * machine's user session keeps it alive. The token written into the status
+ * file is the only way another local process can ask it to stop.
+ */
+async function runBackgroundService(host, auth) {
+    await runWebService({ port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT, host, auth, tray: !options.noTray });
+}
+function printBackgroundStatus() {
+    const status = runningBackground();
+    if (!status) {
+        process.stdout.write("No background service is running.\n");
+        process.stdout.write("Start one with 'neutrino background start'.\n");
+        return;
+    }
+    process.stdout.write(`Neutrino background service: running (pid ${status.pid})\n`);
+    process.stdout.write(`Residency: ${status.resident ? "on" : "off (follows the terminal)"}\n`);
+    process.stdout.write(`Started: ${status.started_at}\n`);
+    process.stdout.write(`Address: ${status.url}\n`);
+    const { urls } = webUrls(status.host, status.port);
+    for (const url of urls) {
+        if (url.replace(/\/$/, "") !== status.url)
+            process.stdout.write(`Also: ${url}\n`);
+    }
 }
 let options;
 try {
@@ -152,29 +238,82 @@ catch (err) {
     process.exit(2);
 }
 // Installed before either mode starts: a crash must leave a usable terminal
-// (TUI) and a log line (both), never a shell flooded with mouse reports.
-installCrashGuard();
+// (TUI) and a log line (both), never a shell flooded with mouse reports. A
+// detached service keeps its own SIGHUP handler so closing the terminal cannot
+// take it down.
+installCrashGuard({ surviveHangup: options.mode === "background" });
 const host = options.lan ? WILDCARD_HOST : options.host || process.env.NEUTRINO_WEB_HOST || undefined;
 const auth = !options.noAuth;
 const portFromEnv = envPort();
 if (options.mode === "web") {
-    // Headless: serve the saved history (and any live sessions in this process,
-    // which for a standalone server is none).
-    const port = options.port ?? portFromEnv ?? DEFAULT_WEB_PORT;
-    try {
-        const handle = await startWebServer({ port, host, auth });
-        reportAccess(handle);
-        process.stdout.write("Serving saved conversations. Press Ctrl+C to stop.\n");
-        const shutdown = () => {
-            handle.close().finally(() => process.exit(0));
-        };
-        process.on("SIGINT", shutdown);
-        process.on("SIGTERM", shutdown);
-    }
-    catch (err) {
-        process.stderr.write(`neutrino: failed to start web server: ${err instanceof Error ? err.message : String(err)}\n`);
+    const result = await startBackgroundService({
+        port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT, host, auth,
+        tray: !options.noTray, resident: loadConfig().background === true, ownerPid: process.pid,
+        strictPort: options.port !== null,
+    });
+    if (!result.ok) {
+        process.stderr.write(`neutrino: failed to start web server: ${result.error}\n`);
         process.exit(1);
     }
+    reportBackgroundAccess(result.status, result.started);
+    process.stdout.write("Serving saved conversations. Press Ctrl+C to close this terminal.\n");
+    // The owner monitor in the service also handles an abrupt terminal close.
+    const keepAlive = setInterval(() => { }, 60_000);
+    const shutdown = () => { clearInterval(keepAlive); process.exit(0); };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+else if (options.mode === "background") {
+    const action = options.backgroundAction ?? "status";
+    if (action === "run") {
+        // The detached child. It does not own a terminal, so its stdio is ignored
+        // by the parent and every diagnostic goes to background.log.
+        await runBackgroundService(host, auth);
+    }
+    else if (action === "start") {
+        const result = await startBackgroundService({
+            port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT,
+            host,
+            auth,
+            tray: !options.noTray,
+        });
+        if (!result.ok) {
+            process.stderr.write(`neutrino: ${result.error}\n`);
+            process.exit(1);
+        }
+        reportBackgroundAccess(result.status, result.started);
+        process.exitCode = 0;
+    }
+    else if (action === "stop") {
+        const result = await stopBackgroundService();
+        if (!result.ok) {
+            process.stderr.write(`neutrino: ${result.error}\n`);
+            process.exit(1);
+        }
+        process.stdout.write(result.stopped ? "Background service stopped.\n" : "No background service is running.\n");
+        process.exitCode = 0;
+    }
+    else if (action === "open") {
+        const started = await startBackgroundService({
+            port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT,
+            host,
+            auth,
+            tray: !options.noTray,
+        });
+        if (!started.ok) {
+            process.stderr.write(`neutrino: ${started.error}\n`);
+            process.exit(1);
+        }
+        if (started.started)
+            reportBackgroundAccess(started.status, true);
+        openInBrowser(started.status.url);
+        process.stdout.write(`Opening ${started.status.url}\n`);
+        process.exitCode = 0;
+    }
+    else {
+        printBackgroundStatus();
+        process.exitCode = 0;
+    }
 }
 else {
     if (!process.stdout.isTTY || !process.stdin.isTTY) {
@@ -184,22 +323,20 @@ else {
     }
     const app = new App();
     const webPort = options.port ?? portFromEnv ?? DEFAULT_WEB_PORT;
-    // Remember where the UI should live even when it is off right now, so the
-    // Settings toggle can mount it without restarting the terminal.
-    app.configureWeb(webPort, host, auth);
-    // Explicit web settings win over the saved preference; otherwise the web UI
-    // is part of a normal launch unless the user turned it off in Settings.
+    const saved = loadConfig();
+    app.configureWeb(webPort, host, auth, true, !options.noTray);
     const requested = options.port !== null || options.host !== undefined || options.lan
         || options.noAuth || portFromEnv !== null || Boolean(process.env.NEUTRINO_WEB_HOST);
-    const enabledByDefault = loadConfig().web_console !== false;
-    if (!options.noWeb && (requested || enabledByDefault)) {
+    if (!options.noWeb && (requested || saved.web_console !== false)) {
         try {
-            const handle = await app.enableWeb(webPort, host, auth);
-            reportAccess(handle);
+            const previous = runningBackground();
+            const status = await app.enableWeb(webPort, host, auth);
+            if (options.port !== null && options.port !== 0 && status.port !== webPort) {
+                process.stderr.write(`note: the Web console is already running on port ${status.port}; --port was not applied.\n`);
+            }
+            reportBackgroundAccess(status, previous?.pid !== status.pid);
         }
         catch (err) {
-            // A console that cannot bind (usually a second instance on 8765) must
-            // never take the terminal down with it.
             const detail = err instanceof Error ? err.message : String(err);
             process.stderr.write(`neutrino: web UI not started: ${detail}\n`);
             process.stderr.write("The terminal UI will keep running. Pass --port <port> to use another port, or --no-web to skip the web UI.\n");

package/dist/config.js

@@ -24,10 +24,10 @@ export const PRO_CONFIG_FILE = path.join(PRO_DIR, "config.json");
 export const PRO_SESSION_DIR = path.join(PRO_DIR, "session");
 /**
  * Settings that intentionally apply to both workspaces. The Web password, the
- * approval policy and the console's interface are properties of this process,
- * not of a conversation workspace.
+ * approval policy, the console's interface/LAN access and background residency
+ * are properties of this process, not of a conversation workspace.
  */
-export const SHARED_CONFIG_KEYS = ["web_password_hash", "approval_mode", "auto_approve_extreme_risk", "web_lan"];
+export const SHARED_CONFIG_KEYS = ["web_password_hash", "approval_mode", "auto_approve_extreme_risk", "web_lan", "background"];
 export function normalizeMode(value) {
     return typeof value === "string" && value.trim().toLowerCase() === "pro" ? "pro" : "standard";
 }
@@ -136,6 +136,10 @@ export const DEFAULT_CONFIG = {
     // Listen on every interface (the equivalent of --lan) instead of loopback.
     // The listener belongs to the process, so both workspaces share this value.
     web_lan: false,
+    // Keep the Web console and the conversations it runs alive after the
+    // terminal UI exits. This is a property of the machine, not of a workspace,
+    // so the regular site and Pro share it.
+    background: false,
     // Working directories opened from the browser, newest first. They remain
     // listed even when they hold no conversations yet.
     web_workspaces: [],

package/dist/header.js

@@ -26,7 +26,8 @@ export function drawHeader(buf, state) {
     if (state.webUrl) {
         // A short reminder that the browser console is live; the startup message
         // prints the full addresses when more than one works.
-        text += `  ·  web ${state.webUrl.replace(/^https?:\/\//, "").replace(/\/$/, "")}`;
+        const label = state.webBackground ? "web (background)" : "web";
+        text += `  ·  ${label} ${state.webUrl.replace(/^https?:\/\//, "").replace(/\/$/, "")}`;
     }
     text = truncateByWidth(text, w);
     buf.centerText(0, text, { fg: C.accent, bg: C.highlightBg, bold: true });

package/dist/llm/tools.js

@@ -157,7 +157,9 @@ function runCommand(command, cwd) {
             resolve("[Error: empty command]");
             return;
         }
-        exec(command, { cwd, timeout: 120000, maxBuffer: MAX_OUTPUT * 4 }, (error, stdout, stderr) => {
+        exec(command, 
+        // A detached Windows service has no console for its tool shells to inherit.
+        { cwd, timeout: 120000, maxBuffer: MAX_OUTPUT * 4, windowsHide: true }, (error, stdout, stderr) => {
             const parts = [];
             if (stdout)
                 parts.push(stdout);

package/dist/migration.js

@@ -0,0 +1,33 @@
+import { loadAgentSession, safeAgentSessionId } from "./agents.js";
+import { loadConfig, loadSession, normalizeApprovalMode, saveSession, } from "./config.js";
+export class SessionMigrationError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Copy the readable conversation into a fresh native transcript, ready to resume. */
+export function migrateAgentSession(agent, sourceId, cwd, selection, mode = "standard", proPreset) {
+    if (!safeAgentSessionId(sourceId))
+        throw new SessionMigrationError(400, "invalid session id");
+    const source = loadAgentSession(agent, sourceId, cwd);
+    if (!source)
+        throw new SessionMigrationError(404, "session not found in this working directory");
+    // Preserve the roles and text exposed by the history viewer. Resumed native
+    // sessions supply their own system prompt and model/tool configuration.
+    const messages = source.messages.map(({ role, content }) => ({ role, content }));
+    if (!messages.length)
+        throw new SessionMigrationError(400, "this session has no messages to migrate");
+    let id;
+    try {
+        id = saveSession(messages, selection.model, selection.provider, selection.intensity, source.cwd, undefined, { prompt: 0, completion: 0 }, undefined, normalizeApprovalMode(loadConfig(mode).approval_mode), undefined, mode, proPreset);
+    }
+    catch (error) {
+        throw new SessionMigrationError(500, error instanceof Error ? error.message : String(error));
+    }
+    const saved = loadSession(id, mode);
+    if (!saved)
+        throw new SessionMigrationError(500, "could not read the migrated conversation");
+    return saved;
+}

package/dist/screens/agentConversation.js

@@ -1,17 +1,22 @@
 import { Screen } from "../terminal/screen.js";
 import { C } from "../colors.js";
 import { drawHeader } from "../header.js";
-import { drawHint, drawScrollbar } from "../ui.js";
+import { drawHint, drawScrollbar, inRect } from "../ui.js";
 import { drawSpans, renderMarkdownText } from "../markdown.js";
-import { ellipsize } from "../width.js";
+import { displayWidth, ellipsize, truncateByWidth } from "../width.js";
+import { migrateAgentSession } from "../migration.js";
 export class AgentConversationScreen extends Screen {
+    source;
     title;
     messages;
     scrollTop = 0;
     followBottom = true;
     scrollbarGeom = null;
-    constructor(title, messages) {
+    migrateButton = null;
+    migrationError = "";
+    constructor(title, messages, source) {
         super();
+        this.source = source;
         this.title = title;
         this.messages = messages;
     }
@@ -37,6 +42,10 @@ export class AgentConversationScreen extends Screen {
         else if (key.name === "escape") {
             this.app.popScreen();
         }
+        else if (key.name === "enter" || key.name === "return" ||
+            (!key.ctrl && !key.meta && key.char.toLowerCase() === "m")) {
+            this.migrate();
+        }
     }
     onMouse(ev) {
         if (ev.type === "wheel") {
@@ -52,6 +61,28 @@ export class AgentConversationScreen extends Screen {
         else if (ev.type === "click" && ev.button === 2) {
             this.app.popScreen();
         }
+        else if (ev.type === "click" && ev.button === 0 && this.migrateButton &&
+            inRect(ev.x, ev.y, this.migrateButton)) {
+            this.migrate();
+        }
+    }
+    migrate() {
+        if (!this.messages.length)
+            return;
+        try {
+            const state = this.app.state;
+            const session = migrateAgentSession(this.source.agent, this.source.id, this.source.cwd, {
+                provider: state.selectedProvider, model: state.selectedModelName, intensity: state.selectedIntensity,
+            });
+            this.app.loadSession(session);
+        }
+        catch (error) {
+            this.migrationError = error instanceof Error ? error.message : String(error);
+            this.app.render();
+        }
+    }
+    alwaysRepaintRows() {
+        return [this.app.height - 3, this.app.height - 2, this.app.height - 1];
     }
     scrollbar() {
         const g = this.scrollbarGeom;
@@ -93,7 +124,7 @@ export class AgentConversationScreen extends Screen {
         const h = buf.height;
         buf.centerText(1, ellipsize(this.title, Math.max(10, w - 4)), { fg: C.dim });
         const logTop = 3;
-        const logBottom = h - 2;
+        const logBottom = h - 4;
         const viewH = Math.max(1, logBottom - logTop + 1);
         const lines = this.buildLines(Math.max(10, w - 4));
         const maxScroll = Math.max(0, lines.length - viewH);
@@ -118,6 +149,18 @@ export class AgentConversationScreen extends Screen {
         }
         // Scrollbar on the right edge, visible only when the log overflows.
         drawScrollbar(buf, w - 1, logTop, logBottom, lines.length, viewH, this.scrollTop);
-        drawHint(buf, h - 1, "↑/↓ scroll  ·  wheel or drag the bar  ·  right-click back  ·  Esc back");
+        if (this.migrationError) {
+            buf.writeText(2, h - 3, ellipsize(`迁移失败：${this.migrationError}`, Math.max(0, w - 4)), { fg: C.red });
+        }
+        const label = truncateByWidth("[ 迁移会话 ]", Math.max(0, w - 2));
+        const buttonWidth = displayWidth(label);
+        this.migrateButton = { x: Math.max(0, w - buttonWidth - 2), y: h - 2, w: buttonWidth, h: 1 };
+        buf.writeText(this.migrateButton.x, this.migrateButton.y, label, {
+            fg: this.messages.length ? C.accent : C.dim, bg: C.highlightBg, bold: true,
+        });
+        for (let x = this.migrateButton.x; x < this.migrateButton.x + buttonWidth; x++) {
+            buf.markChrome(x, this.migrateButton.y);
+        }
+        drawHint(buf, h - 1, "↑/↓ scroll  ·  M/Enter migrate  ·  right-click back  ·  Esc back");
     }
 }

package/dist/screens/agentHistory.js

@@ -97,8 +97,10 @@ export class AgentHistoryScreen extends Screen {
         if (this.selectedIdx < 0 || this.selectedIdx >= this.sessions.length)
             return;
         const s = this.sessions[this.selectedIdx];
-        const messages = loadAgentMessages(this.agent, s.id);
-        this.app.pushScreen(new AgentConversationScreen(`${this.label} · ${s.title || s.id}`, messages));
+        const messages = loadAgentMessages(this.agent, s.id, this.cwd);
+        this.app.pushScreen(new AgentConversationScreen(`${this.label} · ${s.title || s.id}`, messages, {
+            agent: this.agent, id: s.id, cwd: this.cwd,
+        }));
     }
     buildRows() {
         const rows = [];

package/dist/screens/settings.js

@@ -4,8 +4,9 @@ import { CONTEXT_WINDOW_OPTIONS, DEFAULT_CONTEXT_WINDOW, contextWindow, CONFIG_F
 import { drawHeader } from "../header.js";
 import { centerVertically, drawHint } from "../ui.js";
 import { hashWebPassword } from "../web/auth.js";
+import { runningBackground } from "../background.js";
 /** The settings that can be changed here, top to bottom. */
-const ROWS = ["intensity", "compress", "approval_model", "extreme_approval", "sound", "web_console", "web_password"];
+const ROWS = ["intensity", "compress", "approval_model", "extreme_approval", "sound", "web_console", "background", "web_password"];
 export class SettingsScreen extends Screen {
     intensityIdx = 2;
     /** Levels the current chat model accepts, in canonical order. */
@@ -20,8 +21,11 @@ export class SettingsScreen extends Screen {
     soundIdx = 1;
     /** 0 = web UI off, 1 = mounted alongside the terminal. */
     webIdx = 1;
+    /** 0 = terminal only, 1 = the Web console is run by a detached service. */
+    backgroundIdx = 0;
     /** Only a row the user actually touched rewrites the saved default. */
     webChanged = false;
+    backgroundPending = false;
     models = [];
     rowIdx = 0;
     lastHoverX = -1;
@@ -48,6 +52,9 @@ export class SettingsScreen extends Screen {
         // off, so reflect what is actually running first.
         this.webIdx = (this.app.state.webUrl || config.web_console !== false) ? 1 : 0;
         this.webChanged = false;
+        const background = runningBackground();
+        this.backgroundIdx = (state.webUrl ? state.webBackground : background?.resident ?? config.background === true) ? 1 : 0;
+        this.backgroundPending = false;
     }
     /** Change the value of a row by `delta` steps and persist it immediately. */
     cycle(row, delta) {
@@ -81,6 +88,13 @@ export class SettingsScreen extends Screen {
             void this.app.setWebConsole(this.webIdx === 1);
             return;
         }
+        else if (row === "background") {
+            if (this.backgroundPending)
+                return;
+            const service = runningBackground();
+            const current = this.app.state.webUrl ? this.app.state.webBackground : service?.resident ?? this.backgroundIdx === 1;
+            return this.applyBackground(!current);
+        }
         else {
             const options = [...new Set([...CONTEXT_WINDOW_OPTIONS, this.contextTokens])].sort((a, b) => a - b);
             const i = options.indexOf(this.contextTokens);
@@ -89,6 +103,23 @@ export class SettingsScreen extends Screen {
         }
         this.save();
     }
+    async applyBackground(enabled) {
+        this.backgroundPending = true;
+        this.app.render();
+        try {
+            const result = await this.app.setBackgroundResidency(enabled);
+            if (result.ok)
+                this.backgroundIdx = enabled ? 1 : 0;
+            else
+                this.backgroundIdx = loadConfig().background === true ? 1 : 0;
+            if (this.app.state.webUrl)
+                this.webIdx = 1;
+        }
+        finally {
+            this.backgroundPending = false;
+            this.app.render();
+        }
+    }
     onKey(key) {
         if (this.editingPassword) {
             if (key.name === "escape") {
@@ -233,9 +264,19 @@ export class SettingsScreen extends Screen {
                 value: this.webIdx === 0
                     ? "Off"
                     : this.app.state.webUrl
-                        ? `On · ${this.app.state.webUrl}`
+                        ? this.app.state.webBackground
+                            ? `On (background) · ${this.app.state.webUrl}`
+                            : `On · ${this.app.state.webUrl}`
                         : "On (not running)",
             },
+            {
+                label: "Background residency",
+                value: this.backgroundPending
+                    ? "Applying…"
+                    : this.app.state.webUrl
+                        ? this.app.state.webBackground ? "On (running)" : "Off"
+                        : runningBackground()?.resident ? "On (running)" : this.backgroundIdx === 1 ? "On (not running)" : "Off",
+            },
             {
                 label: "Web password",
                 value: this.editingPassword ? "*".repeat(Math.min(this.passwordDraft.length, 24)) || "Type new password" : this.passwordMessage,

package/dist/state.js

@@ -11,6 +11,7 @@ export function defaultState() {
         cursorOn: true,
         approval: null,
         webUrl: null,
+        webBackground: false,
         selection: null,
     };
 }

package/dist/terminal/restore.js

@@ -89,17 +89,7 @@ export function writeCrashLog(kind, err) {
         return null;
     }
 }
-/**
- * Installs process-wide handlers that restore the terminal before the process
- * dies.
- *
- * Without this, any throw that escapes a timer, a stream callback or a floating
- * promise kills the process with raw mode still on and the alternate screen
- * still active. The visible result is a terminal that works but spews
- * `[<b>;<x>;<y>M` mouse reports at the shell prompt, because the shell now
- * receives the mouse events the TUI asked the terminal to send.
- */
-export function installCrashGuard() {
+export function installCrashGuard(options = {}) {
     if (installed)
         return;
     installed = true;
@@ -123,7 +113,8 @@ export function installCrashGuard() {
     });
     // These signals otherwise bypass Node's exit hook, including Ctrl+Break on
     // Windows. The app handles SIGINT as an interrupt and SIGTERM as a quit.
-    process.on("SIGHUP", () => process.exit(129));
+    if (!options.surviveHangup)
+        process.on("SIGHUP", () => process.exit(129));
     process.on("SIGBREAK", () => process.exit(149));
     const fatal = (kind, err) => {
         // Restore first: the terminal must be usable even if logging itself fails.