@join-pantheon/cli 0.32.1 → 0.33.0-rc.2

package/dist/service.js

@@ -1,12 +1,14 @@
-import { writeFileSync, mkdirSync, existsSync, unlinkSync, readFileSync } from "node:fs";
+import { writeFileSync, mkdirSync, existsSync, lstatSync, unlinkSync, readFileSync, renameSync, rmSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { homedir, platform, userInfo } from "node:os";
 import { which } from "./which.js";
-import { dirname, isAbsolute, join, posix, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, posix, resolve } from "node:path";
+import { linuxGraphicalSession } from "./host-env.js";
 import { fileURLToPath } from "node:url";
-import { launcher } from "./install.js";
+import { isVersionManagedPath, launcher } from "./install.js";
 import { childNodeFlags, managedLauncher, managedLayout } from "./managed.js";
 import { CONFIG_DIR } from "./config.js";
+import { HOST_KINDS, LEGACY_TASK_NAME, clearTrayQuit, ensureHostShim, fromUtf16le, hostAlive, hostArgv, hostChildRunning, hostFiles, hostLaunch, isHostKind, launchFileText, legacyTaskIsUsers, readDefinition, readHostState, taskName, taskUserId, taskXml, utf16le, windowsPowerShell, writeDefinition, } from "./win-host.js";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const LABEL = (kind) => `dev.pantheon.${kind}`;
 export function borrowedHome() {
@@ -19,14 +21,55 @@ export function borrowedHome() {
         return false;
     }
 }
+export function borrowedScheduler(env = process.env) {
+    if (env.PANTHEON_SERVICES_ANY_HOME === "1")
+        return false;
+    if (borrowedHome())
+        return true;
+    if (!env.PANTHEON_HOME)
+        return false;
+    try {
+        return resolve(env.PANTHEON_HOME).toLowerCase() !== resolve(join(userInfo().homedir, ".pantheon")).toLowerCase();
+    }
+    catch {
+        return true;
+    }
+}
+export function borrowedProfile(env = process.env, profile = () => userInfo().homedir) {
+    if (env.PANTHEON_SERVICES_ANY_HOME === "1")
+        return false;
+    if (borrowedScheduler(env))
+        return true;
+    let real;
+    try {
+        real = resolve(profile()).toLowerCase();
+    }
+    catch {
+        return true;
+    }
+    return [env.HOME, env.USERPROFILE].some((h) => !!h && resolve(h).toLowerCase() !== real);
+}
+const isSchtasks = (c) => /(^|[\\/])schtasks(\.exe)?$/i.test(c);
 const READ_ONLY = (c, a) => c === "launchctl" ? ["print", "print-disabled", "list"].includes(a[0] ?? "")
     : c === "systemctl" ? a.some((x) => ["is-enabled", "is-active", "status", "show", "show-environment"].includes(x))
-        : true;
-function guardedExecFile(c, a) {
-    if ((c === "launchctl" || c === "systemctl") && !READ_ONLY(c, a) && borrowedHome()) {
-        throw new Error(`refused: ${c} ${a[0] ?? ""} would change this user's real services, but HOME (${homedir()}) is not the user's home — a test or a sandbox. Set PANTHEON_SERVICES_ANY_HOME=1 to allow it.`);
+        : isSchtasks(c) ? (a[0] ?? "").toLowerCase() === "/query"
+            : true;
+export function serviceRefusal(c, a, borrowed = { home: borrowedHome, scheduler: () => borrowedScheduler() }) {
+    if (READ_ONLY(c, a))
+        return null;
+    if ((c === "launchctl" || c === "systemctl") && borrowed.home()) {
+        return `refused: ${c} ${a[0] ?? ""} would change this user's real services, but HOME (${homedir()}) is not the user's home — a test or a sandbox. Set PANTHEON_SERVICES_ANY_HOME=1 to allow it.`;
+    }
+    if (isSchtasks(c) && borrowed.scheduler()) {
+        return `refused: schtasks ${a[0] ?? ""} would change this user's real Task Scheduler task, but this Pantheon home (${CONFIG_DIR}) is not the user's own — a test or a sandbox. Set PANTHEON_SERVICES_ANY_HOME=1 to allow it.`;
     }
-    return execFileSync(c, a, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) ?? "";
+    return null;
+}
+function guardedExecFile(c, a) {
+    const refused = serviceRefusal(c, a);
+    if (refused)
+        throw new Error(refused);
+    return execFileSync(c, a, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true }) ?? "";
 }
 export const realSys = () => ({
     platform: platform(),
@@ -51,11 +94,8 @@ export function servicePath(envPath = process.env.PATH ?? "", managed = managedL
     const last = managed ? [posix.dirname(managed.node)] : [];
     return [...new Set([...first, ...envPath.split(":"), ...SERVICE_BASE_PATH, ...last].filter(Boolean))].join(":");
 }
-export function servicesUnavailable(plat = platform()) {
-    if (plat !== "win32")
-        return null;
-    return "not available — Pantheon does not run in the background on Windows yet. "
-        + "Your agent still answers peers whenever it is open; nothing runs here while you are away.";
+export function servicesUnavailable(_plat = platform()) {
+    return null;
 }
 export function plistPath(kind = "worker") {
     return join(homedir(), "Library", "LaunchAgents", `${LABEL(kind)}.plist`);
@@ -157,15 +197,16 @@ const systemdValue = (v) => {
         throw new Error(`a path with a line break in it cannot be written into a systemd unit: ${JSON.stringify(v)}`);
     return v.replace(/%/g, "%%");
 };
-export function systemdUnit(kind, cwd, args, path = servicePath()) {
+export function systemdUnit(kind, cwd, args, path = servicePath(), opts = {}) {
     const description = kind === "relay"
         ? "pantheon relay — the coordination plane for a space"
         : kind === "worker"
             ? "pantheon worker — answer peers while away"
             : "pantheon notifier — alert a person when their decision is required";
+    const graphical = kind === "notifier" && !!opts.graphical;
     return `[Unit]
 Description=${description}
-After=network-online.target
+${graphical ? "After=graphical-session.target\nPartOf=graphical-session.target" : "After=network-online.target"}
 
 [Service]
 Type=simple
@@ -176,9 +217,47 @@ Restart=always
 RestartSec=30
 
 [Install]
-WantedBy=default.target
+WantedBy=${graphical ? "graphical-session.target" : "default.target"}
 `;
 }
+export const SESSION_ENV_VARS = ["DBUS_SESSION_BUS_ADDRESS", "DISPLAY", "WAYLAND_DISPLAY", "XAUTHORITY"];
+export function sessionEnvToImport(managerEnv, shellEnv = process.env, exists = existsSync) {
+    if (shellEnv.SSH_CONNECTION || shellEnv.SSH_CLIENT || shellEnv.SSH_TTY)
+        return [];
+    if (!linuxGraphicalSession(shellEnv))
+        return [];
+    if (!shellEnv.DBUS_SESSION_BUS_ADDRESS || managerEnv.DBUS_SESSION_BUS_ADDRESS)
+        return [];
+    const runtime = managerEnv.XDG_RUNTIME_DIR || shellEnv.XDG_RUNTIME_DIR;
+    if (runtime && exists(join(runtime, "bus")))
+        return [];
+    return ["DBUS_SESSION_BUS_ADDRESS"];
+}
+export function dropOtherTargetLink(unit, graphical) {
+    const other = graphical ? "default.target" : "graphical-session.target";
+    const link = join(dirname(unit), `${other}.wants`, basename(unit));
+    try {
+        lstatSync(link);
+    }
+    catch {
+        return null;
+    }
+    try {
+        rmSync(link, { force: true });
+        return link;
+    }
+    catch {
+        return null;
+    }
+}
+export function graphicalSessionActive(sys = realSys()) {
+    try {
+        return String(sys.exec("systemctl", ["--user", "is-active", "graphical-session.target"])).trim() === "active";
+    }
+    catch {
+        return false;
+    }
+}
 export function lingerEnabled(sys = realSys()) {
     try {
         const out = sys.exec("loginctl", ["show-user", sys.user || String(sys.uid), "--property=Linger"]);
@@ -193,6 +272,8 @@ export function installService(kind, cwd, args, sys = realSys()) {
     const noServices = servicesUnavailable(sys.platform);
     if (noServices)
         throw new Error(noServices.replace(/^not available — /, ""));
+    if (sys.platform === "win32")
+        return installWindows(kind, resolve(cwd), args, sys);
     const out = [];
     let loaded = true;
     let reason;
@@ -233,13 +314,35 @@ export function installService(kind, cwd, args, sys = realSys()) {
         out.push(`  stop:   pantheon service uninstall ${kind}`);
     }
     else {
-        if (kind === "menubar" || kind === "notifier") {
-            throw new Error(`${kind === "menubar" ? "the menu bar" : "desktop alerts"} run on macOS only, and this machine reports ${sys.platform}`);
+        if (kind === "menubar") {
+            throw new Error(`the menu bar runs on macOS only, and this machine reports ${sys.platform} — on Linux, pantheon board is the view`);
         }
-        const unit = unitPath(kind, systemdUserEnv(sys));
+        const managerEnv = systemdUserEnv(sys);
+        const graphical = kind === "notifier" && graphicalSessionActive(sys);
+        const unit = unitPath(kind, managerEnv);
         mkdirSync(dirname(unit), { recursive: true });
-        writeFileSync(unit, systemdUnit(kind, abs, args));
+        writeFileSync(unit, systemdUnit(kind, abs, args, servicePath(), { graphical }));
         out.push(`  wrote ${unit}`);
+        const dropped = dropOtherTargetLink(unit, graphical);
+        if (dropped)
+            out.push(`  removed ${dropped} (an earlier install's start-up link)`);
+        if (kind === "notifier") {
+            const missing = sessionEnvToImport(managerEnv);
+            if (missing.length) {
+                try {
+                    sys.exec("systemctl", ["--user", "import-environment", ...missing]);
+                    out.push(`  gave systemd this desktop session's bus address (${missing.join(", ")}); it lasts until systemd --user stops, and is good only while this session is`);
+                    out.push(`  ! your desktop does not pass it to systemd at login — for alerts after the next login, add this to your session's autostart:`);
+                    out.push(`      dbus-update-activation-environment --systemd ${missing.join(" ")}`);
+                }
+                catch (e) {
+                    out.push(`  could not pass ${missing.join(", ")} to systemd (${e.message.split("\n")[0]}) — the notifier cannot reach this session's bus until you add  dbus-update-activation-environment --systemd ${missing.join(" ")}  to your session's autostart`);
+                }
+            }
+            out.push(graphical
+                ? "  starts with your desktop session (graphical-session.target) and stops when you log out"
+                : "  starts with your user session (default.target) — this desktop does not use graphical-session.target");
+        }
         try {
             sys.exec("systemctl", ["--user", "daemon-reload"]);
             sys.exec("systemctl", ["--user", "enable", "--now", `pantheon-${kind}`]);
@@ -262,7 +365,10 @@ export function uninstallService(kind, sys = realSys()) {
         const strays = unitPaths(kind, {}).filter((u) => existsSync(u));
         for (const u of strays)
             unlinkSync(u);
-        return strays.length ? strays.map((u) => `  removed ${u}`) : [`  no ${kind} service installed`];
+        const host = uninstallWindows(kind, sys);
+        if (!host)
+            return strays.length ? strays.map((u) => `  removed ${u}`) : [`  no ${kind} service installed`];
+        return [...host, ...strays.map((u) => `  removed ${u}`)];
     }
     if (sys.platform === "darwin") {
         const p = plistPath(kind);
@@ -306,6 +412,10 @@ export function uninstallService(kind, sys = realSys()) {
     return out;
 }
 export function disableService(kind, sys = realSys()) {
+    if (sys.platform === "win32") {
+        disableWindows(kind, sys);
+        return;
+    }
     if (sys.platform === "darwin") {
         try {
             sys.exec("launchctl", ["bootout", `gui/${sys.uid}/${LABEL(kind)}`]);
@@ -326,6 +436,11 @@ function outOf(exec, c, a) {
     }
 }
 export function serviceState(kind, exec = realExec, plat = platform(), uid = process.getuid?.() ?? 501) {
+    if (plat === "win32") {
+        const f = hostFiles();
+        const loaded = outOf(exec, "schtasks", ["/Query", "/TN", taskName(exec)]).ok;
+        return { disabled: isHostKind(kind) && existsSync(f.disabled(kind)), loaded, running: isHostKind(kind) && !!hostChildRunning(kind), ...(isHostKind(kind) ? { from: f.definition(kind) } : {}) };
+    }
     if (plat === "darwin") {
         const dis = outOf(exec, "launchctl", ["print-disabled", `gui/${uid}`]).out;
         const disabled = new RegExp(`"${LABEL(kind).replace(/\./g, "\\.")}"\\s*=>\\s*(disabled|true)`).test(dis);
@@ -344,8 +459,20 @@ export function restartService(kind, exec = realExec, opts = {}) {
     const uid = process.getuid?.() ?? 501;
     const st = serviceState(kind, exec, plat, uid);
     if (st.disabled)
-        return [`  ${kind}: left stopped (you stopped it) — start it again: pantheon service install ${kind}`];
+        return [`  ${kind}: left stopped (you stopped it) — start it again: pantheon service ${plat === "win32" ? "start" : "install"} ${kind}`];
     try {
+        if (plat === "win32") {
+            if (hostAlive(readHostState())) {
+                const f = hostFiles();
+                mkdirSync(f.dir, { recursive: true });
+                writeFileSync(f.restart(kind), new Date().toISOString());
+                return [`  ${kind}: restarted on the new code (the Pantheon host starts it again within seconds)`];
+            }
+            if (!st.loaded)
+                return [`  ${kind}: the ${taskName(exec)} task is not registered — pantheon service install ${kind}`];
+            exec("schtasks", ["/Run", "/TN", taskName(exec)]);
+            return [`  ${kind}: the Pantheon host was not running — started it, and the ${kind} with it, on the new code`];
+        }
         if (plat === "darwin") {
             if (st.loaded && st.from && resolve(st.from) !== resolve(plistPath(kind)) && existsSync(plistPath(kind))) {
                 exec("launchctl", ["bootout", `gui/${uid}/${LABEL(kind)}`]);
@@ -377,8 +504,20 @@ export function restartService(kind, exec = realExec, opts = {}) {
         return [`  ${kind}: could not restart (${e.message.split("\n")[0]}) — pantheon service restart ${kind}`];
     }
 }
-export function refreshServiceDefinition(kind, plat = platform()) {
+export function refreshServiceDefinition(kind, plat = platform(), sys) {
     try {
+        if (plat === "win32") {
+            if (!isHostKind(kind) || !existsSync(hostFiles().definition(kind)))
+                return { changed: false };
+            const s = sys ?? realSys();
+            const t = ensureTask(s, undefined, { migrate: "unattended" });
+            const name = taskName(s.exec, s.env);
+            const said = [
+                ...(t.changed ? [`  ${kind}: the ${name} task now runs ${t.launch.command} — from the host's next start`] : []),
+                ...(t.migrated ? [`  removed the "${LEGACY_TASK_NAME}" task an earlier Pantheon registered — ${name} starts the host from your next logon (the one running now keeps running)`] : []),
+            ];
+            return said.length ? { changed: false, line: said.join("\n") } : { changed: false };
+        }
         if (plat === "darwin") {
             const p = plistPath(kind);
             if (!existsSync(p))
@@ -397,21 +536,21 @@ export function refreshServiceDefinition(kind, plat = platform()) {
             writeFileSync(p, servicePlist(kind, cwd, logDir, argv.slice(at + 1)));
             return { changed: true, line: `  ${kind}: its log now goes to ${join(logDir, `${kind}.log`)}${log ? ` (was ${unxml(log)})` : ""}` };
         }
-        if (plat === "win32")
-            return { changed: false };
         const u = existingUnitPath(kind);
         if (!u)
             return { changed: false };
         const unit = readFileSync(u, "utf8");
-        if (/^Environment="PATH=/m.test(unit) && !/^Environment="PATH=.*\$\$/m.test(unit))
-            return { changed: false };
+        const dropped = dropOtherTargetLink(u, kind === "notifier" && /^WantedBy=graphical-session\.target/m.test(unit));
+        if (/^Environment="PATH=/m.test(unit) && !/^Environment="PATH=.*\$\$/m.test(unit)) {
+            return dropped ? { changed: true, line: `  ${kind}: removed a second start-up link (${dropped})` } : { changed: false };
+        }
         const exec = /^ExecStart=(.*)$/m.exec(unit)?.[1] ?? "";
         const words = exec.startsWith('"') ? [...exec.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1].replace(/\\(.)/g, "$1").replace(/%%/g, "%").replace(/\$\$/g, "$")) : exec.split(/\s+/);
         const at = words.indexOf(kind);
         const cwd = (/^WorkingDirectory=(.*)$/m.exec(unit)?.[1] ?? homedir()).replace(/%%/g, "%");
         if (at < 0)
             return { changed: false };
-        writeFileSync(u, systemdUnit(kind, cwd, words.slice(at + 1)));
+        writeFileSync(u, systemdUnit(kind, cwd, words.slice(at + 1), servicePath(), { graphical: /^WantedBy=graphical-session\.target/m.test(unit) }));
         return { changed: true, line: `  ${kind}: its unit now quotes its paths and carries your PATH` };
     }
     catch (e) {
@@ -422,11 +561,298 @@ const unxml = (s) => s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp
 export function serviceInstalled(kind, plat = platform()) {
     try {
         if (plat === "win32")
-            return false;
+            return isHostKind(kind) && existsSync(hostFiles().definition(kind));
         return plat === "darwin" ? existsSync(plistPath(kind)) : existingUnitPath(kind) !== null;
     }
     catch {
         return false;
     }
 }
+const blockingSleep = (ms) => { try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+catch { } };
+function waitFor(done, ms, sleep) {
+    for (let waited = 0;; waited += 200) {
+        if (done())
+            return true;
+        if (waited >= ms)
+            return false;
+        sleep(200);
+    }
+}
+function nonDefaultHome() {
+    const ph = process.env.PANTHEON_HOME;
+    if (!ph)
+        return null;
+    return resolve(ph).toLowerCase() === resolve(join(homedir(), ".pantheon")).toLowerCase() ? null : resolve(ph);
+}
+export function windowsVersionManaged(p) {
+    return isVersionManagedPath(p)
+        || /[\\/]nvm[\\/]v\d+\.\d+\.\d+[\\/]/i.test(p)
+        || /[\\/]volta[\\/]tools[\\/]/i.test(p)
+        || /[\\/]fnm[\\/]node-versions[\\/]/i.test(p)
+        || /[\\/]fnm_multishells[\\/]/i.test(p)
+        || /[\\/]scoop[\\/]apps[\\/]nodejs(?:-lts)?[\\/]\d/i.test(p);
+}
+export function hostRuntime(o) {
+    if (o.layout)
+        return { node: o.layout.node, cli: o.layout.cli, flags: ["--use-system-ca"] };
+    const moving = windowsVersionManaged;
+    if (!moving(o.execPath) && !moving(o.cli))
+        return { node: o.execPath, cli: o.cli, flags: o.flags };
+    if (o.installed && o.exists(o.installed.node) && o.exists(o.installed.cli))
+        return { node: o.installed.node, cli: o.installed.cli, flags: ["--use-system-ca"] };
+    if (!moving(o.cli)) {
+        const node = o.nodesOnPath.find((n) => !!n && !moving(n) && o.exists(n));
+        if (node)
+            return { node, cli: o.cli, flags: o.flags };
+    }
+    throw new Error(`this Pantheon runs from ${moving(o.cli) ? o.cli : o.execPath}, a folder a Node version manager replaces when you switch Node versions — a logon task naming it would start nothing after the next switch. Install Pantheon with its own Node (irm https://relay.joinpantheon.network/install.ps1 | iex) or with a Node from nodejs.org (npm install -g @join-pantheon/cli), then run this again`);
+}
+function installedManagedLayout(env) {
+    const local = env.LOCALAPPDATA;
+    return local ? managedLayout(`${local.replace(/[\\/]+$/, "")}\\Pantheon\\runtime\\node\\node.exe`, "win32") : null;
+}
+export function desiredTask(sys, log, rt) {
+    const env = sys.env ?? process.env;
+    const runtime = rt || !sys.hostRuntime ? hostRuntime({
+        execPath: process.execPath, cli: resolve(HERE, "cli.js"), flags: childNodeFlags(),
+        layout: managedLayout(process.execPath, "win32"), installed: installedManagedLayout(env),
+        nodesOnPath: [which("node") ?? ""], exists: existsSync,
+        ...rt,
+    }) : sys.hostRuntime;
+    const shim = ensureHostShim({ exec: (c, a) => sys.exec(c, a), env, ...(log ? { log } : {}) });
+    const home = nonDefaultHome();
+    const launch = hostLaunch({ shim, node: runtime.node, flags: runtime.flags, cli: runtime.cli, home, launch: hostFiles().launch, powershell: windowsPowerShell(env) });
+    const name = taskName(sys.exec, env);
+    return { launch, argv: hostArgv(runtime), name, xml: taskXml({ launch, userId: taskUserId(sys.user, env), workingDirectory: homedir(), name }) };
+}
+export function ensureTask(sys, log, opts = {}) {
+    const f = hostFiles();
+    const { xml, launch, argv, name } = desiredTask(sys, log);
+    const text = launchFileText(argv);
+    let had = null;
+    try {
+        had = readFileSync(f.launch, "utf8");
+    }
+    catch { }
+    if (had !== text) {
+        mkdirSync(f.dir, { recursive: true });
+        writeFileSync(`${f.launch}.next`, text);
+        renameSync(`${f.launch}.next`, f.launch);
+    }
+    let last = null;
+    try {
+        last = fromUtf16le(readFileSync(f.taskXml));
+    }
+    catch { }
+    let registered = false;
+    try {
+        sys.exec("schtasks", ["/Query", "/TN", name]);
+        registered = true;
+    }
+    catch { }
+    let changed = false;
+    if (!registered || last !== xml) {
+        mkdirSync(f.dir, { recursive: true });
+        const next = `${f.taskXml}.next`;
+        writeFileSync(next, utf16le(xml));
+        try {
+            sys.exec("schtasks", ["/Create", "/XML", next, "/TN", name, "/F"]);
+        }
+        catch (e) {
+            rmSync(next, { force: true });
+            throw e;
+        }
+        renameSync(next, f.taskXml);
+        changed = true;
+    }
+    const migrated = opts.migrate ? replaceLegacyTask(sys, name, opts.migrate === "unattended", log) : false;
+    return { changed, launch, migrated };
+}
+function replaceLegacyTask(sys, name, unattended, log) {
+    const env = sys.env ?? process.env;
+    if (!legacyTaskIsUsers(sys.exec, env))
+        return false;
+    if (!unattended)
+        for (const l of stopWindowsHost(sys))
+            log?.(l);
+    try {
+        sys.exec("schtasks", ["/Delete", "/TN", LEGACY_TASK_NAME, "/F"]);
+        log?.(`  removed the "${LEGACY_TASK_NAME}" task an earlier Pantheon registered — it is ${name} now, so a second person on this PC can have their own${unattended && hostUp() ? " (the host running now keeps running; from your next logon the new task starts it)" : ""}`);
+        return true;
+    }
+    catch (e) {
+        log?.(`  could not remove the older "${LEGACY_TASK_NAME}" task (${e.message.split("\n")[0]}) — schtasks /Delete /TN ${LEGACY_TASK_NAME} /F`);
+        return false;
+    }
+}
+const hostUp = () => hostAlive(readHostState());
+const windowsBorrowed = (sys) => (sys.borrowed ?? (() => borrowedScheduler(sys.env ?? process.env)))();
+function installWindows(kind, cwd, args, sys) {
+    if (!isHostKind(kind)) {
+        throw new Error(kind === "menubar"
+            ? "the menu bar is macOS's — on Windows the Pantheon tray icon runs with the background host that pantheon service install worker (or notifier) sets up"
+            : "the relay does not run as a Windows background service — run it in a terminal (pantheon relay), or use the hosted relay");
+    }
+    const out = [];
+    let loaded = true;
+    let reason;
+    const f = hostFiles();
+    out.push(`  wrote ${writeDefinition({ kind, cwd, args })}`);
+    rmSync(f.disabled(kind), { force: true });
+    if (clearTrayQuit())
+        out.push("  the tray icon, which you had quit, shows again");
+    mkdirSync(serviceLogDir(), { recursive: true });
+    const name = taskName(sys.exec, sys.env);
+    try {
+        const t = ensureTask(sys, (l) => out.push(l), { migrate: true });
+        if (t.changed) {
+            out.push(`  registered the ${name} task — it starts Pantheon's background host at logon, hidden${t.launch.how === "powershell" ? " (through PowerShell: a console may show for a moment at logon)" : ""}`);
+        }
+        if (hostUp())
+            out.push(`  the host is running — it starts the ${kind} within seconds, and restarts it if it stops`);
+        else {
+            sys.exec("schtasks", ["/Run", "/TN", name]);
+            out.push(`  started — the ${kind} now starts at logon and restarts if it stops`);
+        }
+    }
+    catch (e) {
+        const why = e.message.split("\n")[0];
+        loaded = false;
+        reason = why;
+        if (windowsBorrowed(sys)) {
+            reason = `this Pantheon home (${CONFIG_DIR}) is not your own, so Task Scheduler was not touched`;
+            out.push(`  left unregistered — ${reason}; your own services are unchanged`);
+        }
+        else
+            out.push(`  could not register or start the ${name} task: ${why}`);
+    }
+    out.push(`  logs:   ${serviceLogFile(kind)}`);
+    out.push(`  stop:   pantheon service uninstall ${kind}`);
+    return Object.assign(out, { loaded, ...(reason ? { reason } : {}) });
+}
+export function stopWindowsHost(sys = realSys()) {
+    const f = hostFiles();
+    if (!hostUp())
+        return [];
+    mkdirSync(f.dir, { recursive: true });
+    writeFileSync(f.stop, new Date().toISOString());
+    const gone = waitFor(() => !hostUp(), 10_000, sys.sleep ?? blockingSleep);
+    if (gone)
+        return ["  the Pantheon host stopped (the tray with it)"];
+    const env = sys.env ?? process.env;
+    try {
+        sys.exec("schtasks", ["/End", "/TN", taskName(sys.exec, env)]);
+    }
+    catch { }
+    if (legacyTaskIsUsers(sys.exec, env)) {
+        try {
+            sys.exec("schtasks", ["/End", "/TN", LEGACY_TASK_NAME]);
+        }
+        catch { }
+    }
+    const pid = readHostState()?.pid;
+    return [`  the Pantheon host did not stop in time — ended its task${hostUp() ? `; pid ${pid} still answers: taskkill /PID ${pid} /T /F` : ""}`];
+}
+function uninstallWindows(kind, sys) {
+    if (!isHostKind(kind))
+        return null;
+    const f = hostFiles();
+    const def = f.definition(kind);
+    if (!existsSync(def))
+        return null;
+    const out = [];
+    rmSync(def, { force: true });
+    rmSync(f.disabled(kind), { force: true });
+    rmSync(f.restart(kind), { force: true });
+    const others = HOST_KINDS.filter((k) => k !== kind && existsSync(f.definition(k)));
+    const sleep = sys.sleep ?? blockingSleep;
+    if (others.length) {
+        const stopped = waitFor(() => !hostChildRunning(kind), 6_000, sleep);
+        out.push(stopped ? "  stopped" : "  the host stops it within seconds");
+        out.push(`  removed ${def}`);
+        out.push(`  the Pantheon host keeps running the ${others.join(" and ")}`);
+        return out;
+    }
+    out.push(...stopWindowsHost(sys));
+    const env = sys.env ?? process.env;
+    const name = taskName(sys.exec, env);
+    const remove = (task) => {
+        try {
+            sys.exec("schtasks", ["/Delete", "/TN", task, "/F"]);
+            out.push(`  removed the ${task} task`);
+            if (task === name) {
+                rmSync(f.taskXml, { force: true });
+                rmSync(f.launch, { force: true });
+            }
+        }
+        catch (e) {
+            let still = false;
+            try {
+                sys.exec("schtasks", ["/Query", "/TN", task]);
+                still = true;
+            }
+            catch { }
+            if (still) {
+                out.push(windowsBorrowed(sys)
+                    ? `  left the ${task} task alone — this Pantheon home (${CONFIG_DIR}) is not your own; with nothing installed here its host exits at once`
+                    : `  could not remove the ${task} task (${e.message.split("\n")[0]}) — schtasks /Delete /TN ${task} /F`);
+            }
+        }
+    };
+    remove(name);
+    if (legacyTaskIsUsers(sys.exec, env))
+        remove(LEGACY_TASK_NAME);
+    out.push(`  removed ${def}`);
+    if (!hostUp()) {
+        try {
+            rmSync(f.dir, { recursive: true, force: true });
+            out.push(`  removed ${f.dir}`);
+        }
+        catch { }
+    }
+    return out;
+}
+function disableWindows(kind, sys) {
+    if (!isHostKind(kind))
+        throw new Error(`the ${kind} is not a background service on Windows`);
+    const f = hostFiles();
+    mkdirSync(f.dir, { recursive: true });
+    writeFileSync(f.disabled(kind), new Date().toISOString());
+    waitFor(() => !hostChildRunning(kind), 6_000, sys.sleep ?? blockingSleep);
+}
+export function enableService(kind, sys = realSys()) {
+    if (sys.platform !== "win32")
+        throw new Error("service start is the Windows host's; elsewhere: pantheon service install");
+    if (!isHostKind(kind) || !readDefinition(kind))
+        throw new Error(`the ${kind} is not installed here — pantheon service install ${kind}`);
+    const f = hostFiles();
+    const was = existsSync(f.disabled(kind));
+    rmSync(f.disabled(kind), { force: true });
+    const tray = clearTrayQuit() ? ["  the tray icon, which you had quit, shows again"] : [];
+    if (hostUp())
+        return [`  ${kind}: ${was ? "resumed" : "already on"} — the Pantheon host ${was ? "starts it within seconds" : "runs it"}`, ...tray];
+    const lines = [];
+    ensureTask(sys, (l) => lines.push(l), { migrate: true });
+    sys.exec("schtasks", ["/Run", "/TN", taskName(sys.exec, sys.env)]);
+    return [...lines, `  ${kind}: ${was ? "resumed" : "on"} — started the Pantheon host, which runs it`, ...tray];
+}
+export function showTray(sys = realSys()) {
+    const f = hostFiles();
+    const quit = clearTrayQuit();
+    if (!HOST_KINDS.some((k) => existsSync(f.definition(k)))) {
+        return ["  the tray runs with Pantheon's background host, and nothing is installed here — pantheon service install notifier (or worker)"];
+    }
+    if (hostUp()) {
+        mkdirSync(f.dir, { recursive: true });
+        writeFileSync(f.restart("tray"), new Date().toISOString());
+        return [`  ${quit ? "the tray icon shows again within seconds" : "the tray icon is started again within seconds"}`];
+    }
+    const lines = [];
+    ensureTask(sys, (l) => lines.push(l), { migrate: true });
+    sys.exec("schtasks", ["/Run", "/TN", taskName(sys.exec, sys.env)]);
+    return [...lines, "  started the Pantheon host, and the tray icon with it"];
+}
 //# sourceMappingURL=service.js.map

package/dist/setup-guide.js

@@ -7,6 +7,7 @@ import { applyProfileInit, loadProfile, profilePath, saveProfile, wakeMode } fro
 import { installService as realInstall, uninstallService as realUninstall, serviceInstalled as realInstalled } from "./service.js";
 import { personaDir } from "./persona.js";
 import { hudBinaryPath } from "./notifier.js";
+import { hostEnv } from "./host-env.js";
 import { grant, inWokenRun, loadPolicy, revoke, savePolicy, unsandboxedAllowed } from "./worker-policy.js";
 export const DECISION_AREAS = [
     { id: "product", label: "Product — what we build, for whom, and what goes in a release" },
@@ -175,6 +176,8 @@ export async function runGuide(io, ctx, deps = {}, preset = {}) {
     const serves = ctx.project ? { path: ctx.project, repos: true } : ctx.serves ?? null;
     const os = deps.platform ?? process.platform;
     const mac = os === "darwin";
+    const linuxDesktop = os === "linux" && (deps.desktop ?? hostEnv(process.env, os).desktop);
+    const winDesktop = os === "win32" && (deps.desktop ?? hostEnv(process.env, os).desktop);
     const install = deps.installService ?? realInstall;
     const uninstall = deps.uninstallService ?? realUninstall;
     const installed = deps.serviceInstalled ?? realInstalled;
@@ -295,7 +298,7 @@ export async function runGuide(io, ctx, deps = {}, preset = {}) {
             warnings.push(`profile saved but not published (${e.message}) — run \`pantheon profile publish\` when the relay is reachable`);
         }
     }
-    const wiring = deps.applyAgentWiring ?? ((ap) => installForUser(ap).map((t) => ({ tool: t.tool, status: t.status })));
+    const wiring = deps.applyAgentWiring ?? ((ap) => installForUser(ap, undefined, { direct: true }).map((t) => ({ tool: t.tool, status: t.status })));
     try {
         const rows = wiring(a.approval);
         const failed = rows.filter((t) => /^failed/.test(t.status));
@@ -385,13 +388,27 @@ export async function runGuide(io, ctx, deps = {}, preset = {}) {
         applied.push(`alerts off — decisions still wait in ${waitIn}`);
     }
     else if (optOut.notifications) {
-        applied.push(`alerts: not installed (--no-notifications) — decisions wait in ${waitIn}. Your choice (${chosenAlerts.toLowerCase()}) is saved for when you turn them on${mac ? ": pantheon service install notifier" : ""}`);
+        applied.push(`alerts: not installed (--no-notifications) — decisions wait in ${waitIn}. Your choice (${chosenAlerts.toLowerCase()}) is saved for when you turn them on${mac || linuxDesktop || winDesktop ? ": pantheon service install notifier" : ""}`);
     }
-    else if (!mac) {
-        applied.push(`alerts: none on this machine — desktop alerts are macOS-only. Decisions wait in ${waitIn} (your choice, ${chosenAlerts.toLowerCase()}, is saved)`);
+    else if (os === "linux" && !linuxDesktop) {
+        applied.push(`alerts: none in this session — desktop alerts need a graphical login, and this is SSH or headless. Decisions wait in ${waitIn} and pantheon board --watch (your choice, ${chosenAlerts.toLowerCase()}, is saved)`);
+    }
+    else if (os === "win32" && !winDesktop) {
+        applied.push(`alerts: none in this session — desktop alerts need the Windows desktop, and this is a remote shell (SSH). Decisions wait in ${waitIn} and pantheon board; set Pantheon up from a session at the desktop for alerts (your choice, ${chosenAlerts.toLowerCase()}, is saved)`);
+    }
+    else if (!mac && !linuxDesktop && !winDesktop) {
+        applied.push(`alerts: none on this machine — desktop alerts run on macOS, Windows and Linux desktops, and this is ${os}. Decisions wait in ${waitIn} (your choice, ${chosenAlerts.toLowerCase()}, is saved)`);
     }
     else {
-        if (!installed("notifier")) {
+        if (!installed("notifier") && (linuxDesktop || winDesktop)) {
+            try {
+                install("notifier", deps.home ?? homedir(), []);
+            }
+            catch (e) {
+                warnings.push(`alerts did not install: ${e.message}`);
+            }
+        }
+        else if (!installed("notifier")) {
             if (existsSync(hudBinaryPath(deps.home))) {
                 try {
                     install("notifier", deps.home ?? homedir(), []);