harnery 0.38.0 → 0.40.0

package/dist/core/resources/index.js

@@ -2,4 +2,5 @@ export * from "./contract.js";
 export * from "./sampler.js";
 export * from "./service.js";
 export * from "./service-status.js";
+export * from "./status.js";
 export * from "./storage.js";

package/dist/core/resources/native.d.ts

@@ -0,0 +1,36 @@
+import * as os from "node:os";
+import { type ResourceHostSample, type ResourceSampleResult, type ResourceSamplerState } from "./contract.js";
+export type NativeResourceCommand = (file: string, args: readonly string[]) => string | null;
+export interface NativeResourceSamplerOptions {
+    nowMs?: number;
+    platform?: "darwin" | "win32";
+    os?: Partial<Pick<typeof os, "cpus" | "totalmem" | "freemem" | "availableParallelism" | "loadavg">>;
+    command?: NativeResourceCommand;
+    backgroundHost?: boolean;
+    /** Supervisors use the background collector to keep native CPU sampling on cadence. */
+    hostCollector?: () => ResourceHostSample;
+}
+export declare function sampleNativeResources(_coordRoot: string, previous?: ResourceSamplerState, options?: NativeResourceSamplerOptions): ResourceSampleResult;
+export declare function parseMacVmStat(output: string): {
+    available_bytes: number;
+} | null;
+export declare function parseMacSwapUsage(output: string): {
+    total: number;
+    used: number;
+} | null;
+export interface WindowsHostOptions {
+    nowMs?: number;
+    command?: NativeResourceCommand;
+}
+export declare function createWindowsHostCollector(): (options?: WindowsHostOptions) => ResourceHostSample;
+export declare const collectWindowsHost: (options?: WindowsHostOptions) => ResourceHostSample;
+export type NativeResourceAsyncCommand = (file: string, args: readonly string[]) => Promise<string | null>;
+export interface WindowsHostBackgroundOptions {
+    nowMs?: number;
+    command?: NativeResourceAsyncCommand;
+}
+/** Return immediately; one process-wide probe refreshes all callers' cached host reading. */
+export declare function createWindowsHostBackgroundCollector(): (options?: WindowsHostBackgroundOptions) => ResourceHostSample;
+export declare const collectWindowsHostInBackground: (options?: WindowsHostBackgroundOptions) => ResourceHostSample;
+export declare function parseWindowsResourceOutput(output: string, nowMs?: number): ResourceHostSample;
+//# sourceMappingURL=native.d.ts.map

package/dist/core/resources/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../../../src/core/resources/native.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAGL,KAAK,kBAAkB,EAEvB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,GAAG,IAAI,CAAC;AAE7F,MAAM,WAAW,4BAA4B;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC9B,EAAE,CAAC,EAAE,OAAO,CACV,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,sBAAsB,GAAG,SAAS,CAAC,CACtF,CAAC;IACF,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,kBAAkB,CAAC;CAC1C;AAuDD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,oBAAoB,EAC/B,OAAO,GAAE,4BAAiC,GACzC,oBAAoB,CA4FtB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAejF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAUxF;AAiCD,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED,wBAAgB,0BAA0B,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,kBAAkB,CAuBjG;AAED,eAAO,MAAM,kBAAkB,aAzB0B,kBAAkB,KAAK,kBAyBlB,CAAC;AAE/D,MAAM,MAAM,0BAA0B,GAAG,CACvC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,KACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE5B,MAAM,WAAW,4BAA4B;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,0BAA0B,CAAC;CACtC;AAkBD,6FAA6F;AAC7F,wBAAgB,oCAAoC,IAAI,CACtD,OAAO,CAAC,EAAE,4BAA4B,KACnC,kBAAkB,CAuCtB;AAED,eAAO,MAAM,8BAA8B,aA1C/B,4BAA4B,KACnC,kBAyC+E,CAAC;AAmBrF,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,SAAa,GAAG,kBAAkB,CAsEjG"}

package/dist/core/resources/native.js

