@indigoai-us/hq-cli 5.345.148 → 5.345.149

package/dist/lib/install/codex-targets.d.ts

@@ -23,6 +23,9 @@ export declare function addAgentsMdBlock(current: string | null, charter: string
 /** Strip the HQ block, plus the separator `addAgentsMdBlock` put before it. */
 export declare function removeAgentsMdBlock(current: string): string;
 type Doc = Record<string, unknown>;
+export declare function isAdapterEntry(entry: unknown, hqRoot: string): boolean;
+/** The HQ hooks.json entry for one event and target. */
+export declare function codexHookEntry(hqRoot: string, event: string, target?: HookTarget): Record<string, unknown>;
 /**
  * Add one HQ hook group per event; idempotent. An HQ entry for the other
  * target (adapter vs the hqd shim) is swapped out. Foreign hooks are untouched.

package/dist/lib/install/codex-targets.js

@@ -10,6 +10,7 @@
  * module never writes a second adapter.
  */
 import * as fs from 'fs';
+import { engineArgs, isNativeEntry, quotePosix, quoteWindows } from '../hook-engine/registration.js';
 import * as path from 'path';
 import { shimPath } from './claude-targets.js';
 /** Events the Codex hook adapter is registered for at user scope. */
@@ -88,15 +89,25 @@ export function removeAgentsMdBlock(current) {
         start -= 1;
     return current.slice(0, start) + current.slice(end);
 }
-function isAdapterEntry(entry, hqRoot) {
+export function isAdapterEntry(entry, hqRoot) {
     if (!entry || typeof entry !== 'object')
         return false;
+    if (isNativeEntry(entry, hqRoot))
+        return true;
     const cmd = entry.command;
     return (typeof cmd === 'string' &&
         (cmd.includes(JSON.stringify(codexAdapterPath(hqRoot))) ||
             cmd.includes(JSON.stringify(shimPath(hqRoot))) ||
             cmd.includes(JSON.stringify(path.join(hqRoot, 'core', 'packages', 'hq-anywhere', 'hooks', 'codex.sh')))));
 }
+/** The HQ hooks.json entry for one event and target. */
+export function codexHookEntry(hqRoot, event, target = 'master') {
+    const timeout = event === 'SessionEnd' ? 3 : 300;
+    if (typeof target !== 'object')
+        return { type: 'command', command: codexHookCommand(hqRoot, target), timeout };
+    const argv = [target.engine, ...engineArgs(hqRoot, event, 'codex')];
+    return { type: 'command', command: argv.map(quotePosix).join(' '), ...(target.engine.endsWith('.exe') ? { commandWindows: '& ' + argv.map(quoteWindows).join(' ') } : {}), timeout };
+}
 /**
  * Add one HQ hook group per event; idempotent. An HQ entry for the other
  * target (adapter vs the hqd shim) is swapped out. Foreign hooks are untouched.
@@ -104,14 +115,14 @@ function isAdapterEntry(entry, hqRoot) {
 export function addCodexHooks(doc, hqRoot, target = 'master') {
     const hooks = { ...(doc.hooks ?? {}) };
     let changed = false;
-    const want = codexHookCommand(hqRoot, target);
     for (const event of CODEX_HOOK_EVENTS) {
+        const want = codexHookEntry(hqRoot, event, target);
         let groups = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
-        const present = groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => h.command === want));
+        const present = groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => h.command === want.command && h.commandWindows === ('commandWindows' in want ? want.commandWindows : undefined)));
         if (present)
             continue;
         groups = removeCodexHooks({ hooks: { [event]: groups } }, hqRoot).hooks?.[event] ?? [];
-        groups.push({ hooks: [{ type: 'command', command: want, timeout: event === 'SessionEnd' ? 3 : 300 }] });
+        groups.push({ hooks: [want] });
         hooks[event] = groups;
         changed = true;
     }

package/dist/lib/install/hook-target.d.ts

@@ -0,0 +1,9 @@
+import { type HookTarget } from './claude-targets.js';
+/** True when an hq daemon unit (launchd plist or systemd unit) exists. */
+export declare function isDaemonInstalled(home: string, platform?: NodeJS.Platform, queryTask?: (task: string) => boolean): boolean;
+/**
+ * US-010: with hqd installed (and the checkout shipping the shim), hooks go to
+ * the hqd shim; otherwise to master-hook.sh / the Codex adapter.
+ */
+export declare function hookTargetFor(hqRoot: string, home: string, daemonInstalled?: boolean, env?: NodeJS.ProcessEnv): HookTarget;
+//# sourceMappingURL=hook-target.d.ts.map

package/dist/lib/install/hook-target.js

@@ -0,0 +1,39 @@
+/**
+ * Which hook target a user-scope registration uses. Kept apart from
+ * install-global so hq reindex can reconcile registrations without loading the
+ * install command graph.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { realpathOrSelf } from '../../commands/mcp-registration.js';
+import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK, SYSTEM_UNIT_DIR } from '../daemon/install.js';
+import { readDaemonConfig } from '../daemon/config.js';
+import { daemonPaths } from '../daemon/paths.js';
+import { registrationEngine } from '../hook-engine/registration.js';
+import { shimPath } from './claude-targets.js';
+/** True when an hq daemon unit (launchd plist or systemd unit) exists. */
+export function isDaemonInstalled(home, platform = process.platform, queryTask = (task) => spawnSync('schtasks.exe', ['/Query', '/TN', task], { encoding: 'utf8', windowsHide: true }).status === 0) {
+    if (platform === 'win32')
+        return queryTask(DAEMON_WINDOWS_TASK);
+    const candidates = platform === 'darwin'
+        ? [path.join(home, 'Library', 'LaunchAgents', `${DAEMON_LAUNCHD_LABEL}.plist`)]
+        : platform === 'linux'
+            ? [path.join(home, '.config', 'systemd', 'user', DAEMON_SYSTEMD_UNIT), path.join(SYSTEM_UNIT_DIR, DAEMON_SYSTEMD_UNIT)]
+            : [];
+    return candidates.some((p) => fs.existsSync(p));
+}
+/**
+ * US-010: with hqd installed (and the checkout shipping the shim), hooks go to
+ * the hqd shim; otherwise to master-hook.sh / the Codex adapter.
+ */
+export function hookTargetFor(hqRoot, home, daemonInstalled, env = process.env) {
+    const engine = registrationEngine(home, env);
+    if (engine)
+        return { engine };
+    const installed = daemonInstalled ?? isDaemonInstalled(home);
+    const configuredRoot = readDaemonConfig(daemonPaths(home, env).configPath).hqRoot;
+    const daemonMatchesRoot = configuredRoot !== undefined && realpathOrSelf(configuredRoot) === realpathOrSelf(hqRoot);
+    return installed && daemonMatchesRoot && fs.existsSync(shimPath(hqRoot)) ? 'shim' : 'master';
+}
+//# sourceMappingURL=hook-target.js.map

package/dist/lib/windows/console-encoding.d.ts

@@ -0,0 +1,24 @@
+/** ASCII stand-ins for characters cmd.exe cannot show on code page 437. */
+export declare function toAscii(text: string): string;
+/** Parse `chcp` output (`Active code page: 437`). Null when the number is missing. */
+export declare function parseChcpOutput(text: string): number | null;
+type ChcpRun = () => {
+    status: number | null;
+    stdout: string;
+};
+export declare function readConsoleCodePage(run?: ChcpRun): number | null;
+export interface ConsoleEncodingDeps {
+    platform?: NodeJS.Platform;
+    stdout?: NodeJS.WriteStream;
+    stderr?: NodeJS.WriteStream;
+    /** Known code page. Null means the page could not be read and is treated as not UTF-8. */
+    codePage?: number | null;
+    readCodePage?: () => number | null;
+}
+/**
+ * Wrap console stdout and stderr on Windows when the code page is not UTF-8.
+ * Returns false when no wrap was installed.
+ */
+export declare function installWindowsConsoleEncoding(deps?: ConsoleEncodingDeps): boolean;
+export {};
+//# sourceMappingURL=console-encoding.d.ts.map

package/dist/lib/windows/console-encoding.js

@@ -0,0 +1,83 @@
+/**
+ * cmd.exe on a non-UTF-8 code page prints UTF-8 em dashes as mojibake.
+ * When stdout or stderr is a console and the code page is not 65001, string
+ * writes are transliterated to ASCII. Pipes are left as UTF-8 so captured
+ * logs stay intact. Buffer writes are not modified.
+ */
+import { spawnSync } from "node:child_process";
+const WRAP = Symbol.for("hq.windowsConsoleEncoding");
+const REPLACEMENTS = [
+    [/\u2014/g, "--"],
+    [/\u2013/g, "-"],
+    [/\u2018|\u2019|\u201A/g, "'"],
+    [/\u201C|\u201D|\u201E/g, "\""],
+    [/\u2026/g, "..."],
+    [/\u00A0/g, " "],
+    [/\u2022/g, "*"],
+    [/\u2192/g, "->"],
+    [/\u2190/g, "<-"],
+    [/\u21D2/g, "=>"],
+    [/\u00D7/g, "x"],
+];
+/** ASCII stand-ins for characters cmd.exe cannot show on code page 437. */
+export function toAscii(text) {
+    let out = text;
+    for (const [pattern, replacement] of REPLACEMENTS)
+        out = out.replace(pattern, replacement);
+    return out.replace(/[^\t\n\r\x20-\x7E]/g, "?");
+}
+/** Parse `chcp` output (`Active code page: 437`). Null when the number is missing. */
+export function parseChcpOutput(text) {
+    const match = /:\s*(\d+)/.exec(text);
+    if (!match)
+        return null;
+    const codePage = Number(match[1]);
+    return Number.isInteger(codePage) ? codePage : null;
+}
+function defaultChcp() {
+    const result = spawnSync("chcp", [], { encoding: "utf8", windowsHide: true, timeout: 2000 });
+    return { status: result.status, stdout: result.stdout ?? "" };
+}
+export function readConsoleCodePage(run = defaultChcp) {
+    try {
+        const result = run();
+        if (result.status !== 0)
+            return null;
+        return parseChcpOutput(result.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+function wrapStream(stream) {
+    if (stream[WRAP])
+        return;
+    const original = stream.write.bind(stream);
+    stream.write = ((chunk, encoding, cb) => {
+        if (typeof chunk === "string")
+            return original(toAscii(chunk), encoding, cb);
+        return original(chunk, encoding, cb);
+    });
+    stream[WRAP] = true;
+}
+/**
+ * Wrap console stdout and stderr on Windows when the code page is not UTF-8.
+ * Returns false when no wrap was installed.
+ */
+export function installWindowsConsoleEncoding(deps = {}) {
+    if ((deps.platform ?? process.platform) !== "win32")
+        return false;
+    const stdout = (deps.stdout ?? process.stdout);
+    const stderr = (deps.stderr ?? process.stderr);
+    if (!stdout.isTTY && !stderr.isTTY)
+        return false;
+    const codePage = deps.codePage !== undefined ? deps.codePage : (deps.readCodePage ?? readConsoleCodePage)();
+    if (codePage === 65001)
+        return false;
+    if (stdout.isTTY)
+        wrapStream(stdout);
+    if (stderr.isTTY)
+        wrapStream(stderr);
+    return true;
+}
+//# sourceMappingURL=console-encoding.js.map

package/dist/lib/windows/install-followup.d.ts

@@ -0,0 +1,35 @@
+export declare function isInstallFollowupSkipped(argv: readonly string[], env: NodeJS.ProcessEnv): boolean;
+export declare function isInstalledPackageEntry(entry: string | undefined): boolean;
+/**
+ * `version`: the CLI version whose mesh daemon install succeeded.
+ * `path`: the shim folder and CLI version whose PATH step already ran, so a
+ * refused or locked HKCU is not retried on every command.
+ * `meshFailedAt`: when a daemon install for `meshFailedVersion` last failed.
+ * A failure is retried after MESH_RETRY_MS rather than on every command.
+ */
+export interface InstallFollowupMarker {
+    version?: string;
+    path?: {
+        dir: string;
+        version: string;
+    };
+    meshFailedVersion?: string;
+    meshFailedAt?: number;
+}
+/** A failed daemon install blocks for up to 30 s, so it is retried at most hourly. */
+export declare const MESH_RETRY_MS: number;
+export interface InstallFollowupDeps {
+    argv: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    /** The npm shim folder for this entry, or null when hq is not an npm global install. */
+    shimDir?: () => string | null;
+    ensurePath?: () => void;
+    /** True when the daemon install succeeded. */
+    spawnMesh?: () => boolean;
+    version?: string;
+    readMarker?: () => InstallFollowupMarker;
+    writeMarker?: (marker: InstallFollowupMarker) => void;
+    now?: () => number;
+}
+export declare function runWindowsInstallFollowup(deps: InstallFollowupDeps): void;
+//# sourceMappingURL=install-followup.d.ts.map

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