harnery 0.36.0 → 0.38.0

package/src/core/config.ts

@@ -137,12 +137,31 @@ interface HarneryConfig {
    * (default 32 MiB; `0` disables rotation). Read via
    * `eventLedgerRotateActiveBytes()`.
    */
-  events?: { rotate_active_bytes?: number };
+  events?: {
+    rotate_active_bytes?: number;
+    archive_max_bytes?: number;
+    archive_max_age_days?: number;
+    archive_keep_min?: number;
+    archive_auto_clean?: boolean;
+  };
   /**
    * Managed working-artifact defaults. `default_retention_days` is the
    * create-time TTL when the caller does not pass `artifacts create --days`.
    */
-  artifacts?: { default_retention_days?: number; auto_clean?: boolean };
+  artifacts?: {
+    default_retention_days?: number;
+    auto_clean?: boolean;
+    max_bytes?: number;
+    max_unit_bytes?: number;
+  };
+  /**
+   * Page review packs. `auto_clean` lets `qa-run` and `review-pack create`
+   * delete expired packs in the artifact store before they start. Read via
+   * `reviewPackAutoCleanEnabled()`; ships off.
+   */
+  review_pack?: {
+    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()`.
@@ -622,6 +641,51 @@ export function eventLedgerRotateActiveBytes(coordRoot?: string | null): number
   return resolveEventLedgerRotateActiveBytesV3(root);
 }
 
+const DEFAULT_EVENT_ARCHIVE_MAX_BYTES = 1024 * 1024 * 1024;
+const DEFAULT_EVENT_ARCHIVE_MAX_AGE_DAYS = 7;
+const DEFAULT_EVENT_ARCHIVE_KEEP_MIN = 2;
+
+export interface EventLedgerArchivePolicy {
+  maxBytes: number;
+  maxAgeDays: number;
+  keepMin: number;
+  autoClean: boolean;
+}
+
+/** Bounded retention for closed V3 epochs under `ledgers/v3-archives`. */
+export function eventLedgerArchivePolicy(coordRoot?: string | null): EventLedgerArchivePolicy {
+  const root = coordRoot ?? findCoordRoot();
+  const configured = root ? readConfig(root).events : undefined;
+  return {
+    maxBytes: integerSetting(
+      coordEnv("EVENT_V3_ARCHIVE_MAX_BYTES"),
+      configured?.archive_max_bytes,
+      64 * 1024 * 1024,
+      1024 * 1024 * 1024 * 1024,
+      DEFAULT_EVENT_ARCHIVE_MAX_BYTES,
+    ),
+    maxAgeDays: integerSetting(
+      coordEnv("EVENT_V3_ARCHIVE_MAX_AGE_DAYS"),
+      configured?.archive_max_age_days,
+      1,
+      3650,
+      DEFAULT_EVENT_ARCHIVE_MAX_AGE_DAYS,
+    ),
+    keepMin: integerSetting(
+      coordEnv("EVENT_V3_ARCHIVE_KEEP_MIN"),
+      configured?.archive_keep_min,
+      1,
+      1000,
+      DEFAULT_EVENT_ARCHIVE_KEEP_MIN,
+    ),
+    autoClean: booleanSetting(
+      coordEnv("EVENT_V3_ARCHIVE_AUTO_CLEAN"),
+      configured?.archive_auto_clean,
+      true,
+    ),
+  };
+}
+
 function parseWebPort(value: unknown, source: string): number {
   const port = typeof value === "number" ? value : Number(value);
   if (!Number.isInteger(port) || port < 1024 || port > 65535) {
@@ -703,6 +767,33 @@ export function artifactDefaultRetentionDays(coordRoot?: string | null): number
     : 3;
 }
 
+const DEFAULT_ARTIFACT_MAX_BYTES = 20 * 1024 * 1024 * 1024;
+const DEFAULT_ARTIFACT_MAX_UNIT_BYTES = 1024 * 1024 * 1024;
+
+/** Soft repository budget for managed working artifacts. */
+export function artifactMaxBytes(coordRoot?: string | null): number {
+  const root = coordRoot ?? findCoordRoot();
+  return integerSetting(
+    coordEnv("ARTIFACT_MAX_BYTES"),
+    root ? readConfig(root).artifacts?.max_bytes : undefined,
+    64 * 1024 * 1024,
+    1024 * 1024 * 1024 * 1024,
+    DEFAULT_ARTIFACT_MAX_BYTES,
+  );
+}
+
+/** Size at which one bundle requires an explicit `artifacts create --big` acknowledgement. */
+export function artifactMaxUnitBytes(coordRoot?: string | null): number {
+  const root = coordRoot ?? findCoordRoot();
+  return integerSetting(
+    coordEnv("ARTIFACT_MAX_UNIT_BYTES"),
+    root ? readConfig(root).artifacts?.max_unit_bytes : undefined,
+    16 * 1024 * 1024,
+    1024 * 1024 * 1024 * 1024,
+    DEFAULT_ARTIFACT_MAX_UNIT_BYTES,
+  );
+}
+
 /**
  * Whether the daily SessionStart sweep of expired artifact workspaces runs.
  * Precedence: `HARNERY_ARTIFACT_AUTO_CLEAN` (0/false disables) ->
@@ -718,6 +809,21 @@ export function artifactAutoCleanEnabled(coordRoot?: string | null): boolean {
   return readConfig(root).artifacts?.auto_clean !== false;
 }
 
+/**
+ * Whether `qa-run` and `review-pack create` sweep expired page review packs
+ * out of the artifact store before starting. Precedence:
+ * `HARNERY_REVIEW_PACK_AUTO_CLEAN` (1/true enables, 0/false disables) ->
+ * `review_pack.auto_clean` -> disabled. The sweep deletes only packs whose
+ * manifest says `managed: true` with `retention.expires_at` in the past.
+ */
+export function reviewPackAutoCleanEnabled(coordRoot?: string | null): boolean {
+  const env = coordEnv("REVIEW_PACK_AUTO_CLEAN");
+  if (env !== undefined) return env === "1" || env.toLowerCase() === "true";
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return false;
+  return readConfig(root).review_pack?.auto_clean === true;
+}
+
 /**
  * Sweep cadence in hours. Env-only (`HARNERY_ARTIFACT_AUTO_CLEAN_INTERVAL_HOURS`,
  * mainly for tests): the cadence is an implementation detail, not policy, and
@@ -733,6 +839,32 @@ export function artifactAutoCleanIntervalHours(): number {
   return 24;
 }
 
+function integerSetting(
+  envValue: string | undefined,
+  configured: unknown,
+  minimum: number,
+  maximum: number,
+  fallback: number,
+): number {
+  for (const value of [envValue, configured]) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (Number.isSafeInteger(parsed) && parsed >= minimum && parsed <= maximum) return parsed;
+  }
+  return fallback;
+}
+
+function booleanSetting(
+  envValue: string | undefined,
+  configured: unknown,
+  fallback: boolean,
+): boolean {
+  if (envValue !== undefined) {
+    if (envValue === "1" || envValue.toLowerCase() === "true") return true;
+    if (envValue === "0" || envValue.toLowerCase() === "false") return false;
+  }
+  return typeof configured === "boolean" ? configured : fallback;
+}
+
 /** Resolved `harn backup` defaults (restic repo/password + prune policy). */
 export interface BackupConfig {
   repo: string;

package/src/core/diagnostics/advice.ts

@@ -0,0 +1,147 @@
+import type { SupervisorCapability, SupervisorFinding } from "../supervisor/contract.ts";
+import {
+  DIAGNOSTIC_ADVICE_LIMITS,
+  DIAGNOSTIC_ADVICE_SCHEMA_VERSION,
+  type DiagnosticAdvice,
+  type DiagnosticAdviceFinding,
+  type DiagnosticAdviceReason,
+} from "./contract.ts";
+
+export interface BuildDiagnosticAdviceInput {
+  findings: readonly SupervisorFinding[];
+  sourceCapability: SupervisorCapability;
+  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),
+    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),
+  };
+}
+
+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,
+  };
+}
+
+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);
+}
+
+function boundedIds(findings: readonly SupervisorFinding[]): string[] {
+  return findings
+    .slice(0, DIAGNOSTIC_ADVICE_LIMITS.max_contributing_findings)
+    .map((finding) => finding.id);
+}
+
+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 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)
+  );
+}