@tiens.nguyen/gu-cli 1.0.891 → 1.0.893

package/README.md

@@ -1,17 +1,17 @@
 <h1 align="center">gu — the coding agent for your own models</h1>
 
 <p align="center">
-  <strong>A coding agent in your terminal that runs on Ollama, MLX or any OpenAI-compatible API.</strong><br>
-  It reads your repo, makes the change, runs the tests and shows you what it did. Your code stays in your folder.<br>
-  <strong>Free for 30 days. No account, no sign-in, no card.</strong>
+  <strong>A coding agent in your terminal that runs on Ollama or any OpenAI-compatible API.</strong><br>
+  It reads your repo, makes the change, runs the tests and shows you what it did.<br>
+  <strong>Free installs run entirely on your machine. Free for 30 days: no account, no sign-in, no card.</strong>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@tiens.nguyen/gu-cli"><img alt="npm" src="https://img.shields.io/npm/v/@tiens.nguyen/gu-cli?color=6366f1&label=npm"></a>
   <a href="https://www.npmjs.com/package/@tiens.nguyen/gu-cli"><img alt="downloads" src="https://img.shields.io/npm/dm/@tiens.nguyen/gu-cli?color=6366f1"></a>
-  <img alt="node" src="https://img.shields.io/node/v/@tiens.nguyen/gu-cli?color=6366f1">
+  <img alt="node 20.19+" src="https://img.shields.io/badge/node-20.19%2B-6366f1">
   <img alt="platforms" src="https://img.shields.io/badge/macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-supported-6366f1">
-  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/@tiens.nguyen/gu-cli?color=6366f1"></a>
+  <img alt="license MIT" src="https://img.shields.io/badge/license-MIT-6366f1">
 </p>
 
 <p align="center">
