harnery 0.36.0 → 0.37.0

package/dist/core/supervisor/findings.js

@@ -0,0 +1,399 @@
+import { createHash } from "node:crypto";
+import { SUPERVISOR_DIAGNOSTIC_LIMITS, SUPERVISOR_FINDING_POLICY, SUPERVISOR_FINDING_SCHEMA_VERSION, } from "./contract.js";
+import { evaluateHookHealthAlerts } from "./hook-health-alerts.js";
+const GIB = 1_024 * 1_024 * 1_024;
+const MIB = 1_024 * 1_024;
+const MACHINE_CPU_THRESHOLD = 90;
+const MACHINE_MEMORY_THRESHOLD = 85;
+const MACHINE_SWAP_THRESHOLD = 75;
+const COLLECTOR_CPU_THRESHOLD_MS = 50;
+const PROCESS_MEMORY_THRESHOLD = GIB;
+const GROUP_MEMORY_THRESHOLD = 2 * GIB;
+const OWNER_PROCESS_THRESHOLD = 50;
+const MEMORY_GROWTH_MIN_BYTES = 256 * MIB;
+const MEMORY_GROWTH_RATIO = 1.3;
+const MEMORY_GROWTH_WINDOW_MS = 5 * 60_000;
+/** Pure deterministic evaluator used by the live supervisor and replay. */
+export function evaluateSupervisorFindings(input) {
+    return updateSupervisorFindings(input).active;
+}
+export function updateSupervisorFindings(input) {
+    const observedAt = (input.now ?? new Date(input.resource.sampled_at)).toISOString();
+    const previous = validFindings(input.previous)
+        ? input.previous
+        : {
+            schema_version: SUPERVISOR_FINDING_SCHEMA_VERSION,
+            max_findings: SUPERVISOR_DIAGNOSTIC_LIMITS.max_findings,
+            active: [],
+            transitions: [],
+        };
+    const candidates = evaluateCandidates(input)
+        .sort((left, right) => severityRank(right.severity) - severityRank(left.severity))
+        .slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_active_findings);
+    const priorActive = new Map(previous.active.map((entry) => [entry.fingerprint, entry]));
+    const current = new Set();
+    const active = [];
+    const transitions = new Map(previous.transitions.map((entry) => [entry.id, entry]));
+    for (const candidate of candidates) {
+        const fingerprint = findingFingerprint(candidate);
+        current.add(fingerprint);
+        const prior = priorActive.get(fingerprint) ?? recentResolved(previous, fingerprint, observedAt);
+        const openedAt = prior?.opened_at ?? candidate.primary_source.observed_at;
+        const occurrenceCount = prior
+            ? prior.state === "resolved"
+                ? prior.occurrence_count + 1
+                : prior.occurrence_count
+            : 1;
+        const peak = peakEvidence(prior, candidate.evidence, observedAt);
+        const finding = {
+            schema_version: SUPERVISOR_FINDING_SCHEMA_VERSION,
+            id: deterministicId("find", `${fingerprint}\u0000${openedAt}`),
+            fingerprint,
+            source_kind: candidate.source_kind,
+            finding_kind: candidate.finding_kind,
+            severity: candidate.severity,
+            state: "opened",
+            scope_kind: candidate.scope_kind,
+            scope_id: candidate.scope_id,
+            summary: candidate.summary,
+            opened_at: openedAt,
+            observed_at: observedAt,
+            occurrence_count: occurrenceCount,
+            ...peak,
+            ...(candidate.attribution ? { attribution: candidate.attribution } : {}),
+            ...(candidate.workload_context ? { workload_context: candidate.workload_context } : {}),
+            primary_source: candidate.primary_source,
+            evidence: candidate.evidence.slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_evidence_per_finding),
+            capabilities: boundCapabilities(candidate.capabilities),
+        };
+        active.push(finding);
+        transitions.set(finding.id, finding);
+    }
+    for (const prior of priorActive.values()) {
+        if (current.has(prior.fingerprint))
+            continue;
+        transitions.set(prior.id, {
+            ...prior,
+            state: "resolved",
+            observed_at: observedAt,
+            resolved_at: observedAt,
+        });
+    }
+    return {
+        schema_version: SUPERVISOR_FINDING_SCHEMA_VERSION,
+        max_findings: SUPERVISOR_DIAGNOSTIC_LIMITS.max_findings,
+        active,
+        transitions: [...transitions.values()]
+            .sort((left, right) => left.observed_at.localeCompare(right.observed_at))
+            .slice(-SUPERVISOR_DIAGNOSTIC_LIMITS.max_findings),
+    };
+}
+function evaluateCandidates(input) {
+    const out = [];
+    const resourceCapability = {
+        source_kind: "resource.snapshot",
+        state: input.resource.support.state,
+        ...(input.resource.support.reason
+            ? { reason_code: "sampler-degraded", detail: input.resource.support.reason }
+            : {}),
+    };
+    const source = resourceSource(input.resource, resourceCapability.state);
+    const addMachine = (findingKind, severity, summary, value, unit) => out.push(candidate(findingKind, severity, "machine", "local", summary, source, value, unit, [
+        resourceCapability,
+    ]));
+    const machine = input.resource.machine;
+    if (resourceCapability.state !== "supported") {
+        out.push(capabilityCandidate(resourceCapability, source));
+    }
+    if ((machine.cpu_percent ?? 0) >= MACHINE_CPU_THRESHOLD)
+        addMachine("machine.cpu-pressure", "warning", `Machine CPU is ${machine.cpu_percent}%.`, machine.cpu_percent, "percent");
+    if ((machine.memory_percent ?? 0) >= MACHINE_MEMORY_THRESHOLD)
+        addMachine("machine.memory-pressure", "critical", `Machine memory is ${machine.memory_percent}%.`, machine.memory_percent, "percent");
+    const swapPercent = machine.swap_total_bytes && machine.swap_used_bytes !== null
+        ? round1((machine.swap_used_bytes / machine.swap_total_bytes) * 100)
+        : null;
+    if ((swapPercent ?? 0) >= MACHINE_SWAP_THRESHOLD)
+        addMachine("machine.swap-pressure", "warning", `Machine swap is ${swapPercent}% used.`, swapPercent, "percent");
+    if (input.resource.collector_cpu_ms >= COLLECTOR_CPU_THRESHOLD_MS)
+        out.push(candidate("supervisor.collector-overhead", "warning", "service", "supervisor", `Supervisor resource collection used ${input.resource.collector_cpu_ms} ms of CPU.`, source, input.resource.collector_cpu_ms, "milliseconds", [resourceCapability]));
+    for (const service of input.services.filter((entry) => entry.state === "stale").slice(0, 5)) {
+        const serviceSource = stableSource("service.health", service.id, service.heartbeat_at ?? input.resource.sampled_at, "supported");
+        out.push(candidate("service.stale", "warning", "service", service.id, serviceStaleSummary(service), serviceSource, undefined, undefined, [{ source_kind: "service.health", state: "supported" }]));
+    }
+    for (const hook of input.hooks.filter((entry) => entry.long_running).slice(0, 5)) {
+        const hookSource = stableSource("hook.process", `${hook.owner_id}:${hook.pid}`, input.resource.sampled_at, "supported");
+        out.push(candidate("hook.long-running", "warning", "hook", `${hook.owner_id}:${hook.pid}`, `Hook process ${hook.pid} has run for ${hook.age_seconds} seconds.`, hookSource, hook.age_seconds, "seconds", [{ source_kind: "hook.process", state: "supported" }]));
+    }
+    for (const process of input.resource.processes
+        .filter((entry) => entry.rss_bytes >= PROCESS_MEMORY_THRESHOLD)
+        .slice(0, 5))
+        out.push(candidate("process.memory-pressure", "critical", "process", process.start_id, `Process ${process.pid} uses ${process.rss_bytes} resident bytes.`, resourceSource(input.resource, resourceCapability.state, process.start_id), process.rss_bytes, "bytes", [resourceCapability], processAttribution(process)));
+    for (const group of input.resource.groups
+        .filter((entry) => entry.rss_bytes >= GROUP_MEMORY_THRESHOLD)
+        .slice(0, 5))
+        out.push(candidate("group.memory-pressure", "critical", group.kind, group.id, `${groupLabel(group)} uses ${group.rss_bytes} resident bytes.`, source, group.rss_bytes, "bytes", [resourceCapability], groupAttribution(group)));
+    for (const group of input.resource.groups
+        .filter((entry) => entry.process_count >= OWNER_PROCESS_THRESHOLD)
+        .slice(0, 5))
+        out.push(candidate("group.process-pressure", "warning", group.kind, group.id, `${groupLabel(group)} owns ${group.process_count} visible processes.`, source, group.process_count, "processes", [resourceCapability], groupAttribution(group)));
+    out.push(...memoryGrowthCandidates(input.resource, input.history, resourceCapability, input.activity));
+    if (input.logFeed.unavailable_families > 0) {
+        const logCapability = {
+            source_kind: "log.feed",
+            state: "partial",
+            reason_code: "families-unavailable",
+            detail: `${input.logFeed.unavailable_families} log families were unavailable.`,
+        };
+        out.push(capabilityCandidate(logCapability, stableSource("log.feed", "supervisor-log-feed", input.logFeed.captured_at, logCapability.state, undefined, input.logFeed.schema_version)));
+    }
+    if (input.hookHealth) {
+        const hookCapability = {
+            source_kind: input.hookHealth.capability.source_kind,
+            state: input.hookHealth.capability.state === "unavailable"
+                ? "error"
+                : input.hookHealth.capability.state,
+            ...(input.hookHealth.capability.reason
+                ? {
+                    reason_code: input.hookHealth.capability.reason,
+                    detail: input.hookHealth.capability.reason,
+                }
+                : {}),
+        };
+        for (const alert of evaluateHookHealthAlerts(input.hookHealth)) {
+            const alertSource = stableSource("hook.terminal-log", alert.source.id, alert.source.observed_at, hookCapability.state, alert.source.id, input.hookHealth.schema_version);
+            out.push(candidate(alert.finding_kind, alert.severity, "hook", alert.scope_id, alert.summary, alertSource, alert.observed_value, alert.unit, [hookCapability], alert.owner_id
+                ? {
+                    state: "attributed",
+                    owner_kind: "agent",
+                    owner_id: alert.owner_id,
+                }
+                : { state: "unattributed", reason_code: "no-validated-process-anchor" }));
+        }
+    }
+    if (input.coordination) {
+        const coordination = input.coordination;
+        if (coordination.capability.state !== "supported") {
+            out.push(capabilityCandidate(coordination.capability, stableSource(coordination.capability.source_kind, coordination.capability.reason_code ?? coordination.capability.state, coordination.observed_at, coordination.capability.state)));
+        }
+        for (const diagnostic of coordination.diagnostics.slice(0, 5)) {
+            const diagnosticSource = stableSource("coordination.v3", diagnostic.event_id ?? `${diagnostic.segment_ordinal}:${diagnostic.byte_offset}`, coordination.observed_at, coordination.capability.state, diagnostic.event_id);
+            out.push(candidate("coordination.ledger-diagnostic", "warning", "ledger", diagnostic.code, `Event ledger reported ${diagnostic.code}.`, diagnosticSource, 1, "count", [coordination.capability]));
+        }
+    }
+    return out;
+}
+function capabilityCandidate(capability, source) {
+    return candidate("source.capability-degraded", "info", "source", capability.source_kind, `${capability.source_kind} capability is ${capability.state}${capability.reason_code ? ` (${capability.reason_code})` : ""}.`, source, undefined, undefined, [capability]);
+}
+function memoryGrowthCandidates(resource, history, capability, activity) {
+    const newestAt = Date.parse(resource.sampled_at);
+    const baseline = history.points.find((point) => newestAt - Date.parse(point.sampled_at) <= MEMORY_GROWTH_WINDOW_MS);
+    if (!baseline || newestAt - Date.parse(baseline.sampled_at) < 60_000)
+        return [];
+    const priorByKey = new Map(baseline.groups.map((group) => [groupKey(group), group]));
+    return resource.groups
+        .flatMap((group) => {
+        const prior = priorByKey.get(groupKey(group));
+        if (!prior || prior.rss_bytes <= 0)
+            return [];
+        const delta = group.rss_bytes - prior.rss_bytes;
+        if (delta < MEMORY_GROWTH_MIN_BYTES ||
+            group.rss_bytes / prior.rss_bytes < MEMORY_GROWTH_RATIO)
+            return [];
+        return [
+            memoryGrowthCandidate(group, activity, "resource.memory-growth", `${groupLabel(group)} grew by ${delta} resident bytes since ${baseline.sampled_at}.`, resourceSource(resource, capability.state), delta, capability),
+        ];
+    })
+        .slice(0, 5);
+}
+function memoryGrowthCandidate(group, activity, findingKind, summary, source, delta, resourceCapability) {
+    const workload = workloadContext(group, activity, source.observed_at);
+    const severity = workload.context.relationship === "unexpected-idle-growth" ? "critical" : "warning";
+    const result = candidate(findingKind, severity, group.kind, group.id, summary, source, delta, "bytes", [resourceCapability, workload.capability], groupAttribution(group), workload.context);
+    if (workload.evidence)
+        result.evidence.push(workload.evidence);
+    return result;
+}
+function workloadContext(group, activity, observedAt) {
+    const capability = activity?.capability ?? {
+        source_kind: "coordination.activity-projection",
+        state: "unsupported",
+        reason_code: "activity-projection-not-captured",
+    };
+    const matched = group.kind === "agent"
+        ? activity?.entries.find((entry) => entry.scope_id === group.id)
+        : undefined;
+    if (!matched) {
+        return {
+            context: {
+                relationship: "unknown",
+                declared_activity: "unknown",
+                task_state: "unknown",
+                observed_at: activity?.observed_at ?? observedAt,
+                source: stableSource("coordination.activity-projection", group.kind === "agent" ? group.id : "not-applicable", activity?.observed_at ?? observedAt, capability.state, undefined, activity?.schema_version),
+            },
+            capability,
+        };
+    }
+    const relationship = matched.declared_activity === "working" && matched.task_state === "active"
+        ? "active-work"
+        : matched.declared_activity === "unknown"
+            ? "unknown"
+            : "unexpected-idle-growth";
+    const summary = `Agent declared ${matched.declared_activity} with task state ${matched.task_state}.`;
+    return {
+        context: {
+            relationship,
+            declared_activity: matched.declared_activity,
+            task_state: matched.task_state,
+            observed_at: matched.observed_at,
+            source: matched.source,
+        },
+        capability,
+        evidence: {
+            id: deterministicId("ev", `${findingKindKey(group)}\u0000${matched.source.id}`),
+            source: matched.source,
+            summary,
+        },
+    };
+}
+function findingKindKey(group) {
+    return `resource.memory-growth\u0000${group.kind}\u0000${group.id}`;
+}
+function processAttribution(process) {
+    if ((process.owner_kind === "agent" || process.owner_kind === "service") &&
+        process.owner_id &&
+        process.owner_root_pid !== null) {
+        return {
+            state: "attributed",
+            owner_kind: process.owner_kind,
+            owner_id: process.owner_id,
+            owner_root_pid: process.owner_root_pid,
+        };
+    }
+    return { state: "unattributed", reason_code: "no-validated-process-anchor" };
+}
+function groupAttribution(group) {
+    if (group.kind === "agent" || group.kind === "service") {
+        return {
+            state: "attributed",
+            owner_kind: group.kind,
+            owner_id: group.id,
+            ...(group.root_pids[0] !== undefined ? { owner_root_pid: group.root_pids[0] } : {}),
+        };
+    }
+    return { state: "unattributed", reason_code: "no-validated-process-anchor" };
+}
+function serviceStaleSummary(service) {
+    if (service.reason === "recorded-running-process-missing")
+        return `${service.id} was recorded running, but its process is no longer present.`;
+    if (service.reason === "remote-heartbeat-expired")
+        return `${service.id} has an expired remote heartbeat.`;
+    if (service.reason === "supervisor-reported-error")
+        return `${service.id} reported an error.`;
+    return `${service.id} has stale liveness evidence.`;
+}
+function candidate(findingKind, severity, scopeKind, scopeId, summary, source, observedValue, unit, capabilities, attribution, workloadContext) {
+    const evidence = {
+        id: deterministicId("ev", `${findingKind}\u0000${scopeKind}\u0000${scopeId}\u0000${source.id}`),
+        source,
+        summary: summary.slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_summary_chars),
+        ...(observedValue !== undefined ? { observed_value: observedValue } : {}),
+        ...(unit ? { unit } : {}),
+    };
+    return {
+        source_kind: source.source_kind,
+        finding_kind: findingKind,
+        severity,
+        scope_kind: scopeKind,
+        scope_id: scopeId,
+        summary: evidence.summary,
+        primary_source: source,
+        evidence: [evidence],
+        capabilities,
+        ...(attribution ? { attribution } : {}),
+        ...(workloadContext ? { workload_context: workloadContext } : {}),
+    };
+}
+function resourceSource(resource, capability, recordId) {
+    return stableSource("resource.snapshot", `${resource.platform}:${resource.namespace}`, resource.sampled_at, capability, recordId, resource.schema_version);
+}
+function stableSource(sourceKind, sourceId, observedAt, capability, recordId, schemaVersion) {
+    return {
+        id: deterministicId("src", `${sourceKind}\u0000${sourceId}\u0000${recordId ?? ""}\u0000${observedAt}`),
+        source_kind: sourceKind,
+        source_id: sourceId,
+        observed_at: observedAt,
+        ...(recordId ? { record_id: recordId } : {}),
+        ...(schemaVersion !== undefined ? { schema_version: schemaVersion } : {}),
+        capability,
+    };
+}
+function recentResolved(findings, fingerprint, observedAt) {
+    const observedMs = Date.parse(observedAt);
+    return findings.transitions
+        .filter((entry) => entry.fingerprint === fingerprint &&
+        entry.state === "resolved" &&
+        entry.resolved_at !== undefined &&
+        observedMs - Date.parse(entry.resolved_at) >= 0 &&
+        observedMs - Date.parse(entry.resolved_at) <= SUPERVISOR_FINDING_POLICY.episode_gap_ms)
+        .sort((left, right) => (right.resolved_at ?? "").localeCompare(left.resolved_at ?? ""))[0];
+}
+function peakEvidence(prior, evidence, observedAt) {
+    const current = evidence
+        .filter((entry) => entry.observed_value !== undefined)
+        .sort((left, right) => right.observed_value - left.observed_value)[0];
+    if (prior?.peak_observed_value !== undefined &&
+        (!current || prior.peak_observed_value >= current.observed_value)) {
+        return {
+            peak_observed_value: prior.peak_observed_value,
+            ...(prior.peak_observed_at ? { peak_observed_at: prior.peak_observed_at } : {}),
+            ...(prior.peak_unit ? { peak_unit: prior.peak_unit } : {}),
+        };
+    }
+    return current
+        ? {
+            peak_observed_value: current.observed_value,
+            peak_observed_at: current.source.observed_at || observedAt,
+            ...(current.unit ? { peak_unit: current.unit } : {}),
+        }
+        : {};
+}
+function findingFingerprint(candidate) {
+    return digest([
+        candidate.source_kind,
+        candidate.finding_kind,
+        candidate.scope_kind,
+        candidate.scope_id,
+        candidate.primary_source.source_id,
+    ].join("\u0000")).slice(0, 32);
+}
+function deterministicId(prefix, value) {
+    return `${prefix}_${digest(value).slice(0, 24)}`;
+}
+function digest(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function validFindings(value) {
+    return (value?.schema_version === SUPERVISOR_FINDING_SCHEMA_VERSION &&
+        Array.isArray(value.active) &&
+        Array.isArray(value.transitions));
+}
+function boundCapabilities(capabilities) {
+    const unique = new Map(capabilities.map((entry) => [entry.source_kind, entry]));
+    return [...unique.values()].slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_capabilities);
+}
+function groupKey(group) {
+    return `${group.kind}:${group.id}`;
+}
+function groupLabel(group) {
+    return group.kind === "unattributed"
+        ? "Unattributed processes"
+        : `${group.kind} group ${group.id}`;
+}
+function severityRank(value) {
+    return value === "critical" ? 3 : value === "warning" ? 2 : 1;
+}
+function round1(value) {
+    return Math.round(value * 10) / 10;
+}

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

