@indigoai-us/hq-cli 5.341.2 → 5.341.3

package/dist/lib/daemon/server.js

@@ -9,6 +9,7 @@
 import * as fs from "node:fs";
 import * as net from "node:net";
 import * as path from "node:path";
+import { performance } from "node:perf_hooks";
 import { CLI_VERSION } from "../../cli-version.js";
 import { canonicalDir, emptyRegistry, readRegistry, registryFile, resolveCompanyForDir } from "../registry/registry.js";
 import { readCompaniesManifestMap } from "../work-context/repo-remote.js";
@@ -24,6 +25,7 @@ import { HQ_MCP_TOOL_NAMES, HQD_NATIVE_TOOL_NAMES } from "../mcp/tools.js";
 import { HQ_ANYWHERE_RUNTIME_FLAG } from "../../commands/anywhere-runtime-flag.js";
 import { createBoundedDaemonFlagMonitor } from "./flag-monitor.js";
 import { readDaemonFlag } from "./flag.js";
+import { startWindowsPipeHost, validateWindowsPipeAcl, WINDOWS_PIPE_STARTUP_REFUSAL } from "./windows-pipe-host.js";
 // The allowlist is deliberately read-only. A newly added hosted MCP tool must
 // pass hq.policy_check until it is explicitly reviewed as read-only here.
 const MCP_READ_ONLY_TOOL_NAMES = new Set([
@@ -49,6 +51,47 @@ const MCP_READ_ONLY_TOOL_NAMES = new Set([
     "hq_version",
     "hq_whoami",
 ]);
+function healthResolution(result) {
+    if (result.company) {
+        // A manifest key is expected to be a single company slug. Do not echo
+        // arbitrary registry text through the diagnostics surface.
+        if (/^[a-z0-9][a-z0-9-]{0,62}$/.test(result.company)) {
+            return { scope: "company", company: result.company, fallbackReason: null };
+        }
+        return { scope: "personal", company: null, fallbackReason: "company_not_in_manifest" };
+    }
+    let fallbackReason = "no_match";
+    const reason = "reason" in result ? result.reason : "";
+    if (reason.startsWith("HQ registry is unavailable"))
+        fallbackReason = "registry_unavailable";
+    else if (reason.startsWith("HQ company manifest is unavailable"))
+        fallbackReason = "manifest_missing_or_malformed";
+    else if (reason.startsWith("Registry company "))
+        fallbackReason = "company_not_in_manifest";
+    return { scope: "personal", company: null, fallbackReason };
+}
+function healthSocket(socketPath, isPipe) {
+    if (isPipe) {
+        return { path: socketPath, transport: "windows_named_pipe", mode: null, ownerMatchesUser: null, userOnly: null };
+    }
+    try {
+        const stat = fs.lstatSync(socketPath);
+        const mode = stat.mode & 0o777;
+        const uid = typeof process.getuid === "function" ? process.getuid() : null;
+        const ownerMatchesUser = uid !== null && stat.uid === uid;
+        const userOnly = stat.isSocket() && ownerMatchesUser && (mode & 0o077) === 0;
+        return {
+            path: socketPath,
+            transport: "unix_socket",
+            mode: `0${mode.toString(8).padStart(3, "0")}`,
+            ownerMatchesUser,
+            userOnly,
+        };
+    }
+    catch {
+        return { path: socketPath, transport: "unix_socket", mode: null, ownerMatchesUser: null, userOnly: false };
+    }
+}
 class OpError extends Error {
     code;
     constructor(code, message) {
@@ -164,9 +207,134 @@ function socketIsLive(socketPath) {
         setTimeout(() => done(false), 500).unref();
     });
 }
+function socketLstatOrMissing(socketPath, lstat) {
+    try {
+        return lstat(socketPath);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`${socketPath}: cannot inspect filesystem entry: ${detail}`);
+    }
+}
+function assertTrustedSocketPathComponents(directory, lstat, uid) {
+    const resolved = path.resolve(directory);
+    const { root } = path.parse(resolved);
+    let current = root;
+    for (const component of resolved.slice(root.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, component);
+        const stat = socketLstatOrMissing(current, lstat);
+        if (!stat)
+            return;
+        if (stat.isSymbolicLink())
+            throw new Error(`${current}: path component is a symlink`);
+        if (stat.uid !== uid && stat.uid !== 0 && (stat.mode & 0o022) !== 0) {
+            throw new Error(`${current}: path component is owned by another uid and writable by others`);
+        }
+    }
+}
+function assertPrivateSocketDirectory(directory, stat, uid) {
+    if (stat.isSymbolicLink())
+        throw new Error(`${directory}: socket directory must not be a symlink`);
+    if (!stat.isDirectory())
+        throw new Error(`${directory}: socket directory is not a directory`);
+    if (stat.uid !== uid)
+        throw new Error(`${directory}: socket directory is not owned by the current uid`);
+    if ((stat.mode & 0o077) !== 0)
+        throw new Error(`${directory}: socket directory has group or other permission bits`);
+}
+function assertOwnedUnixSocket(socketPath, stat, uid) {
+    if (stat.isSymbolicLink())
+        throw new Error(`${socketPath}: existing path is a symlink`);
+    if (stat.isDirectory())
+        throw new Error(`${socketPath}: existing path is a directory`);
+    if (!stat.isSocket())
+        throw new Error(`${socketPath}: existing path is not a Unix socket`);
+    if (stat.uid !== uid)
+        throw new Error(`${socketPath}: existing Unix socket is not owned by the current uid`);
+}
+function unlinkOwnedSocketIfPresent(socketPath, lstat, uid, log) {
+    try {
+        assertTrustedSocketPathComponents(path.dirname(socketPath), lstat, uid);
+        const stat = socketLstatOrMissing(socketPath, lstat);
+        if (!stat)
+            return;
+        assertOwnedUnixSocket(socketPath, stat, uid);
+        fs.unlinkSync(socketPath);
+    }
+    catch (err) {
+        log("warn", err instanceof Error ? err.message : `${socketPath}: could not safely remove socket path`);
+    }
+}
+function prepareSocketDirectory(directory, lstat, uid) {
+    assertTrustedSocketPathComponents(directory, lstat, uid);
+    let stat = socketLstatOrMissing(directory, lstat);
+    let created = false;
+    if (!stat) {
+        try {
+            created = fs.mkdirSync(directory, { recursive: true, mode: 0o700 }) !== undefined;
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new Error(`${directory}: cannot create socket directory: ${detail}`);
+        }
+        assertTrustedSocketPathComponents(directory, lstat, uid);
+        stat = socketLstatOrMissing(directory, lstat);
+        if (!stat)
+            throw new Error(`${directory}: socket directory was not created`);
+    }
+    assertPrivateSocketDirectory(directory, stat, uid);
+    if (!created)
+        return;
+    try {
+        fs.chmodSync(directory, 0o700);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`${directory}: cannot set newly created socket directory mode to 0700: ${detail}`);
+    }
+    assertTrustedSocketPathComponents(directory, lstat, uid);
+    const verified = socketLstatOrMissing(directory, lstat);
+    if (!verified)
+        throw new Error(`${directory}: socket directory disappeared during permission verification`);
+    assertPrivateSocketDirectory(directory, verified, uid);
+    if ((verified.mode & 0o7777) !== 0o700) {
+        throw new Error(`${directory}: newly created socket directory mode is not 0700 after chmod`);
+    }
+}
+function verifyUserOnlySocket(socketPath, lstat, uid) {
+    assertTrustedSocketPathComponents(path.dirname(socketPath), lstat, uid);
+    const before = socketLstatOrMissing(socketPath, lstat);
+    if (!before)
+        throw new Error(`${socketPath}: Unix socket is missing after listen`);
+    assertOwnedUnixSocket(socketPath, before, uid);
+    if ((before.mode & 0o7777) !== 0o600) {
+        try {
+            fs.chmodSync(socketPath, 0o600);
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new Error(`${socketPath}: cannot set Unix socket mode to 0600: ${detail}`);
+        }
+    }
+    assertTrustedSocketPathComponents(path.dirname(socketPath), lstat, uid);
+    const after = socketLstatOrMissing(socketPath, lstat);
+    if (!after)
+        throw new Error(`${socketPath}: Unix socket disappeared during permission verification`);
+    assertOwnedUnixSocket(socketPath, after, uid);
+    if ((after.mode & 0o7777) !== 0o600) {
+        throw new Error(`${socketPath}: Unix socket mode is not 0600 after chmod`);
+    }
+}
 export async function startHqdServer(opts) {
-    const { socketPath } = opts;
-    const isPipe = process.platform === "win32";
+    const isPipe = (opts.platform ?? process.platform) === "win32";
+    // Normalize before checking or binding so `..` cannot make the kernel traverse
+    // a symlink that the lexical component check has already removed.
+    const socketPath = isPipe ? opts.socketPath : path.resolve(opts.socketPath);
+    const lstatSocketPath = opts.socketLstat ?? ((candidate) => fs.lstatSync(candidate));
+    const currentUid = !isPipe ? process.getuid?.() : undefined;
+    const startedMonotonicMs = performance.now();
     const startedAtMs = (opts.now ?? (() => new Date()))().getTime();
     const sessions = new SessionRegistry(opts.now);
     const log = opts.log ?? (() => { });
@@ -203,11 +371,28 @@ export async function startHqdServer(opts) {
     };
     let hqMcp = opts.mcpBridge;
     if (!isPipe) {
-        fs.mkdirSync(path.dirname(socketPath), { recursive: true, mode: 0o700 });
-        if (fs.existsSync(socketPath)) {
+        const directory = path.dirname(socketPath);
+        if (currentUid === undefined)
+            throw new Error(`${directory}: cannot verify current uid for Unix socket directory`);
+        prepareSocketDirectory(directory, lstatSocketPath, currentUid);
+        const existing = socketLstatOrMissing(socketPath, lstatSocketPath);
+        if (existing) {
+            assertOwnedUnixSocket(socketPath, existing, currentUid);
             if (await socketIsLive(socketPath))
                 throw new Error(`hqd is already listening on ${socketPath}`);
-            fs.unlinkSync(socketPath);
+            const beforeUnlink = socketLstatOrMissing(socketPath, lstatSocketPath);
+            if (beforeUnlink) {
+                assertOwnedUnixSocket(socketPath, beforeUnlink, currentUid);
+                if (await socketIsLive(socketPath))
+                    throw new Error(`hqd is already listening on ${socketPath}`);
+                try {
+                    fs.unlinkSync(socketPath);
+                }
+                catch (err) {
+                    const detail = err instanceof Error ? err.message : String(err);
+                    throw new Error(`${socketPath}: cannot remove stale owned Unix socket: ${detail}`);
+                }
+            }
         }
     }
     const runtimeFlagMonitor = opts.mcpEnabled ? undefined : createBoundedDaemonFlagMonitor({
@@ -226,6 +411,21 @@ export async function startHqdServer(opts) {
         },
     });
     const mcpEnabled = opts.mcpEnabled ?? (() => runtimeFlagMonitor.enabled());
+    const health = async (cwd) => {
+        const flag = runtimeFlagMonitor?.status() ?? {
+            enabled: await mcpEnabled(),
+            lastSuccessfulReadAgeMs: null,
+            heldThroughReadError: false,
+        };
+        return {
+            reachable: true,
+            version: opts.version ?? CLI_VERSION,
+            uptimeMs: Math.max(0, Math.round(performance.now() - startedMonotonicMs)),
+            flag,
+            resolution: healthResolution(resolve(cwd)),
+            socket: healthSocket(socketPath, isPipe),
+        };
+    };
     /** Synchronous ops answer in request order; policy.check and mcp.call may return a promise. */
     const handle = (req) => {
         const args = req.args ?? {};
@@ -238,6 +438,8 @@ export async function startHqdServer(opts) {
                     pid: process.pid,
                     sessions: sessions.size,
                 };
+            case "health":
+                return health(stringArg(args, "cwd"));
             case "auth.status":
                 return Promise.resolve(mcpEnabled()).then((enabled) => {
                     if (!enabled)
@@ -471,7 +673,7 @@ export async function startHqdServer(opts) {
             socket.write(encodeMessage(msg));
     };
     const clients = new Set();
-    const server = net.createServer((socket) => {
+    const accept = (socket) => {
         clients.add(socket);
         socket.on("close", () => clients.delete(socket));
         socket.on("error", (err) => log("warn", `hqd client error: ${err.message}`));
@@ -527,24 +729,76 @@ export async function startHqdServer(opts) {
             socket.end();
         }, HQD_MAX_LINE_BYTES);
         socket.on("data", push);
-    });
-    await new Promise((resolveListen, rejectListen) => {
-        server.once("error", rejectListen);
-        // Bind with a user-only umask so the socket is never briefly group/world accessible.
-        const prior = isPipe ? null : process.umask(0o177);
+    };
+    if (!isPipe) {
+        if (currentUid === undefined)
+            throw new Error(`${path.dirname(socketPath)}: cannot verify current uid for Unix socket directory`);
+        assertTrustedSocketPathComponents(path.dirname(socketPath), lstatSocketPath, currentUid);
+        const directoryStat = socketLstatOrMissing(path.dirname(socketPath), lstatSocketPath);
+        if (!directoryStat)
+            throw new Error(`${path.dirname(socketPath)}: socket directory is missing before listen`);
+        assertPrivateSocketDirectory(path.dirname(socketPath), directoryStat, currentUid);
+    }
+    let server = null;
+    let windowsPipeHost = null;
+    if (isPipe) {
+        let started;
         try {
-            server.listen(socketPath, () => {
-                server.off("error", rejectListen);
-                resolveListen();
+            const startHost = opts.windowsPipeHostFactory ?? startWindowsPipeHost;
+            started = await startHost(socketPath);
+            (opts.windowsPipeAclCheck ?? validateWindowsPipeAcl)(started.acl);
+            windowsPipeHost = started.host;
+            windowsPipeHost.on("connection", accept);
+            windowsPipeHost.on("failure", (err) => {
+                log("error", `hqd Windows named-pipe helper failed: ${err.message}`);
+                for (const client of clients)
+                    client.destroy(err);
+                opts.onShutdown?.();
+            });
+            windowsPipeHost.on("rejectedRemoteClient", (message) => {
+                log("warn", `hqd rejected a remote Windows named-pipe client: ${message}`);
             });
+            windowsPipeHost.startAccepting();
         }
-        finally {
-            if (prior !== null)
+        catch (err) {
+            if (started)
+                await started.host.close().catch((closeErr) => {
+                    log("warn", `hqd Windows named-pipe helper did not close after security setup failed: ${closeErr.message}`);
+                });
+            policyIndex?.close();
+            hqMcp?.close();
+            log("error", `hqd Windows named-pipe security setup failed: ${err.message}`);
+            throw new Error(WINDOWS_PIPE_STARTUP_REFUSAL);
+        }
+    }
+    else {
+        server = net.createServer(accept);
+        await new Promise((resolveListen, rejectListen) => {
+            server.once("error", rejectListen);
+            // Bind with a user-only umask so the socket is never briefly group/world accessible.
+            const prior = process.umask(0o177);
+            try {
+                server.listen(socketPath, () => {
+                    server.off("error", rejectListen);
+                    resolveListen();
+                });
+            }
+            finally {
                 process.umask(prior);
+            }
+        });
+    }
+    if (!isPipe) {
+        try {
+            verifyUserOnlySocket(socketPath, lstatSocketPath, currentUid);
         }
-    });
-    if (!isPipe)
-        fs.chmodSync(socketPath, 0o600);
+        catch (err) {
+            await new Promise((resolveClose) => server.close(() => resolveClose()));
+            if (currentUid !== undefined)
+                unlinkOwnedSocketIfPresent(socketPath, lstatSocketPath, currentUid, log);
+            throw err;
+        }
+    }
     log("info", `hqd listening on ${socketPath}`);
     let closing = null;
     return {
@@ -554,19 +808,20 @@ export async function startHqdServer(opts) {
             policyIndex?.close();
             runtimeFlagMonitor?.close();
             hqMcp?.close();
-            server.close(() => done());
             // Answered-but-idle clients would otherwise hold close() open.
             for (const client of clients)
                 client.destroy();
-            if (!isPipe) {
-                try {
-                    fs.unlinkSync(socketPath);
-                }
-                catch (err) {
-                    if (err.code !== "ENOENT")
-                        log("warn", `could not remove ${socketPath}: ${err.message}`);
-                }
+            if (windowsPipeHost) {
+                void windowsPipeHost.close().then(done, (err) => {
+                    log("warn", `hqd Windows named-pipe helper did not close cleanly: ${err.message}`);
+                    done();
+                });
+            }
+            else {
+                server.close(() => done());
             }
+            if (!isPipe && currentUid !== undefined)
+                unlinkOwnedSocketIfPresent(socketPath, lstatSocketPath, currentUid, log);
         })),
     };
 }

package/dist/lib/daemon/windows-pipe-host.d.ts

@@ -0,0 +1,17 @@
+export declare const WINDOWS_PIPE_STARTUP_REFUSAL = "hqd is disabled on Windows because the default named-pipe ACL grants read access to Everyone and Anonymous accounts.";
+export interface WindowsPipeAclReport {
+    userSid: string;
+    sddl: string;
+}
+export interface WindowsPipeHost extends NodeJS.EventEmitter {
+    startAccepting(): void;
+    write(connectionId: number, data: Buffer, callback: (err?: Error | null) => void): void;
+    closeConnection(connectionId: number): void;
+    close(): Promise<void>;
+}
+export declare function validateWindowsPipeAcl(report: WindowsPipeAclReport): WindowsPipeAclReport;
+export declare function startWindowsPipeHost(pipePath: string): Promise<{
+    host: WindowsPipeHost;
+    acl: WindowsPipeAclReport;
+}>;
+//# sourceMappingURL=windows-pipe-host.d.ts.map

package/dist/lib/daemon/windows-pipe-host.js

@@ -0,0 +1,218 @@
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { createInterface } from "node:readline";
+import { Duplex } from "node:stream";
+import { fileURLToPath } from "node:url";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseSddlDacl, sddlAccountToSid } from "../work-context/windows-acl.js";
+export const WINDOWS_PIPE_STARTUP_REFUSAL = "hqd is disabled on Windows because the default named-pipe ACL grants read access to Everyone and Anonymous accounts.";
+export function validateWindowsPipeAcl(report) {
+    if (!/^S-1-\d+(?:-\d+)+$/i.test(report.userSid))
+        throw new Error("Windows pipe ACL did not report a valid current user SID");
+    const aces = parseSddlDacl(report.sddl);
+    if (!aces || aces.length !== 1)
+        throw new Error("Windows pipe DACL is not user-only");
+    const [ace] = aces;
+    // Windows uses the LA SDDL alias for the local Administrator account. Its
+    // SID is machine-specific, so match it only when the OS-reported current
+    // user is that account (RID 500).
+    const sid = ace.account.toUpperCase() === "LA" && /^(?:S-1-5-21-\d+-\d+-\d+-)500$/i.test(report.userSid)
+        ? report.userSid.toUpperCase()
+        : sddlAccountToSid(ace.account);
+    const rights = ace.rights.toUpperCase();
+    const fullPipeControl = rights === "GA" || rights === "0X1F019F" || rights === "0X001F019F";
+    if (ace.type !== "A" || ace.flags !== "" || sid?.toUpperCase() !== report.userSid.toUpperCase() || !fullPipeControl) {
+        throw new Error("Windows pipe DACL is not user-only");
+    }
+    const daclPrefix = report.sddl.match(/(?:^|:)D:([A-Z_]*)\(/i)?.[1] ?? "";
+    if (!daclPrefix.includes("P"))
+        throw new Error("Windows pipe DACL is not protected from inherited ACEs");
+    return report;
+}
+function helperPath() {
+    return fileURLToPath(new URL("../../../assets/hqd/windows-pipe-host.ps1", import.meta.url));
+}
+function powershellPath() {
+    const root = process.env.SystemRoot ?? process.env.windir ?? "C:\\Windows";
+    const windowsPowerShell = path.join(root, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    if (fs.existsSync(windowsPowerShell))
+        return windowsPowerShell;
+    const programFiles = process.env.ProgramW6432 ?? process.env.ProgramFiles ?? "C:\\Program Files";
+    const pwsh7 = path.join(programFiles, "PowerShell", "7", "pwsh.exe");
+    if (fs.existsSync(pwsh7))
+        return pwsh7;
+    throw new Error("Windows PowerShell 5.1 or PowerShell 7 is unavailable");
+}
+class WindowsPipeClient extends Duplex {
+    host;
+    connectionId;
+    constructor(host, connectionId) {
+        super({ decodeStrings: true, allowHalfOpen: false });
+        this.host = host;
+        this.connectionId = connectionId;
+    }
+    _read() { }
+    _write(chunk, _encoding, callback) {
+        this.host.write(this.connectionId, chunk, callback);
+    }
+    _final(callback) {
+        this.host.closeConnection(this.connectionId);
+        callback();
+    }
+    _destroy(err, callback) {
+        this.host.closeConnection(this.connectionId);
+        callback(err);
+    }
+    receive(data) {
+        this.push(data);
+    }
+    endFromHost() {
+        this.push(null);
+    }
+}
+class SpawnedWindowsPipeHost extends EventEmitter {
+    child;
+    clients = new Map();
+    lineReader;
+    closed = false;
+    closing = false;
+    constructor(pipePath) {
+        super();
+        const script = helperPath();
+        if (!fs.existsSync(script))
+            throw new Error(`Windows pipe helper is missing at ${script}`);
+        this.child = spawn(powershellPath(), ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", script], {
+            windowsHide: true,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, HQD_PIPE_NAME: pipePath },
+        });
+        let stderr = "";
+        this.child.stderr?.setEncoding("utf8");
+        this.child.stderr?.on("data", (chunk) => {
+            stderr = `${stderr}${chunk}`.slice(-8_192);
+        });
+        this.lineReader = createInterface({ input: this.child.stdout, crlfDelay: Infinity });
+        this.lineReader.on("line", (line) => this.receiveLine(line));
+        this.child.once("error", (err) => this.emit("failure", err));
+        this.child.once("exit", (code, signal) => {
+            this.closed = true;
+            if (this.closing)
+                return;
+            const err = new Error(`Windows pipe helper exited (${signal ?? code})${stderr.trim() ? `: ${stderr.trim()}` : ""}`);
+            this.emit("failure", err);
+            for (const client of this.clients.values())
+                client.destroy(err);
+            this.clients.clear();
+        });
+    }
+    static async start(pipePath, timeoutMs = 15_000) {
+        const host = new SpawnedWindowsPipeHost(pipePath);
+        try {
+            const acl = await new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => reject(new Error("Windows pipe helper did not verify its ACL before timeout")), timeoutMs);
+                const onReady = (report) => {
+                    clearTimeout(timeout);
+                    host.off("failure", onFailure);
+                    resolve(report);
+                };
+                const onFailure = (err) => {
+                    clearTimeout(timeout);
+                    host.off("ready", onReady);
+                    reject(err);
+                };
+                host.once("ready", onReady);
+                host.once("failure", onFailure);
+            });
+            try {
+                return { host, acl: validateWindowsPipeAcl(acl) };
+            }
+            catch (err) {
+                throw new Error(`Windows pipe helper reported DACL ${JSON.stringify(acl.sddl)} for ${acl.userSid}: ${err.message}`);
+            }
+        }
+        catch (err) {
+            await host.close();
+            throw err;
+        }
+    }
+    receiveLine(line) {
+        const [kind, rawId, rawData] = line.split("\t");
+        if (kind === "READY") {
+            try {
+                this.emit("ready", { userSid: rawId, sddl: Buffer.from(rawData ?? "", "base64").toString("utf8") });
+            }
+            catch (err) {
+                this.emit("failure", err instanceof Error ? err : new Error(String(err)));
+            }
+            return;
+        }
+        if (kind === "FATAL") {
+            this.emit("failure", new Error(Buffer.from(rawId ?? "", "base64").toString("utf8") || "Windows pipe helper failed"));
+            return;
+        }
+        if (kind === "REJECT") {
+            this.emit("rejectedRemoteClient", Buffer.from(rawId ?? "", "base64").toString("utf8"));
+            return;
+        }
+        const connectionId = Number(rawId);
+        if (!Number.isSafeInteger(connectionId))
+            return;
+        if (kind === "OPEN") {
+            const client = new WindowsPipeClient(this, connectionId);
+            this.clients.set(connectionId, client);
+            this.emit("connection", client);
+            return;
+        }
+        const client = this.clients.get(connectionId);
+        if (!client)
+            return;
+        if (kind === "DATA")
+            client.receive(Buffer.from(rawData ?? "", "base64"));
+        else if (kind === "CLOSE") {
+            client.endFromHost();
+            this.clients.delete(connectionId);
+        }
+    }
+    write(connectionId, data, callback) {
+        if (this.closed || !this.child.stdin?.writable) {
+            callback(new Error("Windows pipe helper is closed"));
+            return;
+        }
+        this.child.stdin.write(`WRITE\t${connectionId}\t${data.toString("base64")}\n`, "utf8", callback);
+    }
+    closeConnection(connectionId) {
+        if (!this.closed && this.child.stdin?.writable)
+            this.child.stdin.write(`CLOSE\t${connectionId}\n`);
+        this.clients.delete(connectionId);
+    }
+    startAccepting() {
+        if (!this.closed && this.child.stdin?.writable)
+            this.child.stdin.write("START\n");
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closing = true;
+        this.child.stdin?.end();
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.child.kill();
+                resolve();
+            }, 5_000);
+            this.child.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+}
+export async function startWindowsPipeHost(pipePath) {
+    const prefix = "\\\\.\\pipe\\";
+    const pipeName = pipePath.toLowerCase().startsWith(prefix.toLowerCase()) ? pipePath.slice(prefix.length) : pipePath;
+    if (!pipeName || pipeName.includes("\\") || pipeName.includes("/")) {
+        throw new Error("Windows hqd pipe path is not a local named-pipe name");
+    }
+    return SpawnedWindowsPipeHost.start(pipeName);
+}
+//# sourceMappingURL=windows-pipe-host.js.map

