@kal-elsam/kairo-runtime 0.10.0 → 0.12.0

package/src/global/observability/hermes-probe.js

@@ -0,0 +1,171 @@
+import { isAbsolute } from "node:path";
+import {
+  parseVersionFromOutput,
+  probeCommand as defaultProbeCommand
+} from "../cli-probe.js";
+import { normalizeProbeResult } from "./probe-contract.js";
+
+/** Surfaces recognized from `hermes --help` only — never executed by this probe. */
+export const HERMES_DIAGNOSTIC_SURFACES = Object.freeze(["version", "doctor", "status"]);
+export const HERMES_MANDATORY_SURFACES = Object.freeze(["version", "doctor"]);
+
+const WHICH_TIMEOUT_MS = 3000;
+const VERSION_TIMEOUT_MS = 8000;
+const HELP_TIMEOUT_MS = 8000;
+const MAX_PROBE_BYTES = 65_536;
+
+function result(partial) {
+  return normalizeProbeResult({
+    id: "hermes", version: null, contractCompatible: null,
+    diagnostics: [], evidence: [], error: null, ...partial
+  }, "hermes");
+}
+
+function boundText(raw, maxBytes = MAX_PROBE_BYTES) {
+  const text = String(raw ?? "");
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+  return Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");
+}
+
+function whichAbsolutePath(command, env, run = defaultProbeCommand) {
+  const which = run("which", [command], { env, timeoutMs: WHICH_TIMEOUT_MS });
+  if (!which?.ok) return "";
+  const path = String(which.stdout ?? "").trim().split(/\r?\n/)[0] ?? "";
+  return isAbsolute(path) ? path : "";
+}
+
+/** Resolve absolute Hermes binary; never return a bare command name. */
+export function resolveHermesBinaryPath(command = "hermes", env = process.env, {
+  whichCommand,
+  probeCommand = defaultProbeCommand
+} = {}) {
+  const resolver = typeof whichCommand === "function"
+    ? whichCommand
+    : (cmd, e) => whichAbsolutePath(cmd, e, probeCommand);
+  const resolved = resolver(command, env) || null;
+  return resolved && isAbsolute(resolved) ? resolved : null;
+}
+
+/** Presence means the CLI *declares* the surface — not that Kairo may run it. */
+export function detectHermesDiagnosticSurfaces(helpText) {
+  const text = boundText(helpText);
+  const found = Object.create(null);
+  for (const name of HERMES_DIAGNOSTIC_SURFACES) {
+    found[name] = new RegExp(`(?:^|[\\s,{|/])${name}(?=[\\s,}|/-]|$)`, "m").test(text);
+  }
+  return Object.freeze(found);
+}
+
+function softError(label, kind, evidence, extra = {}) {
+  return result({
+    state: "error",
+    diagnostics: [`hermes ${label} ${kind === "timeout" ? "timed out" : "failed"}`],
+    error: kind === "timeout" ? "timeout" : kind === "exit" ? `exit ${extra.code}` : "spawn_error",
+    evidence,
+    ...extra.fields
+  });
+}
+
+function spawnFailure(label, probeResult, evidence, extra = {}) {
+  if (probeResult?.timedOut) return softError(label, "timeout", evidence, extra);
+  if (probeResult?.error) return softError(label, "spawn", evidence, extra);
+  if (probeResult?.status !== 0) {
+    return softError(label, "exit", evidence, { ...extra, code: probeResult?.status ?? "unknown" });
+  }
+  return null;
+}
+
+/** which: preserve timeout/spawn_error; exit/empty → missing (not failure). */
+function whichFailure(probeResult, evidence) {
+  if (probeResult?.timedOut) return softError("which", "timeout", evidence);
+  if (probeResult?.error) return softError("which", "spawn", evidence);
+  return null;
+}
+
+function runProbe(probeCommand, cmd, args, opts) {
+  try { return { ok: true, value: probeCommand(cmd, args, opts) }; }
+  catch { return { ok: false }; }
+}
+
+export async function probeHermes({
+  env = process.env,
+  cwd = process.cwd(),
+  whichCommand,
+  probeCommand = defaultProbeCommand
+} = {}) {
+  const noBinary = [{ kind: "binary", path: null }];
+  let path;
+
+  if (typeof whichCommand === "function") {
+    try { path = resolveHermesBinaryPath("hermes", env, { whichCommand, probeCommand }); }
+    catch { return softError("which", "spawn", noBinary); }
+  } else {
+    const inv = runProbe(probeCommand, "which", ["hermes"], { env, timeoutMs: WHICH_TIMEOUT_MS });
+    if (!inv.ok) return softError("which", "spawn", noBinary);
+    const fail = whichFailure(inv.value, noBinary);
+    if (fail) return fail;
+    const candidate = String(inv.value?.stdout ?? "").trim().split(/\r?\n/)[0] ?? "";
+    path = inv.value?.ok && isAbsolute(candidate) ? candidate : null;
+  }
+
+  if (!path) {
+    return result({
+      state: "missing",
+      diagnostics: [
+        "hermes absolute binary not resolved. Install Hermes Agent separately, then re-run the probe."
+      ],
+      evidence: noBinary
+    });
+  }
+
+  const evidence = [{ kind: "binary", path }];
+  const versionInv = runProbe(probeCommand, path, ["--version"], {
+    cwd, env, timeoutMs: VERSION_TIMEOUT_MS
+  });
+  if (!versionInv.ok) return softError("--version", "spawn", evidence);
+  const versionFail = spawnFailure("--version", versionInv.value, evidence);
+  if (versionFail) return versionFail;
+  const version = parseVersionFromOutput(boundText(versionInv.value.stdout));
+  evidence.push({ kind: "version", version, ok: true });
+  if (!version) {
+    return result({
+      state: "incompatible", contractCompatible: false, evidence,
+      diagnostics: ["hermes --version did not yield a parseable version"]
+    });
+  }
+
+  const helpInv = runProbe(probeCommand, path, ["--help"], {
+    cwd, env, timeoutMs: HELP_TIMEOUT_MS
+  });
+  if (!helpInv.ok) return softError("--help", "spawn", evidence, { fields: { version } });
+  const helpFail = spawnFailure("--help", helpInv.value, evidence, { fields: { version } });
+  if (helpFail) return helpFail;
+
+  const surfaces = detectHermesDiagnosticSurfaces(helpInv.value.stdout);
+  // Capability availability only — surfaces were not executed.
+  evidence.push({ kind: "diagnostic_surfaces", surfaces: { ...surfaces }, executed: false });
+
+  const missingMandatory = HERMES_MANDATORY_SURFACES.filter((name) => !surfaces[name]);
+  if (missingMandatory.length) {
+    return result({
+      state: "incompatible", version, contractCompatible: false, evidence,
+      diagnostics: missingMandatory.map((name) => `missing mandatory surface in --help: ${name}`)
+    });
+  }
+
+  return result({
+    state: "available", version, contractCompatible: true, evidence,
+    diagnostics: surfaces.status ? [] : ["optional surface absent in --help: status"]
+  });
+}
+
+export function createHermesProbe(deps = {}) {
+  return {
+    id: "hermes",
+    declaredEvents: Object.freeze([]),
+    declaredActions: Object.freeze([]),
+    async probe(context = {}) {
+      return probeHermes({ ...deps, ...context, env: context.env ?? deps.env ?? process.env });
+    }
+  };
+}

