@kal-elsam/kairo-runtime 0.8.0 → 0.10.0

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

@@ -0,0 +1,59 @@
+import { createHash, randomBytes } from "node:crypto";
+
+export const ALERT_STATES = Object.freeze({
+  OPEN: "open", RESOLVED: "resolved", DISMISSED: "dismissed"
+});
+
+export const ALERT_SEVERITIES = Object.freeze({
+  HIGH: "high", MEDIUM: "medium", LOW: "low"
+});
+
+export function createAlertId() {
+  return `alt-${randomBytes(12).toString("hex")}`;
+}
+
+export function assertSafeAlertId(alertId) {
+  if (typeof alertId !== "string" || !/^alt-[a-f0-9]{16,32}$/.test(alertId)) {
+    throw new Error(`Invalid alert id "${alertId}".`);
+  }
+}
+
+/** Stable dedupe key — kind + source + title only (never payloads). */
+export function createAlertFingerprint({ kind, source = null, title }) {
+  return createHash("sha256")
+    .update([kind, source ?? "", title].map(String).join("\0"))
+    .digest("hex");
+}
+
+export function createAlert({
+  alertId = createAlertId(),
+  kind,
+  severity = ALERT_SEVERITIES.MEDIUM,
+  title,
+  summary = "",
+  source = null,
+  state = ALERT_STATES.OPEN,
+  createdAt = null,
+  updatedAt = null,
+  resolvedAt = null
+} = {}) {
+  assertSafeAlertId(alertId);
+  const safeKind = String(kind ?? "").trim();
+  const safeTitle = String(title ?? "").trim();
+  if (!safeKind || !safeTitle) throw new Error("Alert kind and title are required.");
+  const now = new Date().toISOString();
+  return {
+    version: 1,
+    alertId,
+    kind: safeKind,
+    severity,
+    title: safeTitle,
+    summary: String(summary ?? "").trim(),
+    source: source == null ? null : String(source),
+    fingerprint: createAlertFingerprint({ kind: safeKind, source, title: safeTitle }),
+    state,
+    createdAt: createdAt ?? now,
+    updatedAt: updatedAt ?? now,
+    resolvedAt: resolvedAt ?? null
+  };
+}

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

