@kal-elsam/kairo-runtime 0.11.0 → 0.13.0

package/src/global/observability/obsidian-vault.js

@@ -0,0 +1,259 @@
+import { existsSync } from "node:fs";
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { basename, isAbsolute, join, resolve, sep } from "node:path";
+import { isPathInside } from "../component-paths.js";
+
+/** Obsidian vault subfolder Kairo may read — never the whole vault. */
+export const KAIRO_VAULT_SUBDIR = "Kairo";
+
+/** Directory basenames refused anywhere under the Kairo tree. */
+export const EXCLUDED_DIR_NAMES = Object.freeze([
+  ".obsidian", ".git", ".trash", "attachments", "Attachment", "Assets", "assets"
+]);
+
+const SECRET_BASENAME = /(?:^|\.)(env|secret|secrets|credentials|token|tokens|key|keys|pem|p12|pfx)(?:\.|$)/i;
+const MARKDOWN_EXT = /\.md$/i;
+const MAX_NOTES = 200;
+const MAX_WALK_DEPTH = 8;
+
+function envelope(partial = {}) {
+  return {
+    state: "error",
+    vaultPath: null,
+    kairoRoot: null,
+    notes: [],
+    diagnostics: [],
+    error: null,
+    ...partial
+  };
+}
+
+/** Absolute vault path only — no home expansion, no relative paths. */
+export function normalizeVaultPath(raw) {
+  if (typeof raw !== "string" || !raw.trim()) {
+    return { ok: false, reason: "vaultPath required" };
+  }
+  const trimmed = raw.trim();
+  if (!isAbsolute(trimmed)) {
+    return { ok: false, reason: "vaultPath must be absolute" };
+  }
+  const resolved = resolve(trimmed);
+  if (resolved.includes("\0")) {
+    return { ok: false, reason: "vaultPath invalid" };
+  }
+  return { ok: true, path: resolved };
+}
+
+export function isExcludedDirName(name) {
+  return EXCLUDED_DIR_NAMES.includes(String(name ?? ""));
+}
+
+export function isSecretBasename(name) {
+  return SECRET_BASENAME.test(String(name ?? ""));
+}
+
+export function isAllowedKairoNoteName(name) {
+  const base = basename(String(name ?? ""));
+  if (!MARKDOWN_EXT.test(base)) return false;
+  if (isSecretBasename(base)) return false;
+  if (base.startsWith(".")) return false;
+  return true;
+}
+
+/**
+ * Candidate must resolve inside kairoRoot (realpath). Symlinks that escape fail.
+ * Relative segments with `..` that leave Kairo/ fail before IO when possible.
+ */
+export async function assertInsideKairoRoot(candidatePath, kairoRoot, {
+  lstatFn = lstat,
+  realpathFn = realpath,
+  existsFn = existsSync
+} = {}) {
+  const root = resolve(kairoRoot);
+  const claimed = resolve(candidatePath);
+  if (!isPathInside(root, claimed) && claimed !== root) {
+    return { ok: false, reason: "path escapes Kairo/" };
+  }
+  if (!existsFn(claimed)) {
+    return { ok: true, path: claimed, missing: true };
+  }
+  try {
+    const st = await lstatFn(claimed);
+    if (st.isSymbolicLink()) {
+      const target = await realpathFn(claimed);
+      if (!isPathInside(root, target) && target !== root) {
+        return { ok: false, reason: "symlink escapes Kairo/" };
+      }
+      return { ok: true, path: target, symlink: true };
+    }
+    const real = await realpathFn(claimed);
+    if (!isPathInside(root, real) && real !== root) {
+      return { ok: false, reason: "realpath escapes Kairo/" };
+    }
+    return { ok: true, path: real };
+  } catch {
+    return { ok: false, reason: "path unreadable" };
+  }
+}
+
+async function refuseVaultSymlink(vaultPath, { lstatFn = lstat } = {}) {
+  try {
+    if ((await lstatFn(vaultPath)).isSymbolicLink()) {
+      return "vault root is a symlink; refusing";
+    }
+  } catch {
+    return "vault unreadable";
+  }
+  return null;
+}
+
+/**
+ * Read-only inspect of an Obsidian vault's Kairo/ subtree.
+ * Never writes; never reads Engram/Graphify stores; never opens .obsidian.
+ */
+export async function inspectObsidianVault({
+  vaultPath,
+  lstatFn = lstat,
+  readdirFn = readdir,
+  realpathFn = realpath,
+  existsFn = existsSync,
+  maxNotes = MAX_NOTES
+} = {}) {
+  const norm = normalizeVaultPath(vaultPath);
+  if (!norm.ok) {
+    return envelope({ state: "unavailable", error: norm.reason, diagnostics: [norm.reason] });
+  }
+  const root = norm.path;
+  if (!existsFn(root)) {
+    return envelope({
+      state: "missing", vaultPath: root, error: "vault missing",
+      diagnostics: ["vault path does not exist"]
+    });
+  }
+  const vaultSym = await refuseVaultSymlink(root, { lstatFn });
+  if (vaultSym) {
+    return envelope({
+      state: "error", vaultPath: root, error: vaultSym, diagnostics: [vaultSym]
+    });
+  }
+
+  let vaultReal;
+  try { vaultReal = await realpathFn(root); }
+  catch {
+    return envelope({
+      state: "error", vaultPath: root, error: "vault unreadable",
+      diagnostics: ["vault realpath failed"]
+    });
+  }
+
+  const kairoRoot = join(vaultReal, KAIRO_VAULT_SUBDIR);
+  if (!existsFn(kairoRoot)) {
+    return envelope({
+      state: "partial", vaultPath: vaultReal, kairoRoot,
+      error: null, diagnostics: ["Kairo/ subdirectory missing"]
+    });
+  }
+
+  const kairoGate = await assertInsideKairoRoot(kairoRoot, kairoRoot, {
+    lstatFn, realpathFn, existsFn
+  });
+  if (!kairoGate.ok) {
+    return envelope({
+      state: "error", vaultPath: vaultReal, kairoRoot,
+      error: kairoGate.reason, diagnostics: [kairoGate.reason]
+    });
+  }
+  if (kairoGate.symlink) {
+    return envelope({
+      state: "error", vaultPath: vaultReal, kairoRoot,
+      error: "Kairo/ is a symlink; refusing",
+      diagnostics: ["Kairo/ is a symlink; refusing"]
+    });
+  }
+
+  const notes = [];
+  const diagnostics = [];
+  await walkKairoNotes(kairoGate.path, kairoGate.path, {
+    notes, diagnostics, depth: 0, maxNotes,
+    lstatFn, readdirFn, realpathFn, existsFn
+  });
+
+  return envelope({
+    state: "available",
+    vaultPath: vaultReal,
+    kairoRoot: kairoGate.path,
+    notes,
+    diagnostics,
+    error: null
+  });
+}
+
+async function walkKairoNotes(dir, kairoRoot, ctx) {
+  if (ctx.notes.length >= ctx.maxNotes || ctx.depth > MAX_WALK_DEPTH) return;
+  let entries;
+  try {
+    entries = await ctx.readdirFn(dir, { withFileTypes: true });
+  } catch {
+    ctx.diagnostics.push("directory unreadable");
+    return;
+  }
+
+  const ordered = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of ordered) {
+    if (ctx.notes.length >= ctx.maxNotes) break;
+    const name = entry.name;
+    if (name === "." || name === ".." || name.includes("\0")) continue;
+    if (isExcludedDirName(name)) continue;
+
+    const full = join(dir, name);
+    const gate = await assertInsideKairoRoot(full, kairoRoot, {
+      lstatFn: ctx.lstatFn, realpathFn: ctx.realpathFn, existsFn: ctx.existsFn
+    });
+    if (!gate.ok) {
+      ctx.diagnostics.push(`skipped unsafe path (${gate.reason})`);
+      continue;
+    }
+    if (gate.missing) continue;
+
+    let st;
+    try { st = await ctx.lstatFn(full); }
+    catch {
+      ctx.diagnostics.push("entry unreadable");
+      continue;
+    }
+
+    if (st.isSymbolicLink()) {
+      ctx.diagnostics.push("skipped symlink");
+      continue;
+    }
+    if (st.isDirectory()) {
+      await walkKairoNotes(gate.path, kairoRoot, { ...ctx, depth: ctx.depth + 1 });
+      continue;
+    }
+    if (!st.isFile()) continue;
+    if (!isAllowedKairoNoteName(name)) continue;
+
+    const rel = gate.path.slice(kairoRoot.length).replace(/^[\\/]/, "").split(sep).join("/");
+    ctx.notes.push({
+      relativePath: rel,
+      title: basename(name, ".md")
+    });
+  }
+}
+
+/** Pure helper for callers composing relative note paths under Kairo/. */
+export function resolveKairoNotePath(kairoRoot, relativePath) {
+  const root = resolve(kairoRoot);
+  const parts = String(relativePath ?? "").split(/[/\\]/).filter(Boolean);
+  if (parts.length === 0 || parts.some((p) => p === ".." || p.includes("\0"))) {
+    return { ok: false, reason: "invalid relativePath" };
+  }
+  if (parts.some((p) => isExcludedDirName(p) || isSecretBasename(p))) {
+    return { ok: false, reason: "relativePath excluded" };
+  }
+  const claimed = resolve(join(root, ...parts));
+  if (!isPathInside(root, claimed)) {
+    return { ok: false, reason: "path escapes Kairo/" };
+  }
+  return { ok: true, path: claimed };
+}

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"]);
+  }
+}