package/src/global/observability/index.js

@@ -0,0 +1,85 @@
+import { createGentleProbe } from "./gentle-probe.js";
+import { createGraphifyProbe } from "./graphify-probe.js";
+import { createHermesProbe } from "./hermes-probe.js";
+import { getObservabilityProbe, registerObservabilityProbe } from "./probe-registry.js";
+
+export {
+  OBSERVABILITY_PROBE_STATES,
+  assertObservabilityProbeContract,
+  normalizeProbeResult
+} from "./probe-contract.js";
+export {
+  registerObservabilityProbe,
+  getObservabilityProbe,
+  listObservabilityProbes,
+  resetObservabilityProbesForTests
+} from "./probe-registry.js";
+export { buildObservabilitySnapshot } from "./build-observability-snapshot.js";
+export {
+  PASSIVE_SNAPSHOT_TTL_MS,
+  PASSIVE_SNAPSHOT_MAX_ENTRIES,
+  buildPassiveSnapshotKey,
+  resetPassiveSnapshotFlightForTests,
+  passiveSnapshotInFlightSizeForTests,
+  runPassiveObservabilitySnapshot
+} from "./passive-snapshot-flight.js";
+export {
+  SUPPORTED_PROTOCOL, SUPPORTED_SCHEMA, SUPPORTED_CONTRACT,
+  SUPPORTED_MANDATORY_FEATURES, evaluateGentleCapabilities, probeGentle, createGentleProbe,
+  resolveGentleBinaryPath
+} from "./gentle-probe.js";
+export { exportGentleReviewBundle, resolveNegotiatedGentleBinary } from "./gentle-bundle-export.js";
+export { importGentleReviewBundle } from "./gentle-bundle-import.js";
+export {
+  inspectGraphArtifact, assertGraphInsideWorkspace,
+  resolveGraphifyBinaryPath, resolveGitHeadSha, scrubGitOverrideEnv,
+  probeGraphify, createGraphifyProbe
+} from "./graphify-probe.js";
+export {
+  GRAPHIFY_PARSE_TTL_MS,
+  GRAPHIFY_PARSE_MAX_ENTRIES,
+  buildGraphifyParseIdentity,
+  resetGraphifyParseCacheForTests,
+  inspectGraphArtifactCached
+} from "./graphify-parse-cache.js";
+export { runGraphifyOp, runGraphifyCli } from "./graphify-ops.js";
+export {
+  HERMES_DIAGNOSTIC_SURFACES, HERMES_MANDATORY_SURFACES,
+  detectHermesDiagnosticSurfaces, resolveHermesBinaryPath,
+  probeHermes, createHermesProbe
+} from "./hermes-probe.js";
+export {
+  DEFAULT_HERMES_API_URL,
+  HERMES_ACTIVITY_LIMIT_DEFAULT, HERMES_ACTIVITY_LIMIT_MAX,
+  HERMES_ACTIVITY_TIMEOUT_MS, HERMES_ACTIVE_WINDOW_MS,
+  assertHermesLoopbackUrl, capabilitiesAdvertiseSessionsList,
+  normalizeHermesSession, loadHermesActivity
+} from "./hermes-activity.js";
+export {
+  SYSTEM_RESOURCES_TIMEOUT_MS, PROCESS_ALLOWLIST,
+  parseProcessTable, loadSystemResources
+} from "./system-resources.js";
+export { recommendSystemResources } from "./resource-advisor.js";
+export {
+  ECOSYSTEM_UPDATES_CACHE_MS,
+  ECOSYSTEM_UPDATES_TIMEOUT_MS,
+  AGENT_SKILLS_PINNED_REV,
+  parseGentleUpdateOutput,
+  parseHermesUpdateCheck,
+  loadEcosystemUpdates
+} from "./ecosystem-updates.js";
+export {
+  SOFT_LINK_WINDOW_MS,
+  parseCompanionTimestamp,
+  resolveRunTimestamp,
+  resolveReviewTimestamp,
+  softLinkReviewToRun,
+  summarizeCompanionProbes,
+  buildCompanionSnapshot
+} from "./build-companion-snapshot.js";
+
+export function ensureObservabilityProbesRegistered() {
+  if (!getObservabilityProbe("gentle")) registerObservabilityProbe(createGentleProbe());
+  if (!getObservabilityProbe("graphify")) registerObservabilityProbe(createGraphifyProbe());
+  if (!getObservabilityProbe("hermes")) registerObservabilityProbe(createHermesProbe());
+}

