@indigoai-us/hq-cli 5.125.0 → 5.126.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).
@@ -14,8 +16,39 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
 import { resolveDaemonAssetDir } from "./log.js";
-import { LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, daemonDir, daemonLogPath, } from "./paths.js";
-import { registerTrustedHqRoot } from "./config.js";
+import { LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, WINDOWS_TASK_NAME, daemonDir, daemonLogPath, daemonPidPath, } from "./paths.js";
+import { isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot } from "./config.js";
+import { defaultPidLockDeps, pidLockStatus, readPidLock } from "./pid-lock.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 ?? ""),
+    };
+};
 /**
  * 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,
@@ -53,6 +86,16 @@ export function restartDaemonServiceIfInstalled(opts = {}) {
             }
             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
@@ -65,6 +108,8 @@ export function detectPlatform(platform = process.platform) {
         return "darwin";
     if (platform === "linux")
         return "linux";
+    if (platform === "win32")
+        return "win32";
     return "other";
 }
 /**
@@ -128,10 +173,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">
@@ -224,6 +330,224 @@ StandardError=append:/home/${user}/.hq/work-mesh/daemon/log
 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;")
@@ -292,6 +616,41 @@ export function installDaemonService(opts) {
             message: `Installed systemd user unit ${SYSTEMD_UNIT_NAME} → ${paths.systemdUnitPath}`,
         };
     }
+    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})`
+                : `${rootLine}Installed Scheduled Task ${WINDOWS_TASK_NAME} → ${paths.windowsTaskXmlPath} (${mode}); ` +
+                    `start failed: ${(started.stderr || started.stdout).trim()}. It starts at next logon.`,
+            notice: windowsLogonNotice(paths),
+        };
+    }
     return {
         platform,
         action: "install",
@@ -304,6 +663,30 @@ 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);
@@ -345,6 +728,65 @@ 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

package/dist/lib/mesh/live/daemon/paths.d.ts

@@ -9,6 +9,8 @@ export declare const DAEMON_LOG_NAME = "log";
 export declare const DAEMON_LOG_MAX_BYTES: number;
 export declare const LAUNCHD_LABEL = "ai.getindigo.hq-mesh-daemon";
 export declare const SYSTEMD_UNIT_NAME = "hq-mesh-daemon.service";
+/** Windows per-user Scheduled Task name (same label as the LaunchAgent). */
+export declare const WINDOWS_TASK_NAME = "ai.getindigo.hq-mesh-daemon";
 export declare function daemonDir(meshRoot?: string, home?: string, env?: NodeJS.ProcessEnv): string;
 export declare function daemonPidPath(dir?: string): string;
 export declare function daemonStatePath(dir?: string): string;

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

@@ -12,6 +12,8 @@ export const DAEMON_LOG_NAME = "log";
 export const DAEMON_LOG_MAX_BYTES = 5 * 1024 * 1024;
 export const LAUNCHD_LABEL = "ai.getindigo.hq-mesh-daemon";
 export const SYSTEMD_UNIT_NAME = "hq-mesh-daemon.service";
+/** Windows per-user Scheduled Task name (same label as the LaunchAgent). */
+export const WINDOWS_TASK_NAME = "ai.getindigo.hq-mesh-daemon";
 export function daemonDir(meshRoot, home = os.homedir(), env = process.env) {
     return path.join(meshRoot ?? workMeshRoot(home, env), DAEMON_DIRNAME);
 }

package/dist/lib/scan-packages/index.js

@@ -163,34 +163,39 @@ function ensureSymlink(link, info, warn) {
         warn(`payload missing: ${link.src} (declared but not shipped)`);
         return;
     }
