@indigoai-us/hq-cli 5.345.147 → 5.345.148

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

@@ -16,6 +16,7 @@
  * never touch launchctl, systemctl or schtasks.
  */
 import { type RunCommand, type SleepFn } from "../service-manager/launchd.js";
+import { type PidLockRecord } from "../mesh/live/daemon/pid-lock.js";
 import type { MachineType } from "./machine-type.js";
 export declare const DAEMON_LAUNCHD_LABEL = "ai.getindigo.hq-daemon";
 export declare const DAEMON_SYSTEMD_UNIT = "hq-daemon.service";
@@ -60,12 +61,28 @@ export interface DaemonUnitResult {
     running: boolean;
     error?: string;
     manualCommand?: string;
+    /**
+     * Windows: the task is registered but no new daemon process appeared within
+     * WINDOWS_START_WAIT_MS of `schtasks /Run`. With no interactive session the
+     * logon trigger starts it at the next sign-in; with one, it did not start.
+     * The caller decides which, since only it can check the session.
+     */
+    startPending?: true;
+    /** Windows: an older daemon may still be running; HQ could not verify it, so did not stop it. */
+    warning?: string;
 }
 export interface InstallDeps {
     run: RunCommand;
-    /** Blocking sleep for the launchd reload wait (tests inject). */
+    /** Blocking sleep for the launchd reload wait and the Windows start wait (tests inject). */
     sleep?: SleepFn;
+    /**
+     * The running daemon's lock record (pid and start time), or null. Default:
+     * the daemon lock, when it names a live `hq daemon run` process.
+     */
+    runningDaemon?: () => PidLockRecord | null;
 }
+/** How long install waits for the Windows task to start a daemon process. */
+export declare const WINDOWS_START_WAIT_MS = 10000;
 export declare const ROOT_REFUSAL = "hq daemon runs its services as the machine's login user, never as root.";
 /**
  * Why the daemon must not run here as root, or null when it may. Agent kits
@@ -76,10 +93,39 @@ export declare function daemonRootRefusal(isRoot: boolean, machineType: MachineT
 /** Boxes run the daemon as a system unit; everything else per user. */
 export declare function installScopeFor(machineType: MachineType): InstallScope;
 export declare function planDaemonUnit(host: DaemonHost, options: InstallOptions): DaemonUnitPlan;
+/** What to tell the user when HQ did not stop pid `pid` because it could not verify it. */
+export declare function oldDaemonWarning(pid: number, reason: string): string;
 export declare function installDaemonUnit(host: DaemonHost, options: InstallOptions, deps: InstallDeps): DaemonUnitResult;
+/**
+ * PowerShell script that lists Windows sessions as `id|state|DOMAIN\user`
+ * lines through WTSEnumerateSessions and WTSQuerySessionInformation. State is
+ * the numeric WTS_CONNECTSTATE_CLASS (0 = WTSActive), so the output does not
+ * depend on the display language, and it needs no query.exe (absent on
+ * Windows Home). Constrained Language Mode refuses Add-Type, so there the
+ * script prints `unavailable|<mode>` and lists nothing.
+ */
+export declare const WINDOWS_SESSIONS_SCRIPT: string;
+/** One Windows session from WINDOWS_SESSIONS_SCRIPT output. */
+export interface WindowsSession {
+    id: number;
+    /** WTS_CONNECTSTATE_CLASS: 0 is WTSActive. */
+    state: number;
+    /** `DOMAIN\user`, a bare user name, or "" when nobody is signed in to it. */
+    user: string;
+}
+export declare function parseWindowsSessions(stdout: string): WindowsSession[];
+/**
+ * Whether `user` (`DOMAIN\user` or a bare name) has an active Windows session.
+ * A disconnected session does not count: an interactive-token task cannot
+ * start in it. Returns "unavailable" when PowerShell runs in Constrained
+ * Language Mode, which refuses the check, and null when the check failed in
+ * any other way.
+ */
+export declare function windowsInteractiveSession(run: RunCommand, user: string): boolean | null | "unavailable";
 export declare function uninstallDaemonUnit(host: DaemonHost, options: InstallOptions, deps: InstallDeps): {
     kind: DaemonUnitPlan["kind"];
     unitPath: string;
     removed: boolean;
+    warning?: string;
 };
 //# sourceMappingURL=install.d.ts.map

package/dist/lib/daemon/install.js

