@tpsdev-ai/flair 0.25.4 → 0.27.0

package/dist/cli.js

@@ -20,7 +20,7 @@ import { markStale, sortOldestVersionFirst } from "./fleet-presence.js";
 import { detectClients, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
 import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, defaultMcpIssuer, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
 import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMcpMetadata, } from "./lib/mcp-enable.js";
-import { readClientMcpBlock, checkClaudeMdBootstrap, checkSessionStartHook, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, describeAgentGateFinding, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
+import { readClientMcpBlock, checkClaudeMdBootstrap, checkSessionStartHook, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, inferSoleAgentId, fixCommandAgentHint, describeAgentGateFinding, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
 import { installHook, uninstallHook, hookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
 import { readSecretFileSecure, readAdminPassFileSecure, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
 // Federation crypto helpers — inlined to avoid cross-boundary imports from
@@ -2725,6 +2725,17 @@ program
             console.log(`   └─────────────────────────────────────────────────┘`);
         }
         console.log(`\n   Export: FLAIR_URL=${httpUrl}`);
+        // flair#802a: a non-interactive shell (CI, Docker, an unattended setup
+        // script) that omits --agent lands here with NO indication that agent
+        // registration, MCP client wiring, and the smoke test were all skipped
+        // — the run exits 0 and looks complete. In a real TTY the missing
+        // --agent is usually obvious from the command the user just typed;
+        // non-interactively it's easy to never notice until something that
+        // needed the agent (recall, an MCP client) mysteriously doesn't work.
+        if (!process.stdin.isTTY) {
+            console.log(`\n   ℹ Non-interactive shell: skipped agent registration, MCP client wiring, and the smoke test.`);
+            console.log(`     Complete setup with: flair init --agent <id> --client all`);
+        }
     }
     // All init work is genuinely done at this point: Harper is installed +
     // running (detached, unref'd — survives this process exiting), the agent is
@@ -6432,6 +6443,12 @@ remNightly
         if (row.candidates) {
             console.log(`Staged:     ${row.candidates.length} candidate${row.candidates.length === 1 ? "" : "s"}`);
         }
+        // row.dedup populates when step 6 (instance-wide dedup-cluster stat,
+        // flair-quality Slice 1c) succeeded this cycle. Absent on dry-run skip
+        // or a non-fatal failure (see Errors below — e.g. non-admin caller).
+        if (row.dedup) {
+            console.log(`Dedup:      ${row.dedup.clusterCount} cluster${row.dedup.clusterCount === 1 ? "" : "s"} (${row.dedup.totalMemoriesInClusters} memories, largest ${row.dedup.largestClusterSize})`);
+        }
         console.log(`Duration:   ${row.durationMs}ms`);
         if (row.errors.length > 0) {
             console.log(`Errors:`);
@@ -8650,11 +8667,22 @@ async function stopFlairProcess(port) {
     console.log("Stopping...");
     try {
         const { execSync } = await import("node:child_process");
-        const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
+        // -sTCP:LISTEN: match the LISTENING server only — a bare `lsof -ti :port`
+        // also matches CLIENT sockets referencing the port, including THIS CLI's
+        // own keep-alive connections left by the credential pre-flight's
+        // probeInstance() HTTP calls (flair#741). Without the filter, the upgrade
+        // path SIGTERM'd its own process mid-restart — "Stopping..." then death
+        // (exit 143) before "Starting..." ever ran, leaving the server down
+        // (flair#800, deterministic on the Linux/non-launchd default path).
+        const lsof = execSync(`lsof -ti :${port} -sTCP:LISTEN`, { encoding: "utf-8" }).trim();
         if (lsof) {
             for (const pid of lsof.split("\n")) {
+                const target = Number(pid.trim());
+                // Belt-and-suspenders: never SIGTERM ourselves, whatever lsof says.
+                if (!Number.isFinite(target) || target === process.pid)
+                    continue;
                 try {
-                    process.kill(Number(pid.trim()), "SIGTERM");
+                    process.kill(target, "SIGTERM");
                 }
                 catch { }
             }
@@ -9815,9 +9843,18 @@ program
                             console.log(`     Skipped.`);
                         }
                         else {
-                            const fixAgentId = opts.agent || process.env.FLAIR_AGENT_ID || anyKnownAgentId;
+                            // flair#802b: fall back to the sole locally-keyed agent when
+                            // nothing else identifies one — the only case doctor can
+                            // infer without being told (see inferSoleAgentId's doc
+                            // comment in doctor-client.ts for why 0/2+ keys don't guess).
+                            const fixAgentId = opts.agent || process.env.FLAIR_AGENT_ID || anyKnownAgentId || inferSoleAgentId(keyAgentIds);
                             if (!fixAgentId) {
-                                console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: no agent id known — pass --agent <id>`);
+                                if (keyAgentIds.length > 1) {
+                                    console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: multiple agents found (${[...keyAgentIds].sort().join(", ")}) — pass --agent <id> to choose which one`);
+                                }
+                                else {
+                                    console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: no agent registered — run \`flair agent add <id>\` first, then re-run \`flair doctor --fix\``);
+                                }
                             }
                             else {
                                 const wireEnv = { FLAIR_AGENT_ID: fixAgentId, FLAIR_URL: resolveWireFlairUrl(block.flairUrl, baseUrl) };
@@ -9833,7 +9870,13 @@ program
                     }
                 }
                 else {
-                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, `(wires ${client.label} automatically)`)}`);
+                    // flair#802b: only splice in a concrete --agent if the id isn't
+                    // already resolvable some other way — an explicit --agent /
+                    // FLAIR_AGENT_ID / an already-wired client's agent id means bare
+                    // `--fix` already works, so don't clutter the suggestion.
+                    const knownAgentId = opts.agent || process.env.FLAIR_AGENT_ID || anyKnownAgentId;
+                    const agentHint = knownAgentId ? "" : fixCommandAgentHint(keyAgentIds);
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix${agentHint} ${render.wrap(render.c.dim, `(wires ${client.label} automatically)`)}`);
                 }
                 issues++;
                 continue;
@@ -10148,6 +10191,892 @@ program
     if (summary.exitCode !== 0)
         process.exit(summary.exitCode);
 });