package/dist/lib/diagnostics.d.ts

@@ -0,0 +1,9 @@
+/**
+ * True when the person asked for diagnostics.
+ *
+ * Global `--verbose`, or `HQ_DEBUG` set to `1`, `true`, or `yes` (any case,
+ * surrounding spaces ignored). Callers pass `options.env` and `options.argv`
+ * when a command injects them; otherwise the process values are used.
+ */
+export declare function diagnosticsEnabled(env?: NodeJS.ProcessEnv, argv?: readonly string[]): boolean;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/lib/diagnostics.js

@@ -0,0 +1,12 @@
+/**
+ * True when the person asked for diagnostics.
+ *
+ * Global `--verbose`, or `HQ_DEBUG` set to `1`, `true`, or `yes` (any case,
+ * surrounding spaces ignored). Callers pass `options.env` and `options.argv`
+ * when a command injects them; otherwise the process values are used.
+ */
+export function diagnosticsEnabled(env = process.env, argv = process.argv) {
+    const debug = env.HQ_DEBUG?.trim() ?? "";
+    return argv.includes("--verbose") || /^(1|true|yes)$/i.test(debug);
+}
+//# sourceMappingURL=diagnostics.js.map

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

@@ -8,6 +8,7 @@
  * WARN or FAIL with a remediation command. When anywhere was never installed
  * on this machine the family reports a single NA line.
  */