@@ -17,15 +17,20 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { activateLaunchd, deactivateLaunchd, defaultRunCommand, installLaunchdPlist, launchdIsLoaded, launchdPlistPath, renderLaunchdPlist, } from "../service-manager/launchd.js";
+import { activateLaunchd, blockingSleep, deactivateLaunchd, defaultRunCommand, installLaunchdPlist, launchdIsLoaded, launchdPlistPath, renderLaunchdPlist, } from "../service-manager/launchd.js";
 import { activateSystemd, deactivateSystemd, renderSystemdUserUnit, systemdUnitPath, } from "../service-manager/systemd.js";
 import { escapeXml, shellQuote } from "../service-manager/types.js";
 import { readPidLock } from "../mesh/live/daemon/pid-lock.js";
 import { userToolDirs } from "./tools.js";
+import { liveDaemonLock, verifyDaemonForKill } from "./lock.js";
+import { daemonPaths } from "./paths.js";
 export const DAEMON_LAUNCHD_LABEL = "ai.getindigo.hq-daemon";
 export const DAEMON_SYSTEMD_UNIT = "hq-daemon.service";
 export const DAEMON_WINDOWS_TASK = "ai.getindigo.hq-daemon";
 export const SYSTEM_UNIT_DIR = "/etc/systemd/system";
