harnery 0.45.2 → 0.46.0

package/src/commands/ledger-v3.ts

@@ -15,9 +15,9 @@ import {
   cleanEventV3Archives,
   initializeEventLedgerV3,
   inventoryEventV3Archives,
-  listHookProducerStateRecordsV3,
   readEventV3ControlState,
   recoverInvalidEventLedgerV3,
+  scanHookProducerStateRecordsV3,
   sha256V3,
 } from "../core/events/v3/index.ts";
 import type { EventV3SupportClassificationEvidence } from "../core/events/v3/support-storage/index.ts";
@@ -61,7 +61,8 @@ export function registerLedgerV3Command(
       try {
         const root = resolve(options.root ?? coordRoot(context));
         const control = readEventV3ControlState(root);
-        const producers = listHookProducerStateRecordsV3(root, { includeTerminal: true });
+        const scan = scanHookProducerStateRecordsV3(root, { includeTerminal: true });
+        const producers = scan.records;
         const counts = producers.reduce<Record<string, number>>((summary, record) => {
           summary[record.state.adapter] = (summary[record.state.adapter] ?? 0) + 1;
           return summary;
@@ -72,6 +73,11 @@ export function registerLedgerV3Command(
             adapters: Object.keys(counts).sort(),
             producer_states: producers.length,
             producer_states_by_adapter: counts,
+            invalid_producer_states: scan.invalid.map((file) => ({
+              adapter: file.adapter,
+              session_hash: file.session_hash,
+              reason: file.reason,
+            })),
           },
         });
       } catch (error) {

package/src/commands/presence.ts

@@ -8,6 +8,7 @@ import {
   resolveOwner,
 } from "../core/agents/index.ts";
 import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.ts";
+import { peerInbox } from "../core/inbox/peer-messages.ts";
 import {
   fetchPresence,
   publishPresence,
@@ -15,6 +16,7 @@ import {
   relayDaemonStatus,
   runRelayDaemon,
 } from "../core/presence/index.ts";
+import { importMail, mailStatus, publishMail } from "../core/presence/mail.ts";
 import {
   ageSeconds,
   applyDetection,
@@ -134,6 +136,53 @@ export function registerPresenceCommand(program: Command, emit: EmitContext): vo
       emit.data(r);
     });
 
+  cmd
+    .command("mail")
+    .description(
+      "Show cross-machine peer messages (ADR 0222): this machine's unacknowledged outbox, " +
+        "acknowledgements it is publishing, and delivered/expired counts. --sync fetches, " +
+        "imports, and publishes first (synchronous; errors report).",
+    )
+    .option(
+      "--sync",
+      "Fetch peers' refs, import mail addressed here, and publish this machine's ref",
+    )
+    .option("--json", "JSON output")
+    .action((opts: { sync?: boolean; json?: boolean }) => {
+      const root = requireRoot(emit);
+      let sync: Record<string, unknown> | undefined;
+      if (opts.sync) {
+        const fetched = fetchPresence(root, { force: true, sync: true });
+        if (fetched.status === "error") {
+          emit.error({ code: "fetch_failed", message: fetched.error });
+          process.exit(1);
+        }
+        const imported = importMail(root, peerInbox(root), { publish: false });
+        const published = publishMail(root, { sync: true });
+        if (published.status === "error") {
+          emit.error({ code: "publish_failed", message: published.error });
+          process.exit(1);
+        }
+        sync = { imported, published };
+      }
+      const status = mailStatus(root);
+      if (opts.json) emit.config({ format: "json" });
+      if (opts.json || !process.stdout.isTTY) {
+        emit.data({ ...status, ...(sync ? { sync } : {}) });
+        return;
+      }
+      emit.text(
+        `${status.machine}: ${status.outbox.length} waiting for acknowledgement, ` +
+          `${status.acks} acknowledgements published, ${status.delivered} delivered, ` +
+          `${status.expired} expired\n`,
+      );
+      for (const m of status.outbox) {
+        emit.text(
+          `  ${m.message_id} to agent-${m.recipient} on ${m.to_machine} (queued ${m.queued_at})\n`,
+        );
+      }
+    });
+
   cmd
     .command("relay-daemon")
     .description(

package/src/commands/qa-run.ts

@@ -17,6 +17,7 @@ import {
   resolveQaRepoRoot,
 } from "../core/qa-artifacts.ts";
 import { acquireAdmission, admissionBaseDir, admissionStatus } from "../lib/admission.ts";
+import { PAGE_REVIEW_MAX_TILE_BUDGET } from "../lib/browser/page-review-contracts.ts";
 import {
   deleteExpiredPacks,
   PAGE_REVIEW_DEFAULT_RETENTION_MINUTES,
@@ -99,7 +100,7 @@ export function registerQaRunCommand(
     )
     .option(
       "--tile-budget <n>",
-      "Maximum native tiles across the complete review pack (8-400; default 96).",
+      `Maximum native tiles across the complete review pack (8-${PAGE_REVIEW_MAX_TILE_BUDGET}; default 96).`,
     )
     .option(
       "--accept-dispositions",
@@ -224,10 +225,10 @@ export function registerQaRunCommand(
       const policy = { ...validation.job.policy };
       if (opts.tileBudget !== undefined) {
         const n = Number(opts.tileBudget);
-        if (!Number.isInteger(n) || n < 8 || n > 400) {
+        if (!Number.isInteger(n) || n < 8 || n > PAGE_REVIEW_MAX_TILE_BUDGET) {
           emit.error({
             code: "qa_run_invalid_tile_budget",
-            message: "--tile-budget must be an integer between 8 and 400",
+            message: `--tile-budget must be an integer between 8 and ${PAGE_REVIEW_MAX_TILE_BUDGET}`,
           });
           process.exitCode = 1;
           return;

package/src/commands/review-pack.ts

@@ -14,7 +14,8 @@ import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-
 import { artifactsRoot } from "../core/artifacts/index.ts";
 import { resolveBinName, reviewPackAutoCleanEnabled } from "../core/config.ts";
 import { createManagedQaOutParent, resolveQaRepoRoot } from "../core/qa-artifacts.ts";
-import { DEFAULT_CRITIQUE_RUBRIC } from "../lib/browser/critique.ts";
+import { DEFAULT_CRITIQUE_RUBRIC, formatCritiqueUsage } from "../lib/browser/critique.ts";
+import { PAGE_REVIEW_MAX_TILE_BUDGET } from "../lib/browser/page-review-contracts.ts";
 import { persistPackReviewDecisions } from "../lib/browser/page-review-evidence.ts";
 import { judgePageReviewPack, toCritiqueRecords } from "../lib/browser/page-review-judge.ts";
 import {
@@ -382,7 +383,9 @@ export function registerReviewPackCommand(
     )
     .option(
       "--max-tiles <n>",
-      "Native tile cap per context, including required top and bottom bands.",
+      "Native tile cap per context, including required top and bottom bands (default 24). " +
+        `The whole pack never exceeds ${PAGE_REVIEW_MAX_TILE_BUDGET} tiles, so the cap is ` +
+        "lowered when the contexts would need more.",
     )
     .option("--concurrency <n>", "Concurrent capture browsers (1-8; default 2).", "2")
     .option("--timeout <ms>", "Per-capture timeout in milliseconds (default 120000).", "120000")
@@ -411,6 +414,31 @@ export function registerReviewPackCommand(
         process.exitCode = 1;
         return;
       }
+      const requestedMaxTiles = Number(opts.maxTiles ?? "24");
+      if (
+        !Number.isInteger(requestedMaxTiles) ||
+        requestedMaxTiles < 1 ||
+        requestedMaxTiles > PAGE_REVIEW_MAX_TILE_BUDGET
+      ) {
+        emit.error({
+          code: "review_pack_invalid_max_tiles",
+          message: `--max-tiles must be an integer between 1 and ${PAGE_REVIEW_MAX_TILE_BUDGET}`,
+        });
+        process.exitCode = 1;
+        return;
+      }
+      // The judge refuses a pack above the ceiling, so share it across contexts here.
+      const perContextMaxTiles = Math.max(
+        2,
+        Math.min(requestedMaxTiles, Math.floor(PAGE_REVIEW_MAX_TILE_BUDGET / contexts.length)),
+      );
+      if (perContextMaxTiles < requestedMaxTiles) {
+        emit.log(
+          `review-pack: ${contexts.length} contexts share the ${PAGE_REVIEW_MAX_TILE_BUDGET}-tile ceiling; ` +
+            `capping each at ${perContextMaxTiles} tiles`,
+          "warn",
+        );
+      }
       const concurrency = Math.max(
         1,
         Math.min(8, Number.parseInt(opts.concurrency ?? "2", 10) || 2),
@@ -472,7 +500,8 @@ export function registerReviewPackCommand(
             "--qa-state",
             ctx.state,
             ...(opts.scope ?? []).flatMap((selector) => ["--review-pack-scope", selector]),
-            ...(opts.maxTiles !== undefined ? ["--check-critique-max-tiles", opts.maxTiles] : []),
+            "--check-critique-max-tiles",
+            String(perContextMaxTiles),
           ];
           emit.log(`capture ${ctx.id}`, "info");
           const res = await defaultQaRunExec(argv, { timeoutMs, env });
@@ -641,7 +670,12 @@ export function registerReviewPackCommand(
       else process.env[QA_RUN_HEADLESS_ONLY_ENV] = prior;
 
       const merged = new Map((manifest.critique ?? []).map((row) => [row.context_id, row]));
-      for (const row of toCritiqueRecords(result)) merged.set(row.context_id, row);
+      for (const row of toCritiqueRecords(result)) {
+        // Re-judging never changes the captured coverage, so a signoff's
+        // sampled acceptance (ADR 0224) still applies.
+        const prior = merged.get(row.context_id)?.coverage_mode;
+        merged.set(row.context_id, prior ? { ...row, coverage_mode: prior } : row);
+      }
       const judgedRecords = new Map(result.contexts.map((row) => [row.context_id, row.record]));
       finalizePageReviewPack({
         packDir,
@@ -671,7 +705,9 @@ export function registerReviewPackCommand(
         );
       }
       emit.log(
-        `judge: ${result.outcome} · pool ${result.pool.concurrency} · ${result.tiles_reviewed} tile(s) in ${result.pool.wall_time_ms}ms · ${packPaths(packDir).review}`,
+        `judge: ${result.outcome} · pool ${result.pool.concurrency} · ${result.tiles_reviewed} tile(s) in ${result.pool.wall_time_ms}ms` +
+          (result.usage ? ` · ${formatCritiqueUsage(result.usage)}` : "") +
+          ` · ${packPaths(packDir).review}`,
         result.outcome === "pass" ? "info" : "warn",
       );
       if (opts.json) emit.data(result as unknown as Record<string, unknown>);

package/src/core/agents/index.ts

@@ -11,4 +11,10 @@ export * from "./canonical-emit.js";
 export * from "./coord-client.js";
 export * from "./live-observation-v3.js";
 export * from "./session-events.js";
+export {
+  type AgentParentReference,
+  type AgentParentReferenceOptions,
+  type AgentParentSubject,
+  resolveAgentParentReference,
+} from "./state/parent-reference.js";
 export * from "./state/session-state.js";

package/src/core/agents/live-authority-v3.ts

@@ -25,10 +25,10 @@ import {
 } from "../events/v3/producers/coordination-recorder.ts";
 import {
   type HookProducerStateV3,
-  listHookProducerStateRecordsV3,
   readHookProducerStateV3,
   readTerminalHookProducerStateV3,
   recordHookSignalV3,
+  scanHookProducerStateRecordsV3,
 } from "../events/v3/producers/recorder.ts";
 import { canonicalClaimPath } from "./claim-path.ts";
 import {
@@ -259,13 +259,20 @@ function readInstanceProducerStatesForBootstrap(
   coordRoot: string,
   instanceId: `inst_${string}`,
 ): HookProducerStateV3[] {
+  let scan: ReturnType<typeof scanHookProducerStateRecordsV3>;
   try {
-    return listHookProducerStateRecordsV3(coordRoot, { includeTerminal: true })
-      .map((record) => record.state)
-      .filter((state) => state.instance_id === instanceId);
+    scan = scanHookProducerStateRecordsV3(coordRoot, { includeTerminal: true });
   } catch {
     throw new LiveCoordinationAuthorityV3Error("producer_state_unsafe");
   }
+  // Another session's invalid file does not block this one; this instance's
+  // own invalid file still fails closed.
+  if (scan.invalid.some((file) => file.instance_id === instanceId)) {
+    throw new LiveCoordinationAuthorityV3Error("producer_state_unsafe");
+  }
+  return scan.records
+    .map((record) => record.state)
+    .filter((state) => state.instance_id === instanceId);
 }
 
 function terminalGenerationForSession(

package/src/core/agents/render/session-context.ts

@@ -8,7 +8,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { resolveBinName, resolveHooksSetupHint } from "../../config.ts";
 import { harneryVersion, loadAdapterWiring } from "../../hooks/adapter/wiring.ts";
@@ -482,9 +482,3 @@ export function formatPendingCouncils(coordRoot: string, agentName: string): str
   }
   return `Councils waiting on your input (${pending.length} open): ${list}. Run \`${bin} agents council list --mine\` to see all of them, then \`${bin} agents council show <id>\` for any brief.`;
 }
-
-/**
- * Suppress unused import warning when statSync isn't used in this file
- * (kept exported for future renderers, e.g. heartbeat-freshness coloring).
- */
-export const _ensureStatSyncImported = statSync;

package/src/core/agents/session-events.ts

@@ -89,9 +89,20 @@ function commandKey(fields: Record<string, unknown>): string | undefined {
     : undefined;
 }
 
-function flushCommandOutput(command: PendingCommand): void {
+/**
+ * `deferDrain` stages each summary durably in the spool without appending it,
+ * for a caller that writes the completion next: that write drains every staged
+ * row under one lease and one witness advance instead of one per row.
+ */
+function flushCommandOutput(command: PendingCommand, deferDrain = false): void {
   for (const summary of command.streams.values()) {
-    recordCommandObservation("command.output_observed", command.fields, command.coordRoot, summary);
+    recordCommandObservation(
+      "command.output_observed",
+      command.fields,
+      command.coordRoot,
+      summary,
+      deferDrain,
+    );
   }
   command.streams.clear();
 }
@@ -104,6 +115,7 @@ function recordCommandObservation(
   fields: Record<string, unknown>,
   coordRoot: string,
   summary?: OutputSummary,
+  deferDrain = false,
 ): boolean {
   const instanceId = typeof fields.instance_id === "string" ? fields.instance_id : undefined;
   if (!instanceId) return false;
@@ -134,6 +146,7 @@ function recordCommandObservation(
       platform: livePlatformV3(),
       ...(fields.bridge === "codex-wsl" ? { bridge: "codex-wsl" as const } : {}),
       monotonic_ns: process.hrtime.bigint().toString(),
+      ...(deferDrain ? { writerOptions: { deferDrain: true } } : {}),
     });
     if (result.state === "generation_unavailable") {
       const expectedLifecycleReopenGap =
@@ -276,7 +289,9 @@ export function writeSessionEvent(
     const coordRoot = command?.coordRoot ?? coordinationRootPath();
     if (type === "command.completed") {
       pendingCommands.delete(key);
-      if (command) flushCommandOutput(command);
+      // The completion below drains the staged summaries with itself. If it
+      // never writes, the rows stay durable in the spool for the next drain.
+      if (command) flushCommandOutput(command, true);
       recordCommandObservation(type, fields, coordRoot);
     } else if (recordCommandObservation(type, fields, coordRoot) && !command) {
       pendingCommands.set(key, {

package/src/core/agents/state/heartbeat-reader.ts

@@ -2,6 +2,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve, sep } from "node:path";
+import type { AgentParentReference } from "./parent-reference-contract.ts";
 import type { AgentActivity, TaskState } from "./session-state.ts";
 
 export interface Heartbeat {
@@ -50,6 +51,8 @@ export interface Heartbeat {
   last_status_at?: string;
   current_turn_id?: string;
   parent_instance_id?: string;
+  /** Read-only display/recipient evidence; never a claim or lifecycle authority input. */
+  parent_reference?: AgentParentReference;
   workflow_run_id?: string;
   workflow_agent_id?: string;
   /** Disposable-cache bindings that prove a row belongs to the current V3 generation. */

package/src/core/agents/state/live-coordination-view.ts

@@ -27,6 +27,17 @@ export interface V3HeartbeatMaterialization extends Heartbeat {
   v3_task_state: "set" | "cleared";
 }
 
+/** Index exact generations; a current replacement never erases its terminal predecessor. */
+export function indexCoordinationGenerationsV3(
+  view: CoordinationViewV3,
+): ReadonlyMap<string, CoordinationGenerationViewV3> {
+  return new Map(
+    [...Object.values(view.terminal_generations), ...Object.values(view.instances)].map(
+      (generation) => [generation.generation_id, generation],
+    ),
+  );
+}
+
 /** Read the live coordination rows through the hard-cut ledger route. */
 export function readLiveCoordinationRows(coordRoot: string): V3HeartbeatMaterialization[] {
   const route = observeLiveEventLedgerRouteV3(coordRoot);
@@ -38,9 +49,7 @@ export function readLiveCoordinationRows(coordRoot: string): V3HeartbeatMaterial
     return [];
   }
   const caches = readV3Caches(coordRoot);
-  const byGeneration = new Map(
-    Object.values(view.instances).map((generation) => [generation.generation_id, generation]),
-  );
+  const byGeneration = indexCoordinationGenerationsV3(view);
   return Object.values(view.instances)
     .filter((generation) => generation.authority_eligible)
     .map((generation) => {
@@ -70,9 +79,7 @@ export function readLiveCoordinationRow(
     if (!generation?.authority_eligible) return null;
     const cache = readHeartbeat(coordRoot, nativeInstanceId);
     const parent = generation.parent_generation_id
-      ? Object.values(view.instances).find(
-          (candidate) => candidate.generation_id === generation.parent_generation_id,
-        )
+      ? indexCoordinationGenerationsV3(view).get(generation.parent_generation_id)
       : undefined;
     return projectHeartbeatV3(
       coordRoot,

package/src/core/agents/state/parent-reference-contract.ts

@@ -0,0 +1,14 @@
+export type AgentParentReference =
+  | {
+      state: "verified";
+      relationship: "delegated-child" | "native-child";
+      parent_instance_id: string;
+      parent_v3_instance_id: string;
+      parent_generation_id: string | null;
+      parent_session_id: string | null;
+      parent_name: string | null;
+      source: "v3-session-link" | "native-session-metadata";
+      source_witness?: string;
+      addressable: boolean;
+    }
+  | { state: "none" | "unknown" | "conflict"; reason: string };

package/src/core/agents/state/parent-reference.ts

@@ -0,0 +1,179 @@
+import type {
+  CoordinationGenerationViewV3,
+  CoordinationViewV3,
+} from "../../events/v3/coordination-view.ts";
+import { readCoordinationViewV3 } from "../../events/v3/coordination-view.ts";
+import { liveInstanceIdV3, nativeInstanceIdV3 } from "../../events/v3/live-route-observer.ts";
+import {
+  type NativeParentObservation,
+  type NativeParentRequest,
+  readNativeParentReference,
+} from "../../hooks/adapter/native-parent.ts";
+import { resolveName } from "./names.ts";
+import type { AgentParentReference } from "./parent-reference-contract.ts";
+
+export type { AgentParentReference } from "./parent-reference-contract.ts";
+
+export interface AgentParentSubject {
+  instance_id: string;
+  generation_id?: string;
+  v3_generation_id?: string;
+  platform?: string;
+  native_session_id?: string;
+}
+
+export interface AgentParentReferenceOptions {
+  view?: CoordinationViewV3;
+  readNativeParent?: (request: NativeParentRequest) => NativeParentObservation;
+}
+
+/** Display/recipient evidence only. Never use native evidence as a claim or lifecycle waiver. */
+export function resolveAgentParentReference(
+  coordRoot: string,
+  child: AgentParentSubject,
+  options: AgentParentReferenceOptions = {},
+): AgentParentReference {
+  try {
+    const view = options.view ?? readCoordinationViewV3(coordRoot);
+    if (!view.source_complete || !view.authority_safe) return unknown("parent_authority_unsafe");
+    if (
+      child.generation_id &&
+      child.v3_generation_id &&
+      child.generation_id !== child.v3_generation_id
+    ) {
+      return unknown("child_generation_mismatch");
+    }
+    const instance = liveInstanceIdV3(child.instance_id);
+    const generationId = child.generation_id ?? child.v3_generation_id;
+    const generations = [
+      ...Object.values(view.instances),
+      ...Object.values(view.terminal_generations),
+    ];
+    const generation = generationId
+      ? generations.find(
+          (row) => row.generation_id === generationId && row.instance_id === instance,
+        )
+      : view.instances[instance];
+    if (!generation) return unknown("child_generation_unavailable");
+    if (!safe(view, generation)) return unknown("child_authority_unsafe");
+    const canonical = generation.parent_generation_id
+      ? generations.find((row) => row.generation_id === generation.parent_generation_id)
+      : undefined;
+    if (generation.parent_generation_id && !canonical)
+      return unknown("parent_generation_unavailable");
+    if (canonical && cyclic(generations, generation)) {
+      return { state: "conflict", reason: "parent_lineage_cycle" };
+    }
+    const adapter = generation.runtime_attestation.adapter;
+    const platform = adapter.state === "observed" ? adapter.value.id : child.platform;
+    const nativeId = child.native_session_id ?? nativeInstanceIdV3(instance);
+    const native =
+      platform === "codex" && liveInstanceIdV3(nativeId) === instance
+        ? (options.readNativeParent ?? readNativeParentReference)({
+            adapter: platform,
+            native_session_id: nativeId,
+          })
+        : ({ state: "unknown", reason: "native_child_identity_unavailable" } as const);
+    if (canonical) {
+      if (
+        native.state === "none" ||
+        (native.state === "observed" &&
+          liveInstanceIdV3(native.parent_session_id) !== canonical.instance_id)
+      ) {
+        return { state: "conflict", reason: "parent_sources_disagree" };
+      }
+      return reference(coordRoot, view, canonical.instance_id, canonical, "v3-session-link");
+    }
+    if (native.state === "observed") {
+      const parentInstance = liveInstanceIdV3(native.parent_session_id);
+      if (parentInstance === instance)
+        return { state: "conflict", reason: "parent_self_reference" };
+      const parent = recipientGeneration(view, parentInstance);
+      if (parent && cyclic(generations, generation, parent)) {
+        return { state: "conflict", reason: "parent_lineage_cycle" };
+      }
+      return reference(
+        coordRoot,
+        view,
+        parentInstance,
+        parent,
+        "native-session-metadata",
+        native.source_witness,
+      );
+    }
+    return { state: native.state, reason: native.reason };
+  } catch {
+    return unknown("parent_reference_unavailable");
+  }
+}
+
+function reference(
+  root: string,
+  view: CoordinationViewV3,
+  instance: string,
+  parent: CoordinationGenerationViewV3 | undefined,
+  source: "v3-session-link" | "native-session-metadata",
+  witness?: string,
+): AgentParentReference {
+  const native = nativeInstanceIdV3(instance);
+  const name = resolveName(root, native)?.name ?? null;
+  const recipient = recipientGeneration(view, instance);
+  return {
+    state: "verified",
+    relationship: source === "v3-session-link" ? "delegated-child" : "native-child",
+    parent_instance_id: native,
+    parent_v3_instance_id: instance,
+    parent_generation_id: parent?.generation_id ?? null,
+    parent_session_id: parent?.session_id ?? null,
+    parent_name: name,
+    source,
+    ...(witness ? { source_witness: witness } : {}),
+    addressable: Boolean(
+      parent && recipient?.generation_id === parent.generation_id && safe(view, parent) && name,
+    ),
+  };
+}
+
+function recipientGeneration(view: CoordinationViewV3, instance: string) {
+  return (
+    view.instances[instance] ??
+    Object.values(view.terminal_generations)
+      .filter((row) => row.instance_id === instance)
+      .sort(
+        (a, b) =>
+          b.source_position.segment_ordinal - a.source_position.segment_ordinal ||
+          b.source_position.byte_offset - a.source_position.byte_offset,
+      )[0]
+  );
+}
+
+function safe(view: CoordinationViewV3, generation: CoordinationGenerationViewV3): boolean {
+  return !(view.diagnostics_by_generation[generation.generation_id] ?? []).some(
+    (d) => d.authority_blocking,
+  );
+}
+
+function cyclic(
+  generations: CoordinationGenerationViewV3[],
+  child: CoordinationGenerationViewV3,
+  first?: CoordinationGenerationViewV3,
+): boolean {
+  const seen = new Set([child.generation_id]);
+  let cursor = first ?? child;
+  for (let depth = 0; depth <= generations.length; depth++) {
+    if (cursor !== child) {
+      if (seen.has(cursor.generation_id) || cursor.instance_id === child.instance_id) return true;
+      seen.add(cursor.generation_id);
+    }
+    if (!cursor.parent_generation_id) return false;
+    const next = generations.find((g) => g.generation_id === cursor.parent_generation_id);
+    if (!next) return false;
+    if (seen.has(next.generation_id)) return true;
+    cursor = next;
+  }
+  return true;
+}
+
+function unknown(reason: string): AgentParentReference {
+  return { state: "unknown", reason };
+}