harnery 0.38.0 → 0.40.0

package/src/core/supervisor/contract.ts

@@ -1,10 +1,15 @@
+import type {
+  PressureAssessment,
+  PressureHysteresisState,
+} from "../diagnostics/pressure-contract.ts";
 import type { ResourceProcessGroup } from "../resources/contract.ts";
 import type { HarneryLogRecordV1 } from "../storage/jsonl.ts";
 
 export const SUPERVISOR_STATUS_SCHEMA_VERSION = 1 as const;
 export const SUPERVISOR_SNAPSHOT_SCHEMA_VERSION = 2 as const;
-export const SUPERVISOR_HISTORY_SCHEMA_VERSION = 1 as const;
-export const SUPERVISOR_FINDING_SCHEMA_VERSION = 2 as const;
+export const SUPERVISOR_HISTORY_SCHEMA_VERSION = 2 as const;
+export const SUPERVISOR_FINDING_SCHEMA_VERSION = 3 as const;
+export const SUPERVISOR_PRESSURE_SCHEMA_VERSION = 1 as const;
 export const SUPERVISOR_ACTIVITY_SCHEMA_VERSION = 1 as const;
 export const SUPERVISOR_TIMELINE_SCHEMA_VERSION = 2 as const;
 export const SUPERVISOR_EXPLANATION_SCHEMA_VERSION = 1 as const;
@@ -108,7 +113,18 @@ export interface SupervisorHistoryPoint {
     memory_percent: number | null;
     memory_used_bytes: number | null;
     swap_used_bytes: number | null;
-    process_count: number;
+    process_count: number | null;
+    load_average_1?: number | null;
+  };
+  /**
+   * The contention readings the pressure trend follows. Null when the platform
+   * does not expose a dimension, never zero, so a gap cannot read as calm.
+   */
+  pressure: {
+    memory_full_avg10: number | null;
+    io_full_avg10: number | null;
+    cpu_some_avg60: number | null;
+    swap_out_bytes_per_second: number | null;
   };
   groups: readonly ResourceProcessGroup[];
 }
@@ -129,6 +145,16 @@ export type SupervisorCapabilityState =
   | "malformed"
   | "redacted";
 export type SupervisorFindingSeverity = "info" | "warning" | "critical";