+/** How long install waits for the Windows task to start a daemon process. */
+export const WINDOWS_START_WAIT_MS = 10_000;
+const WINDOWS_START_POLL_MS = 500;
 export const ROOT_REFUSAL = "hq daemon runs its services as the machine's login user, never as root.";
 /**
  * Why the daemon must not run here as root, or null when it may. Agent kits
@@ -209,7 +214,39 @@ export function planDaemonUnit(host, options) {
 function commandError(what, r) {
     return new Error(`${what} failed: ${r.stderr.trim() || r.stdout.trim() || `exit ${r.status}`}`);
 }
-function activate(plan, host, run, sleep) {
+/**
+ * Stop the Windows task and the recorded daemon's whole process tree. Ending
+ * the task stops only its root process (conhost when --headless is used);
+ * node and the services it runs keep going.
+ *
+ * The pid comes from the lock file, which can be stale: after the daemon
+ * exits, Windows may give its pid to another program. The process is checked
+ * immediately before the kill and killed only when it is verifiably the
+ * daemon. Returns a warning when a process was left running unverified.
+ */
+function endWindowsDaemon(run, owner) {
+    run("schtasks.exe", ["/End", "/TN", DAEMON_WINDOWS_TASK]);
+    if (!owner || owner.pid === process.pid)
+        return undefined;
+    const check = verifyDaemonForKill(owner, run);
+    if (check.verdict === "daemon") {
+        run("taskkill.exe", ["/PID", String(owner.pid), "/T", "/F"]);
+        return undefined;
+    }
+    if (check.verdict === "gone")
+        return undefined;
+    return oldDaemonWarning(owner.pid, check.reason);
+}
+/** What to tell the user when HQ did not stop pid `pid` because it could not verify it. */
+export function oldDaemonWarning(pid, reason) {
+    return [
+        `An older HQ daemon may still be running. HQ did not stop process ${pid} because ${reason}.`,
+        "To find a running HQ daemon:",
+        `  powershell -NoProfile -Command "Get-CimInstance Win32_Process | Where-Object CommandLine -match 'daemon run' | Select-Object ProcessId,CommandLine"`,
+        "Stop the process it lists with: taskkill /PID <ProcessId> /T /F",
+    ].join("\n");
+}
+function activate(plan, host, run, sleep, previous = null) {
     switch (plan.kind) {
         case "launchd":
             activateLaunchd(plan.unitPath, run, host.uid, { sleep });
@@ -231,13 +268,17 @@ function activate(plan, host, run, sleep) {
             const create = run("schtasks.exe", ["/Create", "/TN", DAEMON_WINDOWS_TASK, "/XML", plan.unitPath, "/F"]);
             if (create.status !== 0)
                 throw commandError("schtasks /Create", create);
+            // `/Create /F` leaves a running instance alone and `/Run` is ignored
+            // while one runs, so a daemon from an earlier install would keep the old
+            // settings. Stop it first so `/Run` starts a new one.
+            const warning = previous ? endWindowsDaemon(run, previous) : undefined;
             const start = run("schtasks.exe", ["/Run", "/TN", DAEMON_WINDOWS_TASK]);
             if (start.status !== 0)
                 throw commandError("schtasks /Run", start);
-            return;
+            return warning;
         }
         case "manual":
-            return;
+            return undefined;
     }
 }
 export function installDaemonUnit(host, options, deps) {
@@ -286,8 +327,32 @@ export function installDaemonUnit(host, options, deps) {
     else
         fs.writeFileSync(plan.unitPath, plan.rendered, { mode: plan.kind === "systemd-system" ? 0o644 : 0o600 });
     try {
-        if (plan.kind !== "launchd")
-            activate(plan, host, deps.run, deps.sleep);
+        const lockPath = daemonPaths(host.home, { HQ_DAEMON_DIR: host.daemonDir }).lockPath;
+        const runningDaemon = deps.runningDaemon ?? (() => liveDaemonLock(lockPath));
+        const previous = plan.kind === "schtasks" ? runningDaemon() : null;
+        const warning = plan.kind !== "launchd" ? activate(plan, host, deps.run, deps.sleep, previous) : undefined;
+        const warn = warning ? { warning } : {};
+        if (plan.kind === "schtasks") {
+            // schtasks /Run exits 0 even when the task cannot run: an
+            // InteractiveToken task with no signed-in session stays at "has not yet
+            // run" (267011). Report running only once a daemon started by this
+            // install holds the lock; a daemon from before the install does not count.
+            const outcome = waitForNewDaemon(runningDaemon, previous, deps.sleep ?? blockingSleep);
+            if (outcome === "started")
+                return { kind: plan.kind, unitPath: plan.unitPath, installed: true, running: true, ...warn };
+            if (outcome === "previous") {
+                return {
+                    kind: plan.kind,
+                    unitPath: plan.unitPath,
+                    installed: true,
+                    running: false,
+                    error: `the daemon from before this install (pid ${previous?.pid}) is still running, ` +
+                        "so the new task did not start. Run hq daemon uninstall, then hq daemon install",
+                    ...warn,
+                };
+            }
+            return { kind: plan.kind, unitPath: plan.unitPath, installed: true, running: false, startPending: true, ...warn };
+        }
         return { kind: plan.kind, unitPath: plan.unitPath, installed: true, running: true };
     }
     catch (err) {
@@ -300,6 +365,112 @@ export function installDaemonUnit(host, options, deps) {
         };
     }
 }
+/** A lock record names a different daemon than `previous` (new pid or new start time). */
+function isNewDaemon(now, previous) {
+    return !previous || now.pid !== previous.pid || now.ts !== previous.ts;
+}
+/**
+ * Wait up to WINDOWS_START_WAIT_MS for a daemon started after `previous`.
+ * "previous" means the daemon from before the install still holds the lock at
+ * the end of the wait; "none" means no daemon is running.
+ */
+function waitForNewDaemon(runningDaemon, previous, sleep) {
+    for (let waited = 0;; waited += WINDOWS_START_POLL_MS) {
+        const now = runningDaemon();
+        if (now && isNewDaemon(now, previous))
+            return "started";
+        if (waited >= WINDOWS_START_WAIT_MS)
+            return now ? "previous" : "none";
+        sleep(WINDOWS_START_POLL_MS);
+    }
+}
+/**
+ * PowerShell script that lists Windows sessions as `id|state|DOMAIN\user`
+ * lines through WTSEnumerateSessions and WTSQuerySessionInformation. State is
+ * the numeric WTS_CONNECTSTATE_CLASS (0 = WTSActive), so the output does not
+ * depend on the display language, and it needs no query.exe (absent on
+ * Windows Home). Constrained Language Mode refuses Add-Type, so there the
+ * script prints `unavailable|<mode>` and lists nothing.
+ */
+export const WINDOWS_SESSIONS_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    "$mode = [string]$ExecutionContext.SessionState.LanguageMode",
+    "if ($mode -ne 'FullLanguage') { 'unavailable|' + $mode; exit 0 }",
+    "Add-Type -TypeDefinition @'",
+    "using System;",
+    "using System.Runtime.InteropServices;",
+    "public static class HqWts {",
+    '  [DllImport("wtsapi32.dll", SetLastError = true)]',
+    "  public static extern bool WTSEnumerateSessionsW(IntPtr server, int reserved, int version, out IntPtr info, out int count);",
+    '  [DllImport("wtsapi32.dll", SetLastError = true)]',
+    "  public static extern bool WTSQuerySessionInformationW(IntPtr server, int sessionId, int infoClass, out IntPtr buffer, out int bytes);",
+    '  [DllImport("wtsapi32.dll")]',
+    "  public static extern void WTSFreeMemory(IntPtr memory);",
+    "  static string Query(int id, int infoClass) {",
+    "    IntPtr buffer; int bytes;",
+    '    if (!WTSQuerySessionInformationW(IntPtr.Zero, id, infoClass, out buffer, out bytes)) return "";',
+    "    try { return Marshal.PtrToStringUni(buffer); } finally { WTSFreeMemory(buffer); }",
+    "  }",
+    "  public static string[] List() {",
+    "    IntPtr info; int count;",
+    '    if (!WTSEnumerateSessionsW(IntPtr.Zero, 0, 1, out info, out count)) throw new System.ComponentModel.Win32Exception();',
+    "    try {",
+    "      int size = 3 * IntPtr.Size;",
+    "      string[] lines = new string[count];",
+    "      for (int i = 0; i < count; i++) {",
+    "        IntPtr row = new IntPtr(info.ToInt64() + (long)i * size);",
+    "        int id = Marshal.ReadInt32(row);",
+    "        int state = Marshal.ReadInt32(row, 2 * IntPtr.Size);",
+    "        string user = Query(id, 5);",
+    "        string domain = Query(id, 7);",
+    '        lines[i] = id + "|" + state + "|" + (domain.Length > 0 ? domain + "\\\\" + user : user);',
+    "      }",
+    "      return lines;",
+    "    } finally { WTSFreeMemory(info); }",
+    "  }",
+    "}",
+    "'@",
+    "[HqWts]::List() | ForEach-Object { $_ }",
+].join("\n");
+const WTS_ACTIVE = 0;
+export function parseWindowsSessions(stdout) {
+    const sessions = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        const match = /^(\d+)\|(\d+)\|(.*)$/.exec(line.trim());
+        if (match)
+            sessions.push({ id: Number(match[1]), state: Number(match[2]), user: match[3].trim() });
+    }
+    return sessions;
+}
+/**
+ * Whether `user` (`DOMAIN\user` or a bare name) has an active Windows session.
+ * A disconnected session does not count: an interactive-token task cannot
+ * start in it. Returns "unavailable" when PowerShell runs in Constrained
+ * Language Mode, which refuses the check, and null when the check failed in
+ * any other way.
+ */
+export function windowsInteractiveSession(run, user) {
+    const encoded = Buffer.from(WINDOWS_SESSIONS_SCRIPT, "utf16le").toString("base64");
+    const r = run("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded]);
+    if (r.status !== 0)
+        return null;
+    if (/^unavailable\|/m.test(r.stdout.trim()))
+        return "unavailable";
+    const sessions = parseWindowsSessions(r.stdout);
+    if (sessions.length === 0)
+        return null;
+    const wanted = user.trim().toLowerCase();
+    const bare = (wanted.split("\\").pop() ?? "").trim();
+    if (!bare)
+        return null;
+    return sessions.some((s) => {
+        if (s.state !== WTS_ACTIVE || !s.user)
+            return false;
+        const name = s.user.toLowerCase();
+        // Compare the full DOMAIN\user when both sides have a domain.
+        return name.includes("\\") && wanted.includes("\\") ? name === wanted : name.split("\\").pop() === bare;
+    });
+}
 export function uninstallDaemonUnit(host, options, deps) {
     // A system uninstall does not need the login user; only the unit path matters.
     const plan = host.platform === "linux" && options.scope === "system"
@@ -312,6 +483,7 @@ export function uninstallDaemonUnit(host, options, deps) {
         (plan.kind === "schtasks" && deps.run("schtasks.exe", ["/Query", "/TN", DAEMON_WINDOWS_TASK]).status === 0);
     if (!present)
         return { kind: plan.kind, unitPath: plan.unitPath, removed: false };
+    let warning;
     switch (plan.kind) {
         case "launchd":
             deactivateLaunchd(plan.unitPath, deps.run, host.uid);
@@ -330,14 +502,8 @@ export function uninstallDaemonUnit(host, options, deps) {
             break;
         }
         case "schtasks": {
-            deps.run("schtasks.exe", ["/End", "/TN", DAEMON_WINDOWS_TASK]);
-            // Ending the task stops only its root process (conhost when --headless is
-            // used); node and the services it runs keep going. End the recorded
-            // daemon's whole process tree.
-            const owner = readPidLock(path.join(host.daemonDir, "daemon.pid"));
-            if (owner && owner.pid !== process.pid) {
-                deps.run("taskkill.exe", ["/PID", String(owner.pid), "/T", "/F"]);
-            }
+            // The lock may be stale; endWindowsDaemon kills only a verified daemon.
+            warning = endWindowsDaemon(deps.run, readPidLock(path.join(host.daemonDir, "daemon.pid")));
             const del = deps.run("schtasks.exe", ["/Delete", "/TN", DAEMON_WINDOWS_TASK, "/F"]);
             // Keep the XML so a later uninstall still finds the task.
             if (del.status !== 0)
@@ -346,6 +512,6 @@ export function uninstallDaemonUnit(host, options, deps) {
         }
     }
     fs.rmSync(plan.unitPath, { force: true });
-    return { kind: plan.kind, unitPath: plan.unitPath, removed: true };
+    return { kind: plan.kind, unitPath: plan.unitPath, removed: true, ...(warning ? { warning } : {}) };
 }
 //# sourceMappingURL=install.js.map

package/dist/lib/daemon/lock.d.ts

@@ -31,8 +31,38 @@ export interface DaemonProcessDeps {
  * The pid is alive and is an `hq daemon run`. After a reboot the pid in an old
  * lock file often belongs to an unrelated program; that must not keep the
  * daemon from starting.
+ *
+ * An unreadable command line counts as the daemon here, so a second daemon is
+ * never started next to one HQ cannot inspect. Never use this to decide a
+ * kill: use `verifyDaemonForKill`, which treats an unreadable command line as
+ * "not the daemon".
  */
 export declare function isDaemonProcess(pid: number, deps?: DaemonProcessDeps): boolean;
+/**
+ * PowerShell that prints a Windows process's creation time (UTC, ISO 8601) on
+ * the first line and its command line on the rest, or nothing when no process
+ * has that id. It uses only a cmdlet and DateTime methods, so it also runs in
+ * Constrained Language Mode. `-ErrorAction Stop` makes a WMI failure exit
+ * non-zero, so it reads as "could not read", never as "no such process".
+ */
+export declare function windowsProcessIdentityScript(pid: number): string;
+export type DaemonKillCheck = {
+    verdict: "daemon";
+} | {
+    verdict: "gone";
+} | {
+    verdict: "unverified";
+    reason: string;
+};
+/**
+ * Decide whether the Windows process in `owner` may be killed as the HQ
+ * daemon. Run this immediately before the kill. It is the daemon only when the
+ * process exists, its command line is readable and is `hq daemon run`, and it
+ * was created no later than the lock was written. A process created after the
+ * lock took over a pid the old daemon left behind. Anything that cannot be
+ * read is "unverified", and the caller must not kill.
+ */
+export declare function verifyDaemonForKill(owner: PidLockRecord, run: RunCommand): DaemonKillCheck;
 export type DaemonLockResult = {
     ok: true;
 } | {
@@ -41,6 +71,8 @@ export type DaemonLockResult = {
 };
 export declare function acquireDaemonLock(lockPath: string, pid?: number, alive?: (pid: number) => boolean, now?: () => number): DaemonLockResult;
 export declare function releaseDaemonLock(lockPath: string, pid?: number): void;
+/** The live supervisor's lock record (pid and start time), or null when none is running. */
+export declare function liveDaemonLock(lockPath: string, alive?: (pid: number) => boolean): PidLockRecord | null;
 /** The live supervisor's pid, or null when none is running. */
 export declare function runningDaemonPid(lockPath: string, alive?: (pid: number) => boolean): number | null;
 export {};

package/dist/lib/daemon/lock.js

@@ -53,6 +53,11 @@ export function processCommandLine(pid, deps = defaultCommandLineDeps()) {
  * The pid is alive and is an `hq daemon run`. After a reboot the pid in an old
  * lock file often belongs to an unrelated program; that must not keep the
  * daemon from starting.
+ *
+ * An unreadable command line counts as the daemon here, so a second daemon is
+ * never started next to one HQ cannot inspect. Never use this to decide a
+ * kill: use `verifyDaemonForKill`, which treats an unreadable command line as
+ * "not the daemon".
  */
 export function isDaemonProcess(pid, deps = { alive: (p) => isProcessAlive(p), commandLine: (p) => processCommandLine(p) }) {
     if (!deps.alive(pid))
@@ -60,6 +65,50 @@ export function isDaemonProcess(pid, deps = { alive: (p) => isProcessAlive(p), c
     const cmd = deps.commandLine(pid);
     return cmd === null || /\bdaemon\s+run\b/.test(cmd);
 }
+/**
+ * PowerShell that prints a Windows process's creation time (UTC, ISO 8601) on
+ * the first line and its command line on the rest, or nothing when no process
+ * has that id. It uses only a cmdlet and DateTime methods, so it also runs in
+ * Constrained Language Mode. `-ErrorAction Stop` makes a WMI failure exit
+ * non-zero, so it reads as "could not read", never as "no such process".
+ */
+export function windowsProcessIdentityScript(pid) {
+    return (`$p = Get-CimInstance Win32_Process -Filter "ProcessId=${Math.trunc(pid)}" -ErrorAction Stop; ` +
+        "if ($p) { $p.CreationDate.ToUniversalTime().ToString('o'); [string]$p.CommandLine }");
+}
+/** Seconds a daemon's creation time may follow its lock's ts (whole-second rounding and clock skew). */
+const LOCK_TS_SLACK_SECONDS = 2;
+/**
+ * Decide whether the Windows process in `owner` may be killed as the HQ
+ * daemon. Run this immediately before the kill. It is the daemon only when the
+ * process exists, its command line is readable and is `hq daemon run`, and it
+ * was created no later than the lock was written. A process created after the
+ * lock took over a pid the old daemon left behind. Anything that cannot be
+ * read is "unverified", and the caller must not kill.
+ */
+export function verifyDaemonForKill(owner, run) {
+    const encoded = Buffer.from(windowsProcessIdentityScript(owner.pid), "utf16le").toString("base64");
+    const r = run("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded]);
+    if (r.status !== 0)
+        return { verdict: "unverified", reason: "HQ could not read the process" };
+    const lines = r.stdout.split(/\r?\n/).map((l) => l.trim());
+    while (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    if (lines.length === 0)
+        return { verdict: "gone" };
+    const commandLine = lines.slice(1).join(" ").trim();
+    if (!commandLine)
+        return { verdict: "unverified", reason: "HQ could not read its command line" };
+    if (!/\bdaemon\s+run\b/.test(commandLine))
+        return { verdict: "unverified", reason: "it is not hq daemon run" };
+    const created = Date.parse(lines[0]);
+    if (!Number.isFinite(created))
+        return { verdict: "unverified", reason: "HQ could not read its start time" };
+    if (Math.floor(created / 1000) > owner.ts + LOCK_TS_SLACK_SECONDS) {
+        return { verdict: "unverified", reason: "it started after the daemon lock was written, so it is a different process" };
+    }
+    return { verdict: "daemon" };
+}
 function claimTakeover(claim, pid, now) {
     for (let attempt = 0; attempt < 2; attempt++) {
         try {
@@ -130,9 +179,13 @@ export function releaseDaemonLock(lockPath, pid = process.pid) {
     if (owner?.pid === pid)
         fs.rmSync(lockPath, { force: true });
 }
+/** The live supervisor's lock record (pid and start time), or null when none is running. */
+export function liveDaemonLock(lockPath, alive = isDaemonProcess) {
+    const owner = readPidLock(lockPath);
+    return owner && alive(owner.pid) ? owner : null;
+}
 /** The live supervisor's pid, or null when none is running. */
 export function runningDaemonPid(lockPath, alive = isDaemonProcess) {
-    const owner = readPidLock(lockPath);
-    return owner && alive(owner.pid) ? owner.pid : null;
+    return liveDaemonLock(lockPath, alive)?.pid ?? null;
 }
 //# sourceMappingURL=lock.js.map

package/dist/lib/doctor/__testing__/run-doctor.js

@@ -3,6 +3,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { runDoctor as runDoctorCommand, } from "../../../commands/doctor.js";
 import { createAnywhereFamily } from "../checks/anywhere.js";
+import { createTempHomesFamily } from "../checks/temp-homes.js";
 import { createDefaultRegistry } from "../registry.js";
 /**
  * Run doctor tests against synthetic state. The production registry normally
@@ -45,6 +46,9 @@ export async function runDoctorForTest(options = {}) {
             // Command tests exercise doctor rendering and exit behavior offline. The
             // real person preference is covered in the anywhere-family tests.
             registry.register(createAnywhereFamily({ personSettingReader: async () => false }));
+            // The temp-homes family walks the machine's real temp folders; scan
+            // none here. Its behaviour is covered with fake trees in its own tests.
+            registry.register(createTempHomesFamily({ roots: [] }));
         }
         return await runDoctorCommand({ ...options, registry, integrations: false });
     }

package/dist/lib/doctor/checks/anywhere.d.ts

@@ -17,6 +17,7 @@ export declare const REMEDIATION: {
     readonly repairCodexSkills: "hq uninstall --global --runtime codex && hq install --global --runtime codex";
     readonly daemonInstall: "hq daemon install";
     readonly daemonRestart: "hq daemon restart --daemon";
+    readonly daemonStatus: "hq daemon status";
     readonly link: "hq link <repo-dir> <company>";
 };
 interface DaemonServiceState {
@@ -45,6 +46,8 @@ export interface AnywhereDeps {
     /** The hq-cli version installed on this machine. Default: this CLI's version. */
     cliVersion?: string;
     serviceState?: () => DaemonServiceState;
+    /** Is an hqd process alive? Default: the daemon lock names a live hqd pid. */
+    daemonRunning?: () => boolean;
     now?: () => Date;
 }
 export declare function createAnywhereFamily(deps?: AnywhereDeps): CheckFamily;

package/dist/lib/doctor/checks/anywhere.js

@@ -23,8 +23,10 @@ import { daemonPresenceLabel, heartbeatFile, readHeartbeat } from "../../daemon/
 import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK } from "../../daemon/install.js";
 import { hostedDaemonRunning } from "../../daemon/handoff.js";
 import { daemonPaths } from "../../daemon/paths.js";
+import { runningDaemonPid } from "../../daemon/lock.js";
 import { hqdSocketPath } from "../../daemon/protocol.js";
 import { readRegistry, registryDir, registryFile } from "../../registry/registry.js";
+import { skillCopySource } from "../../../utils/safe-link.js";
 import { anywhereRuntimeEnabled } from "../../../commands/anywhere-runtime-flag.js";
 import { readHqAnywherePersonSetting } from "../../anywhere-person-setting.js";
 const ANYWHERE_FAMILY_ID = "anywhere";
@@ -35,6 +37,7 @@ export const REMEDIATION = {
     repairCodexSkills: "hq uninstall --global --runtime codex && hq install --global --runtime codex",
     daemonInstall: "hq daemon install",
     daemonRestart: "hq daemon restart --daemon",
+    daemonStatus: "hq daemon status",
     link: "hq link <repo-dir> <company>",
 };
 export function createAnywhereFamily(deps = {}) {
@@ -118,7 +121,12 @@ async function runAnywhereChecks(context, deps = {}) {
     const serviceState = runtimeEnabled && installed
         ? (deps.serviceState ?? (() => defaultServiceState(home)))()
         : undefined;
-    const healthCheck = runtimeHealthCheck(health, healthUnsupported, serviceState);
+    // A missing Windows pipe usually means hqd never started; only blame the
+    // pipe ACL when a daemon process is actually alive.
+    const daemonRunning = health.reachable
+        ? true
+        : (deps.daemonRunning ?? (() => runningDaemonPid(daemonPaths(home, env).lockPath) !== null))();
+    const healthCheck = runtimeHealthCheck(health, healthUnsupported, serviceState, daemonRunning);
     if (!runtimeEnabled)
         return [healthCheck, settingCheck];
     const remoteModes = [
@@ -179,7 +187,7 @@ function unreachableHealth(socketPath) {
         socket: { path: socketPath, transport: process.platform === "win32" ? "windows_named_pipe" : "unix_socket", mode: null, ownerMatchesUser: null, userOnly: null },
     };
 }
-function runtimeHealthCheck(health, healthUnsupported = false, serviceState) {
+function runtimeHealthCheck(health, healthUnsupported = false, serviceState, daemonRunning = true) {
     const { flag, resolution, socket } = health;
     const age = flag.lastSuccessfulReadAgeMs === null
         ? "unknown"
@@ -195,9 +203,12 @@ function runtimeHealthCheck(health, healthUnsupported = false, serviceState) {
     const socketSecurity = socket.transport === "windows_named_pipe"
         ? "Windows named pipe (mode and owner are not reported)"
         : `mode ${socket.mode ?? "unknown"}; owner matches current user: ${socket.ownerMatchesUser === null ? "unknown" : socket.ownerMatchesUser ? "yes" : "no"}; user-only: ${socket.userOnly === null ? "unknown" : socket.userOnly ? "yes" : "no"}`;
-    const unreachableMessage = socket.transport === "windows_named_pipe"
-        ? `hqd is not reachable on ${socket.path}; secure Windows named-pipe setup may have refused an unsafe ACL`
-        : `hqd is not reachable on ${socket.path}; version, uptime, flag state, and cwd binding are unavailable`;
+    const pipeWithoutDaemon = socket.transport === "windows_named_pipe" && !daemonRunning;
+    const unreachableMessage = pipeWithoutDaemon
+        ? `hqd is not running, so its named pipe ${socket.path} does not exist. Run ${REMEDIATION.daemonStatus} to see why it has not started.`
+        : socket.transport === "windows_named_pipe"
+            ? `hqd is not reachable on ${socket.path}; secure Windows named-pipe setup may have refused an unsafe ACL`
+            : `hqd is not reachable on ${socket.path}; version, uptime, flag state, and cwd binding are unavailable`;
     const socketNotUserOnly = health.reachable && socket.transport === "unix_socket" && (socket.userOnly !== true || socket.ownerMatchesUser !== true);
     const warningNotes = [
         healthUnsupported ? "resident hqd does not support detailed health; restart hqd for full diagnostics" : null,
@@ -207,7 +218,8 @@ function runtimeHealthCheck(health, healthUnsupported = false, serviceState) {
         ? `hqd reachable; version ${health.version ?? "unknown"}; uptime ${health.uptimeMs === null ? "unknown" : `${new Intl.NumberFormat("en-US").format(health.uptimeMs)} ms`}; runtime flag ${flagLabel}; last successful flag read ${age} ago; held through read error: ${flag.heldThroughReadError ? "yes" : "no"}; cwd binding ${binding}; socket ${socket.path}; ${socketSecurity}${warningNotes.length ? `; ${warningNotes.join("; ")}` : ""}`
         : unreachableMessage;
     const remediation = !health.reachable && serviceState
-        ? serviceState.installed ? REMEDIATION.daemonRestart : REMEDIATION.daemonInstall
+        ? !serviceState.installed ? REMEDIATION.daemonInstall
+            : pipeWithoutDaemon ? REMEDIATION.daemonStatus : REMEDIATION.daemonRestart
         : healthUnsupported || socketNotUserOnly ? REMEDIATION.daemonRestart : undefined;
     return {
         status: health.reachable && warningNotes.length === 0 ? "PASS" : "WARN",
@@ -336,12 +348,15 @@ function checkSkillLinks(runtime, dir, fix, repair = fix) {
         return result("WARN", id, `${dir} does not exist`, fix, dir);
     }
     const links = names.filter((n) => fs.lstatSync(path.join(dir, n)).isSymbolicLink());
-    if (links.length === 0)
+    // Windows falls back to marked copies when it refuses both link types.
+    const copies = names.filter((n) => skillCopySource(path.join(dir, n)) !== null);
+    if (links.length === 0 && copies.length === 0)
         return result("WARN", id, `no hq-* skill links in ${dir}`, fix, dir);
     const broken = links.filter((n) => !fs.existsSync(path.join(dir, n)));
     if (broken.length > 0)
         return result("FAIL", id, `${broken.length} broken skill links in ${dir}: ${broken.slice(0, 5).join(", ")}`, repair, dir);
-    return result("PASS", id, `${links.length} hq-* skill links in ${dir} resolve`, undefined, dir);
+    const copied = copies.length > 0 ? ` (${copies.length} more are copies that do not follow HQ skill updates)` : "";
+    return result("PASS", id, `${links.length} hq-* skill links in ${dir} resolve${copied}`, undefined, dir);
 }
 export function defaultServiceState(home, options = {}) {
     const platform = options.platform ?? process.platform;

package/dist/lib/doctor/checks/cli-path.d.ts

@@ -0,0 +1,11 @@
+import { type ShimPathCheck } from "../../windows/user-path.js";
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+export declare const CLI_PATH_FAMILY_ID = "cli-path";
+export declare const CLI_PATH_CHECK_ID = "cli-path.npm-shim-on-path";
+/**
+ * Windows: is the folder holding the npm `hq.cmd` shim on the PATH a new
+ * terminal gets? Reads the registry only; never edits PATH.
+ */
+export declare const cliPathFamily: CheckFamily;
+export declare function checkCliPath(_context: CheckContext, check?: () => ShimPathCheck | null): CheckResult[];
+//# sourceMappingURL=cli-path.d.ts.map

package/dist/lib/doctor/checks/cli-path.js

@@ -0,0 +1,45 @@
+import { checkShimOnPath, pathFixCommand, shimPathWarning } from "../../windows/user-path.js";
+export const CLI_PATH_FAMILY_ID = "cli-path";
+export const CLI_PATH_CHECK_ID = "cli-path.npm-shim-on-path";
+/**
+ * Windows: is the folder holding the npm `hq.cmd` shim on the PATH a new
+ * terminal gets? Reads the registry only; never edits PATH.
+ */
+export const cliPathFamily = {
+    id: CLI_PATH_FAMILY_ID,
+    title: "hq command on PATH",
+    run: (context) => Promise.resolve(checkCliPath(context)),
+};
+export function checkCliPath(_context, check = () => checkShimOnPath()) {
+    const result = check();
+    if (!result) {
+        return [
+            {
+                status: "NA",
+                checkId: CLI_PATH_CHECK_ID,
+                message: "Not a Windows npm global install, so there is no hq.cmd shim folder to check.",
+            },
+        ];
+    }
+    if (result.onPath) {
+        return [
+            {
+                status: "PASS",
+                checkId: CLI_PATH_CHECK_ID,
+                target: result.shimDir,
+                message: `The hq command folder ${result.shimDir} is on your Windows PATH.`,
+            },
+        ];
+    }
+    return [
+        {
+            status: "WARN",
+            checkId: CLI_PATH_CHECK_ID,
+            target: result.shimDir,
+            message: shimPathWarning(result)[0],
+            details: { source: result.source },
+            remediation: `In PowerShell, then open a new terminal: ${pathFixCommand(result.shimDir)}`,
+        },
+    ];
+}
+//# sourceMappingURL=cli-path.js.map

package/dist/lib/doctor/checks/hook-engine.d.ts

@@ -0,0 +1,4 @@
+import type { CheckFamily, CheckResult } from '../types.js';
+export declare function checkHookEngine(): CheckResult;
+export declare const hookEngineFamily: CheckFamily;
+//# sourceMappingURL=hook-engine.d.ts.map