@indigoai-us/hq-cli 5.302.0 → 5.303.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.303.0] — 2026-10-01
+- Fixed bundled shell scripts failing on Windows when Git Bash is installed but `bash` is not on `PATH`.
+- The bundled token usage script now reads Claude sessions from `CLAUDE_CONFIG_DIR/projects` and the standard Claude project directories, including nested session folders (subagent transcripts are skipped), when no project directory is given.
+
 ## [5.302.0] — 2026-10-01
 
 - Generate company project indexes while preserving hand-written content unless `--accept` is used.

package/assets/scaffold/core/scripts/token-usage-report.sh

@@ -12,7 +12,8 @@
 
 set -euo pipefail
 
-PROJECT_DIR="${CLAUDE_PROJECTS_DIR:-$HOME/.claude/projects/-Users-{your-name}-Documents-HQ}"
+PROJECT_DIR=""
+PROJECT_DIR_SET=0
 LAST_DAYS=7
 SINCE=""
 JSON_MODE=0
@@ -31,6 +32,7 @@ while [ $# -gt 0 ]; do
         exit 1
       fi
       PROJECT_DIR="$2"
+      PROJECT_DIR_SET=1
       shift 2
       ;;
     --compare-windows) shift ;;   # flag, presence triggers compare mode via --before/--after
@@ -47,14 +49,47 @@ done
 
 command -v node >/dev/null 2>&1 || { echo "token-usage-report: node is required" >&2; exit 1; }
 
+# Resolve roots in the same precedence order as the native command. Explicit
+# project directories and environment overrides select one exact activity root;
+# otherwise include standard, desktop-saved, and discovered Claude roots.
+PROJECT_DIRS=("")
+add_project_dir() {
+  local candidate="$1" existing
+  [ -d "$candidate" ] || return 0
+  for existing in "${PROJECT_DIRS[@]}"; do [ "$existing" = "$candidate" ] && return 0; done
+  PROJECT_DIRS+=("$candidate")
+}
+trim_env_path() {
+  local value="$1"
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+  printf '%s' "$value"
+}
+if [ "$PROJECT_DIR_SET" -eq 1 ]; then
+  if [ ! -d "$PROJECT_DIR" ]; then echo "Project dir not found: $PROJECT_DIR" >&2; exit 1; fi
+  add_project_dir "$PROJECT_DIR"
+elif [ -n "$(trim_env_path "${CLAUDE_PROJECTS_DIR:-}")" ]; then
+  add_project_dir "$(trim_env_path "${CLAUDE_PROJECTS_DIR:-}")"
+elif [ -n "$(trim_env_path "${CLAUDE_CONFIG_DIR:-}")" ]; then
+  add_project_dir "$(trim_env_path "${CLAUDE_CONFIG_DIR:-}")/projects"
+else
+  add_project_dir "$HOME/.claude/projects"
+  SAVED_PROJECT_DIR="$(node -e 'try { const value = require(process.argv[1]).claudeProjectsDir; if (typeof value === "string" && value.trim()) process.stdout.write(value.trim()); } catch {}' "$HOME/.hq/menubar.json")"
+  [ -z "$SAVED_PROJECT_DIR" ] || add_project_dir "$SAVED_PROJECT_DIR"
+  for candidate in "$HOME"/.claude-*; do
+    [ -d "$candidate/projects" ] && add_project_dir "$candidate/projects"
+  done
+fi
+if [ "${#PROJECT_DIRS[@]}" -le 1 ]; then echo "Claude activity folders not found" >&2; exit 1; fi
+
 # --- Compare-windows mode (US-011) ---
 # Format: --before YYYY-MM-DD:YYYY-MM-DD --after YYYY-MM-DD:YYYY-MM-DD
 if [ -n "$COMPARE_BEFORE" ] && [ -n "$COMPARE_AFTER" ]; then
-  node - "$PROJECT_DIR" "$COMPARE_BEFORE" "$COMPARE_AFTER" "$MIN_HOURS" "$JSON_MODE" <<'JS'
+  node - "$COMPARE_BEFORE" "$COMPARE_AFTER" "$MIN_HOURS" "$JSON_MODE" "${PROJECT_DIRS[@]:1}" <<'JS'
 const fs = require("fs");
 const path = require("path");
 