package/src/global/observability/passive-snapshot-flight.js

@@ -0,0 +1,93 @@
+import { buildObservabilitySnapshot } from "./build-observability-snapshot.js";
+import { listObservabilityProbes } from "./probe-registry.js";
+
+/** Short TTL for passive Cockpit/MCP observability only — never suite authority. */
+export const PASSIVE_SNAPSHOT_TTL_MS = 5_000;
+export const PASSIVE_SNAPSHOT_MAX_ENTRIES = 8;
+
+/** @type {Map<string, Promise<unknown>>} */
+const flights = new Map();
+/** @type {Map<string, { value: unknown, expiresAt: number }>} */
+const completed = new Map();
+
+export function resetPassiveSnapshotFlightForTests() {
+  flights.clear();
+  completed.clear();
+}
+
+export function passiveSnapshotFlightSizeForTests() {
+  return completed.size;
+}
+
+export function passiveSnapshotInFlightSizeForTests() {
+  return flights.size;
+}
+
+export function buildPassiveSnapshotKey(context = {}, {
+  listProviders = listObservabilityProbes
+} = {}) {
+  const workspace = String(context.workspaceRoot ?? context.cwd ?? "");
+  const head = String(context.headSha ?? "");
+  const providers = listProviders().map((p) => p.id).sort().join(",");
+  return `${workspace}\0${head}\0${providers}`;
+}
+
+function touchCompleted(key, entry) {
+  completed.delete(key);
+  completed.set(key, entry);
+}
+
+function evictOldestCompleted(maxEntries) {
+  while (completed.size > maxEntries) {
+    const oldest = completed.keys().next().value;
+    if (oldest == null) break;
+    completed.delete(oldest);
+  }
+}
+
+/**
+ * Single-flight + short TTL for passive observability snapshots.
+ * force skips completed hits but joins identical in-flight work.
+ * Errors clear that key's flight and completed entry so the next call rebuilds
+ * (a failed force refresh must not leave a stale completed hit).
+ * LRU applies only to completed values — never evicts active flights.
+ */
+export async function runPassiveObservabilitySnapshot(context = {}, {
+  force = false,
+  build = buildObservabilitySnapshot,
+  now = Date.now,
+  listProviders = listObservabilityProbes,
+  ttlMs = PASSIVE_SNAPSHOT_TTL_MS,
+  maxEntries = PASSIVE_SNAPSHOT_MAX_ENTRIES
+} = {}) {
+  const key = buildPassiveSnapshotKey(context, { listProviders });
+  const inflight = flights.get(key);
+  if (inflight) return inflight;
+
+  const cached = completed.get(key);
+  if (!force && cached && cached.expiresAt > now()) {
+    touchCompleted(key, cached);
+    return cached.value;
+  }
+
+  const promise = Promise.resolve()
+    .then(() => build(context))
+    .then((value) => {
+      if (flights.get(key) === promise) {
+        flights.delete(key);
+        touchCompleted(key, { value, expiresAt: now() + ttlMs });
+        evictOldestCompleted(maxEntries);
+      }
+      return value;
+    })
+    .catch((err) => {
+      if (flights.get(key) === promise) {
+        flights.delete(key);
+        completed.delete(key);
+      }
+      throw err;
+    });
+
+  flights.set(key, promise);
+  return promise;
+}