@@ -37,18 +37,21 @@ gu
 ```
 
 **Free to start, no account needed.** The first run creates a free 30-day token for this
-computer automatically. Press Enter to use it. It also asks how this machine runs and which model
-provider to use. Then type what you want done.
+computer. Press Enter to use it, pick a model provider, then type what you want done.
+
+A free install is **private**: gu's API and its database (MongoDB) run on this computer, next to
+your code. The first run shows what it will install and asks before installing anything.
+Needs **Node.js 20.19+**.
 
 > **`gu: command not found`?** Run `npx @tiens.nguyen/gu-cli fix-path`. See [Troubleshooting](#troubleshooting).
 
 ## Why gu
 
-- **Your models, your choice.** Run [Ollama](https://ollama.com) or MLX on your own machine or a GPU
-  box on your network, or bring any OpenAI-compatible provider (OpenAI, DeepSeek, OpenRouter…). Use
+- **Your models, your choice.** Run [Ollama](https://ollama.com) on your own machine or a GPU box
+  on your network, or bring any OpenAI-compatible provider (OpenAI, DeepSeek, OpenRouter…). Use
   one model to plan and another to code; switch any time with `/model`.
-- **Private by default.** Logs hold no prompts, code or keys unless you run `gu --log`. Need
-  everything in-house? Private mode runs the API and database on your own servers.
+- **Private by default.** A free install keeps the agent, its API and its database on your
+  computer. Logs hold no prompts, code or keys unless you run `gu --log`.
 - **It proves it works.** gu runs the build and the tests and fixes what fails. For web pages, the
   `browser` tool drives a real Chrome and checks the result before gu says it is done.
 - **It stays in the repo.** Every edit is a file you can read, diff and revert; `/undo` puts back
@@ -65,16 +68,14 @@ provider to use. Then type what you want done.
 cloud, work on remote Linux boxes over SSH, or want a coding agent that costs $4 a month instead
 of a model subscription.
 
-**Probably not if** you want the strongest frontier model with zero setup and don't mind where your
-code goes: the model vendors' own agents are simpler for that. gu can still use those models
-through an OpenAI-compatible API, but its strength is everything else.
+**Want a frontier model?** gu runs those too, through any OpenAI-compatible API, and keeps
+everything else: the edits in your repo, the tests, the browser check and `/undo`.
 
 ## Quick start
 
 1. **Start gu.** Run `gu` in a project folder. Your free 30-day token is created on the spot:
    no sign-up, no browser, no card.
 2. **Check your models.** `gu doctor` sets up and tests the models on this machine.
-   (`gu doctor --client` installs only the agent's dependencies, when the models run elsewhere.)
 3. **Ask.** Type what you want done. Conversations are saved per folder and resumed next time;
    `/new` starts a fresh one.
 
@@ -86,9 +87,10 @@ gu uses up to three models, each with its own command:
 | --- | --- | --- |
 | `/model` | **coding**: writes the code | this session (`/quick-models` keeps 2 to flip with ← / →) |
 | `/agent-model` | **agent**: talks to you and plans | this machine |
-| `/embed-model` | **embedding**: RAG (`nomic-embed-text`, `qwen3-embedding`), local or remote | this machine; re-indexes what was indexed |
+| `/embed-model` | **embedding**: RAG (`nomic-embed-text`, `qwen3-embedding`), local or remote | this machine |
 
-Run `/doctor` any time to check that each one answers.
+Run `/doctor` any time to check that each one answers. Coding works best with a strong model:
+small local models often fail at multi-step changes.
 
 ## Using gu
 
@@ -102,10 +104,23 @@ gu [-v|--verbose] [--log] [--color] [--name <text>] [--license <pro token>]
 | `--log` | log this run in detail to `~/.gonext/worker.log` (default: starts, stops and errors only) |
 | `--color` | colour the live thought and the thinking spinner |
 | `--name <text>` | show `<text>` instead of the gu logo in the banner (this run only) |
-| `--license <token>` | choose a Pro licence on first install |
+| `--license <token>` | use a Pro licence on first install |
 
 Ctrl-C stops the running turn. Type `/` at the prompt to see every command; Tab completes.
 
+**The commands you'll use most**
+
+| Command | What it does |
+| --- | --- |
+| `/model` | switch the coding model |
+| `/new` | start a new conversation in this folder |
+| `/undo` | put back the files the last stopped turn changed (asks first) |
+| `/test-auto` | for this folder: verify and fix until the tests pass |
+| `/browser` | let the agent check web pages in a real Chrome |
+| `/mcp` | add MCP servers, and choose which tools run without asking |
+| `/doctor` | check that every model answers |
+| `/support` | send a request with gu's logs attached (secrets masked; shows you first) |
+
 <details>
 <summary><strong>All slash commands</strong></summary>
 
@@ -117,28 +132,24 @@ Ctrl-C stops the running turn. Type `/` at the prompt to see every command; Tab
 | `/new` | start a new conversation in this folder (the old one is archived) |
 | `/undo [runId]` | put back the files the last stopped turn changed, from its backups (asks first) |
 | `/test-auto` | toggle auto-test for this folder: verify and fix until it passes |
-| `/browser [allow\|forget\|install\|cleanup]` | the agent's web browser, through the gu Chrome extension or gu's own Chrome window ([guide](browser-extension/README.md)) |
+| `/browser [allow\|forget\|install\|cleanup]` | the agent's web browser, through the gu Chrome extension or gu's own Chrome window |
 | `/shells` | long commands the agent left running in the background: status, output, stop one |
-| `/rag` | where this folder's RAG index lives: local, cloud or both |
+| `/rag` | where this folder's RAG index lives |
 | `/tokens` | break down the last prompt sent to the coding model, including how much was RAG |
 | `/prices [update]` | price tables, and what the last turn and this session cost |
 | `/budget` | your API provider budgets and balances (Pro) |
 | `/mcp [list\|tools\|add\|remove\|enable\|disable\|approve\|allow\|disallow\|reconnect]` | MCP servers, and which of their tools run without asking |
 | `/hooks [list\|approve\|unapprove]` | commands gu runs on `onStart`, `onAsk`, `onToolDone`, `onTurnEnd` |
 | `/switch-skill [claude\|gu]` | use Claude Code's (`.claude`) or gu's (`.gonext`) skills, MCP servers and hooks in this folder |
-| `/skill-pack <name> [--out <file>] [--runtime <dir>]` | pack a skill with its MCP servers, hooks and code into one zip for another machine (no venvs, databases or secrets) |
-| `/skill-install <zip\|folder> [--gu] [--claude] [--dry-run]` | install a packed skill for gu and Claude Code; without gu: `node <name>/install.mjs` |
-| `/resume` | carry on the last unfinished task in this folder, Claude Code's or gu's: shows its plan, last command and next step, then asks (needs the memory skill) |
-| `/skills-copy-to-claude [--dry-run] [name…]` | copy gu's skills into Claude Code's folders |
+| `/skill-pack <name>`, `/skill-install <zip\|folder>` | pack a skill with its MCP servers and hooks into one zip, and install it on another machine (no secrets) |
+| `/resume` | carry on the last unfinished task in this folder, Claude Code's or gu's |
 | `/proxy [show\|set\|on\|off\|clear\|test]` | route model calls through an HTTP proxy (local calls go direct) |
 | `/s3 [test]` | use your own S3 bucket for the RAG index and generated files |
-| `/server` | pick a deployment server (host/user) for this session |
-| `/host-mode` | undo client mode: run agent turns on this machine again |
 | `/save-settings`, `/load-settings` | move providers, models and key *names* (no secrets) to another machine |
 | `/save-preset`, `/open-presets`, `/use-presets` | your whole setup, keys included, to copy, edit and apply (backs up first) |
-| `/clear-logs` | show what logs, RAG indexes and old API versions take on disk, then ask what to clear |
-| `/voucher CODE` | use a voucher code: adds free days to this computer's trial or your free account |
-| `/support` | send the support team a request with gu's logs attached (secrets masked; shows what goes first) |
+| `/clear-logs` | show what logs and indexes take on disk, then ask what to clear |
+| `/voucher CODE` | add free days to this computer's trial or your free account |
+| `/support` | send the support team a request with gu's logs attached |
 | `/help`, `/exit` | list commands / quit |
 
 Each skill in `~/.gonext/skills/<name>/SKILL.md` (or the folder's `.gonext/skills`) is a slash command too.
@@ -149,32 +160,25 @@ Each skill in `~/.gonext/skills/<name>/SKILL.md` (or the folder's `.gonext/skill
 <summary><strong>Shell commands</strong></summary>
 
 ```
-gu status                      worker status and the running model servers
-gu start | stop | restart      the background worker (stop --models: model servers too)
-gu logs [--lines N] [-f]       tail the worker log; gu logs <port|pid|chat|embed> for a model server
-gu doctor [--client]           set up and check models on this machine
-gu rag [plan [path] | --test]  test the embedder, list knowledge bases, estimate index time
-gu api <start|stop|restart|status|upgrade>   the local API (private machines)
+gu status                      is gu running, and which model servers
+gu start | stop | restart      the background worker
+gu logs [--lines N] [-f]       follow gu's log
+gu doctor                      set up and check models on this machine
+gu rag [plan [path] | --test]  test the embedder, estimate index time
 gu workspace revert [runId]    undo an agent run's file edits from its backups
 gu support                     send a support request with masked logs
-gu test-proxy                  check model calls through a proxy
-gu mongo migrate-from-docker   macOS: move a Docker MongoDB to Homebrew
-gu clear [--scratch|--keep-history] [--yes]   back to a fresh machine (asks first)
+gu clear [--yes]               back to a fresh machine (asks first)
 gu fix-path | fix-powershell   repair PATH / remove PowerShell's `gu` alias
 ```
 
