@xingjisoft/neutrino 0.1.7 → 0.2.0

package/README.md

@@ -17,10 +17,12 @@ A CLI coding agent that lives in your terminal. Neutrino gives you an interactiv
 - **Session history** — messages are saved before a turn starts, streamed replies are checkpointed every second, and tool calls/results are saved immediately. The history screen lists conversations started in the current working directory. Failed saves are shown in the terminal and browser UI.
 - **Auto-folding turns** — once a turn finishes, the work behind the reply (the thinking and the tool calls) folds into one summary line in both the terminal and the browser, while the answer itself always stays on screen. Click the line to read the whole round again; a turn with little to hide, or a long answer on its own, stays open. A turn stopped with `ESC ESC` is paused, not finished, so it stays open. Nothing is dropped: the transcript, the saved session and the model's context keep every message.
 - **Complete conversation history** — context compression keeps every original message and tool result on disk. The earlier portion starts collapsed in the terminal and browser; click **Earlier conversation** to expand it, including in reopened history. Model requests use a separate summary plus recent messages.
-- **Token usage stats** — click the `ⓘ` in the chat header to see prompt/completion/total token counts for the current session.
+- **Plan-first turns** — before a request is answered, a planner agent splits it into ordered, independent steps ("model the case from box.png", "animate the camera: push in, orbit, pull back"), and the worker then executes those steps one at a time, top to bottom. Every step is a concrete deliverable, so later work is explicit instead of one vague instruction. See [Plan-first turns](#plan-first-turns).
+- **The step card** — click `ⓘ` in the chat header (or press `Ctrl+P`) to open the info card in the top-right corner. It lists the plan as a vertical timeline of nodes: the step being worked on is highlighted, steps still to come are lit, and finished steps are drawn dark with a tick. The same card shows prompt/completion/total token counts when no plan is running.
+- **Sub-agents** — independent work can be handed to a sub-agent: a second agent loop with its own context, its own tool calls and the same approval gate. Only its report comes back, so a survey that reads thirty files does not fill the conversation with thirty files. See [Sub-agents](#sub-agents).
 - **Agent history browser** — view past sessions from other CLI agents (Claude Code, Codex, OpenCode) directly from the history screen.
 - **Approval gate** — risky commands and paths outside the working directory need your sign-off. The header turns orange and reads **Request Approval**; press `Y` or `N`. Delete-class commands always ask, unless you explicitly granted full trust, and there is an opt-in reviewer agent for automatic decisions.
-- **Browser UI on any port** — mount a local website that lists every saved conversation grouped by working directory, streams the running one in real time, and lets you pause/resume it, send messages, switch provider/model/intensity, and edit settings from the browser.
+- **Browser UI on by default** — every `neutrino` launch also mounts a local website at <http://127.0.0.1:8765> that lists every saved conversation grouped by working directory, streams the running one in real time, and lets you pause/resume it, send messages, switch provider/model/intensity, and edit settings from the browser. Use `--port`/`--host` to move it, `--lan` to share it, or `--no-web` to keep the terminal only.
 
 ## Requirements
 
@@ -50,6 +52,8 @@ neutrino
 ```
 
 Type a message on the start screen and press `Enter` to begin a new chat.
+The browser UI is mounted at <http://127.0.0.1:8765> at the same time; see
+[Web UI](#web-ui) below for `--port`, `--lan` and `--no-web`.
 
 ### Keys
 
@@ -66,7 +70,8 @@ Type a message on the start screen and press `Enter` to begin a new chat.
 | `Ctrl+C` | Do nothing while text is selected; otherwise pause the running conversation or show the exit hint at the top |
 | `Ctrl+C` × 3 | Quit after three consecutive presses, no more than 1.5 seconds apart (another key, paste, click or scroll resets the count) |
 | `Ctrl+Shift+C` | Quit immediately (requires the terminal to forward the shortcut) |
-| `Ctrl+A` | Toggle Request Approval / Auto Approval in a conversation |
+| `Ctrl+A` | Toggle Request Approval / Auto Approval in a conversation |
+| `Ctrl+P` | Toggle the plan / token info card in the top-right corner |
 | `Y` | Approve the pending request (while the approval card is up) |
 | `N` / `Esc` | Deny the pending request |
 | `Ctrl+Q` | Quit |
@@ -83,7 +88,7 @@ Type a message on the start screen and press `Enter` to begin a new chat.
 | Click and drag | Select text under the rectangle; releasing copies it to the clipboard |
 | Drag onto the first/last row of the log | Scroll the log a line at a time (faster the longer you hold it) and keep growing the selection past the screen |
 | Click the header (left of `ⓘ`) | Open the model selector |
-| Click `ⓘ` (chat header) | Toggle token usage stats |
+| Click `ⓘ` (chat header) | Toggle the plan / token info card |
 | Drag the scrollbar | Grab the thumb on the right edge of the chat/log and drag it to scroll |
 | Scroll wheel | Scroll the chat/log, or move through lists |
 | Right-click | Go back (like `Esc`) |
@@ -96,13 +101,78 @@ highlight stops at the log's edge instead of spilling into the header or the
 input box, and the copy includes the lines that scrolled out of view. Scroll back
 and the selection shrinks again; press `Esc` to drop it.
 
+## Plan-first turns
+
+A request is answered in two passes. A **planner agent** first turns the message
+into an ordered list of independent steps; a **worker agent** then executes
+exactly one step per pass, from the top down. Each step names one deliverable, so
+a long request stops being a single vague instruction and becomes a sequence of
+concrete, verifiable ones. The plan is written into the conversation as a
+message and saved with the session, so the steps of a reopened conversation are
+still there.
+
+The steps are also listed in the `ⓘ` card in the top-right corner of the chat —
+click it, or press `Ctrl+P`:
+
+- nodes run top to bottom in execution order, joined by a connector,
+- the step being worked on is the highlighted row,
+- steps still to come are lit, and
+- finished steps are drawn dark with a tick; a failed one is marked in red.
+
+The card opens by itself as soon as a plan is written, and closing it loses
+nothing: `Ctrl+P` brings it back. On a short terminal the card shows a window
+around the running step and counts the steps above and below it.
+
+A step that fails stops the plan: the remaining steps stay pending and the next
+message can re-plan them. A turn paused with `Esc Esc` stops the plan and marks
+it **stopped**, so no step keeps looking live. When no usable plan comes back —
+a single-action request, a provider error, an answer that is not a plan — the
+turn runs in one pass exactly as before, so planning is never a new way to fail.
+
+The prompts are files, not code: [`assets/planner.txt`](./assets/planner.txt)
+says how steps are written, [`assets/step.txt`](./assets/step.txt) is the
+instruction for each step, and [`assets/prompt.txt`](./assets/prompt.txt) is the
+worker's base system prompt. Turn planning off for one run with
+`NEUTRINO_PLAN=off`, or permanently with `"plan_first": false` in `config.json`.
+
+## Sub-agents
+
+The agent can hand one self-contained sub-task to a **sub-agent**: a second agent
+loop with its own transcript, its own tool calls and the same working directory.
+Only its final report comes back — the files it read and the commands it ran
+never enter the main conversation. That is the point: surveying a large codebase
+or probing how a command behaves costs many messages, and the parent needs the
+conclusion, not the transcript. The child's tokens still count in the
+conversation's usage.
+
+- The parent calls the `delegate` tool with a complete task and, optionally, a
+  little context. The sub-agent cannot see the conversation and cannot ask the
+  user, so a task that refers to "the file above" fails; the system prompt tells
+  the model to write a brief that stands alone.
+- Its tool calls go through the **same approval gate**: a risky call parks the
+  turn and shows the usual card (the header turns orange, the browser shows its
+  banner). Denying it tells the sub-agent not to retry unchanged, and the parent
+  receives the refusal in the report.
+- Delegation is one level deep — `delegate` is not in a sub-agent's toolset — so
+  the work always has one owner and one pause button.
+- While it runs, the terminal status line and the browser badge name the current
+  phase (`Sub-agent — read_file`), and the `delegate` tool block shows the task
+  it was given. The report replaces that marker when it arrives, as the result of
+  the tool call.
+- The round limit (12) bounds a child that never finishes; the parent then gets
+  the partial report, clearly marked as partial. A paused turn aborts the
+  sub-agent and says so in the tool result.
+
+The sub-agent's prompt is a file too: [`assets/subagent.txt`](./assets/subagent.txt).
+
 ## Configuration
 
 Settings are stored under `~/.neutrino/`:
 
 - `model.json` — provider and model definitions (edit to add your own endpoints).
 - `config.json` — app configuration (selected provider/model/intensity, theme,
-  language, approval mode, `auto_approve_extreme_risk`, `sound_alerts`).
+  language, approval mode, `auto_approve_extreme_risk`, `sound_alerts`,
+  `web_console`).
 - `session/` — saved conversation sessions, one JSON file per session.
 
 Set your API key in the model select screen or directly in `model.json`.
@@ -111,8 +181,11 @@ A few environment variables override flags:
 
 | Variable | Effect |
 | --- | --- |
-| `NEUTRINO_WEB_PORT` | Web UI port: like `--web-port` in TUI mode, and the port in `neutrino web`. |
-| `NEUTRINO_WEB_HOST` | Interface to bind, like `--host`. |
+| `NEUTRINO_WEB_PORT` | Web UI port: like `--port` in either mode, and it mounts the UI even when `web_console` is off. |
+| `NEUTRINO_WEB_HOST` | Interface to bind, like `--host`; also mounts the UI when `web_console` is off. |
+| `NEUTRINO_NETWORK_ATTEMPTS` | Total tries for a model request that keeps dropping (default 7). |
+| `NEUTRINO_RETRY_DELAY_MS` | Wait before the first retry in ms; each retry doubles it (default 5000). |
+| `NEUTRINO_PLAN` | `off` answers a request in one pass without planning it (overrides `plan_first`); `on` forces planning. |
 
 ### Approvals
 
@@ -210,11 +283,11 @@ Only sessions that were started in the current working directory are listed, so
 
 ## Web UI
 
-Neutrino can mount a small website on a port of your choice. It groups every
-saved conversation by working directory (showing the five newest per path with
-the rest collapsed), folds the work of every finished turn into one summary line
-that opens on a click while the reply stays on screen, streams a running
-conversation live, and lets you pause or
+Neutrino mounts a small website at <http://127.0.0.1:8765> whenever the
+terminal UI starts. It groups every saved conversation by working directory
+(showing the five newest per path with the rest collapsed), folds the work of
+every finished turn into one summary line that opens on a click while the reply
+stays on screen, streams a running conversation live, and lets you pause or
 resume it and send new messages from the browser.
 
 A saved transcript opens read-only, because nothing is running for it. Press
@@ -225,7 +298,7 @@ the same session file.
 
 Use the selectors above a conversation to change its provider, model or
 intensity, then press **Apply to conversation** (pause an active turn first).
-The **⚙ Settings** button in the sidebar edits defaults for new conversations,
+The **Settings** (gear) button in the sidebar edits defaults for new conversations,
 context compression and approval settings. Conversation choices are saved with
 the transcript and do not overwrite the defaults. Configured models and keys
 are shared with the terminal; keys stay on the server.
@@ -238,8 +311,12 @@ to future turns in active conversations. The legacy fixed
 `context_compress_threshold` setting is no longer used.
 
 ```sh
-# Mount the web UI while the terminal UI runs
-neutrino --web-port 8765
+# The terminal UI now brings the web UI up with it
+neutrino
+
+# Pick a different port or interface
+neutrino --port 9000
+neutrino --host 100.64.0.7
 
 # Or serve only the saved history, with no terminal
 neutrino web --port 8765
@@ -248,6 +325,12 @@ neutrino web --port 8765
 Then open <http://127.0.0.1:8765>. The site itself lives in [`web/`](./web) and
 needs no build step; see [`web/README.md`](./web/README.md) for the API.
 
+The console is on by default; turn it off for one run with `--no-web`, or
+permanently in the terminal's **Settings → Web console**. The `--web-port` flag
+is still accepted as an alias for `--port`. If the default port is already taken
+(usually by another Neutrino instance), the terminal UI starts anyway and prints
+how to choose another port.
+
 ### Reaching it from another device
 
 The server binds to loopback, so only this machine can open it. To use it from a
@@ -255,11 +338,13 @@ phone, a tablet or another box on your LAN or VPN, bind an interface others can
 see:
 
 ```sh
-neutrino web --port 8765 --lan          # every interface (0.0.0.0)
-neutrino --web-port 8765 --lan          # same, while the TUI runs
-neutrino web --port 8765 --host 100.64.0.7   # one specific address
+neutrino --lan                          # TUI + web UI on every interface (0.0.0.0)
+neutrino --host 100.64.0.7              # TUI + web UI on one specific address
+neutrino web --port 8765 --lan          # headless web UI on every interface
 ```
 
+`--lan` is shorthand for `--host 0.0.0.0`; the two cannot be combined.
+
 Startup prints every address that works, so you can copy the one matching the
 device you are on:
 
@@ -274,7 +359,9 @@ Open the address that matches your device:
 Open the address and sign in with your permanent Web password. The initial
 password is **`114514`**. Change it in the browser's **Settings → Web access**
 or in the terminal's **Settings → Web password**. It is saved as a salted hash
-in `~/.neutrino/config.json` and survives restarts.
+in `~/.neutrino/config.json` and survives restarts. While the site is running,
+its address is also shown in the terminal header and in the terminal's
+**Settings → Web console** row, which can start or stop it without a restart.
 
 For automatic login, open `http://<host>:8765/?pwd=114514`. The page checks the
 password, remembers the login, and removes `pwd` from the address bar. If it is
@@ -292,8 +379,8 @@ and startup output never contain your password or session credentials.
 - **Firewall:** the first bind to `0.0.0.0` triggers an allow prompt on Windows
   and macOS. Allow it for private networks, and check that your WLAN is not
   marked "public", where incoming connections are blocked anyway.
-- **`127.0.0.1` remains the default** because the zero-config case should not be
-  a network service.
+- **`127.0.0.1` is still the default interface.** The console starts with the
+  terminal UI, but it is not a network service until you pass `--host`/`--lan`.
 
 ## Built-in tools
 
@@ -302,7 +389,8 @@ The agent can call the following tools during a conversation:
 - `run_command` — execute a shell command (120s timeout, output capped).
 - `read_file` — read a text file (capped at 200KB).
 - `write_file` — write content to a file.
-- `list_files` — list directory contents.
+- `list_files` — list directory contents.
+- `delegate` — hand one self-contained sub-task to a sub-agent and return its report.
 
 Every tool takes an additional `reason` argument: one sentence saying what the
 call is for and why it is needed now. It is what the approval card shows and what
@@ -332,11 +420,14 @@ node scripts/test-render.mjs     # fuzz the diff renderer + render the chat scre
                                  # asserting no stale/residual cells are left behind
 node scripts/test-sanitize.mjs   # verify ANSI/control codes never reach the screen
 node scripts/test-drift.mjs      # verify the input area self-heals after terminal drift
-node scripts/test-fetch.mjs      # verify streamed requests release aborts and retry drops
+node scripts/test-fetch.mjs      # verify streamed requests release aborts, retry drops and the 7-attempt backoff
 node scripts/test-compact.mjs    # verify context-compression planning
 node scripts/test-history-fold.mjs # verify full-history retention, folding and resume
 node scripts/test-web-history.mjs  # verify browser history disclosures and streaming state
-node scripts/test-turn-fold.mjs    # verify folded turns keep their reply and every message
+node scripts/test-web-default.mjs  # verify the web console starts and toggles by default
+node scripts/test-turn-fold.mjs    # verify folded turns keep their reply and every message
+node scripts/test-plan.mjs         # verify plan-first turns, step order, the step card and the fallback
+node scripts/test-subagent.mjs     # verify delegation: isolation, approvals, abort, round limits
 node scripts/test-tools.mjs      # verify tool-output folding
 node scripts/test-web.mjs        # verify the web server, API, SSE stream and path-traversal guards
 node scripts/test-web-settings.mjs # verify model switching, persistence, browser controls and defaults
@@ -359,11 +450,28 @@ A cell's glyph is copied straight into the output stream, so a cell holding a *c
 
 ### Network resilience
 
-Model responses arrive over a streamed connection that can drop at any point. A single blip should not end the session, so three cases are handled:
+Model responses arrive over a streamed connection that can drop at any point. A single blip must not end the session — a turn is minutes of work, and a proxy that resets an idle socket says nothing about the user's task — so a failed request is retried before anything is given up:
+
+| Attempt | Wait before it |
+| --- | --- |
+| 1 | — |
+| 2 | 5s |
+| 3 | 10s |
+| 4 | 20s |
+| 5 | 40s |
+| 6 | 80s |
+| 7 | 2m 40s |
+
+That is seven tries and roughly five minutes in total, doubling every time: a link that is merely flaky recovers long before the budget is spent, while a link that is genuinely down is not hammered. `NEUTRINO_NETWORK_ATTEMPTS` and `NEUTRINO_RETRY_DELAY_MS` tune both numbers. The policy lives in `src/llm/retry.ts`.
+
+What counts as worth retrying:
+
+- **Connection failures** — a reset (`ECONNRESET`), a refused or unreachable socket, `EPIPE`, DNS (`EAI_AGAIN`), a connect timeout, and undici's `UND_ERR_*` codes.
+- **A stream that dies before the first byte** — the server or a proxy closed the connection mid-flight (`TypeError: terminated`, `other side closed`, `socket hang up`, …). Nothing has reached the user, so the request is simply re-issued.
+- **A transient HTTP status** — 408/425, 429 and 5xx (502/503/504 from a load balancer, 529 "overloaded"). A bad request is different: 400/401/403/404/422 surface on the first answer, because re-sending them only delays the real message.
+- **A stream that dies after output has started** is *not* retried: replaying it would duplicate the reply, so the error is surfaced with the real reason expanded out of the `error.cause` chain (`fetch failed` alone says nothing useful) and the partial text is kept.
 
-- **The request never goes out** (`fetch` rejects) — retried a couple of times with a short backoff, bounded by a connect timeout.
-- **The stream dies before the first byte** — the server or a proxy closed the connection mid-flight (`TypeError: terminated`, `other side closed`, …). Nothing has reached the user, so the request is simply re-issued.
-- **The stream dies after output has started** — retrying would duplicate text, so the error is surfaced instead, with the real reason expanded out of the `error.cause` chain (`fetch failed` alone says nothing useful).
+A retry can leave the stream silent for up to 160s, so it is never silent *about* being silent: the terminal status line and the web badge name the attempt and the delay ("Network hiccup — retrying in 40s (attempt 4/7)"). The wait is also polled, so pausing the turn, sending a newer message or quitting drops it immediately instead of sitting out the backoff.
 
 Any stream the consumer walks away from (pause, or a newer turn taking over) always has its body cancelled, so sockets are not leaked.
 

package/assets/planner.txt

@@ -0,0 +1,35 @@
+You are Neutrino's planning agent.
+
+You execute nothing. You are given one user request, the project directory and
+the conversation so far, and you return the plan that a second agent will carry
+out. That agent has file, shell and network tools, and it is handed exactly one
+step at a time, so a step that is vague here becomes vague work there.
+
+Split the request into the fewest steps that can each be executed and verified on
+their own:
+
+- One step, one deliverable. "Model the case from box.png" is one step;
+  "model the case and light the scene" is two.
+- Name the concrete material: which reference image, which file, which command,
+  which output. A worker who has to guess guesses differently every run.
+- Order the steps the way the work has to happen: look at what already exists,
+  then create, then wire together, then verify (build, run, test, render).
+- End with the step that proves the whole result works, when the request allows
+  it.
+- Include only what the user asked for. Do not add features, styling or
+  refactors nobody requested, and do not invent files that are neither mentioned
+  nor obviously implied.
+- Between 2 and 8 steps. A single-action request returns one step and runs as a
+  normal turn.
+- When the user supplied exact wording — camera moves, copy, timings, a script —
+  keep it verbatim in that step's detail.
+- Write every title in the same language as the user's request, as an imperative
+  action of at most about 80 characters.
+- Add "detail" only when the step needs it: paths, parameters, acceptance
+  criteria or the user's own wording. Keep it to one line of about 200
+  characters or less.
+
+Answer with JSON only. No prose, no explanation, no code fence:
+
+{"goal": "one line restating what the user wants",
+ "steps": [{"title": "the action", "detail": "optional material for the step"}]}

package/assets/prompt.txt

@@ -1,24 +1,59 @@
-You are XINGJI Neutrino, a powerful CLI-based AI coding assistant. Your capabilities include:
+You are XINGJI Neutrino, an AI engineering agent working inside the user's
+project on the user's machine. You read and edit files and run commands: the
+work is done when the files are changed and the result is verified, not when it
+is described.
 
-1. **Code Generation**: Write clean, efficient, and well-structured code in any programming language.
-2. **File Operations**: Read, create, edit, and manage files in the user's project.
-3. **Command Execution**: Run shell commands to build, test, lint, and deploy code.
-4. **Code Review**: Analyze code for bugs, security issues, and performance problems.
-5. **Refactoring**: Suggest and implement code improvements and restructuring.
-6. **Debugging**: Help identify and fix issues in codebases.
-7. **Documentation**: Generate clear and comprehensive documentation.
-
-Guidelines:
-- Always understand the full context before making changes.
-- Follow existing code style and conventions in the project.
-- Write robust, production-quality code with proper error handling.
-- Prefer simple, readable solutions over complex ones.
-- When suggesting changes, explain the reasoning.
-- Use the tools available to you to explore the codebase before making changes.
-- Verify your changes by running tests and linting when possible.
+## How you work
+- Your work is planned before it starts. When a turn carries a plan you are given
+  exactly one step of it: do that step, verify it, and stop. Never start a later
+  step, and never redo an earlier one.
+- Without a plan, state the numbered steps you are about to take in your first
+  message, then take them in that order.
+- Look before you change: read the files you are about to edit, list the
+  directory, run the command that shows the current state. Anything about the
+  code you have not read is a guess, and guesses are the main source of bad
+  patches.
 - Every tool call must carry a `reason` argument: one honest sentence saying what
-  the call is for and why it is needed for the current request. It is what the
-  user sees when the call needs approval, and a call that needs approval but gives
-  no reason is refused instead of run.
+  the call is for and why the current request needs it. It is what the user sees
+  when the call needs approval, and a call that needs approval but gives no
+  reason is refused instead of run. Never claim in it that the user already
+  approved something.
+- Keep the change minimal and in the project's own style: reuse the existing
+  helpers, match the surrounding naming and formatting, and do not reformat or
+  restructure code you were not asked to touch.
+- Verify what you did: run the build, the tests, or the command whose output
+  proves the result. Do not report success you have not seen, and never invent
+  command output.
+- When something cannot be done, say so plainly with the error or the missing
+  piece, instead of quietly improvising a different task.
+
+## Sub-agents
+- Delegate work that is independent and whose exploration would crowd this
+  conversation: surveying a large codebase, checking how a library or a command
+  really behaves, or one self-contained piece of implementation. The `delegate`
+  tool runs such work in a fresh context and returns only its report, so the
+  files it reads never fill this conversation.
+- Write the task so it stands alone: the sub-agent cannot see this conversation
+  and cannot ask a question. Say what to do, where (paths, references), and what
+  "done" looks like; do not bury it in a list of steps unless the order matters.
+- Its risky calls still go to the user's approval gate, and it cannot delegate
+  further. Treat its report as evidence: quote what it found, and check anything
+  the result depends on before you rely on it.
+
+## Quality bar
+- Production quality: real error handling, no placeholders, no TODOs, no "left as
+  an exercise", no stubbed-out functions, no fake data standing in for the real
+  thing.
+- Prefer the simplest solution that fully works; do not add configuration,
+  options or abstraction that nothing asked for.
+- Never print secrets or API keys, and never write them into a file that is not
+  meant to hold them.
+- Do not delete or overwrite the user's data without a reason the user can see.
 
-Language: Always respond in the same language the user writes in.
+## Answering
+- Answer in the language the user writes in.
+- Be specific and short: what changed (paths), what proves it (command, test,
+  render), what is still open. Skip the description of the process unless it is
+  needed to continue the work.
+- If something is ambiguous in a way that changes the result, ask one precise
+  question instead of guessing silently.

package/assets/step.txt

@@ -0,0 +1,14 @@
+You are executing step {{index}} of {{total}} of the plan below. Do this step
+and nothing else: no later step, and no rewriting of earlier ones. Stop as soon
+as this step is finished and verified.
+
+Plan agreed with the user:
+{{plan}}
+
+Current step {{index}}: {{step}}
+{{detail}}
+
+End with one short paragraph: what you did, which files changed, and the evidence
+(command output, test result, render) that shows it works. If the step cannot be
+done as written, say precisely what blocks it instead of doing something else —
+the user sees this and can re-plan.

package/assets/subagent.txt

@@ -0,0 +1,20 @@
+You are a sub-agent. Another agent working with the user delegated one
+self-contained task to you; it cannot see your messages, and the only thing it
+receives from you is your final message.
+
+Rules:
+- Do the task with the tools you have, in the working directory you are given.
+  You cannot ask the user a question: when something is missing, do what can be
+  done and say precisely what is missing.
+- You have no sub-agents of your own, and you must not try to delegate.
+- Look before you change: read the files you are about to edit and run the
+  command that shows the current state.
+- Risky calls still need the user's approval, exactly as for the parent agent.
+  If one is denied, do not retry it unchanged — work around it or report it as
+  blocked.
+- Verify what you did with a command whose output you can quote. Do not report
+  success you have not seen, and never invent command output.
+- Your final message is your report: what you did, the files you touched, the
+  commands you ran and what their output proved, and anything left unfinished or
+  blocked. Be factual and short — no preamble, no restating of the task.
+- Answer in the same language as the task.

package/dist/app.js

@@ -90,6 +90,8 @@ export class App {
     selOffset = null;
     resizeHandler = () => this.onResize();
     webHandle = null;
+    /** Where the web UI lives; kept even while it is switched off. */
+    webOptions = { port: 8765, auth: true };
     constructor() {
         this.width = process.stdout.columns || 80;
         this.height = process.stdout.rows || 24;
@@ -119,6 +121,13 @@ export class App {
         this.state.selectedModelApiKey = String(config.selected_model_api_key ?? this.state.selectedModelApiKey);
         this.state.selectedModelStreaming = Boolean(config.selected_model_streaming ?? true);
     }
+    /**
+     * Remember where the browser UI should listen. Called at startup even when
+     * the console is disabled, so Settings can mount it later without guessing.
+     */
+    configureWeb(port, host, auth) {
+        this.webOptions = { port, host, auth };
+    }
     /**
      * Mount the browser UI on the given port. Safe to call once; subsequent calls
      * return the already-running server.
@@ -126,8 +135,40 @@ export class App {
     async enableWeb(port, host, auth = true) {
         if (this.webHandle)
             return this.webHandle;
-        this.webHandle = await startWebServer({ port, host, auth });
-        return this.webHandle;
+        this.webOptions = { port, host, auth };
+        const handle = await startWebServer({ port, host, auth });
+        this.webHandle = handle;
+        this.state.webUrl = handle.url;
+        return handle;
+    }
+    /**
+     * Start or stop the browser UI while the terminal keeps running. Returns a
+     * result instead of throwing so a failed bind (usually a port already in use)
+     * can be reported inline without an unhandled rejection.
+     */
+    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}`);
+                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;
+        this.state.webUrl = null;
+        this.render();
+        await handle?.close();
+        this.showToast("Web console stopped");
+        return { ok: true };
     }
     async start() {
         // Installed before anything touches the terminal: from here on, a crash
@@ -752,6 +793,7 @@ export class App {
         screen.loadedTokens = data.tokens ?? null;
         screen.loadedContext = data.context ?? null;
         screen.loadedApprovalMode = data.approval_mode ?? null;
+        screen.loadedPlan = data.plan ?? null;
         if (data.provider)
             this.state.selectedProvider = data.provider;
         if (data.model)

package/dist/bin.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 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";
 const DEFAULT_WEB_PORT = 8765;
@@ -31,25 +32,28 @@ function printHelp() {
     process.stdout.write(`Neutrino
 
 Usage:
-  neutrino                     Start the terminal UI.
-  neutrino --web-port <port>   Start the terminal UI and mount the web UI.
+  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).
 
 Options:
-  -p, --port <port>   Web server port (web mode). Default: ${DEFAULT_WEB_PORT}
+  -p, --port <port>   Web UI port. Default: ${DEFAULT_WEB_PORT}
       --host <host>   Interface to bind. Default: 127.0.0.1
       --lan           Short for --host ${WILDCARD_HOST}: reachable from other
                       devices on your LAN or VPN.
+      --no-web        Do not start the web UI with the terminal UI.
       --no-auth       Serve without password login.
-      --web-port <n>  Also mount the web UI while the TUI runs.
+      --web-port <n>  Deprecated alias for --port while the TUI runs.
   -h, --help          Show this help.
 
 Environment:
-  NEUTRINO_WEB_PORT   Same as --web-port for the TUI, or the port in web mode.
+  NEUTRINO_WEB_PORT   Same as --port in either mode.
   NEUTRINO_WEB_HOST   Same as --host.
 
-The web UI can read every saved conversation and drive an agent with shell
-access, so it binds to loopback by default. Log in with the permanent password
+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
+read every saved conversation and drive an agent with shell access, so it binds
+to loopback unless you ask for --host/--lan. Log in with the permanent password
 (default: 114514). Change it in Settings. --no-auth disables password login.
 `);
 }
@@ -62,7 +66,7 @@ function requireValue(argv, index, flag) {
     return value;
 }
 function parseArgs(argv) {
-    const options = { mode: "tui", port: null, lan: false, noAuth: false };
+    const options = { mode: "tui", port: null, lan: false, noWeb: false, noAuth: false };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "web") {
@@ -89,6 +93,9 @@ function parseArgs(argv) {
         else if (arg === "--lan") {
             options.lan = true;
         }
+        else if (arg === "--no-web") {
+            options.noWeb = true;
+        }
         else if (arg === "--no-auth") {
             options.noAuth = true;
         }
@@ -103,6 +110,12 @@ function parseArgs(argv) {
     if (options.lan && options.host) {
         throw new Error("use either --lan or --host, not both");
     }
+    if (options.noWeb && options.mode === "web") {
+        throw new Error("--no-web cannot be used with the 'web' 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. */
@@ -140,10 +153,11 @@ catch (err) {
 installCrashGuard();
 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 ?? envPort() ?? DEFAULT_WEB_PORT;
+    const port = options.port ?? portFromEnv ?? DEFAULT_WEB_PORT;
     try {
         const handle = await startWebServer({ port, host, auth });
         reportAccess(handle);
@@ -166,15 +180,26 @@ else {
         process.exit(1);
     }
     const app = new App();
-    const webPort = options.port ?? envPort();
-    if (webPort !== null) {
+    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 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)) {
         try {
             const handle = await app.enableWeb(webPort, host, auth);
             reportAccess(handle);
         }
         catch (err) {
-            process.stderr.write(`neutrino: failed to start web server: ${err instanceof Error ? err.message : String(err)}\n`);
-            process.exit(1);
+            // 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");
         }
     }
     await app.start();