@kal-elsam/kairo-runtime 0.8.0 → 0.9.0

package/src/global/ink/use-orchestrator-data.js

@@ -33,8 +33,14 @@ import {
   listRecoverySnapshots,
   reduceRecoveryAction
 } from "./cockpit-recovery.js";
+import {
+  createSettingsActionState,
+  listCuratedIntegrations,
+  reduceSettingsAction
+} from "./cockpit-settings.js";
 import { listReviewReceipts } from "../runtime/review/review-receipts.js";
 import { assertReceiptSecretFree } from "../runtime/review/review-validate.js";
+import { listAlerts, resolveAlert, dismissAlert } from "../runtime/alerts/alert-store.js";
 
 export function useOrchestratorData({
   homeDir,
@@ -54,6 +60,7 @@ export function useOrchestratorData({
   const [selectedEvents, setSelectedEvents] = useState([]);
   const [reviews, setReviews] = useState([]);
   const [selectedReview, setSelectedReview] = useState(null);
+  const [alerts, setAlerts] = useState(null);
   const [statusMessage, setStatusMessage] = useState(null);
   const [launchAgentIndex, setLaunchAgentIndex] = useState(0);
   const [launchStep, setLaunchStep] = useState(LAUNCH_WIZARD_STEPS.AGENT);
@@ -61,6 +68,7 @@ export function useOrchestratorData({
   const [launchPermissionIndex, setLaunchPermissionIndex] = useState(0);
   const [changesAction, setChangesAction] = useState(createChangesActionState);
   const [recoveryAction, setRecoveryAction] = useState(createRecoveryActionState);
+  const [settingsAction, setSettingsAction] = useState(createSettingsActionState);
 
   const serializedReload = useMemo(() => createSerializedReloader(() => loadCockpitScanBundle({
     homeDir,
@@ -90,6 +98,11 @@ export function useOrchestratorData({
     setDashboard(outcome.result.dashboard);
     setDiagnostics(outcome.result.diagnostics);
     setSnapshot(outcome.result.snapshot);
+    try {
+      setAlerts(await listAlerts({ homeDir, limit: 50 }));
+    } catch {
+      setAlerts(null);
+    }
     setError(null);
     setLoading(false);
     setRetrying(false);
@@ -149,6 +162,22 @@ export function useOrchestratorData({
     });
   };
 
+  const handleAlertTransition = async (alert, action) => {
+    if (!alert) return;
+    setBusy(true);
+    try {
+      if (action === "dismiss") await dismissAlert(alert.alertId, { homeDir });
+      else await resolveAlert(alert.alertId, { homeDir });
+      setAlerts(await listAlerts({ homeDir, limit: 50 }));
+      setStatusMessage(action === "dismiss" ? "Alert dismissed" : "Alert resolved");
+    } catch (error) {
+      setError(error instanceof Error ? error.message : String(error));
+      setAlerts(null);
+    } finally {
+      setBusy(false);
+    }
+  };
+
   const handleLaunch = async (draft, profile, dispatch) => {
     if (!draft.agentId || !draft.task.trim()) {
       setError("Agent and task are required.");
@@ -366,6 +395,26 @@ export function useOrchestratorData({
     await reload();
   };
 
+  const previewSettings = (id) => {
+    setSettingsAction((prev) => reduceSettingsAction(prev, { type: "preview", id }));
+  };
+
+  const promptConfirmSettings = () => {
+    setSettingsAction((prev) => reduceSettingsAction(prev, { type: "confirm-prompt" }));
+  };
+
+  const confirmSettings = () => {
+    setSettingsAction((prev) => reduceSettingsAction(prev, { type: "confirm" }));
+  };
+
+  const cancelSettings = () => {
+    setSettingsAction((prev) => reduceSettingsAction(prev, { type: "cancel" }));
+  };
+
+  const resetSettings = () => {
+    setSettingsAction(() => createSettingsActionState());
+  };
+
   return {
     loading,
     busy,
@@ -381,6 +430,7 @@ export function useOrchestratorData({
     reviews,
     selectedReview,
     setSelectedReview,
+    alerts,
     statusMessage,
     launchAgentIndex,
     setLaunchAgentIndex,
@@ -394,11 +444,14 @@ export function useOrchestratorData({
     scanOptions: CONTROL_PLANE_AUTO_SCAN,
     changesAction,
     recoveryAction,
+    settingsAction,
+    curatedIntegrations: listCuratedIntegrations(),
     reload,
     resetLaunchWizard,
     openRunDetail,
     loadReviews,
     openReviewDetail,
+    handleAlertTransition,
     handleLaunch,
     handleCancelRun,
     previewChanges,
@@ -409,6 +462,11 @@ export function useOrchestratorData({
     cancelRecovery,
     confirmApplyRecovery,
     rescanRecovery,
+    previewSettings,
+    promptConfirmSettings,
+    confirmSettings,
+    cancelSettings,
+    resetSettings,
     recoverySnapshots: listRecoverySnapshots(snapshot)
   };
 }

package/src/global/paths.js

@@ -19,6 +19,9 @@ export function harnessHomePaths(homeDir) {
     historyPath: join(root, "history.jsonl"),
     runsDir: join(root, "runs"),
     reviewsDir: join(root, "reviews"),
+    alertsDir: join(root, "alerts"),
+    monitorDir: join(root, "monitor"),
+    monitorStatePath: join(root, "monitor", "state.json"),
     coreDir: join(root, "core"),
     backupsDir: join(root, "backups")
   };

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

@@ -0,0 +1,216 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, unlink } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { harnessHomePaths } from "../../paths.js";
+import { writeAtomicJson } from "../write-atomic-json.js";
+import {
+  ALERT_STATES,
+  assertSafeAlertId,
+  createAlert,
+  createAlertFingerprint
+} from "./alert-types.js";
+import { assertAlertSecretFree } from "./alert-validate.js";
+
+const TERMINAL_ALERT_STATES = new Set([ALERT_STATES.RESOLVED, ALERT_STATES.DISMISSED]);
+
+export class AlertStoreError extends Error {
+  constructor(message, { code = "alert_store_error", details = null } = {}) {
+    super(message);
+    this.name = "AlertStoreError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function alertPaths(homeDir, alertId) {
+  assertSafeAlertId(alertId);
+  const alertDir = join(harnessHomePaths(homeDir).alertsDir, alertId);
+  return { alertDir, alertPath: join(alertDir, "alert.json") };
+}
+
+function openIndexPath(homeDir, fingerprint) {
+  if (typeof fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(fingerprint)) {
+    throw new AlertStoreError(`Invalid alert fingerprint "${fingerprint}".`, {
+      code: "invalid_fingerprint"
+    });
+  }
+  return join(harnessHomePaths(homeDir).alertsDir, "open", fingerprint);
+}
+
+function openDirPath(homeDir) {
+  return join(harnessHomePaths(homeDir).alertsDir, "open");
+}
+
+async function readOpenAlert(indexPath) {
+  const expectedFingerprint = basename(indexPath);
+  const alert = assertAlertSecretFree(JSON.parse(await readFile(indexPath, "utf8")));
+  if (alert.fingerprint !== expectedFingerprint || alert.state !== ALERT_STATES.OPEN) {
+    throw new AlertStoreError(`Corrupt open alert claim "${expectedFingerprint}".`, {
+      code: "corrupt_alert",
+      details: {
+        fingerprint: expectedFingerprint,
+        payloadFingerprint: alert.fingerprint,
+        state: alert.state
+      }
+    });
+  }
+  return alert;
+}
+
+async function readHistoryAlert(homeDir, alertId) {
+  const alert = assertAlertSecretFree(
+    JSON.parse(await readFile(alertPaths(homeDir, alertId).alertPath, "utf8"))
+  );
+  if (alert.alertId !== alertId || !TERMINAL_ALERT_STATES.has(alert.state)) {
+    throw new AlertStoreError(`Corrupt history alert "${alertId}".`, {
+      code: "corrupt_alert",
+      details: {
+        alertId,
+        payloadAlertId: alert.alertId,
+        state: alert.state
+      }
+    });
+  }
+  return alert;
+}
+
+function wrapCorruptAlert(label, details, error) {
+  if (error instanceof AlertStoreError) throw error;
+  throw new AlertStoreError(`Corrupt or unreadable ${label}.`, {
+    code: "corrupt_alert",
+    details: {
+      ...details,
+      cause: error instanceof Error ? error.message : String(error)
+    }
+  });
+}
+
+async function listOpenAlerts(homeDir) {
+  const dir = openDirPath(homeDir);
+  if (!existsSync(dir)) return [];
+  const alerts = [];
+  for (const name of await readdir(dir)) {
+    if (!/^[a-f0-9]{64}$/.test(name)) continue;
+    try {
+      alerts.push(await readOpenAlert(join(dir, name)));
+    } catch (error) {
+      wrapCorruptAlert(`open alert "${name}"`, { fingerprint: name }, error);
+    }
+  }
+  return alerts;
+}
+
+async function findOpenAlert(homeDir, alertId) {
+  assertSafeAlertId(alertId);
+  for (const alert of await listOpenAlerts(homeDir)) {
+    if (alert.alertId === alertId) return alert;
+  }
+  return null;
+}
+
+export async function loadAlert(alertId, { homeDir } = {}) {
+  const open = await findOpenAlert(homeDir, alertId);
+  if (open) return open;
+  const { alertPath } = alertPaths(homeDir, alertId);
+  if (!existsSync(alertPath)) throw new Error(`Alert not found: ${alertId}`);
+  return readHistoryAlert(homeDir, alertId);
+}
+
+async function writeHistoryAlert(alert, { homeDir } = {}) {
+  const sanitized = assertAlertSecretFree(alert);
+  const { alertDir, alertPath } = alertPaths(homeDir, sanitized.alertId);
+  await mkdir(alertDir, { recursive: true });
+  await writeAtomicJson(alertPath, sanitized);
+  return sanitized;
+}
+
+/**
+ * Persist an open alert. `open/<fingerprint>` is the authoritative open record
+ * (exclusive create); no secondary mutex.
+ */
+export async function saveAlert(input, { homeDir } = {}) {
+  const draft = input?.version === 1 ? { ...input } : createAlert(input);
+  draft.fingerprint = createAlertFingerprint(draft);
+  const candidate = assertAlertSecretFree(draft);
+  if (candidate.state !== ALERT_STATES.OPEN) {
+    throw new AlertStoreError("Only open alerts can be saved to the open index.", {
+      code: "invalid_alert_state",
+      details: { state: candidate.state, fingerprint: candidate.fingerprint }
+    });
+  }
+  const indexPath = openIndexPath(homeDir, candidate.fingerprint);
+  await mkdir(openDirPath(homeDir), { recursive: true });
+
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      await writeAtomicJson(indexPath, candidate, { createExclusive: true });
+      return { alert: candidate, deduped: false };
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      try {
+        return { alert: await readOpenAlert(indexPath), deduped: true };
+      } catch (readError) {
+        if (readError?.code !== "ENOENT") throw readError;
+        // Claim removed between EEXIST and read (resolve/dismiss race) — retry create.
+      }
+    }
+  }
+
+  throw new AlertStoreError("Unable to claim open alert fingerprint.", {
+    code: "claim_failed",
+    details: { fingerprint: candidate.fingerprint }
+  });
+}
+
+/**
+ * List alerts. Open records come from open/<fingerprint>;
+ * terminal history comes from alt-<id>/alert.json.
+ * Corrupt records fail closed.
+ */
+export async function listAlerts({ homeDir, state = null, limit = null } = {}) {
+  const dir = harnessHomePaths(homeDir).alertsDir;
+  if (!existsSync(dir)) return [];
+
+  const open = await listOpenAlerts(homeDir);
+  const openIds = new Set(open.map((alert) => alert.alertId));
+  const alerts = [...open];
+
+  for (const alertId of (await readdir(dir)).filter((n) => /^alt-[a-f0-9]{16,32}$/.test(n))) {
+    if (openIds.has(alertId)) continue;
+    try {
+      alerts.push(await readHistoryAlert(homeDir, alertId));
+    } catch (error) {
+      wrapCorruptAlert(`alert "${alertId}"`, { alertId }, error);
+    }
+  }
+
+  alerts.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt))
+    || String(a.alertId).localeCompare(String(b.alertId)));
+  const filtered = state ? alerts.filter((a) => a.state === state) : alerts;
+  return Number.isInteger(limit) && limit >= 0 ? filtered.slice(0, limit) : filtered;
+}
+
+async function transitionAlert(alertId, nextState, { homeDir } = {}) {
+  const current = await loadAlert(alertId, { homeDir });
+  if (current.state !== ALERT_STATES.OPEN) return current;
+  const now = new Date().toISOString();
+  const updated = await writeHistoryAlert({
+    ...current,
+    state: nextState,
+    updatedAt: now,
+    resolvedAt: now
+  }, { homeDir });
+  const indexPath = openIndexPath(homeDir, current.fingerprint);
+  await unlink(indexPath).catch((error) => {
+    if (error?.code !== "ENOENT") throw error;
+  });
+  return updated;
+}
+
+export async function resolveAlert(alertId, { homeDir } = {}) {
+  return transitionAlert(alertId, ALERT_STATES.RESOLVED, { homeDir });
+}
+
+export async function dismissAlert(alertId, { homeDir } = {}) {
+  return transitionAlert(alertId, ALERT_STATES.DISMISSED, { homeDir });
+}

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 };
+}