@indigoai-us/hq-cli 5.338.0 → 5.340.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.340.0] — 2026-10-03
+- Preserve resolver output when child processes exit before Windows pipe data has drained.
+- Native `hq core dm-bind` on Windows now finds an `hq.exe` on PATH, and no longer accepts an `hq.cmd` shim it cannot launch.
+- Document the flag-gated HQ Anywhere global install and hqd daemon. The runtime flag remains off by default.
+
+## [5.339.0] — 2026-10-03
+- Reduce cold-start imports for the `checkpoint-stop-gate` and `session-journal` native fast routes.
+
 ## [5.338.0] — 2026-10-03
 - Preserve policy-trigger mutual exclusion without `flock` and honor configured stale-run thresholds without `yq`.
 - Add a manual macOS VM parity workflow for checking HQ CLI behavior in Tart.

package/README.md

@@ -7,6 +7,11 @@ npm install -g @indigoai-us/hq-cli
 hq --help
 ```
 
+The global HQ runtime installs hooks for supported agent runtimes. When the
+`hq-anywhere-runtime` flag is enabled, the hooks use hqd and a per-user folder
+registry. The flag is off by default. See [HQ Anywhere runtime](docs/anywhere-runtime.md)
+for install and link commands.
+
 ## Deploy comments
 
 List comments left on an app in your current hq-deploy organization. Use the

package/assets/scaffold/core/scripts/resolve-company.sh

@@ -142,16 +142,60 @@ const command = process.argv[1];
 if (!command) process.exit(127);
 const child = spawn(command, process.argv.slice(2), { detached: true, stdio: ["ignore", "pipe", "ignore"] });
 let finished = false;
+let exited = false;
+let exitStatus = 1;
+let flushedAfterExit = false;
+let pendingWrites = 0;
+let stdoutEnded = false;
+let drainTimer;
+const finishWhenReady = () => {
+  if (finished || !exited || pendingWrites !== 0) return;
+  if (!stdoutEnded && !flushedAfterExit) return;
+  finished = true;
+  clearTimeout(timer);
+  clearTimeout(drainTimer);
+  try { process.kill(-child.pid, "SIGTERM"); } catch (_) {}
+  process.exit(exitStatus);
+};
+const forward = (chunk) => {
+  pendingWrites++;
+  process.stdout.write(chunk, () => {
+    pendingWrites--;
+    finishWhenReady();
+  });
+};
 const finish = (status) => {
   if (finished) return;
   finished = true;
   clearTimeout(timer);
+  clearTimeout(drainTimer);
   try { process.kill(-child.pid, "SIGTERM"); } catch (_) {}
   process.exit(status);
 };
-child.stdout.on("data", (chunk) => process.stdout.write(chunk));
+child.stdout.on("data", forward);
+child.stdout.once("end", () => {
+  stdoutEnded = true;
+  finishWhenReady();
+});
 child.once("error", () => finish(127));
-child.once("exit", (code) => finish(typeof code === "number" ? code : 1));
+child.once("exit", (code) => {
+  exited = true;
+  exitStatus = typeof code === "number" ? code : 1;
+  try { process.kill(-child.pid, "SIGTERM"); } catch (_) {}
+  // Normally EOF follows child exit once the pipe has drained. A detached
+  // grandchild can keep the pipe open, so bound that wait and flush buffered
+  // bytes after a short drain window.
+  drainTimer = setTimeout(() => {
+    child.stdout.pause();
+    let chunk;
+    while ((chunk = child.stdout.read()) !== null) forward(chunk);
+    process.stdout.write("", () => {
+      flushedAfterExit = true;
+      finishWhenReady();
+    });
+  }, 250);
+  finishWhenReady();
+});
 const timer = setTimeout(() => finish(124), 2000);
 ' "$@"
 }

package/dist/commands/core-dm-bind-native.d.ts

@@ -11,6 +11,8 @@ export type DmBindDeps = {
     home: string;
     now: () => Date;
     fs: typeof fs;
+    /** Defaults to process.platform; tests pass it to exercise the Windows lookup. */
+    platform?: NodeJS.Platform;
     runHq: (args: string[], env: NodeJS.ProcessEnv) => {
         code: number;
         stdout: string;

package/dist/commands/core-dm-bind-native.js

@@ -91,12 +91,20 @@ function hasHqOnPath(d) {
     for (const directory of (d.env.PATH ?? "").split(path.delimiter)) {
         if (!directory)
             continue;
-        try {
-            const stat = d.fs.statSync(path.join(directory, "hq"));
-            if (stat.isFile() && (stat.mode & 0o111) !== 0)
-                return true;
+        // runHq spawns "hq" without a shell. On Windows that resolves only .exe and
+        // .com files, and Windows file modes carry no execute bits, so accept exactly
+        // what the spawn can launch. npm's hq.cmd shim needs a shell and is not
+        // accepted here.
+        const windows = (d.platform ?? process.platform) === "win32";
+        const names = windows ? ["hq.exe", "hq.com"] : ["hq"];
+        for (const name of names) {
+            try {
+                const stat = d.fs.statSync(path.join(directory, name));
+                if (stat.isFile() && (windows || (stat.mode & 0o111) !== 0))
+                    return true;
+            }
+            catch { /* PATH entry is absent */ }
         }
-        catch { /* PATH entry is absent */ }
     }
     return false;
 }

package/dist/commands/core-session-journal-native.d.ts

@@ -1,4 +1,7 @@
-import { type SessionHelperRuntimeOverrides } from "./core-session-helper-runtime.js";
+type SessionHelperRuntimeOverrides = {
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+};
 export type SessionJournalOperationResult = {
     code: number;
     stdout: Buffer;
@@ -8,4 +11,5 @@ export type SessionJournalOperationResult = {
 export declare function runSessionJournalOperation(args: readonly string[], _stdin: string, cwd: string, hqRoot: string | undefined, dependencies?: SessionHelperRuntimeOverrides): SessionJournalOperationResult;
 /** Native implementation of the fail-soft session journal helper. */
 export declare function runSessionJournalFast(args: readonly string[], stdin: string, cwd: string, hqRoot: string | undefined, dependencies?: SessionHelperRuntimeOverrides): number;
+export {};
 //# sourceMappingURL=core-session-journal-native.d.ts.map

package/dist/commands/core-session-journal-native.js

@@ -1,7 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { resolveSessionHelperRuntime } from "./core-session-helper-runtime.js";
-import { resolveBundledAsset } from "../utils/hq-roots-core.js";
+import { fileURLToPath } from "node:url";
 const USAGE = `session-journal.sh: usage:
   session-journal.sh write "<title>" [--files f1,f2,...] [--body-file PATH] [--session KEY]
   session-journal.sh list [--date YYYY-MM-DD]