+// ─── flair quality — pure metric computation ─────────────────────────────────
+// Slice 1a of the memory-quality-observability arc (ops/proposals/
+// flair-quality-slice1-spec.md, K&S design-approved). Same "extract the pure
+// decision logic" idiom as summarizeDoctorRun above (flair#721) and
+// derivePresenceStatus (resources/Presence.ts): the CLI action spawns a
+// network fetch + a long console.log sequence, which is high-effort/
+// low-value to drive directly in a test — this is the actual metric math,
+// fed a fixture-shaped /HealthDetail body.
+//
+// ZERO new server surface. Every field this reads already exists in
+// resources/health.ts's response (the same one `flair status`/`flair doctor`
+// consume) — no new query pattern, no new endpoint. That's what makes the
+// Sherlock "read-scope holds by construction" argument hold: quality can
+// never see anything status/doctor couldn't already see, because it reads
+// the identical payload.
+//
+// One metric from the design doc is deliberately NOT computed at full
+// fidelity here — it degrades gracefully into a `gaps` entry instead of
+// failing:
+//   - staleness: /HealthDetail's `memories.expired` count is instance-wide
+//     only (resources/health.ts never buckets it per agent), so --agent
+//     does not scope this metric. The "old + never-recalled" variant isn't
+//     computed at all — no read API exposes per-memory last-recalled data.
+//
+// Slice 1b (flair-quality-slice1b): signal density now ALSO carries citation
+// rate. Kern's design nod: extend /HealthDetail's per-agent aggregation
+// server-side (resources/health.ts sums Memory.usageCount — a field already
+// loaded by the existing memory loop, no new query) rather than have the CLI
+// join against `GET /Memory` itself — keeps quality's read footprint
+// identical to status/doctor's by construction. `citationRate` here is
+// computed CLI-side from the two numbers the server hands back
+// (usageCount/memoryCount), same "server aggregates, CLI computes" split as
+// every other metric in this file.
+//
+// Backward compatibility: an OLDER server's /HealthDetail predates
+// per-agent `usageCount` entirely (field is `undefined` on the row, not
+// `0` — Slice 1a's payload literally didn't have the key). That's detected
+// per-row and the whole report degrades to the Slice-1a write-volume-only
+// shape + a gap note, rather than silently reporting citationRate 0 as if
+// it were real data from a server that never sent it.
+//
+// Naming (Sherlock security finding on the design round, reaffirmed for
+// citation rate): "signal density" / "citation rate" describes a USAGE
+// PATTERN, never a trust/quality verdict. A low citation rate means "writes
+// exploratory content that's rarely cited", not "noisy" or "untrustworthy"
+// — same for "quiet agents": an ops fact (days since last write), not a
+// trust signal. Keep that framing in any copy touching this code.
+//
+// Slice 1c (flair-quality-slice1c-dedup-spec.md, K&S-resolved to "Option C,
+// server-side"): dedup-cluster count — how many near-duplicate memory
+// CLUSTERS exist instance-wide. Sherlock's hard security line: embeddings
+// are the most sensitive data in the system and must never leave the
+// server, so — unlike every other metric in this file — the computation
+// does NOT happen here. A nightly server-side REM step
+// (resources/MemoryDedupStats.ts, wired into src/rem/runner.ts) computes it
+// server-side via a bounded-k ANN sweep (reusing the HNSW-backed retrieval
+// core) and persists ONLY the aggregate `{clusterCount, largestClusterSize,
+// totalMemoriesInClusters, computedAt}` to a small server-side stat file.
+// /HealthDetail does a CHEAP read of that file (resources/health.ts) —
+// still zero new query pattern from the CLI's perspective, same "quality
+// reads a precomputed number from /HealthDetail" contract as every other
+// metric here. Nightly-stale by construction (only as fresh as the last
+// REM cycle) — that's an accepted trade-off, not a bug: it's a "silting up"
+// trend signal, not a real-time alert. Absent (fresh instance, REM never
+// run, or an older server) degrades to `null` + a `gaps` entry, never a
+// false zero.
+//
+// Slice 1d (memory-quality arc, self-referential design — no hardcoded canned
+// queries): recall SPOT-CHECK. Unlike every metric above, this ISN'T read
+// from /HealthDetail at all — it's the one metric in this file that requires
+// live QUERIES, because it's checking whether querying itself still works.
+// For a sample of the querying agent's OWN memories (fetchRecallSpotCheckData
+// below, GET /Memory?agentId=<self>), a CUE is derived from each memory
+// (deriveRecallCue — its `subject` if present, else the leading ~8 words /
+// first sentence of `content`; a PARTIAL cue, never the full content) and
+// searched for through the EXACT SAME authenticated read path `flair memory
+// search` uses: `api("POST", "/SemanticSearch", ...)`, which resolves auth
+// via the shared authedRequest() 5-tier resolver (src/lib/auth-resolve.ts) —
+// identical code path, so read-scope holds by construction (no new
+// endpoint, no cross-agent/private data, scoped to the querying agent's own
+// memories same as `flair memory search` always was). computeRecallSpotCheck
+// (below) is the pure scorer: recall@k = fraction of sampled memories whose
+// own id appears in its search's top-k; MRR = mean reciprocal rank (0 if
+// not found within k).
+//
+// Framing — this is a HEALTH SPOT-CHECK, not a benchmark and not a trust
+// judgment. Querying by a cue derived FROM the target memory is easier than
+// a real user query, so a high score means "recall is functioning", not
+// "recall is optimal". Its job is to catch recall CRATERING (embeddings
+// down, index busted) — the score collapsing toward 0 is the signal, not
+// fine-grained precision grading. Requires an actual agent identity to
+// query AS (semantic search is agent-scoped) — no identity, fewer than the
+// sample-size memories to sample, or a search error all degrade to `null` +
+// a `gaps` entry, same graceful-degradation contract as every metric here —
+// NEVER a false 0.0 masquerading as a real (broken) score.
+/** First-pass default, same "documented heuristic, not derived from data we
+ *  don't have" spirit as health.ts's own 10%-hash-fallback threshold below.
+ *  Tunable later if a real fleet shows this is too loud/quiet. */
+export const QUALITY_QUIET_THRESHOLD_DAYS = 7;
+/** Mirrors resources/health.ts's own hash-fallback warning threshold (kept as
+ *  a literal constant here rather than imported — health.ts computes its
+ *  warning string server-side, this recomputes the same judgment CLI-side
+ *  from the raw counts so quality doesn't depend on parsing warning text). */
+export const QUALITY_HASH_FALLBACK_DEGRADED_PCT = 10;
+/** Recall spot-check (Slice 1d) defaults — how many of the querying agent's
+ *  own memories to sample, and the top-k depth each is searched at. Same
+ *  "first-pass default, tunable later" spirit as the thresholds above. */
+export const QUALITY_RECALL_SAMPLE_SIZE = 10;
+export const QUALITY_RECALL_K = 5;
+/**
+ * Derive a PARTIAL search cue from a memory — used by the recall spot-check
+ * (Slice 1d) to query for a memory without handing back its full content.
+ * Prefers `subject` when present and non-trivial (a real word or phrase, not
+ * empty/whitespace-only padding); otherwise falls back to the first sentence
+ * of `content`, capped to the leading ~8 words so the cue stays a genuine
+ * partial cue rather than the whole memory. Pure — no I/O.
+ */
+export function deriveRecallCue(memory) {
+    const subject = (memory.subject ?? "").trim();
+    if (subject.length >= 3)
+        return subject;
+    const content = (memory.content ?? "").trim();
+    if (!content)
+        return "";
+    const sentenceMatch = content.match(/^[^.!?\n]+[.!?]?/);
+    const firstSentence = (sentenceMatch ? sentenceMatch[0] : content).trim();
+    const words = firstSentence.split(/\s+/).filter(Boolean);
+    const cueWordLimit = 8;
+    return words.length <= cueWordLimit ? firstSentence : words.slice(0, cueWordLimit).join(" ");
+}
+/**
+ * Pure scorer for the recall spot-check (Slice 1d): given the ids of the
+ * sampled memories and, for each, the list of memory ids its derived-cue
+ * search returned (already agent-scoped via the same read path `flair
+ * memory search` uses), compute recall@k + MRR. `perQueryResultIds[i]` is
+ * truncated to the first `k` entries here (not assumed pre-truncated by the
+ * caller) so a caller that over-fetches still gets a correct top-k score.
+ * Never throws; an empty sample scores 0/0 rather than dividing by zero —
+ * callers are expected to treat an empty sample as a `gaps` case, not a
+ * real 0.0 score (see fetchRecallSpotCheckData / computeQualityReport).
+ */
+export function computeRecallSpotCheck(sampledIds, perQueryResultIds, k) {
+    const sampleSize = sampledIds.length;
+    if (sampleSize === 0) {
+        return { recallAtK: 0, mrr: 0, sampleSize: 0, k };
+    }
+    let hits = 0;
+    let reciprocalSum = 0;
+    for (let i = 0; i < sampleSize; i++) {
+        const targetId = sampledIds[i];
+        const topK = (perQueryResultIds[i] ?? []).slice(0, k);
+        const rank = topK.indexOf(targetId);
+        if (rank !== -1) {
+            hits += 1;
+            reciprocalSum += 1 / (rank + 1);
+        }
+    }
+    return {
+        recallAtK: Math.round((hits / sampleSize) * 100) / 100,
+        mrr: Math.round((reciprocalSum / sampleSize) * 100) / 100,
+        sampleSize,
+        k,
+    };
+}
+/**
+ * Pure computation: /HealthDetail response (+ reachability) → quality report.
+ * Never throws — every missing data source degrades to a null section + a
+ * `gaps` entry (same graceful-degradation contract as `flair doctor`), so a
+ * partially-populated instance still gets a partial, honest report instead
+ * of a crash.
+ *
+ * `opts.recallSpotCheckData` is the ONE exception to "fed purely from
+ * /HealthDetail": the recall spot-check (Slice 1d) requires live queries
+ * (fetchRecallSpotCheckData, run by the `quality` command BEFORE calling
+ * here, same "I/O happens outside, this function only computes" split as
+ * fetchHealthDetail/computeQualityReport itself). Passing nothing degrades
+ * to a `gaps` entry, same as every other metric.
+ */
+export function computeQualityReport(healthy, healthData, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const agentFilter = opts.agentId ?? null;
+    const gaps = [];
+    // ── Instance health: migrations ──
+    let migrationsClean = null;
+    let haltedMigrations = [];
+    const migList = healthData?.migrations?.migrations;
+    if (Array.isArray(migList)) {
+        haltedMigrations = migList
+            .filter((m) => m?.state === "halted" || m?.state === "failed")
+            .map((m) => ({ id: m.id, state: m.state, reason: m.reason }));
+        migrationsClean = haltedMigrations.length === 0;
+    }
+    else {
+        gaps.push({ metric: "instance.migrationsClean", reason: "no migrations block in /HealthDetail response" });
+    }
+    // ── Instance health: embeddings operational ──
+    // Inferred from stored coverage stats (hash-fallback %, mixed embedding
+    // models) — NOT a live semantic round-trip like `flair doctor` runs
+    // (verifySemanticSearch writes a probe memory to verify recall-by-meaning,
+    // which this read-only command must not do).
+    let embeddingsStatus = "unknown";
+    let embeddingsDetail = "no memory stats available";
+    const memories = healthData?.memories;
+    if (memories && typeof memories.total === "number") {
+        if (memories.total === 0) {
+            embeddingsDetail = "no memories written yet";
+        }
+        else {
+            const hashFallback = memories.hashFallback ?? 0;
+            const pct = Math.round((hashFallback / memories.total) * 100);
+            const modelCounts = (memories.modelCounts ?? {});
+            const realModels = Object.keys(modelCounts).filter((k) => k !== "hash-512d" && modelCounts[k] > 0);
+            if (pct >= QUALITY_HASH_FALLBACK_DEGRADED_PCT) {
+                embeddingsStatus = "degraded";
+                embeddingsDetail = `${hashFallback}/${memories.total} (${pct}%) memories are hash-fallback`;
+            }
+            else if (realModels.length > 1) {
+                embeddingsStatus = "degraded";
+                embeddingsDetail = `multiple embedding models in use (${realModels.join(", ")}) — cross-model search unreliable`;
+            }
+            else {
+                embeddingsStatus = "ok";
+                embeddingsDetail = `${memories.total - hashFallback}/${memories.total} memories have real embeddings`;
+            }
+        }
+    }
+    // ── Embedding coverage ──
+    let embeddingCoverage = null;
+    if (memories && typeof memories.total === "number") {
+        const total = memories.total;
+        const hashFallback = memories.hashFallback ?? 0;
+        const withEmbeddings = typeof memories.withEmbeddings === "number" ? memories.withEmbeddings : Math.max(0, total - hashFallback);
+        const coveragePct = total > 0 ? Math.round((withEmbeddings / total) * 100) : 0;
+        embeddingCoverage = { total, withEmbeddings, hashFallback, coveragePct };
+    }
+    else {
+        gaps.push({ metric: "embeddingCoverage", reason: "no memory stats available in /HealthDetail response" });
+    }
+    // ── Staleness (instance-wide only — see module doc above) ──
+    let staleness = null;
+    if (memories && typeof memories.total === "number" && typeof memories.expired === "number") {
+        const total = memories.total;
+        const expired = memories.expired;
+        const stalePct = total > 0 ? Math.round((expired / total) * 100) : 0;
+        staleness = { scope: "instance", total, expired, stalePct };
+        gaps.push({
+            metric: "staleness",
+            reason: "instance-wide only — /HealthDetail's `expired` count isn't broken down per agent, so --agent doesn't scope this metric; the \"old + never-recalled\" dead-weight variant also isn't computed (no read API exposes per-memory last-recalled data)",
+        });
+    }
+    else {
+        gaps.push({ metric: "staleness", reason: "no expired-memory count available in /HealthDetail response" });
+    }
+    // ── Per-agent rows (shared source for signal density + quiet agents) ──
+    const perAgentAll = Array.isArray(healthData?.agents?.perAgent) ? healthData.agents.perAgent : [];
+    const havePerAgent = Array.isArray(healthData?.agents?.perAgent);
+    const scopedAgents = agentFilter ? perAgentAll.filter((r) => r.id === agentFilter) : perAgentAll;
+    // Detected from the UNFILTERED rows (not scopedAgents) so `--agent` never
+    // masquerades server capability as data-scoping — vacuously true on an
+    // empty perAgent array (nothing to prove otherwise, and both scopes render
+    // identically empty either way).
+    const haveUsageCount = perAgentAll.every((r) => typeof r.usageCount === "number");
+    // ── Signal density (write volume, + citation rate when the server supports it) ──
+    let signalDensity = null;
+    if (havePerAgent && haveUsageCount) {
+        signalDensity = {
+            scope: "write-and-citation",
+            perAgent: scopedAgents.map((r) => {
+                const usageCount = r.usageCount ?? 0;
+                const citationRate = r.memoryCount > 0 ? Math.round((usageCount / r.memoryCount) * 100) / 100 : 0;
+                return { id: r.id, memoryCount: r.memoryCount, writes24h: r.writes24h, lastWriteAt: r.lastWriteAt, usageCount, citationRate };
+            }),
+        };
+    }
+    else if (havePerAgent) {
+        signalDensity = {
+            scope: "write-volume",
+            perAgent: scopedAgents.map((r) => ({ id: r.id, memoryCount: r.memoryCount, writes24h: r.writes24h, lastWriteAt: r.lastWriteAt })),
+        };
+        gaps.push({
+            metric: "signalDensity",
+            reason: "citation rate unavailable — server predates per-agent usageCount in /HealthDetail; upgrade the server",
+        });
+    }
+    else {
+        gaps.push({ metric: "signalDensity", reason: "no per-agent stats available in /HealthDetail response" });
+    }
+    // ── Quiet agents (ops fact — not a trust signal) ──
+    let quietAgents = null;
+    if (havePerAgent) {
+        const rows = scopedAgents.map((r) => {
+            const daysSinceLastWrite = r.lastWriteAt ? Math.floor((now - new Date(r.lastWriteAt).getTime()) / 86_400_000) : null;
+            const quiet = daysSinceLastWrite === null ? true : daysSinceLastWrite >= QUALITY_QUIET_THRESHOLD_DAYS;
+            return { id: r.id, memoryCount: r.memoryCount, writes24h: r.writes24h, lastWriteAt: r.lastWriteAt, daysSinceLastWrite, quiet };
+        });
+        quietAgents = { thresholdDays: QUALITY_QUIET_THRESHOLD_DAYS, perAgent: rows, quietCount: rows.filter((r) => r.quiet).length };
+    }
+    else {
+        gaps.push({ metric: "quietAgents", reason: "no per-agent stats available in /HealthDetail response" });
+    }
+    // ── Dedup clusters (instance-wide near-duplicate count — flair-quality
+    // Slice 1c) — an ops/health signal, not a trust judgment (see module doc
+    // and QualityReport['dedupClusters'] doc above). Always instance-wide;
+    // --agent does not scope it (matches staleness's precedent — the
+    // underlying stat has no per-agent breakdown, by design: per-memory
+    // cluster membership is a disclosure surface Sherlock's review explicitly
+    // ruled out storing at all).
+    let dedupClusters = null;
+    const dedup = healthData?.dedup;
+    if (dedup &&
+        typeof dedup.clusterCount === "number" &&
+        typeof dedup.largestClusterSize === "number" &&
+        typeof dedup.totalMemoriesInClusters === "number" &&
+        typeof dedup.computedAt === "string") {
+        dedupClusters = {
+            clusterCount: dedup.clusterCount,
+            largestClusterSize: dedup.largestClusterSize,
+            totalMemoriesInClusters: dedup.totalMemoriesInClusters,
+            computedAt: dedup.computedAt,
+        };
+    }
+    else {
+        gaps.push({
+            metric: "dedupClusters",
+            reason: "no dedup-cluster stat yet — computed nightly by REM (see `flair rem nightly enable`); run `flair rem nightly run-once` or wait for the first scheduled cycle",
+        });
+    }
+    // ── Recall spot-check (flair-quality Slice 1d) — see module doc above and
+    // QualityReport['recallSpotCheck'] doc for the full framing. Fed by
+    // fetchRecallSpotCheckData's already-fetched raw ids (not by healthData —
+    // this is the one metric here that needed a live query, not a
+    // /HealthDetail read); scored by the pure computeRecallSpotCheck.
+    let recallSpotCheck = null;
+    const rsc = opts.recallSpotCheckData;
+    if (rsc?.ok && rsc.sampledIds && rsc.perQueryResultIds && typeof rsc.k === "number") {
+        const scored = computeRecallSpotCheck(rsc.sampledIds, rsc.perQueryResultIds, rsc.k);
+        recallSpotCheck = { agentId: rsc.agentId ?? agentFilter ?? null, ...scored };
+    }
+    else {
+        gaps.push({
+            metric: "recallSpotCheck",
+            reason: rsc?.skipReason ?? "recall spot-check not attempted — no data passed to computeQualityReport",
+        });
+    }
+    return {
+        agentFilter,
+        instance: { up: healthy, migrationsClean, haltedMigrations, embeddingsStatus, embeddingsDetail },
+        embeddingCoverage,
+        staleness,
+        signalDensity,
+        quietAgents,
+        dedupClusters,
+        recallSpotCheck,
+        gaps,
+    };
+}
+/**
+ * The I/O half of the recall spot-check (Slice 1d): fetch a sample of
+ * `agentId`'s own memories and, for each, search for a cue derived from it.
+ * Reuses the EXACT read path `flair memory search` / `flair memory list`
+ * use — `api()` (→ authedRequest's 5-tier resolver) for both the
+ * `GET /Memory?agentId=...` sample fetch and the `POST /SemanticSearch`
+ * queries — so this has zero new endpoint and zero new auth mechanism; it
+ * is scoped to `agentId`'s own memories exactly as those commands already
+ * are. Never throws: every failure mode (no agentId, fewer than
+ * `sampleSize` memories, a fetch/search error) returns `{ ok: false,
+ * skipReason }` for computeQualityReport to turn into a `gaps` entry.
+ */
+async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
+    const sampleSize = opts.sampleSize ?? QUALITY_RECALL_SAMPLE_SIZE;
+    const k = opts.k ?? QUALITY_RECALL_K;
+    if (!agentId) {
+        return { ok: false, skipReason: "no agent identity to query as — pass --agent or set FLAIR_AGENT_ID" };
+    }
+    let all;
+    try {
+        const q = new URLSearchParams({ agentId }).toString();
+        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl });
+        all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
+    }
+    catch (err) {
+        return { ok: false, agentId, skipReason: `could not fetch memories to sample: ${err?.message ?? String(err)}` };
+    }
+    if (all.length < sampleSize) {
+        return {
+            ok: false,
+            agentId,
+            skipReason: `agent '${agentId}' has ${all.length} memories, fewer than the ${sampleSize} needed to sample`,
+        };
+    }
+    // Deterministic sample: the sampleSize most-recently-written memories.
+    const sorted = all.slice().sort((a, b) => {
+        const ta = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+        const tb = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+        return tb - ta;
+    });
+    const sampled = sorted.slice(0, sampleSize);
+    const sampledIds = [];
+    const perQueryResultIds = [];
+    try {
+        for (const m of sampled) {
+            const id = String(m.id);
+            const cue = deriveRecallCue(m);
+            const body = { agentId, q: cue, limit: k };
+            const res = await api("POST", "/SemanticSearch", body, { baseUrl });
+            const results = Array.isArray(res) ? res : (res?.results ?? []);
+            sampledIds.push(id);
+            perQueryResultIds.push(results.map((r) => String(r.id)));
+        }
+    }
+    catch (err) {
+        return { ok: false, agentId, skipReason: `recall spot-check search failed: ${err?.message ?? String(err)}` };
+    }
+    return { ok: true, agentId, sampledIds, perQueryResultIds, k };
+}
+// ─── flair quality --emit (Slice 2 of the memory-quality-observability arc:
+// quality OrgEvents) ─────────────────────────────────────────────────────────
+//
+// Design (K&S-approved in the arc round, honored exactly here):
+//
+// - NO schema change, NO new table/resource. Events ride the existing
+//   OrgEvent surface (schemas/event.graphql: kind/scope/summary/detail/
+//   targetIds/refId — see `flair orgevent` above) via the exact same
+//   PUT /OrgEvent/{id} write shape, extracted into `publishOrgEvent()` below
+//   so both commands share one call site rather than two hand-rolled fetches.
+// - The threshold/diff DECISION is CLI-side (diffQualitySnapshots, pure,
+//   fixture-tested below); emission is a thin write via that existing
+//   surface. Kind is one of two: `quality.threshold_crossed` (an absolute
+//   line was crossed since the last snapshot) or `quality.regression` (a
+//   metric moved backward by more than its delta threshold since the last
+//   snapshot) — see QualityEventFinding.
+// - Snapshots are stored AS Flair memories (durability persistent, subject
+//   `quality-snapshot/<host>` — qualitySnapshotSubject() below) — free
+//   history + search, dogfoods the product, no new storage surface. Content
+//   is the COMPACT numeric core only (QualitySnapshotCore), never the full
+//   human report — see buildQualitySnapshot().
+// - Sherlock's constraint: events carry BEHAVIORAL FACTS only, never trust
+//   judgments — "embedding coverage dropped to 85% (threshold 90%)", never
+//   "agent X is low quality". Every summary string below is written to that
+//   discipline; keep it that way in any future edit here.
+// - Edge-triggered, not level-triggered: every threshold/regression check
+//   below fires only on the TRANSITION since the immediately-previous
+//   snapshot (e.g. quietAgents requires "was NOT quiet last snapshot, IS
+//   quiet now" — the spec's own "NEWLY quiet" wording), not on every run
+//   while a condition merely persists. Without this, a metric that stays
+//   below threshold across many `--emit` runs would re-emit an event every
+//   single run — pure noise. First run (no previous snapshot) therefore
+//   always emits nothing (diffQualitySnapshots(current, null) === []) — there
+//   is no prior state to diff against, so nothing can have "crossed" or
+//   "regressed" yet; that run only establishes the baseline.
+// - Missing data (a null/gap section on either side of the diff) never
+//   produces an event — absence of data is a gap, not a regression. Encoded
+//   by requiring BOTH current and previous to carry a given metric before
+//   diffing it at all.
+/** First-pass defaults for the Slice 2 diff/thresholds — same "documented
+ *  heuristic, tunable later against a real fleet" spirit as
+ *  QUALITY_QUIET_THRESHOLD_DAYS / QUALITY_HASH_FALLBACK_DEGRADED_PCT above.
+ *  Deliberately NOT exposed as CLI flags (per the arc design: the diff
+ *  decision stays CLI-side and legible in one place, not ad-hoc per
+ *  invocation) — change these constants and their fixture tests together. */
+export const QUALITY_EVENT_COVERAGE_ABS_THRESHOLD_PCT = 90;
+export const QUALITY_EVENT_COVERAGE_DROP_THRESHOLD_PCT = 5;
+export const QUALITY_EVENT_STALENESS_ABS_THRESHOLD_PCT = 10;
+export const QUALITY_EVENT_RECALL_DROP_THRESHOLD = 0.2;
+export const QUALITY_EVENT_DEDUP_GROWTH_PCT_THRESHOLD = 0.5; // >50%
+export const QUALITY_EVENT_DEDUP_GROWTH_ABS_THRESHOLD = 5; // AND by >= 5 clusters
+/** Pure: full QualityReport → compact snapshot core. Any section that's
+ *  `null` in the report (a gap) stays `null` in the snapshot — the diff step
+ *  treats that as "no event", never a false 0. */
+export function buildQualitySnapshot(report, computedAt) {
+    return {
+        schemaVersion: 1,
+        computedAt: computedAt ?? new Date().toISOString(),
+        agentFilter: report.agentFilter,
+        embeddingCoverage: report.embeddingCoverage ? { coveragePct: report.embeddingCoverage.coveragePct } : null,
+        staleness: report.staleness ? { stalePct: report.staleness.stalePct } : null,
+        recallSpotCheck: report.recallSpotCheck
+            ? { recallAtK: report.recallSpotCheck.recallAtK, mrr: report.recallSpotCheck.mrr }
+            : null,
+        quietAgents: report.quietAgents
+            ? { perAgent: report.quietAgents.perAgent.map((a) => ({ id: a.id, quiet: a.quiet, daysSinceLastWrite: a.daysSinceLastWrite })) }
+            : null,
+        dedupClusters: report.dedupClusters ? { clusterCount: report.dedupClusters.clusterCount } : null,
+    };
+}
+/**
+ * Pure diff: current snapshot + previous snapshot (or null on a first run)
+ * → the list of OrgEvent findings to emit. Never throws. See the module doc
+ * above for the edge-triggered / missing-data-means-no-event rules; fixture
+ * tests live in test/unit/quality-report.test.ts.
+ */
+export function diffQualitySnapshots(current, previous) {
+    const findings = [];
+    if (!previous)
+        return findings; // first run — nothing to diff against yet
+    // ── embedding coverage: absolute floor (edge-triggered) + delta drop ──
+    if (current.embeddingCoverage && previous.embeddingCoverage) {
+        const before = previous.embeddingCoverage.coveragePct;
+        const after = current.embeddingCoverage.coveragePct;
+        if (after < QUALITY_EVENT_COVERAGE_ABS_THRESHOLD_PCT && before >= QUALITY_EVENT_COVERAGE_ABS_THRESHOLD_PCT) {
+            findings.push({
+                kind: "quality.threshold_crossed",
+                scope: "quality",
+                summary: `embedding coverage dropped to ${after}% (threshold ${QUALITY_EVENT_COVERAGE_ABS_THRESHOLD_PCT}%)`,
+                detail: { metric: "embeddingCoverage.coveragePct", before, after, threshold: QUALITY_EVENT_COVERAGE_ABS_THRESHOLD_PCT },
+            });
+        }
+        if (before - after > QUALITY_EVENT_COVERAGE_DROP_THRESHOLD_PCT) {
+            findings.push({
+                kind: "quality.regression",
+                scope: "quality",
+                summary: `embedding coverage dropped ${before - after} points since last snapshot (${before}% → ${after}%)`,
+                detail: { metric: "embeddingCoverage.coveragePct", before, after, threshold: QUALITY_EVENT_COVERAGE_DROP_THRESHOLD_PCT },
+            });
+        }
+    }
+    // ── staleness: absolute ceiling only (edge-triggered) ──
+    if (current.staleness && previous.staleness) {
+        const before = previous.staleness.stalePct;
+        const after = current.staleness.stalePct;
+        if (after > QUALITY_EVENT_STALENESS_ABS_THRESHOLD_PCT && before <= QUALITY_EVENT_STALENESS_ABS_THRESHOLD_PCT) {
+            findings.push({
+                kind: "quality.threshold_crossed",
+                scope: "quality",
+                summary: `staleness rose to ${after}% past validTo (threshold ${QUALITY_EVENT_STALENESS_ABS_THRESHOLD_PCT}%)`,
+                detail: { metric: "staleness.stalePct", before, after, threshold: QUALITY_EVENT_STALENESS_ABS_THRESHOLD_PCT },
+            });
+        }
+    }
+    // ── recall spot-check: recall@k and MRR, same delta-drop threshold ──
+    if (current.recallSpotCheck && previous.recallSpotCheck) {
+        const beforeR = previous.recallSpotCheck.recallAtK;
+        const afterR = current.recallSpotCheck.recallAtK;
+        if (beforeR - afterR > QUALITY_EVENT_RECALL_DROP_THRESHOLD) {
+            findings.push({
+                kind: "quality.regression",
+                scope: "quality",
+                summary: `recall spot-check recall@k dropped from ${beforeR} to ${afterR} since last snapshot`,
+                detail: { metric: "recallSpotCheck.recallAtK", before: beforeR, after: afterR, threshold: QUALITY_EVENT_RECALL_DROP_THRESHOLD },
+            });
+        }
+        const beforeM = previous.recallSpotCheck.mrr;
+        const afterM = current.recallSpotCheck.mrr;
+        if (beforeM - afterM > QUALITY_EVENT_RECALL_DROP_THRESHOLD) {
+            findings.push({
+                kind: "quality.regression",
+                scope: "quality",
+                summary: `recall spot-check MRR dropped from ${beforeM} to ${afterM} since last snapshot`,
+                detail: { metric: "recallSpotCheck.mrr", before: beforeM, after: afterM, threshold: QUALITY_EVENT_RECALL_DROP_THRESHOLD },
+            });
+        }
+    }
+    // ── quiet agents: per-agent, NEWLY quiet only (was false last snapshot,
+    // true now) — never re-fires for an agent that was already quiet last
+    // snapshot, and never fires for an agent absent from the previous snapshot
+    // (a brand-new agent can't have "regressed" from a state we never saw). ──
+    if (current.quietAgents && previous.quietAgents) {
+        const prevQuietById = new Map(previous.quietAgents.perAgent.map((a) => [a.id, a.quiet]));
+        for (const a of current.quietAgents.perAgent) {
+            if (a.quiet && prevQuietById.get(a.id) === false) {
+                const days = a.daysSinceLastWrite;
+                findings.push({
+                    kind: "quality.threshold_crossed",
+                    scope: "quality",
+                    summary: days == null ? `agent ${a.id} quiet — no recorded write` : `agent ${a.id} quiet for ${days}d (threshold ${QUALITY_QUIET_THRESHOLD_DAYS}d)`,
+                    detail: { metric: "quietAgents", before: false, after: true, threshold: QUALITY_QUIET_THRESHOLD_DAYS },
+                    targetIds: [a.id],
+                });
+            }
+        }
+    }
+    // ── dedup clusters: BOTH >50% relative growth AND >=5 absolute growth ──
+    if (current.dedupClusters && previous.dedupClusters) {
+        const before = previous.dedupClusters.clusterCount;
+        const after = current.dedupClusters.clusterCount;
+        const growth = after - before;
+        const growthPct = before > 0 ? growth / before : (after > 0 ? Infinity : 0);
+        if (growthPct > QUALITY_EVENT_DEDUP_GROWTH_PCT_THRESHOLD && growth >= QUALITY_EVENT_DEDUP_GROWTH_ABS_THRESHOLD) {
+            findings.push({
+                kind: "quality.regression",
+                scope: "quality",
+                summary: `dedup cluster count grew from ${before} to ${after} since last snapshot`,
+                detail: { metric: "dedupClusters.clusterCount", before, after, threshold: QUALITY_EVENT_DEDUP_GROWTH_PCT_THRESHOLD },
+            });
+        }
+    }
+    return findings;
+}
+/** Subject convention for quality snapshots stored as Flair memories: one
+ *  lineage per (agent, Flair instance) pair — an agent that runs
+ *  `quality --emit` against more than one target gets independent diff
+ *  baselines per target, keyed on HOST (not the full URL, so a bare port
+ *  change on the same box doesn't fork the lineage; a different host/instance
+ *  correctly starts its own). */
+export function qualitySnapshotSubject(baseUrl) {
+    let host;
+    try {
+        host = new URL(baseUrl).host;
+    }
+    catch {
+        host = baseUrl.replace(/^[a-zA-Z]+:\/\//, "").replace(/\/.*$/, "");
+    }
+    return `quality-snapshot/${host}`;
+}
+/** Fetch the most recent prior quality snapshot for `agentId` at `baseUrl`,
+ *  via the exact same read path fetchRecallSpotCheckData uses (`api("GET",
+ *  "/Memory?agentId=...")`, self-scoped by the signed request's own agent
+ *  identity — no new endpoint). Filters client-side by subject (the server's
+ *  `GET /Memory?...` doesn't translate query params into search conditions
+ *  beyond the signed agentId scope — see resources/Memory.ts's search()),
+ *  same client-side-filter pattern `memory list --hash-fallback` already
+ *  uses. Returns null on: no prior snapshot, a fetch error, or a snapshot row
+ *  whose content isn't parseable/versioned JSON (never throws — a corrupt or
+ *  foreign row degrades to "no snapshot", same as a genuine first run, rather
+ *  than crashing `--emit`). */
+async function fetchPreviousQualitySnapshot(agentId, baseUrl, subject) {
+    let all;
+    try {
+        const q = new URLSearchParams({ agentId }).toString();
+        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl });
+        all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
+    }
+    catch {
+        return null;
+    }
+    const matches = all.filter((m) => m?.subject === subject);
+    if (matches.length === 0)
+        return null;
+    matches.sort((a, b) => {
+        const ta = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+        const tb = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+        return tb - ta;
+    });
+    try {
+        const parsed = JSON.parse(matches[0].content);
+        if (parsed && typeof parsed === "object" && parsed.schemaVersion === 1)
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Store `snapshot` as a new persistent-durability memory (subject
+ *  `quality-snapshot/<host>`) — the diff baseline the NEXT `--emit` run reads
+ *  back via fetchPreviousQualitySnapshot. Content is the compact JSON core
+ *  only (buildQualitySnapshot's output), never the full human report. Same
+ *  `PUT /Memory/{id}` write shape `memory write-task-summary` already uses.
+ *  Throws on a write failure — the CLI action below is responsible for
+ *  surfacing that as a clear error, same as every other write path here. */
+async function storeQualitySnapshot(agentId, baseUrl, subject, snapshot) {
+    const memId = `${agentId}-quality-snapshot-${Date.now()}`;
+    const body = {
+        id: memId,
+        agentId,
+        content: JSON.stringify(snapshot),
+        durability: "persistent",
+        tags: ["quality-snapshot"],
+        subject,
+        type: "quality-snapshot",
+        createdAt: new Date().toISOString(),
+    };
+    const out = await api("PUT", `/Memory/${encodeURIComponent(memId)}`, body, { baseUrl });
+    if (out?.error)
+        throw new Error(String(out.error));
+    return memId;
+}
+// ─── flair quality ────────────────────────────────────────────────────────────
+program
+    .command("quality")
+    .description("Memory-quality report: embedding coverage, staleness, signal density, quiet agents, recall spot-check (read-only)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET; alias for --url)")
+    .option("--json", "Output as JSON")
+    .option("--agent <id>", "Scope per-agent metrics to one agent id (or set FLAIR_AGENT_ID); default = all agents")
+    .option("--emit", "Slice 2: snapshot this report, diff it against the previous quality-snapshot memory, and emit OrgEvents (quality.threshold_crossed / quality.regression) for any crossings/regressions found. Requires an agent identity (--agent or FLAIR_AGENT_ID) — the opt-in write boundary; without this flag `flair quality` remains fully read-only")
+    .action(async (opts) => {
+    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts);
+    const agentId = opts.agent || process.env.FLAIR_AGENT_ID || null;
+    if (opts.emit && !agentId) {
+        console.error("Error: --emit requires an agent identity. Pass --agent <id> or set FLAIR_AGENT_ID.");
+        process.exit(1);
+    }
+    // Recall spot-check needs live queries (not just /HealthDetail), so only
+    // attempt it when the instance is actually reachable — no point probing
+    // memory reads against a server fetchHealthDetail already found down.
+    const recallSpotCheckData = healthy
+        ? await fetchRecallSpotCheckData(agentId, baseUrl)
+        : { ok: false, skipReason: "instance unreachable" };
+    const report = computeQualityReport(healthy, healthData, { agentId, recallSpotCheckData });
+    // ── Slice 2: --emit is the opt-in write boundary. Everything above this
+    // point is unchanged from pre-Slice-2 behavior; everything in this block
+    // only runs when the flag is passed AND the instance is reachable (an
+    // unreachable instance has nothing to diff against and no live write
+    // target — it falls through to the existing "unreachable" exit(1) below,
+    // same as always). ──
+    let emitResult = null;
+    if (opts.emit && healthy && agentId) {
+        const subject = qualitySnapshotSubject(baseUrl);
+        const previous = await fetchPreviousQualitySnapshot(agentId, baseUrl, subject);
+        const current = buildQualitySnapshot(report);
+        const findings = diffQualitySnapshots(current, previous); // [] on a first run (previous === null)
+        emitResult = { firstRun: previous === null, emittedEvents: [], snapshotId: null, errors: [] };
+        for (const finding of findings) {
+            const published = await publishOrgEvent({
+                agentId,
+                baseUrl,
+                kind: finding.kind,
+                scope: finding.scope,
+                summary: finding.summary,
+                detail: JSON.stringify(finding.detail),
+                targetIds: finding.targetIds,
+            });
+            if (published.ok) {
+                emitResult.emittedEvents.push({ ...finding, orgEventId: published.id });
+            }
+            else {
+                emitResult.errors.push(`${finding.kind} (${finding.detail.metric}): ${published.error}`);
+            }
+        }
+        try {
+            emitResult.snapshotId = await storeQualitySnapshot(agentId, baseUrl, subject, current);
+        }
+        catch (err) {
+            emitResult.errors.push(`snapshot store failed: ${err?.message ?? String(err)}`);
+        }
+    }
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        const out = { healthy, url: baseUrl, flairVersion: __pkgVersion, ...report };
+        if (emitResult) {
+            out.emit = { firstRun: emitResult.firstRun, snapshotId: emitResult.snapshotId, errors: emitResult.errors };
+            out.emittedEvents = emitResult.emittedEvents.map((e) => ({
+                kind: e.kind,
+                scope: e.scope,
+                summary: e.summary,
+                detail: e.detail,
+                targetIds: e.targetIds,
+                orgEventId: e.orgEventId,
+            }));
+        }
+        console.log(render.asJSON(out));
+        if (!healthy)
+            process.exit(1);
+        return;
+    }
+    if (!healthy) {
+        console.log(`Flair v${__pkgVersion} — 🔴 unreachable`);
+        console.log(`  URL:  ${baseUrl}`);
+        console.log(`\n  Run: flair start  or  flair doctor`);
+        process.exit(1);
+    }
+    const scopeLabel = agentId ? ` ${render.wrap(render.c.dim, `(agent: ${agentId})`)}` : "";
+    console.log(`${render.wrap(render.c.bold, "Flair quality report")}${scopeLabel}`);
+    console.log(render.kv("URL", baseUrl));
+    // Instance health
+    console.log(`\n${render.wrap(render.c.bold, "Instance health")}`);
+    console.log(render.kv("Up", report.instance.up ? `${render.icons.ok} yes` : `${render.icons.error} no`));
+    if (report.instance.migrationsClean === null) {
+        console.log(render.kv("Migrations", `${render.icons.info} unknown ${render.wrap(render.c.dim, "(no data)")}`));
+    }
+    else if (report.instance.migrationsClean) {
+        console.log(render.kv("Migrations", `${render.icons.ok} clean`));
+    }
+    else {
+        console.log(render.kv("Migrations", `${render.icons.error} ${report.instance.haltedMigrations.length} halted/failed`));
+        for (const m of report.instance.haltedMigrations) {
+            console.log(`    ${render.icons.error} ${m.id}: ${m.state}${m.reason ? ` — ${m.reason}` : ""}`);
+        }
+    }
+    const embIcon = report.instance.embeddingsStatus === "ok" ? render.icons.ok :
+        report.instance.embeddingsStatus === "degraded" ? render.icons.error :
+            render.icons.info;
+    console.log(render.kv("Embeddings", `${embIcon} ${report.instance.embeddingsStatus} ${render.wrap(render.c.dim, `(${report.instance.embeddingsDetail})`)}`));
+    // Embedding coverage
+    if (report.embeddingCoverage) {
+        const ec = report.embeddingCoverage;
+        console.log(`\n${render.wrap(render.c.bold, "Embedding coverage")}`);
+        console.log(render.kv("Coverage", `${render.wrap(render.c.bold, `${ec.coveragePct}%`)} ${render.wrap(render.c.dim, `(${ec.withEmbeddings}/${ec.total} real, ${ec.hashFallback} hash-fallback)`)}`));
+    }
+    // Staleness
+    if (report.staleness) {
+        const st = report.staleness;
+        console.log(`\n${render.wrap(render.c.bold, "Staleness")}`);
+        console.log(render.kv("Past validTo", `${render.wrap(render.c.bold, `${st.stalePct}%`)} ${render.wrap(render.c.dim, `(${st.expired}/${st.total}, instance-wide)`)}`));
+    }
+    // Signal density
+    if (report.signalDensity) {
+        console.log(`\n${render.wrap(render.c.bold, "Signal density")} ${render.wrap(render.c.dim, "(write + citation activity — a usage pattern, not a trust signal)")}`);
+        if (agentId && report.signalDensity.perAgent.length === 0) {
+            console.log(`  ${render.icons.info} no data for agent '${agentId}'`);
+        }
+        else {
+            const showCitation = report.signalDensity.scope === "write-and-citation";
+            const cols = [
+                { label: "id", key: "id" },
+                { label: "memories", key: "memoryCount", align: "right" },
+                { label: "writes_24h", key: "writes24h", align: "right" },
+                ...(showCitation
+                    ? [
+                        { label: "citations", key: "usageCount", align: "right" },
+                        { label: "citation_rate", key: "citationRate", align: "right" },
+                    ]
+                    : []),
+                { label: "last_write", key: "lastWriteAt", format: (v) => render.relativeTime(v) },
+            ];
+            console.log(render.table(cols, report.signalDensity.perAgent));
+            if (showCitation) {
+                console.log(`  ${render.wrap(render.c.dim, "citation_rate = avg citations per memory; a low rate means \"writes exploratory content that's rarely cited\", not \"noisy\"")}`);
+            }
+            else {
+                console.log(`  ${render.wrap(render.c.dim, "citation rate not shown — server predates per-agent usageCount in /HealthDetail (see Gaps); low write volume means \"writes exploratory content\", not \"noisy\"")}`);
+            }
+        }
+    }
+    // Quiet agents
+    if (report.quietAgents) {
+        console.log(`\n${render.wrap(render.c.bold, "Quiet agents")} ${render.wrap(render.c.dim, `(no write in ${report.quietAgents.thresholdDays}+ days — an ops fact, not a trust signal)`)}`);
+        if (agentId && report.quietAgents.perAgent.length === 0) {
+            console.log(`  ${render.icons.info} no data for agent '${agentId}'`);
+        }
+        else {
+            const quiet = report.quietAgents.perAgent.filter((r) => r.quiet);
+            if (quiet.length === 0) {
+                console.log(`  ${render.icons.ok} none`);
+            }
+            else {
+                for (const r of quiet) {
+                    const label = r.daysSinceLastWrite == null ? "never written" : `quiet for ${r.daysSinceLastWrite}d`;
+                    console.log(`  ${render.icons.warn} ${r.id} — ${label}`);
+                }
+            }
+        }
+    }
+    // Dedup clusters (flair-quality Slice 1c) — an ops/health signal, not a
+    // trust judgment. Labeled with the nightly REM run that produced it, per
+    // spec, since it's only ever as fresh as the last nightly cycle.
+    if (report.dedupClusters) {
+        const dc = report.dedupClusters;
+        console.log(`\n${render.wrap(render.c.bold, "Dedup clusters")} ${render.wrap(render.c.dim, `(as of last REM run ${render.relativeTime(dc.computedAt)}, ${dc.computedAt})`)}`);
+        console.log(render.kv("Clusters", `${render.wrap(render.c.bold, String(dc.clusterCount))} ${render.wrap(render.c.dim, `(${dc.totalMemoriesInClusters} memories, largest cluster ${dc.largestClusterSize})`)}`));
+        console.log(`  ${render.wrap(render.c.dim, "an ops signal — near-duplicate memories piling up, not a trust judgment")}`);
+    }
+    // Recall spot-check (flair-quality Slice 1d) — a health SPOT-CHECK, not
+    // a benchmark or trust judgment: catches recall cratering (embeddings/
+    // index down), not a quality grade. See QualityReport['recallSpotCheck']
+    // doc for the full framing.
+    if (report.recallSpotCheck) {
+        const rc = report.recallSpotCheck;
+        console.log(`\n${render.wrap(render.c.bold, "Recall spot-check")} ${render.wrap(render.c.dim, `(agent ${rc.agentId ?? "—"}, health signal — not a benchmark)`)}`);
+        console.log(render.kv(`recall@${rc.k}`, `${render.wrap(render.c.bold, rc.recallAtK.toFixed(2))} ${render.wrap(render.c.dim, `(MRR ${rc.mrr.toFixed(2)}, ${rc.sampleSize} sampled)`)}`));
+        console.log(`  ${render.wrap(render.c.dim, "catches recall cratering (embeddings/index down) — a high score means recall is functioning, not that it's optimal")}`);
+    }
+    // Gaps
+    if (report.gaps.length > 0) {
+        console.log(`\n${render.wrap(render.c.bold, "Gaps")} ${render.wrap(render.c.dim, "(degraded or unavailable from existing read APIs)")}`);
+        for (const g of report.gaps) {
+            console.log(`  ${render.icons.info} ${g.metric}: ${g.reason}`);
+        }
+    }
+    // Events (flair-quality Slice 2 — only present when --emit was passed)
+    if (emitResult) {
+        console.log(`\n${render.wrap(render.c.bold, "Events")} ${render.wrap(render.c.dim, "(--emit: snapshot + diff against the previous quality-snapshot memory)")}`);
+        if (emitResult.firstRun) {
+            console.log(`  ${render.icons.info} first run — no prior snapshot to diff against; stored a baseline, emitted nothing`);
+        }
+        else if (emitResult.emittedEvents.length === 0) {
+            console.log(`  ${render.icons.ok} no threshold crossings or regressions since the last snapshot`);
+        }
+        else {
+            console.log(`  ${render.wrap(render.c.bold, String(emitResult.emittedEvents.length))} event(s) emitted:`);
+            for (const e of emitResult.emittedEvents) {
+                const icon = e.kind === "quality.regression" ? render.icons.warn : render.icons.info;
+                console.log(`    ${icon} [${e.kind}] ${e.summary}`);
+            }
+        }
+        if (emitResult.snapshotId) {
+            console.log(`  ${render.wrap(render.c.dim, `snapshot stored: ${emitResult.snapshotId}`)}`);
+        }
+        for (const err of emitResult.errors) {
+            console.log(`  ${render.icons.error} ${err}`);
+        }
+    }
+    console.log("");
+});
 // ─── flair session snapshot ──────────────────────────────────────────────────
 // Slice 2 of FLAIR-AGENT-CONTEXT-TIERS-B. Snapshot a
 // session jsonl + label metadata into a tar.gz under ~/.flair/snapshots/<agent>/sessions/.
