harnery 0.36.0 → 0.37.0

package/src/core/supervisor/history.ts

@@ -0,0 +1,61 @@
+import type { ResourceSnapshot } from "../resources/contract.ts";
+import {
+  SUPERVISOR_HISTORY_SCHEMA_VERSION,
+  type SupervisorHistory,
+  type SupervisorHistoryPoint,
+} from "./contract.ts";
+
+export const SUPERVISOR_HISTORY_INTERVAL_MS = 10_000;
+export const SUPERVISOR_HISTORY_MAX_POINTS = 90;
+
+export function updateSupervisorHistory(
+  previous: SupervisorHistory | undefined,
+  resource: ResourceSnapshot,
+): { history: SupervisorHistory; changed: boolean } {
+  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: SupervisorHistoryPoint = {
+    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: SupervisorHistory | undefined): value is SupervisorHistory {
+  return (
+    value?.schema_version === SUPERVISOR_HISTORY_SCHEMA_VERSION &&
+    Array.isArray(value.points) &&
+    value.points.length <= SUPERVISOR_HISTORY_MAX_POINTS
+  );
+}

package/src/core/supervisor/hook-health-alerts.ts

@@ -0,0 +1,108 @@
+import type { SupervisorFindingEvidence, SupervisorFindingSeverity } from "./contract.ts";
+import {
+  type CompletedHookHealth,
+  type HookHealthAggregate,
+  SUPERVISOR_HIGH_COMPLETED_HOOK_RSS_BYTES,
+  SUPERVISOR_HOOK_RETRY_CLUSTER_COUNT,
+  SUPERVISOR_SLOW_COMPLETED_HOOK_MS,
+  type SupervisorHookHealth,
+} from "./hook-health.ts";
+
+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 function evaluateHookHealthAlerts(health: SupervisorHookHealth): readonly HookHealthAlert[] {
+  if (health.capability.state === "unavailable") return [];
+  const alerts: HookHealthAlert[] = [];
+  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: HookHealthAggregate,
+  receipt: CompletedHookHealth,
+): HookHealthAlert {
+  const severity: SupervisorFindingSeverity =
+    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: readonly CompletedHookHealth[],
+  value: (receipt: CompletedHookHealth) => number,
+): CompletedHookHealth | undefined {
+  return receipts.reduce<CompletedHookHealth | undefined>(
+    (current, receipt) => (!current || value(receipt) > value(current) ? receipt : current),
+    undefined,
+  );
+}

package/src/core/supervisor/hook-health-storage.ts

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

package/src/core/supervisor/hook-health.ts

@@ -0,0 +1,301 @@
+import {
+  HOOK_HEALTH_EVENT,
+  HOOK_HEALTH_RECEIPT_VERSION,
+  type HookHealthOutcome,
+} from "../hooks/health.ts";
+import type { HarneryLogRecordV1 } from "../storage/jsonl.ts";
+import type { SupervisorLogFeed } from "./contract.ts";
+
+export const SUPERVISOR_HOOK_HEALTH_SCHEMA_VERSION = 1 as const;
+export const SUPERVISOR_HOOK_HEALTH_RECENT_LIMIT = 50;
+export const SUPERVISOR_HOOK_HEALTH_AGGREGATE_LIMIT = 40;
+export const SUPERVISOR_SLOW_COMPLETED_HOOK_MS = 30_000;
+export const SUPERVISOR_HIGH_COMPLETED_HOOK_RSS_BYTES = 512 * 1024 * 1024;
+export const SUPERVISOR_HOOK_RETRY_CLUSTER_COUNT = 3;
+export const SUPERVISOR_HOOK_RETRY_CLUSTER_WINDOW_MS = 5 * 60_000;
+
+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 function projectHookHealth(feed: SupervisorLogFeed, now = new Date()): SupervisorHookHealth {
+  const lane = feed.lanes.find((candidate) => candidate.family_id === "agent-hook-debug-log");
+  if (!lane) return unavailable(now, "hook-log-family-not-visible");
+  if (lane.error) return unavailable(now, "hook-log-family-unavailable");
+
+  const parsed: CompletedHookHealth[] = [];
+  let malformed = 0;
+  for (const record of lane.records) {
+    if (record.event !== HOOK_HEALTH_EVENT) continue;
+    const receipt = parseCompletedHookHealth(record);
+    if (receipt) parsed.push(receipt);
+    else malformed += 1;
+  }
+  parsed.sort((left, right) => Date.parse(right.observed_at) - Date.parse(left.observed_at));
+  const recent = parsed.slice(0, SUPERVISOR_HOOK_HEALTH_RECENT_LIMIT);
+  const aggregates = aggregateHookHealth(parsed).slice(0, SUPERVISOR_HOOK_HEALTH_AGGREGATE_LIMIT);
+  const retryCutoff = now.getTime() - SUPERVISOR_HOOK_RETRY_CLUSTER_WINDOW_MS;
+  return {
+    schema_version: SUPERVISOR_HOOK_HEALTH_SCHEMA_VERSION,
+    captured_at: now.toISOString(),
+    capability: {
+      source_kind: "hook.terminal-log",
+      state: lane.truncated || malformed > 0 ? "partial" : "supported",
+      ...(lane.truncated
+        ? { reason: "bounded-log-window-truncated" }
+        : malformed > 0
+          ? { reason: "malformed-terminal-records-ignored" }
+          : {}),
+    },
+    source_record_count: parsed.length,
+    malformed_record_count: malformed,
+    truncated: lane.truncated || parsed.length > SUPERVISOR_HOOK_HEALTH_RECENT_LIMIT,
+    summary: {
+      invocation_count: parsed.length,
+      degraded_count: parsed.filter((receipt) => receipt.outcome === "degraded").length,
+      faulted_count: parsed.filter((receipt) => receipt.outcome === "faulted").length,
+      slow_count: parsed.filter(
+        (receipt) => receipt.duration_ms >= SUPERVISOR_SLOW_COMPLETED_HOOK_MS,
+      ).length,
+      high_memory_count: parsed.filter(
+        (receipt) => receipt.rss_end_bytes >= SUPERVISOR_HIGH_COMPLETED_HOOK_RSS_BYTES,
+      ).length,
+      retry_count: parsed.filter(
+        (receipt) => receipt.retry_worker && Date.parse(receipt.observed_at) >= retryCutoff,
+      ).length,
+    },
+    aggregates,
+    recent,
+  };
+}
+
+export function parseCompletedHookHealth(
+  record: HarneryLogRecordV1,
+): CompletedHookHealth | undefined {
+  if (
+    record.kind !== "record" ||
+    record.component_id !== "agent-hook" ||
+    record.event !== HOOK_HEALTH_EVENT ||
+    record.fields.receipt_version !== HOOK_HEALTH_RECEIPT_VERSION ||
+    record.fields.exit_contract !== "always-zero" ||
+    record.fields.exit_code !== 0
+  ) {
+    return undefined;
+  }
+  const hookName = token(record.fields.hook_name);
+  const adapter = adapterValue(record.fields.adapter);
+  const outcome = outcomeValue(record.fields.outcome);
+  const duration = integer(record.fields.duration_ms);
+  const rssStart = integer(record.fields.rss_start_bytes);
+  const rssEnd = integer(record.fields.rss_end_bytes);
+  const rssDelta = signedInteger(record.fields.rss_delta_bytes);
+  const payloadBytes = integer(record.fields.payload_bytes);
+  const pid = integer(record.fields.pid);
+  const errorCount = integer(record.fields.error_count);
+  const retryWorker = record.fields.retry_worker;
+  const errorPhases = tokenArray(record.fields.error_phases);
+  if (
+    !hookName ||
+    !adapter ||
+    !outcome ||
+    duration === undefined ||
+    rssStart === undefined ||
+    rssEnd === undefined ||
+    rssDelta === undefined ||
+    payloadBytes === undefined ||
+    pid === undefined ||
+    errorCount === undefined ||
+    typeof retryWorker !== "boolean" ||
+    !errorPhases ||
+    !Number.isFinite(Date.parse(record.emitted_at))
+  ) {
+    return undefined;
+  }
+  return {
+    id: `${record.writer_id}:${record.writer_seq}`,
+    observed_at: record.emitted_at,
+    hook_name: hookName,
+    adapter,
+    outcome,
+    duration_ms: duration,
+    rss_start_bytes: rssStart,
+    rss_end_bytes: rssEnd,
+    rss_delta_bytes: rssDelta,
+    retry_worker: retryWorker,
+    error_count: errorCount,
+    error_phases: errorPhases,
+    payload_bytes: payloadBytes,
+    pid,
+    ...optionalToken("owner_id", record.fields.owner_id),
+    ...optionalToken("skipped_reason", record.fields.skipped_reason),
+    ...optionalToken("v3_state", record.fields.v3_state),
+  };
+}
+
+function aggregateHookHealth(receipts: readonly CompletedHookHealth[]): HookHealthAggregate[] {
+  const grouped = new Map<string, CompletedHookHealth[]>();
+  for (const receipt of receipts) {
+    const key = `${receipt.adapter}:${receipt.hook_name}`;
+    const group = grouped.get(key) ?? [];
+    group.push(receipt);
+    grouped.set(key, group);
+  }
+  return [...grouped.entries()]
+    .map(([key, group]) => {
+      const durations = group.map((receipt) => receipt.duration_ms).sort((a, b) => a - b);
+      return {
+        key,
+        hook_name: group[0]!.hook_name,
+        adapter: group[0]!.adapter,
+        invocation_count: group.length,
+        completed_count: countOutcome(group, "completed"),
+        skipped_count: countOutcome(group, "skipped"),
+        degraded_count: countOutcome(group, "degraded"),
+        faulted_count: countOutcome(group, "faulted"),
+        retry_count: group.filter((receipt) => receipt.retry_worker).length,
+        duration_p50_ms: percentile(durations, 0.5),
+        duration_p95_ms: percentile(durations, 0.95),
+        duration_max_ms: durations.at(-1) ?? 0,
+        rss_end_max_bytes: Math.max(...group.map((receipt) => receipt.rss_end_bytes)),
+        rss_delta_max_bytes: Math.max(...group.map((receipt) => receipt.rss_delta_bytes)),
+        latest_observed_at: group[0]!.observed_at,
+        owner_ids: [...new Set(group.flatMap((receipt) => receipt.owner_id ?? []))].slice(0, 8),
+      };
+    })
+    .sort(
+      (left, right) =>
+        Date.parse(right.latest_observed_at) - Date.parse(left.latest_observed_at) ||
+        left.key.localeCompare(right.key),
+    );
+}
+
+function countOutcome(
+  receipts: readonly CompletedHookHealth[],
+  outcome: HookHealthOutcome,
+): number {
+  return receipts.filter((receipt) => receipt.outcome === outcome).length;
+}
+
+function percentile(sorted: readonly number[], fraction: number): number {
+  if (sorted.length === 0) return 0;
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * fraction) - 1))]!;
+}
+
+function unavailable(now: Date, reason: string): SupervisorHookHealth {
+  return {
+    schema_version: SUPERVISOR_HOOK_HEALTH_SCHEMA_VERSION,
+    captured_at: now.toISOString(),
+    capability: { source_kind: "hook.terminal-log", state: "unavailable", reason },
+    source_record_count: 0,
+    malformed_record_count: 0,
+    truncated: false,
+    summary: {
+      invocation_count: 0,
+      degraded_count: 0,
+      faulted_count: 0,
+      slow_count: 0,
+      high_memory_count: 0,
+      retry_count: 0,
+    },
+    aggregates: [],
+    recent: [],
+  };
+}
+
+function token(value: unknown): string | undefined {
+  return typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(value)
+    ? value
+    : undefined;
+}
+
+function adapterValue(value: unknown): CompletedHookHealth["adapter"] | undefined {
+  return value === "claude-code" || value === "codex" || value === "cursor" || value === "unknown"
+    ? value
+    : undefined;
+}
+
+function outcomeValue(value: unknown): HookHealthOutcome | undefined {
+  return value === "completed" || value === "skipped" || value === "degraded" || value === "faulted"
+    ? value
+    : undefined;
+}
+
+function integer(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function signedInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) ? value : undefined;
+}
+
+function tokenArray(value: unknown): readonly string[] | undefined {
+  return Array.isArray(value) && value.length <= 8 && value.every((item) => token(item))
+    ? (value as string[])
+    : undefined;
+}
+
+function optionalToken<Key extends "owner_id" | "skipped_reason" | "v3_state">(
+  key: Key,
+  value: unknown,
+): Partial<Record<Key, string>> {
+  const parsed = token(value);
+  return parsed ? ({ [key]: parsed } as Partial<Record<Key, string>>) : {};
+}