-`gu-cli` takes the same commands, plus `login [--api-base <url>]`, `set <workerKey>`,
-`token [<token>]`, `ws-ping-test` and `simulate-chat [text…]`.
-
 </details>
 
 ## Where gu keeps things
 
 | Path | Contents |
 | --- | --- |
-| `~/.gonext/worker.env` | sign-in: worker key and API address |
 | `~/.gonext/sessions/` | conversation history per folder (`archive/` holds old ones) |
-| `~/.gonext/worker.log`, `~/.gonext/local-api.log` | logs |
+| `~/.gonext/worker.log` | log |
 | `~/.gonext/mcp.json` | MCP servers and their allow rules |
 | `~/.gonext/skills/`, `<folder>/.gonext/skills/` | skills: everywhere / this folder only |
 
@@ -182,57 +186,35 @@ gu fix-path | fix-powershell   repair PATH / remove PowerShell's `gu` alias
 
 | | How long | What you need |
 | --- | --- | --- |
-| **Free trial** | 30 days, starts on the first run | nothing: the token is created for you |
+| **Free trial** | 30 days, from the first run | nothing: the token is created for you |
 | **Free plan** | 3 more months on that computer | a free account at [gucli.com](https://gucli.com) |
-| **Pro** | while subscribed: **$4 a month** (110.000 ₫) + VAT, or $40 a year | the hosted agent and coder (no model server to run), up to 5 computers, provider budgets |
+| **Pro** | **$4 a month** or **$40 a year** (+ VAT where it applies) | hosted models (no model server to run), up to 5 computers, provider budgets |
+
+On Pro, the hosted models and the hosted API run on gu's servers, so the prompts and code you
+send through them go there. A free install keeps everything on your computer.
 
 Got a **voucher code**? Type `/voucher CODE` in gu (or enter it on your
-[account page](https://gucli.com/account)) for extra free days on top.
+[account page](https://gucli.com/account)) for extra free days.
 
 Free time belongs to the computer: reinstalling doesn't restart it. Already have a token? Paste
-it at the first-run question instead, or later with `gu-cli token <token>`. Current prices: [gucli.com/pricing](https://gucli.com/pricing).
+it at the first-run question. Current prices: [gucli.com/pricing](https://gucli.com/pricing).
 
 ## Troubleshooting
 
 **`gu: command not found` after install.** npm 11 skips install scripts it wasn't told to allow,
 so the step that adds npm's bin folder to your PATH may not have run. Run
 `npx @tiens.nguyen/gu-cli fix-path`. It also finds what an old install left behind (broken links,
-a second gu from another npm, a PATH line pinned to an old Homebrew folder) and asks before
-fixing each one. `--check` only reports.
+a second gu from another npm, a stale PATH line) and asks before fixing each one. `--check` only reports.
 
 **Windows: `gu` runs `Get-Unique`.** PowerShell has a built-in `gu` alias. Run `gu-cli fix-powershell`.
 
-**Node version.** Node.js 18+ runs the CLI. A private machine (API and database on this
-computer) needs **Node.js 20.19+**.
+**Node version.** gu needs **Node.js 20.19+** (a Pro install using only hosted models runs on 18+).
 
 **A change in a model or setting seems ignored.** `gu doctor` shows the model and URL actually in use.
 
-**Still stuck?** Run `gu support` (or `/support` in gu, or click **? support** in the footer). It
-sends the team your request with gu's logs attached, secrets masked, and shows you what goes
-before sending.
-
-<details>
-<summary><strong>Advanced: worker jobs and environment variables</strong></summary>
-
-The background worker also runs jobs queued from the [web app](https://gucli.com) on this machine:
-
-- **Agent chat**: choosing **Agent** in the web app runs a
-  [smolagents](https://github.com/huggingface/smolagents) agent on your local model
-  (`pip install smolagents certifi`). Cloud models are not allowed here; pick a local MLX or Ollama model.
-- **API checks**: the worker makes the HTTP request itself, measures status, latency and body,
-  and a local model writes a one-line summary.
-
-| Variable | Meaning |
-| --- | --- |
-| `GONEXT_API_BASE`, `GONEXT_WORKER_KEY` | API address and worker key (normally from `~/.gonext/worker.env`) |
-| `GONEXT_PROBE_PYTHON` | Python for agent scripts (default: `GONEXT_MLX_LM_PYTHON` or `python3`) |
-| `GONEXT_MLX_LM_PYTHON` | Python for the MLX probe (default `python3`) |
-| `GONEXT_OCR_MODEL_PATH` | local GLM-OCR directory (default `~/mlx-models/GLM-OCR-bf16`) |
-| `GONEXT_OCR_DEBUG=1` | print raw OCR output |
-| `GONEXT_SIMULATE_TEXT` | default reply for `simulate-chat` |
-
-</details>
+**Still stuck?** Run `gu support` (or `/support` in gu). It sends the team your request with gu's
+logs attached, secrets masked, and shows you what goes before sending.
 
 ## License
 
-[MIT](./LICENSE) © Tien Nguyen Song
+MIT © Tien Nguyen Song

package/agent-deps-preflight.mjs

@@ -0,0 +1,96 @@
+/**
+ * THE AGENT'S PYTHON PACKAGES, BEFORE THE TERMINAL EXISTS (GH #308).
+ *
+ * `gu` used to find out that smolagents + openai were missing only once its full-screen terminal was up (raw
+ * keyboard, pinned input bar, background worker), and ran pip from inside it. On a brand-new Windows 11 machine
+ * that never came back: the pip child was started and gu's whole event loop stopped — no output, no timeout, a
+ * fifteen-minute hang — while the very same install, run in a plain process, finished in under a minute.
+ *
+ * So the install happens FIRST, in a plain process: no readline, no raw mode, no worker, nothing else running.
+ * One question (default yes) with an ordinary line prompt, then the installer with its own heartbeat, log file
+ * and hard timeout. A failure here never blocks the terminal — it says what to run and carries on.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DECLINED_FILE = join(homedir(), ".gonext", "agent-deps-declined");
+
+/** Is this start one that should check? Interactive terminals only, and not when a test or script opts out. Pure. */
+export function shouldPreflight({ env = process.env, stdinTTY = Boolean(process.stdin.isTTY), stdoutTTY = Boolean(process.stdout.isTTY), declined = existsSync(DECLINED_FILE) } = {}) {
+  if (!stdinTTY || !stdoutTTY) return false;
+  if (env.GU_NO_AGENT_DEPS_PROMPT === "1") return false;
+  if (declined) return false;
+  return true;
+}
+
+/** "y"/"" → true, anything else false. Pure. */
+export function yesAnswer(typed) {
+  const t = String(typed ?? "").trim().toLowerCase();
+  return t === "" || t === "y" || t === "yes";
+}
+
+/** A plain one-line question: its own readline, closed before the real terminal creates its own. */
+export async function askLine(question, { input = process.stdin, output = process.stdout } = {}) {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input, output, terminal: false });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+    input.pause?.();
+  }
+}
+
+/**
+ * → "present" | "installed" | "declined" | "failed" | "skipped". Every dependency is injected, so the whole decision
+ * is testable without Python, a terminal or a network.
+ */
+export async function agentDepsPreflight({
+  shouldRun = shouldPreflight(),
+  hasLibs,
+  install,
+  ask = askLine,
+  markDeclined = () => {},
+  log = (s) => console.log(s),
+} = {}) {
+  if (!shouldRun) return "skipped";
+  let present = false;
+  try {
+    present = await hasLibs();
+  } catch {
+    present = false;
+  }
+  if (present) return "present";
+  log("\ngu: first start — the agent framework (smolagents + openai) isn't installed here, and every turn needs it.");
+  log("  It is a small pip install into gu's own Python environment; no models, nothing system-wide.");
+  const answer = await ask("  Install it now? [Y/n]: ");
+  if (!yesAnswer(answer)) {
+    markDeclined();
+    log("  Skipped — install later with `gu-cli deps` (gu will not ask again at start).");
+    return "declined";
+  }
+  try {
+    const out = await install();
+    const ok = out && (out.agentLibs === "installed" || out.agentLibs === "present");
+    if (!ok) {
+      log("  ⚠ the agent framework did not install — run `gu-cli deps` to see why. Starting gu anyway.");
+      return "failed";
+    }
+    log("  ✓ the agent framework is installed.\n");
+    return "installed";
+  } catch (e) {
+    log(`  ⚠ ${e instanceof Error ? e.message : e}\n  Starting gu anyway — run \`gu-cli deps\` to retry.`);
+    return "failed";
+  }
+}
+
+/** Remember "no" so the question is not asked at every start. */
+export function markDeclinedOnDisk() {
+  try {
+    mkdirSync(dirname(DECLINED_FILE), { recursive: true });
+    writeFileSync(DECLINED_FILE, new Date().toISOString() + "\n");
+  } catch {
+    /* asking again next time is the safe failure */
+  }
+}

package/gu-cli.mjs

@@ -126,6 +126,7 @@ Usage:
   gu-cli stop [--models]                   # stop the daemon (--models: the model servers too)
   gu-cli logs [--lines N] [-f]             # tail the background daemon log
   gu-cli logs <port|pid|chat|embed> [-f]   # tail a MODEL server's log (e.g. logs 8090 -f)
+  gu-cli deps                              # install the agent's Python packages (smolagents + openai)
   gu-cli doctor [--client]                 # set up models here (--client: agent deps only,
                                                #   models stay on another machine)
   gu-cli api <start|stop|restart|status|upgrade>  # the LOCAL API (Local/Client Expert only);
@@ -1818,6 +1819,16 @@ async function guServiceLines() {
   return lines;
 }
 
+if (args[0] === "deps") {
+  // The agent's Python packages (smolagents + openai), installed in a plain process — what the installer and the
+  // first start run, and what to run by hand when either said it could not (GH #308).
+  const md = await import("./model-doctor.mjs");
+  const out = await md.ensureAgentDeps({ log: (l) => console.log(l), confirm: async () => true, modelHost: false, agreed: ["agentLibs"] });
+  const ok = out.agentLibs === "installed" || out.agentLibs === "present";
+  console.log(ok ? "\n  ✓ the agent framework is ready." : "\n  ✗ the agent framework is not installed — see the message above and " + md.PIP_LOG_FILE);
+  process.exit(ok ? 0 : 1);
+}
+
 if (args[0] === "doctor") {
   // Task #304: a Mac whose MongoDB runs in Docker is told the native option, once, up front —
   // a working Docker MongoDB is left alone (it is a choice), a silent one is named as stuck.

package/gu-repl.mjs

@@ -610,7 +610,7 @@ const argv = process.argv.slice(2);
 // process.argv and exits inside its own subcommand branch, before it ever starts polling.
 const CLI_SUBCOMMANDS = [
   "status", "start", "stop", "restart", "logs", "doctor", "login", "set", "rag",
-  "clear", "reset", "api", "token-usage", "tokens", "token", "full-log", "mcp", "hooks", "support",
+  "clear", "reset", "api", "token-usage", "tokens", "token", "full-log", "mcp", "hooks", "support", "deps",
 ];
 // `gu logz` USED TO START THE REPL (task #181). Silently: an unrecognised word was not in
 // the list, so it fell through to "no subcommand given" and a full agent session opened in that
@@ -700,6 +700,20 @@ if (REPL_LOG) {
   process.on("exit", () => ll.releaseLeaseSync());
   console.log(dim("  --log: detailed logging is on for this run (~/.gonext/worker.log); back to minimal when gu closes."));
 }
+
+// THE AGENT'S PYTHON PACKAGES COME FIRST (GH #308), before the first-run setup and the terminal below create their readline and
+// raw keyboard — and before stdout is hooked for the pinned input bar (whose state does not exist yet here): the install ran from inside the live terminal and froze it on a new Windows 11 machine.
+{
+  const pre = await import("./agent-deps-preflight.mjs");
+  if (pre.shouldPreflight()) {
+    const md0 = await import("./model-doctor.mjs");
+    await pre.agentDepsPreflight({
+      hasLibs: () => md0.hasAgentLibs(),
+      install: () => md0.ensureAgentDeps({ log: (l) => console.log(l), confirm: async () => true, modelHost: false, agreed: ["agentLibs"] }),
+      markDeclined: pre.markDeclinedOnDisk,
+    });
+  }
+}
 if (REPL_VERBOSE) {
   process.env.GONEXT_REPL_VERBOSE = "1";
 }

package/model-doctor.mjs

@@ -8,11 +8,12 @@
 // remote box). Downloads happen only when the model dir is genuinely absent AND the user
 // opts in.
 import { spawn, execFile } from "node:child_process";
+import { existsSync } from "node:fs";
 import { open, mkdir, readdir, writeFile } from "node:fs/promises";
 import { arch, homedir, platform, totalmem } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ensureSupportedPython, isBuildToolsMissing, buildFailureMessage } from "./platform-tools.mjs";
+import { ensureSupportedPython, isBuildToolsMissing, buildFailureMessage, ownVenvPython } from "./platform-tools.mjs";
 
 // Minimum RAM to run the default 14B-4bit chat model comfortably on Apple Silicon.
 const MIN_CHAT_RAM_GB = 16;
@@ -40,9 +41,15 @@ const EMBED_SCRIPT = fileURLToPath(new URL("./gonext_mlx_embed.py", import.meta.
 function python3Bin() {
   const explicit = (process.env.GONEXT_PROBE_PYTHON ?? process.env.GONEXT_MLX_LM_PYTHON ?? "").trim();
   if (explicit) return explicit;
+  // gu's OWN environment, when it has one (~/.gonext/venv): the agent's packages were installed INTO it, so a new
+  // process must look there, not in the system Python — or it asks to install them at every start (GH #308).
+  const own = ownVenvPython();
+  if (own) return own;
   return process.platform === "win32" ? "py" : "python3";
 }
 
+export { ownVenvPython };
+
 /**
  * How to install Python HERE. The advice used to say "Xcode Command Line Tools" on every
  * platform, which a Windows user cannot act on at all.
@@ -142,24 +149,66 @@ export function isPipMissing(output) {
   return /No module named pip\b/i.test(String(output ?? ""));
 }
 
-/** Run pip once. Resolves { code, err } — never rejects, so the caller owns the policy. */
-function runPip(python, pkgs, extraArgs = []) {
+/** How long one pip run may take before gu stops waiting (GU_PIP_TIMEOUT_MS overrides; a slow line needs more). */
+export const PIP_TIMEOUT_MS = Number(process.env.GU_PIP_TIMEOUT_MS ?? "") || 600_000;
+/** Where a pip run's whole output is kept, so a failure can be read afterwards. */
+export const PIP_LOG_FILE = join(homedir(), ".gonext", "pip-install.log");
+
+/**
+ * Run pip once. Resolves { code, err, timedOut } — never rejects, so the caller owns the policy.
+ *
+ * NEVER SILENT, NEVER FOREVER (found on a new Windows 11 box: the install sat at "installing …" for fifteen
+ * minutes with no output and no way to tell why). So: a line every 15 s says it is still working, the whole
+ * output goes to a log file, and a hard timeout kills the process tree and reports it as a failure that says
+ * what to do. stdout is piped and relayed rather than inherited, so nothing about the terminal can stall it.
+ */
+function runPip(python, pkgs, extraArgs = [], { log = () => {}, timeoutMs = PIP_TIMEOUT_MS } = {}) {
   return new Promise((resolve) => {
+    const keep = async (d) => {
+      try {
+        const { mkdirSync, appendFileSync } = await import("node:fs");
+        mkdirSync(DIR, { recursive: true });
+        appendFileSync(PIP_LOG_FILE, d);
+      } catch { /* the log is a convenience */ }
+    };
     // --prefer-binary: take an older wheel over a newer source build (a compiler is not a given, #225).
     const child = spawn(python, ["-m", "pip", "install", "-U", "--prefer-binary", ...extraArgs, ...pkgs], {
       // stderr is PIPED so the PEP 668 marker can be recognised, and echoed as it arrives so
       // the user still watches a real install rather than a frozen line.
-      stdio: ["ignore", "inherit", "pipe"],
+      stdio: ["ignore", "pipe", "pipe"],
       env: process.env,
+      windowsHide: true,
     });
+    keep(`\n--- ${new Date().toISOString()} ${python} -m pip install -U --prefer-binary ${pkgs.join(" ")}\n`);
     let err = "";
+    let done = false;
+    const started = Date.now();
+    const finish = (r) => {
+      if (done) return;
+      done = true;
+      clearInterval(beat);
+      clearTimeout(limit);
+      resolve(r);
+    };
+    child.stdout?.on("data", (d) => { keep(d); process.stdout.write(d); });
     child.stderr?.on("data", (d) => {
       const s = String(d);
       err += s;
+      keep(s);
       process.stderr.write(s);
     });
-    child.on("exit", (code) => resolve({ code: code ?? 1, err }));
-    child.on("error", (e) => resolve({ code: -1, err: String(e?.message ?? e) }));
+    const beat = setInterval(() => log(`  … still installing (${Math.round((Date.now() - started) / 1000)} s)`), 15_000);
+    const limit = setTimeout(() => {
+      // The whole tree: py.exe starts python.exe, which starts the build/download helpers.
+      if (process.platform === "win32" && child.pid) {
+        spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => {});
+      } else {
+        try { child.kill("SIGKILL"); } catch { /* already gone */ }
+      }
+      finish({ code: 124, err: `pip did not finish within ${Math.round(timeoutMs / 60000)} minutes`, timedOut: true });
+    }, timeoutMs);
+    child.on("exit", (code) => finish({ code: code ?? 1, err }));
+    child.on("error", (e) => finish({ code: -1, err: String(e?.message ?? e) }));
   });
 }
 
@@ -204,9 +253,42 @@ async function pipInstall(pkgs, log) {
   const sp = await ensureSupportedPython({ log });
   if (!sp.ok) throw new Error(sp.message);
   if (sp.switched) await pinPythonForDaemon({ log });
+
+  const stalled = (r) =>
+    new Error(
+      `${r.err}. The output is in ${PIP_LOG_FILE}. Install them yourself and start gu again: ` +
+        `${python3Bin()} -m pip install -U ${pkgs.join(" ")}`
+    );
+  const intoVenv = async () => {
+    const venvPy = await ensureVenv(log);
+    if (!venvPy) return null;
+    log(`  installing ${pkgs.join(" ")} into gu's own Python environment … (this can take a minute)`);
+    const r = await runPip(venvPy, pkgs, [], { log });
+    if (r.timedOut) throw stalled(r);
+    if (r.code !== 0) {
+      if (isBuildToolsMissing(r.err)) throw new Error(buildFailureMessage(r.err));
+      return null;
+    }
+    // Pin it NOW, not at the end of doctor: the packages live in this interpreter and nothing else can
+    // import them, so a daemon started meanwhile would still see none.
+    process.env.GONEXT_PROBE_PYTHON = venvPy;
+    await pinPythonForDaemon({ log });
+    log(`  installed into the virtualenv and pinned the agent's python to ${venvPy}`);
+    return venvPy;
+  };
+
+  // WINDOWS: gu's OWN environment (~/.gonext/venv) from the start. The system Python is somebody else's: writing
+  // into it needs an administrator, can clash with their packages, and cannot be undone with one folder delete.
+  // (GU_PIP_SYSTEM=1 keeps the old behaviour.)
+  if (process.platform === "win32" && process.env.GU_PIP_SYSTEM !== "1") {
+    if (await intoVenv()) return;
+    log("  ⚠ could not use a private environment — trying the system Python instead");
+  }
+
   log(`  installing ${pkgs.join(" ")} … (pip, this can take a minute)`);
-  let r = await runPip(python3Bin(), pkgs);
+  let r = await runPip(python3Bin(), pkgs, [], { log });
   if (r.code === 0) return;
+  if (r.timedOut) throw stalled(r);
   if (isBuildToolsMissing(r.err)) throw new Error(buildFailureMessage(r.err));
   const noPip = isPipMissing(r.err);
   if (!noPip && !isExternallyManaged(r.err)) {
@@ -218,18 +300,7 @@ async function pipInstall(pkgs, log) {
       ? "  this python has no pip — using a private virtualenv, which brings its own."
       : "  this python is managed by your OS (PEP 668) — it will not accept packages directly."
   );
-  const venvPy = await ensureVenv(log);
-  if (venvPy) {
-    r = await runPip(venvPy, pkgs);
-    if (r.code === 0) {
-      // Pin it NOW, not at the end of doctor: the packages live in this interpreter and
-      // nothing else can import them, so a daemon started meanwhile would still see none.
-      process.env.GONEXT_PROBE_PYTHON = venvPy;
-      await pinPythonForDaemon({ log });
-      log(`  installed into the virtualenv and pinned the agent's python to ${venvPy}`);
-      return;
-    }
-  }
+  if (process.platform !== "win32" && (await intoVenv())) return;
 
   // Without pip AND without venv nothing here can install anything; --break-system-packages
   // would only fail again with the same "No module named pip". Say what to install instead.
@@ -239,7 +310,8 @@ async function pipInstall(pkgs, log) {
     );
   }
   log("  falling back to --break-system-packages (no virtualenv available)");
-  r = await runPip(python3Bin(), pkgs, ["--break-system-packages"]);
+  r = await runPip(python3Bin(), pkgs, ["--break-system-packages"], { log });
+  if (r.timedOut) throw stalled(r);
   if (r.code === 0) return;
   throw new Error(`pip install ${pkgs.join(" ")} exited ${r.code}`);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.891",
-  "description": "gu: the coding agent in your terminal. It reads your repo, makes the change and runs the tests, with your own models (Ollama, MLX or any OpenAI-compatible provider). macOS, Linux and Windows.",
+  "version": "1.0.893",
+  "description": "gu: the coding agent in your terminal. It reads your repo, makes the change and runs the tests, with your own models (Ollama or any OpenAI-compatible provider). Free installs run entirely on your machine. macOS, Linux and Windows.",
   "keywords": [
     "ai",
     "coding-agent",
@@ -9,7 +9,6 @@
     "terminal",
     "llm",
     "ollama",
-    "mlx",
     "openai",
     "agent",
     "mcp",
@@ -63,6 +62,7 @@
   },
   "files": [
     "accent.mjs",
+    "agent-deps-preflight.mjs",
     "edit-card-render.mjs",
     "diff-syntax.mjs",
     "theme.mjs",

package/platform-tools.mjs

@@ -15,6 +15,9 @@
  * been executed on Windows, and a parser with tests is not a working port.
  */
 import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 
 const IS_WINDOWS = process.platform === "win32";
 
@@ -214,9 +217,22 @@ let _python = null;
  * An explicit GONEXT_PROBE_PYTHON still wins, and is passed through untouched.
  * Cached: otherwise this probes a subprocess on every job.
  */
+/**
+ * The interpreter of gu's own private virtualenv (~/.gonext/venv), or "" when there is none. Pure apart from one
+ * file check. The agent's packages are installed INTO it on Windows (GH #308), so everything that runs the agent —
+ * the terminal's checks AND the background worker — must look there, whatever worker.env did or did not pin.
+ */
+export function ownVenvPython(home = homedir(), exists = existsSync, platform = process.platform) {
+  const win = platform === "win32";
+  const py = join(home, ".gonext", "venv", win ? "Scripts" : "bin", win ? "python.exe" : "python");
+  return exists(py) ? py : "";
+}
+
 export async function resolvePython() {
   const explicit = (process.env.GONEXT_PROBE_PYTHON ?? process.env.GONEXT_MLX_LM_PYTHON ?? "").trim();
   if (explicit) return { cmd: explicit, args: [] };
+  const own = ownVenvPython();
+  if (own) return { cmd: own, args: [] };
   if (_python) return _python;
   for (const candidate of pythonCandidates()) {
     const probe = pythonVersionProbe(candidate);
@@ -474,6 +490,39 @@ export function isElevatedGroups(whoamiGroups) {
   return /S-1-16-(12288|16384)\b/.test(String(whoamiGroups ?? ""));
 }
 
+/**
+ * DID THE SCHEDULED TASK NEVER START? — from `schtasks /query /v /fo list`.
+ *
+ * A task runs only while its user has a logon session. Over SSH to an administrator who is not
+ * logged on at the console (a test box, a server), `schtasks /run` answers SUCCESS and the task
+ * stays "Ready" with Last Result 267011 (0x41303, "has not yet run") — nothing starts, and setup
+ * then stops at "The API started but is not usable: not up yet" with no log at all. Pure.
+ */
+export function taskNeverRan(queryOutput) {
+  const text = String(queryOutput ?? "");
+  return /Last Result:\s*267011\b/i.test(text) || /Last Run Time:\s*(N\/A|11\/30\/1999)/i.test(text);
+}
+
+/**
+ * START A PROCESS THAT OUTLIVES AN SSH SESSION, without a logon session: WMI's Win32_Process.Create.
+ *
+ * The process is created by the WMI service, so it is neither in the SSH session's job object (which
+ * kills its children at logoff) nor dependent on the user being logged on (which a scheduled task is).
+ * Needs an administrator token; measured on a Windows 11 box: a loop started this way kept running
+ * after the ssh session that started it had ended. → the pid, or null when WMI refused.
+ */
+export async function startViaWmi(commandLine, cwd = "") {
+  const script =
+    "$a = @{ CommandLine = $env:GU_WMI_CMD }; if ($env:GU_WMI_CWD) { $a.CurrentDirectory = $env:GU_WMI_CWD }; " +
+    "$r = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments $a; " +
+    'Write-Output "WMI $($r.ReturnValue) $($r.ProcessId)"';
+  const out = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+    env: { ...process.env, GU_WMI_CMD: commandLine, GU_WMI_CWD: cwd },
+  });
+  const m = /WMI 0 (\d+)/.exec(String(out ?? ""));
+  return m ? Number(m[1]) : null;
+}
+
 /**
  * Which pid owns a listening port, from `netstat -ano`.
  *
@@ -564,6 +613,27 @@ export async function spawnSurviving({ cmd, args = [], cwd, env = {}, logFile, t
   // generous: this runs once per start, and being slow here is free.
   await new Promise((r) => setTimeout(r, TASK_SETTLE_MS));
 
+  // THE TASK MAY NEVER HAVE STARTED (no logon session for this user — an SSH-only administrator).
+  // Then start it as a plain child of this terminal: it lives as long as the session does, which
+  // is what an SSH user gets everywhere else, and far better than "not up yet".
+  if (taskNeverRan(await run("schtasks.exe", ["/query", "/tn", taskName, "/v", "/fo", "list"]))) {
+    await run(t.remove.cmd, t.remove.args);
+    // Best first: WMI starts it outside the SSH session's job, so it survives the terminal closing.
+    const wmiPid = await startViaWmi(hiddenTaskAction(script, process.env.SystemRoot), cwd || "");
+    if (wmiPid) return { ok: true, pid: wmiPid, how: "WMI (the scheduled task never started — no logon session)" };
+    await rm(script).catch(() => {});
+    const { spawn } = await import("node:child_process");
+    const { open } = await import("node:fs/promises");
+    const log = logFile ? await open(logFile, "a") : null;
+    const child = spawn(cmd, args, {
+      cwd, env: { ...process.env, ...env }, stdio: ["ignore", log ? log.fd : "ignore", log ? log.fd : "ignore"],
+      detached: true, windowsHide: true,
+    });
+    child.unref();
+    await log?.close().catch(() => {});
+    return { ok: true, pid: child.pid ?? null, how: "detached (the scheduled task never started — no logon session)" };
+  }
+
   // Then deregister: nothing should be left scheduled on the user's machine. `/sc once` with a
   // start time in the past would otherwise re-fire, and a task named after gu sitting in
   // Task Scheduler forever is not something anyone asked for.