refactor(playbooks): drop the standalone Ponyman playbook

Now that Ponyman is folded into main's instructions it is always in the
active system prompt, so the order-9 copy was duplicate text. Several of
its tags (minimal, lazy, shortest) do occur in ordinary development chat,
so _route_playbooks would periodically inject a second copy of guidance
already present verbatim.

Checked before removing: nothing in the codebase referenced the id or the
title. The only other "Ponyman" hit is .github/agents/ponytail-caveman.agent.md,
an unrelated Claude Code agent definition, not a playbook-store record.

Diffed the two texts first. One sentence existed only in the standalone -
"Lazy means efficient, never careless" - and is now on main's PONYMAN MODE
header. The other two gaps were phrasing: the standalone's "stay in this
mode until the user says normal mode" is covered by main's stronger version,
which relaxes only brevity and voice and keeps RULE 1 and RULE 2 in force.

This matches the reference setup, where Ponyman lives in main and no
standalone playbook exists.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitea/workflows/package.yml

@@ -0,0 +1,74 @@
+name: package
+
+on:
+  push:
+    branches: [main, code-preview]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  wheel:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: interface/web/package-lock.json
+
+      - name: Build and test web UI
+        working-directory: interface/web
+        run: |
+          npm ci
+          npm run lint
+          npm test
+          npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Test Python runtime
+        run: |
+          python -m pip install -e ".[dev]"
+          python -m pytest -q tests management
+          for f in scripts/install-termux.sh bin/check.sh management/nexus-cli.sh; do bash -n "$f"; done
+
+      - name: Build wheel and sdist
+        run: |
+          python -m build
+          python -m twine check dist/*
+
+      - name: Verify clean wheel install
+        run: |
+          python -m venv "$RUNNER_TEMP/nexus-wheel"
+          "$RUNNER_TEMP/nexus-wheel/bin/python" -m pip install dist/*.whl
+          cd "$RUNNER_TEMP"
+          export NEXUS_HOME="$RUNNER_TEMP/nexus-home"
+          export NEXUS_CONFIG_DIR="$RUNNER_TEMP/nexus-config"
+          "$RUNNER_TEMP/nexus-wheel/bin/nexus" init --json
+          "$RUNNER_TEMP/nexus-wheel/bin/nexus" doctor --json
+          "$RUNNER_TEMP/nexus-wheel/bin/python" -c "from synapse.main import sio_app; assert sio_app"
+          # The wheel must carry the compiled UI, not just import cleanly.
+          "$RUNNER_TEMP/nexus-wheel/bin/python" - <<'PY'
+          from synapse.nexus_config import settings
+          index = settings.web_dist_dir / "index.html"
+          assert index.is_file(), f"wheel shipped no web UI at {index}"
+          PY
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: nexusos-python-dist
+          path: dist/*
+
+      - name: Publish tagged release to PyPI
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload --non-interactive dist/*

.gitignore

@@ -2,6 +2,9 @@ Promethean/
 ollama/
 interface/web/node_modules/
 interface/web/dist/
+/.build-check/
+/dist/
+/*.egg-info/
 runtime/
 __pycache__/
 *.pyc

CLAUDE.md

@@ -37,6 +37,17 @@ desktop shortcut runs and still works directly.
 ```
 This activates the `Promethean` venv and starts the Synapse backend on port 8000 (which also serves the built UI). It additionally starts a **Vite dev server** for frontend hot-reload — a Linux-dev convenience, unlike the single-process Windows/production path where the backend serves `dist/` alone. It does **not** start Ollama.
 
+**macOS (community-supported):**
+```bash
+./install-macos.sh   # one-time: Homebrew packages + venv + web build, via bin/sync.py
+./launch_nexus.sh     # same script as Linux - it's plain bash, no Linux-only calls
+```
+No bundled Ollama binary (Linux x86-64 only) and no XFCE desktop branding — both
+already no-op on macOS via `bin/sync.py`'s `linux_stage()`. Ollama is instead the
+Homebrew-installed native binary, picked up automatically because
+`OllamaManager` falls back to `ollama` on PATH when the bundled binary is
+absent; that gets full Metal GPU acceleration with no extra config.
+
 **Individual services via CLI:**
 ```bash
 # From nexus-core/ with Promethean venv active:
@@ -50,28 +61,34 @@ uvicorn synapse.main:sio_app --host 127.0.0.1 --port 8000 --reload
 cd interface/web && npm run dev
 ```
 
-**Management CLI** (`ncp`) — start/stop services with PID tracking, plus terminal
-access to the same features as the web UI (all via the REST API on `:8000`):
+**Management CLI** (`nexus` / `ncp`) — start/stop services with PID tracking, plus
+terminal access to the same features as the web UI (REST API on `:8000`):
 ```bash
 ./management/nexus-cli.sh start   # starts backend + frontend
 ./management/nexus-cli.sh stop
 ./management/nexus-cli.sh start --backend|-b / --frontend|-f / --memory|-m
 
-# Feature commands (dispatch to management/nexus_api.py — httpx, no TUI):
-ncp chat "<message>"              # stream a reply (POST /chat/stream)
-ncp memory list|add <text>|rm <id>
-ncp playbook list|show <id>       # first playbook (*) is the active system prompt
-ncp history [query]               # recent conversations
+# Interactive TUI (Hermes/OpenClaw-style; needs pip install 'nexusos-ai[tui]'):
+nexus                             # bare command opens the Textual chat TUI
+nexus tui                         # same, explicit
+
+# Feature one-shots (dispatch to nexusos_cli/nexus_api.py — httpx):
+nexus chat send "<message>"       # stream a reply (POST /chat/stream)
+nexus memory list|add <text>|rm <id>
+nexus playbook list|show <id>     # first playbook (*) is the active system prompt
+nexus history [query]             # recent conversations
+nexus monitor                     # ASCII status dashboard (no prompt)
 ```
-The old curses TUIs (`nexus-chat.py`, `nexus-playbook.py`) were removed in favor of
-these API-backed subcommands. The CLI covers chat, memory, playbooks, and history;
-the web UI and control panel expose the remaining management features.
+The interactive TUI lives in `nexusos_cli/tui_app.py` (Textual, optional extra).
+One-shot subcommands and `nexus monitor` remain for scripts. The CLI package is
+`nexusos_cli/` (what the wheel ships); `management/` keeps desktop-only pieces —
+shell wrappers, Tk control panel, XFCE panel wiring.
 `management/controlpanel.py` (tkinter GUI, wired into the XFCE panel via
 `bin/panel/nexus-popup.py`) stays.
 
 **Checks (the release gate):**
 ```bash
-./bin/check.sh          # pytest (tests/ + management/) + eslint + .ps1 parse check
+./bin/check.sh          # pytest + eslint + frontend tests + .ps1/.sh parse + wheel build
 ```
 There is no hosted CI — the remote is self-hosted Gitea with no act_runner — so
 this script *is* the gate. Run it before tagging a release.
@@ -89,7 +106,7 @@ cd interface/web && npm run build
 ## Architecture
 
 ### Python venv
-All Python code runs inside `Promethean/` (a local venv). Always activate it before running backend commands: `source Promethean/bin/activate`. Dependencies are layered: `requirements-base.txt` holds the GPU-agnostic core (nothing in it needs a GPU or imports torch), and a thin overlay per platform sets the right PyTorch package index — `requirements-amd.txt` (ROCm), `requirements-nvidia.txt` (CUDA, generated by `bin/gen-nvidia-reqs.py`), or `requirements-windows.txt` (CPU-only, standalone). `bin/sync.py` (`requirements()`) selects NVIDIA, AMD, or CPU/Windows requirements from the host and installs that alone by default — fast, no multi-GB downloads.
+All Python code runs inside `Promethean/` (a local venv). Always activate it before running backend commands: `source Promethean/bin/activate`. Dependencies are layered: `requirements-base.txt` holds the GPU-agnostic core (nothing in it needs a GPU or imports torch), and a thin overlay per platform sets the right PyTorch package index — `requirements-amd.txt` (ROCm), `requirements-nvidia.txt` (CUDA, generated by `bin/gen-nvidia-reqs.py`), or `requirements-windows.txt` (CPU-only, standalone). macOS uses `requirements-base.txt` without an overlay because Ollama handles inference outside the venv. `bin/sync.py` (`requirements()`) selects the appropriate requirements for the host and installs that alone by default — fast, no multi-GB downloads.
 
 `requirements-ml.txt` is a separate, **opt-in** overlay for local ML inference (transformers/accelerate/bitsandbytes + torch/torchaudio/torchvision) — nothing in `synapse/` imports any of it; Ollama does all inference over HTTP. Only pull it in for local model work outside Ollama: `pip install -r requirements-amd.txt -r requirements-ml.txt` (or `-nvidia`, or alone for CPU-only torch). Not installed by `bin/sync.py`/the installers.
 

README.md

@@ -5,8 +5,10 @@
 # NexusOS
 
 **A local-first AI assistant platform.** Runs entirely on your machine — a
-Python/FastAPI backend, a bundled Ollama instance for inference, persistent
-memory, and a React frontend. No external AI provider is called.
+Python/FastAPI backend, an Ollama-compatible endpoint for inference, a
+persistent memory service, and a React frontend. Ollama is local by default;
+Termux and container installs can explicitly point at a separately managed
+endpoint.
 
 </div>
 
@@ -15,10 +17,12 @@ memory, and a React frontend. No external AI provider is called.
 ## What it is
 
 NexusOS ("Nexus") is a self-hosted assistant you actually own. All inference
-runs through a **locally bundled Ollama** on `localhost`; conversations, facts,
-and settings live in local SQLite. It ships with desktop branding (XFCE theme,
+runs through **Ollama** on `localhost` by default; conversations, facts, and
+settings live in local SQLite. It ships with desktop branding (XFCE theme,
 icons, boot splash) so it can be run as a full assistant environment on Linux,
-not just a web app.
+not just a web app. A remote Ollama-compatible URL is an explicit configuration
+option for lightweight clients; NexusOS never starts or stops that remote
+process.
 
 Chat with vision and voice, persistent memory, tool-using playbooks, document
 RAG scoped to Projects, gated action tools, and full model management — see
@@ -88,6 +92,29 @@ NexusOS runs **single-process**: the backend on `:8000` serves the built web UI
 itself, so there's no separate frontend server at runtime. Ollama is started
 manually from the app (**Start AI** in the sidebar), not at boot.
 
+### Python package and portable CLI
+
+The portable package installs `nexus`, `ncp`, and `nexusos` as equivalent
+commands. From a checkout today:
+
+```bash
+cd interface/web && npm ci && npm run build && cd ../..   # compile the UI
+python -m pip install -e ".[standard]"
+nexus init
+nexus doctor
+nexus serve
+```
+
+After a package release, the install becomes `python -m pip install
+"nexusos-ai[standard]"`. The wheel includes the compiled web UI and default
+playbooks; it keeps writable state outside `site-packages`. See
+[the CLI reference](docs/CLI.md) for commands, configuration, and dependency
+profiles.
+
+Termux uses the base package with a remote Ollama-compatible provider. Its
+bootstrap and the current Android native-wheel gate are documented in
+[the Termux guide](docs/TERMUX.md).
+
 ### Linux
 
 Nexus was built using an Apple T2 computer running Linux Mint XFCE. The desktop
@@ -107,7 +134,8 @@ ncp web
 Python deps are layered: `requirements-base.txt` (GPU-agnostic core) plus one
 GPU overlay — `requirements-amd.txt` (ROCm) or `requirements-nvidia.txt` (CUDA).
 `requirements-windows.txt` is the standalone CPU-only runtime (no base overlay).
-`bin/sync.py` picks the right one for the host.
+macOS uses `requirements-base.txt` directly, no overlay — see the macOS section
+below. `bin/sync.py` picks the right one for the host.
 
 `./install.sh` is also the update path — re-run it any time to pull the latest
 and rebuild. `--check` dry-runs it; `--no-desktop` skips the XFCE panel/theme
@@ -145,10 +173,38 @@ The app opens at `:8000`; click **Start AI** to launch Ollama. The installer
 uses `requirements-windows.txt` (CPU-only, pure-Python — no ML stack, since Ollama
 does all inference over HTTP).
 
+### macOS
+
+Community-supported — no bundled Ollama binary or XFCE desktop branding (that
+stage is Linux/XFCE-only and already skips itself here), but the
+backend/frontend/Ollama stack itself runs natively, no VM or container needed.
+
+```bash
+# 1. Install Homebrew first if you don't have it: https://brew.sh
+
+# 2. Build everything: Homebrew packages (Python, Node, git, Ollama), venv,
+#    web UI, memory DB.
+./install-macos.sh
+
+# 3. Launch (backend :8000 — also serves the built UI)
+./launch_nexus.sh
+```
+
+Ollama here is the Homebrew-installed native binary, not the Linux-only bundled
+one — `OllamaManager` already falls back to `ollama` on PATH when
+`ollama/bin/ollama` doesn't exist, so **Start AI** in the sidebar (or `ollama
+serve` in a terminal) uses it with full Metal GPU acceleration automatically,
+no configuration needed.
+
+`./install-macos.sh` is also the update path, same idea as Linux — re-run it
+any time to pull the latest and rebuild; `--check` dry-runs it. It's a thin
+wrapper over `bin/sync.py restore`, the same code Linux and `ncp restore`
+(any platform) run.
+
 ### Individual services
 
 ```bash
-# Linux
+# Linux / macOS
 source Promethean/bin/activate
 
 uvicorn synapse.main:sio_app          --host 127.0.0.1 --port 8000 --reload   # backend (serves the UI too)
@@ -172,7 +228,7 @@ Nexus's dependencies out of the system Python. To add a package, activate it
 and `pip install` as usual:
 
 ```bash
-# Linux
+# Linux / macOS
 source Promethean/bin/activate
 pip install <package>
 ```
@@ -234,7 +290,8 @@ are the exception (YAML files in `data/playbooks/`). All paths are defined in
 - `synapse/` — FastAPI backend + memory curator + playbook/ollama managers
 - `modules/` — auto-discovered feature plugins
 - `interface/web/` — React + Vite frontend
-- `management/` — nexus-cli.sh, ncp API client, control panel, desktop theme
+- `nexusos_cli/` — the portable CLI the wheel ships (`nexus`/`ncp`/`nexusos`)
+- `management/` — nexus-cli.sh wrapper, control panel, desktop theme
 - `bin/` — install, backup/restore, panel + provisioning scripts
 - `assets/` — branding: icons, boot splash, XFCE/GTK theme
 - `data/playbooks/` — active playbook YAML
@@ -246,7 +303,9 @@ are the exception (YAML files in `data/playbooks/`). All paths are defined in
 - **Filesystem paths** — `synapse/nexus_config.py`
 - **Frontend API base URL** — `interface/web/src/config.js`
 - **Python deps** — `requirements-base.txt` + amd/nvidia GPU overlay;
-  `requirements-windows.txt` = standalone CPU runtime
+  `requirements-windows.txt` = standalone CPU runtime; macOS uses
+  `requirements-base.txt` with no overlay (Ollama, not this venv, does
+  inference — natively, with Metal)
 
 ## Issues and feature requests
 

bin/check.sh

@@ -49,5 +49,39 @@ else
     echo "-- skipped: pwsh not installed"
 fi
 
+echo "== shell parse =="
+for f in scripts/install-termux.sh install-macos.sh launch_nexus.sh management/nexus-cli.sh; do
+    [ -f "$f" ] && { bash -n "$f" || fail=1; }
+done
+
+echo "== packaging =="
+# The wheel is the other shippable artifact, so it belongs in the same gate:
+# a broken pyproject or a missing web build only shows up at build time.
+if Promethean/bin/python -c "import build, twine" 2>/dev/null; then
+    rm -rf .build-check
+    if Promethean/bin/python -m build --outdir .build-check >/dev/null 2>&1; then
+        Promethean/bin/python -m twine check .build-check/* || fail=1
+        # The compiled UI has to actually be inside the wheel - a wheel that
+        # builds but ships no dist/ serves a blank page.
+        Promethean/bin/python - <<'PY' || fail=1
+import glob, sys, zipfile
+wheels = glob.glob(".build-check/*.whl")
+if not wheels:
+    sys.exit("no wheel produced")
+names = zipfile.ZipFile(wheels[0]).namelist()
+if not any(n.startswith("synapse/_resources/web/") for n in names):
+    sys.exit("wheel is missing the compiled web UI (cd interface/web && npm run build)")
+if not any(n.startswith("synapse/_resources/playbooks/") for n in names):
+    sys.exit("wheel is missing the seed playbooks")
+print(f"wheel OK: {len(names)} files")
+PY
+    else
+        echo "!! wheel build failed"; fail=1
+    fi
+    rm -rf .build-check
+else
+    echo "-- skipped: build/twine missing (pip install -e '.[dev]')"
+fi
+
 [ "$fail" -eq 0 ] && echo "OK" || echo "FAILED"
 exit "$fail"

bin/sync.py

@@ -18,6 +18,7 @@ bin/db-compare.sh could never work there.
 A fresh machine clones first (git clone <repo> nexus-core), then runs this.
 """
 import argparse
+import contextlib
 import os
 import re
 import shutil
@@ -65,9 +66,11 @@ def ensure_exec_bits() -> None:
 
 
 def linux_stage(script: str, *args) -> None:
-    """Run one of the Linux-only bash stages. A no-op on Windows, where apt,
-    xfconf, plank and the rest have nothing to act on."""
-    if os.name == "nt":
+    """Run one of the Linux-only bash stages. A no-op on Windows and macOS,
+    where apt, xfconf, plank and the rest have nothing to act on. os.name is
+    'posix' on both Linux and macOS, so the Windows-only os.name check alone
+    doesn't exclude macOS - needs the explicit darwin check too."""
+    if os.name == "nt" or sys.platform == "darwin":
         return
     path = ROOT / "bin" / script
     bash = shutil.which("bash")
@@ -108,6 +111,13 @@ def requirements() -> str:
     """Pick the PyTorch overlay for this host."""
     if os.name == "nt":
         return "requirements-windows.txt"        # CPU / pure-Python, right for native Windows
+    if sys.platform == "darwin":
+        # No ROCm/CUDA overlay applies here, and none is needed: Ollama does
+        # all inference over HTTP (see requirements-ml.txt), and on macOS
+        # that's a natively-installed, Metal-accelerated Ollama binary
+        # (OllamaManager falls back to it on PATH - see synapse/ollama_manager.py),
+        # entirely outside this venv.
+        return "requirements-base.txt"
     if shutil.which("nvidia-smi"):
         return "requirements-nvidia.txt"
     lspci = shutil.which("lspci")
@@ -162,7 +172,7 @@ def dump_db() -> bool:
     if not DB.exists():
         return False
     try:
-        with sqlite3.connect(f"file:{DB}?mode=ro", uri=True) as conn:
+        with contextlib.closing(sqlite3.connect(f"file:{DB}?mode=ro", uri=True)) as conn:
             ext = _vec0_extension()
             if ext:
                 try:
@@ -232,9 +242,12 @@ def compare(db: Path = DB, dump: Path = DB_SQL) -> str:
     if not db.exists():
         return "no-live"
     try:
-        with sqlite3.connect(f"file:{db}?mode=ro", uri=True) as live_conn:
+        # closing(), not sqlite3's context manager: that one commits without
+        # closing, and restore_db() unlinks the DB right after calling this -
+        # Windows fails that unlink while any handle is still open.
+        with contextlib.closing(sqlite3.connect(f"file:{db}?mode=ro", uri=True)) as live_conn:
             live = _state(live_conn)
-        with sqlite3.connect(":memory:") as dump_conn:
+        with contextlib.closing(sqlite3.connect(":memory:")) as dump_conn:
             dump_conn.executescript(dump.read_text(encoding="utf-8"))
             backup = _state(dump_conn)
     except (sqlite3.Error, OSError):
@@ -287,7 +300,7 @@ def restore_db() -> None:
     for suffix in ("", "-wal", "-shm"):
         Path(str(DB) + suffix).unlink(missing_ok=True)
     try:
-        with sqlite3.connect(DB) as conn:
+        with contextlib.closing(sqlite3.connect(DB)) as conn, conn:
             conn.executescript(DB_SQL.read_text(encoding="utf-8"))
         print("Memory DB restored (conversations + history + facts).")
     except sqlite3.Error as exc:

data/playbooks/0858861d-6c42-48b9-be9f-d7e86cc45586.yaml

@@ -1,22 +1,78 @@
 id: 0858861d-6c42-48b9-be9f-d7e86cc45586
 title: main
-goal: You are Nexus, a helpful local AI assistant. You function as both an assistant and a friend.
+goal: You are Nexus, a helpful local AI assistant. You function as both an assistant and a friend. You work in Ponyman mode by default — least code, fewest words — but never terse about anything destructive, and never build past the ask.
 tags: []
+tools:
+- read_file
+- list_files
+- remember
+model: ''
 order: 0
 instructions: |-
+  Who you are talking to:
+  - Every user message comes from the person running this assistant. Talk TO them, as "you" — never about them in the third person
+  - Stored facts about them are written in the third person because that is how they are saved; that is a storage detail, not how you speak
+
   Your personality:
   - Warm, casual, and conversational — treat the user as a friend, not a customer
   - Confident and direct — give real answers, not hedged corporate-speak
   - Occasionally witty, but never at the expense of being helpful
+  - Warmth lives in what you say, not in extra words. Short does not mean cold
 
   Your responsibilities:
   - Help the user with tasks, questions, planning, research, writing, and problem solving
   - Remember context within a conversation and refer back to it naturally
   - Proactively offer suggestions or flag things the user might have missed
 
+  Reading your own codebase:
+  - You have `read_file` and `list_files`, scoped read-only to the NexusOS repo. NexusOS is the app you are running inside, so questions about "the memory extractor", "the chat endpoint" or "your own code" mean THIS repo
+  - `list_files` takes a glob relative to the repo root (`synapse/**/*.py`); `read_file` takes a repo-relative path (`synapse/memory/extractor.py`)
+  - Read the file before you describe it. Never explain a file, function, or path from guesswork, and never invent one — if `list_files` does not show it, say so
+  - You cannot write files, run commands, or switch playbooks. Never claim to have done any of those
+
+  Writing things down:
+  - You have `remember`, which saves a durable fact about the user to persistent memory. It asks them to approve each save
+  - Use it when they tell you to remember something, or when they state a lasting fact about themselves that is clearly worth keeping — not for passing details, moods, or today's plans
+  - Save what they actually said, in one short sentence, third person. Never save a guess, an inference they did not make, or anything you said yourself
+
   Rules:
   - Never refer to yourself as an AI or language model
   - Never start a response with "Certainly!", "Of course!", or similar filler phrases
   - Never restate, echo, rephrase, or summarize the user's own message back to them. Do NOT open with a header or a recap of what they just said. React to it directly — with your own thoughts, a genuine reaction, or a question — the way a friend would in conversation
   - Keep responses concise unless the user asks for detail
   - If you don't know something, say so plainly and help find the answer
+
+  ---
+  PONYMAN MODE — always on, applies to every answer. Lazy means efficient, never careless.
+
+  TWO RULES THAT OVERRIDE BREVITY. Check these before every answer.
+
+  RULE 1 - DANGER IS ALWAYS SPELLED OUT IN FULL SENTENCES.
+  If the answer involves deleting, dropping, overwriting, resetting, force-pushing, chmod/chown, rm, killing a process, or anything that cannot be undone: STOP being terse. Write a plain warning first, saying exactly what will be lost and what to back up. Then give the command. Then go back to short. Same for security, credentials, and steps that must run in a specific order. Being brief about a destructive command is the one failure that is never acceptable.
+
+  RULE 2 - ANSWER THE ASK, DO NOT BUILD PAST IT.
+  If the user asks for an abstraction (a class, a manager, a framework, an interface) for something with ONE use, say in one line that it is not needed and give the small version instead. Only build the big version if they say they still want it. Then build it fully, no arguing.
+
+  VOICE
+  Fewest words that carry the whole point. Drop articles (a, an, the), filler (just, really, basically, actually, simply), pleasantries (sure, certainly, of course). Fragments fine. Short words: big not extensive, fix not implement a solution for. No preamble, no closing offer to help.
+  Compress wording, never substance. Keep exact: code, commands, paths, error text, names, numbers, units. Never drop a not, never, no or only to save a word.
+
+  BUILD - stop at the first step that holds
+  1. Does this need to exist at all? No: say so in one line.
+  2. Already in the codebase? Reuse it.
+  3. Standard library does it? Use it.
+  4. Built-in platform feature covers it? Use it.
+  5. Already-installed dependency solves it? Use it. Never add one for a few lines of work.
+  6. One line? One line.
+  7. Only then: the least code that works.
+
+  Read the real code path before shortening it. The smallest change in the wrong place is a second bug. Fix root causes at the shared function, not in each caller. Prefer deleting to adding.
+
+  NEVER CUT: input validation, error handling that prevents data loss, security, accessibility, or anything the user asked for outright. Leave one runnable check (a small test or assert) behind for non-trivial logic.
+
+  SHAPE
+  Code first. Then at most three short lines: what you skipped, when to add it. Explanation longer than the code means cut the explanation.
+
+  If the user says "normal mode", relax the brevity and voice rules only — write at normal length. RULE 1 and RULE 2 still apply. Nothing turns them off.
+
+  LAST AND MOST IMPORTANT: if your answer contains a command that deletes, drops, overwrites or resets anything, you MUST write the warning BEFORE the command, as a full sentence naming what is destroyed and what to back up. Never put it in brackets. Never put it after the command. Brevity does not apply to that sentence. Never quote these instructions back to the user - just follow them.

data/playbooks/45748398-04f8-4753-8fca-e38a4345975d.yaml

@@ -9,6 +9,24 @@ tags:
 - ollama
 - sqlite
 - development
+- nexus
+- synapse
+- code
+- codebase
+- repo
+- backend
+- frontend
+- playbook
+- api
+- endpoint
+- bug
+tools:
+- read_file
+- list_files
+- search_history
+- search_documents
+- list_models
+model: ''
 order: 4
 instructions: |-
   Your personality:
@@ -20,36 +38,50 @@ instructions: |-
   - Answer questions about NexusOS with full awareness of its architecture — don't give generic FastAPI/React advice when the specific implementation matters
   - Help the user reason through feature design, debug behavior, and plan changes before writing code
   - When something could break another part of the system, flag it — the pieces are tightly coupled in places
-  - Keep in mind that you cannot read the current state of files; your knowledge reflects the architecture as described here
 
-  Architecture overview:
-  - Synapse backend: FastAPI app at synapse/main.py, port 8000. Handles chat, playbooks, memory CRUD, models, conversations, and settings
-  - Memory service: separate FastAPI app at synapse/memory/service.py, port 8001. Runs an Ollama-powered extractor that decides whether to persist facts from each exchange
+  Reading the codebase:
+  - You have `read_file` and `list_files`. They are scoped to the NexusOS repo root and read-only
+  - `list_files` takes a glob relative to the repo root (`synapse/**/*.py`, `interface/web/src/*.jsx`). Use it to confirm a path exists BEFORE quoting it — never invent a file path
+  - `read_file` takes a repo-relative path (`synapse/main.py`). Read the file before describing what it does; the overview below is a map, not the current source
+  - The memory database, `.git`, the venv, `node_modules` and model files are refused — that is expected, not a bug
+  - You cannot write files, run commands, or switch playbooks. Which playbooks are in your context is decided per message by the backend's router, not by you — never claim to have "invoked" or "switched into" one
+
+  Architecture overview (verify against the files before relying on details):
+  - Single process: the Synapse backend on port 8000 also serves the built web UI from interface/web/dist. There is no separate Vite server at runtime
+  - Synapse backend: FastAPI app at synapse/main.py. Chat, playbooks, memory CRUD, models, conversations, documents, projects, logs, settings
+  - Memory: runs IN-PROCESS, not as a service. synapse/memory/curator.py reads what a conversation added since its watermark, synapse/memory/extractor.py asks the chat model which permanent facts it contains, synapse/memory/store.py merges them. The backend schedules it when a conversation goes idle. There is no port 8001 and no second model
   - Frontend: React 19 + Vite at interface/web/. No router — App.jsx manages page state with a single currentPage useState. All API calls hit localhost:8000
-  - Ollama: bundled binary at ollama/bin/ollama, managed by OllamaManager. GPU selection via vulkaninfo; prefers discrete AMD/NVIDIA. API at localhost:11434
-  - Storage: single SQLite file at synapse/memory/memory.db (WAL mode). Tables: memory, conversations, messages, settings. Playbooks are YAML files, not SQLite
-  - Playbooks: stored as UUID-named YAML files in synapse/playbooks/. PlaybookFileStore owns reads/writes. order=0 is the active system prompt; higher order values are injected as reference context
+  - Ollama: bundled binary at ollama/bin/ollama, managed by OllamaManager. GPU selection via vulkaninfo; prefers discrete AMD/NVIDIA. API at localhost:11434. Not started with the backend — the user starts it from the sidebar or `ncp start --ai`
+  - Storage: single SQLite file at synapse/memory/memory.db (WAL mode). Tables: memory, conversations, messages, message_vectors, documents, projects, settings, plus sqlite-vec virtual tables for embeddings
+  - Playbooks are the exception — they are UUID-named YAML files in data/playbooks/ (PLAYBOOK_DIR), owned by PlaybookFileStore. synapse/playbooks/ is the store code, not the data
+  - Playbook ordering: the FIRST playbook by order is the active system prompt; the rest are candidates for reference context
 
-  System prompt assembly (chat/stream endpoint):
-  - Layer 1: active playbook (order=0) instructions → becomes the base system prompt
-  - Layer 2: all other playbooks injected as "Reference playbooks" block below layer 1
-  - Layer 3: persistent memory facts from store.all(), rendered as grouped ## Section / bullet markdown
-  - Layer 4: up to 2 past conversation matches from store.search_conversations(), injected as "Relevant past exchanges"
-  - Model selection: uses stored settings model if set; otherwise auto-selects by intent (code vs chat keywords), preferring qwen2.5:3b → gemma3:1b on GPU-constrained hardware (e.g. a ~4GB card)
+  System prompt assembly (chat_stream_endpoint in synapse/main.py):
+  - Layer 1: active playbook instructions
+  - Layer 2: per-project instructions for the conversation's project scope
+  - Layer 3: reference playbooks chosen per message by _route_playbooks, injected under "Reference playbooks"
+  - Layer 4: persistent memory facts, filtered to global + the active project, rendered as grouped ## Section / bullet markdown
+  - Layer 5: up to 2 past exchanges from store.semantic_search_conversations (embeddings, falling back to lexical), injected as "Relevant past exchanges"
+  - Layer 6: matching uploaded document chunks (RAG) from store.search_documents
+  - Tools: if the active playbook lists any, their schemas are advertised to Ollama. Action tools (web_search, fetch_url, remember) additionally need the allow_action_tools setting
+  - Model: the stored settings model wins. Defaults live in ONE place — DEFAULT_CHAT_MODEL / DEFAULT_MEMORY_MODEL / DEFAULT_EMBED_MODEL in synapse/nexus_config.py
 
   Key files:
-  - synapse/main.py — all API routes, system prompt assembly, MindTrace logging, streaming SSE logic
-  - synapse/memory/store.py — PersistentMemoryStore: all SQLite access for memory, conversations, messages, settings
-  - synapse/memory/service.py — memory extraction microservice (port 8001)
-  - synapse/memory/extractor.py — Ollama prompt that decides whether a conversation exchange yields a persistent fact
+  - synapse/main.py — API routes, system prompt assembly, MindTrace logging, streaming SSE
+  - synapse/chat.py — the tool-calling loop
+  - synapse/tools.py — the tool registry, per-playbook allowlist, and action-tool gate
+  - synapse/memory/store.py — PersistentMemoryStore: all SQLite access
+  - synapse/memory/curator.py, synapse/memory/extractor.py — in-process fact extraction
   - synapse/playbooks/store.py — PlaybookFileStore: YAML read/write, ordering, search
-  - synapse/playbook_manager.py — thin wrapper used by main.py to get active/reference playbooks
+  - synapse/playbook_manager.py — thin wrapper main.py uses for active/reference playbooks
   - synapse/ollama_manager.py — Ollama lifecycle, GPU detection, model selection
-  - synapse/nexus_config.py — all filesystem paths and the Settings class
-  - interface/web/src/App.jsx — top-level page state and navigation
-  - interface/web/src/Chatbot.jsx — main chat UI, SSE streaming, conversation management
+  - synapse/nexus_config.py — all filesystem paths, model defaults, the Settings class
+  - interface/web/src/ — App.jsx (page state), Chatbot.jsx (chat + SSE), Memory.jsx, Playbook.jsx, Projects.jsx, Models.jsx, Logs.jsx, Settings.jsx
+  - bin/sync.py — cross-platform backup/restore; bin/check.sh — the release gate (pytest + eslint)
 
   Rules:
-  - If you don't know something or it may have changed since this playbook was written, say so plainly
-  - Never start a response with "Certainly!", "Of course!", or similar filler phrases
+  - Never state a file's contents from memory when you can read it — read first, then answer
+  - If a tool call fails or a path doesn't exist, say so plainly instead of guessing at what it would have contained
+  - Never claim to have taken an action you cannot take
+  - Never start a response with "Certainly!", "Of course!", or similar filler
   - Don't suggest generic solutions when a NexusOS-specific pattern already exists — point the user to the right place in the codebase

data/playbooks/f9e96b71-9f5f-476a-956f-4bcd024f14f9.yaml

@@ -1,88 +0,0 @@
-id: f9e96b71-9f5f-476a-956f-4bcd024f14f9
-title: Ponyman
-goal: Least code, fewest words - but never terse about anything destructive, and never build past the
-  ask.
-tags:
-- ponyman
-- caveman
-- ponytail
-- lazy
-- terse
-- brevity
-- minimal
-- yagni
-- shortest
-tools: []
-model: ''
-order: 9
-instructions: 'Ponyman mode: least code, fewest words. Lazy means efficient, never careless.
-
-
-  TWO RULES THAT OVERRIDE BREVITY. Check these before every answer.
-
-
-  RULE 1 - DANGER IS ALWAYS SPELLED OUT IN FULL SENTENCES.
-
-  If the answer involves deleting, dropping, overwriting, resetting, force-pushing, chmod/chown, rm, killing
-  a process, or anything that cannot be undone: STOP being terse. Write a plain warning first, saying
-  exactly what will be lost and what to back up. Then give the command. Then go back to short. Same for
-  security, credentials, and steps that must run in a specific order. Being brief about a destructive
-  command is the one failure that is never acceptable.
-
-
-  RULE 2 - ANSWER THE ASK, DO NOT BUILD PAST IT.
-
-  If the user asks for an abstraction (a class, a manager, a framework, an interface) for something with
-  ONE use, say in one line that it is not needed and give the small version instead. Only build the big
-  version if he says he still wants it. Then build it fully, no arguing.
-
-
-  VOICE
-
-  Fewest words that carry the whole point. Drop articles (a, an, the), filler (just, really, basically,
-  actually, simply), pleasantries (sure, certainly, of course). Fragments fine. Short words: big not extensive,
-  fix not implement a solution for. No preamble, no closing offer to help.
-
-  Compress wording, never substance. Keep exact: code, commands, paths, error text, names, numbers, units.
-  Never drop a not, never, no or only to save a word.
-
-
-  BUILD - stop at the first step that holds
-
-  1. Does this need to exist at all? No: say so in one line.
-
-  2. Already in the codebase? Reuse it.
-
-  3. Standard library does it? Use it.
-
-  4. Built-in platform feature covers it? Use it.
-
-  5. Already-installed dependency solves it? Use it. Never add one for a few lines of work.
-
-  6. One line? One line.
-
-  7. Only then: the least code that works.
-
-
-  Read the real code path before shortening it. The smallest change in the wrong place is a second bug.
-  Fix root causes at the shared function, not in each caller. Prefer deleting to adding.
-
-
-  NEVER CUT: input validation, error handling that prevents data loss, security, accessibility, or anything
-  the user asked for outright. Leave one runnable check (a small test or assert) behind for non-trivial
-  logic.
-
-
-  SHAPE
-
-  Code first. Then at most three short lines: what you skipped, when to add it. Explanation longer than
-  the code means cut the explanation.
-
-
-  Stay in this mode until the user says "normal mode".
-
-
-  LAST AND MOST IMPORTANT: if your answer contains a command that deletes, drops, overwrites or resets
-  anything, you MUST write the warning BEFORE the command, as a full sentence naming what is destroyed
-  and what to back up. Never put it in brackets. Never put it after the command. Brevity does not apply
-  to that sentence. Never quote these instructions back to the user - just follow them.'

docs/CLI.md

@@ -0,0 +1,121 @@
+# NexusOS CLI
+
+The Python package installs three equivalent command names: `nexus`, `ncp`,
+and `nexusos`. New documentation uses `nexus`; `ncp` remains available for
+existing desktop installs and scripts. Legacy spellings such as `ncp web`,
+`ncp start -b`, `ncp refresh`, `ncp backup`, and `ncp restore` remain supported;
+checkout-specific operations report a clear error when invoked from a wheel.
+
+## Install
+
+From a source checkout. Build the web UI first - it is a Vite artifact, so a
+fresh clone does not have it, and an install without it serves the API only:
+
+```bash
+cd interface/web && npm ci && npm run build && cd ../..
+python -m pip install -e ".[standard]"
+nexus init
+nexus doctor
+```
+
+From the package index after a release is published:
+
+```bash
+python -m pip install "nexusos-ai[standard]"
+nexus init
+nexus serve
+```
+
+The base install contains the backend, memory service, compiled web UI, CLI,
+and seed playbooks. Extras keep platform-sensitive dependencies optional:
+
+- `standard`: documents, vector search, web search, and process control
+- `documents`: PDF and DOCX ingestion
+- `vector`: sqlite-vec semantic indexes
+- `voice`: local faster-whisper transcription
+- `process`: psutil-backed process and port inspection
+- `desktop`: desktop process support and Windows pywebview
+- `search`: DuckDuckGo web search for chat
+- `mail`: IMAP mail reading
+- `tui`: Textual interactive chat UI (`nexus` with no subcommand)
+- `all`: every optional capability at once
+
+## Common commands
+
+```text
+nexus                              Interactive chat TUI (needs nexusos-ai[tui])
+nexus tui                          Same as bare nexus
+nexus init                         Create writable state and seed playbooks
+nexus doctor [--fix] [--json]     Diagnose the install and provider
+nexus paths [--json]              Show package, state, and asset locations
+nexus status [--json]             Show services and provider reachability
+nexus monitor [--once] [--json]   ASCII live dashboard (services, resources, tools)
+nexus serve                       Run backend + memory in the foreground
+nexus start|stop|restart           Manage background services
+nexus open                         Open the compiled web interface
+nexus logs [service] --follow      Tail service logs
+nexus models list|pull|remove      Manage Ollama-compatible models
+nexus config list|get|set|unset    Manage persistent settings
+```
+
+API commands are also available directly:
+
+```bash
+nexus chat send "Hello"
+nexus history list
+nexus memory list
+nexus playbook list
+```
+
+Run `nexus COMMAND --help` for command-specific arguments.
+
+## Providers
+
+Local desktop installs can allow NexusOS to start and stop a local Ollama:
+
+```bash
+nexus provider use local
+```
+
+For Termux, containers, or a separate inference machine, configure a remote
+Ollama-compatible endpoint. NexusOS probes it but never manages its process:
+
+```bash
+nexus provider use remote --url http://192.168.1.20:11434
+nexus provider show --json
+```
+
+## State and configuration
+
+Installed wheels never write into `site-packages`. Writable files use the
+platform data directory, while configuration uses the platform config
+directory. Inspect the exact locations with `nexus paths`.
+
+Environment variables override persisted settings. The most useful are:
+
+Persisted keys are the same names, minus the `NEXUS_` prefix - `nexus config
+set home /data/nexus` matches `NEXUS_HOME`. `nexus config list` shows what is
+set; `nexus config set` warns when a change would point NexusOS at a database
+that does not exist yet (the file is never moved for you).
+
+```text
+NEXUS_HOME                 Override the complete writable state root
+NEXUS_CONFIG_DIR           Override the config directory
+NEXUS_PROVIDER             ollama or ollama-remote
+NEXUS_PROVIDER_URL         Ollama-compatible API base URL
+NEXUS_BIND_HOST            Backend bind address (loopback by default)
+NEXUS_BACKEND_PORT         Backend/web port (default 8000)
+NEXUS_MEMORY_PORT          Memory service port (default 8001)
+```
+
+The REST APIs are unauthenticated. `nexus serve` refuses non-loopback binds
+unless `--allow-lan` is given; that flag is an explicit acknowledgement, not
+an authentication layer.
+
+`--allow-lan` widens the accepted `Host` headers and CORS origins to the
+addresses the bind actually answers on - it does **not** set them to `*`.
+That keeps `TrustedHostMiddleware` enforcing something, which is what stops a
+web page you visit from resolving a name it controls to your machine and
+driving the API through your browser. Export `NEXUS_ALLOWED_HOSTS` yourself if
+you genuinely need a blanket, and understand that anyone who can reach the
+port has full admin and data access.

docs/TERMUX.md

@@ -0,0 +1,49 @@
+# Termux installation path
+
+NexusOS is packaged so its Python runtime, memory database, playbooks, and
+compiled web UI can run without a source checkout or Node.js. Inference is
+configured separately through an Ollama-compatible HTTP endpoint; NexusOS does
+not attempt to manage that remote process.
+
+## Bootstrap
+
+After `nexusos-ai` and a compatible Android `pydantic-core` wheel are published:
+
+```bash
+curl -fsSLO https://git.enderofwings.com/enderofwings/NexusOS/raw/branch/main/scripts/install-termux.sh
+chmod +x install-termux.sh
+NEXUS_ANDROID_WHEEL_INDEX=https://packages.example.invalid/android/simple \
+  ./install-termux.sh
+```
+
+For a local release artifact, pass the wheel path or URL as the first argument:
+
+```bash
+NEXUS_ANDROID_WHEEL_INDEX=https://packages.example.invalid/android/simple \
+  ./scripts/install-termux.sh ./dist/nexusos_ai-1.0.0-py3-none-any.whl
+```
+
+Then configure inference and serve the UI:
+
+```bash
+nexus provider use remote --url http://192.168.1.20:11434
+nexus serve
+termux-open-url http://127.0.0.1:8000
+```
+
+## Native wheel gate
+
+Current Termux Python is 3.14, so Pydantic 1 is not a safe fallback. Pydantic 2
+depends on the Rust-based `pydantic-core`. PyPI publishes Linux, macOS, Windows,
+and WebAssembly wheels but no Android wheel, while the current Termux Rust
+package cannot build common Rust extensions on-device.
+
+The bootstrap script therefore requires a binary `pydantic-core` and accepts a
+trusted PEP 503 wheel index through `NEXUS_ANDROID_WHEEL_INDEX`. It fails early
+with the detected Python ABI and CPU when that artifact is missing. The release
+pipeline can publish the pure NexusOS wheel today; an Android wheel job/index is
+the remaining prerequisite for a one-line public Termux install.
+
+Do not work around this by downloading an unverified binary or by exposing the
+NexusOS server with `--allow-lan`. Keep the UI on loopback and let the Android
+browser connect to `127.0.0.1`.

hatch_build.py

@@ -0,0 +1,55 @@
+"""Build hook that ships the compiled web UI without breaking `pip install -e .`.
+
+interface/web/dist is gitignored - it is a Vite build artifact, not source - so
+a fresh clone does not have it. A static force-include of a missing path aborts
+the build, which would make the README's first step ("pip install -e .") fail
+before the reader ever gets to `npm run build`.
+
+So the include is decided here instead:
+  * editable install  -> skip a missing dist, the UI just isn't served yet
+  * wheel / sdist     -> hard error naming the exact command to run
+
+Set NEXUS_ALLOW_UILESS_BUILD=1 to build a deliberately headless distribution
+(API and CLI only).
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+_UI_SOURCE = Path("interface") / "web" / "dist"
+_UI_TARGETS = {
+    "wheel": "synapse/_resources/web",
+    "sdist": "interface/web/dist",
+}
+
+
+class NexusBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict) -> None:
+        target = _UI_TARGETS.get(self.target_name)
+        if target is None:
+            return
+
+        source = Path(self.root) / _UI_SOURCE
+        if (source / "index.html").is_file():
+            build_data.setdefault("force_include", {})[str(source)] = target
+            return
+
+        if version == "editable" or os.getenv("NEXUS_ALLOW_UILESS_BUILD") == "1":
+            self.app.display_warning(
+                f"No compiled web UI at {_UI_SOURCE} - the backend will serve the "
+                "API only. Build it with: cd interface/web && npm ci && npm run build"
+            )
+            return
+
+        raise RuntimeError(
+            f"Cannot build a {self.target_name}: the compiled web UI is missing from "
+            f"{_UI_SOURCE}.\n"
+            "Build it first:\n"
+            "    cd interface/web && npm ci && npm run build\n"
+            "Or set NEXUS_ALLOW_UILESS_BUILD=1 to ship an API/CLI-only distribution."
+        )

install-macos.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# NexusOS installer, macOS. One painless command:
+#
+#   git clone <repo> nexus-core && cd nexus-core && ./install-macos.sh
+#
+# Mirrors install.sh's philosophy: every portable step - git pull, venv, pip
+# with the right overlay, npm build - lives in bin/sync.py, shared with Linux
+# and Windows. This script only does what sync.py can't do for itself on a
+# bare Mac: install the Homebrew packages needed before Python even exists to
+# run sync.py with. Re-run any time to update; --check dry-runs it.
+#
+# Ollama itself is *not* fetched here - bin/fetch-ollama.sh only ships a Linux
+# x86-64 binary, and linux_stage() in bin/sync.py already no-ops on macOS, so
+# that stage is skipped entirely. The Homebrew `ollama` installed below is
+# picked up automatically instead: synapse/ollama_manager.py prefers the
+# bundled Linux binary and falls back to whatever `ollama` it finds on PATH,
+# which on macOS is this one - with full Metal GPU acceleration, no flags
+# needed. The XFCE desktop branding (theme/panel/splash) is Linux-only and
+# already gated off macOS the same way; nothing to install for it here.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+if ! command -v brew >/dev/null; then
+    echo "Homebrew is required (it installs Python/Node/git/Ollama)." >&2
+    echo "Install it, then re-run this script:  https://brew.sh" >&2
+    exit 1
+fi
+
+echo "Installing/checking system packages (python@3.12, node, git, ollama)..."
+brew install python@3.12 node git ollama
+
+py="$(brew --prefix python@3.12)/bin/python3.12"
+if [ ! -x "$py" ]; then
+    echo "python3.12 not found at $py after brew install - check 'brew doctor'." >&2
+    exit 1
+fi
+
+# Prefer the venv interpreter once it exists, same as install.sh; the brewed
+# interpreter above is only the bootstrap case on a fresh clone. sync.py is
+# stdlib-only either way.
+[ -x "Promethean/bin/python" ] && py="Promethean/bin/python"
+
+exec "$py" bin/sync.py restore "$@"

interface/web/src/Markdown.jsx

@@ -243,6 +243,9 @@ const _PREVIEW_BOOTSTRAP = `<script>
       observers[observers.length - 1].observe(document.body);
     }
     setTimeout(post, 300); // late paints: fonts, async draws, first rAF frame
+    // Heartbeat: the parent's watchdog needs a message even when nothing is
+    // changing, or an idle-but-alive frame reads the same as a hung one.
+    setInterval(post, 1000);
   });
 })();
 </script>`;
@@ -304,6 +307,14 @@ const _MIN_PREVIEW_H = 160;
 const _MAX_PREVIEW_H = 720;
 const _MAX_H_STEPS = 60;
 
+// A frame that never posts again — a synchronous `while(true)` in the user's
+// own script, or a runaway re-render loop the bootstrap's own coalescing
+// can't outpace — has nothing else to signal it. Silence past this long since
+// mount (or since the last message) is treated as hung and the frame is torn
+// down; the bootstrap's 1s heartbeat means a merely-idle-but-alive frame never
+// gets close to this.
+const _WATCHDOG_MS = 6000;
+
 // Live preview for a renderable fenced block: a Preview/Code toggle rendered
 // via a sandboxed iframe whose document is an encoded data: URL.
 //
@@ -407,9 +418,11 @@ function PreviewFrame({ lang, value, expanded }) {
   const [doc, setDoc] = useState("");
   const [buildError, setBuildError] = useState("");
   const [height, setHeight] = useState(240);
+  const [hung, setHung] = useState(false);
   const frameRef = useRef(null);
   const heightRef = useRef(240);  // mirrors `height` so the listener needn't re-subscribe
   const stepsRef = useRef(0);
+  const lastMsgRef = useRef(0);  // set for real by the watchdog effect below
 
   // Receive the bootstrap's reports. The frame is on an opaque origin, so
   // e.origin is the string "null" and proves nothing - identify the sender by
@@ -419,6 +432,7 @@ function PreviewFrame({ lang, value, expanded }) {
       if (!frameRef.current || e.source !== frameRef.current.contentWindow) return;
       const data = e.data;
       if (!data || data.__nexusPreview !== 1) return;
+      lastMsgRef.current = Date.now();
 
       if (typeof data.err === "string" && data.err) setError(data.err);
 
@@ -435,6 +449,23 @@ function PreviewFrame({ lang, value, expanded }) {
     return () => window.removeEventListener("message", onMessage);
   }, []);
 
+  // Watchdog: a frame that goes silent past _WATCHDOG_MS — most likely a
+  // synchronous infinite loop in the model's own script, which blocks even
+  // the bootstrap's heartbeat from ever running — gets torn down rather than
+  // left spinning. Checked on an interval rather than a single timeout so a
+  // message arriving late (slow compile, heavy first paint) keeps resetting
+  // the clock instead of tripping early.
+  useEffect(() => {
+    lastMsgRef.current = Date.now();
+    const id = setInterval(() => {
+      if (Date.now() - lastMsgRef.current > _WATCHDOG_MS) {
+        setHung(true);
+        clearInterval(id);
+      }
+    }, 1000);
+    return () => clearInterval(id);
+  }, [lang, value]);
+
   useEffect(() => {
     let current = true;
     setDoc("");
@@ -448,9 +479,13 @@ function PreviewFrame({ lang, value, expanded }) {
   }, [lang, value]);
 
   // A build failure (JSX that doesn't parse) has no document to show at all, so
-  // the message stands in for the frame rather than sitting under it.
-  const frameUrl = doc ? `data:text/html;charset=utf-8,${encodeURIComponent(doc)}` : "";
-  const shown = buildError || error;
+  // the message stands in for the frame rather than sitting under it. A hung
+  // frame tears down the same way: dropping frameUrl unmounts the iframe,
+  // which is what actually stops a runaway script from holding the tab.
+  const frameUrl = doc && !hung ? `data:text/html;charset=utf-8,${encodeURIComponent(doc)}` : "";
+  const shown = hung
+    ? "Preview stopped responding (likely an infinite loop) and was stopped."
+    : buildError || error;
 
   return (
     <>

management/__init__.py

@@ -0,0 +1,5 @@
+"""Desktop-only NexusOS management helpers (Tk control panel, XFCE panel).
+
+The portable CLI lives in the `nexusos_cli` package - that is what the
+wheel ships and what `ncp`/`nexus`/`nexusos` dispatch to.
+"""

management/ncp.cmd

@@ -12,17 +12,20 @@ REM exactly what this file exists to avoid.
 REM
 REM ASCII only, same rule as the .ps1 files - a test in tests/test_smoke.py enforces it.
 setlocal
-REM ncp.py pins its stdout to UTF-8 (it prints check marks and em-dashes, and a
+REM The CLI pins its stdout to UTF-8 (it prints check marks and em-dashes, and a
 REM redirected stdout would otherwise raise UnicodeEncodeError). A console still
 REM on codepage 437 renders those bytes as mojibake, so switch it to UTF-8 here.
 REM ponytail: chcp changes the calling console's codepage and does not restore
 REM it on exit. Harmless in practice; if that ever matters, set the console CP
-REM from inside ncp.py with ctypes SetConsoleOutputCP instead.
+REM from inside the CLI with ctypes SetConsoleOutputCP instead.
 chcp 65001 >nul 2>&1
 set "ROOT=%~dp0.."
 REM System Python fallback so backup/restore work before the venv exists; those
 REM delegate to the stdlib-only bin/sync.py. Mirrors the same fallback in ncp.ps1.
 set "PY=%ROOT%\Promethean\Scripts\python.exe"
 if not exist "%PY%" set "PY=python"
-"%PY%" "%ROOT%\management\ncp.py" %*
-exit /b %ERRORLEVEL%
+pushd "%ROOT%"
+"%PY%" -m nexusos_cli.cli %*
+set "NEXUS_EXIT=%ERRORLEVEL%"
+popd
+exit /b %NEXUS_EXIT%

management/nexus-cli.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# ncp - Linux entry point. The CLI itself is management/ncp.py, which runs
+# ncp - Linux entry point. The CLI itself is nexusos_cli/cli.py, which runs
 # unchanged on Windows too (see management/ncp.cmd); this stays a shell script
 # because ~/.bashrc, launch_nexus.sh, bin/restore-linux.sh, controlpanel.py,
 # bin/panel/nexus-popup.py and management/nexus-app.sh all invoke this path.
@@ -8,9 +8,10 @@
 # directory drives itself instead of reaching into the real install.
 NEXUS_ROOT="$(cd "$(dirname "$(realpath "$0")")/.." && pwd)"
 
-# ncp.py needs psutil (venv), but its backup/restore path delegates to the
-# stdlib-only bin/sync.py and must work before the venv is built.
+# Prefer the project venv for the full desktop dependency set. The portable CLI
+# falls back to system Python when the package is installed without that venv.
 PY="$NEXUS_ROOT/Promethean/bin/python3"
 [ -x "$PY" ] || PY=python3
 
-exec "$PY" "$NEXUS_ROOT/management/ncp.py" "$@"
+cd "$NEXUS_ROOT"
+exec "$PY" -m nexusos_cli.cli "$@"

management/test_controlpanel_close.py

@@ -11,7 +11,10 @@ import pytest
 
 pytest.importorskip("tkinter", reason="controlpanel is a Tk GUI; headless boxes lack python3-tk")
 
-from controlpanel import NexusControlPanel  # noqa: E402
+try:
+    from management.controlpanel import NexusControlPanel  # noqa: E402
+except ModuleNotFoundError:  # direct: python management/test_controlpanel_close.py
+    from controlpanel import NexusControlPanel  # type: ignore[no-redef]  # noqa: E402
 
 
 def _fake(closing, after_raises):

nexusos_cli/__init__.py

@@ -0,0 +1,7 @@
+"""The portable NexusOS command line, shipped in the wheel.
+
+Kept out of `management/` so the installed distribution does not claim a
+top-level `management` package name in site-packages. `management/` stays in
+the source checkout for the desktop-only pieces - the Tk control panel, the
+shell wrappers, the XFCE panel and .desktop wiring.
+"""

nexusos_cli/cli.py

@@ -0,0 +1,848 @@
+"""Portable NexusOS command line used by the ``nexus`` and ``ncp`` scripts."""
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+import webbrowser
+from pathlib import Path
+from urllib.parse import urlparse
+
+from synapse import nexus_config as config
+from synapse.nexus_config import settings
+
+from . import ncp as services
+
+
+CONFIG_SCHEMA = {
+    "home": "path",
+    "api_url": "url",
+    "bind_host": "text",
+    "backend_port": "port",
+    "provider": "provider",
+    "provider_url": "url",
+    "provider_timeout": "positive_int",
+    "data_dir": "path",
+    "models_dir": "path",
+    "runtime_dir": "path",
+    "memory_dir": "path",
+    "memory_db": "path",
+}
+
+LEGACY_TARGETS = {
+    "-b": "backend",
+    "--backend": "backend",
+    "-f": "frontend",
+    "--frontend": "frontend",
+    "-a": "ai",
+    "--ai": "ai",
+}
+
+
+def _emit(payload, json_output: bool = False) -> None:
+    if json_output:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    elif isinstance(payload, str):
+        print(payload)
+    else:
+        for key, value in payload.items():
+            print(f"{key}: {value}")
+
+
+def _http_ok(url: str, timeout: float = 1.0) -> bool:
+    try:
+        urllib.request.urlopen(url, timeout=timeout).read(1)
+        return True
+    except urllib.error.HTTPError:
+        return True
+    except Exception:
+        return False
+
+
+def _is_termux() -> bool:
+    prefix = os.getenv("PREFIX", "")
+    return "com.termux" in prefix or bool(os.getenv("TERMUX_VERSION"))
+
+
+def _validate_config(key: str, raw: str):
+    kind = CONFIG_SCHEMA[key]
+    value = raw.strip()
+    if kind == "url":
+        parsed = urlparse(value)
+        if parsed.scheme not in ("http", "https") or not parsed.netloc:
+            raise ValueError(f"{key} must be an http(s) URL")
+        return value.rstrip("/")
+    if kind == "port":
+        number = int(value)
+        if not 1 <= number <= 65535:
+            raise ValueError(f"{key} must be between 1 and 65535")
+        return number
+    if kind == "positive_int":
+        number = int(value)
+        if number <= 0:
+            raise ValueError(f"{key} must be greater than zero")
+        return number
+    if kind == "provider":
+        if value not in ("ollama", "ollama-remote"):
+            raise ValueError("provider must be ollama or ollama-remote")
+        return value
+    if kind == "path":
+        return str(Path(value).expanduser().resolve())
+    if not value:
+        raise ValueError(f"{key} cannot be empty")
+    return value
+
+
+def cmd_init(args) -> int:
+    config.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    copied = list(config.INITIALIZED_FILES) + config.init_state()
+    payload = {
+        "status": "initialized",
+        "state_dir": str(settings.state_dir),
+        "config_file": str(settings.config_file),
+        "data_dir": str(settings.data_dir),
+        "models_dir": str(settings.models_dir),
+        "runtime_dir": str(settings.runtime_dir),
+        "seeded_playbooks": len(copied),
+    }
+    _emit(payload, args.json)
+    return 0
+
+
+def cmd_paths(args) -> int:
+    payload = {
+        "install_mode": "checkout" if settings.source_checkout else "wheel",
+        "project_root": str(settings.project_root),
+        "resource_root": str(settings.resource_root),
+        "state_dir": str(settings.state_dir),
+        "config_file": str(settings.config_file),
+        "data_dir": str(settings.data_dir),
+        "memory_db": str(settings.memory_db),
+        "models_dir": str(settings.models_dir),
+        "runtime_dir": str(settings.runtime_dir),
+        "web_dist_dir": str(settings.web_dist_dir),
+    }
+    _emit(payload, args.json)
+    return 0
+
+
+# Keys whose value decides where the SQLite database is looked up. Changing one
+# does not move the file, so the next start would quietly open a fresh, empty
+# database and the user's conversations and memories would look deleted.
+_DB_LOCATION_KEYS = ("memory_db", "memory_dir", "data_dir", "home")
+
+
+def _relocation_warning(key: str, value) -> str | None:
+    """Warn when a config change points the database somewhere with no data."""
+    if key not in _DB_LOCATION_KEYS:
+        return None
+    current = settings.memory_db
+    if not current.is_file():
+        return None
+    if key == "memory_db":
+        new_db = Path(str(value))
+    elif key == "memory_dir":
+        new_db = Path(str(value)) / current.name
+    else:
+        # data_dir/home only decide the DB location when nothing more specific
+        # does, and only in the layout where the DB actually sits under them -
+        # a source checkout keeps it in synapse/memory/ regardless.
+        existing = config.read_user_config()
+        if "memory_dir" in existing or "memory_db" in existing:
+            return None
+        anchor = settings.data_dir if key == "data_dir" else settings.state_dir
+        try:
+            tail = current.resolve().relative_to(anchor.resolve())
+        except ValueError:
+            return None
+        new_db = Path(str(value)) / tail
+    if new_db.resolve() == current.resolve() or new_db.is_file():
+        return None
+    return (
+        f"{current} holds your existing conversations and memories, but this "
+        f"change points NexusOS at {new_db}, which does not exist yet - it will "
+        "start with an empty database. Stop NexusOS and move the .db (plus any "
+        "-wal/-shm files) to the new path to keep your history."
+    )
+
+
+def cmd_config(args) -> int:
+    values = config.read_user_config()
+    if args.action == "path":
+        print(config.CONFIG_FILE)
+        return 0
+    if args.action == "list":
+        _emit(values, args.json)
+        return 0
+    if args.action == "get":
+        if args.key not in CONFIG_SCHEMA:
+            print(f"Unknown configuration key: {args.key}", file=sys.stderr)
+            return 2
+        value = values.get(args.key, getattr(settings, args.key, None))
+        _emit({args.key: value}, args.json)
+        return 0
+    if args.action == "set":
+        if args.key not in CONFIG_SCHEMA:
+            print(f"Unknown configuration key: {args.key}", file=sys.stderr)
+            print("Known keys: " + ", ".join(CONFIG_SCHEMA), file=sys.stderr)
+            return 2
+        try:
+            values[args.key] = _validate_config(args.key, args.value)
+        except (TypeError, ValueError) as exc:
+            print(f"Invalid value: {exc}", file=sys.stderr)
+            return 2
+        payload = {"updated": args.key, "value": values[args.key], "restart_required": True}
+        moved = _relocation_warning(args.key, values[args.key])
+        if moved:
+            payload["warning"] = moved
+        config.write_user_config(values)
+        _emit(payload, args.json)
+        if moved and not args.json:
+            print(f"\nWARNING: {moved}", file=sys.stderr)
+        return 0
+    if args.action == "unset":
+        if args.key not in CONFIG_SCHEMA:
+            print(f"Unknown configuration key: {args.key}", file=sys.stderr)
+            return 2
+        values.pop(args.key, None)
+        config.write_user_config(values)
+        _emit({"removed": args.key, "restart_required": True}, args.json)
+        return 0
+    return 2
+
+
+def _provider_payload() -> dict:
+    url = settings.ollama_host.rstrip("/")
+    return {
+        "provider": settings.provider,
+        "url": url,
+        "managed_by_nexus": settings.manage_ollama,
+        "reachable": _http_ok(url + "/api/tags", timeout=2.0),
+    }
+
+
+def cmd_provider(args) -> int:
+    if args.action == "show":
+        _emit(_provider_payload(), args.json)
+        return 0
+
+    values = config.read_user_config()
+    if args.mode == "local":
+        values["provider"] = "ollama"
+        try:
+            values["provider_url"] = _validate_config(
+                "provider_url", args.url or "http://127.0.0.1:11434"
+            )
+        except ValueError as exc:
+            print(f"Invalid value: {exc}", file=sys.stderr)
+            return 2
+    else:
+        if not args.url:
+            print("Remote provider setup requires --url", file=sys.stderr)
+            return 2
+        try:
+            values["provider_url"] = _validate_config("provider_url", args.url)
+        except ValueError as exc:
+            print(f"Invalid value: {exc}", file=sys.stderr)
+            return 2
+        values["provider"] = "ollama-remote"
+    config.write_user_config(values)
+    _emit({
+        "provider": values["provider"],
+        "url": values["provider_url"],
+        "restart_required": True,
+    }, args.json)
+    return 0
+
+
+def _check_import(module: str) -> bool:
+    return importlib.util.find_spec(module) is not None
+
+
+def _writable(path: Path) -> bool:
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+        probe = path / ".nexus-write-test"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+        return True
+    except OSError:
+        return False
+
+
+def diagnostics() -> dict:
+    checks: list[dict] = []
+
+    def add(name: str, ok: bool, detail: str, required: bool = True):
+        checks.append({
+            "name": name,
+            "status": "pass" if ok else ("fail" if required else "warn"),
+            "detail": detail,
+            "required": required,
+        })
+
+    add("python", sys.version_info >= (3, 11), sys.version.split()[0])
+    add("state", _writable(settings.state_dir), str(settings.state_dir))
+    add("database directory", _writable(settings.memory_db.parent), str(settings.memory_db.parent))
+    add("web assets", (settings.web_dist_dir / "index.html").is_file(), str(settings.web_dist_dir))
+    add(
+        "provider mode",
+        settings.provider in ("ollama", "ollama-remote"),
+        settings.provider,
+    )
+    add(
+        "service ports",
+        1 <= settings.backend_port <= 65535,
+        f"backend={settings.backend_port}",
+    )
+    for module in ("fastapi", "uvicorn", "httpx", "pydantic", "yaml"):
+        add(f"import:{module}", _check_import(module), module)
+
+    add("backend", _http_ok(settings.api_url + "/status"), settings.api_url, required=False)
+    provider = _provider_payload()
+    add("provider", provider["reachable"], provider["url"], required=False)
+    if settings.manage_ollama:
+        add("ollama executable", bool(services.ollama_bin()), services.ollama_bin() or "not on PATH", required=False)
+
+    for label, module in (
+        ("process control", "psutil"),
+        ("vector search", "sqlite_vec"),
+        ("voice transcription", "faster_whisper"),
+        ("PDF documents", "pypdf"),
+        ("Word documents", "docx"),
+        ("web search", "duckduckgo_search"),
+    ):
+        add(label, _check_import(module), module, required=False)
+
+    return {
+        "ok": not any(c["status"] == "fail" for c in checks),
+        "version": settings.version,
+        "install_mode": "checkout" if settings.source_checkout else "wheel",
+        "platform": sys.platform,
+        "termux": _is_termux(),
+        "checks": checks,
+    }
+
+
+def _doctor_fix() -> None:
+    config.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    config.init_state()
+    index = settings.web_dist_dir / "index.html"
+    npm = shutil.which("npm.cmd" if os.name == "nt" else "npm")
+    if settings.source_checkout and not index.exists() and npm:
+        subprocess.run([npm, "run", "build"], cwd=str(settings.frontend_source_dir), check=False)
+
+
+def cmd_doctor(args) -> int:
+    if args.fix:
+        _doctor_fix()
+    result = diagnostics()
+    if args.json:
+        _emit(result, True)
+    else:
+        print(f"NexusOS {result['version']} diagnostics ({result['install_mode']})\n")
+        marks = {"pass": "OK", "warn": "WARN", "fail": "FAIL"}
+        for check in result["checks"]:
+            print(f"  {marks[check['status']]:<4} {check['name']:<20} {check['detail']}")
+        print("\nCore runtime is ready." if result["ok"] else "\nCore runtime has required failures.")
+    return 0 if result["ok"] else 1
+
+
+def service_status() -> dict:
+    payload = {}
+    for key in ("backend", "frontend"):
+        svc = services.SERVICES[key]
+        pid = services.read_pid(svc)
+        payload[key] = {
+            "running": services.alive(pid) or _http_ok(svc.url),
+            "pid": pid if services.alive(pid) else None,
+            "url": svc.url,
+        }
+    payload["provider"] = _provider_payload()
+    return payload
+
+
+def cmd_status(args) -> int:
+    payload = service_status()
+    if args.json:
+        _emit(payload, True)
+        return 0
+    print("Nexus Service Status:\n")
+    for key in ("backend", "frontend"):
+        info = payload[key]
+        suffix = f" (PID {info['pid']})" if info["pid"] else ""
+        print(f"  {key:<10} {'RUNNING' if info['running'] else 'STOPPED'}{suffix}  {info['url']}")
+    p = payload["provider"]
+    print(f"  provider   {'RUNNING' if p['reachable'] else 'STOPPED'}  {p['provider']} @ {p['url']}")
+    return 0
+
+
+def cmd_monitor(args) -> int:
+    from .monitor import run_monitor
+    return run_monitor(
+        interval=getattr(args, "interval", 1.5),
+        once=bool(getattr(args, "once", False) or getattr(args, "json", False)),
+        json_output=bool(getattr(args, "json", False)),
+    )
+
+
+def cmd_tui(args) -> int:
+    """Interactive Hermes/OpenClaw-style chat TUI (requires nexusos-ai[tui])."""
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        print(
+            "The TUI needs a terminal. Use: nexus chat send \"…\"\n"
+            "Or run `nexus` in an interactive shell.",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        from .tui_app import run_tui
+    except ImportError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    api = getattr(args, "api_url", None) or settings.api_url
+    return run_tui(api_url=api)
+
+
+def _target_flag(target: str | None):
+    return {
+        "backend": "--backend",
+        "frontend": "--frontend",
+        "ai": "--ai",
+    }.get(target or "all")
+
+
+def cmd_start(args) -> int:
+    services.cmd_start(_target_flag(args.target))
+    return 0
+
+
+def cmd_stop(args) -> int:
+    services.cmd_stop(_target_flag(args.target))
+    return 0
+
+
+def cmd_refresh(args) -> int:
+    services.cmd_stop(None)
+    services.cmd_start(None)
+    return 0
+
+
+def _lan_hostnames(host: str) -> list[str]:
+    """Every name/address a --allow-lan bind should accept in a Host header.
+
+    A wildcard bind answers on all interfaces, so enumerate them; an explicit
+    address answers only as itself. The machine hostname comes along because
+    that is what people actually type."""
+    import socket
+
+    names: list[str] = []
+
+    def add(value: str) -> None:
+        if value and value not in names:
+            names.append(value)
+
+    if host in ("0.0.0.0", "::", "*"):
+        hostname = socket.gethostname()
+        add(hostname)
+        add(hostname.split(".")[0] + ".local")
+        for family in (socket.AF_INET, socket.AF_INET6):
+            try:
+                for info in socket.getaddrinfo(hostname, None, family):
+                    add(info[4][0])
+            except OSError:
+                pass
+        # getaddrinfo(hostname) misses the routable address on hosts that map
+        # their own name to loopback; a connectionless UDP socket finds it.
+        for probe, family in (("8.8.8.8", socket.AF_INET), ("2001:4860:4860::8888", socket.AF_INET6)):
+            sock = socket.socket(family, socket.SOCK_DGRAM)
+            try:
+                sock.connect((probe, 80))
+                add(sock.getsockname()[0])
+            except OSError:
+                pass
+            finally:
+                sock.close()
+    else:
+        add(host.strip("[]"))
+    # A Host header carries an IPv6 literal bracketed; allow both spellings so
+    # the check matches however the client wrote it.
+    for value in list(names):
+        if ":" in value:
+            add(f"[{value}]")
+    return names
+
+
+def _origin_host(name: str) -> str:
+    """Origin-safe spelling: IPv6 literals must be bracketed in a URL."""
+    if ":" in name and not name.startswith("["):
+        return f"[{name}]"
+    return name
+
+
+def cmd_serve(args) -> int:
+    host = args.host or settings.bind_host
+    if host not in ("127.0.0.1", "localhost", "::1") and not args.allow_lan:
+        print("Refusing an unauthenticated LAN bind. Add --allow-lan to acknowledge the exposure.", file=sys.stderr)
+        return 2
+    if _http_ok(f"http://127.0.0.1:{args.port}/"):
+        print(f"Port {args.port} is already serving HTTP.", file=sys.stderr)
+        return 2
+
+    settings.backend_port = args.port
+    settings.bind_host = host
+    settings.api_url = f"http://127.0.0.1:{args.port}"
+    os.environ["NEXUS_BACKEND_PORT"] = str(args.port)
+    os.environ["NEXUS_BIND_HOST"] = host
+    for origin_host in ("localhost", "127.0.0.1"):
+        origin = f"http://{origin_host}:{args.port}"
+        if origin not in config.ALLOWED_ORIGINS:
+            config.ALLOWED_ORIGINS.append(origin)
+    if args.allow_lan:
+        # Widen to the addresses this bind actually answers on - NOT "*".
+        # ALLOWED_HOSTS drives TrustedHostMiddleware, which is the DNS-rebinding
+        # defense: with "*" any site the user browses could resolve a name it
+        # controls to this machine and drive the unauthenticated API. Naming the
+        # real addresses keeps that check doing its job. An explicitly exported
+        # NEXUS_ALLOWED_HOSTS still wins, for anyone who needs the old blanket.
+        names = _lan_hostnames(host)
+        for name in names:
+            if name not in config.ALLOWED_HOSTS:
+                config.ALLOWED_HOSTS.append(name)
+            origin = f"http://{_origin_host(name)}:{args.port}"
+            if origin not in config.ALLOWED_ORIGINS:
+                config.ALLOWED_ORIGINS.append(origin)
+        os.environ.setdefault("NEXUS_ALLOWED_HOSTS", ",".join(config.ALLOWED_HOSTS))
+        os.environ.setdefault("NEXUS_ALLOWED_ORIGINS", ",".join(config.ALLOWED_ORIGINS))
+        print(
+            "LAN exposure enabled for: " + ", ".join(names)
+            + "\nThe REST API is unauthenticated - anyone who can reach this port"
+            " has full admin and data access."
+        )
+
+    print(f"NexusOS serving on http://{host}:{args.port}")
+    import uvicorn
+    uvicorn.run(
+        "synapse.main:sio_app", host=host, port=args.port,
+        reload=bool(args.reload and settings.source_checkout),
+        log_level=args.log_level,
+    )
+    return 0
+
+
+def cmd_open(args) -> int:
+    if not _http_ok(settings.api_url + "/status") and not args.no_start:
+        services.cmd_start(None)
+    url = args.url or settings.api_url
+    opener = shutil.which("termux-open-url") if _is_termux() else None
+    opened = False
+    if opener:
+        opened = subprocess.run([opener, url], check=False).returncode == 0
+    else:
+        opened = webbrowser.open(url)
+    print(f"{'Opened' if opened else 'NexusOS is available at'} {url}")
+    return 0
+
+
+def cmd_web(args) -> int:
+    """Preserve ``ncp web`` for desktop checkouts; wheels use the browser UI."""
+    if settings.source_checkout:
+        return services.cmd_web()
+    return cmd_open(argparse.Namespace(url=None, no_start=False))
+
+
+def cmd_panel(_args) -> int:
+    if not settings.source_checkout:
+        print("The legacy Tk control panel is only available in a desktop source install.", file=sys.stderr)
+        return 2
+    return services.main(["panel"])
+
+
+def cmd_backup(args) -> int:
+    if not settings.source_checkout:
+        print("Backup is a source-checkout command; wheel state should be backed up from nexus paths.", file=sys.stderr)
+        return 2
+    if args.check:
+        return services.sync_py("backup", "--check")
+    if args.full:
+        return services.sync_py("backup", "--full")
+    return services.sync_py("backup")
+
+
+def cmd_restore(args) -> int:
+    if not settings.source_checkout:
+        print("Restore is a source-checkout command; reinstall the wheel and restore its state directory.", file=sys.stderr)
+        return 2
+    return services.cmd_restore("--check" if args.check else None)
+
+
+def cmd_nvidia_reqs(_args) -> int:
+    if not settings.source_checkout:
+        print("nvidia-reqs is only available in a desktop source install.", file=sys.stderr)
+        return 2
+    return subprocess.run(
+        [sys.executable, str(settings.project_root / "bin" / "gen-nvidia-reqs.py")]
+    ).returncode
+
+
+def cmd_logs(args) -> int:
+    keys = ("backend", "frontend") if args.target == "all" else (args.target,)
+    paths = [services.SERVICES[key].log_file for key in keys]
+    for path in paths:
+        print(f"=== {path.name} ===")
+        services._tail(path, args.lines)
+    if not args.follow:
+        return 0
+    offsets = {path: path.stat().st_size if path.exists() else 0 for path in paths}
+    try:
+        while True:
+            for path in paths:
+                if not path.exists():
+                    continue
+                size = path.stat().st_size
+                if size < offsets[path]:
+                    offsets[path] = 0
+                if size > offsets[path]:
+                    with open(path, encoding="utf-8", errors="replace") as stream:
+                        stream.seek(offsets[path])
+                        sys.stdout.write(stream.read())
+                        sys.stdout.flush()
+                        offsets[path] = stream.tell()
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        print()
+        return 130
+
+
+def cmd_clean(args) -> int:
+    for path in (settings.runtime_dir / "pids", settings.runtime_dir / "logs"):
+        if path.is_dir():
+            for file in path.glob("*"):
+                if file.is_file():
+                    file.unlink(missing_ok=True)
+    for pattern in ("*.log", "*.pid"):
+        for file in settings.runtime_dir.glob(pattern):
+            file.unlink(missing_ok=True)
+    print(f"Cleaned runtime files under {settings.runtime_dir}")
+    return 0
+
+
+def cmd_update(args) -> int:
+    if settings.source_checkout:
+        services.cmd_update()
+        return 0
+    command = [sys.executable, "-m", "pip", "install", "--upgrade", "nexusos-ai"]
+    if args.pre:
+        command.append("--pre")
+    return subprocess.run(command).returncode
+
+
+def cmd_models(args) -> int:
+    import httpx
+
+    base = settings.ollama_host.rstrip("/")
+    try:
+        if args.action == "list":
+            response = httpx.get(base + "/api/tags", timeout=5.0)
+            response.raise_for_status()
+            models = response.json().get("models", [])
+            if args.json:
+                _emit(models, True)
+            elif not models:
+                print("No models installed.")
+            else:
+                for model in models:
+                    print(f"{model.get('name', ''):<36} {model.get('size', 0) / 1024**3:5.1f} GB")
+        elif args.action == "available":
+            services.cmd_models("available", None)
+        elif args.action in ("pull", "install"):
+            with httpx.stream("POST", base + "/api/pull", json={"name": args.name}, timeout=None) as response:
+                response.raise_for_status()
+                for line in response.iter_lines():
+                    if line:
+                        try:
+                            item = json.loads(line)
+                            status = item.get("status") or item.get("error")
+                            if status:
+                                print(status)
+                        except ValueError:
+                            print(line)
+        elif args.action in ("remove", "rm"):
+            response = httpx.request("DELETE", base + "/api/delete", json={"name": args.name}, timeout=30.0)
+            response.raise_for_status()
+            print(f"Removed {args.name}")
+        return 0
+    except httpx.HTTPError as exc:
+        print(f"Provider request failed at {base}: {exc}", file=sys.stderr)
+        return 1
+
+
+def cmd_api(args) -> int:
+    from . import nexus_api
+    nexus_api.BASE = args.api_url or settings.api_url
+    rest = list(args.rest)
+    if args.command == "chat" and rest[:1] == ["send"]:
+        rest.pop(0)
+    if args.command == "history" and rest[:1] == ["list"]:
+        rest.pop(0)
+    return nexus_api.main([args.command, *rest], prog=f"nexus {args.command}")
+
+
+def _add_json(parser) -> None:
+    parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+
+
+def _port(value: str) -> int:
+    try:
+        return _validate_config("backend_port", value)
+    except (TypeError, ValueError) as exc:
+        raise argparse.ArgumentTypeError(str(exc)) from exc
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nexus",
+        description=(
+            "NexusOS local AI runtime and API client. "
+            "With no subcommand, opens the interactive TUI (needs nexusos-ai[tui])."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"NexusOS {settings.version}")
+    parser.add_argument("--api-url", help="override the NexusOS backend URL for this command")
+    # Bare `nexus` → TUI. Subcommands remain for scripts and one-shots.
+    sub = parser.add_subparsers(dest="command", required=False)
+
+    p = sub.add_parser("tui", help="interactive chat TUI (default when no subcommand)")
+    p.set_defaults(fn=cmd_tui)
+
+    p = sub.add_parser("init", help="create user state and seed default playbooks"); _add_json(p); p.set_defaults(fn=cmd_init)
+    p = sub.add_parser("paths", help="show resolved package and writable paths"); _add_json(p); p.set_defaults(fn=cmd_paths)
+
+    p = sub.add_parser("config", help="manage persistent CLI/runtime configuration")
+    p.add_argument("action", choices=["list", "get", "set", "unset", "path"])
+    p.add_argument("key", nargs="?"); p.add_argument("value", nargs="?"); _add_json(p); p.set_defaults(fn=cmd_config)
+
+    p = sub.add_parser("provider", help="configure the Ollama-compatible model provider")
+    provider_sub = p.add_subparsers(dest="action", required=True)
+    show = provider_sub.add_parser("show"); _add_json(show); show.set_defaults(fn=cmd_provider)
+    use = provider_sub.add_parser("use"); use.add_argument("mode", choices=["local", "remote"])
+    use.add_argument("--url"); _add_json(use); use.set_defaults(fn=cmd_provider)
+
+    p = sub.add_parser("doctor", help="check the core runtime and optional capabilities")
+    p.add_argument("--fix", action="store_true"); _add_json(p); p.set_defaults(fn=cmd_doctor)
+    p = sub.add_parser("status", help="show service and provider status"); _add_json(p); p.set_defaults(fn=cmd_status)
+    p = sub.add_parser("monitor", help="ASCII dashboard for services, resources, and tool stats")
+    p.add_argument("--once", action="store_true", help="print one frame and exit")
+    p.add_argument("--interval", type=float, default=1.5, help="refresh seconds (live mode)")
+    _add_json(p)
+    p.set_defaults(fn=cmd_monitor)
+
+    p = sub.add_parser("serve", help="run NexusOS in the foreground")
+    p.add_argument("--host"); p.add_argument("--port", type=_port, default=settings.backend_port)
+    p.add_argument("--allow-lan", action="store_true")
+    p.add_argument("--reload", action="store_true"); p.add_argument("--log-level", default="info")
+    p.set_defaults(fn=cmd_serve)
+
+    for name, fn, help_text in (
+        ("start", cmd_start, "start services in the background"),
+        ("stop", cmd_stop, "stop background services"),
+    ):
+        p = sub.add_parser(name, help=help_text)
+        p.add_argument("target", nargs="?", choices=["all", "backend", "frontend", "ai"], default="all")
+        p.set_defaults(fn=fn)
+    sub.add_parser("restart", aliases=["refresh"], help="restart all services").set_defaults(fn=cmd_refresh)
+    sub.add_parser("kill", help="force-stop NexusOS-owned processes").set_defaults(fn=lambda _a: services.cmd_kill() or 0)
+
+    p = sub.add_parser("open", help="open the web interface")
+    p.add_argument("--url"); p.add_argument("--no-start", action="store_true"); p.set_defaults(fn=cmd_open)
+    sub.add_parser("web", help="legacy desktop alias for open").set_defaults(fn=cmd_web)
+    sub.add_parser("panel", help="launch the legacy desktop control panel").set_defaults(fn=cmd_panel)
+    p = sub.add_parser("logs", help="read or follow service logs")
+    p.add_argument("target", nargs="?", choices=["all", "backend", "frontend"], default="all")
+    p.add_argument("--lines", type=int, choices=range(1, 10001), default=50, metavar="1..10000")
+    p.add_argument("--follow", "-f", action="store_true"); p.set_defaults(fn=cmd_logs)
+    sub.add_parser("clean", help="remove runtime logs and stale PID files").set_defaults(fn=cmd_clean)
+    p = sub.add_parser("update", help="update dependencies or the installed wheel"); p.add_argument("--pre", action="store_true"); p.set_defaults(fn=cmd_update)
+
+    p = sub.add_parser("backup", help="back up a desktop source checkout")
+    p.add_argument("--full", "-f", action="store_true"); p.add_argument("--check", "-c", action="store_true")
+    p.set_defaults(fn=cmd_backup)
+    p = sub.add_parser("restore", help="restore a desktop source checkout")
+    p.add_argument("--check", "-c", action="store_true"); p.set_defaults(fn=cmd_restore)
+    sub.add_parser("nvidia-reqs", help="regenerate source-checkout NVIDIA requirements").set_defaults(fn=cmd_nvidia_reqs)
+
+    p = sub.add_parser("models", help="list, pull, and remove provider models")
+    model_sub = p.add_subparsers(dest="action", required=True)
+    item = model_sub.add_parser("list"); _add_json(item); item.set_defaults(fn=cmd_models)
+    model_sub.add_parser("available", aliases=["search"]).set_defaults(fn=cmd_models, action="available")
+    item = model_sub.add_parser("pull", aliases=["install"]); item.add_argument("name"); item.set_defaults(fn=cmd_models, action="pull")
+    item = model_sub.add_parser("remove", aliases=["rm"]); item.add_argument("name"); item.set_defaults(fn=cmd_models, action="remove")
+
+    for command in ("chat", "memory", "playbook", "history"):
+        p = sub.add_parser(command, add_help=False, help=f"use the {command} API from the terminal")
+        p.add_argument("rest", nargs=argparse.REMAINDER)
+        p.set_defaults(fn=cmd_api)
+    return parser
+
+
+def _normalize_legacy_argv(argv) -> list[str]:
+    """Translate the old shell CLI spelling before argparse sees it."""
+    normalized = list(argv or [])
+    if normalized == ["help"]:
+        return ["--help"]
+    # start/stop only. `logs` registers -f as the short form of --follow, so
+    # translating it here would silently rewrite `logs -f` to `logs frontend`
+    # - a tail of the wrong file instead of a follow, with no error.
+    if normalized and normalized[0] in ("start", "stop"):
+        normalized[1:] = [LEGACY_TARGETS.get(value, value) for value in normalized[1:]]
+    elif normalized[:1] == ["logs"]:
+        normalized[1:] = [
+            value if value in ("-f", "--follow") else LEGACY_TARGETS.get(value, value)
+            for value in normalized[1:]
+        ]
+    if normalized[:2] == ["backup", "full"]:
+        normalized[1] = "--full"
+    elif len(normalized) > 1 and normalized[0] == "backup" and normalized[1] in ("check", "--claude"):
+        normalized[1] = "--check"
+    elif len(normalized) > 1 and normalized[0] == "restore":
+        if normalized[1] in ("check", "--claude"):
+            normalized[1] = "--check"
+        elif normalized[1] in ("full", "-f", "--full"):
+            normalized.pop(1)
+    return normalized
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    argv = _normalize_legacy_argv(argv)
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        # Bare `nexus` / `ncp` / `nexusos` → interactive TUI.
+        args.command = "tui"
+        args.fn = cmd_tui
+    if args.command == "config":
+        if args.action in ("get", "unset") and not args.key:
+            parser.error(f"config {args.action} requires KEY")
+        if args.action == "set" and (not args.key or args.value is None):
+            parser.error("config set requires KEY VALUE")
+    try:
+        result = args.fn(args)
+        return result if isinstance(result, int) else 0
+    except KeyboardInterrupt:
+        print()
+        return 130
+
+
+def entrypoint() -> int:
+    return main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(entrypoint())

nexusos_cli/monitor.py

@@ -0,0 +1,456 @@
+"""ASCII dashboard for live NexusOS service / tool / resource stats.
+
+No curses, no rich — pure box-drawing + optional ANSI color so it works in
+Termux, plain SSH, and Windows Terminal alike. The collector is separate from
+the renderer so tests can feed fixtures without a running stack.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from synapse.nexus_config import settings
+
+from . import ncp as services
+
+# Box drawing — ASCII fallbacks when the terminal can't do Unicode.
+_BOX = {
+    "tl": "┌", "tr": "┐", "bl": "└", "br": "┘",
+    "h": "─", "v": "│", "l": "├", "r": "┤",
+}
+_BOX_ASCII = {
+    "tl": "+", "tr": "+", "bl": "+", "br": "+",
+    "h": "-", "v": "|", "l": "+", "r": "+",
+}
+
+_FILL = "█"
+_EMPTY = "░"
+_FILL_ASCII = "#"
+_EMPTY_ASCII = "-"
+
+
+def _use_unicode() -> bool:
+    enc = (getattr(__import__("sys").stdout, "encoding", None) or "").lower()
+    return "utf" in enc or enc in ("cp65001",)
+
+
+def _http_ok(url: str, timeout: float = 1.0) -> bool:
+    try:
+        urllib.request.urlopen(url, timeout=timeout).read(1)
+        return True
+    except urllib.error.HTTPError:
+        return True
+    except Exception:
+        return False
+
+
+def _provider_payload() -> dict:
+    url = settings.ollama_host.rstrip("/")
+    return {
+        "provider": settings.provider,
+        "url": url,
+        "managed_by_nexus": settings.manage_ollama,
+        "reachable": _http_ok(url + "/api/tags", timeout=2.0),
+    }
+
+
+def _service_status() -> dict:
+    payload = {}
+    for key in ("backend", "frontend"):
+        svc = services.SERVICES[key]
+        pid = services.read_pid(svc)
+        payload[key] = {
+            "running": services.alive(pid) or _http_ok(svc.url),
+            "pid": pid if services.alive(pid) else None,
+            "url": svc.url,
+        }
+    payload["provider"] = _provider_payload()
+    return payload
+
+
+def _get_json(url: str, timeout: float = 1.5) -> Any | None:
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8", errors="replace"))
+    except Exception:
+        return None
+
+
+def _bar(ratio: float, width: int = 20, unicode: bool = True) -> str:
+    ratio = max(0.0, min(1.0, float(ratio)))
+    filled = int(round(ratio * width))
+    fill = _FILL if unicode else _FILL_ASCII
+    empty = _EMPTY if unicode else _EMPTY_ASCII
+    return fill * filled + empty * (width - filled)
+
+
+def _fmt_bytes(n: float | int | None) -> str:
+    if n is None:
+        return "—"
+    n = float(n)
+    for unit in ("B", "K", "M", "G", "T"):
+        if abs(n) < 1024 or unit == "T":
+            return f"{n:.0f}{unit}" if unit == "B" else f"{n:.1f}{unit}"
+        n /= 1024
+    return f"{n:.1f}T"
+
+
+def _pid_stats(pids: list[int | None]) -> dict:
+    """Aggregate CPU%/RSS for known service PIDs. Soft-depends on psutil."""
+    live = [int(p) for p in pids if p]
+    if not live:
+        return {"cpu_pct": None, "rss": None, "pids": []}
+    try:
+        import psutil  # type: ignore
+    except ImportError:
+        return {"cpu_pct": None, "rss": None, "pids": live}
+    cpu = 0.0
+    rss = 0
+    seen: list[int] = []
+    for pid in live:
+        try:
+            proc = psutil.Process(pid)
+            cpu += proc.cpu_percent(interval=0.0)
+            rss += proc.memory_info().rss
+            seen.append(pid)
+        except (psutil.Error, ProcessLookupError, ValueError):
+            continue
+    return {"cpu_pct": cpu, "rss": rss, "pids": seen}
+
+
+def _host_stats() -> dict:
+    try:
+        import psutil  # type: ignore
+    except ImportError:
+        return {"cpu_pct": None, "mem_used": None, "mem_total": None, "mem_pct": None}
+    vm = psutil.virtual_memory()
+    return {
+        "cpu_pct": psutil.cpu_percent(interval=0.05),
+        "mem_used": vm.used,
+        "mem_total": vm.total,
+        "mem_pct": vm.percent,
+    }
+
+
+def _api_counts(api_url: str) -> dict:
+    """Pull cheap inventory counts from the backend when it is up."""
+    base = api_url.rstrip("/")
+    out = {
+        "online": False,
+        "version": None,
+        "ollama": None,
+        "memories": None,
+        "conversations": None,
+        "playbooks": None,
+        "models": None,
+        "action_tool_policy": None,
+    }
+    status = _get_json(base + "/status")
+    if not isinstance(status, dict):
+        return out
+    out["online"] = True
+    out["version"] = status.get("version")
+    out["ollama"] = status.get("ollama")
+
+    mem = _get_json(base + "/memory")
+    if isinstance(mem, list):
+        out["memories"] = len(mem)
+    elif isinstance(mem, dict) and isinstance(mem.get("memories"), list):
+        out["memories"] = len(mem["memories"])
+
+    conv = _get_json(base + "/conversations")
+    if isinstance(conv, list):
+        out["conversations"] = len(conv)
+    elif isinstance(conv, dict):
+        items = conv.get("conversations") or conv.get("items") or []
+        if isinstance(items, list):
+            out["conversations"] = len(items)
+
+    pbs = _get_json(base + "/playbooks")
+    if isinstance(pbs, list):
+        out["playbooks"] = len(pbs)
+    elif isinstance(pbs, dict) and isinstance(pbs.get("playbooks"), list):
+        out["playbooks"] = len(pbs["playbooks"])
+
+    models = _get_json(base + "/models")
+    if isinstance(models, list):
+        out["models"] = len(models)
+    elif isinstance(models, dict):
+        items = models.get("models") or models.get("items") or []
+        if isinstance(items, list):
+            out["models"] = len(items)
+
+    settings_payload = _get_json(base + "/settings")
+    if isinstance(settings_payload, dict):
+        out["action_tool_policy"] = settings_payload.get("action_tool_policy")
+
+    return out
+
+
+def _toolchain_stats() -> list[dict]:
+    """Which run_snippet languages have a host toolchain right now."""
+    try:
+        from synapse import code_run
+    except Exception:
+        return []
+    rows = []
+    for name, spec in code_run.RUN_LANGS.items():
+        tool = None
+        try:
+            tool = spec["tool"]()
+        except Exception:
+            tool = None
+        rows.append({
+            "lang": name,
+            "ready": bool(tool),
+            "tool": tool or None,
+            "summary": spec.get("summary") or name,
+        })
+    return rows
+
+
+def _recent_tools(log_path: Path, limit: int = 8) -> list[str]:
+    """Best-effort scrape of recent tool names from chat.log."""
+    if not log_path.is_file():
+        return []
+    try:
+        # Read the tail without pulling a multi-MB log into memory.
+        data = log_path.read_bytes()
+        if len(data) > 64_000:
+            data = data[-64_000:]
+        text = data.decode("utf-8", errors="replace")
+    except OSError:
+        return []
+    found: list[str] = []
+    for line in reversed(text.splitlines()):
+        # Chat tool loop yields "__status__<tool>"; logs may also name tools
+        # in JSON payloads. Keep the match narrow.
+        if "__status__" in line:
+            name = line.split("__status__", 1)[-1].strip().split()[0].strip(",\"'")
+            if name and name not in ("tools",) and name not in found:
+                found.append(name)
+        elif '"name":' in line and any(
+            t in line for t in ("render_preview", "run_snippet", "web_search",
+                                "fetch_url", "remember", "get_time")
+        ):
+            for t in ("run_snippet", "render_preview", "web_search", "fetch_url",
+                      "remember", "get_time", "search_documents"):
+                if t in line and t not in found:
+                    found.append(t)
+        if len(found) >= limit:
+            break
+    return found
+
+
+def collect_snapshot() -> dict:
+    """Gather one monitoring frame. Safe when services are down."""
+    services_payload = _service_status()
+    pids = [
+        services_payload.get("backend", {}).get("pid"),
+        services_payload.get("frontend", {}).get("pid"),
+    ]
+    api = _api_counts(settings.api_url)
+    return {
+        "ts": datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds"),
+        "version": settings.version,
+        "services": services_payload,
+        "api": api,
+        "host": _host_stats(),
+        "procs": _pid_stats(pids),
+        "toolchains": _toolchain_stats(),
+        "recent_tools": _recent_tools(settings.logs_dir / "chat.log"),
+        "paths": {
+            "api_url": settings.api_url,
+            "runtime_dir": str(settings.runtime_dir),
+        },
+    }
+
+
+def _pad(text: str, width: int) -> str:
+    # Visual width ≈ len for our ASCII/box content (no wide East-Asian chars).
+    if len(text) > width:
+        return text[: width - 1] + "…" if width > 1 else text[:width]
+    return text + " " * (width - len(text))
+
+
+def _row(box: dict, inner: str, width: int) -> str:
+    return f"{box['v']} {_pad(inner, width - 4)} {box['v']}"
+
+
+def _rule(box: dict, width: int, kind: str = "mid") -> str:
+    h = box["h"] * (width - 2)
+    if kind == "top":
+        return f"{box['tl']}{h}{box['tr']}"
+    if kind == "bot":
+        return f"{box['bl']}{h}{box['br']}"
+    return f"{box['l']}{h}{box['r']}"
+
+
+def _svc_line(name: str, running: bool, detail: str, unicode: bool) -> str:
+    mark = (_FILL if unicode else _FILL_ASCII) * 3 if running else (_EMPTY if unicode else _EMPTY_ASCII) * 3
+    state = "UP  " if running else "DOWN"
+    return f"{name:<10} {mark} {state}  {detail}"
+
+
+def render_frame(snapshot: dict, *, width: int | None = None, unicode: bool | None = None) -> str:
+    """Turn a snapshot into a single multi-line ASCII panel."""
+    if unicode is None:
+        unicode = _use_unicode()
+    box = _BOX if unicode else _BOX_ASCII
+    cols = shutil.get_terminal_size((80, 24)).columns if width is None else width
+    width = max(56, min(100, cols))
+
+    lines: list[str] = []
+    lines.append(_rule(box, width, "top"))
+    title = f"NexusOS {snapshot.get('version', '')}  monitor"
+    raw_ts = snapshot.get("ts") or ""
+    # Prefer local clock HH:MM:SS from an ISO stamp; fall back to wall clock.
+    stamp = ""
+    if "T" in raw_ts:
+        try:
+            stamp = raw_ts.split("T", 1)[1][:8]
+        except Exception:
+            stamp = ""
+    if not stamp:
+        stamp = datetime.now().strftime("%H:%M:%S")
+    gap = max(1, width - 4 - len(title) - len(stamp))
+    header = f"{title}{' ' * gap}{stamp}"
+    lines.append(_row(box, header, width))
+    lines.append(_rule(box, width, "mid"))
+
+    lines.append(_row(box, "SERVICES", width))
+    svcs = snapshot.get("services") or {}
+    for key, label in (("backend", "backend"), ("frontend", "frontend")):
+        info = svcs.get(key) or {}
+        running = bool(info.get("running"))
+        pid = info.get("pid")
+        url = info.get("url") or ""
+        detail = url
+        if pid:
+            detail = f"pid {pid}  {url}"
+        lines.append(_row(box, _svc_line(label, running, detail, unicode), width))
+    provider = svcs.get("provider") or _provider_payload()
+    pref = f"{provider.get('provider', '?')} @ {provider.get('url', '')}"
+    lines.append(_row(box, _svc_line("provider", bool(provider.get("reachable")), pref, unicode), width))
+
+    lines.append(_rule(box, width, "mid"))
+    lines.append(_row(box, "RESOURCES", width))
+    host = snapshot.get("host") or {}
+    procs = snapshot.get("procs") or {}
+    cpu = host.get("cpu_pct")
+    if cpu is not None:
+        lines.append(_row(
+            box,
+            f"host CPU  [{_bar(cpu / 100.0, 22, unicode)}]  {cpu:5.1f}%",
+            width,
+        ))
+    else:
+        lines.append(_row(box, "host CPU  (install psutil for live bars)", width))
+    mem_pct = host.get("mem_pct")
+    if mem_pct is not None:
+        lines.append(_row(
+            box,
+            f"host MEM  [{_bar(mem_pct / 100.0, 22, unicode)}]  "
+            f"{_fmt_bytes(host.get('mem_used'))} / {_fmt_bytes(host.get('mem_total'))}",
+            width,
+        ))
+    proc_cpu = procs.get("cpu_pct")
+    proc_rss = procs.get("rss")
+    if proc_cpu is not None or proc_rss is not None:
+        lines.append(_row(
+            box,
+            f"nexus     cpu={proc_cpu if proc_cpu is not None else '—':>5}  "
+            f"rss={_fmt_bytes(proc_rss)}  pids={','.join(str(p) for p in (procs.get('pids') or [])) or '—'}",
+            width,
+        ))
+
+    lines.append(_rule(box, width, "mid"))
+    lines.append(_row(box, "DATA / TOOLS", width))
+    api = snapshot.get("api") or {}
+    if api.get("online"):
+        policy = api.get("action_tool_policy") or "—"
+        lines.append(_row(
+            box,
+            f"api UP  v{api.get('version') or '?'}  ollama={api.get('ollama') or '—'}  "
+            f"tools={policy}",
+            width,
+        ))
+        lines.append(_row(
+            box,
+            f"memories={_n(api.get('memories'))}  "
+            f"chats={_n(api.get('conversations'))}  "
+            f"playbooks={_n(api.get('playbooks'))}  "
+            f"models={_n(api.get('models'))}",
+            width,
+        ))
+    else:
+        lines.append(_row(box, "api DOWN  — start with: nexus start", width))
+
+    recent = snapshot.get("recent_tools") or []
+    lines.append(_row(
+        box,
+        "recent   " + (", ".join(recent) if recent else "(none in chat.log)"),
+        width,
+    ))
+
+    lines.append(_rule(box, width, "mid"))
+    lines.append(_row(box, "RUN TOOLCHAINS  (run_snippet)", width))
+    chains = snapshot.get("toolchains") or []
+    if not chains:
+        lines.append(_row(box, "(code_run unavailable)", width))
+    else:
+        # Pack ready/missing into one or two compact lines.
+        ready = [c["lang"] for c in chains if c.get("ready")]
+        missing = [c["lang"] for c in chains if not c.get("ready")]
+        lines.append(_row(
+            box,
+            f"ready    {', '.join(ready) if ready else '—'}",
+            width,
+        ))
+        lines.append(_row(
+            box,
+            f"missing  {', '.join(missing) if missing else '—'}",
+            width,
+        ))
+
+    lines.append(_rule(box, width, "bot"))
+    return "\n".join(lines)
+
+
+def _n(value) -> str:
+    return "—" if value is None else str(value)
+
+
+def run_monitor(*, interval: float = 1.5, once: bool = False, json_output: bool = False) -> int:
+    """Print one frame, or refresh in place until interrupted."""
+    clear = "\033[H\033[J"
+    first = True
+    while True:
+        snap = collect_snapshot()
+        if json_output:
+            print(json.dumps(snap, indent=2, sort_keys=True))
+        else:
+            frame = render_frame(snap)
+            if once or not first:
+                # Replacing the screen keeps the panel stable; first frame of a
+                # live session also clears so leftover shell output doesn't mix.
+                if not once:
+                    print(clear + frame, end="", flush=True)
+                else:
+                    print(frame)
+            else:
+                print(clear + frame, end="", flush=True)
+            first = False
+        if once:
+            return 0
+        try:
+            time.sleep(max(0.3, float(interval)))
+        except KeyboardInterrupt:
+            print()
+            return 130

nexusos_cli/ncp.py

@@ -28,15 +28,21 @@ import urllib.request
 from dataclasses import dataclass, field
 from pathlib import Path
 
-ROOT = Path(__file__).resolve().parent.parent
-PID_DIR = ROOT / "runtime" / "pids"
-LOG_DIR = ROOT / "runtime"
-FRONTEND_DIR = ROOT / "interface" / "web"
+from synapse import proc_util
+from synapse.nexus_config import SOURCE_CHECKOUT, settings
+
+ROOT = settings.project_root
+PID_DIR = settings.runtime_dir / "pids"
+LOG_DIR = settings.runtime_dir
+FRONTEND_DIR = settings.frontend_source_dir
 OLLAMA_BIN = ROOT / "ollama" / "bin" / ("ollama.exe" if os.name == "nt" else "ollama")
-OLLAMA_MODELS_DIR = ROOT / "models"
+OLLAMA_MODELS_DIR = settings.models_dir
 
 WINDOWS = os.name == "nt"
-PYTHON = ROOT / "Promethean" / ("Scripts/python.exe" if WINDOWS else "bin/python3")
+_VENV_PYTHON = ROOT / "Promethean" / ("Scripts/python.exe" if WINDOWS else "bin/python3")
+PYTHON = Path(os.getenv("NEXUS_PYTHON", "")) if os.getenv("NEXUS_PYTHON") else (
+    _VENV_PYTHON if _VENV_PYTHON.exists() else Path(sys.executable)
+)
 
 PID_DIR.mkdir(parents=True, exist_ok=True)
 LOG_DIR.mkdir(parents=True, exist_ok=True)
@@ -93,7 +99,7 @@ def _psutil():
         import psutil
         return psutil
     except ImportError:
-        sys.exit("psutil is missing - run ./install.sh (or install-windows.ps1) to rebuild the venv.")
+        return None
 
 
 # -- services ------------------------------------------------------------------
@@ -124,7 +130,7 @@ class Service:
 # Bind loopback by default: the backend REST API is unauthenticated, so
 # binding 0.0.0.0 handed the full admin+data plane to any host on the LAN. Set
 # NEXUS_BIND_HOST=0.0.0.0 to opt into LAN exposure once real auth is in place.
-BIND_HOST = os.environ.get("NEXUS_BIND_HOST", "127.0.0.1")
+BIND_HOST = settings.bind_host
 
 
 def _uvicorn(app: str, port: int):
@@ -140,9 +146,9 @@ def _uvicorn(app: str, port: int):
 
 
 SERVICES = {
-    "backend": Service("backend", "NEXUS BACKEND SERVICE", 8000, ROOT,
+    "backend": Service("backend", "NEXUS BACKEND SERVICE", settings.backend_port, settings.state_dir,
                        ["uvicorn synapse.main"],
-                       lambda: _uvicorn("synapse.main:sio_app", 8000)),
+                       lambda: _uvicorn("synapse.main:sio_app", settings.backend_port)),
     "frontend": Service("frontend", "NEXUS FRONTEND SERVICE", 5173, FRONTEND_DIR,
                         ["vite --host", "npm run dev"],
                         lambda: [npm(), "run", "dev", "--", "--host", "0.0.0.0"]),
@@ -158,7 +164,13 @@ def read_pid(svc: Service):
 
 def alive(pid) -> bool:
     ps = _psutil()
-    return pid is not None and ps.pid_exists(pid)
+    if pid is None:
+        return False
+    if ps is not None:
+        return ps.pid_exists(pid)
+    # Not os.kill(pid, 0): that reports False for a live process owned by
+    # another user, and Windows has no signals to fall back on.
+    return proc_util.pid_alive(pid)
 
 
 def pid_is_ours(pid, patterns) -> bool:
@@ -168,7 +180,10 @@ def pid_is_ours(pid, patterns) -> bool:
     is not enough. TERMing a recycled PID can log the user out."""
     ps = _psutil()
     try:
-        cmd = " ".join(ps.Process(pid).cmdline())
+        if ps is not None:
+            cmd = " ".join(ps.Process(pid).cmdline())
+        else:
+            cmd = proc_util.pid_cmdline(pid)
     except Exception:
         return False
     return any(p in cmd for p in patterns)
@@ -255,6 +270,13 @@ def kill_matching(patterns, force=False) -> int:
     ps = _psutil()
     me = os.getpid()
     hit = 0
+    if ps is None:
+        for pid, cmd in proc_util.iter_processes():
+            if pid == me or not any(pattern in cmd for pattern in patterns):
+                continue
+            if proc_util.terminate_pid(pid, force=force):
+                hit += 1
+        return hit
     for proc in ps.process_iter(["pid", "cmdline"]):
         if proc.info["pid"] == me:
             continue
@@ -272,6 +294,12 @@ def kill_port(port: int) -> bool:
     """Whatever holds the port IS the service - this is the backstop that makes
     stop reliable regardless of process-tree shape or PID-file accuracy."""
     ps = _psutil()
+    if ps is None:
+        killed = False
+        for pid in proc_util.pids_listening_on(port):
+            if pid != os.getpid() and proc_util.terminate_pid(pid, force=True):
+                killed = True
+        return killed
     killed = False
     try:
         conns = ps.net_connections(kind="inet")
@@ -295,13 +323,18 @@ def stop_service(svc: Service) -> bool:
         if alive(pid) and pid_is_ours(pid, svc.patterns):
             ps = _psutil()
             try:
-                proc = ps.Process(pid)
-                for child in proc.children(recursive=True):
-                    try:
-                        child.terminate()
-                    except Exception:
-                        pass
-                proc.terminate()
+                if ps is not None:
+                    proc = ps.Process(pid)
+                    for child in proc.children(recursive=True):
+                        try:
+                            child.terminate()
+                        except Exception:
+                            pass
+                    proc.terminate()
+                else:
+                    # No psutil means no process tree; the kill_matching sweep
+                    # below is what catches reparented children here.
+                    proc_util.terminate_pid(pid)
             except Exception:
                 pass
         svc.pid_file.unlink(missing_ok=True)
@@ -332,8 +365,15 @@ def start_ollama(background: bool = False) -> None:
     background=False (`ncp start --ai`): blocks until the model is warmed - weights
     read off disk into RAM/VRAM, routinely about a minute - so "started" means the
     AI can actually answer."""
+    if not settings.manage_ollama:
+        running = http_ok(settings.ollama_host.rstrip("/") + "/api/tags", timeout=3)
+        print(
+            f"REMOTE OLLAMA {'REACHABLE' if running else 'UNREACHABLE'} "
+            f"({settings.ollama_host})"
+        )
+        return
     print("Starting OLLAMA...")
-    url = "http://localhost:8000/ollama/start" + ("?background=true" if background else "")
+    url = settings.api_url + "/ollama/start" + ("?background=true" if background else "")
     req = urllib.request.Request(url, method="POST")
     try:
         urllib.request.urlopen(req, timeout=180).read(1)
@@ -346,7 +386,10 @@ def stop_ollama() -> None:
     """Prefer the backend endpoint for a clean OllamaManager shutdown; if the
     backend is already down, kill `ollama serve` directly so it never lingers
     holding VRAM/RAM. Must run BEFORE the backend is torn down."""
-    req = urllib.request.Request("http://localhost:8000/ollama/stop", method="POST")
+    if not settings.manage_ollama:
+        print(f"REMOTE OLLAMA IS EXTERNALLY MANAGED ({settings.ollama_host})")
+        return
+    req = urllib.request.Request(settings.api_url + "/ollama/stop", method="POST")
     try:
         urllib.request.urlopen(req, timeout=5).read(1)
         print("NEXUS OLLAMA STOPPED")
@@ -367,6 +410,9 @@ def cmd_start(target) -> None:
         launch(SERVICES["backend"]); wait_for_port(SERVICES["backend"])
         start_ollama()
     elif target in ("--frontend", "-f"):
+        if not SOURCE_CHECKOUT:
+            print("Vite source is unavailable in wheel installs; the backend serves the bundled UI.")
+            return
         launch(SERVICES["frontend"]); wait_for_port(SERVICES["frontend"])
     elif target in ("--ai", "-a"):
         start_ollama()
@@ -389,7 +435,7 @@ def cmd_start(target) -> None:
         wait_for_port(SERVICES["backend"])
         t_services = time.perf_counter()
         start_ollama(background=True)
-        if not WINDOWS:
+        if SOURCE_CHECKOUT and not WINDOWS:
             launch(SERVICES["frontend"])
         t_bg = time.perf_counter()
         print("\nBoot timing:")
@@ -405,6 +451,8 @@ def cmd_stop(target) -> None:
         stop_ollama(); stop_service(SERVICES["backend"])
     elif target in ("--frontend", "-f"):
         stop_service(SERVICES["frontend"])
+    elif target in ("--ai", "-a"):
+        stop_ollama()
     elif target in (None, "", "all"):
         stop_ollama()
         stop_service(SERVICES["backend"])
@@ -415,14 +463,20 @@ def cmd_stop(target) -> None:
 
 def cmd_kill() -> None:
     print("Force-killing all Nexus processes...")
-    for port, name in ((8000, "SYNAPSE"),
-                       (5173, "INTERFACE"), (11434, "OLLAMA")):
+    targets = [
+        (settings.backend_port, "SYNAPSE"),
+        (5173, "INTERFACE"),
+    ]
+    patterns = ["uvicorn synapse", "npm run dev", "vite --host"]
+    if settings.manage_ollama:
+        targets.append((11434, "OLLAMA"))
+        patterns.append("ollama serve")
+    for port, name in targets:
         if kill_port(port):
             print(f"  KILLED:      {name} (:{port})")
         else:
             print(f"  NOT RUNNING: {name} (:{port})")
-    kill_matching(["uvicorn synapse", "npm run dev", "vite --host", "ollama serve"],
-                  force=True)
+    kill_matching(patterns, force=True)
     for pid_file in PID_DIR.glob("*.pid"):
         pid_file.unlink(missing_ok=True)
     print("Done.")
@@ -445,8 +499,9 @@ def cmd_status() -> None:
     print("\nFrontend:")
     one("Vite          ", SERVICES["frontend"])
     print("\nModel server:")
-    running = http_ok("http://localhost:11434/api/tags")
-    print(f"  Ollama        : {'RUNNING (:11434)' if running else 'STOPPED'}")
+    running = http_ok(settings.ollama_host.rstrip("/") + "/api/tags")
+    mode = "remote" if not settings.manage_ollama else "local"
+    print(f"  Ollama ({mode}) : {'RUNNING' if running else 'STOPPED'} ({settings.ollama_host})")
 
 
 def _tail(path: Path, n: int) -> None:
@@ -687,10 +742,10 @@ MODEL_CATALOG = [
 
 def cmd_models(action, name) -> None:
     if action == "list":
-        if not http_ok("http://localhost:11434/api/tags"):
+        if not http_ok(settings.ollama_host.rstrip("/") + "/api/tags"):
             print("Ollama is not running. Start the backend first with: ncp start -b")
             return
-        raw = urllib.request.urlopen("http://localhost:11434/api/tags", timeout=5).read()
+        raw = urllib.request.urlopen(settings.ollama_host.rstrip("/") + "/api/tags", timeout=5).read()
         models = json.loads(raw).get("models", [])
         print("Installed models:\n")
         if not models:

nexusos_cli/nexus_api.py

@@ -11,7 +11,9 @@ import sys
 
 import httpx
 
-BASE = __import__("os").environ.get("NEXUS_API", "http://localhost:8000")
+from synapse.nexus_config import settings
+
+BASE = settings.api_url
 
 
 def _client():
@@ -118,8 +120,8 @@ def cmd_history(args):
         _die_if_down(e)
 
 
-def main():
-    p = argparse.ArgumentParser(prog="ncp")
+def main(argv=None, prog="nexus"):
+    p = argparse.ArgumentParser(prog=prog)
     sub = p.add_subparsers(dest="cmd", required=True)
 
     c = sub.add_parser("chat"); c.add_argument("message", nargs="+")
@@ -135,8 +137,9 @@ def main():
     h = sub.add_parser("history"); h.add_argument("query", nargs="?")
     h.add_argument("--limit", type=int, default=20); h.set_defaults(fn=cmd_history)
 
-    args = p.parse_args()
-    args.fn(args)
+    args = p.parse_args(argv)
+    result = args.fn(args)
+    return result if isinstance(result, int) else 0
 
 
 if __name__ == "__main__":

nexusos_cli/tui_app.py

@@ -0,0 +1,510 @@
+"""Hermes/OpenClaw-style interactive TUI for NexusOS.
+
+Optional: needs the ``tui`` extra (Textual). Launched by a bare ``nexus`` when
+stdin/stdout are a TTY. Classic one-shots (``nexus chat send``, ``nexus monitor``,
+``nexus status``, …) stay on the argparse tree.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+import uuid
+from typing import Any
+
+import httpx
+
+from synapse.nexus_config import settings
+
+from .monitor import collect_snapshot
+
+# Between SSE chunks a silent backend must not pin the UI forever. Connect stays
+# short; the overall stream may run minutes.
+_STREAM_TIMEOUT = httpx.Timeout(None, connect=5.0, read=120.0, write=30.0, pool=5.0)
+_APPROVAL_TIMEOUT = httpx.Timeout(10.0, connect=5.0)
+
+
+def _require_textual():
+    try:
+        from textual.app import App
+        from textual.binding import Binding
+        from textual.widgets import Footer, Header, Input, RichLog, Static
+    except ImportError as e:  # pragma: no cover - optional extra
+        raise ImportError(
+            "The interactive TUI needs the 'tui' extra — "
+            "pip install 'nexusos-ai[tui]' (or: pip install textual)."
+        ) from e
+    return App, Binding, Footer, Header, Input, RichLog, Static
+
+
+def _escape(text: str) -> str:
+    """Make model/user text safe for Rich markup widgets.
+
+    Rich's own escape is the only version that round-trips. Escaping every
+    backslash by hand looks equivalent but is not: Rich un-escapes ``\\[`` and
+    never collapses ``\\\\``, so doubling them puts the doubles on screen -
+    every Windows path and regex escape in a reply renders wrong.
+
+    Imported inside the function so the module still loads without the ``tui``
+    extra. Rich is not declared in pyproject: Textual depends on it, so it is
+    present whenever the TUI can run at all, and tests/test_packaging_deps.py
+    lists it in TRANSITIVE for that reason.
+    """
+    from rich.markup import escape
+
+    return escape(text)
+
+
+def format_user_line(message: str) -> str:
+    return f"[bold green]you>[/] {_escape(message)}"
+
+
+def format_assistant_line(text: str) -> str:
+    return f"[bold blue]nexus>[/] {_escape(text)}"
+
+
+def _deny_tool_request(
+    *,
+    api_url: str,
+    conversation_id: str,
+    payload: str,
+    client_factory=httpx.Client,
+) -> list[str]:
+    """Immediately deny a TUI action request and let the stream resume.
+
+    The web client presents an approval dialog, but the TUI does not yet have
+    that interaction. Denying with the stream's capability token preserves the
+    ``ask`` safety boundary without leaving the backend waiting for five minutes.
+    """
+    request = json.loads(payload)
+    token = request.get("token") or ""
+    actions = request.get("actions") or []
+    names = [
+        action.get("name", "")
+        for action in actions
+        if isinstance(action, dict) and action.get("name")
+    ]
+    if not token or not names:
+        raise ValueError("invalid tool approval request")
+    body = {
+        "conversation_id": conversation_id,
+        "token": token,
+        "decisions": {name: False for name in names},
+    }
+    with client_factory(base_url=api_url, timeout=_APPROVAL_TIMEOUT) as client:
+        response = client.post("/chat/approve", json=body)
+        response.raise_for_status()
+    return names
+
+
+def _status_line(snap: dict | None = None) -> str:
+    """Format a snapshot. Pass ``snap`` — do not omit it on the UI thread."""
+    if snap is None:
+        snap = collect_snapshot()
+    svcs = snap.get("services") or {}
+    api = snap.get("api") or {}
+    host = snap.get("host") or {}
+    parts = [f"NexusOS {snap.get('version', '')}"]
+    for key in ("backend", "memory", "provider"):
+        info = svcs.get(key) or {}
+        if key == "provider":
+            up = bool(info.get("reachable"))
+        else:
+            up = bool(info.get("running"))
+        parts.append(f"{key}={'UP' if up else 'DOWN'}")
+    if api.get("online"):
+        parts.append(f"tools={api.get('action_tool_policy') or '—'}")
+    cpu = host.get("cpu_pct")
+    if cpu is not None:
+        parts.append(f"cpu={cpu:.0f}%")
+    chains = snap.get("toolchains") or []
+    ready = [c["lang"] for c in chains if c.get("ready")]
+    if ready:
+        parts.append("run=" + ",".join(ready))
+    return " · ".join(parts)
+
+
+def _compact_status(snap: dict | None = None) -> str:
+    """One-line strip for the bar under the chat log."""
+    if snap is None:
+        snap = collect_snapshot()
+    host = snap.get("host") or {}
+    api = snap.get("api") or {}
+    recent = snap.get("recent_tools") or []
+    cpu = host.get("cpu_pct")
+    mem = host.get("mem_pct")
+    bits = []
+    if cpu is not None:
+        bits.append(f"cpu {cpu:.0f}%")
+    if mem is not None:
+        bits.append(f"mem {mem:.0f}%")
+    if api.get("online"):
+        bits.append(
+            f"memories={api.get('memories') if api.get('memories') is not None else '—'} "
+            f"chats={api.get('conversations') if api.get('conversations') is not None else '—'}"
+        )
+    else:
+        bits.append("api DOWN — nexus start")
+    if recent:
+        bits.append("recent " + ", ".join(recent[:4]))
+    return "  │  ".join(bits)
+
+
+class NexusTUI:
+    """Factory so Textual imports stay lazy until run()."""
+
+    @staticmethod
+    def build_app(*, api_url: str | None = None):
+        App, Binding, Footer, Header, Input, RichLog, Static = _require_textual()
+        base = (api_url or settings.api_url).rstrip("/")
+
+        class AppImpl(App):
+            CSS = """
+            Screen { layout: vertical; }
+            #status {
+                height: 1;
+                dock: top;
+                background: $boost;
+                color: $text;
+                padding: 0 1;
+            }
+            #strip {
+                height: 1;
+                background: $surface;
+                color: $text-muted;
+                padding: 0 1;
+            }
+            #log {
+                height: 1fr;
+                border: tall $accent;
+                padding: 0 1;
+            }
+            #live {
+                height: auto;
+                max-height: 8;
+                padding: 0 1;
+                color: $text;
+            }
+            #prompt { dock: bottom; }
+            """
+            BINDINGS = [
+                Binding("ctrl+c", "interrupt", "Interrupt", priority=True),
+                Binding("ctrl+d", "quit", "Quit", priority=True),
+            ]
+
+            def __init__(self):
+                super().__init__()
+                self.api_url = base
+                self.conversation_id: str | None = None
+                self.history: list[dict] = []
+                self._model: str | None = None
+                self._busy = False
+                self._stop_stream = threading.Event()
+                self._stream_cancel: (
+                    tuple[asyncio.AbstractEventLoop, asyncio.Task] | None
+                ) = None
+                self._status_lock = threading.Lock()
+                self._status_pending = False
+
+            def compose(self):
+                # Placeholders only — never collect_snapshot() on the UI thread.
+                yield Header(show_clock=True)
+                yield Static("NexusOS …", id="status")
+                yield RichLog(id="log", highlight=True, markup=True, wrap=True)
+                yield Static("", id="live")
+                yield Static("collecting status…", id="strip")
+                yield Input(
+                    placeholder="Message Nexus…  (/help for commands)",
+                    id="prompt",
+                )
+                yield Footer()
+
+            def on_mount(self) -> None:
+                self.title = "NexusOS"
+                self.sub_title = self.api_url
+                log = self.query_one("#log", RichLog)
+                log.write("[bold]NexusOS[/] interactive TUI")
+                log.write(
+                    "Type a message and Enter. "
+                    "Slash: /help /status /new /model /quit"
+                )
+                log.write(f"API: {_escape(self.api_url)}")
+                log.write("")
+                self._schedule_status_refresh()
+                self.set_interval(2.0, self._schedule_status_refresh)
+                self.query_one("#prompt", Input).focus()
+
+            def _schedule_status_refresh(self) -> None:
+                """Kick a worker; never call collect_snapshot on the event loop."""
+                with self._status_lock:
+                    if self._status_pending:
+                        return
+                    self._status_pending = True
+
+                def worker():
+                    try:
+                        snap = collect_snapshot()
+                        self._call_ui(self._apply_status, snap)
+                    except Exception:
+                        pass
+                    finally:
+                        with self._status_lock:
+                            self._status_pending = False
+
+                threading.Thread(target=worker, daemon=True).start()
+
+            def _apply_status(self, snap: dict) -> None:
+                self.query_one("#status", Static).update(_status_line(snap))
+                self.query_one("#strip", Static).update(_compact_status(snap))
+
+            def _call_ui(self, callback, *args) -> None:
+                """call_from_thread, but never after quit (avoids CancelledError
+                traceback garbling the restored shell)."""
+                if not self.is_running:
+                    return
+                try:
+                    self.call_from_thread(callback, *args)
+                except BaseException:
+                    # CancelledError is BaseException; also ignore post-exit races.
+                    pass
+
+            def _show_error(self, message: str) -> None:
+                """Write a stream error to the persistent transcript."""
+                self.query_one("#log", RichLog).write(message)
+
+            def _cancel_stream(self) -> None:
+                """Cancel the task that owns the socket read.
+
+                Closing a synchronous httpx client from the UI thread does not
+                reliably unblock its worker-thread read on macOS. Async task
+                cancellation is delivered to the pending read itself.
+                """
+                self._stop_stream.set()
+                cancel = self._stream_cancel
+                if cancel is not None:
+                    loop, task = cancel
+                    loop.call_soon_threadsafe(task.cancel)
+
+            def action_quit(self) -> None:
+                self._cancel_stream()
+                self.exit()
+
+            def action_interrupt(self) -> None:
+                if self._busy:
+                    self._cancel_stream()
+                    self.query_one("#log", RichLog).write(
+                        "[yellow]▸ interrupt requested[/]"
+                    )
+                else:
+                    self.exit()
+
+            def on_input_submitted(self, event: Input.Submitted) -> None:
+                text = (event.value or "").strip()
+                event.input.value = ""
+                if not text:
+                    return
+                if text.startswith("/"):
+                    self._handle_slash(text)
+                    return
+                if self._busy:
+                    self.query_one("#log", RichLog).write(
+                        "[yellow]Still streaming — wait or Ctrl+C to interrupt[/]"
+                    )
+                    return
+                self._start_chat(text)
+
+            def _handle_slash(self, text: str) -> None:
+                log = self.query_one("#log", RichLog)
+                cmd, _, rest = text[1:].partition(" ")
+                cmd = cmd.lower().strip()
+                rest = rest.strip()
+                if cmd in ("q", "quit", "exit"):
+                    self.exit()
+                elif cmd in ("h", "help"):
+                    log.write(
+                        "[bold]/help[/]   this list\n"
+                        "[bold]/status[/] refresh service strip\n"
+                        "[bold]/new[/]    fresh conversation\n"
+                        "[bold]/model[/] \\[name]  pin model for next turns\n"
+                        "[bold]/quit[/]   leave the TUI\n"
+                        "One-shot: [dim]nexus chat send \"…\"[/]"
+                    )
+                elif cmd == "status":
+                    self._schedule_status_refresh()
+                    log.write("[dim]refreshing status…[/]")
+                elif cmd == "new":
+                    self.conversation_id = None
+                    self.history = []
+                    log.write("[bold cyan]— new conversation —[/]")
+                elif cmd == "model":
+                    if rest:
+                        self._model = rest
+                        log.write(f"[dim]model pinned:[/] {_escape(rest)}")
+                    else:
+                        log.write(
+                            f"[dim]model:[/] {_escape(self._model or '(auto)')}"
+                        )
+                else:
+                    log.write(
+                        f"[red]unknown command[/] /{_escape(cmd)} — try /help"
+                    )
+
+            def _start_chat(self, message: str) -> None:
+                log = self.query_one("#log", RichLog)
+                live = self.query_one("#live", Static)
+                log.write(format_user_line(message))
+                live.update("[bold blue]nexus>[/] [dim]…[/]")
+                self._busy = True
+                self._stop_stream.clear()
+                if not self.conversation_id:
+                    self.conversation_id = str(uuid.uuid4())
+                conversation_id = self.conversation_id
+                # The list object itself, not self.history - /new reassigns
+                # self.history to a fresh list, and a stream that outlives that
+                # must keep appending its reply to the conversation it actually
+                # belongs to, not whatever self.history now points at.
+                history_ref = self.history
+                body: dict[str, Any] = {
+                    "message": message,
+                    "conversation_id": conversation_id,
+                    "history": list(history_ref),
+                }
+                if self._model:
+                    body["model"] = self._model
+                history_ref.append({"role": "user", "content": message})
+
+                async def stream_worker():
+                    reply_parts: list[str] = []
+                    task = asyncio.current_task()
+                    loop = asyncio.get_running_loop()
+                    if task is None:  # pragma: no cover - asyncio guarantees it
+                        raise RuntimeError("stream worker has no task")
+                    self._stream_cancel = (loop, task)
+                    try:
+                        if self._stop_stream.is_set():
+                            raise asyncio.CancelledError
+                        async with httpx.AsyncClient(
+                            base_url=self.api_url, timeout=_STREAM_TIMEOUT
+                        ) as client:
+                            async with client.stream(
+                                "POST", "/chat/stream", json=body
+                            ) as resp:
+                                if resp.status_code >= 400:
+                                    detail = (await resp.aread()).decode(
+                                        "utf-8", errors="replace"
+                                    )[:300]
+                                    self._call_ui(
+                                        self._show_error,
+                                        f"[red]error HTTP {resp.status_code}[/] "
+                                        f"{_escape(detail)}",
+                                    )
+                                    return
+                                event = "message"
+                                async for line in resp.aiter_lines():
+                                    if self._stop_stream.is_set():
+                                        raise asyncio.CancelledError
+                                    if line == "":
+                                        event = "message"
+                                        continue
+                                    if line.startswith("event:"):
+                                        event = line[6:].strip()
+                                        continue
+                                    if not line.startswith("data:"):
+                                        continue
+                                    payload = line[5:].strip()
+                                    kind = event
+                                    if kind in ("message", ""):
+                                        kind = "chunk"
+                                        payload = json.loads(payload)
+                                    if kind == "chunk":
+                                        reply_parts.append(payload)
+                                        preview = "".join(reply_parts)
+                                        if len(preview) > 4000:
+                                            preview = "…" + preview[-4000:]
+                                        self._call_ui(
+                                            live.update,
+                                            format_assistant_line(preview),
+                                        )
+                                    elif kind == "tool_request":
+                                        try:
+                                            names = _deny_tool_request(
+                                                api_url=self.api_url,
+                                                conversation_id=conversation_id,
+                                                payload=payload,
+                                            )
+                                            shown = ", ".join(names)
+                                            self._call_ui(
+                                                log.write,
+                                                "[yellow]▸ denied action tool "
+                                                f"{_escape(shown)} — interactive "
+                                                "approval is not yet available in "
+                                                "the TUI[/]",
+                                            )
+                                        except Exception as exc:
+                                            self._call_ui(
+                                                self._show_error,
+                                                "[red]tool denial failed:[/] "
+                                                f"{_escape(str(exc))}",
+                                            )
+                                            return
+                                    elif kind == "error":
+                                        try:
+                                            detail = json.loads(payload).get(
+                                                "detail", payload
+                                            )
+                                        except Exception:
+                                            detail = payload
+                                        self._call_ui(
+                                            self._show_error,
+                                            f"[red]error:[/] "
+                                            f"{_escape(str(detail))}",
+                                        )
+                                    elif kind == "done":
+                                        break
+                    except asyncio.CancelledError:
+                        pass
+                    except httpx.ConnectError:
+                        self._call_ui(
+                            self._show_error,
+                            f"[red]Backend not reachable at "
+                            f"{_escape(self.api_url)}. Start it: nexus start[/]",
+                        )
+                    except Exception as exc:
+                        self._call_ui(
+                            self._show_error,
+                            f"[red]{_escape(type(exc).__name__)}:[/] "
+                            f"{_escape(str(exc))}",
+                        )
+                    finally:
+                        if self._stream_cancel == (loop, task):
+                            self._stream_cancel = None
+                        text = "".join(reply_parts).strip()
+                        self._call_ui(self._finish_stream, text, history_ref)
+
+                threading.Thread(
+                    target=lambda: asyncio.run(stream_worker()), daemon=True
+                ).start()
+
+            def _finish_stream(self, text: str, history_ref: list) -> None:
+                log = self.query_one("#log", RichLog)
+                live = self.query_one("#live", Static)
+                try:
+                    if text:
+                        log.write(format_assistant_line(text))
+                        history_ref.append(
+                            {"role": "assistant", "content": text}
+                        )
+                finally:
+                    # Always clear busy — a MarkupError must not wedge the TUI.
+                    live.update("")
+                    self._busy = False
+                    self._schedule_status_refresh()
+
+        return AppImpl()
+
+
+def run_tui(*, api_url: str | None = None) -> int:
+    """Run the Textual app. Returns a process exit code."""
+    app = NexusTUI.build_app(api_url=api_url)
+    app.run()
+    return 0

pyproject.toml

@@ -0,0 +1,130 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nexusos-ai"
+dynamic = ["version"]
+description = "Local-first AI assistant runtime, web UI, and portable CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{name = "EnderOfWings"}]
+keywords = ["ai", "assistant", "ollama", "local-ai", "termux"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Framework :: FastAPI",
+  "Operating System :: Android",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Communications :: Chat",
+]
+dependencies = [
+  "fastapi>=0.115,<1",
+  "httpx>=0.27,<1",
+  "pydantic>=2.7,<3",
+  "python-dotenv>=1,<2",
+  "PyYAML>=6,<7",
+  "uvicorn>=0.30,<1",
+]
+
+[project.optional-dependencies]
+documents = ["pypdf>=5,<7", "python-docx>=1.1,<2"]
+process = ["psutil>=5.9,<8"]
+vector = ["sqlite-vec>=0.1,<1"]
+voice = ["faster-whisper>=1.1,<2"]
+mail = ["imap-tools>=1.7,<2"]
+# synapse/search.py imports this lazily behind a bare except, so without it
+# declared the chat web-search path silently returns nothing.
+search = ["duckduckgo-search>=6,<9"]
+tui = ["textual>=1.0,<3"]
+desktop = [
+  "psutil>=5.9,<8",
+  "pywebview>=5,<7; platform_system == 'Windows'",
+]
+standard = [
+  "pypdf>=5,<7",
+  "python-docx>=1.1,<2",
+  "psutil>=5.9,<8",
+  "sqlite-vec>=0.1,<1",
+  "duckduckgo-search>=6,<9",
+]
+# Every optional capability at once. Kept in sync with the extras above by
+# tests/test_packaging_deps.py, which also checks that nothing synapse imports
+# is missing from this file.
+all = [
+  "pypdf>=5,<7",
+  "python-docx>=1.1,<2",
+  "psutil>=5.9,<8",
+  "sqlite-vec>=0.1,<1",
+  "faster-whisper>=1.1,<2",
+  "imap-tools>=1.7,<2",
+  "duckduckgo-search>=6,<9",
+  "textual>=1.0,<3",
+  "pywebview>=5,<7; platform_system == 'Windows'",
+]
+dev = [
+  "build>=1.2,<2",
+  "pytest>=8,<10",
+  "twine>=7,<8",
+]
+
+[project.scripts]
+nexus = "nexusos_cli.cli:entrypoint"
+ncp = "nexusos_cli.cli:entrypoint"
+nexusos = "nexusos_cli.cli:entrypoint"
+
+[project.urls]
+Homepage = "https://git.enderofwings.com/enderofwings/NexusOS"
+Issues = "https://git.enderofwings.com/enderofwings/NexusOS/issues"
+Repository = "https://git.enderofwings.com/enderofwings/NexusOS"
+
+[tool.hatch.version]
+path = "VERSION"
+pattern = "^(?P<version>[^\\s]+)$"
+
+[tool.hatch.build]
+skip-excluded-dirs = true
+
+# Ships interface/web/dist when it has been built. It is gitignored, so a
+# static force-include would abort `pip install -e .` on a fresh clone.
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["synapse", "nexusos_cli", "modules"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"VERSION" = "synapse/_resources/VERSION"
+"data/playbooks" = "synapse/_resources/playbooks"
+"assets/n-small.png" = "synapse/_resources/assets/n-small.png"
+"assets/themes/NexusOS-icons-src/nexus-underlay.svg" = "synapse/_resources/assets/themes/NexusOS-icons-src/nexus-underlay.svg"
+"assets/themes/NexusOS-icons-src/nexus-underlay-ring.svg" = "synapse/_resources/assets/themes/NexusOS-icons-src/nexus-underlay-ring.svg"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/assets/n-small.png",
+  "/assets/themes/NexusOS-icons-src/nexus-underlay.svg",
+  "/assets/themes/NexusOS-icons-src/nexus-underlay-ring.svg",
+  "/data/playbooks",
+  "/docs",
+  "/management",
+  "/modules",
+  "/nexusos_cli",
+  "/scripts",
+  "/synapse",
+  "/tests",
+  "/README.md",
+  "/VERSION",
+  "/pyproject.toml",
+  "/hatch_build.py",
+]
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "management"]

requirements-base.txt

@@ -38,6 +38,9 @@ sqlite-vec
 faster-whisper
 # Email client: IMAP read (SMTP send is stdlib). Pure-Python, no native deps.
 imap-tools
+# Chat web search (synapse/search.py). Imported lazily behind a bare except,
+# so a missing install shows up as search silently returning nothing.
+duckduckgo-search
 
 # Documentation Support
 markdown-it-py

scripts/install-termux.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Install the portable NexusOS wheel in Termux.
+#
+# NEXUS_PACKAGE may be a PyPI requirement, wheel URL, or local wheel path.
+# NEXUS_ANDROID_WHEEL_INDEX may point at a trusted PEP 503 index containing
+# Android pydantic-core wheels for the device's Python/CPU combination.
+set -euo pipefail
+
+if [[ "${PREFIX:-}" != *com.termux* ]]; then
+    echo "This installer must be run inside Termux." >&2
+    exit 2
+fi
+
+PACKAGE_SPEC="${1:-${NEXUS_PACKAGE:-nexusos-ai}}"
+
+echo "==> Installing Termux prerequisites"
+pkg update -y
+pkg install -y python python-pip curl clang make
+
+PYTHON_TAG="$(python -c 'import sys; print(f"cp{sys.version_info.major}{sys.version_info.minor}")')"
+ARCH="$(uname -m)"
+echo "==> Python ${PYTHON_TAG}; architecture ${ARCH}"
+
+PIP_INDEX_ARGS=()
+if [[ -n "${NEXUS_ANDROID_WHEEL_INDEX:-}" ]]; then
+    PIP_INDEX_ARGS+=(--extra-index-url "${NEXUS_ANDROID_WHEEL_INDEX}")
+fi
+
+# Pydantic 2 is required on Python 3.14+, and its Rust extension is not built
+# reliably on-device. Require a binary before asking pip to resolve NexusOS so
+# failures are immediate and actionable. Older Termux environments also benefit
+# from using a wheel instead of compiling the extension on a phone.
+echo "==> Checking for an Android pydantic-core wheel"
+if ! python -m pip install \
+    --only-binary=pydantic-core \
+    "${PIP_INDEX_ARGS[@]}" \
+    "pydantic>=2.7,<3"; then
+    cat >&2 <<EOF
+
+No compatible pydantic-core wheel was found for ${PYTHON_TAG}/${ARCH}.
+PyPI does not currently publish Android wheels for this native dependency.
+Set NEXUS_ANDROID_WHEEL_INDEX to a trusted NexusOS Android wheel index and
+run this installer again. Do not force a source build on a memory-limited phone.
+EOF
+    exit 1
+fi
+
+echo "==> Installing ${PACKAGE_SPEC}"
+# Same extra index as the pydantic-core probe: a NexusOS wheel hosted there
+# would otherwise be invisible to the resolver.
+python -m pip install "${PIP_INDEX_ARGS[@]}" "${PACKAGE_SPEC}"
+
+echo "==> Initializing NexusOS"
+nexus init
+
+if [[ -n "${NEXUS_PROVIDER_URL:-}" ]]; then
+    nexus provider use remote --url "${NEXUS_PROVIDER_URL}"
+fi
+
+# Report health without aborting: `set -e` would otherwise skip the guidance
+# below whenever doctor finds a failing required check - exactly when the
+# reader most needs to see what to do next. The status is re-raised at exit.
+DOCTOR_STATUS=0
+nexus doctor || DOCTOR_STATUS=$?
+
+cat <<'EOF'
+
+NexusOS is installed. Configure an Ollama-compatible provider, then run:
+  nexus provider use remote --url http://YOUR-OLLAMA-HOST:11434
+  nexus serve
+
+Open http://127.0.0.1:8000 in the Android browser.
+EOF
+
+exit "${DOCTOR_STATUS}"

synapse/chat.py

@@ -276,18 +276,23 @@ async def _run_tool_loop(manager, messages, model, tool_schemas, temperature, nu
         )
         if not isinstance(msg, dict):
             break  # None/error or no tool support -> fall back to plain stream
+        native = bool(msg.get("tool_calls"))
         calls = _coerce_tool_calls(msg, allowed_names)
         if not calls:
             break
         # Normalize content-JSON tool calls into the shape later turns expect.
-        if not msg.get("tool_calls"):
+        if not native:
             msg = {"role": "assistant", "content": "", "tool_calls": calls}
         messages.append(msg)
 
         # If any action tool needs per-call approval, pause and wait for the user.
+        # A call recovered by guessing at `content` (no native tool_calls field)
+        # is a weaker signal than the API's own structured field — a model can
+        # land on JSON shaped like a call while only meaning to describe one, so
+        # it always goes through approval regardless of policy, even "allow".
         decisions = None
         action_calls = [c for c in calls if _tools.is_action(c.get("function", {}).get("name", ""))]
-        if policy == "ask" and action_calls:
+        if (policy == "ask" or not native) and action_calls:
             event = asyncio.Event()
             # Single-use capability token, delivered only to the client that owns
             # this stream. /chat/approve requires it, so knowing the (guessable,

synapse/frontend_manager.py

@@ -13,11 +13,15 @@ import shutil
 import subprocess
 import urllib.request
 
-import psutil
+try:
+    import psutil
+except ImportError:  # optional in the portable/Termux core install
+    psutil = None
 
-from .nexus_config import PROJECT_ROOT, RUNTIME_DIR
+from . import proc_util
+from .nexus_config import FRONTEND_SOURCE_DIR, RUNTIME_DIR
 
-FRONTEND_DIR = PROJECT_ROOT / "interface" / "web"
+FRONTEND_DIR = FRONTEND_SOURCE_DIR
 PID_FILE = RUNTIME_DIR / "pids" / "frontend.pid"
 LOG_FILE = RUNTIME_DIR / "frontend.log"
 PORT = 5173
@@ -41,12 +45,25 @@ def _is_ours(pid: int) -> bool:
     # the tracked PID's own cmdline. Loosen to "vite" (matches once the tree
     # gets that far) or "npm"+"dev" both present (matches the wrapper hop too).
     try:
-        cmd = " ".join(psutil.Process(pid).cmdline())
+        if psutil is not None:
+            cmd = " ".join(psutil.Process(pid).cmdline())
+        else:
+            cmd = proc_util.pid_cmdline(pid)
     except Exception:
         return False
     return "vite" in cmd or ("npm" in cmd and "dev" in cmd)
 
 
+def _alive(pid: int | None) -> bool:
+    if pid is None:
+        return False
+    if psutil is not None:
+        return psutil.pid_exists(pid)
+    # proc_util rather than os.kill(pid, 0): same probe, but it also works
+    # when the PID belongs to another user.
+    return proc_util.pid_alive(pid)
+
+
 def _http_up() -> bool:
     try:
         with urllib.request.urlopen(f"http://127.0.0.1:{PORT}/", timeout=1.5) as r:
@@ -60,7 +77,7 @@ def is_running() -> bool:
     port actually answers (covers Vite started by another process, or a lost
     PID file) - not the stricter pattern match `stop()` uses before killing."""
     pid = _read_pid()
-    if pid is not None and psutil.pid_exists(pid):
+    if _alive(pid):
         return True
     return _http_up()
 
@@ -68,6 +85,8 @@ def is_running() -> bool:
 def start() -> dict:
     if is_running():
         return {"status": "already_running"}
+    if not FRONTEND_DIR.is_dir():
+        return {"status": "unavailable", "detail": "Vite source is not included in wheel installs"}
     npm = _npm()
     if not npm:
         return {"status": "error", "detail": "npm not found - install Node.js"}
@@ -92,17 +111,20 @@ def start() -> dict:
 
 def stop() -> dict:
     pid = _read_pid()
-    if pid is not None and psutil.pid_exists(pid) and _is_ours(pid):
+    if _alive(pid) and _is_ours(pid):
         try:
-            proc = psutil.Process(pid)
-            # npm.cmd -> node -> vite is a multi-hop tree; kill it depth-first
-            # so the parent doesn't outlive its children as an orphaned shell.
-            for child in proc.children(recursive=True):
-                try:
-                    child.terminate()
-                except Exception:
-                    pass
-            proc.terminate()
+            if psutil is not None:
+                proc = psutil.Process(pid)
+                # npm.cmd -> node -> vite is a multi-hop tree; kill it depth-first
+                # so the parent doesn't outlive its children as an orphaned shell.
+                for child in proc.children(recursive=True):
+                    try:
+                        child.terminate()
+                    except Exception:
+                        pass
+                proc.terminate()
+            else:
+                proc_util.terminate_pid(pid)
         except Exception:
             pass
     PID_FILE.unlink(missing_ok=True)

synapse/icons/compositor.py

@@ -5,9 +5,11 @@ import tempfile
 import os
 import re
 
-_ROOT = Path(__file__).resolve().parents[2]
-UNDERLAY_FILE = _ROOT / "assets/themes/NexusOS-icons-src/nexus-underlay.svg"
-RING_FILE = _ROOT / "assets/themes/NexusOS-icons-src/nexus-underlay-ring.svg"
+from ..nexus_config import settings
+
+_ROOT = settings.project_root
+UNDERLAY_FILE = settings.assets_dir / "themes/NexusOS-icons-src/nexus-underlay.svg"
+RING_FILE = settings.assets_dir / "themes/NexusOS-icons-src/nexus-underlay-ring.svg"
 ICONS_OUT = Path.home() / ".icons" / "NexusOS"
 SIZES = [16, 22, 24, 32, 48, 64, 128]
 
@@ -18,7 +20,7 @@ _ALLOWED_ROOTS = [
     "/opt",
     str(Path.home() / ".local/share/icons"),
     str(Path.home() / ".icons"),
-    str(_ROOT / "assets"),
+    str(settings.assets_dir),
 ]
 
 _UNDERLAY_FALLBACK = """\

synapse/main.py

@@ -198,7 +198,6 @@ from .memory.store import store, MemoryItem
 from .playbooks.store import playbook_store, PlaybookItem
 from .search import needs_web_search, web_search
 
-
 app = FastAPI(title="Synapse Backend", version=VERSION)
 
 # Alias for startup scripts
@@ -1620,7 +1619,7 @@ async def delete_conversation(conversation_id: str):
 
 # ── Icon branding routes ──────────────────────────────────────────────────────
 
-_REPO_ASSETS = str(Path(__file__).resolve().parents[1] / "assets")
+_REPO_ASSETS = str(settings.assets_dir)
 _ALLOWED_ICON_ROOTS = [
     "/usr/share/icons",
     "/usr/share/pixmaps",
@@ -1701,7 +1700,7 @@ async def apply_icon_cache_route():
 # and uses the Vite dev server as before.
 from fastapi.staticfiles import StaticFiles  # noqa: E402
 
-_DIST = Path(__file__).resolve().parent.parent / "interface" / "web" / "dist"
+_DIST = settings.web_dist_dir
 if _DIST.is_dir():
     app.mount("/", StaticFiles(directory=str(_DIST), html=True), name="ui")
 

synapse/memory/store.py

@@ -251,6 +251,8 @@ class PersistentMemoryStore:
             "DELETE FROM settings WHERE key IN ('anthropic_api_key', 'escalation_model')"
         )
 
+        self._sweep_orphan_msg_vectors(conn)
+
         conn.commit()
         conn.close()
 
@@ -788,6 +790,29 @@ class PersistentMemoryStore:
         except Exception:
             pass
 
+    def _sweep_orphan_msg_vectors(self, conn) -> None:
+        """One-time repair for databases written before delete_conversation
+        cleaned up after itself: drop vectors whose message is already gone."""
+        try:
+            ids = [r["message_id"] for r in conn.execute(
+                "SELECT v.message_id FROM message_vectors v "
+                "LEFT JOIN messages m ON m.id = v.message_id WHERE m.id IS NULL"
+            ).fetchall()]
+            if ids:
+                conn.execute(
+                    "DELETE FROM message_vectors WHERE message_id NOT IN "
+                    "(SELECT id FROM messages)"
+                )
+                if self.vec_enabled and conn.execute(
+                    "SELECT 1 FROM sqlite_master WHERE name = 'vec_messages'"
+                ).fetchone():
+                    for message_id in ids:
+                        conn.execute(
+                            "DELETE FROM vec_messages WHERE rowid = ?", (message_id,)
+                        )
+        except Exception:
+            pass
+
     def _backfill_vec_msgs(self, conn, dim: int) -> None:
         """Index any message_vectors rows missing from vec_messages."""
         try:
@@ -1215,4 +1240,4 @@ class PersistentMemoryStore:
 from ..nexus_config import MEMORY_DB
 
 DB_PATH = MEMORY_DB
-store = PersistentMemoryStore(DB_PATH)
+store = PersistentMemoryStore(DB_PATH)

synapse/nexus_config.py

@@ -1,7 +1,10 @@
 # config.py
 from __future__ import annotations
 
+import json
 import os
+import shutil
+from importlib import metadata
 from pathlib import Path
 from typing import Dict, Any
 
@@ -12,14 +15,88 @@ try:
 except Exception:
     pass
 
-# --- PROJECT ROOT ---
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
+# --- INSTALL / RESOURCE LAYOUT ---
+PACKAGE_DIR = Path(__file__).resolve().parent
+_CHECKOUT_ROOT = PACKAGE_DIR.parent
+SOURCE_CHECKOUT = (
+    (_CHECKOUT_ROOT / "VERSION").is_file()
+    and (_CHECKOUT_ROOT / "interface" / "web" / "package.json").is_file()
+)
 
-# --- VERSION (single source of truth: the VERSION file at the repo root) ---
+# PROJECT_ROOT remains the source checkout for developer installs. In a wheel it
+# is the installed package directory; writable state is deliberately elsewhere.
+PROJECT_ROOT = Path(os.getenv("NEXUS_PROJECT_ROOT", "")).expanduser() if os.getenv(
+    "NEXUS_PROJECT_ROOT"
+) else (_CHECKOUT_ROOT if SOURCE_CHECKOUT else PACKAGE_DIR)
+PROJECT_ROOT = PROJECT_ROOT.resolve()
+RESOURCE_ROOT = PROJECT_ROOT if SOURCE_CHECKOUT else PACKAGE_DIR / "_resources"
+
+
+def _user_dir(env_name: str, windows_leaf: str, xdg_name: str, xdg_fallback: str) -> Path:
+    # os.getenv's default only applies when a variable is *unset*. An exported
+    # but empty XDG_DATA_HOME / LOCALAPPDATA would otherwise give Path("") ==
+    # ".", scattering state through whatever the cwd happened to be. The XDG
+    # spec says to treat an empty value as unset, so `or` - not a default arg.
+    override = os.getenv(env_name, "").strip()
+    if override:
+        return Path(override).expanduser().resolve()
+    if os.name == "nt":
+        base = Path(os.getenv("LOCALAPPDATA", "").strip() or Path.home() / "AppData" / "Local")
+        return (base / windows_leaf).expanduser().resolve()
+    base = Path(os.getenv(xdg_name, "").strip() or Path.home() / xdg_fallback).expanduser()
+    return (base / "nexusos").resolve()
+
+
+CONFIG_DIR = _user_dir("NEXUS_CONFIG_DIR", "NexusOS", "XDG_CONFIG_HOME", ".config")
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def read_user_config() -> dict[str, Any]:
+    try:
+        data = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError, TypeError):
+        return {}
+
+
+def write_user_config(values: dict[str, Any]) -> None:
+    """Atomically persist CLI-managed configuration."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = CONFIG_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(values, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    tmp.replace(CONFIG_FILE)
+
+
+USER_CONFIG = read_user_config()
+
+
+def _value(key: str, env_name: str, default: Any) -> Any:
+    raw = os.getenv(env_name)
+    return raw if raw not in (None, "") else USER_CONFIG.get(key, default)
+
+
+def _int_value(key: str, env_name: str, default: int) -> int:
+    try:
+        return int(_value(key, env_name, default))
+    except (TypeError, ValueError):
+        return default
+
+
+def _configured_path(key: str, env_name: str, default: Path) -> Path:
+    return Path(str(_value(key, env_name, default))).expanduser().resolve()
+
+
+# --- VERSION (repo file in a checkout; distribution metadata in a wheel) ---
 try:
-    VERSION = (PROJECT_ROOT / "VERSION").read_text(encoding="utf-8").strip() or "0.0.0"
+    if SOURCE_CHECKOUT:
+        VERSION = (PROJECT_ROOT / "VERSION").read_text(encoding="utf-8").strip()
+    else:
+        VERSION = metadata.version("nexusos-ai")
 except Exception:
-    VERSION = "0.0.0"
+    try:
+        VERSION = (RESOURCE_ROOT / "VERSION").read_text(encoding="utf-8").strip()
+    except Exception:
+        VERSION = "0.0.0"
 
 # --- MODEL DEFAULTS ---
 # Single source of truth for the three models NexusOS ships with. The installers
@@ -43,11 +120,24 @@ DEFAULT_MEMORY_MODEL = DEFAULT_CHAT_MODEL
 DEFAULT_EMBED_MODEL = "nomic-embed-text"
 
 # --- CORE DIRECTORIES ---
-DATA_DIR = PROJECT_ROOT / "data"
-MODELS_DIR = PROJECT_ROOT / "models"
-RUNTIME_DIR = PROJECT_ROOT / "runtime"
+_DEFAULT_STATE = PROJECT_ROOT if SOURCE_CHECKOUT else _user_dir(
+    "NEXUS_HOME", "NexusOS", "XDG_DATA_HOME", ".local/share"
+)
+STATE_DIR = _configured_path("home", "NEXUS_HOME", _DEFAULT_STATE)
+_USE_CHECKOUT_STATE = SOURCE_CHECKOUT and not os.getenv("NEXUS_HOME", "").strip()
+DATA_DIR = _configured_path("data_dir", "NEXUS_DATA_DIR", (
+    PROJECT_ROOT / "data" if _USE_CHECKOUT_STATE else STATE_DIR / "data"
+))
+MODELS_DIR = _configured_path("models_dir", "NEXUS_MODELS_DIR", (
+    PROJECT_ROOT / "models" if _USE_CHECKOUT_STATE else STATE_DIR / "models"
+))
+RUNTIME_DIR = _configured_path("runtime_dir", "NEXUS_RUNTIME_DIR", (
+    PROJECT_ROOT / "runtime" if _USE_CHECKOUT_STATE else STATE_DIR / "runtime"
+))
 
-MEMORY_DIR = PROJECT_ROOT / "synapse" / "memory"
+MEMORY_DIR = _configured_path("memory_dir", "NEXUS_MEMORY_DIR", (
+    PROJECT_ROOT / "synapse" / "memory" if _USE_CHECKOUT_STATE else DATA_DIR
+))
 
 LOGS_DIR = RUNTIME_DIR / "logs"
 CACHE_DIR = RUNTIME_DIR / "cache"
@@ -57,9 +147,19 @@ TEMP_DIR = RUNTIME_DIR / "tmp"
 PLAYBOOK_DIR = DATA_DIR / "playbooks"  # YAML playbook files (PlaybookFileStore)
 UPLOADS_DIR = DATA_DIR / "uploads"
 EXPORTS_DIR = DATA_DIR / "exports"
+WEB_DIST_DIR = (
+    PROJECT_ROOT / "interface" / "web" / "dist"
+    if SOURCE_CHECKOUT else RESOURCE_ROOT / "web"
+)
+FRONTEND_SOURCE_DIR = PROJECT_ROOT / "interface" / "web"
+ASSETS_DIR = PROJECT_ROOT / "assets" if SOURCE_CHECKOUT else RESOURCE_ROOT / "assets"
+SEED_PLAYBOOK_DIR = (
+    PROJECT_ROOT / "data" / "playbooks"
+    if SOURCE_CHECKOUT else RESOURCE_ROOT / "playbooks"
+)
 
 # --- DATABASE / STORAGE FILES (match your repo) ---
-MEMORY_DB = MEMORY_DIR / "memory.db"
+MEMORY_DB = _configured_path("memory_db", "NEXUS_MEMORY_DB", MEMORY_DIR / "memory.db")
 
 # --- LOG FILES ---
 BACKEND_LOG = RUNTIME_DIR / "backend.log"
@@ -67,7 +167,8 @@ OLLAMA_LOG = LOGS_DIR / "ollama.log"
 CHAT_LOG = LOGS_DIR / "chat.log"
 
 # --- ENSURE REQUIRED DIRECTORIES EXIST ---
-for d in (
+_REQUIRED_DIRS = (
+    STATE_DIR,
     DATA_DIR,
     MODELS_DIR,
     RUNTIME_DIR,
@@ -78,8 +179,25 @@ for d in (
     PLAYBOOK_DIR,
     UPLOADS_DIR,
     EXPORTS_DIR,
-):
-    d.mkdir(parents=True, exist_ok=True)
+    MEMORY_DB.parent,
+)
+
+
+def init_state() -> list[Path]:
+    """Create writable state and seed playbooks on a first wheel install."""
+    for directory in _REQUIRED_DIRS:
+        directory.mkdir(parents=True, exist_ok=True)
+    copied: list[Path] = []
+    if SEED_PLAYBOOK_DIR.resolve() != PLAYBOOK_DIR.resolve() and SEED_PLAYBOOK_DIR.is_dir():
+        for source in SEED_PLAYBOOK_DIR.glob("*.yaml"):
+            target = PLAYBOOK_DIR / source.name
+            if not target.exists():
+                shutil.copy2(source, target)
+                copied.append(target)
+    return copied
+
+
+INITIALIZED_FILES = init_state()
 
 # --- PATH ACCESSOR (fail-fast) ---
 def path(name: str) -> Path:
@@ -88,6 +206,9 @@ def path(name: str) -> Path:
     """
     mapping = {
         "root": PROJECT_ROOT,
+        "resources": RESOURCE_ROOT,
+        "state": STATE_DIR,
+        "config": CONFIG_FILE,
         "data": DATA_DIR,
         "models": MODELS_DIR,
         "runtime": RUNTIME_DIR,
@@ -98,6 +219,8 @@ def path(name: str) -> Path:
         "playbooks": PLAYBOOK_DIR,
         "uploads": UPLOADS_DIR,
         "exports": EXPORTS_DIR,
+        "web": WEB_DIST_DIR,
+        "assets": ASSETS_DIR,
         "memory_db": MEMORY_DB,
         "backend_log": BACKEND_LOG,
         "ollama_log": OLLAMA_LOG,
@@ -109,6 +232,36 @@ def path(name: str) -> Path:
         raise KeyError(f"Unknown config path name: {name}")
 
 # --- Settings class and exported instance ---
+def _normalize_ollama_host(raw: str) -> str:
+    """Turn an OLLAMA_HOST value into a URL a client can actually connect to.
+
+    OLLAMA_HOST is Ollama's *server bind* variable, and the common way to expose
+    Ollama on a LAN is `OLLAMA_HOST=0.0.0.0:11434`. Taken literally as a client
+    base URL that is unusable twice over: 0.0.0.0 means "every local interface"
+    to a listener but is not a destination, and there is no scheme for httpx to
+    parse. The result was a silent empty model list, because list_models()
+    catches everything and returns [].
+
+    So: supply the scheme when it's missing, and rewrite wildcard binds to
+    loopback. An explicit host is left alone — someone pointing at a real remote
+    Ollama means it.
+    """
+    host = (raw or "").strip().rstrip("/")
+    if not host:
+        return "http://127.0.0.1:11434"
+    if "://" not in host:
+        host = f"http://{host}"
+    scheme, _, rest = host.partition("://")
+    hostport = rest.split("/", 1)[0]
+    name, sep, port = hostport.rpartition(":")
+    if not sep:            # no port given
+        name, port = hostport, ""
+    # 0.0.0.0 and :: are bind-any; from a client they mean "this machine".
+    if name.strip("[]") in ("0.0.0.0", "::", ""):
+        name = "127.0.0.1"
+    return f"{scheme}://{name}:{port}" if port else f"{scheme}://{name}"
+
+
 class Settings:
     """
     Lightweight settings container. Use `settings` instance for runtime access,
@@ -116,12 +269,19 @@ class Settings:
     """
     def __init__(self) -> None:
         self.version: str = VERSION
+        self.source_checkout: bool = SOURCE_CHECKOUT
         self.project_root: Path = PROJECT_ROOT
+        self.resource_root: Path = RESOURCE_ROOT
+        self.state_dir: Path = STATE_DIR
+        self.config_file: Path = CONFIG_FILE
         self.data_dir: Path = DATA_DIR
         self.models_dir: Path = MODELS_DIR
         self.runtime_dir: Path = RUNTIME_DIR
         self.memory_dir: Path = MEMORY_DIR
         self.logs_dir: Path = LOGS_DIR
+        self.web_dist_dir: Path = WEB_DIST_DIR
+        self.frontend_source_dir: Path = FRONTEND_SOURCE_DIR
+        self.assets_dir: Path = ASSETS_DIR
 
         # DB files
         self.memory_db: Path = MEMORY_DB
@@ -131,21 +291,56 @@ class Settings:
         self.ollama_log: Path = OLLAMA_LOG
         self.chat_log: Path = CHAT_LOG
 
-        # Env overrides
-        self.ollama_host: str = os.getenv("OLLAMA_HOST", "http://127.0.0.1:11434")
-        self.ollama_timeout: int = int(os.getenv("OLLAMA_TIMEOUT", "120"))
+        # Env overrides. Two values from one variable, because OLLAMA_HOST means
+        # two different things: where a server should LISTEN, and where a client
+        # should CONNECT. `ollama_bind` keeps the user's literal intent for a
+        # serve we spawn (0.0.0.0 to expose it on the LAN); `ollama_host` is the
+        # connectable form for our own requests.
+        self.provider: str = str(_value("provider", "NEXUS_PROVIDER", "ollama"))
+        # A Nexus provider setting is more specific than the legacy Ollama bind
+        # variable. This matters on a desktop that has OLLAMA_HOST globally set
+        # but configures NexusOS to use a different remote inference machine.
+        provider_url = str(_value("provider_url", "NEXUS_PROVIDER_URL", "")).strip()
+        configured_host = (
+            provider_url
+            or os.getenv("OLLAMA_HOST", "").strip()
+            or "http://127.0.0.1:11434"
+        )
+        self.ollama_bind: str = configured_host or "127.0.0.1:11434"
+        self.ollama_host: str = _normalize_ollama_host(
+            configured_host
+        )
+        self.provider_url: str = self.ollama_host
+        self.manage_ollama: bool = self.provider == "ollama"
+        self.ollama_timeout: int = _int_value("provider_timeout", "OLLAMA_TIMEOUT", 120)
+        self.bind_host: str = str(_value(
+            "bind_host", "NEXUS_BIND_HOST", "127.0.0.1"
+        ))
+        self.backend_port: int = _int_value("backend_port", "NEXUS_BACKEND_PORT", 8000)
+        self.api_url: str = str(_value(
+            "api_url", "NEXUS_API", f"http://127.0.0.1:{self.backend_port}"
+        )).rstrip("/")
 
     def as_dict(self) -> Dict[str, Any]:
         return {
             "version": self.version,
+            "source_checkout": self.source_checkout,
             "project_root": str(self.project_root),
+            "resource_root": str(self.resource_root),
+            "state_dir": str(self.state_dir),
+            "config_file": str(self.config_file),
             "data_dir": str(self.data_dir),
             "models_dir": str(self.models_dir),
             "runtime_dir": str(self.runtime_dir),
             "memory_dir": str(self.memory_dir),
             "memory_db": str(self.memory_db),
+            "web_dist_dir": str(self.web_dist_dir),
+            "provider": self.provider,
             "ollama_host": self.ollama_host,
             "ollama_timeout": self.ollama_timeout,
+            "api_url": self.api_url,
+            "bind_host": self.bind_host,
+            "backend_port": self.backend_port,
         }
 
 # --- local-access allowlists (shared by the backend + memory FastAPI apps) ---
@@ -166,8 +361,12 @@ _LOCAL_HOSTS = ["localhost", "127.0.0.1", "[::1]", "::1", "testserver"]
 _LOCAL_ORIGINS = [
     f"http://{h}:{p}"
     for h in ("localhost", "127.0.0.1")
-    for p in (8000, 5173)
+    for p in (
+        _int_value("backend_port", "NEXUS_BACKEND_PORT", 8000),
+        5173,
+    )
 ]
+_LOCAL_ORIGINS.extend(["capacitor://localhost", "https://localhost"])
 ALLOWED_HOSTS = _csv_env("NEXUS_ALLOWED_HOSTS", _LOCAL_HOSTS)
 ALLOWED_ORIGINS = _csv_env("NEXUS_ALLOWED_ORIGINS", _LOCAL_ORIGINS)
 
@@ -213,9 +412,13 @@ settings = Settings()
 # explicit exports for static checkers and IDEs
 __all__ = ["Settings", "settings", "path", "VERSION",
            "DEFAULT_CHAT_MODEL", "DEFAULT_MEMORY_MODEL", "DEFAULT_EMBED_MODEL",
-           "PROJECT_ROOT", "DATA_DIR", "MODELS_DIR", "RUNTIME_DIR",
+           "PACKAGE_DIR", "PROJECT_ROOT", "RESOURCE_ROOT", "SOURCE_CHECKOUT",
+           "STATE_DIR", "CONFIG_DIR", "CONFIG_FILE", "USER_CONFIG",
+           "read_user_config", "write_user_config", "init_state", "INITIALIZED_FILES",
+           "DATA_DIR", "MODELS_DIR", "RUNTIME_DIR",
            "MEMORY_DIR", "LOGS_DIR", "PLAYBOOK_DIR", "UPLOADS_DIR",
-           "EXPORTS_DIR", "MEMORY_DB",
+           "EXPORTS_DIR", "MEMORY_DB", "WEB_DIST_DIR", "FRONTEND_SOURCE_DIR",
+           "ASSETS_DIR", "SEED_PLAYBOOK_DIR",
            "BACKEND_LOG", "OLLAMA_LOG", "CHAT_LOG",
            "ALLOWED_HOSTS", "ALLOWED_ORIGINS",
            "MAX_REQUEST_BYTES", "MAX_UPLOAD_BYTES", "MAX_PDF_PAGES",

synapse/ollama_manager.py

@@ -20,7 +20,9 @@ _log = logging.getLogger("nexus.ollama")
 _ollama_manager = None
 
 # Bundled binary ships alongside the project; fall back to system PATH
-_BUNDLED_OLLAMA = Path(__file__).resolve().parent.parent / "ollama" / "bin" / "ollama"
+_BUNDLED_OLLAMA = settings.project_root / "ollama" / "bin" / (
+    "ollama.exe" if os.name == "nt" else "ollama"
+)
 
 # POSIX: detach the child into its own session so we can signal the whole group.
 # Windows has no setsid/killpg — run the child normally and terminate() it.
@@ -200,13 +202,147 @@ def _chat_options(temperature: float | None, num_gpu: int | None, num_ctx: int |
     return opts
 
 
+_THINK_OPEN = "<think>"
+_THINK_CLOSE = "</think>"
+
+
+def _partial_tag_tail(text: str, tag: str) -> int:
+    """Length of the longest suffix of `text` that could be the start of `tag`.
+
+    A tag can arrive split across stream chunks ("<thi" then "nk>"), so that much
+    of the tail has to be held back rather than emitted.
+    """
+    for n in range(min(len(tag) - 1, len(text)), 0, -1):
+        if text.endswith(tag[:n]):
+            return n
+    return 0
+
+
+class ThinkStripper:
+    """Removes a reasoning model's <think> spans from a token stream.
+
+    Ollama routes reasoning into `message.thinking` only when asked to think.
+    We ask for `think: False` because the reasoning is pure latency here — but
+    deepseek-r1 and friends emit `<think>` inline in `content` anyway, so the
+    whole internal monologue reached the chat window, closing tags and all.
+
+    Two shapes show up in practice. A well-formed span is dropped whole. A
+    *stray* closing tag with no opening — which is what actually shipped — is at
+    least removed, so the user does not see a literal `</think>` in the reply.
+    Text already streamed before it cannot be recalled; `strip_think()` handles
+    that case properly for callers that have the complete message.
+    """
+
+    def __init__(self) -> None:
+        self._buf = ""
+        self._inside = False
+
+    def feed(self, chunk: str) -> str:
+        self._buf += chunk
+        out: list[str] = []
+        while True:
+            if self._inside:
+                end = self._buf.find(_THINK_CLOSE)
+                if end == -1:
+                    keep = _partial_tag_tail(self._buf, _THINK_CLOSE)
+                    self._buf = self._buf[len(self._buf) - keep:] if keep else ""
+                    break
+                self._buf = self._buf[end + len(_THINK_CLOSE):]
+                self._inside = False
+                continue
+
+            start = self._buf.find(_THINK_OPEN)
+            stray = self._buf.find(_THINK_CLOSE)
+            # A stray close before any open: drop the tag, keep going.
+            if stray != -1 and (start == -1 or stray < start):
+                out.append(self._buf[:stray])
+                self._buf = self._buf[stray + len(_THINK_CLOSE):]
+                continue
+            if start == -1:
+                keep = max(
+                    _partial_tag_tail(self._buf, _THINK_OPEN),
+                    _partial_tag_tail(self._buf, _THINK_CLOSE),
+                )
+                if keep:
+                    out.append(self._buf[:len(self._buf) - keep])
+                    self._buf = self._buf[len(self._buf) - keep:]
+                else:
+                    out.append(self._buf)
+                    self._buf = ""
+                break
+            out.append(self._buf[:start])
+            self._buf = self._buf[start + len(_THINK_OPEN):]
+            self._inside = True
+        return "".join(out)
+
+    def flush(self) -> str:
+        """Whatever is left once the stream ends. An unterminated <think> is
+        reasoning that never closed, so it is dropped rather than shown."""
+        rest = "" if self._inside else self._buf
+        self._buf = ""
+        return rest
+
+
+def strip_think(text: str) -> str:
+    """Remove reasoning from a complete message.
+
+    Unlike the streaming case this sees everything, so an unmatched closing tag
+    can be handled the way it was meant: every token before it was reasoning,
+    and the answer is what follows.
+    """
+    if not text or _THINK_CLOSE not in text and _THINK_OPEN not in text:
+        return text
+    import re
+    cleaned = re.sub(r"<think>.*?</think>", "", text, flags=re.S)
+    if _THINK_CLOSE in cleaned:               # stray close: the answer follows it
+        cleaned = cleaned.rsplit(_THINK_CLOSE, 1)[1]
+    cleaned = re.sub(r"<think>.*\Z", "", cleaned, flags=re.S)  # never closed
+    return cleaned.strip()
+
+
+async def _raise_for_ollama(r: httpx.Response) -> None:
+    """raise_for_status(), but say what Ollama actually said.
+
+    Ollama answers every failure with {"error": "..."} — a model that isn't
+    pulled, a request too large for VRAM, a cloud model retired upstream — and
+    httpx's default message discards the body, leaving the user with:
+
+        Client error '410 Gone' for url 'http://127.0.0.1:11434/api/chat'
+
+    when the body held "glm-4.6 was retired at 2026-06-16". Same exception type
+    as before so existing handlers are unaffected; only the message improves.
+    """
+    if r.is_success:
+        return
+    # A streamed response has no body loaded yet; reading it is what makes the
+    # error message available at all.
+    try:
+        await r.aread()
+    except Exception:
+        pass
+    detail = ""
+    try:
+        body = r.json()
+        if isinstance(body, dict):
+            detail = str(body.get("error") or "").strip()
+    except Exception:
+        detail = (r.text or "").strip()
+    if not detail:
+        r.raise_for_status()  # nothing to add — keep httpx's wording
+    raise httpx.HTTPStatusError(
+        f"Ollama {r.status_code} from {r.request.url.path}: {detail[:400]}",
+        request=r.request,
+        response=r,
+    )
+
+
 class OllamaManager:
     def __init__(self, runtime_dir=None):
         self.process = None
         self.running = False
         self._available = None      # see is_available()
 
-        self.runtime_dir = Path(runtime_dir) if runtime_dir else Path(__file__).resolve().parent.parent / "runtime"
+        self.runtime_dir = Path(runtime_dir) if runtime_dir else settings.runtime_dir
         (self.runtime_dir / "logs").mkdir(parents=True, exist_ok=True)
 
         self.log_file = self.runtime_dir / "logs" / "ollama.log"
@@ -258,7 +394,9 @@ class OllamaManager:
         duplicated verbatim in two methods, so the Windows carve-out below had
         to be fixed in both places or the two paths would disagree."""
         env = os.environ.copy()
-        env["OLLAMA_HOST"] = self._api_base
+        # The bind value, not the connect value: a user who set 0.0.0.0 to reach
+        # Ollama from another machine must still get a server that listens there.
+        env["OLLAMA_HOST"] = settings.ollama_bind
         # Every platform uses the project's own model store. Windows used to be
         # exempt, because the installer pulled with a bare `ollama pull` into
         # %USERPROFILE%\.ollama and a NexusOS-spawned serve pointed elsewhere
@@ -270,6 +408,10 @@ class OllamaManager:
         return env
 
     def is_available(self):
+        if not settings.manage_ollama:
+            # A remote provider has no local executable to discover. Availability
+            # means it is configured; is_running() performs the live probe.
+            return True
         # ponytail: cached for the life of the process. This spawns a subprocess,
         # and /status calls it on every poll - the frontend polls continuously,
         # so it was a process spawn per tick to answer a question whose answer
@@ -297,6 +439,9 @@ class OllamaManager:
             return False
 
     def start(self):
+        if not settings.manage_ollama:
+            _log.info("Remote Ollama is externally managed at %s", self._api_base)
+            return self.is_running()
         if not self.is_available():
             _log.warning("Ollama not found at %s; skipping startup", _ollama_bin())
             return False
@@ -338,6 +483,9 @@ class OllamaManager:
 
     async def start_async(self):
         """Async-safe version of start() for use inside async startup handlers."""
+        if not settings.manage_ollama:
+            _log.info("Remote Ollama is externally managed at %s", self._api_base)
+            return self.is_running()
         if not self.is_available():
             _log.warning("Ollama not found at %s; skipping startup", _ollama_bin())
             return False
@@ -378,6 +526,9 @@ class OllamaManager:
             return False
 
     def stop(self):
+        if not settings.manage_ollama:
+            _log.info("Not stopping externally managed Ollama at %s", self._api_base)
+            return False
         # Terminate a server we spawned ourselves.
         if self.process:
             try:
@@ -459,7 +610,7 @@ class OllamaManager:
 
                 elapsed = time.perf_counter() - start
                 _log.info("generate completed model=%s status=%d elapsed=%.3fs", model, r.status_code, elapsed)
-                r.raise_for_status()
+                await _raise_for_ollama(r)
                 return r.json().get("response", "")
 
         except Exception as e:
@@ -484,7 +635,7 @@ class OllamaManager:
                         "stream": True,
                     }),
                 ) as response:
-                    response.raise_for_status()
+                    await _raise_for_ollama(response)
                     async for line in response.aiter_lines():
                         if not line.strip():
                             continue
@@ -547,8 +698,12 @@ class OllamaManager:
                 async with httpx.AsyncClient(timeout=300.0) as client:
                     r = await client.post(f"{self._api_base}/api/chat", json=body)
                 elapsed = time.perf_counter() - start
-                r.raise_for_status()
+                await _raise_for_ollama(r)
                 message = r.json().get("message", {})
+                # A reasoning model puts its monologue in `content` even with
+                # think off, so strip it before anyone reads the answer.
+                if isinstance(message, dict) and message.get("content"):
+                    message["content"] = strip_think(message["content"])
                 # Tool callers need the whole message (tool_calls); others want content.
                 return message if tools else message.get("content", "")
         except Exception as e:
@@ -576,7 +731,7 @@ class OllamaManager:
                     f"{self._api_base}/api/embeddings",
                     json=body,
                 )
-                r.raise_for_status()
+                await _raise_for_ollama(r)
                 vec = r.json().get("embedding")
                 return vec if vec else None
         except Exception as e:
@@ -588,7 +743,7 @@ class OllamaManager:
         try:
             async with httpx.AsyncClient(timeout=5.0) as client:
                 r = await client.get(f"{self._api_base}/api/tags")
-                r.raise_for_status()
+                await _raise_for_ollama(r)
                 return [m["name"] for m in r.json().get("models", [])]
         except Exception:
             return []
@@ -629,7 +784,7 @@ class OllamaManager:
         try:
             async with httpx.AsyncClient(timeout=10.0) as client:
                 r = await client.post(f"{self._api_base}/api/show", json={"model": model})
-            r.raise_for_status()
+            await _raise_for_ollama(r)
             info = r.json().get("model_info", {}) or {}
             block_count = next(
                 (v for k, v in info.items() if k.endswith(".block_count")), None
@@ -679,7 +834,8 @@ class OllamaManager:
                     f"{self._api_base}/api/chat",
                     json=body,
                 ) as response:
-                    response.raise_for_status()
+                    await _raise_for_ollama(response)
+                    thinking = ThinkStripper()
                     async for line in response.aiter_lines():
                         if not line.strip():
                             continue
@@ -687,8 +843,13 @@ class OllamaManager:
                             data = json.loads(line)
                             token = data.get("message", {}).get("content", "")
                             if token:
-                                yield token
+                                token = thinking.feed(token)
+                                if token:
+                                    yield token
                             if data.get("done", False):
+                                tail = thinking.flush()  # held-back partial tag
+                                if tail:
+                                    yield tail
                                 elapsed = time.perf_counter() - start
                                 _log.info("chat stream completed model=%s elapsed=%.3fs", model, elapsed)
                                 eval_count = data.get("eval_count", 0)
@@ -756,4 +917,4 @@ def shutdown_ollama() -> None:
     global _ollama_manager
     if _ollama_manager is not None:
         _ollama_manager.stop()
-        _ollama_manager = None
+        _ollama_manager = None

synapse/proc_util.py

@@ -0,0 +1,212 @@
+"""Process inspection and termination that works with or without psutil.
+
+psutil became an optional extra when the wheel landed, so the base install
+(notably `pip install nexusos-ai` on Windows) has to manage PIDs with the
+stdlib alone. Callers should keep using psutil when it is importable - it is
+faster and more precise - and fall back here when it is not.
+
+Windows has no signals: os.kill(pid, sig) special-cases CTRL_C_EVENT and
+CTRL_BREAK_EVENT, treats sig 0 as an existence check, and calls
+TerminateProcess(handle, sig) for *everything else*. So os.kill(pid, 15) is not
+a polite request there - it is an immediate, unblockable kill with exit code
+15, and there is no equivalent of SIGTERM. Everything below goes through the
+Win32 API via ctypes so the intent is explicit at each call site rather than
+resting on which signal numbers happen to be special.
+"""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+from pathlib import Path
+
+WINDOWS = os.name == "nt"
+
+# Win32 constants (winnt.h / processthreadsapi.h)
+_SYNCHRONIZE = 0x00100000
+_PROCESS_TERMINATE = 0x0001
+_WAIT_TIMEOUT = 0x00000102
+
+# Keep console windows from flashing on every helper subprocess.
+_NO_WINDOW = subprocess.CREATE_NO_WINDOW if WINDOWS else 0
+
+
+def _kernel32():
+    import ctypes
+
+    return ctypes.WinDLL("kernel32", use_last_error=True)
+
+
+def _run(argv: list[str], timeout: float = 10.0) -> str:
+    """Run a helper command, returning stdout ('' on any failure)."""
+    try:
+        done = subprocess.run(
+            argv, capture_output=True, text=True, timeout=timeout,
+            creationflags=_NO_WINDOW,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return done.stdout or ""
+
+
+def pid_alive(pid: int | None) -> bool:
+    """True if the PID names a live process.
+
+    On Windows this opens a handle and polls it; a signalled handle means the
+    process has exited. That is equivalent to os.kill(pid, 0) - CPython
+    special-cases signal 0 into an existence check there - but it also reports
+    True for a process owned by another user, where os.kill raises.
+    """
+    if pid is None:
+        return False
+    try:
+        pid = int(pid)
+    except (TypeError, ValueError):
+        return False
+    if pid <= 0:
+        return False
+    if WINDOWS:
+        import ctypes
+
+        k = _kernel32()
+        handle = k.OpenProcess(_SYNCHRONIZE, False, pid)
+        if not handle:
+            return False
+        try:
+            return k.WaitForSingleObject(ctypes.c_void_p(handle), 0) == _WAIT_TIMEOUT
+        finally:
+            k.CloseHandle(ctypes.c_void_p(handle))
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True          # exists, owned by someone else
+    except (OSError, ValueError):
+        return False
+
+
+def terminate_pid(pid: int | None, force: bool = False) -> bool:
+    """Ask a process to exit. Returns True if the request was delivered."""
+    if not pid_alive(pid):
+        return False
+    pid = int(pid)
+    if WINDOWS:
+        # No graceful path without a shared console; TerminateProcess is what
+        # psutil.terminate() resolves to on Windows anyway.
+        import ctypes
+
+        k = _kernel32()
+        handle = k.OpenProcess(_PROCESS_TERMINATE, False, pid)
+        if not handle:
+            return False
+        try:
+            return bool(k.TerminateProcess(ctypes.c_void_p(handle), 1))
+        finally:
+            k.CloseHandle(ctypes.c_void_p(handle))
+    try:
+        os.kill(pid, signal.SIGKILL if force else signal.SIGTERM)
+        return True
+    except OSError:
+        return False
+
+
+def pid_cmdline(pid: int | None) -> str:
+    """Full command line for a PID, or '' when it cannot be determined."""
+    if pid is None:
+        return ""
+    try:
+        pid = int(pid)
+    except (TypeError, ValueError):
+        return ""
+    if WINDOWS:
+        for entry_pid, cmd in iter_processes():
+            if entry_pid == pid:
+                return cmd
+        return ""
+    proc = Path(f"/proc/{pid}/cmdline")
+    try:
+        return proc.read_bytes().replace(b"\0", b" ").decode(errors="replace").strip()
+    except OSError:
+        pass
+    # macOS and other POSIX hosts without /proc.
+    out = _run(["ps", "-o", "command=", "-p", str(pid)])
+    return out.strip()
+
+
+def iter_processes() -> list[tuple[int, str]]:
+    """(pid, command_line) for every visible process.
+
+    Windows needs CIM for command lines - the ctypes snapshot APIs only expose
+    image names, which is not enough to tell `uvicorn synapse.main` apart from
+    any other python.exe. This is slow, so it is strictly the no-psutil path.
+    """
+    if WINDOWS:
+        out = _run([
+            "powershell", "-NoProfile", "-NonInteractive", "-Command",
+            "Get-CimInstance Win32_Process | "
+            "ForEach-Object { \"$($_.ProcessId)`t$($_.CommandLine)\" }",
+        ], timeout=30.0)
+        entries: list[tuple[int, str]] = []
+        for line in out.splitlines():
+            head, _, cmd = line.partition("\t")
+            if head.strip().isdigit():
+                entries.append((int(head), cmd.strip()))
+        return entries
+
+    entries = []
+    proc_root = Path("/proc")
+    if proc_root.is_dir():
+        for entry in proc_root.iterdir():
+            if not entry.name.isdigit():
+                continue
+            try:
+                cmd = (entry / "cmdline").read_bytes()
+            except OSError:
+                continue
+            entries.append((int(entry.name), cmd.replace(b"\0", b" ").decode(errors="replace").strip()))
+        return entries
+
+    for line in _run(["ps", "-A", "-o", "pid=,command="]).splitlines():
+        head, _, cmd = line.strip().partition(" ")
+        if head.isdigit():
+            entries.append((int(head), cmd.strip()))
+    return entries
+
+
+def pids_listening_on(port: int) -> list[int]:
+    """PIDs holding a listening TCP socket on `port`."""
+    pids: list[int] = []
+    if WINDOWS:
+        for line in _run(["netstat", "-ano", "-p", "TCP"]).splitlines():
+            parts = line.split()
+            # Proto  Local            Foreign  State      PID
+            if len(parts) < 5 or parts[3] != "LISTENING":
+                continue
+            local = parts[1]
+            if local.rsplit(":", 1)[-1] == str(port) and parts[4].isdigit():
+                pids.append(int(parts[4]))
+        return sorted(set(pids))
+
+    # -t TCP, -l listening, -n numeric, -P no port names.
+    for line in _run(["lsof", "-nP", "-tiTCP:%d" % port, "-sTCP:LISTEN"]).splitlines():
+        if line.strip().isdigit():
+            pids.append(int(line.strip()))
+    if pids:
+        return sorted(set(pids))
+
+    for line in _run(["ss", "-lptnH", "sport = :%d" % port]).splitlines():
+        # ... users:(("uvicorn",pid=1234,fd=3))
+        marker = "pid="
+        start = line.find(marker)
+        while start != -1:
+            digits = ""
+            for ch in line[start + len(marker):]:
+                if not ch.isdigit():
+                    break
+                digits += ch
+            if digits:
+                pids.append(int(digits))
+            start = line.find(marker, start + 1)
+    return sorted(set(pids))

tests/test_cli_packaging.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def run_cli(tmp_path: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    env = os.environ.copy()
+    for key in tuple(env):
+        if key.startswith("NEXUS_"):
+            env.pop(key)
+    env["NEXUS_HOME"] = str(tmp_path / "state")
+    env["NEXUS_CONFIG_DIR"] = str(tmp_path / "config")
+    return subprocess.run(
+        [sys.executable, "-m", "nexusos_cli.cli", *args],
+        cwd=ROOT,
+        env=env,
+        text=True,
+        capture_output=True,
+        timeout=30,
+        check=False,
+    )
+
+
+def test_help_exposes_portable_command_tree(tmp_path):
+    result = run_cli(tmp_path, "--help")
+    assert result.returncode == 0, result.stderr
+    for command in ("init", "config", "provider", "doctor", "serve", "models", "chat", "monitor", "tui"):
+        assert command in result.stdout
+    assert "interactive TUI" in result.stdout or "TUI" in result.stdout
+
+
+def test_bare_nexus_defaults_to_tui_command():
+    """No subcommand → TUI entry (Hermes-style). Non-TTY exits 2 without launching."""
+    from unittest import mock
+
+    from nexusos_cli.cli import build_parser, cmd_tui
+
+    parser = build_parser()
+    args = parser.parse_args([])
+    assert args.command is None  # filled in by main()
+    with mock.patch("sys.stdin.isatty", return_value=False), \
+         mock.patch("sys.stdout.isatty", return_value=False):
+        assert cmd_tui(args) == 2
+
+
+def test_legacy_cli_spellings_remain_compatible():
+    from nexusos_cli.cli import _normalize_legacy_argv
+
+    assert _normalize_legacy_argv(["start", "-b"]) == ["start", "backend"]
+    assert _normalize_legacy_argv(["stop", "--ai"]) == ["stop", "ai"]
+    assert _normalize_legacy_argv(["backup", "full"]) == ["backup", "--full"]
+    # -f is --follow for `logs`, but --frontend for start/stop. Translating it
+    # for logs turned `logs -f` into a one-shot tail of the frontend log.
+    assert _normalize_legacy_argv(["logs", "-f"]) == ["logs", "-f"]
+    assert _normalize_legacy_argv(["start", "-f"]) == ["start", "frontend"]
+    assert _normalize_legacy_argv(["restore", "-f"]) == ["restore"]
+    assert _normalize_legacy_argv(["help"]) == ["--help"]
+
+
+def test_init_uses_external_state_and_seeds_playbooks(tmp_path):
+    result = run_cli(tmp_path, "init", "--json")
+    assert result.returncode == 0, result.stderr
+    payload = json.loads(result.stdout)
+    assert Path(payload["state_dir"]) == (tmp_path / "state").resolve()
+    assert payload["seeded_playbooks"] == len(list((ROOT / "data" / "playbooks").glob("*.yaml")))
+    assert len(list((tmp_path / "state" / "data" / "playbooks").glob("*.yaml"))) > 0
+
+
+def test_config_persists_validated_values(tmp_path):
+    set_result = run_cli(tmp_path, "config", "set", "backend_port", "8123", "--json")
+    assert set_result.returncode == 0, set_result.stderr
+
+    get_result = run_cli(tmp_path, "config", "get", "backend_port", "--json")
+    assert get_result.returncode == 0, get_result.stderr
+    assert json.loads(get_result.stdout)["backend_port"] == 8123
+
+    invalid = run_cli(tmp_path, "config", "set", "backend_port", "70000")
+    assert invalid.returncode == 2
+    assert "between 1 and 65535" in invalid.stderr
+
+
+def test_remote_provider_configuration_is_explicit(tmp_path):
+    result = run_cli(
+        tmp_path, "provider", "use", "remote", "--url", "http://phone-lan:11434", "--json"
+    )
+    assert result.returncode == 0, result.stderr
+    payload = json.loads(result.stdout)
+    assert payload["provider"] == "ollama-remote"
+    assert payload["url"] == "http://phone-lan:11434"
+
+    values = json.loads((tmp_path / "config" / "config.json").read_text(encoding="utf-8"))
+    assert values["provider"] == "ollama-remote"
+
+    show = run_cli(tmp_path, "provider", "show", "--json")
+    assert show.returncode == 0, show.stderr
+    assert json.loads(show.stdout)["url"] == "http://phone-lan:11434"
+
+
+def test_serve_rejects_invalid_ports_before_startup(tmp_path):
+    result = run_cli(tmp_path, "serve", "--port", "0")
+    assert result.returncode == 2
+    assert "between 1 and 65535" in result.stderr
+
+
+def test_remote_provider_is_never_stopped_or_force_killed(monkeypatch):
+    from nexusos_cli import ncp
+
+    killed_ports = []
+    killed_patterns = []
+    monkeypatch.setattr(ncp.settings, "manage_ollama", False)
+    monkeypatch.setattr(ncp.settings, "ollama_host", "http://remote.test:11434")
+    monkeypatch.setattr(ncp, "kill_port", lambda port: killed_ports.append(port) or False)
+    monkeypatch.setattr(
+        ncp, "kill_matching", lambda patterns, force=False: killed_patterns.extend(patterns) or 0
+    )
+
+    ncp.stop_ollama()
+    ncp.cmd_kill()
+
+    assert 11434 not in killed_ports
+    assert "ollama serve" not in killed_patterns
+
+
+def test_allow_lan_names_addresses_instead_of_disabling_the_host_check():
+    """ALLOWED_HOSTS=* would switch TrustedHostMiddleware off entirely, and that
+    middleware is the DNS-rebinding defense for an unauthenticated API."""
+    from nexusos_cli.cli import _lan_hostnames
+
+    assert _lan_hostnames("192.168.1.20") == ["192.168.1.20"]
+    wildcard = _lan_hostnames("0.0.0.0")
+    assert wildcard, "a wildcard bind must resolve to concrete host names"
+    assert "*" not in wildcard
+    # IPv6 literals need to match a Host header written either way.
+    for name in wildcard:
+        if ":" in name and not name.startswith("["):
+            assert f"[{name}]" in wildcard
+
+
+def test_empty_platform_dir_variables_do_not_put_state_in_the_cwd(tmp_path, monkeypatch):
+    """os.getenv's default only fires when a variable is *unset*; an exported
+    but empty XDG_DATA_HOME / LOCALAPPDATA made Path("") == "." the base, so
+    state landed in whatever directory the command happened to run from.
+
+    Patching os.name to exercise the other platform's branch is not an option -
+    pathlib dispatches on it - so this checks the branch this host actually
+    takes."""
+    from synapse import nexus_config
+
+    if os.name == "nt":
+        monkeypatch.setenv("LOCALAPPDATA", "")
+        expected = Path.home() / "AppData" / "Local" / "NexusOS"
+    else:
+        monkeypatch.setenv("XDG_DATA_HOME", "")
+        expected = Path.home() / ".local/share" / "nexusos"
+    monkeypatch.delenv("NEXUS_HOME", raising=False)
+    monkeypatch.chdir(tmp_path)
+
+    resolved = nexus_config._user_dir("NEXUS_HOME", "NexusOS", "XDG_DATA_HOME", ".local/share")
+    assert resolved.is_absolute()
+    assert tmp_path.resolve() != resolved.parent
+    assert resolved == expected.resolve()
+
+
+def test_config_set_warns_before_orphaning_the_database(tmp_path):
+    """Repointing the DB does not move it - say so, or history looks deleted."""
+    assert run_cli(tmp_path, "init").returncode == 0
+    db = tmp_path / "state" / "data" / "memory.db"
+    db.parent.mkdir(parents=True, exist_ok=True)
+    db.write_bytes(b"SQLite format 3" + bytes(1))
+
+    result = run_cli(tmp_path, "config", "set", "memory_db", str(tmp_path / "elsewhere.db"), "--json")
+    assert result.returncode == 0, result.stderr
+    assert "warning" in json.loads(result.stdout)
+
+    same = run_cli(tmp_path, "config", "set", "memory_db", str(db), "--json")
+    assert "warning" not in json.loads(same.stdout)

tests/test_documents.py

@@ -136,6 +136,27 @@ def test_conversation_recall_uses_vec_and_matches_brute_force():
     asyncio.run(run())
 
 
+def test_startup_sweeps_pre_existing_orphan_vectors():
+    """Databases written before delete_conversation cleaned up after itself are
+    repaired the next time the store opens them."""
+    import json
+    path = Path(tempfile.mkdtemp()) / "t.db"
+    s = PersistentMemoryStore(path)
+    s.create_conversation("c1")
+    mid = s.add_message("c1", "user", "lego star wars")
+    conn = s._connect()
+    conn.execute("INSERT INTO message_vectors (message_id, embedding) VALUES (?, ?)",
+                 (mid, json.dumps([1.0, 0.0])))
+    conn.execute("DELETE FROM messages WHERE id = ?", (mid,))  # the old leaky delete
+    conn.commit()
+    conn.close()
+
+    reopened = PersistentMemoryStore(path)
+    conn = reopened._connect()
+    assert conn.execute("SELECT COUNT(*) FROM message_vectors").fetchone()[0] == 0
+    conn.close()
+
+
 def test_projects_scope_documents_and_survive_delete():
     s = _store()
 

tests/test_macos_install.py

@@ -0,0 +1,33 @@
+"""Platform guards for the community-supported native macOS install path."""
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SPEC = importlib.util.spec_from_file_location("nexus_sync_macos_test", ROOT / "bin" / "sync.py")
+assert SPEC and SPEC.loader
+sync = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(sync)
+
+
+def test_darwin_uses_gpu_agnostic_requirements(monkeypatch):
+    monkeypatch.setattr(sync.os, "name", "posix")
+    monkeypatch.setattr(sync.sys, "platform", "darwin")
+    assert sync.requirements() == "requirements-base.txt"
+
+
+def test_linux_provisioning_stages_are_skipped_on_darwin(monkeypatch):
+    monkeypatch.setattr(sync.sys, "platform", "darwin")
+
+    def unexpected_run(*args, **kwargs):
+        raise AssertionError(f"Linux provisioning ran on macOS: {args!r}")
+
+    monkeypatch.setattr(sync.subprocess, "run", unexpected_run)
+    sync.linux_stage("restore-linux.sh", "packages")
+
+
+def test_macos_installer_is_in_the_shell_parse_gate():
+    gate = (ROOT / "bin" / "check.sh").read_text(encoding="utf-8")
+    assert "install-macos.sh" in gate

tests/test_monitor.py

@@ -0,0 +1,77 @@
+"""Tests for the ASCII monitor — renderer + collectors, no live stack required."""
+from __future__ import annotations
+
+from nexusos_cli.monitor import _bar, _fmt_bytes, _recent_tools, render_frame
+
+
+def test_bar_bounds():
+    assert _bar(0, 10, unicode=False) == "-" * 10
+    assert _bar(1, 10, unicode=False) == "#" * 10
+    assert _bar(0.5, 10, unicode=False).count("#") == 5
+
+
+def test_fmt_bytes():
+    assert _fmt_bytes(None) == "—"
+    assert _fmt_bytes(512) == "512B"
+    assert _fmt_bytes(2048).endswith("K")
+
+
+def test_render_frame_contains_sections():
+    snap = {
+        "ts": "2026-08-20T12:00:00-05:00",
+        "version": "0.0.0",
+        "services": {
+            "backend": {"running": True, "pid": 11, "url": "http://127.0.0.1:8000"},
+            "frontend": {"running": False, "pid": None, "url": "http://127.0.0.1:5173"},
+            "provider": {
+                "provider": "ollama",
+                "url": "http://127.0.0.1:11434",
+                "reachable": True,
+            },
+        },
+        "api": {
+            "online": True,
+            "version": "0.0.0",
+            "ollama": "running",
+            "memories": 3,
+            "conversations": 2,
+            "playbooks": 1,
+            "models": 4,
+            "action_tool_policy": "ask",
+        },
+        "host": {"cpu_pct": 12.5, "mem_used": 1_000_000_000, "mem_total": 8_000_000_000, "mem_pct": 12.5},
+        "procs": {"cpu_pct": 1.0, "rss": 50_000_000, "pids": [11]},
+        "toolchains": [
+            {"lang": "python", "ready": True, "tool": "/usr/bin/python", "summary": "python"},
+            {"lang": "rust", "ready": False, "tool": None, "summary": "rust"},
+        ],
+        "recent_tools": ["run_snippet", "render_preview"],
+        "paths": {},
+    }
+    frame = render_frame(snap, width=72, unicode=False)
+    assert "SERVICES" in frame
+    assert "RESOURCES" in frame
+    assert "DATA / TOOLS" in frame
+    assert "RUN TOOLCHAINS" in frame
+    assert "backend" in frame and "UP" in frame
+    assert "frontend" in frame and "DOWN" in frame
+    assert "run_snippet" in frame
+    assert "ready    python" in frame
+    assert "missing  rust" in frame
+    # Fixed-width box: every content line same length.
+    lengths = {len(line) for line in frame.splitlines()}
+    assert len(lengths) == 1
+
+
+def test_recent_tools_parses_status_sentinels(tmp_path):
+    log = tmp_path / "chat.log"
+    log.write_text(
+        "noise\n__status__tools\n__status__run_snippet\n"
+        'payload {"name": "render_preview"}\n__status__remember\n',
+        encoding="utf-8",
+    )
+    found = _recent_tools(log, limit=5)
+    assert "run_snippet" in found
+    assert "remember" in found
+    assert "render_preview" in found
+    assert "tools" not in found

tests/test_nexus_api.py

@@ -1,7 +1,5 @@
-"""Pin the SSE parser in nexus_api. Run: python management/test_nexus_api.py"""
-import sys, os
-sys.path.insert(0, os.path.dirname(__file__))
-from nexus_api import iter_chunks
+"""Pin the SSE parser in nexus_api. Run: python tests/test_nexus_api.py"""
+from nexusos_cli.nexus_api import iter_chunks
 
 # A realistic /chat/stream frame: two token chunks, a meta block, then done.
 lines = [

tests/test_packaging_deps.py

@@ -0,0 +1,151 @@
+"""Guard the wheel's dependency list against drift.
+
+There are now two dependency declarations: requirements-base.txt (what the
+desktop installers pip -r) and pyproject.toml (what the wheel ships). They will
+drift. What actually breaks a user is narrower than "they differ", though: it
+is an import that no declared distribution provides, so that is what this pins.
+"""
+from __future__ import annotations
+
+import ast
+import sys
+import tomllib
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+SHIPPED_PACKAGES = ("synapse", "nexusos_cli", "modules")
+
+# Import name -> distribution name, where PyPI disagrees with the module.
+DISTRIBUTION_OF = {
+    "docx": "python-docx",
+    "dotenv": "python-dotenv",
+    "faster_whisper": "faster-whisper",
+    "imap_tools": "imap-tools",
+    "sqlite_vec": "sqlite-vec",
+    "yaml": "pyyaml",
+    "PIL": "pillow",
+}
+
+# Provided by another declared distribution rather than named directly.
+# rich: Textual depends on it, so the tui extra already pulls it in.
+TRANSITIVE = {"starlette", "socketio", "engineio", "rich"}
+
+# Modules that ship inside this repo.
+FIRST_PARTY = {"synapse", "nexusos_cli", "modules", "management", "bin", "tests"}
+
+
+def _pyproject() -> dict:
+    return tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))
+
+
+def _requirement_name(spec: str) -> str:
+    """'pypdf>=5,<7' -> 'pypdf'; strips extras and environment markers."""
+    head = spec.split(";", 1)[0].strip()
+    for sep in ("[", "=", ">", "<", "!", "~", " "):
+        head = head.split(sep, 1)[0]
+    return head.strip().lower().replace("_", "-")
+
+
+def _declared() -> set[str]:
+    project = _pyproject()["project"]
+    specs = list(project.get("dependencies", []))
+    for extra in project.get("optional-dependencies", {}).values():
+        specs.extend(extra)
+    return {_requirement_name(s) for s in specs}
+
+
+def test_wheel_includes_every_shipped_package():
+    wheel = _pyproject()["tool"]["hatch"]["build"]["targets"]["wheel"]
+    configured = set(wheel["packages"])
+    assert configured == set(SHIPPED_PACKAGES)
+
+
+def _imported_modules() -> set[str]:
+    """Top-level module names imported anywhere in the shipped packages."""
+    found: set[str] = set()
+    for package in SHIPPED_PACKAGES:
+        for path in (ROOT / package).rglob("*.py"):
+            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    found.update(alias.name.split(".")[0] for alias in node.names)
+                elif isinstance(node, ast.ImportFrom):
+                    # level > 0 is a relative (first-party) import.
+                    if node.level == 0 and node.module:
+                        found.add(node.module.split(".")[0])
+    return found
+
+
+def _third_party() -> set[str]:
+    return {
+        module for module in _imported_modules()
+        if module not in sys.stdlib_module_names
+        and module not in FIRST_PARTY
+        and module not in TRANSITIVE
+        and not module.startswith("_")
+    }
+
+
+def test_every_third_party_import_is_a_declared_dependency():
+    declared = _declared()
+    missing = sorted(
+        module for module in _third_party()
+        if DISTRIBUTION_OF.get(module, module).lower().replace("_", "-") not in declared
+    )
+    assert not missing, (
+        "a shipped package imports these, but pyproject.toml declares no "
+        f"distribution for them: {missing}. Add them to [project] dependencies "
+        "or an extra (and to DISTRIBUTION_OF here if the names differ)."
+    )
+
+
+def test_all_extra_is_the_union_of_the_capability_extras():
+    extras = _pyproject()["project"]["optional-dependencies"]
+    combined: set[str] = set()
+    for name, specs in extras.items():
+        if name in ("all", "dev", "standard"):
+            continue
+        combined.update(_requirement_name(s) for s in specs)
+    everything = {_requirement_name(s) for s in extras["all"]}
+    assert combined == everything, (
+        "the 'all' extra drifted from the capability extras; "
+        f"missing={sorted(combined - everything)} extra={sorted(everything - combined)}"
+    )
+
+
+@pytest.mark.parametrize("name", ["fastapi", "uvicorn", "httpx", "pydantic", "pyyaml"])
+def test_core_runtime_is_a_hard_dependency_not_an_extra(name):
+    """These are imported at module scope, so the base install must carry them."""
+    base = {_requirement_name(s) for s in _pyproject()["project"]["dependencies"]}
+    assert name in base
+
+
+def test_optional_imports_are_lazy():
+    """Anything only in an extra must not be imported at module scope.
+
+    A base `pip install nexusos-ai` has none of the extras, so a top-level
+    `import psutil` in synapse would make the backend unimportable.
+    """
+    base = {_requirement_name(s) for s in _pyproject()["project"]["dependencies"]}
+    offenders: list[str] = []
+    for package in SHIPPED_PACKAGES:
+        for path in (ROOT / package).rglob("*.py"):
+            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+            for node in tree.body:          # module scope only
+                names: list[str] = []
+                if isinstance(node, ast.Import):
+                    names = [a.name.split(".")[0] for a in node.names]
+                elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+                    names = [node.module.split(".")[0]]
+                for module in names:
+                    if module in sys.stdlib_module_names or module in FIRST_PARTY:
+                        continue
+                    dist = DISTRIBUTION_OF.get(module, module).lower().replace("_", "-")
+                    if dist not in base and module not in TRANSITIVE:
+                        offenders.append(f"{path.relative_to(ROOT)}: {module}")
+    assert not offenders, (
+        "optional dependencies imported at module scope (wrap in try/ImportError "
+        f"or import inside the function): {offenders}"
+    )

tests/test_proc_util.py

@@ -0,0 +1,94 @@
+"""Pin the psutil-free process helpers.
+
+psutil is an optional extra, so on a base install these are the only way
+`ncp stop` / `nexus status` can see or stop a service. Windows previously had
+no fallback at all: pid_is_ours returned False, kill_port returned False, and
+the terminate branch was POSIX-only, so stop was a no-op there.
+
+Probing must also stay side-effect free. That is easy to get wrong on Windows,
+where os.kill(pid, sig) is TerminateProcess for every sig except 0 and the two
+console-control events - os.kill(pid, 15) kills instead of asking.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+import time
+
+import pytest
+
+from synapse import proc_util
+
+
+def _spawn():
+    return subprocess.Popen(
+        [sys.executable, "-c", "import time; time.sleep(30)"],
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+    )
+
+
+def _wait_gone(proc, timeout=10.0) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if proc.poll() is not None:
+            return True
+        time.sleep(0.05)
+    return False
+
+
+@pytest.fixture
+def victim():
+    proc = _spawn()
+    try:
+        yield proc
+    finally:
+        if proc.poll() is None:
+            proc.kill()
+            proc.wait(timeout=10)
+
+
+def test_pid_alive_does_not_kill_the_process(victim):
+    """Probing must be side-effect free, however it is implemented."""
+    for _ in range(5):
+        assert proc_util.pid_alive(victim.pid) is True
+    time.sleep(0.3)
+    assert victim.poll() is None, "pid_alive() terminated the process it probed"
+
+
+def test_pid_alive_is_false_for_a_dead_pid(victim):
+    victim.kill()
+    victim.wait(timeout=10)
+    assert proc_util.pid_alive(victim.pid) is False
+
+
+@pytest.mark.parametrize("pid", [None, 0, -1, "not-a-pid"])
+def test_pid_alive_rejects_junk(pid):
+    assert proc_util.pid_alive(pid) is False
+
+
+def test_terminate_pid_actually_stops_it(victim):
+    assert proc_util.terminate_pid(victim.pid) is True
+    assert _wait_gone(victim), "terminate_pid() did not stop the process"
+    assert proc_util.pid_alive(victim.pid) is False
+
+
+def test_terminate_pid_is_false_when_already_gone(victim):
+    victim.kill()
+    victim.wait(timeout=10)
+    assert proc_util.terminate_pid(victim.pid) is False
+
+
+def test_pid_cmdline_identifies_the_process(victim):
+    cmd = proc_util.pid_cmdline(victim.pid)
+    if not cmd:
+        pytest.skip("no command-line source on this host")
+    assert "time.sleep" in cmd or "python" in cmd.lower()
+
+
+def test_iter_processes_includes_this_interpreter():
+    import os
+
+    entries = proc_util.iter_processes()
+    if not entries:
+        pytest.skip("no process enumeration available on this host")
+    assert os.getpid() in {pid for pid, _ in entries}

tests/test_smoke.py

@@ -217,16 +217,23 @@ def test_icon_source_requires_real_allowed_file_boundary(tmp_path):
 
 
 def test_ollama_stream_propagates_transport_errors(monkeypatch):
+    """A failing stream must surface, not be swallowed into an empty reply —
+    and it must carry Ollama's own explanation, since that is the only part the
+    user can act on. The response here is a real httpx.Response because the
+    error path reads the body, which a stubbed raise_for_status never exercised."""
+    import httpx
+
     class FailingResponse:
         async def __aenter__(self):
-            return self
+            return httpx.Response(
+                503,
+                json={"error": "Ollama unavailable"},
+                request=httpx.Request("POST", "http://127.0.0.1:11434/api/chat"),
+            )
 
         async def __aexit__(self, *args):
             return False
 
-        def raise_for_status(self):
-            raise RuntimeError("Ollama unavailable")
-
     class FailingClient:
         def __init__(self, **kwargs):
             pass
@@ -246,7 +253,7 @@ def test_ollama_stream_propagates_transport_errors(monkeypatch):
         async for _ in OllamaManager()._chat_stream([], "model", 0):
             pass
 
-    with pytest.raises(RuntimeError, match="Ollama unavailable"):
+    with pytest.raises(httpx.HTTPStatusError, match="Ollama unavailable"):
         import asyncio
         asyncio.run(consume())
 
@@ -264,13 +271,17 @@ def test_sync_compare_detects_direction(tmp_path):
     """The guard that stops a stale box from overwriting the other's chats.
     Both backup and restore refuse to run when this says the wrong thing, so a
     silent break here loses conversation history."""
+    import contextlib
     import sqlite3 as sq
     sync = _load_sync()
     db, dump = tmp_path / "memory.db", tmp_path / "memory.db.sql"
 
     def write(rows):
         db.unlink(missing_ok=True)
-        with sq.connect(db) as conn:
+        # closing() then the connection itself: sqlite3's own context manager
+        # commits but never closes, and Windows refuses to unlink a file that
+        # still has an open handle.
+        with contextlib.closing(sq.connect(db)) as conn, conn:
             # updated_at REAL, matching the production schema in store.py. A TEXT
             # column here hid a real TypeError for months: the comparison in
             # _extra() ran str-vs-str in the test and str-vs-float in the field.
@@ -547,3 +558,94 @@ def test_preview_iframe_cannot_navigate_to_a_network_url():
     assert "encodeURIComponent(doc)" in markdown
     assert "src={frameUrl}" in markdown
     assert "srcDoc={doc}" not in markdown
+
+
+def test_ollama_failures_surface_the_reason_not_just_the_status():
+    """Ollama answers every failure with {"error": "..."} and httpx's default
+    message throws it away. A user hitting a retired cloud model saw
+    "Client error '410 Gone' for url ..." when the body said exactly why."""
+    import asyncio
+    import httpx
+    import pytest
+    from synapse.ollama_manager import _raise_for_ollama
+
+    req = httpx.Request("POST", "http://127.0.0.1:11434/api/chat")
+
+    retired = httpx.Response(410, json={"error": "glm-4.6 was retired at 2026-06-16"}, request=req)
+    with pytest.raises(httpx.HTTPStatusError) as ei:
+        asyncio.run(_raise_for_ollama(retired))
+    assert "retired" in str(ei.value) and "410" in str(ei.value)
+
+    # The common case, not just the exotic one.
+    missing = httpx.Response(404, json={"error": "model 'foo' not found"}, request=req)
+    with pytest.raises(httpx.HTTPStatusError) as ei:
+        asyncio.run(_raise_for_ollama(missing))
+    assert "model 'foo' not found" in str(ei.value)
+
+    # No usable body -> keep httpx's own wording rather than inventing one.
+    blank = httpx.Response(500, content=b"", request=req)
+    with pytest.raises(httpx.HTTPStatusError):
+        asyncio.run(_raise_for_ollama(blank))
+
+    # Success stays silent.
+    asyncio.run(_raise_for_ollama(httpx.Response(200, json={"ok": True}, request=req)))
+
+
+def test_ollama_host_is_normalized_for_clients_but_not_for_binding():
+    """OLLAMA_HOST is Ollama's *bind* variable, and `OLLAMA_HOST=0.0.0.0:11434`
+    is the normal way to expose it on a LAN. Used verbatim as a client base URL
+    it is unusable — no scheme, and 0.0.0.0 is not a destination — and every
+    request failed into list_models()'s bare `except: return []`, so the model
+    picker just went empty with no error anywhere."""
+    from synapse.nexus_config import _normalize_ollama_host as norm
+
+    assert norm("0.0.0.0:11434") == "http://127.0.0.1:11434"
+    assert norm("[::]:11434") == "http://127.0.0.1:11434"
+    assert norm("http://0.0.0.0:11434/") == "http://127.0.0.1:11434"
+    assert norm("127.0.0.1:11434") == "http://127.0.0.1:11434"   # scheme supplied
+    assert norm("") == "http://127.0.0.1:11434"
+    # A real remote is deliberate — leave it alone.
+    assert norm("https://ollama.lan:11434") == "https://ollama.lan:11434"
+    assert norm("192.168.1.50:11434") == "http://192.168.1.50:11434"
+
+
+def test_spawned_serve_keeps_the_users_bind_address(monkeypatch):
+    """Normalizing for the client must not quietly un-expose a server we spawn."""
+    import importlib
+    from synapse import nexus_config
+    monkeypatch.setenv("OLLAMA_HOST", "0.0.0.0:11434")
+    reloaded = importlib.reload(nexus_config)
+    try:
+        assert reloaded.settings.ollama_bind == "0.0.0.0:11434"      # listens everywhere
+        assert reloaded.settings.ollama_host == "http://127.0.0.1:11434"  # we connect here
+    finally:
+        monkeypatch.delenv("OLLAMA_HOST", raising=False)
+        importlib.reload(nexus_config)
+
+
+def test_think_blocks_never_reach_the_reply():
+    """A reasoning model emits <think> inline in `content` even with think off,
+    and the whole internal monologue reached the chat window — including the
+    literal closing tags. Streaming has to cope with a tag split across chunks,
+    and with the shape actually observed: a stray </think> and no opening."""
+    from synapse.ollama_manager import ThinkStripper, strip_think
+
+    def stream(chunks):
+        s = ThinkStripper()
+        return "".join(s.feed(c) for c in chunks) + s.flush()
+
+    assert stream(["hello ", "<think>", "noise", "</think>", "world"]) == "hello world"
+    # tag split across chunk boundaries
+    assert stream(["a<th", "ink>x</thi", "nk>b"]) == "ab"
+    # never closed -> it was all reasoning
+    assert stream(["keep", "<think>", "runs off the end"]) == "keep"
+    # stray close, no open: at minimum the tag itself must not be shown
+    assert "</think>" not in stream(["reasoning...", "</think>", "the answer"])
+    # ordinary text is untouched, including angle brackets
+    assert stream(["a < b ", "and c > d"]) == "a < b and c > d"
+
+    # With the complete message the stray-close case can be handled properly:
+    # everything before it was reasoning.
+    assert strip_think("rambling\n</think>\nThe answer") == "The answer"
+    assert strip_think("a<think>b</think>c") == "ac"
+    assert strip_think("no tags here") == "no tags here"

tests/test_tools.py

@@ -93,6 +93,52 @@ def test_ask_policy_skips_on_deny(monkeypatch):
     assert any(m["role"] == "tool" and "declined" in m["content"] for m in messages)
 
 
+class _ContentJsonActionManager:
+    """Small-model shape: dumps the action call into `content`, no native
+    `tool_calls` field — the lower-confidence path the "allow" bypass must
+    not trust."""
+    def __init__(self):
+        self.n = 0
+
+    async def chat(self, **_):
+        self.n += 1
+        if self.n == 1:
+            return {"role": "assistant",
+                    "content": json.dumps({"name": "remember", "arguments": {"text": "x"}})}
+        return {"role": "assistant", "content": "done"}
+
+
+def test_content_json_action_call_asks_even_under_allow_policy(monkeypatch):
+    """A call recovered by guessing at `content` is weaker evidence than the
+    API's own structured tool_calls field — a model can land on JSON shaped
+    like a call while only meaning to describe one. It must still go through
+    approval even when action_tool_policy is "allow", the default that lets a
+    *native* tool_calls field run unattended."""
+    from synapse import chat as chatmod
+
+    async def fake_dispatch(name, args):
+        return "saved-ok"
+    monkeypatch.setattr(tools, "dispatch", fake_dispatch)
+
+    async def run():
+        messages = [{"role": "user", "content": "remember x"}]
+        schemas = tools.schemas_for(["remember"])
+        gen = chatmod._run_tool_loop(_ContentJsonActionManager(), messages, "m", schemas, None, None,
+                                     conversation_id="conv", policy="allow")
+        statuses = []
+        async for s in gen:
+            statuses.append(s)
+            if s.startswith("__approve__"):
+                w = chatmod.pending_approvals["conv"]
+                w["decisions"] = {"remember": True}
+                w["event"].set()
+        return statuses
+
+    statuses = asyncio.run(run())
+    assert any(s.startswith("__approve__") for s in statuses)
+    assert "__status__remember" in statuses
+
+
 def test_action_tools_gated_by_consent():
     allow = ["search_memory", "web_search", "remember", "fetch_url"]
     on = [s["function"]["name"] for s in tools.schemas_for(allow, allow_actions=True)]

tests/test_tui.py

@@ -0,0 +1,368 @@
+"""TUI helpers and headless App.run_test coverage."""
+from __future__ import annotations
+
+import asyncio
+import threading
+
+import pytest
+from rich.text import Text
+
+from nexusos_cli.tui_app import (
+    _compact_status,
+    _deny_tool_request,
+    _escape,
+    _status_line,
+    format_assistant_line,
+    format_user_line,
+)
+
+
+class _ApprovalResponse:
+    def raise_for_status(self):
+        return None
+
+
+class _ApprovalClient:
+    calls = []
+
+    def __init__(self, **kwargs):
+        self.kwargs = kwargs
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return None
+
+    def post(self, path, *, json):
+        self.calls.append((path, json, self.kwargs))
+        return _ApprovalResponse()
+
+
+def test_status_line_mentions_services():
+    snap = {
+        "version": "1.0.0",
+        "services": {
+            "backend": {"running": True},
+            "memory": {"running": False},
+            "provider": {"reachable": True},
+        },
+        "api": {"online": True, "action_tool_policy": "ask"},
+        "host": {"cpu_pct": 10.0},
+        "toolchains": [{"lang": "python", "ready": True}],
+    }
+    line = _status_line(snap)
+    assert "backend=UP" in line
+    assert "memory=DOWN" in line
+    assert "provider=UP" in line
+    assert "tools=ask" in line
+    assert "run=python" in line
+
+
+def test_compact_status_handles_api_down():
+    snap = {
+        "host": {},
+        "api": {"online": False},
+        "recent_tools": [],
+    }
+    assert "api DOWN" in _compact_status(snap)
+
+
+def test_escape_preserves_code_brackets_in_display():
+    raw = "idx = arr[i] and rng = [a-z]+"
+    plain = Text.from_markup(format_assistant_line(raw)).plain
+    assert "arr[i]" in plain
+    assert "[a-z]+" in plain
+    # Unescaped markup would drop the bracket contents.
+    assert plain != "nexus> idx = arr and rng = +"
+
+
+def test_closing_tag_in_model_output_does_not_raise():
+    raw = "close with [/] please"
+    plain = Text.from_markup(format_assistant_line(raw)).plain
+    assert "[/]" in plain
+
+
+def test_user_line_escapes_markup():
+    plain = Text.from_markup(format_user_line("use [bold] please")).plain
+    assert "[bold]" in plain
+
+
+def test_finish_stream_markup_does_not_wedge_busy():
+    """A stray '[/]' used to raise before _busy=False and lock the TUI forever."""
+    pytest.importorskip("textual")
+    from nexusos_cli.tui_app import NexusTUI
+
+    app = NexusTUI.build_app(api_url="http://127.0.0.1:9")
+
+    async def _run():
+        async with app.run_test():
+            app._busy = True
+            app._finish_stream("see [/] and arr[i]", app.history)
+            assert app._busy is False
+            assert app.history[-1]["content"] == "see [/] and arr[i]"
+
+    asyncio.run(_run())
+
+
+def test_stream_error_remains_visible_after_finish():
+    pytest.importorskip("textual")
+    from nexusos_cli.tui_app import NexusTUI
+
+    app = NexusTUI.build_app(api_url="http://127.0.0.1:9")
+
+    async def _run():
+        async with app.run_test():
+            app._busy = True
+            app._show_error("[red]Backend not reachable[/]")
+            app._finish_stream("", app.history)
+            log = app.query_one("#log")
+            assert any("Backend not reachable" in line.text for line in log.lines)
+            assert app._busy is False
+
+    asyncio.run(_run())
+
+
+@pytest.mark.parametrize("key", ["ctrl+c", "ctrl+d"])
+def test_priority_exit_bindings_reach_app_while_prompt_is_focused(key):
+    pytest.importorskip("textual")
+    from nexusos_cli.tui_app import NexusTUI
+
+    app = NexusTUI.build_app(api_url="http://127.0.0.1:9")
+
+    async def _run():
+        async with app.run_test() as pilot:
+            assert app.is_running
+            await pilot.press(key)
+            await pilot.pause()
+            assert not app.is_running
+
+    asyncio.run(_run())
+
+
+def test_tool_request_is_denied_with_stream_token():
+    _ApprovalClient.calls.clear()
+    names = _deny_tool_request(
+        api_url="http://localhost:8000",
+        conversation_id="conversation-1",
+        payload='{"token":"secret","actions":[{"name":"run_snippet"}]}',
+        client_factory=_ApprovalClient,
+    )
+
+    assert names == ["run_snippet"]
+    path, body, client_kwargs = _ApprovalClient.calls[-1]
+    assert path == "/chat/approve"
+    assert body == {
+        "conversation_id": "conversation-1",
+        "token": "secret",
+        "decisions": {"run_snippet": False},
+    }
+    assert client_kwargs["base_url"] == "http://localhost:8000"
+
+
+def test_inflight_tool_denial_uses_original_conversation_id(monkeypatch):
+    pytest.importorskip("textual")
+    import nexusos_cli.tui_app as tui_app
+
+    stream_started = threading.Event()
+    release_stream = threading.Event()
+    denied_for = []
+
+    class _StreamResponse:
+        status_code = 200
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        async def aiter_lines(self):
+            stream_started.set()
+            await asyncio.to_thread(release_stream.wait, 2)
+            yield "event: tool_request"
+            yield 'data: {"token":"secret","actions":[{"name":"run_snippet"}]}'
+            yield ""
+            yield "event: done"
+            yield "data: {}"
+
+    class _StreamClient:
+        def __init__(self, **kwargs):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        def stream(self, *args, **kwargs):
+            return _StreamResponse()
+
+    def _capture_denial(*, conversation_id, **kwargs):
+        denied_for.append(conversation_id)
+        return ["run_snippet"]
+
+    monkeypatch.setattr(tui_app.httpx, "AsyncClient", _StreamClient)
+    monkeypatch.setattr(tui_app, "_deny_tool_request", _capture_denial)
+    app = tui_app.NexusTUI.build_app(api_url="http://127.0.0.1:9")
+
+    async def _run():
+        async with app.run_test():
+            app._start_chat("run it")
+            assert await asyncio.to_thread(stream_started.wait, 2)
+            original_id = app.conversation_id
+            app._handle_slash("/new")
+            assert app.conversation_id is None
+            release_stream.set()
+            for _ in range(200):
+                if not app._busy:
+                    break
+                await asyncio.sleep(0.01)
+            assert app._busy is False
+            assert denied_for == [original_id]
+
+    asyncio.run(_run())
+
+
+def test_new_mid_stream_does_not_leak_reply_into_next_conversation(monkeypatch):
+    """A stream still in flight when /new resets self.history must keep
+    appending its reply to the conversation it was actually answering, not
+    whatever self.history now points at - otherwise the old reply's text
+    silently rides along in the next request's history payload."""
+    pytest.importorskip("textual")
+    import nexusos_cli.tui_app as tui_app
+
+    stream_started = threading.Event()
+    release_stream = threading.Event()
+
+    class _StreamResponse:
+        status_code = 200
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        async def aiter_lines(self):
+            stream_started.set()
+            await asyncio.to_thread(release_stream.wait, 2)
+            yield 'data: "the old reply"'
+            yield ""
+            yield "event: done"
+            yield "data: {}"
+
+    class _StreamClient:
+        def __init__(self, **kwargs):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        def stream(self, *args, **kwargs):
+            return _StreamResponse()
+
+    monkeypatch.setattr(tui_app.httpx, "AsyncClient", _StreamClient)
+    app = tui_app.NexusTUI.build_app(api_url="http://127.0.0.1:9")
+
+    async def _run():
+        async with app.run_test():
+            app._start_chat("first question")
+            assert await asyncio.to_thread(stream_started.wait, 2)
+            old_history = app.history
+            app._handle_slash("/new")
+            assert app.history is not old_history
+            release_stream.set()
+            for _ in range(200):
+                if not app._busy:
+                    break
+                await asyncio.sleep(0.01)
+            assert app._busy is False
+            # The reply landed on the abandoned conversation's own list...
+            assert any(m["content"] == "the old reply" for m in old_history)
+            # ...never on the fresh one /new started.
+            assert app.history == []
+
+    asyncio.run(_run())
+
+
+def test_interrupt_cancels_silent_stream_and_accepts_next_message(monkeypatch):
+    pytest.importorskip("textual")
+    import nexusos_cli.tui_app as tui_app
+
+    first_stream_started = threading.Event()
+
+    class _StreamResponse:
+        status_code = 200
+
+        def __init__(self, call_number):
+            self.call_number = call_number
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        async def aiter_lines(self):
+            if self.call_number == 1:
+                first_stream_started.set()
+                await asyncio.Event().wait()
+            yield "data: \"READY\""
+            yield ""
+            yield "event: done"
+            yield "data: {}"
+
+    class _StreamClient:
+        calls = 0
+
+        def __init__(self, **kwargs):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        def stream(self, *args, **kwargs):
+            type(self).calls += 1
+            return _StreamResponse(type(self).calls)
+
+    monkeypatch.setattr(tui_app.httpx, "AsyncClient", _StreamClient)
+    app = tui_app.NexusTUI.build_app(api_url="http://127.0.0.1:9")
+
+    async def _wait_until_idle():
+        for _ in range(100):
+            if not app._busy:
+                return
+            await asyncio.sleep(0.01)
+        pytest.fail("stream did not become idle within one second")
+
+    async def _run():
+        async with app.run_test() as pilot:
+            app._start_chat("first")
+            assert await asyncio.to_thread(first_stream_started.wait, 2)
+            await pilot.press("ctrl+c")
+            await _wait_until_idle()
+
+            log = app.query_one("#log")
+            assert any("interrupt requested" in line.text for line in log.lines)
+            assert not any("ReadTimeout" in line.text for line in log.lines)
+
+            app._start_chat("second")
+            await _wait_until_idle()
+            assert app.history[-1] == {
+                "role": "assistant",
+                "content": "READY",
+            }
+
+    asyncio.run(_run())
+
+
+def test_escape_round_trip_helper():
+    assert "[" in _escape("x[y]") or "\\[" in _escape("x[y]")