package/src/core/supervisor/hooks.ts

@@ -0,0 +1,35 @@
+import type { ResourceSnapshot } from "../resources/contract.ts";
+import type { ObservedHookHealth } from "./contract.ts";
+
+export const SUPERVISOR_LONG_HOOK_SECONDS = 120;
+
+/**
+ * Command text may label a process only after PID ancestry proved its agent
+ * owner. It never establishes ownership by itself.
+ */
+export function collectHookHealth(resource: ResourceSnapshot): ObservedHookHealth[] {
+  return resource.processes
+    .filter(
+      (row) =>
+        row.owner_kind === "agent" &&
+        row.owner_id !== null &&
+        exactHookEntrypoint(row.name, row.command),
+    )
+    .map((row) => ({
+      pid: row.pid,
+      owner_id: row.owner_id!,
+      state: row.state,
+      age_seconds: row.age_seconds,
+      cpu_percent: row.cpu_percent,
+      rss_bytes: row.rss_bytes,
+      command: row.command,
+      long_running: row.age_seconds >= SUPERVISOR_LONG_HOOK_SECONDS,
+      evidence: "validated-owner-and-exact-entrypoint" as const,
+    }))
+    .sort((left, right) => right.age_seconds - left.age_seconds || left.pid - right.pid);
+}
+
+export function exactHookEntrypoint(name: string, command: string): boolean {
+  if (name === "agent-hook" || name === "agent-hook.exe") return true;
+  return /(?:^|[\\/\s])agent-hook(?:\.exe)?(?:\s|$)/.test(command);
+}

