harnery 0.36.0 → 0.37.0

package/src/commands/qa-run.ts

@@ -0,0 +1,184 @@
+// `qa-run <target>`: run the whole page-QA matrix (planner, deterministic
+// gates, interactions, critique, snapshot) in one command. The agent's loop
+// collapses to: build the job, run this, read page-qa-result.json.
+
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import { QA_RUN_RESULT_FILENAME, runQaMatrix } from "../lib/browser/qa-run.ts";
+import {
+  QA_RUN_JOB_SCHEMA_VERSION,
+  type QaRunJob,
+  validateQaRunJob,
+} from "../lib/browser/qa-run-contracts.ts";
+
+interface QaRunOpts {
+  job?: string;
+  mode: string;
+  concurrency?: string;
+  allowMetered?: boolean;
+  outDir?: string;
+  json?: boolean;
+}
+
+export function registerQaRunCommand(program: Command, emit: EmitContext): void {
+  program
+    .command("qa-run <target>")
+    .description(
+      "Run the whole page-QA matrix in one command: QA planner, deterministic " +
+        "gates per viewport/theme/state through a bounded process pool, serial " +
+        "interaction assertions, manifest-required vision critique, and the QA " +
+        "snapshot. Writes page-qa-result.json with a fail-closed verdict.",
+    )
+    .option(
+      "--job <file>",
+      "QA job document (JSON). Validated before any browser starts — secret-bearing " +
+        "fields are refused, and the job may widen but never narrow the planner's coverage. " +
+        "Absent: a minimal implicit job for <target> is used.",
+    )
+    .option(
+      "--mode <mode>",
+      "signoff persists a QA snapshot on a passing run; review never does.",
+      "signoff",
+    )
+    .option(
+      "--concurrency <n>",
+      "Concurrent deterministic captures (1-8; default 2). Interactions and critique " +
+        "always run serially.",
+    )
+    .option(
+      "--allow-metered",
+      "Permit the critique provider's metered-API fallback. Default: subscription-backed " +
+        "headless harnesses only — exhaustion becomes an incomplete blocker, never a metered call.",
+    )
+    .option(
+      "--out-dir <dir>",
+      "Artifact + result directory (default: .qa-run/<timestamp> under the current directory).",
+    )
+    .option("--json", "Print the full QaRunResult JSON to stdout.")
+    .addHelpText(
+      "after",
+      "\nExit codes: 0 verdict passed · 1 usage or job-validation error · " +
+        "2 verdict failed · 4 verdict incomplete.",
+    )
+    .action(async (target: string, opts: QaRunOpts, command: Command) => {
+      if (opts.mode !== "signoff" && opts.mode !== "review") {
+        emit.error({
+          code: "qa_run_invalid_mode",
+          message: '--mode must be "signoff" or "review"',
+        });
+        process.exitCode = 1;
+        return;
+      }
+      const modeExplicit = command.getOptionValueSource("mode") === "cli";
+
+      let jobDocument: unknown;
+      if (opts.job) {
+        let rawText: string;
+        try {
+          rawText = readFileSync(opts.job, "utf8");
+        } catch (err: unknown) {
+          emit.error({
+            code: "qa_run_job_unreadable",
+            message: `cannot read --job file ${opts.job}: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          process.exitCode = 1;
+          return;
+        }
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(rawText);
+        } catch (err: unknown) {
+          emit.error({
+            code: "qa_run_job_invalid_json",
+            message: `--job file ${opts.job} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          process.exitCode = 1;
+          return;
+        }
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+          const raw = parsed as Record<string, unknown>;
+          // The CLI target argument is authoritative; a job file may omit
+          // target and mode. An explicit --mode overrides the job's mode.
+          jobDocument = {
+            ...raw,
+            target,
+            ...(raw.mode === undefined || modeExplicit ? { mode: opts.mode } : {}),
+          };
+        } else {
+          jobDocument = parsed;
+        }
+      } else {
+        jobDocument = { schema_version: QA_RUN_JOB_SCHEMA_VERSION, target, mode: opts.mode };
+      }
+
+      // All validation errors print at once, before any browser starts.
+      const validation = validateQaRunJob(jobDocument);
+      if (!validation.ok) {
+        for (const message of validation.errors) emit.log(`job: ${message}`, "error");
+        emit.error({
+          code: "qa_run_invalid_job",
+          message: `job validation failed with ${validation.errors.length} error${validation.errors.length === 1 ? "" : "s"}`,
+        });
+        process.exitCode = 1;
+        return;
+      }
+
+      const policy = { ...validation.job.policy };
+      if (opts.concurrency !== undefined) {
+        const n = Number.parseInt(opts.concurrency, 10);
+        if (!Number.isInteger(n) || n < 1 || n > 8) {
+          emit.error({
+            code: "qa_run_invalid_concurrency",
+            message: "--concurrency must be an integer between 1 and 8",
+          });
+          process.exitCode = 1;
+          return;
+        }
+        policy.command_concurrency = n;
+      }
+      if (opts.allowMetered) policy.allow_metered_critique = true;
+      const job: QaRunJob = { ...validation.job, policy };
+
+      const outDir = resolve(
+        opts.outDir ?? join(".qa-run", new Date().toISOString().replace(/[:.]/g, "-")),
+      );
+      const cliScript = process.argv[1];
+      if (!cliScript) {
+        emit.error({
+          code: "qa_run_no_cli_script",
+          message: "cannot resolve the host CLI script path for child browse invocations",
+        });
+        process.exitCode = 1;
+        return;
+      }
+      // Children run the same host CLI, so they inherit the host's browse
+      // wiring (critique provider, cookie jar, profiles) unchanged.
+      const browseArgv = [process.execPath, cliScript, "browse"];
+
+      const result = await runQaMatrix({
+        job,
+        outDir,
+        browseArgv,
+        onLog: (message) => emit.log(message, "info"),
+      });
+
+      if (opts.json) emit.data(result);
+      const resultPath = join(outDir, QA_RUN_RESULT_FILENAME);
+      for (const blocker of result.blockers) {
+        emit.log(
+          `blocker [${blocker.stage}${blocker.context_id ? ` ${blocker.context_id}` : ""}]: ${blocker.reason}`,
+          "warn",
+        );
+      }
+      emit.log(
+        `verdict: ${result.verdict} — ${result.contexts.length} context${result.contexts.length === 1 ? "" : "s"}, ` +
+          `${result.commands.length} command${result.commands.length === 1 ? "" : "s"}, ` +
+          `${result.blockers.length} blocker${result.blockers.length === 1 ? "" : "s"}; result: ${resultPath}`,
+        result.verdict === "passed" ? "info" : "warn",
+      );
+      if (result.verdict === "failed") process.exitCode = 2;
+      else if (result.verdict === "incomplete") process.exitCode = 4;
+    });
+}

package/src/commands/resources.ts

@@ -0,0 +1,38 @@
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { sampleResources } from "../core/resources/index.ts";
+
+export function registerResourcesCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  const resources = program
+    .command("resources")
+    .description("Observe local CPU and memory pressure by agent and process tree");
+
+  resources
+    .command("snapshot")
+    .description("Capture one machine and process-resource snapshot")
+    .option("--root <path>", "Explicit coordination root")
+    .action((options: { root?: string }) => {
+      try {
+        emit.data(sampleResources(resolve(options.root ?? coordRoot(context))).snapshot);
+      } catch (error) {
+        fail(emit, "resource_snapshot_failed", error);
+      }
+    });
+}
+
+function coordRoot(context?: HarneryProgramContext): string {
+  return context?.resolveCoordRoot?.() ?? context?.repoRoot ?? process.cwd();
+}
+
+function fail(emit: EmitContext, code: string, error: unknown): void {
+  emit.error({
+    code,
+    message: error instanceof Error ? error.message : String(error),
+  });
+  emit.setExitCode(1);
+}

