@kal-elsam/kairo-runtime 0.8.0 → 0.10.0

package/src/global/ink/ux/live-usage.js

@@ -0,0 +1,51 @@
+/**
+ * Live semantic Usage panel — renderer only; model lives in cockpit-usage.js.
+ * ActionList never owns focus.
+ */
+import React from "react";
+import { Box, Text } from "ink";
+import { COCKPIT_COLORS } from "../theme.js";
+import { LAYOUT_MODES } from "../layout.js";
+import { adaptUsageModel } from "../cockpit-usage.js";
+import { ActionList, Callout } from "./semantic.js";
+
+export function SemanticUsagePanel({
+  snapshot = null,
+  dashboard = null,
+  layoutMode = LAYOUT_MODES.COMPACT,
+  colorEnabled = true,
+  unicode = true
+}) {
+  const model = adaptUsageModel({ snapshot, dashboard, layoutMode });
+  const muted = colorEnabled ? COCKPIT_COLORS.muted : undefined;
+  return React.createElement(Box, { flexDirection: "column" },
+    React.createElement(Text, {
+      bold: true, color: colorEnabled ? COCKPIT_COLORS.secondary : undefined
+    }, model.title),
+    React.createElement(Callout, {
+      tone: model.callout.tone,
+      title: model.callout.title,
+      body: model.callout.body || undefined,
+      colorEnabled,
+      compact: true
+    }),
+    React.createElement(Text, { bold: true }, "Measured"),
+    React.createElement(Text, null, `  ${model.measured}`),
+    React.createElement(Text, { bold: true }, "Configured limits"),
+    React.createElement(Text, null, `  ${model.configured}`),
+    React.createElement(Text, { bold: true }, "Run usage"),
+    model.runs.length === 0
+      ? React.createElement(Text, null, "  No auditable run tokenUsage yet.")
+      : React.createElement(ActionList, {
+        items: model.runs,
+        selectedIndex: -1,
+        focused: false,
+        colorEnabled,
+        unicode
+      }),
+    model.moreLine
+      ? React.createElement(Text, { color: muted }, model.moreLine)
+      : null,
+    React.createElement(Text, { color: muted }, model.footnote)
+  );
+}

package/src/global/ink/ux/semantic.js

