@indigoai-us/hq-cli 5.345.148 → 5.345.150

package/dist/hq-cloud-sync-runner/package.json

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.88","bundleSha256":"7e9ee380eae55e059a474fd5f415e8aeb16088805b761d791318d5299645becd","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.90","bundleSha256":"cb49486573d2d1141ee6e18d73dde825f2b7c02074560f19504e3b1daf7eeba8","formatVersion":1}

package/dist/index.d.ts

@@ -3,6 +3,15 @@ import "./node-preflight.js";
 import "./node-network-compat-fast.js";
 import { isVersionRequest } from "./version-request.js";
 import { isFastCoreRequest } from "./fast-scaffold.js";
+/**
+ * Whether the install follow-up would read the registry or spawn the mesh
+ * daemon. False for fast routes' callers, and for commands that are not run
+ * from an npm install: the PATH repair needs the npm shim folder above
+ * node_modules, and the daemon step needs the installed package. Inlined so
+ * those routes do not load user-path.ts. Keep the skip rules aligned with
+ * install-followup.ts.
+ */
+export declare function installFollowupWouldDoWork(argv: readonly string[], env: NodeJS.ProcessEnv, platform: NodeJS.Platform): boolean;
 type PackageUseLeaseLoader = () => Promise<void>;
 type PackageUseUpdateProbe = () => Promise<boolean>;
 /** Resolves true once the command was re-run (exit code already set). */
