@tiens.nguyen/gu-cli 1.0.834 → 1.0.836

package/install-path.mjs

@@ -53,7 +53,7 @@ const isEntryPoint = (() => {
 
 if (isEntryPoint) {
   try {
-    main();
+    await main();
   } catch (e) {
     // A postinstall that throws uninstalls the package. Report, swallow, succeed.
     console.log(`gu-cli: PATH setup skipped (${e.message}) — run \`npx @tiens.nguyen/gu-cli fix-path\` if \`gu\` is not found.`);
@@ -105,7 +105,7 @@ export function fixPathPrefix({ here = "", env = process.env, exists = existsSyn
 }
 
 function main() {
-  if (platform() === "win32") return;                 // registry PATH + PowerShell alias: not here
+  if (platform() === "win32") return windowsNotes();  // registry PATH: report, never edit (#375)
   if (process.env.CI) return;                          // no user shell to help in CI
   const prefix = process.env.npm_config_prefix;
   if (!prefix) return;                                 // not an npm install context
@@ -143,6 +143,23 @@ function main() {
   }
 }
 
+/**
+ * Windows (#375, GitHub #156): the PATH lives in the registry and is the user's to change, so the
+ * install only SAYS whether npm's folder is on it and how to add it — the same words as the
+ * installer and `gu-cli fix-path`, which also offers to add it. npm shows this only with
+ * --foreground-scripts; the installer (install.ps1) is what most people see.
+ */
+async function windowsNotes() {
+  if (process.env.CI || process.env.npm_config_global !== "true") return;
+  const prefix = process.env.npm_config_prefix;
+  if (!prefix) return;
+  const wp = await import("./win-path.mjs");
+  const status = wp.pathStatus({ dir: prefix, sessionPath: process.env.Path || process.env.PATH || "", ...wp.readSavedPaths() });
+  if (status.saved) return;
+  const { notes } = wp.installSummary({ version: "", location: "", dir: prefix, status });
+  console.log(`gu-cli: !! Setup notes:\n${notes.map((n) => `  \u2022 ${n}`).join("\n")}\n  Or run: gu-cli fix-path`);
+}
+
 /** The installer's home — the invoking user's, not root's, under sudo. */
 function realUserHome() {
   const sudoUser = process.env.SUDO_USER;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.834",
+  "version": "1.0.836",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -125,10 +125,13 @@
     "skills.mjs",
     "skill-source.mjs",
     "shell-details.mjs",
+    "proc-identity.mjs",
+    "win-path.mjs",
     "browser-command.mjs",
     "browser-bridge.mjs",
     "browser-extension/manifest.json",
     "browser-extension/background.js",
+    "browser-extension/actions.js",
     "browser-extension/popup.html",
     "browser-extension/popup.js",
     "browser-extension/icons/",
@@ -144,6 +147,7 @@
     "gu_skills.py",
     "gu_test_digest.py",
     "gu_browser.py",
+    "gu_powershell.py",
     "gu_hooks.py",
     "prompt_scaffold_check.py",
     "gonext_transcribe.py",

package/proc-identity.mjs

@@ -0,0 +1,53 @@
+// IS THIS PID STILL THE PROCESS WE MEANT? (task #373, GitHub #154)
+//
+// gu keeps process ids in files — shells.json, the local API's pid file, the browser bridge's state —
+// and those files outlive their processes. After a reboot or a crash the id is free, and the OS
+// hands it to the next program (VS Code, Chrome); a SIGTERM to the saved id then lands on that.
+// A process's START TIME is what tells two holders of one id apart, so it is what gu records and
+// checks before it signals anything. POSIX only: `ps -o lstart=` reads the same on macOS and procps.
+
+import { spawnSync } from "node:child_process";
+
+const MONTHS = "JanFebMarAprMayJunJulAugSepOctNovDec";
+
+/** When `pid` started (epoch s); null = no such process; NaN = cannot tell (no ps, Windows). */
+export function procStart(pid, { platform = process.platform } = {}) {
+  if (platform === "win32" || !(Number(pid) > 0)) return NaN;
+  const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+    encoding: "utf8",
+    env: { ...process.env, LC_ALL: "C", LANG: "C" },
+    timeout: 5000,
+  });
+  if (r.error) return NaN;
+  const raw = String(r.stdout || "").trim().replace(/\s+/g, " ");
+  if (!raw) return null;
+  // "Wed Oct 14 23:26:17 2026", local time.
+  const m = raw.match(/^\w{3} (\w{3}) (\d{1,2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/);
+  const mon = m ? MONTHS.indexOf(m[1]) / 3 : -1;
+  if (!m || mon < 0 || !Number.isInteger(mon)) return NaN;
+  return new Date(Number(m[6]), mon, Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5])).getTime() / 1000;
+}
+
+/** The command line of `pid` ("" when there is none, or no ps). */
+export function procCommand(pid, { platform = process.platform } = {}) {
+  if (platform === "win32" || !(Number(pid) > 0)) return "";
+  const r = spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8", timeout: 5000 });
+  return r.error ? "" : String(r.stdout || "").trim();
+}
+
+/**
+ * Is `pid` the process that was running at `startedAt` (epoch s, as recorded)?
+ *   "same"  — it started then (within `before` s before and `after` s after the record);
+ *   "gone"  — no process has that id;
+ *   "other" — that id belongs to a process started at another time: never signal it;
+ *   "unknown" — nothing to compare (Windows, no ps, nothing recorded).
+ * `before` is the room for a record written a while after its process started (a server that
+ * records itself once it listens); `after` is ps's whole-second rounding.
+ */
+export function sameProcess(pid, startedAt, { before = 5, after = 5, startOf = procStart } = {}) {
+  const t = startOf(pid);
+  if (t === null) return "gone";
+  const rec = Number(startedAt);
+  if (!Number.isFinite(t) || startedAt == null || !Number.isFinite(rec)) return "unknown";
+  return t >= rec - before && t <= rec + after ? "same" : "other";
+}

package/shell-details.mjs

@@ -15,6 +15,9 @@ import { existsSync, openSync, readSync, closeSync, fstatSync, readFileSync, rea
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, normalize } from "node:path";
 import { spawnSync } from "node:child_process";
+import { procStart } from "./proc-identity.mjs";
+
+export { procStart };
 
 export const shellsPath = (home = homedir()) => join(home, ".gonext", "shells.json");
 
@@ -40,10 +43,39 @@ export function readExit(rec) {
   }
 }
 
-/** Is the shell's process group (POSIX) or process (Windows) still there? */
-export function isAlive(rec, platform = process.platform) {
+// A SAVED PGID IS ONLY OURS WHILE ITS LEADER IS THE PROCESS WE STARTED (#373, GitHub #154) — the
+// same rule as the agent's _ws_group_owner. shells.json outlives its commands; after a reboot or a
+// crash the id goes to the next program (VS Code is its own group leader), and "a group with that
+// id exists" read as running and offered "Stop it" on someone else's app. The record's start time
+// is the proof: the process whose pid == the pgid must have started then (± START_SLACK_S). With
+// no such process, members left in the group are still ours — an id in use is never reused.
+export const START_SLACK_S = 5;
+
+/** The record's start (epoch s): `started`, else the older "YYYY-MM-DD HH:MM:SS" `started_at`. */
+function recordStarted(rec) {
+  const n = Number(rec?.started);
+  if (rec?.started != null && Number.isFinite(n)) return n;
+  const m = String(rec?.started_at ?? "").match(/^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/);
+  return m ? new Date(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]).getTime() / 1000 : null;
+}
+
+/** "ours" | "leader-gone" | "other" (the id now belongs to another program) | "unknown". */
+export function groupOwner(rec, { platform = process.platform, startOf = procStart } = {}) {
+  if (platform === "win32") return "ours";
+  const pgid = Number(rec?.pgid || rec?.pid || 0);
+  if (!pgid) return "unknown";
+  const leader = startOf(pgid);
+  if (leader === null) return "leader-gone";
+  const started = recordStarted(rec);
+  if (!Number.isFinite(leader) || started == null) return "unknown";
+  return Math.abs(leader - started) <= START_SLACK_S ? "ours" : "other";
+}
+
+/** Is the shell's process group (POSIX) or process (Windows) still there — and still ours? */
+export function isAlive(rec, platform = process.platform, { startOf = procStart } = {}) {
   const pid = Number(rec?.pgid || rec?.pid || 0);
   if (!pid) return false;
+  if (groupOwner(rec, { platform, startOf }) === "other") return false;
   try {
     process.kill(platform === "win32" ? pid : -pid, 0);
     return true;
@@ -85,23 +117,17 @@ export function statusText(st) {
   return "ended (exit code unknown)";
 }
 
-/**
- * The bottom notice row's shell control, or null. Running shells first — that is the thing worth
- * a row. Otherwise the newest one that finished while this terminal was open and that the user
- * has not opened yet, so a build that ends between questions is not missed.
- */
-export function shellsNotice(entries, { viewed = new Set(), since = 0 } = {}) {
+/** The bottom notice row's shell control while a shell is running, else null. */
+export function shellsNotice(entries) {
+  // ONLY WHILE SOMETHING RUNS (#376, GitHub #157). A finished shell used to keep "shell exited 0
+  // (click)" on the row until it was opened — a done build still asking for attention. When one
+  // finishes, the agent hears about it (a recap turn, or the next step of the turn it is in), and
+  // /shells still lists every shell with its output.
   const running = entries.filter((e) => e.st.state === "running");
-  if (running.length) {
-    const one = running.length === 1;
-    // No runtime here: it would change the row every second, and the bar repaints on change.
-    return { tone: "accent", text: `${running.length} shell${one ? "" : "s"} running (click)` };
-  }
-  const done = entries.filter((e) => !viewed.has(String(e.rec.id)) && e.st.ended >= since);
-  if (!done.length) return null;
-  const last = done[done.length - 1];
-  const ok = last.st.state === "exited";
-  return { tone: ok ? "accent" : "warn", text: `shell ${statusText(last.st)} (click)` };
+  if (!running.length) return null;
+  const one = running.length === 1;
+  // No runtime here: it would change the row every second, and the bar repaints on change.
+  return { tone: "accent", text: `${running.length} shell${one ? "" : "s"} running (click)` };
 }
 
 const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
@@ -225,6 +251,29 @@ export function renderShellDetails({ rec, st, output = [], outputFrom = "", widt
   return rows;
 }
 
+/**
+ * Shell details as a panel of EXACTLY `rows` rows (#376, GitHub #157) — drawn at the bottom, above
+ * the bar, and redrawn in place every second, so its height must not change while it is open
+ * (the in-place redraw walks up as many rows as it drew). The output keeps its NEWEST lines when
+ * space is short: a build's last lines are the news. Short content is padded with blank rows.
+ */
+export function shellPanelRows({ rec, st, output = [], outputFrom = "", width = 80, gutter = "  ", style = {}, rows = 20, footer = "" }) {
+  const head = renderShellDetails({ rec, st, output: [], outputFrom, width, gutter, style });
+  // renderShellDetails ends with "No output available" when given none; drop it — the real
+  // output (or that line) is placed below, in the room that is left.
+  head.pop();
+  const p = { dim: plain, ...style };
+  const room = Math.max(1, rows - head.length - (footer ? 1 : 0));
+  const inner = Math.max(20, width - gutter.length);
+  const out = output.length
+    ? output.slice(-room).map((l) => gutter + (l.length > inner ? l.slice(0, inner - 1) + "…" : l))
+    : [gutter + p.dim("No output available")];
+  const body = [...head, ...out].slice(0, Math.max(0, rows - (footer ? 1 : 0)));
+  while (body.length < rows - (footer ? 1 : 0)) body.push("");
+  if (footer) body.push(gutter + p.dim(footer));
+  return body.slice(0, rows);
+}
+
 /** A picker row for one shell: status · runtime · command, clipped to `width`. */
 export function shellPickerLabel(rec, st, width = 80) {
   const head = `${statusText(st)} · ${fmtRuntime(st.runtime)} · `;
@@ -237,15 +286,17 @@ export function shellPickerLabel(rec, st, width = 80) {
  * Stop a shell's whole group and record that it was killed — the record is what the agent reads
  * next turn, so "killed" must not later read as "ended (exit code unknown)".
  */
-export async function killShell(rec, { path = shellsPath(), platform = process.platform } = {}) {
+export async function killShell(rec, { path = shellsPath(), platform = process.platform, startOf = procStart } = {}) {
   const pid = Number(rec?.pgid || rec?.pid || 0);
-  if (pid && isAlive(rec, platform)) {
+  // Only a group that is provably the one gu started is signalled — never "unknown", never "other".
+  const ours = ["ours", "leader-gone"].includes(groupOwner(rec, { platform, startOf }));
+  if (pid && ours && isAlive(rec, platform, { startOf })) {
     if (platform === "win32") {
       spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
     } else {
       try { process.kill(-pid, "SIGTERM"); } catch { /* gone already */ }
-      for (let i = 0; i < 10 && isAlive(rec, platform); i++) await new Promise((r) => setTimeout(r, 100));
-      if (isAlive(rec, platform)) try { process.kill(-pid, "SIGKILL"); } catch { /* gone */ }
+      for (let i = 0; i < 10 && isAlive(rec, platform, { startOf }); i++) await new Promise((r) => setTimeout(r, 100));
+      if (isAlive(rec, platform, { startOf })) try { process.kill(-pid, "SIGKILL"); } catch { /* gone */ }
     }
   }
   if (!existsSync(path)) return;
@@ -278,10 +329,14 @@ export function shellsToRecap(entries, { cwd = process.cwd(), since = 0 } = {})
     const up = dirname(raw);
     return up === raw ? raw : join(real(up), basename(raw));
   };
-  const base = real(cwd).replace(/\/+$/, "");
+  // THE SAME PROJECT (#376): the git repository this terminal is in, else this folder. gu started
+  // in app/ while the agent ran the build at the repository root (its workspace): the shell's
+  // folder is ABOVE this one, and the recap never came, though the build was this terminal's.
+  // Not "any folder above" — the home folder is above every project.
+  const base = projectRoot(real(cwd)).replace(/\/+$/, "");
   const under = (wd) => {
-    const w = real(wd);
-    return w === base || w.startsWith(base + "/");
+    const w = real(wd).replace(/\/+$/, "");
+    return Boolean(w) && (w === base || w.startsWith(base + "/"));
   };
   return entries
     .filter(({ rec, st }) => st.state !== "running" && st.state !== "killed" && !rec.seen && !rec.announced
@@ -289,6 +344,17 @@ export function shellsToRecap(entries, { cwd = process.cwd(), since = 0 } = {})
     .map((e) => e.rec);
 }
 
+/** The nearest folder at or above `dir` holding .git — or `dir` itself when there is none. */
+export function projectRoot(dir, exists = existsSync) {
+  let d = String(dir ?? "");
+  for (;;) {
+    if (exists(join(d, ".git"))) return d;
+    const up = dirname(d);
+    if (up === d) return String(dir ?? "");
+    d = up;
+  }
+}
+
 /** Mark these shells announced in shells.json, so neither the agent nor another terminal repeats it. */
 export function markAnnounced(ids, { path = shellsPath() } = {}) {
   const shells = readShells(path);
@@ -306,6 +372,9 @@ export function recapQuestion(entries) {
   const parts = entries.map(({ rec, st }) =>
     `shell ${rec.id} ${statusText(st)} after ${fmtRuntime(st.runtime)} (${String(rec.command ?? "").replace(/\s+/g, " ").trim().slice(0, 120)})`);
   const ids = entries.map(({ rec }) => `shell_output('${rec.id}')`).join(", ");
+  // #376: come back to the work, not only report on it — a failed build is the next thing to fix,
+  // a finished one may be the step before the next; a recap only when nothing is left to do.
   return `[gu: background ${entries.length === 1 ? "shell" : "shells"} finished — ${parts.join("; ")}] `
-    + `Read the result with ${ids}, tell me briefly what happened, and continue with the next step if the task needs one.`;
+    + `Read the result with ${ids}. If it failed, find out why and fix it. If it was a step of the task you `
+    + `were doing, carry on with the next step now. If nothing is left to do, tell me in one or two lines what happened.`;
 }

package/terminal-layout.mjs

@@ -1148,6 +1148,7 @@ export function trimWords(text, limit) {
 // grey ✗ with dim text. Judged by the LAST segment of a chain/pipeline (its exit status is
 // the one reported): `ps aux | grep foo` and `cd src && rg Foo` are both look-ups.
 const SEARCH_CMDS = new Set([
+  // platform-ok: names to recognise in a command the agent ran — nothing here runs them.
   "grep", "egrep", "fgrep", "zgrep", "rg", "ag", "ack", "pgrep", "which", "whereis", "lsof",
 ]);
 export function isSoftFailCommand(cmd) {

package/win-path.mjs

@@ -0,0 +1,185 @@
+/**
+ * IS gu ON THE WINDOWS PATH, AND IF NOT, WHAT DOES THE USER DO? (task #375, GitHub #156)
+ *
+ * On Windows, `npm i -g` puts gu.cmd in npm's global folder (%APPDATA%\npm by default; nvm-windows
+ * and a custom prefix put it elsewhere). When that folder is not on PATH, the next `gu` answers
+ * "'gu' is not recognized" and the user calls the install broken. Claude Code's installer says it
+ * plainly instead — "C:\Users\x\.local\bin is not in your PATH. Add it by opening: System
+ * Properties → Environment Variables → Edit User PATH → New → Add the path above. Then restart
+ * your terminal." — and gu now does the same, in the same words, from:
+ *
+ *   - the installer (https://gu.getmarsic.cc/install.ps1, web-v2/public — its own PowerShell copy
+ *     of this wording; tests/win-path.test.mjs holds the two together),
+ *   - `gu-cli fix-path`, which also offers to add it (a yes, never silently),
+ *   - npm's postinstall (shown only with --foreground-scripts: npm hides install-script output).
+ *
+ * WHY THE SAVED PATH AND NOT ONLY THIS ONE: a new terminal reads PATH from the registry (User +
+ * Machine), not from the process that installed. A folder in this session only — added by hand,
+ * or by an installer that ran here — is gone in the next window.
+ *
+ * Pure except readSavedPaths / addToUserPath, which run PowerShell.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** `%APPDATA%\npm\` / `"C:/x"` / `c:\X` → one comparable form. %VARS% from `env` (case-insensitive). */
+export function normalizeDir(dir, env = process.env) {
+  const lower = {};
+  for (const [k, v] of Object.entries(env || {})) lower[k.toLowerCase()] = v;
+  let d = String(dir ?? "").trim().replace(/^"(.*)"$/, "$1");
+  d = d.replace(/%([^%]+)%/g, (m, name) => lower[name.toLowerCase()] ?? m);
+  d = d.replace(/\//g, "\\").replace(/\\+$/, "");
+  if (/^[a-z]:$/i.test(d)) d += "\\";
+  return d.toLowerCase();
+}
+
+/** Does the ;-separated PATH value hold `dir`? */
+export function pathHas(pathValue, dir, env = process.env) {
+  const want = normalizeDir(dir, env);
+  if (!want) return false;
+  return String(pathValue ?? "")
+    .split(";")
+    .some((p) => p.trim() && normalizeDir(p, env) === want);
+}
+
+/** { session, saved } — saved = the User or the Machine PATH in the registry. */
+export function pathStatus({ dir, sessionPath = "", userPath = "", machinePath = "", env = process.env }) {
+  return {
+    session: pathHas(sessionPath, dir, env),
+    saved: pathHas(userPath, dir, env) || pathHas(machinePath, dir, env),
+  };
+}
+
+/** The user PATH value with `dir` appended once — no doubled or trailing `;`. */
+export function userPathWith(userPath, dir, env = process.env) {
+  const parts = String(userPath ?? "")
+    .split(";")
+    .map((p) => p.trim())
+    .filter(Boolean);
+  if (parts.some((p) => normalizeDir(p, env) === normalizeDir(dir, env))) return parts.join(";");
+  return [...parts, dir].join(";");
+}
+
+/** npm's global folder from where this package lives: <prefix>\node_modules\@tiens.nguyen\gu-cli. */
+export function windowsPrefixOf(packageDir) {
+  const parts = String(packageDir ?? "").replace(/\//g, "\\").replace(/\\+$/, "").split("\\");
+  const n = parts.length;
+  if (n < 4 || parts[n - 3].toLowerCase() !== "node_modules" || !parts[n - 2].startsWith("@")) return "";
+  const prefix = parts.slice(0, n - 3);
+  if (prefix.some((p) => p.toLowerCase() === "node_modules")) return ""; // a project's, not global
+  return prefix.join("\\");
+}
+
+/** Where npm put gu's Windows launcher in that folder (kept here: see powershell-alias.mjs on
+ *  why gu-cli.mjs never names it). */
+export const guLocation = (dir) => join(dir, "gu.cmd");
+
+const ARROW = "\u2192";
+
+/** The lines Claude Code's installer prints, in gu's words. The installer prints the same. */
+export const NOTE_PATH = (dir) =>
+  `${dir} is not in your PATH. Add it by opening: System Properties ${ARROW} Environment Variables ` +
+  `${ARROW} Edit User PATH ${ARROW} New ${ARROW} Add the path above. Then restart your terminal.`;
+export const NOTE_PATH_SESSION = (dir) =>
+  `${dir} is in your saved PATH, but not in this terminal yet. Open a new terminal to use gu.`;
+export const NOTE_ALIAS =
+  "In PowerShell, `gu` is a built-in alias (Get-Unique) that wins over this program. Run " +
+  "`gu-cli fix-powershell` once to remove it; until then start gu with `gu.cmd`. cmd.exe is not affected.";
+
+/** The one-liner to add `dir` to the user PATH in PowerShell, keeping %VARS% entries as they are. */
+export function addToPathOneLiner(dir) {
+  const q = String(dir).replace(/'/g, "''");
+  return (
+    `$k = 'HKCU:\\Environment'; $p = (Get-Item $k).GetValue('Path', '', 'DoNotExpandEnvironmentNames'); ` +
+    `Set-ItemProperty $k Path (($p.TrimEnd(';') + ';${q}').TrimStart(';')) -Type ExpandString`
+  );
+}
+
+/**
+ * What to print after an install: { ok, lines, notes }. `notes` are the "Setup notes" bullets —
+ * empty when there is nothing for the user to do.
+ */
+export function installSummary({ version, location, dir, status, powershell = false }) {
+  const notes = [];
+  if (!status.saved) notes.push(NOTE_PATH(dir), `Or run this in PowerShell: ${addToPathOneLiner(dir)}`);
+  else if (!status.session) notes.push(NOTE_PATH_SESSION(dir));
+  if (powershell) notes.push(NOTE_ALIAS);
+  const lines = [
+    "gu successfully installed!",
+    "",
+    `  Version:  ${version || "?"}`,
+    "",
+    `  Location: ${location}`,
+    "",
+    // In PowerShell `gu` is Get-Unique until the alias is removed; gu.cmd is the same program.
+    `  Next: Run ${powershell ? "gu.cmd" : "gu"} to get started`,
+  ];
+  return { ok: status.saved, lines, notes };
+}
+
+/** Print an installSummary the way the installer does (yellow notes, `•` bullets). */
+export function formatSummary({ lines, notes }, { color = false } = {}) {
+  const y = (s) => (color ? `\x1b[33m${s}\x1b[0m` : s);
+  const g = (s) => (color ? `\x1b[32m${s}\x1b[0m` : s);
+  const out = [g(lines[0]), ...lines.slice(1)];
+  if (notes.length) {
+    out.push("", y("!! Setup notes:"));
+    for (const n of notes) out.push(`  \u2022 ${n}`);
+  }
+  return out.join("\n");
+}
+
+// ------------------------------------------------------------------ Windows only ------------
+
+const powershellExe = () =>
+  join(process.env.SystemRoot || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+
+/** Run a PowerShell script from a FILE (no quoting across a command line), stdout as text. */
+function runPs(script) {
+  const dir = mkdtempSync(join(tmpdir(), "gu-path-"));
+  const file = join(dir, "x.ps1");
+  try {
+    writeFileSync(file, "\ufeff" + script, "utf8"); // a BOM: Windows PowerShell 5.1 reads UTF-8 then
+    const r = spawnSync(powershellExe(), ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", file], {
+      encoding: "utf8",
+      timeout: 30_000,
+      windowsHide: true,
+    });
+    return { ok: !r.error && r.status === 0, out: String(r.stdout || ""), err: String(r.stderr || r.error?.message || "") };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** { userPath, machinePath } from the registry, as stored (%VARS% unexpanded). */
+export function readSavedPaths() {
+  const r = runPs(
+    "$u = (Get-Item 'HKCU:\\Environment').GetValue('Path', '', 'DoNotExpandEnvironmentNames')\n" +
+      "$m = (Get-Item 'HKLM:\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment').GetValue('Path', '', 'DoNotExpandEnvironmentNames')\n" +
+      "[Console]::Out.Write(\"$u`n$m\")\n",
+  );
+  const [userPath = "", machinePath = ""] = r.out.split(/\r?\n/);
+  return { userPath, machinePath, ok: r.ok };
+}
+
+/**
+ * Add `dir` to the USER PATH — only ever after the user said yes. Written as REG_EXPAND_SZ so
+ * entries like %USERPROFILE%\x keep working (setx and .NET's SetEnvironmentVariable on 5.1 flatten
+ * them, and setx cuts PATH at 1024 characters); then the change is announced
+ * (WM_SETTINGCHANGE, via a throwaway variable's set + clear) so new terminals see it.
+ */
+export function addToUserPath(dir) {
+  const q = String(dir).replace(/'/g, "''");
+  const r = runPs(
+    "$k = 'HKCU:\\Environment'\n" +
+      "$p = (Get-Item $k).GetValue('Path', '', 'DoNotExpandEnvironmentNames')\n" +
+      `$d = '${q}'\n` +
+      "$have = @($p -split ';' | Where-Object { $_.Trim().TrimEnd('\\') -ieq $d.TrimEnd('\\') })\n" +
+      "if (-not $have) { Set-ItemProperty $k Path (($p.TrimEnd(';') + ';' + $d).TrimStart(';')) -Type ExpandString }\n" +
+      "[Environment]::SetEnvironmentVariable('GU_PATH_REFRESH', '1', 'User')\n" +
+      "[Environment]::SetEnvironmentVariable('GU_PATH_REFRESH', $null, 'User')\n",
+  );
+  return { ok: r.ok, error: r.ok ? "" : r.err.trim() };
+}