@tiens.nguyen/gu-cli 1.0.686

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@tiens.nguyen/gu-cli",
+  "version": "1.0.686",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tiennsloit/gu.git"
+  },
+  "homepage": "https://github.com/tiennsloit/gu#readme",
+  "bugs": {
+    "url": "https://github.com/tiennsloit/gu/issues"
+  },
+  "bin": {
+    "gu-cli": "./gu-cli.mjs",
+    "gu-local-worker": "./gu-cli.mjs",
+    "gu": "./gu-repl.mjs"
+  },
+  "scripts": {
+    "test": "python3 -m unittest discover tests -v && node --test",
+    "test:js": "node --test",
+    "test:keys": "node --test tests/key-choice-regression.test.mjs tests/coding-key-line.test.mjs tests/coding-key-picker.test.mjs tests/coding-key-prompt.test.mjs tests/coding-key-notice.test.mjs tests/coding-key-fallback-line.test.mjs tests/manage-coding-providers.test.mjs tests/add-coding-provider.test.mjs tests/coding-provider-setup.test.mjs",
+    "deploy:local": "npm install -g .",
+    "run": "gu-cli",
+    "publish:org": "npm publish --access public",
+    "preflight": "node scripts/preflight.mjs",
+    "test:e2e": "GONEXT_E2E=1 node --test tests/client-expert-e2e.test.mjs",
+    "test:linux": "bash scripts/e2e-linux.sh",
+    "test:rag": "node scripts/rag-e2e.mjs",
+    "test:ollama1-e2e": "GONEXT_OLLAMA1_LIVE=1 node --test --test-timeout=1800000 tests/ollama1-e2e.test.mjs",
+    "test:ollama1": "GONEXT_OLLAMA1_LIVE=1 python3 -m unittest discover tests -p \"test_ollama1_live.py\" -v",
+    "test:proxy": "python3 -m unittest discover tests -p \"test_proxy.py\" && node --test --test-timeout=30000 tests/proxy-config.test.mjs tests/proxy-transport.test.mjs tests/proxy-local-bypass.test.mjs tests/proxy-selftest.test.mjs tests/proxy-command.test.mjs",
+    "coverage": "node scripts/coverage.mjs",
+    "capture:cache": "GONEXT_OLLAMA1_LIVE=1 node scripts/capture-cache-fixture.mjs",
+    "test:cache-e2e": "GONEXT_OLLAMA1_LIVE=1 node --test --test-timeout=1800000 tests/prefix-cache-e2e.test.mjs",
+    "test:tokens": "python3 -m unittest discover tests -p \"test_cached_tokens.py\" -v && node --test tests/prefix-cache.test.mjs tests/agent-turn-shape.test.mjs",
+    "test:selection": "node --test tests/selection-scrollback.test.mjs tests/selection-while-thinking.test.mjs tests/terminal-selection.test.mjs tests/terminal-copy.test.mjs tests/terminal-viewport.test.mjs tests/hover-repaint.test.mjs",
+    "capture:turn": "GONEXT_OLLAMA1_LIVE=1 node scripts/capture-turn-fixture.mjs",
+    "test:bearer": "node --test tests/bearer-routing.test.mjs tests/bearer-verify.test.mjs",
+    "test:bearer-e2e": "bash scripts/bearer-e2e.sh"
+  },
+  "files": [
+    "gu-cli.mjs",
+    "gu-repl.mjs",
+    "terminal-hover.mjs",
+    "terminal-layout.mjs",
+    "terminal-viewport.mjs",
+    "terminal-copy.mjs",
+    "version-check.mjs",
+    "rag-selftest.mjs",
+    "device-login.mjs",
+    "daemon-control.mjs",
+    "poll-errors.mjs",
+    "node-version.mjs",
+    "clear-state.mjs",
+    "platform-tools.mjs",
+    "job-pools.mjs",
+    "rag-job-config.mjs",
+    "completed-flush.mjs",
+    "agent-model-label.mjs",
+    "coding-choice-tags.mjs",
+    "coding-provider-setup.mjs",
+    "client-expert-setup.mjs",
+    "client-expert-run.mjs",
+    "client-expert-api.mjs",
+    "first-run-steps.mjs",
+    "proxy-config.mjs",
+    "agent-model-command.mjs",
+    "ollama-setup.mjs",
+    "s3-setup.mjs",
+    "doctor-check.mjs",
+    "embed-model-command.mjs",
+    "proxy-command.mjs",
+    "proxy-selftest.mjs",
+    "proxy-store.mjs",
+    "proxy-dispatcher.mjs",
+    "model-doctor.mjs",
+    "coding-key-prompt.mjs",
+    "gonext_probe_agent.py",
+    "gonext_agent_chat.py",
+    "gonext_transcribe.py",
+    "gonext_mlx_embed.py",
+    "thinking_words.txt",
+    "README.md",
+    "launchd/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "express": "^4.21.0",
+    "openai": "^4.77.0",
+    "undici": "^7.29.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/platform-tools.mjs

@@ -0,0 +1,520 @@
+/**
+ * The three questions the CLI asks the operating system, each answered in ONE place (#157).
+ *
+ *   · which processes are running, and what command started them
+ *   · is this particular pid still one of ours
+ *   · what is listening on a port
+ *
+ * They were previously answered inline with `ps` and `lsof`, which do not exist on Windows —
+ * so the platform difference lived at every call site, and the next POSIX assumption would
+ * have been added somewhere nobody thinks to look. One concept, one function, the platform
+ * inside it.
+ *
+ * COMMAND SELECTION AND OUTPUT PARSING ARE PURE and are tested on macOS against recorded
+ * Windows output. Actually running them is not testable from here: nothing in this file has
+ * been executed on Windows, and a parser with tests is not a working port.
+ */
+import { execFile } from "node:child_process";
+
+const IS_WINDOWS = process.platform === "win32";
+
+const run = (cmd, args, opts = {}) =>
+  new Promise((resolve) => {
+    execFile(cmd, args, { maxBuffer: 8 * 1024 * 1024, ...opts }, (err, stdout) =>
+      resolve(err ? null : String(stdout ?? ""))
+    );
+  });
+
+/* ------------------------------------------------------------------ process listing ----- */
+
+/** The command that lists every process with its full command line. */
+export function processListCommand(platform = process.platform) {
+  return platform === "win32"
+    ? {
+        // CIM over WMIC: wmic is deprecated and absent from newer Windows 11 images, and
+        // `tasklist` gives no command LINE — only an image name, which cannot distinguish our
+        // daemon from any other node.exe.
+        cmd: "powershell.exe",
+        args: [
+          "-NoProfile", "-NonInteractive", "-Command",
+          "Get-CimInstance Win32_Process | ForEach-Object { \"$($_.ProcessId) $($_.CommandLine)\" }",
+        ],
+      }
+    : { cmd: "ps", args: ["-A", "-o", "pid=,command="] };
+}
+
+/**
+ * Parse a process listing into {pid, command} rows.
+ *
+ * Both platforms are made to produce "<pid> <command line>" so there is ONE parser: a second
+ * one would drift, and the thing it decides — is our daemon running — is not something to be
+ * wrong about differently per platform.
+ */
+export function parseProcessList(stdout) {
+  const rows = [];
+  for (const line of String(stdout ?? "").split(/\r?\n/)) {
+    const m = /^\s*(\d+)\s+(.*)$/.exec(line);
+    if (!m) continue;
+    const command = m[2].trim();
+    if (!command) continue; // a pid with no command line (a protected process) tells us nothing
+    rows.push({ pid: Number(m[1]), command });
+  }
+  return rows;
+}
+
+/** Every running process, as {pid, command}. Empty when the platform tool is unavailable. */
+export async function listProcesses() {
+  const { cmd, args } = processListCommand();
+  const out = await run(cmd, args);
+  return out === null ? [] : parseProcessList(out);
+}
+
+/** The command line of ONE pid, or "" if it is gone. */
+export function processCommandCommand(pid, platform = process.platform) {
+  return platform === "win32"
+    ? {
+        cmd: "powershell.exe",
+        args: [
+          "-NoProfile", "-NonInteractive", "-Command",
+          `(Get-CimInstance Win32_Process -Filter "ProcessId=${Number(pid)}").CommandLine`,
+        ],
+      }
+    : { cmd: "ps", args: ["-p", String(pid), "-o", "command="] };
+}
+
+export async function processCommand(pid) {
+  const { cmd, args } = processCommandCommand(pid);
+  const out = await run(cmd, args);
+  return out === null ? "" : out.trim();
+}
+
+/* ------------------------------------------------------------------ listening ports ----- */
+
+/** What is listening, for a set of pids. */
+export function listeningPortsCommand(pids, platform = process.platform) {
+  const list = pids.map(Number).filter(Number.isFinite);
+  return platform === "win32"
+    ? // -ano gives numeric addresses and the owning pid, and needs no elevation.
+      { cmd: "netstat.exe", args: ["-ano", "-p", "TCP"], pids: list }
+    : {
+        cmd: "lsof",
+        args: ["-a", "-p", list.join(","), "-iTCP", "-sTCP:LISTEN", "-P", "-n"],
+        pids: list,
+      };
+}
+
+/**
+ * Ports being LISTENED on by `pids`, from either tool's output.
+ *
+ * Behavioural on both platforms, deliberately: "did this command start a server" is answered
+ * by a socket existing, never by guessing from the command name. That is what lets
+ * `npm start`, `flask run` and a hand-rolled server all be recognised without a list.
+ */
+export function parseListeningPorts(stdout, pids, platform = process.platform) {
+  const want = new Set(pids.map(Number));
+  const ports = new Set();
+  for (const line of String(stdout ?? "").split(/\r?\n/)) {
+    if (platform === "win32") {
+      // Proto  Local Address        Foreign Address   State       PID
+      // TCP    0.0.0.0:3000         0.0.0.0:0         LISTENING   1234
+      const m = /^\s*TCP\s+\S+:(\d+)\s+\S+\s+LISTENING\s+(\d+)\s*$/i.exec(line);
+      if (m && want.has(Number(m[2]))) ports.add(Number(m[1]));
+    } else {
+      const m = /:(\d+)\s+\(LISTEN\)/.exec(line);
+      if (m) ports.add(Number(m[1]));
+    }
+  }
+  return [...ports].sort((a, b) => a - b);
+}
+
+/** TCP ports the given pids are listening on. */
+export async function listeningPorts(pids) {
+  const { cmd, args } = listeningPortsCommand(pids);
+  const out = await run(cmd, args);
+  return out === null ? [] : parseListeningPorts(out, pids);
+}
+
+/* ------------------------------------------------------------------ killing a tree ------ */
+
+/**
+ * Stop a process AND its children.
+ *
+ * POSIX gets one handle for the whole tree (setsid + killpg). Windows has no equivalent worth
+ * emulating: `taskkill /T` walks the tree by parent-pid, which is the honest substitute —
+ * imperfect if a child re-parents, but it does not silently leave a dev server holding a port,
+ * which is the failure that actually costs someone an afternoon.
+ */
+export function killTreeCommand(pid, { force = false, platform = process.platform } = {}) {
+  return platform === "win32"
+    ? { cmd: "taskkill.exe", args: ["/PID", String(Number(pid)), "/T", ...(force ? ["/F"] : [])] }
+    : { cmd: "kill", args: [force ? "-9" : "-15", String(Number(pid))] };
+}
+
+export const isWindows = () => IS_WINDOWS;
+
+
+/* ------------------------------------------------------------------ python ------------- */
+
+/**
+ * Interpreters to try, in order, for the platform.
+ *
+ * `python3` is hardcoded across the worker and does not exist on Windows — and worse, typing
+ * it there usually hits the Microsoft Store alias stub, which runs nothing. The launcher
+ * (`py -3`) is the reliable entry point on Windows and is what the official installer
+ * registers.
+ *
+ * MEASURED ON REAL HARDWARE 2026-08-29 (Windows 11 Pro 26100, admin@192.168.1.117), because
+ * this file was written against recorded output and never executed there:
+ *
+ *     python3 --version   → exit 9009, "Python was not found; run without arguments to
+ *                           install from the Microsoft Store…"   (C:\…\WindowsApps\python3.exe)
+ *     py -3 -c "…"        → exit 0, "3"                          (C:\Python314\python.exe)
+ *
+ * So on THIS build the stub exits 9009, not 0 — an earlier note here said it "looks like a
+ * success", and that half is wrong. It does not matter to the code, and that is the point of
+ * how the check is built: pythonVersionProbe asks for `sys.version_info[0]` and isPython3
+ * tests the OUTPUT, so the stub is rejected for printing prose whatever it exits with. A check
+ * that trusted the exit code would be a check that depends on a Windows build's mood.
+ */
+export function pythonCandidates(platform = process.platform) {
+  return platform === "win32"
+    ? [
+        { cmd: "py", args: ["-3"] },     // the launcher: present with any official install
+        { cmd: "python", args: [] },     // a python on PATH
+        { cmd: "python3", args: [] },    // last: often the Store stub, which runs nothing
+      ]
+    : [{ cmd: "python3", args: [] }, { cmd: "python", args: [] }];
+}
+
+/**
+ * Does this candidate actually RUN python? Not "is it on PATH" — the Store stub is on PATH
+ * and answers nothing, which is the exact failure this exists to avoid.
+ */
+export function pythonVersionProbe(candidate) {
+  return { cmd: candidate.cmd, args: [...candidate.args, "-c", "import sys; print(sys.version_info[0])"] };
+}
+
+/** True when the probe's output really came from a Python 3. */
+export function isPython3(stdout) {
+  return /^3\s*$/.test(String(stdout ?? "").trim());
+}
+
+let _python = null;
+
+/**
+ * The interpreter to spawn python with, as a SPAWN-READY {cmd, args}.
+ *
+ * Not a bare string: the Windows answer is `py -3`, and every call site here does
+ * spawn(python, [script, ...]) — a string with a space in it would be looked up as a single
+ * executable named "py -3" and fail. Returning the pair makes that impossible to get wrong:
+ *
+ *     const py = await resolvePython();
+ *     spawn(py.cmd, [...py.args, script, ...rest])
+ *
+ * An explicit GONEXT_PROBE_PYTHON still wins, and is passed through untouched.
+ * Cached: otherwise this probes a subprocess on every job.
+ */
+export async function resolvePython() {
+  const explicit = (process.env.GONEXT_PROBE_PYTHON ?? process.env.GONEXT_MLX_LM_PYTHON ?? "").trim();
+  if (explicit) return { cmd: explicit, args: [] };
+  if (_python) return _python;
+  for (const candidate of pythonCandidates()) {
+    const probe = pythonVersionProbe(candidate);
+    const out = await run(probe.cmd, probe.args, { timeout: 8000 });
+    if (out !== null && isPython3(out)) {
+      _python = { cmd: candidate.cmd, args: [...candidate.args] };
+      return _python;
+    }
+  }
+  // Nothing answered. Keep today's behaviour rather than inventing one, so the failure stays
+  // the familiar "python3: not found" instead of a new thing to diagnose.
+  return process.platform === "win32"
+    ? { cmd: "py", args: ["-3"] }
+    : { cmd: "python3", args: [] };
+}
+
+/** How to SAY the resolved interpreter in a log line or error message. */
+export const pythonLabel = (py) => [py.cmd, ...py.args].join(" ");
+
+/* ------------------------------------------------- surviving the session --------------- */
+
+/**
+ * Does a background process on this platform need help to outlive the session that starts it?
+ *
+ * ONLY WINDOWS, and not for the reason it looks like. `detached: true` is enough for a POSIX
+ * daemon, and on Windows it correctly detaches from the console — but an SSH session there runs
+ * inside a JOB OBJECT, and Windows kills every process in a job when the job ends. A detached
+ * child is still IN the job, so `gu-cli api start` over SSH starts a server that is dead
+ * the moment you disconnect.
+ *
+ * Proved on a real Windows 11 box: the API died, and so did the worker DAEMON — which uses the
+ * same detached spawn that survives perfectly when started from an ordinary console window.
+ * Same code, same flags; the only difference was who its parent was.
+ */
+/** How long to let a scheduled task's process get going before removing the task. */
+export const TASK_SETTLE_MS = Number(process.env.GONEXT_TASK_SETTLE_MS ?? "6000") || 6000;
+
+export function needsJobBreakaway(platform = process.platform) {
+  return platform === "win32";
+}
+
+/**
+ * The launcher script contents for a Windows background process.
+ *
+ * A FILE, not an inline command, because `schtasks /tr` takes one quoted string and the command
+ * needs its own quotes for paths with spaces — nesting them is where this breaks. A script has
+ * no quoting problem at all, and it can be read afterwards to see exactly what was run.
+ */
+export function windowsLauncherScript({ cmd, args = [], cwd, env = {}, logFile }) {
+  const lines = ["@echo off"];
+  for (const [k, v] of Object.entries(env)) {
+    // SKIP names cmd cannot set. Windows really has `ProgramFiles(x86)` and
+    // `CommonProgramFiles(x86)`; `set ProgramFiles(x86)=...` is a syntax error, and one bad
+    // line does not fail loudly — the script keeps going and the process never starts. That is
+    // what happened when the daemon was handed the whole of process.env: the API, which passes
+    // four variables, worked; the daemon, which passed hundreds, silently did not.
+    //
+    // Nothing is lost by skipping them: the scheduler runs the task AS THE USER, so the real
+    // environment is inherited anyway. This block is only for the EXTRAS a caller adds.
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) continue;
+    // A newline in a value would end the `set` and turn the rest into a command.
+    if (/[\r\n]/.test(String(v))) continue;
+    // No quotes around the value: `set X="v"` puts the QUOTES in the variable. A trailing
+    // space is equally fatal — `set PORT=4100 ` sets PORT to "4100 ".
+    lines.push(`set ${k}=${String(v).replace(/\s+$/, "")}`);
+  }
+  if (cwd) lines.push(`cd /d "${cwd}"`);
+  const command = [`"${cmd}"`, ...args.map((a) => `"${a}"`)].join(" ");
+  const redirected = logFile ? `${command} >> "${logFile}" 2>&1` : command;
+  // `start "" /b` so THIS SCRIPT RETURNS IMMEDIATELY and the task instance completes.
+  //
+  // Without it the task stays in state Running for as long as the server does — and removing a
+  // RUNNING task terminates its instance, taking the process with it. That is precisely what
+  // happened: with a long settle the daemon started and its log grew; with the normal 6s settle
+  // the task was deleted while still running and the daemon vanished, leaving no error anywhere.
+  // The empty "" is the window TITLE argument — omit it and `start` treats a quoted path as the
+  // title and runs nothing.
+  lines.push(`start "" /b ${redirected}`);
+  return lines.join("\r\n") + "\r\n";
+}
+
+/**
+ * Register → run → deregister. The task is a LAUNCH MECHANISM, not a persistent registration:
+ * it exists only to start the process outside our job, and is removed immediately afterwards
+ * so nothing is left scheduled on the user's machine. The started process keeps running —
+ * deleting a task does not kill what it launched (verified).
+ */
+export function schtasksCommands(taskName, scriptPath) {
+  return {
+    create: {
+      cmd: "schtasks.exe",
+      args: ["/create", "/tn", taskName, "/tr", scriptPath, "/sc", "once", "/st", "00:00", "/f"],
+    },
+    run: { cmd: "schtasks.exe", args: ["/run", "/tn", taskName] },
+    remove: { cmd: "schtasks.exe", args: ["/delete", "/tn", taskName, "/f"] },
+  };
+}
+
+/**
+ * Which pid owns a listening port, from `netstat -ano`.
+ *
+ * Needed because a task-launched process is not our child — there is no pid to record. The
+ * port is the only handle we have on it, and it is the one that matters anyway: what we care
+ * about is "who is serving this", not "who did we spawn".
+ */
+export function portOwnerPid(stdout, port) {
+  const want = Number(port);
+  for (const line of String(stdout ?? "").split(/\r?\n/)) {
+    const m = /^\s*TCP\s+\S+:(\d+)\s+\S+\s+LISTENING\s+(\d+)\s*$/i.exec(line);
+    if (m && Number(m[1]) === want) return Number(m[2]);
+  }
+  return null;
+}
+
+/**
+ * Start a long-lived background process that OUTLIVES this session, on any platform.
+ *
+ * POSIX: an ordinary detached spawn — nothing else is needed.
+ * Windows: written to a launcher script and started by the TASK SCHEDULER, because the
+ * scheduler's process is not in our job object and neither is what it starts. The task is
+ * removed immediately afterwards; it is a launch mechanism, not a registration, and deleting
+ * it does not kill what it started.
+ *
+ * Returns { ok, pid, how } — `pid` may be null on Windows, where the process is not our child.
+ * The caller finds it by the port it is serving, which is the better question anyway.
+ */
+export async function spawnSurviving({ cmd, args = [], cwd, env = {}, logFile, taskName }) {
+  if (!needsJobBreakaway()) {
+    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,
+    });
+    child.unref();
+    await log?.close().catch(() => {});
+    return { ok: true, pid: child.pid ?? null, how: "detached" };
+  }
+
+  const { writeFile, mkdir, rm } = await import("node:fs/promises");
+  const { dirname, join } = await import("node:path");
+  const script = join(dirname(logFile || cwd || "."), `${taskName}.cmd`);
+  await mkdir(dirname(script), { recursive: true }).catch(() => {});
+
+  // THE SCHEDULER'S ENVIRONMENT IS NOT YOURS. A task launched this way starts with a minimal
+  // environment — no USERPROFILE among it — so `os.homedir()` does not resolve to the user's
+  // profile and anything that reads ~/.gonext (worker.env, the sessions, the RAG index) fails.
+  // The daemon exited 1 that way, silently, with "Last Result: 1" the only trace.
+  //
+  // Carried EXPLICITLY, and only these: passing the whole of process.env is what put names cmd
+  // cannot set (`ProgramFiles(x86)`) into the script. Identity and PATH is what a child needs;
+  // everything else is the caller's business.
+  const IDENTITY = ["USERPROFILE", "HOMEDRIVE", "HOMEPATH", "HOME", "APPDATA", "LOCALAPPDATA", "PATH", "SystemRoot", "TEMP"];
+  const carried = {};
+  for (const k of IDENTITY) if (process.env[k]) carried[k] = process.env[k];
+
+  await writeFile(
+    script,
+    windowsLauncherScript({ cmd, args, cwd, env: { ...carried, ...env }, logFile }),
+    "utf8"
+  );
+
+  const t = schtasksCommands(taskName, script);
+  const created = await run(t.create.cmd, t.create.args);
+  if (created === null) {
+    // No scheduler (or no rights): fall back to a plain detached spawn. It dies with an SSH
+    // session, but it is correct from a console window — better than not starting at all.
+    const { spawn } = await import("node:child_process");
+    const child = spawn(cmd, args, {
+      cwd, env: { ...process.env, ...env }, stdio: "ignore", detached: true, windowsHide: true,
+    });
+    child.unref();
+    return { ok: true, pid: child.pid ?? null, how: "detached (schtasks unavailable)" };
+  }
+  await run(t.run.cmd, t.run.args);
+
+  // LET IT GET GOING BEFORE DEREGISTERING. `schtasks /run` returns as soon as the request is
+  // accepted, not when the process is up — and deleting the task while its instance is still
+  // starting kills what it started. Observed exactly that: the API logged "API listening" and
+  // "[mongo] connected", then vanished, with an immediate delete. The same sequence with a few
+  // seconds in between survived. The wait is empirical, not principled, which is why it is
+  // generous: this runs once per start, and being slow here is free.
+  await new Promise((r) => setTimeout(r, TASK_SETTLE_MS));
+
+  // 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.
+  await run(t.remove.cmd, t.remove.args);
+  await rm(script).catch(() => {});
+  return { ok: true, pid: null, how: "scheduled task" };
+}
+
+/** The pid serving `port`, or null. The handle we have on a process we did not spawn. */
+export async function pidOnPort(port) {
+  if (needsJobBreakaway()) {
+    const out = await run("netstat.exe", ["-ano", "-p", "TCP"]);
+    return out === null ? null : portOwnerPid(out, port);
+  }
+  const out = await run("lsof", ["-nP", `-iTCP:${Number(port)}`, "-sTCP:LISTEN", "-t"]);
+  const pid = Number(String(out ?? "").trim().split(/\s+/)[0]);
+  return Number.isFinite(pid) && pid > 0 ? pid : null;
+}
+
+/* ------------------------------------------------------- "View logs" (task #166) ---------- */
+
+/**
+ * Shell-quote one argument for the shell that will actually run it.
+ *
+ * NOT COSMETIC. A home directory with a space in it is routine on macOS ("/Users/Jo Smith") and
+ * normal on Windows, and every branch below builds a COMMAND STRING for a shell rather than an
+ * argv array — so an unquoted path silently becomes two arguments and the window opens tailing
+ * the wrong file, or nothing.
+ *
+ * POSIX uses single quotes (with the standard '\'' escape); cmd.exe has no escape inside double
+ * quotes, so an embedded '"' is simply dropped — it cannot appear in a Windows path anyway.
+ */
+export function shellQuote(arg, platform = process.platform) {
+  const s = String(arg ?? "");
+  if (platform === "win32") return `"${s.replace(/"/g, "")}"`;
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The command that FOLLOWS the log, per platform.
+ *
+ * Windows has no `tail`. PowerShell's `Get-Content -Wait` is the equivalent, and -Tail seeds it
+ * with the recent lines so the window is not blank until the next write — which is what makes it
+ * feel broken. Shipping `tail -f` everywhere would work on two of the three platforms the
+ * feature was asked for.
+ */
+export function logTailCommand(logFile, platform = process.platform) {
+  if (platform === "win32") {
+    // SINGLE quotes for the path, inside the double-quoted -Command block. Using shellQuote()
+    // here produced nested double quotes —
+    //   powershell -Command "Get-Content … -Path "C:\Users\Jo Smith\…""
+    // — which cmd.exe cannot parse, so the window opened on nothing. PowerShell reads '…' as a
+    // literal string, and doubling an embedded quote ('') is its own escape.
+    const psPath = `'${String(logFile ?? "").replace(/'/g, "''")}'`;
+    return `powershell -NoLogo -NoExit -Command "Get-Content -Wait -Tail 50 -Path ${psPath}"`;
+  }
+  return `tail -n 50 -f ${shellQuote(logFile, platform)}`;
+}
+
+/**
+ * How to open a NEW terminal window running `inner`, or null when this machine has none.
+ *
+ * NULL IS A REAL ANSWER and the most important one here. A headless Linux box, a container, or a
+ * plain SSH session has no display at all: spawning gnome-terminal there fails with a confusing
+ * error, or appears to succeed and does nothing. The caller prints the command to paste instead,
+ * which is a complete answer — a button that silently does nothing is not.
+ *
+ * `available` lists the emulators actually found on PATH; the caller supplies it so this stays
+ * pure and testable. Order is deliberate: the generic Debian/Ubuntu alternative first (it points
+ * at whatever the user actually chose), then the common desktops.
+ */
+export function terminalOpenCommand({
+  platform = process.platform,
+  inner,
+  hasDisplay = true,
+  available = [],
+} = {}) {
+  if (!inner) return null;
+  if (platform === "darwin") {
+    // osascript rather than `open -a Terminal <file>`: open needs a FILE, so running a command
+    // that way means writing a temp script and leaving it behind.
+    const script = `tell application "Terminal" to do script ${JSON.stringify(inner)}`;
+    return `osascript -e ${shellQuote(script, "darwin")}`;
+  }
+  if (platform === "win32") {
+    // `start ""` — the empty first argument is the WINDOW TITLE. Without it, cmd treats a quoted
+    // command as the title and opens an empty window, which is the classic version of this bug.
+    return `start "" ${inner}`;
+  }
+  // Linux and friends: a terminal is not guaranteed to exist at all.
+  if (!hasDisplay) return null;
+  for (const term of ["x-terminal-emulator", "gnome-terminal", "konsole", "xfce4-terminal", "xterm"]) {
+    if (available.includes(term)) {
+      // gnome-terminal needs `--` before the command; the others take -e.
+      return term === "gnome-terminal"
+        ? `gnome-terminal -- bash -lc ${shellQuote(inner, platform)}`
+        : `${term} -e bash -lc ${shellQuote(inner, platform)}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * What "View logs" should DO on this machine: open a window, or tell the user what to type.
+ *
+ * Returns { action: "spawn", command } or { action: "print", command } — never throws and never
+ * silently does nothing, because the whole point of the link is that the log is otherwise hard
+ * to reach.
+ */
+export function viewLogsPlan({ logFile, platform = process.platform, hasDisplay = true, available = [] } = {}) {
+  const inner = logTailCommand(logFile, platform);
+  const open = terminalOpenCommand({ platform, inner, hasDisplay, available });
+  return open ? { action: "spawn", command: open, inner } : { action: "print", command: inner, inner };
+}