package/src/global/observability/probe-contract.js

@@ -0,0 +1,38 @@
+/** Observability probe contract — read-only; no lifecycle mutations. */
+
+export const OBSERVABILITY_PROBE_STATES = Object.freeze([
+  "missing", "available", "incompatible", "error"
+]);
+
+export function assertObservabilityProbeContract(probe) {
+  if (probe == null || typeof probe !== "object" || Array.isArray(probe)) {
+    throw new Error("Observability probe must be an object.");
+  }
+  if (typeof probe.id !== "string" || !probe.id) {
+    throw new Error("Observability probe id must be a non-empty string.");
+  }
+  if (typeof probe.probe !== "function") {
+    throw new Error(`Observability probe "${probe.id}" is missing probe().`);
+  }
+  if (!Array.isArray(probe.declaredEvents)) {
+    throw new Error(`Observability probe "${probe.id}" declaredEvents must be an array.`);
+  }
+  if (!Array.isArray(probe.declaredActions)) {
+    throw new Error(`Observability probe "${probe.id}" declaredActions must be an array.`);
+  }
+  return probe;
+}
+
+export function normalizeProbeResult(raw, fallbackId) {
+  const id = typeof raw?.id === "string" && raw.id ? raw.id : fallbackId;
+  const state = OBSERVABILITY_PROBE_STATES.includes(raw?.state) ? raw.state : "error";
+  return {
+    id,
+    state,
+    version: raw?.version ?? null,
+    contractCompatible: typeof raw?.contractCompatible === "boolean" ? raw.contractCompatible : null,
+    diagnostics: Array.isArray(raw?.diagnostics) ? raw.diagnostics.map(String) : [],
+    evidence: Array.isArray(raw?.evidence) ? raw.evidence : [],
+    error: raw?.error == null ? null : String(raw.error)
+  };
+}

package/src/global/observability/probe-registry.js