@@ -0,0 +1,84 @@
+/** Semantic Ink primitives — structured models, not string-array panels. */
+import React from "react";
+import { Box, Text } from "ink";
+import { COCKPIT_COLORS, statusColor, resolveGlyphs } from "../theme.js";
+
+const mute = (on) => (on ? COCKPIT_COLORS.muted : undefined);
+
+export function ActionList({ items = [], selectedIndex = 0, focused = true, colorEnabled = true, unicode = true }) {
+  const g = resolveGlyphs(unicode);
+  return React.createElement(Box, { flexDirection: "column" },
+    ...items.map((item, i) => {
+      const sel = i === selectedIndex;
+      return React.createElement(Text, {
+        key: item.id ?? String(i),
+        bold: sel,
+        color: sel && focused && colorEnabled ? COCKPIT_COLORS.primary : undefined
+      }, `${sel && focused ? g.focus : " "} ${item.label}${item.hint ? `  ${item.hint}` : ""}`);
+    })
+  );
+}
+
+export function Stepper({ steps = [], currentIndex = 0, colorEnabled = true, unicode = true }) {
+  // Progress marks: not focus `>` and not failure-looking `x`.
+  const done = unicode ? "✓" : "+";
+  const current = unicode ? "●" : "*";
+  const idle = unicode ? "·" : "-";
+  return React.createElement(Box, { flexDirection: "column" },
+    ...steps.map((step, i) => {
+      const isDone = i < currentIndex;
+      const cur = i === currentIndex;
+      const color = isDone
+        ? (colorEnabled ? COCKPIT_COLORS.success : undefined)
+        : cur ? (colorEnabled ? COCKPIT_COLORS.primary : undefined) : mute(colorEnabled);
+      return React.createElement(Text, {
+        key: step.id ?? String(i), bold: cur, color
+      }, `${isDone ? done : cur ? current : idle} ${i + 1}. ${step.label}`);
+    })
+  );
+}
+
+export function Callout({ tone = "info", title, body, colorEnabled = true, compact = false }) {
+  const kind = tone === "danger" ? "danger" : tone === "warn" ? "warn" : "ready";
+  return React.createElement(Box, {
+    flexDirection: "column",
+    marginY: compact ? 0 : 1
+  },
+    React.createElement(Text, { bold: true, color: statusColor(kind, { colorEnabled }) }, title),
+    body ? React.createElement(Text, null, body) : null
+  );
+}
+
+export function Confirm({ summary, primaryLabel = "Confirm", focused = true, colorEnabled = true, mark = " " }) {
+  return React.createElement(Box, { flexDirection: "column" },
+    summary ? React.createElement(Text, null, summary) : null,
+    React.createElement(Text, {
+      bold: focused,
+      color: focused && colorEnabled ? COCKPIT_COLORS.primary : undefined
+    }, `${mark} ${primaryLabel}`)
+  );
+}
+
+export function Receipt({ title = "Receipt", lines = [], colorEnabled = true }) {
+  return React.createElement(Box, { flexDirection: "column" },
+    React.createElement(Text, { bold: true, color: colorEnabled ? COCKPIT_COLORS.success : undefined }, title),
+    ...lines.map((line, i) => React.createElement(Text, { key: `r${i}`, color: mute(colorEnabled) }, line))
+  );
+}
+
+export function Details({ open = false, summary = "Details", lines = [], colorEnabled = true, focused = false, mark = " " }) {
+  const color = focused && colorEnabled ? COCKPIT_COLORS.primary : mute(colorEnabled);
+  if (!open) return React.createElement(Text, { bold: focused, color }, `${mark} ${summary} · Space`);
+  return React.createElement(Box, { flexDirection: "column" },
+    React.createElement(Text, { bold: true, color }, `${mark} ${summary}`),
+    ...lines.map((line, i) => React.createElement(Text, { key: `d${i}`, color: mute(colorEnabled) }, line))
+  );
+}
+
+export function KeyBar({ hints = [], colorEnabled = true, columns = 80 }) {
+  const width = Math.max(24, Math.min(Number(columns) || 80, 120));
+  return React.createElement(Box, { width },
+    React.createElement(Text, { color: mute(colorEnabled) },
+      hints.map((h) => `${h.keys} ${h.label}`).join(" · "))
+  );
+}

package/src/global/ink/ux/task-flow-app.js