@@ -12593,6 +13522,58 @@ workspace
 // Memory.write(): `${agentId}-${randomUUID()}`).
 const MAX_ORGEVENT_SUMMARY_LENGTH = 500;
 const MAX_ORGEVENT_DETAIL_LENGTH = 8000;
+/**
+ * The ONE write shape behind `flair orgevent` — signed PUT /OrgEvent/{id} —
+ * extracted so `flair quality --emit` (flair-quality Slice 2) reuses the
+ * exact same call, rather than hand-rolling a second one. Everything below
+ * mirrors what the `orgevent` command's action used to do inline: id
+ * convention (`${agentId}-${randomUUID()}`, matching flair-client's
+ * Memory.write()), the same Ed25519 signing (buildEd25519Auth), the same
+ * length guards (MAX_ORGEVENT_SUMMARY_LENGTH/MAX_ORGEVENT_DETAIL_LENGTH) so
+ * every caller — CLI flag or programmatic — gets them, and the same
+ * authorId self-declaration OrgEvent.put() verifies server-side against the
+ * signature (see the module doc above `orgevent`). Never throws — every
+ * failure mode (missing key, oversized field, non-2xx response) returns
+ * `{ ok: false, error }` for the caller to surface however fits its own UX.
+ */
+async function publishOrgEvent(params) {
+    if (params.summary.length > MAX_ORGEVENT_SUMMARY_LENGTH) {
+        return { ok: false, error: `summary exceeds ${MAX_ORGEVENT_SUMMARY_LENGTH} character limit (got ${params.summary.length})` };
+    }
+    if (params.detail && params.detail.length > MAX_ORGEVENT_DETAIL_LENGTH) {
+        return { ok: false, error: `detail exceeds ${MAX_ORGEVENT_DETAIL_LENGTH} character limit (got ${params.detail.length})` };
+    }
+    const keyPath = resolveKeyPath(params.agentId);
+    if (!keyPath) {
+        return { ok: false, error: `private key not found for agent '${params.agentId}'. Check ~/.flair/keys/ or set FLAIR_KEY_DIR.` };
+    }
+    const id = `${params.agentId}-${randomUUID()}`;
+    const auth = buildEd25519Auth(params.agentId, "PUT", `/OrgEvent/${id}`, keyPath);
+    const body = {
+        id,
+        authorId: params.agentId,
+        kind: params.kind,
+        summary: params.summary,
+        createdAt: new Date().toISOString(),
+    };
+    if (params.detail)
+        body.detail = params.detail;
+    if (params.scope)
+        body.scope = params.scope;
+    if (params.targetIds && params.targetIds.length > 0)
+        body.targetIds = params.targetIds;
+    const res = await fetch(`${params.baseUrl}/OrgEvent/${id}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        return { ok: false, error: `PUT /OrgEvent/${id} failed (${res.status}): ${text}` };
+    }
+    const data = await res.json().catch(() => null);
+    return { ok: true, id: data?.id ?? id };
+}
 program
     .command("orgevent")
     .description("Publish an org-wide coordination event attributed to your agent (PUT /OrgEvent/{id})")
@@ -12610,59 +13591,26 @@ program
         console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
         process.exit(1);
     }
-    if (opts.summary && String(opts.summary).length > MAX_ORGEVENT_SUMMARY_LENGTH) {
-        console.error(`Error: --summary exceeds ${MAX_ORGEVENT_SUMMARY_LENGTH} character limit (got ${String(opts.summary).length}).`);
-        process.exit(1);
-    }
-    if (opts.detail && String(opts.detail).length > MAX_ORGEVENT_DETAIL_LENGTH) {
-        console.error(`Error: --detail exceeds ${MAX_ORGEVENT_DETAIL_LENGTH} character limit (got ${String(opts.detail).length}).`);
-        process.exit(1);
-    }
-    const keyPath = resolveKeyPath(agentId);
-    if (!keyPath) {
-        console.error(`Error: private key not found for agent '${agentId}'. Check ~/.flair/keys/ or set FLAIR_KEY_DIR.`);
-        process.exit(1);
-    }
     // orgevent reuses --target for recipients, so the remote-URL override is
     // --target-url here (env FLAIR_TARGET still honored via resolveBaseUrl).
     const baseUrl = resolveBaseUrl({ target: opts.targetUrl, port: opts.port }).replace(/\/$/, "");
-    // id generation mirrors flair-client's Memory.write() convention
-    // (`${agentId}-${randomUUID()}`) — unique per publish, unlike OrgEvent's
-    // own (HTTP-unreachable) post() default of `${authorId}-${isoTimestamp}`,
-    // which can collide within the same millisecond.
-    const id = `${agentId}-${randomUUID()}`;
-    const auth = buildEd25519Auth(agentId, "PUT", `/OrgEvent/${id}`, keyPath);
-    // authorId IS included in the body now — OrgEvent.put() (unlike post())
-    // does not auto-attribute from the signature, it 403s any mismatch. This
-    // is a self-declaration the server verifies against the signature, not a
-    // forgeable claim.
-    const body = {
-        id,
-        authorId: agentId,
+    const targetIds = Array.isArray(opts.target) && opts.target.length > 0 ? opts.target : undefined;
+    const result = await publishOrgEvent({
+        agentId,
+        baseUrl,
         kind: opts.kind,
         summary: opts.summary,
-        createdAt: new Date().toISOString(),
-    };
-    if (opts.detail)
-        body.detail = opts.detail;
-    if (opts.scope)
-        body.scope = opts.scope;
-    if (Array.isArray(opts.target) && opts.target.length > 0)
-        body.targetIds = opts.target;
-    const res = await fetch(`${baseUrl}/OrgEvent/${id}`, {
-        method: "PUT",
-        headers: { "Content-Type": "application/json", Authorization: auth },
-        body: JSON.stringify(body),
+        detail: opts.detail,
+        scope: opts.scope,
+        targetIds,
     });
-    if (!res.ok) {
-        const text = await res.text().catch(() => "");
-        console.error(`Error: PUT /OrgEvent/${id} failed (${res.status}): ${text}`);
+    if (!result.ok) {
+        console.error(`Error: ${result.error}`);
         process.exit(1);
     }
-    const data = await res.json().catch(() => null);
-    const targets = Array.isArray(opts.target) && opts.target.length > 0 ? ` → ${opts.target.join(", ")}` : "";
+    const targets = targetIds ? ` → ${targetIds.join(", ")}` : "";
     console.log(`✓ OrgEvent published as '${agentId}': kind=${opts.kind}${targets}`);
-    console.log(`  id: ${data?.id ?? id}`);
+    console.log(`  id: ${result.id}`);
 });
 // ─── flair attention ─────────────────────────────────────────────────────────
 //