@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -4,13 +4,37 @@
  * - 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).
  * Tests must not actually install services — use a temp HOME/prefix.
  */
 import * as fs from "node:fs";
-export type DaemonInstallPlatform = "darwin" | "linux" | "other";
+import { type RunCommand, type SleepFn } from "../../../service-manager/launchd.js";
+export type DaemonInstallPlatform = "darwin" | "linux" | "win32" | "other";
+/** Result of one schtasks.exe invocation (tests inject; never the real binary). */
+export interface SchtasksResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type SchtasksRunner = (args: string[]) => SchtasksResult;
+/**
+ * `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 declare function stopWindowsDaemonProcess(dir: string, deps?: {
+    readFileSync?: typeof fs.readFileSync;
+    existsSync?: typeof fs.existsSync;
+    kill?: (pid: number) => void;
+    selfPid?: number;
+}): number | null;
+export declare const defaultSchtasks: SchtasksRunner;
 export interface InstallPaths {
     home: string;
     hqBinary: string;
@@ -21,8 +45,22 @@ export interface InstallPaths {
     plistPath: string;
     systemdUserDir: string;
     systemdUnitPath: string;
+    /** Windows: rendered Task Scheduler XML kept under the daemon dir. */
+    windowsTaskXmlPath: string;
+    /** Windows: `DOMAIN\user` the task is registered for (logon trigger + principal). */
+    windowsUser: string;
+    /**
+     * Windows: `conhost.exe` used as `conhost --headless node hq ...` so the
+     * logon-triggered daemon gets no visible console window. Undefined when the
+     * host has no conhost (the task then runs node directly).
+     */
+    windowsHeadlessLauncher?: string;
     /** When true, render the root/ec2-user system unit instead of user unit. */
     systemUser?: string;