@@ -18,6 +27,7 @@ declare function runCliEntry(entryUrl: string, dispatch: () => void, loadLease?:
 export declare const __test__: {
     isVersionRequest: typeof isVersionRequest;
     isFastCoreRequest: typeof isFastCoreRequest;
+    installFollowupWouldDoWork: typeof installFollowupWouldDoWork;
     dispatchWithPackageUseLease: typeof dispatchWithPackageUseLease;
     waitForUpdateThenReexec: typeof waitForUpdateThenReexec;
     runCliEntry: typeof runCliEntry;

package/dist/index.js

@@ -156,6 +156,26 @@ async function runMonitorCheckFastWithRecovery(request) {
         return;
     await runMainWithInstallTreeRecovery();
 }
+/**
+ * Whether the install follow-up would read the registry or spawn the mesh
+ * daemon. False for fast routes' callers, and for commands that are not run
+ * from an npm install: the PATH repair needs the npm shim folder above
+ * node_modules, and the daemon step needs the installed package. Inlined so
+ * those routes do not load user-path.ts. Keep the skip rules aligned with
+ * install-followup.ts.
+ */
+export function installFollowupWouldDoWork(argv, env, platform) {
+    if (env.HQ_INSTALL_FOLLOWUP === "1" || env.HQ_STAGED_INSTALL === "1")
+        return false;
+    const args = argv.slice(2).filter((arg) => arg !== "--verbose");
+    if (args[0] === "mesh" && args[1] === "daemon")
+        return false;
+    if (args[0] === "daemon" && (args[1] === "run" || args[1] === "install"))
+        return false;
+    if (platform === "win32")
+        return /[/\\]node_modules[/\\]/i.test(argv[1] ?? "");
+    return /node_modules[/\\]@indigoai-us[/\\]hq-cli[/\\]/i.test(argv[1] ?? "");
+}
 function dispatchCliEntry() {
     // Before anything spawns: a background hq on Windows (no terminal) hides the
     // console window of every child it starts (feedback_351a40d5).
@@ -165,6 +185,19 @@ function dispatchCliEntry() {
         void runHookEnginePath(engineArgs);
         return;
     }
+    // cmd.exe code page 437 prints em dashes as mojibake. Pipes stay UTF-8.
+    // Loaded only on Windows so Linux fast routes do not pay for the module.
+    if (process.platform === "win32") {
+        void import("./lib/windows/console-encoding.js").then(({ installWindowsConsoleEncoding }) => {
+            installWindowsConsoleEncoding();
+        }).catch(() => undefined).then(() => {
+            dispatchCliRoutes();
+        });
+        return;
+    }
+    dispatchCliRoutes();
+}
+function dispatchCliRoutes() {
     if (process.platform === "win32" && coreCommandHasPathOperands(process.argv)) {
         // Keep cygpath off non-Windows and non-path command routes.
         process.argv = normalizeCorePathOperands(process.argv, "win32", cygpathMixedPath);
@@ -172,6 +205,37 @@ function dispatchCliEntry() {
     const versionRequest = isVersionRequest(process.argv);
     const helpRequest = !versionRequest && isCommandHelpRequest(process.argv);
     const parsedFastCore = versionRequest || helpRequest ? null : parseFastCore(process.argv);
+    const monitorRequest = versionRequest || helpRequest ? null : parseMonitorCheckFastRequest(process.argv);
+    const secretsRequest = versionRequest || helpRequest || monitorRequest || parsedFastCore
+        ? null
+        : parseSecretsEnvFastRequest(process.argv);
+    const mcpRequest = !versionRequest &&
+        !helpRequest &&
+        !monitorRequest &&
+        !parsedFastCore &&
+        !secretsRequest &&
+        isMcpServeRequest(process.argv);
+    // `--version`, hook, MCP, and secrets fast routes must not pay for PATH or
+    // daemon work, so they never start PowerShell or reg.exe. The module stays
+    // unloaded when there is nothing to do, so a Linux fast route does not
+    // import it.
+    if (!versionRequest && !monitorRequest && !parsedFastCore && !secretsRequest && !mcpRequest
+        && installFollowupWouldDoWork(process.argv, process.env, process.platform)) {
+        void import("./lib/windows/install-followup.js").then(({ runWindowsInstallFollowup }) => {
+            try {
+                runWindowsInstallFollowup({ argv: process.argv });
+            }
+            catch {
+                // Install repair must not turn into a failed command.
+            }
+        }).catch(() => undefined).then(() => {
+            dispatchCliCommand(versionRequest, helpRequest, parsedFastCore, monitorRequest, secretsRequest, mcpRequest);
+        });
+        return;
+    }
+    dispatchCliCommand(versionRequest, helpRequest, parsedFastCore, monitorRequest, secretsRequest, mcpRequest);
+}
+function dispatchCliCommand(versionRequest, helpRequest, parsedFastCore, monitorRequest, secretsRequest, mcpRequest) {
     if (versionRequest) {
         // Bare `--version` is the CLI semver only (the contract field updaters
         // compare). `hq version` and `--json` print the labelled HQ/CLI report.
@@ -202,11 +266,11 @@ function dispatchCliEntry() {
             await runMainWithInstallTreeRecovery();
         });
     }
-    else if (parseMonitorCheckFastRequest(process.argv)) {
+    else if (monitorRequest) {
         // The Stop hook runs this every turn in every session. Answer the common
         // no-active-lane case from the lane-record directory alone; anything the
         // fast route cannot prove falls back to the full command graph.
-        void runMonitorCheckFastWithRecovery(parseMonitorCheckFastRequest(process.argv));
+        void runMonitorCheckFastWithRecovery(monitorRequest);
     }
     else if (parsedFastCore?.entry.kind === "native" &&
         (process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "true" ||
@@ -222,8 +286,8 @@ function dispatchCliEntry() {
         // existing full-graph route.
         void runNativeFastRouteWithRecovery(parsedFastCore);
     }
-    else if (parseSecretsEnvFastRequest(process.argv)) {
-        const request = parseSecretsEnvFastRequest(process.argv);
+    else if (secretsRequest) {
+        const request = secretsRequest;
         void import("./secrets-env-fast-route.js").then(async (route) => {
             await route.dispatchSecretsEnvFastRequest(request, {
                 isEnabled: () => route.secretsEnvFastRouteEnabled(request),
@@ -237,7 +301,7 @@ function dispatchCliEntry() {
             });
         });
     }
-    else if (isMcpServeRequest(process.argv)) {
+    else if (mcpRequest) {
         // Keep the minimal startup route; runMcpServe applies the hq-flags gate.
         void import("./commands/mcp-serve.js").then(({ runMcpServe }) => runMcpServe());
     }
@@ -373,6 +437,7 @@ void runCliEntry(import.meta.url, dispatchCliEntry);
 export const __test__ = {
     isVersionRequest,
     isFastCoreRequest,
+    installFollowupWouldDoWork,
     dispatchWithPackageUseLease,
     waitForUpdateThenReexec,
     runCliEntry,

package/dist/lazy-commands.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { COMMAND_CATALOG } from "./command-catalog.generated.js";
+import { installUnknownCommandSuggestions } from "./unknown-command.js";
 const commandCatalog = COMMAND_CATALOG;
 /**
  * One entry for every root, including groups that are assembled by several
@@ -105,6 +106,7 @@ export function findRuntimeHqRoot(start, parentOf = dirname, isRoot = (directory
 export function registerCommandCatalog(program) {
     for (const command of commandCatalog)
         program.addCommand(commandDefinition(command));
+    installUnknownCommandSuggestions(program);
 }
 function commandForToken(token) {
     return commandCatalog.find((candidate) => candidate.name === token || candidate.aliases.includes(token));

package/dist/lib/billing/usage-cost.d.ts

@@ -201,14 +201,44 @@ export interface UsageReport {
     freeItems: string;
     drivers: Driver[];
     noSyncGuideUrl: string;
+    /** Set by `hq billing usage`: the account is on usage pricing, so meters are priced. */
+    onUsagePricing?: true;
     readOnly: true;
 }
+/** One meter's reading with no price attached. */
+export interface MeterReadingRow {
+    key: UsageMeterKey;
+    displayName: string;
+    /** In billed units (GB for storage). Null unless measured. */
+    value: number | null;
+    state: MeterState;
+}
+/**
+ * The report for an account that is not on usage pricing (a flat plan, or the
+ * server did not say). Readings only: no rates, no cost, no projected bill.
+ */
+export interface UsageReadingsReport {
+    scope: UsageScope;
+    source: MonthUsage["source"];
+    /** False: flat plan, meters are not billed. Null: HQ did not say. */
+    onUsagePricing: false | null;
+    period: MonthUsage["period"];
+    meters: MeterReadingRow[];
+    storage?: StorageSplit;
+    /** The one line that says why no cost is shown. */
+    notice: string;
+    readOnly: true;
+}
+export type BillingUsageReport = UsageReport | UsageReadingsReport;
+export declare function isReadingsReport(r: BillingUsageReport): r is UsageReadingsReport;
+/** Readings for an account not on usage pricing. Never prices a meter. */
+export declare function buildReadingsReport(usage: MonthUsage, onUsagePricing: false | null): UsageReadingsReport;
 export declare function buildReport(usage: MonthUsage, rates: {
     rates: readonly UsageMeterRate[];
     allowanceUsd: number;
     source: "published" | "bundled";
     card?: UsageCard;
 }): UsageReport;
-export declare function formatReport(r: UsageReport): string;
+export declare function formatReport(r: BillingUsageReport): string;
 export {};
 //# sourceMappingURL=usage-cost.d.ts.map

package/dist/lib/billing/usage-cost.js

@@ -362,6 +362,38 @@ export function findDrivers(usage, bill) {
 // ── Report ──────────────────────────────────────────────────────────────────
 /** The self-hosted / no-sync guide the usage card links (feed `signup.selfHosted.url`). */
 export const NO_SYNC_GUIDE_URL = SELF_HOSTED_GUIDE_URL;
+export function isReadingsReport(r) {
+    return !("bill" in r);
+}
+function readingsNotice(scope, onUsagePricing) {
+    if (onUsagePricing === false) {
+        return scope.kind === "company"
+            ? `${scope.companySlug} is on a flat plan, so usage meters are not billed.`
+            : "Your personal account is on a flat plan, so usage meters are not billed.";
+    }
+    const who = scope.kind === "company" ? scope.companySlug : "your personal account";
+    return `HQ did not say whether ${who} is on usage pricing, so no costs are shown.`;
+}
+/** Readings for an account not on usage pricing. Never prices a meter. */
+export function buildReadingsReport(usage, onUsagePricing) {
+    const byKey = new Map(usage.meters.map((m) => [m.key, m]));
+    const meters = BUNDLED_USAGE_METER_RATES.map((rate) => {
+        const reading = byKey.get(rate.key);
+        return reading && reading.state === "measured" && reading.value !== null
+            ? { key: rate.key, displayName: rate.displayName, value: reading.value, state: "measured" }
+            : { key: rate.key, displayName: rate.displayName, value: null, state: reading?.state ?? "not-available" };
+    });
+    return {
+        scope: usage.scope,
+        source: usage.source,
+        onUsagePricing,
+        period: usage.period,
+        meters,
+        ...(usage.storage ? { storage: usage.storage } : {}),
+        notice: readingsNotice(usage.scope, onUsagePricing),
+        readOnly: true,
+    };
+}
 export function buildReport(usage, rates) {
     const bill = computeBill(usage, rates.rates, rates.allowanceUsd);
     return {
@@ -394,7 +426,21 @@ function valueText(m) {
         return `${Math.round(m.value)} vault${Math.round(m.value) === 1 ? "" : "s"}`;
     return `${Math.round(m.value)}`;
 }
+function formatReadingsReport(r) {
+    const who = r.scope.kind === "company" ? r.scope.companySlug : "your personal HQ";
+    const lines = [];
+    lines.push(`Usage for ${who}, ${r.period.start.slice(0, 7)} (as of ${r.period.asOf.slice(0, 10)})`);
+    lines.push("");
+    const nameW = Math.max(...r.meters.map((m) => m.displayName.length));
+    for (const m of r.meters)
+        lines.push(`  ${m.displayName.padEnd(nameW)}  ${valueText(m)}`);
+    lines.push("");
+    lines.push(r.notice);
+    return lines.join("\n");
+}
 export function formatReport(r) {
+    if (isReadingsReport(r))
+        return formatReadingsReport(r);
     const who = r.scope.kind === "company" ? r.scope.companySlug : "your personal HQ";
     const month = r.period.start.slice(0, 7);
     const lines = [];

package/dist/lib/db/local.d.ts

@@ -4,9 +4,9 @@
  * File lives at ~/.hq/db/{company}/vault.db with WAL journal mode.
  * Never returns or logs remote connection strings.
  */
-import Database from "better-sqlite3";
+import type BetterSqlite3 from "better-sqlite3";
 import { type LocalDbPathEnv } from "./paths.js";
-export type LocalDb = Database.Database;
+export type LocalDb = BetterSqlite3.Database;
 export interface OpenLocalDbOptions extends LocalDbPathEnv {
     /** When true, do not create the file if missing (throws). Default false. */
     readonly?: boolean;

package/dist/lib/db/local.js

@@ -5,7 +5,7 @@
  * Never returns or logs remote connection strings.
  */
 import fs from "node:fs";
-import Database from "better-sqlite3";
+import { loadBetterSqlite3 } from "./sqlite-binding.js";
 import { ensureLocalDbDir, resolveLocalDbPath, } from "./paths.js";
 const MIGRATIONS_TABLE = "hq_schema_migrations";
 /**
@@ -33,7 +33,7 @@ export function openLocalDb(companySlug, opts) {
         }
         ensureLocalDbDir(companySlug, opts);
     }
-    const db = new Database(dbPath);
+    const db = new (loadBetterSqlite3())(dbPath);
     // WAL for concurrent readers; safe for agent/CLI workloads.
     db.pragma("journal_mode = WAL");
     db.pragma("foreign_keys = ON");

package/dist/lib/db/sql.js

@@ -5,7 +5,7 @@
  * resolved company slug from HQ session/flags. Path overrides that open
  * another company's DB are denied unless an explicit dangerous flag is set.
  */
-import Database from "better-sqlite3";
+import { loadBetterSqlite3 } from "./sqlite-binding.js";
 import { openLocalDb } from "./local.js";
 import { normalizeCompanySlugForLocalDb, resolveLocalDbPath, } from "./paths.js";
 const WRITE_PATTERN = /^\s*(INSERT|UPDATE|DELETE|REPLACE|CREATE|DROP|ALTER|TRUNCATE|REINDEX|VACUUM|BEGIN|COMMIT|ROLLBACK)\b/i;
@@ -49,7 +49,7 @@ export function resolveSqlDbPath(opts) {
     return opts.dbPathOverride;
 }
 function openByPath(dbPath) {
-    const db = new Database(dbPath);
+    const db = new (loadBetterSqlite3())(dbPath);
     db.pragma("journal_mode = WAL");
     db.pragma("foreign_keys = ON");
     return db;

package/dist/lib/db/sqlite-binding.d.ts

@@ -0,0 +1,22 @@
+import type BetterSqlite3 from "better-sqlite3";
+import { type SpawnPlan } from "../../utils/windows-spawn.js";
+export type BetterSqlite3Constructor = typeof BetterSqlite3;
+export declare class SqliteBindingError extends Error {
+    constructor(cause?: unknown);
+}
+export interface LoadBetterSqlite3Options {
+    importDatabase?: () => BetterSqlite3Constructor;
+    /** Return true when the native binary is ready to load again. */
+    repair?: () => boolean;
+}
+export declare function resetSqliteBindingForTests(): void;
+export declare function clearBetterSqlite3RequireCache(): void;
+/**
+ * A `.js` bin runs under this Node. A `.cmd` shim goes through the escaped
+ * cmd.exe plan, so a profile path with spaces or `&` stays one argument.
+ */
+export declare function planRepairToolSpawn(cmd: string, args: readonly string[], env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): SpawnPlan;
+/** Download or build better-sqlite3's native binary inside its own package directory. */
+export declare function repairBetterSqlite3(): boolean;
+export declare function loadBetterSqlite3(options?: LoadBetterSqlite3Options): BetterSqlite3Constructor;
+//# sourceMappingURL=sqlite-binding.d.ts.map

package/dist/lib/db/sqlite-binding.js

@@ -0,0 +1,168 @@
+/**
+ * Load better-sqlite3 without requiring the user to approve npm scripts.
+ * npm 11 skips dependency install scripts, so the prebuilt binary is often
+ * missing after `npm install -g`. Try a one-shot prebuild download from the
+ * installed package, then surface the exact allow-scripts command.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { planResolvedCommandSpawn } from "../../utils/windows-spawn.js";
+const require = createRequire(import.meta.url);
+export class SqliteBindingError extends Error {
+    constructor(cause) {
+        super("better-sqlite3 did not load. npm 11.16 and later skip its install script unless scripts are allowed, so the prebuilt binary was not downloaded. " +
+            "HQ tried to download the prebuild and it still failed. " +
+            "Fix: npm install -g @indigoai-us/hq-cli --allow-scripts=better-sqlite3");
+        this.name = "SqliteBindingError";
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+let cached;
+let failed;
+let defaultRepairAttempted = false;
+export function resetSqliteBindingForTests() {
+    cached = undefined;
+    failed = undefined;
+    defaultRepairAttempted = false;
+}
+function isNativeBindingError(error) {
+    const record = error;
+    const text = error instanceof Error ? `${record?.code ?? ""} ${error.message}` : String(error);
+    return /better_sqlite3\.node|could not locate the bindings file|NODE_MODULE_VERSION|was compiled against a different node|not a valid win32 application|dlopen|ERR_DLOPEN_FAILED|MODULE_NOT_FOUND/i.test(text);
+}
+export function clearBetterSqlite3RequireCache() {
+    for (const id of Object.keys(require.cache)) {
+        if (id.includes(`${path.sep}better-sqlite3${path.sep}`))
+            delete require.cache[id];
+    }
+}
+function defaultImport() {
+    return require("better-sqlite3");
+}
+function resolveTool(dir, tool) {
+    const names = process.platform === "win32" ? [`${tool}.cmd`, `${tool}.exe`, tool] : [tool];
+    const bins = [path.join(path.dirname(dir), ".bin"), path.join(dir, "node_modules", ".bin")];
+    for (const bin of bins) {
+        for (const name of names) {
+            const candidate = path.join(bin, name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+    }
+    try {
+        const localRequire = createRequire(path.join(dir, "package.json"));
+        const pkgJson = localRequire.resolve(`${tool}/package.json`);
+        const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf8"));
+        const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[tool];
+        if (typeof rel === "string")
+            return path.join(path.dirname(pkgJson), rel);
+    }
+    catch {
+        // The tool is not installed next to better-sqlite3.
+    }
+    return null;
+}
+/**
+ * A `.js` bin runs under this Node. A `.cmd` shim goes through the escaped
+ * cmd.exe plan, so a profile path with spaces or `&` stays one argument.
+ */
+export function planRepairToolSpawn(cmd, args, env = process.env, platform = process.platform) {
+    if (cmd.endsWith(".js"))
+        return { cmd: process.execPath, args: [cmd, ...args], shell: false };
+    return planResolvedCommandSpawn(cmd, args, env, platform);
+}
+function runTool(cmd, args, cwd) {
+    const plan = planRepairToolSpawn(cmd, args);
+    spawnSync(plan.cmd, plan.args, {
+        cwd,
+        timeout: 60_000,
+        windowsHide: true,
+        stdio: "ignore",
+        shell: plan.shell,
+        ...(plan.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+    });
+}
+/** Download or build better-sqlite3's native binary inside its own package directory. */
+export function repairBetterSqlite3() {
+    let dir;
+    try {
+        dir = path.dirname(require.resolve("better-sqlite3/package.json"));
+    }
+    catch {
+        return false;
+    }
+    const artifact = path.join(dir, "build", "Release", "better_sqlite3.node");
+    if (fs.existsSync(artifact))
+        return true;
+    const prebuild = resolveTool(dir, "prebuild-install");
+    if (prebuild)
+        runTool(prebuild, [], dir);
+    if (fs.existsSync(artifact))
+        return true;
+    const nodeGyp = resolveTool(dir, "node-gyp");
+    if (nodeGyp)
+        runTool(nodeGyp, ["rebuild", "--release"], dir);
+    return fs.existsSync(artifact);
+}
+function attemptRepair(options) {
+    if (options.repair) {
+        try {
+            return options.repair();
+        }
+        catch {
+            return false;
+        }
+    }
+    if (defaultRepairAttempted)
+        return false;
+    defaultRepairAttempted = true;
+    try {
+        return repairBetterSqlite3();
+    }
+    catch {
+        return false;
+    }
+}
+export function loadBetterSqlite3(options = {}) {
+    const injected = options.importDatabase !== undefined;
+    if (!injected && cached)
+        return cached;
+    if (!injected && failed)
+        throw failed;
+    const importDatabase = options.importDatabase ?? defaultImport;
+    const load = () => {
+        const ctor = importDatabase();
+        if (!injected)
+            cached = ctor;
+        return ctor;
+    };
+    try {
+        return load();
+    }
+    catch (error) {
+        if (!isNativeBindingError(error))
+            throw error;
+        const repaired = attemptRepair(options);
+        if (!repaired) {
+            const wrapped = new SqliteBindingError(error);
+            if (!injected)
+                failed = wrapped;
+            throw wrapped;
+        }
+        if (!injected)
+            clearBetterSqlite3RequireCache();
+        try {
+            return load();
+        }
+        catch (retryError) {
+            const wrapped = new SqliteBindingError(retryError);
+            if (!injected)
+                failed = wrapped;
+            throw wrapped;
+        }
+    }
+}
+//# sourceMappingURL=sqlite-binding.js.map

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

@@ -48,10 +48,22 @@ export interface AnywhereDeps {
     serviceState?: () => DaemonServiceState;
     /** Is an hqd process alive? Default: the daemon lock names a live hqd pid. */
     daemonRunning?: () => boolean;
+    /** Transport to report when health throws. Production uses the platform default. */
+    unreachableTransport?: "windows_named_pipe" | "unix_socket";
     now?: () => Date;
 }
+export interface PipeConnectFailure {
+    code?: string;
+    detail?: string;
+}
 export declare function createAnywhereFamily(deps?: AnywhereDeps): CheckFamily;
 export declare const anywhereFamily: CheckFamily;
+/**
+ * What to say when the Windows named pipe cannot be used. The old wording
+ * guessed an ACL refusal whenever any process looked like a daemon. This
+ * reports the connect error that was actually observed.
+ */
+export declare function windowsNamedPipeUnreachableMessage(socketPath: string, daemonRunning: boolean, failure?: PipeConnectFailure): string;
 export declare function defaultServiceState(home: string, options?: DaemonServiceProbeOptions): DaemonServiceState;
 export {};
 //# sourceMappingURL=anywhere.d.ts.map

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

@@ -63,6 +63,7 @@ async function runAnywhereChecks(context, deps = {}) {
         : result(personSetting ? "PASS" : "WARN", "person-setting", `HQ Anywhere person setting is ${personSetting ? "on" : "off"}`);
     let health;
     let healthUnsupported = false;
+    let connectFailure;
     try {
         if (deps.health) {
             health = await deps.health(cwd);
@@ -107,12 +108,14 @@ async function runAnywhereChecks(context, deps = {}) {
                 };
                 healthUnsupported = true;
             }
-            catch {
-                health = unreachableHealth(socketPath);
+            catch (inner) {
+                health = unreachableHealth(socketPath, deps.unreachableTransport);
+                connectFailure = connectFailureFrom(inner);
             }
         }
         else {
-            health = unreachableHealth(socketPath);
+            health = unreachableHealth(socketPath, deps.unreachableTransport);
+            connectFailure = connectFailureFrom(error);
         }
     }
     const claude = claudeTargets(home);
@@ -126,7 +129,7 @@ async function runAnywhereChecks(context, deps = {}) {
     const daemonRunning = health.reachable
         ? true
         : (deps.daemonRunning ?? (() => runningDaemonPid(daemonPaths(home, env).lockPath) !== null))();
-    const healthCheck = runtimeHealthCheck(health, healthUnsupported, serviceState, daemonRunning);
+    const healthCheck = runtimeHealthCheck(health, healthUnsupported, serviceState, daemonRunning, connectFailure);
     if (!runtimeEnabled)
         return [healthCheck, settingCheck];
     const remoteModes = [
@@ -177,17 +180,67 @@ async function runAnywhereChecks(context, deps = {}) {
         out.push(checkSkillLinks("codex", codex.skillsDir, REMEDIATION.installCodex, REMEDIATION.repairCodexSkills));
     return out;
 }
-function unreachableHealth(socketPath) {
+function unreachableHealth(socketPath, transport) {
     return {
         reachable: false,
         version: null,
         uptimeMs: null,
         flag: { enabled: null, lastSuccessfulReadAgeMs: null, heldThroughReadError: false },
         resolution: { scope: "unknown", company: null, fallbackReason: null },
-        socket: { path: socketPath, transport: process.platform === "win32" ? "windows_named_pipe" : "unix_socket", mode: null, ownerMatchesUser: null, userOnly: null },
+        socket: {
+            path: socketPath,
+            transport: transport ?? (process.platform === "win32" ? "windows_named_pipe" : "unix_socket"),
+            mode: null,
+            ownerMatchesUser: null,
+            userOnly: null,
+        },
     };
 }
-function runtimeHealthCheck(health, healthUnsupported = false, serviceState, daemonRunning = true) {
+function connectFailureFrom(error) {
+    if (error instanceof HqdClientError)
+        return { code: error.code, detail: error.message };
+    if (error instanceof Error) {
+        const code = error.code;
+        return { code: typeof code === "string" ? code : undefined, detail: error.message };
+    }
+    return { detail: String(error) };
+}
+function failureSuffix(failure) {
+    if (!failure)
+        return "";
+    const parts = [failure.code, failure.detail].filter((part) => Boolean(part && part.trim()));
+    return parts.length === 0 ? "" : ` (${parts.join(": ")})`;
+}
+function accessDenied(failure) {
+    const code = (failure?.code ?? "").toUpperCase();
+    if (code === "EACCES" || code === "EPERM")
+        return true;
+    return /access is denied|unsafe acl/i.test(failure?.detail ?? "");
+}
+/**
+ * What to say when the Windows named pipe cannot be used. The old wording
+ * guessed an ACL refusal whenever any process looked like a daemon. This
+ * reports the connect error that was actually observed.
+ */
+export function windowsNamedPipeUnreachableMessage(socketPath, daemonRunning, failure) {
+    const suffix = failureSuffix(failure);
+    if (!daemonRunning) {
+        return `hqd is not running, so its named pipe ${socketPath} does not exist${suffix}. Run ${REMEDIATION.daemonStatus} to see why it has not started.`;
+    }
+    if (accessDenied(failure)) {
+        return `hqd is running but access to named pipe ${socketPath} was denied${suffix}. The pipe ACL does not allow this user. Run ${REMEDIATION.daemonRestart} to recreate the pipe.`;
+    }
+    const code = (failure?.code ?? "").toUpperCase();
+    if (code === "ENOENT") {
+        return `hqd is running but named pipe ${socketPath} does not exist${suffix}. Run ${REMEDIATION.daemonRestart} to recreate the pipe.`;
+    }
+    if (code === "ETIMEDOUT") {
+        return `hqd is running but did not answer on named pipe ${socketPath}${suffix}. Run ${REMEDIATION.daemonStatus}, then ${REMEDIATION.daemonRestart}.`;
+    }
+    const observed = suffix || " (observed)";
+    return `hqd is not reachable on ${socketPath}${observed}. HQ did not see an access-denied error, so this is not a named-pipe ACL refusal. Run ${REMEDIATION.daemonStatus} to see why, then ${REMEDIATION.daemonRestart}.`;
+}
+function runtimeHealthCheck(health, healthUnsupported = false, serviceState, daemonRunning = true, failure) {
     const { flag, resolution, socket } = health;
     const age = flag.lastSuccessfulReadAgeMs === null
         ? "unknown"
@@ -204,11 +257,9 @@ function runtimeHealthCheck(health, healthUnsupported = false, serviceState, dae
         ? "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 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 unreachableMessage = socket.transport === "windows_named_pipe"
+        ? windowsNamedPipeUnreachableMessage(socket.path, daemonRunning, failure)
+        : `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,