@@ -0,0 +1,30 @@
+import { assertObservabilityProbeContract } from "./probe-contract.js";
+
+const probes = new Map();
+
+export function registerObservabilityProbe(probe) {
+  assertObservabilityProbeContract(probe);
+  if (probes.has(probe.id)) {
+    throw new Error(`Observability probe "${probe.id}" is already registered.`);
+  }
+  const frozen = Object.freeze({
+    id: probe.id,
+    probe: probe.probe.bind(probe),
+    declaredEvents: Object.freeze([...(probe.declaredEvents ?? [])]),
+    declaredActions: Object.freeze([...(probe.declaredActions ?? [])])
+  });
+  probes.set(probe.id, frozen);
+  return frozen;
+}
+
+export function getObservabilityProbe(id) {
+  return probes.get(id) ?? null;
+}
+
+export function listObservabilityProbes() {
+  return [...probes.values()];
+}
+
+export function resetObservabilityProbesForTests() {
+  probes.clear();
+}

package/src/global/observability/resource-advisor.js

@@ -0,0 +1,71 @@
+/**
+ * Deterministic Local Resource Advisor — observe and recommend only.
+ * Never deletes, compacts, or kills. Deep-scan is explicit opt-in.
+ */
+
+export function recommendSystemResources(resources, { deepScan = false } = {}) {
+  const recommendations = [];
+  if (resources == null || typeof resources !== "object") {
+    return { recommendations, deepScan: false };
+  }
+  const state = typeof resources.state === "string" ? resources.state : "error";
+  if (state === "unavailable" || state === "error" || state === "incompatible") {
+    return { recommendations, deepScan: Boolean(deepScan) };
+  }
+
+  const diskPct = resources.disk?.freePercent;
+  if (typeof diskPct === "number" && Number.isFinite(diskPct)) {
+    if (diskPct < 10) {
+      recommendations.push({
+        id: "free-disk-critical",
+        severity: "critical",
+        title: "Free disk space",
+        detail: "Disk free below 10%. Clear caches manually after review — Kairo performs no removals."
+      });
+    } else if (diskPct < 20) {
+      recommendations.push({
+        id: "free-disk-warning",
+        severity: "warning",
+        title: "Disk space running low",
+        detail: "Disk free below 20%. Prefer quitting unused apps before large downloads."
+      });
+    }
+  }
+
+  const ramPct = resources.memory?.freePercent;
+  if (typeof ramPct === "number" && Number.isFinite(ramPct) && ramPct < 15) {
+    recommendations.push({
+      id: "quit-heavy-apps",
+      severity: "warning",
+      title: "Quit heavy apps",
+      detail: "Memory free below 15%. Quit unused agents/browsers; Kairo never terminates processes."
+    });
+  }
+
+  const tracked = Array.isArray(resources.processes?.tracked) ? resources.processes.tracked : [];
+  const busy = tracked.filter((entry) =>
+    entry != null && typeof entry === "object"
+    && typeof entry.name === "string"
+    && Number.isInteger(entry.count) && entry.count >= 2
+  );
+  if (busy.length > 0) {
+    const names = busy.map((entry) => entry.name).join(", ");
+    recommendations.push({
+      id: "inspect-tracked-apps",
+      severity: "info",
+      title: "Inspect local heavy apps",
+      detail: `Tracked pressure: ${names}. Review in Activity Monitor — no auto-quit.`
+    });
+  }
+
+  if (deepScan === true) {
+    recommendations.push({
+      id: "deep-scan-known-caches",
+      severity: "info",
+      title: "Inspect known local caches",
+      detail: "Opt-in deep scan only. Lists known cache/DB locations for human review — performs no removals."
+    });
+  }
+
+  return { recommendations, deepScan: deepScan === true };
+}

package/src/global/observability/system-resources.js

