harnery 0.32.0 → 0.34.0

package/src/core/agents/finalization.ts

@@ -10,9 +10,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { type AgentFinalizationDisposition, agentsFinalizationRoots } from "../config.ts";
-import { readStreamTailBounded } from "./events/consume.ts";
-
-const CLAIM_HISTORY_CAP_BYTES = 128 * 1024 * 1024;
+import { readFinalizationScopeV3 } from "../events/v3/finalization-view.ts";
+import { liveInstanceIdV3, resolveLiveEventLedgerRouteV3 } from "../events/v3/live-routing.ts";
 
 const GIT_DISCOVERY_VARS = [
   "GIT_DIR",
@@ -42,6 +41,9 @@ export interface GitFinalizationResult {
   claim_history_complete: boolean;
   dirty_paths: string[];
   unpushed_repos: string[];
+  behind_repos: string[];
+  stale_submodules: string[];
+  diverged_submodules: string[];
   host_output_paths: string[];
   unsupported_paths: UnsupportedFinalizationPath[];
   unverifiable_paths: string[];
@@ -94,38 +96,16 @@ export interface SessionWriteClaims {
 export function readSessionWriteClaims(
   coordRoot: string,
   instanceId: string,
-  sessionId: string,
+  _sessionId: string,
 ): SessionWriteClaims {
-  const streamPath = join(coordRoot, ".harnery", "events.ndjson");
-  const { text, truncated } = readStreamTailBounded(streamPath, CLAIM_HISTORY_CAP_BYTES);
-  const paths = new Set<string>();
-  let sawSessionStart = false;
-
-  for (const line of text.split("\n")) {
-    if (line.trim().length === 0) continue;
-    try {
-      const event = JSON.parse(line) as {
-        event_type?: string;
-        instance_id?: string;
-        session_id?: string;
-        data?: { path?: unknown; mode?: unknown };
-      };
-      if (event.instance_id !== instanceId || event.session_id !== sessionId) continue;
-      if (event.event_type === "session.start") sawSessionStart = true;
-      if (
-        event.event_type === "claim.acquire" &&
-        event.data?.mode === "write" &&
-        typeof event.data.path === "string"
-      ) {
-        paths.add(event.data.path);
-      }
-    } catch {
-      // Ignore malformed and crash-truncated event lines, matching the
-      // canonical stream consumer's recovery behavior.
-    }
+  const route = resolveLiveEventLedgerRouteV3(coordRoot);
+  if (route.state === "blocked") return { paths: [], complete: false };
+  try {
+    const scope = readFinalizationScopeV3(coordRoot, liveInstanceIdV3(instanceId));
+    return { paths: scope.files_touched, complete: true };
+  } catch {
+    return { paths: [], complete: false };
   }
-
-  return { paths: [...paths], complete: !truncated || sawSessionStart };
 }
 
 function git(args: string[], cwd: string): GitResult {
@@ -417,6 +397,64 @@ function repoSyncState(repoRoot: string): "synced" | "unpushed" | "unverifiable"
   return containing.stdout.trim().length > 0 ? "synced" : "unpushed";
 }
 
+function repoIsBehindUpstream(repoRoot: string): boolean {
+  if (!repoHasRemote(repoRoot)) return false;
+  const upstream = git(
+    ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"],
+    repoRoot,
+  );
+  if (upstream.status !== 0) return false;
+  const behind = git(["rev-list", "--count", "HEAD..@{upstream}"], repoRoot);
+  return behind.status === 0 && Number.parseInt(behind.stdout.trim(), 10) > 0;
+}
+
+function rootSubmoduleFreshness(repoRoot: string): {
+  stale: string[];
+  diverged: string[];
+} {
+  const modules = git(
+    ["config", "--file", ".gitmodules", "--get-regexp", "^submodule\\..*\\.path$"],
+    repoRoot,
+  );
+  if (modules.status !== 0 || modules.stdout.trim().length === 0) {
+    return { stale: [], diverged: [] };
+  }
+
+  const stale: string[] = [];
+  const diverged: string[] = [];
+  for (const line of modules.stdout.trim().split("\n")) {
+    const path = line.trim().split(/\s+/).at(-1);
+    if (!path) continue;
+    const target = git(["rev-parse", `HEAD:${path}`], repoRoot);
+    const checkout = git(["rev-parse", "HEAD"], join(repoRoot, path));
+    if (target.status !== 0 || checkout.status !== 0) {
+      stale.push(path);
+      continue;
+    }
+    const targetSha = target.stdout.trim();
+    const checkoutSha = checkout.stdout.trim();
+    if (targetSha === checkoutSha) continue;
+
+    const checkoutBehind = git(
+      ["merge-base", "--is-ancestor", checkoutSha, targetSha],
+      join(repoRoot, path),
+    );
+    if (checkoutBehind.status === 0) {
+      stale.push(path);
+      continue;
+    }
+    const checkoutAhead = git(
+      ["merge-base", "--is-ancestor", targetSha, checkoutSha],
+      join(repoRoot, path),
+    );
+    // A checkout ahead of its gitlink is in-flight local work. Its owning
+    // session is responsible for the eventual pointer bump; unrelated turns
+    // must not be blocked globally while that work is active.
+    if (checkoutAhead.status !== 0) diverged.push(path);
+  }
+  return { stale: stale.sort(), diverged: diverged.sort() };
+}
+
 /** Compare gitlink commits without treating dirty contents inside the child as a pointer change. */
 function gitlinkIsDirty(parentRoot: string, gitlink: string): boolean {
   const head = git(["rev-parse", `HEAD:${gitlink}`], parentRoot);
@@ -435,6 +473,9 @@ export function checkGitFinalization(
   options: { claimHistoryComplete?: boolean } = {},
 ): GitFinalizationResult {
   const root = resolve(coordRoot);
+  // Repository discovery resolves symlinks. Use the same physical base for
+  // display labels so macOS /var -> /private/var aliases stay repo-relative.
+  const labelRoot = physicalPath(root) ?? root;
   const repos = new Map<string, RepoWork>();
   const hostOutputPaths = new Set<string>();
   const unsupportedPaths: UnsupportedFinalizationPath[] = [];
@@ -466,7 +507,7 @@ export function checkGitFinalization(
     for (const repoPath of work.paths) {
       if (work.gitlinks.has(repoPath)) {
         if (gitlinkIsDirty(work.root, repoPath)) {
-          const label = repoLabel(root, work.root);
+          const label = repoLabel(labelRoot, work.root);
           dirtyPaths.add(label === "." ? repoPath : `${label}/${repoPath}`);
         }
         continue;
@@ -476,36 +517,47 @@ export function checkGitFinalization(
         work.root,
       );
       if (status.status !== 0) {
-        unverifiablePaths.push(join(repoLabel(root, work.root), repoPath).replaceAll("\\", "/"));
+        unverifiablePaths.push(
+          join(repoLabel(labelRoot, work.root), repoPath).replaceAll("\\", "/"),
+        );
       } else if (status.stdout.length > 0) {
-        const label = repoLabel(root, work.root);
+        const label = repoLabel(labelRoot, work.root);
         dirtyPaths.add(label === "." ? repoPath : `${label}/${repoPath}`);
       }
     }
 
     const syncState = repoSyncState(work.root);
-    const label = repoLabel(root, work.root);
+    const label = repoLabel(labelRoot, work.root);
     if (syncState === "unpushed") unpushedRepos.push(label);
     if (syncState === "unverifiable") unverifiableRepos.push(label);
   }
 
+  const behindRepos = repoIsBehindUpstream(root) ? ["."] : [];
+  const submoduleFreshness = rootSubmoduleFreshness(root);
+
   const result: GitFinalizationResult = {
     ok: false,
     claim_history_complete: options.claimHistoryComplete ?? true,
     dirty_paths: [...dirtyPaths].sort(),
     unpushed_repos: [...new Set(unpushedRepos)].sort(),
+    behind_repos: behindRepos,
+    stale_submodules: submoduleFreshness.stale,
+    diverged_submodules: submoduleFreshness.diverged,
     host_output_paths: [...hostOutputPaths].sort(),
     unsupported_paths: unsupportedPaths.sort(
       (a, b) => a.path.localeCompare(b.path) || a.reason.localeCompare(b.reason),
     ),
     unverifiable_paths: [...new Set(unverifiablePaths)].sort(),
     unverifiable_repos: [...new Set(unverifiableRepos)].sort(),
-    repos_checked: [...repos.keys()].map((repo) => repoLabel(root, repo)).sort(),
+    repos_checked: [...repos.keys()].map((repo) => repoLabel(labelRoot, repo)).sort(),
   };
   result.ok =
     result.claim_history_complete &&
     result.dirty_paths.length === 0 &&
     result.unpushed_repos.length === 0 &&
+    result.behind_repos.length === 0 &&
+    result.stale_submodules.length === 0 &&
+    result.diverged_submodules.length === 0 &&
     result.unsupported_paths.length === 0 &&
     result.unverifiable_paths.length === 0 &&
     result.unverifiable_repos.length === 0;
@@ -526,6 +578,24 @@ export function formatGitFinalizationFailure(result: GitFinalizationResult, bin:
       ...result.unpushed_repos.map((repo) => `  - ${repo}`),
     );
   }
+  if (result.behind_repos.length > 0) {
+    lines.push(
+      "Repositories behind their upstream:",
+      ...result.behind_repos.map((repo) => `  - ${repo}`),
+    );
+  }
+  if (result.stale_submodules.length > 0) {
+    lines.push(
+      "Submodule checkouts behind their parent gitlinks:",
+      ...result.stale_submodules.map((path) => `  - ${path}`),
+    );
+  }
+  if (result.diverged_submodules.length > 0) {
+    lines.push(
+      "Submodule checkouts diverged from their parent gitlinks:",
+      ...result.diverged_submodules.map((path) => `  - ${path}`),
+    );
+  }
   if (result.unsupported_paths.length > 0) {
     lines.push(
       "Paths without an authorized end-turn disposition:",
@@ -549,6 +619,9 @@ export function formatGitFinalizationFailure(result: GitFinalizationResult, bin:
   if (
     result.dirty_paths.length > 0 ||
     result.unpushed_repos.length > 0 ||
+    result.behind_repos.length > 0 ||
+    result.stale_submodules.length > 0 ||
+    result.diverged_submodules.length > 0 ||
     result.unverifiable_paths.length > 0 ||
     result.unverifiable_repos.length > 0
   ) {
@@ -556,6 +629,15 @@ export function formatGitFinalizationFailure(result: GitFinalizationResult, bin:
       `Commit and push the owned Git work, then rerun \`${bin} agents status --end-turn\`.`,
     );
   }
+  if (
+    result.behind_repos.length > 0 ||
+    result.stale_submodules.length > 0 ||
+    result.diverged_submodules.length > 0
+  ) {
+    lines.push(
+      "Run the host repository's safe sync command, resolve any reported submodule state, then rerun the guarded status.",
+    );
+  }
   if (result.unsupported_paths.length > 0) {
     lines.push(
       "For a legacy claim, add the containing Git repository or intentional non-Git output root to the project's `agents.finalizationRoots`, then rerun the guarded status. For new work, start the task from the target Git project or configure that root before editing.",

package/src/core/agents/index.ts

@@ -1,14 +1,14 @@
 /**
  * agent-coord library public exports.
  *
- * `coord-client`: coordination helpers
- * (Heartbeat reader, owner-resolver via ppid-walk, monorepo-root finder).
- * Imported by every TS caller that needs to read coord state.
+ * `coord-client`: V3 producer identity resolution, ppid-map attribution, and
+ * coordination-root discovery.
  *
- * `canonical-emit`: fire-and-forget client for the canonical event stream;
- * spawns `bin/agent-coord emit-event` and never blocks the caller.
+ * `canonical-emit`: canonical V3 observation helpers.
  */
 
 export * from "./canonical-emit.js";
 export * from "./coord-client.js";
+export * from "./live-observation-v3.js";
 export * from "./session-events.js";
+export * from "./state/session-state.js";

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

@@ -0,0 +1,375 @@
+import { randomUUID } from "node:crypto";
+import type { Adapter } from "../adapter.ts";
+import type { AuthorityMutationV3 } from "../events/v3/authority-outbox.ts";
+import { canonicalJsonV3, sha256V3 } from "../events/v3/canonical.ts";
+import type { EventV3WriteMode } from "../events/v3/control.ts";
+import {
+  readCoordinationViewV3,
+  requireAuthoritySafeCoordinationViewV3,
+} from "../events/v3/coordination-view.ts";
+import {
+  LIVE_HOOK_V3_PRODUCER_ID,
+  liveInstanceIdV3,
+  livePlatformV3,
+  resolveLiveEventLedgerRouteV3,
+} from "../events/v3/live-routing.ts";
+import type {
+  CoordinationAuthoritySignalV3,
+  CoordinationObservationBySignalV3,
+} from "../events/v3/producers/coordination.ts";
+import {
+  type RecordCoordinationAuthorityV3Result,
+  recordCoordinationAuthorityV3,
+} from "../events/v3/producers/coordination-recorder.ts";
+import {
+  readTerminalHookProducerStateV3,
+  recordHookSignalV3,
+} from "../events/v3/producers/recorder.ts";
+import {
+  acquireClaim,
+  type Heartbeat,
+  readHeartbeat,
+  releaseClaim,
+  setIdentityCache,
+  setLifecycleCache,
+  setTask,
+} from "./state/heartbeat-writer.ts";
+import {
+  ensureLiveCoordinationHeartbeat,
+  liveCoordinationAdapterV3,
+} from "./state/live-coordination-view.ts";
+import { recordNameAssumption } from "./state/names.ts";
+
+export const LIVE_COORDINATION_V3_PRODUCER_ID = "prd_agent-coord" as const;
+
+export class LiveCoordinationAuthorityV3Error extends Error {
+  constructor(public readonly reason: string) {
+    super(`event_v3_coordination_authority:${reason}`);
+    this.name = "LiveCoordinationAuthorityV3Error";
+  }
+}
+
+export type LiveCoordinationAuthorityV3Result =
+  | { state: "unchanged" }
+  | { state: "recorded"; result: RecordCoordinationAuthorityV3Result };
+
+export interface ReopenedLiveCoordinationGenerationV3 {
+  state: "reopened";
+  adapter: Adapter;
+  prior_generation_id: `gen_${string}`;
+  generation_id: `gen_${string}`;
+}
+
+interface LiveAuthorityBaseV3 {
+  coordRoot: string;
+  owner: string;
+  subject?: string;
+  nativeSessionId: string;
+  adapter: Adapter;
+  observationId?: string;
+}
+
+/**
+ * Open a fresh derived generation for a human-facing session that is executing
+ * again after an authoritative terminal. The terminal generation is never
+ * changed or reused.
+ */
+export function reopenLiveCoordinationGenerationV3(input: {
+  coordRoot: string;
+  owner: string;
+  nativeSessionId: string;
+}): ReopenedLiveCoordinationGenerationV3 {
+  const route = resolveLiveEventLedgerRouteV3(input.coordRoot);
+  if (route.state === "blocked") throw new LiveCoordinationAuthorityV3Error(route.reason);
+  const instanceId = liveInstanceIdV3(input.owner);
+  const terminal = readTerminalHookProducerStateV3(
+    input.coordRoot,
+    input.nativeSessionId,
+    instanceId,
+  );
+  if (!terminal) {
+    throw new LiveCoordinationAuthorityV3Error("terminal_generation_identity_missing");
+  }
+  const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(input.coordRoot));
+  const terminalView = view.terminal_generations[terminal.generation_id];
+  if (!terminalView || terminalView.instance_id !== instanceId) {
+    throw new LiveCoordinationAuthorityV3Error("terminal_generation_authority_missing");
+  }
+  if (terminalView.parent_generation_id || terminalView.delegation_id || terminalView.workflow_id) {
+    throw new LiveCoordinationAuthorityV3Error("lifecycle_not_human_facing");
+  }
+  const reopened = recordHookSignalV3({
+    coordRoot: input.coordRoot,
+    mode: route.mode,
+    signal: "session-start",
+    payload: { raw: {}, session_id: input.nativeSessionId },
+    adapter: terminal.adapter,
+    instance_id: instanceId,
+    producer_id: LIVE_HOOK_V3_PRODUCER_ID,
+    build_id: route.build_id,
+    platform: livePlatformV3(),
+    session_start_derivation: "approved_lifecycle_reopen",
+  });
+  if (reopened.state !== "recorded" && reopened.state !== "already_started") {
+    throw new LiveCoordinationAuthorityV3Error(`generation_reopen_failed:${reopened.state}`);
+  }
+  const heartbeat = ensureLiveCoordinationHeartbeat(
+    input.coordRoot,
+    input.owner,
+    input.nativeSessionId,
+    terminal.adapter,
+  );
+  if (!heartbeat) {
+    throw new LiveCoordinationAuthorityV3Error("reopened_generation_materialization_failed");
+  }
+  return {
+    state: "reopened",
+    adapter: terminal.adapter,
+    prior_generation_id: terminal.generation_id,
+    generation_id: heartbeat.v3_generation_id as `gen_${string}`,
+  };
+}
+
+export function recordLiveTaskChangeV3(
+  input: LiveAuthorityBaseV3 & { task: string },
+): LiveCoordinationAuthorityV3Result {
+  liveCoordinationWriteModeV3(input.coordRoot);
+  const before = requireHeartbeat(input, input.subject ?? input.owner);
+  const cleared = input.task.length === 0;
+  const desired = {
+    ...before,
+    task: undefined,
+    v3_task_state: cleared ? ("cleared" as const) : ("set" as const),
+  };
+  // A task declaration is also per-turn ritual evidence. Record repeated
+  // declarations, including cleared -> cleared, even when the disposable view
+  // does not change. Otherwise a conversational Cursor remediation turn can
+  // run `set-task ""` exactly as instructed and still loop forever because no
+  // coord.task_changed event reaches the verdict window.
+  return recordLiveAuthority(
+    input,
+    "task-changed",
+    {
+      native_observation_id: input.observationId ?? `task-${randomUUID()}`,
+      state: cleared ? "cleared" : "set",
+      ...(cleared ? {} : { task: input.task }),
+    },
+    before,
+    desired,
+    () => {
+      // The canonical event records only the privacy-safe set/cleared state.
+      // Task prose and its operator-facing suggested name live exclusively in
+      // this generation-bound disposable cache; they never enter the ledger.
+      if (!setTask(input.coordRoot, input.subject ?? input.owner, input.task)) {
+        throw new LiveCoordinationAuthorityV3Error("task_materialization_failed");
+      }
+    },
+  );
+}
+
+export function recordLiveLifecycleChangeV3(
+  input: LiveAuthorityBaseV3 & {
+    state: "active" | "blocked" | "done";
+    reason?: string;
+    suggestedSessionName?: string;
+    observedAt?: string;
+  },
+): LiveCoordinationAuthorityV3Result {
+  liveCoordinationWriteModeV3(input.coordRoot);
+  const subject = input.subject ?? input.owner;
+  const before = requireHeartbeat(input, subject);
+  const desired: Heartbeat = {
+    ...before,
+    task_state: input.state,
+    task_state_reason: input.state === "active" ? undefined : input.reason,
+    ...(input.suggestedSessionName ? { suggested_session_name: input.suggestedSessionName } : {}),
+  };
+  if (authorityStateDigest(before) === authorityStateDigest(desired)) return { state: "unchanged" };
+  return recordLiveAuthority(
+    input,
+    "lifecycle-changed",
+    {
+      native_observation_id: input.observationId ?? `lifecycle-${randomUUID()}`,
+      state: input.state,
+      ...(input.reason ? { reason_code: `operator_${input.state}` } : {}),
+    },
+    before,
+    desired,
+    () => {
+      if (
+        !setLifecycleCache(
+          input.coordRoot,
+          subject,
+          input.state,
+          input.reason,
+          input.suggestedSessionName,
+        )
+      ) {
+        throw new LiveCoordinationAuthorityV3Error("lifecycle_materialization_failed");
+      }
+    },
+  );
+}
+
+export function recordLiveClaimChangeV3(
+  input: LiveAuthorityBaseV3 & {
+    operation: "acquired" | "released";
+    path: string;
+    access?: "read" | "write";
+  },
+): LiveCoordinationAuthorityV3Result {
+  liveCoordinationWriteModeV3(input.coordRoot);
+  const subject = input.subject ?? input.owner;
+  const before = requireHeartbeat(input, subject);
+  const canonical = canonicalClaimPath(input.coordRoot, input.path);
+  const desiredFiles =
+    input.operation === "acquired"
+      ? [
+          ...new Set([
+            ...(before.files_touched ?? []).map((path) =>
+              canonicalClaimPath(input.coordRoot, path),
+            ),
+            canonical,
+          ]),
+        ].sort()
+      : (before.files_touched ?? []).filter(
+          (path) => canonicalClaimPath(input.coordRoot, path) !== canonical,
+        );
+  const desired: Heartbeat = { ...before, files_touched: desiredFiles };
+  if (authorityStateDigest(before) === authorityStateDigest(desired)) return { state: "unchanged" };
+  return recordLiveAuthority(
+    input,
+    "claim-changed",
+    {
+      native_observation_id: input.observationId ?? `claim-${randomUUID()}`,
+      operation: input.operation,
+      target: canonical,
+      access: input.access ?? "write",
+    },
+    before,
+    desired,
+    () => {
+      const result =
+        input.operation === "acquired"
+          ? acquireClaim(input.coordRoot, subject, canonical)
+          : releaseClaim(input.coordRoot, subject, canonical);
+      if (!result) throw new LiveCoordinationAuthorityV3Error("claim_materialization_failed");
+    },
+  );
+}
+
+export function recordLiveIdentityChangeV3(
+  input: LiveAuthorityBaseV3 & { name: string; identityId: string },
+): LiveCoordinationAuthorityV3Result {
+  liveCoordinationWriteModeV3(input.coordRoot);
+  const subject = input.subject ?? input.owner;
+  const before = requireHeartbeat(input, subject);
+  const desired: Heartbeat = { ...before, name: input.name, agent_id: input.identityId };
+  if (authorityStateDigest(before) === authorityStateDigest(desired)) return { state: "unchanged" };
+  return recordLiveAuthority(
+    input,
+    "identity-attested",
+    {
+      native_observation_id: input.observationId ?? `identity-${randomUUID()}`,
+      identity_id: input.identityId,
+      method: "operator_assumption",
+    },
+    before,
+    desired,
+    () => {
+      recordNameAssumption(input.coordRoot, subject, input.name, input.identityId, "session");
+      if (!setIdentityCache(input.coordRoot, subject, input.name, input.identityId)) {
+        throw new LiveCoordinationAuthorityV3Error("identity_materialization_failed");
+      }
+    },
+  );
+}
+
+function recordLiveAuthority<S extends CoordinationAuthoritySignalV3>(
+  input: LiveAuthorityBaseV3,
+  signal: S,
+  observation: CoordinationObservationBySignalV3[S],
+  expected: Heartbeat,
+  desired: Heartbeat,
+  apply: () => void,
+): LiveCoordinationAuthorityV3Result {
+  const route = resolveLiveEventLedgerRouteV3(input.coordRoot);
+  if (route.state === "blocked") throw new LiveCoordinationAuthorityV3Error(route.reason);
+  const adapter = liveCoordinationAdapterV3(input.coordRoot, input.owner);
+  if (!adapter) throw new LiveCoordinationAuthorityV3Error("actor_generation_missing");
+  const subject = input.subject ?? input.owner;
+  const result = recordAuthority({
+    coordRoot: input.coordRoot,
+    mode: route.mode,
+    signal,
+    observation,
+    adapter,
+    native_actor_session_id: input.nativeSessionId,
+    actor_instance_id: liveInstanceIdV3(input.owner),
+    subject_instance_id: liveInstanceIdV3(subject),
+    producer_id: LIVE_COORDINATION_V3_PRODUCER_ID,
+    build_id: route.build_id,
+    platform: livePlatformV3(),
+    expected_prior_state_digest: authorityStateDigest(expected),
+    desired_state_digest: authorityStateDigest(desired),
+    reconciler: {
+      readStateDigest: () => {
+        const heartbeat = readHeartbeat(input.coordRoot, subject);
+        if (!heartbeat || heartbeat.v3_generation_id !== expected.v3_generation_id) {
+          throw new LiveCoordinationAuthorityV3Error(`heartbeat_generation_mismatch:${subject}`);
+        }
+        return authorityStateDigest(heartbeat);
+      },
+      apply: (_mutation: AuthorityMutationV3) => apply(),
+    },
+  });
+  if (result.state === "gate_closed" || result.state === "generation_unavailable") {
+    throw new LiveCoordinationAuthorityV3Error(`${result.state}:${result.reason}`);
+  }
+  if (result.state === "pending_transaction") {
+    throw new LiveCoordinationAuthorityV3Error(`pending_transaction:${result.transaction_id}`);
+  }
+  return { state: "recorded", result };
+}
+
+function recordAuthority<S extends CoordinationAuthoritySignalV3>(
+  input: Parameters<typeof recordCoordinationAuthorityV3<S>>[0],
+): RecordCoordinationAuthorityV3Result {
+  return recordCoordinationAuthorityV3(input);
+}
+
+export function liveCoordinationWriteModeV3(coordRoot: string): EventV3WriteMode {
+  const route = resolveLiveEventLedgerRouteV3(coordRoot);
+  if (route.state === "blocked") throw new LiveCoordinationAuthorityV3Error(route.reason);
+  return route.mode;
+}
+
+function requireHeartbeat(input: LiveAuthorityBaseV3, owner: string): Heartbeat {
+  const heartbeat = ensureLiveCoordinationHeartbeat(
+    input.coordRoot,
+    owner,
+    owner === input.owner ? input.nativeSessionId : owner,
+    input.adapter,
+  );
+  if (!heartbeat) throw new LiveCoordinationAuthorityV3Error(`heartbeat_missing:${owner}`);
+  return heartbeat;
+}
+
+function authorityStateDigest(heartbeat: Heartbeat): `sha256:${string}` {
+  return sha256V3(
+    canonicalJsonV3({
+      instance_id: heartbeat.v3_instance_id ?? heartbeat.instance_id,
+      generation_id: heartbeat.v3_generation_id ?? null,
+      task_state: heartbeat.v3_task_state ?? (heartbeat.task ? "set" : "cleared"),
+      lifecycle_state: heartbeat.task_state ?? "active",
+      task_state_reason: heartbeat.task_state_reason ?? null,
+      files_touched: [...new Set(heartbeat.files_touched ?? [])].sort(),
+      identity_id: heartbeat.agent_id ?? null,
+      display_name: heartbeat.name ?? null,
+    }),
+  );
+}
+
+function canonicalClaimPath(coordRoot: string, path: string): string {
+  return path.startsWith(`${coordRoot}/`) ? path.slice(coordRoot.length + 1) : path;
+}