@xingjisoft/neutrino 0.4.0 → 0.4.1

package/dist/web/service.js

@@ -0,0 +1,135 @@
+import { randomBytes } from "node:crypto";
+import process from "node:process";
+import { backgroundLog, clearBackgroundStatus, isProcessAlive, writeBackgroundStatus, } from "../background.js";
+import { loadConfig, saveConfig } from "../config.js";
+import { startBackgroundTray } from "../tray.js";
+import { hub } from "./hub.js";
+import { startWebServer } from "./server.js";
+import { TerminalBridges } from "./terminalBridge.js";
+/** The detached process owns browser conversations for their entire lifetime. */
+export async function runWebService(options) {
+    const token = process.env.NEUTRINO_BACKGROUND_TOKEN?.trim() || randomBytes(32).toString("hex");
+    let resident = process.env.NEUTRINO_BACKGROUND_RESIDENT !== "0";
+    const owner = Number(process.env.NEUTRINO_BACKGROUND_OWNER);
+    let owners = new Set(Number.isSafeInteger(owner) && owner > 0 ? [owner] : []);
+    const startedAt = new Date().toISOString();
+    let handle = null;
+    let tray = null;
+    let monitor = null;
+    let stopping = false;
+    const bridges = new TerminalBridges();
+    const status = () => {
+        if (!handle)
+            throw new Error("the Web console is starting");
+        return {
+            pid: process.pid, port: handle.port, host: handle.host, url: handle.url,
+            auth_required: options.auth, token, started_at: startedAt,
+            resident, owner_pids: [...owners],
+        };
+    };
+    const syncTray = () => {
+        if (!resident) {
+            tray?.close();
+            tray = null;
+        }
+        else if (!tray && options.tray && handle) {
+            tray = startBackgroundTray({ url: handle.url, stopUrl: `${handle.url}/api/background/stop`, token, pid: process.pid });
+        }
+    };
+    const shutdown = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        if (monitor)
+            clearInterval(monitor);
+        tray?.close();
+        bridges.close();
+        backgroundLog(`stopping pid=${process.pid}`);
+        clearBackgroundStatus(process.pid);
+        const finish = () => process.exit(0);
+        if (handle)
+            handle.close().finally(finish).catch(finish);
+        else
+            finish();
+        setTimeout(finish, 3000).unref();
+    };
+    const configure = (update) => {
+        if (stopping)
+            throw new Error("the Web console is shutting down");
+        if (update.ownerPid !== undefined && !isProcessAlive(update.ownerPid)) {
+            throw new Error("the terminal that owns this console has already exited");
+        }
+        const previousResident = resident;
+        const previousOwners = owners;
+        const config = loadConfig();
+        const changed = update.resident !== undefined;
+        if (changed)
+            saveConfig({ ...config, background: update.resident });
+        resident = update.resident ?? resident;
+        owners = new Set(owners);
+        if (update.ownerPid !== undefined)
+            owners.add(update.ownerPid);
+        try {
+            writeBackgroundStatus(status());
+        }
+        catch (error) {
+            resident = previousResident;
+            owners = previousOwners;
+            if (changed) {
+                try {
+                    saveConfig(config);
+                }
+                catch { /* Report the original failure. */ }
+            }
+            throw error;
+        }
+        if (update.bridge && update.ownerPid)
+            bridges.add(update.ownerPid, update.bridge);
+        syncTray();
+        return status();
+    };
+    try {
+        handle = await startWebServer({
+            port: options.port, host: options.host, auth: options.auth,
+            backgroundPrompt: !resident && process.env.NEUTRINO_BACKGROUND_PROMPT === "1",
+            backgroundService: { token, onStop: shutdown, status, configure },
+            onAddressChange: () => { if (handle)
+                writeBackgroundStatus(status()); },
+        });
+        writeBackgroundStatus(status());
+    }
+    catch (error) {
+        backgroundLog(`failed to start pid=${process.pid}: ${error instanceof Error ? error.message : String(error)}`);
+        if (handle)
+            await handle.close();
+        process.exit(1);
+    }
+    backgroundLog(`started pid=${process.pid} on ${handle.url} (residency ${resident ? "on" : "off"})`);
+    syncTray();
+    // No helper processes: polling pids must remain invisible on Windows. An
+    // orphaned, non-resident console lets an in-flight browser turn finish before
+    // exiting, so disabling residency also cannot throw away running work.
+    monitor = setInterval(() => {
+        try {
+            const live = new Set([...owners].filter(isProcessAlive));
+            if (live.size !== owners.size) {
+                for (const owner of owners)
+                    if (!live.has(owner))
+                        bridges.remove(owner);
+                owners = live;
+                writeBackgroundStatus(status());
+            }
+            if (!resident && owners.size === 0 && !hub.list().some(entry => entry.busy || entry.paused || entry.queued || entry.compressing || entry.approval || entry.reviewing)) {
+                shutdown();
+            }
+        }
+        catch (error) {
+            backgroundLog(`lifetime check failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }, 500);
+    monitor.unref();
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    if (process.platform !== "win32")
+        process.on("SIGHUP", () => { });
+}

package/dist/web/session.js

@@ -27,8 +27,6 @@ import { writeCrashLog } from "../terminal/restore.js";
 import { hub, liveApprovalDetails, } from "./hub.js";
 /** Drop a resumed conversation nobody touched for this long. */
 const IDLE_DISPOSE_MS = 30 * 60 * 1000;
-/** Upper bound on tool round-trips inside a single turn. */
-const MAX_TOOL_ROUNDS = 24;
 /** Placeholder shown while a tool is still running. */
 const TOOL_PENDING = "…";
 /** A sub-agent gets the same tools minus delegation: one level, never a tree. */
@@ -710,9 +708,12 @@ export class WebSession {
         const tools = this.mode === "pro" ? getProToolDefinitions() : getToolDefinitions();
         const team = this.proTeam;
         try {
-            for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+            while (true) {
                 if (token !== this.turnToken || this.paused)
                     return false;
+                // Match the terminal: long tasks can keep using tools until the model
+                // finishes, while older tool results are trimmed near the context limit.
+                apiMessages = this.trimApiMessages(apiMessages);
                 const client = team ? team.client("main_model") : new LLMClient(this.model, this.provider, this.intensity);
                 let text = "";
                 this.streamingContent = "";
@@ -825,9 +826,6 @@ export class WebSession {
                 }
                 this.save();
             }
-            if (this.mode === "pro")
-                this.messages.push({ role: "assistant", content: "[Error: Pro main agent reached its tool round limit before completion.]" });
-            return false;
         }
         catch (err) {
             if (token !== this.turnToken)
@@ -976,6 +974,25 @@ export class WebSession {
         }
         return contextCompressionThreshold(this.provider, this.model, this.mode);
     }
+    /** Trim old tool results in a long turn without changing the saved history. */
+    trimApiMessages(apiMessages) {
+        const threshold = this.compressThreshold();
+        if (threshold <= 0 || this.lastPromptTokens < threshold)
+            return apiMessages;
+        const toolIdx = [];
+        for (let i = 0; i < apiMessages.length; i++) {
+            if (apiMessages[i].role === "tool")
+                toolIdx.push(i);
+        }
+        const dropCount = toolIdx.length - COMPACT_KEEP;
+        if (dropCount <= 0)
+            return apiMessages;
+        const copy = apiMessages.slice();
+        for (let k = 0; k < dropCount; k++) {
+            copy[toolIdx[k]] = { ...copy[toolIdx[k]], content: "[tool output omitted to save context]" };
+        }
+        return copy;
+    }
     async autoCompress(token) {
         const threshold = this.compressThreshold();
         if (threshold <= 0 || this.lastPromptTokens < threshold)

package/dist/web/settings.js

@@ -62,6 +62,7 @@ export function getWebSettings(mode = "standard") {
             approval_mode: normalizeApprovalMode(config.approval_mode),
             web_console: config.web_console !== false,
             web_lan: config.web_lan === true,
+            background: config.background === true,
         },
     };
 }
@@ -150,6 +151,11 @@ export function updateWebSettings(value, mode = "standard") {
                     throw new Error("LAN access must be a boolean");
                 config.web_lan = val;
             }
+            else if (key === "background") {
+                if (typeof val !== "boolean")
+                    throw new Error("background residency must be a boolean");
+                config.background = val;
+            }
             else if (key === "web_password") {
                 validateWebPassword(val);
             }

package/dist/web/terminalBridge.js

@@ -0,0 +1,250 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import http from "node:http";
+import { resolveModelSelection } from "../config.js";
+import { hub } from "./hub.js";
+function sendJson(res, status, data) {
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    res.end(JSON.stringify(data));
+}
+function authorized(req, token) {
+    const provided = req.headers.authorization?.replace(/^Bearer /, "") ?? "";
+    const expected = Buffer.from(token);
+    const actual = Buffer.from(provided);
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > 1_000_000)
+            throw new Error("request too large");
+        chunks.push(bytes);
+    }
+    const value = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid request");
+    return value;
+}
+/** A private loopback bridge exposes only the terminal's live hub. */
+export async function startTerminalBridge() {
+    const token = randomBytes(32).toString("hex");
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            if (!authorized(req, token)) {
+                sendJson(res, 401, { error: "terminal token required" });
+                return;
+            }
+            if (req.method === "GET" && req.url === "/snapshots") {
+                const snapshots = [];
+                for (const entry of hub.list()) {
+                    const snapshot = hub.snapshot(entry.key);
+                    if (snapshot)
+                        snapshots.push({ mode: hub.has(entry.key, "pro") ? "pro" : "standard", snapshot });
+                }
+                sendJson(res, 200, snapshots);
+                return;
+            }
+            if (req.method !== "POST" || req.url !== "/action") {
+                sendJson(res, 404, { error: "not found" });
+                return;
+            }
+            const input = await readBody(req);
+            const key = typeof input.key === "string" ? input.key : "";
+            const action = input.action;
+            const body = input.body && typeof input.body === "object" && !Array.isArray(input.body)
+                ? input.body : {};
+            if (!hub.has(key)) {
+                sendJson(res, 404, { error: "unknown live session" });
+                return;
+            }
+            if (action === "pause")
+                hub.pause(key);
+            else if (action === "resume")
+                hub.resume(key);
+            else if (action === "message") {
+                if (typeof body.text !== "string" || !body.text.trim())
+                    throw new Error("empty message");
+                hub.send(key, body.text);
+            }
+            else if (action === "approve") {
+                if (!hub.approve(key, body.approved === true)) {
+                    sendJson(res, 409, { error: "no approval is pending" });
+                    return;
+                }
+            }
+            else if (action === "approval-mode") {
+                if (body.mode !== "request" && body.mode !== "auto")
+                    throw new Error("mode must be request or auto");
+                if (!hub.setApprovalMode(key, body.mode)) {
+                    sendJson(res, 409, { error: "this session cannot change approval mode" });
+                    return;
+                }
+            }
+            else if (action === "model") {
+                const result = hub.configure(key, resolveModelSelection(body));
+                if (!result.ok) {
+                    sendJson(res, 409, { error: result.error });
+                    return;
+                }
+            }
+            else if (action === "pro-preset") {
+                if (typeof body.preset !== "string")
+                    throw new Error("invalid Pro preset");
+                const result = hub.setProPreset(key, body.preset);
+                if (!result.ok) {
+                    sendJson(res, 409, { error: result.error });
+                    return;
+                }
+            }
+            else if (action === "clear") {
+                if (!hub.clear(key)) {
+                    sendJson(res, 409, { error: "this session cannot be cleared" });
+                    return;
+                }
+            }
+            else {
+                sendJson(res, 400, { error: "this session is owned by the terminal UI" });
+                return;
+            }
+            sendJson(res, 200, {
+                ok: true, snapshot: hub.snapshot(key),
+                ...(action === "pause" ? { paused: true } : action === "resume" ? { paused: false } : {}),
+                ...(action === "approve" ? { approved: body.approved === true } : {}),
+            });
+        })().catch(error => {
+            if (!res.headersSent)
+                sendJson(res, 400, { error: error instanceof Error ? error.message : "invalid request" });
+            else
+                res.end();
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => { server.removeListener("error", reject); resolve(); });
+    });
+    server.unref();
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("could not open the terminal bridge");
+    return { url: `http://127.0.0.1:${address.port}`, token, close: () => { server.close(); } };
+}
+class RemoteTerminal {
+    bridge;
+    remoteKey;
+    mode;
+    current;
+    key = "";
+    constructor(bridge, remoteKey, mode, initial) {
+        this.bridge = bridge;
+        this.remoteKey = remoteKey;
+        this.mode = mode;
+        this.current = initial;
+        this.key = hub.register(this);
+    }
+    liveCwd() { return this.current.cwd; }
+    liveMeta() {
+        const { key: _key, cwd: _cwd, messages: _messages, streamingContent: _streaming, context: _context, plan: _plan, ...meta } = this.current;
+        return meta;
+    }
+    liveSnapshot(key) { return { ...this.current, key }; }
+    // The public server forwards actions through remoteAction, where failures can
+    // be returned to the browser rather than silently lost.
+    livePause() { }
+    liveResume() { }
+    liveSend(_text) { }
+    update(snapshot) {
+        this.current = snapshot;
+        hub.notify(this.key);
+    }
+    async remoteAction(action, body) {
+        try {
+            const response = await fetch(`${this.bridge.url}/action`, {
+                method: "POST", headers: { Authorization: `Bearer ${this.bridge.token}`, "Content-Type": "application/json" },
+                body: JSON.stringify({ key: this.remoteKey, action, body }), signal: AbortSignal.timeout(5000),
+            });
+            const data = await response.json();
+            if (data.snapshot) {
+                this.update(data.snapshot);
+                data.snapshot = this.liveSnapshot(this.key);
+            }
+            return { status: response.status, data };
+        }
+        catch {
+            return { status: 503, data: { error: "the terminal session is unavailable" } };
+        }
+    }
+    close() { hub.unregister(this.key); }
+}
+/** Mirror each attached terminal's live sessions into the Web service. */
+export class TerminalBridges {
+    entries = new Map();
+    timer = setInterval(() => { for (const owner of this.entries.keys())
+        void this.poll(owner); }, 250);
+    constructor() { this.timer.unref(); }
+    add(owner, bridge) {
+        this.remove(owner);
+        this.entries.set(owner, { bridge, sessions: new Map(), polling: false, failures: 0 });
+        void this.poll(owner);
+    }
+    remove(owner) {
+        const entry = this.entries.get(owner);
+        if (!entry)
+            return;
+        this.entries.delete(owner);
+        for (const session of entry.sessions.values())
+            session.close();
+    }
+    close() {
+        clearInterval(this.timer);
+        for (const owner of this.entries.keys())
+            this.remove(owner);
+    }
+    async poll(owner) {
+        const entry = this.entries.get(owner);
+        if (!entry || entry.polling)
+            return;
+        entry.polling = true;
+        try {
+            const response = await fetch(`${entry.bridge.url}/snapshots`, {
+                headers: { Authorization: `Bearer ${entry.bridge.token}` }, signal: AbortSignal.timeout(1500),
+            });
+            if (!response.ok)
+                throw new Error("terminal bridge failed");
+            const snapshots = await response.json();
+            if (!Array.isArray(snapshots) || this.entries.get(owner) !== entry)
+                return;
+            entry.failures = 0;
+            const live = new Set();
+            for (const { mode, snapshot } of snapshots) {
+                if (!snapshot || typeof snapshot.key !== "string" || (mode !== "standard" && mode !== "pro"))
+                    continue;
+                live.add(snapshot.key);
+                const session = entry.sessions.get(snapshot.key);
+                if (session)
+                    session.update(snapshot);
+                else
+                    entry.sessions.set(snapshot.key, new RemoteTerminal(entry.bridge, snapshot.key, mode, snapshot));
+            }
+            for (const [key, session] of entry.sessions) {
+                if (!live.has(key)) {
+                    session.close();
+                    entry.sessions.delete(key);
+                }
+            }
+        }
+        catch {
+            // Keep snapshots over brief disconnects, but never expose a dead terminal
+            // indefinitely if its process stays alive after the bridge fails.
+            if (++entry.failures >= 4) {
+                for (const session of entry.sessions.values())
+                    session.close();
+                entry.sessions.clear();
+            }
+        }
+        finally {
+            entry.polling = false;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingjisoft/neutrino",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "XINGJI Neutrino - a CLI coding agent in the terminal.",
   "type": "module",
   "license": "Apache-2.0",
@@ -18,7 +18,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node scripts/test-paste.mjs && node scripts/test-mouse.mjs && node scripts/test-cursor.mjs && node scripts/test-selection.mjs && node scripts/test-drag-scroll.mjs && node scripts/test-selection-performance.mjs && node scripts/test-copy.mjs && node scripts/test-scrollbar.mjs && node scripts/test-render.mjs && node scripts/test-drift.mjs && node scripts/test-sanitize.mjs && node scripts/test-markdown.mjs && node scripts/test-wrap.mjs && node scripts/test-fetch.mjs && node scripts/test-compact.mjs && node scripts/test-history-fold.mjs && node scripts/test-web-history.mjs && node scripts/test-web-default.mjs && node scripts/test-turn-fold.mjs && node scripts/test-plan.mjs && node scripts/test-subagent.mjs && node scripts/test-web-settings.mjs && node scripts/test-model-intensity.mjs && node scripts/test-web-markdown.mjs && node scripts/test-web-i18n.mjs && node scripts/test-web-workspaces.mjs && node scripts/test-tools.mjs && node scripts/test-approval.mjs && node scripts/test-approval-review.mjs && node scripts/test-approval-ui.mjs && node scripts/test-web-approval-details.mjs && node scripts/test-approval-mode.mjs && node scripts/test-approval-context.mjs && node scripts/test-settings-render.mjs && node scripts/test-approval-flow.mjs && node scripts/test-web.mjs && node scripts/test-web-settings-http.mjs && node scripts/test-web-lan.mjs && node scripts/test-web-auth.mjs && node scripts/test-web-auth-ui.mjs && node scripts/test-web-pro.mjs && node scripts/test-pro-preflight.mjs && node scripts/test-pro-runtime.mjs && node scripts/test-pro-team.mjs && node scripts/test-pro-ui.mjs && node scripts/test-interrupt.mjs && node scripts/test-terminal-lifecycle.mjs && node scripts/test-persistence.mjs && node scripts/test-resilience.mjs && node scripts/test-approval-timeout.mjs && node scripts/test-approval-hardening.mjs && node scripts/test-approval-extreme.mjs && node scripts/test-approval-reason.mjs",
+    "test": "npm run build && node scripts/test-paste.mjs && node scripts/test-mouse.mjs && node scripts/test-cursor.mjs && node scripts/test-selection.mjs && node scripts/test-drag-scroll.mjs && node scripts/test-selection-performance.mjs && node scripts/test-copy.mjs && node scripts/test-scrollbar.mjs && node scripts/test-render.mjs && node scripts/test-drift.mjs && node scripts/test-sanitize.mjs && node scripts/test-markdown.mjs && node scripts/test-wrap.mjs && node scripts/test-fetch.mjs && node scripts/test-compact.mjs && node scripts/test-history-fold.mjs && node scripts/test-web-history.mjs && node scripts/test-session-migration.mjs && node scripts/test-web-session-migration.mjs && node scripts/test-web-default.mjs && node scripts/test-turn-fold.mjs && node scripts/test-long-turn.mjs && node scripts/test-plan.mjs && node scripts/test-subagent.mjs && node scripts/test-web-settings.mjs && node scripts/test-model-intensity.mjs && node scripts/test-background.mjs && node scripts/test-background-lifetime.mjs && node scripts/test-web-markdown.mjs && node scripts/test-web-i18n.mjs && node scripts/test-web-workspaces.mjs && node scripts/test-tools.mjs && node scripts/test-approval.mjs && node scripts/test-approval-review.mjs && node scripts/test-approval-ui.mjs && node scripts/test-web-approval-details.mjs && node scripts/test-approval-mode.mjs && node scripts/test-approval-context.mjs && node scripts/test-settings-render.mjs && node scripts/test-approval-flow.mjs && node scripts/test-web.mjs && node scripts/test-web-settings-http.mjs && node scripts/test-web-lan.mjs && node scripts/test-web-auth.mjs && node scripts/test-web-auth-ui.mjs && node scripts/test-web-pro.mjs && node scripts/test-pro-preflight.mjs && node scripts/test-pro-runtime.mjs && node scripts/test-pro-team.mjs && node scripts/test-pro-ui.mjs && node scripts/test-interrupt.mjs && node scripts/test-terminal-lifecycle.mjs && node scripts/test-persistence.mjs && node scripts/test-resilience.mjs && node scripts/test-approval-timeout.mjs && node scripts/test-approval-hardening.mjs && node scripts/test-approval-extreme.mjs && node scripts/test-approval-reason.mjs",
     "prepare": "npm run build",
     "web": "node dist/bin.js web"
   },

package/web/README.md

@@ -19,11 +19,13 @@ A small, dependency-free single page app that is served by the Neutrino CLI at
   access;
 - switch the interface between English and 简体中文, instantly and persistently;
 - open the same plan / token card as the terminal's `ⓘ`, clear a conversation,
-  delete a saved transcript, and review other agents' read-only history;
+  delete a saved transcript, and review or migrate other agents' history;
 - drive the running conversation: pause / resume the current turn and send new
   messages (they queue while the agent is busy);
 - pick up a saved conversation in the browser and keep chatting, even when no
-  terminal is running.
+  terminal is running;
+- run the console as a detached background service, so conversations started in
+  the browser survive closing the terminal and the CLI process.
 
 Nothing needs to be built — these are plain `.html`, `.css` and `.js` files.
 
@@ -40,6 +42,10 @@ permanently in the terminal's **Settings → Web console**. LAN access can be
 switched on and off at any time in the browser's **Settings → Web access**
 without restarting anything.
 
+To keep the console alive after the terminal exits, turn on **Settings →
+Background residency** in either workspace, or use `neutrino background` — see
+[Background residency](#background-residency).
+
 Or serve only the saved history, without a terminal:
 
 ```sh
@@ -50,6 +56,44 @@ npm run web
 
 Then open <http://127.0.0.1:8765>.
 
+## Background residency
+
+Background residency is off by default. It is a property of the process, so the
+regular and Pro workspaces share it; changing it in either page (or in the
+terminal's **Settings → Background residency**) applies immediately, including
+to browser tasks already in progress.
+
+With it on, closing the terminal or exiting the CLI does not interrupt browser
+conversations. With it off, the console follows its attached terminals and lets
+current browser tasks finish before it shuts down. The terminal's own
+conversations remain local to the terminal. Terminal and standalone launches
+share one Web console; a standalone launch reports a conflict if its requested
+port, interface or password setting differs from the running console. A ready
+service can be managed without a terminal:
+
+```sh
+neutrino background start     # detach the web console
+neutrino background status    # show its pid and address
+neutrino background open      # open it in the default browser
+neutrino background stop      # stop it
+```
+
+On Windows the service adds a notification-area icon using the same orbit badge
+as the regular console's top-left logo. Click it to open the console; its menu
+opens or stops the service. `--no-tray` suppresses it, and `NEUTRINO_NO_TRAY=1`
+does the same for automation. The service records its pid, address and a random
+management token in `~/.neutrino/background.json` (mode `0600`) and appends
+startup/stop diagnostics to `~/.neutrino/background.log`. The token protects
+`/api/background/ping` and `/api/background/stop`; it is never sent to a
+browser.
+
+When a console is mounted by the terminal and the setting is off, the first
+browser to open it is offered **建议开启后台常驻，避免误触中断任务** with a
+highlighted **开启** and **取消**. Either answer consumes the invitation for
+that CLI run — a reload does not ask again. **开启** applies immediately to the
+current browser tasks. The invitation is never shown when residency is already
+on or by a bare `neutrino web` server.
+
 ## Using it from another device
 
 The server binds to loopback by default. To open it from your phone or another
@@ -193,15 +237,16 @@ removed can still be continued.
 The **Settings** (gear) button in the sidebar opens the interface language,
 plan-first turns, the default approval mode, defaults for new conversations, the
 context compression threshold, the approval reviewer model, sound alerts, the
-extreme-risk automatic approval option, LAN access, and the Web password. Save
-settings explicitly; cancelling leaves the saved values intact. Conversation
-model changes are separate from these defaults. Models come from the same
-catalog as the terminal, and API keys stay on the server. Configure missing keys
-in the terminal model screen first. Intensity uses the same Low–Ultra sampling
-settings as the terminal, and both only offer the levels the selected model
-declares in `model.json`. The regular and [Pro](#pro-workspace) workspaces keep
-their own copy of every setting here except the approval policy, the Web password
-and LAN access, which belong to the whole process.
+extreme-risk automatic approval option, background residency, LAN access, and
+the Web password. Save settings explicitly; cancelling leaves the saved values
+intact. Conversation model changes are separate from these defaults. Models come
+from the same catalog as the terminal, and API keys stay on the server. Configure
+missing keys in the terminal model screen first. Intensity uses the same
+Low–Ultra sampling settings as the terminal, and both only offer the levels the
+selected model declares in `model.json`. The regular and [Pro](#pro-workspace)
+workspaces keep their own copy of every setting here except the approval policy,
+the Web password, LAN access and background residency, which belong to the whole
+process.
 
 ## New conversations and working directories
 
@@ -272,6 +317,14 @@ the complete transcript in the conversation pane with a `read-only` badge. The
 sources are the same as the terminal's history browser; OpenCode requires Node.js
 22.13+ because it reads its SQLite database through `node:sqlite`.
 
+Click **Migrate session** at the bottom right of an opened transcript to convert
+its readable user/assistant text into a new, saved Neutrino conversation. The
+copy opens immediately in the same working directory, using the current
+Neutrino model (or the current Pro preset on `/pro`). The source is unchanged.
+Foreign system prompts, tool records and non-text attachments are not imported.
+The button is disabled while copying; a failed migration leaves the source open
+with an error so you can retry.
+
 ## Plan-first turns
 
 A browser-owned turn is planned before it runs, exactly like a turn in the
@@ -328,13 +381,17 @@ to know whether a conversation is driven by the terminal or by the server.
 | GET | `/api/fs?path=…` | Folder listing for the picker (folders only, roots, parent) |
 | POST | `/api/fs/mkdir` | Create `{ "path": "…" }` and return the new path |
 | POST | `/api/conversations` | Start `{ cwd, selection?, approval_mode? }`, returns `{ key, snapshot }` |
-| GET | `/api/settings` | Model catalog (each model lists its supported intensities), languages, public settings, and the live bind address (`web_host`, `web_urls`); no credentials |
-| POST | `/api/settings` | Save validated `{ selection?, settings? }`, including `language`, `plan_first`, `approval_mode`, `web_lan` and `web_password` |
+| GET | `/api/settings` | Model catalog (each model lists its supported intensities), languages, public settings, the live bind address (`web_host`, `web_urls`) and the background state (`background`, `background_running`, `background_url`, one-time `background_prompt`); no credentials |
+| POST | `/api/settings` | Save validated `{ selection?, settings? }`, including `language`, `plan_first`, `approval_mode`, `web_lan`, `background` and `web_password` |
+| POST | `/api/background/dismiss` | Consume the one-time background-residency invitation for this console run |
+| GET | `/api/background/ping` | Management probe of a detached service; requires `Authorization: Bearer <background.json token>` |
+| POST | `/api/background/stop` | Ask a detached service to shut down; same bearer token |
 | GET | `/api/session/:id` | One saved transcript |
 | POST | `/api/session/:id/continue` | Resume a transcript with optional `{ selection }`, returns `{ key }` |
 | POST | `/api/session/:id/delete` | Delete a saved, non-running transcript |
 | GET | `/api/agents/:agent/sessions?cwd=…` | Read-only sessions from Claude Code / Codex / OpenCode |
 | GET | `/api/agents/:agent/sessions/:id` | Read-only messages of one other-agent session |
+| POST | `/api/agents/:agent/sessions/:id/migrate` | Copy a source in `cwd` into a saved native conversation and return its live key; accepts optional `selection` or Pro `pro_preset` |
 | GET | `/api/live/:key` | Snapshot of a live session |
 | GET | `/api/live/:key/stream` | SSE stream of a live session |
 | POST | `/api/live/:key/pause` | Pause the running turn |
@@ -351,7 +408,10 @@ to know whether a conversation is driven by the terminal or by the server.
 
 Conversation and settings routes require the login cookie; see
 [Authentication](#authentication). `OPTIONS` is answered unauthenticated so
-preflights are not blocked, and it returns no data.
+preflights are not blocked, and it returns no data. The `/api/background/*`
+management routes are the exception: they exist only in a detached service and
+authenticate with the bearer token from `background.json`, because the CLI and
+the tray icon have no browser cookie.
 
 ### Approval requests