@indigoai-us/hq-cli 5.345.203 → 5.345.204

package/dist/lib/capacity/collectors/claude-oauth.js

@@ -36,6 +36,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { DIR_MODE, FILE_MODE, appendReadings, capacityRoot, EXPIRED_REASON, SIGN_IN_REVOKED_REASON, readCollectorMark, redactProviderTokens, } from "../ledger.js";
 import { hashClaudeAccountId } from "./claude-statusline.js";
+import { REMOTE_LANE_READ_ENV } from "../../lanes/outpost-dispatch.js";
 export const CLAUDE_OAUTH_PARSER_VERSION = "claude-oauth-usage.1";
 export const CLAUDE_OAUTH_PROVIDER = "claude";
 export const CLAUDE_OAUTH_SOURCE = "oauth-usage";
@@ -136,7 +137,11 @@ export function mapClaudeOAuthUsage(body, options) {
     }
     return { readings, failures };
 }
-export async function collectClaudeOAuth(options = {}) {
+export async function collectClaudeOAuth(inputOptions = {}) {
+    const options = {
+        ...inputOptions,
+        listLiveLanes: memoizeListLiveLanes(inputOptions.listLiveLanes ?? defaultListLiveLanes),
+    };
     const ledger = ledgerOptions(options);
     const root = ledger.root ?? capacityRoot(ledger.env, ledger.home);
     const scoped = { ...ledger, root };
@@ -1766,43 +1771,62 @@ export function resolveHqInvocation(argv = process.argv, execPath = process.exec
 }
 /** Output cap for the `hq ... --json` reads behind the refresh gates. */
 const HQ_JSON_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
-const HQ_JSON_TIMEOUT_MS = 15_000;
-/** Exported for tests; `invocation` defaults to {@link resolveHqInvocation}. */
+const HQ_JSON_TIMEOUT_MS = 30_000;
+/**
+ * Run `hq ... --json` and parse stdout. Async on purpose: the collector runs inside the mesh
+ * daemon, and a synchronous read that takes 15-30 s on a loaded machine froze the daemon's
+ * event loop (MQTT keepalive, owner heartbeat) for the whole read.
+ * Exported for tests; `invocation` defaults to {@link resolveHqInvocation}.
+ */
 export function execHqJson(args, invocation = resolveHqInvocation(), env = process.env) {
-    const result = spawnSync(invocation.command, [...invocation.args, ...args], {
-        env,
-        encoding: "utf8",
-        // The lane list takes ~2.5 s on a busy machine and grows with lane history; 5 s left too
-        // little headroom under load, and a timeout fails the gate closed.
-        timeout: HQ_JSON_TIMEOUT_MS,
-        // `hq lanes list --json` grows with lane history (1.7 MB on a busy machine). The spawnSync
-        // default of 1 MiB raised ENOBUFS, which made the live-lane gate fail closed on every collect.
-        maxBuffer: HQ_JSON_MAX_BUFFER_BYTES,
-        windowsHide: true,
-        stdio: ["ignore", "pipe", "pipe"],
+    const label = `hq ${args.join(" ")}`;
+    return new Promise((resolve, reject) => {
+        execFile(invocation.command, [...invocation.args, ...args], {
+            env,
+            encoding: "utf8",
+            // The lane list takes ~2.5 s on an idle machine and grows with lane history. Under heavy
+            // load (load average ~95 on 18 cores) the same read took 16-18 s, so 15 s still failed the
+            // gate closed on every collect and every Claude home stayed expired.
+            timeout: HQ_JSON_TIMEOUT_MS,
+            // `hq lanes list --json` grows with lane history (6.8 MB on a busy machine). The 1 MiB
+            // default made the live-lane gate fail closed on every collect.
+            maxBuffer: HQ_JSON_MAX_BUFFER_BYTES,
+            // SIGTERM can be trapped, and execFile waits for the child to exit before calling back.
+            killSignal: "SIGKILL",
+            windowsHide: true,
+        }, (error, stdout) => {
+            if (error) {
+                const failure = error;
+                const code = failure.code;
+                if (code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+                    reject(new Error(`${label} output exceeded ${HQ_JSON_MAX_BUFFER_BYTES} bytes`));
+                }
+                else if (failure.killed) {
+                    reject(new Error(`${label} timed out`));
+                }
+                else if (typeof code === "number") {
+                    reject(new Error(`${label} exit ${code}`));
+                }
+                else if (failure.signal) {
+                    reject(new Error(`${label} killed by ${failure.signal}`));
+                }
+                else {
+                    reject(new Error(`${label} failed to spawn: ${failure.message}`));
+                }
+                return;
+            }
+            if (!stdout) {
+                reject(new Error(`${label} empty stdout`));
+                return;
+            }
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch (parseError) {
+                reject(new Error(`${label} invalid JSON: ${parseError.message}`));
+            }
+        });
     });
-    if (result.error) {
-        const code = result.error.code;
-        if (code === "ETIMEDOUT")
-            throw new Error(`hq ${args.join(" ")} timed out`);
-        if (code === "ENOBUFS")
-            throw new Error(`hq ${args.join(" ")} output exceeded ${HQ_JSON_MAX_BUFFER_BYTES} bytes`);
-        throw new Error(`hq ${args.join(" ")} failed to spawn: ${result.error.message}`);
-    }
-    if (result.signal)
-        throw new Error(`hq ${args.join(" ")} killed by ${result.signal}`);
-    if (typeof result.status !== "number")
-        throw new Error(`hq ${args.join(" ")} no exit status`);
-    if (result.status !== 0)
-        throw new Error(`hq ${args.join(" ")} exit ${result.status}`);
-    if (!result.stdout)
-        throw new Error(`hq ${args.join(" ")} empty stdout`);
-    try {
-        return JSON.parse(result.stdout);
-    }
-    catch (error) {
-        throw new Error(`hq ${args.join(" ")} invalid JSON: ${error.message}`);
-    }
 }
 /**
  * Parse `hq lanes list --json` payload into typed rows.
@@ -1889,12 +1913,31 @@ export function buildLiveLanesFromPayloads(lanes, accounts) {
  * Throws on hq call failure or unexpected JSON shape; callers skip the refresh.
  */
 const defaultListLiveLanes = async () => {
-    const lanesPayload = execHqJson(["lanes", "list", "--json"]);
-    const accountsPayload = execHqJson(["lanes", "accounts", "list", "--json"]);
+    // The gate only needs lanes that use this host's Claude homes. Skip the Outpost mirror
+    // refresh (a network round trip per Outpost); cached mirror rows are still listed.
+    const env = { ...process.env, [REMOTE_LANE_READ_ENV]: "1" };
+    const invocation = resolveHqInvocation();
+    const [lanesPayload, accountsPayload] = await Promise.all([
+        execHqJson(["lanes", "list", "--json"], invocation, env),
+        execHqJson(["lanes", "accounts", "list", "--json"], invocation, env),
+    ]);
     const lanes = parseLanesListPayload(lanesPayload);
     const accounts = parseAccountsListPayload(accountsPayload);
     return buildLiveLanesFromPayloads(lanes, accounts);
 };
+/**
+ * Share one lane read across every home in a collect. Without this each expired home ran its
+ * own pair of `hq lanes ... --json` reads, so one slow machine turned into N timeouts per
+ * collect. A failure is shared too: the next home fails closed without waiting again.
+ * Exported for tests.
+ */
+export function memoizeListLiveLanes(list) {
+    let pending = null;
+    return () => {
+        pending ??= list();
+        return pending;
+    };
+}
 /**
  * Parse `ps -axo pid=,command=` into rows that mention the `claude` executable.
  * Exported for tests. Returned rows carry `probe: "command-only"` so the gate
@@ -1926,14 +1969,145 @@ export function parsePsClaudeOutput(stdout) {
     }
     return out;
 }
+/** Pid to full command line, from `ps -ww -o pid=,command= -p <pids>`. Exported for tests. */
+export function parsePsCommandLines(stdout) {
+    const lines = new Map();
+    for (const rawLine of stdout.split("\n")) {
+        const match = /^\s*(\d+) (.*)$/.exec(rawLine.replace(/\s+$/, ""));
+        if (match)
+            lines.set(Number(match[1]), match[2]);
+    }
+    return lines;
+}
+/**
+ * Upgrade darwin command-only rows with each process's environment. `ps -wwE` prints a
+ * same-user process's command line followed by its environment, unquoted and space separated.
+ * Only the text after the exact command line (read separately with `ps -ww`) is treated as the
+ * environment, so a prompt argument that mentions CLAUDE_CONFIG_DIR= or HOME= is never read as
+ * env. A row becomes `probe: "env"` only when:
+ *   - the `-E` line starts with the command line plus a space, and the rest starts with NAME=;
+ *   - CLAUDE_CONFIG_DIR= appears at most once in that rest, and its value is absolute and
+ *     names an existing directory (the value runs to the next ` NAME=` or the end of line).
+ * Anything else stays command-only, which blocks every home. A pid missing from the output
+ * is dropped only when it is known to have exited; otherwise it stays command-only.
+ * Exported for tests.
+ */
+export function parsePsEnvOutput(envStdout, commandLines, rows, options = {}) {
+    const isDirectory = options.isDirectory ?? defaultIsDirectory;
+    const isAlive = options.isAlive ?? defaultIsAlive;
+    const envLines = parsePsCommandLines(envStdout);
+    const blocked = (pid) => ({ pid, env: {}, probe: "command-only" });
+    const out = [];
+    for (const row of rows) {
+        const command = commandLines.get(row.pid);
+        const line = envLines.get(row.pid);
+        if (command === undefined || line === undefined) {
+            if (isAlive(row.pid))
+                out.push(blocked(row.pid));
+            continue;
+        }
+        if (!line.startsWith(`${command} `)) {
+            // No visible env (another user's or a protected process), or the pid was reused.
+            out.push(blocked(row.pid));
+            continue;
+        }
+        const env = line.slice(command.length + 1);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*=/.test(env)) {
+            out.push(blocked(row.pid));
+            continue;
+        }
+        const mentions = env.split("CLAUDE_CONFIG_DIR=").length - 1;
+        const match = /(?:^| )CLAUDE_CONFIG_DIR=(.*?)(?= [A-Za-z_][A-Za-z0-9_]*=|$)/.exec(env);
+        if (mentions === 0) {
+            // The default config dir is HOME/.claude for this process. HOME must be one absolute
+            // value; an unset HOME falls back to the collector's own home.
+            const homes = [...env.matchAll(/(?:^| )HOME=(.*?)(?= [A-Za-z_][A-Za-z0-9_]*=|$)/g)].map((m) => m[1]);
+            if (homes.length === 0) {
+                out.push({ pid: row.pid, env: {}, probe: "env" });
+            }
+            else if (homes.length === 1 && path.isAbsolute(homes[0])) {
+                out.push({ pid: row.pid, env: { HOME: homes[0] }, probe: "env" });
+            }
+            else {
+                out.push(blocked(row.pid));
+            }
+        }
+        else if (mentions === 1 && match && path.isAbsolute(match[1]) && isDirectory(match[1])) {
+            out.push({ pid: row.pid, env: { CLAUDE_CONFIG_DIR: match[1] }, probe: "env" });
+        }
+        else {
+            out.push(blocked(row.pid));
+        }
+    }
+    return out;
+}
+/** Default config dir of an env-probed process with CLAUDE_CONFIG_DIR unset. Exported for tests. */
+export function processDefaultConfigDir(proc) {
+    const home = typeof proc.env.HOME === "string" && path.isAbsolute(proc.env.HOME) ? proc.env.HOME : os.homedir();
+    return path.join(home, ".claude");
+}
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+/**
+ * Canonical form of a home directory for comparison: symlinks resolved by the OS, and lower
+ * case on darwin, where APFS is case-insensitive by default. Null when the path cannot be
+ * resolved. Exported for tests.
+ */
+export function canonicalHomePath(dir, platform = process.platform) {
+    try {
+        const real = fs.realpathSync.native(path.resolve(dir));
+        return platform === "darwin" ? real.toLowerCase() : real;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultIsDirectory(dir) {
+    try {
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function runPs(args) {
+    const result = spawnSync("ps", [...args], {
+        encoding: "utf8",
+        timeout: 5_000,
+        // Full command lines for every process can pass the 1 MiB default on a busy machine.
+        maxBuffer: HQ_JSON_MAX_BUFFER_BYTES,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.error)
+        throw new Error(`ps failed to spawn: ${result.error.message}`);
+    if (result.signal)
+        throw new Error(`ps killed by ${result.signal}`);
+    if (typeof result.status !== "number")
+        throw new Error("ps no exit status");
+    // `ps -p` exits 1 both when no pid still exists and on a real error. Accept exit 1 only with
+    // empty stderr; parsePsEnvOutput then keeps any pid that is not known to be gone as blocking.
+    const quietNoMatch = args.includes("-p") && result.status === 1 && !(result.stderr ?? "").trim();
+    if (result.status !== 0 && !quietNoMatch)
+        throw new Error(`ps exit ${result.status}`);
+    return result.stdout ?? "";
+}
 /**
  * Fail-closed enumeration of running Claude Code processes.
  *
  * linux: /proc/<pid>/environ gives us per-process CLAUDE_CONFIG_DIR; absent
  *   value means the process holds the default home.
- * darwin: ps cannot read a child process environment, so we return
- *   `probe: "command-only"` rows. The gate treats such a row as holding the
- *   default home AND blocking every non-default home.
+ * darwin: `ps -axo` finds claude processes, then `ps -wwE` reads their
+ *   environment (same user only). Rows whose environment cannot be read stay
+ *   `probe: "command-only"`; the gate treats such a row as holding the default
+ *   home AND blocking every non-default home.
  * other platforms: return []. The lane gate is authoritative there.
  *
  * Throws on ps/readdir failure so the caller skips refresh.
@@ -1975,32 +2149,23 @@ const defaultListProcesses = async () => {
                 throw new Error(`read /proc/${entry}/environ failed`);
             }
             const match = /(?:^|\0)CLAUDE_CONFIG_DIR=([^\0]+)/.exec(envText);
-            out.push({
-                pid,
-                env: match && match[1] ? { CLAUDE_CONFIG_DIR: match[1] } : {},
-                probe: "env",
-            });
+            const homeMatch = /(?:^|\0)HOME=([^\0]+)/.exec(envText);
+            const procEnv = {};
+            if (match && match[1])
+                procEnv.CLAUDE_CONFIG_DIR = match[1];
+            if (homeMatch && homeMatch[1])
+                procEnv.HOME = homeMatch[1];
+            out.push({ pid, env: procEnv, probe: "env" });
         }
         return out;
     }
     if (process.platform === "darwin") {
-        const result = spawnSync("ps", ["-axo", "pid=,command="], {
-            encoding: "utf8",
-            timeout: 5_000,
-            // Full command lines for every process can pass the 1 MiB default on a busy machine.
-            maxBuffer: HQ_JSON_MAX_BUFFER_BYTES,
-            windowsHide: true,
-            stdio: ["ignore", "pipe", "pipe"],
-        });
-        if (result.error)
-            throw new Error(`ps failed to spawn: ${result.error.message}`);
-        if (result.signal)
-            throw new Error(`ps killed by ${result.signal}`);
-        if (typeof result.status !== "number")
-            throw new Error("ps no exit status");
-        if (result.status !== 0)
-            throw new Error(`ps exit ${result.status}`);
-        return parsePsClaudeOutput(result.stdout ?? "");
+        const rows = parsePsClaudeOutput(runPs(["-axo", "pid=,command="]));
+        if (rows.length === 0)
+            return rows;
+        const pids = rows.map((row) => String(row.pid)).join(",");
+        const commandLines = parsePsCommandLines(runPs(["-ww", "-o", "pid=,command=", "-p", pids]));
+        return parsePsEnvOutput(runPs(["-wwE", "-o", "pid=,command=", "-p", pids]), commandLines, rows);
     }
     return [];
 };
@@ -2027,7 +2192,16 @@ async function attemptClaudeTokenRefresh(ctx) {
         return { outcome: "skipped-live-check-failed", errorMessage: message };
     }
     const resolvedHome = path.resolve(ctx.home);
-    const sameHome = (candidate) => typeof candidate === "string" && candidate.length > 0 && path.resolve(candidate) === resolvedHome;
+    const targetHome = canonicalHomePath(ctx.home) ?? resolvedHome;
+    // Exact match, for the auth-failed short circuit, which records the home as revoked.
+    const sameHome = (candidate) => typeof candidate === "string" && candidate.length > 0 && canonicalHomePath(candidate) === targetHome;
+    // Blocking match: a path that cannot be resolved might be this home, so it blocks.
+    const mayHoldHome = (candidate) => {
+        if (typeof candidate !== "string" || candidate.length === 0)
+            return false;
+        const canonical = canonicalHomePath(candidate);
+        return canonical === null || canonical === targetHome;
+    };
     // Addendum 1: if the lane watcher classified a 401/403 on this home as
     // provider_auth_failed, treat the account as already signed out and record
     // revoked immediately. No token endpoint call, no response body stored.
@@ -2046,7 +2220,7 @@ async function attemptClaudeTokenRefresh(ctx) {
         });
         return { outcome: "revoked", errorClass: "revoked" };
     }
-    if (liveLanes.some((lane) => lane.isLive && sameHome(lane.home))) {
+    if (liveLanes.some((lane) => lane.isLive && mayHoldHome(lane.home))) {
         recordRefresh(ctx.root, key, { attemptedAt: new Date(ctx.nowMs).toISOString(), outcome: "skipped-live" });
         return { outcome: "skipped-live" };
     }
@@ -2065,15 +2239,21 @@ async function attemptClaudeTokenRefresh(ctx) {
         return { outcome: "skipped-process-check-failed", errorMessage: message };
     }
     const defaultHome = path.join(os.homedir(), ".claude");
-    const isDefaultHome = resolvedHome === path.resolve(defaultHome);
+    const isDefaultHome = targetHome === (canonicalHomePath(defaultHome) ?? path.resolve(defaultHome));
     const procBlocks = procs.some((proc) => {
         if (proc.probe === "env") {
             const dir = typeof proc.env.CLAUDE_CONFIG_DIR === "string" ? proc.env.CLAUDE_CONFIG_DIR : "";
-            // On linux we have a real env read. Default home is held when
-            // CLAUDE_CONFIG_DIR is empty; non-default home only when it points here.
-            if (!dir)
-                return isDefaultHome;
-            return path.resolve(dir) === resolvedHome;
+            // A real env read. With CLAUDE_CONFIG_DIR unset the process holds HOME/.claude for its
+            // own HOME (the collector's home when HOME was not read). Claude Code adds no keychain
+            // suffix without CLAUDE_CONFIG_DIR, so such a process may also use the default keychain
+            // item; it keeps blocking the collector's default home too.
+            // Compare the process's default dir the same way as the collector's: a dir that does not
+            // exist yet is compared by its resolved path, so a missing ~/.claude does not block every home.
+            if (!dir) {
+                const procDefault = processDefaultConfigDir(proc);
+                return isDefaultHome || targetHome === (canonicalHomePath(procDefault) ?? path.resolve(procDefault));
+            }
+            return mayHoldHome(dir);
         }
         // command-only (darwin): we cannot read the per-process env. Conservatively
         // treat the row as holding the default home AND blocking non-default homes.

package/dist/lib/daemon/catalog.js

@@ -211,8 +211,8 @@ function planService(service, ctx) {
             return [unit];
         }
         case "sync-core": {
-            if (ctx.platform !== "darwin" && ctx.platform !== "linux") {
-                return [unavailable(service, "the new sync engine runs on macOS and Linux only")];
+            if (ctx.platform !== "darwin" && ctx.platform !== "linux" && ctx.platform !== "win32") {
+                return [unavailable(service, "the new sync engine runs on macOS, Linux and Windows only")];
             }
             const reconcile = base(service, {
                 id: SYNC_CORE_RECONCILE_UNIT,

package/dist/lib/daemon/run.js

@@ -82,7 +82,7 @@ export function syncCoreVaultPlans(home, hqRoot, platform) {
             release: state.release,
             ...(vault.legacyOffSince ? { legacyOffSince: vault.legacyOffSince } : {}),
         }, platform);
-        const releaseHold = vault.phase === "full" ? fullModeHold(vault, state.release) : undefined;
+        const releaseHold = vault.phase === "full" ? fullModeHold(vault, state.release, platform) : undefined;
         return releaseHold ? { ...plan, blockedReason: releaseHold } : plan;
     });
 }
@@ -115,7 +115,7 @@ export function planUnitsWithSyncCoreInterlock(services, context, supervisor) {
         let restorePersonal = false;
         const restoreCompanies = {};
         for (const vault of context.syncCoreVaults ?? []) {
-            if (vault.phase !== "full" || runningVaults.has(vault.uid) || !fullModeHold(vault, vault.release))
+            if (vault.phase !== "full" || runningVaults.has(vault.uid) || !fullModeHold(vault, vault.release, context.platform))
                 continue;
             if (vault.kind === "personal") {
                 restorePersonal = personalOff;

package/dist/lib/lanes/config.js

@@ -172,6 +172,14 @@ function optionalUnitInterval(value, field) {
     }
     return value;
 }
+function optionalPercent(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 100) {
+        throw new LanesConfigError("invalid_config", `${field} must be a number in [0, 100]`, { field, value });
+    }
+    return value;
+}
 function parseAccount(provider, id, raw, deps) {
     if (!isPlainObject(raw)) {
         throw new LanesConfigError("invalid_config", `providers.${provider}.accounts.${id} must be an object`, { provider, account: id });
@@ -407,6 +415,11 @@ function parseThrottle(raw) {
         }
         result.min_available_mem_mb = obj.min_available_mem_mb;
     }
+    // darwin: a warn pressure level holds only at or below this free
+    // percentage. Unset means DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT (20).
+    const warnMinFree = optionalPercent(obj.memory_warn_min_free_percent, "throttle.memory_warn_min_free_percent");
+    if (warnMinFree !== undefined)
+        result.memory_warn_min_free_percent = warnMinFree;
     return result;
 }
 function parseLiveness(raw) {

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

@@ -25,6 +25,17 @@ export declare const SYSCTL_BIN = "/usr/sbin/sysctl";
  * hw.memsize turns the percentage into MiB for min_available_mem_mb.
  */
 export declare const MEMORY_PRESSURE_SYSCTLS: readonly ["kern.memorystatus_level", "kern.memorystatus_vm_pressure_level", "hw.memsize"];
+/**
+ * Default for throttle.memory_warn_min_free_percent. On darwin a warn pressure
+ * level holds admission only while the free percentage is at or below this.
+ */
+export declare const DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT = 20;
+/**
+ * Whether a darwin memory_pressure level holds admission on its own. Critical
+ * always holds. Warn holds only at or below warnMinFreePercent free, or when
+ * the free percentage is unknown.
+ */
+export declare function pressureLevelHolds(signal: MemorySignal, warnMinFreePercent?: number): boolean;
 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 {
@@ -129,7 +140,7 @@ export declare function readMemorySignal(deps?: ThrottleDeps): MemorySignal | nu
 /** Available memory in MiB from readMemorySignal; null skips the memory gate. */
 export declare function readAvailableMemMb(deps?: ThrottleDeps): number | null;
 /** Plain explanation of a memory hold: which signal, its value, and the threshold. */
-export declare function formatMemoryHoldMessage(signal: MemorySignal, thresholdMb: number): string;
+export declare function formatMemoryHoldMessage(signal: MemorySignal, thresholdMb: number, warnMinFreePercent?: number): string;
 export interface ThrottleState {
     consecutiveDeferrals: number;
     lastAdmissionAt: string | null;

package/dist/lib/lanes/throttle.js

@@ -34,6 +34,23 @@ export const MEMORY_PRESSURE_SYSCTLS = [
     "kern.memorystatus_vm_pressure_level",
     "hw.memsize",
 ];
+/**
+ * Default for throttle.memory_warn_min_free_percent. On darwin a warn pressure
+ * level holds admission only while the free percentage is at or below this.
+ */
+export const DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT = 20;
+/**
+ * Whether a darwin memory_pressure level holds admission on its own. Critical
+ * always holds. Warn holds only at or below warnMinFreePercent free, or when
+ * the free percentage is unknown.
+ */
+export function pressureLevelHolds(signal, warnMinFreePercent = DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT) {
+    if (signal.pressure_level === "critical")
+        return true;
+    if (signal.pressure_level !== "warn")
+        return false;
+    return signal.free_percent === undefined || signal.free_percent <= warnMinFreePercent;
+}
 export const LANES_CPU_BUSY_OVERRIDE = "HQ_LANES_CPU_BUSY_OVERRIDE";
 export const LANES_CPU_CHECK = "HQ_LANES_CPU_CHECK";
 function defaultSleep(ms) {
@@ -340,11 +357,11 @@ function formatMb(mb) {
     return `${Math.round(mb)} MB`;
 }
 /** Plain explanation of a memory hold: which signal, its value, and the threshold. */
-export function formatMemoryHoldMessage(signal, thresholdMb) {
+export function formatMemoryHoldMessage(signal, thresholdMb, warnMinFreePercent = DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT) {
     if (signal.source === "memory_pressure") {
         const reading = `memory_pressure reports ${signal.free_percent}% free (about ${formatMb(signal.available_mb)}), pressure level ${signal.pressure_level}`;
-        if (signal.pressure_level !== "normal") {
-            return `Holding new lanes: ${reading}. Lanes wait while the level is warn or critical (throttle.min_available_mem_mb is ${thresholdMb}).`;
+        if (pressureLevelHolds(signal, warnMinFreePercent)) {
+            return `Holding new lanes: ${reading}. Lanes wait while the level is critical, or warn with ${warnMinFreePercent}% free or less (throttle.memory_warn_min_free_percent; throttle.min_available_mem_mb is ${thresholdMb}).`;
         }
         return `Holding new lanes: ${reading}, below throttle.min_available_mem_mb ${thresholdMb}.`;
     }
@@ -379,6 +396,8 @@ export function evaluateThrottle(input) {
     const pause = input.throttle.cpu_busy_pause;
     const resume = input.throttle.cpu_busy_resume;
     const minMem = input.throttle.min_available_mem_mb;
+    const warnMinFree = input.throttle.memory_warn_min_free_percent ??
+        DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT;
     // Each gate is opt-in: an unset threshold never blocks admission.
     let cpuBlocks = false;
     if (pause !== undefined && input.cpuCheckEnabled && input.busy !== null) {
@@ -389,8 +408,9 @@ export function evaluateThrottle(input) {
             cpuBlocks = input.busy >= pause;
         }
     }
-    // On darwin the signal is memory_pressure's: a warn or critical level holds
-    // even above the threshold, and a normal level holds only below it.
+    // On darwin the signal is memory_pressure's: a critical level holds even
+    // above the threshold, a warn level holds only at or below
+    // memory_warn_min_free_percent free, and otherwise only below the threshold.
     let memBlocks = false;
     let memorySignal;
     if (minMem !== undefined && input.availableMemMb !== null) {
@@ -398,8 +418,7 @@ export function evaluateThrottle(input) {
             ? input.memory
             : { source: "meminfo", available_mb: input.availableMemMb };
         memBlocks = input.availableMemMb < minMem ||
-            memorySignal.pressure_level === "warn" ||
-            memorySignal.pressure_level === "critical";
+            pressureLevelHolds(memorySignal, warnMinFree);
     }
     if (!cpuBlocks && !memBlocks) {
         return {
@@ -420,7 +439,7 @@ export function evaluateThrottle(input) {
         memory_hold: {
             ...memorySignal,
             threshold_mb: minMem,
-            message: formatMemoryHoldMessage(memorySignal, minMem),
+            message: formatMemoryHoldMessage(memorySignal, minMem, warnMinFree),
         },
     };
 }

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

@@ -1226,6 +1226,11 @@ export interface ThrottleConfig {
     cpu_busy_pause?: number;
     cpu_busy_resume?: number;
     min_available_mem_mb?: number;
+    /**
+     * darwin only: a warn memory_pressure level holds admission only at or
+     * below this free percentage (0-100). Unset means 20. Critical always holds.
+     */
+    memory_warn_min_free_percent?: number;
 }
 /** Session liveness windows from spec §9. Missing keys keep these documented defaults. */
 export interface LivenessWindows {