package/src/commands/supervisor.ts

@@ -0,0 +1,141 @@
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { readSupervisorHookHealth } from "../core/supervisor/hook-health-storage.ts";
+import {
+  requestSupervisorStop,
+  runSupervisor,
+  spawnSupervisor,
+} from "../core/supervisor/service.ts";
+import { readSupervisorStatus } from "../core/supervisor/status.ts";
+import {
+  readSupervisorFindings,
+  readSupervisorHistory,
+  readSupervisorLogFeed,
+  readSupervisorSnapshot,
+} from "../core/supervisor/storage.ts";
+
+export function registerSupervisorCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  const supervisor = program
+    .command("supervisor")
+    .description("Run Harnery's optional local diagnostic supervisor");
+
+  supervisor
+    .command("start")
+    .description("Start the detached local supervisor")
+    .option("--root <path>", "Explicit coordination root")
+    .option("--interval-ms <milliseconds>", "Collection interval from 500 to 60000 ms", integer)
+    .option(
+      "--idle-exit-ms <milliseconds>",
+      "Exit after this long without a live dashboard consumer or attributed agent",
+      integer,
+    )
+    .option("--keep-alive", "Remain resident until explicitly stopped")
+    .action(
+      async (options: {
+        root?: string;
+        intervalMs?: number;
+        idleExitMs?: number;
+        keepAlive?: boolean;
+      }) => {
+        try {
+          emit.data(
+            await spawnSupervisor(resolve(options.root ?? coordRoot(context)), {
+              intervalMs: options.intervalMs,
+              idleExitMs: options.idleExitMs,
+              keepAlive: options.keepAlive,
+            }),
+          );
+        } catch (error) {
+          fail(emit, "supervisor_start_failed", error);
+        }
+      },
+    );
+
+  supervisor
+    .command("status")
+    .description("Show supervisor liveness and its latest bounded projections")
+    .option("--root <path>", "Explicit coordination root")
+    .action((options: { root?: string }) => {
+      try {
+        const root = resolve(options.root ?? coordRoot(context));
+        emit.data({
+          service: readSupervisorStatus(root),
+          snapshot: readSupervisorSnapshot(root),
+          history: readSupervisorHistory(root),
+          findings: readSupervisorFindings(root),
+          hook_health: readSupervisorHookHealth(root),
+          log_feed: readSupervisorLogFeed(root),
+        });
+      } catch (error) {
+        fail(emit, "supervisor_status_failed", error);
+      }
+    });
+
+  supervisor
+    .command("stop")
+    .description("Request a graceful supervisor stop")
+    .option("--root <path>", "Explicit coordination root")
+    .action(async (options: { root?: string }) => {
+      try {
+        const root = resolve(options.root ?? coordRoot(context));
+        let status = requestSupervisorStop(root);
+        const deadline = Date.now() + 5_000;
+        while (status.running && Date.now() < deadline) {
+          await new Promise((done) => setTimeout(done, 50));
+          status = readSupervisorStatus(root);
+        }
+        emit.data(status);
+      } catch (error) {
+        fail(emit, "supervisor_stop_failed", error);
+      }
+    });
+
+  supervisor
+    .command("daemon", { hidden: true })
+    .description("Internal detached local supervisor entrypoint")
+    .option("--root <path>", "Explicit coordination root")
+    .option("--interval-ms <milliseconds>", "Collection interval", integer)
+    .option("--idle-exit-ms <milliseconds>", "Idle exit interval", integer)
+    .option("--keep-alive", "Remain resident until explicitly stopped")
+    .action(
+      async (options: {
+        root?: string;
+        intervalMs?: number;
+        idleExitMs?: number;
+        keepAlive?: boolean;
+      }) => {
+        try {
+          emit.data(
+            await runSupervisor({
+              coordRoot: resolve(options.root ?? coordRoot(context)),
+              intervalMs: options.intervalMs,
+              idleExitMs: options.idleExitMs,
+              keepAlive: options.keepAlive,
+            }),
+          );
+        } catch (error) {
+          fail(emit, "supervisor_daemon_failed", error);
+        }
+      },
+    );
+}
+
+function coordRoot(context?: HarneryProgramContext): string {
+  return context?.resolveCoordRoot?.() ?? context?.repoRoot ?? process.cwd();
+}
+
+function integer(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) throw new Error(`expected an integer, got ${value}`);
+  return parsed;
+}
+
+function fail(emit: EmitContext, code: string, error: unknown): void {
+  emit.error({ code, message: error instanceof Error ? error.message : String(error) });
+  emit.setExitCode(1);
+}