@@ -0,0 +1,418 @@
+import { execFile, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import * as os from "node:os";
+import { RESOURCE_SNAPSHOT_SCHEMA_VERSION, } from "./contract.js";
+const WINDOWS_CACHE_MS = 15_000;
+const COMMAND_TIMEOUT_MS = 4_000;
+// Queries are static and read-only. Individual optional providers may be absent.
+const WINDOWS_QUERY = `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$osInfo = Get-CimInstance Win32_OperatingSystem -Property TotalVisibleMemorySize,FreePhysicalMemory,NumberOfProcesses
+$processors = $null; $pagefiles = $null; $disks = $null
+try { $processors = @(Get-CimInstance Win32_Processor -Property NumberOfLogicalProcessors,LoadPercentage | Select-Object NumberOfLogicalProcessors,LoadPercentage) } catch {}
+try { $pagefiles = @(Get-CimInstance Win32_PageFileUsage -Property AllocatedBaseSize,CurrentUsage | Select-Object AllocatedBaseSize,CurrentUsage) } catch {}
+try { $disks = @(Get-CimInstance Win32_LogicalDisk -Filter 'DriveType = 3' -Property DeviceID,Size,FreeSpace | Select-Object DeviceID,Size,FreeSpace) } catch {}
+[pscustomobject]@{
+  sampled_at = [DateTime]::UtcNow.ToString('o')
+  memory_total_kib = $osInfo.TotalVisibleMemorySize
+  memory_available_kib = $osInfo.FreePhysicalMemory
+  process_count = $osInfo.NumberOfProcesses
+  processors = $processors
+  pagefiles = $pagefiles
+  disks = $disks
+} | ConvertTo-Json -Depth 4 -Compress
+`;
+function runNativeCommand(file, args) {
+    const macTools = {
+        vm_stat: "/usr/bin/vm_stat",
+        sysctl: "/usr/sbin/sysctl",
+        ps: "/bin/ps",
+    };
+    const executable = os.platform() === "darwin" ? (macTools[file] ?? file) : file;
+    const result = spawnSync(executable, [...args], {
+        encoding: "utf8",
+        timeout: COMMAND_TIMEOUT_MS,
+        maxBuffer: 1_048_576,
+        windowsHide: true,
+        env: os.platform() === "darwin" ? { ...process.env, LC_ALL: "C" } : undefined,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    return result.status === 0 && !result.error ? result.stdout : null;
+}
+function readCommand(command, file, args) {
+    try {
+        return command(file, args);
+    }
+    catch {
+        return null;
+    }
+}
+export function sampleNativeResources(_coordRoot, previous, options = {}) {
+    const started = performance.now();
+    const cpuBefore = process.cpuUsage();
+    const nowMs = options.nowMs ?? Date.now();
+    const platform = options.platform ?? os.platform();
+    if (platform !== "darwin" && platform !== "win32") {
+        throw new Error("native_resource_platform_invalid");
+    }
+    const nativeOs = { ...os, ...options.os };
+    const command = options.command ?? runNativeCommand;
+    const cpuRows = nativeOs.cpus();
+    const cpu = sumCpuCounters(cpuRows);
+    const reasons = ["native_process_attribution_unavailable"];
+    let available = nonnegative(nativeOs.freemem());
+    const total = positive(nativeOs.totalmem());
+    let swap = null;
+    let processCount = null;
+    if (platform === "darwin") {
+        const vm = parseMacVmStat(readCommand(command, "vm_stat", []) ?? "");
+        if (vm) {
+            available = vm.available_bytes;
+            reasons.push("memory_available_estimated_from_free_inactive_speculative_pages");
+        }
+        else {
+            reasons.push("vm_stat_unavailable_using_free_memory");
+        }
+        swap = parseMacSwapUsage(readCommand(command, "sysctl", ["-n", "vm.swapusage"]) ?? "");
+        processCount = parseProcessCount(readCommand(command, "ps", ["-axo", "pid="]));
+    }
+    else {
+        const host = options.hostCollector?.() ??
+            (options.backgroundHost
+                ? collectWindowsHostInBackground({ nowMs })
+                : collectWindowsHost({ nowMs, command }));
+        if (host.machine) {
+            swap =
+                host.machine.swap_total_bytes !== null && host.machine.swap_used_bytes !== null
+                    ? { total: host.machine.swap_total_bytes, used: host.machine.swap_used_bytes }
+                    : null;
+            processCount = host.machine.process_count;
+        }
+        else {
+            reasons.push(host.reason ?? "windows_auxiliary_metrics_unavailable");
+        }
+    }
+    if (total !== null && available !== null && available > total)
+        available = null;
+    const used = total !== null && available !== null ? total - available : null;
+    const cpuPercent = cpu ? cpuDeltaPercent(cpu, previous, nowMs) : null;
+    if (!cpu)
+        reasons.push("cpu_counters_unavailable");
+    if (!swap)
+        reasons.push("swap_unavailable");
+    if (processCount === null)
+        reasons.push("process_count_unavailable");
+    const collectorCpu = process.cpuUsage(cpuBefore);
+    return {
+        snapshot: {
+            schema_version: RESOURCE_SNAPSHOT_SCHEMA_VERSION,
+            sampled_at: new Date(nowMs).toISOString(),
+            interval_ms: previous ? Math.max(0, nowMs - previous.sampled_at_ms) : null,
+            sample_duration_ms: round1(performance.now() - started),
+            collector_cpu_ms: round1((collectorCpu.user + collectorCpu.system) / 1_000),
+            platform,
+            namespace: "host",
+            support: { state: "partial", sampler: platform, reason: reasons.join("; ") },
+            machine: {
+                cpu_percent: cpuPercent,
+                cpu_logical_count: cpuRows.length,
+                cpu_available_parallelism: nativeOs.availableParallelism(),
+                load_average: platform === "darwin" ? nativeOs.loadavg() : null,
+                memory_total_bytes: total,
+                memory_available_bytes: available,
+                memory_used_bytes: used,
+                memory_percent: used !== null && total !== null ? round1((used / total) * 100) : null,
+                swap_total_bytes: swap?.total ?? null,
+                swap_used_bytes: swap?.used ?? null,
+                process_count: processCount,
+            },
+            groups: [],
+            processes: [],
+            visible_process_count: 0,
+            omitted_process_count: processCount ?? 0,
+            unattributed_process_count: 0,
+        },
+        ...(cpu
+            ? {
+                state: {
+                    sampled_at_ms: nowMs,
+                    cpu_total_ticks: cpu.total,
+                    cpu_idle_ticks: cpu.idle,
+                    process_ticks: new Map(),
+                    process_owners: new Map(),
+                },
+            }
+            : {}),
+    };
+}
+export function parseMacVmStat(output) {
+    const pageSize = positive(output.match(/page size of (\d+) bytes/)?.[1]);
+    if (pageSize === null)
+        return null;
+    const fields = new Map();
+    for (const line of output.split(/\r?\n/)) {
+        const match = /^Pages (free|inactive|speculative):\s*(\d+)\.?\s*$/.exec(line.trim());
+        if (match)
+            fields.set(match[1], Number(match[2]));
+        else if (/^Pages (free|inactive|speculative):/.test(line.trim()))
+            return null;
+    }
+    const free = fields.get("free");
+    const inactive = fields.get("inactive");
+    if (free === undefined || inactive === undefined)
+        return null;
+    // Purgeable pages overlap other queues; adding them again would double count.
+    const available = (free + inactive + (fields.get("speculative") ?? 0)) * pageSize;
+    return Number.isSafeInteger(available) ? { available_bytes: available } : null;
+}
+export function parseMacSwapUsage(output) {
+    const values = new Map();
+    for (const match of output.matchAll(/\b(total|used)\s*=\s*([\d.]+)([KMGT]?)\b/g)) {
+        const multiplier = 1_024 ** (match[3] ? "KMGT".indexOf(match[3]) + 1 : 0);
+        const value = nonnegative(Number(match[2]) * multiplier);
+        if (value !== null)
+            values.set(match[1], Math.round(value));
+    }
+    const total = values.get("total");
+    const used = values.get("used");
+    return total !== undefined && used !== undefined && used <= total ? { total, used } : null;
+}
+function parseProcessCount(output) {
+    if (!output?.trim())
+        return null;
+    const rows = output.trim().split(/\r?\n/);
+    return rows.every((row) => /^\s*\d+\s*$/.test(row)) ? rows.length : null;
+}
+function sumCpuCounters(rows) {
+    let total = 0;
+    let idle = 0;
+    if (rows.length === 0)
+        return null;
+    for (const row of rows) {
+        const times = [row.times.user, row.times.nice, row.times.sys, row.times.idle, row.times.irq];
+        if (times.some((time) => nonnegative(time) === null))
+            return null;
+        total += times.reduce((sum, value) => sum + value, 0);
+        idle += row.times.idle;
+    }
+    return Number.isSafeInteger(total) && total > 0 ? { total, idle } : null;
+}
+function cpuDeltaPercent(cpu, previous, nowMs) {
+    if (!previous || nowMs <= previous.sampled_at_ms)
+        return null;
+    const totalDelta = cpu.total - previous.cpu_total_ticks;
+    const idleDelta = cpu.idle - previous.cpu_idle_ticks;
+    if (totalDelta <= 0 || idleDelta < 0 || idleDelta > totalDelta)
+        return null;
+    return round1(((totalDelta - idleDelta) / totalDelta) * 100);
+}
+export function createWindowsHostCollector() {
+    const cache = new WeakMap();
+    return (options = {}) => {
+        const nowMs = options.nowMs ?? Date.now();
+        const command = options.command ?? runNativeCommand;
+        const cached = cache.get(command);
+        if (cached && nowMs >= cached.at && nowMs - cached.at < WINDOWS_CACHE_MS)
+            return cached.sample;
+        let sample;
+        try {
+            const executable = command === runNativeCommand ? windowsPowerShellExecutable() : "powershell.exe";
+            const output = command(executable, windowsPowerShellArgs());
+            sample =
+                output === null
+                    ? unavailableWindowsHost(nowMs, "windows_host_query_failed")
+                    : parseWindowsResourceOutput(output, nowMs);
+        }
+        catch {
+            sample = unavailableWindowsHost(nowMs, "windows_host_query_failed");
+        }
+        // Cache failures too: missing interop/CIM must not launch PowerShell every tick.
+        cache.set(command, { at: nowMs, sample });
+        return sample;
+    };
+}
+export const collectWindowsHost = createWindowsHostCollector();
+function runWindowsCommandAsync(file, args) {
+    return new Promise((resolve) => {
+        execFile(file, [...args], {
+            encoding: "utf8",
+            timeout: COMMAND_TIMEOUT_MS,
+            maxBuffer: 1_048_576,
+            windowsHide: true,
+        }, (error, stdout) => resolve(error ? null : stdout));
+    });
+}
+/** Return immediately; one process-wide probe refreshes all callers' cached host reading. */
+export function createWindowsHostBackgroundCollector() {
+    const cache = new WeakMap();
+    return (options = {}) => {
+        const nowMs = options.nowMs ?? Date.now();
+        const command = options.command ?? runWindowsCommandAsync;
+        let entry = cache.get(command);
+        if (entry?.pending || (entry && nowMs >= entry.at && nowMs - entry.at < WINDOWS_CACHE_MS))
+            return entry.sample;
+        entry ??= {
+            at: nowMs,
+            sample: { ...unavailableWindowsHost(nowMs, "windows_host_query_pending"), state: "partial" },
+            pending: false,
+        };
+        entry.at = nowMs;
+        entry.pending = true;
+        cache.set(command, entry);
+        const current = entry;
+        const executable = command === runWindowsCommandAsync ? windowsPowerShellExecutable() : "powershell.exe";
+        // Resolve on a microtask so even an injected synchronous throw cannot interrupt a tick.
+        void Promise.resolve()
+            .then(() => command(executable, windowsPowerShellArgs()))
+            .then((output) => {
+            current.sample =
+                output === null
+                    ? unavailableWindowsHost(nowMs, "windows_host_query_failed")
+                    : parseWindowsResourceOutput(output, nowMs);
+        })
+            .catch(() => {
+            current.sample = unavailableWindowsHost(nowMs, "windows_host_query_failed");
+        })
+            .finally(() => {
+            current.pending = false;
+        });
+        return current.sample;
+    };
+}
+export const collectWindowsHostInBackground = createWindowsHostBackgroundCollector();
+function windowsPowerShellExecutable() {
+    // A WSL toolchain may deliberately exclude Windows executables from PATH.
+    const wslPowerShell = "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe";
+    return os.platform() === "linux" && existsSync(wslPowerShell) ? wslPowerShell : "powershell.exe";
+}
+function windowsPowerShellArgs() {
+    // Preserve the static multiline program across both Win32 and WSL argument transports.
+    return [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-EncodedCommand",
+        Buffer.from(WINDOWS_QUERY, "utf16le").toString("base64"),
+    ];
+}
+export function parseWindowsResourceOutput(output, nowMs = Date.now()) {
+    let row;
+    try {
+        const parsed = JSON.parse(output.replace(/^\uFEFF/, "").trim());
+        if (!isRecord(parsed))
+            throw new Error("invalid");
+        row = parsed;
+    }
+    catch {
+        return unavailableWindowsHost(nowMs, "windows_host_output_invalid");
+    }
+    const totalKiB = positive(row.memory_total_kib);
+    const availableKiB = nonnegative(row.memory_available_kib);
+    if (totalKiB === null || availableKiB === null || availableKiB > totalKiB) {
+        return unavailableWindowsHost(nowMs, "windows_host_memory_invalid");
+    }
+    const processors = records(row.processors);
+    let logical = 0;
+    let weightedCpu = 0;
+    let cpuValid = processors !== null && processors.length > 0;
+    for (const processor of processors ?? []) {
+        const count = positive(processor.NumberOfLogicalProcessors);
+        const percent = nonnegative(processor.LoadPercentage);
+        if (count === null || !Number.isInteger(count))
+            cpuValid = false;
+        else
+            logical += count;
+        if (count === null || percent === null || percent > 100)
+            cpuValid = false;
+        else
+            weightedCpu += count * percent;
+    }
+    const pagefiles = records(row.pagefiles);
+    let swapTotal = 0;
+    let swapUsed = 0;
+    let swapValid = pagefiles !== null;
+    for (const file of pagefiles ?? []) {
+        const total = nonnegative(file.AllocatedBaseSize);
+        const used = nonnegative(file.CurrentUsage);
+        if (total === null || used === null || used > total)
+            swapValid = false;
+        else {
+            swapTotal += total * 1_048_576;
+            swapUsed += used * 1_048_576;
+        }
+    }
+    const disks = (records(row.disks) ?? []).map(parseWindowsDisk);
+    const processCount = nonnegative(row.process_count);
+    const machine = {
+        cpu_percent: cpuValid && logical > 0 ? round1(weightedCpu / logical) : null,
+        cpu_logical_count: logical,
+        load_average: null,
+        memory_total_bytes: totalKiB * 1_024,
+        memory_available_bytes: availableKiB * 1_024,
+        memory_used_bytes: (totalKiB - availableKiB) * 1_024,
+        memory_percent: round1(((totalKiB - availableKiB) / totalKiB) * 100),
+        swap_total_bytes: swapValid ? swapTotal : null,
+        swap_used_bytes: swapValid ? swapUsed : null,
+        process_count: processCount !== null && Number.isInteger(processCount) ? processCount : null,
+    };
+    const complete = cpuValid &&
+        swapValid &&
+        machine.process_count !== null &&
+        disks.length > 0 &&
+        disks.every((disk) => disk.state === "supported");
+    return {
+        platform: "win32",
+        sampled_at: typeof row.sampled_at === "string" && Number.isFinite(Date.parse(row.sampled_at))
+            ? new Date(row.sampled_at).toISOString()
+            : new Date(nowMs).toISOString(),
+        state: complete ? "supported" : "partial",
+        machine,
+        disks,
+        ...(!complete ? { reason: "windows_host_optional_metrics_unavailable" } : {}),
+    };
+}
+function parseWindowsDisk(row) {
+    const total = positive(row.Size);
+    const available = nonnegative(row.FreeSpace);
+    const valid = typeof row.DeviceID === "string" && total !== null && available !== null && available <= total;
+    return {
+        path: typeof row.DeviceID === "string" ? `${row.DeviceID}\\` : "unknown",
+        state: valid ? "supported" : "error",
+        total_bytes: valid ? total : null,
+        available_bytes: valid ? available : null,
+        used_percent: valid ? round1(((total - available) / total) * 100) : null,
+        ...(!valid ? { reason: "windows_disk_counters_invalid" } : {}),
+    };
+}
+function unavailableWindowsHost(nowMs, reason) {
+    return {
+        platform: "win32",
+        sampled_at: new Date(nowMs).toISOString(),
+        state: "error",
+        machine: null,
+        disks: [],
+        reason,
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function records(value) {
+    return Array.isArray(value) && value.every(isRecord) ? value : null;
+}
+function nonnegative(value) {
+    if (typeof value !== "number" && !(typeof value === "string" && /^\d+(\.\d+)?$/.test(value)))
+        return null;
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 0 && number <= Number.MAX_SAFE_INTEGER
+        ? number
+        : null;
+}
+function positive(value) {
+    const number = nonnegative(value);
+    return number !== null && number > 0 ? number : null;
+}
+function round1(value) {
+    return Math.round(value * 10) / 10;
+}

package/dist/core/resources/sampler.d.ts

@@ -1,6 +1,8 @@
 import { type ResourceSampleResult, type ResourceSamplerState } from "./contract.js";
 interface ResourceSamplerOptions {
+    backgroundHost?: boolean;
     procRoot?: string;
+    sysRoot?: string;
     nowMs?: number;
     clockTicks?: number;
     pageSize?: number;

package/dist/core/resources/sampler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../../../src/core/resources/sampler.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAE1B,MAAM,eAAe,CAAC;AA0BvB,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClD,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,YAAY;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAKD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,oBAAoB,EAC/B,OAAO,GAAE,sBAA2B,GACnC,oBAAoB,CAmJtB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CA0BP;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAuB7D"}
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../../../src/core/resources/sampler.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAE1B,MAAM,eAAe,CAAC;AAgCvB,UAAU,sBAAsB;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClD,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,YAAY;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAKD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,oBAAoB,EAC/B,OAAO,GAAE,sBAA2B,GACnC,oBAAoB,CA+BtB;AA2JD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CA0BP;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAuB7D"}

package/dist/core/resources/sampler.js

@@ -1,12 +1,14 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, readlinkSync } from "node:fs";
-import { cpus, loadavg, platform, release } from "node:os";
+import { availableParallelism, cpus, loadavg, platform, release } from "node:os";
 import { basename, join } from "node:path";
 import { performance } from "node:perf_hooks";
 import { readLiveCoordinationRows } from "../agents/state/live-coordination-view.js";
 import { parsePidmapRow } from "../agents/state/pidmap.js";
 import { checkPidToken } from "../agents/state/proc-start.js";
 import { RESOURCE_SNAPSHOT_SCHEMA_VERSION, } from "./contract.js";
+import { collectWindowsHost, collectWindowsHostInBackground, sampleNativeResources, } from "./native.js";
+import { collectSystemResources } from "./system.js";
 const DEFAULT_CLOCK_TICKS = 100;
 const DEFAULT_PAGE_SIZE = 4_096;
 const DEFAULT_UNATTRIBUTED_CPU_FLOOR = 0.5;
@@ -16,6 +18,34 @@ const MAX_COMMAND_CHARS = 240;
 let cachedClockTicks;
 let cachedPageSize;
 export function sampleResources(coordRoot, previous, options = {}) {
+    const started = performance.now();
+    const cpuBefore = process.cpuUsage();
+    const currentPlatform = platform();
+    const result = currentPlatform === "darwin" || currentPlatform === "win32"
+        ? sampleNativeResources(coordRoot, previous, {
+            nowMs: options.nowMs,
+            backgroundHost: options.backgroundHost,
+        })
+        : sampleProcessResources(coordRoot, previous, options);
+    Object.assign(result.snapshot, collectSystemResources(coordRoot, {
+        procRoot: options.procRoot,
+        sysRoot: options.sysRoot,
+        nowMs: options.nowMs,
+        namespace: result.snapshot.namespace,
+    }));
+    result.snapshot.machine.cpu_available_parallelism = availableParallelism();
+    // A fixture procfs has no relationship to the actual Windows host.
+    if (result.snapshot.namespace === "wsl" && !options.procRoot) {
+        result.snapshot.host = options.backgroundHost
+            ? collectWindowsHostInBackground()
+            : collectWindowsHost();
+    }
+    result.snapshot.sample_duration_ms = round1(performance.now() - started);
+    const cpuUsed = process.cpuUsage(cpuBefore);
+    result.snapshot.collector_cpu_ms = round1((cpuUsed.user + cpuUsed.system) / 1_000);
+    return result;
+}
+function sampleProcessResources(coordRoot, previous, options = {}) {
     const started = performance.now();
     const cpuBefore = process.cpuUsage();
     const nowMs = options.nowMs ?? Date.now();

package/dist/core/resources/status.d.ts

@@ -0,0 +1,61 @@
+import { type PressureAssessment, type PressureHysteresisState } from "../diagnostics/contract.js";
+import { type SupervisorCapability, type SupervisorPressureRecord } from "../supervisor/contract.js";
+import { type ResourceDiskSample, type ResourceHostSample, type ResourceIoSample, type ResourceMachineSample, type ResourceOomSample, type ResourcePressureSample, type ResourceProcessSample, type ResourceSnapshot } from "./contract.js";
+export declare const RESOURCE_STATUS_STALE_MS = 15000;
+export declare const RESOURCE_STATUS_MAX_BYTES: number;
+export declare const RESOURCE_STATUS_PROCESS_LIMIT = 20;
+export declare const RESOURCE_HOST_STATUS_STALE_MS = 30000;
+export interface ResourceStatus {
+    schema_version: 2;
+    state: "fresh" | "stale" | "unavailable";
+    reason: string | null;
+    sampled_at: string | null;
+    sample_age_ms: number | null;
+    stale_after_ms: number;
+    platform: NodeJS.Platform | null;
+    namespace: ResourceSnapshot["namespace"];
+    support: ResourceSnapshot["support"] | null;
+    writer: {
+        running: boolean;
+        stale: boolean;
+    };
+    /**
+     * The one published pressure assessment, read from the observer's record so
+     * this surface, the prompt notice, the dashboard, and a diagnostic bundle all
+     * report the same answer for the same input.
+     */
+    assessment: PressureAssessment;
+    /** The state the sample before the published one carried forward. */
+    prior_hysteresis: PressureHysteresisState | null;
+    /** Where the assessment came from, and why it is missing when it is. */
+    assessment_capability: SupervisorCapability;
+    machine: ResourceMachineSample | null;
+    disks: ResourceDiskSample[];
+    pressure: ResourcePressureSample | null;
+    oom: ResourceOomSample | null;
+    io: ResourceIoSample | null;
+    host: ResourceHostSample | null;
+    processes?: Array<Pick<ResourceProcessSample, "pid" | "name" | "cpu_percent" | "rss_bytes" | "owner_kind" | "owner_id">>;
+    processes_omitted?: number;
+}
+/** A bounded cache-only read. Never samples the OS or starts the writer. */
+export declare function readResourceStatus(coordRoot: string, options?: {
+    nowMs?: number;
+    includeProcesses?: boolean;
+}): ResourceStatus;
+export declare function formatResourceSummary(status: ResourceStatus): string;
+export declare function formatResourceStatus(status: ResourceStatus, bin: string): string;
+export declare const PRESSURE_RECORD_MAX_BYTES: number;
+export interface PublishedPressure {
+    assessment: PressureAssessment;
+    prior_hysteresis: PressureHysteresisState | null;
+    capability: SupervisorCapability;
+    record: SupervisorPressureRecord | null;
+}
+/**
+ * Read the assessment the observer published. Bounded, cache only, and never a
+ * computation: a missing, stale, or malformed record yields `unknown` with the
+ * reason stated, because a gap in the evidence is not a measurement of health.
+ */
+export declare function readPublishedPressure(coordRoot: string, nowMs?: number, writer?: ResourceStatus["writer"]): PublishedPressure;
+//# sourceMappingURL=status.d.ts.map

package/dist/core/resources/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/core/resources/status.ts"],"names":[],"mappings":"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"}