@@ -0,0 +1,9 @@
+import type { ResourceSnapshot } from "../resources/contract.js";
+import { type SupervisorHistory } from "./contract.js";
+export declare const SUPERVISOR_HISTORY_INTERVAL_MS = 10000;
+export declare const SUPERVISOR_HISTORY_MAX_POINTS = 90;
+export declare function updateSupervisorHistory(previous: SupervisorHistory | undefined, resource: ResourceSnapshot): {
+    history: SupervisorHistory;
+    changed: boolean;
+};
+//# sourceMappingURL=history.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/history.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,8BAA8B,QAAS,CAAC;AACrD,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,QAAQ,EAAE,gBAAgB,GACzB;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAuClD"}

package/dist/core/supervisor/history.js

@@ -0,0 +1,46 @@
+import { SUPERVISOR_HISTORY_SCHEMA_VERSION, } from "./contract.js";
+export const SUPERVISOR_HISTORY_INTERVAL_MS = 10_000;
+export const SUPERVISOR_HISTORY_MAX_POINTS = 90;
+export function updateSupervisorHistory(previous, resource) {
+    const prior = validHistory(previous) ? previous.points : [];
+    const lastAt = prior.length > 0 ? Date.parse(prior[prior.length - 1].sampled_at) : Number.NaN;
+    const sampledAt = Date.parse(resource.sampled_at);
+    if (Number.isFinite(lastAt) &&
+        Number.isFinite(sampledAt) &&
+        sampledAt - lastAt < SUPERVISOR_HISTORY_INTERVAL_MS) {
+        return {
+            history: {
+                schema_version: SUPERVISOR_HISTORY_SCHEMA_VERSION,
+                interval_ms: SUPERVISOR_HISTORY_INTERVAL_MS,
+                max_points: SUPERVISOR_HISTORY_MAX_POINTS,
+                points: prior,
+            },
+            changed: false,
+        };
+    }
+    const point = {
+        sampled_at: resource.sampled_at,
+        machine: {
+            cpu_percent: resource.machine.cpu_percent,
+            memory_percent: resource.machine.memory_percent,
+            memory_used_bytes: resource.machine.memory_used_bytes,
+            swap_used_bytes: resource.machine.swap_used_bytes,
+            process_count: resource.machine.process_count,
+        },
+        groups: resource.groups.map((group) => ({ ...group, root_pids: [...group.root_pids] })),
+    };
+    return {
+        history: {
+            schema_version: SUPERVISOR_HISTORY_SCHEMA_VERSION,
+            interval_ms: SUPERVISOR_HISTORY_INTERVAL_MS,
+            max_points: SUPERVISOR_HISTORY_MAX_POINTS,
+            points: [...prior, point].slice(-SUPERVISOR_HISTORY_MAX_POINTS),
+        },
+        changed: true,
+    };
+}
+function validHistory(value) {
+    return (value?.schema_version === SUPERVISOR_HISTORY_SCHEMA_VERSION &&
+        Array.isArray(value.points) &&
+        value.points.length <= SUPERVISOR_HISTORY_MAX_POINTS);
+}