package/src/commands/web.ts

@@ -8,6 +8,11 @@ import type { EmitContext } from "../commander.ts";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.ts";
 import { ensureSemanticServiceRunning } from "../core/semantic/service.ts";
 import { processLogDestination } from "../core/storage/process-log.ts";
+import { ensureSupervisorRunning } from "../core/supervisor/service.ts";
+import {
+  registerSupervisorConsumer,
+  unregisterSupervisorConsumer,
+} from "../core/supervisor/services.ts";
 import {
   parsePerformanceWindow,
   readWebPerformanceReport,
@@ -109,6 +114,16 @@ async function startSemanticServiceWithWeb(coordRoot: string, emit: EmitContext)
   }
 }
 
+async function startSupervisorWithWeb(coordRoot: string, emit: EmitContext): Promise<void> {
+  registerSupervisorConsumer(coordRoot, { id: "dashboard" });
+  const result = await ensureSupervisorRunning(coordRoot);
+  if (result.state === "started") emit.log("local supervisor · started automatically", "info");
+  if (result.state === "running") emit.log("local supervisor · already running", "info");
+  if (result.state === "unavailable") {
+    emit.log(`local supervisor · unavailable (${result.error})`, "warn");
+  }
+}
+
 /**
  * Resolve the web app root. A local `web/` (source checkout / submodule) wins.
  * Otherwise, on an npm install, lazy-fetch it (clone + install) unless the
@@ -233,6 +248,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
 
       if (!(await requireAvailablePort(emit, port))) return;
 
+      await startSupervisorWithWeb(coordRoot, emit);
       await startSemanticServiceWithWeb(coordRoot, emit);
 
       const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
@@ -264,6 +280,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       process.on("SIGTERM", () => cleanup("SIGTERM"));
 
       child.on("exit", (code, sig) => {
+        unregisterSupervisorConsumer(coordRoot, "dashboard");
         if (sig) {
           emit.log(`web exited on ${sig}`, "info");
         } else if (code !== 0) {
@@ -326,6 +343,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
         return;
       }
       if (!(await requireAvailablePort(emit, port))) return;
+      await startSupervisorWithWeb(coordRoot, emit);
       await startSemanticServiceWithWeb(coordRoot, emit);
       const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
       const nodeOptions = nodeOptionsWithWebDiagnostics(root, heapMb);
@@ -355,6 +373,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       process.on("SIGTERM", () => cleanup("SIGTERM"));
 
       child.on("exit", (code) => {
+        unregisterSupervisorConsumer(coordRoot, "dashboard");
         process.exitCode = code ?? 0;
       });
     });

package/src/commands/workflow.ts

@@ -28,6 +28,7 @@ import type { WorkspaceProvider } from "../core/workflow/index.ts";
 interface WorkflowRunOpts {
   maxAgents?: string;
   concurrency?: string;
+  observePressure?: boolean;
   cwd?: string;
   adapter?: string;
   resumeFrom?: string;
@@ -98,6 +99,10 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     )
     .option("--max-agents <n>", "Total-agent ceiling for the run (default 50)")
     .option("--concurrency <n>", "Concurrent-subagent cap (default 4)")
+    .option(
+      "--observe-pressure",
+      "Record observer-only local pressure before the first real child dispatch",
+    )
     .option("--cwd <dir>", "Working directory children spawn in (default: coord root)")
     .option(
       "--adapter <name>",
@@ -194,6 +199,9 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
           allowApiBilling: opts.allowApiBilling,
           maxAgents: opts.maxAgents ? Number.parseInt(opts.maxAgents, 10) : undefined,
           concurrency: opts.concurrency ? Number.parseInt(opts.concurrency, 10) : undefined,
+          diagnosticAdmission: opts.observePressure
+            ? { schema_version: 1, mode: "shadow" }
+            : undefined,
           cwd: opts.cwd,
           ...adapterProofInputs(
             registry.list().map((adapter) => adapter.profile),

package/src/core/agents/cli.ts

@@ -708,8 +708,10 @@ async function handleStaleSweep(root: string, _rest: string[]): Promise<number>
 }
 
 async function handleReconcileFinalization(root: string): Promise<number> {
-  const { reconcileSessionFinalizationV3 } = await import("./session-finalizer-v3.ts");
-  const result = reconcileSessionFinalizationV3(root);
+  // Shares the supervisor composition with `agents reconcile` so session start
+  // sweeps the stale cache in the same pass, as ADR 0077 specified.
+  const { reconcileCoordinationV3 } = await import("./reconcile-coordination-v3.ts");
+  const result = reconcileCoordinationV3(root);
   process.stdout.write(`${JSON.stringify(result)}\n`);
   return result.diagnostics.some((item) => item === "ledger_not_authority_safe") ? 2 : 0;
 }
@@ -759,6 +761,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
   const instanceId = args.instance;
   const sessionId = args.session ?? instanceId;
   const agentName = args.name;
+  const adapter = args.adapter;
   const sessionNameNudge = args["session-name-nudge"] === "true";
   const taskNudge = args["task-nudge"] === "true";
   const hostPromptReminder = args["host-prompt-reminder"] === "true";
@@ -769,7 +772,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     args["turn-ritual-nudge"] === "true" ? "generic" : args["turn-ritual-nudge"];
   if (!instanceId) {
     process.stderr.write(
-      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--session-name-nudge] [--task-nudge] [--host-prompt-reminder] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n",
+      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--adapter <id>] [--session-name-nudge] [--task-nudge] [--host-prompt-reminder] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n",
     );
     return 2;
   }
@@ -784,6 +787,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     hostPromptReminder,
     statusFooterNudge,
     turnRitualNudge,
+    adapter,
   });
   process.stdout.write(text);
   return 0;

package/src/core/agents/health.ts

@@ -0,0 +1,142 @@
+import { closeSync, existsSync, lstatSync, openSync, readSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { SupervisorCapability, SupervisorSourceReference } from "../supervisor/contract.ts";
+
+export interface CoordinationHealthDiagnostic {
+  code: "malformed_json" | "invalid_contract";
+  byte_offset: number;
+  segment_ordinal: number;
+  event_id?: string;
+}
+
+export interface CoordinationHealthSnapshot {
+  observed_at: string;
+  capability: SupervisorCapability;
+  recent_events: readonly SupervisorSourceReference[];
+  diagnostics: readonly CoordinationHealthDiagnostic[];
+  omitted_event_count: number;
+}
+
+const MAX_EVENT_REFERENCES = 64;
+const MAX_DIAGNOSTICS = 16;
+const MAX_TAIL_BYTES = 256 * 1_024;
+
+/** Read bounded V3 references without retaining event payloads or the full ledger reader. */
+export function collectCoordinationHealthSnapshot(
+  coordRoot: string,
+  now = new Date(),
+): CoordinationHealthSnapshot {
+  const observedAt = now.toISOString();
+  const active = join(resolve(coordRoot), ".harnery", "ledgers", "v3", "active.ndjson");
+  if (!existsSync(active)) return unavailable(observedAt, "ledger-missing");
+
+  let handle: number | undefined;
+  try {
+    const stat = lstatSync(active);
+    if (stat.isSymbolicLink() || !stat.isFile()) return unavailable(observedAt, "ledger-unsafe");
+    if (stat.size === 0) return available(observedAt, [], [], 0);
+    const start = Math.max(0, stat.size - MAX_TAIL_BYTES);
+    const bytes = Buffer.allocUnsafe(stat.size - start);
+    handle = openSync(active, "r");
+    const count = readSync(handle, bytes, 0, bytes.length, start);
+    const lines = bytes.subarray(0, count).toString("utf8").split("\n");
+    if (start > 0) lines.shift();
+    const completeLines = lines.filter((line) => line.length > 0);
+    const diagnostics: CoordinationHealthDiagnostic[] = [];
+    const references: SupervisorSourceReference[] = [];
+    let byteOffset = start;
+    for (const line of completeLines) {
+      const reference = parseReference(line);
+      if (reference) references.push(reference);
+      else if (diagnostics.length < MAX_DIAGNOSTICS) {
+        diagnostics.push({
+          code: line.trimStart().startsWith("{") ? "invalid_contract" : "malformed_json",
+          byte_offset: byteOffset,
+          segment_ordinal: 1,
+        });
+      }
+      byteOffset += Buffer.byteLength(line) + 1;
+    }
+    const recent = references.slice(-MAX_EVENT_REFERENCES);
+    return available(
+      observedAt,
+      recent,
+      diagnostics,
+      Math.max(0, references.length - recent.length) + (start > 0 ? 1 : 0),
+    );
+  } catch {
+    return unavailable(observedAt, "tail-read-failed", "error");
+  } finally {
+    if (handle !== undefined) closeSync(handle);
+  }
+}
+
+function parseReference(line: string): SupervisorSourceReference | undefined {
+  try {
+    const value = JSON.parse(line) as Record<string, unknown>;
+    const contract = object(value.contract);
+    const time = object(value.time);
+    const producer = object(value.producer);
+    if (
+      contract.major !== 3 ||
+      typeof value.event_id !== "string" ||
+      typeof value.event_type !== "string" ||
+      typeof time.observed_at !== "string" ||
+      typeof producer.sequence !== "number" ||
+      !Number.isSafeInteger(producer.sequence)
+    )
+      return undefined;
+    return {
+      id: `v3:${value.event_id}`,
+      source_kind: "coordination.v3",
+      source_id: value.event_type,
+      record_id: value.event_id,
+      sequence: producer.sequence,
+      schema_version: 3,
+      observed_at: time.observed_at,
+      capability: "supported",
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function object(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function available(
+  observedAt: string,
+  recentEvents: readonly SupervisorSourceReference[],
+  diagnostics: readonly CoordinationHealthDiagnostic[],
+  omittedEventCount: number,
+): CoordinationHealthSnapshot {
+  const state = diagnostics.length === 0 ? "supported" : "partial";
+  return {
+    observed_at: observedAt,
+    capability: {
+      source_kind: "coordination.v3.references",
+      state,
+      ...(state === "partial" ? { reason_code: diagnostics[0]?.code ?? "tail-invalid" } : {}),
+    },
+    recent_events: recentEvents.map((reference) => ({ ...reference, capability: state })),
+    diagnostics,
+    omitted_event_count: omittedEventCount,
+  };
+}
+
+function unavailable(
+  observedAt: string,
+  reasonCode: string,
+  state: "unsupported" | "error" = "unsupported",
+): CoordinationHealthSnapshot {
+  return {
+    observed_at: observedAt,
+    capability: { source_kind: "coordination.v3.references", state, reason_code: reasonCode },
+    recent_events: [],
+    diagnostics: [],
+    omitted_event_count: 0,
+  };
+}