@euqns/nudge-mcp 1.22.0 → 1.25.0

package/dist/service.js

@@ -1,4 +1,4 @@
-// Run the runner or the agent companion as a login service.
+// Run the runner or the agent companion as a login service, and manage it.
 //
 // Both long-lived subcommands die with the terminal that started them, so a
 // reboot (or a closed laptop lid followed by a logout) silently takes the
@@ -9,39 +9,33 @@
 //   macOS  → ~/Library/LaunchAgents/com.nudge.<runner|agent>.plist  (launchd)
 //   Linux  → ~/.config/systemd/user/nudge-<runner|agent>.service    (systemd --user)
 //
-// The service runs THIS node binary and THIS installed copy of nudge-mcp, with
-// the caller's PATH baked in — launchd and systemd start user services with a
-// bare PATH, and the runner needs `git`, `gh`, `claude`, `codex` and friends to
-// be findable. The in-process supervisor (runner-restart.ts) still handles
-// rebuilds; the OS service manager handles reboots and crashes.
+// and gives both kinds the same verbs: install, uninstall, start, stop,
+// restart, status, logs. The service runs THIS node binary and THIS installed
+// copy of nudge-mcp, with the caller's PATH baked in — launchd and systemd
+// start user services with a bare PATH, and the runner needs `git`, `gh`,
+// `claude`, `codex` and friends to be findable. The in-process supervisor
+// (runner-restart.ts) still handles rebuilds; the OS service manager handles
+// reboots and crashes.
 //
-// Windows has no user-level equivalent this code can write safely, so it gets
-// an actionable message instead of a half-working Task Scheduler entry.
-import { execFile } from "node:child_process";
+// `status` and `install` never ask the user to read a log: the process itself
+// reports in through ~/.nudge/state (service-state.ts) — version, machine,
+// board, listener, pairing URL — and when it fails to, the CLI shows the exit
+// code and the last log lines inline.
+//
+// Windows has no user-level equivalent this code can write safely, so every
+// lifecycle verb gets an actionable message instead of a half-working Task
+// Scheduler entry; `status` still reports a process started from a terminal.
+import { execFile, spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { CREDENTIALS_DIR } from "./credentials.js";
+import { SERVICE_KINDS, SERVICE_LABEL_ENV, SERVICE_MANAGER_ENV, isStateLive, readProcessState, sanitizeInstance, serviceLabel, unitName, waitForProcessState, } from "./service-state.js";
+import { NUDGE_MCP_VERSION } from "./version.js";
+export { SERVICE_KINDS, sanitizeInstance, serviceLabel, unitName };
 const execFileAsync = promisify(execFile);
-export const SERVICE_KINDS = ["runner", "agent"];
 export const LOG_DIR = path.join(CREDENTIALS_DIR, "logs");
-/** Only [a-z0-9-] survive; anything else becomes a dash. `--instance "Mac 2"` → `mac-2`. */
-export function sanitizeInstance(raw) {
-    return raw
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-}
-export function serviceLabel(kind, instance) {
-    const suffix = instance ? sanitizeInstance(instance) : "";
-    return suffix ? `com.nudge.${kind}.${suffix}` : `com.nudge.${kind}`;
-}
-/** systemd unit names can't start with the reverse-DNS prefix comfortably;
- * `com.nudge.runner` → `nudge-runner`, `com.nudge.runner.mac-2` → `nudge-runner-mac-2`. */
-export function unitName(label) {
-    return label.replace(/^com\.nudge\./, "nudge-").replace(/\./g, "-");
-}
 /** Value of `--flag VALUE` or `--flag=VALUE` in argv, or null. */
 export function findFlag(argv, flag) {
     for (let i = 0; i < argv.length; i++) {
@@ -52,6 +46,22 @@ export function findFlag(argv, flag) {
     }
     return null;
 }
+/** argv without `--flag VALUE` / `--flag=VALUE` / bare `--flag` occurrences. */
+export function stripFlag(argv, flag, takesValue) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === flag) {
+            if (takesValue)
+                i++;
+            continue;
+        }
+        if (arg.startsWith(`${flag}=`))
+            continue;
+        out.push(arg);
+    }
+    return out;
+}
 /**
  * Rewrite `--cwd X` to an absolute path. The service has no notion of "the
  * directory I typed the install command in", so a relative `--cwd .` pasted
@@ -111,6 +121,13 @@ export function serviceEnv(kind, source = process.env) {
     }
     return env;
 }
+export function managerForPlatform(platform) {
+    if (platform === "darwin")
+        return "launchd";
+    if (platform === "linux")
+        return "systemd";
+    return null;
+}
 export function buildSpec(kind, argv, ctx) {
     // Flags pass through untouched (including `--save`: re-writing runner.json
     // with the same values at every start is idempotent), except that a
@@ -118,6 +135,11 @@ export function buildSpec(kind, argv, ctx) {
     const args = absolutizeCwd(argv, ctx.cwd);
     const label = serviceLabel(kind, kind === "runner" ? findFlag(args, "--instance") : null);
     const cwd = findFlag(args, "--cwd") ?? ctx.cwd;
+    const env = serviceEnv(kind, ctx.env);
+    if (ctx.manager) {
+        env[SERVICE_MANAGER_ENV] = ctx.manager;
+        env[SERVICE_LABEL_ENV] = label;
+    }
     return {
         kind,
         label,
@@ -125,7 +147,7 @@ export function buildSpec(kind, argv, ctx) {
         entry: ctx.entry,
         args,
         cwd,
-        env: serviceEnv(kind, ctx.env),
+        env,
         logPath: path.join(LOG_DIR, `${label}.log`),
     };
 }
@@ -210,6 +232,17 @@ TimeoutStopSec=120
 WantedBy=default.target
 `;
 }
+/** The nudge-mcp entry point an installed service file runs, so `status` can
+ * notice when an upgrade or uninstall moved it out from under the service. */
+export function entryFromServiceFile(text) {
+    const plist = /<key>ProgramArguments<\/key>\s*<array>\s*<string>[^<]*<\/string>\s*<string>([^<]*)<\/string>/.exec(text);
+    if (plist)
+        return plist[1].replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"');
+    const unit = /^ExecStart="[^"]*" "((?:[^"\\]|\\.)*)"/m.exec(text);
+    if (unit)
+        return unit[1].replace(/\\(.)/g, "$1");
+    return null;
+}
 // ---- platform paths -------------------------------------------------------
 export function launchdPlistPath(label, home = os.homedir()) {
     return path.join(home, "Library", "LaunchAgents", `${label}.plist`);
@@ -240,184 +273,586 @@ async function run(cmd, args, opts) {
         throw new Error(`\`${cmd} ${args.join(" ")}\` failed${detail ? `: ${detail}` : ""}`);
     }
 }
-// ---- launchd (macOS) ------------------------------------------------------
-const gui = () => `gui/${process.getuid?.() ?? 501}`;
-async function launchdInstall(spec) {
-    const plist = launchdPlistPath(spec.label);
-    await fs.mkdir(LOG_DIR, { recursive: true, mode: 0o700 });
-    await writePrivate(plist, renderLaunchdPlist(spec));
-    // Replace rather than layer: bootstrapping a label that's already loaded
-    // fails, and a stale definition would keep the old flags.
-    await run("launchctl", ["bootout", `${gui()}/${spec.label}`], { ignoreFailure: true });
-    await run("launchctl", ["bootstrap", gui(), plist]);
-    return plist;
+/** Stream a command's output to this terminal (for `logs`, esp. `--follow`). */
+function stream(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: "inherit" });
+        child.once("error", (err) => reject(err.code === "ENOENT"
+            ? new Error(`\`${cmd}\` is not available on this machine.`)
+            : err));
+        child.once("exit", () => resolve());
+    });
 }
