@tiens.nguyen/gu-cli 1.0.686

package/completed-flush.mjs

@@ -0,0 +1,105 @@
+/**
+ * What is still unshown when a job flips to "completed" (#173, and #72 from the other side).
+ *
+ * THE ONE INVARIANT EVERYTHING HERE DEPENDS ON: the completed `resultText` must EXTEND the text
+ * that was streamed. The REPL renders a poll by printing `resultText.slice(charsAlreadyShown)`,
+ * so a completed payload that REPLACES the stream with a shorter, different string breaks the
+ * arithmetic in both directions:
+ *
+ *   · too short  → the slice is empty, and a plain reply renders cut mid-word. That is #72,
+ *                  reported live as "Hello! How" out of a 36-character answer.
+ *   · different  → the slice is a garbage tail from the middle of a sentence.
+ *
+ * #72 fixed the STREAMED case by sending fullText. The non-streamed case still sent the bare
+ * answer, which is how #173 happened: an agent turn wraps every step line in a <think> fence and
+ * appends the answer after it, so the bare answer drops the entire fence. Any step emitted inside
+ * the last poll window was therefore never delivered — which is why "Composing answer…" has never
+ * once appeared on screen despite being named in task #41 as a bullet that prints.
+ *
+ * WHY THE AGENT TAIL CANNOT SIMPLY BE FLUSHED. The tail usually contains the answer too, and the
+ * caller prints the answer itself (renderAnswer, wrapped and indented, from the same resultText).
+ * Flushing the whole tail would print it twice. So the agent branch flushes only what is still
+ * INSIDE the fence and stops at `</think>`; everything after it belongs to the caller.
+ *
+ * Pure, and separate from gu-repl.mjs because that file starts a REPL on import and cannot be
+ * reached by a test — the same reason job-pools.mjs and rag-job-config.mjs exist.
+ */
+
+/** Strip whole <think> blocks, and an unclosed one, exactly as the REPL's answerFrom does. */
+export function answerFrom(s) {
+  return String(s ?? "")
+    .replace(/<think>[\s\S]*?<\/think>/gi, "")
+    .replace(/<think>[\s\S]*$/i, "")
+    .trim();
+}
+
+/**
+ * Does this completed payload continue the stream, or replace it?
+ *
+ * `seenRaw` is the first ≤4KB of what was streamed — a fingerprint, not the whole thing, so this
+ * stays cheap on a long turn. A payload SHORTER than what we already showed cannot be an
+ * extension whatever it starts with, hence both halves.
+ */
+export function extendsStream({ resultText = "", shownChars = 0, seenRaw = "" } = {}) {
+  const text = String(resultText ?? "");
+  return text.length >= shownChars && text.startsWith(String(seenRaw ?? ""));
+}
+
+/**
+ * What the completed poll should print. Returns { kind, text }:
+ *
+ *   "none"    — nothing left to show
+ *   "suffix"  — plain reply: feed `text` to the live consumer, it continues the stream
+ *   "recover" — plain reply whose payload did NOT extend the stream (an older worker): print
+ *               `text`, the part of the final answer that was never shown live
+ *   "steps"   — agent turn: feed `text` (step lines only, never the answer) to the live consumer
+ *
+ * The caller still owns cursor/gutter mechanics; this owns the decision and the string.
+ */
+export function completedFlush({
+  resultText = "",
+  shownChars = 0,
+  seenRaw = "",
+  plainReplyFlow = false,
+  answerShownLive = false,
+  liveAnswer = "",
+  streamPlainReply = true,
+} = {}) {
+  const text = String(resultText ?? "");
+  const shown = Math.max(0, Number(shownChars) || 0);
+  const extended = extendsStream({ resultText: text, shownChars: shown, seenRaw });
+
+  if (plainReplyFlow) {
+    // Unchanged from #72 — both branches, including the gate on STREAM_PLAIN_REPLY, which is why
+    // it is threaded through rather than assumed.
+    if (!streamPlainReply) return { kind: "none", text: "" };
+    if (extended && text.length > shown) {
+      return { kind: "suffix", text: text.slice(shown) };
+    }
+    if (!extended && answerShownLive) {
+      const ans = answerFrom(text);
+      const live = String(liveAnswer ?? "");
+      let rest = ans.startsWith(live) ? ans.slice(live.length) : null;
+      if (rest === null) {
+        // The live text may carry trailing whitespace the trimmed answer lacks.
+        const printed = live.replace(/\s+$/, "");
+        rest = ans.startsWith(printed) ? ans.slice(printed.length) : null;
+      }
+      return rest ? { kind: "recover", text: rest } : { kind: "none", text: "" };
+    }
+    return { kind: "none", text: "" };
+  }
+
+  // ---- agent turn (#173) ----
+  // Only ever a continuation. There is no recovery branch here on purpose: when the payload does
+  // not extend the stream we cannot tell which step lines were already shown, and printing the
+  // fence again would duplicate the whole action list. Silence beats a double transcript.
+  if (!extended || text.length <= shown) return { kind: "none", text: "" };
+  const tail = text.slice(shown);
+  const close = tail.search(/<\/think>/i);
+  // No closing tag in the tail means the fence closed before this point, so the tail is the
+  // ANSWER — the caller's job, not ours.
+  if (close < 0) return { kind: "none", text: "" };
+  const steps = tail.slice(0, close);
+  return steps ? { kind: "steps", text: steps } : { kind: "none", text: "" };
+}

