comisai 1.0.42 → 1.0.44

package/node_modules/@comis/daemon/dist/api/obs-handlers/fleet-findings.js

@@ -0,0 +1,464 @@
+import { chimericModelFromRow, DEDICATED_SCRIPT_SIGNALS, deliveryDeadletteredFromRow, flaggedPostureKeys, healthSignalLabel, multilingualFromRow, nodeBudgetExceededFromRow, pipelineAuthoringFromRow, pricingGapFromRow, sandboxDowngradeFromRow, scriptZeroHitFromRow, servedBelowConfiguredFromRow, voiceDegradedFromRow, } from "./fleet-findings-extractors.js";
+import { buildAutonomyFindings } from "./fleet-autonomy.js";
+/**
+ * TELEM-01 (Plan 173-03): the pipeline-authoring aggregate the Phase-174 gate
+ * (`pipelineAuthoringGate`) consumes — computed compute-on-read over the windowed
+ * `health_signal` rows (no persisted rollup; Open Q2 / D-AGGREGATE).
+ *
+ * The `PipelineAuthoringAggregate` type is now SINGLE-SOURCED in
+ * `@comis/observability` (Plan 173-04, MEDIUM-4) — the provisional local
+ * interface declared here at Plan 03 was deleted and this file imports the
+ * canonical type (see the top-of-file `import type`). The field NAMES + ORDER
+ * (`smallTierInvocations`, `smallTierValidRate`, `frontierValidRate`) are
+ * unchanged — the swap is structural.
+ *
+ * The small/local tier = capabilityClass "small" OR "nano" (D-TIER); frontier =
+ * "frontier". "mid" and "unknown" rows are in NEITHER cohort (they are not the
+ * comparison tiers). Rates are 0 (never NaN) when the cohort is empty.
+ *
+ * Reduce the windowed `health_signal` rows to the `PipelineAuthoringAggregate`.
+ * PURE — no I/O, no globals, no Date.now(); malformed / non-pipeline rows fold out
+ * (counted in neither cohort, never throws). Exported so Plan 04 / fleet-health.ts
+ * can feed the gate.
+ */
+export function pipelineAuthoringAggregateFromRows(rows) {
+    let smallTotal = 0;
+    let smallValid = 0;
+    let frontierTotal = 0;
+    let frontierValid = 0;
+    for (const row of rows) {
+        const parsed = pipelineAuthoringFromRow(row);
+        if (parsed === null)
+            continue;
+        if (parsed.tier === "small" || parsed.tier === "nano") {
+            smallTotal += 1;
+            if (parsed.schemaValid)
+                smallValid += 1;
+        }
+        else if (parsed.tier === "frontier") {
+            frontierTotal += 1;
+            if (parsed.schemaValid)
+                frontierValid += 1;
+        }
+        // "mid" / "unknown": counted in neither cohort (D-TIER).
+    }
+    return {
+        smallTierInvocations: smallTotal,
+        smallTierValidRate: smallTotal > 0 ? smallValid / smallTotal : 0,
+        frontierValidRate: frontierTotal > 0 ? frontierValid / frontierTotal : 0,
+    };
+}
+/**
+ * Derive `{code, detail, count, hint}` findings from the I-track rows. Counts +
+ * short codes + hints ONLY — NEVER the raw `row.message`/`row.details` body (H1 +
+ * the 159 schema is digest-only). `health_signal` rows are grouped by their
+ * closed `signal` label (so distinct signal classes are distinct findings);
+ * `model_health` / `config_posture` are category-level rollups. The OBS-01
+ * script signals get DEDICATED findings (script=/lane= grouping + named knob
+ * hints) and are excluded from the generic rollup so they are not double-reported
+ * (mirrors how KNOB-03's dedicated finding sits beside the config_posture rollup).
+ */
+/** Defensive `details` JSON parse: malformed / missing → `{}` (digest-only, never throws, never echoes a body). */
+function parseDetailsObject(details) {
+    try {
+        return details ? JSON.parse(details) : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The closed reflection admission-outcome vocabulary (OBS-3b) — off-vocabulary folds to "unknown". */
+const REFLECT_ADMISSION_OUTCOMES = new Set([
+    "admitted", "uncorroborated", "rejected_validation", "rejected_name_length",
+    "untrusted_origin", "empty_reflection", "no_successes",
+]);
+export function buildFindings(healthSignals, modelHealth, configPosture, 
+// OBS-3b (hindsight-reflection-20260626): the windowed `learning_health` rows (the reflection
+// funnel). Defaulted `[]` so the pre-OBS-3b callers/tests stay byte-identical.
+learningHealth = [], 
+// OBS-2b (reflect-obs-20260627): the windowed `memory_lifecycle` rows (the forget sweep). Defaulted
+// `[]` so the pre-OBS-2b callers/tests stay byte-identical.
+memoryLifecycle = []) {
+    const findings = [];
+    // health_signal — one finding per closed `signal` label (counts only). The
+    // OBS-01 script labels are EXCLUDED here (they get dedicated findings below).
+    const bySignal = new Map();
+    for (const row of healthSignals) {
+        const label = healthSignalLabel(row);
+        if (DEDICATED_SCRIPT_SIGNALS.has(label))
+            continue;
+        bySignal.set(label, (bySignal.get(label) ?? 0) + 1);
+    }
+    for (const [label, count] of bySignal) {
+        findings.push({
+            code: `health_signal:${label}`,
+            detail: `${count} ${label} health signal(s) in the window`,
+            count,
+            hint: "run `comis explain` on an affected session; inspect the recurring health WARNs",
+        });
+    }
+    // OBS-01 (Phase 180): dedicated script_zero_hit finding — one per
+    // (scriptClass, lane) group, reading "N non-Latin zero-hit searches
+    // (script=X, lane=Y)". Counts + closed enums only; the hint names the repair
+    // that backfills the normalized trigram twins (history backfill).
+    const byScriptLane = new Map();
+    for (const row of healthSignals) {
+        const parsed = scriptZeroHitFromRow(row);
+        if (parsed === null)
+            continue;
+        const key = `${parsed.scriptClass} ${parsed.lane}`;
+        byScriptLane.set(key, (byScriptLane.get(key) ?? 0) + 1);
+    }
+    for (const [key, count] of byScriptLane) {
+        const [scriptClass, lane] = key.split(" ");
+        findings.push({
+            code: "script_zero_hit",
+            detail: `${count} non-Latin zero-hit searches (script=${scriptClass}, lane=${lane})`,
+            count,
+            hint: "non-Latin search found nothing on a cleanly-executed lane; rebuild the normalized trigram twins with `comis doctor --repair` (history backfill), then `comis explain` an affected session",
+        });
+    }
+    // OBS-01 (Phase 180): dedicated summary_language_mismatch finding — a single
+    // rollup count whose hint names the exact knob (a non-Latin chunk summarized in
+    // Latin; visibility only, never gated). Counts only, no source/summary body.
+    const mismatchCount = healthSignals.filter((row) => healthSignalLabel(row) === "summary_language_mismatch").length;
+    if (mismatchCount > 0) {
+        findings.push({
+            code: "summary_language_mismatch",
+            detail: `${mismatchCount} summary(ies) whose dominant script diverged from the source (non-Latin source → Latin summary)`,
+            count: mismatchCount,
+            hint: "summaries are drifting to Latin for non-Latin sources; set contextEngine.compaction.strongerSummarizerModel to a model that preserves the source language (visibility only — not gated)",
+        });
+    }
+    // GENQ-01: dedicated generation_quality finding — the memory-generation analog of
+    // summary_language_mismatch over the consolidation/reasoning/user-representation
+    // passes (the F-ML1 regression class made a fleet count instead of an offline
+    // probe). Counts only, no source/generated body; visibility only, never gated.
+    const genQualityCount = healthSignals.filter((row) => healthSignalLabel(row) === "generation_quality").length;
+    if (genQualityCount > 0) {
+        findings.push({
+            code: "generation_quality",
+            detail: `${genQualityCount} memory-generation pass(es) whose output diverged from the source (non-Latin source → Latin output, empty, or unparseable)`,
+            count: genQualityCount,
+            hint: "a memory-generation pass (consolidation/reasoning/user-representation) is producing low-quality output for non-Latin sources; the memory-pipeline model is too weak — configure a stronger memory model or pin providers.entries.<id>.capabilities.capabilityClass to frontier/mid (the R6 memory-ops override). Visibility only — not gated",
+        });
+    }
+    // TELEM-01 (Plan 173-03): dedicated pipeline_authoring finding — the HEADLINE
+    // metric is the small-model pipeline-authoring failure rate = (small-tier rows
+    // where schemaValid===false) / (small-tier rows total) over the window (D-TIER:
+    // small|nano = the small tier). Counts + a static hint ONLY (no source/generated
+    // graph body — the pipelineAuthoringFromRow parser reads only the closed tier +
+    // the schemaValid boolean). Fires only when smallTotal > 0 (no finding on zero
+    // small-tier traffic — mirrors the GENQ-01/voice if-guards). The reducer above is
+    // the same compute-on-read fold; here we re-walk for the invalid COUNT the finding
+    // names.
+    //
+    // METRIC BOUNDARY (Phase 173 review WR-02): the denominator counts every
+    // CONTRACT-PARSE-REACHABLE authoring invocation. graph.define emits
+    // schemaValid:false on BOTH a strict-contract (GraphDefineContract) parse
+    // rejection AND a buildGraphInput parse/validate throw; graph.execute (a loose
+    // z.record contract that never rejects) emits on the buildGraphInput throw.
+    // EXCLUDED — and so NOT in either cohort — are the bespoke pre-Zod guards
+    // (graph.define's "Missing required parameter: nodes" empty-call check and
+    // graph.execute's agent-to-agent-disabled policy gate): an empty/garbage call
+    // or a policy rejection is not an "authoring attempt." This is a deliberate,
+    // documented boundary, not a silent undercount.
+    let smallTotal = 0;
+    let smallInvalid = 0;
+    for (const row of healthSignals) {
+        const parsed = pipelineAuthoringFromRow(row);
+        if (parsed === null)
+            continue;
+        if (parsed.tier === "small" || parsed.tier === "nano") {
+            smallTotal += 1;
+            if (!parsed.schemaValid)
+                smallInvalid += 1;
+        }
+    }
+    if (smallTotal > 0) {
+        const pct = ((smallInvalid / smallTotal) * 100).toFixed(1);
+        findings.push({
+            code: "pipeline_authoring",
+            detail: `${smallInvalid}/${smallTotal} small-tier pipeline authorings invalid (rate ${pct}%)`,
+            count: smallInvalid,
+            hint: "small/local models are failing to author valid pipeline DAGs; this is the Phase-174 (small-model-authorable DAGs) gate metric — review before enabling orchestration.authoring.*",
+        });
+    }
+    // ORCH-OBS (orchestration-observability): dedicated sandbox_downgrade_refused
+    // finding — the count of fail-closed sub-agent spawn refusals + the violated
+    // sandbox dimensions (closed enum labels). A spawn refusal is fail-closed working,
+    // but it means an agent was configured to spawn a LESS-confined child (a
+    // misconfiguration or an escalation attempt) — an operator must see it. Counts +
+    // closed dimension labels + a STATIC hint ONLY (never a path/host/uid value — the
+    // row never carried them). Zero-traffic guard (the voice_health if-pattern).
+    let sandboxRefusedCount = 0;
+    const sandboxDimCounts = new Map();
+    for (const row of healthSignals) {
+        const parsed = sandboxDowngradeFromRow(row);
+        if (parsed === null)
+            continue;
+        sandboxRefusedCount += 1;
+        for (const dim of parsed.dimensions) {
+            sandboxDimCounts.set(dim, (sandboxDimCounts.get(dim) ?? 0) + 1);
+        }
+    }
+    if (sandboxRefusedCount > 0) {
+        const dims = [...sandboxDimCounts.entries()]
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .map(([d]) => d);
+        findings.push({
+            code: "sandbox_downgrade_refused",
+            detail: dims.length > 0
+                ? `${sandboxRefusedCount} sub-agent spawn(s) refused for sandbox downgrade (dimension(s): ${dims.join(", ")})`
+                : `${sandboxRefusedCount} sub-agent spawn(s) refused for sandbox downgrade`,
+            count: sandboxRefusedCount,
+            hint: "a sub-agent was configured LESS confined than its spawner on the named dimension(s); align the child's skills.execSandbox posture with (or stricter than) the parent's, or remove the offending agent-to-agent spawn. run `comis explain` on the spawner's session",
+        });
+    }
+    // ORCH-OBS: dedicated delivery_deadlettered finding — the count of sub-agent
+    // completions PERMANENTLY DROPPED (self-healing delivery exhausted retries, or an
+    // immediate permanent failure). This is a SILENT degradation today (the graph
+    // reports completed while a node's result never reached the parent). Counts + the
+    // transient/permanent split ONLY — never a runId, an announcement body, or an error
+    // string. Zero-traffic guard.
+    let deadletterCount = 0;
+    let deadletterTransient = 0;
+    for (const row of healthSignals) {
+        const parsed = deliveryDeadletteredFromRow(row);
+        if (parsed === null)
+            continue;
+        deadletterCount += 1;
+        if (parsed.transient)
+            deadletterTransient += 1;
+    }
+    if (deadletterCount > 0) {
+        const permanent = deadletterCount - deadletterTransient;
+        findings.push({
+            code: "delivery_deadlettered",
+            detail: `${deadletterCount} sub-agent completion(s) dead-lettered (dropped): ${deadletterTransient} after retries, ${permanent} permanent`,
+            count: deadletterCount,
+            hint: "a sub-agent result was permanently dropped before reaching its parent (the graph still reports completed); run `comis explain` on the affected session and check the delivery channel health / retry budget (security.agentToAgent.delivery)",
+        });
+    }
+    // ORCH-OBS: dedicated node_budget_exceeded finding — the count of per-node token
+    // budget breaches + the DOMINANT cap source (which knob bound the node). Counts +
+    // the closed capSource label + a hint NAMING all three knobs ONLY (the per-node
+    // token numbers are per-incident — on the node error string + the WARN + `comis
+    // explain`). Zero-traffic guard.
+    let budgetCount = 0;
+    const capSourceCounts = new Map();
+    for (const row of healthSignals) {
+        const parsed = nodeBudgetExceededFromRow(row);
+        if (parsed === null)
+            continue;
+        budgetCount += 1;
+        capSourceCounts.set(parsed.capSource, (capSourceCounts.get(parsed.capSource) ?? 0) + 1);
+    }
+    if (budgetCount > 0) {
+        const topSource = [...capSourceCounts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0];
+        findings.push({
+            code: "node_budget_exceeded",
+            detail: topSource !== undefined
+                ? `${budgetCount} node(s) exceeded their token budget (dominant cap source: ${topSource})`
+                : `${budgetCount} node(s) exceeded their token budget`,
+            count: budgetCount,
+            hint: "graph nodes are being cut off by their token budget; raise the binding knob — the node's own `tokenBudget`, the operator default `security.agentToAgent.tokenBudget`, or the graph `budget.maxTokens` (inherit-share). run `comis explain` for the per-node numbers",
+        });
+    }
+    // FLEET-01 (Phase 220-03): the three dedicated autonomy findings (durable_orphaned
+    // / autonomy_revoked / autonomy_killed; kill separable from revoke) — extracted to
+    // the `fleet-autonomy.ts` sibling (the obs-handlers 500-line subdir cap). Each has
+    // its own zero-traffic guard inside the helper; the returned findings inherit the
+    // FLEET_FINDINGS_CAP bound + the highest-count-first sort below.
+    findings.push(...buildAutonomyFindings(healthSignals));
+    // OBS-04 (Phase 196): dedicated voice_health finding — the degraded STT/TTS
+    // turn count + the DOMINANT voice errorKind (the closed domain SttErrorKind),
+    // rolled up from the `voice_degraded` health_signal rows the daemon voice obs
+    // emits on a transcription/synthesis failure. Counts + a closed errorKind label
+    // + a STATIC hint ONLY — NEVER a raw provider message body or a secret (the H1
+    // no-body rule; safe to paste). Mirrors the `model_health` if-guard + the
+    // script-signal dedicated-grouping pattern. Beside model_health/config_posture.
+    let voiceDegradedCount = 0;
+    const voiceKindCounts = new Map();
+    for (const row of healthSignals) {
+        const parsed = voiceDegradedFromRow(row);
+        if (parsed === null)
+            continue;
+        voiceDegradedCount += 1;
+        if (parsed.errorKind !== undefined) {
+            voiceKindCounts.set(parsed.errorKind, (voiceKindCounts.get(parsed.errorKind) ?? 0) + 1);
+        }
+    }
+    if (voiceDegradedCount > 0) {
+        // The dominant errorKind: highest count, lexicographic tie-break (deterministic).
+        const topKind = [...voiceKindCounts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0];
+        findings.push({
+            code: "voice_health",
+            detail: topKind !== undefined
+                ? `${voiceDegradedCount} degraded STT/TTS turn(s); top errorKind ${topKind}`
+                : `${voiceDegradedCount} degraded STT/TTS turn(s)`,
+            count: voiceDegradedCount,
+            hint: "run `comis explain` on an affected voice session; for model_load_failed/model_download_failed check the whisper model cache + disk + the local engine probe (a keyless engine), or set the provider's audio API key for auth_required",
+        });
+    }
+    // The generic "provider degradation" rollup counts ONLY degraded rows
+    // (severity "warning" — recordModelHealth marks a row "warning" exactly when
+    // the embedding provider is absent at boot, the primary degraded-recall
+    // cause). The once-per-boot HEALTHY snapshot (severity "info", embedding
+    // present) is NOT degradation; counting every row inflated the fleet view —
+    // a keyless daemon that had rebooted N times showed "N provider-degradation
+    // signal(s)" from N healthy boots (BENIGN_*_REASONS: routine events must not
+    // inflate warning counts). The multilingual advisory below is STANDING STATE
+    // read from the latest row and stays severity-independent.
+    const degradedModelHealth = modelHealth.filter((r) => r.severity === "warning");
+    if (degradedModelHealth.length > 0) {
+        findings.push({
+            code: "model_health",
+            detail: `${degradedModelHealth.length} model-health signal(s) (provider degradation)`,
+            count: degradedModelHealth.length,
+            hint: "check provider status + rate-limit headroom; confirm the model/provider config (a 'warning' row means the embedding provider was absent at boot — recall falls back to the FTS floor)",
+        });
+    }
+    if (modelHealth.length > 0) {
+        // EMB-01: multilingual advisory read from the LATEST model_health row
+        // (STANDING STATE, not a reboot count — mirror the KNOB-03 latest-row pattern
+        // below, NOT the generic count above; Pitfall 4). Counts/codes/hints only; the
+        // hint names the DOC-01 recommendation + the I4 FTS floor. Advisory ONLY — no
+        // recall/search behavior gates on these flags anywhere (I4).
+        let latestModelHealth = modelHealth[0];
+        for (const row of modelHealth) {
+            if (row.timestamp > latestModelHealth.timestamp)
+                latestModelHealth = row;
+        }
+        const ml = multilingualFromRow(latestModelHealth);
+        if (ml.embedding === false || ml.embedding === "unknown") {
+            findings.push({
+                code: "model_health:embedder_not_multilingual",
+                detail: `embedder not multilingual (${ml.embedding === "unknown" ? "id-inferred unknown" : "declared/known English"}): non-Latin semantic recall coverage degraded`,
+                count: 1,
+                hint: "set embedding.multilingual or switch to bge-m3 / multilingual-e5 / LaBSE; the FTS trigram floor still carries recall (advisory only, not gated)",
+            });
+        }
+        if (ml.reranker === false || ml.reranker === "unknown") {
+            findings.push({
+                code: "model_health:reranker_not_multilingual",
+                detail: `reranker not multilingual (${ml.reranker === "unknown" ? "id-inferred unknown" : "known English"}): non-Latin recall ORDERING degraded`,
+                count: 1,
+                hint: "switch the reranker to bge-reranker-v2-m3 (the default); the FTS trigram floor still carries recall (advisory only, not gated)",
+            });
+        }
+    }
+    if (configPosture.length > 0) {
+        // The LATEST posture row (max timestamp — scan, never assume query order). Posture is
+        // STANDING STATE, not cumulative: an old insecure/under-served boot superseded by a
+        // healthy one must not keep flagging the fleet. Used for BOTH the named-keys rollup and
+        // the dedicated served-below / chimeric findings below.
+        let latest = configPosture[0];
+        for (const row of configPosture) {
+            if (row.timestamp > latest.timestamp)
+                latest = row;
+        }
+        // T1.3 (F6): name the SPECIFIC flagged keys (closed labels only) so an operator does
+        // not have to grep daemon.log to learn WHICH knob is off (gateway.tls, CANARY_SECRET…).
+        const flaggedKeys = flaggedPostureKeys(latest);
+        findings.push({
+            code: "config_posture",
+            detail: flaggedKeys.length > 0
+                ? `${configPosture.length} config-posture signal(s) (insecure or drifted config) — flagged: ${flaggedKeys.join(", ")}`
+                : `${configPosture.length} config-posture signal(s) (insecure or drifted config)`,
+            count: configPosture.length,
+            hint: "reconcile the named flagged keys against the secure baseline (served-below + chimeric model have their own findings)",
+        });
+        // KNOB-03: dedicated served-below-configured finding from the latest posture row.
+        const latestCount = servedBelowConfiguredFromRow(latest);
+        if (latestCount > 0) {
+            findings.push({
+                code: "config_posture:served_below_configured",
+                detail: `Ollama served context window below configured for ${latestCount} provider(s)`,
+                count: latestCount,
+                hint: "set OLLAMA_CONTEXT_LENGTH / Modelfile 'PARAMETER num_ctx' to the configured window (config-yaml served-window section); run `comis explain` on a served-bound session for the numbers",
+            });
+        }
+        // RESOLVE-01: dedicated chimeric-provider/model finding from the SAME latest
+        // posture row. A NATIVE provider (anthropic/openai/google) paired with a foreign
+        // model family resolves a phantom ModelProfile (incident ffe11736) — name it.
+        const chimeraCount = chimericModelFromRow(latest);
+        if (chimeraCount > 0) {
+            findings.push({
+                code: "config_posture:chimeric_model",
+                detail: `${chimeraCount} agent(s) configured with a native provider + a foreign model family (chimera — resolves a phantom capability profile)`,
+                count: chimeraCount,
+                hint: "align agents.<id>.provider with the model family (e.g. provider:anthropic ⇒ a claude model; for a qwen/llama model use an ollama/openrouter provider), or set the model id explicitly under the right provider",
+            });
+        }
+        // SPEND-05: dedicated pricing-gap finding from the SAME latest posture row.
+        // Configured agents burning tokens on remote-unknown-priced models (a NATIVE
+        // provider with no catalog rate — the ffe11736 fail-open where spend is silently
+        // under-counted as $0). Surfaces the kill-switch's pricing coverage so an operator
+        // sees how much spend the ceiling cannot account for. Counts + remediation only.
+        const pricingGapCount = pricingGapFromRow(latest);
+        if (pricingGapCount > 0) {
+            findings.push({
+                code: "config_posture:pricing_gap",
+                detail: `${pricingGapCount} agent(s) burning tokens on remote-unknown-priced models — spend is under-counted for these (honest $0 only applies to local/free providers)`,
+                count: pricingGapCount,
+                hint: "set the model id under a priced provider, or use a local/free provider where $0 is correct; run `comis explain` on an unknown-priced session for the pricing_state",
+            });
+        }
+    }
+    // OBS-3b (hindsight-reflection-20260626): dedicated learning_health finding — the reflection funnel
+    // rolled up over the window. The daemon-wide "is reflection learning / why-0-admitted" posture, beside
+    // model_health / config_posture. Counts + the LATEST closed admissionOutcome verdict (standing state,
+    // max-timestamp scan — never assume query order) + summed admitted/untrustedDrops ONLY (the
+    // reflect:funnel event is content-free — never a doc body; every details field parsed defensively). A
+    // non-admit window is NOT a fault (the anti-poison gates working), so the hint says so explicitly.
+    if (learningHealth.length > 0) {
+        let latest = learningHealth[0];
+        for (const row of learningHealth) {
+            if (row.timestamp > latest.timestamp)
+                latest = row;
+        }
+        let admittedSum = 0;
+        let untrustedSum = 0;
+        for (const row of learningHealth) {
+            const d = parseDetailsObject(row.details);
+            if (typeof d.admitted === "number")
+                admittedSum += d.admitted;
+            if (typeof d.untrustedDrops === "number")
+                untrustedSum += d.untrustedDrops;
+        }
+        const ld = parseDetailsObject(latest.details);
+        const latestOutcome = typeof ld.admissionOutcome === "string" && REFLECT_ADMISSION_OUTCOMES.has(ld.admissionOutcome)
+            ? ld.admissionOutcome
+            : "unknown";
+        findings.push({
+            code: "learning_health",
+            detail: `${learningHealth.length} reflection run(s) in the window; latest outcome=${latestOutcome}, admitted=${admittedSum}, untrustedDrops=${untrustedSum}`,
+            count: learningHealth.length,
+            hint: 'run `cron.runs jobName "Reflection"` for the per-run funnel; admitted=0 with untrustedDrops/uncorroborated is the anti-poison gates WORKING (not a fault); admitted=0 DESPITE genuine corroboration ⇒ a topicKey under-merge — `comis explain` the reflection run',
+        });
+    }
+    // OBS-2b (reflect-obs-20260627): the dedicated memory_lifecycle finding — the forget sweep rolled up
+    // over the window (the parity of learning_health for the forget half). Counts ONLY (summed evicted/
+    // demoted across the window's sweeps; every details field parsed defensively). A sweep that evicted
+    // nothing (no eviction-candidates) is NOT a fault — healthy maintenance — so the hint says so.
+    if (memoryLifecycle.length > 0) {
+        let evictedSum = 0;
+        let demotedSum = 0;
+        for (const row of memoryLifecycle) {
+            const d = parseDetailsObject(row.details);
+            if (typeof d.evicted === "number")
+                evictedSum += d.evicted;
+            if (typeof d.demoted === "number")
+                demotedSum += d.demoted;
+        }
+        findings.push({
+            code: "memory_lifecycle",
+            detail: `${memoryLifecycle.length} forget sweep(s) in the window; evicted=${evictedSum}, demoted=${demotedSum}`,
+            count: memoryLifecycle.length,
+            hint: 'run `cron.runs jobName "Memory lifecycle"` for the per-sweep counts; evicted=0 is usually healthy (no corroborated-wrong / dormant candidates) — NOT a fault. Eviction is gated by learning.forget + the INV-4 exemptions (pinned/high-proof/system survive).',
+        });
+    }
+    // Deterministic order: highest-count first, then code asc (stable tie-break).
+    return findings.sort((a, b) => b.count - a.count || a.code.localeCompare(b.code));
+}

package/node_modules/@comis/daemon/dist/api/obs-handlers/fleet-health.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `obs.fleet.health` RPC handler — the cross-session FleetHealthReport assembler
+ * (Phase 161 R2 + H1). The SIBLING of `obs-explain.ts`: `obs.explain` post-mortems
+ * ONE session; this rolls up a WINDOW of sessions into a bounded, deterministic,
+ * digest-only fleet triage.
+ *
+ * The assembler is a READ FAN-IN over four EXISTING, bounded, soft-fail sources
+ * (the `assembleIncidentReportFromSources` shape — that reads 4 sources too):
+ *
+ *   A1 + A2 — `ObservabilityStore.aggregateSessionsInWindow(sinceMs)` ->
+ *             `reduceFleetWindow` (pure cross-session reduce; synthetic excluded).
+ *   A3      — `readSessionIndexWindow(dataDir, sinceMs, nowMs)` (multi-day
+ *             activity aggregate; `daysRead`/`daysMissing` feed the coverage
+ *             honesty block). `nowMs` is the SAME injected instant as `sinceMs`,
+ *             so the A3 day-key window tracks the injected clock (WR-01).
+ *   I-track — `queryDiagnostics({ category })` over the Phase-160
+ *             `health_signal` / `model_health` / `config_posture` rows (counts +
+ *             labels only — the 160 rows already dropped raw bodies).
+ *
+ * Determinism (X3): the report root carries NO wall-clock field — there is ONE
+ * clock read (the injected `ClockPort.now()`), captured once and threaded as
+ * BOTH the window start (`sinceHours -> sinceMs`) AND the A3 reader's window
+ * upper bound (`nowMs`). NEVER `Date.now()`/`new Date()` downstream (the globals
+ * gate). Same injected clock + same data -> byte-identical report — true even
+ * when the injected instant differs from real wall-clock (WR-01).
+ *
+ * Bounded (digest-only): `findings[]` is capped at {@link FLEET_FINDINGS_CAP}
+ * (highest-count-first), recording the drop in `truncations[]` — the
+ * `obs-explain-bound.ts` cap-then-record pattern, lighter because the 159 schema
+ * + A2's top-3 cap already bound the rest.
+ *
+ * H1 dual-layer admin gate: the contract is `scopes:["admin"]` (gateway-router
+ * primary) AND the handler re-checks `_trustLevel === "admin"` (defense-in-depth),
+ * cloned verbatim from `obs-explain.ts`. `stripInternalFields` runs BEFORE the
+ * contract parse so `_trustLevel` can never be smuggled into the parsed params or
+ * the report.
+ *
+ * The heuristic registry + bounding pass are co-located here (KISS — start
+ * co-located, split to `fleet-health-heuristics.ts` / `fleet-health-bound.ts`
+ * only if the 800L file-size cap is approached; the obs-explain split is the
+ * precedent).
+ *
+ * @module
+ */
+import { type FleetHealthReport, type ClockPort, type DurableRunPort } from "@comis/core";
+import { type ObservabilityStore } from "@comis/memory";
+import type { RpcHandler } from "../types.js";
+import { type ObsHandlerDeps } from "./obs-helpers.js";
+/**
+ * Assemble the cross-session {@link FleetHealthReport} from the four bounded
+ * sources. NEITHER an admin check NOR a contract parse — it takes an
+ * ALREADY-AUTHORIZED window and runs the deterministic read fan-in, so it can be
+ * reached under daemon authority by a caller with its own authorization boundary
+ * (the admin RPC handler keeps its admin gate; the Phase-161-02 MCP closure relies
+ * on the per-client allowlist + the digest-only report).
+ *
+ * @param deps.obsStore - the observability store (A1/A2 + I-track). Soft-fail:
+ *   absent yields an empty (but self-evidently empty, via coverage) report.
+ * @param deps.dataDir - the data dir for the A3 session-index reader.
+ * @param deps.clock - the injected ClockPort. The ONE clock read (for `sinceMs`);
+ *   NEVER `Date.now()` (the globals gate).
+ * @param deps.durableRuns - FLEET-01/02/04 (Phase 220-03): the durable-run store
+ *   for the autonomy block's run counts (`countByStatus(sinceMs)`). Soft-fail (the
+ *   `obsStore?` precedent): absent ⇒ the autonomy block is honestly OMITTED (the
+ *   daemon-less offline CLI / a non-durability boot). NO extra clock read — reuses
+ *   the ONE `sinceMs` window.
+ * @param sinceHours - the window size (the caller applies the 24h default). A
+ *   non-finite or non-positive value is clamped to {@link DEFAULT_WINDOW_HOURS}
+ *   here (IN-01 defense-in-depth) so a contract-bypassing caller cannot produce
+ *   a `-Infinity`/`NaN` window bound.
+ */
+export declare function assembleFleetHealthReport(deps: {
+    obsStore?: ObservabilityStore;
+    dataDir: string;
+    clock: ClockPort;
+    durableRuns?: DurableRunPort;
+}, sinceHours: number): Promise<FleetHealthReport>;
+/**
+ * Bind the `obs.fleet.health` handler — the H1 admin gate + strip-before-parse +
+ * the read fan-in. COMPUTED-KEY form (`[ObsFleetHealthContract.method]`) is
+ * MANDATORY — `api-contracts-bidirectional.test.ts` only recognizes the computed
+ * key, not a `"obs.fleet.health":` string literal.
+ *
+ * @param deps - the shared obs-handler deps; `deps.clock` is populated by
+ *   `buildRpcDispatchDeps` in daemon.ts (Phase 161-02). The handler asserts
+ *   `deps.clock!` because 161-02 always populates it.
+ */
+export declare function bindFleetHealthHandlers(deps: ObsHandlerDeps): Record<string, RpcHandler>;