harnery 0.45.2 → 0.46.1

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/rules/claim-conflict.ts

@@ -18,7 +18,9 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { adapterFromPlatform as sharedAdapterFromPlatform } from "../../adapter.ts";
-import { recordLiveClaimChangeV3 } from "../live-authority-v3.ts";
+import { resolveBinName } from "../../config.ts";
+import { writeProducerDiagnosticV3 } from "../../events/v3/producers/intake.ts";
+import { LiveCoordinationAuthorityV3Error, recordLiveClaimChangeV3 } from "../live-authority-v3.ts";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.ts";
 
 const FRESHNESS_SECS = 600;
@@ -82,8 +84,15 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
     // prune the claim from their heartbeat and allow the edit. Skips when the
     // file doesn't exist (intent-to-create claim); that surface IS load-bearing.
     if (isFileCommittedClean(coordRoot, req.path)) {
-      if (!releaseClaimThroughLedger(coordRoot, conflict.instance_id, req.path, req)) {
-        return authorityUnavailable(req.path, "release the stale claim on");
+      const refused = releaseClaimThroughLedger(coordRoot, conflict.instance_id, req.path, req);
+      if (refused) {
+        return authorityUnavailable(
+          coordRoot,
+          req,
+          req.path,
+          "release the stale claim on",
+          refused,
+        );
       }
       // Fall through to ordering check + allow.
     } else {
@@ -146,8 +155,9 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
       // Every blocker is a finished (committed-clean) edit: prune them so they
       // stop constraining future acquisitions, then fall through to allow.
       for (const p of blockers) {
-        if (!releaseClaimThroughLedger(coordRoot, req.instance_id, p, req)) {
-          return authorityUnavailable(p, "release the completed claim on");
+        const refused = releaseClaimThroughLedger(coordRoot, req.instance_id, p, req);
+        if (refused) {
+          return authorityUnavailable(coordRoot, req, p, "release the completed claim on", refused);
         }
       }
     }
@@ -156,9 +166,8 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
   // Acquire the claim: atomic check-and-set. Adds req.path to my
   // files_touched if not already present.
   if (req.mode !== "read") {
-    if (!acquireClaimThroughLedger(coordRoot, req)) {
-      return authorityUnavailable(req.path, "acquire");
-    }
+    const refused = acquireClaimThroughLedger(coordRoot, req);
+    if (refused) return authorityUnavailable(coordRoot, req, req.path, "acquire", refused);
   }
 
   return { allow: true, exit_code: 0, rule: "claim.pass" };
@@ -242,7 +251,8 @@ function isFileCommittedClean(coordRoot: string, relPath: string): boolean {
   }
 }
 
-function acquireClaimThroughLedger(coordRoot: string, req: ClaimRequest): boolean {
+/** Returns null when the ledger recorded the claim, else the refusal reason. */
+function acquireClaimThroughLedger(coordRoot: string, req: ClaimRequest): string | null {
   const owner = readPeers(coordRoot).find((peer) => peer.instance_id === req.instance_id);
   try {
     recordLiveClaimChangeV3({
@@ -254,9 +264,9 @@ function acquireClaimThroughLedger(coordRoot: string, req: ClaimRequest): boolea
       path: req.path,
       access: "write",
     });
-    return true;
-  } catch {
-    return false;
+    return null;
+  } catch (error) {
+    return refusalReason(error);
   }
 }
 
@@ -265,7 +275,7 @@ function releaseClaimThroughLedger(
   subjectInstanceId: string,
   relPath: string,
   actor: ClaimRequest,
-): boolean {
+): string | null {
   const owner = readPeers(coordRoot).find((peer) => peer.instance_id === actor.instance_id);
   try {
     recordLiveClaimChangeV3({
@@ -278,17 +288,39 @@ function releaseClaimThroughLedger(
       path: relPath,
       access: "write",
     });
-    return true;
-  } catch {
-    return false;
+    return null;
+  } catch (error) {
+    return refusalReason(error);
   }
 }
 
-function authorityUnavailable(path: string, operation: string): VerdictResult {
+function refusalReason(error: unknown): string {
+  if (error instanceof LiveCoordinationAuthorityV3Error) return error.reason;
+  return error instanceof Error ? error.message : String(error);
+}
+
+function authorityUnavailable(
+  coordRoot: string,
+  req: ClaimRequest,
+  path: string,
+  operation: string,
+  refusal: string,
+): VerdictResult {
+  // The ledger's own reason is the only evidence of why a healthy-looking
+  // session cannot claim; a generic message sent agents to diagnose the wrong
+  // layer, so keep the reason in the verdict and in a durable diagnostic.
+  writeProducerDiagnosticV3(coordRoot, "claim_authority_refused", {
+    instance_id: req.instance_id,
+    operation,
+    reason: refusal,
+  });
   return {
     allow: false,
     exit_code: 2,
     rule: "claim.authority_unavailable",
-    reason: `Cannot safely ${operation} ${path}; V3 authority is unavailable.`,
+    reason:
+      `Cannot safely ${operation} ${path}; the coordination ledger refused the claim ` +
+      `(${refusal}). Run \`${resolveBinName(coordRoot)} agents health\` and retry; if health ` +
+      "is safe, the refusal reason above names the session state that blocked it.",
   };
 }

package/src/core/agents/rules/stop-hook.ts

@@ -36,6 +36,12 @@ export interface StopHookRequest {
   session_name_observation_unavailable?: boolean;
   bypass?: boolean;
   workflow_child?: boolean;
+  /**
+   * Claude Code moved this session's foreground command into the background
+   * and has not yet reported it finished. Finalization cannot pass until it
+   * does, so status and reply-box demands wait for the notification turn.
+   */
+  pending_background_handoff?: boolean;
 }
 
 export const STOP_REMEDIATION_MARKER = "[harnery:stop-remediation";
@@ -170,6 +176,7 @@ export function evaluateStopHookV3Events(
   // Pure prose turns keep the human-visible acknowledgement but do not require
   // task or final-status mutations. This preserves the pre-V3 policy exactly.
   if (!usedTool) {
+    if (!ackPresent && req.pending_background_handoff) return backgroundHandoffDeferred();
     if (!ackPresent) return withCycleAnchor(ackBlock(), cycleAnchor);
     return {
       allow: true,
@@ -203,12 +210,32 @@ export function evaluateStopHookV3Events(
     }
   }
 
-  const blocked = mergeStopBlocks(pending);
+  // A status check run now would refuse on the in-flight commit and a box
+  // cannot be issued without it, so bouncing only loops until the task ends.
+  // Task and naming evidence do not depend on the task and stay enforced.
+  const enforced = req.pending_background_handoff
+    ? pending.filter(
+        (block) => block.rule !== "stop-hook.rule_1_3" && block.rule !== "stop-hook.rule_2_3",
+      )
+    : pending;
+  const blocked = mergeStopBlocks(enforced);
   if (blocked) return withCycleAnchor(blocked, cycleAnchor);
+  if (enforced.length < pending.length) return backgroundHandoffDeferred();
 
   return { allow: true, exit_code: 0, rule: "stop-hook.pass" };
 }
 
+function backgroundHandoffDeferred(): VerdictResult {
+  return {
+    allow: true,
+    exit_code: 0,
+    rule: "stop-hook.background_handoff_deferred",
+    reason:
+      "a command Claude Code moved to the background is still running; status and reply-box " +
+      "evidence are required on the turn its completion notification starts",
+  };
+}
+
 function unconditionalVerdict(req: StopHookRequest): VerdictResult | undefined {
   if (req.bypass) {
     return {

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 };