+import { type HqdHealthResult } from "../../daemon/protocol.js";
 import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
 export declare const ANYWHERE_FAMILY_ID = "anywhere";
 export declare const REMEDIATION: {
@@ -27,6 +28,10 @@ export interface AnywhereDeps {
     env?: NodeJS.ProcessEnv;
     /** Version hqd reports; rejects when the socket is unreachable. */
     ping?: () => Promise<string>;
+    /** Read-only hqd health op. Test seam; production queries the daemon socket. */
+    health?: (cwd: string) => Promise<HqdHealthResult>;
+    /** Test seam for the local runtime gate used to keep other checks out of a disabled runtime. */
+    runtimeEnabled?: () => boolean;
     /** The hq-cli version installed on this machine. Default: this CLI's version. */
     cliVersion?: string;
     serviceState?: () => DaemonServiceState;
@@ -34,5 +39,5 @@ export interface AnywhereDeps {
 }
 export declare function createAnywhereFamily(deps?: AnywhereDeps): CheckFamily;
 export declare const anywhereFamily: CheckFamily;
-export declare function runAnywhereChecks(_context: CheckContext, deps?: AnywhereDeps): Promise<CheckResult[]>;
+export declare function runAnywhereChecks(context: CheckContext, deps?: AnywhereDeps): Promise<CheckResult[]>;
 //# sourceMappingURL=anywhere.d.ts.map