package/src/global/runtime/alerts/alert-cli.js

@@ -0,0 +1,31 @@
+import { resolveHomeDir } from "../../paths.js";
+import { printJson } from "../../json-output.js";
+import { commandHeader } from "../../brand/index.js";
+import { formatCliCommand } from "../../brand/cli.js";
+import { controlledDismissAlert, controlledResolveAlert } from "./controlled-alert-actions.js";
+
+export async function runGlobalAlerts(options) {
+  const homeDir = resolveHomeDir();
+  const action = options.alertsAction;
+  const alertId = options.alertId;
+  if ((action !== "resolve" && action !== "dismiss") || !alertId) {
+    throw new Error(`Use: ${formatCliCommand("alerts resolve|dismiss <alertId> --confirm-…")}`);
+  }
+  const isResolve = action === "resolve";
+  const confirmed = Boolean(isResolve ? options.confirmResolve : options.confirmDismiss);
+  const result = await (isResolve ? controlledResolveAlert : controlledDismissAlert)({
+    alertId, confirmed, source: "cli", homeDir
+  });
+  if (options.json) {
+    printJson({
+      ok: result.ok, code: result.code, alertId, state: result.alert?.state ?? null,
+      permissionAuthority: result.permissionAuthority, diagnostics: result.diagnostics
+    });
+  } else if (result.ok) {
+    console.log(`${commandHeader(`alerts ${action}`)}\n${alertId} → ${result.alert.state}`);
+  } else {
+    console.error(`alerts ${action} failed (${result.code}).`);
+  }
+  if (!result.ok) process.exitCode = 2;
+  return result;
+}