harnery 0.34.1 → 0.36.0

package/src/core/events/v3/live-routing.ts

@@ -1,25 +1,38 @@
-import { createHash } from "node:crypto";
 import type { Adapter } from "../../adapter.ts";
 import type { ParsedPayload } from "../../hooks/adapter/parse.ts";
+import { refreshIncompatibleEventLedgerV3, rotateOversizedEventLedgerV3 } from "./bootstrap.ts";
+import type { EventV3 } from "./contract.ts";
+import { readEventV3ControlState } from "./control.ts";
+import { repairEventV3ControlPair } from "./control-writer.ts";
 import {
-  type EventV3WriteMode,
-  readEventV3ControlState,
-  repairEventV3ControlPair,
-} from "./control.ts";
+  type LiveEventLedgerRouteV3,
+  liveEventLedgerRouteFromControlV3,
+  liveInstanceIdV3,
+  runtimeCapabilityProfileCurrentV3,
+} from "./live-route-observer.ts";
 import type { HookSignalV3 } from "./producers/hook.ts";
 import type { TurnRitualEvidenceV3 } from "./producers/hook-base.ts";
-import { type RecordHookSignalV3Result, recordHookSignalV3 } from "./producers/recorder.ts";
+import {
+  type ReconcilePendingRuntimeContextV3Result,
+  type RecordHookSignalV3Result,
+  reconcilePendingRuntimeContextV3,
+  recordHookSignalV3,
+} from "./producers/recorder.ts";
+import { livePlatformV3 } from "./runtime-identity.ts";
+
+export {
+  type LiveEventLedgerRouteV3,
+  liveInstanceIdV3,
+  nativeInstanceIdV3,
+} from "./live-route-observer.ts";
+export { liveEventV3BuildId, livePlatformV3 } from "./runtime-identity.ts";
 
 export const LIVE_HOOK_V3_PRODUCER_ID = "prd_agent-hook" as const;
 export const LIVE_COMMAND_V3_PRODUCER_ID = "prd_session-tee" as const;
 
-export type LiveEventLedgerRouteV3 =
-  | { state: "v3"; mode: EventV3WriteMode; build_id: `build_${string}` }
-  | { state: "blocked"; reason: string };
-
 /**
  * Resolve the V3-only ledger route. A root without an initialized V3 control
- * packet is blocked; no producer or consumer may fall back to an older ledger.
+ * packet is blocked; no mutating producer may fall back to an older ledger.
  * Manifest-first crashes are repaired from the immutable packet and every
  * other invalid state closes the writer gate.
  */
@@ -27,36 +40,32 @@ export function resolveLiveEventLedgerRouteV3(coordRoot: string): LiveEventLedge
   let control = readEventV3ControlState(coordRoot);
   if (control.state === "closed") return { state: "blocked", reason: "v3_not_initialized" };
   if (control.state === "repairable") control = repairEventV3ControlPair(coordRoot);
