harnery 0.35.0 → 0.37.0

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

@@ -1,12 +1,13 @@
 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 { canonicalJsonV3, normalizeNativeIdV3, sha256V3 } from "../events/v3/canonical.ts";
+import { type EventV3WriteMode, readEventV3ControlState } from "../events/v3/control.ts";
 import {
   readCoordinationViewV3,
   requireAuthoritySafeCoordinationViewV3,
 } from "../events/v3/coordination-view.ts";
+import { fingerprintContextV3 } from "../events/v3/fingerprint-keys.ts";
 import {
   LIVE_HOOK_V3_PRODUCER_ID,
   liveInstanceIdV3,
@@ -22,6 +23,9 @@ import {
   recordCoordinationAuthorityV3,
 } from "../events/v3/producers/coordination-recorder.ts";
 import {
+  type HookProducerStateV3,
+  listHookProducerStateRecordsV3,
+  readHookProducerStateV3,
   readTerminalHookProducerStateV3,
   recordHookSignalV3,
 } from "../events/v3/producers/recorder.ts";
@@ -36,9 +40,10 @@ import {
   setTask,
 } from "./state/heartbeat-writer.ts";
 import {
-  ensureLiveCoordinationHeartbeat,
   liveCoordinationAdapterV3,
+  readLiveCoordinationRow,
 } from "./state/live-coordination-view.ts";
+import { ensureLiveCoordinationHeartbeat } from "./state/live-coordination-writer.ts";
 import { recordNameAssumption } from "./state/names.ts";
 
 export const LIVE_COORDINATION_V3_PRODUCER_ID = "prd_agent-coord" as const;
@@ -61,6 +66,20 @@ export interface ReopenedLiveCoordinationGenerationV3 {
   generation_id: `gen_${string}`;
 }
 
+export interface BootstrappedLiveCoordinationAuthorityV3 {
+  state: "created" | "reused";
+  adapter: Adapter;
+  generation_id: `gen_${string}`;
+  heartbeat: Heartbeat;
+}
+
+export interface RestoredLiveCoordinationStateV3 {
+  state: "unchanged" | "restored";
+  task: boolean;
+  claims: number;
+  lifecycle: boolean;
+}
+
 interface LiveAuthorityBaseV3 {
   coordRoot: string;
   owner: string;
@@ -70,6 +89,315 @@ interface LiveAuthorityBaseV3 {
   observationId?: string;
 }
 
+/**
+ * Establish the missing generation authority for one adapter-native session,
+ * then reconstruct its disposable heartbeat cache.
+ *
+ * This is intentionally narrower than mid-flight hook onboarding. The caller
+ * must supply an already validated native session, adapter, and current
+ * instance identity. Existing authority is reused only when all three bind to
+ * the same non-terminal producer generation. A terminal generation, an
+ * adapter/session collision, or any disagreement between private producer
+ * control and the public projection fails closed. No turn is synthesized.
+ */
+export function bootstrapLiveCoordinationAuthorityV3(input: {
+  coordRoot: string;
+  owner: string;
+  nativeSessionId: string;
+  adapter: Adapter;
+}): BootstrappedLiveCoordinationAuthorityV3 {
+  if (!/^[a-zA-Z0-9._-]{1,128}$/.test(input.owner)) {
+    throw new LiveCoordinationAuthorityV3Error("invalid_instance_identity");
+  }
+  if (
+    input.nativeSessionId.length === 0 ||
+    input.nativeSessionId.length > 512 ||
+    input.nativeSessionId.includes("\0")
+  ) {
+    throw new LiveCoordinationAuthorityV3Error("invalid_native_session_identity");
+  }
+
+  const route = resolveLiveEventLedgerRouteV3(input.coordRoot);
+  if (route.state === "blocked") throw new LiveCoordinationAuthorityV3Error(route.reason);
+  const control = readEventV3ControlState(input.coordRoot);
+  if (control.state !== route.mode) {
+    throw new LiveCoordinationAuthorityV3Error("control_state_mismatch");
+  }
+
+  const instanceId = liveInstanceIdV3(input.owner);
+  const rootId = control.genesis.event.scope.root_id as `root_${string}`;
+  const context = fingerprintContextV3(
+    input.coordRoot,
+    rootId,
+    undefined,
+    control.genesis.profile.privacy_key_epoch,
+  );
+  const sessionId = `sid_${normalizeNativeIdV3(
+    context,
+    `${input.adapter}.session`,
+    input.nativeSessionId,
+  ).slice(4)}`;
+
+  const view = readAuthoritySafeViewForBootstrap(input.coordRoot);
+  const existing = view.instances[instanceId];
+  const sessionStates = readSessionProducerStatesForBootstrap(
+    input.coordRoot,
+    input.nativeSessionId,
+  );
+  const instanceStates = readInstanceProducerStatesForBootstrap(input.coordRoot, instanceId);
+
+  const crossAdapter = sessionStates.find((state) => state.adapter !== input.adapter);
+  if (crossAdapter) {
+    throw new LiveCoordinationAuthorityV3Error("cross_adapter_identity");
+  }
+  const crossInstance = sessionStates.find((state) => state.instance_id !== instanceId);
+  if (crossInstance) {
+    throw new LiveCoordinationAuthorityV3Error("cross_instance_identity");
+  }
+
+  const direct = sessionStates.find((state) => state.adapter === input.adapter);
+  if (
+    direct?.terminal ||
+    (!existing && terminalGenerationForSession(view, instanceId, sessionId))
+  ) {
+    throw new LiveCoordinationAuthorityV3Error("terminal_generation_forbidden");
+  }
+
+  const liveInstanceStates = instanceStates.filter((state) => !state.terminal);
+  if (liveInstanceStates.length > 1 || sessionStates.length > 1) {
+    throw new LiveCoordinationAuthorityV3Error("generation_ambiguous");
+  }
+
+  if (existing) {
+    const observedAdapter = existing.runtime_attestation.adapter;
+    if (observedAdapter.state !== "observed" || observedAdapter.value.id !== input.adapter) {
+      throw new LiveCoordinationAuthorityV3Error("cross_adapter_identity");
+    }
+    if (existing.session_id !== sessionId) {
+      throw new LiveCoordinationAuthorityV3Error("cross_session_identity");
+    }
+    if (
+      !direct ||
+      direct.terminal ||
+      direct.generation_id !== existing.generation_id ||
+      liveInstanceStates.length !== 1 ||
+      liveInstanceStates[0]?.generation_id !== existing.generation_id
+    ) {
+      throw new LiveCoordinationAuthorityV3Error("generation_control_mismatch");
+    }
+    return materializeBootstrappedAuthority(input, existing.generation_id, "reused");
+  }
+
+  if (direct || liveInstanceStates.length > 0) {
+    throw new LiveCoordinationAuthorityV3Error("generation_control_mismatch");
+  }
+
+  const started = recordHookSignalV3({
+    coordRoot: input.coordRoot,
+    mode: route.mode,
+    signal: "session-start",
+    payload: { raw: {}, session_id: input.nativeSessionId },
+    adapter: input.adapter,
+    instance_id: instanceId,
+    producer_id: LIVE_HOOK_V3_PRODUCER_ID,
+    build_id: route.build_id,
+    platform: livePlatformV3(),
+    session_start_derivation: "validated_current_session_heal",
+  });
+  if (started.state !== "recorded" && started.state !== "already_started") {
+    const reason = "reason" in started ? `:${started.reason}` : "";
+    throw new LiveCoordinationAuthorityV3Error(
+      `generation_bootstrap_failed:${started.state}${reason}`,
+    );
+  }
+
+  const after = readAuthoritySafeViewForBootstrap(input.coordRoot).instances[instanceId];
+  const producer = readSessionProducerStatesForBootstrap(
+    input.coordRoot,
+    input.nativeSessionId,
+  ).filter((state) => state.adapter === input.adapter && state.instance_id === instanceId);
+  if (
+    !after ||
+    after.session_id !== sessionId ||
+    producer.length !== 1 ||
+    producer[0]?.terminal ||
+    producer[0]?.generation_id !== after.generation_id
+  ) {
+    throw new LiveCoordinationAuthorityV3Error("generation_control_mismatch");
+  }
+  return materializeBootstrappedAuthority(
+    input,
+    after.generation_id,
+    started.state === "recorded" ? "created" : "reused",
+  );
+}
+
+function readAuthoritySafeViewForBootstrap(coordRoot: string) {
+  try {
+    return requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+  } catch (error) {
+    if (error instanceof LiveCoordinationAuthorityV3Error) throw error;
+    throw new LiveCoordinationAuthorityV3Error("coordination_view_unsafe");
+  }
+}
+
+function readSessionProducerStatesForBootstrap(
+  coordRoot: string,
+  nativeSessionId: string,
+): HookProducerStateV3[] {
+  try {
+    return (["claude-code", "codex", "cursor"] as const)
+      .map((adapter) => readHookProducerStateV3(coordRoot, adapter, nativeSessionId))
+      .filter((state): state is HookProducerStateV3 => state !== undefined);
+  } catch {
+    throw new LiveCoordinationAuthorityV3Error("producer_state_unsafe");
+  }
+}
+
+function readInstanceProducerStatesForBootstrap(
+  coordRoot: string,
+  instanceId: `inst_${string}`,
+): HookProducerStateV3[] {
+  try {
+    return listHookProducerStateRecordsV3(coordRoot, { includeTerminal: true })
+      .map((record) => record.state)
+      .filter((state) => state.instance_id === instanceId);
+  } catch {
+    throw new LiveCoordinationAuthorityV3Error("producer_state_unsafe");
+  }
+}
+
+function terminalGenerationForSession(
+  view: ReturnType<typeof readCoordinationViewV3>,
+  instanceId: `inst_${string}`,
+  sessionId: string,
+): boolean {
+  return Object.values(view.terminal_generations).some(
+    (generation) => generation.instance_id === instanceId && generation.session_id === sessionId,
+  );
+}
+
+function materializeBootstrappedAuthority(
+  input: { coordRoot: string; owner: string; nativeSessionId: string; adapter: Adapter },
+  generationId: string,
+  state: "created" | "reused",
+): BootstrappedLiveCoordinationAuthorityV3 {
+  const heartbeat = ensureLiveCoordinationHeartbeat(
+    input.coordRoot,
+    input.owner,
+    input.nativeSessionId,
+    input.adapter,
+  );
+  if (!heartbeat || heartbeat.v3_generation_id !== generationId) {
+    throw new LiveCoordinationAuthorityV3Error("generation_materialization_failed");
+  }
+  return {
+    state,
+    adapter: input.adapter,
+    generation_id: generationId as `gen_${string}`,
+    heartbeat,
+  };
+}
+
+/**
+ * Reapply private, generation-bound coordination state after a runtime epoch
+ * replaces the canonical ledger. The old heartbeat is only accepted for the
+ * same native session and a different V3 generation. Its task prose and
+ * lifecycle reason remain in the disposable cache; canonical events retain
+ * only the privacy-safe authority signals.
+ */
+export function restoreLiveCoordinationStateAfterEpochV3(input: {
+  coordRoot: string;
+  owner: string;
+  nativeSessionId: string;
+  adapter: Adapter;
+  prior: Heartbeat | null;
+  currentGenerationId?: `gen_${string}`;
+}): RestoredLiveCoordinationStateV3 {
+  const unchanged: RestoredLiveCoordinationStateV3 = {
+    state: "unchanged",
+    task: false,
+    claims: 0,
+    lifecycle: false,
+  };
+  const prior = input.prior;
+  if (!prior || prior.instance_id !== input.owner) return unchanged;
+  if (
+    prior.session_id !== input.nativeSessionId &&
+    prior.native_session_id !== input.nativeSessionId
+  ) {
+    return unchanged;
+  }
+  // The recorder just committed this hook under the named generation. When
+  // it is the cache's generation, no epoch replacement occurred and the
+  // expensive complete coordination projection cannot change the answer.
+  if (input.currentGenerationId && prior.v3_generation_id === input.currentGenerationId) {
+    return unchanged;
+  }
+  const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(input.coordRoot));
+  const priorGenerationStillCurrent = [
+    ...Object.values(view.instances),
+    ...Object.values(view.terminal_generations),
+  ].some((generation) => generation.generation_id === prior.v3_generation_id);
+  if (priorGenerationStillCurrent) return unchanged;
+  const current = readLiveCoordinationRow(input.coordRoot, input.owner);
+  if (!current || !prior.v3_generation_id || current.v3_generation_id === prior.v3_generation_id) {
+    return unchanged;
+  }
+
+  let task = false;
+  let claims = 0;
+  let lifecycle = false;
+  if (typeof prior.task === "string" && prior.task.length > 0 && current.task !== prior.task) {
+    recordLiveTaskChangeV3({
+      coordRoot: input.coordRoot,
+      owner: input.owner,
+      nativeSessionId: input.nativeSessionId,
+      adapter: input.adapter,
+      task: prior.task,
+    });
+    task = true;
+  }
+  const currentClaims = new Set(
+    (current.files_touched ?? []).map((path) => canonicalClaimPath(input.coordRoot, path)),
+  );
+  for (const path of [...new Set(prior.files_touched ?? [])].sort()) {
+    const canonical = canonicalClaimPath(input.coordRoot, path);
+    if (currentClaims.has(canonical)) continue;
+    recordLiveClaimChangeV3({
+      coordRoot: input.coordRoot,
+      owner: input.owner,
+      nativeSessionId: input.nativeSessionId,
+      adapter: input.adapter,
+      operation: "acquired",
+      path: canonical,
+    });
+    currentClaims.add(canonical);
+    claims += 1;
+  }
+  const priorLifecycle = prior.task_state ?? "active";
+  if (
+    priorLifecycle !== "active" &&
+    (current.task_state !== priorLifecycle || current.task_state_reason !== prior.task_state_reason)
+  ) {
+    recordLiveLifecycleChangeV3({
+      coordRoot: input.coordRoot,
+      owner: input.owner,
+      nativeSessionId: input.nativeSessionId,
+      adapter: input.adapter,
+      state: priorLifecycle,
+      ...(prior.task_state_reason ? { reason: prior.task_state_reason } : {}),
+      ...(prior.suggested_session_name
+        ? { suggestedSessionName: prior.suggested_session_name }
+        : {}),
+    });
+    lifecycle = true;
+  }
+  return task || claims > 0 || lifecycle
+    ? { state: "restored", task, claims, lifecycle }
+    : unchanged;
+}
+
 /**
  * Open a fresh derived generation for a human-facing session that is executing
  * again after an authoritative terminal. The terminal generation is never
@@ -185,7 +513,8 @@ export function recordLiveLifecycleChangeV3(
     task_state_reason: input.state === "active" ? undefined : input.reason,
     ...(input.suggestedSessionName ? { suggested_session_name: input.suggestedSessionName } : {}),
   };
-  if (authorityStateDigest(before) === authorityStateDigest(desired)) return { state: "unchanged" };
+  if (coordinationAuthorityStateDigestV3(before) === coordinationAuthorityStateDigestV3(desired))
+    return { state: "unchanged" };
   return recordLiveAuthority(
     input,
     "lifecycle-changed",
@@ -237,7 +566,8 @@ export function recordLiveClaimChangeV3(
           (path) => canonicalClaimPath(input.coordRoot, path) !== canonical,
         );
   const desired: Heartbeat = { ...before, files_touched: desiredFiles };
-  if (authorityStateDigest(before) === authorityStateDigest(desired)) return { state: "unchanged" };
+  if (coordinationAuthorityStateDigestV3(before) === coordinationAuthorityStateDigestV3(desired))
+    return { state: "unchanged" };
   return recordLiveAuthority(
     input,
     "claim-changed",
@@ -266,7 +596,8 @@ export function recordLiveIdentityChangeV3(
   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" };
+  if (coordinationAuthorityStateDigestV3(before) === coordinationAuthorityStateDigestV3(desired))
+    return { state: "unchanged" };
   return recordLiveAuthority(
     input,
     "identity-attested",
@@ -311,15 +642,15 @@ function recordLiveAuthority<S extends CoordinationAuthoritySignalV3>(
     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),
+    expected_prior_state_digest: coordinationAuthorityStateDigestV3(expected),
+    desired_state_digest: coordinationAuthorityStateDigestV3(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);
+        return coordinationAuthorityStateDigestV3(heartbeat);
       },
       apply: (_mutation: AuthorityMutationV3) => apply(),
     },
@@ -356,7 +687,7 @@ function requireHeartbeat(input: LiveAuthorityBaseV3, owner: string): Heartbeat
   return heartbeat;
 }
 
-function authorityStateDigest(heartbeat: Heartbeat): `sha256:${string}` {
+export function coordinationAuthorityStateDigestV3(heartbeat: Heartbeat): `sha256:${string}` {
   return sha256V3(
     canonicalJsonV3({
       instance_id: heartbeat.v3_instance_id ?? heartbeat.instance_id,

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

@@ -121,7 +121,12 @@ function recordObservation<T extends "lifecycle.sweep_observed" | "session.resum
     monotonic_ns: process.hrtime.bigint().toString(),
   };
   const event = buildEventV3(eventType, { ...common, payload } as never) as EventV3;
-  writeEventV3(input.coordRoot, event);
+  const durability = writeEventV3(input.coordRoot, event, {
+    expectedGenesisId: control.genesis.event.payload.genesis_id as `gex_${string}`,
+  });
+  if (durability.state === "epoch_replaced") {
+    throw new LiveCoordinationAuthorityV3Error("epoch_replaced");
+  }
   return { state: "recorded", event };
 }
 

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

@@ -195,7 +195,12 @@ export function recordLiveCoordinationObservationV3(
       break;
     }
   }
-  writeEventV3(input.coordRoot, event);
+  const durability = writeEventV3(input.coordRoot, event, {
+    expectedGenesisId: control.genesis.event.payload.genesis_id as `gex_${string}`,
+  });
+  if (durability.state === "epoch_replaced") {
+    throw new LiveCoordinationAuthorityV3Error("epoch_replaced");
+  }
   return { state: "recorded", event };
 }