-const [proj, before, after, minHoursS, jsonModeS] = process.argv.slice(2);
+const [before, after, minHoursS, jsonModeS, ...projectDirs] = process.argv.slice(2);
 const minHours = parseFloat(minHoursS);
 const jsonMode = parseInt(jsonModeS, 10) === 1;
 
@@ -63,13 +98,24 @@ const [bStart, bEnd] = parseRange(before);
 const [aStart, aEnd] = parseRange(after);
 
 const fmt = (n) => n.toLocaleString("en-US");
-const listJsonl = () => {
-  try { return fs.readdirSync(proj).filter((f) => f.endsWith(".jsonl")).sort(); } catch (e) { return []; }
+const listJsonl = (projectDir) => {
+  const found = [];
+  const visit = (current, relative) => {
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch (e) { return; }
+    for (const entry of entries) {
+      const nextRelative = path.join(relative, entry.name);
+      if (entry.isDirectory() && entry.name !== "subagents") visit(path.join(current, entry.name), nextRelative);
+      else if (entry.isFile() && entry.name.endsWith(".jsonl")) found.push(nextRelative);
+    }
+  };
+  visit(projectDir, "");
+  return found.sort();
 };
 
 function collect(windowStart, windowEnd) {
   const rows = [];
-  for (const name of listJsonl()) {
+  for (const proj of projectDirs) for (const name of listJsonl(proj)) {
     const f = path.join(proj, name);
     let cr = 0, firstTs = null, lastTs = null;
     const sid = name.replace(/\.jsonl$/, "");
@@ -130,16 +176,11 @@ JS
   exit 0
 fi
 
-if [ ! -d "$PROJECT_DIR" ]; then
-  echo "Project dir not found: $PROJECT_DIR" >&2
-  exit 1
-fi
-
-node - "$PROJECT_DIR" "$LAST_DAYS" "$SINCE" "$JSON_MODE" <<'JS'
+node - "$LAST_DAYS" "$SINCE" "$JSON_MODE" "${PROJECT_DIRS[@]:1}" <<'JS'
 const fs = require("fs");
 const path = require("path");
 
-const [projectDir, lastDaysS, sinceS, jsonModeS] = process.argv.slice(2);
+const [lastDaysS, sinceS, jsonModeS, ...projectDirs] = process.argv.slice(2);
 const lastDays = parseInt(lastDaysS, 10);
 const jsonMode = parseInt(jsonModeS, 10) === 1;
 
@@ -156,11 +197,20 @@ const fmt = (n) => n.toLocaleString("en-US");
 const dayTotals = {};
 const sessionTotals = {};
 
-let names;
-try { names = fs.readdirSync(projectDir).filter((f) => f.endsWith(".jsonl")).sort(); } catch (e) { names = []; }
-
-// Parent sessions only (top-level *.jsonl)
-for (const name of names) {
+// Parent sessions only; listJsonl skips each session's subagents/ tree.
+for (const projectDir of projectDirs) {
+  const listJsonl = (current, relative = "") => {
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch (e) { return []; }
+    return entries.flatMap((entry) => {
+      const nextRelative = path.join(relative, entry.name);
+      if (entry.isDirectory() && entry.name !== "subagents") return listJsonl(path.join(current, entry.name), nextRelative);
+      if (entry.isFile() && entry.name.endsWith(".jsonl")) return [nextRelative];
+      return [];
+    }).sort();
+  };
+  const names = listJsonl(projectDir);
+  for (const name of names) {
   const f = path.join(projectDir, name);
   let mtime;
   try { mtime = fs.statSync(f).mtime; } catch (e) { continue; }
@@ -170,6 +220,7 @@ for (const name of names) {
   let firstTs = null, lastTs = null, firstUser = "";
   let subCount = 0;
   const sid = name.replace(/\.jsonl$/, "");
+  const sessionId = path.basename(path.dirname(projectDir)) + "/" + sid;
   let content;
   try { content = fs.readFileSync(f, "utf8"); } catch (e) { continue; }
   for (const line of content.split(/\r?\n/)) {
@@ -196,15 +247,16 @@ for (const name of names) {
   if (!day) day = mt;
   if (day < cutoff) continue;
   if (!dayTotals[day]) dayTotals[day] = { sessions: new Set(), inp: 0, out: 0, cc: 0, cr: 0 };
-  dayTotals[day].sessions.add(sid);
+  dayTotals[day].sessions.add(sessionId);
   dayTotals[day].inp += inp;
   dayTotals[day].out += out;
   dayTotals[day].cc += cc;
   dayTotals[day].cr += cr;
-  sessionTotals[sid] = {
+  sessionTotals[sessionId] = {
     day: day, inp: inp, out: out, cc: cc, cr: cr,
     eff: Math.trunc(eff), subagents: subCount, first_user: firstUser.split("\n").join(" "),
   };
+  }
 }
 
 const sortedDays = Object.keys(dayTotals).sort();

package/dist/lib/bot/cli-update.d.ts

@@ -35,16 +35,8 @@ import type { BotLogger } from "./log.js";
 export declare const CLI_UPDATE_RESTART_EXIT_CODE = 75;
 /** How often the installed package.json is read. */
 export declare const CLI_UPDATE_CHECK_INTERVAL_MS = 60000;
-/** Consecutive checks that must agree on the new version before acting. */
-export declare const CLI_UPDATE_CONFIRMATIONS = 2;
-/** At most this many update restarts per window, whatever the versions. */
-export declare const CLI_UPDATE_RESTART_LIMIT = 4;
-export declare const CLI_UPDATE_RESTART_WINDOW_MS: number;
-/** A restart that came back on the old version blocks that target this long. */
-export declare const CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS: number;
 /** Set to "1" to turn the watcher off (development runs). */
 export declare const CLI_UPDATE_DISABLE_ENV = "HQ_BOT_NO_CLI_UPDATE_RESTART";
-export declare const CLI_UPDATE_LEDGER_FILE = "cli-update.json";
 export type InstalledCliRead = {
     ok: true;
     version: string;

package/dist/lib/bot/cli-update.js

@@ -42,15 +42,15 @@ export const CLI_UPDATE_RESTART_EXIT_CODE = 75;
 /** How often the installed package.json is read. */
 export const CLI_UPDATE_CHECK_INTERVAL_MS = 60_000;
 /** Consecutive checks that must agree on the new version before acting. */
-export const CLI_UPDATE_CONFIRMATIONS = 2;
+const CLI_UPDATE_CONFIRMATIONS = 2;
 /** At most this many update restarts per window, whatever the versions. */
-export const CLI_UPDATE_RESTART_LIMIT = 4;
-export const CLI_UPDATE_RESTART_WINDOW_MS = 60 * 60_000;
+const CLI_UPDATE_RESTART_LIMIT = 4;
+const CLI_UPDATE_RESTART_WINDOW_MS = 60 * 60_000;
 /** A restart that came back on the old version blocks that target this long. */
-export const CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS = 6 * 60 * 60_000;
+const CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS = 6 * 60 * 60_000;
 /** Set to "1" to turn the watcher off (development runs). */
 export const CLI_UPDATE_DISABLE_ENV = "HQ_BOT_NO_CLI_UPDATE_RESTART";
-export const CLI_UPDATE_LEDGER_FILE = "cli-update.json";
+const CLI_UPDATE_LEDGER_FILE = "cli-update.json";
 /**
  * The hq-cli version installed behind `entry`, resolved the way the next launch
  * of the same command line will resolve it: follow the symlinks now (a pnpm or

package/dist/lib/bot/local-jobs.d.ts

@@ -18,9 +18,7 @@
  * - A fire is recorded before it is handed over, so a crash never runs the
  *   same due time twice.
  */
-import { type BotApi, type BotJobRecord, type InboxItem, type JobRunCompletion } from "./api.js";
-export declare const LOCAL_JOBS_FILE = "jobs.json";
-export declare const LOCAL_JOB_MESSAGE_PREFIX = "localjob-";
+import { type BotApi, type InboxItem } from "./api.js";
 export interface LocalJob {
     jobId: string;
     prompt: string;
@@ -40,9 +38,7 @@ export interface LocalJob {
     lastStatus?: string;
     runCount?: number;
 }
-export declare function localJobsPath(dir: string): string;
 export declare function readLocalJobs(dir: string): LocalJob[];
-export declare function writeLocalJobs(dir: string, jobs: LocalJob[]): void;
 /**
  * Run a read-change-write of `jobs.json` under an exclusive lock. The running
  * bot (firing, finishing) and `hq bot jobs` (add, remove) are separate
@@ -67,40 +63,24 @@ export interface CronMatcher {
 export declare function toStandardCron(expr: string): string | null;
 /** Parse a standard 5-field cron, or null when it is not one. */
 export declare function parseCron(expr: string): CronMatcher | null;
-export declare function cronMatches(cron: CronMatcher, date: Date, timeZone: string): boolean;
-/**
- * The newest time this job was due, at or before `now` and after the last one
- * already fired. Null when nothing new is due.
- */
-/** `rate(5 minutes)` / `rate(1 hour)` / `rate(2 days)` as milliseconds. */
-export declare function rateIntervalMs(expr: string): number | null;
-export declare function isRunnableSchedule(expr: string): boolean;
 export declare function latestDueFire(job: LocalJob, now: Date): Date | null;
 /** The next time this job is due after `now`, within a week; null otherwise. */
 export declare function nextDueFire(job: LocalJob, now: Date): Date | null;
-export declare function toJobRecord(job: LocalJob, now?: Date): BotJobRecord;
 export declare function addLocalJob(dir: string, input: {
     prompt: string;
     cron: string;
     timezone: string;
     context?: Record<string, unknown>;
 }, now?: Date): LocalJob;
-/** Remove a job. Returns false when the bot has no job with that id. */
-export declare function removeLocalJob(dir: string, jobId: string): boolean;
 /** Forget the once-per-minute check (tests, and a bot restarted in-process). */
 export declare function resetLocalJobChecks(): void;
 export declare function takeDueLocalJobRuns(dir: string, now?: Date): InboxItem[];
-export declare function isLocalJobMessage(messageId: string): boolean;
-/** Record how a local run finished and release the job for its next fire. */
-export declare function finishLocalJobRun(dir: string, jobId: string, messageId: string, completion: Pick<JobRunCompletion, "status">, now?: Date): void;
 /**
  * The bot's cloud client, with its scheduled runs answered on this computer:
  * due local jobs join the inbox, and their ack and completion are recorded
  * locally instead of being sent to the cloud.
  */
 export declare function withLocalJobs(api: BotApi, dir: string, clock?: () => Date): BotApi;
-/** The most jobs one bot may hold (the same cap the cloud uses). */
-export declare const MAX_LOCAL_JOBS = 25;
 /**
  * `hq bot jobs` against the bot's own folder: the same three calls the cloud
  * client offers, answered from `jobs.json`.

package/dist/lib/bot/local-jobs.js

@@ -22,15 +22,15 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import { BotApiError } from "./api.js";
-export const LOCAL_JOBS_FILE = "jobs.json";
-export const LOCAL_JOB_MESSAGE_PREFIX = "localjob-";
+const LOCAL_JOBS_FILE = "jobs.json";
+const LOCAL_JOB_MESSAGE_PREFIX = "localjob-";
 /** How far back a missed fire is still looked for (one week). */
 const LOOKBACK_MINUTES = 7 * 24 * 60;
 /** A run that never reported back releases its job after this long. */
 const IN_FLIGHT_RELEASE_MS = 60 * 60 * 1000;
 /** A fire is "late" (a catch-up) once this long past its due time. */
 const STALE_AFTER_MS = 10 * 60 * 1000;
-export function localJobsPath(dir) {
+function localJobsPath(dir) {
     return path.join(dir, LOCAL_JOBS_FILE);
 }
 export function readLocalJobs(dir) {
@@ -42,7 +42,7 @@ export function readLocalJobs(dir) {
         return [];
     }
 }
-export function writeLocalJobs(dir, jobs) {
+function writeLocalJobs(dir, jobs) {
     const file = localJobsPath(dir);
     const tmp = `${file}.${process.pid}.tmp`;
     fs.writeFileSync(tmp, JSON.stringify({ v: 1, jobs }, null, 2));
@@ -210,7 +210,7 @@ function zonedParts(date, timeZone) {
         weekday: WEEKDAY[get("weekday")] ?? -1,
     };
 }
-export function cronMatches(cron, date, timeZone) {
+function cronMatches(cron, date, timeZone) {
     const t = zonedParts(date, timeZone);
     if (!cron.minutes.has(t.minute) || !cron.hours.has(t.hour) || !cron.months.has(t.month))
         return false;
@@ -226,7 +226,7 @@ export function cronMatches(cron, date, timeZone) {
  * already fired. Null when nothing new is due.
  */
 /** `rate(5 minutes)` / `rate(1 hour)` / `rate(2 days)` as milliseconds. */
-export function rateIntervalMs(expr) {
+function rateIntervalMs(expr) {
     const match = /^rate\((\d+)\s+(minute|minutes|hour|hours|day|days)\)$/.exec(expr.trim());
     if (!match)
         return null;
@@ -234,7 +234,7 @@ export function rateIntervalMs(expr) {
     const unit = match[2].startsWith("minute") ? 60_000 : match[2].startsWith("hour") ? 3_600_000 : 86_400_000;
     return n > 0 ? n * unit : null;
 }
-export function isRunnableSchedule(expr) {
+function isRunnableSchedule(expr) {
     return rateIntervalMs(expr) !== null || parseCron(expr) !== null;
 }
 export function latestDueFire(job, now) {
@@ -281,7 +281,7 @@ export function nextDueFire(job, now) {
     return null;
 }
 // ─── The job list (what `hq bot jobs` reads and writes) ──────────────────────
-export function toJobRecord(job, now = new Date()) {
+function toJobRecord(job, now = new Date()) {
     const next = nextDueFire(job, now);
     return {
         jobId: job.jobId,
@@ -311,7 +311,7 @@ export function addLocalJob(dir, input, now = new Date()) {
     return job;
 }
 /** Remove a job. Returns false when the bot has no job with that id. */
-export function removeLocalJob(dir, jobId) {
+function removeLocalJob(dir, jobId) {
     return withJobsLock(dir, () => {
         const jobs = readLocalJobs(dir);
         const next = jobs.filter((job) => job.jobId !== jobId);
@@ -375,11 +375,11 @@ export function takeDueLocalJobRuns(dir, now = new Date()) {
         return items;
     });
 }
-export function isLocalJobMessage(messageId) {
+function isLocalJobMessage(messageId) {
     return messageId.startsWith(LOCAL_JOB_MESSAGE_PREFIX);
 }
 /** Record how a local run finished and release the job for its next fire. */
-export function finishLocalJobRun(dir, jobId, messageId, completion, now = new Date()) {
+function finishLocalJobRun(dir, jobId, messageId, completion, now = new Date()) {
     withJobsLock(dir, () => {
         const jobs = readLocalJobs(dir);
         let changed = false;
@@ -428,7 +428,7 @@ export function withLocalJobs(api, dir, clock = () => new Date()) {
     return local;
 }
 /** The most jobs one bot may hold (the same cap the cloud uses). */
-export const MAX_LOCAL_JOBS = 25;
+const MAX_LOCAL_JOBS = 25;
 /**
  * `hq bot jobs` against the bot's own folder: the same three calls the cloud
  * client offers, answered from `jobs.json`.

package/dist/lib/daemon/config.d.ts

@@ -23,7 +23,6 @@ export interface DaemonConfig {
 }
 export type SyncOwner = "daemon" | "desktop-app";
 export declare function effectiveSyncOwner(config: Pick<DaemonConfig, "syncOwner">, machineType: MachineType): SyncOwner;
-export declare function emptyDaemonConfig(): DaemonConfig;
 export declare function readDaemonConfig(file: string): DaemonConfig;
 export declare function writeDaemonConfig(file: string, config: DaemonConfig): void;
 /**

package/dist/lib/daemon/config.js

@@ -13,7 +13,7 @@ import { ensurePrivateDir } from "./paths.js";
 export function effectiveSyncOwner(config, machineType) {
     return config.syncOwner ?? (machineType === "desktop" ? "desktop-app" : "daemon");
 }
-export function emptyDaemonConfig() {
+function emptyDaemonConfig() {
     return { version: 1, syncPaused: false, enable: [], disable: [] };
 }
 function stringList(value) {

package/dist/lib/report-snapshot.d.ts

@@ -1,7 +1,5 @@
 /** File name of the snapshot inside the published report. */
 export declare const REPORT_PREVIEW_FILE = "hq-preview.png";
-export declare const REPORT_PREVIEW_WIDTH = 1280;
-export declare const REPORT_PREVIEW_HEIGHT = 720;
 /** First installed browser that can take a snapshot, or null. */
 export declare function findSnapshotBrowser(env?: NodeJS.ProcessEnv, platform?: string, exists?: (file: string) => boolean): string | null;
 export declare function snapshotArgs(indexFile: string, outFile: string, profileDir: string): string[];

package/dist/lib/report-snapshot.js

@@ -13,8 +13,8 @@ import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 /** File name of the snapshot inside the published report. */
 export const REPORT_PREVIEW_FILE = "hq-preview.png";
-export const REPORT_PREVIEW_WIDTH = 1280;
-export const REPORT_PREVIEW_HEIGHT = 720;
+const REPORT_PREVIEW_WIDTH = 1280;
+const REPORT_PREVIEW_HEIGHT = 720;
 const SNAPSHOT_TIMEOUT_MS = 30_000;
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
 const BROWSER_PATHS = {

package/dist/utils/run-bundled-script.js

@@ -29,6 +29,7 @@
  *     script needs to see termination, not a success code.
  */
 import { spawnSync } from "child_process";
+import * as fs from "node:fs";
 import * as path from "path";
 import { resolveBundledAsset } from "./hq-roots.js";
 /**
@@ -41,6 +42,93 @@ export function interpreterFor(asset) {
     const ext = path.extname(asset).toLowerCase();
     return ext === ".mjs" || ext === ".js" || ext === ".cjs" ? "node" : "bash";
 }
+function envValue(env, name) {
+    const key = Object.keys(env).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+    return key ? env[key] : undefined;
+}
+function isFile(file, lookupErrors) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch (error) {
+        // Missing PATH candidates are expected during lookup; retain the cause so
+        // the final actionable error can expose why no interpreter was resolved.
+        lookupErrors.push(error);
+        return false;
+    }
+}
+function isWithinWindowsDirectory(file, directory) {
+    const normalizedFile = path.win32.resolve(file).toLowerCase();
+    const normalizedDirectory = path.win32.resolve(directory).toLowerCase();
+    return (normalizedFile === normalizedDirectory ||
+        normalizedFile.startsWith(`${normalizedDirectory}${path.win32.sep}`));
+}
+function isExcludedWindowsBash(file, env) {
+    if (path.win32.basename(file).toLowerCase() !== "bash.exe")
+        return false;
+    const windowsDir = envValue(env, "SystemRoot") ?? envValue(env, "WINDIR") ?? "C:\\Windows";
+    const systemBash = path.win32.resolve(windowsDir, "System32", "bash.exe");
+    if (path.win32.resolve(file).toLowerCase() === systemBash.toLowerCase())
+        return true;
+    const localAppData = envValue(env, "LOCALAPPDATA");
+    return Boolean(localAppData &&
+        isWithinWindowsDirectory(file, path.win32.resolve(localAppData, "Microsoft", "WindowsApps")));
+}
+function findOnWindowsPath(executable, env, lookupErrors) {
+    const pathValue = envValue(env, "PATH") ?? "";
+    const extensions = executable.includes(".")
+        ? [""]
+        : (envValue(env, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD")
+            .split(";")
+            .filter(Boolean)
+            .map((ext) => ext.toLowerCase());
+    for (const entry of pathValue.split(";").filter(Boolean)) {
+        const directory = entry.trim().replace(/^"|"$/g, "");
+        for (const extension of extensions) {
+            const candidate = path.win32.join(directory, `${executable}${extension}`);
+            if (!isExcludedWindowsBash(candidate, env) && isFile(candidate, lookupErrors))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+function resolveWindowsBash(env) {
+    const lookupErrors = [];
+    const configured = envValue(env, "CLAUDE_CODE_GIT_BASH_PATH");
+    if (configured && !isExcludedWindowsBash(configured, env) && isFile(configured, lookupErrors)) {
+        return { executable: configured, cause: lookupErrors.at(-1) };
+    }
+    const pathBash = findOnWindowsPath("bash", env, lookupErrors);
+    if (pathBash)
+        return { executable: pathBash, cause: lookupErrors.at(-1) };
+    const gitExe = findOnWindowsPath("git.exe", env, lookupErrors);
+    if (gitExe) {
+        const derived = path.win32.resolve(path.win32.dirname(gitExe), "..", "bin", "bash.exe");
+        if (!isExcludedWindowsBash(derived, env) && isFile(derived, lookupErrors)) {
+            return { executable: derived, cause: lookupErrors.at(-1) };
+        }
+    }
+    const programFiles = envValue(env, "ProgramFiles") ?? "C:\\Program Files";
+    const localAppData = envValue(env, "LOCALAPPDATA");
+    const standardPaths = [
+        path.win32.join(programFiles, "Git", "bin", "bash.exe"),
+        ...(localAppData ? [path.win32.join(localAppData, "Programs", "Git", "bin", "bash.exe")] : []),
+    ];
+    const executable = standardPaths.find((candidate) => !isExcludedWindowsBash(candidate, env) && isFile(candidate, lookupErrors));
+    return {
+        executable,
+        cause: lookupErrors.at(-1) ??
+            Object.assign(new Error("Bash was not found (ENOENT)"), { code: "ENOENT" }),
+    };
+}
+function bashNotFoundError(asset, cause) {
+    const isHandoff = asset.replaceAll("\\", "/").endsWith("core/scripts/handoff-finalize.sh");
+    const recovery = isHandoff
+        ? "The handoff was not saved; rerun the command."
+        : "The script did not run; rerun this command.";
+    return new Error(`Bash was not found to run bundled script ${asset}. Install Git for Windows or ` +
+        `set CLAUDE_CODE_GIT_BASH_PATH. ${recovery}`, { cause });
+}
 /**
  * Execute a bundled scaffold script and return its exit code.
  *
@@ -56,12 +144,26 @@ export function runBundledScript(opts) {
         env.CLAUDE_PROJECT_DIR = opts.hqRoot;
     }
     Object.assign(env, opts.env ?? {});
-    const result = spawnSync(interpreterFor(opts.asset), [script, ...(opts.args ?? [])], {
+    const interpreter = interpreterFor(opts.asset);
+    const windowsBash = process.platform === "win32" && interpreter === "bash"
+        ? resolveWindowsBash(env)
+        : undefined;
+    const executable = windowsBash?.executable ?? interpreter;
+    if (windowsBash && !windowsBash.executable) {
+        throw bashNotFoundError(opts.asset, windowsBash.cause);
+    }
+    const result = spawnSync(executable, [script, ...(opts.args ?? [])], {
         cwd: opts.cwd,
         env,
         stdio: "inherit",
     });
     if (result.error) {
+        const spawnError = result.error;
+        if (process.platform === "win32" &&
+            interpreter === "bash" &&
+            spawnError.code === "ENOENT") {
+            throw bashNotFoundError(opts.asset, spawnError);
+        }
         throw new Error(`Failed to run bundled script ${opts.asset}: ${result.error.message}`);
     }
     if (result.signal) {

package/package.json

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