harnery 0.36.0 → 0.37.0

package/dist/core/storage/query.js

@@ -65,6 +65,57 @@ export function rotationFollowCursor(family) {
         active_offset: existsSync(active) ? regularFileStat(active).size : 0,
     };
 }
+/**
+ * Read the newest complete records from one family's active segment without
+ * walking sealed history. Dashboard-style live views need a cheap bounded
+ * snapshot; the full `queryLogs` surface remains the historical query path.
+ */
+export function readRecentActiveLogs(family, options) {
+    if (!Number.isSafeInteger(options.max_records) ||
+        options.max_records <= 0 ||
+        !Number.isSafeInteger(options.max_bytes) ||
+        options.max_bytes <= 0) {
+        throw new Error("recent log read requires positive budgets");
+    }
+    const active = join(familyLogDirectory(family), "active.jsonl");
+    if (!existsSync(active))
+        return { records: [], bytes_examined: 0, truncated: false };
+    const opened = openRegularNoFollow(active);
+    try {
+        const size = fstatSync(opened.fd).size;
+        const start = Math.max(0, size - options.max_bytes);
+        const length = size - start;
+        if (length === 0)
+            return { records: [], bytes_examined: 0, truncated: false };
+        const buffer = Buffer.allocUnsafe(length);
+        let consumed = 0;
+        while (consumed < length) {
+            const count = readSync(opened.fd, buffer, consumed, length - consumed, start + consumed);
+            if (count === 0)
+                break;
+            consumed += count;
+        }
+        assertOpenFileIdentity(active, opened.fd, opened.parent);
+        const text = buffer.subarray(0, consumed).toString("utf8");
+        let lines = text.split("\n");
+        // A bounded tail can begin in the middle of a record. The active writer
+        // can also leave a not-yet-complete final record while this snapshot reads.
+        if (start > 0)
+            lines = lines.slice(1);
+        if (!text.endsWith("\n"))
+            lines = lines.slice(0, -1);
+        const records = lines.filter((line) => line.trim()).map(parseLogRecord);
+        const truncated = start > 0 || records.length > options.max_records;
+        return {
+            records: records.slice(-options.max_records),
+            bytes_examined: consumed,
+            truncated,
+        };
+    }
+    finally {
+        closeSync(opened.fd);
+    }
+}
 export async function readLogFollow(family, cursor, maxBytes) {
     if (cursor.family_id !== family.id)
         throw new Error("follow cursor family mismatch");

package/dist/core/supervisor/activity.d.ts

@@ -0,0 +1,4 @@
+import { type SupervisorActivitySnapshot } from "./contract.js";
+/** Read a bounded, generation-bound activity projection without loading Event Ledger V3. */
+export declare function collectSupervisorActivitySnapshot(coordRoot: string, now?: Date): SupervisorActivitySnapshot;
+//# sourceMappingURL=activity.d.ts.map

package/dist/core/supervisor/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/activity.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,0BAA0B,EAGhC,MAAM,eAAe,CAAC;AAoBvB,4FAA4F;AAC5F,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,MAAM,EACjB,GAAG,OAAa,GACf,0BAA0B,CAoF5B"}

package/dist/core/supervisor/activity.js

@@ -0,0 +1,141 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { SUPERVISOR_ACTIVITY_SCHEMA_VERSION, SUPERVISOR_DIAGNOSTIC_LIMITS, SUPERVISOR_FINDING_POLICY, } from "./contract.js";
+/** Read a bounded, generation-bound activity projection without loading Event Ledger V3. */
+export function collectSupervisorActivitySnapshot(coordRoot, now = new Date()) {
+    const observedAt = now.toISOString();
+    const directory = join(resolve(coordRoot), ".harnery", "active");
+    if (!existsSync(directory))
+        return unavailable(observedAt, "activity-projection-missing");
+    const candidates = [];
+    let rejected = 0;
+    try {
+        for (const entry of readdirSync(directory)) {
+            if (!/^[A-Za-z0-9_-]{1,128}\.json$/.test(entry)) {
+                rejected += 1;
+                continue;
+            }
+            const path = join(directory, entry);
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink() ||
+                !stat.isFile() ||
+                stat.size < 2 ||
+                stat.size > SUPERVISOR_FINDING_POLICY.max_activity_file_bytes) {
+                rejected += 1;
+                continue;
+            }
+            candidates.push({ name: entry.slice(0, -5), path, bytes: stat.size, mtimeMs: stat.mtimeMs });
+        }
+    }
+    catch {
+        return unavailable(observedAt, "activity-projection-read-failed", "error");
+    }
+    candidates.sort((left, right) => right.mtimeMs - left.mtimeMs || left.name.localeCompare(right.name));
+    const entries = [];
+    let totalBytes = 0;
+    let stale = 0;
+    for (const candidate of candidates) {
+        if (entries.length >= SUPERVISOR_DIAGNOSTIC_LIMITS.max_activity_entries ||
+            totalBytes + candidate.bytes > SUPERVISOR_FINDING_POLICY.max_activity_total_bytes) {
+            rejected += 1;
+            continue;
+        }
+        totalBytes += candidate.bytes;
+        let cache;
+        try {
+            cache = JSON.parse(readFileSync(candidate.path, "utf8"));
+        }
+        catch {
+            rejected += 1;
+            continue;
+        }
+        if (!validCache(cache, candidate.name)) {
+            rejected += 1;
+            continue;
+        }
+        const age = now.getTime() - Date.parse(cache.last_heartbeat);
+        if (!Number.isFinite(age) ||
+            age < -30_000 ||
+            age > SUPERVISOR_FINDING_POLICY.activity_freshness_ms) {
+            stale += 1;
+            continue;
+        }
+        entries.push(activityEntry(cache));
+    }
+    const state = rejected > 0 ? "partial" : "supported";
+    return {
+        schema_version: SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+        observed_at: observedAt,
+        max_entries: SUPERVISOR_DIAGNOSTIC_LIMITS.max_activity_entries,
+        entries: entries.sort((left, right) => left.scope_id.localeCompare(right.scope_id)),
+        omitted_entry_count: rejected + stale,
+        capability: {
+            source_kind: "coordination.activity-projection",
+            state,
+            ...(state === "partial" ? { reason_code: "bounded-cache-rejection" } : {}),
+            ...(rejected + stale > 0
+                ? { detail: `${rejected} invalid or over-budget and ${stale} stale activity rows omitted.` }
+                : {}),
+        },
+    };
+}
+function validCache(cache, fileId) {
+    return (cache.schema_version === 2 &&
+        cache.instance_id === fileId &&
+        typeof cache.session_id === "string" &&
+        cache.session_id.length > 0 &&
+        isActivity(cache.activity) &&
+        isTaskState(cache.task_state) &&
+        typeof cache.last_heartbeat === "string" &&
+        typeof cache.v3_instance_id === "string" &&
+        cache.v3_instance_id.startsWith("inst_") &&
+        typeof cache.v3_generation_id === "string" &&
+        cache.v3_generation_id.startsWith("gen_"));
+}
+function activityEntry(cache) {
+    const source = activitySource(cache);
+    return {
+        scope_kind: "agent",
+        scope_id: cache.instance_id,
+        session_id: cache.session_id,
+        declared_activity: cache.activity,
+        task_state: cache.task_state,
+        observed_at: cache.last_heartbeat,
+        source,
+    };
+}
+function activitySource(cache) {
+    const sourceId = `${cache.v3_instance_id}:${cache.v3_generation_id}`;
+    return {
+        id: `src_${digest(`coordination.activity-projection\u0000${sourceId}\u0000${cache.last_heartbeat}`).slice(0, 24)}`,
+        source_kind: "coordination.activity-projection",
+        source_id: sourceId,
+        observed_at: cache.last_heartbeat,
+        schema_version: SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+        capability: "supported",
+    };
+}
+function unavailable(observedAt, reasonCode, state = "unsupported") {
+    return {
+        schema_version: SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+        observed_at: observedAt,
+        max_entries: SUPERVISOR_DIAGNOSTIC_LIMITS.max_activity_entries,
+        entries: [],
+        omitted_entry_count: 0,
+        capability: {
+            source_kind: "coordination.activity-projection",
+            state,
+            reason_code: reasonCode,
+        },
+    };
+}
+function isActivity(value) {
+    return value === "working" || value === "needs_input" || value === "idle" || value === "unknown";
+}
+function isTaskState(value) {
+    return value === "active" || value === "blocked" || value === "done";
+}
+function digest(value) {
+    return createHash("sha256").update(value).digest("hex");
+}