@@ -0,0 +1,117 @@
+import {
+  ALERT_SEVERITIES,
+  ALERT_STATES,
+  assertSafeAlertId,
+  createAlertFingerprint
+} from "./alert-types.js";
+
+export const ALERT_VALIDATION_ERROR_CODES = Object.freeze({
+  INVALID_ALERT: "invalid_alert",
+  FORBIDDEN_FIELD: "forbidden_field",
+  FINGERPRINT_MISMATCH: "fingerprint_mismatch"
+});
+
+const SEVERITY_SET = new Set(Object.values(ALERT_SEVERITIES));
+const STATE_SET = new Set(Object.values(ALERT_STATES));
+const FORBIDDEN_KEYS = new Set([
+  "prompt", "diff", "transcript", "raw", "rawOutput", "stdout", "stderr",
+  "output", "message", "messages", "content", "secret", "secrets", "token", "apiKey"
+]);
+const ALLOWED = new Set([
+  "version", "alertId", "kind", "severity", "title", "summary",
+  "source", "fingerprint", "state", "createdAt", "updatedAt", "resolvedAt"
+]);
+
+export class AlertValidationError extends Error {
+  constructor(message, { code, details = null } = {}) {
+    super(message);
+    this.name = "AlertValidationError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function assertNoForbiddenKeys(value, label) {
+  if (!value || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    for (const item of value) assertNoForbiddenKeys(item, label);
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      throw new AlertValidationError(`Forbidden field "${key}" in ${label}.`, {
+        code: ALERT_VALIDATION_ERROR_CODES.FORBIDDEN_FIELD,
+        details: { key, label }
+      });
+    }
+    assertNoForbiddenKeys(child, `${label}.${key}`);
+  }
+}
+
+function requireString(alert, key, { allowEmpty = false } = {}) {
+  const value = alert[key];
+  if (typeof value !== "string" || (!allowEmpty && !value.trim())) {
+    throw new AlertValidationError(`Invalid alert.${key}: expected string.`, {
+      code: ALERT_VALIDATION_ERROR_CODES.INVALID_ALERT,
+      details: { key }
+    });
+  }
+  return value;
+}
+
+/** Fail-closed scalar schema + recursive secret scan + derived fingerprint. */
+export function assertAlertSecretFree(alert) {
+  if (!alert || typeof alert !== "object" || Array.isArray(alert)) {
+    throw new AlertValidationError("Invalid alert: expected object.", {
+      code: ALERT_VALIDATION_ERROR_CODES.INVALID_ALERT
+    });
+  }
+  assertNoForbiddenKeys(alert, "alert");
+  for (const key of Object.keys(alert)) {
+    if (!ALLOWED.has(key)) {
+      throw new AlertValidationError(`Unknown field "${key}" in alert.`, {
+        code: ALERT_VALIDATION_ERROR_CODES.FORBIDDEN_FIELD,
+        details: { key }
+      });
+    }
+  }
+  if (typeof alert.version !== "number" || !Number.isFinite(alert.version)) {
+    throw new AlertValidationError("Invalid alert.version.", {
+      code: ALERT_VALIDATION_ERROR_CODES.INVALID_ALERT
+    });
+  }
+  assertSafeAlertId(requireString(alert, "alertId"));
+  requireString(alert, "kind");
+  requireString(alert, "title");
+  requireString(alert, "summary", { allowEmpty: true });
+  requireString(alert, "fingerprint");
+  requireString(alert, "createdAt");
+  requireString(alert, "updatedAt");
+  if (!(alert.source === null || typeof alert.source === "string")) {
+    throw new AlertValidationError("Invalid alert.source.", {
+      code: ALERT_VALIDATION_ERROR_CODES.INVALID_ALERT
+    });
+  }
+  if (!(alert.resolvedAt === null || typeof alert.resolvedAt === "string")) {
+    throw new AlertValidationError("Invalid alert.resolvedAt.", {
+      code: ALERT_VALIDATION_ERROR_CODES.INVALID_ALERT
+    });
+  }
+  if (!SEVERITY_SET.has(alert.severity) || !STATE_SET.has(alert.state)) {
+    throw new AlertValidationError("Unknown alert severity or state.", {
+      code: ALERT_VALIDATION_ERROR_CODES.INVALID_ALERT
+    });
+  }
+  const expected = createAlertFingerprint({
+    kind: alert.kind,
+    source: alert.source,
+    title: alert.title
+  });
+  if (alert.fingerprint !== expected) {
+    throw new AlertValidationError("Alert fingerprint does not match kind+source+title.", {
+      code: ALERT_VALIDATION_ERROR_CODES.FINGERPRINT_MISMATCH,
+      details: { expected }
+    });
+  }
+  return alert;
+}

package/src/global/runtime/monitor/monitor-cli.js