@@ -56,6 +55,7 @@ function yamlDoubleQuoted(value) {
 }
 const warning = (message) => { process.stderr.write(`session-journal: ${message}\n`); };
 const journalDir = (root, date) => path.join(root, "workspace/threads/journal", date);
+const sessionJournalAsset = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../assets/scaffold/core/scripts/session-journal.sh");
 const hasFile = (file) => {
     try {
         return fs.statSync(file).isFile();
@@ -190,11 +190,13 @@ function runToolCounter(root, action, sessionArg, env, now, writers) {
     const counter = path.join(dir, `.tool-count-${key}`);
     const lock = `${counter}.lock`;
     const reportDirectoryWriteFailure = (error, line) => {
-        const code = error.code;
-        if (code !== "EISDIR")
+        if (error.code !== "EISDIR")
             return;
-        const asset = resolveBundledAsset("core/scripts/session-journal.sh");
-        writers.stderr(`${asset}: line ${line}: ${counter}: Is a directory\n`);
+        if (!fs.existsSync(sessionJournalAsset)) {
+            throw new Error("Bundled asset is missing from the installed package: assets/scaffold/core/scripts/session-journal.sh\n" +
+                "This is a packaging fault — the file exists in source but was not published.");
+        }
+        writers.stderr(`${sessionJournalAsset}: line ${line}: ${counter}: Is a directory\n`);
     };
     if (action === "increment") {
         withCounterLock(lock, () => {
@@ -243,7 +245,10 @@ export function runSessionJournalFast(args, stdin, cwd, hqRoot, dependencies = {
 }
 function executeSessionJournal(args, cwd, hqRoot, dependencies, writers) {
     const warning = (message) => { writers.stderr(`session-journal: ${message}\n`); };
-    const runtime = resolveSessionHelperRuntime(dependencies);
+    const runtime = {
+        env: dependencies.env ?? process.env,
+        now: dependencies.now ?? (() => new Date()),
+    };
     const today = () => runtime.now().toISOString().slice(0, 10);
     const nowIso = () => runtime.now().toISOString().replace(/\.\d{3}Z$/, "Z");
     const nowHhmm = () => runtime.now().toISOString().slice(11, 16) + "Z";

package/dist/fast-core.d.ts

@@ -14,4 +14,10 @@ export declare function readStdinIfPiped(stream: NodeJS.ReadStream): Promise<str
  * doing anything.
  */
 export declare function runFastCore(argv: readonly string[], parsed?: ReturnType<typeof parseFastCore>): Promise<void>;
+/**
+ * Resolve valid explicit roots for the two measured hook routes without loading
+ * the general root resolver. Anything uncertain falls through to that resolver,
+ * which retains its diagnostics and cwd-discovery behavior.
+ */
+export declare function resolveExplicitFastLiveRoot(hqRootArg: string | undefined, env: NodeJS.ProcessEnv): string | undefined;
 //# sourceMappingURL=fast-core.d.ts.map

package/dist/fast-core.js

@@ -6,7 +6,14 @@
  * entries use the bundled-script runner; native entries import their one handler
  * module. The registration in `core.ts` remains the complete fallback path.
  */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseFastCore } from "./fast-scaffold.js";
+const FAST_ROUTE_PROFILE_TOKEN = "hq-fast-route";
+function wantsFastRouteProfile(env) {
+    return env.NODE_DEBUG === FAST_ROUTE_PROFILE_TOKEN;
+}
 export async function readStdinIfPiped(stream) {
     if (stream.isTTY)
         return "";
@@ -23,6 +30,14 @@ export async function readStdinIfPiped(stream) {
 export async function runFastCore(argv, parsed = parseFastCore(argv)) {
     if (!parsed)
         return;
+    const profile = wantsFastRouteProfile(process.env);
+    const profileStart = profile ? process.hrtime.bigint() : undefined;
+    let familyFlagMs = 0;
+    let rootResolutionMs = 0;
+    let handlerImportMs = 0;
+    let stdinReadMs = 0;
+    const profileMark = () => profile ? process.hrtime.bigint() : undefined;
+    const profileElapsed = (start, end) => start === undefined || end === undefined ? 0 : Number(end - start) / 1_000_000;
     const entry = parsed.entry;
     // The full graph's process gate accepts textual true/false overrides. It ignores
     // numeric env values, so preserve that behavior for family flags here too.
@@ -36,6 +51,7 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
         await runCli();
         return;
     }
+    familyFlagMs = profileElapsed(profileStart, profileMark());
     const useShell = entry.kind === "native" && Boolean(entry.familyFlagKey) && !familyEnabled;
     let worktreeScopeFixEnabled;
     if (entry.name === "repo-run-registry") {
@@ -53,21 +69,32 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
     // fail-soft behavior; newly routed commands fall back to the full graph so
     // its expected-user-error formatting remains authoritative.
     let hqRoot;
+    const rootResolutionStartedAt = profileMark();
     if (shouldInjectRoot) {
-        const { resolveLiveRoot } = await import("./utils/hq-roots-core.js");
-        try {
-            hqRoot = resolveLiveRoot(parsed.hqRootArg ? { hqRoot: parsed.hqRootArg } : {});
+        const shortcutRoot = entry.name === "checkpoint-stop-gate" || entry.name === "session-journal"
+            ? resolveExplicitFastLiveRoot(parsed.hqRootArg, process.env)
+            : undefined;
+        if (shortcutRoot !== undefined) {
+            hqRoot = shortcutRoot;
         }
-        catch {
-            if (entry.kind === "native") {
-                const { runCli } = await import("./main.js");
-                await runCli();
-                return;
+        else {
+            const { resolveLiveRoot } = await import("./utils/hq-roots-core.js");
+            try {
+                hqRoot = resolveLiveRoot(parsed.hqRootArg ? { hqRoot: parsed.hqRootArg } : {});
+            }
+            catch {
+                if (entry.kind === "native") {
+                    const { runCli } = await import("./main.js");
+                    await runCli();
+                    return;
+                }
+                hqRoot = undefined;
             }
-            hqRoot = undefined;
         }
     }
+    rootResolutionMs = profileElapsed(rootResolutionStartedAt, profileMark());
     if (entry.kind === "native" && !useShell) {
+        const handlerImportStartedAt = profileMark();
         const { installFastPathStreamErrorHandlers } = await import("./utils/fast-stream-errors.js");
         installFastPathStreamErrorHandlers();
         const handlerModule = await import(entry.modulePath);
@@ -75,8 +102,21 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
         if (typeof handler !== "function") {
             throw new Error(`Native fast handler ${entry.exportName} was not exported`);
         }
+        handlerImportMs = profileElapsed(handlerImportStartedAt, profileMark());
+        const stdinStartedAt = profileMark();
         const readsStdin = entry.readsStdinFor?.(parsed.args) ?? entry.readsStdin ?? false;
         const stdin = readsStdin ? await readStdinIfPiped(process.stdin) : "";
+        stdinReadMs = profileElapsed(stdinStartedAt, profileMark());
+        if (profile && profileStart !== undefined) {
+            process.stderr.write(`HQ_FAST_ROUTE_PROFILE ${JSON.stringify({
+                command: entry.name,
+                pre_handler_ms: profileElapsed(profileStart, profileMark()),
+                family_flag_ms: familyFlagMs,
+                root_resolution_ms: rootResolutionMs,
+                handler_import_ms: handlerImportMs,
+                stdin_read_ms: stdinReadMs,
+            })}\n`);
+        }
         const code = await handler(parsed.args, stdin, process.cwd(), hqRoot, entry.name.split(" ").at(-1) ?? entry.name, parsed.hqRootArg, worktreeScopeFixEnabled);
         if (code === undefined) {
             if (!entry.fallbackToCommandGraph) {
@@ -120,6 +160,29 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
     // Propagate verbatim: these scripts use their exit code as their interface.
     process.exit(code);
 }
+/**
+ * Resolve valid explicit roots for the two measured hook routes without loading
+ * the general root resolver. Anything uncertain falls through to that resolver,
+ * which retains its diagnostics and cwd-discovery behavior.
+ */
+export function resolveExplicitFastLiveRoot(hqRootArg, env) {
+    const candidate = hqRootArg || env.HQ_ROOT || env.CLAUDE_PROJECT_DIR;
+    if (!candidate)
+        return undefined;
+    try {
+        const resolved = fs.realpathSync(candidate);
+        const packageRoot = fs.realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+        const relative = path.relative(packageRoot, resolved);
+        if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)))
+            return undefined;
+        if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory())
+            return undefined;
+        return resolved;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Match hq-flags-client's literal true/false env override without loading its module. */
 function localBooleanFlagOverride(flagKey, env) {
     const envKey = `HQ_FLAG_${flagKey.replace(/[.-]/g, "_").toUpperCase()}`;

package/docs/anywhere-runtime.md

@@ -0,0 +1,60 @@
+# HQ Anywhere runtime
+
+HQ Anywhere installs global hooks for supported agent runtimes and uses the
+local hqd daemon on macOS and Linux. Windows does not currently start hqd, so
+the daemon-backed routing described here is unavailable there. A per-user
+registry links repositories to HQ companies. The `hq-anywhere-runtime` flag
+controls these features and is off by default.
+
+## Install
+
+Install and start hqd before registering global hooks. The global installer
+checks for the daemon service when choosing the hook target.
+
+```sh
+hq daemon install
+hq daemon status
+hq install --global --runtime claude
+```
+
+`hq install --global` defaults to Claude. Select other supported runtimes
+explicitly with `--runtime codex`, `--runtime chatgpt`, or `--runtime grok`.
+Claude and Codex receive local hook configuration. ChatGPT and Grok print
+connector setup instructions and require the runtime flag to be enabled.
+
+The CLI stores the HQ root at `~/.hq/root` and keeps the folder registry in
+`~/.hq/registry.json`. These files belong to the current host. They are not
+stored in a repository or synced HQ folder.
+
+On Windows, `hq daemon install` reports that hqd cannot start because its
+named-pipe ACL is not supported. Global hook installation may still configure
+local runtime hooks, but it does not provide the hqd routing described below.
+
+When the flag is enabled, the global hook uses hqd for events outside the HQ
+root. Inside the root, the project hook routes through hqd when it is running
+and uses the direct master hook when it is stopped.
+
+## Link a repository
+
+Run `hq link <company>` from a repository to associate it with a company. The
+registry uses the normalized Git remote when one is available. Otherwise, it
+uses the repository's canonical absolute path.
+
+`HQ_REGISTRY_DIR` changes the registry directory, and `HQ_HQD_SOCKET` changes
+the daemon socket path. The managed service does not inherit overrides from
+the shell that ran `hq daemon install`; it persists `PATH` and
+`HQ_DAEMON_DIR`. Keep the defaults for a managed install unless you configure
+both the daemon service and the agent runtime with the same overrides. For a
+systemd user service, add `Environment=HQ_REGISTRY_DIR=...` and
+`Environment=HQ_HQD_SOCKET=...` in `systemctl --user edit hq-daemon.service`,
+then run `systemctl --user daemon-reload` and
+`systemctl --user restart hq-daemon.service`. For launchd, set both keys in the
+`EnvironmentVariables` dictionary in
+`~/Library/LaunchAgents/ai.getindigo.hq-daemon.plist`, then restart the job
+with `launchctl kickstart -k gui/$(id -u)/ai.getindigo.hq-daemon`. Also set
+both variables in the agent runtime environment so hooks and `hq link` use
+the same paths.
+
+The registry does not infer a company when a repository has no matching entry.
+That session uses personal context. The socket protocol and registry format are
+documented in the HQ Anywhere runtime knowledge entry in hq-core.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.338.0",
+  "version": "5.340.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -16,6 +16,7 @@
     "assets/lanes-reconcile",
     "assets/lanes-hooks",
     "templates",
+    "docs/anywhere-runtime.md",
     "CHANGELOG.md",
     "README.md",
     "contracts",