package/dist/core/supervisor/contract.d.ts

@@ -0,0 +1,268 @@
+import type { ResourceProcessGroup } from "../resources/contract.js";
+import type { HarneryLogRecordV1 } from "../storage/jsonl.js";
+export declare const SUPERVISOR_STATUS_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_SNAPSHOT_SCHEMA_VERSION: 2;
+export declare const SUPERVISOR_HISTORY_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_FINDING_SCHEMA_VERSION: 2;
+export declare const SUPERVISOR_ACTIVITY_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_TIMELINE_SCHEMA_VERSION: 2;
+export declare const SUPERVISOR_EXPLANATION_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_LOG_FEED_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_CONSUMER_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_DIAGNOSTIC_LIMITS: {
+    readonly max_findings: 100;
+    readonly max_active_findings: 32;
+    readonly max_evidence_per_finding: 32;
+    readonly max_timeline_entries: 160;
+    readonly max_explanation_items: 24;
+    readonly max_capabilities: 16;
+    readonly max_activity_entries: 64;
+    readonly max_bundle_files: 32;
+    readonly max_bundle_bytes: number;
+    readonly max_summary_chars: 500;
+    readonly max_excerpt_chars: 2000;
+};
+export declare const SUPERVISOR_FINDING_POLICY: {
+    readonly episode_gap_ms: number;
+    readonly activity_freshness_ms: number;
+    readonly max_activity_file_bytes: number;
+    readonly max_activity_total_bytes: number;
+};
+export declare const SUPERVISOR_RESOURCE_BUDGET: {
+    readonly max_rss_bytes: number;
+    readonly max_cycle_duration_ms: 50;
+    readonly max_startup_duration_ms: 2000;
+    readonly max_cache_bytes: number;
+    readonly max_regression_ratio: 1.2;
+};
+export type SupervisorProcessState = "starting" | "running" | "stopping" | "stopped" | "error";
+export interface SupervisorServiceStatusRecord {
+    schema_version: typeof SUPERVISOR_STATUS_SCHEMA_VERSION;
+    pid: number;
+    start_token?: string;
+    host: string;
+    nonce: string;
+    state: SupervisorProcessState;
+    started_at: string;
+    heartbeat_at: string;
+    interval_ms: number;
+    keep_alive: boolean;
+    idle_exit_ms: number;
+    cycle_count: number;
+    last_cycle_at?: string;
+    last_cycle_duration_ms?: number;
+    idle_since?: string;
+    last_error_code?: string;
+    stopped_at?: string;
+}
+export interface SupervisorStatus {
+    running: boolean;
+    stale: boolean;
+    record?: SupervisorServiceStatusRecord;
+    status_path: string;
+    snapshot_path: string;
+}
+export interface SupervisorConsumerRecord {
+    schema_version: typeof SUPERVISOR_CONSUMER_SCHEMA_VERSION;
+    id: string;
+    pid: number;
+    start_token?: string;
+    registered_at: string;
+}
+export type ObservedServiceState = "running" | "stopped" | "stale" | "unknown";
+export interface ObservedServiceHealth {
+    id: "supervisor" | "semantic-reader" | "presence-relay" | "governor" | "dashboard";
+    state: ObservedServiceState;
+    pid?: number;
+    started_at?: string;
+    heartbeat_at?: string;
+    reason?: string;
+}
+export interface ObservedHookHealth {
+    pid: number;
+    owner_id: string;
+    state: string;
+    age_seconds: number;
+    cpu_percent: number | null;
+    rss_bytes: number;
+    command: string;
+    long_running: boolean;
+    evidence: "validated-owner-and-exact-entrypoint";
+}
+export interface SupervisorHistoryPoint {
+    sampled_at: string;
+    machine: {
+        cpu_percent: number | null;
+        memory_percent: number | null;
+        memory_used_bytes: number | null;
+        swap_used_bytes: number | null;
+        process_count: number;
+    };
+    groups: readonly ResourceProcessGroup[];
+}
+export interface SupervisorHistory {
+    schema_version: typeof SUPERVISOR_HISTORY_SCHEMA_VERSION;
+    interval_ms: number;
+    max_points: number;
+    points: readonly SupervisorHistoryPoint[];
+}
+export type SupervisorCapabilityState = "supported" | "partial" | "unsupported" | "error" | "expired" | "malformed" | "redacted";
+export type SupervisorFindingSeverity = "info" | "warning" | "critical";
+export type SupervisorFindingState = "opened" | "resolved";
+export interface SupervisorCapability {
+    source_kind: string;
+    state: SupervisorCapabilityState;
+    reason_code?: string;
+    detail?: string;
+}
+export interface SupervisorSourceReference {
+    id: string;
+    source_kind: string;
+    source_id: string;
+    observed_at: string;
+    record_id?: string;
+    sequence?: number;
+    schema_version?: number;
+    capability: SupervisorCapabilityState;
+}
+export interface SupervisorFindingEvidence {
+    id: string;
+    source: SupervisorSourceReference;
+    summary: string;
+    observed_value?: number;
+    unit?: "percent" | "bytes" | "milliseconds" | "seconds" | "processes" | "count";
+}
+export interface SupervisorFindingAttribution {
+    state: "attributed" | "unattributed";
+    owner_kind?: "agent" | "service";
+    owner_id?: string;
+    owner_root_pid?: number;
+    reason_code?: "no-validated-process-anchor";
+}
+export interface SupervisorFindingWorkloadContext {
+    relationship: "active-work" | "unexpected-idle-growth" | "unknown";
+    declared_activity: "working" | "needs_input" | "idle" | "unknown";
+    task_state: "active" | "blocked" | "done" | "unknown";
+    observed_at: string;
+    source: SupervisorSourceReference;
+}
+export interface SupervisorFinding {
+    schema_version: typeof SUPERVISOR_FINDING_SCHEMA_VERSION;
+    id: string;
+    fingerprint: string;
+    source_kind: string;
+    finding_kind: string;
+    severity: SupervisorFindingSeverity;
+    state: SupervisorFindingState;
+    scope_kind: string;
+    scope_id: string;
+    summary: string;
+    opened_at: string;
+    observed_at: string;
+    resolved_at?: string;
+    occurrence_count: number;
+    peak_observed_value?: number;
+    peak_observed_at?: string;
+    peak_unit?: SupervisorFindingEvidence["unit"];
+    attribution?: SupervisorFindingAttribution;
+    workload_context?: SupervisorFindingWorkloadContext;
+    primary_source: SupervisorSourceReference;
+    evidence: readonly SupervisorFindingEvidence[];
+    capabilities: readonly SupervisorCapability[];
+}
+export interface SupervisorDeclaredActivity {
+    scope_kind: "agent";
+    scope_id: string;
+    session_id: string;
+    declared_activity: "working" | "needs_input" | "idle" | "unknown";
+    task_state: "active" | "blocked" | "done";
+    observed_at: string;
+    source: SupervisorSourceReference;
+}
+export interface SupervisorActivitySnapshot {
+    schema_version: typeof SUPERVISOR_ACTIVITY_SCHEMA_VERSION;
+    observed_at: string;
+    max_entries: number;
+    entries: readonly SupervisorDeclaredActivity[];
+    omitted_entry_count: number;
+    capability: SupervisorCapability;
+}
+export interface SupervisorFindings {
+    schema_version: typeof SUPERVISOR_FINDING_SCHEMA_VERSION;
+    max_findings: number;
+    active: readonly SupervisorFinding[];
+    transitions: readonly SupervisorFinding[];
+}
+export type SupervisorTimelineRelation = "opened" | "observed" | "related" | "resolved" | "capability" | "missing";
+export interface SupervisorTimelineEntry {
+    id: string;
+    occurred_at: string;
+    first_occurred_at: string;
+    last_occurred_at: string;
+    occurrence_count: number;
+    relation: SupervisorTimelineRelation;
+    summary: string;
+    source: SupervisorSourceReference;
+    evidence_id?: string;
+}
+export interface SupervisorTimeline {
+    schema_version: typeof SUPERVISOR_TIMELINE_SCHEMA_VERSION;
+    finding_id: string;
+    start_at: string;
+    end_at: string;
+    max_entries: number;
+    omitted_entries: number;
+    compacted_entries: number;
+    entries: readonly SupervisorTimelineEntry[];
+    capabilities: readonly SupervisorCapability[];
+}
+export interface SupervisorExplanationStatement {
+    id: string;
+    code: string;
+    summary: string;
+    evidence_ids: readonly string[];
+}
+export interface SupervisorPossibleExplanation extends SupervisorExplanationStatement {
+    confidence: "low" | "medium" | "high";
+    evidence_against_ids: readonly string[];
+}
+export interface SupervisorFindingExplanation {
+    schema_version: typeof SUPERVISOR_EXPLANATION_SCHEMA_VERSION;
+    finding_id: string;
+    generated_at: string;
+    observed: readonly SupervisorExplanationStatement[];
+    related: readonly SupervisorExplanationStatement[];
+    possible: readonly SupervisorPossibleExplanation[];
+    missing_capabilities: readonly SupervisorCapability[];
+}
+export interface SupervisorLogLane {
+    family_id: string;
+    owner: string;
+    storage_class: "operational-log" | "debug-log";
+    records: readonly HarneryLogRecordV1[];
+    truncated: boolean;
+    error?: string;
+}
+export interface SupervisorLogFeed {
+    schema_version: typeof SUPERVISOR_LOG_FEED_SCHEMA_VERSION;
+    captured_at: string;
+    sequence: number;
+    lanes: readonly SupervisorLogLane[];
+    total_records: number;
+    unavailable_families: number;
+}
+export interface SupervisorSnapshot {
+    schema_version: typeof SUPERVISOR_SNAPSHOT_SCHEMA_VERSION;
+    sampled_at: string;
+    sequence: number;
+    collector_duration_ms: number;
+    resource_sample_duration_ms: number;
+    services: readonly ObservedServiceHealth[];
+    hooks: readonly ObservedHookHealth[];
+    active_finding_count: number;
+    history_point_count: number;
+    log_record_count: number;
+    live_consumer_count: number;
+    attributed_agent_count: number;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/core/supervisor/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/contract.ts"],"names":[],"mappings":"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"}

package/dist/core/supervisor/contract.js

@@ -0,0 +1,35 @@
+export const SUPERVISOR_STATUS_SCHEMA_VERSION = 1;
+export const SUPERVISOR_SNAPSHOT_SCHEMA_VERSION = 2;
+export const SUPERVISOR_HISTORY_SCHEMA_VERSION = 1;
+export const SUPERVISOR_FINDING_SCHEMA_VERSION = 2;
+export const SUPERVISOR_ACTIVITY_SCHEMA_VERSION = 1;
+export const SUPERVISOR_TIMELINE_SCHEMA_VERSION = 2;
+export const SUPERVISOR_EXPLANATION_SCHEMA_VERSION = 1;
+export const SUPERVISOR_LOG_FEED_SCHEMA_VERSION = 1;
+export const SUPERVISOR_CONSUMER_SCHEMA_VERSION = 1;
+export const SUPERVISOR_DIAGNOSTIC_LIMITS = {
+    max_findings: 100,
+    max_active_findings: 32,
+    max_evidence_per_finding: 32,
+    max_timeline_entries: 160,
+    max_explanation_items: 24,
+    max_capabilities: 16,
+    max_activity_entries: 64,
+    max_bundle_files: 32,
+    max_bundle_bytes: 8 * 1_024 * 1_024,
+    max_summary_chars: 500,
+    max_excerpt_chars: 2_000,
+};
+export const SUPERVISOR_FINDING_POLICY = {
+    episode_gap_ms: 5 * 60_000,
+    activity_freshness_ms: 2 * 60_000,
+    max_activity_file_bytes: 64 * 1_024,
+    max_activity_total_bytes: 512 * 1_024,
+};
+export const SUPERVISOR_RESOURCE_BUDGET = {
+    max_rss_bytes: 128 * 1_024 * 1_024,
+    max_cycle_duration_ms: 50,
+    max_startup_duration_ms: 2_000,
+    max_cache_bytes: 8 * 1_024 * 1_024,
+    max_regression_ratio: 1.2,
+};

package/dist/core/supervisor/explanations.d.ts

@@ -0,0 +1,4 @@
+import { type SupervisorFinding, type SupervisorFindingExplanation } from "./contract.js";
+/** Build evidence-linked statements without presenting correlation as causation. */
+export declare function explainSupervisorFinding(finding: SupervisorFinding): SupervisorFindingExplanation;
+//# sourceMappingURL=explanations.d.ts.map

package/dist/core/supervisor/explanations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explanations.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/explanations.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,4BAA4B,EAElC,MAAM,eAAe,CAAC;AAEvB,oFAAoF;AACpF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,iBAAiB,GAAG,4BAA4B,CAiBjG"}

package/dist/core/supervisor/explanations.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { SUPERVISOR_DIAGNOSTIC_LIMITS, SUPERVISOR_EXPLANATION_SCHEMA_VERSION, } from "./contract.js";
+/** Build evidence-linked statements without presenting correlation as causation. */
+export function explainSupervisorFinding(finding) {
+    const observed = finding.evidence.map((evidence) => statement("observed.source", evidence.summary, [evidence.id]));
+    const related = relatedStatements(finding);
+    const possible = possibleStatements(finding);
+    return {
+        schema_version: SUPERVISOR_EXPLANATION_SCHEMA_VERSION,
+        finding_id: finding.id,
+        generated_at: finding.observed_at,
+        observed: observed.slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_explanation_items),
+        related: related.slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_explanation_items),
+        possible: possible.slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_explanation_items),
+        missing_capabilities: finding.capabilities
+            .filter((capability) => capability.state !== "supported")
+            .slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_capabilities),
+    };
+}
+function relatedStatements(finding) {
+    const sources = new Set(finding.evidence.map((evidence) => evidence.source.source_kind));
+    if (sources.size < 2)
+        return [];
+    return [
+        statement("related.multi-source", `${sources.size} independent source kinds recorded related observations in this finding window.`, finding.evidence.map((evidence) => evidence.id)),
+    ];
+}
+function possibleStatements(finding) {
+    const evidenceIds = finding.evidence.map((evidence) => evidence.id);
+    const possible = [];
+    if (finding.finding_kind.includes("memory")) {
+        possible.push({
+            ...statement("possible.memory-retention-or-workload", "A growing workload, retained objects, or operating-system caching could explain the memory observation; this evidence does not distinguish them.", evidenceIds),
+            confidence: "low",
+            evidence_against_ids: [],
+        });
+    }
+    else if (finding.finding_kind.includes("process-pressure")) {
+        possible.push({
+            ...statement("possible.concurrent-work", "Concurrent local work could explain the process count; the finding does not establish which activity caused it.", evidenceIds),
+            confidence: "low",
+            evidence_against_ids: [],
+        });
+    }
+    else if (finding.finding_kind === "hook.long-running") {
+        possible.push({
+            ...statement("possible.hook-stall", "The hook may be waiting on I/O or blocked work, but elapsed time alone cannot identify the cause.", evidenceIds),
+            confidence: "low",
+            evidence_against_ids: [],
+        });
+    }
+    else if (finding.finding_kind === "coordination.ledger-diagnostic") {
+        possible.push({
+            ...statement("possible.ledger-write-or-read-boundary", "A producer write or reader validation boundary may explain the ledger diagnostic; inspect the referenced V3 record before attributing a cause.", evidenceIds),
+            confidence: "low",
+            evidence_against_ids: [],
+        });
+    }
+    return possible;
+}
+function statement(code, summary, evidenceIds) {
+    return {
+        id: `ex_${createHash("sha256")
+            .update(`${code}\u0000${summary}\u0000${evidenceIds.join(",")}`)
+            .digest("hex")
+            .slice(0, 24)}`,
+        code,
+        summary: summary.slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_summary_chars),
+        evidence_ids: [...evidenceIds].slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_evidence_per_finding),
+    };
+}

