@indigoai-us/hq-cli 5.345.160 → 5.345.161

package/dist/hq-cloud-sync-runner/package.json

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.98","bundleSha256":"70fe5497fffdbb678370515f8b7df63438d7a59a95467102307459e78f9f4715","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.99","bundleSha256":"05ece85b87c743511d74111934f420f24a47677e9e90a18dd45e6d3d1d8d0375","formatVersion":1}

package/dist/index.js

@@ -15,6 +15,7 @@ import { installFastPathStreamErrorHandlers } from "./utils/fast-stream-errors.j
 import { installWindowsHideDefault } from "./utils/windows-hide-default.js";
 import { fileURLToPath } from "node:url";
 import { parseMonitorCheckFastRequest } from "./lanes-monitor-check-argv.js";
+import { isLaneSessionStartFastRequest } from "./lanes-session-start-argv.js";
 import { createRequire } from "node:module";
 import { hookEnginePathArgs, runHookEnginePath } from "./hook-engine-path.js";
 function cygpathMixedPath(value) {
@@ -156,6 +157,22 @@ async function runMonitorCheckFastWithRecovery(request) {
         return;
     await runMainWithInstallTreeRecovery();
 }
+/**
+ * The SessionStart hook runs `hq lanes session-start` on every new session
+ * under a 2 s cap. Load only that command's module, not the command graph.
+ */
+async function runLaneSessionStartFastWithRecovery() {
+    const loaded = await recoverFastImport(() => import("./commands/lanes-session-start.js"));
+    if (loaded.reexecStatus !== undefined) {
+        process.exitCode = loaded.reexecStatus;
+        return;
+    }
+    if (loaded.module) {
+        await loaded.module.runLaneSessionStart();
+        return;
+    }
+    await runMainWithInstallTreeRecovery();
+}
 /**
  * Whether the install follow-up would read the registry or spawn the mesh
  * daemon. False for fast routes' callers, and for commands that are not run
@@ -206,6 +223,10 @@ function dispatchCliRoutes() {
     const helpRequest = !versionRequest && isCommandHelpRequest(process.argv);
     const parsedFastCore = versionRequest || helpRequest ? null : parseFastCore(process.argv);
     const monitorRequest = versionRequest || helpRequest ? null : parseMonitorCheckFastRequest(process.argv);
+    if (!versionRequest && !helpRequest && !monitorRequest && isLaneSessionStartFastRequest(process.argv)) {
+        void runLaneSessionStartFastWithRecovery();
+        return;
+    }
     const secretsRequest = versionRequest || helpRequest || monitorRequest || parsedFastCore
         ? null
         : parseSecretsEnvFastRequest(process.argv);

package/dist/lanes-session-start-argv.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Dependency-free argv matcher for the `hq lanes session-start` fast route.
+ * Imported statically by src/index.ts, so it must not import anything.
+ */
+/** Exactly `hq lanes session-start` with no options (the SessionStart hook form). */
+export declare function isLaneSessionStartFastRequest(argv: readonly string[]): boolean;
+//# sourceMappingURL=lanes-session-start-argv.d.ts.map

package/dist/lanes-session-start-argv.js

@@ -0,0 +1,9 @@
+/**
+ * Dependency-free argv matcher for the `hq lanes session-start` fast route.
+ * Imported statically by src/index.ts, so it must not import anything.
+ */
+/** Exactly `hq lanes session-start` with no options (the SessionStart hook form). */
+export function isLaneSessionStartFastRequest(argv) {
+    return argv.length === 4 && argv[2] === "lanes" && argv[3] === "session-start";
+}
+//# sourceMappingURL=lanes-session-start-argv.js.map

package/dist/lib/bot/log.d.ts

@@ -6,8 +6,9 @@ export declare function ensureBotLog(dir: string): string;
 export declare function rotateBotLogIfNeeded(dir: string, maxBytes?: number): void;
 /** Strip anything that looks like a bearer token, secret, or op:// ref. */
 export declare function redactForLog(message: string): string;
-export declare function botLogLine(level: "info" | "warn" | "error", message: string, now?: () => Date): string;
+export type BotLogLevel = "debug" | "info" | "warn" | "error";
+export declare function botLogLine(level: BotLogLevel, message: string, now?: () => Date): string;
 export declare function appendBotLog(dir: string, line: string): void;
-export type BotLogger = (level: "info" | "warn" | "error", message: string) => void;
+export type BotLogger = (level: BotLogLevel, message: string) => void;
 export declare function createBotLogger(dir: string, now?: () => Date): BotLogger;
 //# sourceMappingURL=log.d.ts.map

package/dist/lib/bot/progress.d.ts

@@ -54,7 +54,23 @@ export interface ProgressPosterOptions {
      * it, anything else (another message, the end of the turn) keeps it.
      */
     dropPreToolMessages?: boolean;
+    /**
+     * Called with each message dropped because a tool call followed it (see
+     * `dropPreToolMessages` and `isPreToolAside`), so the bot log can record it.
+     */
+    onDropped?: (text: string) => void;
 }
+/** Below this many characters a message right before a tool call is an aside, not a progress note. */
+export declare const PRE_TOOL_ASIDE_MAX_CHARS = 40;
+/**
+ * True for a short assistant text that is an aside to itself when a tool call
+ * follows it ("Bind first, separately." reached a person on 2026-10-13: the
+ * model thinking out loud before a tool_use in the same assistant message).
+ * Real progress notes are full sentences addressed to the person ("Reading
+ * your agency docs now, then I'll look at the client folders.") and run past
+ * the limit; an hq-block is always content the desktop app must draw.
+ */
+export declare function isPreToolAside(text: string): boolean;
 /** Whitespace-insensitive form used to recognise repeated text. */
 export declare function normalizeForCompare(text: string): string;
 /** Matches {"action":"no_reply"} anywhere in a model reply, with or without preamble text. */
@@ -71,7 +87,13 @@ export declare class ProgressPoster {
     private readonly workingNoticeText;
     private readonly buffer;
     private readonly dropPreTool;
-    /** dropPreToolMessages: messages waiting to learn whether a tool call follows. */
+    private readonly onDropped;
+    /**
+     * Messages waiting to learn whether a tool call follows: every message when
+     * dropPreToolMessages is set, short asides (isPreToolAside) otherwise. The
+     * runtime streams one content block per event, so "followed by a tool_use
+     * in the same assistant message" is "the next event is a tool call".
+     */
     private candidates;
     private pending;
     /** In-between questions, held until the turn ends (see the header). */

package/dist/lib/bot/progress.js

@@ -27,6 +27,20 @@ export const PROGRESS_COALESCE_MS = 2_000;
 export const PROGRESS_MIN_GAP_MS = 4_000;
 export const WORKING_NOTICE_MS = 60_000;
 export const WORKING_NOTICE_TEXT = "Working on it — I'll reply here when it's done.";
+/** Below this many characters a message right before a tool call is an aside, not a progress note. */
+export const PRE_TOOL_ASIDE_MAX_CHARS = 40;
+/**
+ * True for a short assistant text that is an aside to itself when a tool call
+ * follows it ("Bind first, separately." reached a person on 2026-10-13: the
+ * model thinking out loud before a tool_use in the same assistant message).
+ * Real progress notes are full sentences addressed to the person ("Reading
+ * your agency docs now, then I'll look at the client folders.") and run past
+ * the limit; an hq-block is always content the desktop app must draw.
+ */
+export function isPreToolAside(text) {
+    const t = text.trim();
+    return t.length < PRE_TOOL_ASIDE_MAX_CHARS && !t.includes("```hq-block");
+}
 /** Whitespace-insensitive form used to recognise repeated text. */
 export function normalizeForCompare(text) {
     return text.replace(/\s+/g, "");
@@ -47,7 +61,13 @@ export class ProgressPoster {
     workingNoticeText;
     buffer;
     dropPreTool;
-    /** dropPreToolMessages: messages waiting to learn whether a tool call follows. */
+    onDropped;
+    /**
+     * Messages waiting to learn whether a tool call follows: every message when
+     * dropPreToolMessages is set, short asides (isPreToolAside) otherwise. The
+     * runtime streams one content block per event, so "followed by a tool_use
+     * in the same assistant message" is "the next event is a tool call".
+     */
     candidates = [];
     pending = [];
     /** In-between questions, held until the turn ends (see the header). */
@@ -82,6 +102,7 @@ export class ProgressPoster {
         this.workingNoticeText = opts.workingNoticeText ?? WORKING_NOTICE_TEXT;
         this.buffer = opts.buffer ?? false;
         this.dropPreTool = opts.dropPreToolMessages ?? false;
+        this.onDropped = opts.onDropped ?? (() => undefined);
     }
     /** Arm the one-time "working on it" note. Call when the turn starts. */
     start() {
@@ -93,6 +114,12 @@ export class ProgressPoster {
             this.noticeTimer = null;
             if (this.finished || this.said.length > 0 || this.noticeSent)
                 return;
+            // A short message is waiting to learn whether a tool call follows: if it
+            // was real, it is the model's own "working on it"; look again later.
+            if (!this.dropPreTool && this.candidates.length > 0) {
+                this.start();
+                return;
+            }
             this.noticeSent = true;
             this.enqueueWith(this.workingNoticeText, this.sendProgress);
         }, this.workingNoticeMs);
@@ -106,9 +133,9 @@ export class ProgressPoster {
         // silence signal, not content, and must never be posted as progress.
         if (containsNoReplySentinel(t))
             return;
-        if (this.dropPreTool) {
-            // The previous message was not followed by a tool call: it was real.
-            this.promoteCandidates();
+        // The previous message was not followed by a tool call: it was real.
+        this.promoteCandidates();
+        if (this.dropPreTool || isPreToolAside(t)) {
             this.candidates.push(t);
             return;
         }
@@ -116,9 +143,18 @@ export class ProgressPoster {
     }
     /** The model called a tool: whatever it wrote just before was a note to itself. */
     tool() {
-        if (this.finished || !this.dropPreTool)
+        if (this.finished)
             return;
+        const dropped = this.candidates;
         this.candidates = [];
+        for (const t of dropped) {
+            try {
+                this.onDropped(t);
+            }
+            catch {
+                /* a log hook must never break the turn */
+            }
+        }
     }
     promoteCandidates() {
         const kept = this.candidates;
@@ -199,6 +235,8 @@ export class ProgressPoster {
     async abandon() {
         if (this.finished)
             return this.chain;
+        // A message the turn ended on (no tool after it) is real.
+        this.promoteCandidates();
         this.finished = true;
         this.cancelNotice();
         this.cancelFlush();

package/dist/lib/bot/run.js

@@ -1118,6 +1118,8 @@ export async function runBot(deps) {
             // reach them, and it posts no "still working" notice either — the
             // desktop app shows that the bot is working.
             ...(isSetupBot ? { dropPreToolMessages: true } : {}),
+            // Short asides before a tool call never reach the person either (isPreToolAside).
+            onDropped: (text) => log("debug", `dropped a pre-tool aside for ${messageId} (${text.length} chars): ${text}`),
             ...deps.progress,
             ...(args.workingNotice === false || silenceable || isSetupBot ? { workingNoticeMs: 0 } : {}),
             ...(silenceable || args.suppressOutput ? { buffer: true } : {}),

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

@@ -27,6 +27,18 @@ export declare const FALLBACK_CLAUDE_PERMISSION_MODE = "auto";
 export declare const CLAUDE_EFFORT_ENV = "HQ_BOT_CLAUDE_EFFORT";
 export declare const DEFAULT_CLAUDE_EFFORT = "medium";
 export declare function claudeEffort(env?: NodeJS.ProcessEnv): string;
+/**
+ * Per-tool-call safety for a bot turn: Claude Code reads these to bound each
+ * Bash tool call (its default and the most a call may ask for). On 2026-10-13
+ * a bot-authored command ended in `cat > /dev/null`, waited on stdin that
+ * never closed, and the turn showed "working" for over 15 minutes. Set only
+ * when the environment does not already set them.
+ */
+export declare const CLAUDE_BASH_DEFAULT_TIMEOUT_ENV = "BASH_DEFAULT_TIMEOUT_MS";
+export declare const CLAUDE_BASH_MAX_TIMEOUT_ENV = "BASH_MAX_TIMEOUT_MS";
+export declare const BOT_BASH_TIMEOUT_MS: number;
+/** Claude's `runtimeEnv` layer: the Bash tool timeouts defaulted (pure). */
+export declare function claudeRuntimeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function claudePermissionMode(env?: NodeJS.ProcessEnv, autoApprove?: boolean, explicit?: string): string;
 /**
  * True when Claude Code refused to start because bypassPermissions is turned

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

@@ -34,6 +34,25 @@ export const DEFAULT_CLAUDE_EFFORT = "medium";
 export function claudeEffort(env = process.env) {
     return env[CLAUDE_EFFORT_ENV]?.trim() || DEFAULT_CLAUDE_EFFORT;
 }
+/**
+ * Per-tool-call safety for a bot turn: Claude Code reads these to bound each
+ * Bash tool call (its default and the most a call may ask for). On 2026-10-13
+ * a bot-authored command ended in `cat > /dev/null`, waited on stdin that
+ * never closed, and the turn showed "working" for over 15 minutes. Set only
+ * when the environment does not already set them.
+ */
+export const CLAUDE_BASH_DEFAULT_TIMEOUT_ENV = "BASH_DEFAULT_TIMEOUT_MS";
+export const CLAUDE_BASH_MAX_TIMEOUT_ENV = "BASH_MAX_TIMEOUT_MS";
+export const BOT_BASH_TIMEOUT_MS = 10 * 60 * 1000;
+/** Claude's `runtimeEnv` layer: the Bash tool timeouts defaulted (pure). */
+export function claudeRuntimeEnv(env) {
+    const out = { ...env };
+    for (const key of [CLAUDE_BASH_DEFAULT_TIMEOUT_ENV, CLAUDE_BASH_MAX_TIMEOUT_ENV]) {
+        if (!out[key]?.trim())
+            out[key] = String(BOT_BASH_TIMEOUT_MS);
+    }
+    return out;
+}
 export function claudePermissionMode(env = process.env, autoApprove = true, explicit) {
     const raw = env[CLAUDE_PERMISSION_MODE_ENV]?.trim();
     if (raw)
@@ -193,6 +212,7 @@ export function createClaudeRuntime(env = process.env, opts = {}) {
                 args.push("--session-id", scratch.newSessionId);
             return args;
         },
+        runtimeEnv: claudeRuntimeEnv,
         stdinInput(input) {
             return input.platform === "win32"
                 ? JSON.stringify({

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

@@ -1,5 +1,5 @@
 import type { BotRuntimeId } from "../config.js";
-import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult, type SpawnLike } from "./types.js";
+import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult, type SpawnLike, type SpawnOptions } from "./types.js";
 export * from "./types.js";
 export { createClaudeRuntime, claudePermissionMode } from "./claude.js";
 export { createCodexRuntime, codexPrompt } from "./codex.js";
@@ -19,6 +19,15 @@ export declare function runtimeFor(id: BotRuntimeId, env?: NodeJS.ProcessEnv): B
 export declare function descendantPids(pid: number, listProcesses?: () => string): number[];
 /** After a stop, wait this long for the output pipes to close before settling anyway. */
 export declare const STOP_SETTLE_GRACE_MS = 2000;
+/**
+ * The child's stdin: a pipe only when this process has something to write to
+ * it (a stdin prompt, which is ended right after it is written, or a
+ * protocol), otherwise closed (`ignore` = /dev/null). The prompt normally
+ * travels on argv, so the model CLI must never inherit or wait on an open
+ * stdin: a bot-authored `cat > /dev/null` on 2026-10-13 blocked a turn for
+ * over 15 minutes.
+ */
+export declare function runtimeStdinMode(options: Pick<SpawnOptions, "stdin" | "protocol">): "pipe" | "ignore";
 export declare const defaultSpawn: SpawnLike;
 /** Time limit for the short helper commands a turn may run (`--version`, the bundled model catalog). */
 export declare const AUX_COMMAND_TIMEOUT_MS = 20000;

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

@@ -71,6 +71,17 @@ function defaultListProcesses() {
 }
 /** After a stop, wait this long for the output pipes to close before settling anyway. */
 export const STOP_SETTLE_GRACE_MS = 2_000;
+/**
+ * The child's stdin: a pipe only when this process has something to write to
+ * it (a stdin prompt, which is ended right after it is written, or a
+ * protocol), otherwise closed (`ignore` = /dev/null). The prompt normally
+ * travels on argv, so the model CLI must never inherit or wait on an open
+ * stdin: a bot-authored `cat > /dev/null` on 2026-10-13 blocked a turn for
+ * over 15 minutes.
+ */
+export function runtimeStdinMode(options) {
+    return options.stdin !== undefined || options.protocol ? "pipe" : "ignore";
+}
 export const defaultSpawn = (command, args, options) => new Promise((resolve, reject) => {
     let stdout = "";
     let stderr = "";
@@ -80,7 +91,7 @@ export const defaultSpawn = (command, args, options) => new Promise((resolve, re
     const child = spawn(plan.cmd, plan.args, {
         cwd: options.cwd,
         env: options.env,
-        stdio: [options.stdin !== undefined || options.protocol ? "pipe" : "ignore", "pipe", "pipe"],
+        stdio: [runtimeStdinMode(options), "pipe", "pipe"],
         ...(plan.shell ? { shell: plan.shell } : {}),
         ...(plan.windowsVerbatimArguments !== undefined
             ? { windowsVerbatimArguments: plan.windowsVerbatimArguments }
@@ -347,7 +358,8 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
     const args = runtime.buildArgs(remembered ? { ...turnInput, model: remembered.to } : turnInput, { outputFile, newSessionId });
     // Enforce at the model boundary too: old plists and direct `bot run` callers
     // may lack the guard. A bot prompt must never quit the user's desktop app.
-    const env = { ...(input.env ?? deps.env ?? process.env), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
+    const baseEnv = { ...(input.env ?? deps.env ?? process.env), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
+    const env = { ...(runtime.runtimeEnv?.(baseEnv) ?? baseEnv), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
     const binary = runtime.resolveBinary?.(env, input.cwd, turnInput.platform) ?? runtime.binary;
     const stdin = runtime.stdinInput?.(turnInput);
     const protocol = runtime.spawnProtocol?.(turnInput);

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

@@ -146,6 +146,14 @@ export interface BotRuntime {
     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: runtime-specific defaults layered onto the turn's environment
+     * (per-tool safety defaults the CLI honours, for example). Applied in
+     * `runRuntimeTurn` on top of the env that `turnEnv` in run.ts built from
+     * the bot's identity rules; it only adds runtime keys and never changes
+     * who the turn acts as. Pure; must not mutate `env`.
+     */
+    runtimeEnv?(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
     /** Optional bidirectional process protocol for this runtime. */
     spawnProtocol?(input: RuntimeTurnInput): SpawnProtocol | undefined;
     /** Build the argv for one turn. Pure. */

package/dist/lib/doctor/checks/ps1-shims.d.ts

@@ -0,0 +1,21 @@
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+export declare const PS1_SHIM_FAMILY_ID = "cli-ps1-shim";
+export declare const PS1_SHIM_CHECK_ID = "cli-ps1-shim.blocked-by-policy";
+export interface Ps1ShimCheckDeps {
+    platform: NodeJS.Platform;
+    /** The npm prefix holding `hq.cmd`, or null when hq is not an npm global install. */
+    binDir: () => string | null;
+    /** The npm-generated hq-cli `.ps1` launchers present in the prefix. */
+    findShims: (dir: string) => string[];
+    /** The effective PowerShell execution policy, or null when it could not be read. */
+    readPolicy: () => string | null;
+}
+/**
+ * Windows: npm writes `hq.ps1` next to `hq.cmd`, and PowerShell prefers the
+ * `.ps1`. Under a policy that blocks unsigned scripts (the Windows client
+ * default) `hq` then fails with UnauthorizedAccess. This check only reads:
+ * it never changes the execution policy.
+ */
+export declare const ps1ShimsFamily: CheckFamily;
+export declare function checkPs1Shims(_context: CheckContext, deps?: Ps1ShimCheckDeps): CheckResult[];
+//# sourceMappingURL=ps1-shims.d.ts.map

package/dist/lib/doctor/checks/ps1-shims.js

@@ -0,0 +1,82 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { npmShimDir } from "../../windows/user-path.js";
+import { findHqCliPs1Shims, policyBlocksUnsignedScripts, readExecutionPolicy } from "../../windows/ps1-shims.js";
+export const PS1_SHIM_FAMILY_ID = "cli-ps1-shim";
+export const PS1_SHIM_CHECK_ID = "cli-ps1-shim.blocked-by-policy";
+const defaultDeps = {
+    platform: process.platform,
+    binDir: () => npmShimDir(process.argv[1], fs.existsSync),
+    findShims: (dir) => findHqCliPs1Shims(dir),
+    readPolicy: () => readExecutionPolicy(),
+};
+const REMEDIATION = "Run `hq.cmd doctor --fix` (or `hq.cmd install --global`) to remove the hq .ps1 launchers. " +
+    "Until then, type `hq.cmd` instead of `hq` in PowerShell. Your execution policy is not changed.";
+/**
+ * Windows: npm writes `hq.ps1` next to `hq.cmd`, and PowerShell prefers the
+ * `.ps1`. Under a policy that blocks unsigned scripts (the Windows client
+ * default) `hq` then fails with UnauthorizedAccess. This check only reads:
+ * it never changes the execution policy.
+ */
+export const ps1ShimsFamily = {
+    id: PS1_SHIM_FAMILY_ID,
+    title: "hq PowerShell launchers",
+    run: (context) => Promise.resolve(checkPs1Shims(context)),
+};
+export function checkPs1Shims(_context, deps = defaultDeps) {
+    const dir = deps.platform === "win32" ? deps.binDir() : null;
+    if (!dir) {
+        return [
+            {
+                status: "NA",
+                checkId: PS1_SHIM_CHECK_ID,
+                message: "Not a Windows npm global install, so there are no hq PowerShell launchers to check.",
+            },
+        ];
+    }
+    const shims = deps.findShims(dir);
+    if (shims.length === 0) {
+        return [
+            {
+                status: "PASS",
+                checkId: PS1_SHIM_CHECK_ID,
+                target: dir,
+                message: `No hq .ps1 launchers in ${dir}; PowerShell runs hq.cmd.`,
+            },
+        ];
+    }
+    const names = shims.map((file) => path.win32.basename(file)).join(", ");
+    const policy = deps.readPolicy();
+    if (policy === null) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: PS1_SHIM_CHECK_ID,
+                target: shims[0],
+                message: `Found ${names} in ${dir} but could not read the PowerShell execution policy. If \`hq\` fails with UnauthorizedAccess, use \`hq.cmd\`.`,
+                remediation: REMEDIATION,
+            },
+        ];
+    }
+    if (!policyBlocksUnsignedScripts(policy)) {
+        return [
+            {
+                status: "PASS",
+                checkId: PS1_SHIM_CHECK_ID,
+                target: shims[0],
+                message: `${names} can run under the ${policy} execution policy.`,
+            },
+        ];
+    }
+    return [
+        {
+            status: "WARN",
+            checkId: PS1_SHIM_CHECK_ID,
+            target: shims[0],
+            message: `PowerShell runs ${names} for \`hq\`, and the ${policy} execution policy blocks it, so \`hq\` fails with UnauthorizedAccess.`,
+            details: { policy, shims },
+            remediation: REMEDIATION,
+        },
+    ];
+}
+//# sourceMappingURL=ps1-shims.js.map

package/dist/lib/doctor/fix/apply.d.ts

@@ -17,7 +17,10 @@
  *      execute bit, add a hook id to the gate profiles it is missing from,
  *      re-register a script present on disk, or pull a company or personal
  *      vault whose local tree exists but whose journal is stale — and NEVER
- *      rewrites a hook body or deletes a file. Classification is owned by
+ *      rewrites a hook body or deletes a file, with one scoped exception: on
+ *      Windows, `remove-ps1-shims` deletes npm-generated hq-cli `.ps1`
+ *      launchers (and only files whose content is that shim) from the npm
+ *      prefix, outside the HQ tree. Classification is owned by
  *      {@link deriveRemediation};
  *      a content-drift finding is manual-only and simply never appears in the
  *      fixable set.
@@ -38,6 +41,7 @@ import { type SpawnSyncReturns } from "node:child_process";
 import type { CheckResult, DoctorStatus } from "../types.js";
 import { type GateProfile } from "../hook-gate-profiles.js";
 import { type FixClass } from "./remediation.js";
+import { type RemovePs1ShimsResult } from "../../windows/ps1-shims.js";
 import { type RefreshSyncOutcome } from "./refresh-sync-outcome.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export declare const HOOK_CONFIG_DIRS: readonly [".claude", ".codex", ".grok"];
@@ -109,6 +113,12 @@ export interface ApplyFixesOptions {
         from: string | null;
         to: string;
     } | null;
+    /**
+     * Removal used by the `remove-ps1-shims` class: delete npm's hq-cli `.ps1`
+     * launchers from the given npm prefix (Windows only; other files and the
+     * execution policy are left alone). Tests inject a stub.
+     */
+    removePs1Shims?: (dir: string) => RemovePs1ShimsResult;
 }
 /** One company or personal vault the `refresh-sync` class will pull. */
 export interface RefreshSyncTarget {
@@ -311,6 +321,8 @@ export declare function defaultRewriteBotNodePath(name: string): {
     from: string;
     to: string;
 } | null;
+/** Default `remove-ps1-shims` repair: Windows only, a no-op elsewhere. */
+export declare function defaultRemovePs1Shims(dir: string): RemovePs1ShimsResult;
 /**
  * An hq path a bot may be pointed at unattended: an installed package entry
  * or its stable shim, never a worktree or one-off build that happens to be

package/dist/lib/doctor/fix/apply.js

@@ -17,7 +17,10 @@
  *      execute bit, add a hook id to the gate profiles it is missing from,
  *      re-register a script present on disk, or pull a company or personal
  *      vault whose local tree exists but whose journal is stale — and NEVER
- *      rewrites a hook body or deletes a file. Classification is owned by
+ *      rewrites a hook body or deletes a file, with one scoped exception: on
+ *      Windows, `remove-ps1-shims` deletes npm-generated hq-cli `.ps1`
+ *      launchers (and only files whose content is that shim) from the npm
+ *      prefix, outside the HQ tree. Classification is owned by
  *      {@link deriveRemediation};
  *      a content-drift finding is manual-only and simply never appears in the
  *      fixable set.
@@ -44,6 +47,7 @@ import { parseHookGateProfiles, requiredMissingProfiles, } from "../hook-gate-pr
 import { createBackup } from "./backup.js";
 import { removeStrayGateEntries } from "../stray-gate-entries.js";
 import { deriveRemediation } from "./remediation.js";
+import { HQ_CLI_BINS, removeHqCliPs1Shims } from "../../windows/ps1-shims.js";
 import { botDir } from "../../bot/paths.js";
 import { readBotConfig } from "../../bot/config.js";
 import { buildBotDaemonPaths, installedDaemonHqBinary, repairBotDaemonIfStale, rewriteBotDaemonNodePath, } from "../../bot/daemon.js";
@@ -197,6 +201,7 @@ export async function applyFixes(options) {
     };
     const rewriteBotNodePath = options.rewriteBotNodePath ?? defaultRewriteBotNodePath;
     const repairBotHqBinary = options.repairBotHqBinary ?? defaultRepairBotHqBinary;
+    const removePs1Shims = options.removePs1Shims ?? defaultRemovePs1Shims;
     // 2. Collect findings, then plan each newly unlocked allowlisted repair.
     //    Identity is deliberately the check id + target pair: an unsuccessful
     //    repair must not be applied repeatedly in one invocation.
@@ -238,7 +243,7 @@ export async function applyFixes(options) {
             const rem = deriveRemediation(result);
             if (!rem?.autoFixable)
                 continue;
-            const plan = planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath, repairBotHqBinary, refreshManifest);
+            const plan = planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath, repairBotHqBinary, refreshManifest, removePs1Shims);
             if (!plan)
                 continue;
             const key = JSON.stringify([plan.checkId, plan.target]);
@@ -683,8 +688,10 @@ export function uncommittedHookConfigChanges(hqRoot) {
 }
 // --- Fix planning --------------------------------------------------------------
 /** Build the concrete plan for one auto-fixable finding, or null if unplannable. */
-function planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath = defaultRewriteBotNodePath, repairBotHqBinary = defaultRepairBotHqBinary, refreshManifest = defaultRefreshManifest) {
+function planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath = defaultRewriteBotNodePath, repairBotHqBinary = defaultRepairBotHqBinary, refreshManifest = defaultRefreshManifest, removePs1Shims = defaultRemovePs1Shims) {
     switch (rem.fixClass) {
+        case "remove-ps1-shims":
+            return planRemovePs1Shims(result, rem, removePs1Shims);
         case "bot-node-path":
             return planBotNodePath(result, rem, rewriteBotNodePath);
         case "bot-hq-binary":
@@ -753,6 +760,34 @@ function planBotHqBinary(result, rem, repair) {
         postStatus: (results) => results.find((entry) => entry.checkId === result.checkId)?.status ?? null,
     };
 }
+/** Remove npm's hq-cli `.ps1` launchers so PowerShell falls back to `hq.cmd`. */
+function planRemovePs1Shims(result, rem, remove) {
+    const dir = rem.fixTarget;
+    if (!dir)
+        return null;
+    let failure;
+    return {
+        checkId: result.checkId,
+        fixClass: "remove-ps1-shims",
+        target: dir,
+        relpath: "",
+        preview: Object.keys(HQ_CLI_BINS).map((bin) => `  - ${path.win32.join(dir, `${bin}.ps1`)}`).join("\n") +
+            "\n      only npm's hq-cli launchers are removed; hq.cmd stays and the execution policy is not changed",
+        summary: "remove hq .ps1 launchers",
+        apply: () => {
+            const outcome = remove(dir);
+            failure = outcome.failed.length > 0 ? outcome.failed.map((entry) => entry.reason).join("; ") : undefined;
+        },
+        postStatus: (results) => results.find((entry) => entry.checkId === result.checkId)?.status ?? null,
+        failureReason: () => failure,
+    };
+}
+/** Default `remove-ps1-shims` repair: Windows only, a no-op elsewhere. */
+export function defaultRemovePs1Shims(dir) {
+    if (process.platform !== "win32")
+        return { removed: [], kept: [], failed: [] };
+    return removeHqCliPs1Shims(dir);
+}
 /** Real launchctl for the `bot-hq-binary` reload; a failure is a non-ok result. */
 const doctorLaunchctl = (args) => {
     const r = spawnSync("launchctl", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });

package/dist/lib/doctor/fix/remediation.d.ts

@@ -35,6 +35,14 @@
  *                         and hashes); it never writes the HQ tree. A company
  *                         scope whose slug did not resolve locally stays
  *                         manual-only.
+ *   - `remove-ps1-shims` — Windows only: delete the npm-generated `hq.ps1` /
+ *                         `hq-auth-refresh.ps1` launchers from the npm prefix
+ *                         when the PowerShell execution policy blocks them.
+ *                         `hq.cmd` stays and PowerShell falls back to it. The
+ *                         removal only touches files whose content is npm's
+ *                         hq-cli shim (see `lib/windows/ps1-shims.ts`); the
+ *                         execution policy is never changed. This is the one
+ *                         scoped exception to the no-delete rule below.
  *
  * EVERYTHING else — content drift between platform copies, a missing script, a
  * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
@@ -46,7 +54,7 @@
  */
 import type { CheckResult } from "../types.js";
 /** The allowlisted safe repair classes `--fix` is permitted to apply. */
-export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync" | "refresh-manifest" | "bot-node-path" | "bot-hq-binary";
+export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync" | "refresh-manifest" | "bot-node-path" | "bot-hq-binary" | "remove-ps1-shims";
 /**
  * A finding's structured remediation. `autoFixable`, `action`, and `command`
  * are the `--json` surface (AC1); `fixTarget`/`fixClass` are the internal handle