@@ -0,0 +1,171 @@
+import { probeCommand as defaultProbeCommand } from "../cli-probe.js";
+
+export const SYSTEM_RESOURCES_TIMEOUT_MS = 2000;
+export const PROCESS_ALLOWLIST = Object.freeze([
+  "cursor", "codex", "chatgpt", "brave", "teams", "obsidian", "ollama"
+]);
+
+const BIN = Object.freeze({
+  sysctl: "/usr/sbin/sysctl", vmStat: "/usr/bin/vm_stat", pagesize: "/usr/bin/pagesize",
+  df: "/bin/df", ps: "/bin/ps"
+});
+
+const emptyProcesses = () => ({ totalCount: 0, zombieCount: 0, tracked: [] });
+
+function envelope(state, nowMs, diagnostics = [], partial = {}) {
+  return {
+    state, sampledAt: new Date(nowMs).toISOString(), diagnostics: diagnostics.map(String),
+    memory: null, swap: null, disk: null, processes: emptyProcesses(),
+    thermal: { state: "unavailable" }, ssdWear: { state: "unavailable" }, ...partial
+  };
+}
+
+function invoke(probeCommand, cmd, args, timeoutMs) {
+  try { return { ok: true, value: probeCommand(cmd, args, { timeoutMs }) }; }
+  catch { return { ok: false }; }
+}
+
+function classify(inv) {
+  if (!inv.ok) return { kind: "spawn_error" };
+  const r = inv.value;
+  if (r?.timedOut) return { kind: "timeout" };
+  if (r?.error) {
+    return /EACCES|EPERM|permission/i.test(String(r.error))
+      ? { kind: "permission_denied" } : { kind: "spawn_error" };
+  }
+  if (!r?.ok) {
+    return /permission|denied|Operation not permitted/i.test(String(r.stderr ?? ""))
+      ? { kind: "permission_denied" } : { kind: "exit" };
+  }
+  return { kind: "ok", stdout: String(r.stdout ?? "") };
+}
+
+function parseBytesUnit(raw) {
+  const m = String(raw).trim().match(/^([\d.]+)\s*([KMGTP]?)/i);
+  if (!m || !Number.isFinite(Number(m[1]))) return null;
+  const mul = { B: 1, K: 1024, M: 1024 ** 2, G: 1024 ** 3, T: 1024 ** 4, P: 1024 ** 5 };
+  return Math.round(Number(m[1]) * (mul[(m[2] || "B").toUpperCase()] ?? 1));
+}
+
+function parseSwap(stdout) {
+  const grab = (label) => {
+    const m = stdout.match(new RegExp(`${label}\\s*=\\s*([\\d.]+\\s*[KMGTP]?)`, "i"));
+    return m ? parseBytesUnit(m[1]) : null;
+  };
+  const totalBytes = grab("total"), usedBytes = grab("used"), freeBytes = grab("free");
+  return totalBytes == null || usedBytes == null || freeBytes == null
+    ? null : { totalBytes, usedBytes, freeBytes };
+}
+
+function parseDf(stdout) {
+  const lines = String(stdout).trim().split(/\r?\n/).filter(Boolean);
+  if (lines.length < 2) return null;
+  const cols = lines.at(-1).trim().split(/\s+/);
+  const totalKb = Number(cols[1]), availKb = Number(cols[3]);
+  if (!Number.isFinite(totalKb) || !Number.isFinite(availKb) || totalKb <= 0) return null;
+  const totalBytes = totalKb * 1024, freeBytes = availKb * 1024;
+  return { totalBytes, freeBytes, freePercent: Math.round((freeBytes / totalBytes) * 1000) / 10 };
+}
+
+function matchAllowlist(comm) {
+  const name = String(comm ?? "").toLowerCase();
+  return PROCESS_ALLOWLIST.find((key) => name.includes(key)) ?? null;
+}
+
+export function parseProcessTable(stdout) {
+  let totalCount = 0, zombieCount = 0;
+  const counts = Object.fromEntries(PROCESS_ALLOWLIST.map((k) => [k, 0]));
+  for (const line of String(stdout).split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const m = trimmed.match(/^(\d+)\s+(\S+)\s+(.+)$/);
+    if (!m) continue;
+    totalCount += 1;
+    if (/^Z/i.test(m[2])) zombieCount += 1;
+    const key = matchAllowlist(m[3]);
+    if (key) counts[key] += 1;
+  }
+  return {
+    totalCount, zombieCount,
+    tracked: PROCESS_ALLOWLIST.filter((k) => counts[k] > 0).map((k) => ({ name: k, count: counts[k] }))
+  };
+}
+
+function probeMemory(probeCommand, timeoutMs) {
+  const mem = classify(invoke(probeCommand, BIN.sysctl, ["-n", "hw.memsize"], timeoutMs));
+  if (mem.kind !== "ok") return { ok: false, kind: mem.kind };
+  const totalBytes = Number(String(mem.stdout).trim());
+  if (!Number.isFinite(totalBytes) || totalBytes <= 0) return { ok: false, kind: "parse" };
+  const page = classify(invoke(probeCommand, BIN.pagesize, [], timeoutMs));
+  if (page.kind !== "ok") return { ok: false, kind: page.kind };
+  const pageSize = Number(String(page.stdout).trim());
+  if (!Number.isFinite(pageSize) || pageSize <= 0) return { ok: false, kind: "parse" };
+  const vm = classify(invoke(probeCommand, BIN.vmStat, [], timeoutMs));
+  if (vm.kind !== "ok") return { ok: false, kind: vm.kind };
+  const free = vm.stdout.match(/Pages free:\s+(\d+)/i);
+  const spec = vm.stdout.match(/Pages speculative:\s+(\d+)/i);
+  if (!free) return { ok: false, kind: "parse" };
+  const freeBytes = (Number(free[1]) + (spec ? Number(spec[1]) : 0)) * pageSize;
+  return { ok: true, value: { totalBytes, freePercent: Math.round((freeBytes / totalBytes) * 1000) / 10 } };
+}
+
+function runProbe(fn, probeCommand, deadlineMs) {
+  const left = Math.max(0, deadlineMs - Date.now());
+  if (left <= 0) return { ok: false, kind: "timeout" };
+  return fn(probeCommand, left);
+}
+
+function probeSwap(probeCommand, timeoutMs) {
+  const cls = classify(invoke(probeCommand, BIN.sysctl, ["-n", "vm.swapusage"], timeoutMs));
+  if (cls.kind !== "ok") return { ok: false, kind: cls.kind };
+  const value = parseSwap(cls.stdout);
+  return value ? { ok: true, value } : { ok: false, kind: "parse" };
+}
+
+function probeDisk(probeCommand, timeoutMs) {
+  let cls = classify(invoke(probeCommand, BIN.df, ["-k", "/System/Volumes/Data"], timeoutMs));
+  if (cls.kind !== "ok") cls = classify(invoke(probeCommand, BIN.df, ["-k", "/"], timeoutMs));
+  if (cls.kind !== "ok") return { ok: false, kind: cls.kind };
+  const value = parseDf(cls.stdout);
+  return value ? { ok: true, value } : { ok: false, kind: "parse" };
+}
+
+function probeProcesses(probeCommand, timeoutMs) {
+  const cls = classify(invoke(probeCommand, BIN.ps, ["-axc", "-o", "pid=,stat=,comm="], timeoutMs));
+  if (cls.kind !== "ok") return { ok: false, kind: cls.kind };
+  return { ok: true, value: parseProcessTable(cls.stdout) };
+}
+
+/** Read-only local system resources (macOS first). Absolute bins only; never throws. */
+export async function loadSystemResources({
+  platform = process.platform, nowMs = Date.now(),
+  timeoutMs = SYSTEM_RESOURCES_TIMEOUT_MS, probeCommand = defaultProbeCommand
+} = {}) {
+  try {
+    if (platform !== "darwin") {
+      return envelope("unavailable", nowMs, ["system resources unsupported on this platform"]);
+    }
+    const diagnostics = [];
+    const deadlineMs = Date.now() + timeoutMs;
+    const memory = runProbe(probeMemory, probeCommand, deadlineMs);
+    const swap = runProbe(probeSwap, probeCommand, deadlineMs);
+    const disk = runProbe(probeDisk, probeCommand, deadlineMs);
+    const processes = runProbe(probeProcesses, probeCommand, deadlineMs);
+    for (const [label, result] of [["memory", memory], ["swap", swap], ["disk", disk], ["processes", processes]]) {
+      if (!result.ok) diagnostics.push(`system ${label} ${result.kind}`);
+    }
+    const anyOk = memory.ok || swap.ok || disk.ok || processes.ok;
+    if (!anyOk) {
+      return envelope("error", nowMs, diagnostics.length ? diagnostics : ["system resources probe failed"]);
+    }
+    const available = memory.ok && swap.ok && disk.ok && processes.ok;
+    return envelope(available ? "available" : "partial", nowMs, diagnostics, {
+      memory: memory.ok ? memory.value : null,
+      swap: swap.ok ? swap.value : null,
+      disk: disk.ok ? disk.value : null,
+      processes: processes.ok ? processes.value : emptyProcesses()
+    });
+  } catch {
+    return envelope("error", nowMs, ["system resources error"]);
+  }
+}