package/dist/core/supervisor/findings.d.ts

@@ -0,0 +1,20 @@
+import type { CoordinationHealthSnapshot } from "../agents/health.js";
+import type { ResourceSnapshot } from "../resources/contract.js";
+import { type ObservedHookHealth, type ObservedServiceHealth, type SupervisorActivitySnapshot, type SupervisorFinding, type SupervisorFindings, type SupervisorHistory, type SupervisorLogFeed } from "./contract.js";
+import type { SupervisorHookHealth } from "./hook-health.js";
+export interface SupervisorFindingEvaluationInput {
+    previous?: SupervisorFindings;
+    resource: ResourceSnapshot;
+    services: readonly ObservedServiceHealth[];
+    hooks: readonly ObservedHookHealth[];
+    history: SupervisorHistory;
+    logFeed: SupervisorLogFeed;
+    hookHealth?: SupervisorHookHealth;
+    coordination?: CoordinationHealthSnapshot;
+    activity?: SupervisorActivitySnapshot;
+    now?: Date;
+}
+/** Pure deterministic evaluator used by the live supervisor and replay. */
+export declare function evaluateSupervisorFindings(input: Omit<SupervisorFindingEvaluationInput, "previous">): readonly SupervisorFinding[];
+export declare function updateSupervisorFindings(input: SupervisorFindingEvaluationInput): SupervisorFindings;
+//# sourceMappingURL=findings.d.ts.map

package/dist/core/supervisor/findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/findings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAI1B,KAAK,0BAA0B,EAE/B,KAAK,iBAAiB,EAItB,KAAK,kBAAkB,EAEvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AA8B7D,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC3C,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,YAAY,CAAC,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,EAAE,0BAA0B,CAAC;IACtC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,2EAA2E;AAC3E,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,IAAI,CAAC,gCAAgC,EAAE,UAAU,CAAC,GACxD,SAAS,iBAAiB,EAAE,CAE9B;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,gCAAgC,GACtC,kBAAkB,CAwEpB"}