@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/mesh/live/daemon/install.js

@@ -4,6 +4,8 @@
  * - macOS: LaunchAgent ai.getindigo.hq-mesh-daemon
  * - Linux: systemd user unit hq-mesh-daemon.service
  *   (documented fallback: root-owned unit running as ec2-user)
+ * - Windows: per-user Scheduled Task ai.getindigo.hq-mesh-daemon registered
+ *   from a rendered task XML via schtasks.exe (no native dependencies)
  *
  * The unit embeds the hq binary resolved at install time. Logs go to
  * ~/.hq/work-mesh/daemon/log (rotation at 5MB handled by the daemon).
@@ -12,20 +14,282 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+import semver from "semver";
 import { resolveDaemonAssetDir } from "./log.js";
-import { LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, daemonDir, daemonLogPath, } from "./paths.js";
+import { LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, WINDOWS_TASK_NAME, daemonDir, daemonLogPath, daemonPidPath, } from "./paths.js";
+import { isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot, verifyHqRoot } from "./config.js";
+import { defaultPidLockDeps, pidLockStatus, readPidLock } from "./pid-lock.js";
+import { retireLegacyListen } from "./legacy-listen.js";
+import { readDaemonState } from "./state.js";
+import { activateLaunchd, defaultRunCommand, launchdIsLoaded, launchdServiceTarget, launchdPlistProgramArguments, launchdProgramArgumentsDiffer, parseLaunchctlPrintArguments, } from "../../../service-manager/launchd.js";
+import { activateSystemd, systemdIsActive } from "../../../service-manager/systemd.js";
+import { nodeBinaryProblem, preferStableNodeBinary } from "../../../node-binary.js";
+/**
+ * `schtasks /End` terminates the task's root process only. The daemon is
+ * launched through `conhost.exe --headless`, so ending the task kills conhost
+ * and leaves node running as an orphan that still holds the pid lock. Stop
+ * the recorded daemon pid explicitly. Returns the pid that was signalled, or
+ * null when no live daemon pid was recorded.
+ */
+export function stopWindowsDaemonProcess(dir, deps = {}) {
+    const record = readPidLock(daemonPidPath(dir), {
+        readFileSync: deps.readFileSync,
+        existsSync: deps.existsSync,
+    });
+    if (!record || record.pid === (deps.selfPid ?? process.pid))
+        return null;
+    try {
+        (deps.kill ?? ((pid) => process.kill(pid)))(record.pid);
+        return record.pid;
+    }
+    catch {
+        return null;
+    }
+}
+export const defaultSchtasks = (args) => {
+    const r = spawnSync("schtasks.exe", args, { encoding: "utf8", windowsHide: true });
+    return {
+        status: r.status,
+        stdout: r.stdout ?? "",
+        stderr: r.error ? r.error.message : (r.stderr ?? ""),
+    };
+};
+function readServiceText(file, existsSync, readFileSync) {
+    if (!existsSync(file))
+        return "";
+    const raw = readFileSync(file);
+    const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(String(raw));
+    if ((buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) || buf.includes(0)) {
+        return buf.toString("utf16le").replace(/^\uFEFF/, "");
+    }
+    return buf.toString("utf8");
+}
+function hqRootFromUnitText(platform, text) {
+    if (platform === "win32")
+        return parseWindowsTaskHqRoot(text);
+    if (platform === "darwin") {
+        const match = /<key>HQ_ROOT<\/key>\s*<string>([^<]*)<\/string>/.exec(text);
+        return match?.[1] ?? null;
+    }
+    const match = /^Environment=HQ_ROOT=(.*)$/m.exec(text);
+    if (!match)
+        return null;
+    const value = match[1].trim();
+    return value.startsWith("'") && value.endsWith("'") ? value.slice(1, -1) : value;
+}
+/**
+ * Record the HQ root the daemon was serving and replace a pre-allowlist unit
+ * before the process is restarted. A unit with no HQ_ROOT (or Restart=on-failure)
+ * comes back with an empty root allowlist unless this runs first.
+ */
+function migrateLegacyDaemonUnit(opts) {
+    const { platform, home } = opts;
+    if (platform !== "darwin" && platform !== "linux" && platform !== "win32")
+        return;
+    const unitPath = platform === "darwin"
+        ? path.join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`)
+        : platform === "linux"
+            ? path.join(home, ".config", "systemd", "user", SYSTEMD_UNIT_NAME)
+            : path.join(daemonDir(undefined, home, opts.env), `${WINDOWS_TASK_NAME}.xml`);
+    if (!opts.existsSync(unitPath))
+        return;
+    const text = readServiceText(unitPath, opts.existsSync, opts.readFileSync);
+    const fromUnit = hqRootFromUnitText(platform, text);
+    const verified = verifyHqRoot(fromUnit ?? undefined)
+        ?? verifyHqRoot(opts.hqRoot)
+        ?? verifyHqRoot(opts.env?.HQ_ROOT);
+    if (!verified)
+        return;
+    registerTrustedHqRoot(daemonDir(undefined, home, opts.env), verified);
+    const legacy = platform === "linux"
+        ? !text.includes("Environment=HQ_ROOT=") || /Restart=on-failure/.test(text)
+        : platform === "darwin"
+            ? !/<key>HQ_ROOT<\/key>/.test(text)
+            : !fromUnit;
+    if (!legacy)
+        return;
+    const paths = buildInstallPaths({
+        home,
+        env: opts.env,
+        hqRoot: verified,
+        hqBinary: "/usr/bin/hq",
+        nodeBinary: process.execPath ? resolveNodeBinary(process.execPath, opts.env ?? process.env) : "/usr/bin/node",
+    });
+    try {
+        paths.hqBinary = resolveHqBinary(process.argv, opts.env ?? process.env);
+    }
+    catch {
+        // The rendered command only has to name a binary; install already resolved one.
+    }
+    if (platform === "darwin") {
+        opts.writeFileSync(unitPath, renderLaunchdPlist(paths), { mode: 0o600 });
+        return;
+    }
+    if (platform === "linux") {
+        opts.writeFileSync(unitPath, renderSystemdUserUnit(paths), { mode: 0o600 });
+        opts.run("systemctl", ["--user", "daemon-reload"]);
+        return;
+    }
+    const rendered = renderWindowsTaskXml(paths);
+    opts.writeFileSync(unitPath, encodeWindowsTaskXml(rendered));
+    opts.run("schtasks.exe", ["/Create", "/TN", WINDOWS_TASK_NAME, "/XML", unitPath, "/F"]);
+}
+/**
+ * Restart the installed user daemon after a CLI upgrade. This is deliberately
+ * best-effort: an update must remain successful if a user has no service,
+ * launchctl/systemd is unavailable, or the user manager is not running.
+ */
+function asRunCommand(run) {
+    return (command, args) => {
+        const result = run(command, args);
+        return {
+            status: result.status,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+        };
+    };
+}
+export function restartDaemonServiceIfInstalled(opts = {}) {
+    const platform = opts.platform ?? detectPlatform();
+    const home = opts.home ?? os.homedir();
+    const existsSync = opts.existsSync ?? fs.existsSync;
+    const readFileSync = opts.readFileSync ?? fs.readFileSync;
+    const writeFileSync = opts.writeFileSync ?? fs.writeFileSync;
+    const run = opts.run ?? ((command, args) => {
+        const result = spawnSync(command, args, { encoding: "utf8" });
+        return {
+            status: result.status,
+            stdout: typeof result.stdout === "string" ? result.stdout : "",
+            stderr: result.error ? result.error.message : (typeof result.stderr === "string" ? result.stderr : ""),
+        };
+    });
+    try {
+        migrateLegacyDaemonUnit({ platform, home, hqRoot: opts.hqRoot, env: opts.env, existsSync, readFileSync, writeFileSync, run });
+        if (platform === "darwin") {
+            const plist = path.join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+            if (!existsSync(plist))
+                return { attempted: false, restarted: false };
+            const uid = opts.uid ?? process.getuid?.();
+            if (typeof uid !== "number")
+                return { attempted: false, restarted: false };
+            const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+            const printed = run("launchctl", ["print", target]);
+            const loadedArgs = parseLaunchctlPrintArguments(printed.stdout ?? "");
+            const rawPlist = readFileSync(plist);
+            const plistText = Buffer.isBuffer(rawPlist) ? rawPlist.toString("utf8") : String(rawPlist);
+            const plistArgs = launchdPlistProgramArguments(plistText);
+            if (launchdProgramArgumentsDiffer(loadedArgs, plistArgs)) {
+                try {
+                    activateLaunchd(plist, asRunCommand(run), uid, { sleep: opts.sleep });
+                    return { attempted: true, restarted: true };
+                }
+                catch (err) {
+                    return { attempted: true, restarted: false, message: err instanceof Error ? err.message : String(err) };
+                }
+            }
+            const result = run("launchctl", ["kickstart", "-k", target]);
+            return { attempted: true, restarted: result.status === 0 };
+        }
+        if (platform === "linux") {
+            const unit = path.join(home, ".config", "systemd", "user", SYSTEMD_UNIT_NAME);
+            if (existsSync(unit)) {
+                const result = run("systemctl", ["--user", "restart", SYSTEMD_UNIT_NAME]);
+                return { attempted: true, restarted: result.status === 0 };
+            }
+            const systemUnit = path.join("/etc", "systemd", "system", SYSTEMD_UNIT_NAME);
+            if (existsSync(systemUnit)) {
+                return {
+                    attempted: true,
+                    restarted: false,
+                    message: "system unit detected; restart requires the box's service manager",
+                };
+            }
+            return { attempted: false, restarted: false };
+        }
+        if (platform === "win32") {
+            const dir = daemonDir(undefined, home);
+            const xml = path.join(dir, `${WINDOWS_TASK_NAME}.xml`);
+            if (!existsSync(xml))
+                return { attempted: false, restarted: false };
+            run("schtasks.exe", ["/End", "/TN", WINDOWS_TASK_NAME]);
+            stopWindowsDaemonProcess(dir, { existsSync, kill: opts.kill });
+            const result = run("schtasks.exe", ["/Run", "/TN", WINDOWS_TASK_NAME]);
+            return { attempted: true, restarted: result.status === 0 };
+        }
+    }
+    catch {
+        // The caller has already completed the update; service restart failure is
+        // intentionally non-fatal and will be retried by normal service recovery.
+    }
+    return { attempted: false, restarted: false };
+}
 export function detectPlatform(platform = process.platform) {
     if (platform === "darwin")
         return "darwin";
     if (platform === "linux")
         return "linux";
+    if (platform === "win32")
+        return "win32";
     return "other";
 }
+/**
+ * HQ updates moved the CLI from toolchain/node/bin/hq to
+ * toolchain/npm-global/bin/hq. A LaunchAgent that still names the old path
+ * dies with MODULE_NOT_FOUND on the next restart. Prefer the live npm-global
+ * binary when both exist.
+ */
+export function preferStableHqBinary(entry) {
+    const stale = `${path.sep}toolchain${path.sep}node${path.sep}bin${path.sep}`;
+    const stable = `${path.sep}toolchain${path.sep}npm-global${path.sep}bin${path.sep}`;
+    if (!entry.includes(stale))
+        return entry;
+    const candidate = entry.replace(stale, stable);
+    if (candidate !== entry && fs.existsSync(candidate))
+        return path.resolve(candidate);
+    return entry;
+}
+/**
+ * Absolute path of the CLI entry that is executing this process.
+ * realpath of argv[1] only — never a PATH lookup of `hq`.
+ */
+export function resolveRunningCliEntry(argv = process.argv) {
+    const entry = argv[1];
+    if (!entry) {
+        throw new Error("Cannot resolve hq binary: process.argv[1] is empty");
+    }
+    try {
+        return fs.realpathSync(entry);
+    }
+    catch {
+        throw new Error(`Cannot resolve hq binary: ${entry} is not a real path`);
+    }
+}
+/**
+ * Absolute node binary for a service unit: the realpath of process.execPath,
+ * then its upgrade-stable alias (/opt/homebrew/bin/node rather than
+ * /opt/homebrew/Cellar/node/<version>/bin/node) when one resolves to the same
+ * binary. No PATH lookup of `node` by name.
+ */
+export function resolveAbsoluteNodeBinary(execPath = process.execPath) {
+    if (!execPath)
+        throw new Error("Cannot resolve node binary: execPath is empty");
+    let real;
+    try {
+        real = fs.realpathSync(execPath);
+    }
+    catch {
+        if (path.isAbsolute(execPath))
+            return execPath;
+        throw new Error(`Cannot resolve node binary: ${execPath} is not a real path`);
+    }
+    return preferStableNodeBinary(real);
+}
 /** Resolve the hq binary the current shell uses (argv[1] or PATH). */
 export function resolveHqBinary(argv = process.argv, env = process.env) {
     const entry = argv[1];
     if (entry && fs.existsSync(entry)) {
-        return path.resolve(entry);
+        return preferStableHqBinary(path.resolve(entry));
     }
     const pathEnv = env.PATH ?? "";
     for (const dir of pathEnv.split(path.delimiter)) {
@@ -39,9 +303,104 @@ export function resolveHqBinary(argv = process.argv, env = process.env) {
     }
     throw new Error("Cannot resolve hq binary for daemon install");
 }
+/** True when this CLI is newer than the version the daemon recorded, or nothing was recorded. */
+export function isNewerCliVersion(current, recorded) {
+    const recordedVersion = recorded?.trim() ?? "";
+    if (!recordedVersion)
+        return true;
+    if (semver.valid(current) && semver.valid(recordedVersion)) {
+        return semver.gt(current, recordedVersion);
+    }
+    return current !== recordedVersion;
+}
+/**
+ * Reinstall and restart the user daemon only when `currentVersion` is newer
+ * than daemon/state.json `cliVersion`. A missing record counts as stale.
+ * `run` is the launchctl/systemctl seam — tests pass a stub.
+ */
+export function installDaemonIfStale(opts) {
+    const recorded = readDaemonState(opts.paths.daemonDir)?.cliVersion;
+    const platformForUnit = opts.platform ?? detectPlatform();
+    const installedNode = installedDaemonNodeBinary(opts.paths, platformForUnit, opts.readUnit);
+    // Only a rewrite that changes the node path helps: a unit whose node is gone
+    // or versioned, while this install resolves a different (stable) one.
+    const nodeProblem = installedNode && installedNode !== opts.paths.nodeBinary
+        ? (opts.nodeProblem ?? nodeBinaryProblem)(installedNode)
+        : null;
+    if (!isNewerCliVersion(opts.currentVersion, recorded) && !nodeProblem) {
+        return {
+            reinstalled: false,
+            message: `daemon already records hq ${recorded}; not reinstalling`,
+        };
+    }
+    const run = opts.run ?? ((command, args) => {
+        const result = spawnSync(command, args, { encoding: "utf8" });
+        return {
+            status: result.status,
+            stdout: typeof result.stdout === "string" ? result.stdout : "",
+            stderr: typeof result.stderr === "string" ? result.stderr : "",
+        };
+    });
+    const platform = opts.platform ?? detectPlatform();
+    const installed = installDaemonService({
+        platform,
+        paths: opts.paths,
+        systemUser: opts.systemUser,
+        writeFileSync: opts.writeFileSync,
+        mkdirSync: opts.mkdirSync,
+        reloadSystemd: opts.reloadSystemd,
+        schtasks: opts.schtasks,
+        kill: opts.kill,
+        runCommand: opts.runCommand,
+        windowsLegacyTaskPresent: opts.windowsLegacyTaskPresent,
+        run,
+        uid: opts.uid,
+        sleep: opts.sleep,
+    });
+    if (platform === "linux" && !opts.systemUser && !opts.paths.systemUser) {
+        activateSystemd(SYSTEMD_UNIT_NAME, run);
+    }
+    return {
+        reinstalled: true,
+        message: `${installed.message} Restarted with ${opts.paths.nodeBinary} ${opts.paths.hqBinary}.`,
+    };
+}
+/**
+ * The node binary baked into the installed daemon unit (darwin plist or linux
+ * user unit), or null when there is no unit or it cannot be read. Used to
+ * reinstall a unit whose node was a versioned path an upgrade removed.
+ */
+export function installedDaemonNodeBinary(paths, platform, readUnit = (file) => {
+    try {
+        return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+    }
+    catch {
+        return null;
+    }
+}) {
+    if (platform === "darwin") {
+        const text = readUnit(paths.plistPath);
+        if (!text)
+            return null;
+        const block = text.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+        const first = block?.[1]?.match(/<string>([^<]*)<\/string>/);
+        return first?.[1] ?? null;
+    }
+    if (platform === "linux") {
+        const text = readUnit(paths.systemdUnitPath);
+        if (!text)
+            return null;
+        const m = text.match(/^ExecStart=('(?:[^']|'\\'')*'|\S+)/m);
+        if (!m)
+            return null;
+        const raw = m[1];
+        return raw.startsWith("'") ? raw.slice(1, -1).replace(/'\\''/g, "'") : raw;
+    }
+    return null;
+}
 export function resolveNodeBinary(execPath = process.execPath, env = process.env) {
     if (execPath && fs.existsSync(execPath))
-        return execPath;
+        return preferStableNodeBinary(execPath, { env });
     const pathEnv = env.PATH ?? "";
     for (const dir of pathEnv.split(path.delimiter)) {
         const candidate = path.join(dir, "node");
@@ -66,9 +425,71 @@ export function buildInstallPaths(opts) {
         plistPath: path.join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`),
         systemdUserDir: path.join(home, ".config", "systemd", "user"),
         systemdUnitPath: path.join(home, ".config", "systemd", "user", SYSTEMD_UNIT_NAME),
