@indigoai-us/hq-cli 5.151.0 → 5.152.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [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
+
+- `hq mesh daemon install` (plain and `--if-stale`) now bootouts, bootstraps, and kickstarts the LaunchAgent after writing the plist. Bootstrap retries launchd `5: Input/output error` up to five times, one second apart. After a CLI upgrade, a loaded job whose program no longer matches the plist is reloaded the same way.
+
 ## [5.151.0] — 2026-09-23
 
 - `hq report publish` no longer fails when another app it cannot see holds the report's address. It publishes at the next free address (`<slug>-2`, then `-3`) and saves that address on the report.

package/dist/commands/mesh.js

@@ -36,6 +36,7 @@ import { readLegacyBacklog } from "../lib/mesh/live/emit-replay.js";
 import { resolveMeshEmitMode, writeMeshConfigMode, } from "../lib/mesh/live/daemon/mode.js";
 import { workMeshRoot } from "../lib/mesh/live/paths.js";
 import { buildInstallPaths, collectDaemonDoctor, daemonServiceStatus, findAncestorHqRoot, resolveInstallHqRoot, detectPlatform, formatCliIdentityLines, formatDaemonDoctor, installDaemonIfStale, installDaemonService, readDaemonState, resolveAbsoluteNodeBinary, resolveRunningCliEntry, runMeshDaemon, uninstallDaemonService, daemonDir, } from "../lib/mesh/live/daemon/index.js";
+import { defaultRunCommand } from "../lib/service-manager/launchd.js";
 import { workContextRoot } from "../lib/work-context/paths.js";
 import { formatMigrateConfirmation, submitSessionMigration, } from "../lib/work-context/migrate.js";
 import { formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, submitOrganizeDecision, } from "../lib/work-context/organize.js";
@@ -2050,6 +2051,7 @@ async function runDaemonInstall(opts) {
         platform: detectPlatform(),
         paths,
         systemUser: opts.systemUser,
+        run: defaultRunCommand,
     });
     if (opts.json) {
         console.log(JSON.stringify({

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/lib/mesh/live/daemon/install.d.ts

@@ -12,7 +12,7 @@
  * Tests must not actually install services — use a temp HOME/prefix.
  */
 import * as fs from "node:fs";
-import { type RunCommand } from "../../../service-manager/launchd.js";
+import { type RunCommand, type SleepFn } from "../../../service-manager/launchd.js";
 export type DaemonInstallPlatform = "darwin" | "linux" | "win32" | "other";
 /** Result of one schtasks.exe invocation (tests inject; never the real binary). */
 export interface SchtasksResult {
@@ -93,11 +93,6 @@ export interface RestartDaemonResult {
     restarted: boolean;
     message?: string;
 }
-/**
- * Restart the installed user daemon after a CLI upgrade. This is deliberately
- * best-effort: an update must remain successful if a user has no service,
- * launchctl/systemd is unavailable, or the user manager is not running.
- */
 export declare function restartDaemonServiceIfInstalled(opts?: {
     platform?: DaemonInstallPlatform;
     home?: string;
@@ -110,7 +105,10 @@ export declare function restartDaemonServiceIfInstalled(opts?: {
     writeFileSync?: typeof fs.writeFileSync;
     run?: (command: string, args: string[]) => {
         status: number | null;
+        stdout?: string;
+        stderr?: string;
     };
+    sleep?: SleepFn;
     /** Windows: terminate the recorded daemon pid after `schtasks /End` (tests inject). */
     kill?: (pid: number) => void;
 }): RestartDaemonResult;
@@ -149,6 +147,7 @@ export declare function installDaemonIfStale(opts: {
     systemUser?: string;
     run?: RunCommand;
     uid?: number;
+    sleep?: SleepFn;
     writeFileSync?: typeof fs.writeFileSync;
     mkdirSync?: typeof fs.mkdirSync;
     reloadSystemd?: () => {
@@ -282,6 +281,10 @@ export declare function installDaemonService(opts: {
         stderr: string;
     };
     windowsLegacyTaskPresent?: boolean;
+    /** launchctl/systemctl seam — when set on darwin, bootout/bootstrap/kickstart after writing the plist. */
+    run?: RunCommand;
+    uid?: number;
+    sleep?: SleepFn;
 }): InstallResult;
 export declare function uninstallDaemonService(opts: {
     platform?: DaemonInstallPlatform;

package/dist/lib/mesh/live/daemon/install.js

@@ -22,7 +22,7 @@ import { isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot, verifyHqR
 import { defaultPidLockDeps, pidLockStatus, readPidLock } from "./pid-lock.js";
 import { retireLegacyListen } from "./legacy-listen.js";
 import { readDaemonState } from "./state.js";
-import { activateLaunchd } from "../../../service-manager/launchd.js";
+import { activateLaunchd, launchdPlistProgramArguments, launchdProgramArgumentsDiffer, parseLaunchctlPrintArguments, } from "../../../service-manager/launchd.js";
 import { activateSystemd } from "../../../service-manager/systemd.js";
 /**
  * `schtasks /End` terminates the task's root process only. The daemon is
@@ -139,13 +139,30 @@ function migrateLegacyDaemonUnit(opts) {
  * best-effort: an update must remain successful if a user has no service,
  * launchctl/systemd is unavailable, or the user manager is not running.
  */
+function asRunCommand(run) {
+    return (command, args) => {
+        const result = run(command, args);
+        return {
+            status: result.status,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+        };
+    };
+}
 export function restartDaemonServiceIfInstalled(opts = {}) {
     const platform = opts.platform ?? detectPlatform();
     const home = opts.home ?? os.homedir();
     const existsSync = opts.existsSync ?? fs.existsSync;
     const readFileSync = opts.readFileSync ?? fs.readFileSync;
     const writeFileSync = opts.writeFileSync ?? fs.writeFileSync;
-    const run = opts.run ?? ((command, args) => spawnSync(command, args, { stdio: "ignore" }));
+    const run = opts.run ?? ((command, args) => {
+        const result = spawnSync(command, args, { encoding: "utf8" });
+        return {
+            status: result.status,
+            stdout: typeof result.stdout === "string" ? result.stdout : "",
+            stderr: result.error ? result.error.message : (typeof result.stderr === "string" ? result.stderr : ""),
+        };
+    });
     try {
         migrateLegacyDaemonUnit({ platform, home, hqRoot: opts.hqRoot, env: opts.env, existsSync, readFileSync, writeFileSync, run });
         if (platform === "darwin") {
@@ -155,7 +172,22 @@ export function restartDaemonServiceIfInstalled(opts = {}) {
             const uid = opts.uid ?? process.getuid?.();
             if (typeof uid !== "number")
                 return { attempted: false, restarted: false };
-            const result = run("launchctl", ["kickstart", "-k", `gui/${uid}/${LAUNCHD_LABEL}`]);
+            const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+            const printed = run("launchctl", ["print", target]);
+            const loadedArgs = parseLaunchctlPrintArguments(printed.stdout ?? "");
+            const rawPlist = readFileSync(plist);
+            const plistText = Buffer.isBuffer(rawPlist) ? rawPlist.toString("utf8") : String(rawPlist);
+            const plistArgs = launchdPlistProgramArguments(plistText);
+            if (launchdProgramArgumentsDiffer(loadedArgs, plistArgs)) {
+                try {
+                    activateLaunchd(plist, asRunCommand(run), uid, { sleep: opts.sleep });
+                    return { attempted: true, restarted: true };
+                }
+                catch {
+                    return { attempted: true, restarted: false };
+                }
+            }
+            const result = run("launchctl", ["kickstart", "-k", target]);
             return { attempted: true, restarted: result.status === 0 };
         }
         if (platform === "linux") {
@@ -306,11 +338,11 @@ export function installDaemonIfStale(opts) {
         kill: opts.kill,
         runCommand: opts.runCommand,
         windowsLegacyTaskPresent: opts.windowsLegacyTaskPresent,
+        run,
+        uid: opts.uid,
+        sleep: opts.sleep,
     });
-    if (platform === "darwin") {
-        activateLaunchd(opts.paths.plistPath, run, opts.uid);
-    }
-    else if (platform === "linux" && !opts.systemUser && !opts.paths.systemUser) {
+    if (platform === "linux" && !opts.systemUser && !opts.paths.systemUser) {
         activateSystemd(SYSTEMD_UNIT_NAME, run);
     }
     return {
@@ -753,7 +785,12 @@ export function installDaemonService(opts) {
         const rendered = renderLaunchdPlist(paths);
         mkdirSync(paths.launchAgentsDir, { recursive: true });
         writeFileSync(paths.plistPath, rendered, { mode: 0o600 });
-        opts.activate?.(platform, paths.plistPath);
+        if (opts.run) {
+            activateLaunchd(paths.plistPath, opts.run, opts.uid, { sleep: opts.sleep });
+        }
+        else {
+            opts.activate?.(platform, paths.plistPath);
+        }
         return {
             platform,
             action: "install",

package/dist/lib/service-manager/index.d.ts

@@ -9,9 +9,8 @@ import { type RunCommand } from "./launchd.js";
 import { type ServiceHostPaths, type ServicePlatform, type ServiceSpec } from "./types.js";
 export type { ServiceSpec, ServiceHostPaths, ServicePlatform } from "./types.js";
 export { detectServicePlatform } from "./types.js";
-export { renderLaunchdPlist } from "./launchd.js";
+export { defaultRunCommand, renderLaunchdPlist } from "./launchd.js";
 export { renderSystemdUserUnit, systemdUnitName } from "./systemd.js";
-export declare const defaultRunCommand: RunCommand;
 export interface ServiceManagerDeps {
     platform?: ServicePlatform;
     run?: RunCommand;

package/dist/lib/service-manager/index.js

@@ -4,22 +4,13 @@
  * injectable so the kit tests exercise the real rendering and dispatch
  * without touching the host's service manager.
  */
-import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
-import { activateLaunchd, deactivateLaunchd, launchAgentsDir, launchdIsLoaded, launchdPlistPath, renderLaunchdPlist, } from "./launchd.js";
+import { activateLaunchd, deactivateLaunchd, defaultRunCommand, launchAgentsDir, launchdIsLoaded, launchdPlistPath, renderLaunchdPlist, } from "./launchd.js";
 import { activateSystemd, deactivateSystemd, renderSystemdUserUnit, systemdIsActive, systemdUnitName, systemdUnitPath, systemdUserDir, } from "./systemd.js";
 import { detectServicePlatform, } from "./types.js";
 export { detectServicePlatform } from "./types.js";
-export { renderLaunchdPlist } from "./launchd.js";
+export { defaultRunCommand, renderLaunchdPlist } from "./launchd.js";
 export { renderSystemdUserUnit, systemdUnitName } from "./systemd.js";
-export const defaultRunCommand = (cmd, args) => {
-    const r = spawnSync(cmd, args, { encoding: "utf8" });
-    return {
-        status: r.status,
-        stdout: r.stdout ?? "",
-        stderr: r.error ? r.error.message : (r.stderr ?? ""),
-    };
-};
 function unitPathFor(platform, home, spec) {
     return platform === "darwin" ? launchdPlistPath(home, spec) : systemdUnitPath(home, spec);
 }

package/dist/lib/service-manager/launchd.d.ts

@@ -16,8 +16,36 @@ export type RunCommand = (cmd: string, args: string[]) => {
     stdout: string;
     stderr: string;
 };
-/** (Re)load a plist: bootout is best-effort (not loaded yet is fine). */
-export declare function activateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
+export type SleepFn = (ms: number) => void;
+/** Bootstrap attempts after bootout (first try + EIO retries). */
+export declare const LAUNCHD_BOOTSTRAP_ATTEMPTS = 5;
+/** Delay between bootstrap retries while the old job is still exiting. */
+export declare const LAUNCHD_BOOTSTRAP_RETRY_MS = 1000;
+export declare const defaultRunCommand: RunCommand;
+export declare function launchdServiceTarget(plistPath: string, uid?: number): string;
+/** launchd returns EIO (5) when bootstrap races the previous job's exit. */
+export declare function isRetryableLaunchdBootstrap(r: {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}): boolean;
+/** ProgramArguments from a LaunchAgent plist. */
+export declare function launchdPlistProgramArguments(plist: string): string[];
+/**
+ * Arguments of a loaded job from `launchctl print gui/<uid>/<label>`.
+ * Prefers the `arguments = { ... }` block; falls back to `program =`.
+ */
+export declare function parseLaunchctlPrintArguments(stdout: string): string[];
+export declare function launchdProgramArgumentsDiffer(loaded: string[], plist: string[]): boolean;
+/**
+ * (Re)load a plist so launchd picks up a rewritten ProgramArguments.
+ * bootout is best-effort (not loaded yet is fine). bootstrap retries EIO a
+ * bounded number of times — bootout returns before the old job has actually
+ * exited. kickstart then starts the newly loaded program.
+ */
+export declare function activateLaunchd(plistPath: string, run: RunCommand, uid?: number, opts?: {
+    sleep?: SleepFn;
+}): void;
 export declare function deactivateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
 export declare function launchdIsLoaded(label: string, run: RunCommand, uid?: number): boolean;
 //# sourceMappingURL=launchd.d.ts.map

package/dist/lib/service-manager/launchd.js

@@ -6,6 +6,7 @@
  * picks up a changed plist). Command execution is injected so tests never
  * touch launchctl.
  */
+import { spawnSync } from "node:child_process";
 import * as os from "node:os";
 import * as path from "node:path";
 import { escapeXml, } from "./types.js";
@@ -59,17 +60,92 @@ ${envXml}
 </plist>
 `;
 }
+/** Bootstrap attempts after bootout (first try + EIO retries). */
+export const LAUNCHD_BOOTSTRAP_ATTEMPTS = 5;
+/** Delay between bootstrap retries while the old job is still exiting. */
+export const LAUNCHD_BOOTSTRAP_RETRY_MS = 1000;
+export const defaultRunCommand = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8" });
+    return {
+        status: r.status,
+        stdout: typeof r.stdout === "string" ? r.stdout : "",
+        stderr: r.error ? r.error.message : (typeof r.stderr === "string" ? r.stderr : ""),
+    };
+};
+function blockingSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 function guiDomain(uid = os.userInfo().uid) {
     return `gui/${uid}`;
 }
-/** (Re)load a plist: bootout is best-effort (not loaded yet is fine). */
-export function activateLaunchd(plistPath, run, uid) {
+export function launchdServiceTarget(plistPath, uid) {
+    return `${guiDomain(uid)}/${path.basename(plistPath, ".plist")}`;
+}
+function bootstrapErrorText(r) {
+    return `${r.stderr} ${r.stdout} exit ${r.status ?? ""}`;
+}
+/** launchd returns EIO (5) when bootstrap races the previous job's exit. */
+export function isRetryableLaunchdBootstrap(r) {
+    if (r.status === 0)
+        return false;
+    return /Input\/output error|\bEIO\b|Bootstrap failed: 5|Boot-strap failed: 5/i.test(bootstrapErrorText(r));
+}
+function unescapeXml(value) {
+    return value
+        .replace(/&quot;/g, '"')
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
+/** ProgramArguments from a LaunchAgent plist. */
+export function launchdPlistProgramArguments(plist) {
+    const block = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (!block)
+        return [];
+    return [...block[1].matchAll(/<string>([^<]*)<\/string>/g)].map((m) => unescapeXml(m[1]));
+}
+/**
+ * Arguments of a loaded job from `launchctl print gui/<uid>/<label>`.
+ * Prefers the `arguments = { ... }` block; falls back to `program =`.
+ */
+export function parseLaunchctlPrintArguments(stdout) {
+    const block = /(?:program\s+)?arguments\s*=\s*\{([^}]*)\}/i.exec(stdout);
+    if (block) {
+        return block[1]
+            .split(/\r?\n/)
+            .map((line) => line.trim().replace(/;+$/, ""))
+            .filter((line) => line.length > 0);
+    }
+    const program = /^\s*program\s*=\s*(.+?);?\s*$/m.exec(stdout);
+    return program ? [program[1].trim()] : [];
+}
+export function launchdProgramArgumentsDiffer(loaded, plist) {
+    if (loaded.length === 0 || plist.length === 0)
+        return loaded.length !== plist.length;
+    if (loaded.length !== plist.length)
+        return true;
+    return loaded.some((value, i) => value !== plist[i]);
+}
+/**
+ * (Re)load a plist so launchd picks up a rewritten ProgramArguments.
+ * bootout is best-effort (not loaded yet is fine). bootstrap retries EIO a
+ * bounded number of times — bootout returns before the old job has actually
+ * exited. kickstart then starts the newly loaded program.
+ */
+export function activateLaunchd(plistPath, run, uid, opts) {
     const domain = guiDomain(uid);
-    run("launchctl", ["bootout", domain, plistPath]);
-    const r = run("launchctl", ["bootstrap", domain, plistPath]);
-    if (r.status !== 0) {
-        throw new Error(`launchctl bootstrap failed for ${plistPath}: ${r.stderr.trim() || r.stdout.trim() || `exit ${r.status}`}`);
+    const target = launchdServiceTarget(plistPath, uid);
+    run("launchctl", ["bootout", target]);
+    const sleep = opts?.sleep ?? blockingSleep;
+    let last = run("launchctl", ["bootstrap", domain, plistPath]);
+    for (let attempt = 1; attempt < LAUNCHD_BOOTSTRAP_ATTEMPTS && last.status !== 0 && isRetryableLaunchdBootstrap(last); attempt++) {
+        sleep(LAUNCHD_BOOTSTRAP_RETRY_MS);
+        last = run("launchctl", ["bootstrap", domain, plistPath]);
+    }
+    if (last.status !== 0) {
+        throw new Error(`launchctl bootstrap failed for ${plistPath}: ${last.stderr.trim() || last.stdout.trim() || `exit ${last.status}`}`);
     }
+    run("launchctl", ["kickstart", "-k", target]);
 }
 export function deactivateLaunchd(plistPath, run, uid) {
     run("launchctl", ["bootout", guiDomain(uid), plistPath]);

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.151.0",
+  "version": "5.152.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {