@indigoai-us/hq-cli 5.345.102 → 5.345.103

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.345.103] — 2026-10-12
+- On Macs, idle `hq lanes` work no longer sits queued on the memory throttle
+  just because reclaimable cache made free RAM look too low.
+
 ## [5.345.102] — 2026-10-12
 - Session-start health no longer files a leftover company journal as an
   unrepaired doctor finding, and company manifest rows keep a real check id

package/dist/lib/lanes/index.d.ts

@@ -36,7 +36,7 @@ export { ENVELOPE_INVALID_REASON, decideEnvelopeRepair, emitMeshSoft, envelopeQu
 export type { EnvelopeRepairDecision, LatestEnvelopeFile } from "./watcher.js";
 export { LANE_MESH_EVENTS, WIRE_EVENT_KINDS, createLaneMesh, emitLaneDecisionEvents, emitLaneProgressEvent, laneCanEmit, parseLaneMeshEvent, progressEventDue, toWireThreadEvent, } from "./mesh-events.js";
 export type { CreateLaneMeshOptions, LaneMesh, LaneMeshEvent, WireEventKind, WireThreadEvent, } from "./mesh-events.js";
-export { CPU_SAMPLE_MS, LANES_CPU_BUSY_OVERRIDE, LANES_CPU_CHECK, PROC_MEMINFO, STARVATION_MAX_DEFERRALS, STARVATION_MAX_MS, applyThrottleDecision, busyFractionFromDeltas, cpuTimesSnapshot, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, parseMemAvailableKb, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyFraction, starvationBoundReached, throttleStatePath, writeThrottleState, } from "./throttle.js";
+export { CPU_SAMPLE_MS, LANES_CPU_BUSY_OVERRIDE, LANES_CPU_CHECK, PROC_MEMINFO, STARVATION_MAX_DEFERRALS, STARVATION_MAX_MS, VM_STAT_BIN, applyThrottleDecision, busyFractionFromDeltas, cpuTimesSnapshot, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, parseMemAvailableKb, parseVmStatAvailableMb, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyFraction, starvationBoundReached, throttleStatePath, writeThrottleState, } from "./throttle.js";
 export type { CpuTimes, ThrottleAdmitReason, ThrottleDecision, ThrottleDeferReason, ThrottleDeps, ThrottleState, } from "./throttle.js";
 export { effectiveAccountHome, } from "./account-home.js";
 export type { EffectiveAccountHome, } from "./account-home.js";

package/dist/lib/lanes/index.js

@@ -20,7 +20,7 @@ export { PID_LIVENESS_DECISIONS, PROVIDER_COMMAND, PROVIDER_MODEL_FLAG, SPAWN_TE
 export { SILENCE_MS, WATCHER_DECISION_EVENTS, WATCHER_OUT_MAX_BYTES, WATCHER_POLL_MS, WATCHER_SIGNAL_KINDS, appendCappedLog, appendWatcherSignal, applyTerminalToLane, classifyLaneExit, clearLaneStalled, isPidAlive, laneIdentityFromRecord, markLaneStalled, notifySlotFreed, parseWatcherSignalKind, readLatestEnvelope, runWatcherLoop, stalledReason, tickWatcher, watcherEventsPath, watcherLastSignalPath, watcherOutLogPath, writeWatcherDecision, } from "./watcher.js";
 export { ENVELOPE_INVALID_REASON, decideEnvelopeRepair, emitMeshSoft, envelopeQuestionIds, readLatestEnvelopeFile, readLatestEnvelopeRecord, } from "./watcher.js";
 export { LANE_MESH_EVENTS, WIRE_EVENT_KINDS, createLaneMesh, emitLaneDecisionEvents, emitLaneProgressEvent, laneCanEmit, parseLaneMeshEvent, progressEventDue, toWireThreadEvent, } from "./mesh-events.js";
-export { CPU_SAMPLE_MS, LANES_CPU_BUSY_OVERRIDE, LANES_CPU_CHECK, PROC_MEMINFO, STARVATION_MAX_DEFERRALS, STARVATION_MAX_MS, applyThrottleDecision, busyFractionFromDeltas, cpuTimesSnapshot, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, parseMemAvailableKb, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyFraction, starvationBoundReached, throttleStatePath, writeThrottleState, } from "./throttle.js";
+export { CPU_SAMPLE_MS, LANES_CPU_BUSY_OVERRIDE, LANES_CPU_CHECK, PROC_MEMINFO, STARVATION_MAX_DEFERRALS, STARVATION_MAX_MS, VM_STAT_BIN, applyThrottleDecision, busyFractionFromDeltas, cpuTimesSnapshot, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, parseMemAvailableKb, parseVmStatAvailableMb, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyFraction, starvationBoundReached, throttleStatePath, writeThrottleState, } from "./throttle.js";
 export { effectiveAccountHome, } from "./account-home.js";
 export { AUTH_JSON_NAME, CLAUDE_CREDENTIALS_NAME, PROVIDER_CREDENTIAL_FILES, PROVIDER_HOME_ENV, accountEnv, accountStatus, authJsonPath, authStateFor, credentialPaths, hasCredentialFile, isCredentialProven, isLoggedOut, isOccupyingLaneState, lastStartedAt, listAccountStatuses, occupyingLaneCount, resolveAccount, runningLaneCount, selectBalancedAccount, } from "./accounts.js";
 export { LIVE_WITHIN_MS, LIVENESS_EVENT_KINDS, SILENT_LOST_MS, TURN_START_LOST_MS, buildLivenessIndexFromSpool, classifySessionLiveness, defaultLivenessDeps, defaultSpoolPath, ingestSpoolLine, listSessionLiveness, livenessIndexPath, loadLivenessIndex, readDaemonPresenceConnected, readLivenessIndex, rebuildLivenessIndex, sessionLiveness, } from "./liveness.js";

package/dist/lib/lanes/throttle.d.ts

@@ -16,6 +16,7 @@ export declare const CPU_SAMPLE_MS = 5000;
 export declare const STARVATION_MAX_DEFERRALS = 10;
 export declare const STARVATION_MAX_MS: number;
 export declare const PROC_MEMINFO = "/proc/meminfo";
+export declare const VM_STAT_BIN = "/usr/bin/vm_stat";
 export declare const LANES_CPU_BUSY_OVERRIDE = "HQ_LANES_CPU_BUSY_OVERRIDE";
 export declare const LANES_CPU_CHECK = "HQ_LANES_CPU_CHECK";
 export interface CpuTimes {
@@ -30,9 +31,19 @@ export interface ThrottleDeps {
     readFileSync: (file: string, encoding: "utf8") => string;
     /**
      * Fallback only where MemAvailable is absent from /proc/meminfo (or the
-     * file itself is missing). Do not use this as the Linux primary reading.
+     * file itself is missing on a non-darwin host). Do not use this as the
+     * Linux primary reading, and do not use it on darwin: os.freemem() there
+     * excludes reclaimable page cache and will hold every lane.
      */
     freemem: () => number;
+    platform: () => NodeJS.Platform;
+    /**
+     * Darwin only: read vm_stat when /proc/meminfo is absent. Unused on Linux.
+     */
+    execFileSync: (file: string, args: readonly string[], options: {
+        encoding: "utf8";
+        timeout: number;
+    }) => string;
     existsSync: (file: string) => boolean;
     mkdirSync: typeof fs.mkdirSync;
     writeFileSync: typeof fs.writeFileSync;
@@ -70,8 +81,15 @@ export declare function recordCpuBusyObservation(state: ThrottleState, observati
 /** Parse MemAvailable kB from /proc/meminfo. */
 export declare function parseMemAvailableKb(contents: string): number | null;
 /**
- * Available memory in MiB. Prefers kernel MemAvailable; falls back to
- * os.freemem() only where MemAvailable is absent.
+ * Available memory in MiB from darwin `vm_stat`: free + inactive + speculative
+ * pages. That is the reclaimable set os.freemem() omits on macOS.
+ */
+export declare function parseVmStatAvailableMb(contents: string): number | null;
+/**
+ * Available memory in MiB. Prefers kernel MemAvailable. On darwin without
+ * /proc/meminfo, uses vm_stat (free+inactive+speculative) and never os.freemem().
+ * Elsewhere, falls back to os.freemem() only where MemAvailable is absent.
+ * Returning null skips the memory gate instead of holding every lane.
  */
 export declare function readAvailableMemMb(deps?: ThrottleDeps): number | null;
 export interface ThrottleState {

package/dist/lib/lanes/throttle.js

@@ -9,6 +9,7 @@
  * Overrides HQ_LANES_CPU_BUSY_OVERRIDE and HQ_LANES_CPU_CHECK are deliberately
  * distinct from the runner's HQ_WORKFLOW_* pair — this module never reads those.
  */
+import { execFileSync as nodeExecFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -20,6 +21,8 @@ const CPU_CUMULATIVE_MAX_AGE_MS = 5 * 60 * 1000;
 export const STARVATION_MAX_DEFERRALS = 10;
 export const STARVATION_MAX_MS = 30 * 60 * 1000;
 export const PROC_MEMINFO = "/proc/meminfo";
+export const VM_STAT_BIN = "/usr/bin/vm_stat";
+const VM_STAT_TIMEOUT_MS = 2_000;
 export const LANES_CPU_BUSY_OVERRIDE = "HQ_LANES_CPU_BUSY_OVERRIDE";
 export const LANES_CPU_CHECK = "HQ_LANES_CPU_CHECK";
 function defaultSleep(ms) {
@@ -35,8 +38,13 @@ export function defaultThrottleDeps(env = process.env) {
         sleep: defaultSleep,
         readFileSync: (file, encoding) => fs.readFileSync(file, encoding),
         // os.freemem() reports MemFree on Linux (excludes page cache). Used only
-        // where MemAvailable is absent — see readAvailableMemMb.
+        // where MemAvailable is absent on a non-darwin host — see readAvailableMemMb.
         freemem: () => os.freemem(),
+        platform: () => process.platform,
+        execFileSync: (file, args, options) => nodeExecFileSync(file, [...args], {
+            encoding: "utf8",
+            timeout: options.timeout,
+        }),
         existsSync: (file) => fs.existsSync(file),
         mkdirSync: fs.mkdirSync.bind(fs),
         writeFileSync: fs.writeFileSync.bind(fs),
@@ -184,9 +192,63 @@ export function parseMemAvailableKb(contents) {
     }
     return null;
 }
+function parseVmStatPages(contents, label) {
+    const match = new RegExp(`^Pages ${label}:\\s+([0-9.]+)\\s*$`, "m").exec(contents);
+    if (!match)
+        return null;
+    const n = Number(match[1].replace(/\.$/, ""));
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+/**
+ * Available memory in MiB from darwin `vm_stat`: free + inactive + speculative
+ * pages. That is the reclaimable set os.freemem() omits on macOS.
+ */
+export function parseVmStatAvailableMb(contents) {
+    const pageSizeMatch = /page size of (\d+) bytes/i.exec(contents);
+    const pageSize = pageSizeMatch ? Number(pageSizeMatch[1]) : Number.NaN;
+    if (!Number.isFinite(pageSize) || pageSize <= 0)
+        return null;
+    const free = parseVmStatPages(contents, "free");
+    const inactive = parseVmStatPages(contents, "inactive");
+    const speculative = parseVmStatPages(contents, "speculative");
+    if (free === null || inactive === null || speculative === null)
+        return null;
+    return ((free + inactive + speculative) * pageSize) / (1024 * 1024);
+}
+function readDarwinAvailableMemMb(deps) {
+    try {
+        const contents = deps.execFileSync(VM_STAT_BIN, [], {
+            encoding: "utf8",
+            timeout: VM_STAT_TIMEOUT_MS,
+        });
+        const mb = parseVmStatAvailableMb(contents);
+        if (mb !== null)
+            return mb;
+        process.stderr.write("lanes throttle: darwin vm_stat output was unreadable; skipping the memory gate\n");
+        return null;
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: darwin vm_stat failed: ${err instanceof Error ? err.message : String(err)}; skipping the memory gate\n`);
+        return null;
+    }
+}
+function readFreememMb(deps) {
+    try {
+        const bytes = deps.freemem();
+        if (!Number.isFinite(bytes) || bytes < 0)
+            return null;
+        return bytes / (1024 * 1024);
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: freemem fallback failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
 /**
- * Available memory in MiB. Prefers kernel MemAvailable; falls back to
- * os.freemem() only where MemAvailable is absent.
+ * Available memory in MiB. Prefers kernel MemAvailable. On darwin without
+ * /proc/meminfo, uses vm_stat (free+inactive+speculative) and never os.freemem().
+ * Elsewhere, falls back to os.freemem() only where MemAvailable is absent.
+ * Returning null skips the memory gate instead of holding every lane.
  */
 export function readAvailableMemMb(deps = defaultThrottleDeps()) {
     try {
@@ -203,18 +265,10 @@ export function readAvailableMemMb(deps = defaultThrottleDeps()) {
             process.stderr.write(`lanes throttle: failed to read ${PROC_MEMINFO}: ${err instanceof Error ? err.message : String(err)}\n`);
             return null;
         }
-        // Platform without /proc/meminfo — fall back to free memory.
-    }
-    try {
-        const bytes = deps.freemem();
-        if (!Number.isFinite(bytes) || bytes < 0)
-            return null;
-        return bytes / (1024 * 1024);
-    }
-    catch (err) {
-        process.stderr.write(`lanes throttle: freemem fallback failed: ${err instanceof Error ? err.message : String(err)}\n`);
-        return null;
+        if (deps.platform() === "darwin")
+            return readDarwinAvailableMemMb(deps);
     }
+    return readFreememMb(deps);
 }
 export function emptyThrottleState() {
     return {

package/package.json

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