harnery 0.45.1 → 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/commands/workflow.ts

@@ -73,15 +73,7 @@ interface WorkflowConfirmedMutationOpts {
 
 interface WorkflowReclaimOpts extends WorkflowConfirmedMutationOpts {
   discard?: boolean;
-  unknownLiveness?: string;
-  actor?: string;
-  reason?: string;
-}
-
-interface WorkflowUnlockOpts extends WorkflowConfirmedMutationOpts {
-  lockSha256?: string;
-  actor?: string;
-  reason?: string;
+  force?: boolean;
 }
 
 export function registerWorkflowCommand(program: Command, emit: EmitContext): void {
@@ -632,11 +624,9 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .option("--yes", "Confirm that this commits or discards uncommitted work, then releases")
     .option("--discard", "Throw the uncommitted work away instead of salvaging it")
     .option(
-      "--unknown-liveness <sha256>",
-      "Recover unknown evidence pinned by the preview digest; active evidence still refuses",
+      "--force",
+      "With --yes, admit missing or corrupt liveness evidence (active evidence still refuses) and record it",
     )
-    .option("--actor <id>", "Actor responsible for an audited recovery")
-    .option("--reason <text>", "Reason for an audited recovery")
     .option("--json", "Emit the reclaim preview or confirmed result as JSON")
     .action(async (runId: string, opts: WorkflowReclaimOpts) => {
       const coordRoot = resolveCoordRoot();
@@ -663,13 +653,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
         const result = await provider.reclaim(binding, {
           mode: opts.discard ? "discard" : "salvage",
           yes: opts.yes,
-          unknownLiveness: opts.unknownLiveness
-            ? {
-                evidenceSha256: opts.unknownLiveness,
-                actor: opts.actor!,
-                reason: opts.reason!,
-              }
-            : undefined,
+          force: opts.force,
         });
         if (opts.json) {
           emit.config({ format: "json" });
@@ -684,11 +668,13 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
           emit.text(
             `reclaim preview: ${result.run_id}\n` +
               `mode: ${result.mode}\nliveness: ${result.liveness}\nownership: ${result.ownership}\n` +
-              `evidence sha256: ${result.evidence_sha256}\n` +
               `lease holder: ${holders.length > 0 ? holders.join(", ") : "none observed"}\n` +
               `dirty paths: ${result.dirty_paths === null ? "unknown" : result.dirty_paths.length > 0 ? result.dirty_paths.join(", ") : "none"}\n` +
               (result.ownership_detail ? `ownership detail: ${result.ownership_detail}\n` : "") +
-              `Pass --yes to confirm ${result.mode} and release after all checks pass.\n`,
+              `Pass --yes to confirm ${result.mode} and release after all checks pass.\n` +
+              (result.liveness === "unknown"
+                ? "Liveness is unknown; add --force with --yes only if the run is known to be stopped.\n"
+                : ""),
           );
           return;
         }
@@ -708,42 +694,6 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
       }
     });
 
-  workflow
-    .command("unlock <run-id>")
-    .description(
-      "Preview or explicitly retire one exact resume lock whose local owner is proven dead.",
-    )
-    .option("--lock-sha256 <sha256>", "Exact lock identity digest returned by the preview")
-    .option("--actor <id>", "Actor responsible for the recovery")
-    .option("--reason <text>", "Reason for the recovery")
-    .option("--yes", "Confirm removal after dead-owner and exact-lock checks")
-    .option("--json", "Emit the recovery preview or result as JSON")
-    .action(async (runId: string, opts: WorkflowUnlockOpts) => {
-      try {
-        const coordRoot = resolveCoordRoot();
-        if (!coordRoot) throw new Error("no .harnery/ coordination root found");
-        const { recoverWorkflowResumeLease } = await import("../core/workflow/index.ts");
-        const result = recoverWorkflowResumeLease(coordRoot, runId, opts);
-        if (opts.json) {
-          emit.config({ format: "json" });
-          emit.data(result);
-          return;
-        }
-        emit.text(
-          `resume lock ${result.action}: ${runId}\nowner: ${result.owner_state}\nlock sha256: ${result.lock_sha256 ?? "absent"}\n` +
-            (result.action === "preview"
-              ? "Pass --lock-sha256, --actor, --reason and --yes to confirm exact dead-owner recovery.\n"
-              : `recovery: ${result.recovery_id}\n`),
-        );
-      } catch (error) {
-        emit.error({
-          code: "workflow_resume_unlock_failed",
-          message: error instanceof Error ? error.message : String(error),
-        });
-        process.exit(1);
-      }
-    });
-
   const approvals = program
     .command("approval")
     .description("Inspect and resolve durable run-policy approvals.");

package/src/core/agents/coord-client.ts

@@ -265,27 +265,7 @@ export function parsePidmapRowStartToken(row: string): string | undefined {
  * a test can hold this one against `processStartToken` and fail on drift.
  */
 export function pidStartToken(pid: number): string | null {
-  if (!Number.isInteger(pid) || pid <= 0) return null;
   const forced = process.env.HARNERY_PID_PROBE;
-  if (process.platform === "win32" && forced !== "procfs" && forced !== "ps") {
-    try {
-      const out = spawnSync(
-        "powershell.exe",
-        [
-          "-NoLogo",
-          "-NoProfile",
-          "-NonInteractive",
-          "-Command",
-          `$process = [Diagnostics.Process]::GetProcessById(${pid}); try { 'w' + $process.StartTime.ToFileTimeUtc().ToString([Globalization.CultureInfo]::InvariantCulture) } finally { $process.Dispose() }`,
-        ],
-        { encoding: "utf8", timeout: 10_000, windowsHide: true },
-      );
-      const token = String(out.stdout ?? "").trim();
-      return out.status === 0 && /^w\d+$/.test(token) ? token : null;
-    } catch {
-      return null;
-    }
-  }
   const useProcfs = forced === "procfs" || (forced !== "ps" && existsSync("/proc/self/stat"));
   // One machine, one probe. Falling back to the other on a read failure would
   // answer in the wrong dialect and read as a recycled pid.

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