@xingjisoft/neutrino 0.1.7 → 0.2.1

package/dist/screens/settings.js

@@ -5,7 +5,7 @@ import { drawHeader } from "../header.js";
 import { centerVertically, drawHint } from "../ui.js";
 import { hashWebPassword } from "../web/auth.js";
 /** The settings that can be changed here, top to bottom. */
-const ROWS = ["intensity", "compress", "approval_model", "extreme_approval", "sound", "web_password"];
+const ROWS = ["intensity", "compress", "approval_model", "extreme_approval", "sound", "web_console", "web_password"];
 export class SettingsScreen extends Screen {
     intensityIdx = 2;
     contextTokens = DEFAULT_CONTEXT_WINDOW;
@@ -16,6 +16,10 @@ export class SettingsScreen extends Screen {
     extremeIdx = 0;
     /** 0 = silent, 1 = audible cue on turn end and on approval requests. */
     soundIdx = 1;
+    /** 0 = web UI off, 1 = mounted alongside the terminal. */
+    webIdx = 1;
+    /** Only a row the user actually touched rewrites the saved default. */
+    webChanged = false;
     models = [];
     rowIdx = 0;
     lastHoverX = -1;
@@ -38,6 +42,10 @@ export class SettingsScreen extends Screen {
         this.approvalModelIdx = approvalAt >= 0 ? approvalAt + 1 : 0;
         this.extremeIdx = config.auto_approve_extreme_risk === true ? 1 : 0;
         this.soundIdx = config.sound_alerts === false ? 0 : 1;
+        // A console started by an explicit flag is on even if the saved default is
+        // off, so reflect what is actually running first.
+        this.webIdx = (this.app.state.webUrl || config.web_console !== false) ? 1 : 0;
+        this.webChanged = false;
     }
     /** Change the value of a row by `delta` steps and persist it immediately. */
     cycle(row, delta) {
@@ -62,6 +70,15 @@ export class SettingsScreen extends Screen {
         else if (row === "sound") {
             this.soundIdx = this.soundIdx === 1 ? 0 : 1;
         }
+        else if (row === "web_console") {
+            this.webIdx = this.webIdx === 1 ? 0 : 1;
+            this.webChanged = true;
+            this.save();
+            // Mount or unmount immediately; a failed bind is shown as a toast and
+            // the saved preference stays on so the next launch tries again.
+            void this.app.setWebConsole(this.webIdx === 1);
+            return;
+        }
         else {
             const options = [...new Set([...CONTEXT_WINDOW_OPTIONS, this.contextTokens])].sort((a, b) => a - b);
             const i = options.indexOf(this.contextTokens);
@@ -209,6 +226,14 @@ export class SettingsScreen extends Screen {
                 label: "Sound alerts",
                 value: this.soundIdx === 1 ? "On (turn end, approvals)" : "Off",
             },
+            {
+                label: "Web console",
+                value: this.webIdx === 0
+                    ? "Off"
+                    : this.app.state.webUrl
+                        ? `On · ${this.app.state.webUrl}`
+                        : "On (not running)",
+            },
             {
                 label: "Web password",
                 value: this.editingPassword ? "*".repeat(Math.min(this.passwordDraft.length, 24)) || "Type new password" : this.passwordMessage,
@@ -244,6 +269,10 @@ export class SettingsScreen extends Screen {
         config.approval_model = this.approvalModelIdx === 0 ? "" : this.models[this.approvalModelIdx - 1] ?? "";
         config.auto_approve_extreme_risk = this.extremeIdx === 1;
         config.sound_alerts = this.soundIdx === 1;
+        if (this.webChanged) {
+            config.web_console = this.webIdx === 1;
+            this.webChanged = false;
+        }
         saveConfig(config);
     }
     render(buf) {

package/dist/state.js

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

package/dist/web/session.js

@@ -10,10 +10,12 @@
  * registers itself in the live hub, so the regular `/api/live/*` endpoints
  * (snapshot, stream, pause, resume, message) work unchanged.
  */
-import { findModel, contextCompressionThreshold, loadConfig, normalizeApprovalMode, loadModels, loadPrompt, saveSession, } from "../config.js";
+import { findModel, contextCompressionThreshold, loadConfig, loadPlannerPrompt, loadStepPrompt, loadSubAgentPrompt, normalizeApprovalMode, planFirstEnabled, loadModels, loadPrompt, saveSession, } from "../config.js";
 import { COMPACT_KEEP, planCompaction, transcriptFor, modelHistory, normalizeContext, } from "../compact.js";
 import { LLMClient, describeError } from "../llm/client.js";
-import { executeTool, getToolDefinitions } from "../llm/tools.js";
+import { advancePlan, buildPlannerInput, lastRequestText, needsPlan, parsePlan, planMessage, planTranscript, renderStepDirective, resumePlan, stopPlan, } from "../llm/plan.js";
+import { DELEGATE_TOOL, executeTool, getSubAgentToolDefinitions, getToolDefinitions } from "../llm/tools.js";
+import { buildSubAgentTask, formatSubAgentResult, runSubAgent as runSubAgentTask, } from "../llm/subagent.js";
 import { assessToolCall } from "../llm/risk.js";
 import { ApprovalGate, captureApprovalContext, describeApprovalIntent } from "../llm/approval.js";
 import { SessionCheckpoint } from "../persistence.js";
@@ -25,6 +27,8 @@ const IDLE_DISPOSE_MS = 30 * 60 * 1000;
 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. */
+const SUB_AGENT_TOOLS = getSubAgentToolDefinitions();
 /** Marker for the model-only summary, separate from the original transcript. */
 const SUMMARY_PREFIX = "Context was compressed. Summary of the earlier part:";
 function parseArguments(raw) {
@@ -82,7 +86,15 @@ export class WebSession {
     compressing = false;
     context = null;
     streamingContent = null;
+    /** The plan of the current turn, if this turn was planned. */
+    plan = null;
+    /** True while the planner agent is writing the steps. */
+    planning = false;
+    /** What the sub-agent is doing, or null when none is running. */
+    subagent = null;
     saveError = null;
+    /** A retried request, so the browser can explain why the stream is quiet. */
+    retrying = null;
     checkpoint = new SessionCheckpoint(() => {
         const saved = this.writeSession();
         this.publishLive();
@@ -105,6 +117,7 @@ export class WebSession {
         this.sessionId = source.id;
         this.messages = source.messages.slice();
         this.context = normalizeContext(source.context, this.messages.filter((m) => m.role !== "system").length);
+        this.plan = resumePlan(source.plan ?? null);
         this.tokens = {
             prompt: source.tokens?.prompt ?? 0,
             completion: source.tokens?.completion ?? 0,
@@ -165,7 +178,11 @@ export class WebSession {
             queued: this.queued,
             compressing: this.compressing,
             saveError: this.saveError,
+            retrying: this.retrying
+                ? { attempt: this.retrying.attempt, attempts: this.retrying.attempts, delayMs: this.retrying.delayMs }
+                : null,
             tokens: { prompt: this.tokens.prompt, completion: this.tokens.completion },
+            subagent: this.subagent,
             approval: this.pendingApproval
                 ? liveApprovalDetails(this.pendingApproval.tool, this.pendingApproval.args, this.pendingApproval.risk, this.dir)
                 : null,
@@ -197,6 +214,7 @@ export class WebSession {
             messages,
             streamingContent: this.streamingContent,
             context: this.context,
+            plan: this.plan,
         };
     }
     livePause() {
@@ -212,6 +230,8 @@ export class WebSession {
         }
         this.busy = false;
         this.retainStreamingContent();
+        this.subagent = null;
+        stopPlan(this.plan);
         this.save();
         this.publishLive();
     }
@@ -278,20 +298,121 @@ export class WebSession {
         this.streamingContent = "";
         this.publishLive();
         void (async () => {
-            await this.autoCompress(token);
-            if (token !== this.turnToken || this.paused)
-                return;
-            await this.agentLoop(this.buildApiMessages(turnMessages), token, approvalContext);
+            await this.runTurn(token, turnMessages, approvalContext);
         })().catch((err) => {
             if (token === this.turnToken)
                 this.failTurn(err);
         });
     }
+    /**
+     * One user turn, mirroring the terminal: plan first, then execute the steps in
+     * order, one agent loop per step. Without a usable plan the turn runs in one
+     * pass, exactly as it did before planning existed.
+     */
+    async runTurn(token, turnMessages, approvalContext) {
+        await this.autoCompress(token);
+        if (token !== this.turnToken || this.paused)
+            return;
+        const plan = await this.makePlan(token);
+        if (token !== this.turnToken || this.paused)
+            return;
+        if (plan) {
+            this.plan = plan;
+            this.messages.push({ role: "assistant", content: planMessage(plan) });
+            this.save();
+            this.publishLive();
+            const template = loadStepPrompt();
+            for (let i = 0; i < plan.steps.length; i++) {
+                if (token !== this.turnToken || this.paused)
+                    return;
+                this.setStep(i, "active");
+                const finished = await this.agentLoop(this.buildApiMessages(this.turnView(turnMessages), renderStepDirective(template, plan, i)), token, approvalContext);
+                if (token !== this.turnToken || this.paused)
+                    return;
+                this.setStep(i, finished ? "done" : "failed");
+                if (!finished)
+                    break;
+            }
+        }
+        else {
+            await this.agentLoop(this.buildApiMessages(this.turnView(turnMessages)), token, approvalContext);
+            if (token !== this.turnToken || this.paused)
+                return;
+        }
+        this.onTurnFinished();
+    }
+    /**
+     * The transcript this turn may see: the messages it started with plus what it
+     * added since. A user message queued while the turn runs belongs to the next
+     * turn, so the model never sees it early.
+     */
+    turnView(snapshot) {
+        const view = snapshot.slice();
+        for (let i = snapshot.length; i < this.messages.length; i++) {
+            if (this.messages[i].role !== "user")
+                view.push(this.messages[i]);
+        }
+        return view;
+    }
+    /** Move the plan to one step and publish it. */
+    setStep(index, status) {
+        if (!advancePlan(this.plan, index, status))
+            return;
+        this.save();
+        this.publishLive();
+    }
+    /**
+     * Run the planner agent over the current request. Null on every failure path:
+     * a plan must improve a turn, never be a new way for one to fail.
+     */
+    async makePlan(token) {
+        if (!planFirstEnabled())
+            return null;
+        const request = lastRequestText(this.messages);
+        if (!request.trim())
+            return null;
+        // One action is not a plan: run the turn in one pass, as the terminal does.
+        if (!needsPlan(request))
+            return null;
+        this.planning = true;
+        this.publishLive();
+        try {
+            const client = new LLMClient(this.model, this.provider, this.intensity);
+            const answer = await client.complete(loadPlannerPrompt(), buildPlannerInput({ request, cwd: this.dir, transcript: planTranscript(this.messages) }), {
+                onRetry: (notice) => {
+                    this.retrying = notice;
+                    this.publishLive();
+                },
+                cancelled: () => token !== this.turnToken || this.paused,
+            });
+            if (client.usage) {
+                this.tokens.prompt += client.usage.prompt;
+                this.tokens.completion += client.usage.completion;
+                this.lastPromptTokens = client.usage.prompt;
+            }
+            if (token !== this.turnToken)
+                return null;
+            return parsePlan(answer);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            this.planning = false;
+            this.retrying = null;
+            if (token === this.turnToken)
+                this.publishLive();
+        }
+    }
     /** Ends a turn whose floating promise rejected, instead of crashing the app. */
     failTurn(err) {
         this.retainStreamingContent();
         this.messages.push({ role: "assistant", content: `[Error: ${describeError(err)}]` });
         this.streamingContent = null;
+        // The turn died outside the loop, so the step it was on never reported back.
+        const active = this.plan?.steps.findIndex((step) => step.status === "active") ?? -1;
+        if (active >= 0)
+            advancePlan(this.plan, active, "failed");
         try {
             this.onTurnFinished();
         }
@@ -300,8 +421,12 @@ export class WebSession {
             this.paused = false;
         }
     }
-    buildApiMessages(messages = this.messages) {
-        const api = [{ role: "system", content: loadPrompt() }];
+    buildApiMessages(messages = this.messages, directive = "") {
+        // A step directive extends the system prompt: the plan is an instruction, not
+        // something the user just said.
+        const api = [
+            { role: "system", content: directive ? `${loadPrompt()}\n\n${directive}` : loadPrompt() },
+        ];
         for (const m of modelHistory(messages, this.context)) {
             if (m.role === "user" || m.role === "assistant") {
                 api.push({ role: m.role, content: m.content });
@@ -312,44 +437,75 @@ export class WebSession {
         }
         return api;
     }
+    /**
+     * One agent conversation for a single request (or a single plan step). Returns
+     * true when the model finished on its own, false when the turn was cut short;
+     * the caller owns the turn's end because a planned turn runs this per step.
+     */
     async agentLoop(apiMessages, token, approvalContext) {
         const tools = getToolDefinitions();
         try {
             for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
                 if (token !== this.turnToken || this.paused)
-                    return;
+                    return false;
                 const client = new LLMClient(this.model, this.provider, this.intensity);
                 let text = "";
                 this.streamingContent = "";
                 this.publishLive();
-                for await (const chunk of client.streamTurn(apiMessages, tools)) {
+                for await (const chunk of client.streamTurn(apiMessages, tools, {
+                    onRetry: (notice) => {
+                        this.retrying = notice;
+                        this.publishLive();
+                    },
+                    cancelled: () => token !== this.turnToken || this.paused,
+                })) {
+                    this.retrying = null;
                     if (token !== this.turnToken || this.paused)
-                        return;
+                        return false;
                     text += chunk;
                     this.streamingContent = text;
                     this.checkpoint.schedule();
                     this.publishLive();
                 }
                 if (token !== this.turnToken || this.paused)
-                    return;
+                    return false;
                 this.streamingContent = null;
                 if (client.usage) {
                     this.tokens.prompt += client.usage.prompt;
                     this.tokens.completion += client.usage.completion;
                     this.lastPromptTokens = client.usage.prompt;
                 }
+                const toolCalls = client.toolCalls;
                 if (text.trim()) {
                     this.messages.push({ role: "assistant", content: text });
-                    apiMessages.push({ role: "assistant", content: text });
+                }
+                if (text.trim() || toolCalls.length > 0) {
+                    // The assistant message and the tool results it produced must stay
+                    // paired: a `tool` message without its `tool_calls` parent is
+                    // rejected by every OpenAI-compatible endpoint. The reasoning is the
+                    // thinking that produced the calls, which DeepSeek requires back.
+                    apiMessages.push({
+                        role: "assistant",
+                        content: text,
+                        reasoning_content: client.reasoningContent ?? "",
+                        ...(toolCalls.length > 0
+                            ? {
+                                tool_calls: toolCalls.map((call) => ({
+                                    id: call.id,
+                                    type: "function",
+                                    function: { name: call.name, arguments: call.arguments },
+                                })),
+                            }
+                            : {}),
+                    });
                 }
                 this.save();
                 this.publishLive();
-                const toolCalls = client.toolCalls;
                 if (toolCalls.length === 0)
                     break;
                 for (const call of toolCalls) {
                     if (token !== this.turnToken || this.paused)
-                        return;
+                        return false;
                     const args = parseArguments(call.arguments);
                     const toolMsg = {
                         role: "tool",
@@ -365,7 +521,7 @@ export class WebSession {
                         context: captureApprovalContext(apiMessages).context,
                     });
                     if (token !== this.turnToken || this.paused)
-                        return;
+                        return false;
                     if (!decision.approved) {
                         // A malformed request was never shown to anyone, so there is no
                         // verdict to respect and the right move is a corrected retry.
@@ -382,27 +538,27 @@ export class WebSession {
                     }
                     let result;
                     try {
-                        result = await executeTool(call.name, args, this.dir);
+                        result = await this.runTool(call.name, args, toolMsg, token, apiMessages, approvalContext);
                     }
                     catch (err) {
                         result = `Error: ${err instanceof Error ? err.message : String(err)}`;
                     }
                     if (this.disposed)
-                        return;
+                        return false;
                     toolMsg.result = result;
                     this.save();
                     if (token !== this.turnToken || this.paused)
-                        return;
+                        return false;
                     apiMessages.push({ role: "tool", content: result, tool_call_id: call.id });
                     this.publishLive();
                 }
                 this.save();
             }
-            this.onTurnFinished();
+            return true;
         }
         catch (err) {
             if (token !== this.turnToken)
-                return;
+                return false;
             if (this.streamingContent) {
                 this.messages.push({ role: "assistant", content: this.streamingContent });
             }
@@ -411,10 +567,11 @@ export class WebSession {
                 role: "assistant",
                 content: `[Error: ${err instanceof Error ? err.message : String(err)}]`,
             });
-            this.onTurnFinished();
+            return false;
         }
     }
     onTurnFinished() {
+        this.retrying = null;
         this.busy = false;
         this.paused = false;
         this.streamingContent = null;
@@ -463,6 +620,58 @@ export class WebSession {
         }
         return { model: this.model, provider: this.provider, intensity: this.intensity };
     }
+    // ---- sub-agents ------------------------------------------------------
+    /**
+     * Run one approved tool call. `delegate` runs a child agent instead of
+     * touching the filesystem, so it is handled here, where the session's model,
+     * approval gate and abort signal live.
+     */
+    async runTool(name, args, toolMsg, token, apiMessages, approvalContext) {
+        if (name !== DELEGATE_TOOL)
+            return executeTool(name, args, this.dir);
+        return this.delegate(args, toolMsg, token, apiMessages, approvalContext);
+    }
+    /**
+     * Run a sub-agent for one `delegate` call and return its report. The child
+     * works in its own transcript; only the report reaches this conversation, and
+     * its risky calls go through the same approval gate as the parent turn.
+     */
+    async delegate(args, toolMsg, token, apiMessages, approvalContext) {
+        const task = String(args.task ?? "").trim();
+        if (!task)
+            return "[Error: delegate needs a task: what should the sub-agent do?]";
+        const context = typeof args.context === "string" ? args.context.trim() : "";
+        const approval = { ...approvalContext, context: captureApprovalContext(apiMessages).context };
+        const run = await runSubAgentTask({
+            createClient: () => new LLMClient(this.model, this.provider, this.intensity),
+            system: loadSubAgentPrompt(),
+            task: buildSubAgentTask({ task, context, cwd: this.dir }),
+            tools: SUB_AGENT_TOOLS,
+            approve: (name, callArgs) => this.requestApproval(name, callArgs, approval),
+            execute: (name, callArgs) => name === DELEGATE_TOOL
+                ? Promise.resolve("[Error: sub-agents cannot delegate further]")
+                : executeTool(name, callArgs, this.dir),
+            onProgress: (label) => {
+                this.subagent = label;
+                toolMsg.result = `… ${label}`;
+                this.publishLive();
+            },
+            onUsage: (usage) => {
+                this.tokens.prompt += usage.prompt;
+                this.tokens.completion += usage.completion;
+            },
+            onRetry: (notice) => {
+                this.retrying = notice;
+                this.publishLive();
+            },
+            cancelled: () => token !== this.turnToken || this.paused || this.disposed,
+        });
+        this.subagent = null;
+        this.retrying = null;
+        toolMsg.result = TOOL_PENDING;
+        this.publishLive();
+        return formatSubAgentResult(run);
+    }
     // ---- compression -----------------------------------------------------
     compressThreshold() {
         return contextCompressionThreshold(this.provider, this.model);
@@ -487,7 +696,9 @@ export class WebSession {
         this.publishLive();
         let summary = "";
         try {
-            summary = await new LLMClient(this.model, this.provider, this.intensity).summarize(transcript);
+            summary = await new LLMClient(this.model, this.provider, this.intensity).summarize(transcript, {
+                cancelled: () => token !== this.turnToken || this.paused,
+            });
         }
         catch {
             summary = "";
@@ -538,7 +749,7 @@ export class WebSession {
         if (chat.length === 0)
             return true;
         try {
-            this.sessionId = saveSession(chat, this.model.name, this.provider, this.intensity, this.dir, this.sessionId, this.tokens, this.context, this.approvalMode);
+            this.sessionId = saveSession(chat, this.model.name, this.provider, this.intensity, this.dir, this.sessionId, this.tokens, this.context, this.approvalMode, this.plan);
             this.saveError = null;
             return true;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingjisoft/neutrino",
-  "version": "0.1.7",
+  "version": "0.2.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-turn-fold.mjs && node scripts/test-web-settings.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-auth.mjs && node scripts/test-web-auth-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-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-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-auth.mjs && node scripts/test-web-auth-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

@@ -1,7 +1,7 @@
 # Neutrino Web UI
 
-A small, dependency-free single page app that is served by the Neutrino CLI on
-a port you choose. It lets you:
+A small, dependency-free single page app that is served by the Neutrino CLI at
+<http://127.0.0.1:8765> whenever the terminal UI runs. It lets you:
 
 - browse every saved conversation grouped by working directory (like Codex),
   with only the five latest transcripts per path shown and the rest collapsed;
@@ -19,12 +19,15 @@ Nothing needs to be built — these are plain `.html`, `.css` and `.js` files.
 
 ## Running it
 
-While using the terminal UI, mount the website on a port:
+The terminal UI starts the website by default:
 
 ```sh
-neutrino --web-port 8765
+neutrino
 ```
 
+Use `--port` to move it, `--no-web` to skip it for that run, or turn it off
+permanently in the terminal's **Settings → Web console**.
+
 Or serve only the saved history, without a terminal:
 
 ```sh
@@ -41,8 +44,9 @@ The server binds to loopback by default. To open it from your phone or another
 machine, bind an interface others can reach:
 
 ```sh
-neutrino web --port 8765 --lan               # every interface (0.0.0.0)
-neutrino web --port 8765 --host 100.64.0.7   # one specific address
+neutrino --lan                               # TUI + web UI, every interface (0.0.0.0)
+neutrino --host 100.64.0.7                   # TUI + web UI, one specific address
+neutrino web --port 8765 --lan               # headless web UI, every interface
 ```
 
 Startup prints the addresses to open:
@@ -97,7 +101,7 @@ disables password login.
 
 ## Models and settings
 
-Open a conversation to see the **Provider**, **Model** and **Thinking intensity**
+Open a conversation to see the **Provider**, **Model** and **Thinking**
 selectors. Choose a configured model and press **Apply to conversation**. The
 next turn uses that selection, and it is saved with the transcript. The same
 controls also update a conversation running in the terminal. Pause an active
@@ -108,7 +112,7 @@ selection. Changing the selectors and then using **Continue here** or sending a
 message also uses the draft selection, so a transcript whose old model was
 removed can still be continued.
 
-The **⚙ Settings** button in the sidebar opens defaults for new conversations,
+The **Settings** (gear) button in the sidebar opens defaults for new conversations,
 the context compression threshold, the approval reviewer model, and the
 extreme-risk automatic approval option. Save settings explicitly; cancelling
 leaves the saved values intact. Conversation model changes are separate from
@@ -119,12 +123,12 @@ Intensity uses the same Low–Ultra sampling settings as the terminal.
 ## History vs. live sessions
 
 A saved transcript on disk is a finished record: nothing is running, so the
-page shows it read-only (dashed `read-only` badge) and there is nothing to
+page shows it read-only (a neutral `read-only` badge) and there is nothing to
 pause.
 
 To continue one, either
 
-- press **✎ Continue here** in the header, or
+- press **Continue here** in the header, or
 - just start typing in the composer and press Enter.
 
 Both create a *browser-owned session*: the server resumes the transcript from
@@ -140,6 +144,38 @@ Browser-owned sessions are dropped after 30 idle minutes, or immediately through
 `POST /api/live/:key/close`. Sessions owned by the terminal cannot be closed from
 the web.
 
+## Plan-first turns
+
+A browser-owned turn is planned before it runs, exactly like a turn in the
+terminal: the planner agent writes the ordered steps, then each step is executed
+one at a time. The plan is written into the transcript as an assistant message,
+so it shows up in the conversation with everything else, and it is saved with the
+session (`plan` in the session file) so a resumed transcript still knows its
+steps.
+
+The plan travels in every live snapshot as a structured field — no text parsing
+needed by a client:
+
+```json
+"plan": {
+  "goal": "build and animate the scene",
+  "steps": [
+    { "title": "Model the case from box.png", "detail": "match the reference", "status": "done" },
+    { "title": "Model the monitor from vision.jpg", "status": "active" },
+    { "title": "Animate the camera", "status": "pending" }
+  ]
+}
+```
+
+`status` is `pending`, `active`, `done` or `failed`; `stopped: true` marks a plan
+whose turn was paused before the last step. The terminal draws this in its `ⓘ`
+card; a browser client can render the same timeline from the snapshot. The page
+itself currently shows the plan as the message it already is.
+
+Planning is the default for both loops. It can be turned off with
+`"plan_first": false` in `~/.neutrino/config.json` or `NEUTRINO_PLAN=off`; a
+request that produces no usable plan then runs in one pass.
+
 ## How real-time works
 
 A `ChatScreen` registers itself with the in-process hub when it is opened. Every