harnery 0.38.0 → 0.40.0

package/src/core/artifacts/mutation-lock.ts

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import {
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmdirSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { processStartToken } from "../agents/state/proc-start.ts";
+
+interface LockOwner {
+  version: 1;
+  host: string;
+  pid: number;
+  process_start: string | null;
+  acquired_at: string;
+}
+
+/** Age is never authority to evict an owner. Unknown owners fail closed. */
+function reclaimDeadOwner(lock: string): boolean {
+  try {
+    const stat = lstatSync(lock);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return false;
+    const names = readdirSync(lock);
+    if (names.length !== 1 || !/^owner-[0-9a-f-]{36}\.json$/.test(names[0]!)) return false;
+    const ownerPath = join(lock, names[0]!);
+    const ownerStat = lstatSync(ownerPath);
+    if (!ownerStat.isFile() || ownerStat.isSymbolicLink() || ownerStat.size > 4096) return false;
+    const owner = JSON.parse(readFileSync(ownerPath, "utf8")) as LockOwner;
+    if (
+      owner.version !== 1 ||
+      owner.host !== hostname() ||
+      !Number.isSafeInteger(owner.pid) ||
+      owner.pid <= 0 ||
+      !(owner.process_start === null || typeof owner.process_start === "string")
+    )
+      return false;
+    let dead = false;
+    try {
+      process.kill(owner.pid, 0);
+      const current = processStartToken(owner.pid);
+      // Wall-clock ps lstart output can drift even for a live process. Only
+      // boot-scoped procfs ticks establish PID reuse; other probes need ESRCH.
+      const bootScoped = /^l[0-9a-f]{8}\.\d+$/;
+      dead =
+        typeof owner.process_start === "string" &&
+        bootScoped.test(owner.process_start) &&
+        typeof current === "string" &&
+        bootScoped.test(current) &&
+        current !== owner.process_start;
+    } catch (error) {
+      dead = (error as NodeJS.ErrnoException).code === "ESRCH";
+    }
+    if (!dead) return false;
+    // Only the contender that removes this unique owner's file may remove the
+    // directory. A losing reaper must not unlink a replacement owner's lock.
+    unlinkSync(ownerPath);
+    rmdirSync(lock);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function withArtifactLock<T>(repoRoot: string, action: () => T): T {
+  // Probe before mkdir so a slow platform process probe cannot hold an
+  // ownerless lock open while other writers are trying to acquire it.
+  const owner: LockOwner = {
+    version: 1,
+    host: hostname(),
+    pid: process.pid,
+    process_start: processStartToken(process.pid),
+    acquired_at: new Date().toISOString(),
+  };
+  const lock = join(resolve(repoRoot), ".harnery/artifacts-mutation.lock");
+  mkdirSync(dirname(lock), { recursive: true });
+  try {
+    mkdirSync(lock);
+  } catch {
+    if (!reclaimDeadOwner(lock)) {
+      throw new Error(
+        "artifact store mutation lock unavailable; a live or unverifiable owner holds it. " +
+          "Dead local owners recover automatically; an empty or invalid lock requires explicit inspection.",
+      );
+    }
+    // Another caller may win after recovery. Never retry by removing its lock.
+    mkdirSync(lock);
+  }
+  const ownerPath = join(lock, `owner-${randomUUID()}.json`);
+  try {
+    writeFileSync(ownerPath, JSON.stringify(owner), { flag: "wx" });
+    return action();
+  } finally {
+    // A crash before publication or between these two calls leaves an empty
+    // directory. It cannot be distinguished safely from an initializing owner.
+    // Publication may have failed before creating a file. Remove only our
+    // unique file, then the empty directory; never recursively delete contents.
+    rmSync(ownerPath, { force: true });
+    rmdirSync(lock);
+  }
+}

package/src/core/backup/host-snapshot.ts

@@ -0,0 +1,76 @@
+/**
+ * Freshness helpers shared by `harn backup snapshot` and the session-start
+ * scheduler. The host cache is a local, best-effort record of this machine's
+ * newest known snapshot: the scheduler reads it to skip a remote restic round
+ * trip when the host is plainly current, and restic stays the authority
+ * whenever the cache is missing, stale, or written by another host.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import path from "node:path";
+
+export function parseBackupDuration(value: string): number | null {
+  const match = /^([1-9][0-9]*)(ms|s|m|h|d)$/.exec(value.trim());
+  if (!match) return null;
+  const scalar = Number(match[1]);
+  const factor = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[
+    match[2] as "ms" | "s" | "m" | "h" | "d"
+  ];
+  const duration = scalar * factor;
+  return Number.isSafeInteger(duration) ? duration : null;
+}
+
+/** Newest snapshot time (epoch ms) in `restic snapshots --json` output, or null. */
+export function newestSnapshotTime(output: string): number | null {
+  try {
+    const rows = JSON.parse(output) as Array<{ time?: string }>;
+    const newest = rows.reduce((latest, row) => {
+      const time = typeof row.time === "string" ? Date.parse(row.time) : Number.NaN;
+      return Number.isFinite(time) ? Math.max(latest, time) : latest;
+    }, Number.NEGATIVE_INFINITY);
+    return Number.isFinite(newest) ? newest : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface HostSnapshotCache {
+  host: string;
+  snapshotAt: number;
+}
+
+export function hostSnapshotCachePath(harneryDir: string): string {
+  return path.join(harneryDir, "logs", "backup-host-snapshot.json");
+}
+
+export function readHostSnapshotCache(harneryDir: string): HostSnapshotCache | null {
+  try {
+    const parsed = JSON.parse(readFileSync(hostSnapshotCachePath(harneryDir), "utf8")) as {
+      host?: unknown;
+      snapshot_at?: unknown;
+    };
+    const snapshotAt =
+      typeof parsed.snapshot_at === "string" ? Date.parse(parsed.snapshot_at) : Number.NaN;
+    if (typeof parsed.host !== "string" || !Number.isFinite(snapshotAt)) return null;
+    return { host: parsed.host, snapshotAt };
+  } catch {
+    return null;
+  }
+}
+
+export function recordHostSnapshot(harneryDir: string, snapshotAt: number): void {
+  try {
+    const file = hostSnapshotCachePath(harneryDir);
+    mkdirSync(path.dirname(file), { recursive: true });
+    const body = `${JSON.stringify({
+      host: hostname(),
+      snapshot_at: new Date(snapshotAt).toISOString(),
+      recorded_at: new Date().toISOString(),
+    })}\n`;
+    writeFileSync(`${file}.tmp`, body, "utf8");
+    renameSync(`${file}.tmp`, file);
+  } catch {
+    // The cache is an optimisation; a failed write only costs a restic query later.
+  }
+}

package/src/core/config.ts

@@ -7,7 +7,7 @@
  *   2. `<project-root>/.harnery/config.jsonc` — project override (authoritative)
  *
  * Fields owned here: `binName` (host CLI name for agent-facing strings),
- * `hooksSetupHint`, `agents`, `instructions`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
+ * `hooksSetupHint`, `hooks`, `agents`, `instructions`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
  * `coord` (heartbeat freshness), `logs` (structured-log storage budgets),
  * `artifacts` (working-file retention),
  * `backup` (restic repo/password/prune policy), `sync` (rclone
@@ -21,10 +21,14 @@
 
 import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { coordEnv } from "../lib/env.ts";
 import { DEFAULT_WEB_PORT } from "../lib/local-file-url.ts";
 import { resolveEventLedgerRotateActiveBytesV3 } from "./events/v3/rotation-config.ts";
+import {
+  type PromptContextConfig,
+  parsePromptContextConfig,
+} from "./hooks/prompt-context/contract.ts";
 import { findCoordRoot } from "./hooks/resolve/coord-root.ts";
 
 export { DEFAULT_WEB_PORT } from "../lib/local-file-url.ts";
@@ -73,6 +77,10 @@ interface HarneryConfig {
    * declares it here (e.g. "scripts/setup-hooks.sh"). Unset → a generic hint.
    */
   hooksSetupHint?: string;
+  /** Optional host prompt-context extension. Project config only. */
+  hooks?: {
+    promptContext?: unknown;
+  };
   /**
    * Agent-ritual policy owned by the host project. Git finalization is opt-in:
    * standalone Harnery and embedding hosts keep the ordinary status ritual
@@ -163,12 +171,18 @@ interface HarneryConfig {
     auto_clean?: boolean;
   };
   /**
-   * `harn backup` (restic) defaults: `repo` path/URL, `password_file`, and the
-   * `keep_daily`/`keep_weekly`/`keep_monthly` prune policy. Read via `backupConfig()`.
+   * `harn backup` (restic) defaults. Read via `backupConfig()`.
    */
   backup?: {
     repo?: string;
     password_file?: string;
+    include?: string[];
+    exclude?: string[];
+    max_bytes?: number;
+    schedule?: {
+      if_stale?: string;
+      tags?: string[];
+    };
     keep_daily?: number;
     keep_weekly?: number;
     keep_monthly?: number;
@@ -482,6 +496,18 @@ export function hostPromptReminder(coordRoot?: string | null): string | null {
   return reminder;
 }
 
+/**
+ * Project-owned prompt-context provider settings. The user-global config is
+ * ignored because one project's executable and data policy must not become a
+ * default for another project. Invalid values fail closed to `null`; callers
+ * treat that the same as a disabled provider and keep the prompt hook usable.
+ */
+export function hostPromptContextConfig(coordRoot?: string | null): PromptContextConfig | null {
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return null;
+  return parsePromptContextConfig(readProjectConfig(root).hooks?.promptContext);
+}
+
 /**
  * Whether the host requires the guarded Git check at the end of tool-using
  * turns. Default false: Harnery exposes `agents status --end-turn` as a capability
@@ -795,7 +821,7 @@ export function artifactMaxUnitBytes(coordRoot?: string | null): number {
 }
 
 /**
- * Whether the daily SessionStart sweep of expired artifact workspaces runs.
+ * Whether opportunistic cleanup of expired artifact workspaces runs.
  * Precedence: `HARNERY_ARTIFACT_AUTO_CLEAN` (0/false disables) ->
  * `artifacts.auto_clean` -> enabled. The sweep only ever deletes
  * `managed-expired` entries via the same guarded classifier as
@@ -826,9 +852,8 @@ export function reviewPackAutoCleanEnabled(coordRoot?: string | null): boolean {
 
 /**
  * Sweep cadence in hours. Env-only (`HARNERY_ARTIFACT_AUTO_CLEAN_INTERVAL_HOURS`,
- * mainly for tests): the cadence is an implementation detail, not policy, and
- * retention itself is quantized in whole days, so the 24h default is not a
- * config surface.
+ * mainly for tests). Session starts and new artifact work share the hourly
+ * throttle so minute-scale retention is useful within long sessions.
  */
 export function artifactAutoCleanIntervalHours(): number {
   const env = coordEnv("ARTIFACT_AUTO_CLEAN_INTERVAL_HOURS");
@@ -836,7 +861,7 @@ export function artifactAutoCleanIntervalHours(): number {
     const n = Number(env);
     if (Number.isFinite(n) && n > 0 && n <= 24 * 365) return n;
   }
-  return 24;
+  return 1;
 }
 
 function integerSetting(
@@ -869,6 +894,10 @@ function booleanSetting(
 export interface BackupConfig {
   repo: string;
   passwordFile: string;
+  include: readonly string[];
+  exclude: readonly string[];
+  maxBytes: number;
+  schedule: { ifStale: string; tags: readonly string[] } | null;
   keepDaily: number;
   keepWeekly: number;
   keepMonthly: number;
@@ -878,6 +907,7 @@ export interface BackupConfig {
  * `harn backup` (restic) defaults. Per field, precedence is env → config → built-in:
  *   repo:          `HARNERY_RESTIC_REPO` → `backup.repo` → `~/.cache/harnery/restic-repo`
  *   passwordFile:  `HARNERY_RESTIC_PASSWORD_FILE` → `backup.password_file` → `~/.config/harnery/restic-password`
+ *   include/exclude/maxBytes/schedule: `backup.*` → catalog defaults / 50 MiB / disabled
  *   keepDaily/Weekly/Monthly: `backup.keep_*` → 7 / 4 / 6
  * `coordRoot` is resolved via `findCoordRoot()` when not passed.
  */
@@ -889,13 +919,36 @@ export function backupConfig(coordRoot?: string | null): BackupConfig {
     typeof v === "string" && v.trim() ? v.trim() : undefined;
   const repo =
     coordEnv("RESTIC_REPO") ?? cfgStr(b.repo) ?? join(home, ".cache", "harnery", "restic-repo");
-  const passwordFile =
-    coordEnv("RESTIC_PASSWORD_FILE") ??
-    cfgStr(b.password_file) ??
-    join(home, ".config", "harnery", "restic-password");
+  const envPasswordFile = coordEnv("RESTIC_PASSWORD_FILE");
+  const configuredPasswordFile = cfgStr(b.password_file);
+  const passwordFile = envPasswordFile
+    ? envPasswordFile
+    : configuredPasswordFile
+      ? root && !isAbsolute(configuredPasswordFile)
+        ? resolve(root, configuredPasswordFile)
+        : configuredPasswordFile
+      : join(home, ".config", "harnery", "restic-password");
+  const stringList = (value: unknown): readonly string[] =>
+    Array.isArray(value)
+      ? value.filter(
+          (entry): entry is string => typeof entry === "string" && entry.trim().length > 0,
+        )
+      : [];
+  const schedule = isPlainObject(b.schedule)
+    ? (() => {
+        const ifStale = cfgStr(b.schedule?.if_stale);
+        return ifStale
+          ? { ifStale, tags: stringList(b.schedule?.tags).map((tag) => tag.trim()) }
+          : null;
+      })()
+    : null;
   return {
     repo,
     passwordFile,
+    include: stringList(b.include).map((entry) => entry.trim()),
+    exclude: stringList(b.exclude).map((entry) => entry.trim()),
+    maxBytes: posIntOr(b.max_bytes, 50 * 1_024 * 1_024),
+    schedule,
     keepDaily: posIntOr(b.keep_daily, 7),
     keepWeekly: posIntOr(b.keep_weekly, 4),
     keepMonthly: posIntOr(b.keep_monthly, 6),

package/src/core/diagnostics/advice.ts

@@ -1,147 +1,175 @@
-import type { SupervisorCapability, SupervisorFinding } from "../supervisor/contract.ts";
+import type { SupervisorCapability, SupervisorHistoryPoint } from "../supervisor/contract.ts";
 import {
-  DIAGNOSTIC_ADVICE_LIMITS,
   DIAGNOSTIC_ADVICE_SCHEMA_VERSION,
   type DiagnosticAdvice,
-  type DiagnosticAdviceFinding,
-  type DiagnosticAdviceReason,
+  PRESSURE_ASSESSMENT_SCHEMA_VERSION,
+  PRESSURE_POLICY,
+  type PressureAssessment,
+  type PressureDimension,
+  type PressureEvidenceDimension,
+  type PressureHysteresisState,
+  type PressureReason,
+  type PressureReasonCode,
+  type PressureScope,
+  type PressureWorkloadGuidance,
 } from "./contract.ts";
+import type { PressureHistorySample } from "./pressure-contract.ts";
 
+/**
+ * Advice is an envelope around one already-computed assessment. It maps
+ * nothing: severity does not become pressure here, and no numeric threshold is
+ * read. `assessPressure` owns the judgement, the observer publishes it, and
+ * every surface renders this envelope so all of them agree.
+ */
 export interface BuildDiagnosticAdviceInput {
-  findings: readonly SupervisorFinding[];
+  assessment: PressureAssessment;
+  /** The state the previous sample carried forward, so a replay can reproduce a transition. */
+  priorHysteresis: PressureHysteresisState | null;
+  /** Where the assessment came from, and why it is missing when it is. */
   sourceCapability: SupervisorCapability;
+  activeFindingCount: number;
   evaluatedAt: string;
 }
 
-const SEVERITY_RANK: Readonly<Record<SupervisorFinding["severity"], number>> = {
-  info: 0,
-  warning: 1,
-  critical: 2,
-};
-
 export function buildDiagnosticAdvice(input: BuildDiagnosticAdviceInput): DiagnosticAdvice {
-  const sourceAvailable = input.sourceCapability.state === "supported";
-  const active = sourceAvailable
-    ? input.findings.filter((finding) => finding.state === "opened").sort(compareFindings)
-    : [];
-  const pressureFindings = active.filter(
-    (finding): finding is SupervisorFinding & { severity: "warning" | "critical" } =>
-      finding.severity === "warning" || finding.severity === "critical",
-  );
-  const critical = pressureFindings.filter((finding) => finding.severity === "critical");
-  const warning = pressureFindings.filter((finding) => finding.severity === "warning");
-  const pressure = critical.length
-    ? "critical"
-    : warning.length
-      ? "elevated"
-      : sourceAvailable
-        ? "normal"
-        : "unknown";
-  const fanOutRecommendation =
-    pressure === "critical"
-      ? "avoid-new-fan-out"
-      : pressure === "elevated"
-        ? "use-caution"
-        : pressure === "normal"
-          ? "proceed"
-          : "unknown";
-  const contributing = pressureFindings.slice(
-    0,
-    DIAGNOSTIC_ADVICE_LIMITS.max_contributing_findings,
-  );
   return {
     schema_version: DIAGNOSTIC_ADVICE_SCHEMA_VERSION,
     evaluated_at: input.evaluatedAt,
-    pressure,
-    fan_out_recommendation: fanOutRecommendation,
     observer_only: true,
-    summary: summaryFor(pressure),
+    assessment: input.assessment,
+    prior_hysteresis: input.priorHysteresis,
     source_capability: input.sourceCapability,
-    active_finding_count: active.length,
-    contributing_finding_count: pressureFindings.length,
-    omitted_contributing_finding_count: Math.max(0, pressureFindings.length - contributing.length),
-    contributing_findings: contributing.map(adviceFinding),
-    reasons: reasonsFor(critical, warning, input.sourceCapability),
+    active_finding_count: Math.max(0, Math.trunc(input.activeFindingCount)),
+    summary: input.assessment.summary,
   };
 }
 
-function adviceFinding(
-  finding: SupervisorFinding & { severity: "warning" | "critical" },
-): DiagnosticAdviceFinding {
-  return {
-    finding_id: finding.id,
-    finding_kind: finding.finding_kind,
-    severity: finding.severity,
-    summary: finding.summary,
-    scope_kind: finding.scope_kind,
-    scope_id: finding.scope_id,
-    occurrence_count: finding.occurrence_count,
-    owner_kind: finding.attribution?.owner_kind,
-    owner_id: finding.attribution?.owner_id,
-    workload_relationship: finding.workload_context?.relationship,
-  };
-}
+export const PRESSURE_DIMENSIONS: readonly PressureDimension[] = [
+  "memory_stall",
+  "io_stall",
+  "cpu_stall",
+  "oom_kills",
+  "swap_activity",
+  "direct_reclaim",
+  "memory_available",
+  "disk_available",
+  "host_memory",
+];
 
-function reasonsFor(
-  critical: readonly SupervisorFinding[],
-  warning: readonly SupervisorFinding[],
-  capability: SupervisorCapability,
-): DiagnosticAdviceReason[] {
-  const reasons: DiagnosticAdviceReason[] = [];
-  if (critical.length) {
-    reasons.push({
-      code: "critical_findings_active",
-      summary: `${critical.length} active critical finding${critical.length === 1 ? "" : "s"} ${critical.length === 1 ? "requires" : "require"} attention.`,
-      finding_ids: boundedIds(critical),
-    });
-  }
-  if (warning.length) {
-    reasons.push({
-      code: "warning_findings_active",
-      summary: `${warning.length} active warning finding${warning.length === 1 ? "" : "s"} ${warning.length === 1 ? "indicates" : "indicate"} elevated pressure.`,
-      finding_ids: boundedIds(warning),
-    });
-  }
-  if (capability.state !== "supported") {
-    reasons.push({
-      code: "findings_source_unavailable",
-      summary: `The findings source is ${capability.state}${capability.reason_code ? ` (${capability.reason_code})` : ""}.`,
-      finding_ids: [],
-    });
-  }
-  if (!critical.length && !warning.length && capability.state === "supported") {
-    reasons.push({
-      code: "no_active_pressure_findings",
-      summary: "No active warning or critical findings were observed.",
-      finding_ids: [],
-    });
-  }
-  return reasons.slice(0, DIAGNOSTIC_ADVICE_LIMITS.max_reasons);
+export interface UnknownPressureAssessmentInput {
+  observedAt: string;
+  /** A stable code from the frozen union, normally `evidence_unavailable` or `snapshot_stale`. */
+  reasonCode: PressureReasonCode;
+  /** One plain sentence naming what is missing. Becomes the assessment summary. */
+  summary: string;
+  scope?: PressureScope;
+  sampleAgeMs?: number | null;
+  prior?: PressureHysteresisState | null;
+  observerGeneration?: string | null;
 }
 
-function boundedIds(findings: readonly SupervisorFinding[]): string[] {
-  return findings
-    .slice(0, DIAGNOSTIC_ADVICE_LIMITS.max_contributing_findings)
-    .map((finding) => finding.id);
+/**
+ * The assessment to publish when the source is absent, stale, or malformed.
+ * Every dimension reads `unavailable` and no owner is named, because a gap in
+ * the evidence is not a measurement of health.
+ */
+export function unknownPressureAssessment(
+  input: UnknownPressureAssessmentInput,
+): PressureAssessment {
+  const reason: PressureReason = {
+    code: input.reasonCode,
+    dimension: null,
+    summary: input.summary,
+    observed_value: null,
+    threshold_value: null,
+    unit: null,
+    sample_count: 0,
+    contributes_to: "unknown",
+  };
+  return {
+    schema_version: PRESSURE_ASSESSMENT_SCHEMA_VERSION,
+    observer_only: true,
+    state: "unknown",
+    scope: input.scope ?? "native",
+    limiting_resource: "unknown",
+    trend: "unknown",
+    observed_at: input.observedAt,
+    sample_age_ms: input.sampleAgeMs ?? null,
+    evidence_state: "unavailable",
+    evidence: PRESSURE_DIMENSIONS.map(
+      (dimension): PressureEvidenceDimension => ({
+        dimension,
+        state: "unavailable",
+        observed_value: null,
+        unit: null,
+        sample_count: 0,
+        reason_code: input.reasonCode,
+      }),
+    ).slice(0, PRESSURE_POLICY.limits.max_evidence),
+    reasons: [reason],
+    contributors: [],
+    omitted_contributor_count: 0,
+    unattributed_memory_percent: null,
+    recommended_action: "unknown",
+    summary: input.summary,
+    guidance: unknownGuidance(),
+    hysteresis: {
+      state: "unknown",
+      state_since: input.observedAt,
+      consecutive_clear_samples: 0,
+      dimension_streaks: {},
+      oom_baseline_total_kills: input.prior?.oom_baseline_total_kills ?? null,
+      oom_hold_until: null,
+      observer_generation: input.observerGeneration ?? input.prior?.observer_generation ?? null,
+    },
+    policy_version: PRESSURE_POLICY.policy_version,
+  };
 }
 
-function summaryFor(pressure: DiagnosticAdvice["pressure"]): string {
-  switch (pressure) {
-    case "critical":
-      return "Critical local pressure is active. Avoid starting additional agent work until the findings change.";
-    case "elevated":
-      return "Elevated local pressure is active. Limit new fan-out and inspect the contributing findings.";
-    case "normal":
-      return "No active warning or critical findings were observed. Diagnostics do not restrict new fan-out.";
-    case "unknown":
-      return "Local pressure cannot be determined because the findings source is unavailable.";
-  }
+function unknownGuidance(): PressureWorkloadGuidance[] {
+  return [
+    {
+      workload_class: "lightweight",
+      recommendation: "unknown",
+      summary:
+        "Reads and small edits cost almost nothing, so continue them while the measurements are missing.",
+    },
+    {
+      workload_class: "cpu-heavy",
+      recommendation: "unknown",
+      summary:
+        "Builds and test runs cannot be judged from here. Start one only if you already know the machine is idle.",
+    },
+    {
+      workload_class: "memory-heavy",
+      recommendation: "unknown",
+      summary:
+        "Browser captures and page QA cannot be judged from here. Run one at a time until the measurements return.",
+    },
+    {
+      workload_class: "storage-heavy",
+      recommendation: "unknown",
+      summary:
+        "Large writes and exports cannot be judged from here. Check free disk space yourself before starting one.",
+    },
+  ];
 }
 
-function compareFindings(left: SupervisorFinding, right: SupervisorFinding): number {
-  return (
-    SEVERITY_RANK[right.severity] - SEVERITY_RANK[left.severity] ||
-    right.observed_at.localeCompare(left.observed_at) ||
-    left.id.localeCompare(right.id)
-  );
+/**
+ * Project bounded supervisor history into the trend input the assessment reads.
+ * The observer and a bundle replay both call this, so the trend they compute
+ * from the same stored history is the same trend.
+ */
+export function pressureHistoryFromSupervisor(
+  points: readonly SupervisorHistoryPoint[],
+): PressureHistorySample[] {
+  return points.slice(-PRESSURE_POLICY.max_history_samples).map((point) => ({
+    sampled_at: point.sampled_at,
+    memory_full_avg10: point.pressure.memory_full_avg10,
+    io_full_avg10: point.pressure.io_full_avg10,
+    cpu_some_avg60: point.pressure.cpu_some_avg60,
+    memory_available_percent:
+      point.machine.memory_percent === null ? null : 100 - point.machine.memory_percent,
+    swap_out_bytes_per_second: point.pressure.swap_out_bytes_per_second,
+  }));
 }