@opennous/cli 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @opennous/cli changelog
 
+## 0.17.1
+
+### Fixed: a sign-out or an outage no longer fails your reads
+
+Signed out of Claude or Codex, or the model not answering: `runner` and `backfill` now wait instead
+of marking every conversation unreadable, and tell you what to run. At your plan's limit they wait
+until the reset time the limit message names, not a fixed 30 minutes (GET-1303).
+
+## 0.17.0
+
+### Added: `runner`, reading on your own plan all the time
+
+`backfill` reads your history once. `runner` keeps going: it reads your new calls and email on your
+own Claude or ChatGPT plan as they come in, with the same no-tools sandbox. `runner install` starts it
+now and every time you log in (launchd on macOS, systemd on Linux); `runner status` and
+`runner uninstall` check on it and remove it. When your plan hits its limit it waits and carries on
+by itself. The app's Settings → Your plan shows it as connected (GET-1289).
+
 ## 0.16.0
 
 ### Added: your Intelligence report after `backfill`

package/README.md

@@ -12,6 +12,17 @@ npx @opennous/cli@latest init
 
 Then tell your agent *"set up my Ownable workspace"* — it reads your project, finds your ICP (or drafts one), and syncs it. On self-host, add `--url https://api.yourdomain.com`.
 
+## Read on your own plan
+
+Reading your calls and email runs on your own Claude Code or Codex plan, not on credits:
+
+```bash
+npx @opennous/cli@latest backfill          # your history, once
+npx @opennous/cli@latest runner install    # what's new, from now on; starts at login
+```
+
+`runner status` says whether it's running, `runner uninstall` stops it. Settings → AI subscription in the app shows each runner and what's waiting to be read.
+
 ## Event tracking
 
 `nous track init` detects your stack (Next.js, Node, Python), writes a small `nous.js` (or `nous.py`) module with three helpers, and updates your `.env`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opennous/cli",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Ownable CLI — set up Ownable, connect it to your coding agent, and read the Context API from your terminal",
   "type": "module",
   "bin": {

package/src/backfill.js

@@ -53,14 +53,16 @@ export function parseAnswer(agent, out) {
     if (j.is_error) throw new Error(String(j.result));
     return { text: j.result, usage: { input_tokens: j.usage?.input_tokens ?? 0, output_tokens: j.usage?.output_tokens ?? 0 } };
   }
-  let text = "", usage = null;
+  let text = "", usage = null, error = null;
   for (const line of out.split("\n")) {
     let e;
     try { e = JSON.parse(line); } catch { continue; }
     if (e.item?.type === "agent_message") text = e.item.text;
     if (e.usage) usage = e.usage;
+    // An error event says why (a limit, a sign-out), which the runner needs (GET-1303).
+    if (e.type === "error" || e.type === "turn.failed") error = e.message ?? e.error?.message ?? error;
   }
-  if (!text) throw new Error("codex gave no answer");
+  if (!text) throw new Error(error || "codex gave no answer");
   return { text, usage: { input_tokens: usage?.input_tokens ?? 0, output_tokens: usage?.output_tokens ?? 0 } };
 }
 
@@ -69,6 +71,55 @@ export function isPlanLimit(message) {
   return /usage limit|rate.?limit|hit your .*limit|limit reached|too many requests|\b429\b|quota/i.test(String(message));
 }
 