+    /** Verified HQ root to persist and pass to the installed service. */
+    hqRoot?: string;
+    /** How hqRoot was chosen (shown in the Windows install confirmation). */
+    hqRootSource?: "flag" | "env" | "ancestor";
 }
 export interface InstallResult {
     platform: DaemonInstallPlatform;
@@ -32,10 +70,113 @@ export interface InstallResult {
     dest?: string;
     running?: boolean;
     message: string;
+    /**
+     * Windows status: the task's "Last Result" code from `schtasks /Query /V`
+     * (normalized to unsigned 32-bit), or null when unavailable.
+     */
+    lastResult?: number | null;
+    /** Windows status: true when lastResult indicates the last start failed. */
+    lastRunFailed?: boolean;
+    /** One plain line of operator context (Windows: logged-on-only visibility). */
+    notice?: string;
+    /**
+     * Windows status: HQ root read back from the registered task XML (else the
+     * persisted daemon config), never re-resolved from cwd. Null when unknown.
+     */
+    recordedHqRoot?: string | null;
+    /** Windows status: whether recordedHqRoot still passes isInstallableHqRoot. */
+    rootValid?: boolean;
+}
+/** Best-effort restart result used after an in-place CLI upgrade. */
+export interface RestartDaemonResult {
+    attempted: boolean;
+    restarted: boolean;
+    message?: string;
 }
+export declare function restartDaemonServiceIfInstalled(opts?: {
+    platform?: DaemonInstallPlatform;
+    home?: string;
+    uid?: number;
+    /** HQ root the daemon was serving, or the root this update was run from. */
+    hqRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    existsSync?: typeof fs.existsSync;
+    readFileSync?: typeof fs.readFileSync;
+    writeFileSync?: typeof fs.writeFileSync;
+    run?: (command: string, args: string[]) => {
+        status: number | null;
+        stdout?: string;
+        stderr?: string;
+    };
+    sleep?: SleepFn;
+    /** Windows: terminate the recorded daemon pid after `schtasks /End` (tests inject). */
+    kill?: (pid: number) => void;
+}): RestartDaemonResult;
 export declare function detectPlatform(platform?: NodeJS.Platform): DaemonInstallPlatform;
+/**
+ * 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 declare function preferStableHqBinary(entry: string): string;
+/**
+ * Absolute path of the CLI entry that is executing this process.
+ * realpath of argv[1] only — never a PATH lookup of `hq`.
+ */
+export declare function resolveRunningCliEntry(argv?: string[]): string;
+/**
+ * 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 declare function resolveAbsoluteNodeBinary(execPath?: string): string;
 /** Resolve the hq binary the current shell uses (argv[1] or PATH). */
 export declare function resolveHqBinary(argv?: string[], env?: NodeJS.ProcessEnv): string;
+/** True when this CLI is newer than the version the daemon recorded, or nothing was recorded. */
+export declare function isNewerCliVersion(current: string, recorded: string | null | undefined): boolean;
+export interface InstallIfStaleResult {
+    reinstalled: boolean;
+    message: string;
+}
+/**
+ * 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 declare function installDaemonIfStale(opts: {
+    currentVersion: string;
+    platform?: DaemonInstallPlatform;
+    paths: InstallPaths;
+    systemUser?: string;
+    run?: RunCommand;
+    uid?: number;
+    sleep?: SleepFn;
+    writeFileSync?: typeof fs.writeFileSync;
+    mkdirSync?: typeof fs.mkdirSync;
+    reloadSystemd?: () => {
+        status: number | null;
+    };
+    schtasks?: SchtasksRunner;
+    kill?: (pid: number) => void;
+    runCommand?: (cmd: string, args: string[]) => {
+        status: number | null;
+        stdout: string;
+        stderr: string;
+    };
+    windowsLegacyTaskPresent?: boolean;
+    /** Reads the installed unit (tests); defaults to the file on disk. */
+    readUnit?: (file: string) => string | null;
+    /** Checks the installed unit's node path (tests); defaults to the real filesystem. */
+    nodeProblem?: (nodePath: string) => "missing" | "versioned" | null;
+}): InstallIfStaleResult;
+/**
+ * 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 declare function installedDaemonNodeBinary(paths: Pick<InstallPaths, "plistPath" | "systemdUnitPath">, platform: DaemonInstallPlatform, readUnit?: (file: string) => string | null): string | null;
 export declare function resolveNodeBinary(execPath?: string, env?: NodeJS.ProcessEnv): string;
 export declare function buildInstallPaths(opts: {
     home?: string;
@@ -46,7 +187,35 @@ export declare function buildInstallPaths(opts: {
     env?: NodeJS.ProcessEnv;
     argv?: string[];
     execPath?: string;
+    hqRoot?: string;
+    hqRootSource?: "flag" | "env" | "ancestor";
+    /** Windows account (`DOMAIN\user`) the task runs as; defaults to the current user. */
+    windowsUser?: string;
+    /** Windows headless launcher override (tests); defaults to %SystemRoot%\System32\conhost.exe when present. */
+    windowsHeadlessLauncher?: string | null;
 }): InstallPaths;
+/** `DOMAIN\user` for the current account, as Task Scheduler expects. */
+export declare function resolveWindowsUser(env?: NodeJS.ProcessEnv): string;
+/**
+ * `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 declare const WINDOWS_CONHOST_HEADLESS_MIN_BUILD = 17763;
+/** Build number from an os.release() string such as "10.0.26200"; null if unparsable. */
+export declare function parseWindowsBuild(release: string): number | 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 declare function resolveWindowsHeadlessLauncher(env?: NodeJS.ProcessEnv, existsSync?: typeof fs.existsSync, release?: string): string | undefined;
+export type WindowsLaunchMode = "conhost-headless" | "direct";
+/** Which launch wrapper the rendered task uses (recorded in the install message). */
+export declare function windowsLaunchMode(paths: Pick<InstallPaths, "windowsHeadlessLauncher">): WindowsLaunchMode;
+/** The task uses the interactive token, so it exists only inside the user's logon session. */
+export declare function windowsLogonNotice(paths: Pick<InstallPaths, "windowsUser">): string;
 export declare function renderLaunchdPlist(paths: InstallPaths): string;
 export declare function renderSystemdUserUnit(paths: InstallPaths): string;
 /**
@@ -54,6 +223,55 @@ export declare function renderSystemdUserUnit(paths: InstallPaths): string;
  * Documented fallback — written only when --system-user is passed.
  */
 export declare function renderSystemdSystemUnit(paths: InstallPaths): string;