package/dist/core/supervisor/hook-health-alerts.d.ts

@@ -0,0 +1,14 @@
+import type { SupervisorFindingEvidence, SupervisorFindingSeverity } from "./contract.js";
+import { type CompletedHookHealth, type SupervisorHookHealth } from "./hook-health.js";
+export interface HookHealthAlert {
+    finding_kind: "hook.execution-degraded" | "hook.execution-slow" | "hook.memory-heavy" | "hook.retry-cluster";
+    severity: SupervisorFindingSeverity;
+    scope_id: string;
+    summary: string;
+    observed_value: number;
+    unit: SupervisorFindingEvidence["unit"];
+    source: CompletedHookHealth;
+    owner_id?: string;
+}
+export declare function evaluateHookHealthAlerts(health: SupervisorHookHealth): readonly HookHealthAlert[];
+//# sourceMappingURL=hook-health-alerts.d.ts.map

package/dist/core/supervisor/hook-health-alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-health-alerts.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/hook-health-alerts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EACL,KAAK,mBAAmB,EAKxB,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,eAAe;IAC9B,YAAY,EACR,yBAAyB,GACzB,qBAAqB,GACrB,mBAAmB,GACnB,oBAAoB,CAAC;IACzB,QAAQ,EAAE,yBAAyB,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,yBAAyB,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,eAAe,EAAE,CAsDjG"}