@@ -0,0 +1,85 @@
+import React, { useEffect, useReducer } from "react";
+import { Box, Text, useApp, useInput, useStdout } from "ink";
+import { COCKPIT_COLORS, resolveGlyphs } from "../theme.js";
+import { resolveTerminalCapabilities } from "../terminal-capabilities.js";
+import { ActionList, Callout, Confirm, Details, KeyBar, Receipt, Stepper } from "./semantic.js";
+import {
+  FOCUS, SCREENS, createTaskFlowState, keyHintsFor, modelForState, reduceTaskFlow, resolvePrimaryPresentation
+} from "./task-flow.js";
+
+export function TaskFlowApp({ columns: cols, rows: rowCount, onExit } = {}) {
+  const { exit } = useApp();
+  const { stdout } = useStdout();
+  const [state, dispatch] = useReducer(
+    reduceTaskFlow,
+    createTaskFlowState({ columns: cols ?? stdout?.columns ?? 80, rows: rowCount ?? stdout?.rows ?? 24 })
+  );
+  const caps = resolveTerminalCapabilities({
+    columns: state.columns, rows: state.rows, env: process.env, isTTY: true
+  });
+  const model = modelForState(state);
+  const primary = resolvePrimaryPresentation(model, state, caps.unicode);
+  const detailsMark = state.focus === FOCUS.DETAILS ? resolveGlyphs(caps.unicode).focus : " ";
+  const accent = caps.color ? COCKPIT_COLORS.primary : undefined;
+
+  useEffect(() => {
+    if (!stdout) return undefined;
+    const onResize = () => dispatch({ type: "resize", columns: stdout.columns ?? 80, rows: stdout.rows ?? 24 });
+    stdout.on("resize", onResize);
+    return () => stdout.off("resize", onResize);
+  }, [stdout]);
+
+  useEffect(() => {
+    if (!state.exited) return;
+    onExit?.({ reason: "escape" });
+    exit();
+  }, [state.exited, exit, onExit]);
+
+  useInput((input, key) => {
+    if (key.upArrow) dispatch({ type: "up" });
+    else if (key.downArrow) dispatch({ type: "down" });
+    else if (key.return) dispatch({ type: "enter" });
+    else if (key.escape) dispatch({ type: "escape" });
+    else if (input === " ") dispatch({ type: "space" });
+    else if (input === "/") dispatch({ type: "slash" });
+  });
+
+  return React.createElement(Box, { flexDirection: "column", width: state.columns },
+    React.createElement(Text, { bold: true, color: accent }, `Kairo · ${model.title} · ${state.layout}`),
+    React.createElement(Callout, { ...model.callout, colorEnabled: caps.color }),
+    state.screen === SCREENS.SETUP
+      ? React.createElement(Stepper, {
+        steps: model.steps, currentIndex: model.stepIndex, colorEnabled: caps.color, unicode: caps.unicode
+      })
+      : null,
+    primary.mode === "confirm"
+      ? React.createElement(Confirm, {
+        summary: primary.summary, primaryLabel: primary.label,
+        focused: state.focus === FOCUS.PRIMARY, colorEnabled: caps.color, mark: primary.mark
+      })
+      : React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, {
+          bold: state.focus === FOCUS.PRIMARY,
+          color: state.focus === FOCUS.PRIMARY ? accent : undefined
+        }, `${primary.mark} ${primary.label}`),
+        primary.detail
+          ? React.createElement(Text, { color: caps.color ? COCKPIT_COLORS.muted : undefined }, primary.detail)
+          : null
+      ),
+    model.receipt ? React.createElement(Receipt, { ...model.receipt, colorEnabled: caps.color }) : null,
+    (model.secondary || model.metrics)
+      ? React.createElement(ActionList, {
+        items: model.secondary ?? model.metrics,
+        selectedIndex: state.listIndex,
+        focused: state.focus === FOCUS.LIST,
+        colorEnabled: caps.color,
+        unicode: caps.unicode
+      })
+      : null,
+    React.createElement(Details, {
+      open: state.detailsOpen, summary: "Details", lines: model.details,
+      colorEnabled: caps.color, focused: state.focus === FOCUS.DETAILS, mark: detailsMark
+    }),
+    React.createElement(KeyBar, { hints: keyHintsFor(state), colorEnabled: caps.color, columns: state.columns })
+  );
+}

package/src/global/ink/ux/task-flow.js

