@indigoai-us/hq-cli 5.152.0 → 5.152.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.152.1] — 2026-09-23
+
+### Fixed
+
+- Windows bot runtimes resolve provider binaries through PATH and PATHEXT, safely launch npm .cmd and .bat shims, pass multiline and long prompts through stdin or Grok ACP, and stop the full process tree.
+
 ## [5.152.0] — 2026-09-23
 
 ### Fixed

package/dist/lib/bot/runtime/claude.d.ts

@@ -44,6 +44,6 @@ export declare function onPath(name: string, env: NodeJS.ProcessEnv): boolean;
  * skipped), matching the HQ desktop app's own lookup.
  */
 export declare function bundledClaudeBin(homeDir?: string): string | null;
-export declare function resolveClaudeBinary(env: NodeJS.ProcessEnv, homeDir?: string): string;
+export declare function resolveClaudeBinary(env: NodeJS.ProcessEnv, homeDir?: string, platform?: NodeJS.Platform, cwd?: string): string;
 export declare function createClaudeRuntime(env?: NodeJS.ProcessEnv): BotRuntime;
 //# sourceMappingURL=claude.d.ts.map

package/dist/lib/bot/runtime/claude.js

@@ -18,6 +18,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { messagesStreamEvents, messagesStreamFailure, messagesStreamResult } from "./messages-stream.js";
+import { resolveRuntimeBinary } from "./windows.js";
 export const CLAUDE_PERMISSION_MODE_ENV = "HQ_BOT_CLAUDE_PERMISSION_MODE";
 export const DEFAULT_CLAUDE_PERMISSION_MODE = "bypassPermissions";
 export const GATED_CLAUDE_PERMISSION_MODE = "acceptEdits";
@@ -102,7 +103,9 @@ export function bundledClaudeBin(homeDir = os.homedir()) {
     });
     return candidates.at(-1)?.bin ?? null;
 }