@@ -0,0 +1,62 @@
+import { join } from "node:path";
+import { resolveHomeDir } from "../../paths.js";
+import { printJson } from "../../json-output.js";
+import { commandHeader } from "../../brand/index.js";
+import {
+  disableMonitor, enableMonitor, getMonitorStatus, runMonitorTick
+} from "./monitor.js";
+
+export async function runGlobalMonitor(options, _manifest, deps = {}) {
+  const homeDir = deps.homeDir ?? resolveHomeDir();
+  const action = options.monitorAction ?? "status";
+  const packageRoot = deps.packageRoot;
+  const entry = deps.cliEntry ?? (packageRoot ? join(packageRoot, "bin", "kairo.js") : null);
+  try {
+    if (action === "enable") {
+      await (deps.enableMonitorImpl ?? enableMonitor)(homeDir, {
+        cliEntry: entry, nodePath: deps.nodePath ?? process.execPath, platform: deps.platform
+      });
+      await (deps.runMonitorTickImpl ?? runMonitorTick)(homeDir, {
+        packageRoot, workspaceRoot: options.cwd, notifyImpl: deps.notifyImpl
+      });
+    } else if (action === "disable") {
+      await (deps.disableMonitorImpl ?? disableMonitor)(homeDir, { platform: deps.platform });
+    } else if (action === "tick") {
+      const result = await (deps.runMonitorTickImpl ?? runMonitorTick)(homeDir, {
+        packageRoot, workspaceRoot: options.cwd, notifyImpl: deps.notifyImpl
+      });
+      return done(options, { ok: true, action, raised: result.raised.length, lastTick: result.state.lastTick });
+    }
+    const status = await (deps.getMonitorStatusImpl ?? getMonitorStatus)(homeDir, {
+      platform: deps.platform
+    });
+    return done(options, { ok: true, action: action === "status" ? "status" : action, ...status });
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    if (options.json) printJson({ ok: false, error: message });
+    else console.error(message);
+    process.exitCode = 1;
+    return { ok: false, error: message };
+  }
+}
+
+function done(options, payload) {
+  if (options.json) { printJson(payload); return payload; }
+  console.log(commandHeader(`monitor ${payload.action}`));
+  if (payload.action === "tick") {
+    console.log(`Raised ${payload.raised} alert(s) this tick.`);
+    return payload;
+  }
+  console.log(`Enabled: ${payload.corrupt ? "unavailable" : payload.enabled ? "yes" : "no"} · ${payload.platform}`);
+  if (payload.corrupt) console.log("State: corrupt — run monitor disable to repair");
+  else {
+    const a = payload.autostart;
+    console.log(`Autostart: ${a?.loaded ? "loaded" : a?.configured ? "configured (not loaded)" : "off"}`
+      + `${a?.supported === false ? " (unsupported)" : ""}`);
+  }
+  console.log(`Open alerts: ${payload.openAlerts ?? "unavailable"}`);
+  if (payload.lastTickAt) {
+    console.log(`Last tick: ${payload.lastTickAt}${payload.lastTick?.complete === false ? " (incomplete)" : ""}`);
+  }
+  return payload;
+}

package/src/global/runtime/monitor/monitor-platform.js