package/dist/core/supervisor/hook-health-alerts.js

@@ -0,0 +1,70 @@
+import { SUPERVISOR_HIGH_COMPLETED_HOOK_RSS_BYTES, SUPERVISOR_HOOK_RETRY_CLUSTER_COUNT, SUPERVISOR_SLOW_COMPLETED_HOOK_MS, } from "./hook-health.js";
+export function evaluateHookHealthAlerts(health) {
+    if (health.capability.state === "unavailable")
+        return [];
+    const alerts = [];
+    for (const aggregate of health.aggregates) {
+        const receipts = health.recent.filter((receipt) => `${receipt.adapter}:${receipt.hook_name}` === aggregate.key);
+        const problem = receipts.find((receipt) => receipt.outcome === "faulted" || receipt.outcome === "degraded");
+        if (problem)
+            alerts.push(problemAlert(aggregate, problem));
+        const slow = maxReceipt(receipts, (receipt) => receipt.duration_ms);
+        if (slow && slow.duration_ms >= SUPERVISOR_SLOW_COMPLETED_HOOK_MS) {
+            alerts.push({
+                finding_kind: "hook.execution-slow",
+                severity: "warning",
+                scope_id: aggregate.key,
+                summary: `${aggregate.hook_name} completed in ${slow.duration_ms} milliseconds.`,
+                observed_value: slow.duration_ms,
+                unit: "milliseconds",
+                source: slow,
+                ...(slow.owner_id ? { owner_id: slow.owner_id } : {}),
+            });
+        }
+        const heavy = maxReceipt(receipts, (receipt) => receipt.rss_end_bytes);
+        if (heavy && heavy.rss_end_bytes >= SUPERVISOR_HIGH_COMPLETED_HOOK_RSS_BYTES) {
+            alerts.push({
+                finding_kind: "hook.memory-heavy",
+                severity: "warning",
+                scope_id: aggregate.key,
+                summary: `${aggregate.hook_name} completed with ${heavy.rss_end_bytes} resident bytes.`,
+                observed_value: heavy.rss_end_bytes,
+                unit: "bytes",
+                source: heavy,
+                ...(heavy.owner_id ? { owner_id: heavy.owner_id } : {}),
+            });
+        }
+    }
+    if (health.summary.retry_count >= SUPERVISOR_HOOK_RETRY_CLUSTER_COUNT) {
+        const latestRetry = health.recent.find((receipt) => receipt.retry_worker);
+        if (latestRetry) {
+            alerts.push({
+                finding_kind: "hook.retry-cluster",
+                severity: "warning",
+                scope_id: `${latestRetry.adapter}:runtime-context-retry`,
+                summary: `${health.summary.retry_count} hook retry workers ran inside five minutes.`,
+                observed_value: health.summary.retry_count,
+                unit: "count",
+                source: latestRetry,
+                ...(latestRetry.owner_id ? { owner_id: latestRetry.owner_id } : {}),
+            });
+        }
+    }
+    return alerts.slice(0, 12);
+}
+function problemAlert(aggregate, receipt) {
+    const severity = receipt.outcome === "faulted" ? "critical" : "warning";
+    return {
+        finding_kind: "hook.execution-degraded",
+        severity,
+        scope_id: aggregate.key,
+        summary: `${aggregate.hook_name} completed with internal outcome ${receipt.outcome}.`,
+        observed_value: aggregate.degraded_count + aggregate.faulted_count,
+        unit: "count",
+        source: receipt,
+        ...(receipt.owner_id ? { owner_id: receipt.owner_id } : {}),
+    };
+}
+function maxReceipt(receipts, value) {
+    return receipts.reduce((current, receipt) => (!current || value(receipt) > value(current) ? receipt : current), undefined);
+}

