@indigoai-us/hq-cli 5.345.148 → 5.345.150

package/dist/lib/windows/install-followup.js

@@ -0,0 +1,142 @@
+/**
+ * Work that npm 11 will not run from postinstall: put the hq shim folder on
+ * the user PATH, and point the mesh daemon at this install once per CLI version.
+ * Failures are ignored. Hook, version, and staged-install routes do not run it.
+ *
+ * Both steps record their result in ~/.hq/install-followup.json, so later
+ * commands start no PowerShell or daemon process for the same version.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureShimOnUserPath, npmShimDir } from "./user-path.js";
+const MARKER_NAME = "install-followup.json";
+export function isInstallFollowupSkipped(argv, env) {
+    if (env.HQ_INSTALL_FOLLOWUP === "1" || env.HQ_STAGED_INSTALL === "1")
+        return true;
+    const args = argv.slice(2).filter((arg) => arg !== "--verbose");
+    if (args[0] === "mesh" && args[1] === "daemon")
+        return true;
+    if (args[0] === "daemon" && (args[1] === "run" || args[1] === "install"))
+        return true;
+    return false;
+}
+export function isInstalledPackageEntry(entry) {
+    return Boolean(entry && /node_modules[/\\]@indigoai-us[/\\]hq-cli[/\\]/i.test(entry));
+}
+function packageVersion() {
+    try {
+        const pkgPath = fileURLToPath(new URL("../../../package.json", import.meta.url));
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "";
+    }
+    catch {
+        return "";
+    }
+}
+/** A failed daemon install blocks for up to 30 s, so it is retried at most hourly. */
+export const MESH_RETRY_MS = 60 * 60 * 1000;
+function markerFile(env) {
+    const home = env.USERPROFILE || env.HOME || os.homedir();
+    return path.join(home, ".hq", MARKER_NAME);
+}
+function readMarker(env) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(markerFile(env), "utf8"));
+        const marker = {};
+        if (typeof parsed.version === "string")
+            marker.version = parsed.version;
+        if (typeof parsed.path?.dir === "string" && typeof parsed.path.version === "string") {
+            marker.path = { dir: parsed.path.dir, version: parsed.path.version };
+        }
+        if (typeof parsed.meshFailedVersion === "string" && typeof parsed.meshFailedAt === "number") {
+            marker.meshFailedVersion = parsed.meshFailedVersion;
+            marker.meshFailedAt = parsed.meshFailedAt;
+        }
+        return marker;
+    }
+    catch {
+        return {};
+    }
+}
+function writeMarker(env, marker) {
+    const file = markerFile(env);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(marker)}\n`);
+}
+/** True only when `hq mesh daemon install --if-stale` exited 0. */
+function defaultSpawnMesh(argv, env) {
+    const entry = argv[1];
+    if (!entry)
+        return false;
+    const result = spawnSync(process.execPath, [entry, "mesh", "daemon", "install", "--if-stale"], {
+        env: { ...env, HQ_INSTALL_FOLLOWUP: "1" },
+        timeout: 30_000,
+        windowsHide: true,
+        stdio: "ignore",
+    });
+    return result.status === 0 && !result.error;
+}
+export function runWindowsInstallFollowup(deps) {
+    const env = deps.env ?? process.env;
+    if (isInstallFollowupSkipped(deps.argv, env))
+        return;
+    const version = deps.version ?? packageVersion();
+    if (!version)
+        return;
+    const read = deps.readMarker ?? (() => readMarker(env));
+    const write = deps.writeMarker ?? ((marker) => writeMarker(env, marker));
+    const save = (update) => {
+        try {
+            write({ ...read(), ...update });
+        }
+        catch {
+            // A marker failure only means the next command tries again.
+        }
+    };
+    let shimDir;
+    try {
+        shimDir = (deps.shimDir ?? (() => npmShimDir(deps.argv[1], fs.existsSync)))();
+    }
+    catch {
+        shimDir = null;
+    }
+    const marker = read();
+    if (shimDir && !(marker.path?.dir === shimDir && marker.path.version === version)) {
+        try {
+            (deps.ensurePath ?? (() => {
+                ensureShimOnUserPath({ entry: deps.argv[1], env });
+            }))();
+        }
+        catch {
+            // PATH repair must not block the command the user asked for.
+        }
+        // Recorded whatever the outcome: a refused or locked HKCU is retried after
+        // the next upgrade, and `hq doctor` keeps reporting the missing folder.
+        save({ path: { dir: shimDir, version } });
+    }
+    if (!isInstalledPackageEntry(deps.argv[1]))
+        return;
+    const mesh = read();
+    if (mesh.version === version)
+        return;
+    const now = (deps.now ?? Date.now)();
+    if (mesh.meshFailedVersion === version && mesh.meshFailedAt !== undefined && now - mesh.meshFailedAt < MESH_RETRY_MS)
+        return;
+    let ok = false;
+    try {
+        ok = (deps.spawnMesh ?? (() => defaultSpawnMesh(deps.argv, env)))();
+    }
+    catch {
+        // The daemon install is best-effort, same as the old postinstall `|| true`.
+    }
+    // Only a successful install marks the version done. A failure is retried
+    // after MESH_RETRY_MS.
+    if (ok)
+        save({ version, meshFailedVersion: undefined, meshFailedAt: undefined });
+    else
+        save({ meshFailedVersion: version, meshFailedAt: now });
+}
+//# sourceMappingURL=install-followup.js.map

package/dist/lib/windows/user-path.d.ts

@@ -1,4 +1,4 @@
-export type RegRun = (cmd: string, args: string[]) => {
+export type PowerShellRun = (script: string, env: NodeJS.ProcessEnv) => {
     status: number | null;
     stdout: string;
 };
@@ -14,19 +14,38 @@ export interface ShimPathDeps {
     /** The running CLI entry script (process.argv[1]). */
     entry?: string;
     exists?: (p: string) => boolean;
-    run?: RegRun;
+    powerShell?: PowerShellRun;
     env?: NodeJS.ProcessEnv;
 }
+/** The longest user Path HQ will write. Longer values break `setx` and some installers. */
+export declare const MAX_USER_PATH_LENGTH = 2047;
+/**
+ * Tests on Windows point the scripts at a scratch key with this variable. The
+ * scripts accept only keys under HKCU:\Software\HQTest\ and skip the
+ * broadcast for them.
+ */
+export declare const USER_PATH_TEST_KEY_ENV = "HQ_USER_PATH_TEST_KEY";
 /** The npm prefix folder above the package's `node_modules`, when `hq.cmd` is there. */
 export declare function npmShimDir(entry: string | undefined, exists: (p: string) => boolean): string | null;
 /** Expand `%NAME%` references the way Windows does, matching names case-insensitively. */
 export declare function expandWindowsEnv(value: string, env: NodeJS.ProcessEnv): string;
+/**
+ * Prints `U:<base64>` for the unexpanded user Path and `M:<base64>` for the
+ * machine Path, base64 of the UTF-16LE bytes, or `U-` / `M-` when a value
+ * cannot be read. Base64 is ASCII, so the console code page cannot change it.
+ */
+export declare const READ_PATHS_SCRIPT: string;
+/** Decode READ_PATHS_SCRIPT output. Null for a value that could not be read. */
+export declare function parseReadPathsOutput(stdout: string): {
+    user: string | null;
+    machine: string | null;
+};
 /**
  * The PATH a new terminal will get: the user Path then the machine Path, as
  * stored in the registry. Falls back to this process's PATH when neither can
  * be read.
  */
-export declare function readPersistedPath(run: RegRun, env: NodeJS.ProcessEnv): {
+export declare function readPersistedPath(run: PowerShellRun, env: NodeJS.ProcessEnv): {
     value: string;
     source: "registry" | "process";
 };
@@ -45,4 +64,62 @@ export declare const PATH_REFRESH_VAR = "HQ_PATH_REFRESH";
 export declare function pathFixCommand(dir: string): string;
 /** Lines to print when the shim folder is missing from PATH; empty when it is present. */
 export declare function shimPathWarning(check: ShimPathCheck): string[];
+export type UserPathWriteReason = "unreadable" | "present" | "written" | "write-failed" | "unsafe-value" | "too-long";
+export interface UserPathWriteResult {
+    written: boolean;
+    reason: UserPathWriteReason;
+}
+/** Adds a folder to HKCU Path in one step: read, check, and write happen together. */
+export interface UserPathStore {
+    appendUserPath(dir: string): UserPathWriteResult;
+}
+export type UserPathAppendPlan = {
+    action: "write";
+    value: string;
+} | {
+    action: "skip";
+    reason: "present" | "unsafe-value" | "too-long";
+};
+/**
+ * Decide the new unexpanded user Path. Membership is decided on the expanded
+ * value so `%APPDATA%\npm` counts. The stored text keeps `%VARS%`. A value
+ * that already holds U+FFFD was garbled by an earlier decode and is never
+ * written back. The ensure script applies the same rules inside PowerShell.
+ */
+export declare function planUserPathAppend(current: string, dir: string, env: NodeJS.ProcessEnv): UserPathAppendPlan;
+/** Exit codes of ENSURE_USER_PATH_SCRIPT. */
+export declare const ENSURE_EXIT: {
+    readonly written: 0;
+    readonly badInput: 2;
+    readonly unreadable: 3;
+    readonly unsafeValue: 4;
+    readonly tooLong: 5;
+    readonly writtenNoBroadcast: 6;
+    readonly present: 10;
+};
+/**
+ * Appends $env:HQ_SHIM_DIR to the HKCU Path as REG_EXPAND_SZ, then broadcasts
+ * the change. The value is read, checked, and written inside this script, so
+ * no console encoding touches it. Mirrors planUserPathAppend.
+ */
+export declare const ENSURE_USER_PATH_SCRIPT: string;
+export declare function ensureExitReason(status: number | null): UserPathWriteResult;
+export declare function powershellUserPathStore(run?: PowerShellRun, extraEnv?: NodeJS.ProcessEnv): UserPathStore;
+export interface EnsureShimResult {
+    shimDir: string;
+    written: boolean;
+    onPath: boolean;
+    source: ShimPathCheck["source"];
+    reason: UserPathWriteReason;
+}
+export interface EnsureShimDeps extends ShimPathDeps {
+    store?: UserPathStore;
+}
+export declare function resetUserPathEnsureCacheForTests(): void;
+/**
+ * Add the npm shim folder to HKCU Path when it is missing. Null off Windows
+ * or when this process is not an npm global install. A failed read does not
+ * write. Machine Path is never written.
+ */
+export declare function ensureShimOnUserPath(deps?: EnsureShimDeps): EnsureShimResult | null;
 //# sourceMappingURL=user-path.d.ts.map

package/dist/lib/windows/user-path.js

@@ -3,14 +3,28 @@
  *
  * npm writes `hq.cmd` directly under its prefix (never `<prefix>\bin`). When
  * that folder is not on the user or machine Path, a new terminal cannot find
- * `hq` even though the install succeeded. HQ detects this and prints the exact
- * fix; it never edits PATH itself.
+ * `hq` even though the install succeeded. The supported install adds that
+ * folder to the user PATH (HKCU only) and broadcasts the change. It never
+ * edits the machine PATH. When the add fails, doctor prints the exact command.
+ *
+ * Windows PowerShell 5.1 and reg.exe print piped output in the console code
+ * page, so a Path holding `C:\Users\José` comes back garbled when read as
+ * UTF-8. Reads therefore return the value as base64 of its UTF-16LE bytes, and
+ * the append is one PowerShell script that reads, checks, and writes the value
+ * without it ever leaving PowerShell.
  */
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
-const USER_ENV_KEY = "HKCU\\Environment";
-const MACHINE_ENV_KEY = "HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment";
+/** The longest user Path HQ will write. Longer values break `setx` and some installers. */
+export const MAX_USER_PATH_LENGTH = 2047;
+const REPLACEMENT_CHAR = "\uFFFD";
+/**
+ * Tests on Windows point the scripts at a scratch key with this variable. The
+ * scripts accept only keys under HKCU:\Software\HQTest\ and skip the
+ * broadcast for them.
+ */
+export const USER_PATH_TEST_KEY_ENV = "HQ_USER_PATH_TEST_KEY";
 /** The npm prefix folder above the package's `node_modules`, when `hq.cmd` is there. */
 export function npmShimDir(entry, exists) {
     if (!entry)
@@ -30,23 +44,37 @@ export function expandWindowsEnv(value, env) {
         return found === undefined ? whole : found;
     });
 }
-function regPath(run, key) {
-    try {
-        const result = run("reg.exe", ["query", key, "/v", "Path"]);
-        if (result.status !== 0)
-            return null;
-        for (const line of result.stdout.split(/\r?\n/)) {
-            // An empty value prints no text after the type, which is an empty Path,
-            // not an unreadable one.
-            const match = /^\s+Path\s+REG_(?:EXPAND_)?SZ(?:\s+(.*))?$/i.exec(line);
-            if (match)
-                return (match[1] ?? "").trim();
-        }
-    }
-    catch {
-        // reg.exe missing or refused: treat as unreadable.
+const SELECT_USER_KEY = [
+    "$key = 'HKCU:\\Environment'",
+    `$test = $env:${USER_PATH_TEST_KEY_ENV}`,
+    "if ($test) { if (-not $test.StartsWith('HKCU:\\Software\\HQTest\\', [StringComparison]::OrdinalIgnoreCase)) { exit 2 }; $key = $test }",
+];
+/**
+ * Prints `U:<base64>` for the unexpanded user Path and `M:<base64>` for the
+ * machine Path, base64 of the UTF-16LE bytes, or `U-` / `M-` when a value
+ * cannot be read. Base64 is ASCII, so the console code page cannot change it.
+ */
+export const READ_PATHS_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    ...SELECT_USER_KEY,
+    "function Emit($tag, $k) { $i = Get-Item -LiteralPath $k -ErrorAction SilentlyContinue; if ($null -eq $i) { return $tag + '-' }; $v = $i.GetValue('Path', $null, 'DoNotExpandEnvironmentNames'); if ($v -isnot [string]) { return $tag + '-' }; return $tag + ':' + [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($v)) }",
+    "Write-Output (Emit 'U' $key)",
+    "Write-Output (Emit 'M' 'HKLM:\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment')",
+].join("\n");
+/** Decode READ_PATHS_SCRIPT output. Null for a value that could not be read. */
+export function parseReadPathsOutput(stdout) {
+    const out = { user: null, machine: null };
+    for (const line of stdout.split(/\r?\n/)) {
+        const match = /^([UM]):([A-Za-z0-9+/=]*)$/.exec(line.trim());
+        if (!match)
+            continue;
+        const value = Buffer.from(match[2], "base64").toString("utf16le");
+        if (match[1] === "U")
+            out.user = value;
+        else
+            out.machine = value;
     }
-    return null;
+    return out;
 }
 /**
  * The PATH a new terminal will get: the user Path then the machine Path, as
@@ -54,7 +82,17 @@ function regPath(run, key) {
  * be read.
  */
 export function readPersistedPath(run, env) {
-    const values = [regPath(run, USER_ENV_KEY), regPath(run, MACHINE_ENV_KEY)].filter((v) => v !== null);
+    let values = [];
+    try {
+        const result = run(READ_PATHS_SCRIPT, {});
+        if (result.status === 0) {
+            const read = parseReadPathsOutput(result.stdout);
+            values = [read.user, read.machine].filter((v) => v !== null);
+        }
+    }
+    catch {
+        // PowerShell missing or refused: treat as unreadable.
+    }
     if (values.length === 0)
         return { value: env.PATH ?? env.Path ?? "", source: "process" };
     return { value: values.map((v) => expandWindowsEnv(v, env)).join(";"), source: "registry" };
@@ -69,8 +107,15 @@ export function isDirOnPath(dir, pathValue) {
     const want = normalizeDir(dir);
     return pathValue.split(";").some((entry) => normalizeDir(entry) === want);
 }
-function defaultRun(cmd, args) {
-    const result = spawnSync(cmd, args, { encoding: "utf8", windowsHide: true, timeout: 5000 });
+/** Runs a script through Windows PowerShell. The script travels as -EncodedCommand (UTF-16LE), so quoting cannot change it. */
+function defaultPowerShell(script, extraEnv) {
+    const encoded = Buffer.from(script, "utf16le").toString("base64");
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded], {
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: 15_000,
+        env: { ...process.env, ...extraEnv },
+    });
     return { status: result.status, stdout: result.stdout ?? "" };
 }
 /** Null when not on Windows or when hq was not installed as an npm global shim. */
@@ -80,7 +125,7 @@ export function checkShimOnPath(deps = {}) {
     const shimDir = npmShimDir(deps.entry ?? process.argv[1], deps.exists ?? fs.existsSync);
     if (!shimDir)
         return null;
-    const persisted = readPersistedPath(deps.run ?? defaultRun, deps.env ?? process.env);
+    const persisted = readPersistedPath(deps.powerShell ?? defaultPowerShell, deps.env ?? process.env);
     return { shimDir, onPath: isDirOnPath(shimDir, persisted.value), source: persisted.source };
 }
 /** Dummy user variable set and cleared so Windows tells running programs that the environment changed. */
@@ -106,9 +151,125 @@ export function shimPathWarning(check) {
         return [];
     return [
         `The folder that holds the hq command (${check.shimDir}) is not on your Windows PATH, so a new terminal will not find hq.`,
-        "To add it for your user, run this in PowerShell, then open a new terminal:",
+        "HQ could not add it automatically. To add it for your user, run this in PowerShell, then open a new terminal:",
         `  ${pathFixCommand(check.shimDir)}`,
-        "HQ does not change PATH for you.",
     ];
 }
+/**
+ * Decide the new unexpanded user Path. Membership is decided on the expanded
+ * value so `%APPDATA%\npm` counts. The stored text keeps `%VARS%`. A value
+ * that already holds U+FFFD was garbled by an earlier decode and is never
+ * written back. The ensure script applies the same rules inside PowerShell.
+ */
+export function planUserPathAppend(current, dir, env) {
+    if (isDirOnPath(dir, expandWindowsEnv(current, env)))
+        return { action: "skip", reason: "present" };
+    if (current.includes(REPLACEMENT_CHAR) || dir.includes(REPLACEMENT_CHAR) || dir.includes(";")) {
+        return { action: "skip", reason: "unsafe-value" };
+    }
+    const trimmed = current.trim().replace(/;+$/g, "");
+    const value = trimmed ? `${trimmed};${dir}` : dir;
+    if (value.length > MAX_USER_PATH_LENGTH)
+        return { action: "skip", reason: "too-long" };
+    return { action: "write", value };
+}
+/** Exit codes of ENSURE_USER_PATH_SCRIPT. */
+export const ENSURE_EXIT = {
+    written: 0,
+    badInput: 2,
+    unreadable: 3,
+    unsafeValue: 4,
+    tooLong: 5,
+    writtenNoBroadcast: 6,
+    present: 10,
+};
+/**
+ * Appends $env:HQ_SHIM_DIR to the HKCU Path as REG_EXPAND_SZ, then broadcasts
+ * the change. The value is read, checked, and written inside this script, so
+ * no console encoding touches it. Mirrors planUserPathAppend.
+ */
+export const ENSURE_USER_PATH_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    "$dir = $env:HQ_SHIM_DIR",
+    `if ([string]::IsNullOrWhiteSpace($dir) -or $dir.Contains(';') -or $dir.Contains([string][char]0xFFFD)) { exit ${ENSURE_EXIT.badInput} }`,
+    ...SELECT_USER_KEY,
+    "$item = Get-Item -LiteralPath $key -ErrorAction SilentlyContinue",
+    `if ($null -eq $item) { exit ${ENSURE_EXIT.unreadable} }`,
+    "$p = $item.GetValue('Path', '', 'DoNotExpandEnvironmentNames')",
+    `if ($p -isnot [string]) { exit ${ENSURE_EXIT.unsafeValue} }`,
+    // Same comparison as normalizeDir: unquote, use backslashes, collapse repeated
+    // separators (keeping a UNC prefix), drop trailing ones, ignore case.
+    "function Norm($s) { $t = $s.Trim(); if ($t.Length -ge 2 -and $t.StartsWith([string][char]34) -and $t.EndsWith([string][char]34)) { $t = $t.Substring(1, $t.Length - 2).Trim() }; $t = $t.Replace([char]47, [char]92); $bs = [string][char]92; $lead = ''; if ($t.StartsWith($bs + $bs)) { $lead = $bs + $bs; $t = $t.Substring(2) }; $t = $lead + [regex]::Replace($t, ($bs + $bs + '+'), $bs); return $t.TrimEnd([char]92).ToLowerInvariant() }",
+    "$want = Norm $dir",
+    `foreach ($e in [Environment]::ExpandEnvironmentVariables($p).Split(';')) { if ((Norm $e) -eq $want) { exit ${ENSURE_EXIT.present} } }`,
+    `if ($p.Contains([string][char]0xFFFD)) { exit ${ENSURE_EXIT.unsafeValue} }`,
+    "$t = $p.Trim().TrimEnd(';')",
+    "if ($t) { $new = $t + ';' + $dir } else { $new = $dir }",
+    `if ($new.Length -gt ${MAX_USER_PATH_LENGTH}) { exit ${ENSURE_EXIT.tooLong} }`,
+    "New-ItemProperty -LiteralPath $key -Name Path -PropertyType ExpandString -Force -Value $new | Out-Null",
+    `if (-not $test) { try { [Environment]::SetEnvironmentVariable('${PATH_REFRESH_VAR}','1','User'); [Environment]::SetEnvironmentVariable('${PATH_REFRESH_VAR}',$null,'User') } catch { exit ${ENSURE_EXIT.writtenNoBroadcast} } }`,
+    `exit ${ENSURE_EXIT.written}`,
+].join("\n");
+export function ensureExitReason(status) {
+    switch (status) {
+        case ENSURE_EXIT.written:
+        case ENSURE_EXIT.writtenNoBroadcast:
+            return { written: true, reason: "written" };
+        case ENSURE_EXIT.present:
+            return { written: false, reason: "present" };
+        case ENSURE_EXIT.unreadable:
+            return { written: false, reason: "unreadable" };
+        case ENSURE_EXIT.unsafeValue:
+        case ENSURE_EXIT.badInput:
+            return { written: false, reason: "unsafe-value" };
+        case ENSURE_EXIT.tooLong:
+            return { written: false, reason: "too-long" };
+        default:
+            return { written: false, reason: "write-failed" };
+    }
+}
+export function powershellUserPathStore(run = defaultPowerShell, extraEnv = {}) {
+    return {
+        appendUserPath(dir) {
+            try {
+                return ensureExitReason(run(ENSURE_USER_PATH_SCRIPT, { ...extraEnv, HQ_SHIM_DIR: dir }).status);
+            }
+            catch {
+                return { written: false, reason: "write-failed" };
+            }
+        },
+    };
+}
+let cachedOnPathDir = null;
+export function resetUserPathEnsureCacheForTests() {
+    cachedOnPathDir = null;
+}
+/**
+ * Add the npm shim folder to HKCU Path when it is missing. Null off Windows
+ * or when this process is not an npm global install. A failed read does not
+ * write. Machine Path is never written.
+ */
+export function ensureShimOnUserPath(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== "win32")
+        return null;
+    const cacheable = deps.store === undefined && deps.powerShell === undefined && deps.platform === undefined;
+    if (cacheable && cachedOnPathDir) {
+        return { shimDir: cachedOnPathDir, written: false, onPath: true, source: "registry", reason: "present" };
+    }
+    const check = checkShimOnPath(deps);
+    if (!check)
+        return null;
+    if (check.onPath) {
+        if (cacheable)
+            cachedOnPathDir = check.shimDir;
+        return { shimDir: check.shimDir, written: false, onPath: true, source: check.source, reason: "present" };
+    }
+    const store = deps.store ?? powershellUserPathStore(deps.powerShell);
+    const applied = store.appendUserPath(check.shimDir);
+    const onPath = applied.written || applied.reason === "present";
+    if (onPath && cacheable)
+        cachedOnPathDir = check.shimDir;
+    return { shimDir: check.shimDir, written: applied.written, onPath, source: check.source, reason: applied.reason };
+}
 //# sourceMappingURL=user-path.js.map

package/dist/main.js

@@ -48,6 +48,7 @@ import { enforceVersionGate, getVersionGatePhase, isLocalDependencyInstall, reso
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { findLazyCommand, registerCommandCatalog } from "./lazy-commands.js";
+import { argvWithoutHelpOnUnknownCommand } from "./unknown-command.js";
 import { emitCliFirstSyncNextStepOutcome, emitCliFeatureUsed, emitCliLimitNoticeEngagement, emitCliLimitNoticeExposure, emitCliInviteNudgeEvent, emitCliSessionStarted, emitPlanLimitInviteTeammateExposure, isCliLimitResourceKind, queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, takeFirstSyncStepOutcomes, takeCliFeatureUsages, takeCliLimitNoticeEngagements, takeCliLimitNoticeExposures, takeCliInviteNudgeEvents, takePlanLimitInviteTeammateExposures, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.js";
 import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
@@ -308,7 +309,7 @@ export async function runCli() {
             return;
         }
         await releasePackageUseLeaseAfterCommandLoad(process.argv);
-        await program.parseAsync();
+        await program.parseAsync(argvWithoutHelpOnUnknownCommand(process.argv));
         commandParsed = true;
         if (process.exitCode === undefined || process.exitCode === 0) {
             maybeShowFirstSyncNextStep();

package/dist/unknown-command.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `hq invite --help` is not a root command. Commander treats `--help` as a
+ * request for the parent help and exits 0 before unknownCommand(). Strip help
+ * flags when the first command word is not a root, then append a nested
+ * did-you-mean when Commander has not already suggested one.
+ * A hidden root such as `daemon` is still a real command, so its `--help` stays.
+ */
+import { Command } from "commander";
+export declare function firstCommandToken(argv: readonly string[]): string | undefined;
+export declare function isKnownRootCommand(token: string): boolean;
+/** Drop `--help`/`-h` so an unknown first word is reported instead of printing root help. */
+export declare function argvWithoutHelpOnUnknownCommand(argv: readonly string[]): string[];
+/** Nested `parent child` paths whose command name or alias is `token`. Hidden commands are skipped. */
+export declare function suggestNestedCommands(token: string): string[];
+export declare function augmentUnknownCommandError(text: string): string;
+/** Wrap the current stderr writer once. A bare unknown-command line gains a nested suggestion. */
+export declare function installUnknownCommandSuggestions(program: Command): void;
+//# sourceMappingURL=unknown-command.d.ts.map

package/dist/unknown-command.js

@@ -0,0 +1,88 @@
+import { COMMAND_CATALOG } from "./command-catalog.generated.js";
+const SUGGEST = Symbol.for("hq.unknownCommandSuggest");
+const ANSI = new RegExp(`${String.fromCharCode(0x1b)}\\[[0-?]*[ -/]*[@-~]`, "g");
+export function firstCommandToken(argv) {
+    const args = argv.slice(2);
+    for (const token of args) {
+        if (token === "--")
+            break;
+        if (token.startsWith("-"))
+            continue;
+        return token;
+    }
+    return undefined;
+}
+export function isKnownRootCommand(token) {
+    const catalog = COMMAND_CATALOG;
+    // Hidden roots are omitted from help, but they are still commands. Stripping
+    // `--help` from `hq daemon remote-control-pools --help` makes Commander print
+    // that command's usage to stderr and exit 1.
+    return catalog.some((command) => command.name === token || command.aliases.includes(token));
+}
+/** Drop `--help`/`-h` so an unknown first word is reported instead of printing root help. */
+export function argvWithoutHelpOnUnknownCommand(argv) {
+    const token = firstCommandToken(argv);
+    if (!token || token === "help" || isKnownRootCommand(token))
+        return [...argv];
+    const out = [];
+    let passthrough = false;
+    argv.forEach((arg, index) => {
+        if (index < 2) {
+            out.push(arg);
+            return;
+        }
+        if (arg === "--")
+            passthrough = true;
+        if (!passthrough && (arg === "--help" || arg === "-h"))
+            return;
+        out.push(arg);
+    });
+    return out;
+}
+/** Nested `parent child` paths whose command name or alias is `token`. Hidden commands are skipped. */
+export function suggestNestedCommands(token) {
+    const hits = new Set();
+    const walk = (entries, prefix) => {
+        for (const entry of entries) {
+            if (entry.hidden)
+                continue;
+            const next = [...prefix, entry.name];
+            if (prefix.length > 0 && (entry.name === token || entry.aliases.includes(token)))
+                hits.add(next.join(" "));
+            if (entry.subcommands.length > 0)
+                walk(entry.subcommands, next);
+        }
+    };
+    walk(COMMAND_CATALOG, []);
+    return [...hits].sort((a, b) => a.localeCompare(b));
+}
+export function augmentUnknownCommandError(text) {
+    const plain = text.replace(ANSI, "");
+    const match = /^error: unknown command '([^']+)'\n$/.exec(plain);
+    if (!match)
+        return text;
+    const suggestions = suggestNestedCommands(match[1]);
+    if (suggestions.length === 0)
+        return text;
+    const hint = suggestions.length === 1
+        ? `(Did you mean ${suggestions[0]}?)`
+        : `(Did you mean one of ${suggestions.join(", ")}?)`;
+    return `${text}${hint}\n`;
+}
+/** Wrap the current stderr writer once. A bare unknown-command line gains a nested suggestion. */
+export function installUnknownCommandSuggestions(program) {
+    const tagged = program;
+    if (tagged[SUGGEST])
+        return;
+    tagged[SUGGEST] = true;
+    const config = program._outputConfiguration;
+    const base = config?.writeErr ?? ((str) => {
+        process.stderr.write(str);
+    });
+    program.configureOutput({
+        writeErr(str) {
+            base(augmentUnknownCommandError(str));
+        },
+    });
+}
+//# sourceMappingURL=unknown-command.js.map

package/dist/utils/cognito-session.d.ts

@@ -119,6 +119,14 @@ export type EnsureCognitoTokenOptions = {
     /** Cancels bounded, non-interactive person-session refreshes. */
     signal?: AbortSignal;
 };
+/**
+ * Env switch a parent process sets so a child `hq` never opens a browser
+ * sign-in. A hook-driven helper (SessionStart's refresh-vault-access) cannot
+ * complete a browser login, and a child waiting on one outlives its caller.
+ */
+export declare const HQ_NO_BROWSER_LOGIN_ENV = "HQ_NO_BROWSER_LOGIN";
+/** An explicit `interactive` option wins; otherwise interactive unless the env switch is "1". */
+export declare function resolveInteractiveLogin(options: Pick<EnsureCognitoTokenOptions, "interactive">, env?: NodeJS.ProcessEnv): boolean;
 /**
  * True when a usable person Cognito cache file exists under the effective
  * `HQ_STATE_DIR` (or `~/.hq`). Presence alone keeps human commands on the