package/daemon-control.mjs

@@ -0,0 +1,462 @@
+// Worker-daemon lifecycle for the gu CLI (task #127, Phase 2). Lets a plain terminal
+// keep the polling worker running WITHOUT the GoTerminal desktop app: `gu-cli
+// start|stop|status|logs`, and `gu` (the REPL) auto-ensures it on startup.
+//
+// BC4 (task #127): NEVER double-spawn. A second polling daemon would race the first for
+// jobs. We detect an already-running daemon two ways — our own pidfile AND a `ps` scan that
+// also catches a daemon started by GoTerminal or by hand (which never wrote our pidfile) —
+// and refuse to start when either says one is alive.
+import { spawn, execFile } from "node:child_process";
+import { readFile, writeFile, unlink, mkdir, open, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  processListCommand,
+  processCommandCommand,
+  spawnSurviving,
+} from "./platform-tools.mjs";
+import { isLocalApiBase } from "./terminal-layout.mjs";
+const PROC_LIST = processListCommand();
+
+const DIR = join(homedir(), ".gonext");
+export const PID_FILE = join(DIR, "worker.pid");
+/**
+ * What the worker is RUNNING RIGHT NOW, published for other processes (task #209 req 1).
+ *
+ * stopDaemon lives in a DIFFERENT process from the worker, so it cannot see the in-flight job
+ * map and has been SIGTERMing turns with no idea they existed. `doctor` reaches that path at the
+ * end of every run, which is how a user lost an hour-long turn to a dependency check.
+ *
+ * A FILE RATHER THAN AN API CALL, deliberately: the question "is a turn running on this machine"
+ * must be answerable when the API is down, which is exactly when someone is restarting things.
+ * The pid is stored WITH it so a file left behind by a SIGKILLed worker is ignored rather than
+ * blocking every future stop — a stale busy-file must never be able to wedge the CLI.
+ */
+export const BUSY_FILE = join(DIR, "worker-busy.json");
+export const LOG_FILE = join(DIR, "worker.log");
+const LOCK_FILE = join(DIR, "worker.start.lock");
+const LOCK_STALE_MS = 30_000; // a lock older than this is from a crashed start → steal it
+const DAEMON_SCRIPT = fileURLToPath(new URL("./gu-cli.mjs", import.meta.url));
+// The daemon script was named gonext-local-worker.mjs before the CLI was renamed to
+// gu-cli. Match BOTH so BC4 (never double-spawn) still detects a daemon started by an
+// OLDER install across the upgrade window.
+// A CLOSING QUOTE COUNTS AS A BOUNDARY. Windows command lines quote every path, so the real
+// cmdline is `"…\node.exe"  "…\gu-cli.mjs"` — the character after `.mjs` is a QUOTE, not
+// whitespace. Requiring `\s|$` therefore matched nothing on Windows, and the consequences were
+// not subtle: `status` reported no daemon while one was polling, `stop` could not find it to
+// stop it, and every `start` believed there was none — so they accumulated. Observed with TWO
+// daemons running and gu insisting there were none.
+const DAEMON_FILE_RE = /gu-(cli|local-worker)\.mjs(["'\s]|$)/;
+
+// Any cmdline containing one of these is a SUBCOMMAND invocation (login, start, …), not the
+// polling daemon — so it must not be mistaken for a running worker in the ps scan.
+const SUBCOMMANDS = [
+  "login", "set", "start", "stop", "status", "logs", "restart",
+  "ws-ping-test", "simulate-chat", "embed", "workspace",
+];
+
+// ---- client-only ("agent") mode -----------------------------------------------------------
+// A machine that does NOT host models: the terminal here just enqueues turns, and a daemon on
+// the machine that DOES have the models executes them. Machine-level on purpose (unlike the
+// per-folder prompt memory in task #135): "this box has no models" is a fact about the box,
+// and storing it per folder would let a second folder start a competing daemon again.
+const PREFS_FILE = join(DIR, "prefs.json");
+
+async function readPrefs() {
+  try {
+    return JSON.parse(await readFile(PREFS_FILE, "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * WHY A "CLIENT OVERRIDE" EXISTED, AND WHY IT IS GONE (task #134 → removed 2026-09-06).
+ *
+ * THE ORIGINAL PROBLEM WAS REAL. "Client mode" means this box hosts no models; it shares an
+ * account with the machine that does. That machine's settings said
+ * `agentModelUrl = http://127.0.0.1:11434/v1` — correct THERE, and on a client it resolves to
+ * the client itself, which has nothing listening. So a client substituted a shared, reachable
+ * Ollama locally and never wrote that back to the account.
+ *
+ * WHY IT HAD TO GO. The premise stopped being true. Since task #220 setup ASKS for the Ollama
+ * URL and stores a routable one, and since the agent model became a choice there is a chosen
+ * name as well. But the substitution never checked any of that — it replaced the URL AND the
+ * model on every client turn, so a machine configured with a reachable server and a deliberate
+ * model silently ran something else, and the banner reported the constant it had substituted.
+ * That was reported three separate times as "why does it still say <model>", because the value
+ * on screen was never the value the user had set. A setting that cannot be observed cannot be
+ * changed, and one the machine quietly discards should not be offered.
+ *
+ * WHAT REPLACES IT: nothing. The configured URL and model are used, always. When they cannot
+ * work from here this says so — see clientAgentProblem — because a substitution that fixes the
+ * turn while hiding the cause is what made this take three rounds to find.
+ */
+
+/**
+ * Is the account's agent URL unusable FROM THIS MACHINE? → a sentence to show, or "".
+ *
+ * Only loopback qualifies, and only in client mode: that is the exact shape task #134 existed
+ * for — the model host's own address, meaningless on a box that is not it. Everything else is
+ * the user's own answer and is left alone, including addresses that turn out to be down, which
+ * is a different problem with a different message (see probeReachable).
+ */
+export function clientAgentProblem({ accountUrl = "", clientMode = false } = {}) {
+  if (!clientMode) return "";
+  const url = String(accountUrl ?? "").trim();
+  if (!url) {
+    return "no agent model server is configured — run /model to point this machine at one.";
+  }
+  if (isLocalApiBase(url)) {
+    return (
+      `the agent model server is ${url}, which on this machine means THIS machine — and it ` +
+      "hosts no models. Run /model to point it at the box that does."
+    );
+  }
+  return "";
+}
+
+/**
+ * A stable id for THIS MACHINE, generated locally and stored in ~/.gonext/instance.
+ *
+ * Deliberately NOT derived from the worker key: client mode exists so a second machine can
+ * reuse the same key without logging in, which makes the key — and therefore workerHostId —
+ * identical on both. Job pinning needs something that actually differs per machine, and this
+ * is it. Created once, then read; losing the file just mints a new id (jobs pinned to the
+ * old one would be orphaned, so it is written atomically-enough and never rewritten).
+ */
+const INSTANCE_FILE = join(DIR, "instance");
+
+export async function getInstanceId() {
+  try {
+    const id = String(await readFile(INSTANCE_FILE, "utf8")).trim();
+    if (id) return id;
+  } catch {
+    /* first run */
+  }
+  const { randomUUID } = await import("node:crypto");
+  const id = randomUUID();
+  try {
+    await mkdir(DIR, { recursive: true });
+    await writeFile(INSTANCE_FILE, id + "\n", { encoding: "utf8", mode: 0o600 });
+  } catch {
+    /* not fatal — an in-memory id still separates this run from another machine */
+  }
+  return id;
+}
+
+/** True when this machine is marked client-only. */
+export async function isClientMode() {
+  return (await readPrefs()).clientMode === true;
+}
+
+/** Mark (or unmark) this machine as client-only. Read-merge-write. */
+export async function setClientMode(on) {
+  const prefs = await readPrefs();
+  prefs.clientMode = Boolean(on);
+  prefs.updatedAt = new Date().toISOString();
+  await mkdir(DIR, { recursive: true });
+  await writeFile(PREFS_FILE, JSON.stringify(prefs, null, 2) + "\n");
+  return PREFS_FILE;
+}
+
+/**
+ * The coding model's context window, as stated by the user (`/context-window`). 0 = not set.
+ *
+ * PER MACHINE, not per account, and that is a compromise worth naming. The window is really a
+ * property of the MODEL, so the account would be the tidier home — but writing it there means a
+ * new allow-listed settings field and therefore an API publish before it works anywhere, and
+ * this exists precisely because a probe cannot learn the number from a hosted endpoint. A file
+ * on the machine that needs it takes effect on the next turn. Set it once per machine; the
+ * env var still wins for anyone scripting it.
+ */
+export async function getCodingContextWindow() {
+  const v = Number((await readPrefs()).codingContextWindow ?? 0);
+  return Number.isFinite(v) && v > 4096 ? Math.floor(v) : 0;
+}
+
+/**
+ * Store it, or clear it with 0/null. Rejects anything at or below 4096 rather than storing it.
+ *
+ * A window set too HIGH is worse than unknown — the model refuses mid-turn instead of
+ * compacting early — and one set absurdly LOW compacts a turn into uselessness. Both are
+ * refused at the door so a typo cannot become a budget.
+ */
+export async function setCodingContextWindow(tokens) {
+  const n = Number(tokens);
+  // CLEAR IS AN EXPLICIT SET, not "anything falsy". `!tokens` also catches NaN and false, so
+  // setCodingContextWindow(NaN) — a parse that failed — silently WIPED the setting instead of
+  // being refused. Garbage must not be able to unset a working value.
+  const clear = tokens === 0 || tokens === "0" || tokens === null || tokens === undefined
+    || tokens === "";
+  if (!clear && (!Number.isFinite(n) || n <= 4096)) return null;
+  const prefs = await readPrefs();
+  if (clear) delete prefs.codingContextWindow;
+  else prefs.codingContextWindow = Math.floor(n);
+  prefs.updatedAt = new Date().toISOString();
+  await mkdir(DIR, { recursive: true });
+  await writeFile(PREFS_FILE, JSON.stringify(prefs, null, 2) + "\n");
+  return clear ? 0 : Math.floor(n);
+}
+
+function pidAlive(pid) {
+  if (!pid || !Number.isFinite(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM = the process exists but we can't signal it (still "alive" for our purposes).
+    return e && e.code === "EPERM";
+  }
+}
+
+function psList() {
+  return new Promise((resolve) => {
+    execFile(
+      // Windows has no `ps` — the command and its parsing live in platform-tools.mjs so the
+      // difference is in one place rather than at every call site (#157).
+      PROC_LIST.cmd,
+      PROC_LIST.args,
+      { maxBuffer: 8 * 1024 * 1024 },
+      (err, stdout) => {
+        if (err) return resolve([]);
+        const rows = [];
+        for (const line of String(stdout).split(/\r?\n/)) {
+          const m = line.trim().match(/^(\d+)\s+(.*)$/);
+          if (m) rows.push({ pid: Number(m[1]), cmd: m[2] });
+        }
+        resolve(rows);
+      }
+    );
+  });
+}
+
+/**
+ * PIDs of polling worker daemons currently running (excluding THIS process and any
+ * subcommand invocation). Catches a daemon started by GoTerminal / by hand, not just ours.
+ */
+export async function findRunningDaemonPids() {
+  const rows = await psList();
+  const self = process.pid;
+  return rows
+    .filter((r) => r.pid !== self)
+    .filter((r) => DAEMON_FILE_RE.test(r.cmd))
+    .filter((r) => !SUBCOMMANDS.some((sc) => new RegExp(`(\\s|/)${sc}(\\s|$)`).test(r.cmd)))
+    .map((r) => r.pid);
+}
+
+/**
+ * True when `pid` is actually a gu polling daemon (not an unrelated process that reused
+ * the PID). Reads that one pid's command line — cheap and exact (review M1).
+ */
+function pidIsGonextDaemon(pid) {
+  if (!pid || !Number.isFinite(pid)) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const one = processCommandCommand(pid);
+    execFile(one.cmd, one.args, (err, stdout) => {
+      const cmd = String(stdout || "").trim();
+      resolve(
+        !err &&
+          DAEMON_FILE_RE.test(cmd) &&
+          !SUBCOMMANDS.some((sc) => new RegExp(`(\\s|/)${sc}(\\s|$)`).test(cmd))
+      );
+    });
+  });
+}
+
+async function readPidFile() {
+  try {
+    const n = Number(String(await readFile(PID_FILE, "utf8")).trim());
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * { running, pids, pidFilePid }. The `ps` scan is the primary signal. The pidfile is trusted
+ * ONLY after VERIFYING that its PID is genuinely a gu daemon (review M1) — this both
+ * rescues the case where the full-table scan missed it and rejects a stale pidfile whose PID
+ * was reused by an unrelated process (which would otherwise wrongly suppress auto-start).
+ */
+/** Publish (or clear) the jobs this worker is running. Best-effort: never break a turn. */
+export async function writeBusyState(jobIds) {
+  const ids = Array.isArray(jobIds) ? jobIds.filter(Boolean) : [];
+  try {
+    if (!ids.length) {
+      await unlink(BUSY_FILE).catch(() => {});
+      return;
+    }
+    await mkdir(DIR, { recursive: true });
+    await writeFile(
+      BUSY_FILE,
+      JSON.stringify({ pid: process.pid, jobIds: ids, at: new Date().toISOString() }, null, 2)
+    );
+  } catch {
+    /* the turn matters more than the bookkeeping */
+  }
+}
+
+/**
+ * Is a turn running on this machine? → { busy, jobIds, pid } — busy false when nothing is.
+ *
+ * IGNORES A FILE WHOSE PROCESS IS GONE. A worker killed with -9 (or a machine that lost power)
+ * leaves this behind, and a stale file that made every later `stop` ask a question would be a
+ * worse bug than the one this prevents. The pid is the liveness test, so the file can only ever
+ * report on a process that still exists.
+ */
+export async function readBusyState() {
+  const none = { busy: false, jobIds: [], pid: null };
+  try {
+    const raw = JSON.parse(await readFile(BUSY_FILE, "utf8"));
+    const pid = Number(raw?.pid);
+    const jobIds = Array.isArray(raw?.jobIds) ? raw.jobIds.filter(Boolean) : [];
+    if (!Number.isFinite(pid) || pid <= 0 || !jobIds.length) return none;
+    if (!pidAlive(pid)) return none; // the worker is gone; the file is a leftover
+    return { busy: true, jobIds, pid };
+  } catch {
+    return none; // no file, unreadable, or malformed — all mean "nothing running"
+  }
+}
+
+export async function daemonStatus() {
+  const [pids, pidFilePid] = await Promise.all([findRunningDaemonPids(), readPidFile()]);
+  const pidFileIsDaemon =
+    pidFilePid != null && (pids.includes(pidFilePid) || (await pidIsGonextDaemon(pidFilePid)));
+  const allPids = pidFileIsDaemon && !pids.includes(pidFilePid) ? [...pids, pidFilePid] : pids;
+  return {
+    running: allPids.length > 0,
+    pids: allPids,
+    pidFilePid: pidFileIsDaemon ? pidFilePid : null,
+  };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Acquire an exclusive single-flight lock over the check→spawn window (review L2). O_EXCL
+ * (`wx`) is atomic, so of two concurrent starts exactly one wins. A lock left by a crashed
+ * start is stolen once it's older than LOCK_STALE_MS so it can never wedge startup.
+ * Returns a handle whose .release() removes the lock, or null if another start holds it.
+ */
+async function acquireStartLock() {
+  await mkdir(DIR, { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fh = await open(LOCK_FILE, "wx");
+      await fh.writeFile(String(process.pid), "utf8");
+      return {
+        release: async () => {
+          await fh.close().catch(() => {});
+          await unlink(LOCK_FILE).catch(() => {});
+        },
+      };
+    } catch (e) {
+      if (!e || e.code !== "EEXIST") throw e;
+      // Held by someone else — steal it only if it's stale (a crashed start), then retry.
+      let age = 0;
+      try {
+        age = Date.now() - (await stat(LOCK_FILE)).mtimeMs;
+      } catch {
+        age = LOCK_STALE_MS + 1; // vanished between EEXIST and stat → treat as free
+      }
+      if (age > LOCK_STALE_MS) {
+        await unlink(LOCK_FILE).catch(() => {});
+        continue; // retry the atomic create
+      }
+      return null; // a fresh lock → another start is genuinely in progress
+    }
+  }
+  return null;
+}
+
+/**
+ * Start the polling daemon DETACHED (survives the launching shell, logs to ~/.gonext/
+ * worker.log). No-op when one is already running (BC4). Concurrency-safe (L2): a lock
+ * serializes the check→spawn window so two simultaneous starts can't both spawn.
+ * Returns { started, pid?, pids }.
+ */
+export async function startDaemon() {
+  // Fast path: already running → no lock needed.
+  const pre = await daemonStatus();
+  if (pre.running) return { started: false, ...pre };
+  const lock = await acquireStartLock();
+  if (!lock) {
+    // A concurrent start holds the lock — let it win, then report the resulting state.
+    await sleep(700);
+    const s = await daemonStatus();
+    return { started: false, ...s };
+  }
+  try {
+    // Re-check UNDER the lock — the winner of a race must see the loser's daemon if it
+    // spawned in the gap (and vice-versa this is where the second caller no-ops).
+    const status = await daemonStatus();
+    if (status.running) return { started: false, ...status };
+    // spawnSurviving, not a bare detached spawn: on Windows an SSH session runs inside a JOB
+    // OBJECT and every process in it dies when the session ends. This daemon was the PROOF —
+    // started over SSH with the detached spawn it had always used, it was gone the moment the
+    // session closed, while the same code from a console window runs for days.
+    const res = await spawnSurviving({
+      // No env: the daemon reads worker.env itself, and spawnSurviving inherits the parent's
+      // environment on POSIX. Handing it process.env put HUNDREDS of variables into a Windows
+      // launcher script — including names cmd cannot set — and the script died before reaching
+      // the command. Pass extras, never the whole environment.
+      cmd: process.execPath,
+      args: [DAEMON_SCRIPT],
+      logFile: LOG_FILE,
+      taskName: "gu-worker-daemon",
+    });
+    if (res.pid) {
+      await writeFile(PID_FILE, String(res.pid), "utf8");
+      return { started: true, pid: res.pid, pids: [] };
+    }
+    // Task-launched: not our child, so wait for it to appear and record what it turned out
+    // to be. A pidfile that never gets written would make `stop` a no-op forever.
+    for (let i = 0; i < 20; i++) {
+      await sleep(250);
+      const pids = await findRunningDaemonPids();
+      if (pids.length) {
+        await writeFile(PID_FILE, String(pids[0]), "utf8");
+        return { started: true, pid: pids[0], pids };
+      }
+    }
+    return { started: true, pid: null, pids: [] };
+  } finally {
+    await lock.release();
+  }
+}
+
+/** Stop every running daemon (ours + any ps-found) and clear the pidfile. */
+export async function stopDaemon() {
+  const status = await daemonStatus();
+  const targets = new Set(status.pids);
+  if (status.pidFilePid) targets.add(status.pidFilePid);
+  let killed = 0;
+  for (const pid of targets) {
+    try {
+      process.kill(pid, "SIGTERM");
+      killed++;
+    } catch {
+      /* already gone */
+    }
+  }
+  try {
+    await unlink(PID_FILE);
+  } catch {
+    /* no pidfile */
+  }
+  return { killed };
+}
+
+/** Last `n` lines of the daemon log (empty string when none yet). */
+export async function tailLog(n = 40) {
+  try {
+    const txt = await readFile(LOG_FILE, "utf8");
+    const lines = txt.split("\n");
+    return lines.slice(Math.max(0, lines.length - n)).join("\n");
+  } catch {
+    return "";
+  }
+}