+/**
+ * What an error says about the plan, not the call (GET-1303): 'limit' (passes at its reset),
+ * 'signed_out' (passes when the person signs in again), 'outage' (the model is down; passes by
+ * itself), or null for a bad call. A call that fails for any of these is not unreadable, so it must
+ * not be marked failed. Pure.
+ */
+export function troubleOf(message) {
+  const m = String(message ?? "");
+  if (isPlanLimit(m)) return "limit";
+  if (/not logged in|please (run )?\/?login|log ?in again|sign ?in again|invalid api key|authentication[_ ](error|failed)|oauth token|token (has )?expired|unauthori[sz]ed|\b401\b|codex login/i.test(m)) return "signed_out";
+  if (/overloaded|\b529\b|\b503\b|\b502\b|service unavailable|internal server error|api error: 5\d\d|econnreset|etimedout|enotfound|network error|socket hang up|stream disconnected/i.test(m)) return "outage";
+  return null;
+}
+
+const MIN_WAIT_MS = 60_000;
+const MAX_WAIT_MS = 7 * 86_400_000;
+
+/**
+ * When the plan's limit lifts, from its own message (GET-1303), or null when it doesn't say.
+ * Claude: "…limit reached|1731470400" or "resets 3pm" / "resets 3:30pm". Codex: "try again in 2 hours
+ * 5 minutes" or "try again at 3:04 PM". Clock times are this machine's local time, the next one to
+ * come. A minute is added, so the retry lands after the reset, not on it. Pure.
+ */
+export function resetAt(message, now = Date.now()) {
+  const m = String(message ?? "");
+  const clamp = (t) => (Number.isFinite(t) && t > now ? Math.min(now + MAX_WAIT_MS, Math.max(now + MIN_WAIT_MS, t + 60_000)) : null);
+  const unix = /\|(\d{10})\b/.exec(m);
+  if (unix) return clamp(Number(unix[1]) * 1000);
+  const inMatch = /try again in\s+(?:(\d+)\s*d(?:ays?)?\s*)?(?:(\d+)\s*h(?:ours?|rs?)?\s*)?(?:(\d+)\s*m(?:in(?:utes?)?)?)?/i.exec(m);
+  if (inMatch && (inMatch[1] || inMatch[2] || inMatch[3])) {
+    const ms = ((+inMatch[1] || 0) * 24 * 60 + (+inMatch[2] || 0) * 60 + (+inMatch[3] || 0)) * 60_000;
+    return clamp(now + ms);
+  }
+  const clock = /(?:resets?|try again at)\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?/i.exec(m);
+  if (clock) {
+    let h = Number(clock[1]);
+    const min = Number(clock[2] ?? 0);
+    const ap = clock[3]?.toLowerCase();
+    if (h > 23 || min > 59 || (ap && (h < 1 || h > 12))) return null;
+    if (ap === "pm" && h < 12) h += 12;
+    if (ap === "am" && h === 12) h = 0;
+    const d = new Date(now);
+    d.setHours(h, min, 0, 0);
+    if (d.getTime() <= now) d.setDate(d.getDate() + 1);
+    return clamp(d.getTime());
+  }
+  return null;
+}
+
 export function detectAgents(run = spawnSync) {
   const found = [];
   if (run("claude", ["auth", "status"], { encoding: "utf8" }).status === 0) found.push("claude");
@@ -167,9 +218,19 @@ export async function runBackfill({ api, agent, jobId, run, sleep, log, now = Da
         answered++;
         return;
       } catch (err) {
-        if (isPlanLimit(err.message)) {
-          if (now() >= waitUntil) log(`Your ${agent} plan hit its limit. Waiting ${Math.round(limitWaitMs / 60000)} minutes, then carrying on. You can stop now and run this again later instead.`);
-          waitUntil = Math.max(waitUntil, now() + limitWaitMs);
+        // A limit, a sign-out or an outage (GET-1303) is not this call's fault: wait, then try it again.
+        const trouble = troubleOf(err.message);
+        if (trouble) {
+          const until = trouble === "limit" ? (resetAt(err.message, now()) ?? now() + limitWaitMs) : now() + 5 * 60_000;
+          if (now() >= waitUntil) {
+            const mins = Math.max(1, Math.round((until - now()) / 60000));
+            log(trouble === "signed_out"
+              ? `You're signed out of ${agent}. Run \`${agent === "codex" ? "codex login" : "claude"}\` in another terminal and sign in; this carries on by itself.`
+              : trouble === "outage"
+                ? `${agent} isn't answering right now. Trying again in ${mins} minutes.`
+                : `Your ${agent} plan hit its limit. Waiting ${mins} minutes, until it resets, then carrying on. You can stop now and run this again later instead.`);
+          }
+          waitUntil = Math.max(waitUntil, until);
           continue;
         }
         if (attempt >= RETRIES) { await api.answer(call.id, { error: err.message }); return; }

package/src/index.js

@@ -650,6 +650,118 @@ program
     if (reportUrl) console.log(`Your Intelligence report is ready: ${reportUrl}`);
   });
 
+// `nous runner` (GET-1293): keeps reading your new calls and email on your own plan. `install`
+// starts it at login; the app's "Your plan" page shows it as connected once it has polled.
+const runnerCmd = program
+  .command("runner")
+  .description("Keep reading your new calls and email on your own Claude or ChatGPT plan")
+  .option("--agent <agent>", "claude or codex (default: whichever you're signed in to)")
+  .option("--workspace <id>", "the workspace to read; the app's command fills this in")
+  .option("--url <url>", "API base URL (default: https://api.opennous.cloud)")
+  .action(async (opts) => {
+    const { detectAgents, liveRun, NO_AGENT } = await import("./backfill.js");
+    const { runRunner } = await import("./runner.js");
+    const agent = await pickAgent(opts.agent, detectAgents, NO_AGENT);
+    const key = await runnerKey(opts);
+    const api = apiClient(key);
+    const service = process.env.NOUS_RUNNER_SERVICE === "1";
+    const stamp = (line) => (service ? `${new Date().toISOString()} ${line}` : line);
+    console.log(stamp(`Reading on your ${agent} plan. ${service ? "" : "Stop with Ctrl-C; `nous runner install` keeps it going on its own."}`.trim()));
+    await runRunner({
+      agent, version, run: liveRun(), log: (l) => console.log(stamp(l)),
+      sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+      api: {
+        poll: (body) => api.softPost("/v2/runner/poll", body),
+        answer: (id, body) => api.softPost(`/v2/runner/calls/${id}`, body),
+      },
+    });
+  });
+
+runnerCmd
+  .command("install")
+  .description("Start the runner now and every time you log in")
+  .option("--agent <agent>", "claude or codex (default: whichever you're signed in to)")
+  .option("--workspace <id>", "the workspace to read; the app's command fills this in")
+  .option("--url <url>", "API base URL (default: https://api.opennous.cloud)")
+  .action(async (opts) => {
+    const { detectAgents, NO_AGENT } = await import("./backfill.js");
+    const { installService } = await import("./runner.js");
+    const agent = await pickAgent(opts.agent, detectAgents, NO_AGENT);
+    const key = await runnerKey(opts);
+    // One poll before installing, so a bad key or plan fails here and not silently in the background.
+    try {
+      await apiClient(key).softPost("/v2/runner/poll", { agent, host: hostname(), version, limit: 0 });
+    } catch (e) {
+      console.error(`Couldn't connect: ${e.message}`);
+      process.exit(1);
+    }
+    try {
+      const where = installService({ agent, workspace: opts.workspace ?? null });
+      console.log(`Connected. The runner reads on your ${agent} plan and starts every time you log in.`);
+      if (where.log) console.log(`Log: ${where.log}`);
+      console.log("Check on it with `npx @opennous/cli@latest runner status`. Stop it with `npx @opennous/cli@latest runner uninstall`.");
+    } catch (e) {
+      console.error(e.message);
+      process.exit(1);
+    }
+  });
+
+runnerCmd
+  .command("uninstall")
+  .description("Stop the runner and stop it starting at login")
+  .action(async () => {
+    const { uninstallService } = await import("./runner.js");
+    console.log(uninstallService() ? "Stopped. It won't start at login any more." : "No runner is installed on this machine.");
+  });
+
+runnerCmd
+  .command("status")
+  .description("Whether the runner is installed and running on this machine")
+  .action(async () => {
+    const { serviceStatus } = await import("./runner.js");
+    const s = serviceStatus();
+    if (!s.installed) { console.log("Not installed. Run `npx @opennous/cli@latest runner install`."); return; }
+    console.log(s.running ? "Running." : "Installed, but not running right now.");
+    if (s.log) console.log(`Log: ${s.log}`);
+  });
+
+/** The agent to read with: the one asked for, or whichever is signed in. Exits with what to do. */
+async function pickAgent(asked, detectAgents, noAgent) {
+  const agents = detectAgents();
+  const agent = asked ?? agents[0];
+  if (!agent || !agents.includes(agent)) {
+    console.error(asked ? `You're not signed in to ${asked}. Run \`${asked === "codex" ? "codex login" : "claude"}\` first.` : noAgent);
+    process.exit(1);
+  }
+  return agent;
+}
+
+/** The key the runner reads with: for --workspace when given (signing in to it if needed), else the saved one. */
+async function runnerKey(opts) {
+  if (opts.url) writeConfig({ ...readConfig(), apiUrl: opts.url });
+  if (!hasKey()) await browserLogin(opts.url);
+  const cfg = readConfig();
+  const apiUrl = opts.url || process.env.NOUS_API_URL || cfg.apiUrl || "https://api.opennous.cloud";
+  let key = process.env.NOUS_API_KEY || cfg.apiKey;
+  if (!opts.workspace) return key;
+  const kept = cfg.workspaceKeys?.[opts.workspace];
+  for (const k of [key, kept].filter(Boolean)) {
+    if ((await fetchWhoami(apiUrl, k))?.workspace?.id === opts.workspace) {
+      if (k !== kept) writeConfig({ ...cfg, workspaceKeys: { ...cfg.workspaceKeys, [opts.workspace]: k } });
+      return k;
+    }
+  }
+  console.log("Sign in to the workspace this runner is for.");
+  key = await browserLogin(opts.url, { save: false });
+  if ((await fetchWhoami(apiUrl, key))?.workspace?.id !== opts.workspace) {
+    console.error("That sign-in is for another workspace. Open the right workspace in the app, then run this again.");
+    process.exit(1);
+  }
+  const saved = readConfig();
+  writeConfig({ ...saved, workspaceKeys: { ...saved.workspaceKeys, [opts.workspace]: key } });
+  return key;
+}
+
 program
   .command("logout")
   .description("Sign out — remove the saved API key")

package/src/runner.js

@@ -0,0 +1,224 @@
+// `nous runner` (GET-1293): reads your new calls and email on your own Claude or ChatGPT plan, all
+// the time. It is `nous backfill`'s loop that never ends: it polls the server, answers each model
+// call with the `claude` or `codex` CLI you are signed in to (no tools, the same sandbox as backfill:
+// a call's prompt holds other people's words), and posts the answer back. The server decides what to
+// read; this only answers. `nous runner install` starts it at login, so it keeps going on its own.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, hostname, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { commandFor, parseAnswer, troubleOf, resetAt } from "./backfill.js";
+
+export const WORKERS = 3;
+/** Busy: there is a read going, so ask again soon. */
+export const BUSY_MS = 2000;
+/** Idle: nothing going. A heartbeat still has to land well inside the server's two minutes. */
+export const IDLE_MS = 20_000;
+/** At the plan's limit: take nothing, keep the heartbeat. */
+export const LIMITED_POLL_MS = 60_000;
+/** A limit whose message gives no reset time is tried again after this. */
+export const LIMIT_WAIT_MS = 30 * 60_000;
+/** Signed out, or the model down: look again after this (GET-1303). */
+export const RECHECK_MS = 5 * 60_000;
+const RETRIES = 2;
+const ERROR_BACKOFF_MS = 30_000;
+
+export const LABEL = "cloud.opennous.runner";
+export const RUN_COMMAND = "npx -y @opennous/cli@latest runner";
+
+/** What the status line says about the read in progress, or null. Pure. */
+export function readingLine(reading) {
+  if (!reading) return null;
+  const what = reading.live ? "Reading what's new" : "Reading your history";
+  if (reading.status === "paused_own_model") return `${what}: picking it back up.`;
+  if (reading.finished) return `${what}: wrapping up.`;
+  if (reading.total) return `${what}: ${reading.done ?? 0} of ${reading.total}.`;
+  return `${what}.`;
+}
+
+/** What the log says when reading stops for a while, by why. Pure. */
+export function pauseLine(agent, reason, until, now = Date.now()) {
+  const name = agent === "codex" ? "Codex" : "Claude";
+  const at = new Date(until).toLocaleString([], until - now > 20 * 3_600_000
+    ? { weekday: "short", hour: "2-digit", minute: "2-digit" } : { hour: "2-digit", minute: "2-digit" });
+  if (reason === "signed_out") return `You're signed out of ${name}. Run \`${agent === "codex" ? "codex login" : "claude"}\` and sign in; reading carries on by itself. Nothing is lost meanwhile.`;
+  if (reason === "outage") return `${name} isn't answering right now. Trying again at ${at}. Nothing is lost meanwhile.`;
+  return `Your ${name} plan hit its limit. Reading carries on at ${at}, when it resets. Nothing is lost meanwhile.`;
+}
+
+/**
+ * The loop. Injected: `api` ({ poll, answer }), `run` (one command → stdout), `sleep`, `log`.
+ * `stop()` → true ends it (tests; the real one runs until the process is stopped).
+ */
+export async function runRunner({ api, agent, host = hostname(), version = null, run, sleep, log, now = Date.now,
+  workers = WORKERS, limitWaitMs = LIMIT_WAIT_MS, stop = () => false }) {
+  let limitedUntil = 0, limitReason = null, answered = 0, lastLine = null, lastError = null, toldBackfill = false;
+  const answerOne = async (call, models) => {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const { text, usage } = parseAnswer(agent, await run(commandFor(agent, models[agent], call)));
+        await api.answer(call.id, { answer: text, model: models[agent].model, usage });
+        answered++;
+        if (limitReason) { log(limitReason === "signed_out" ? "Signed in again. Reading." : "Reading again."); limitReason = null; }
+        return;
+      } catch (err) {
+        // The plan's limit, a sign-out or an outage (GET-1303): none of them is the call's fault, so
+        // it is dropped, not failed (its lease runs out and it comes back), and nothing more is taken
+        // until it passes. The heartbeat keeps going, so the app shows why.
+        const reason = troubleOf(err.message);
+        if (reason) {
+          const until = reason === "limit" ? (resetAt(err.message, now()) ?? now() + limitWaitMs) : now() + RECHECK_MS;
+          if (now() >= limitedUntil || reason !== limitReason) log(pauseLine(agent, reason, until, now()));
+          limitedUntil = Math.max(limitedUntil, until);
+          limitReason = reason;
+          return;
+        }
+        if (attempt >= RETRIES) { await api.answer(call.id, { error: err.message }).catch(() => {}); return; }
+      }
+    }
+  };
+  while (!stop()) {
+    let page;
+    try {
+      page = await api.poll({ agent, host, version, answered, limit: workers,
+        limited_until: limitedUntil > now() ? new Date(limitedUntil).toISOString() : null,
+        limit_reason: limitedUntil > now() ? limitReason : null });
+      if (lastError) { log("Back online."); lastError = null; }
+    } catch (err) {
+      if (err.message !== lastError) log(`Waiting on Ownable: ${err.message}. Trying again every ${ERROR_BACKOFF_MS / 1000} seconds.`);
+      lastError = err.message;
+      await sleep(ERROR_BACKOFF_MS);
+      continue;
+    }
+    if (page.needs_backfill && !toldBackfill) {
+      toldBackfill = true;
+      log("Your history hasn't been read yet. Run `npx @opennous/cli@latest backfill` once; after that this keeps it current.");
+    }
+    const line = readingLine(page.reading);
+    if (line && line !== lastLine) { log(line); }
+    lastLine = line;
+    const calls = page.calls ?? [];
+    if (!calls.length) { await sleep(limitedUntil > now() ? LIMITED_POLL_MS : page.reading ? BUSY_MS : IDLE_MS); continue; }
+    await Promise.all(calls.map((c) => answerOne(c, page.models)));
+  }
+  return { answered };
+}
+
+// ── Start at login ───────────────────────────────────────────────────────────────────────────
+
+/** The absolute path of a command, or null. */
+export function which(cmd, run = spawnSync) {
+  const r = run("/bin/sh", ["-c", `command -v ${cmd}`], { encoding: "utf8" });
+  const p = r.status === 0 ? String(r.stdout).trim().split("\n")[0] : "";
+  return p.startsWith("/") ? p : null;
+}
+
+/** PATH for the service: where node, npx and the agent CLIs live, then the usual places. Pure. */
+export function servicePath(binaries) {
+  const dirs = [...new Set(binaries.filter(Boolean).map((b) => dirname(b)))];
+  for (const d of ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"]) if (!dirs.includes(d)) dirs.push(d);
+  return dirs.join(":");
+}
+
+const xml = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+/** The launchd agent for macOS. Pure. */
+export function launchdPlist({ npx, agent, workspace = null, path, log }) {
+  const args = [npx, "-y", "@opennous/cli@latest", "runner", "--agent", agent, ...(workspace ? ["--workspace", workspace] : [])];
+  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.map((a) => `    <string>${xml(a)}</string>`).join("\n")}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${xml(path)}</string>
+    <key>NOUS_RUNNER_SERVICE</key><string>1</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>30</integer>
+  <key>StandardOutPath</key><string>${xml(log)}</string>
+  <key>StandardErrorPath</key><string>${xml(log)}</string>
+</dict>
+</plist>
+`;
+}
+
+/** The systemd user unit for Linux. Pure. */
+export function systemdUnit({ npx, agent, workspace = null, path }) {
+  const args = [npx, "-y", "@opennous/cli@latest", "runner", "--agent", agent, ...(workspace ? ["--workspace", workspace] : [])];
+  return `[Unit]
+Description=Ownable runner: reads on your own ${agent === "codex" ? "ChatGPT" : "Claude"} plan
+After=network-online.target
+
+[Service]
+ExecStart=${args.join(" ")}
+Environment=PATH=${path}
+Environment=NOUS_RUNNER_SERVICE=1
+Restart=always
+RestartSec=30
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** Where the service files live on this machine. Pure. */
+export function servicePaths(os = platform(), home = homedir()) {
+  if (os === "darwin") return { kind: "launchd", file: join(home, "Library", "LaunchAgents", `${LABEL}.plist`), log: join(home, "Library", "Logs", "opennous-runner.log") };
+  if (os === "linux") return { kind: "systemd", file: join(home, ".config", "systemd", "user", "opennous-runner.service"), log: null };
+  return null;
+}
+
+/** Install and start the runner as a service. Returns { kind, file, log } or throws with what to do. */
+export function installService({ agent, workspace = null, run = spawnSync, os = platform(), home = homedir() } = {}) {
+  const where = servicePaths(os, home);
+  if (!where) throw new Error(`Starting at login isn't supported on ${os} yet. Run \`${RUN_COMMAND}\` in a terminal you keep open instead.`);
+  const npx = which("npx", run);
+  if (!npx) throw new Error("Couldn't find npx. Install Node.js 20 or later, then run this again.");
+  const path = servicePath([npx, which("node", run), which(agent, run)]);
+  mkdirSync(dirname(where.file), { recursive: true });
+  if (where.kind === "launchd") {
+    mkdirSync(dirname(where.log), { recursive: true });
+    writeFileSync(where.file, launchdPlist({ npx, agent, workspace, path, log: where.log }));
+    run("launchctl", ["unload", where.file], { stdio: "ignore" });
+    const r = run("launchctl", ["load", "-w", where.file], { encoding: "utf8" });
+    if (r.status !== 0) throw new Error(`launchctl couldn't start it: ${(r.stderr || "").trim()}`);
+  } else {
+    writeFileSync(where.file, systemdUnit({ npx, agent, workspace, path }));
+    run("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+    const r = run("systemctl", ["--user", "enable", "--now", "opennous-runner.service"], { encoding: "utf8" });
+    if (r.status !== 0) throw new Error(`systemd couldn't start it: ${(r.stderr || "").trim()}`);
+    // Keeps it running after logout, where the machine allows it. Best effort.
+    run("loginctl", ["enable-linger"], { stdio: "ignore" });
+  }
+  return where;
+}
+
+/** Stop and remove the service. True when there was one. */
+export function uninstallService({ run = spawnSync, os = platform(), home = homedir() } = {}) {
+  const where = servicePaths(os, home);
+  if (!where || !existsSync(where.file)) return false;
+  if (where.kind === "launchd") run("launchctl", ["unload", "-w", where.file], { stdio: "ignore" });
+  else {
+    run("systemctl", ["--user", "disable", "--now", "opennous-runner.service"], { stdio: "ignore" });
+  }
+  rmSync(where.file, { force: true });
+  return true;
+}
+
+/** Whether the service is installed, and running as far as the OS says. */
+export function serviceStatus({ run = spawnSync, os = platform(), home = homedir() } = {}) {
+  const where = servicePaths(os, home);
+  if (!where || !existsSync(where.file)) return { installed: false, running: false, ...(where ?? {}) };
+  const r = where.kind === "launchd"
+    ? run("launchctl", ["list", LABEL], { encoding: "utf8" })
+    : run("systemctl", ["--user", "is-active", "opennous-runner.service"], { encoding: "utf8" });
+  return { installed: true, running: r.status === 0, ...where };
+}