@indigoai-us/hq-cli 5.345.101 → 5.345.103

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [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
+  instead of showing up as unlabeled `unknown`. `hq doctor --fix` still
+  refreshes that company journal when hook files have uncommitted changes.
+
 ## [5.345.101] — 2026-10-12
 - Doctor JSON no longer counts an ordinary HQ Core upgrade warning in its
   summary after omitting it from results. Session-start health that only saw

package/dist/commands/doctor.js

@@ -33,7 +33,7 @@ import { PARITY_FAMILY_ID, PARITY_FAMILY_TITLE, runParityReplay, } from "../lib/
 import { applyFixes } from "../lib/doctor/fix/apply.js";
 import { renderDoctorFixJson } from "../lib/doctor/fix/json-output.js";
 import { clientHealthCheckStatusEnabled as isActiveCompanyClientHealthCheckStatusEnabled, clientHealthCheckStatusEnabledForCompany, clientHealthReasonCodesEnabled as isActiveCompanyClientHealthReasonCodesEnabled, clientHealthReasonCodesEnabledForCompany, } from "../lib/doctor/client-health-reason-codes-flag.js";
-import { isCompanyJournalSlug } from "../lib/doctor/checks/sync-health.js";
+import { clientHealthCompanyScopeFromCheckId } from "../lib/doctor/checks/sync-health.js";
 import { readCompaniesManifestMap } from "../lib/work-context/repo-remote.js";
 import * as readline from "node:readline";
 import { runSideEffectTests } from "../lib/doctor/deep/sandbox.js";
@@ -207,15 +207,7 @@ async function resolveClientHealthReasonCodesCheckIds(families, resolveForCompan
                 (result.status !== "FAIL" && result.status !== "WARN")) {
                 continue;
             }
-            const scoped = /^sync\.(?:journal|manifest)\.(.+)$/.exec(result.checkId);
-            const companyUidScope = scoped
-                ? /^company:(cmp_[A-Za-z0-9]{3,128})$/.exec(scoped[1])
-                : null;
-            const companySlug = companyUidScope
-                ? `company:${companyUidScope[1]}`
-                : scoped && isCompanyJournalSlug(scoped[1])
-                    ? scoped[1]
-                    : null;
+            const companySlug = clientHealthCompanyScopeFromCheckId(result.checkId);
             const checkIds = checksByCompany.get(companySlug) ?? [];
             checkIds.push(result.checkId);
             checksByCompany.set(companySlug, checkIds);
@@ -242,8 +234,7 @@ async function resolveClientHealthCheckStatusCheckIds(families, resolveForCompan
         for (const result of run.results) {
             if (result.status !== "FAIL" && result.status !== "WARN")
                 continue;
-            const scoped = /^sync\.(?:journal|manifest)\.(.+)$/.exec(result.checkId);
-            const companySlug = scoped && isCompanyJournalSlug(scoped[1]) ? scoped[1] : null;
+            const companySlug = clientHealthCompanyScopeFromCheckId(result.checkId);
             const checkIds = checksByCompany.get(companySlug) ?? [];
             checkIds.push(result.checkId);
             checksByCompany.set(companySlug, checkIds);

package/dist/lib/doctor/checks/sync-health.d.ts

@@ -107,6 +107,23 @@ export interface SyncHealthDeps {
  * outside `companies/`.
  */
 export declare function isSafeCompanySlug(slug: string): boolean;
+/**
+ * SessionStart health only ships `checkId` values matching
+ * `^sync.[A-Za-z0-9._-]{1,160}$`. A colon (hq-cloud's `company:cmp_…` scope
+ * key) becomes the unlabeled `unknown` row in those reports.
+ */
+export declare const CLIENT_HEALTH_SYNC_CHECK_ID: RegExp;
+/**
+ * Doctor JSON `checkId` for a manifest scope. hq-cloud keys company rows
+ * `company:cmp_…`; the colon is replaced so SessionStart health can report
+ * the real id instead of `unknown`.
+ */
+export declare function manifestCheckIdFromScopeKey(scopeKey: string): string;
+/**
+ * Company slug or `company:cmp_…` uid used to resolve per-company health
+ * flags from a sync finding. Manifest ids may use a colon or a dot.
+ */
+export declare function clientHealthCompanyScopeFromCheckId(checkId: string): string | null;
 /** True when this journal slug names a company rather than the personal tree. */
 export declare function isCompanyJournalSlug(slug: string): boolean;
 /** True when this journal slug names the personal tree or personal vault. */

package/dist/lib/doctor/checks/sync-health.js

@@ -194,13 +194,64 @@ const NON_COMPANY_JOURNAL_SLUGS = new Set([
     PERSONAL_SCOPE_SLUG,
     PERSONAL_VAULT_SCOPE_SLUG,
 ]);
+/**
+ * SessionStart health only ships `checkId` values matching
+ * `^sync.[A-Za-z0-9._-]{1,160}$`. A colon (hq-cloud's `company:cmp_…` scope
+ * key) becomes the unlabeled `unknown` row in those reports.
+ */
+export const CLIENT_HEALTH_SYNC_CHECK_ID = /^sync\.[A-Za-z0-9._-]{1,160}$/;
+const COMPANY_SCOPE_UID = /^company[.:](cmp_[A-Za-z0-9]{3,128})$/;
 /** Keep malformed scopes distinct without letting them imitate valid slugs. */
 function journalSlugForCheckId(slug) {
     if (NON_COMPANY_JOURNAL_SLUGS.has(slug) || isSafeCompanySlug(slug)) {
         return slug;
     }
     const encoded = Array.from(slug, (character) => character.codePointAt(0).toString(16)).join("-");
-    return `__hq_invalid_journal_scope__${encoded}`;
+    return boundInvalidScopeToken(`__hq_invalid_journal_scope__${encoded}`);
+}
+function boundInvalidScopeToken(token) {
+    // `sync.` + token must fit the health-hook 160-char suffix budget.
+    const maxSuffix = 160;
+    if (token.length <= maxSuffix)
+        return token;
+    return token.slice(0, maxSuffix);
+}
+/**
+ * Doctor JSON `checkId` for a manifest scope. hq-cloud keys company rows
+ * `company:cmp_…`; the colon is replaced so SessionStart health can report
+ * the real id instead of `unknown`.
+ */
+export function manifestCheckIdFromScopeKey(scopeKey) {
+    if (scopeKey.startsWith("company:")) {
+        return `sync.manifest.${scopeKey.replace(/:/g, ".")}`;
+    }
+    if (scopeKey === "personal" || isSafeCompanySlug(scopeKey)) {
+        return `sync.manifest.${scopeKey}`;
+    }
+    const encoded = Array.from(scopeKey, (character) => character.codePointAt(0).toString(16)).join("-");
+    return `sync.manifest.${boundInvalidScopeToken(`__hq_invalid_scope__${encoded}`)}`;
+}
+/**
+ * Company slug or `company:cmp_…` uid used to resolve per-company health
+ * flags from a sync finding. Manifest ids may use a colon or a dot.
+ */
+export function clientHealthCompanyScopeFromCheckId(checkId) {
+    const journalSlug = journalSlugFromCheckId(checkId);
+    if (journalSlug && isCompanyJournalSlug(journalSlug) && isSafeCompanySlug(journalSlug)) {
+        return journalSlug;
+    }
+    const manifest = /^sync\.manifest\.(.+)$/.exec(checkId);
+    if (!manifest)
+        return null;
+    const rest = manifest[1];
+    const companyUid = COMPANY_SCOPE_UID.exec(rest)?.[1];
+    if (companyUid)
+        return `company:${companyUid}`;
+    if (rest === "personal" || NON_COMPANY_JOURNAL_SLUGS.has(rest))
+        return null;
+    if (isSafeCompanySlug(rest))
+        return rest;
+    return null;
 }
 /** True when this journal slug names a company rather than the personal tree. */
 export function isCompanyJournalSlug(slug) {
@@ -553,7 +604,7 @@ function manifestResults(deps, journals) {
     }
     const nowMs = deps.now().getTime();
     const reported = statuses.map((entry) => {
-        const checkId = `sync.manifest.${entry.scopeKey}`;
+        const checkId = manifestCheckIdFromScopeKey(entry.scopeKey);
         if (!entry.lastUploadAt) {
             return {
                 status: "UNTESTED",

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