+    const relativeSrc = path.relative(path.dirname(link.dst), link.src);
     fs.mkdirSync(path.dirname(link.dst), { recursive: true });
     try {
         const stat = fs.lstatSync(link.dst);
         if (stat.isSymbolicLink()) {
             const existing = fs.readlinkSync(link.dst);
-            if (existing === link.src)
+            // Correct form is relative to the host directory so a tree can move
+            // between machines. An absolute match (this host, pre-relative installer)
+            // is ours and converges. A dangling leftover from another HQ root is
+            // not host content and is rewritten the same way.
+            if (existing === relativeSrc)
                 return;
-            // "Host content wins" protects content. A symlink that does not resolve
-            // is not content — and it is the shape every pack link takes when a tree
-            // moves between machines, because these links are absolute and the old
-            // HQ root does not exist on the new host. Skipping it would make that
-            // state permanent: stale on this run, and on every run after it.
-            //
+            if (existing === link.src) {
+                fs.rmSync(link.dst, { force: true });
+                fs.symlinkSync(relativeSrc, link.dst);
+                info(`relinked ${link.dst} -> ${relativeSrc} (was ${existing})`);
+                return;
+            }
             // Only a lookup that specifically says "not there" earns a relink.
             // fs.existsSync also answers false for EACCES, which would read content
             // this user merely cannot traverse as absent and delete the link to it.
             const lookup = targetLookup(link.dst);
             if (lookup === 'absent') {
                 fs.rmSync(link.dst, { force: true });
-                fs.symlinkSync(link.src, link.dst);
-                info(`relinked ${link.dst} -> ${link.src} (was ${existing}, which does not exist here)`);
+                fs.symlinkSync(relativeSrc, link.dst);
+                info(`relinked ${link.dst} -> ${relativeSrc} (was ${existing}, which does not exist here)`);
                 return;
             }
             if (lookup !== 'present') {
                 warn(`collision: ${link.dst} points at ${existing}, which could not be checked (${lookup}) — leaving it alone`);
                 return;
             }
-            warn(`collision: ${link.dst} already points at ${existing} (wanted ${link.src}) — skipping`);
+            warn(`collision: ${link.dst} already points at ${existing} (wanted ${relativeSrc}) — skipping`);
             return;
         }
         warn(`collision: ${link.dst} exists as regular file/dir — host content wins, skipping`);
@@ -200,8 +205,8 @@ function ensureSymlink(link, info, warn) {
         if (error.code !== 'ENOENT')
             throw error;
     }
-    fs.symlinkSync(link.src, link.dst);
-    info(`linked ${link.dst} -> ${link.src}`);
+    fs.symlinkSync(relativeSrc, link.dst);
+    info(`linked ${link.dst} -> ${relativeSrc}`);
 }
 /**
  * The link text, when `entry` is a symlink whose target is definitively not

package/dist/lib/work-context/config.d.ts

@@ -2,6 +2,8 @@
  * Device-local default company preference (~/.hq/work-context/config.json).
  * Preference only — never authority. activeCompany is never treated as default.
  */
+import * as fs from "node:fs";
+import { type WindowsAclCheckOptions } from "./windows-acl.js";
 import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
 export declare const DEVICE_CONFIG_SCHEMA_VERSION: 1;
 export interface DeviceDefaultCompany {
@@ -81,6 +83,24 @@ export declare function acquireDeviceConfigLock(root: string, options?: {
     timeoutMs?: number;
     staleMs?: number;
 }): () => void;
+/** Injection points for assertSafeConfigPath (tests only). */
+export interface SafeConfigPathIo {
+    platform?: NodeJS.Platform;
+    existsSync?: (p: string) => boolean;
+    lstatSync?: (p: string) => Pick<fs.Stats, "mode" | "isSymbolicLink">;
+    windowsAcl?: WindowsAclCheckOptions;
+}
+/**
+ * Refuse a config path that is a symlink (every platform) or writable by
+ * anyone other than the owner.
+ *
+ * - POSIX (darwin/linux/...): `mode & 0o022` must be clear. Unchanged.
+ * - win32: NTFS has no POSIX mode bits; Node reports 0666 for every regular
+ *   file, so the mode test would reject every config (US-018). We read the
+ *   real DACL instead (see windows-acl.ts). Unreadable DACL → documented
+ *   reduced-guarantee path: one diagnostic line, no throw.
+ */
+export declare function assertSafeConfigPath(configPath: string, io?: SafeConfigPathIo): void;
 export declare function readDeviceConfig(deps: Pick<DeviceConfigDeps, "root">): WorkContextDeviceConfig;
 export declare function getDefaultCompany(deps: Pick<DeviceConfigDeps, "root">): DeviceDefaultCompany | null;
 /** A clear is a durable opt-out, not an invitation for automatic reactivation. */