@indigoai-us/hq-cli 5.302.0 → 5.304.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.304.0] — 2026-10-01
+- `hq lanes show` skips owner refresh only when a failed Outpost dispatch explicitly recorded `pickup_persisted: false` and no owner heartbeat; it reports `remote_refresh: "skipped_undispatched"` in that case.
+
+## [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/commands/lanes.d.ts

@@ -132,6 +132,8 @@ export declare function parseMaxRuntimeSeconds(raw: unknown, workerId: string):
 export declare const PICKUP_TERMINAL_REASONS: readonly ["account_not_logged_in", "unknown_account", "account_disabled", "model_unsupported"];
 export declare const DISPATCH_TERMINAL_REASON: "outpost_dispatch_failed";
 export type PickupTerminalReason = (typeof PICKUP_TERMINAL_REASONS)[number];
+/** Only explicit non-persistence evidence can prove a failed dispatch has no owner snapshot. */
+export declare function isUndispatchedOutpostMirror(lane: LaneRecord): boolean;
 /**
  * The CAS updater a pickup failure applies. A lane that is already terminal
  * for any reason (a cancel that landed after the caller's last read, an

package/dist/commands/lanes.js

@@ -1284,9 +1284,7 @@ async function refreshRemoteLaneMirrors(ctx, hqRoot, records, parentLaneIds, opt
         ((parentLaneIds === undefined || (lane.senior.kind === "lane" &&
             lane.senior.id !== undefined &&
             parentLaneIds.has(lane.senior.id))) || options.laneIds?.has(lane.lane_id) === true) &&
-        !(isTerminalLaneState(lane.state) &&
-            lane.terminal_reason === DISPATCH_TERMINAL_REASON &&
-            lane.last_host_report_at === undefined) &&
+        !isUndispatchedOutpostMirror(lane) &&
         (options.includeTerminalMirrors === true || !isTerminalLaneState(lane.state)))
         .sort((a, b) => {
         const terminalOrder = Number(isTerminalLaneState(a.state)) - Number(isTerminalLaneState(b.state));
@@ -2524,6 +2522,14 @@ export const PICKUP_TERMINAL_REASONS = [
     "model_unsupported",
 ];
 export const DISPATCH_TERMINAL_REASON = "outpost_dispatch_failed";
+/** Only explicit non-persistence evidence can prove a failed dispatch has no owner snapshot. */
+export function isUndispatchedOutpostMirror(lane) {
+    return lane.host.kind === "outpost" &&
+        isTerminalLaneState(lane.state) &&
+        lane.terminal_reason === DISPATCH_TERMINAL_REASON &&
+        lane.terminal_details?.pickup_persisted === false &&
+        lane.last_host_report_at == null;
+}
 function parsePickupTerminalReason(value) {
     if (PICKUP_TERMINAL_REASONS.includes(value)) {
         return value;
@@ -3647,6 +3653,9 @@ async function dispatchCreatedOutpostLane(ctx, input) {
                 command_id: dispatched.commandId,
                 exit_code: dispatched.exitCode,
                 status: dispatched.status,
+                ...(remote?.pickup_persisted === false || ownerError.details.pickup_persisted === false
+                    ? { pickup_persisted: false }
+                    : {}),
                 owner_error: ownerError,
             });
             await emitLaneTerminalStateSoft(ctx, failed);
@@ -5038,13 +5047,17 @@ async function runOutpostIdentityBackfillTarget(ctx, opts) {
 }
 async function refreshOutpostLaneCopiesForShow(ctx, lane, localLanes) {
     if (lane.host.kind !== "outpost" || laneRunsHere(lane, reconcileHostFromCtx(ctx))) {
-        return lane;
+        return { lane };
+    }
+    if (isUndispatchedOutpostMirror(lane)) {
+        return { lane, remoteRefresh: "skipped_undispatched" };
     }
     const outpostId = lane.host.id;
     const descendantIds = localLanes
         .filter((candidate) => candidate.lane_id !== lane.lane_id &&
         candidate.host.kind === "outpost" && candidate.host.id === outpostId &&
         walkHitsLane(ctx.hqRoot(), candidate.senior, lane.lane_id, ctx))
+        .filter((candidate) => !isUndispatchedOutpostMirror(candidate))
         .map((candidate) => candidate.lane_id);
     const refresh = async (laneId) => {
         try {
@@ -5061,13 +5074,14 @@ async function refreshOutpostLaneCopiesForShow(ctx, lane, localLanes) {
     };
     const refreshed = await mapWithConcurrency([lane.lane_id, ...descendantIds], OUTPOST_HIRE_SUMMARY_CONCURRENCY, refresh);
     const refreshedLane = refreshed[0] ?? null;
-    return refreshedLane ?? lane;
+    return { lane: refreshedLane ?? lane };
 }
 async function runShow(ctx, laneId, hasPendingQuestionForLane) {
     const hqRoot = ctx.hqRoot();
     const initialLane = readLane(hqRoot, laneId);
     const initialLanes = loadAllLanes(hqRoot);
-    const storedLane = await refreshOutpostLaneCopiesForShow(ctx, initialLane, initialLanes);
+    const showRefresh = await refreshOutpostLaneCopiesForShow(ctx, initialLane, initialLanes);
+    const storedLane = showRefresh.lane;
     const allLanes = loadAllLanes(hqRoot);
     const hire = await laneHirePresentation(ctx, storedLane, allLanes);
     const remoteQueued = storedLane.state === "queued" &&
@@ -5152,6 +5166,7 @@ async function runShow(ctx, laneId, hasPendingQuestionForLane) {
         stalled_reason: lane.stalled_reason ?? null,
         ask_delivery_failed: askDeliveryFailed,
         delivery,
+        ...(showRefresh.remoteRefresh === undefined ? {} : { remote_refresh: showRefresh.remoteRefresh }),
         provider_session_id: lane.provider_session_id ?? null,
         provider_session_id_absent: lane.provider_session_id_absent ?? null,
         envelope_repair_mode: lane.envelope_repair?.mode ?? null,

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/doctor/deep/executor.d.ts

@@ -55,7 +55,7 @@ export declare const DEFAULT_PER_CASE_TIMEOUT_MS = 10000;
  */
 export declare const SANDBOX_COPY_RELPATHS: readonly string[];
 /** One gate execution's inputs. */
-export interface GateRunInput {
+interface GateRunInput {
     /** Absolute path to the sandboxed `hook-gate.sh`. */
     gatePath: string;
     /** Absolute path to the sandboxed hook script the gate delegates to. */
@@ -72,7 +72,7 @@ export interface GateRunInput {
     timeoutMs: number;
 }
 /** One gate execution's observed outcome. */
-export interface GateRunResult {
+interface GateRunResult {
     /** True when the execution exceeded {@link GateRunInput.timeoutMs}. */
     timedOut: boolean;
     /** Gate exit code, or null when it did not exit normally (timeout/signal). */
@@ -81,14 +81,7 @@ export interface GateRunResult {
     stderr: string;
 }
 /** Executes one gate invocation. Injectable so the aggregation is unit-testable. */
-export type GateRunner = (input: GateRunInput) => GateRunResult;
-/**
- * The real runner: spawn `bash hook-gate.sh <id> <script>` with the payload on
- * stdin, `HQ_HOOK_PROFILE` set, and a hard timeout. A timeout is detected by the
- * `ETIMEDOUT` error code spawnSync reports; the process is killed with SIGKILL so
- * a hook cannot ignore the bound.
- */
-export declare const defaultGateRunner: GateRunner;
+type GateRunner = (input: GateRunInput) => GateRunResult;
 /** Options for {@link runDeepGuardTests}. All are injectable for testing. */
 export interface DeepTestOptions {
     /** Per-case time bound. Default: {@link DEFAULT_PER_CASE_TIMEOUT_MS}. */
@@ -109,4 +102,5 @@ export declare function cleanupAllDeepSandboxes(): void;
  * an empty list — creating no sandbox — when there is nothing to run.
  */
 export declare function runDeepGuardTests(context: CheckContext, options?: DeepTestOptions): Promise<CheckResult[]>;
+export {};
 //# sourceMappingURL=executor.d.ts.map

package/dist/lib/doctor/deep/executor.js

@@ -74,7 +74,7 @@ export const SANDBOX_COPY_RELPATHS = [
  * `ETIMEDOUT` error code spawnSync reports; the process is killed with SIGKILL so
  * a hook cannot ignore the bound.
  */
-export const defaultGateRunner = (input) => {
+const defaultGateRunner = (input) => {
     const result = spawnSync("bash", [input.gatePath, input.hookId, input.hookScriptPath], {
         input: input.payload,
         cwd: input.cwd,

package/dist/lib/doctor/deep/parity.d.ts

@@ -46,14 +46,6 @@ import { type PlatformId } from "../payload-shapes.js";
 export declare const PARITY_FAMILY_ID = "deep-parity";
 /** Human title of the parity family. */
 export declare const PARITY_FAMILY_TITLE = "Cross-platform parity replay";
-/** Default per-case, per-platform time bound. */
-export declare const DEFAULT_PARITY_TIMEOUT_MS = 10000;
-/** The gate profile the replay runs each hook under. Strict is the broadest
- * allowlist, so profile gating never suppresses the hook whose LOGIC is being
- * compared across platforms — profile-specific behaviour is US-008's concern. */
-export declare const PARITY_GATE_PROFILE = "strict";
-/** The session id stamped onto every replay payload. */
-export declare const PARITY_SESSION_ID = "hq-doctor-parity-replay";
 /** One platform replay's inputs. */
 export interface PlatformRunInput {
     /** Which platform's adapter path to exercise. */
@@ -85,27 +77,7 @@ export interface PlatformRunOutput {
 /** Executes one platform replay. Injectable so the comparison is unit-testable. */
 export type PlatformRunner = (input: PlatformRunInput) => PlatformRunOutput;
 /** The real runner set, keyed by platform. */
-export type PlatformRunners = Record<PlatformId, PlatformRunner>;
-/** The real Claude runner: the canonical script through the Claude gate. */
-export declare const defaultClaudeRunner: PlatformRunner;
-/** The real Codex runner: the duplicated mirror through the Codex gate. */
-export declare const defaultCodexRunner: PlatformRunner;
-/**
- * The real Grok runner. Grok shares the canonical `.claude/hooks/` scripts with
- * Claude — it has no mirror of its own — and its adapter's whole job is to read
- * the camelCase payload, map the tool alias back to canonical, build the Claude
- * JSON, and pipe it to the same `hook-gate.sh`. We reproduce that routing here
- * (via {@link toGrokPayload} + {@link grokToSnakePayload}) rather than spawn the
- * adapter directly, for two reasons: the live adapter runs a whole tool
- * *sequence* where the replay needs one isolated hook, and its user-global
- * bridge cannot be simulated from a project-local run (US-005 keeps bridge
- * presence a wiring check). The Grok block protocol still applies — the gate's
- * non-zero exit is what the adapter would translate into a stdout `deny`
- * ({@link interpretGrokBlock} in verdictFor recognises both).
- */
-export declare const defaultGrokRunner: PlatformRunner;
-/** The default real runner set wired to each platform's real adapter path. */
-export declare const defaultPlatformRunners: PlatformRunners;
+type PlatformRunners = Record<PlatformId, PlatformRunner>;
 /** Options for {@link runParityReplay}. All injectable for testing. */
 export interface ParityOptions {
     /** Per-case, per-platform time bound. Default: {@link DEFAULT_PARITY_TIMEOUT_MS}. */
@@ -126,4 +98,5 @@ export declare function cleanupAllParitySandboxes(): void;
  * empty list — creating no sandbox — when there is nothing to replay.
  */
 export declare function runParityReplay(context: CheckContext, options?: ParityOptions): Promise<CheckResult[]>;
+export {};
 //# sourceMappingURL=parity.d.ts.map

package/dist/lib/doctor/deep/parity.js

@@ -52,13 +52,13 @@ export const PARITY_FAMILY_ID = "deep-parity";
 /** Human title of the parity family. */
 export const PARITY_FAMILY_TITLE = "Cross-platform parity replay";
 /** Default per-case, per-platform time bound. */
-export const DEFAULT_PARITY_TIMEOUT_MS = 10_000;
+const DEFAULT_PARITY_TIMEOUT_MS = 10_000;
 /** The gate profile the replay runs each hook under. Strict is the broadest
  * allowlist, so profile gating never suppresses the hook whose LOGIC is being
  * compared across platforms — profile-specific behaviour is US-008's concern. */
-export const PARITY_GATE_PROFILE = "strict";
+const PARITY_GATE_PROFILE = "strict";
 /** The session id stamped onto every replay payload. */
-export const PARITY_SESSION_ID = "hq-doctor-parity-replay";
+const PARITY_SESSION_ID = "hq-doctor-parity-replay";
 function spawnWithStdin(command, args, stdin, input) {
     const result = spawnSync(command, args, {
         input: stdin,
@@ -96,12 +96,12 @@ function runThroughGate(input, platformDir, payload) {
     return { ...spawned };
 }
 /** The real Claude runner: the canonical script through the Claude gate. */
-export const defaultClaudeRunner = (input) => runThroughGate(input, ".claude", JSON.stringify(toClaudePayload(input.testCase, {
+const defaultClaudeRunner = (input) => runThroughGate(input, ".claude", JSON.stringify(toClaudePayload(input.testCase, {
     cwd: input.sandbox,
     sessionId: PARITY_SESSION_ID,
 })));
 /** The real Codex runner: the duplicated mirror through the Codex gate. */
-export const defaultCodexRunner = (input) => runThroughGate(input, ".codex", JSON.stringify(toCodexPayload(input.testCase, {
+const defaultCodexRunner = (input) => runThroughGate(input, ".codex", JSON.stringify(toCodexPayload(input.testCase, {
     cwd: input.sandbox,
     sessionId: PARITY_SESSION_ID,
 })));
@@ -118,7 +118,7 @@ export const defaultCodexRunner = (input) => runThroughGate(input, ".codex", JSO
  * non-zero exit is what the adapter would translate into a stdout `deny`
  * ({@link interpretGrokBlock} in verdictFor recognises both).
  */
-export const defaultGrokRunner = (input) => {
+const defaultGrokRunner = (input) => {
     const grokPayload = toGrokPayload(input.testCase, {
         cwd: input.sandbox,
         sessionId: PARITY_SESSION_ID,
@@ -127,7 +127,7 @@ export const defaultGrokRunner = (input) => {
     return runThroughGate(input, ".claude", JSON.stringify(snake));
 };
 /** The default real runner set wired to each platform's real adapter path. */
-export const defaultPlatformRunners = {
+const defaultPlatformRunners = {
     claude: defaultClaudeRunner,
     codex: defaultCodexRunner,
     grok: defaultGrokRunner,

package/dist/lib/doctor/deep/sandbox.d.ts

@@ -46,21 +46,10 @@ export declare const DEFAULT_PER_CASE_TIMEOUT_MS = 15000;
  * come under sandboxed execution.
  */
 export type Precondition = "git-repo" | "session-metadata" | "company-scaffold";
-/** Every precondition the default seeder knows how to provide. */
-export declare const KNOWN_PRECONDITIONS: readonly Precondition[];
-/**
- * Tree entries copied from the live tree into every sandbox — the same curated
- * set US-008 uses: the hook scripts and gate, the settings a hook may read, the
- * Codex/Grok mirrors, and `core/` (helpers hooks source). Missing entries are
- * skipped so a partial tree still sandboxes cleanly.
- */
-export declare const SANDBOX_SEED_RELPATHS: readonly string[];
 /** Remove every side-effect sandbox still on disk. Safe to call repeatedly. */
 export declare function cleanupAllSandboxes(): void;
 /** The sandbox roots this process is still tracking (for tests). */
 export declare function trackedSandboxRoots(): string[];
-/** Remove one sandbox and stop tracking it. Idempotent. */
-export declare function destroySandbox(root: string): void;
 /** The outcome of seeding one sandbox. */
 export interface SeedResult {
     /** Absolute, realpath'd sandbox root under the OS temp dir. */
@@ -91,7 +80,7 @@ export interface SeedOptions {
  */
 export declare function seedSandbox(hqRoot: string, opts?: SeedOptions): SeedResult;
 /** One hook execution's inputs. */
-export interface HookRunInput {
+interface HookRunInput {
     /** Absolute path to the sandboxed hook script. */
     hookScriptPath: string;
     /** The JSON payload piped to the hook's stdin. */
@@ -104,7 +93,7 @@ export interface HookRunInput {
     timeoutMs: number;
 }
 /** One hook execution's observed result (exit code is diagnostic only). */
-export interface HookRunResult {
+interface HookRunResult {
     /** True when the execution exceeded {@link HookRunInput.timeoutMs}. */
     timedOut: boolean;
     /** Exit code, or null when it did not exit normally (timeout/signal). */
@@ -113,17 +102,9 @@ export interface HookRunResult {
     stderr: string;
 }
 /** Runs one hook. Injectable so the tier's aggregation is unit-testable. */
-export type HookRunner = (input: HookRunInput) => HookRunResult;
-/**
- * The real runner: fire the hook script directly with the payload on stdin, its
- * cwd and session env pointed at the sandbox, and a hard timeout. Unlike a pure
- * guard (US-008), a side-effecting hook is run directly rather than through the
- * gate — its exit code is irrelevant here; what matters is the effect it leaves
- * on the sandbox, which effects.ts reads afterwards.
- */
-export declare const defaultHookRunner: HookRunner;
+type HookRunner = (input: HookRunInput) => HookRunResult;
 /** One parsed side-effecting fixture case (its own shape, not the US-007 schema). */
-export interface SideEffectCase {
+interface SideEffectCase {
     name: string;
     event: string;
     tool: string;
@@ -136,13 +117,13 @@ export interface SideEffectCase {
     expectedFailure?: ExpectedFailure;
 }
 /** A validated side-effecting fixture. */
-export interface SideEffectFixture {
+interface SideEffectFixture {
     hookId: string;
     relpath: string;
     cases: SideEffectCase[];
 }
 /** A side-effecting fixture that could not be parsed. */
-export interface SideEffectFixtureError {
+interface SideEffectFixtureError {
     hookId: string | null;
     relpath: string;
     message: string;
@@ -187,4 +168,5 @@ export interface SideEffectTestOptions {
  * Returns an empty list when there is nothing side-effecting to run.
  */
 export declare function runSideEffectTests(context: CheckContext, options?: SideEffectTestOptions): Promise<CheckResult[]>;
+export {};
 //# sourceMappingURL=sandbox.d.ts.map

package/dist/lib/doctor/deep/sandbox.js

@@ -46,7 +46,7 @@ import { captureEffectBaseline, describeEffect, defaultGitProbe, evaluateEffects
 /** Default per-case time bound. No latency target, but no case may hang. */
 export const DEFAULT_PER_CASE_TIMEOUT_MS = 15_000;
 /** Every precondition the default seeder knows how to provide. */
-export const KNOWN_PRECONDITIONS = [
+const KNOWN_PRECONDITIONS = [
     "git-repo",
     "session-metadata",
     "company-scaffold",
@@ -57,7 +57,7 @@ export const KNOWN_PRECONDITIONS = [
  * Codex/Grok mirrors, and `core/` (helpers hooks source). Missing entries are
  * skipped so a partial tree still sandboxes cleanly.
  */
-export const SANDBOX_SEED_RELPATHS = [
+const SANDBOX_SEED_RELPATHS = [
     ".claude/hooks",
     ".claude/settings.json",
     ".claude/settings.local.json",
@@ -100,7 +100,7 @@ function removeTree(root) {
     }
 }
 /** Remove one sandbox and stop tracking it. Idempotent. */
-export function destroySandbox(root) {
+function destroySandbox(root) {
     removeTree(root);
     trackedSandboxes.delete(root);
 }
@@ -198,7 +198,7 @@ function git(root, args) {
  * gate — its exit code is irrelevant here; what matters is the effect it leaves
  * on the sandbox, which effects.ts reads afterwards.
  */
-export const defaultHookRunner = (input) => {
+const defaultHookRunner = (input) => {
     const result = spawnSync("bash", [input.hookScriptPath], {
         input: input.payload,
         cwd: input.cwd,

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