-async function launchdUninstall(label) {
-    const plist = launchdPlistPath(label);
-    await run("launchctl", ["bootout", `${gui()}/${label}`], { ignoreFailure: true });
+async function fileExists(file) {
+    return fs.access(file).then(() => true, () => false);
+}
+async function tailFile(file, lines) {
     try {
-        await fs.unlink(plist);
-        return true;
+        const text = await fs.readFile(file, "utf8");
+        return text.split("\n").filter((l, i, all) => i < all.length - 1 || l !== "").slice(-lines).join("\n");
     }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return false;
-        throw err;
+    catch {
+        return "";
     }
 }
-async function launchdStatus(label) {
-    const plist = launchdPlistPath(label);
-    const installed = await fs.access(plist).then(() => true, () => false);
-    if (!installed)
-        return "not installed";
-    const out = await run("launchctl", ["print", `${gui()}/${label}`], { ignoreFailure: true });
-    const pid = /^\s*pid = (\d+)/m.exec(out)?.[1];
-    const state = /^\s*state = (\w+)/m.exec(out)?.[1];
-    if (pid)
-        return `running (pid ${pid})`;
-    if (state)
-        return state;
-    return out ? "loaded" : "installed but not loaded (log in again, or run `nudge-mcp service install` once more)";
-}
-// ---- systemd --user (Linux) -----------------------------------------------
-async function systemdInstall(spec) {
-    const unit = systemdUnitPath(spec.label);
-    await writePrivate(unit, renderSystemdUnit(spec));
-    await run("systemctl", ["--user", "daemon-reload"]);
-    await run("systemctl", ["--user", "enable", "--now", path.basename(unit)]);
-    return unit;
-}
-async function systemdUninstall(label) {
-    const unit = systemdUnitPath(label);
-    await run("systemctl", ["--user", "disable", "--now", path.basename(unit)], {
+const gui = () => `gui/${process.getuid?.() ?? 501}`;
+export const launchd = {
+    name: "launchd",
+    file: (label) => launchdPlistPath(label),
+    render: renderLaunchdPlist,
+    async install(spec) {
+        const plist = launchdPlistPath(spec.label);
+        await fs.mkdir(LOG_DIR, { recursive: true, mode: 0o700 });
+        await writePrivate(plist, renderLaunchdPlist(spec));
+        // Replace rather than layer: bootstrapping a label that's already loaded
+        // fails, and a stale definition would keep the old flags.
+        await run("launchctl", ["bootout", `${gui()}/${spec.label}`], { ignoreFailure: true });
+        await run("launchctl", ["bootstrap", gui(), plist]);
+        return plist;
+    },
+    async uninstall(label) {
+        const plist = launchdPlistPath(label);
+        await run("launchctl", ["bootout", `${gui()}/${label}`], { ignoreFailure: true });
+        try {
+            await fs.unlink(plist);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return false;
+            throw err;
+        }
+    },
+    async start(label) {
+        const plist = launchdPlistPath(label);
+        // `bootstrap` fails when the label is already loaded — harmless here; a
+        // loaded-but-stopped service is what `kickstart` is for.
+        await run("launchctl", ["bootstrap", gui(), plist], { ignoreFailure: true });
+        await run("launchctl", ["kickstart", `${gui()}/${label}`]);
+    },
+    async stop(label) {
+        // Unloading (rather than killing) is the only way to stop a KeepAlive
+        // service without launchd restarting it. The plist stays, so it loads
+        // again at next login — same semantics as `systemctl --user stop`.
+        await run("launchctl", ["bootout", `${gui()}/${label}`]);
+    },
+    async restart(label) {
+        const plist = launchdPlistPath(label);
+        await run("launchctl", ["bootstrap", gui(), plist], { ignoreFailure: true });
+        await run("launchctl", ["kickstart", "-k", `${gui()}/${label}`]);
+    },
+    async status(label) {
+        const file = launchdPlistPath(label);
+        const installed = await fileExists(file);
+        const entry = installed ? entryFromServiceFile(await fs.readFile(file, "utf8")) : null;
+        if (!installed) {
+            return { installed, file, loaded: false, running: false, pid: null, lastExitCode: null, detail: null, entry };
+        }
+        const out = await run("launchctl", ["print", `${gui()}/${label}`], { ignoreFailure: true });
+        const pid = /^\s*pid = (\d+)/m.exec(out)?.[1];
+        const state = /^\s*state = (\w+)/m.exec(out)?.[1] ?? null;
+        const exit = /^\s*last exit code = (-?\d+|\(never exited\))/m.exec(out)?.[1];
+        return {
+            installed,
+            file,
+            loaded: out.trim().length > 0,
+            running: !!pid,
+            pid: pid ? Number(pid) : null,
+            lastExitCode: exit && exit !== "(never exited)" ? Number(exit) : null,
+            detail: state,
+            entry,
+        };
+    },
+    async logs(label, { lines, follow }) {
+        const file = path.join(LOG_DIR, `${label}.log`);
+        if (!(await fileExists(file))) {
+            throw new Error(`No log yet at ${file} — the service has not started.`);
+        }
+        await stream("tail", follow ? ["-n", String(lines), "-f", file] : ["-n", String(lines), file]);
+    },
+    recentLog: (label, lines) => tailFile(path.join(LOG_DIR, `${label}.log`), lines),
+    logHint: (label) => path.join(LOG_DIR, `${label}.log`),
+    installNotes: () => [],
+};
+export const systemd = {
+    name: "systemd",
+    file: (label) => systemdUnitPath(label),
+    render: renderSystemdUnit,
+    async install(spec) {
+        const unit = systemdUnitPath(spec.label);
+        await writePrivate(unit, renderSystemdUnit(spec));
+        await run("systemctl", ["--user", "daemon-reload"]);
+        // `restart` rather than `enable --now` alone: a re-install must load the
+        // new flags into an already-running unit.
+        await run("systemctl", ["--user", "enable", path.basename(unit)]);
+        await run("systemctl", ["--user", "restart", path.basename(unit)]);
+        return unit;
+    },
+    async uninstall(label) {
+        const unit = systemdUnitPath(label);
+        await run("systemctl", ["--user", "disable", "--now", path.basename(unit)], {
+            ignoreFailure: true,
+        });
+        let removed = true;
+        try {
+            await fs.unlink(unit);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            removed = false;
+        }
+        await run("systemctl", ["--user", "daemon-reload"], { ignoreFailure: true });
+        return removed;
+    },
+    start: (label) => run("systemctl", ["--user", "start", `${unitName(label)}.service`]).then(() => undefined),
+    stop: (label) => run("systemctl", ["--user", "stop", `${unitName(label)}.service`]).then(() => undefined),
+    restart: (label) => run("systemctl", ["--user", "restart", `${unitName(label)}.service`]).then(() => undefined),
+    async status(label) {
+        const file = systemdUnitPath(label);
+        const installed = await fileExists(file);
+        const entry = installed ? entryFromServiceFile(await fs.readFile(file, "utf8")) : null;
+        if (!installed) {
+            return { installed, file, loaded: false, running: false, pid: null, lastExitCode: null, detail: null, entry };
+        }
+        const out = await run("systemctl", ["--user", "show", `${unitName(label)}.service`, "-p", "ActiveState,SubState,MainPID,ExecMainStatus,UnitFileState"], { ignoreFailure: true });
+        const prop = (name) => new RegExp(`^${name}=(.*)$`, "m").exec(out)?.[1]?.trim() ?? null;
+        const pid = Number(prop("MainPID") ?? 0);
+        const active = prop("ActiveState");
+        const sub = prop("SubState");
+        const exitStatus = prop("ExecMainStatus");
+        const unitFileState = prop("UnitFileState");
+        return {
+            installed,
+            file,
+            loaded: unitFileState === "enabled" || unitFileState === "static" || active === "active",
+            running: active === "active" && pid > 0,
+            pid: pid > 0 ? pid : null,
+            lastExitCode: exitStatus !== null && exitStatus !== "" ? Number(exitStatus) : null,
+            detail: active ? (sub && sub !== active ? `${active} (${sub})` : active) : null,
+            entry,
+        };
+    },
+    async logs(label, { lines, follow }) {
+        const args = ["--user", "-u", `${unitName(label)}.service`, "-n", String(lines), "--no-pager"];
+        if (follow)
+            args.push("-f");
+        await stream("journalctl", args);
+    },
+    recentLog: (label, lines) => run("journalctl", ["--user", "-u", `${unitName(label)}.service`, "-n", String(lines), "--no-pager", "-o", "cat"], {
         ignoreFailure: true,
-    });
-    let removed = true;
-    try {
-        await fs.unlink(unit);
+    }).then((s) => s.trim()),
+    logHint: (label) => `journalctl --user -u ${unitName(label)} -f`,
+    installNotes: () => [
+        `  Boot:      loginctl enable-linger ${os.userInfo().username}   # start before anyone logs in`,
+    ],
+};
+function nudgeCmd(kind, verb, label) {
+    const instance = /^com\.nudge\.(?:runner|agent)\.(.+)$/.exec(label)?.[1];
+    return `nudge-mcp service ${verb} ${kind}${instance ? ` --instance ${instance}` : ""}`;
+}
+/** Turn raw facts into the summary, problems and next steps a person needs.
+ * Pure, so every branch is unit-testable without a service manager. */
+export function diagnose(input) {
+    const { kind, label, service, process, live } = input;
+    const problems = [];
+    const nextSteps = [];
+    let summary;
+    let recentLog = null;
+    const startCmd = nudgeCmd(kind, "start", label);
+    const logsCmd = nudgeCmd(kind, "logs", label);
+    const installCmd = kind === "runner"
+        ? "nudge-mcp service install runner --cwd <checkout> [--token nrun_… --convex-url …] --save"
+        : "nudge-mcp service install agent --no-open";
+    if (!service) {
+        // No service manager on this platform: only the process report counts.
+        if (live) {
+            summary = `running in a terminal (pid ${process.pid})`;
+            problems.push(`Login services are not supported on ${input.platform}; this process dies with its terminal.`);
+            nextSteps.push(`Keep the terminal open, or add a Task Scheduler task that runs \`nudge-mcp ${kind}\` at log-on.`);
+        }
+        else {
+            summary = "not running";
+            problems.push(`Login services are not supported on ${input.platform}.`);
+            nextSteps.push(`Start it in a terminal: nudge-mcp ${kind}`);
+        }
     }
-    catch (err) {
-        if (err.code !== "ENOENT")
-            throw err;
-        removed = false;
+    else if (!service.installed) {
+        if (live) {
+            summary = `running in a terminal (pid ${process.pid}), not installed as a service`;
+            problems.push("This process will not come back after a reboot or a closed terminal.");
+            nextSteps.push(`Install it as a login service: ${installCmd}`);
+        }
+        else {
+            summary = "not installed";
+            nextSteps.push(installCmd);
+        }
+    }
+    else if (service.running) {
+        if (live) {
+            summary = `running (pid ${service.pid})`;
+        }
+        else if (process && !live) {
+            summary = `running (pid ${service.pid}), process has not reported in yet`;
+            problems.push("The service is up but the process has not written its status yet (starting, or an older build).");
+            nextSteps.push(`Wait a few seconds and run ${nudgeCmd(kind, "status", label)} again; if it stays this way: ${logsCmd}`);
+        }
+        else {
+            summary = `running (pid ${service.pid}), no status report yet`;
+            nextSteps.push(`Starting up? Run ${nudgeCmd(kind, "status", label)} again in a few seconds. Still nothing? The service runs a build older than 1.24 — \`${nudgeCmd(kind, "restart", label)}\` loads the installed copy${kind === "agent" ? " (and prints the new pairing URL)" : ""}.`);
+        }
+        if (input.entryExists === false && service.entry) {
+            problems.push(`The installed copy at ${service.entry} no longer exists — the running process is the last one that will start.`);
+            nextSteps.push(`Reinstall from the current copy: nudge-mcp service install ${kind} …`);
+        }
     }
-    await run("systemctl", ["--user", "daemon-reload"], { ignoreFailure: true });
-    return removed;
+    else {
+        // Installed, not running.
+        if (input.entryExists === false && service.entry) {
+            summary = "installed, cannot start";
+            problems.push(`The service points at ${service.entry}, which no longer exists (an npm upgrade or uninstall moved it).`);
+            nextSteps.push(`Reinstall from the current copy: nudge-mcp service install ${kind} …`);
+        }
+        else if (!service.loaded) {
+            summary = "installed, not loaded in this login session";
+            problems.push("The OS has not loaded the service (it was stopped, or installed from another session).");
+            nextSteps.push(startCmd);
+        }
+        else if (service.lastExitCode !== null && service.lastExitCode !== 0) {
+            summary = `stopped — last run exited with code ${service.lastExitCode}`;
+            problems.push(`The process exited with code ${service.lastExitCode}; the OS is holding it back or has given up.`);
+            recentLog = input.recentLog?.trim() ? input.recentLog.trim() : null;
+            nextSteps.push(`Fix the error above, then: ${startCmd}`);
+            nextSteps.push(`Full log: ${logsCmd}`);
+        }
+        else {
+            summary = `stopped${service.detail ? ` (${service.detail})` : ""}`;
+            nextSteps.push(startCmd);
+        }
+    }
+    return {
+        kind,
+        label,
+        platform: input.platform,
+        manager: input.manager,
+        service,
+        process,
+        live,
+        summary,
+        problems,
+        nextSteps,
+        recentLog,
+    };
 }
-async function systemdStatus(label) {
-    const unit = systemdUnitPath(label);
-    const installed = await fs.access(unit).then(() => true, () => false);
-    if (!installed)
-        return "not installed";
-    const out = await run("systemctl", ["--user", "is-active", path.basename(unit)], {
-        ignoreFailure: true,
-    });
-    return out.trim() || "inactive";
+function ago(at, now) {
+    const s = Math.max(0, Math.round((now - at) / 1000));
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 48)
+        return `${h}h ${m % 60}m ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+function short(id) {
+    return id.length > 12 ? `${id.slice(0, 8)}…` : id;
+}
+/** Render one service's block for humans. */
+export function formatStatus(report, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const { kind, label, service, process: p, live } = report;
+    const lines = [];
+    lines.push(`${kind.padEnd(7)} ${label}`);
+    lines.push(`  Service:   ${report.manager ?? "none"} · ${report.summary}${service?.installed ? ` · ${service.file}` : ""}`);
+    if (p && live) {
+        const managed = p.service ? `managed by ${p.service.manager}` : p.supervised ? "auto-restart on rebuild" : "foreground";
+        lines.push(`  Process:   nudge-mcp ${p.version} · pid ${p.pid} · started ${ago(p.startedAt, now)} · ${managed}`);
+        lines.push(`  Machine:   ${p.hostname}${p.kind === "runner" ? ` · id ${short(p.machineId)}${p.instance ? ` · instance ${p.instance}` : ""}` : ""}`);
+        if (p.kind === "runner") {
+            lines.push(`  Board:     ${p.board.title}${p.board.repo ? ` (${p.board.repo})` : ""} · ${p.convexUrl}`);
+            lines.push(`  Checkout:  ${p.cwd}`);
+            lines.push(`  Agents:    ${p.engines.length ? p.engines.join(", ") : "none detected"} · up to ${p.concurrency} job${p.concurrency === 1 ? "" : "s"} at once`);
+        }
+        else {
+            lines.push(`  Listener:  http://127.0.0.1:${p.port} · app ${p.appUrl}`);
+            lines.push(`  Workspace: ${p.cwd}`);
+            lines.push(`  Agents:    ${p.providers.length ? p.providers.join(", ") : "none ready"}`);
+            lines.push(`  Pairing:   ${p.pairingUrl}`);
+            lines.push("             (current — open it in the browser where Nudge is signed in)");
+        }
+    }
+    else if (p && !live) {
+        lines.push(`  Process:   last reported nudge-mcp ${p.version} on ${p.hostname}, ${ago(p.updatedAt ?? p.startedAt, now)} (pid ${p.pid} is gone)`);
+        if (p.kind === "agent")
+            lines.push("  Pairing:   none current — a stopped companion's URL is not shown; start it and run status again");
+    }
+    if (report.recentLog) {
+        lines.push("  Last log lines:");
+        for (const l of report.recentLog.split("\n").slice(-12))
+            lines.push(`    ${l}`);
+    }
+    for (const problem of report.problems)
+        lines.push(`  ⚠ ${problem}`);
+    if (report.nextSteps.length) {
+        lines.push(`  ${report.nextSteps.length === 1 ? "Next:     " : "Next:"}${report.nextSteps.length === 1 ? ` ${report.nextSteps[0]}` : ""}`);
+        if (report.nextSteps.length > 1)
+            for (const step of report.nextSteps)
+                lines.push(`    - ${step}`);
+    }
+    if (opts.logHint && (service?.installed || live))
+        lines.push(`  Logs:      ${nudgeCmd(kind, "logs", label)}   (${opts.logHint})`);
+    return lines.join("\n");
 }
 // ---- CLI ------------------------------------------------------------------
 export const SERVICE_USAGE = [
     "Usage:",
     "  nudge-mcp service install runner [runner options]   Start the runner at login and keep it alive.",
     "  nudge-mcp service install agent  [agent options]    Same for the Nudge Agent companion.",
-    "  nudge-mcp service uninstall runner|agent [--instance NAME]",
-    "  nudge-mcp service status",
+    "  nudge-mcp service uninstall runner|agent            Stop it and remove the login service.",
+    "  nudge-mcp service start|stop|restart runner|agent   Control the installed service now.",
+    "  nudge-mcp service status [runner|agent] [--json]    State, version, machine, board / pairing URL, and what to do next.",
+    "  nudge-mcp service logs runner|agent [-n N] [-f]     Show (or follow) the service log.",
     "",
-    "Options after the kind are passed to the runner/agent unchanged (a relative",
-    "--cwd is pinned to the current directory). Add --dry-run to print the service",
-    "file without installing it. macOS uses a launchd LaunchAgent, Linux a systemd",
-    "--user unit; both restart the process after a crash and at every login.",
+    "Every verb accepts --instance NAME for a second runner installed with --instance.",
+    "Options after `install <kind>` are passed to the runner/agent unchanged (a relative",
+    "--cwd is pinned to the current directory). Add --dry-run to print the service file",
+    "without installing it. macOS uses a launchd LaunchAgent, Linux a systemd --user unit;",
+    "both start the process at login and restart it after a crash. `stop` keeps the",
+    "service installed (it returns at next login); `uninstall` removes it for good.",
 ].join("\n");
-function unsupported() {
-    throw new Error([
-        `Login services are supported on macOS (launchd) and Linux (systemd --user); this is ${process.platform}.`,
+export const SERVICE_ACTIONS = [
+    "install",
+    "uninstall",
+    "start",
+    "stop",
+    "restart",
+    "status",
+    "logs",
+];
+function unsupportedMessage(platform, kind, node, entry) {
+    return [
+        `Login services are supported on macOS (launchd) and Linux (systemd --user); this is ${platform}.`,
         "On Windows, create a Task Scheduler task that runs at log-on with the action:",
-        `  "${process.execPath}" "${process.argv[1]}" runner`,
-        "and set it to restart on failure.",
-    ].join("\n"));
+        `  "${node}" "${entry}" ${kind}`,
+        "and set it to restart on failure. `nudge-mcp service status` still reports a",
+        `${kind} started from a terminal.`,
+    ].join("\n");
 }
-function parseKind(raw) {
+function parseKind(raw, action) {
     if (raw === "runner" || raw === "agent")
         return raw;
-    throw new Error(`Expected "runner" or "agent" after the service action, got ${raw ? `"${raw}"` : "nothing"}.\n\n${SERVICE_USAGE}`);
+    throw new Error(`Expected "runner" or "agent" after \`service ${action}\`, got ${raw ? `"${raw}"` : "nothing"}.\n\n${SERVICE_USAGE}`);
 }
-export async function runService(argv) {
-    const action = argv[0];
+function parseLines(argv) {
+    const raw = findFlag(argv, "--lines") ?? findFlag(argv, "-n");
+    const n = raw === null ? 60 : Number(raw);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new Error(`--lines must be a positive integer, got "${raw}".`);
+    return n;
+}
+export async function defaultDeps() {
     const platform = process.platform;
+    const managerName = managerForPlatform(platform);
+    return {
+        platform,
+        manager: managerName === "launchd" ? launchd : managerName === "systemd" ? systemd : null,
+        node: process.execPath,
+        entry: await fs.realpath(process.argv[1]),
+        cwd: process.cwd(),
+        env: process.env,
+        hostname: os.hostname(),
+        now: Date.now,
+        out: (line) => console.log(line),
+        warn: (line) => console.warn(line),
+        readState: (label) => readProcessState(label),
+        isLive: (state) => isStateLive(state),
+        waitForState: (label, since) => waitForProcessState(label, { since }),
+        entryExists: fileExists,
+    };
+}
+async function buildReport(kind, label, deps) {
+    const service = deps.manager ? await deps.manager.status(label) : null;
+    const state = await deps.readState(label);
+    const live = !!state && deps.isLive(state);
+    const entryExists = service?.entry ? await deps.entryExists(service.entry) : null;
+    const needsLog = !!service && service.installed && !service.running && service.lastExitCode !== null && service.lastExitCode !== 0;
+    const recentLog = needsLog && deps.manager ? await deps.manager.recentLog(label, 12) : null;
+    return diagnose({ kind, label, platform: deps.platform, manager: deps.manager?.name ?? null, service, process: state, live, entryExists, recentLog });
+}
+export async function runService(argv, overrides = {}) {
+    const deps = { ...(await defaultDeps()), ...overrides };
+    const action = argv[0];
+    const { out, manager } = deps;
+    if (action === undefined || action === "help" || action === "--help" || action === "-h") {
+        out(SERVICE_USAGE);
+        return;
+    }
+    if (!SERVICE_ACTIONS.includes(action)) {
+        throw new Error(`Unknown service action "${action}".\n\n${SERVICE_USAGE}`);
+    }
+    // ---- status -------------------------------------------------------------
     if (action === "status") {
-        if (platform !== "darwin" && platform !== "linux")
-            unsupported();
-        const rows = [];
-        for (const kind of SERVICE_KINDS) {
-            const label = serviceLabel(kind);
-            const status = platform === "darwin" ? await launchdStatus(label) : await systemdStatus(label);
-            rows.push(`  ${kind.padEnd(7)} ${label.padEnd(20)} ${status}`);
+        const rest = argv.slice(1);
+        const json = rest.includes("--json");
+        const only = rest[0] === "runner" || rest[0] === "agent" ? rest[0] : null;
+        const instance = findFlag(rest, "--instance");
+        const kinds = only ? [only] : [...SERVICE_KINDS];
+        const reports = await Promise.all(kinds.map((kind) => {
+            const label = serviceLabel(kind, kind === "runner" ? instance : null);
+            return buildReport(kind, label, deps);
+        }));
+        if (json) {
+            out(JSON.stringify({ hostname: deps.hostname, platform: deps.platform, nudgeMcp: NUDGE_MCP_VERSION, services: reports }, null, 2));
+            return;
         }
-        console.log(["Nudge login services:", ...rows].join("\n"));
-        if (platform === "darwin")
-            console.log(`\nLogs: ${LOG_DIR}/<label>.log`);
-        else
-            console.log("\nLogs: journalctl --user -u nudge-runner -f");
+        const platformName = deps.platform === "darwin" ? "macOS" : deps.platform;
+        out(`Nudge services on ${deps.hostname} (${platformName}, nudge-mcp ${NUDGE_MCP_VERSION})`);
+        out("");
+        for (const report of reports) {
+            out(formatStatus(report, { now: deps.now(), logHint: manager ? manager.logHint(report.label) : null }));
+            out("");
+        }
+        if (!manager)
+            out(unsupportedMessage(deps.platform, only ?? "runner", deps.node, deps.entry));
         return;
     }
-    if (action === "uninstall") {
-        const kind = parseKind(argv[1]);
-        const label = serviceLabel(kind, findFlag(argv.slice(2), "--instance"));
-        if (platform !== "darwin" && platform !== "linux")
-            unsupported();
-        const removed = platform === "darwin" ? await launchdUninstall(label) : await systemdUninstall(label);
-        console.log(removed
-            ? `Removed ${label}. The ${kind} no longer starts at login; a running instance was stopped.`
-            : `${label} was not installed.`);
+    const kind = parseKind(argv[1], action);
+    const rest = argv.slice(2);
+    // ---- logs ---------------------------------------------------------------
+    if (action === "logs") {
+        if (!manager)
+            throw new Error(unsupportedMessage(deps.platform, kind, deps.node, deps.entry));
+        const label = serviceLabel(kind, kind === "runner" ? findFlag(rest, "--instance") : null);
+        await manager.logs(label, { lines: parseLines(rest), follow: rest.includes("--follow") || rest.includes("-f") });
         return;
     }
-    if (action === "install") {
-        const kind = parseKind(argv[1]);
-        const rest = argv.slice(2);
-        const dryRun = rest.includes("--dry-run");
-        const passthrough = rest.filter((a) => a !== "--dry-run");
-        const entry = await fs.realpath(process.argv[1]);
-        const spec = buildSpec(kind, passthrough, {
-            node: process.execPath,
-            entry,
-            cwd: process.cwd(),
-        });
-        if (platform !== "darwin" && platform !== "linux")
-            unsupported();
-        const rendered = platform === "darwin" ? renderLaunchdPlist(spec) : renderSystemdUnit(spec);
-        const target = platform === "darwin" ? launchdPlistPath(spec.label) : systemdUnitPath(spec.label);
-        if (dryRun) {
-            console.log(`# ${target}\n${rendered}`);
-            return;
+    // ---- start / stop / restart ---------------------------------------------
+    if (action === "start" || action === "stop" || action === "restart") {
+        if (!manager)
+            throw new Error(unsupportedMessage(deps.platform, kind, deps.node, deps.entry));
+        const label = serviceLabel(kind, kind === "runner" ? findFlag(rest, "--instance") : null);
+        const before = await manager.status(label);
+        if (!before.installed) {
+            throw new Error(`${label} is not installed, so there is nothing to ${action}.\n` +
+                `Install it first: nudge-mcp service install ${kind}${kind === "agent" ? " --no-open" : " …"}`);
         }
-        if (isNpxCachePath(entry)) {
-            console.warn([
-                `[nudge-mcp service] warning: this copy lives in npm's npx cache (${entry}).`,
-                "  npm may prune it, which would break the service on a later boot.",
-                "  Prefer: npm install -g @euqns/nudge-mcp && nudge-mcp service install " + kind,
-            ].join("\n"));
+        if (before.entry && !(await deps.entryExists(before.entry))) {
+            throw new Error(`${label} points at ${before.entry}, which no longer exists (an npm upgrade or uninstall moved it).\n` +
+                `Reinstall from the current copy: nudge-mcp service install ${kind} …`);
         }
-        const written = platform === "darwin" ? await launchdInstall(spec) : await systemdInstall(spec);
-        const lines = [
-            `Installed ${spec.label} → ${written}`,
-            `  Runs:      ${[spec.kind, ...spec.args].join(" ")}`,
-            `  Directory: ${spec.cwd}`,
-            "  Starts at login and restarts after a crash. It is starting now.",
-        ];
-        if (platform === "darwin") {
-            lines.push(`  Logs:      ${spec.logPath}`);
-            lines.push(`  Stop:      launchctl bootout ${gui()}/${spec.label}`);
-        }
-        else {
-            lines.push(`  Logs:      journalctl --user -u ${unitName(spec.label)} -f`);
-            lines.push(`  Boot:      loginctl enable-linger ${os.userInfo().username}   # start before anyone logs in`);
+        if (action === "stop") {
+            await manager.stop(label);
+            out(`Stopped ${label}. It stays installed and starts again at next login; \`${nudgeCmd(kind, "start", label)}\` brings it back now.`);
+            return;
         }
-        if (kind === "agent" && !passthrough.includes("--no-open")) {
-            lines.push("  Note:      the companion opens its pairing page in the browser at every login; add --no-open to skip that.");
+        const since = deps.now();
+        if (action === "start")
+            await manager.start(label);
+        else
+            await manager.restart(label);
+        out(`${action === "start" ? "Started" : "Restarted"} ${label}. Waiting for it to report in…`);
+        const state = await deps.waitForState(label, since);
+        if (state) {
+            out(describeFreshState(state));
+            return;
         }
-        lines.push(`  Remove:    nudge-mcp service uninstall ${kind}`);
-        console.log(lines.join("\n"));
+        // It did not report in: say why, right here.
+        const report = await buildReport(kind, label, deps);
+        out(formatStatus(report, { now: deps.now(), logHint: manager.logHint(label) }));
+        if (!report.service?.running)
+            throw new Error(`${label} did not stay running.`);
         return;
     }
-    throw new Error(SERVICE_USAGE);
+    // ---- uninstall ----------------------------------------------------------
+    if (action === "uninstall") {
+        if (!manager)
+            throw new Error(unsupportedMessage(deps.platform, kind, deps.node, deps.entry));
+        const label = serviceLabel(kind, kind === "runner" ? findFlag(rest, "--instance") : null);
+        const removed = await manager.uninstall(label);
+        out(removed
+            ? `Removed ${label}. The ${kind} no longer starts at login; a running instance was stopped.`
+            : `${label} was not installed.`);
+        return;
+    }
+    // ---- install ------------------------------------------------------------
+    const dryRun = rest.includes("--dry-run");
+    const passthrough = rest.filter((a) => a !== "--dry-run");
+    const spec = buildSpec(kind, passthrough, {
+        node: deps.node,
+        entry: deps.entry,
+        cwd: deps.cwd,
+        env: deps.env,
+        manager: manager?.name ?? null,
+    });
+    if (!manager)
+        throw new Error(unsupportedMessage(deps.platform, kind, deps.node, deps.entry));
+    if (dryRun) {
+        out(`# ${manager.file(spec.label)}\n${manager.render(spec)}`);
+        return;
+    }
+    if (isNpxCachePath(deps.entry)) {
+        deps.warn([
+            `[nudge-mcp service] warning: this copy lives in npm's npx cache (${deps.entry}).`,
+            "  npm may prune it, which would break the service on a later boot.",
+            "  Prefer: npm install -g @euqns/nudge-mcp && nudge-mcp service install " + kind,
+        ].join("\n"));
+    }
+    const since = deps.now();
+    const written = await manager.install(spec);
+    const lines = [
+        `Installed ${spec.label} → ${written}`,
+        `  Runs:      ${[spec.kind, ...spec.args].join(" ")}`,
+        `  Directory: ${spec.cwd}`,
+        "  Starts at login and restarts after a crash. It is starting now.",
+        `  Logs:      ${nudgeCmd(kind, "logs", spec.label)}   (${manager.logHint(spec.label)})`,
+        `  Status:    ${nudgeCmd(kind, "status", spec.label)}`,
+        `  Control:   nudge-mcp service start|stop|restart ${kind}`,
+        ...manager.installNotes(spec),
+    ];
+    if (kind === "agent" && !passthrough.includes("--no-open")) {
+        lines.push("  Note:      the companion opens its pairing page in the browser at every login; add --no-open to skip that.");
+    }
+    lines.push(`  Remove:    ${nudgeCmd(kind, "uninstall", spec.label)}`);
+    out(lines.join("\n"));
+    // Wait for THIS start to report in — the state file carries the pairing URL
+    // (agent) or the registration (runner), so nobody has to open a log. Only a
+    // report written after `since` counts: a URL from a previous run is stale.
+    out("");
+    out(kind === "agent" ? "Waiting for the pairing URL…" : "Waiting for the runner to register…");
+    const state = await deps.waitForState(spec.label, since);
+    if (state) {
+        out(describeFreshState(state));
+        return;
+    }
+    const report = await buildReport(kind, spec.label, deps);
+    out("");
+    out(formatStatus(report, { now: deps.now(), logHint: manager.logHint(spec.label) }));
+    if (!report.service?.running)
+        throw new Error(`${spec.label} did not stay running — see above.`);
+}
+/** What to tell the user once a freshly (re)started process has reported in. */
+export function describeFreshState(state) {
+    if (state.kind === "agent") {
+        return [
+            `Nudge Agent is running (nudge-mcp ${state.version} on ${state.hostname}, pid ${state.pid}).`,
+            `  Agents:    ${state.providers.length ? state.providers.join(", ") : "none ready — sign in to codex, claude or cursor-agent"}`,
+            `  Listener:  http://127.0.0.1:${state.port}`,
+            "",
+            "Open this pairing URL in the browser where Nudge is signed in:",
+            state.pairingUrl,
+            "",
+            "A rebuild restart keeps this pairing. A reboot or crash restart mints a new one —",
+            "`nudge-mcp service status agent` always prints the current URL.",
+        ].join("\n");
+    }
+    return [
+        `Runner is registered as "${state.name}" on ${state.board.title}${state.board.repo ? ` (${state.board.repo})` : ""}.`,
+        `  Version:   nudge-mcp ${state.version} on ${state.hostname} · pid ${state.pid}`,
+        `  Checkout:  ${state.cwd}`,
+        `  Agents:    ${state.engines.length ? state.engines.join(", ") : "none detected"} · up to ${state.concurrency} job${state.concurrency === 1 ? "" : "s"} at once`,
+        "The board's Agent View shows this machine as online while it heartbeats.",
+    ].join("\n");
 }
 //# sourceMappingURL=service.js.map