@indigoai-us/hq-cli 5.276.0 → 5.277.0

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

@@ -24,6 +24,7 @@
 import type { UnitPlan } from "./catalog.js";
 import type { MachineType } from "./machine-type.js";
 import type { ControlRequest } from "./requests.js";
+import { syncPassResult } from "./sync-runner.js";
 export declare const BACKOFF_BASE_MS = 1000;
 export declare const BACKOFF_MAX_MS = 60000;
 export declare const HEALTHY_RUN_MS = 60000;
@@ -34,6 +35,9 @@ export declare const HANDOFF_STAGGER_MS = 15000;
 export declare const HANDOFF_DRAIN_MAX_MS: number;
 export interface SupervisedChild {
     pid?: number;
+    stdout?: {
+        on(event: "data" | "end", handler: (chunk?: Buffer | string) => void): unknown;
+    };
     on(event: "exit", handler: (code: number | null, signal: string | null) => void): unknown;
     on(event: "error", handler: (err: Error) => void): unknown;
     kill(signal?: NodeJS.Signals | number): boolean;
@@ -57,6 +61,8 @@ export interface UnitState {
     lastRunAt?: number;
     nextRunAt?: number;
     lastResult?: "ok" | "failed";
+    lastHeartbeatAt?: string;
+    lastPassResult?: ReturnType<typeof syncPassResult>;
 }
 /** An app that runs the daemon as its own child process instead of an OS unit. */
 export type HostApp = "desktop";
@@ -99,6 +105,8 @@ export interface SupervisorDeps {
     clearTimeout?: (handle: unknown) => void;
     reconcileMs?: number;
     requestPollMs?: number;
+    /** Read hq-cloud's lease status after it exits with the lease-conflict code. */
+    syncOwnerBlockReason?: () => string | undefined;
     /** The running CLI's version; part of the key of units that run `hq` commands. */
     cliVersion?: string;
     /** Services to take over from the previous daemon instead of starting them. */

package/dist/lib/daemon/supervisor.js

@@ -21,6 +21,8 @@
  *
  * Processes, time, and state output are injected; `run.ts` wires the real ones.
  */
+import { StringDecoder } from "node:string_decoder";
+import { SYNC_RUNNER_LEASE_CONFLICT_EXIT, SYNC_RUNNER_LEASE_RETRY_MS, parseSyncRunnerProtocolLine, syncPassResult, } from "./sync-runner.js";
 export const BACKOFF_BASE_MS = 1_000;
 export const BACKOFF_MAX_MS = 60_000;
 export const HEALTHY_RUN_MS = 60_000;
@@ -39,7 +41,15 @@ export function backoffMs(attempt) {
  * `keepAcrossCliUpdates` running.
  */
 export function planKey(plan, cliVersion) {
-    const fields = [plan.kind, plan.restart, plan.intervalSec, plan.initialDelaySec, plan.command, plan.env];
+    const fields = [
+        plan.kind,
+        plan.restart,
+        plan.intervalSec,
+        plan.initialDelaySec,
+        plan.heartbeatTimeoutMs,
+        plan.command,
+        plan.env,
+    ];
     if (cliVersion !== undefined && plan.command?.type === "hq" && !plan.keepAcrossCliUpdates)
         fields.push(cliVersion);
     return JSON.stringify(fields);
@@ -89,6 +99,11 @@ export function createSupervisor(deps) {
             clearT(slot.timer);
         slot.timer = undefined;
     };
+    const clearHeartbeatTimer = (slot) => {
+        if (slot.heartbeatTimer !== undefined)
+            clearT(slot.heartbeatTimer);
+        slot.heartbeatTimer = undefined;
+    };
     const setBlocked = (slot) => {
         const block = slot.plan.blocked;
         slot.state.status = block.state;
@@ -111,6 +126,7 @@ export function createSupervisor(deps) {
      */
     const terminate = (slot, then, drain = false) => {
         clearTimer(slot);
+        clearHeartbeatTimer(slot);
         const child = slot.child;
         if (!child) {
             then?.();
@@ -163,6 +179,69 @@ export function createSupervisor(deps) {
     const watch = (slot, child) => {
         live.add(child);
         let ended = false;
+        const timeoutMs = slot.plan.heartbeatTimeoutMs;
+        const decoder = timeoutMs ? new StringDecoder("utf8") : null;
+        let stdoutRemainder = "";
+        let lastHeartbeatPersistedAt = now() - 15_000;
+        const armHeartbeatWatchdog = () => {
+            if (!timeoutMs)
+                return;
+            clearHeartbeatTimer(slot);
+            slot.heartbeatTimer = setT(() => {
+                slot.heartbeatTimer = undefined;
+                if (stopped || slot.child !== child || slot.expectingExit)
+                    return;
+                deps.log("warn", `${slot.plan.id} emitted no sync protocol heartbeat for ${timeoutMs}ms; restarting it`);
+                terminate(slot, () => scheduleRestart(slot));
+                emit();
+            }, timeoutMs);
+        };
+        const acceptProtocolLine = (line) => {
+            let event;
+            try {
+                event = parseSyncRunnerProtocolLine(line);
+            }
+            catch (err) {
+                deps.log("error", `${slot.plan.id} emitted invalid sync protocol output (${Buffer.byteLength(line)} bytes): ${errorMessage(err)}`);
+                return;
+            }
+            if (!event)
+                return;
+            const at = now();
+            slot.state.lastHeartbeatAt = new Date(at).toISOString();
+            const pass = syncPassResult(event, slot.state.lastHeartbeatAt);
+            if (pass)
+                slot.state.lastPassResult = pass;
+            armHeartbeatWatchdog();
+            if (pass || at - lastHeartbeatPersistedAt >= 15_000) {
+                lastHeartbeatPersistedAt = at;
+                emit();
+            }
+        };
+        if (decoder && child.stdout) {
+            child.stdout.on("data", (chunk) => {
+                if (chunk === undefined)
+                    return;
+                stdoutRemainder += decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                let newline = stdoutRemainder.indexOf("\n");
+                while (newline >= 0) {
+                    acceptProtocolLine(stdoutRemainder.slice(0, newline).trim());
+                    stdoutRemainder = stdoutRemainder.slice(newline + 1);
+                    newline = stdoutRemainder.indexOf("\n");
+                }
+                // A malformed or unexpectedly large line is not a heartbeat. Bound
+                // retained data so a broken child cannot grow daemon memory forever.
+                if (Buffer.byteLength(stdoutRemainder) > 1024 * 1024)
+                    stdoutRemainder = "";
+            });
+            child.stdout.on("end", () => {
+                stdoutRemainder += decoder.end();
+                if (stdoutRemainder)
+                    acceptProtocolLine(stdoutRemainder.trim());
+                stdoutRemainder = "";
+            });
+        }
+        armHeartbeatWatchdog();
         const onEnd = (code, signal) => {
             if (ended)
                 return;
@@ -173,6 +252,7 @@ export function createSupervisor(deps) {
             if (slot.child !== child)
                 return;
             slot.child = undefined;
+            clearHeartbeatTimer(slot);
             if (slot.killTimer !== undefined) {
                 clearT(slot.killTimer);
                 slot.killTimer = undefined;
@@ -200,6 +280,20 @@ export function createSupervisor(deps) {
                 emit();
                 return;
             }
+            if (slot.plan.service === "sync" && code === SYNC_RUNNER_LEASE_CONFLICT_EXIT) {
+                const reason = deps.syncOwnerBlockReason?.() ?? "sync owned by another runner";
+                slot.state.status = "waiting";
+                slot.state.reason = reason;
+                slot.state.nextRunAt = now() + SYNC_RUNNER_LEASE_RETRY_MS;
+                deps.log("info", `${reason}; retrying in ${SYNC_RUNNER_LEASE_RETRY_MS}ms`);
+                slot.timer = setT(() => {
+                    slot.timer = undefined;
+                    startLong(slot);
+                    emit();
+                }, SYNC_RUNNER_LEASE_RETRY_MS);
+                emit();
+                return;
+            }
             deps.log("warn", `${slot.plan.id} exited (code=${code ?? "null"} signal=${signal ?? "none"})`);
             if (ranFor >= HEALTHY_RUN_MS)
                 slot.attempts = 0;
@@ -505,6 +599,11 @@ export function createSupervisor(deps) {
         }
     };
     const handleRequest = (req) => {
+        if (req.action === "reconcile") {
+            deps.log("info", "reconciling daemon configuration (requested)");
+            reconcile();
+            return;
+        }
         if (req.action === "restart-daemon") {
             deps.log("info", "restarting the daemon (requested)");
             if (deps.restartDaemon)
@@ -614,6 +713,7 @@ export function createSupervisor(deps) {
                 clearT(handoffTimer);
             for (const slot of slots.values()) {
                 clearTimer(slot);
+                clearHeartbeatTimer(slot);
                 slot.child = undefined;
                 if (slot.killTimer !== undefined)
                     clearT(slot.killTimer);

package/dist/lib/daemon/sync-runner.d.ts

@@ -0,0 +1,58 @@
+/** Local status and resource controls shared by the daemon and its sync runner. */
+export declare const SYNC_RUNNER_OWNER = "hq-daemon";
+export declare const SYNC_RUNNER_LEASE_CONFLICT_EXIT = 20;
+export declare const SYNC_RUNNER_LEASE_RETRY_MS = 15000;
+export declare const DEFAULT_SYNC_HEARTBEAT_TIMEOUT_MS = 300000;
+export declare const DEFAULT_SYNC_RUNNER_HEAP_MB = 3584;
+export declare const SYNC_HEARTBEAT_TIMEOUT_ENV = "HQ_DAEMON_SYNC_HEARTBEAT_TIMEOUT_SECONDS";
+export declare const SYNC_RUNNER_HEAP_ENV = "HQ_SYNC_RUNNER_MAX_OLD_SPACE_MB";
+export interface WatchRunnerOwnerStatus {
+    owner: string;
+    pid: number;
+    version: string;
+    startedAt: string;
+    heartbeatAt: string;
+}
+export interface SyncRunnerProcess {
+    pid: number;
+    commandLine: string;
+}
+export type SyncRunnerProcessList = {
+    ok: true;
+    processes: SyncRunnerProcess[];
+} | {
+    ok: false;
+    error: string;
+};
+export interface ProcessListCommandResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+export type ProcessListRunner = (command: string, args: string[]) => ProcessListCommandResult;
+export interface SyncPassResult {
+    status: "ok" | "partial" | "failed";
+    completedAt: string;
+    companiesAttempted?: number;
+    errors: number;
+    transient: number;
+}
+/** The status file path used by hq-cloud's watch-owner lease. */
+export declare function watchRunnerOwnerStatusPath(hqRoot: string, home?: string, env?: NodeJS.ProcessEnv): string;
+/** Read the watch-owner status JSON without taking or changing its lease. */
+export declare function readWatchRunnerOwnerStatus(statusPath: string): WatchRunnerOwnerStatus | null;
+/** Match a live process command line to the hq-cloud watch runner executable. */
+export declare function isSyncRunnerCommandLine(commandLine: string): boolean;
+/** Return a clear wait reason when an unleased runner already targets this HQ root. */
+export declare function syncRunnerUnleasedBlockReason(hqRoot: string, processes: readonly SyncRunnerProcess[], ownerPid: number | null, platform?: NodeJS.Platform, daemonRunnerPids?: ReadonlySet<number>): string | undefined;
+/** Read complete process command lines so root matching can include trailing arguments. */
+export declare function listSyncRunnerProcesses(platform?: NodeJS.Platform, run?: ProcessListRunner): SyncRunnerProcessList;
+/** The watchdog follows the runner's NDJSON protocol, the same liveness signal used by the desktop app. */
+export declare function parseSyncRunnerProtocolLine(line: string): Record<string, unknown> | null;
+/** Summarize the runner's all-complete event for daemon status. */
+export declare function syncPassResult(event: Record<string, unknown>, completedAt?: string): SyncPassResult | null;
+export declare function syncHeartbeatTimeoutMs(env: NodeJS.ProcessEnv): number;
+/** Preserve an explicit NODE_OPTIONS heap setting; otherwise apply the desktop runner's default/override. */
+export declare function syncRunnerNodeOptions(env: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=sync-runner.d.ts.map

package/dist/lib/daemon/sync-runner.js

@@ -0,0 +1,277 @@
+/** Local status and resource controls shared by the daemon and its sync runner. */
+import * as crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const SYNC_RUNNER_OWNER = "hq-daemon";
+export const SYNC_RUNNER_LEASE_CONFLICT_EXIT = 20;
+export const SYNC_RUNNER_LEASE_RETRY_MS = 15_000;
+export const DEFAULT_SYNC_HEARTBEAT_TIMEOUT_MS = 300_000;
+export const DEFAULT_SYNC_RUNNER_HEAP_MB = 3_584;
+export const SYNC_HEARTBEAT_TIMEOUT_ENV = "HQ_DAEMON_SYNC_HEARTBEAT_TIMEOUT_SECONDS";
+export const SYNC_RUNNER_HEAP_ENV = "HQ_SYNC_RUNNER_MAX_OLD_SPACE_MB";
+const SYNC_RUNNER_COMMAND = /(?:^|[\s/\\])(?:sync-runner\.js|hq-sync-runner(?:\.(?:cmd|exe))?)(?:[\s"']|$)/i;
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** The status file path used by hq-cloud's watch-owner lease. */
+export function watchRunnerOwnerStatusPath(hqRoot, home = os.homedir(), env = process.env) {
+    let canonicalRoot = path.resolve(hqRoot);
+    try {
+        canonicalRoot = fs.realpathSync.native(canonicalRoot);
+    }
+    catch (error) {
+        // hq-cloud uses the resolved path until the HQ root can be canonicalized.
+        if (error?.code !== "ENOENT") {
+            throw new Error(`could not canonicalize HQ root ${canonicalRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    const rootHash = crypto.createHash("sha1").update(canonicalRoot).digest("hex").slice(0, 16);
+    const stateDir = env.HQ_STATE_DIR?.trim() || path.join(home, ".hq");
+    return path.join(stateDir, "locks", `watch-owner-${rootHash}.json`);
+}
+/** Read the watch-owner status JSON without taking or changing its lease. */
+export function readWatchRunnerOwnerStatus(statusPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return null;
+        throw new Error(`could not read watch-runner owner status at ${statusPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const value = record(parsed);
+    if (!value ||
+        typeof value.owner !== "string" ||
+        !Number.isInteger(value.pid) ||
+        typeof value.version !== "string" ||
+        typeof value.startedAt !== "string" ||
+        typeof value.heartbeatAt !== "string") {
+        throw new Error(`watch-runner owner status at ${statusPath} has an invalid shape`);
+    }
+    return value;
+}
+/** Match a live process command line to the hq-cloud watch runner executable. */
+export function isSyncRunnerCommandLine(commandLine) {
+    return SYNC_RUNNER_COMMAND.test(commandLine);
+}
+function commandLineArgs(commandLine) {
+    const args = [];
+    let current = "";
+    let quote = null;
+    let started = false;
+    for (let i = 0; i < commandLine.length; i++) {
+        const char = commandLine[i];
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+                started = true;
+            }
+            else if (char === "\\" && commandLine[i + 1] === quote) {
+                current += commandLine[++i];
+                started = true;
+            }
+            else {
+                current += char;
+                started = true;
+            }
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            started = true;
+        }
+        else if (/\s/.test(char)) {
+            if (started) {
+                args.push(current);
+                current = "";
+                started = false;
+            }
+        }
+        else {
+            current += char;
+            started = true;
+        }
+    }
+    if (started)
+        args.push(current);
+    return args;
+}
+function syncRunnerHqRoot(commandLine) {
+    const args = commandLineArgs(commandLine);
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--hq-root")
+            return args[i + 1] || null;
+        if (arg.startsWith("--hq-root="))
+            return arg.slice("--hq-root=".length) || null;
+    }
+    return null;
+}
+function commandLineNamesRoot(commandLine, hqRoot, platform) {
+    const parsedRoot = syncRunnerHqRoot(commandLine);
+    if (parsedRoot !== null && canonicalRoot(parsedRoot, platform) === canonicalRoot(hqRoot, platform))
+        return true;
+    const pathApi = platform === "win32" ? path.win32 : path;
+    const variants = new Set([pathApi.resolve(hqRoot)]);
+    if (platform === process.platform) {
+        try {
+            variants.add(fs.realpathSync.native(pathApi.resolve(hqRoot)));
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT") {
+                throw new Error(`could not canonicalize sync runner HQ root ${hqRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+        }
+    }
+    const compareFlags = platform === "win32" ? "i" : "";
+    return [...variants].some((root) => {
+        const escaped = root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        return new RegExp(`(?:^|\\s)--hq-root(?:=|\\s+)["']?${escaped}["']?(?=\\s|$)`, compareFlags).test(commandLine);
+    });
+}
+function canonicalRoot(root, platform) {
+    const pathApi = platform === "win32" ? path.win32 : path;
+    let resolved = pathApi.resolve(root);
+    if (platform === process.platform) {
+        try {
+            resolved = fs.realpathSync.native(resolved);
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT") {
+                throw new Error(`could not canonicalize sync runner HQ root ${resolved}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+        }
+    }
+    return platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+/** Return a clear wait reason when an unleased runner already targets this HQ root. */
+export function syncRunnerUnleasedBlockReason(hqRoot, processes, ownerPid, platform = process.platform, daemonRunnerPids = new Set()) {
+    const runner = processes.find((candidate) => {
+        if (daemonRunnerPids.has(candidate.pid) || candidate.pid === ownerPid)
+            return false;
+        if (!isSyncRunnerCommandLine(candidate.commandLine))
+            return false;
+        return commandLineNamesRoot(candidate.commandLine, hqRoot, platform);
+    });
+    if (!runner)
+        return undefined;
+    const lease = ownerPid === null ? "missing" : `belongs to pid ${ownerPid}`;
+    return `sync runner pid ${runner.pid} for ${hqRoot} is running without the watch-owner lease (status ${lease}); waiting for it to exit`;
+}
+/** Read complete process command lines so root matching can include trailing arguments. */
+export function listSyncRunnerProcesses(platform = process.platform, run = (command, args) => {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: 15_000,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        ...(result.error ? { error: result.error } : {}),
+    };
+}) {
+    const command = platform === "win32" ? "powershell.exe" : "ps";
+    const args = platform === "win32"
+        ? [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "Get-CimInstance Win32_Process | Select-Object @{Name='pid';Expression={$_.ProcessId}},@{Name='commandLine';Expression={$_.CommandLine}} | ConvertTo-Json -Compress",
+        ]
+        : ["-eww", "-o", "pid=", "-o", "args="];
+    const result = run(command, args);
+    if (result.error)
+        return { ok: false, error: `could not list process command lines: ${result.error.message}` };
+    if (result.status !== 0) {
+        return { ok: false, error: `could not list process command lines: ${(result.stderr ?? "").trim() || `exit ${result.status}`}` };
+    }
+    if (platform === "win32") {
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout || "[]");
+        }
+        catch (error) {
+            return { ok: false, error: `could not parse Windows process list: ${error instanceof Error ? error.message : String(error)}` };
+        }
+        const rows = Array.isArray(parsed) ? parsed : [parsed];
+        return {
+            ok: true,
+            processes: rows.flatMap((row) => {
+                if (!row || typeof row !== "object")
+                    return [];
+                const value = row;
+                return Number.isInteger(value.pid) && typeof value.commandLine === "string"
+                    ? [{ pid: value.pid, commandLine: value.commandLine }]
+                    : [];
+            }),
+        };
+    }
+    const processes = [];
+    for (const line of (result.stdout ?? "").split(/\r?\n/)) {
+        const match = /^\s*(\d+)\s+(.+)$/.exec(line);
+        if (match)
+            processes.push({ pid: Number(match[1]), commandLine: match[2] });
+    }
+    return { ok: true, processes };
+}
+/** The watchdog follows the runner's NDJSON protocol, the same liveness signal used by the desktop app. */
+export function parseSyncRunnerProtocolLine(line) {
+    if (!line.trim())
+        return null;
+    const parsed = record(JSON.parse(line));
+    return parsed && typeof parsed.type === "string" && parsed.type.length > 0 ? parsed : null;
+}
+/** Summarize the runner's all-complete event for daemon status. */
+export function syncPassResult(event, completedAt = new Date().toISOString()) {
+    if (event.type !== "all-complete")
+        return null;
+    const errors = Array.isArray(event.errors) ? event.errors.length : 0;
+    const transient = Array.isArray(event.transient) ? event.transient.length : 0;
+    const status = event.partial === true || transient > 0 ? "partial" : errors > 0 ? "failed" : "ok";
+    return {
+        status,
+        completedAt,
+        ...(typeof event.companiesAttempted === "number" ? { companiesAttempted: event.companiesAttempted } : {}),
+        errors,
+        transient,
+    };
+}
+export function syncHeartbeatTimeoutMs(env) {
+    const raw = env[SYNC_HEARTBEAT_TIMEOUT_ENV]?.trim();
+    if (!raw || !/^\d+$/.test(raw))
+        return DEFAULT_SYNC_HEARTBEAT_TIMEOUT_MS;
+    const seconds = Number(raw);
+    const maxSeconds = Math.floor(2_147_483_647 / 1_000);
+    if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > maxSeconds)
+        return DEFAULT_SYNC_HEARTBEAT_TIMEOUT_MS;
+    return seconds * 1_000;
+}
+function hasHeapOption(options) {
+    const tokens = options.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i].replaceAll("--max_old_space_size", "--max-old-space-size");
+        if (token === "--max-old-space-size" || token.startsWith("--max-old-space-size="))
+            return true;
+    }
+    return false;
+}
+/** Preserve an explicit NODE_OPTIONS heap setting; otherwise apply the desktop runner's default/override. */
+export function syncRunnerNodeOptions(env) {
+    const inherited = env.NODE_OPTIONS?.trim() ?? "";
+    if (hasHeapOption(inherited))
+        return inherited || undefined;
+    const rawOverride = env[SYNC_RUNNER_HEAP_ENV]?.trim();
+    const override = rawOverride && /^\d+$/.test(rawOverride) ? Number(rawOverride) : undefined;
+    const heapMb = override && Number.isSafeInteger(override) && override > 0 ? override : DEFAULT_SYNC_RUNNER_HEAP_MB;
+    const heapFlag = `--max-old-space-size=${heapMb}`;
+    return inherited ? `${inherited} ${heapFlag}` : heapFlag;
+}
+//# sourceMappingURL=sync-runner.js.map

package/dist/lib/doctor/__testing__/run-doctor.d.ts

@@ -0,0 +1,8 @@
+import { type RunDoctorOptions, type RunDoctorResult } from "../../../commands/doctor.js";
+/**
+ * Run doctor tests against synthetic state. The production registry normally
+ * reads local HQ work-context, sync, daemon, and session state; tests must not
+ * inspect the developer's HOME or request the live integrations inventory.
+ */
+export declare function runDoctorForTest(options?: RunDoctorOptions): Promise<RunDoctorResult>;
+//# sourceMappingURL=run-doctor.d.ts.map

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

@@ -0,0 +1,52 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { runDoctor as runDoctorCommand, } from "../../../commands/doctor.js";
+/**
+ * Run doctor tests against synthetic state. The production registry normally
+ * reads local HQ work-context, sync, daemon, and session state; tests must not
+ * inspect the developer's HOME or request the live integrations inventory.
+ */
+export async function runDoctorForTest(options = {}) {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "hq-doctor-test-home-"));
+    const homeRoot = path.parse(home).root;
+    const homeDrive = homeRoot.endsWith(path.sep) ? homeRoot.slice(0, -1) : homeRoot;
+    const homePath = home.slice(homeDrive.length);
+    const isolatedEnv = {
+        HOME: home,
+        USERPROFILE: home,
+        HOMEDRIVE: process.platform === "win32" ? homeDrive : undefined,
+        HOMEPATH: process.platform === "win32" ? homePath : undefined,
+        HQ_ROOT: undefined,
+        HQ_STATE_DIR: path.join(home, ".hq"),
+        HQ_MACHINE_TOKEN_STATE_DIR: path.join(home, ".hq", "work-mesh", "daemon"),
+        HQ_MACHINE_CREDS_FILE: undefined,
+        HQ_AGENT_DIR: path.join(home, ".hq-agent"),
+        HQ_BOTS_ROOT: path.join(home, ".hq", "bots"),
+        HQ_DAEMON_DIR: path.join(home, ".hq", "daemon"),
+        HQ_WORK_CONTEXT_ROOT: path.join(home, ".hq", "work-context"),
+        HQ_WORK_MESH_ROOT: path.join(home, ".hq", "work-mesh"),
+        HQ_RUNTIME_MARKER_FILE: path.join(home, "runtime.json"),
+        HQ_FLEET_CONFIG_FILE: path.join(home, ".hq-fleet", "config.yaml"),
+    };
+    const originalEnv = new Map(Object.keys(isolatedEnv).map((key) => [key, process.env[key]]));
+    try {
+        for (const [key, value] of Object.entries(isolatedEnv)) {
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+        return await runDoctorCommand({ ...options, integrations: false });
+    }
+    finally {
+        for (const [key, value] of originalEnv) {
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=run-doctor.js.map