package/dist/core/supervisor/hook-health-storage.d.ts

@@ -0,0 +1,5 @@
+import { type SupervisorHookHealth } from "./hook-health.js";
+export declare function supervisorHookHealthPath(coordRoot: string): string;
+export declare function writeSupervisorHookHealth(coordRoot: string, value: SupervisorHookHealth): void;
+export declare function readSupervisorHookHealth(coordRoot: string): SupervisorHookHealth | undefined;
+//# sourceMappingURL=hook-health-storage.d.ts.map

package/dist/core/supervisor/hook-health-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-health-storage.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/hook-health-storage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyC,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAEpG,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAE9F;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAW5F"}

package/dist/core/supervisor/hook-health-storage.js

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { writePrivateJsonAtomic } from "../storage/atomic-json.js";
+import { SUPERVISOR_HOOK_HEALTH_SCHEMA_VERSION } from "./hook-health.js";
+export function supervisorHookHealthPath(coordRoot) {
+    return join(resolve(coordRoot), ".harnery", "supervisor", "hook-health.json");
+}
+export function writeSupervisorHookHealth(coordRoot, value) {
+    writePrivateJsonAtomic(supervisorHookHealthPath(coordRoot), value);
+}
+export function readSupervisorHookHealth(coordRoot) {
+    const path = supervisorHookHealthPath(coordRoot);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value?.schema_version === SUPERVISOR_HOOK_HEALTH_SCHEMA_VERSION
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/supervisor/hook-health.d.ts

@@ -0,0 +1,72 @@
+import { type HookHealthOutcome } from "../hooks/health.js";
+import type { HarneryLogRecordV1 } from "../storage/jsonl.js";
+import type { SupervisorLogFeed } from "./contract.js";
+export declare const SUPERVISOR_HOOK_HEALTH_SCHEMA_VERSION: 1;
+export declare const SUPERVISOR_HOOK_HEALTH_RECENT_LIMIT = 50;
+export declare const SUPERVISOR_HOOK_HEALTH_AGGREGATE_LIMIT = 40;
+export declare const SUPERVISOR_SLOW_COMPLETED_HOOK_MS = 30000;
+export declare const SUPERVISOR_HIGH_COMPLETED_HOOK_RSS_BYTES: number;
+export declare const SUPERVISOR_HOOK_RETRY_CLUSTER_COUNT = 3;
+export declare const SUPERVISOR_HOOK_RETRY_CLUSTER_WINDOW_MS: number;
+export interface CompletedHookHealth {
+    id: string;
+    observed_at: string;
+    hook_name: string;
+    adapter: "claude-code" | "codex" | "cursor" | "unknown";
+    outcome: HookHealthOutcome;
+    duration_ms: number;
+    rss_start_bytes: number;
+    rss_end_bytes: number;
+    rss_delta_bytes: number;
+    retry_worker: boolean;
+    error_count: number;
+    error_phases: readonly string[];
+    payload_bytes: number;
+    pid: number;
+    owner_id?: string;
+    skipped_reason?: string;
+    v3_state?: string;
+}
+export interface HookHealthAggregate {
+    key: string;
+    hook_name: string;
+    adapter: CompletedHookHealth["adapter"];
+    invocation_count: number;
+    completed_count: number;
+    skipped_count: number;
+    degraded_count: number;
+    faulted_count: number;
+    retry_count: number;
+    duration_p50_ms: number;
+    duration_p95_ms: number;
+    duration_max_ms: number;
+    rss_end_max_bytes: number;
+    rss_delta_max_bytes: number;
+    latest_observed_at: string;
+    owner_ids: readonly string[];
+}
+export interface SupervisorHookHealth {
+    schema_version: typeof SUPERVISOR_HOOK_HEALTH_SCHEMA_VERSION;
+    captured_at: string;
+    capability: {
+        source_kind: "hook.terminal-log";
+        state: "supported" | "partial" | "unavailable";
+        reason?: string;
+    };
+    source_record_count: number;
+    malformed_record_count: number;
+    truncated: boolean;
+    summary: {
+        invocation_count: number;
+        degraded_count: number;
+        faulted_count: number;
+        slow_count: number;
+        high_memory_count: number;
+        retry_count: number;
+    };
+    aggregates: readonly HookHealthAggregate[];
+    recent: readonly CompletedHookHealth[];
+}
+export declare function projectHookHealth(feed: SupervisorLogFeed, now?: Date): SupervisorHookHealth;
+export declare function parseCompletedHookHealth(record: HarneryLogRecordV1): CompletedHookHealth | undefined;
+//# sourceMappingURL=hook-health.d.ts.map

package/dist/core/supervisor/hook-health.d.ts.map

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