@@ -0,0 +1,173 @@
+/** Pure task-flow prototype: Home → Setup → Overview. Mock only — no writes. */
+
+export const SCREENS = { HOME: "home", SETUP: "setup", OVERVIEW: "overview" };
+export const FOCUS = { PRIMARY: "primary", LIST: "list", DETAILS: "details" };
+export const SETUP_STEPS = [
+  { id: "detect", label: "Detect agents" },
+  { id: "select", label: "Select governance" },
+  { id: "review", label: "Review changes" },
+  { id: "confirm", label: "Confirm" },
+  { id: "receipt", label: "Receipt" }
+];
+
+export function resolveLayout(c = 80, r = 24) {
+  if (c >= 120 && r >= 40) return "wide";
+  if (c < 80 || r < 24) return "minimal";
+  return "compact";
+}
+
+export function createTaskFlowState(init = {}) {
+  const columns = init.columns ?? 80;
+  const rows = init.rows ?? 24;
+  return {
+    screen: init.screen ?? SCREENS.HOME,
+    setupStep: init.setupStep ?? 0,
+    listIndex: init.listIndex ?? 0,
+    focus: init.focus ?? FOCUS.PRIMARY,
+    detailsOpen: Boolean(init.detailsOpen),
+    columns,
+    rows,
+    exited: Boolean(init.exited),
+    layout: resolveLayout(columns, rows)
+  };
+}
+
+export function buildHomeModel() {
+  return {
+    title: "Home",
+    callout: { tone: "warn", title: "Needs attention", body: "2 open alerts · monitor idle · 1 active run" },
+    primary: { id: "start-setup", label: "Start setup · Cursor drift", detail: "Opens guided setup. Stale hooks detected." },
+    secondary: [
+      { id: "overview", label: "Open overview" },
+      { id: "details", label: "Show details", hint: "paths · ids" }
+    ],
+    details: ["project: agentic-harness", "path hidden until Details"]
+  };
+}
+
+export function buildSetupModel(stepIndex = 0) {
+  const step = SETUP_STEPS[stepIndex] ?? SETUP_STEPS[0];
+  const isConfirm = step.id === "confirm";
+  const isReceipt = step.id === "receipt";
+  return {
+    title: "Setup",
+    steps: SETUP_STEPS,
+    stepIndex,
+    callout: {
+      tone: "info",
+      title: step.label,
+      body: isReceipt ? "Prototype receipt — no files written." : "Enter advances · Esc leaves setup."
+    },
+    primary: { label: isReceipt ? "Open overview" : isConfirm ? "Confirm (no write)" : "Continue" },
+    confirm: isConfirm ? { summary: "Apply governance preview to Cursor hooks.", primaryLabel: "Confirm (no write)" } : null,
+    receipt: isReceipt ? { title: "Receipt", lines: ["status: simulated", "wrote: none", "planId: proto-1"] } : null,
+    details: [`step: ${step.id}`, "write: disabled"]
+  };
+}
+
+export function buildOverviewModel() {
+  return {
+    title: "Overview",
+    callout: { tone: "warn", title: "Attention first", body: "2 items need a decision before secondary metrics." },
+    primary: { label: "Back to home priority" },
+    metrics: [
+      { id: "agents", label: "Protected agents · Cursor · Codex · Pi" },
+      { id: "monitor", label: "Monitor · Disabled" },
+      { id: "runs", label: "Active runs · 1" },
+      { id: "usage", label: "Usage · Pi evidence only" }
+    ],
+    details: ["alert: alt-1", "run: run-1"]
+  };
+}
+
+export function modelForState(state) {
+  if (state.screen === SCREENS.SETUP) return buildSetupModel(state.setupStep);
+  if (state.screen === SCREENS.OVERVIEW) return buildOverviewModel();
+  return buildHomeModel();
+}
+
+/** Focus mark only when PRIMARY — list/details own their own markers. */
+export function focusMarkFor(state, unicode = true) {
+  return state.focus === FOCUS.PRIMARY ? (unicode ? "›" : ">") : " ";
+}
+
+/** Exactly one primary surface; confirm steps own the action (no duplicate line). */
+export function resolvePrimaryPresentation(model, state, unicode = true) {
+  const mark = focusMarkFor(state, unicode);
+  if (model.confirm) {
+    return { mode: "confirm", summary: model.confirm.summary, label: model.confirm.primaryLabel, mark };
+  }
+  return { mode: "primary", label: model.primary.label, detail: model.primary.detail ?? null, mark };
+}
+
+export function keyHintsFor(state) {
+  const hints = [
+    { keys: "↑↓", label: "Move" },
+    { keys: "Enter", label: "Primary" },
+    { keys: "Space", label: "Details" },
+    { keys: "/", label: "Home" },
+    { keys: "Esc", label: state.screen === SCREENS.SETUP ? "Home" : "Exit" }
+  ];
+  return state.layout === "minimal" ? hints.slice(0, 3) : hints;
+}
+
+export function reduceTaskFlow(state, event) {
+  switch (event.type) {
+    case "resize": {
+      const columns = event.columns ?? state.columns;
+      const rows = event.rows ?? state.rows;
+      return { ...state, columns, rows, layout: resolveLayout(columns, rows) };
+    }
+    case "up": return moveList(state, -1);
+    case "down": return moveList(state, 1);
+    case "space": return { ...state, detailsOpen: !state.detailsOpen, focus: FOCUS.DETAILS };
+    case "slash":
+      return { ...state, screen: SCREENS.HOME, focus: FOCUS.PRIMARY, listIndex: 0, detailsOpen: false };
+    case "escape":
+      if (state.detailsOpen) return { ...state, detailsOpen: false, focus: FOCUS.PRIMARY };
+      if (state.screen === SCREENS.SETUP) {
+        return { ...state, screen: SCREENS.HOME, focus: FOCUS.PRIMARY, listIndex: 0 };
+      }
+      return { ...state, exited: true };
+    case "enter": return activate(state);
+    default: return state;
+  }
+}
+
+function listLength(state) {
+  if (state.screen === SCREENS.HOME) return 2;
+  if (state.screen === SCREENS.OVERVIEW) return 4;
+  return 0;
+}
+
+function moveList(state, delta) {
+  const len = listLength(state);
+  if (len <= 0) return { ...state, focus: FOCUS.PRIMARY };
+  if (state.focus !== FOCUS.LIST) {
+    return { ...state, listIndex: delta > 0 ? 0 : len - 1, focus: FOCUS.LIST };
+  }
+  return { ...state, listIndex: (state.listIndex + delta + len) % len, focus: FOCUS.LIST };
+}
+
+function activate(state) {
+  if (state.screen === SCREENS.HOME) {
+    if (state.focus === FOCUS.LIST) {
+      const id = buildHomeModel().secondary[state.listIndex]?.id;
+      if (id === "overview") {
+        return { ...state, screen: SCREENS.OVERVIEW, focus: FOCUS.PRIMARY, listIndex: 0, detailsOpen: false };
+      }
+      if (id === "details") return { ...state, detailsOpen: !state.detailsOpen, focus: FOCUS.DETAILS };
+    }
+    return { ...state, screen: SCREENS.SETUP, setupStep: 0, focus: FOCUS.PRIMARY, listIndex: 0, detailsOpen: false };
+  }
+  if (state.screen === SCREENS.SETUP) {
+    if (state.setupStep >= SETUP_STEPS.length - 1) {
+      return { ...state, screen: SCREENS.OVERVIEW, focus: FOCUS.PRIMARY, listIndex: 0, detailsOpen: false };
+    }
+    return { ...state, setupStep: state.setupStep + 1, focus: FOCUS.PRIMARY, detailsOpen: false };
+  }
+  if (state.screen === SCREENS.OVERVIEW) {
+    return { ...state, screen: SCREENS.HOME, focus: FOCUS.PRIMARY, listIndex: 0, detailsOpen: false };
+  }
+  return state;
+}