@@ -0,0 +1,95 @@
+import { existsSync } from "node:fs";
+import { mkdir, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCb);
+export const MONITOR_LABEL = "local.kairo.monitor";
+
+export function resolveMonitorPlatform(platform = process.platform) {
+  if (platform === "darwin") {
+    const agentsDir = join(homedir(), "Library", "LaunchAgents");
+    return {
+      id: "darwin", supportsAutostart: true, supportsNotify: true,
+      agentsDir, plistPath: join(agentsDir, `${MONITOR_LABEL}.plist`)
+    };
+  }
+  return { id: platform, supportsAutostart: false, supportsNotify: platform === "linux" };
+}
+
+function gui() { return `gui/${process.getuid?.() ?? 501}`; }
+
+function plist({ nodePath, cliEntry, homeDir, intervalSec }) {
+  const e = (v) => String(v).replaceAll("&", "&amp;").replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+  const log = join(homeDir, ".harness", "monitor");
+  const n = Math.max(60, Number(intervalSec) || 300);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${MONITOR_LABEL}</string>
+<key>ProgramArguments</key><array><string>${e(nodePath)}</string><string>${e(cliEntry)}</string><string>monitor</string><string>tick</string></array>
+<key>StartInterval</key><integer>${n}</integer><key>RunAtLoad</key><true/>
+<key>EnvironmentVariables</key><dict><key>HARNESS_HOME</key><string>${e(homeDir)}</string></dict>
+<key>StandardOutPath</key><string>${e(join(log, "out.log"))}</string>
+<key>StandardErrorPath</key><string>${e(join(log, "err.log"))}</string>
+</dict></plist>`;
+}
+
+export async function notifyNewAlert({
+  title, body, platform = resolveMonitorPlatform(), execFileImpl = execFile
+} = {}) {
+  const t = String(title ?? "Kairo").slice(0, 80);
+  const b = String(body ?? "").slice(0, 180).replace(/[\r\n]+/g, " ");
+  try {
+    if (platform.id === "darwin") {
+      await execFileImpl("osascript", [
+        "-e", `display notification ${JSON.stringify(b)} with title ${JSON.stringify(t)}`
+      ], { shell: false, timeout: 5000 });
+      return { sent: true };
+    }
+    if (platform.id === "linux") {
+      await execFileImpl("notify-send", [t, b], { shell: false, timeout: 5000 });
+      return { sent: true };
+    }
+  } catch { /* degrade */ }
+  return { sent: false };
+}
+
+export async function installAutostart({
+  homeDir, platform = resolveMonitorPlatform(), nodePath, cliEntry,
+  intervalSec = 300, execFileImpl = execFile
+} = {}) {
+  if (!platform.supportsAutostart) {
+    return {
+      supported: false, configured: false, loaded: false, installed: false,
+      detail: `unsupported on ${platform.id}`
+    };
+  }
+  await mkdir(platform.agentsDir, { recursive: true });
+  await mkdir(join(homeDir, ".harness", "monitor"), { recursive: true });
+  await writeFile(platform.plistPath, plist({ nodePath, cliEntry, homeDir, intervalSec }));
+  try {
+    await execFileImpl("launchctl", ["bootout", `${gui()}/${MONITOR_LABEL}`], { shell: false }).catch(() => {});
+    await execFileImpl("launchctl", ["bootstrap", gui(), platform.plistPath], { shell: false });
+    return { supported: true, configured: true, loaded: true, installed: true, detail: "LaunchAgent loaded" };
+  } catch (error) {
+    return {
+      supported: true, configured: true, loaded: false, installed: false,
+      detail: `plist configured; not loaded (${error?.message ?? error})`
+    };
+  }
+}
+
+export async function removeAutostart({
+  platform = resolveMonitorPlatform(), execFileImpl = execFile
+} = {}) {
+  if (!platform.supportsAutostart) {
+    return { supported: false, configured: false, loaded: false, installed: false };
+  }
+  await execFileImpl("launchctl", ["bootout", `${gui()}/${MONITOR_LABEL}`], { shell: false }).catch(() => {});
+  if (platform.plistPath && existsSync(platform.plistPath)) await unlink(platform.plistPath).catch(() => {});
+  return { supported: true, configured: false, loaded: false, installed: false };
+}

package/src/global/runtime/monitor/monitor.js

@@ -0,0 +1,249 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { harnessHomePaths } from "../../paths.js";
+import { detectGlobalDrift, hasRepairableDrift } from "../../drift.js";
+import { writeAtomicJson } from "../write-atomic-json.js";
+import { listAlerts, saveAlert } from "../alerts/alert-store.js";
+import { ALERT_SEVERITIES, ALERT_STATES } from "../alerts/alert-types.js";
+import { listRunRecords } from "../run-store.js";
+import { isRunAlive } from "../run-liveness.js";
+import { RUN_STATES, isActiveRunState } from "../run-types.js";
+import {
+  installAutostart, notifyNewAlert, removeAutostart, resolveMonitorPlatform
+} from "./monitor-platform.js";
+
+export {
+  installAutostart, notifyNewAlert, removeAutostart, resolveMonitorPlatform
+} from "./monitor-platform.js";
+
+const SOURCE = "monitor";
+const INTERVAL = 300;
+
+export class MonitorStateError extends Error {
+  constructor(message, { code = "corrupt_monitor_state" } = {}) {
+    super(message);
+    this.name = "MonitorStateError";
+    this.code = code;
+  }
+}
+
+export function defaultMonitorState() {
+  return {
+    version: 1, enabled: false, intervalSec: INTERVAL,
+    lastTickAt: null, lastTick: null,
+    autostart: {
+      platform: null, installed: false, supported: false, configured: false, loaded: false
+    },
+    updatedAt: null
+  };
+}
+
+function assertMonitorState(raw) {
+  if (!raw || typeof raw !== "object" || raw.version !== 1 || typeof raw.enabled !== "boolean") {
+    throw new MonitorStateError("Monitor state schema invalid.");
+  }
+  if (!Number.isFinite(raw.intervalSec) || raw.intervalSec < 1) {
+    throw new MonitorStateError("Monitor state.intervalSec invalid.");
+  }
+  const a = raw.autostart;
+  if (!a || typeof a !== "object"
+    || typeof a.supported !== "boolean"
+    || typeof a.configured !== "boolean"
+    || typeof a.loaded !== "boolean"
+    || typeof a.installed !== "boolean") {
+    throw new MonitorStateError("Monitor state.autostart invalid.");
+  }
+  if (a.loaded && !a.configured) {
+    throw new MonitorStateError("Monitor state.autostart loaded requires configured.");
+  }
+  if (a.installed !== a.loaded) {
+    throw new MonitorStateError("Monitor state.autostart installed must equal loaded.");
+  }
+  if (!a.supported && (a.configured || a.loaded || a.installed)) {
+    throw new MonitorStateError("Monitor state.autostart unsupported with lifecycle flags.");
+  }
+  if (!raw.enabled && (a.configured || a.loaded || a.installed)) {
+    throw new MonitorStateError("Monitor disabled with active autostart lifecycle.");
+  }
+  return {
+    ...defaultMonitorState(),
+    ...raw,
+    version: 1,
+    enabled: raw.enabled,
+    intervalSec: raw.intervalSec,
+    autostart: { ...defaultMonitorState().autostart, ...a }
+  };
+}
+
+export async function readMonitorState(homeDir, { repair = false } = {}) {
+  const path = harnessHomePaths(homeDir).monitorStatePath;
+  if (!existsSync(path)) return defaultMonitorState();
+  try {
+    return assertMonitorState(JSON.parse(await readFile(path, "utf8")));
+  } catch (error) {
+    if (repair) return defaultMonitorState();
+    if (error instanceof MonitorStateError) throw error;
+    throw new MonitorStateError("Monitor state unreadable.");
+  }
+}
+
+export async function writeMonitorState(homeDir, patch, { repair = false } = {}) {
+  const { monitorDir, monitorStatePath } = harnessHomePaths(homeDir);
+  await mkdir(monitorDir, { recursive: true });
+  const next = {
+    ...await readMonitorState(homeDir, { repair }), ...patch,
+    updatedAt: new Date().toISOString()
+  };
+  await writeAtomicJson(monitorStatePath, next);
+  return next;
+}
+
+async function raise(homeDir, input, notifyImpl) {
+  const result = await saveAlert({ ...input, source: SOURCE }, { homeDir });
+  if (!result.deduped) {
+    await notifyImpl({ title: "Kairo", body: `${result.alert.severity} · ${result.alert.title}` });
+  }
+  return result;
+}
+
+function autostartRecord(platform, a) {
+  return {
+    platform: platform.id, supported: a.supported,
+    configured: Boolean(a.configured), loaded: Boolean(a.loaded),
+    installed: Boolean(a.loaded), detail: a.detail ?? null
+  };
+}
+
+export async function runMonitorTick(homeDir, deps = {}) {
+  const {
+    notifyImpl = notifyNewAlert, detectDriftImpl = detectGlobalDrift,
+    listRunsImpl = listRunRecords, isRunAliveImpl = isRunAlive,
+    packageRoot = null, workspaceRoot = null
+  } = deps;
+  const raised = [];
+  await mkdir(harnessHomePaths(homeDir).monitorDir, { recursive: true });
+  try {
+    const paths = harnessHomePaths(homeDir);
+    const state = existsSync(paths.statePath)
+      ? JSON.parse(await readFile(paths.statePath, "utf8")) : null;
+    if (hasRepairableDrift(await detectDriftImpl({
+      homeDir, paths, state, packageRoot, workspaceRoot, context: { homeDir }
+    }))) {
+      raised.push(await raise(homeDir, {
+        kind: "monitor.drift", title: "Managed configuration drift",
+        summary: "Managed configs drifted. Run kairo sync.", severity: ALERT_SEVERITIES.HIGH
+      }, notifyImpl));
+    }
+  } catch {
+    raised.push(await raise(homeDir, {
+      kind: "monitor.drift", title: "Governance scan unavailable",
+      summary: "Monitor could not complete the drift scan.", severity: ALERT_SEVERITIES.MEDIUM
+    }, notifyImpl));
+  }
+
+  let runsOk = true; let dead = 0; let failed = 0;
+  try {
+    for (const run of await listRunsImpl(homeDir, { limit: 40 })) {
+      if (isActiveRunState(run.state) && !(await isRunAliveImpl(homeDir, run))) dead += 1;
+      if (run.state === RUN_STATES.FAILED) failed += 1;
+    }
+  } catch {
+    runsOk = false;
+    raised.push(await raise(homeDir, {
+      kind: "monitor.runs-unavailable", title: "Run monitoring unavailable",
+      summary: "Monitor could not inspect agent run health this tick.",
+      severity: ALERT_SEVERITIES.MEDIUM
+    }, notifyImpl));
+  }
+  if (runsOk && dead > 0) {
+    raised.push(await raise(homeDir, {
+      kind: "run.orphaned", title: "Orphaned agent run",
+      summary: `${dead} active run(s) have no live process.`, severity: ALERT_SEVERITIES.HIGH
+    }, notifyImpl));
+  }
+  if (runsOk && failed > 0) {
+    raised.push(await raise(homeDir, {
+      kind: "run.failed", title: "Agent run failed",
+      summary: `${failed} failed run(s) need attention.`, severity: ALERT_SEVERITIES.MEDIUM
+    }, notifyImpl));
+  }
+
+  const lastTick = {
+    raised: raised.length,
+    created: raised.filter((r) => !r.deduped).length,
+    deduped: raised.filter((r) => r.deduped).length,
+    complete: runsOk, runs: runsOk ? "ok" : "unavailable"
+  };
+  return {
+    state: await writeMonitorState(homeDir, {
+      lastTickAt: new Date().toISOString(), lastTick
+    }),
+    raised
+  };
+}
+
+export async function enableMonitor(homeDir, {
+  cliEntry, nodePath = process.execPath, platform = resolveMonitorPlatform(), intervalSec = INTERVAL
+} = {}) {
+  const autostart = await installAutostart({ homeDir, platform, nodePath, cliEntry, intervalSec });
+  try {
+    return await writeMonitorState(homeDir, {
+      enabled: true, intervalSec, autostart: autostartRecord(platform, autostart)
+    }, { repair: true });
+  } catch (error) {
+    if (autostart.loaded) await removeAutostart({ platform });
+    throw error;
+  }
+}
+
+export async function disableMonitor(homeDir, { platform = resolveMonitorPlatform() } = {}) {
+  return writeMonitorState(homeDir, {
+    enabled: false, autostart: autostartRecord(platform, await removeAutostart({ platform }))
+  }, { repair: true });
+}
+
+export async function getMonitorStatus(homeDir, { platform = resolveMonitorPlatform() } = {}) {
+  try {
+    const state = await readMonitorState(homeDir);
+    let openAlerts = 0;
+    try {
+      openAlerts = (await listAlerts({ homeDir, state: ALERT_STATES.OPEN })).length;
+    } catch { openAlerts = null; }
+    return {
+      available: true, corrupt: false, enabled: state.enabled, intervalSec: state.intervalSec,
+      lastTickAt: state.lastTickAt, lastTick: state.lastTick, autostart: state.autostart,
+      platform: platform.id,
+      notify: { supported: platform.supportsNotify, backend: platform.id }, openAlerts
+    };
+  } catch (error) {
+    if (error?.code !== "corrupt_monitor_state") throw error;
+    return {
+      available: false, corrupt: true, enabled: null, intervalSec: null,
+      lastTickAt: null, lastTick: null, autostart: null, platform: platform.id,
+      notify: { supported: platform.supportsNotify, backend: platform.id },
+      openAlerts: null, error: error.message
+    };
+  }
+}
+
+export async function monitorDoctorCheck(homeDir) {
+  const s = await getMonitorStatus(homeDir);
+  if (s.corrupt || s.available === false) {
+    return {
+      name: "monitor", status: "stale", category: "monitor",
+      detail: "corrupt state — run kairo monitor disable to repair"
+    };
+  }
+  if (s.enabled && s.autostart?.supported && !s.autostart?.loaded) {
+    return {
+      name: "monitor", status: "stale", category: "monitor",
+      detail: "enabled but autostart not loaded"
+    };
+  }
+  return {
+    name: "monitor", status: "ok", category: "monitor",
+    detail: s.enabled
+      ? `enabled · last ${s.lastTickAt ?? "none"} · autostart ${s.autostart?.loaded ? "loaded" : "off"}`
+      : "disabled (opt-in · kairo monitor enable)"
+  };
+}