+/**
+ * Why a finding exists, and therefore what it may influence.
+ *
+ * `contention` findings report that a shared resource is actually contended,
+ * and are the only class the pressure assessment may read as machine state.
+ * `attribution` findings name who holds a resource; they are always carried as
+ * contributors and never set state. `diagnostic` findings report that an
+ * observation path itself is degraded.
+ */
+export type SupervisorFindingClass = "contention" | "attribution" | "diagnostic";
 export type SupervisorFindingState = "opened" | "resolved";
 
 export interface SupervisorCapability {
@@ -179,6 +205,7 @@ export interface SupervisorFinding {
   fingerprint: string;
   source_kind: string;
   finding_kind: string;
+  finding_class: SupervisorFindingClass;
   severity: SupervisorFindingSeverity;
   state: SupervisorFindingState;
   scope_kind: string;
@@ -217,6 +244,21 @@ export interface SupervisorActivitySnapshot {
   capability: SupervisorCapability;
 }
 
+/**
+ * The pressure assessment the observer published on its last cycle, with the
+ * hysteresis state that produced it. The observer is the only writer, because
+ * it is the only reader that sees consecutive samples; every other surface
+ * reads this record so all of them report the same assessment.
+ */
+export interface SupervisorPressureRecord {
+  schema_version: typeof SUPERVISOR_PRESSURE_SCHEMA_VERSION;
+  published_at: string;
+  /** Identity of the observer run, so a restart resets carried-forward streaks. */
+  observer_generation: string;
+  assessment: PressureAssessment;
+  prior_hysteresis: PressureHysteresisState | null;
+}
+
 export interface SupervisorFindings {
   schema_version: typeof SUPERVISOR_FINDING_SCHEMA_VERSION;
   max_findings: number;

package/src/core/supervisor/findings.ts

@@ -15,6 +15,7 @@ import {
   type SupervisorCapability,
   type SupervisorFinding,
   type SupervisorFindingAttribution,
+  type SupervisorFindingClass,
   type SupervisorFindingEvidence,
   type SupervisorFindingSeverity,
   type SupervisorFindings,
@@ -25,6 +26,10 @@ import {
 } from "./contract.ts";
 import type { SupervisorHookHealth } from "./hook-health.ts";
 import { evaluateHookHealthAlerts } from "./hook-health-alerts.ts";
+import {
+  type LedgerControlStateFindingInputV1,
+  ledgerControlStateFindingCandidateV1,
+} from "./ledger-state.ts";
 
 const GIB = 1_024 * 1_024 * 1_024;
 const MIB = 1_024 * 1_024;
@@ -42,6 +47,7 @@ const MEMORY_GROWTH_WINDOW_MS = 5 * 60_000;
 interface Candidate {
   source_kind: string;
   finding_kind: string;
+  finding_class: SupervisorFindingClass;
   severity: SupervisorFindingSeverity;
   scope_kind: string;
   scope_id: string;
@@ -63,6 +69,8 @@ export interface SupervisorFindingEvaluationInput {
   hookHealth?: SupervisorHookHealth;
   coordination?: CoordinationHealthSnapshot;
   activity?: SupervisorActivitySnapshot;
+  /** Event ledger control drift, when the caller observed the control state. */
+  ledgerControlState?: LedgerControlStateFindingInputV1;
   now?: Date;
 }
 
@@ -110,6 +118,7 @@ export function updateSupervisorFindings(
       fingerprint,
       source_kind: candidate.source_kind,
       finding_kind: candidate.finding_kind,
+      finding_class: candidate.finding_class,
       severity: candidate.severity,
       state: "opened",
       scope_kind: candidate.scope_kind,
@@ -158,6 +167,7 @@ function evaluateCandidates(input: {
   hookHealth?: SupervisorHookHealth;
   coordination?: CoordinationHealthSnapshot;
   activity?: SupervisorActivitySnapshot;
+  ledgerControlState?: LedgerControlStateFindingInputV1;
 }): Candidate[] {
   const out: Candidate[] = [];
   const resourceCapability: SupervisorCapability = {
@@ -213,6 +223,131 @@ function evaluateCandidates(input: {
       swapPercent!,
       "percent",
     );
+  for (const disk of input.resource.disks ?? []) {
+    if (disk.state !== "supported" || disk.available_bytes === null || disk.used_percent === null)
+      continue;
+    if (disk.used_percent < 90 && disk.available_bytes >= 5 * GIB) continue;
+    out.push(
+      candidate(
+        "machine.disk-space",
+        disk.used_percent >= 97 || disk.available_bytes < GIB ? "critical" : "warning",
+        "filesystem",
+        disk.path,
+        `Filesystem ${disk.path} has ${round1(disk.available_bytes / GIB)} GiB available (${disk.used_percent}% used).`,
+        source,
+        disk.used_percent,
+        "percent",
+        [resourceCapability],
+      ),
+    );
+  }
+  const pressure = input.resource.pressure;
+  if (pressure?.state === "supported" || pressure?.state === "partial") {
+    for (const [kind, full] of [
+      ["memory", pressure.memory_full],
+      ["io", pressure.io_full],
+    ] as const) {
+      if (!full || (full.avg10 < 50 && !(full.avg10 >= 20 && full.avg10 > full.avg60))) continue;
+      const direction =
+        full.avg10 > full.avg60 ? "rising" : full.avg10 < full.avg60 ? "falling" : "steady";
+      addMachine(
+        `machine.${kind}-full-stall`,
+        full.avg10 >= 50 ? "critical" : "warning",
+        `All non-idle tasks stalled on ${kind} for ${full.avg10}% of the recent 10-second window (${direction}; 60s ${full.avg60}%, 300s ${full.avg300}%).`,
+        full.avg10,
+        "percent",
+      );
+    }
+    for (const [kind, value, threshold] of [
+      ["cpu", pressure.cpu, 20],
+      ["memory", pressure.memory, 5],
+      ["io", pressure.io, 10],
+    ] as const) {
+      if (!value || value.avg60 < threshold) continue;
+      addMachine(
+        `machine.${kind}-stall`,
+        value.avg60 >= threshold * 2 ? "critical" : "warning",
+        `At least one task stalled on ${kind} for ${value.avg60}% of the last minute.`,
+        value.avg60,
+        "percent",
+      );
+    }
+  }
+  const oom = input.resource.oom;
+  if (
+    oom?.state === "supported" &&
+    oom.last_kill_age_ms !== null &&
+    oom.last_kill_age_ms <= 60_000 &&
+    oom.total_kills !== null
+  ) {
+    addMachine(
+      "machine.oom-kill",
+      "critical",
+      `Kernel OOM kills increased ${Math.round(oom.last_kill_age_ms / 1000)}s ago; ${oom.total_kills} kills reported in total. Work may have been lost.`,
+      oom.total_kills,
+      "count",
+    );
+  }
+  const host = input.resource.host;
+  const hostAge = host
+    ? Date.parse(input.resource.sampled_at) +
+      input.resource.sample_duration_ms -
+      Date.parse(host.sampled_at)
+    : NaN;
+  if (
+    host?.machine &&
+    (host.state === "supported" || host.state === "partial") &&
+    hostAge >= 0 &&
+    hostAge <= 30_000
+  ) {
+    const hostSource = stableSource(
+      "resource.windows-host",
+      "windows-host",
+      host.sampled_at,
+      host.state,
+    );
+    for (const [kind, value, threshold, severity] of [
+      ["cpu", host.machine.cpu_percent, MACHINE_CPU_THRESHOLD, "warning"],
+      ["memory", host.machine.memory_percent, MACHINE_MEMORY_THRESHOLD, "critical"],
+    ] as const) {
+      if (value === null || value < threshold) continue;
+      out.push(
+        candidate(
+          `machine.host-${kind}-pressure`,
+          severity,
+          "machine",
+          "windows-host",
+          `Windows host ${kind} is ${value}%.`,
+          hostSource,
+          value,
+          "percent",
+          [{ source_kind: "resource.windows-host", state: host.state }],
+        ),
+      );
+    }
+    for (const disk of host.disks) {
+      if (
+        disk.state !== "supported" ||
+        disk.available_bytes === null ||
+        disk.used_percent === null ||
+        (disk.used_percent < 90 && disk.available_bytes >= 5 * GIB)
+      )
+        continue;
+      out.push(
+        candidate(
+          "machine.host-disk-space",
+          disk.used_percent >= 97 || disk.available_bytes < GIB ? "critical" : "warning",
+          "filesystem",
+          `windows-host:${disk.path}`,
+          `Windows filesystem ${disk.path} has ${round1(disk.available_bytes / GIB)} GiB available (${disk.used_percent}% used).`,
+          hostSource,
+          disk.used_percent,
+          "percent",
+          [{ source_kind: "resource.windows-host", state: host.state }],
+        ),
+      );
+    }
+  }
   if (input.resource.collector_cpu_ms >= COLLECTOR_CPU_THRESHOLD_MS)
     out.push(
       candidate(
@@ -431,6 +566,10 @@ function evaluateCandidates(input: {
       );
     }
   }
+  if (input.ledgerControlState) {
+    const ledger = ledgerControlStateFindingCandidateV1(input.ledgerControlState);
+    if (ledger) out.push(ledger);
+  }
   return out;
 }
 
@@ -642,6 +781,7 @@ function candidate(
   return {
     source_kind: source.source_kind,
     finding_kind: findingKind,
+    finding_class: classifyFinding(findingKind),
     severity,
     scope_kind: scopeKind,
     scope_id: scopeId,
@@ -654,6 +794,25 @@ function candidate(
   };
 }
 
+/**
+ * Which question a finding answers. Contention findings report a machine
+ * resource the kernel says is exhausted or stalling. Attribution findings name
+ * who is consuming a resource, which is useful for an operator but is never
+ * evidence that the machine is under contention. Diagnostic findings report
+ * that the observation path itself is degraded. Anything unrecognized is
+ * diagnostic, because only contention may ever bear machine state.
+ */
+function classifyFinding(findingKind: string): SupervisorFindingClass {
+  if (findingKind.startsWith("machine.")) return "contention";
+  if (
+    findingKind === "resource.memory-growth" ||
+    ["process.", "group.", "hook.", "service."].some((prefix) => findingKind.startsWith(prefix))
+  ) {
+    return "attribution";
+  }
+  return "diagnostic";
+}
+
 function resourceSource(
   resource: ResourceSnapshot,
   capability: SupervisorSourceReference["capability"],

package/src/core/supervisor/history.ts

@@ -38,7 +38,9 @@ export function updateSupervisorHistory(
       memory_used_bytes: resource.machine.memory_used_bytes,
       swap_used_bytes: resource.machine.swap_used_bytes,
       process_count: resource.machine.process_count,
+      load_average_1: resource.machine.load_average?.[0] ?? null,
     },
+    pressure: pressurePoint(resource),
     groups: resource.groups.map((group) => ({ ...group, root_pids: [...group.root_pids] })),
   };
   return {
@@ -52,6 +54,19 @@ export function updateSupervisorHistory(
   };
 }
 
+function pressurePoint(resource: ResourceSnapshot): SupervisorHistoryPoint["pressure"] {
+  const pressure = resource.pressure;
+  const usable = pressure?.state === "supported" || pressure?.state === "partial";
+  const vmstat = resource.vmstat;
+  const vmstatUsable = vmstat?.state === "supported" || vmstat?.state === "partial";
+  return {
+    memory_full_avg10: usable ? (pressure.memory_full?.avg10 ?? null) : null,
+    io_full_avg10: usable ? (pressure.io_full?.avg10 ?? null) : null,
+    cpu_some_avg60: usable ? (pressure.cpu?.avg60 ?? null) : null,
+    swap_out_bytes_per_second: vmstatUsable ? vmstat.swap_out_bytes_per_second : null,
+  };
+}
+
 function validHistory(value: SupervisorHistory | undefined): value is SupervisorHistory {
   return (
     value?.schema_version === SUPERVISOR_HISTORY_SCHEMA_VERSION &&

package/src/core/supervisor/service.ts

@@ -14,8 +14,13 @@ import {
 import { hostname } from "node:os";
 import { resolve } from "node:path";
 import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
 import { collectCoordinationHealthSnapshot } from "../agents/health.ts";
 import { checkPidToken, processStartToken } from "../agents/state/proc-start.ts";
+import { pressureHistoryFromSupervisor } from "../diagnostics/advice.ts";
+import { assessPressure } from "../diagnostics/pressure.ts";
+import { readEventV3ControlState } from "../events/v3/control.ts";
+import { janitorLiveDisplayV3 } from "../events/v3/live-feed.ts";
 import type { ResourceSamplerState } from "../resources/contract.ts";
 import { sampleResources } from "../resources/sampler.ts";
 import { requestResourceServiceStop } from "../resources/service.ts";
@@ -25,8 +30,11 @@ import { writePrivateJsonAtomic } from "../storage/atomic-json.ts";
 import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.ts";
 import { collectSupervisorActivitySnapshot } from "./activity.ts";
 import {
+  SUPERVISOR_PRESSURE_SCHEMA_VERSION,
   SUPERVISOR_SNAPSHOT_SCHEMA_VERSION,
   SUPERVISOR_STATUS_SCHEMA_VERSION,
+  type SupervisorCapability,
+  type SupervisorPressureRecord,
   type SupervisorServiceStatusRecord,
   type SupervisorSnapshot,
   type SupervisorStatus,
@@ -37,10 +45,19 @@ import { updateSupervisorHistory } from "./history.ts";
 import { projectHookHealth } from "./hook-health.ts";
 import { writeSupervisorHookHealth } from "./hook-health-storage.ts";
 import { collectHookHealth } from "./hooks.ts";
+import type {
+  LedgerControlStateFindingInputV1,
+  LedgerControlStateObservationV1,
+} from "./ledger-state.ts";
 import { SupervisorLogCollector } from "./log-feed.ts";
 import { collectServiceHealth } from "./services.ts";
 import { readSupervisorStatus } from "./status.ts";
-import { readSupervisorFindings, readSupervisorHistory, supervisorPaths } from "./storage.ts";
+import {
+  readSupervisorFindings,
+  readSupervisorHistory,
+  readSupervisorPressure,
+  supervisorPaths,
+} from "./storage.ts";
 import { buildSupervisorTimeline } from "./timeline.ts";
 
 export const SUPERVISOR_DEFAULT_INTERVAL_MS = 2_000;
@@ -49,6 +66,7 @@ const SUPERVISOR_MIN_INTERVAL_MS = 500;
 const SUPERVISOR_MAX_INTERVAL_MS = 60_000;
 const SUPERVISOR_MIN_IDLE_EXIT_MS = 5_000;
 const SUPERVISOR_MAX_IDLE_EXIT_MS = 24 * 60 * 60_000;
+const LIVE_DISPLAY_SWEEP_INTERVAL_MS = 5 * 60_000;
 
 interface SupervisorLease {
   pid: number;
@@ -87,12 +105,15 @@ export async function spawnSupervisor(
   const paths = supervisorPaths(coordRoot);
   mkdirSync(paths.root, { recursive: true, mode: 0o700 });
   rmSync(paths.stop, { force: true });
-  const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
-  if (!existsSync(harnBin)) throw new Error(`cannot find harn executable at ${harnBin}`);
+  const cliPath = fileURLToPath(
+    new URL(import.meta.url.endsWith(".ts") ? "../../cli.ts" : "../../cli.js", import.meta.url),
+  );
+  if (!existsSync(cliPath)) throw new Error(`cannot find harn entrypoint at ${cliPath}`);
   let spawnError: Error | undefined;
   const child = spawn(
-    harnBin,
+    process.execPath,
     [
+      cliPath,
       "supervisor",
       "daemon",
       "--root",
@@ -106,6 +127,7 @@ export async function spawnSupervisor(
     {
       cwd: coordRoot,
       detached: true,
+      windowsHide: true,
       stdio: ["ignore", "ignore", "ignore"],
       env: {
         ...process.env,
@@ -153,7 +175,7 @@ export function requestSupervisorStop(coordRootRaw: string): SupervisorStatus {
     requested_at: new Date().toISOString(),
     requested_by_pid: process.pid,
   });
-  if (status.running && status.record?.host === hostname()) {
+  if (status.running && status.record?.host === hostname() && process.platform !== "win32") {
     try {
       process.kill(status.record.pid, "SIGTERM");
     } catch {
@@ -196,7 +218,22 @@ export async function runSupervisor(
   let history = readSupervisorHistory(coordRoot);
   let findings = readSupervisorFindings(coordRoot);
   let coordination = collectCoordinationHealthSnapshot(coordRoot, now());
+  // The observer is the only reader that sees consecutive samples, so it is the
+  // only writer of the pressure assessment. Trend needs recent samples and a
+  // restart deliberately starts with none, which reports an unknown trend
+  // rather than a guessed one.
+  // The control state is now a cheap witnessed read in both states, so the
+  // observer can watch it every cycle. A single non-active sample is a normal
+  // boundary between two appends; the finding needs two, so keep a short run.
+  const ledgerObservations: LedgerControlStateObservationV1[] = [];
+  const priorPressure = readSupervisorPressure(coordRoot);
+  let pressureHysteresis = priorPressure?.assessment.hysteresis ?? null;
+  const observerGeneration = `${process.pid}:${startedAt}`;
   const logs = new SupervisorLogCollector(coordRoot);
+  // Live-display rows expire within the hour, but nothing else deletes their
+  // generation files. Left alone the directory grows without bound and every
+  // dashboard read pays for the residue, so the supervisor sweeps it.
+  let lastLiveDisplaySweepMs = 0;
   const writeStatus = () => {
     status.heartbeat_at = now().toISOString();
     writePrivateJsonAtomic(paths.service, status);
@@ -221,8 +258,18 @@ export async function runSupervisor(
       const cycleStarted = performance.now();
       try {
         const cycleNow = now();
+        if (cycleNow.getTime() - lastLiveDisplaySweepMs >= LIVE_DISPLAY_SWEEP_INTERVAL_MS) {
+          lastLiveDisplaySweepMs = cycleNow.getTime();
+          try {
+            const swept = janitorLiveDisplayV3(coordRoot, now);
+            if (swept.removed > 0) log(coordRoot, "supervisor.live_display_swept", { ...swept });
+          } catch (error) {
+            log(coordRoot, "supervisor.live_display_sweep_error", {}, error);
+          }
+        }
         const serviceHealth = collectServiceHealth(coordRoot, status);
         const resource = sampleResources(coordRoot, previousResource, {
+          backgroundHost: true,
           services: [
             { pid: process.pid, id: "supervisor" },
             ...serviceHealth.consumers.map((consumer) => ({
@@ -246,6 +293,14 @@ export async function runSupervisor(
         if (historyResult.changed)
           coordination = collectCoordinationHealthSnapshot(coordRoot, cycleNow);
         writePrivateJsonAtomic(paths.coordination_health, coordination);
+        const ledgerControl = observeLedgerControlState(coordRoot, cycleNow);
+        const ledgerControlState: LedgerControlStateFindingInputV1 = {
+          current: ledgerControl.observation,
+          previous: [...ledgerObservations].reverse(),
+          capability: ledgerControl.capability,
+        };
+        ledgerObservations.push(ledgerControl.observation);
+        if (ledgerObservations.length > LEDGER_OBSERVATION_LIMIT) ledgerObservations.shift();
         const priorActiveFindingIds = new Set(findings?.active.map((finding) => finding.id) ?? []);
         const priorTransitionKeys = new Set(
           findings?.transitions.map((finding) => `${finding.id}:${finding.state}`) ?? [],
@@ -260,9 +315,43 @@ export async function runSupervisor(
           hookHealth,
           coordination,
           activity,
+          ledgerControlState,
           now: cycleNow,
         });
         writePrivateJsonAtomic(paths.findings, findings);
+        const assessment = assessPressure({
+          snapshot: resource.snapshot,
+          history: pressureHistoryFromSupervisor(history.points),
+          findings: findings.active,
+          findings_capability: { source_kind: "supervisor-findings", state: "supported" },
+          prior: pressureHysteresis,
+          observer_generation: observerGeneration,
+          // Read the clock after sampling. `cycleNow` predates the snapshot, so
+          // using it here dates the sample in the future and publishes a
+          // negative age that the status reader rejects as malformed.
+          now_ms: now().getTime(),
+        });
+        writePrivateJsonAtomic(paths.pressure, {
+          schema_version: SUPERVISOR_PRESSURE_SCHEMA_VERSION,
+          published_at: cycleNow.toISOString(),
+          observer_generation: observerGeneration,
+          assessment,
+          prior_hysteresis: pressureHysteresis,
+        } satisfies SupervisorPressureRecord);
+        const priorPressureState = pressureHysteresis?.state ?? null;
+        if (assessment.state !== priorPressureState) {
+          // The sample log carries only cycle timings, so without this record
+          // a past elevated episode cannot be explained after it clears.
+          log(coordRoot, "supervisor.pressure_transition", {
+            from_state: priorPressureState ?? "none",
+            to_state: assessment.state,
+            scope: assessment.scope,
+            limiting_resource: assessment.limiting_resource,
+            recommended_action: assessment.recommended_action,
+            reasons: assessment.reasons.map((reason) => `${reason.code}: ${reason.summary}`),
+          });
+        }
+        pressureHysteresis = assessment.hysteresis;
         mkdirSync(paths.timelines, { recursive: true, mode: 0o700 });
         mkdirSync(paths.explanations, { recursive: true, mode: 0o700 });
         const projectionUpdates = [
@@ -365,6 +454,45 @@ export async function runSupervisor(
   return status;
 }
 
+const LEDGER_OBSERVATION_LIMIT = 8;
+
+/**
+ * Read the control state without letting a broken ledger break observation.
+ * A failed read is reported as an unsupported capability with an `invalid`
+ * state, never as a healthy `active`.
+ */
+function observeLedgerControlState(
+  coordRoot: string,
+  now: Date,
+): { observation: LedgerControlStateObservationV1; capability: SupervisorCapability } {
+  const observedAt = now.toISOString();
+  try {
+    const control = readEventV3ControlState(coordRoot);
+    return {
+      observation: {
+        state: control.state,
+        ...("reason" in control && control.reason ? { reason: control.reason } : {}),
+        observed_at: observedAt,
+      },
+      capability: { source_kind: "event-ledger.control-state", state: "supported" },
+    };
+  } catch (error) {
+    return {
+      observation: {
+        state: "invalid",
+        reason: "control_state_unreadable",
+        observed_at: observedAt,
+      },
+      capability: {
+        source_kind: "event-ledger.control-state",
+        state: "error",
+        reason_code: "control-state-unreadable",
+        detail: error instanceof Error ? error.message.slice(0, 200) : "unknown error",
+      },
+    };
+  }
+}
+
 function acquireLease(coordRoot: string, now: Date): SupervisorLease {
   const paths = supervisorPaths(coordRoot);
   mkdirSync(paths.root, { recursive: true, mode: 0o700 });

package/src/core/supervisor/storage.ts

@@ -8,6 +8,7 @@ import type {
   SupervisorFindings,
   SupervisorHistory,
   SupervisorLogFeed,
+  SupervisorPressureRecord,
   SupervisorServiceStatusRecord,
   SupervisorSnapshot,
   SupervisorTimeline,
@@ -22,6 +23,7 @@ export interface SupervisorPaths {
   history: string;
   activity: string;
   findings: string;
+  pressure: string;
   timelines: string;
   explanations: string;
   coordination_health: string;
@@ -40,6 +42,7 @@ export function supervisorPaths(coordRootRaw: string): SupervisorPaths {
     history: join(root, "history.json"),
     activity: join(root, "activity.json"),
     findings: join(root, "findings.json"),
+    pressure: join(root, "pressure.json"),
     timelines: join(root, "timelines"),
     explanations: join(root, "explanations"),
     coordination_health: join(root, "coordination-health.json"),
@@ -74,6 +77,10 @@ export function readSupervisorFindings(coordRoot: string): SupervisorFindings |
   return readJson<SupervisorFindings>(supervisorPaths(coordRoot).findings);
 }
 
+export function readSupervisorPressure(coordRoot: string): SupervisorPressureRecord | undefined {
+  return readJson<SupervisorPressureRecord>(supervisorPaths(coordRoot).pressure);
+}
+
 export function readSupervisorTimeline(
   coordRoot: string,
   findingId: string,