@tpsdev-ai/flair 0.5.3 → 0.6.0

package/dist/resources/health.js

@@ -1,5 +1,21 @@
 import { Resource, databases } from "@harperfast/harper";
+import { promises as fsp } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
 const db = databases;
+const redactHome = (p) => {
+    const home = homedir();
+    return p.startsWith(home) ? "~" + p.slice(home.length) : p;
+};
+const exists = async (path) => {
+    try {
+        await fsp.stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * Health endpoint — unauthenticated, returns only { ok: true }.
  *
@@ -15,26 +31,87 @@ export class Health extends Resource {
 /**
  * Authenticated health detail — returns memory/agent/soul stats + process info.
  * Requires Ed25519 agent auth or admin basic auth.
+ *
+ * Every optional-subsystem lookup is wrapped so a missing table or absent
+ * schema downgrades to "not configured" rather than failing the whole call.
  */
 export class HealthDetail extends Resource {
     async get() {
         const stats = { ok: true };
+        const nowMs = Date.now();
+        const warnings = [];
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const callerAgent = request?.tpsAgent;
+        const isAdmin = request?.tpsAgentIsAdmin === true || !callerAgent;
+        stats.caller = { agentId: callerAgent ?? null, isAdmin };
+        let memoriesList = [];
         // ── Memory stats ──
         try {
-            const list = [];
             for await (const m of db.flair.Memory.search({})) {
-                list.push(m);
+                memoriesList.push(m);
+            }
+            // Per-model counts: "hash-512d" is the hash-fallback marker; any other
+            // value (or missing value) is a real embedding. Multiple distinct
+            // non-hash models means mixed vector spaces — cross-space searches
+            // return garbage unless reconciled via `flair reembed`.
+            const modelCounts = {};
+            for (const m of memoriesList) {
+                const model = m.embeddingModel || "hash-512d";
+                modelCounts[model] = (modelCounts[model] ?? 0) + 1;
+            }
+            const hashFallback = modelCounts["hash-512d"] ?? 0;
+            const withEmbeddings = memoriesList.length - hashFallback;
+            const realModels = Object.keys(modelCounts).filter((k) => k !== "hash-512d");
+            const byDurability = { permanent: 0, persistent: 0, standard: 0, ephemeral: 0 };
+            let archived = 0;
+            let expired = 0;
+            for (const m of memoriesList) {
+                const d = (m.durability ?? "standard");
+                if (d in byDurability)
+                    byDurability[d]++;
+                if (m.archived)
+                    archived++;
+                if (!m.archived && m.validTo && new Date(m.validTo).getTime() < nowMs)
+                    expired++;
             }
             stats.memories = {
-                total: list.length,
-                withEmbeddings: list.filter((m) => m.embeddingModel && m.embeddingModel !== "hash-512d").length,
-                hashFallback: list.filter((m) => !m.embeddingModel || m.embeddingModel === "hash-512d").length,
+                total: memoriesList.length,
+                withEmbeddings,
+                hashFallback,
+                modelCounts,
+                byDurability,
+                archived,
+                expired,
             };
-            if (list.length > 0) {
-                const sorted = list.filter((m) => m.createdAt).sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+            if (memoriesList.length > 0) {
+                const sorted = memoriesList
+                    .filter((m) => m.createdAt)
+                    .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
                 if (sorted[0])
                     stats.lastWrite = sorted[0].createdAt;
             }
+            if (expired > 0)
+                warnings.push({ level: "warn", message: `${expired} memories have expired validTo but aren't archived` });
+            // Hash-fallback coverage — tiered by percentage. Thresholds are
+            // first-pass defaults; Kern's review on ops-n4n may tune them.
+            if (memoriesList.length > 0) {
+                const pct = Math.round((hashFallback / memoriesList.length) * 100);
+                if (pct >= 10) {
+                    warnings.push({
+                        level: "warn",
+                        message: `${hashFallback}/${memoriesList.length} (${pct}%) memories are hash-fallback — run: flair reembed --stale-only --dry-run`,
+                    });
+                }
+            }
+            // Mixed embedding models — searches across vector spaces return garbage.
+            if (realModels.length > 1) {
+                const list = realModels.map((k) => `${k}:${modelCounts[k]}`).join(", ");
+                warnings.push({
+                    level: "warn",
+                    message: `multiple embedding models in use (${list}) — cross-model search unreliable; run: flair reembed against one model`,
+                });
+            }
         }
         catch {
             stats.memories = null;
@@ -42,28 +119,380 @@ export class HealthDetail extends Resource {
         // ── Agent stats ──
         try {
             const agents = [];
-            for await (const a of db.flair.Agent.search({})) {
+            for await (const a of db.flair.Agent.search({}))
                 agents.push(a);
+            const blank = (id) => ({
+                id, memoryCount: 0, hashFallback: 0, writes24h: 0, lastWriteAt: null,
+            });
+            const perAgentMap = new Map();
+            for (const a of agents) {
+                if (a.id)
+                    perAgentMap.set(a.id, blank(a.id));
+            }
+            const cutoff24h = nowMs - 24 * 3600 * 1000;
+            for (const m of memoriesList) {
+                if (!m.agentId)
+                    continue;
+                const row = perAgentMap.get(m.agentId) ?? blank(m.agentId);
+                row.memoryCount++;
+                if (!m.embeddingModel || m.embeddingModel === "hash-512d")
+                    row.hashFallback++;
+                if (m.createdAt) {
+                    const ts = new Date(m.createdAt).getTime();
+                    if (ts >= cutoff24h)
+                        row.writes24h++;
+                    if (!row.lastWriteAt || ts > new Date(row.lastWriteAt).getTime()) {
+                        row.lastWriteAt = m.createdAt;
+                    }
+                }
+                perAgentMap.set(m.agentId, row);
             }
+            const perAgentFull = Array.from(perAgentMap.values()).sort((a, b) => b.memoryCount - a.memoryCount);
+            const perAgent = isAdmin
+                ? perAgentFull
+                : perAgentFull.filter((r) => r.id === callerAgent);
             stats.agents = {
                 count: agents.length,
-                names: agents.map((a) => a.id).filter(Boolean),
+                names: isAdmin ? agents.map((a) => a.id).filter(Boolean) : undefined,
+                perAgent,
             };
         }
         catch {
             stats.agents = null;
         }
-        // ── Soul stats ──
+        // ── Relationships ──
         try {
-            let count = 0;
-            for await (const _ of db.flair.Soul.search({})) {
-                count++;
+            const rels = [];
+            for await (const r of db.flair.Relationship.search({}))
+                rels.push(r);
+            if (rels.length === 0) {
+                stats.relationships = null;
+            }
+            else {
+                const active = rels.filter((r) => !r.validTo || new Date(r.validTo).getTime() > nowMs).length;
+                stats.relationships = { total: rels.length, active };
             }
-            stats.soulEntries = count;
+        }
+        catch {
+            stats.relationships = null;
+        }
+        // ── Soul ──
+        try {
+            const souls = [];
+            for await (const s of db.flair.Soul.search({}))
+                souls.push(s);
+            stats.soulEntries = souls.length;
+            const byPriority = { critical: 0, high: 0, standard: 0, low: 0 };
+            for (const s of souls) {
+                const p = (s.priority ?? "standard");
+                if (p in byPriority)
+                    byPriority[p]++;
+            }
+            stats.soul = { total: souls.length, byPriority };
         }
         catch {
             stats.soulEntries = null;
+            stats.soul = null;
+        }
+        // ── Federation ──
+        try {
+            const instances = [];
+            try {
+                for await (const i of db.flair.Instance.search({}))
+                    instances.push(i);
+            }
+            catch { /* absent */ }
+            const peers = [];
+            try {
+                for await (const p of db.flair.Peer.search({}))
+                    peers.push(p);
+            }
+            catch { /* absent */ }
+            const tokens = [];
+            try {
+                for await (const t of db.flair.PairingToken.search({}))
+                    tokens.push(t);
+            }
+            catch { /* absent */ }
+            if (instances.length === 0 && peers.length === 0) {
+                stats.federation = null;
+            }
+            else {
+                const inst = instances[0];
+                const peersBlock = {
+                    total: peers.length,
+                    connected: peers.filter((p) => p.status === "connected").length,
+                    disconnected: peers.filter((p) => p.status === "disconnected").length,
+                    revoked: peers.filter((p) => p.status === "revoked").length,
+                };
+                const pendingTokens = tokens.filter((t) => !t.consumedBy && t.expiresAt && new Date(t.expiresAt).getTime() > nowMs).length;
+                stats.federation = {
+                    instance: inst ? { id: inst.id, role: inst.role, status: inst.status } : null,
+                    peers: peersBlock,
+                    pendingTokens,
+                    peerList: isAdmin
+                        ? peers.map((p) => ({
+                            id: p.id,
+                            role: p.role,
+                            status: p.status,
+                            lastSyncAt: p.lastSyncAt ?? null,
+                        }))
+                        : undefined,
+                };
+                if (peers.length > 0 && peersBlock.connected === 0) {
+                    const oldest = peers
+                        .map((p) => (p.lastSyncAt ? new Date(p.lastSyncAt).getTime() : 0))
+                        .reduce((a, b) => (a === 0 ? b : b === 0 ? a : Math.min(a, b)), 0);
+                    if (oldest > 0 && nowMs - oldest > 24 * 3600 * 1000) {
+                        warnings.push({ level: "warn", message: "federation peers all disconnected >24h" });
+                    }
+                }
+                if (pendingTokens > 0) {
+                    warnings.push({ level: "info", message: `${pendingTokens} pairing token(s) unconsumed` });
+                }
+            }
+        }
+        catch {
+            stats.federation = null;
+        }
+        // ── OAuth / IdP ──
+        try {
+            const clients = [];
+            try {
+                for await (const c of db.flair.OAuthClient.search({}))
+                    clients.push(c);
+            }
+            catch { /* absent */ }
+            const idps = [];
+            try {
+                for await (const i of db.flair.IdpConfig.search({}))
+                    idps.push(i);
+            }
+            catch { /* absent */ }
+            let activeTokens = 0;
+            let tokensAvailable = true;
+            try {
+                const toks = [];
+                for await (const t of db.flair.OAuthToken.search({}))
+                    toks.push(t);
+                activeTokens = toks.filter((t) => {
+                    if (t.revokedAt)
+                        return false;
+                    if (t.expiresAt && new Date(t.expiresAt).getTime() < nowMs)
+                        return false;
+                    return true;
+                }).length;
+            }
+            catch {
+                tokensAvailable = false;
+            }
+            if (clients.length === 0 && idps.length === 0) {
+                stats.oauth = null;
+            }
+            else {
+                stats.oauth = {
+                    clients: clients.length,
+                    idpConfigs: idps.length,
+                    activeTokens: tokensAvailable ? activeTokens : 0,
+                    clientList: isAdmin
+                        ? clients.map((c) => ({
+                            id: c.id,
+                            name: c.name,
+                            registeredBy: c.registeredBy ?? null,
+                            createdAt: c.createdAt ?? null,
+                        }))
+                        : undefined,
+                    idpList: isAdmin
+                        ? idps.map((i) => ({ id: i.id, name: i.name, issuer: i.issuer }))
+                        : undefined,
+                };
+            }
+        }
+        catch {
+            stats.oauth = null;
+        }
+        // ── REM ──
+        try {
+            const logsDir = join(homedir(), ".flair", "logs");
+            const remLog = join(logsDir, "rem.jsonl");
+            const nightlyLog = join(logsDir, "rem-nightly.jsonl");
+            const tailJsonl = async (path, maxBytes = 256 * 1024) => {
+                let fh = null;
+                try {
+                    const st = await fsp.stat(path).catch(() => null);
+                    if (!st)
+                        return [];
+                    const start = Math.max(0, st.size - maxBytes);
+                    const len = st.size - start;
+                    if (len === 0)
+                        return [];
+                    fh = await fsp.open(path, "r");
+                    const buf = Buffer.alloc(len);
+                    await fh.read(buf, 0, len, start);
+                    return buf
+                        .toString("utf-8")
+                        .split("\n")
+                        .filter((l) => l.trim())
+                        .map((l) => { try {
+                        return JSON.parse(l);
+                    }
+                    catch {
+                        return null;
+                    } })
+                        .filter(Boolean);
+                }
+                catch {
+                    return [];
+                }
+                finally {
+                    if (fh)
+                        await fh.close().catch(() => { });
+                }
+            };
+            const remRecords = await tailJsonl(remLog);
+            const findLast = (kind) => {
+                for (let i = remRecords.length - 1; i >= 0; i--) {
+                    const r = remRecords[i];
+                    if (r && (r.kind === kind || r.type === kind))
+                        return r.at ?? r.ts ?? r.timestamp ?? null;
+                }
+                return null;
+            };
+            const lastLightAt = findLast("light");
+            const lastRapidAt = findLast("rapid");
+            const lastRestorativeAt = findLast("restorative");
+            let nightlyEnabled = null;
+            const plat = platform();
+            if (plat === "darwin") {
+                nightlyEnabled = await exists(join(homedir(), "Library", "LaunchAgents", "dev.flair.rem.nightly.plist"));
+            }
+            else if (plat === "linux") {
+                nightlyEnabled = await exists(join(homedir(), ".config", "systemd", "user", "flair-rem-nightly.timer"));
+            }
+            const nightlyRecords = await tailJsonl(nightlyLog);
+            const lastNightlyRec = nightlyRecords[nightlyRecords.length - 1];
+            const lastNightlyAt = lastNightlyRec ? (lastNightlyRec.at ?? lastNightlyRec.ts ?? lastNightlyRec.timestamp ?? null) : null;
+            let pendingCandidates = null;
+            try {
+                let count = 0;
+                for await (const c of db.flair.MemoryCandidate.search({})) {
+                    if (c.status === "pending")
+                        count++;
+                }
+                pendingCandidates = count;
+            }
+            catch {
+                pendingCandidates = null;
+            }
+            const allNull = !lastLightAt &&
+                !lastRapidAt &&
+                !lastRestorativeAt &&
+                nightlyEnabled === null &&
+                !lastNightlyAt &&
+                pendingCandidates === null;
+            if (allNull) {
+                stats.rem = null;
+            }
+            else {
+                stats.rem = {
+                    lastLightAt,
+                    lastRapidAt,
+                    lastRestorativeAt,
+                    nightlyEnabled,
+                    lastNightlyAt,
+                    pendingCandidates,
+                };
+                if (nightlyEnabled && lastNightlyAt && nowMs - new Date(lastNightlyAt).getTime() > 48 * 3600 * 1000) {
+                    warnings.push({ level: "warn", message: "nightly REM hasn't run in >48h" });
+                }
+            }
+        }
+        catch {
+            stats.rem = null;
+        }
+        // ── Disk ──
+        try {
+            const dataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+            const snapshotDir = join(homedir(), ".flair", "snapshots");
+            const dirSize = async (root, maxDepth = 6) => {
+                if (!(await exists(root)))
+                    return null;
+                let total = 0;
+                const walk = async (p, depth) => {
+                    if (depth > maxDepth)
+                        return;
+                    let entries;
+                    try {
+                        entries = await fsp.readdir(p, { withFileTypes: true });
+                    }
+                    catch {
+                        return;
+                    }
+                    const subdirs = [];
+                    const files = [];
+                    for (const e of entries) {
+                        const full = join(p, e.name);
+                        if (e.isDirectory())
+                            subdirs.push(full);
+                        else if (e.isFile())
+                            files.push(full);
+                    }
+                    const sizes = await Promise.all(files.map((f) => fsp.stat(f).then((s) => s.size).catch(() => 0)));
+                    total += sizes.reduce((a, b) => a + b, 0);
+                    await Promise.all(subdirs.map((d) => walk(d, depth + 1)));
+                };
+                await walk(root, 0);
+                return total;
+            };
+            const [dataBytes, snapshotBytes] = await Promise.all([dirSize(dataDir), dirSize(snapshotDir)]);
+            if (dataBytes === null && snapshotBytes === null) {
+                stats.disk = null;
+            }
+            else {
+                stats.disk = {
+                    dataDir: isAdmin ? dataDir : redactHome(dataDir),
+                    dataBytes: dataBytes ?? 0,
+                    snapshotDir: isAdmin ? snapshotDir : redactHome(snapshotDir),
+                    snapshotBytes: snapshotBytes ?? 0,
+                };
+            }
+        }
+        catch {
+            stats.disk = null;
+        }
+        // ── Bridges ──
+        try {
+            const cwd = process.cwd();
+            const candidates = [join(cwd, "node_modules"), join(homedir(), ".flair", "node_modules")];
+            const installed = new Set();
+            await Promise.all(candidates.map(async (base) => {
+                if (!(await exists(base)))
+                    return;
+                try {
+                    const names = await fsp.readdir(base);
+                    for (const name of names) {
+                        if (name.startsWith("flair-bridge-"))
+                            installed.add(name);
+                    }
+                }
+                catch { /* skip */ }
+            }));
+            if (installed.size === 0) {
+                stats.bridges = null;
+            }
+            else {
+                stats.bridges = {
+                    installed: Array.from(installed).sort(),
+                    lastImport: null,
+                    lastExport: null,
+                };
+            }
+        }
+        catch {
+            stats.bridges = null;
         }
+        // ── Warnings ──
+        stats.warnings = warnings;
         // ── Process info ──
         stats.pid = process.pid;
         stats.uptimeSeconds = Math.floor(process.uptime());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",
@@ -30,6 +30,7 @@
   "files": [
     "dist/",
     "schemas/",
+    "ui/",
     "config.yaml",
     "LICENSE",
     "README.md",
@@ -52,10 +53,12 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.0.0",
+    "@harperfast/harper": "5.0.1",
+    "@types/js-yaml": "^4.0.9",
     "commander": "14.0.3",
-    "harper-fabric-embeddings": "0.2.2",
+    "harper-fabric-embeddings": "0.2.3",
     "jose": "^6.2.2",
+    "js-yaml": "^4.1.1",
     "tweetnacl": "1.0.3"
   },
   "devDependencies": {
@@ -70,8 +73,5 @@
   "workspaces": [
     "packages/*",
     "plugins/*"
-  ],
-  "optionalDependencies": {
-    "@node-llama-cpp/mac-arm64-metal": "3.18.1"
-  }
+  ]
 }

package/ui/observation-center.html

@@ -0,0 +1,91 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Observation Center</title>
+  <style>
+    :root{--bg:#f4efe6;--panel:rgba(255,251,243,.86);--ink:#1e241f;--muted:#697265;--line:rgba(30,36,31,.12);--accent:#0f766e;--accent-soft:rgba(15,118,110,.12);--ok:#166534;--warn:#b45309;--shadow:0 18px 48px rgba(69,58,35,.14)}
+    *{box-sizing:border-box}body{margin:0;min-height:100vh;font:15px/1.45 "IBM Plex Sans","Avenir Next",sans-serif;color:var(--ink);background:radial-gradient(circle at top left,rgba(15,118,110,.14),transparent 28rem),radial-gradient(circle at top right,rgba(180,83,9,.1),transparent 18rem),linear-gradient(180deg,#fcfaf5,var(--bg))}
+    .shell{max-width:1280px;margin:0 auto;padding:28px 18px 40px}.hero,.panel{background:var(--panel);border:1px solid var(--line);border-radius:22px;backdrop-filter:blur(14px);box-shadow:var(--shadow)}.hero{padding:24px;margin-bottom:18px}.hero h1,.panel h2{margin:0;font-family:"IBM Plex Serif","Iowan Old Style",serif}.hero h1{font-size:clamp(2rem,4vw,3.1rem)}.hero p,.subtle,.empty{color:var(--muted)}
+    .summary,.grid,.events,.toolbar,.layout{display:grid;gap:12px}.summary{grid-template-columns:repeat(auto-fit,minmax(150px,1fr));margin-top:18px}.chip,.card,.event{background:rgba(255,255,255,.62);border:1px solid var(--line);border-radius:16px;padding:14px}.chip strong{display:block;font-size:1.3rem}.chip span{font-size:.92rem;color:var(--muted)}
+    .toolbar{grid-template-columns:repeat(auto-fit,minmax(160px,1fr));padding:16px;margin-bottom:18px}.field{display:flex;flex-direction:column;gap:6px}.field label{font-size:.8rem;text-transform:uppercase;letter-spacing:.08em;color:var(--muted)}.field input,.field select,.field button{width:100%;padding:11px 12px;border-radius:12px;border:1px solid var(--line);background:#fffaf1;font:inherit;color:var(--ink)}.field button{cursor:pointer;color:#fff;background:linear-gradient(135deg,var(--accent),#115e59);border:none;font-weight:600}
+    .layout{grid-template-columns:1.05fr 1.4fr;align-items:start}.panel{padding:18px}.head,.row{display:flex;justify-content:space-between;gap:10px}.head{align-items:baseline;margin-bottom:14px}.grid{grid-template-columns:repeat(auto-fill,minmax(220px,1fr))}.events{max-height:72vh;overflow:auto;padding-right:4px}.card h3,.event h3{margin:0;font-size:1rem}.meta,.workspace{font-size:.9rem;color:var(--muted)}.event p{margin:8px 0 0;white-space:pre-wrap;word-break:break-word}.kind{font:0.82rem "IBM Plex Mono",monospace;color:var(--accent)}.badge{display:inline-flex;align-items:center;gap:6px;padding:4px 10px;border-radius:999px;font-size:.8rem;font-weight:600;background:var(--accent-soft);color:var(--accent)}.ok{background:rgba(22,101,52,.12);color:var(--ok)}.warn{background:rgba(180,83,9,.14);color:var(--warn)}
+    @media (max-width:1080px){.toolbar{grid-template-columns:repeat(2,minmax(0,1fr))}.layout{grid-template-columns:1fr}.events{max-height:none}}@media (max-width:640px){.shell{padding:18px 12px 32px}.toolbar{grid-template-columns:1fr}}
+  </style>
+</head>
+<body>
+  <div class="shell">
+    <section class="hero">
+      <h1>Observation Center</h1>
+      <p>Read-only Flair dashboard for OrgEvents, roster state, and latest workspace snapshots. Polling every 5 seconds.</p>
+      <div class="summary" id="summary"></div>
+    </section>
+    <section class="panel toolbar">
+      <div class="field"><label for="baseUrl">Flair URL</label><input id="baseUrl" placeholder="(same origin)"></div>
+      <div class="field"><label for="adminPass">Admin password</label><input id="adminPass" type="password" placeholder="Basic admin auth"></div>
+      <div class="field"><label for="agentFilter">Agent</label><select id="agentFilter"><option value="">All agents</option></select></div>
+      <div class="field"><label for="kindFilter">Event kind</label><select id="kindFilter"><option value="">All kinds</option></select></div>
+      <div class="field"><label for="timeFilter">Time range</label><select id="timeFilter"><option value="15m">Last 15 minutes</option><option value="1h" selected>Last hour</option><option value="6h">Last 6 hours</option><option value="24h">Last 24 hours</option></select></div>
+      <div class="field"><label>&nbsp;</label><button id="refresh">Refresh now</button></div>
+    </section>
+    <div class="layout">
+      <section class="panel">
+        <div class="head"><div><h2>Agent Grid</h2><p class="subtle">Status is derived from recent OrgEvents and workspace snapshots.</p></div><p class="subtle" id="agentStatus">Loading agents…</p></div>
+        <div class="grid" id="agentGrid"></div>
+      </section>
+      <section class="panel">
+        <div class="head"><div><h2>Event Feed</h2><p class="subtle">Events visible to <code>anvil</code> via <code>/OrgEventCatchup/anvil</code>.</p></div><p class="subtle" id="feedStatus">Waiting for first poll…</p></div>
+        <div class="events" id="eventFeed"></div>
+      </section>
+    </div>
+  </div>
+  <script>
+    const state={anchorAgent:"anvil",agents:[],events:[],workspace:{},latestPoll:null,timer:null};
+    const els={summary:document.querySelector("#summary"),baseUrl:document.querySelector("#baseUrl"),adminPass:document.querySelector("#adminPass"),agentFilter:document.querySelector("#agentFilter"),kindFilter:document.querySelector("#kindFilter"),timeFilter:document.querySelector("#timeFilter"),refresh:document.querySelector("#refresh"),agentGrid:document.querySelector("#agentGrid"),eventFeed:document.querySelector("#eventFeed"),agentStatus:document.querySelector("#agentStatus"),feedStatus:document.querySelector("#feedStatus")};
+    const SS_PASS="flair.observation.adminPass",SS_URL="flair.observation.baseUrl";
+    const storedPass=sessionStorage.getItem(SS_PASS);if(storedPass)els.adminPass.value=storedPass;
+    const storedUrl=sessionStorage.getItem(SS_URL);if(storedUrl)els.baseUrl.value=storedUrl;
+    function authHeader(){const p=clean(els.adminPass.value);return p?"Basic "+btoa("admin:"+p):""}
+    const clean=v=>String(v??"").trim();
+    const ESC_MAP={"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"};
+    // esc() is used in BOTH attribute and text contexts; browsers HTML-decode attribute
+    // values when reading .value, so round-trips (e.g. agentFilter.value) preserve the original.
+    const esc=v=>String(v??"").replace(/[&<>"']/g,c=>ESC_MAP[c]);
+    const parse=v=>{if(!v)return null;if(typeof v==="object")return v;try{return JSON.parse(v)}catch{return null}};
+    const list=v=>Array.isArray(v)?v:Array.isArray(v?.items)?v.items:Array.isArray(v?.data)?v.data:[];
+    const eventKind=e=>clean(e?.kind||e?.type||e?.status||"unknown");
+    const eventText=e=>clean(e?.summary||e?.detail||e?.message||"");
+    const eventAgents=e=>[e?.authorId,...(Array.isArray(e?.targetIds)?e.targetIds:[])].map(clean).filter(Boolean);
+    const timeAgo=iso=>{const diff=Date.now()-new Date(iso).getTime();if(!Number.isFinite(diff))return"unknown";const m=Math.round(diff/6e4);if(m<1)return"just now";if(m<60)return`${m}m ago`;const h=Math.round(m/60);if(h<24)return`${h}h ago`;return`${Math.round(h/24)}d ago`};
+    const rangeMs=()=>({"15m":9e5,"1h":36e5,"6h":216e5,"24h":864e5}[els.timeFilter.value]||36e5);
+    const rangeStart=()=>new Date(Date.now()-rangeMs());
+    async function getJson(url){const headers={accept:"application/json"};const auth=authHeader();if(auth)headers.authorization=auth;const res=await fetch(url,{headers});if(res.status===401){sessionStorage.removeItem(SS_PASS);els.adminPass.value="";throw new Error("401 unauthorized — enter admin password and refresh")}if(!res.ok)throw new Error(`${res.status} ${res.statusText}`);return res.json()}
+    async function loadRoster(baseUrl){return list(await getJson(baseUrl+"/Agent"))}
+    async function loadWorkspace(baseUrl,agentIds){const rows=await Promise.all(agentIds.map(async id=>{try{return[id,await getJson(baseUrl+"/WorkspaceLatest/"+encodeURIComponent(id))]}catch{return[id,null]}}));state.workspace=Object.fromEntries(rows)}
+    function deriveAgent(agent){
+      const id=clean(agent.id||agent.agentId||agent.name);
+      const related=state.events.filter(event=>eventAgents(event).includes(id));
+      const latest=related.at(-1);
+      const ws=state.workspace[id];
+      const snapshot=parse(ws?.snapshot);
+      const lastAt=clean(latest?.createdAt||ws?.timestamp||ws?.createdAt||agent.updatedAt||agent.createdAt);
+      const online=lastAt&&(Date.now()-new Date(lastAt).getTime())<6e5;
+      return{id,name:clean(agent.name||id),role:clean(agent.role||agent.type||"agent"),status:online?"online":"offline",lastAt,currentTask:clean(parse(latest?.detail)?.taskId||latest?.refId||latest?.summary||"idle"),latestKind:eventKind(latest),workspace:clean(snapshot?.gitBranch||ws?.gitBranch||ws?.path||"unavailable")};
+    }
+    function filteredEvents(){const agent=els.agentFilter.value,kind=els.kindFilter.value,start=rangeStart();return state.events.filter(e=>{if(new Date(e.createdAt||0)<start)return false;if(agent&&!eventAgents(e).includes(agent))return false;if(kind&&eventKind(e)!==kind)return false;return true}).slice().reverse()}
+    function renderSummary(cards,events){const items=[["Agents",cards.length],["Online",cards.filter(c=>c.status==="online").length],["Events",events.length],["Last Poll",state.latestPoll?timeAgo(state.latestPoll):"never"]];els.summary.innerHTML=items.map(([l,v])=>`<div class="chip"><strong>${v}</strong><span>${l}</span></div>`).join("")}
+    function renderFilters(){const agents=state.agents.map(a=>clean(a.id||a.agentId||a.name)).filter(Boolean).sort();const kinds=[...new Set(state.events.map(eventKind).filter(Boolean))].sort();const chosenAgent=els.agentFilter.value,chosenKind=els.kindFilter.value;els.agentFilter.innerHTML=`<option value="">All agents</option>`+agents.map(id=>`<option value="${esc(id)}" ${id===chosenAgent?"selected":""}>${esc(id)}</option>`).join("");els.kindFilter.innerHTML=`<option value="">All kinds</option>`+kinds.map(kind=>`<option value="${esc(kind)}" ${kind===chosenKind?"selected":""}>${esc(kind)}</option>`).join("")}
+    function renderAgents(cards){els.agentStatus.textContent=`${cards.length} agents via /Agent`;els.agentGrid.innerHTML=cards.length?cards.map(agent=>`<article class="card"><div class="row"><h3>${esc(agent.name)}</h3><span class="badge ${agent.status==="online"?"ok":"warn"}">${esc(agent.status)}</span></div><div class="meta">${esc(agent.role)}</div><div class="row"><span class="kind">${esc(agent.latestKind)}</span><span class="meta">${agent.lastAt?timeAgo(agent.lastAt):"no signal"}</span></div><p><strong>Current task:</strong> ${esc(agent.currentTask)}</p><div class="workspace">Workspace: ${esc(agent.workspace)}</div></article>`).join(""):`<div class="empty">No agents found.</div>`}
+    function renderEvents(events){els.feedStatus.textContent=`${events.length} matching events`;els.eventFeed.innerHTML=events.length?events.map(event=>`<article class="event"><div class="row"><h3>${esc(clean(event.summary||eventKind(event)))}</h3><span class="meta">${timeAgo(event.createdAt)}</span></div><div class="row"><span class="kind">${esc(eventKind(event))}</span><span class="badge">${esc(eventAgents(event).join(", "))||"org-wide"}</span></div><p>${esc(eventText(event))||"No detail provided."}</p></article>`).join(""):`<div class="empty">No events match the current filters.</div>`}
+    function render(){renderFilters();const cards=state.agents.map(deriveAgent);const events=filteredEvents();renderSummary(cards,events);renderAgents(cards);renderEvents(events)}
+    async function refresh(){const baseUrl=clean(els.baseUrl.value).replace(/\/$/,"");const since=rangeStart().toISOString();els.feedStatus.textContent="Polling Flair…";try{const [agents,events]=await Promise.all([loadRoster(baseUrl),getJson(`${baseUrl}/OrgEventCatchup/${encodeURIComponent(state.anchorAgent)}?since=${encodeURIComponent(since)}`)]);state.agents=agents;state.events=list(events).sort((a,b)=>clean(a.createdAt).localeCompare(clean(b.createdAt)));await loadWorkspace(baseUrl,state.agents.map(a=>clean(a.id||a.agentId||a.name)).filter(Boolean));state.latestPoll=new Date().toISOString();render()}catch(error){els.feedStatus.textContent=`Poll failed: ${error.message}`}}
+    function schedule(){clearInterval(state.timer);state.timer=setInterval(refresh,5e3)}
+    [els.agentFilter,els.kindFilter,els.timeFilter].forEach(el=>el.addEventListener("change",()=>{render();if(el===els.timeFilter)refresh()}));
+    els.refresh.addEventListener("click",refresh);
+    els.baseUrl.addEventListener("change",()=>{sessionStorage.setItem(SS_URL,clean(els.baseUrl.value));refresh();schedule()});
+    els.adminPass.addEventListener("change",()=>{sessionStorage.setItem(SS_PASS,clean(els.adminPass.value));refresh()});
+    refresh();schedule();
+  </script>
+</body>
+</html>