-  if (control.state !== "candidate" && control.state !== "active") {
-    return { state: "blocked", reason: `${control.state}:${control.reason}` };
+  if (
+    (control.state === "invalid" && control.reason === "genesis_schema_digest_incompatible") ||
+    ((control.state === "candidate" || control.state === "active") &&
+      !runtimeCapabilityProfileCurrentV3(control))
+  ) {
+    try {
+      control = refreshIncompatibleEventLedgerV3(coordRoot).control;
+    } catch (error) {
+      return {
+        state: "blocked",
+        reason: `runtime_refresh_failed:${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
   }
-  const buildId = liveEventV3BuildId(control.genesis.profile.harnery_commit);
-  if (!control.genesis.profile.producer_build_ids.includes(buildId)) {
-    return { state: "blocked", reason: "live_producer_build_not_approved" };
+  if (control.state === "active") {
+    // Bound the epoch every producer must re-validate: an oversized active
+    // segment rotates into the archive here, on the shared route boundary.
+    // Rotation failure never blocks recording; the current epoch stays live.
+    try {
+      const rotated = rotateOversizedEventLedgerV3(coordRoot);
+      if (rotated.state === "rotated" && rotated.control) control = rotated.control;
+    } catch {
+      // The oversized epoch keeps serving; the next route resolution retries.
+    }
   }
-  return { state: "v3", mode: control.state, build_id: buildId };
-}
-
-export function liveEventV3BuildId(harneryCommit: string): `build_${string}` {
-  const exact = harneryCommit.normalize("NFC");
-  if (/^[a-zA-Z0-9._-]{1,120}$/.test(exact)) return `build_${exact}`;
-  return `build_${createHash("sha256").update(exact).digest("hex")}`;
-}
-
-export function liveInstanceIdV3(instanceId: string): `inst_${string}` {
-  if (/^inst_[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) return instanceId as `inst_${string}`;
-  if (/^[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) return `inst_${instanceId}`;
-  return `inst_${createHash("sha256").update(instanceId.normalize("NFC")).digest("hex")}`;
-}
-
-/**
- * The adapter-native id a canonical `inst_*` id carries, for display and for
- * joins against native-keyed records. Only the direct prefix form round-trips:
- * a hashed id has no recoverable native form and is returned unchanged, so
- * never treat this as a guaranteed inverse of `liveInstanceIdV3`.
- */
-export function nativeInstanceIdV3(instanceId: string): string {
-  return instanceId.startsWith("inst_") ? instanceId.slice("inst_".length) : instanceId;
+  return liveEventLedgerRouteFromControlV3(control);
 }
 
 export function hookSignalV3(eventName: string): HookSignalV3 | undefined {
@@ -84,6 +93,20 @@ export function hookSignalV3(eventName: string): HookSignalV3 | undefined {
   }
 }
 
+/**
+ * Tool lifecycle hooks may stop after publishing their event to the durable
+ * ready WAL. The next non-tool hook drains the causal batch into the active
+ * ledger, avoiding one global append-lease cycle for every tool boundary.
+ */
+export function liveHookSignalDefersDrainV3(eventName: string, override?: string): boolean {
+  if (override === "1") return true;
+  if (override === "0") return false;
+  const signal = hookSignalV3(eventName);
+  return (
+    signal === "pre-tool-use" || signal === "post-tool-use" || signal === "post-tool-use-failure"
+  );
+}
+
 export function recordLiveHookSignalV3(input: {
   coordRoot: string;
   route: Extract<LiveEventLedgerRouteV3, { state: "v3" }>;
@@ -104,11 +127,27 @@ export function recordLiveHookSignalV3(input: {
 }): RecordHookSignalV3Result | { state: "ignored" } {
   const signal = hookSignalV3(input.eventName);
   if (!signal) return { state: "ignored" };
+  const nativeChild = input.payload?.subagent_id ?? input.payload?.agent_id;
+  const childOwnsSignal =
+    signal !== "sub-agent-start" &&
+    signal !== "sub-agent-stop" &&
+    nativeChild !== undefined &&
+    liveInstanceIdV3(input.instanceId) === liveInstanceIdV3(nativeChild);
+  const payload = input.payload
+    ? childOwnsSignal
+      ? {
+          ...input.payload,
+          session_id: nativeChild,
+          conversation_id: undefined,
+          parent_session_id: input.payload.session_id ?? input.payload.conversation_id,
+        }
+      : input.payload
+    : { raw: {} };
   return recordHookSignalV3({
     coordRoot: input.coordRoot,
     mode: input.route.mode,
     signal,
-    payload: input.payload ?? { raw: {} },
+    payload,
     adapter: input.adapter,
     instance_id: liveInstanceIdV3(input.instanceId),
     run_id: input.run_id,
@@ -127,9 +166,107 @@ export function recordLiveHookSignalV3(input: {
   });
 }
 
-export function livePlatformV3(): "linux" | "windows" | "macos" | "unknown" {
-  if (process.platform === "linux") return "linux";
-  if (process.platform === "win32") return "windows";
-  if (process.platform === "darwin") return "macos";
-  return "unknown";
+export function reconcileLivePendingRuntimeContextV3(input: {
+  coordRoot: string;
+  route: Extract<LiveEventLedgerRouteV3, { state: "v3" }>;
+  nativeSessionId: string;
+  finalAttempt?: boolean;
+}): ReconcilePendingRuntimeContextV3Result {
+  return reconcilePendingRuntimeContextV3({
+    coordRoot: input.coordRoot,
+    mode: input.route.mode,
+    nativeSessionId: input.nativeSessionId,
+    producer_id: LIVE_HOOK_V3_PRODUCER_ID,
+    build_id: input.route.build_id,
+    platform: livePlatformV3(),
+    finalAttempt: input.finalAttempt,
+  });
+}
+
+/**
+ * Open the child generation named by a native SubagentStart event.
+ *
+ * The parent producer owns the delegation span and mints its child generation
+ * id. This second crash-safe session-start gives that exact generation its own
+ * producer authority, so later child tool hooks can resolve away from the
+ * parent session and the disposable heartbeat projection has a real source.
+ */
+export function recordLiveDelegatedChildSessionV3(input: {
+  coordRoot: string;
+  route: Extract<LiveEventLedgerRouteV3, { state: "v3" }>;
+  parentEvent: Extract<EventV3, { event_type: "agent.started" }>;
+  payload: ParsedPayload;
+  adapter: Adapter;
+  bridge?: "codex-wsl";
+  monotonic_ns?: string;
+}): RecordHookSignalV3Result | { state: "ignored" } {
+  const nativeChild = input.payload.subagent_id ?? input.payload.agent_id;
+  if (!nativeChild) return { state: "ignored" };
+  const parentGeneration = (input.parentEvent.links as { parent_generation_id?: `gen_${string}` })
+    .parent_generation_id;
+  if (!parentGeneration) return { state: "ignored" };
+  const nativeParent = input.payload.session_id ?? input.payload.conversation_id;
+  const childPayload: ParsedPayload = {
+    session_id: nativeChild,
+    agent_id: nativeChild,
+    parent_session_id: nativeParent,
+    source: "startup",
+    model: input.payload.model,
+    cwd: input.payload.cwd,
+    raw: {
+      session_id: nativeChild,
+      agent_id: nativeChild,
+      ...(nativeParent ? { parent_session_id: nativeParent } : {}),
+      ...(input.payload.raw.agent_type ? { agent_type: input.payload.raw.agent_type } : {}),
+    },
+  };
+  const started = recordHookSignalV3({
+    coordRoot: input.coordRoot,
+    mode: input.route.mode,
+    signal: "session-start",
+    payload: childPayload,
+    adapter: input.adapter,
+    instance_id: liveInstanceIdV3(nativeChild),
+    producer_id: LIVE_HOOK_V3_PRODUCER_ID,
+    build_id: input.route.build_id,
+    platform: livePlatformV3(),
+    ...(input.bridge ? { bridge: input.bridge } : {}),
+    monotonic_ns: input.monotonic_ns,
+    hook_name: "sub-agent-start-child-session",
+    delegated_child: {
+      generation_id: input.parentEvent.payload.child_generation_id as `gen_${string}`,
+      parent_generation_id: parentGeneration,
+      delegation_id: input.parentEvent.payload.delegation_id as `del_${string}`,
+      caused_by_event_id: input.parentEvent.event_id as `evt_${string}`,
+    },
+  });
+  if (started.state !== "recorded" && started.state !== "already_started") return started;
+  const childStartEventId = (
+    started.state === "recorded" ? started.event.event_id : started.event_id
+  ) as `evt_${string}`;
+  recordHookSignalV3({
+    coordRoot: input.coordRoot,
+    mode: input.route.mode,
+    signal: "user-prompt-submit",
+    payload: {
+      ...childPayload,
+      turn_id: `delegated:${nativeChild}`,
+      raw: { ...childPayload.raw, turn_id: `delegated:${nativeChild}` },
+    },
+    adapter: input.adapter,
+    instance_id: liveInstanceIdV3(nativeChild),
+    producer_id: LIVE_HOOK_V3_PRODUCER_ID,
+    build_id: input.route.build_id,
+    platform: livePlatformV3(),
+    ...(input.bridge ? { bridge: input.bridge } : {}),
+    monotonic_ns: input.monotonic_ns,
+    hook_name: "sub-agent-start-child-turn",
+    delegated_child: {
+      generation_id: input.parentEvent.payload.child_generation_id as `gen_${string}`,
+      parent_generation_id: parentGeneration,
+      delegation_id: input.parentEvent.payload.delegation_id as `del_${string}`,
+      caused_by_event_id: childStartEventId,
+    },
+  });
+  return started;
 }

package/src/core/events/v3/producers/command-recorder.ts

@@ -141,6 +141,14 @@ export function recordCommandSignalV3(
     if (state && !matchesHookState(state, hook, input, epochId)) {
       throw new Error("V3 command producer state does not match the joined hook generation");
     }
+    if (state && state.attestation_id !== hook.attestation_id) {
+      // A mid-generation re-attestation (session.attestation_changed) moves
+      // the hook's attestation id without opening a new generation or turn. A
+      // command span that straddles the change keeps its span, sequence, and
+      // dedupe state; later events ride the live attestation, the same
+      // in-place adoption the hook producer performs.
+      state.attestation_id = hook.attestation_id;
+    }
     let recovered = false;
     if (state?.pending) {
       const pending = state.pending;
@@ -445,7 +453,8 @@ function matchesHookState(
     state.session_id === hook.session_id &&
     state.generation_id === hook.generation_id &&
     state.turn_id === hook.current_turn_id &&
-    state.attestation_id === hook.attestation_id &&
+    // attestation_id is deliberately absent: a re-attestation within the
+    // generation is a continuation, adopted by the caller, not a mismatch.
     state.privacy_epoch_id === epochId
   );
 }

package/src/core/events/v3/producers/coordination-recorder.ts

@@ -6,6 +6,7 @@ import {
   fsyncSync,
   mkdirSync,
   openSync,
+  readdirSync,
   readFileSync,
   renameSync,
   statSync,
@@ -13,7 +14,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { hostname } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import type { Adapter } from "../../../adapter.ts";
 import { fsyncParentDirectory } from "../../../workflow/durable-record.ts";
 import { acquireNoClobberLease } from "../../../workflow/workspaces/leases.ts";
@@ -21,6 +22,7 @@ import {
   type AuthorityReceiptV3,
   type AuthorityReconcilerV3,
   type AuthorityTransactionV3,
+  authorityRecoveryIntentPathV3,
   buildAuthorityTransactionV3,
   publishAuthorityTransactionV3,
   reconcileAuthorityTransactionV3,
@@ -38,7 +40,7 @@ import {
   type CoordinationObservationBySignalV3,
   normalizeCoordinationAuthorityV3,
 } from "./coordination.ts";
-import { readHookProducerStateV3 } from "./recorder.ts";
+import { readJoinableHookProducerStateV3 } from "./recorder.ts";
 
 const COORDINATION_STATE_FORMAT = "harnery-v3-coordination-producer" as const;
 const COORDINATION_STATE_VERSION = 2 as const;
@@ -78,6 +80,11 @@ interface CoordinationRecorderStateV3 {
   pending?: PendingCoordinationTransactionV3;
 }
 
+export interface PendingCoordinationTransactionV3Location {
+  producer_state_file: string;
+  transaction: AuthorityTransactionV3;
+}
+
 export interface RecordCoordinationAuthorityV3Input<
   S extends CoordinationAuthoritySignalV3 = CoordinationAuthoritySignalV3,
 > {
@@ -124,10 +131,11 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
 ): RecordCoordinationAuthorityV3Result {
   const control = readEventV3ControlState(input.coordRoot);
   if (control.state !== input.mode) return { state: "gate_closed", reason: control.state };
-  const hook = readHookProducerStateV3(
+  const hook = readJoinableHookProducerStateV3(
     input.coordRoot,
     input.adapter,
     input.native_actor_session_id,
+    input.actor_instance_id,
   );
   if (
     !hook ||
@@ -140,6 +148,9 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
 
   const rootId = control.genesis.event.scope.root_id as `root_${string}`;
   const epochId = control.genesis.profile.privacy_key_epoch;
+  const epochFence = {
+    expectedGenesisId: control.genesis.event.payload.genesis_id as `gex_${string}`,
+  };
   const rootContext = fingerprintContextV3(input.coordRoot, rootId, undefined, epochId);
   const producerSource = normalizeNativeIdV3(
     rootContext,
@@ -158,7 +169,28 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
     if (state && !matchesHookState(state, hook, input, epochId)) {
       throw new Error("V3 coordination producer state does not match the joined hook generation");
     }
+    if (state && state.attestation_id !== hook.attestation_id) {
+      // A mid-generation re-attestation (session.attestation_changed) moves
+      // the hook's attestation id without opening a new generation. The
+      // producer keeps its one continuous sequence, clock, and observation
+      // dedupe for the generation and stamps later events with the live
+      // attestation — the same in-place adoption the hook producer performs.
+      // Refusing here would wedge the producer forever, since its state path
+      // is derived from the generation alone and can never be superseded.
+      state.attestation_id = hook.attestation_id;
+    }
     if (state?.pending) {
+      if (
+        existsSync(
+          authorityRecoveryIntentPathV3(input.coordRoot, state.pending.transaction.transaction_id),
+        )
+      ) {
+        return {
+          state: "pending_transaction",
+          transaction_id: state.pending.transaction.transaction_id,
+          mutation_kind: state.pending.transaction.mutation.kind,
+        };
+      }
       if (state.pending.source_id !== sourceId) {
         // A writer that died mid-commit leaves `pending` owned by an
         // observation that will never retry (hook observations are one-shot).
@@ -169,11 +201,12 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
         // still refuses rather than guessing at a conflicting mutation.
         const stale = state.pending;
         try {
-          publishAuthorityTransactionV3(input.coordRoot, stale.transaction);
+          publishAuthorityTransactionV3(input.coordRoot, stale.transaction, epochFence);
           reconcileAuthorityTransactionV3(
             input.coordRoot,
             stale.transaction.transaction_id,
             input.reconciler,
+            epochFence,
           );
         } catch {
           return {
@@ -192,11 +225,12 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
         publishCoordinationState(path, state);
       } else {
         const pending = state.pending;
-        publishAuthorityTransactionV3(input.coordRoot, pending.transaction);
+        publishAuthorityTransactionV3(input.coordRoot, pending.transaction, epochFence);
         const receipt = reconcileAuthorityTransactionV3(
           input.coordRoot,
           pending.transaction.transaction_id,
           input.reconciler,
+          epochFence,
         );
         const event = eventFromTransaction(pending.transaction);
         applyCoordinationEvent(state, pending.source_id, pending.transaction, event);
@@ -296,11 +330,12 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
     if (input.signal === "wait-ended" && waitId) delete state.open_waits[waitId];
     state.pending = { source_id: sourceId, transaction };
     publishCoordinationState(path, state);
-    publishAuthorityTransactionV3(input.coordRoot, transaction);
+    publishAuthorityTransactionV3(input.coordRoot, transaction, epochFence);
     const receipt = reconcileAuthorityTransactionV3(
       input.coordRoot,
       transaction.transaction_id,
       input.reconciler,
+      epochFence,
     );
     applyCoordinationEvent(state, sourceId, transaction, normalized.event);
     state.pending = undefined;
@@ -311,9 +346,71 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
   }
 }
 
+/** Locate the one private producer state that owns a pending authority transaction. */
+export function findPendingCoordinationTransactionV3(
+  coordRoot: string,
+  transactionId: string,
+): PendingCoordinationTransactionV3Location | null {
+  const directory = coordinationProducerDirectory(coordRoot);
+  if (!existsSync(directory)) return null;
+  const matches = readdirSync(directory)
+    .filter((name) => /^hid_[a-f0-9]{64}\.json$/.test(name))
+    .sort()
+    .flatMap((name) => {
+      const state = readCoordinationState(join(directory, name));
+      return state.pending?.transaction.transaction_id === transactionId
+        ? [{ producer_state_file: name, transaction: state.pending.transaction }]
+        : [];
+    });
+  if (matches.length > 1) {
+    throw new Error("authority transaction is pending in more than one coordination producer");
+  }
+  return matches[0] ?? null;
+}
+
+/** Clear one transaction from its exact producer state after durable quarantine is established. */
+export function withPendingCoordinationTransactionRecoveryV3<T>(
+  coordRoot: string,
+  producerStateFile: string,
+  transaction: AuthorityTransactionV3,
+  allowAlreadyCleared: boolean,
+  operation: (control: { clearPending: () => "cleared" | "already_cleared" }) => T,
+): T {
+  if (!/^hid_[a-f0-9]{64}\.json$/.test(producerStateFile)) {
+    throw new Error("coordination producer state file is invalid");
+  }
+  const path = join(coordinationProducerDirectory(coordRoot), basename(producerStateFile));
+  if (!existsSync(path)) throw new Error("coordination producer state is missing");
+  const lease = acquireCoordinationLease(coordRoot, path);
+  try {
+    const state = readCoordinationState(path);
+    if (!state.pending && !allowAlreadyCleared) {
+      throw new Error("coordination producer no longer owns the pending transaction");
+    }
+    if (state.pending) {
+      if (
+        state.pending.transaction.transaction_id !== transaction.transaction_id ||
+        canonicalJsonV3(state.pending.transaction) !== canonicalJsonV3(transaction)
+      ) {
+        throw new Error("coordination producer pending transaction changed during recovery");
+      }
+    }
+    return operation({
+      clearPending: () => {
+        if (!state.pending) return "already_cleared";
+        state.pending = undefined;
+        publishCoordinationState(path, state);
+        return "cleared";
+      },
+    });
+  } finally {
+    lease.release();
+  }
+}
+
 function newCoordinationState<S extends CoordinationAuthoritySignalV3>(
   input: RecordCoordinationAuthorityV3Input<S>,
-  hook: NonNullable<ReturnType<typeof readHookProducerStateV3>>,
+  hook: NonNullable<ReturnType<typeof readJoinableHookProducerStateV3>>,
   epochId: `pep_${string}`,
 ): CoordinationRecorderStateV3 {
   return {
@@ -340,7 +437,7 @@ function newCoordinationState<S extends CoordinationAuthoritySignalV3>(
 
 function matchesHookState<S extends CoordinationAuthoritySignalV3>(
   state: CoordinationRecorderStateV3,
-  hook: NonNullable<ReturnType<typeof readHookProducerStateV3>>,
+  hook: NonNullable<ReturnType<typeof readJoinableHookProducerStateV3>>,
   input: RecordCoordinationAuthorityV3Input<S>,
   epochId: string,
 ): boolean {
@@ -349,7 +446,8 @@ function matchesHookState<S extends CoordinationAuthoritySignalV3>(
     state.actor_instance_id === input.actor_instance_id &&
     state.session_id === hook.session_id &&
     state.generation_id === hook.generation_id &&
-    state.attestation_id === hook.attestation_id &&
+    // attestation_id is deliberately absent: a re-attestation within the
+    // generation is a continuation, adopted by the caller, not a mismatch.
     state.privacy_epoch_id === epochId &&
     state.producer_id === input.producer_id &&
     state.build_id === input.build_id &&
@@ -380,12 +478,11 @@ function eventFromTransaction(transaction: AuthorityTransactionV3): EventV3 {
 }
 
 function coordinationStatePath(coordRoot: string, producerSource: `hid_${string}`): string {
-  return join(
-    resolve(coordRoot),
-    EVENT_V3_LEDGER_RELATIVE_ROOT,
-    "private-producers/agent-coord",
-    `${producerSource}.json`,
-  );
+  return join(coordinationProducerDirectory(coordRoot), `${producerSource}.json`);
+}
+
+function coordinationProducerDirectory(coordRoot: string): string {
+  return join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers/agent-coord");
 }
 
 function acquireCoordinationLease(coordRoot: string, statePath: string) {