+/**
+ * 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 declare function renderWindowsTaskXml(paths: InstallPaths): string;
+/** schtasks stores task XML as UTF-16 LE with BOM; match it so /XML parses. */
+export declare function encodeWindowsTaskXml(rendered: string): Buffer;
+/** Status column of `schtasks /Query /FO CSV /NH`: "TaskName","Next Run Time","Status". */
+export declare function parseSchtasksCsvStatus(stdout: string): string | null;
+/**
+ * "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 declare function parseSchtasksLastResult(stdout: string): number | 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 declare function schtasksLastResultFailed(code: number | null): boolean;
+/** `--hq-root <path>` from a rendered task's <Arguments> (XML-escaped, optionally quoted). */
+export declare function parseWindowsTaskHqRoot(xml: string): string | 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 declare function readRecordedWindowsHqRoot(paths: Pick<InstallPaths, "windowsTaskXmlPath" | "daemonDir">, deps?: {
+    existsSync?: typeof fs.existsSync;
+    readFileSync?: typeof fs.readFileSync;
+}): string | null;
 export declare function installDaemonService(opts: {
     platform?: DaemonInstallPlatform;
     paths?: InstallPaths;
@@ -63,6 +281,25 @@ export declare function installDaemonService(opts: {
     mkdirSync?: typeof fs.mkdirSync;
     /** Optional: actually load the service (disabled in tests). */
     activate?: (platform: DaemonInstallPlatform, dest: string) => void;
+    /** Reload a rewritten user unit so a legacy Restart=on-failure unit migrates immediately. */
+    reloadSystemd?: () => {
+        status: number | null;
+    };
+    /** Windows: schtasks.exe runner (tests inject; never the real binary). */
+    schtasks?: SchtasksRunner;
+    /** Windows: terminate the recorded daemon pid when replacing a task (tests inject). */
+    kill?: (pid: number) => void;
+    /** Service-manager runner for retiring the legacy listen unit (tests inject). */
+    runCommand?: (cmd: string, args: string[]) => {
+        status: number | null;
+        stdout: string;
+        stderr: string;
+    };
+    windowsLegacyTaskPresent?: boolean;
+    /** launchctl/systemctl seam — when set on darwin, bootout/bootstrap/kickstart after writing the plist. */
+    run?: RunCommand;
+    uid?: number;
+    sleep?: SleepFn;
 }): InstallResult;
 export declare function uninstallDaemonService(opts: {
     platform?: DaemonInstallPlatform;
@@ -70,13 +307,30 @@ export declare function uninstallDaemonService(opts: {
     unlinkSync?: typeof fs.unlinkSync;
     existsSync?: typeof fs.existsSync;
     deactivate?: (platform: DaemonInstallPlatform, dest: string) => void;
+    /** Service-manager runner for uninstall deactivation (tests inject; never the real binary). */
+    run?: RunCommand;
+    uid?: number;
+    /** Windows: schtasks.exe runner (tests inject; never the real binary). */
+    schtasks?: SchtasksRunner;
+    /** Windows: terminate the recorded daemon pid after `schtasks /End` (tests inject). */
+    kill?: (pid: number) => void;
 }): InstallResult;
+/**
+ * Live service-manager probe for `daemonServiceStatus`: `launchctl print
+ * gui/<uid>/<label>` on macOS, `systemctl --user is-active` on Linux.
+ */
+export declare function daemonServiceIsLoaded(run: RunCommand, uid?: number): (platform: DaemonInstallPlatform, dest: string) => boolean;
 export declare function daemonServiceStatus(opts: {
     platform?: DaemonInstallPlatform;
     paths?: InstallPaths;
     existsSync?: typeof fs.existsSync;
     /** Optional live probe (launchctl/systemctl); tests inject. */
     isLoaded?: (platform: DaemonInstallPlatform, dest: string) => boolean;
+    /** Windows: schtasks.exe runner (tests inject; never the real binary). */
+    schtasks?: SchtasksRunner;
+    /** Windows: liveness probe for the daemon pid lock (tests inject). */
+    isProcessAlive?: (pid: number) => boolean;
+    readFileSync?: typeof fs.readFileSync;
 }): InstallResult;
 /** Read baked template files from assets/ (optional; renderers are primary). */
 export declare function readAssetTemplate(name: "launchd.plist.template" | "systemd.user.service.template" | "systemd.system.service.template"): string | null;