package/src/global/orchestrator.js

@@ -85,27 +85,44 @@ export async function runOrchestratorShell({
       }
     }
 
-    const outcome = await runOrchestratorInkImpl({
-      homeDir,
-      workspaceRoot,
-      packageRoot,
-      packageName: packageManifest.name,
-      cliVersion: packageManifest.version,
-      hasGlobalState: hasConfiguredGlobalState(homeDir),
-      fullscreenSession: session
-    });
-
-    if (outcome.error) {
-      throw outcome.error;
-    }
+    for (;;) {
+      const outcome = await runOrchestratorInkImpl({
+        homeDir,
+        workspaceRoot,
+        packageRoot,
+        packageName: packageManifest.name,
+        cliVersion: packageManifest.version,
+        hasGlobalState: hasConfiguredGlobalState(homeDir),
+        fullscreenSession: session
+      });
+
+      if (outcome.error) {
+        throw outcome.error;
+      }
 
-    return {
-      cancelled: Boolean(outcome.cancelled),
-      wrote: Boolean(setupOutcome && !setupOutcome.cancelled),
-      action: outcome.action ?? null,
-      initialMode,
-      setup: setupOutcome
-    };
+      if (outcome?.action === "setup") {
+        const mid = await runHarnessSetupImpl({
+          packageRoot,
+          packageName: packageManifest.name,
+          cliVersion: packageManifest.version,
+          homeDir,
+          workspaceRoot,
+          onboarding: false,
+          interactive: true,
+          fullscreenSession: session
+        });
+        if (!mid?.cancelled) setupOutcome = mid;
+        continue;
+      }
+
+      return {
+        cancelled: Boolean(outcome.cancelled),
+        wrote: Boolean(setupOutcome && !setupOutcome.cancelled),
+        action: outcome.action ?? null,
+        initialMode,
+        setup: setupOutcome
+      };
+    }
   } finally {
     if (ownsSession) {
       session.leave();

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