-export function resolveClaudeBinary(env, homeDir) {
+export function resolveClaudeBinary(env, homeDir, platform = process.platform, cwd = process.cwd()) {
+    if (platform === "win32")
+        return resolveRuntimeBinary("claude", env, platform, fs.existsSync, cwd);
     if (onPath("claude", env))
         return "claude";
     return bundledClaudeBin(homeDir ?? env.HOME ?? os.homedir()) ?? "claude";
@@ -111,13 +114,15 @@ export function createClaudeRuntime(env = process.env) {
     return {
         id: "claude",
         binary: "claude",
-        resolveBinary: (turnEnv) => resolveClaudeBinary(turnEnv),
+        resolveBinary: (turnEnv, cwd, platform) => resolveClaudeBinary(turnEnv, undefined, platform ?? process.platform, cwd),
         buildArgs(input, scratch) {
+            const usesWindowsStdin = input.platform === "win32";
             const args = [
                 "-p",
-                input.prompt,
+                ...(usesWindowsStdin ? [] : [input.prompt]),
                 "--output-format",
                 "stream-json",
+                ...(usesWindowsStdin ? ["--input-format", "stream-json"] : []),
                 "--verbose",
                 "--permission-mode",
                 claudePermissionMode(env, input.autoApprove !== false, input.permissionMode),
@@ -137,6 +142,14 @@ export function createClaudeRuntime(env = process.env) {
                 args.push("--session-id", scratch.newSessionId);
             return args;
         },
+        stdinInput(input) {
+            return input.platform === "win32"
+                ? JSON.stringify({
+                    type: "user",
+                    message: { role: "user", content: [{ type: "text", text: input.prompt }] },
+                }) + "\n"
+                : undefined;
+        },
         parseOutput(stdout) {
             return messagesStreamResult(stdout, "claude");
         },

package/dist/lib/bot/runtime/codex.js

@@ -14,6 +14,7 @@
  * cannot run under this machine's account).
  */
 import { parseJsonLine, RuntimeError } from "./types.js";
+import { resolveRuntimeBinary } from "./windows.js";
 /** Progress events in one codex JSONL line: finished agent messages and tool starts. */
 export function codexStreamEvents(line) {
     const ev = parseJsonLine(line);
@@ -82,7 +83,9 @@ export function createCodexRuntime() {
     return {
         id: "codex",
         binary: "codex",
+        resolveBinary: (env, cwd, platform) => resolveRuntimeBinary("codex", env, platform ?? process.platform, undefined, cwd),
         buildArgs(input, scratch) {
+            const promptArg = input.platform === "win32" ? "-" : codexPrompt(input);
             const common = ["--json", "--skip-git-repo-check", "-o", scratch.outputFile];
             if (input.autoApprove !== false) {
                 // Headless: nobody can answer an approval prompt, so a gated command
@@ -96,9 +99,12 @@ export function createCodexRuntime() {
                 common.push("-m", input.model);
             common.push("-c", `model_reasoning_effort=${JSON.stringify(input.effort?.trim() || "medium")}`);
             if (input.sessionId) {
-                return ["exec", "resume", ...common, input.sessionId, codexPrompt(input)];
+                return ["exec", "resume", ...common, input.sessionId, promptArg];
             }
-            return ["exec", ...common, "-C", input.cwd, codexPrompt(input)];
+            return ["exec", ...common, "-C", input.cwd, promptArg];
+        },
+        stdinInput(input) {
+            return input.platform === "win32" ? codexPrompt(input) : undefined;
         },
         parseOutput(stdout, extra) {
             let sessionId;

package/dist/lib/bot/runtime/grok-acp.d.ts

@@ -0,0 +1,40 @@
+export interface GrokAcpClientOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    prompt: string;
+    sessionId?: string;
+    send: (message: Record<string, unknown>) => void;
+    onText: (line: string) => void;
+    onComplete: (sessionId: string, text: string) => void;
+    onFailure: (message: string) => void;
+}
+/** A minimal ACP client for Grok's documented stdio runtime. */
+export declare class GrokAcpClient {
+    private readonly options;
+    private nextId;
+    private readonly pending;
+    private readonly terminals;
+    private sessionId;
+    private text;
+    private finished;
+    constructor(options: GrokAcpClientOptions);
+    start(): void;
+    receive(line: string): void;
+    private request;
+    private notify;
+    private authenticate;
+    private openSession;
+    private prompt;
+    private receiveUpdate;
+    private complete;
+    private fail;
+    private receiveRequest;
+    private handleClientRequest;
+    private createTerminal;
+    private getTerminal;
+    private terminalOutput;
+    private waitForTerminal;
+    private killTerminal;
+    private releaseTerminal;
+}
+//# sourceMappingURL=grok-acp.d.ts.map

package/dist/lib/bot/runtime/grok-acp.js

@@ -0,0 +1,265 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { planBotRuntimeSpawn } from "./windows.js";
+/** A minimal ACP client for Grok's documented stdio runtime. */
+export class GrokAcpClient {
+    options;
+    nextId = 1;
+    pending = new Map();
+    terminals = new Map();
+    sessionId;
+    text = "";
+    finished = false;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        this.request("initialize", {
+            protocolVersion: 1,
+            clientCapabilities: { terminal: true },
+        }, (result) => this.authenticate(result));
+    }
+    receive(line) {
+        let message;
+        try {
+            const parsed = JSON.parse(line);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return;
+            message = parsed;
+        }
+        catch {
+            return;
+        }
+        if (message.method === "session/update") {
+            this.receiveUpdate(message);
+            return;
+        }
+        if (typeof message.method === "string" && (typeof message.id === "number" || typeof message.id === "string")) {
+            void this.receiveRequest(message);
+            return;
+        }
+        if (typeof message.id !== "number" && typeof message.id !== "string")
+            return;
+        const resolve = this.pending.get(message.id);
+        if (!resolve)
+            return;
+        this.pending.delete(message.id);
+        if (message.error && typeof message.error === "object") {
+            const error = message.error;
+            this.fail(typeof error.message === "string" ? error.message : "Grok ACP request failed");
+            return;
+        }
+        const result = message.result && typeof message.result === "object" ? message.result : {};
+        resolve(result);
+    }
+    request(method, params, complete) {
+        if (this.finished)
+            return;
+        const id = this.nextId++;
+        this.pending.set(id, complete);
+        this.options.send({ jsonrpc: "2.0", id, method, params });
+    }
+    notify(method, params = {}) {
+        this.options.send({ jsonrpc: "2.0", method, params });
+    }
+    authenticate(result) {
+        const methods = Array.isArray(result.authMethods) ? result.authMethods : [];
+        const authMethods = new Set(methods.flatMap((method) => method && typeof method === "object" && typeof method.id === "string"
+            ? [String(method.id)]
+            : []));
+        const apiKey = Object.entries(this.options.env).some(([key, value]) => key.toUpperCase() === "XAI_API_KEY" && Boolean(value?.trim()));
+        const methodId = apiKey && authMethods.has("xai.api_key") ? "xai.api_key" : authMethods.has("cached_token") ? "cached_token" : null;
+        if (!methodId) {
+            this.fail("Grok has no cached login; run `grok login` or configure XAI_API_KEY before starting the bot.");
+            return;
+        }
+        this.request("authenticate", { methodId, _meta: { headless: true } }, () => this.openSession());
+    }
+    openSession() {
+        if (this.options.sessionId) {
+            this.request("session/load", { sessionId: this.options.sessionId, cwd: this.options.cwd, mcpServers: [], _meta: { yoloMode: true } }, (result) => this.prompt(result));
+            return;
+        }
+        this.request("session/new", { cwd: this.options.cwd, mcpServers: [], _meta: { yoloMode: true } }, (result) => this.prompt(result));
+    }
+    prompt(result) {
+        if (typeof result.sessionId !== "string" || !result.sessionId) {
+            this.fail("Grok ACP did not return a session ID");
+            return;
+        }
+        this.sessionId = result.sessionId;
+        this.request("session/prompt", { sessionId: this.sessionId, prompt: [{ type: "text", text: this.options.prompt }] }, (response) => this.complete(response));
+    }
+    receiveUpdate(message) {
+        const params = message.params && typeof message.params === "object" ? message.params : {};
+        const update = params.update && typeof params.update === "object" ? params.update : {};
+        const content = update.content && typeof update.content === "object" ? update.content : {};
+        if (update.sessionUpdate !== "agent_message_chunk" || typeof content.text !== "string")
+            return;
+        this.text += content.text;
+        this.options.onText(JSON.stringify({
+            type: "assistant",
+            message: { role: "assistant", content: [{ type: "text", text: content.text }] },
+            parent_tool_use_id: null,
+            session_id: this.sessionId,
+        }));
+    }
+    complete(response) {
+        if (!this.sessionId) {
+            this.fail("Grok ACP completed without a session ID");
+            return;
+        }
+        if (typeof response.stopReason === "string" && response.stopReason.toLowerCase() === "cancelled") {
+            this.fail("Grok ACP cancelled the bot turn");
+            return;
+        }
+        this.finished = true;
+        this.notify("exit");
+        this.options.onComplete(this.sessionId, this.text);
+    }
+    fail(message) {
+        if (this.finished)
+            return;
+        this.finished = true;
+        this.pending.clear();
+        this.options.onFailure(message);
+    }
+    async receiveRequest(message) {
+        const method = message.method;
+        const params = message.params && typeof message.params === "object" ? message.params : {};
+        try {
+            const result = await this.handleClientRequest(method, params);
+            this.options.send({ jsonrpc: "2.0", id: message.id, result });
+        }
+        catch (err) {
+            this.options.send({
+                jsonrpc: "2.0",
+                id: message.id,
+                error: { code: -32000, message: err instanceof Error ? err.message : String(err) },
+            });
+        }
+    }
+    async handleClientRequest(method, params) {
+        const shortMethod = method.startsWith("x.ai/") ? method.slice("x.ai/".length) : method;
+        if (shortMethod === "session/request_permission") {
+            const options = Array.isArray(params.options) ? params.options : [];
+            const allow = options.find((option) => {
+                if (!option || typeof option !== "object")
+                    return false;
+                const candidate = option;
+                return typeof candidate.optionId === "string" && /allow|approve/i.test(String(candidate.kind ?? candidate.name ?? ""));
+            });
+            if (!allow || typeof allow.optionId !== "string")
+                return { outcome: "cancelled" };
+            return { outcome: "selected", optionId: allow.optionId };
+        }
+        if (shortMethod === "terminal/create")
+            return this.createTerminal(params);
+        if (shortMethod === "terminal/output")
+            return this.terminalOutput(params);
+        if (shortMethod === "terminal/wait_for_exit")
+            return this.waitForTerminal(params);
+        if (shortMethod === "terminal/kill")
+            return this.killTerminal(params);
+        if (shortMethod === "terminal/release")
+            return this.releaseTerminal(params);
+        throw new Error(`Unsupported Grok ACP client request: ${method}`);
+    }
+    createTerminal(params) {
+        if (typeof params.command !== "string" || !params.command)
+            throw new Error("Grok ACP terminal request has no command");
+        const args = Array.isArray(params.args) ? params.args.filter((arg) => typeof arg === "string") : [];
+        const env = { ...this.options.env };
+        if (Array.isArray(params.env)) {
+            for (const entry of params.env) {
+                if (!entry || typeof entry !== "object")
+                    continue;
+                const item = entry;
+                const name = item.name;
+                const value = item.value;
+                if (typeof name === "string" && typeof value === "string") {
+                    const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name.toUpperCase()) ?? name;
+                    env[key] = value;
+                }
+            }
+        }
+        const commandPlan = planBotRuntimeSpawn(params.command, args, env);
+        const child = spawn(commandPlan.cmd, commandPlan.args, {
+            cwd: typeof params.cwd === "string" ? params.cwd : this.options.cwd,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+            ...(commandPlan.shell ? { shell: commandPlan.shell } : {}),
+            ...(commandPlan.windowsVerbatimArguments !== undefined
+                ? { windowsVerbatimArguments: commandPlan.windowsVerbatimArguments }
+                : {}),
+            windowsHide: true,
+        });
+        let resolveExit;
+        const exited = new Promise((resolve) => {
+            resolveExit = resolve;
+        });
+        const handle = { child, output: "", truncated: false, exitCode: null, exited };
+        const append = (chunk) => {
+            const max = 1_000_000;
+            handle.output += chunk.toString();
+            if (Buffer.byteLength(handle.output) > max) {
+                const bytes = Buffer.from(handle.output);
+                handle.output = bytes.subarray(bytes.length - max).toString();
+                handle.truncated = true;
+            }
+        };
+        child.stdout?.on("data", append);
+        child.stderr?.on("data", append);
+        child.once("error", (err) => {
+            handle.output += `\n[hq bot] terminal command failed to start: ${err.message}`;
+            handle.exitCode = 1;
+            resolveExit(1);
+        });
+        child.once("close", (code) => {
+            handle.exitCode = code;
+            resolveExit(code);
+        });
+        const terminalId = randomUUID();
+        this.terminals.set(terminalId, handle);
+        return { terminalId };
+    }
+    getTerminal(params) {
+        if (typeof params.terminalId !== "string")
+            throw new Error("Grok ACP terminal request has no terminalId");
+        const terminal = this.terminals.get(params.terminalId);
+        if (!terminal)
+            throw new Error("Grok ACP requested an unknown terminal");
+        return terminal;
+    }
+    terminalOutput(params) {
+        const terminal = this.getTerminal(params);
+        const limit = typeof params.outputByteLimit === "number" && params.outputByteLimit > 0 ? params.outputByteLimit : 65_536;
+        const bytes = Buffer.from(terminal.output);
+        const output = bytes.length > limit ? bytes.subarray(bytes.length - limit).toString() : terminal.output;
+        return {
+            output,
+            exitStatus: terminal.exitCode === null ? null : { exitCode: terminal.exitCode },
+            truncated: terminal.truncated || bytes.length > limit,
+        };
+    }
+    async waitForTerminal(params) {
+        const terminal = this.getTerminal(params);
+        const exitCode = terminal.exitCode ?? (await terminal.exited);
+        return { exitCode };
+    }
+    killTerminal(params) {
+        const terminal = this.getTerminal(params);
+        if (terminal.child.exitCode === null && terminal.child.signalCode === null)
+            terminal.child.kill();
+        return {};
+    }
+    releaseTerminal(params) {
+        const terminal = this.getTerminal(params);
+        if (terminal.child.exitCode === null && terminal.child.signalCode === null) {
+            throw new Error("Grok ACP cannot release a terminal command that is still running");
+        }
+        this.terminals.delete(String(params.terminalId));
+        return {};
+    }
+}
+//# sourceMappingURL=grok-acp.js.map

package/dist/lib/bot/runtime/grok.d.ts

@@ -20,11 +20,13 @@
  * still accepted.
  */
 import { type BotRuntime, type RuntimeTurnInput } from "./types.js";
+import type { SpawnPlan } from "../../../utils/windows-spawn.js";
 export declare const GROK_OUTPUT_FORMAT_LEGACY = "streaming-messages-json";
 export declare const GROK_OUTPUT_FORMAT_STREAMING_JSON = "streaming-json";
 export declare function resetGrokOutputFormatCache(): void;
 /** Pick the streaming `--output-format` grok's `--help` says it accepts. */
 export declare function grokOutputFormatFromHelp(helpText: string): string;
+export declare function grokHelpSpawnPlan(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, existsSync?: (candidate: string) => boolean): SpawnPlan;
 /** Probe `grok --help` once and cache the streaming format. */
 export declare function probeGrokOutputFormat(readHelp?: () => string): string;
 /**

package/dist/lib/bot/runtime/grok.js

@@ -22,6 +22,7 @@
 import { execFileSync } from "node:child_process";
 import { messagesStreamEvents, messagesStreamFailure, messagesStreamResult } from "./messages-stream.js";
 import { parseJsonLine, RuntimeError } from "./types.js";
+import { planBotRuntimeSpawn, resolveRuntimeBinary } from "./windows.js";
 export const GROK_OUTPUT_FORMAT_LEGACY = "streaming-messages-json";
 export const GROK_OUTPUT_FORMAT_STREAMING_JSON = "streaming-json";
 let cachedOutputFormat;
@@ -45,12 +46,21 @@ export function grokOutputFormatFromHelp(helpText) {
         return GROK_OUTPUT_FORMAT_STREAMING_JSON;
     return GROK_OUTPUT_FORMAT_LEGACY;
 }
+export function grokHelpSpawnPlan(env = process.env, platform = process.platform, existsSync) {
+    const command = resolveRuntimeBinary("grok", env, platform, existsSync);
+    return planBotRuntimeSpawn(command, ["--help"], env, platform);
+}
 function defaultGrokHelp() {
+    const plan = grokHelpSpawnPlan();
     try {
-        return execFileSync("grok", ["--help"], {
+        return execFileSync(plan.cmd, plan.args, {
             encoding: "utf8",
             timeout: 5_000,
             stdio: ["ignore", "pipe", "pipe"],
+            ...(plan.shell ? { shell: plan.shell } : {}),
+            ...(plan.windowsVerbatimArguments !== undefined
+                ? { windowsVerbatimArguments: plan.windowsVerbatimArguments }
+                : {}),
         });
     }
     catch (err) {
@@ -99,7 +109,16 @@ export function createGrokRuntime(opts = {}) {
     return {
         id: "grok",
         binary: "grok",
+        resolveBinary: (env, cwd, platform) => resolveRuntimeBinary("grok", env, platform ?? process.platform, undefined, cwd),
         buildArgs(input) {
+            if (input.platform === "win32") {
+                const args = ["--no-auto-update", "agent", "--always-approve", "--no-subagents"];
+                if (input.model)
+                    args.push("--model", input.model);
+                args.push("--effort", input.effort?.trim() || "medium");
+                args.push("stdio");
+                return args;
+            }
             const args = [
                 "-p",
                 grokPrompt(input),
@@ -117,6 +136,11 @@ export function createGrokRuntime(opts = {}) {
                 args.push("-r", input.sessionId);
             return args;
         },
+        spawnProtocol(input) {
+            return input.platform === "win32"
+                ? { kind: "grok-acp", prompt: grokPrompt(input), ...(input.sessionId ? { sessionId: input.sessionId } : {}) }
+                : undefined;
+        },
         parseOutput(stdout) {
             // Older grok: one `{ text, sessionId }` object.
             const legacy = stdout

package/dist/lib/bot/runtime/index.d.ts

@@ -26,6 +26,7 @@ export interface RunTurnDeps {
     timeoutMs?: number;
     scratchDir?: string;
     newSessionId?: () => string;
+    platform?: NodeJS.Platform;
 }
 /**
  * Run one turn: spawn the runtime CLI, parse the reply, clean up scratch.

package/dist/lib/bot/runtime/index.js

@@ -3,6 +3,8 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { planBotRuntimeSpawn } from "./windows.js";
+import { GrokAcpClient } from "./grok-acp.js";
 import { createClaudeRuntime } from "./claude.js";
 import { createCodexRuntime } from "./codex.js";
 import { createGrokRuntime, grokRetryArgsAfterInvalidOutputFormat, probeGrokOutputFormat } from "./grok.js";
@@ -72,12 +74,19 @@ export const defaultSpawn = (command, args, options) => new Promise((resolve, re
     let stderr = "";
     let partial = "";
     let settled = false;
-    const child = spawn(command, args, {
+    const plan = planBotRuntimeSpawn(command, args, options.env);
+    const child = spawn(plan.cmd, plan.args, {
         cwd: options.cwd,
         env: options.env,
-        stdio: ["ignore", "pipe", "pipe"],
+        stdio: [options.stdin !== undefined || options.protocol ? "pipe" : "ignore", "pipe", "pipe"],
+        ...(plan.shell ? { shell: plan.shell } : {}),
+        ...(plan.windowsVerbatimArguments !== undefined
+            ? { windowsVerbatimArguments: plan.windowsVerbatimArguments }
+            : {}),
+        windowsHide: true,
     });
     let stopping = false;
+    let protocolComplete = false;
     const signalTree = (sig, pids) => {
         for (const p of pids) {
             try {
@@ -90,6 +99,55 @@ export const defaultSpawn = (command, args, options) => new Promise((resolve, re
     };
     const kill = () => {
         stopping = true;
+        if (process.platform === "win32" && child.pid !== undefined) {
+            const rootKey = Object.keys(options.env).find((key) => key.toUpperCase() === "SYSTEMROOT");
+            const systemRoot = rootKey ? options.env[rootKey] : undefined;
+            const taskkill = path.win32.join(systemRoot || "C:\\Windows", "System32", "taskkill.exe");
+            let finished = false;
+            const fallbackKill = (reason) => {
+                if (finished)
+                    return;
+                finished = true;
+                stderr += `\n[hq bot] could not stop the Windows process tree with taskkill.exe: ${reason}`;
+                try {
+                    child.kill();
+                }
+                catch (err) {
+                    stderr += `\n[hq bot] could not stop the runtime wrapper: ${err instanceof Error ? err.message : String(err)}`;
+                }
+            };
+            let killer;
+            try {
+                killer = spawn(taskkill, ["/PID", String(child.pid), "/T", "/F"], {
+                    env: options.env,
+                    stdio: "ignore",
+                    windowsHide: true,
+                });
+            }
+            catch (err) {
+                fallbackKill(err instanceof Error ? err.message : String(err));
+                return;
+            }
+            const fallbackTimer = setTimeout(() => fallbackKill("taskkill.exe did not finish within 5 seconds"), 5_000);
+            killer.once("error", (err) => {
+                clearTimeout(fallbackTimer);
+                fallbackKill(err.message);
+            });
+            killer.once("close", (code) => {
+                clearTimeout(fallbackTimer);
+                finished = true;
+                if (code !== 0 && child.exitCode === null && child.signalCode === null) {
+                    stderr += `\n[hq bot] taskkill.exe exited with code ${code} while stopping the runtime process tree`;
+                    try {
+                        child.kill();
+                    }
+                    catch (err) {
+                        stderr += `\n[hq bot] could not stop the runtime wrapper: ${err instanceof Error ? err.message : String(err)}`;
+                    }
+                }
+            });
+            return;
+        }
         // Snapshot the tree before the parent dies (its children get re-parented).
         const tree = process.platform === "win32" || child.pid === undefined ? [] : descendantPids(child.pid);
         try {
@@ -139,13 +197,63 @@ export const defaultSpawn = (command, args, options) => new Promise((resolve, re
             /* a listener must never break the turn */
         }
     };
+    const emitProtocolLine = (line) => {
+        stdout += line + "\n";
+        emit(line);
+    };
     const cleanup = () => {
         if (timer)
             clearTimeout(timer);
         options.signal?.removeEventListener("abort", onAbort);
     };
+    let protocolPartial = "";
+    const protocol = options.protocol?.kind === "grok-acp"
+        ? new GrokAcpClient({
+            cwd: options.cwd,
+            env: options.env,
+            prompt: options.protocol.prompt,
+            ...(options.protocol.sessionId ? { sessionId: options.protocol.sessionId } : {}),
+            send: (message) => {
+                try {
+                    child.stdin?.write(JSON.stringify(message) + "\n");
+                }
+                catch (err) {
+                    stderr += `\n[hq bot] could not write to the Grok ACP process: ${err instanceof Error ? err.message : String(err)}`;
+                }
+            },
+            onText: emitProtocolLine,
+            onComplete: (sessionId, text) => {
+                protocolComplete = true;
+                emitProtocolLine(JSON.stringify({ type: "result", subtype: "success", is_error: false, result: text, session_id: sessionId }));
+                child.stdin?.end();
+                setTimeout(() => {
+                    if (!settled && child.exitCode === null && child.signalCode === null)
+                        kill();
+                }, STOP_SETTLE_GRACE_MS).unref?.();
+            },
+            onFailure: (message) => {
+                stderr += `\n[hq bot] ${message}`;
+                stopping = true;
+                child.stdin?.end();
+                setTimeout(() => {
+                    if (!settled && child.exitCode === null && child.signalCode === null)
+                        kill();
+                }, STOP_SETTLE_GRACE_MS).unref?.();
+            },
+        })
+        : undefined;
     child.stdout?.on("data", (d) => {
         const chunk = d.toString();
+        if (protocol) {
+            protocolPartial += chunk;
+            let nl = protocolPartial.indexOf("\n");
+            while (nl >= 0) {
+                protocol.receive(protocolPartial.slice(0, nl).replace(/\r$/, ""));
+                protocolPartial = protocolPartial.slice(nl + 1);
+                nl = protocolPartial.indexOf("\n");
+            }
+            return;
+        }
         stdout += chunk;
         if (!options.onStdoutLine)
             return;
@@ -160,6 +268,10 @@ export const defaultSpawn = (command, args, options) => new Promise((resolve, re
     child.stderr?.on("data", (d) => {
         stderr += d.toString();
     });
+    child.stdin?.on("error", (err) => {
+        if (!settled)
+            stderr += `\n[hq bot] could not write input to ${command}: ${err.message}`;
+    });
     child.on("error", (err) => {
         if (settled)
             return;
@@ -167,6 +279,10 @@ export const defaultSpawn = (command, args, options) => new Promise((resolve, re
         cleanup();
         reject(err);
     });
+    if (protocol && !options.signal?.aborted)
+        protocol.start();
+    else if (options.stdin !== undefined)
+        child.stdin?.end(options.stdin);
     // A stopped process can exit while something it started (and we could not
     // reach) still holds stdout open; settle shortly after the exit instead of
     // waiting for that pipe.
@@ -192,7 +308,12 @@ export const defaultSpawn = (command, args, options) => new Promise((resolve, re
         cleanup();
         if (partial)
             emit(partial);
-        resolve({ code, signal, stdout, stderr });
+        resolve({
+            code: protocol ? (protocolComplete ? 0 : 1) : code,
+            signal: protocolComplete ? null : signal,
+            stdout,
+            stderr,
+        });
     });
 });
 /**
@@ -204,9 +325,12 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
     const scratchDir = deps.scratchDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "hq-bot-turn-"));
     const outputFile = path.join(scratchDir, "last-message.txt");
     const newSessionId = input.newSessionId ?? (deps.newSessionId ?? randomUUID)();
-    const args = runtime.buildArgs(input, { outputFile, newSessionId });
+    const turnInput = { ...input, platform: deps.platform ?? input.platform ?? process.platform };
+    const args = runtime.buildArgs(turnInput, { outputFile, newSessionId });
     const env = input.env ?? deps.env ?? process.env;
-    const binary = runtime.resolveBinary?.(env) ?? runtime.binary;
+    const binary = runtime.resolveBinary?.(env, input.cwd, turnInput.platform) ?? runtime.binary;
+    const stdin = runtime.stdinInput?.(turnInput);
+    const protocol = runtime.spawnProtocol?.(turnInput);
     const onEvent = input.onEvent;
     const onStdoutLine = onEvent && runtime.parseStreamLine
         ? (line) => {
@@ -224,6 +348,8 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
     const spawnOptions = {
         cwd: input.cwd,
         env,
+        ...(stdin !== undefined ? { stdin } : {}),
+        ...(protocol ? { protocol } : {}),
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         ...(onStdoutLine ? { onStdoutLine } : {}),
         ...(input.signal ? { signal: input.signal } : {}),

package/dist/lib/bot/runtime/types.d.ts

@@ -42,6 +42,8 @@ export interface RuntimeTurnInput {
     onEvent?: (event: RuntimeStreamEvent) => void;
     /** Aborting kills the runtime process (owner stop); the turn then fails with `aborted`. */
     signal?: AbortSignal;
+    /** Runtime host platform; set by runRuntimeTurn and injectable for platform tests. */
+    platform?: NodeJS.Platform;
 }
 /**
  * What a runtime's streaming output means to the bot, per stdout line:
@@ -76,7 +78,16 @@ export interface SpawnOptions {
     onStdoutLine?: (line: string) => void;
     /** Kill the process when aborted. */
     signal?: AbortSignal;
+    /** Optional full input stream for CLIs that accept prompts through stdin. */
+    stdin?: string;
+    /** Optional interactive protocol implemented over the child stdin/stdout streams. */
+    protocol?: SpawnProtocol;
 }
+export type SpawnProtocol = {
+    kind: "grok-acp";
+    prompt: string;
+    sessionId?: string;
+};
 export interface SpawnLike {
     (command: string, args: string[], options: SpawnOptions): Promise<SpawnResult>;
 }
@@ -101,7 +112,11 @@ export interface BotRuntime {
      * PATH (e.g. Claude Code that only exists inside the Claude desktop app).
      * Resolved per turn so an app update that swaps the version folder is picked up.
      */
-    resolveBinary?(env: NodeJS.ProcessEnv): string;
+    resolveBinary?(env: NodeJS.ProcessEnv, cwd?: string, platform?: NodeJS.Platform): string;
+    /** Optional full prompt stream sent through stdin instead of argv. */
+    stdinInput?(input: RuntimeTurnInput): string | undefined;
+    /** Optional bidirectional process protocol for this runtime. */
+    spawnProtocol?(input: RuntimeTurnInput): SpawnProtocol | undefined;
     /** Build the argv for one turn. Pure. */
     buildArgs(input: RuntimeTurnInput, scratch: {
         outputFile: string;

package/dist/lib/bot/runtime/windows.d.ts

@@ -0,0 +1,10 @@
+import { type SpawnPlan } from "../../../utils/windows-spawn.js";
+type ExistsSync = (candidate: string) => boolean;
+/** Resolve an npm-installed provider command using Windows PATH and PATHEXT. */
+export declare function resolveWindowsExecutable(name: string, env: NodeJS.ProcessEnv, existsSync?: ExistsSync, cwd?: string): string | null;
+/** Preserve non-Windows lookup. Windows returns the first PATH/PATHEXT match. */
+export declare function resolveRuntimeBinary(name: string, env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, existsSync?: ExistsSync, cwd?: string): string;
+/** Directly spawn native files; pass only batch shims through cmd.exe. */
+export declare function planBotRuntimeSpawn(command: string, args: readonly string[], env: NodeJS.ProcessEnv, platform?: NodeJS.Platform): SpawnPlan;
+export {};
+//# sourceMappingURL=windows.d.ts.map

package/dist/lib/bot/runtime/windows.js

@@ -0,0 +1,53 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildCmdExeSpawnPlan, isWindowsBatchFile, } from "../../../utils/windows-spawn.js";
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+const SUPPORTED_PATHEXT = new Set([".com", ".exe", ".cmd", ".bat"]);
+function envValue(env, name) {
+    const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name);
+    return key ? env[key] : undefined;
+}
+/** Resolve an npm-installed provider command using Windows PATH and PATHEXT. */
+export function resolveWindowsExecutable(name, env, existsSync = fs.existsSync, cwd = process.cwd()) {
+    const pathValue = envValue(env, "PATH") ?? "";
+    const rawExtensions = (envValue(env, "PATHEXT") || DEFAULT_PATHEXT)
+        .split(";")
+        .map((extension) => {
+        const trimmed = extension.trim();
+        if (!trimmed)
+            return "";
+        return (trimmed.startsWith(".") ? trimmed : "." + trimmed).toLowerCase();
+    });
+    const extensions = [...new Set(rawExtensions.filter((extension) => SUPPORTED_PATHEXT.has(extension)))];
+    if (extensions.includes(".exe")) {
+        extensions.splice(extensions.indexOf(".exe"), 1);
+        extensions.unshift(".exe");
+    }
+    const searchExtensions = path.win32.extname(name) ? [""] : extensions;
+    for (const rawDir of pathValue.split(";")) {
+        const dir = rawDir.trim().replace(/^"(.*)"$/, "$1");
+        if (!dir)
+            continue;
+        const absoluteDir = path.win32.resolve(cwd, dir);
+        for (const extension of searchExtensions) {
+            const candidate = path.win32.join(absoluteDir, name + extension);
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** Preserve non-Windows lookup. Windows returns the first PATH/PATHEXT match. */
+export function resolveRuntimeBinary(name, env, platform = process.platform, existsSync = fs.existsSync, cwd = process.cwd()) {
+    if (platform !== "win32")
+        return name;
+    return resolveWindowsExecutable(name, env, existsSync, cwd) ?? name;
+}
+/** Directly spawn native files; pass only batch shims through cmd.exe. */
+export function planBotRuntimeSpawn(command, args, env, platform = process.platform) {
+    if (isWindowsBatchFile(command, platform)) {
+        return buildCmdExeSpawnPlan(command, args, env, platform);
+    }
+    return { cmd: command, args: [...args], shell: false };
+}
+//# sourceMappingURL=windows.js.map

package/dist/utils/windows-spawn.d.ts

@@ -2,7 +2,13 @@ export type SpawnPlan = {
     cmd: string;
     args: string[];
     shell: boolean;
+    windowsVerbatimArguments?: boolean;
 };
+/**
+ * Explicit cmd.exe plan for a resolved .cmd/.bat target. Keeping cmd.exe's
+ * argv construction here makes the shell boundary testable without Windows.
+ */
+export declare function buildCmdExeSpawnPlan(command: string, args: readonly string[], env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): SpawnPlan;
 /**
  * Quote one entry for a Windows `cmd.exe` invocation. Node does not quote for
  * `shell: true` on Windows — it joins the array with spaces — so a bare prefix

package/dist/utils/windows-spawn.js

@@ -13,6 +13,43 @@
 // This module is the single implementation of that policy. The self-update path
 // (version-gate) and the qmd spawn path (search-index) both import it, so there
 // is exactly one Windows spawn recipe in the repo.
+const CMD_META_CHARS = /([()\][%!\x5e\x60"<>&|;, *?])/g;
+function assertCmdArgument(value) {
+    if (/[\r\n\0]/.test(value)) {
+        throw Object.assign(new Error("Windows batch commands cannot accept newline or NUL characters"), {
+            code: "EINVAL",
+        });
+    }
+}
+function escapeCmdCommand(value) {
+    assertCmdArgument(value);
+    return value.replace(CMD_META_CHARS, "^$1");
+}
+function escapeCmdArgument(value) {
+    assertCmdArgument(value);
+    let escaped = value.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+    escaped = escaped.replace(/(?=(\\+?)?)\1$/, "$1$1");
+    return ('"' + escaped + '"').replace(CMD_META_CHARS, "^$1");
+}
+function environmentValue(env, name) {
+    const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name);
+    return key ? env[key] : undefined;
+}
+/**
+ * Explicit cmd.exe plan for a resolved .cmd/.bat target. Keeping cmd.exe's
+ * argv construction here makes the shell boundary testable without Windows.
+ */
+export function buildCmdExeSpawnPlan(command, args, env = process.env, platform = process.platform) {
+    if (platform !== "win32")
+        return { cmd: command, args: [...args], shell: false };
+    const commandLine = [escapeCmdCommand(command), ...args.map(escapeCmdArgument)].join(" ");
+    return {
+        cmd: environmentValue(env, "COMSPEC")?.trim() || "cmd.exe",
+        args: ["/d", "/s", "/c", '"' + commandLine + '"'],
+        shell: false,
+        windowsVerbatimArguments: true,
+    };
+}
 /**
  * Quote one entry for a Windows `cmd.exe` invocation. Node does not quote for
  * `shell: true` on Windows — it joins the array with spaces — so a bare prefix

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.152.0",
+  "version": "5.152.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {