harnery 0.36.0 → 0.38.0

package/dist/core/config.js

@@ -473,6 +473,20 @@ export function eventLedgerRotateActiveBytes(coordRoot) {
     const root = coordRoot ?? findCoordRoot();
     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;
+/** Bounded retention for closed V3 epochs under `ledgers/v3-archives`. */
+export function eventLedgerArchivePolicy(coordRoot) {
+    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, source) {
     const port = typeof value === "number" ? value : Number(value);
     if (!Number.isInteger(port) || port < 1024 || port > 65535) {
@@ -540,6 +554,18 @@ export function artifactDefaultRetentionDays(coordRoot) {
         ? configured
         : 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) {
+    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) {
+    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) ->
@@ -556,6 +582,22 @@ export function artifactAutoCleanEnabled(coordRoot) {
         return true;
     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) {
+    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
@@ -571,6 +613,23 @@ export function artifactAutoCleanIntervalHours() {
     }
     return 24;
 }
+function integerSetting(envValue, configured, minimum, maximum, fallback) {
+    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, configured, fallback) {
+    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;
+}
 /**
  * `harn backup` (restic) defaults. Per field, precedence is env → config → built-in:
  *   repo:          `HARNERY_RESTIC_REPO` → `backup.repo` → `~/.cache/harnery/restic-repo`

package/dist/core/diagnostics/advice.d.ts

@@ -0,0 +1,9 @@
+import type { SupervisorCapability, SupervisorFinding } from "../supervisor/contract.js";
+import { type DiagnosticAdvice } from "./contract.js";
+export interface BuildDiagnosticAdviceInput {
+    findings: readonly SupervisorFinding[];
+    sourceCapability: SupervisorCapability;
+    evaluatedAt: string;
+}
+export declare function buildDiagnosticAdvice(input: BuildDiagnosticAdviceInput): DiagnosticAdvice;
+//# sourceMappingURL=advice.d.ts.map

package/dist/core/diagnostics/advice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advice.d.ts","sourceRoot":"","sources":["../../../src/core/diagnostics/advice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,EAGL,KAAK,gBAAgB,EAGtB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,gBAAgB,EAAE,oBAAoB,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;CACrB;AAQD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,gBAAgB,CA4CzF"}

package/dist/core/diagnostics/advice.js

@@ -0,0 +1,112 @@
+import { DIAGNOSTIC_ADVICE_LIMITS, DIAGNOSTIC_ADVICE_SCHEMA_VERSION, } from "./contract.js";
+const SEVERITY_RANK = {
+    info: 0,
+    warning: 1,
+    critical: 2,
+};
+export function buildDiagnosticAdvice(input) {
+    const sourceAvailable = input.sourceCapability.state === "supported";
+    const active = sourceAvailable
+        ? input.findings.filter((finding) => finding.state === "opened").sort(compareFindings)
+        : [];
+    const pressureFindings = active.filter((finding) => 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) {
+    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, warning, capability) {
+    const reasons = [];
+    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) {
+    return findings
+        .slice(0, DIAGNOSTIC_ADVICE_LIMITS.max_contributing_findings)
+        .map((finding) => finding.id);
+}
+function summaryFor(pressure) {
+    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, right) {
+    return (SEVERITY_RANK[right.severity] - SEVERITY_RANK[left.severity] ||
+        right.observed_at.localeCompare(left.observed_at) ||
+        left.id.localeCompare(right.id));
+}

package/dist/core/diagnostics/bundle.d.ts

@@ -0,0 +1,51 @@
+import type { ArtifactActor, ArtifactInventoryEntry } from "../artifacts/index.js";
+import { type DiagnosticBundleManifest, type DiagnosticReplayResult, type DiagnosticSummary, type ValidatedDiagnosticBundle } from "./contract.js";
+export interface CaptureDiagnosticBundleInput {
+    findingId?: string;
+    startAt?: string;
+    endAt?: string;
+    actor?: ArtifactActor;
+    retentionDays?: number;
+    now?: Date;
+    machineLabel?: string;
+    engineVersion?: string;
+}
+export interface CapturedDiagnosticBundle {
+    path: string;
+    manifest: DiagnosticBundleManifest;
+    summary: DiagnosticSummary;
+}
+export interface DiagnosticBundleListRow {
+    artifact_id: string;
+    created_at: string;
+    expires_at: string | null;
+    classification: ArtifactInventoryEntry["classification"];
+    valid: boolean;
+    captured_at?: string;
+    finding_id?: string;
+    error?: string;
+}
+export interface DiagnosticBundleCandidateRow {
+    artifact_id: string;
+    created_at: string;
+    expires_at: string | null;
+    classification: ArtifactInventoryEntry["classification"];
+    selectable: boolean;
+    captured_at?: string;
+    finding_id?: string;
+    error?: string;
+}
+export declare function captureDiagnosticBundle(repoRootRaw: string, input?: CaptureDiagnosticBundleInput): CapturedDiagnosticBundle;
+export declare function validateDiagnosticBundle(repoRootRaw: string, ref: string): ValidatedDiagnosticBundle;
+/** Frozen web readers accept an opaque artifact id, never a filesystem path. */
+export declare function readFrozenDiagnosticBundle(repoRoot: string, artifactId: string): ValidatedDiagnosticBundle;
+export declare function showDiagnosticBundle(repoRoot: string, ref: string): ValidatedDiagnosticBundle;
+export declare function listDiagnosticBundles(repoRoot: string): DiagnosticBundleListRow[];
+/**
+ * Lists managed bundle candidates without opening their bounded payloads.
+ * Selection is not authority: every show, replay, and comparison operation
+ * still performs complete digest and schema validation before returning data.
+ */
+export declare function listDiagnosticBundleCandidates(repoRoot: string): DiagnosticBundleCandidateRow[];
+export declare function replayDiagnosticBundle(repoRoot: string, ref: string, now?: Date): DiagnosticReplayResult;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/core/diagnostics/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../../src/core/diagnostics/bundle.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,aAAa,EACb,sBAAsB,EAEvB,MAAM,uBAAuB,CAAC;AAwB/B,OAAO,EAUL,KAAK,wBAAwB,EAG7B,KAAK,sBAAsB,EAE3B,KAAK,iBAAiB,EAEtB,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AA0BvB,MAAM,WAAW,4BAA4B;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,wBAAwB,CAAC;IACnC,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,4BAA4B;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IACzD,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,4BAAiC,GACvC,wBAAwB,CAqG1B;AAkCD,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GACV,yBAAyB,CAsB3B;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,yBAAyB,CAK3B;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,yBAAyB,CAE7F;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,uBAAuB,EAAE,CA0BjF;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,4BAA4B,EAAE,CA4C/F;AAqCD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,OAAa,GACf,sBAAsB,CAgBxB"}