+        windowsTaskXmlPath: path.join(ddir, `${WINDOWS_TASK_NAME}.xml`),
+        windowsUser: opts.windowsUser ?? resolveWindowsUser(env),
+        windowsHeadlessLauncher: opts.windowsHeadlessLauncher === undefined
+            ? resolveWindowsHeadlessLauncher(env)
+            : (opts.windowsHeadlessLauncher ?? undefined),
         systemUser: opts.systemUser,
+        hqRoot: opts.hqRoot,
+        hqRootSource: opts.hqRootSource,
     };
 }
+/** `DOMAIN\user` for the current account, as Task Scheduler expects. */
+export function resolveWindowsUser(env = process.env) {
+    const user = env.USERNAME?.trim() || safeUsername();
+    const domain = env.USERDOMAIN?.trim();
+    return domain ? `${domain}\\${user}` : user;
+}
+/**
+ * `conhost.exe --headless` is undocumented. It shipped with the ConPTY
+ * conhost in Windows 10 1809 (build 17763); older conhost builds reject the
+ * flag and the task would fail on every logon. Gate on the kernel build
+ * reported by os.release() ("10.0.<build>") plus a presence check.
+ */
+export const WINDOWS_CONHOST_HEADLESS_MIN_BUILD = 17763;
+/** Build number from an os.release() string such as "10.0.26200"; null if unparsable. */
+export function parseWindowsBuild(release) {
+    const m = /^\d+\.\d+\.(\d+)/.exec(release.trim());
+    if (!m)
+        return null;
+    const build = Number(m[1]);
+    return Number.isFinite(build) ? build : null;
+}
+/**
+ * `conhost.exe --headless` (Windows 10 1809+) runs a console app with no
+ * window. Returns the launcher path only when conhost.exe exists under
+ * SystemRoot and the host build is new enough to honour `--headless`.
+ */
+export function resolveWindowsHeadlessLauncher(env = process.env, existsSync = fs.existsSync, release = os.release()) {
+    const build = parseWindowsBuild(release);
+    if (build === null || build < WINDOWS_CONHOST_HEADLESS_MIN_BUILD)
+        return undefined;
+    const systemRoot = env.SystemRoot?.trim() || env.windir?.trim() || "C:\\Windows";
+    const candidate = path.join(systemRoot, "System32", "conhost.exe");
+    return existsSync(candidate) ? candidate : undefined;
+}
+/** Which launch wrapper the rendered task uses (recorded in the install message). */
+export function windowsLaunchMode(paths) {
+    return paths.windowsHeadlessLauncher ? "conhost-headless" : "direct";
+}
+/** The task uses the interactive token, so it exists only inside the user's logon session. */
+export function windowsLogonNotice(paths) {
+    return `runs at logon of ${paths.windowsUser}; not running while logged out`;
+}
+function describeWindowsLaunchMode(paths) {
+    return windowsLaunchMode(paths) === "conhost-headless"
+        ? `mode: conhost --headless via ${paths.windowsHeadlessLauncher}`
+        : "mode: direct node (conhost --headless unavailable on this host; a console window may appear at logon)";
+}
+function safeUsername() {
+    try {
+        return os.userInfo().username;
+    }
+    catch {
+        return "";
+    }
+}
 export function renderLaunchdPlist(paths) {
     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">
@@ -100,6 +521,7 @@ export function renderLaunchdPlist(paths) {
     <string>${escapeXml(paths.home)}</string>
     <key>PATH</key>
     <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    ${paths.hqRoot ? `<key>HQ_ROOT</key>\n    <string>${escapeXml(paths.hqRoot)}</string>` : ""}
   </dict>
 </dict>
 </plist>
@@ -115,11 +537,11 @@ Wants=network-online.target
 Type=simple
 ExecStart=${shellQuote(paths.nodeBinary)} ${shellQuote(paths.hqBinary)} mesh daemon run
 WorkingDirectory=${paths.daemonDir}
-Restart=on-failure
+Restart=always
 RestartSec=5
 Environment=HOME=${paths.home}
 Environment=PATH=/usr/local/bin:/usr/bin:/bin
-StandardOutput=append:${paths.logPath}
+${paths.hqRoot ? `Environment=HQ_ROOT=${shellQuote(paths.hqRoot)}\n` : ""}StandardOutput=append:${paths.logPath}
 StandardError=append:${paths.logPath}
 
 [Install]
@@ -147,19 +569,237 @@ User=${user}
 Group=${user}
 ExecStart=${shellQuote(paths.nodeBinary)} ${shellQuote(paths.hqBinary)} mesh daemon run
 WorkingDirectory=/home/${user}/.hq/work-mesh/daemon
-Restart=on-failure
+Restart=always
 RestartSec=5
 Environment=HOME=/home/${user}
 Environment=PATH=/usr/local/bin:/usr/bin:/bin
 Environment=HQ_MACHINE_CREDS_FILE=/home/${user}/.hq-agent/machine-creds.json
 Environment=HQ_AGENT_IDENTITY_FILE=/var/lib/hq-agent/identity.json
-StandardOutput=append:/home/${user}/.hq/work-mesh/daemon/log
+${paths.hqRoot ? `Environment=HQ_ROOT=${shellQuote(paths.hqRoot)}\n` : ""}StandardOutput=append:/home/${user}/.hq/work-mesh/daemon/log
 StandardError=append:/home/${user}/.hq/work-mesh/daemon/log
 
 [Install]
 WantedBy=multi-user.target
 `;
 }
+/**
+ * Windows Task Scheduler definition (schtasks /Create /XML). Runs at logon of
+ * the registering user, hidden, no execution time limit, one instance, and
+ * restarts every minute on failure. HOME/USERPROFILE come from the user's own
+ * session. Task Scheduler XML has no environment block, so the HQ root the
+ * install was run for is passed explicitly as `mesh daemon run --hq-root
+ * <path>` (the launchd/systemd equivalent of Environment=HQ_ROOT) and is also
+ * persisted in the daemon config as a trusted root.
+ *
+ * LogonType is InteractiveToken: S4U ("run whether user is logged on or not")
+ * needs elevation to register, and the interactive token is what an
+ * unprivileged `hq mesh daemon install` can create. As a consequence the task
+ * runs only while the registering user is logged on. The console window that
+ * an interactive-token task would otherwise open is avoided by launching
+ * through `conhost.exe --headless` when the host supports it (see
+ * resolveWindowsHeadlessLauncher); otherwise node is run directly.
+ */
+export function renderWindowsTaskXml(paths) {
+    const user = escapeXml(paths.windowsUser);
+    const nodeArg = windowsArgQuote(paths.nodeBinary);
+    const hqArg = windowsArgQuote(paths.hqBinary);
+    const command = paths.windowsHeadlessLauncher ?? paths.nodeBinary;
+    const rootArgs = paths.hqRoot ? ` --hq-root ${windowsArgQuote(paths.hqRoot)}` : "";
+    const args = paths.windowsHeadlessLauncher
+        ? `--headless ${nodeArg} ${hqArg} mesh daemon run${rootArgs}`
+        : `${hqArg} mesh daemon run${rootArgs}`;
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <URI>\\${WINDOWS_TASK_NAME}</URI>
+    <Description>HQ Work Mesh Live daemon (spool drainer + MQTT presence)</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${user}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${user}</UserId>
+      <LogonType>${WINDOWS_TASK_LOGON_TYPE}</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>true</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <DisallowStartOnRemoteAppSession>false</DisallowStartOnRemoteAppSession>
+    <UseUnifiedSchedulingEngine>true</UseUnifiedSchedulingEngine>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${escapeXml(command)}</Command>
+      <Arguments>${escapeXml(args)}</Arguments>
+      <WorkingDirectory>${escapeXml(paths.daemonDir)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+const WINDOWS_TASK_LOGON_TYPE = "InteractiveToken";
+/** schtasks stores task XML as UTF-16 LE with BOM; match it so /XML parses. */
+export function encodeWindowsTaskXml(rendered) {
+    return Buffer.from(`\uFEFF${rendered}`, "utf16le");
+}
+function windowsArgQuote(value) {
+    if (/^[A-Za-z0-9_.:\\/-]+$/.test(value))
+        return value;
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+/** Status column of `schtasks /Query /FO CSV /NH`: "TaskName","Next Run Time","Status". */
+export function parseSchtasksCsvStatus(stdout) {
+    for (const line of stdout.split(/\r?\n/)) {
+        const cells = line.match(/"([^"]*)"/g);
+        if (!cells || cells.length < 3)
+            continue;
+        return cells[2].slice(1, -1).trim();
+    }
+    return null;
+}
+/** Split one CSV line as schtasks emits it (all cells quoted, `""` escapes a quote). */
+function splitCsvLine(line) {
+    const cells = [];
+    let cur = "";
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (line[i + 1] === '"') {
+                    cur += '"';
+                    i++;
+                }
+                else
+                    inQuotes = false;
+            }
+            else
+                cur += ch;
+        }
+        else if (ch === '"')
+            inQuotes = true;
+        else if (ch === ",") {
+            cells.push(cur);
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    cells.push(cur);
+    return cells;
+}
+/** Column index of "Last Result" in `schtasks /Query /V /FO CSV` (fixed order, header localized). */
+const SCHTASKS_LAST_RESULT_COLUMN = 6;
+/**
+ * "Last Result" of `schtasks /Query /TN <name> /V /FO CSV`, normalized to an
+ * unsigned 32-bit code (schtasks prints HRESULT/NTSTATUS values as signed
+ * decimals, e.g. -2147024894 for 0x80070002). Prefers the English header
+ * when present; otherwise uses the fixed column position. Null when the
+ * output carries no task row or the cell is not numeric.
+ */
+export function parseSchtasksLastResult(stdout) {
+    const lines = stdout.split(/\r?\n/).filter((l) => l.trim().length > 0);
+    if (lines.length === 0)
+        return null;
+    let column = SCHTASKS_LAST_RESULT_COLUMN;
+    let rows = lines;
+    const header = splitCsvLine(lines[0]);
+    const headerIdx = header.findIndex((h) => /^last result$/i.test(h.trim()));
+    if (headerIdx >= 0 || /^hostname$/i.test(header[0]?.trim() ?? "")) {
+        if (headerIdx >= 0)
+            column = headerIdx;
+        rows = lines.slice(1);
+    }
+    for (const line of rows) {
+        const cells = splitCsvLine(line);
+        if (cells.length <= column)
+            continue;
+        const raw = cells[column].trim();
+        if (!/^-?\d+$/.test(raw))
+            continue;
+        return Number(raw) >>> 0;
+    }
+    return null;
+}
+/**
+ * Task Scheduler informational results mean "no failed start": 0 is success,
+ * and every SCHED_S_* code (ready, running, not yet run, terminated, queued,
+ * ...) is a success-severity HRESULT (bit 31 clear) in FACILITY_ITF (0x4)
+ * with code 0x1300-0x13FF, i.e. 0x00041300-0x000413FF. Everything else
+ * (0x8007xxxx, 0xC000xxxx, process exit codes such as 1) is a failed start.
+ */
+export function schtasksLastResultFailed(code) {
+    if (code === null || code === 0)
+        return false;
+    const severityFailed = (code & 0x80000000) !== 0;
+    const facility = (code >>> 16) & 0x7ff;
+    const lowCode = code & 0xffff;
+    if (!severityFailed && facility === 0x4 && lowCode >= 0x1300 && lowCode <= 0x13ff)
+        return false;
+    return true;
+}
+/** `--hq-root <path>` from a rendered task's <Arguments> (XML-escaped, optionally quoted). */
+export function parseWindowsTaskHqRoot(xml) {
+    const m = /<Arguments>([^<]*)<\/Arguments>/.exec(xml);
+    if (!m)
+        return null;
+    const args = unescapeXml(m[1]);
+    const quoted = /--hq-root "((?:[^"\\]|\\.)*)"/.exec(args);
+    if (quoted)
+        return quoted[1].replace(/\\"/g, '"');
+    const bare = /--hq-root (\S+)/.exec(args);
+    return bare ? bare[1] : null;
+}
+/**
+ * The HQ root the installed Windows task actually carries: the task XML on
+ * disk first, else the first persisted trusted root. Reads state only; never
+ * resolves from cwd, so status reports what install recorded.
+ */
+export function readRecordedWindowsHqRoot(paths, deps = {}) {
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    const readFileSync = deps.readFileSync ?? fs.readFileSync;
+    try {
+        if (existsSync(paths.windowsTaskXmlPath)) {
+            const raw = readFileSync(paths.windowsTaskXmlPath);
+            const text = Buffer.isBuffer(raw) ? raw.toString("utf16le").replace(/^\uFEFF/, "") : String(raw);
+            const fromXml = parseWindowsTaskHqRoot(text);
+            if (fromXml)
+                return fromXml;
+        }
+    }
+    catch {
+        // fall through to config
+    }
+    return readDaemonConfig(paths.daemonDir).trustedHqRoots[0] ?? null;
+}
+function unescapeXml(value) {
+    return value
+        .replace(/&quot;/g, '"')
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
 function escapeXml(value) {
     return value
         .replace(/&/g, "&amp;")
@@ -179,18 +819,33 @@ export function installDaemonService(opts) {
     const writeFileSync = opts.writeFileSync ?? fs.writeFileSync;
     const mkdirSync = opts.mkdirSync ?? fs.mkdirSync;
     mkdirSync(paths.daemonDir, { recursive: true, mode: 0o700 });
+    registerTrustedHqRoot(paths.daemonDir, paths.hqRoot);
+    const retired = retireLegacyListen({
+        home: paths.home,
+        platform,
+        run: opts.runCommand,
+        windowsTaskPresent: opts.windowsLegacyTaskPresent,
+    });
+    const legacyNote = retired.removed
+        ? " Retired legacy listener ai.getindigo.hq-work-mesh-listen."
+        : "";
     if (platform === "darwin") {
         const rendered = renderLaunchdPlist(paths);
         mkdirSync(paths.launchAgentsDir, { recursive: true });
         writeFileSync(paths.plistPath, rendered, { mode: 0o600 });
-        opts.activate?.(platform, paths.plistPath);
+        if (opts.run) {
+            activateLaunchd(paths.plistPath, opts.run, opts.uid, { sleep: opts.sleep });
+        }
+        else {
+            opts.activate?.(platform, paths.plistPath);
+        }
         return {
             platform,
             action: "install",
             paths,
             rendered,
             dest: paths.plistPath,
-            message: `Installed LaunchAgent ${LAUNCHD_LABEL} → ${paths.plistPath}`,
+            message: `Installed LaunchAgent ${LAUNCHD_LABEL} → ${paths.plistPath}${legacyNote}`,
         };
     }
     if (platform === "linux") {
@@ -210,12 +865,13 @@ export function installDaemonService(opts) {
                 dest,
                 message: `Wrote system unit template for user ${opts.systemUser ?? paths.systemUser} at ${dest}. ` +
                     `Install with: sudo cp ${dest} /etc/systemd/system/${SYSTEMD_UNIT_NAME} && ` +
-                    `sudo systemctl daemon-reload && sudo systemctl enable --now ${SYSTEMD_UNIT_NAME}`,
+                    `sudo systemctl daemon-reload && sudo systemctl enable --now ${SYSTEMD_UNIT_NAME}${legacyNote}`,
             };
         }
         const rendered = renderSystemdUserUnit(paths);
         mkdirSync(paths.systemdUserDir, { recursive: true });
         writeFileSync(paths.systemdUnitPath, rendered, { mode: 0o600 });
+        (opts.reloadSystemd ?? (() => spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" })))();
         opts.activate?.(platform, paths.systemdUnitPath);
         return {
             platform,
@@ -223,14 +879,49 @@ export function installDaemonService(opts) {
             paths,
             rendered,
             dest: paths.systemdUnitPath,
-            message: `Installed systemd user unit ${SYSTEMD_UNIT_NAME} → ${paths.systemdUnitPath}`,
+            message: `Installed systemd user unit ${SYSTEMD_UNIT_NAME} → ${paths.systemdUnitPath}${legacyNote}`,
+        };
+    }
+    if (platform === "win32") {
+        const schtasks = opts.schtasks ?? defaultSchtasks;
+        const rendered = renderWindowsTaskXml(paths);
+        writeFileSync(paths.windowsTaskXmlPath, encodeWindowsTaskXml(rendered), { mode: 0o600 });
+        const created = schtasks([
+            "/Create", "/TN", WINDOWS_TASK_NAME, "/XML", paths.windowsTaskXmlPath, "/F",
+        ]);
+        if (created.status !== 0) {
+            throw new Error(`schtasks /Create failed for ${WINDOWS_TASK_NAME} (exit ${created.status ?? "signal"}): ` +
+                `${(created.stderr || created.stdout).trim()}`);
+        }
+        // /F replaced any previous registration without ending its instance; stop
+        // the recorded daemon so the fresh task instance can take the pid lock.
+        schtasks(["/End", "/TN", WINDOWS_TASK_NAME]);
+        stopWindowsDaemonProcess(paths.daemonDir, { kill: opts.kill });
+        const started = schtasks(["/Run", "/TN", WINDOWS_TASK_NAME]);
+        const running = started.status === 0;
+        const mode = describeWindowsLaunchMode(paths);
+        const rootLine = paths.hqRoot
+            ? `HQ root: ${paths.hqRoot}${paths.hqRootSource ? ` (from ${paths.hqRootSource})` : ""}\n`
+            : "";
+        return {
+            platform,
+            action: "install",
+            paths,
+            rendered,
+            dest: paths.windowsTaskXmlPath,
+            running,
+            message: running
+                ? `${rootLine}Installed Scheduled Task ${WINDOWS_TASK_NAME} → ${paths.windowsTaskXmlPath} (started; ${mode})${legacyNote}`
+                : `${rootLine}Installed Scheduled Task ${WINDOWS_TASK_NAME} → ${paths.windowsTaskXmlPath} (${mode}); ` +
+                    `start failed: ${(started.stderr || started.stdout).trim()}. It starts at next logon.${legacyNote}`,
+            notice: windowsLogonNotice(paths),
         };
     }
     return {
         platform,
         action: "install",
         paths,
-        message: `Unsupported platform for service install; run: ${paths.nodeBinary} ${paths.hqBinary} mesh daemon run`,
+        message: `Unsupported platform for service install; run: ${paths.nodeBinary} ${paths.hqBinary} mesh daemon run${legacyNote}`,
     };
 }
 export function uninstallDaemonService(opts) {
@@ -238,9 +929,44 @@ export function uninstallDaemonService(opts) {
     const paths = opts.paths ?? buildInstallPaths({});
     const unlinkSync = opts.unlinkSync ?? fs.unlinkSync;
     const existsSync = opts.existsSync ?? fs.existsSync;
+    if (platform === "win32") {
+        const schtasks = opts.schtasks ?? defaultSchtasks;
+        const registered = schtasks(["/Query", "/TN", WINDOWS_TASK_NAME, "/FO", "CSV", "/NH"]).status === 0;
+        if (registered) {
+            schtasks(["/End", "/TN", WINDOWS_TASK_NAME]);
+            stopWindowsDaemonProcess(paths.daemonDir, { existsSync, kill: opts.kill });
+            const deleted = schtasks(["/Delete", "/TN", WINDOWS_TASK_NAME, "/F"]);
+            if (deleted.status !== 0) {
+                throw new Error(`schtasks /Delete failed for ${WINDOWS_TASK_NAME} (exit ${deleted.status ?? "signal"}): ` +
+                    `${(deleted.stderr || deleted.stdout).trim()}`);
+            }
+        }
+        if (existsSync(paths.windowsTaskXmlPath))
+            unlinkSync(paths.windowsTaskXmlPath);
+        return {
+            platform,
+            action: "uninstall",
+            paths,
+            dest: paths.windowsTaskXmlPath,
+            message: registered
+                ? `Removed Scheduled Task ${WINDOWS_TASK_NAME}`
+                : `Scheduled Task ${WINDOWS_TASK_NAME} was not registered; removed local task XML if present`,
+        };
+    }
     if (platform === "darwin") {
         if (existsSync(paths.plistPath)) {
-            opts.deactivate?.(platform, paths.plistPath);
+            if (opts.deactivate) {
+                opts.deactivate(platform, paths.plistPath);
+            }
+            else {
+                const run = opts.run ?? defaultRunCommand;
+                const target = launchdServiceTarget(paths.plistPath, opts.uid);
+                const bootout = run("launchctl", ["bootout", target]);
+                if (bootout.status !== 0 && run("launchctl", ["print", target]).status === 0) {
+                    const detail = (bootout.stderr || bootout.stdout).trim();
+                    throw new Error(`launchctl bootout failed for ${target}${detail ? `: ${detail}` : ` (exit ${bootout.status})`}`);
+                }
+            }
             unlinkSync(paths.plistPath);
         }
         return {
@@ -275,10 +1001,82 @@ export function uninstallDaemonService(opts) {
         message: "Nothing to uninstall on this platform",
     };
 }
+/**
+ * Live service-manager probe for `daemonServiceStatus`: `launchctl print
+ * gui/<uid>/<label>` on macOS, `systemctl --user is-active` on Linux.
+ */
+export function daemonServiceIsLoaded(run, uid) {
+    return (platform) => {
+        if (platform === "darwin")
+            return launchdIsLoaded(LAUNCHD_LABEL, run, uid);
+        if (platform === "linux")
+            return systemdIsActive(SYSTEMD_UNIT_NAME, run);
+        return false;
+    };
+}
 export function daemonServiceStatus(opts) {
     const platform = opts.platform ?? detectPlatform();
     const paths = opts.paths ?? buildInstallPaths({});
     const existsSync = opts.existsSync ?? fs.existsSync;
+    if (platform === "win32") {
+        const schtasks = opts.schtasks ?? defaultSchtasks;
+        // schtasks only tells us whether the task exists. Its Status column is
+        // localized ("Running" / "Wird ausgeführt" / ...), so the daemon pid lock
+        // is the source of truth for "running"; the column is shown when it
+        // happens to carry a value, as extra context only.
+        const query = schtasks(["/Query", "/TN", WINDOWS_TASK_NAME, "/FO", "CSV", "/NH"]);
+        const installed = query.status === 0;
+        const taskState = installed ? parseSchtasksCsvStatus(query.stdout) : null;
+        // The verbose query carries "Last Result": a non-zero, non-informational
+        // code means the last start failed (for example conhost rejecting
+        // --headless), which the pid lock alone would report as merely "not
+        // running". Surface it so a failed start never looks like a clean idle.
+        const verbose = installed
+            ? schtasks(["/Query", "/TN", WINDOWS_TASK_NAME, "/V", "/FO", "CSV"])
+            : null;
+        const lastResult = verbose && verbose.status === 0 ? parseSchtasksLastResult(verbose.stdout) : null;
+        const lastRunFailed = schtasksLastResultFailed(lastResult);
+        const lock = pidLockStatus(daemonPidPath(paths.daemonDir), {
+            isProcessAlive: opts.isProcessAlive ?? defaultPidLockDeps().isProcessAlive,
+            readFileSync: opts.readFileSync,
+            existsSync,
+        });
+        const running = lock === "held";
+        // Read the root the task actually carries and re-check it: a moved,
+        // renamed, or deleted HQ tree leaves the task pointing at nothing.
+        const recordedHqRoot = installed
+            ? readRecordedWindowsHqRoot(paths, { existsSync, readFileSync: opts.readFileSync })
+            : null;
+        const rootValid = recordedHqRoot ? isInstallableHqRoot(recordedHqRoot) : undefined;
+        const detail = (taskState ? ` [task: ${taskState}]` : "") +
+            (lastRunFailed ? ` [last run failed: result ${lastResult}]` : "") +
+            (rootValid === false ? ` [recorded root no longer qualifies: ${recordedHqRoot}]` : "");
+        let message;
+        if (!installed) {
+            message = running
+                ? `Scheduled Task ${WINDOWS_TASK_NAME}: not installed (daemon running outside the task)`
+                : `Scheduled Task ${WINDOWS_TASK_NAME}: not installed`;
+        }
+        else if (running) {
+            message = `Scheduled Task ${WINDOWS_TASK_NAME}: running${detail}`;
+        }
+        else {
+            message = `Scheduled Task ${WINDOWS_TASK_NAME}: installed (daemon not running${lock === "stale" ? ", stale pid lock" : ""})${detail}`;
+        }
+        return {
+            platform,
+            action: "status",
+            paths,
+            dest: paths.windowsTaskXmlPath,
+            running,
+            message,
+            lastResult,
+            lastRunFailed,
+            notice: installed ? windowsLogonNotice(paths) : undefined,
+            recordedHqRoot,
+            rootValid,
+        };
+    }
     if (platform === "darwin") {
         const installed = existsSync(paths.plistPath);
         const running = installed