package/src/core/supervisor/index.ts

@@ -0,0 +1,14 @@
+export * from "./contract.ts";
+export * from "./explanations.ts";
+export * from "./findings.ts";
+export * from "./history.ts";
+export * from "./hook-health.ts";
+export * from "./hook-health-alerts.ts";
+export * from "./hook-health-storage.ts";
+export * from "./hooks.ts";
+export * from "./log-feed.ts";
+export * from "./service.ts";
+export * from "./services.ts";
+export * from "./status.ts";
+export * from "./storage.ts";
+export * from "./timeline.ts";

package/src/core/supervisor/log-feed.ts

@@ -0,0 +1,131 @@
+import { createStorageCatalog } from "../storage/catalog.ts";
+import {
+  HARNERY_STRUCTURED_LOG_PROVIDER_ID,
+  type HarneryRegisteredStorageFamily,
+} from "../storage/contract.ts";
+import type { HarneryLogRecordV1 } from "../storage/jsonl.ts";
+import {
+  type HarneryLogFollowCursor,
+  readLogFollow,
+  readRecentActiveLogs,
+  rotationFollowCursor,
+} from "../storage/query.ts";
+import {
+  SUPERVISOR_LOG_FEED_SCHEMA_VERSION,
+  type SupervisorLogFeed,
+  type SupervisorLogLane,
+} from "./contract.ts";
+
+const MAX_RECORDS_PER_FAMILY = 100;
+const MAX_SEED_BYTES_PER_FAMILY = 256 * 1024;
+const MAX_FOLLOW_BYTES_PER_FAMILY = 64 * 1024;
+
+interface LaneState {
+  family: HarneryRegisteredStorageFamily;
+  cursor: HarneryLogFollowCursor;
+  records: HarneryLogRecordV1[];
+  truncated: boolean;
+  error?: string;
+}
+
+export class SupervisorLogCollector {
+  readonly #lanes: LaneState[];
+  #sequence = 0;
+
+  constructor(coordRoot: string) {
+    const catalog = createStorageCatalog({ coord_root: coordRoot, project_root: coordRoot });
+    this.#lanes = catalog.families.filter(isStructuredLogFamily).map((family) => seedLane(family));
+  }
+
+  async collect(now = new Date()): Promise<SupervisorLogFeed> {
+    let changed = this.#sequence === 0;
+    for (const lane of this.#lanes) {
+      try {
+        const followed = await readLogFollow(lane.family, lane.cursor, MAX_FOLLOW_BYTES_PER_FAMILY);
+        lane.cursor = followed.cursor;
+        if (followed.records.length > 0 || followed.rotated || followed.history_expired) {
+          const merged = dedupe([...lane.records, ...followed.records]);
+          lane.records = merged.slice(-MAX_RECORDS_PER_FAMILY);
+          lane.truncated =
+            lane.truncated || followed.history_expired || merged.length > MAX_RECORDS_PER_FAMILY;
+          changed = true;
+        }
+        if (lane.error) changed = true;
+        lane.error = undefined;
+      } catch (error) {
+        const next = error instanceof Error ? error.message : String(error);
+        if (next !== lane.error) changed = true;
+        lane.error = next;
+      }
+    }
+    if (changed) this.#sequence += 1;
+    const lanes: SupervisorLogLane[] = this.#lanes
+      .map((lane) => ({
+        family_id: lane.family.id,
+        owner: lane.family.owner,
+        storage_class: lane.family.storage_class as "operational-log" | "debug-log",
+        records: lane.records,
+        truncated: lane.truncated,
+        ...(lane.error ? { error: lane.error } : {}),
+      }))
+      .sort((left, right) => {
+        const activeDelta = Number(right.records.length > 0) - Number(left.records.length > 0);
+        return activeDelta || left.family_id.localeCompare(right.family_id);
+      });
+    return {
+      schema_version: SUPERVISOR_LOG_FEED_SCHEMA_VERSION,
+      captured_at: now.toISOString(),
+      sequence: this.#sequence,
+      lanes,
+      total_records: lanes.reduce((sum, lane) => sum + lane.records.length, 0),
+      unavailable_families: lanes.filter((lane) => lane.error).length,
+    };
+  }
+}
+
+export function recentSupervisorLogs(feed: SupervisorLogFeed, limit = 20): HarneryLogRecordV1[] {
+  return feed.lanes
+    .flatMap((lane) => lane.records)
+    .sort((left, right) => Date.parse(left.emitted_at) - Date.parse(right.emitted_at))
+    .slice(-Math.max(0, limit));
+}
+
+function seedLane(family: HarneryRegisteredStorageFamily): LaneState {
+  try {
+    const seed = readRecentActiveLogs(family, {
+      max_records: MAX_RECORDS_PER_FAMILY,
+      max_bytes: MAX_SEED_BYTES_PER_FAMILY,
+    });
+    return {
+      family,
+      cursor: rotationFollowCursor(family),
+      records: [...seed.records],
+      truncated: seed.truncated,
+    };
+  } catch (error) {
+    return {
+      family,
+      cursor: rotationFollowCursor(family),
+      records: [],
+      truncated: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function isStructuredLogFamily(family: HarneryRegisteredStorageFamily): boolean {
+  return (
+    (family.storage_class === "operational-log" || family.storage_class === "debug-log") &&
+    family.provider.provider_id === HARNERY_STRUCTURED_LOG_PROVIDER_ID
+  );
+}
+
+function dedupe(records: readonly HarneryLogRecordV1[]): HarneryLogRecordV1[] {
+  const keyed = new Map<string, HarneryLogRecordV1>();
+  for (const record of records) {
+    keyed.set(`${record.family_id}:${record.writer_id}:${record.writer_seq}`, record);
+  }
+  return [...keyed.values()].sort(
+    (left, right) => Date.parse(left.emitted_at) - Date.parse(right.emitted_at),
+  );
+}