grok-telegram-bot 2.0.0

package/src/service/macos.ts

@@ -0,0 +1,101 @@
+/**
+ * macOS service controller — installs a launchd LaunchAgent that runs at login
+ * and is kept alive automatically.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runSafe } from "./platform.js";
+import type { LaunchSpec, ServiceController, ServiceResult } from "./types.js";
+
+const LABEL = "com.grok.telegrambot";
+
+function plistPath(): string {
+  return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+
+export const macosController: ServiceController = {
+  platform: "macos",
+
+  async install(spec) {
+    mkdirSync(join(homedir(), "Library", "LaunchAgents"), { recursive: true });
+    mkdirSync(spec.logsDir, { recursive: true });
+    const path = plistPath();
+    runSafe("launchctl", ["unload", "-w", path]); // ignore if not loaded
+    writeFileSync(path, plist(spec), "utf-8");
+    const r = runSafe("launchctl", ["load", "-w", path]);
+    return r.ok ? ok(`Installed and loaded LaunchAgent "${LABEL}".`) : fail(r.out);
+  },
+
+  async uninstall() {
+    runSafe("launchctl", ["unload", "-w", plistPath()]);
+    rmSync(plistPath(), { force: true });
+    return ok(`Removed LaunchAgent "${LABEL}".`);
+  },
+
+  async start() {
+    const r = runSafe("launchctl", ["start", LABEL]);
+    return r.ok ? ok("Started.") : fail(r.out);
+  },
+
+  async stop() {
+    const r = runSafe("launchctl", ["stop", LABEL]);
+    return r.ok ? ok("Stopped.") : fail(r.out);
+  },
+
+  async status() {
+    const r = runSafe("launchctl", ["list"]);
+    const line = r.out.split("\n").find((l) => l.includes(LABEL));
+    return ok(line ? `Loaded: ${line.trim()}` : "Not loaded.");
+  },
+};
+
+function plist(spec: LaunchSpec): string {
+  const args = [spec.nodePath, ...spec.args].map((a) => `    <string>${esc(a)}</string>`).join("\n");
+  const envEntries = Object.entries(spec.env ?? {});
+  const envBlock = envEntries.length
+    ? [
+        "  <key>EnvironmentVariables</key>",
+        "  <dict>",
+        ...envEntries.flatMap(([k, v]) => [`    <key>${esc(k)}</key>`, `    <string>${esc(v)}</string>`]),
+        "  </dict>",
+      ]
+    : [];
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    "  <key>Label</key>",
+    `  <string>${LABEL}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    args,
+    "  </array>",
+    ...envBlock,
+    "  <key>WorkingDirectory</key>",
+    `  <string>${esc(spec.cwd)}</string>`,
+    "  <key>RunAtLoad</key>",
+    "  <true/>",
+    "  <key>KeepAlive</key>",
+    "  <true/>",
+    "  <key>StandardOutPath</key>",
+    `  <string>${esc(spec.logFile)}</string>`,
+    "  <key>StandardErrorPath</key>",
+    `  <string>${esc(spec.logFile)}</string>`,
+    "</dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+}
+
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function ok(message: string): ServiceResult {
+  return { ok: true, message };
+}
+function fail(message: string): ServiceResult {
+  return { ok: false, message };
+}

package/src/service/platform.ts

@@ -0,0 +1,64 @@
+/**
+ * Platform detection, launch-spec construction, and a small command runner
+ * shared by the per-OS service controllers.
+ */
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { PROJECT_ROOT, INSTANCE_DIR } from "../config.js";
+
+export type Platform = "windows" | "linux" | "macos" | "unknown";
+
+export function detectPlatform(): Platform {
+  switch (process.platform) {
+    case "win32":
+      return "windows";
+    case "linux":
+      return "linux";
+    case "darwin":
+      return "macos";
+    default:
+      return "unknown";
+  }
+}
+
+import type { LaunchSpec } from "./types.js";
+
+/** Build the launch spec that runs the bot via the current node + tsx loader. */
+export function buildLaunchSpec(): LaunchSpec {
+  const logsDir = join(INSTANCE_DIR, "logs");
+  const args = ["--import", "tsx", join(PROJECT_ROOT, "src", "index.ts")];
+  // Run the code from the package dir (cwd below) so `tsx` resolves, but tell
+  // the bot where its .env/logs/data live. Only appended for a global install
+  // (instance dir differs) so in-place checkouts keep identical launch args.
+  if (INSTANCE_DIR !== PROJECT_ROOT) args.push("--instance", INSTANCE_DIR);
+  return {
+    id: "grok-telegram-bot",
+    displayName: "Grok Telegram Bot",
+    nodePath: process.execPath,
+    args,
+    cwd: PROJECT_ROOT,
+    // Tells the running bot it's under a supervisor (systemd/launchd) that
+    // relaunches on exit — so its auto-updater exits cleanly instead of
+    // re-exec'ing (which would double-run). Windows applies no env, so its
+    // Scheduled Task (no auto-restart) takes the re-exec path instead.
+    env: { GROK_TG_SUPERVISED: "1" },
+    logsDir,
+    logFile: join(logsDir, "grok-telegram-bot.log"),
+  };
+}
+
+/** Run a command, returning combined output. Throws on non-zero exit. */
+export function run(cmd: string, args: string[]): string {
+  return execFileSync(cmd, args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+}
+
+/** Run a command, swallowing errors and returning { ok, out }. */
+export function runSafe(cmd: string, args: string[]): { ok: boolean; out: string } {
+  try {
+    return { ok: true, out: run(cmd, args) };
+  } catch (e) {
+    const err = e as { stdout?: Buffer | string; stderr?: Buffer | string; message?: string };
+    const out = String(err.stdout ?? "") + String(err.stderr ?? "") || err.message || "failed";
+    return { ok: false, out };
+  }
+}

package/src/service/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Cross-platform service (daemon) abstraction.
+ */
+
+export interface LaunchSpec {
+  /** Internal service id, e.g. "grok-telegram-bot". */
+  id: string;
+  /** Human-readable name. */
+  displayName: string;
+  /** Absolute path to the node binary that should run the bot. */
+  nodePath: string;
+  /** Arguments after the node binary (tsx loader + entry file). */
+  args: string[];
+  /** Working directory (the installed bot folder). */
+  cwd: string;
+  /** Extra environment variables for the service process. */
+  env?: Record<string, string>;
+  /** Absolute log file path. */
+  logFile: string;
+  /** Log directory. */
+  logsDir: string;
+}
+
+export interface ServiceResult {
+  ok: boolean;
+  message: string;
+}
+
+export interface ServiceController {
+  readonly platform: string;
+  install(spec: LaunchSpec): Promise<ServiceResult>;
+  uninstall(spec: LaunchSpec): Promise<ServiceResult>;
+  start(spec: LaunchSpec): Promise<ServiceResult>;
+  stop(spec: LaunchSpec): Promise<ServiceResult>;
+  status(spec: LaunchSpec): Promise<ServiceResult>;
+}

package/src/service/windows.ts

@@ -0,0 +1,198 @@
+/**
+ * Windows service controller — runs the bot at logon. Preferred mechanism is a
+ * hidden ONLOGON Scheduled Task, but registering a logon-triggered task needs
+ * admin, so from a normal (non-elevated) terminal we fall back to a launcher in
+ * the per-user Startup folder — both run a small .vbs that starts node with no
+ * console window; the app logs to a file. Stop precisely targets our node
+ * process by command line, so it works regardless of how it was launched.
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { runSafe } from "./platform.js";
+import type { LaunchSpec, ServiceController, ServiceResult } from "./types.js";
+
+const TASK = "GrokTelegramBot";
+/** Launcher dropped in the per-user Startup folder when no admin is available. */
+const STARTUP_VBS = "GrokTelegramBot.vbs";
+
+/** The per-user Startup folder (runs at logon for the current user, no admin).
+ *  Undefined only if APPDATA is unset (e.g. running with no roaming profile). */
+function startupDir(): string | undefined {
+  const appData = process.env.APPDATA;
+  return appData ? join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup") : undefined;
+}
+
+function startupVbsPath(): string | undefined {
+  const dir = startupDir();
+  return dir ? join(dir, STARTUP_VBS) : undefined;
+}
+
+/** Remove a leftover Startup-folder launcher (e.g. from an earlier non-elevated
+ *  install) so a task-based install never double-launches the bot at logon. */
+function removeStartupLauncher(): void {
+  const p = startupVbsPath();
+  if (p) rmSync(p, { force: true });
+}
+
+/** Canonical launcher in the bot folder (the Scheduled Task points at it). */
+function vbsPath(spec: LaunchSpec): string {
+  return join(spec.cwd, "run-service.vbs");
+}
+
+/** True when our hidden Scheduled Task is registered. */
+function taskInstalled(): boolean {
+  return runSafe("schtasks", ["/Query", "/TN", TASK]).ok;
+}
+
+/** True when a bot process matching this spec is currently running. Launch
+ *  paths use this to avoid starting a second instance — two pollers on one
+ *  bot token make Telegram return 409 Conflict. */
+function isRunning(spec: LaunchSpec): boolean {
+  const proc = runSafe("powershell", ["-NoProfile", "-Command", countScript(entryOf(spec))]);
+  return proc.ok && /[1-9]\d*/.test(proc.out.trim());
+}
+
+export const windowsController: ServiceController = {
+  platform: "windows",
+
+  async install(spec) {
+    mkdirSync(spec.logsDir, { recursive: true });
+    const vbs = vbsPath(spec);
+    writeFileSync(vbs, vbsLauncher(spec), "utf-8");
+
+    // Preferred: a hidden ONLOGON Scheduled Task. Registering a *logon-triggered*
+    // task is a privileged operation, so /Create succeeds only from an elevated
+    // (admin) terminal. From a normal terminal it returns "Access is denied".
+    runSafe("schtasks", ["/Delete", "/F", "/TN", TASK]); // replace if present
+    const res = runSafe("schtasks", [
+      "/Create",
+      "/F",
+      "/SC",
+      "ONLOGON",
+      "/TN",
+      TASK,
+      "/TR",
+      `wscript.exe "${vbs}"`,
+    ]);
+    if (res.ok) {
+      removeStartupLauncher(); // avoid a leftover launcher double-starting the bot
+      if (!isRunning(spec)) runSafe("schtasks", ["/Run", "/TN", TASK]);
+      return ok(`Installed scheduled task "${TASK}" (starts at logon) and launched it.`);
+    }
+
+    // A task may still exist that we just couldn't overwrite (e.g. created by an
+    // earlier elevated install). Reuse it rather than ALSO adding a Startup
+    // launcher, which would double-launch the bot at logon (409 Conflict).
+    if (taskInstalled()) {
+      removeStartupLauncher();
+      if (!isRunning(spec)) runSafe("schtasks", ["/Run", "/TN", TASK]);
+      return ok(`Scheduled task "${TASK}" already exists; launched it. (Re-run elevated to recreate it.)`);
+    }
+
+    // Fallback (no admin — the common case): drop the launcher in the per-user
+    // Startup folder. It runs hidden at every logon with no elevation.
+    const startupVbs = startupVbsPath();
+    const dir = startupDir();
+    if (!startupVbs || !dir) {
+      return fail(
+        `Could not create the logon task (${res.out.trim()}) and no per-user Startup folder is available. ` +
+          `Re-run "grok-tg install" from an elevated terminal (Run as administrator).`,
+      );
+    }
+    try {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(startupVbs, vbsLauncher(spec), "utf-8");
+    } catch (e) {
+      return fail(`Startup-folder install failed: ${(e as Error).message}`);
+    }
+    if (!isRunning(spec)) runSafe("wscript.exe", [startupVbs]); // launch now
+    return ok(
+      `Installed via the Startup folder — starts hidden at logon, no admin needed — and launched it.\n` +
+        `(Tip: run "grok-tg install" from an elevated terminal to use a hidden Scheduled Task instead.)`,
+    );
+  },
+
+  async uninstall(spec) {
+    await this.stop(spec);
+    runSafe("schtasks", ["/Delete", "/F", "/TN", TASK]); // best-effort (may not exist)
+    rmSync(vbsPath(spec), { force: true });
+    const startupVbs = startupVbsPath();
+    if (startupVbs) rmSync(startupVbs, { force: true });
+    return ok(`Removed "${TASK}" (scheduled task and/or Startup launcher).`);
+  },
+
+  async start(spec) {
+    if (isRunning(spec)) return ok("Already running.");
+    if (taskInstalled()) {
+      const res = runSafe("schtasks", ["/Run", "/TN", TASK]);
+      return res.ok ? ok("Started.") : fail(res.out);
+    }
+    const startupVbs = startupVbsPath();
+    if (startupVbs && existsSync(startupVbs)) {
+      runSafe("wscript.exe", [startupVbs]);
+      return ok("Started.");
+    }
+    return fail(`Not installed. Run "grok-tg install" first.`);
+  },
+
+  async stop(spec) {
+    runSafe("schtasks", ["/End", "/TN", TASK]); // best-effort if task-based
+    const res = runSafe("powershell", ["-NoProfile", "-Command", killScript(entryOf(spec))]);
+    return ok(`Stopped. ${res.out.trim()}`);
+  },
+
+  async status(spec) {
+    const installedTask = taskInstalled();
+    const startupVbs = startupVbsPath();
+    const installedStartup = !!startupVbs && existsSync(startupVbs);
+    const installed = installedTask || installedStartup;
+    const running = isRunning(spec);
+    const how = installedTask ? "scheduled task" : installedStartup ? "Startup folder" : "—";
+    const detail = installedTask
+      ? `\n${runSafe("schtasks", ["/Query", "/TN", TASK, "/FO", "LIST"]).out.trim()}`
+      : installedStartup
+        ? `\nLauncher: ${startupVbs}`
+        : "";
+    return ok(
+      `Installed: ${installed ? `yes (${how})` : "no"} | Running: ${running ? "yes" : "no"}${detail}`,
+    );
+  },
+};
+
+/** The bot entry file — unique enough to identify the bot process. It may be
+ *  followed by trailing args (e.g. `--instance <dir>`), so find it explicitly. */
+function entryOf(spec: LaunchSpec): string {
+  return (
+    spec.args.find((a) => a.endsWith("index.ts")) ?? spec.args[spec.args.length - 1] ?? spec.cwd
+  );
+}
+
+function vbsLauncher(spec: LaunchSpec): string {
+  const cmd = `""${spec.nodePath}"" ${spec.args.map((a) => `""${a}""`).join(" ")}`;
+  return [
+    'Set sh = CreateObject("WScript.Shell")',
+    `sh.CurrentDirectory = "${spec.cwd}"`,
+    `sh.Run "${cmd}", 0, False`,
+  ].join("\r\n");
+}
+
+function killScript(entry: string): string {
+  const safe = entry.replace(/'/g, "''");
+  return [
+    `$p = Get-CimInstance Win32_Process -Filter "Name='node.exe'" | Where-Object { $_.CommandLine -like '*${safe}*' };`,
+    `$p | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue };`,
+    `"killed " + (@($p).Count)`,
+  ].join(" ");
+}
+
+function countScript(entry: string): string {
+  const safe = entry.replace(/'/g, "''");
+  return `@(Get-CimInstance Win32_Process -Filter "Name='node.exe'" | Where-Object { $_.CommandLine -like '*${safe}*' }).Count`;
+}
+
+function ok(message: string): ServiceResult {
+  return { ok: true, message };
+}
+function fail(message: string): ServiceResult {
+  return { ok: false, message };
+}

package/src/sessions/history.ts

@@ -0,0 +1,225 @@
+/**
+ * History parser — turns a session's .jsonl event log into readable entries.
+ * Reads only the tail of large logs to stay fast.
+ */
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { extractProgress, PROGRESS_DIRECTIVE } from "../render/progress.js";
+import type { HistoryEntry, HistoryRole } from "./types.js";
+
+const TAIL_WINDOWS = [256 * 1024, 1024 * 1024, 4 * 1024 * 1024]; // grow until entries found
+
+interface RawEvent {
+  kind?: string;
+  data?: {
+    content?: Array<{ kind?: string; data?: unknown; text?: unknown }>;
+    meta?: { timestamp?: number };
+    name?: string;
+    tool_name?: string;
+  };
+}
+
+/** Parse the most recent `maxEntries` history entries from a session log. */
+export function readHistory(jsonlPath: string, maxEntries = 20): HistoryEntry[] {
+  for (const window of TAIL_WINDOWS) {
+    const entries = parseTail(jsonlPath, window, maxEntries);
+    if (entries.length > 0) return entries;
+  }
+  return [];
+}
+
+/** Current byte size of a session log (0 if missing). */
+export function jsonlSize(jsonlPath: string): number {
+  try {
+    return statSync(jsonlPath).size;
+  } catch {
+    return 0;
+  }
+}
+
+/** Last-write time of a session log in epoch ms (0 if missing). */
+export function jsonlMtimeMs(jsonlPath: string): number {
+  try {
+    return statSync(jsonlPath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/** The first user prompt in a session log (read from the start), or "". */
+export function readFirstPrompt(jsonlPath: string, maxBytes = 256 * 1024): string {
+  let size: number;
+  try {
+    size = statSync(jsonlPath).size;
+  } catch {
+    return "";
+  }
+  if (size === 0) return "";
+  const length = Math.min(size, maxBytes);
+  const fd = openSync(jsonlPath, "r");
+  try {
+    const buf = Buffer.alloc(length);
+    readSync(fd, buf, 0, length, 0);
+    for (const line of buf.toString("utf-8").split("\n")) {
+      const e = parseEventLine(line);
+      if (e && e.role === "user" && e.text.trim()) return e.text;
+    }
+    return "";
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Read the entries appended after `fromByte` (the "unread" since last seen).
+ * Returns the parsed entries and the new end-of-file byte offset. Grok appends
+ * whole newline-terminated JSON objects, so `fromByte` is always a line boundary.
+ */
+export function readEntriesFrom(jsonlPath: string, fromByte: number): { entries: HistoryEntry[]; size: number } {
+  const size = jsonlSize(jsonlPath);
+  if (size <= fromByte || size === 0) return { entries: [], size };
+  const length = size - fromByte;
+  const fd = openSync(jsonlPath, "r");
+  try {
+    const buf = Buffer.alloc(length);
+    readSync(fd, buf, 0, length, fromByte);
+    const lines = buf.toString("utf-8").split("\n").filter((l) => l.trim().length > 0);
+    const entries: HistoryEntry[] = [];
+    for (const line of lines) {
+      const e = parseEventLine(line);
+      if (e) entries.push(e);
+    }
+    return { entries, size };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function parseTail(jsonlPath: string, window: number, maxEntries: number): HistoryEntry[] {
+  const text = readTail(jsonlPath, window);
+  if (!text) return [];
+
+  const lines = text.split("\n").filter((l) => l.trim().length > 0);
+  const entries: HistoryEntry[] = [];
+
+  for (const line of lines) {
+    const entry = parseEventLine(line);
+    if (entry) entries.push(entry);
+  }
+
+  return entries.slice(-maxEntries);
+}
+
+/** Parse a single .jsonl event line into a history entry (or undefined). */
+export function parseEventLine(line: string): HistoryEntry | undefined {
+  const trimmed = line.trim();
+  if (!trimmed) return undefined;
+  let ev: RawEvent;
+  try {
+    ev = JSON.parse(trimmed) as RawEvent;
+  } catch {
+    return undefined;
+  }
+  return toEntry(ev);
+}
+
+/** Build a compact plain-text transcript from history entries (for priming). */
+export function buildTranscript(entries: HistoryEntry[], perEntryMax = 600): string {
+  const label: Record<string, string> = {
+    user: "User",
+    assistant: "Assistant",
+    tool: "Tool",
+    system: "System",
+  };
+  return entries
+    .map((e) => {
+      const text = e.text.length > perEntryMax ? e.text.slice(0, perEntryMax) + " …" : e.text;
+      return `${label[e.role] ?? e.role}: ${text}`;
+    })
+    .join("\n");
+}
+
+function toEntry(ev: RawEvent): HistoryEntry | undefined {
+  const role = roleOf(ev.kind);
+  if (!role) return undefined;
+
+  const text = cleanStoredText(extractText(ev.data?.content));
+  const tool = ev.data?.tool_name || ev.data?.name;
+  if (!text && !tool) return undefined;
+
+  return {
+    role,
+    text: text || (tool ? `(${tool})` : ""),
+    tool,
+    timestamp: ev.data?.meta?.timestamp,
+  };
+}
+
+/** Strip the `{progress: N%}` markers (any role) and the appended progress
+ *  directive (user prompts) from persisted text so history / unread / previews
+ *  / fork-priming never surface the raw plumbing. */
+function cleanStoredText(text: string): string {
+  if (!text) return text;
+  let t = extractProgress(text).cleaned;
+  if (t.includes(PROGRESS_DIRECTIVE)) t = t.split(PROGRESS_DIRECTIVE).join("").trim();
+  return t;
+}
+
+function roleOf(kind?: string): HistoryRole | undefined {
+  switch (kind) {
+    case "Prompt":
+    case "UserMessage":
+      return "user";
+    case "AssistantMessage":
+    case "Response":
+      return "assistant";
+    case "ToolUse":
+    case "ToolUseResults":
+      return "tool";
+    default:
+      return undefined;
+  }
+}
+
+function extractText(content?: Array<{ kind?: string; data?: unknown; text?: unknown }>): string {
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (block.kind === "text") {
+      if (typeof block.data === "string") parts.push(block.data);
+      else if (block.data && typeof (block.data as { text?: unknown }).text === "string") {
+        parts.push((block.data as { text: string }).text);
+      }
+    } else if (typeof block.text === "string") {
+      parts.push(block.text);
+    }
+  }
+  return parts.join("").trim();
+}
+
+/** Read up to `maxBytes` from the end of a file as UTF-8 text. */
+function readTail(path: string, maxBytes: number): string {
+  let size: number;
+  try {
+    size = statSync(path).size;
+  } catch {
+    return "";
+  }
+  if (size === 0) return "";
+
+  const start = Math.max(0, size - maxBytes);
+  const length = size - start;
+  const fd = openSync(path, "r");
+  try {
+    const buf = Buffer.alloc(length);
+    readSync(fd, buf, 0, length, start);
+    let text = buf.toString("utf-8");
+    // If we started mid-file, drop the partial first line.
+    if (start > 0) {
+      const nl = text.indexOf("\n");
+      if (nl !== -1) text = text.slice(nl + 1);
+    }
+    return text;
+  } finally {
+    closeSync(fd);
+  }
+}

package/src/sessions/process.ts

@@ -0,0 +1,30 @@
+/**
+ * Process control helpers for Grok sessions: force-killing the process that
+ * holds a session's `.lock` (its `lockPid`). Shared by /killall and the
+ * per-session kill button so the behaviour stays identical.
+ */
+import { execFileSync } from "node:child_process";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("sessions:process");
+
+/**
+ * Force-kill a process by PID — and its child tree on Windows (`taskkill /T`),
+ * which a `grok` session may have spawned (shells, tools). Returns whether
+ * the kill command was issued without throwing. A non-existent PID or one we
+ * may not signal counts as failure (callers report it).
+ */
+export function killPid(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    if (process.platform === "win32") {
+      execFileSync("taskkill", ["/F", "/T", "/PID", String(pid)], { stdio: "ignore" });
+    } else {
+      process.kill(pid, "SIGKILL");
+    }
+    return true;
+  } catch (e) {
+    log.debug(`kill ${pid} failed:`, (e as Error).message);
+    return false;
+  }
+}