harnery 0.35.0 → 0.36.0

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

@@ -97,6 +97,10 @@ const CLOSED_TURN_MEMORY_CAP = 16;
 const SPAN_SOFT_WATERMARK = 128;
 const PENDING_RUNTIME_CONTEXT_CAP = 4;
 const RUNTIME_CONTEXT_RETRY_LIMIT = 2;
+/** Active turns pay for at most one bounded adapter telemetry read per interval. */
+const ACTIVE_RUNTIME_CONTEXT_PROBE_INTERVAL_MS = 15_000;
+/** Codex can flush the terminal row just after Stop; keep this grace bounded and off other hooks. */
+const STOP_RUNTIME_CONTEXT_RETRY_DELAYS_MS = [75, 175] as const;
 /** Finalization is off the interactive hook path; briefly cover Codex's delayed transcript flush. */
 const APPROVED_END_RUNTIME_CONTEXT_RETRY_DELAYS_MS = [0, 250, 250] as const;
 /**
@@ -159,6 +163,12 @@ interface PendingRuntimeContextV3 extends TurnContextTargetV3 {
   attempts: number;
 }
 
+interface ActiveRuntimeContextProbeV3 {
+  turn_id: `tid_${string}`;
+  attempted_at: string;
+  boundary?: "tool_completed";
+}
+
 interface DelegationStateV3 extends OpenSpanStateV3 {
   source_id: `hid_${string}`;
   delegation_id: `del_${string}`;
@@ -177,6 +187,14 @@ export interface HookProducerStateV3 {
   capability_profile: `cap_${string}`;
   cursor_mode?: CursorExecutionModeV3;
   privacy_epoch_id: `pep_${string}`;
+  /**
+   * Genesis id of the ledger epoch this producer's boot chain lives in. The
+   * fingerprint key epoch survives ledger rotation, so this is the field that
+   * keeps a state file from being adopted across an epoch boundary (its
+   * sequences and causal links only validate inside their own epoch). A state
+   * without it predates the field and is never adopted.
+   */
+  epoch_genesis_id?: `gex_${string}`;
   boot_id: `boot_${string}`;
   clock_id: `clk_${string}`;
   next_sequence: number;
@@ -189,6 +207,9 @@ export interface HookProducerStateV3 {
   last_monotonic_ns?: string;
   last_observed_at?: string;
   started_event_id?: `evt_${string}`;
+  /** A derived lifecycle reopen is allowed to exist before the adapter's next
+   * native prompt. Retained owner-only until that prompt starts a real turn. */
+  session_start_derivation?: "approved_lifecycle_reopen" | "validated_current_session_heal";
   session_span: OpenSpanStateV3;
   current_turn_span?: OpenSpanStateV3;
   terminal: boolean;
@@ -201,6 +222,10 @@ export interface HookProducerStateV3 {
   turn_ordinal: number;
   pending?: PendingEventV3;
   pending_runtime_contexts?: PendingRuntimeContextV3[];
+  /** Last bounded active-turn probe; owner-only and used only for cadence. */
+  active_runtime_context_probe?: ActiveRuntimeContextProbeV3;
+  /** Last emitted runtime source witness; owner-only measurement deduplication. */
+  last_context_source_witness?: string;
   /** Verified adapter-native transcript path retained only in owner-only state. */
   runtime_transcript_path?: string;
   /** Tuning carried by the current attestation; {} means attested-none.
@@ -243,7 +268,7 @@ export interface RecordHookSignalV3Input {
   hook_duration_ms?: number;
   stop_remediation?: boolean;
   turn_ritual?: TurnRitualEvidenceV3;
-  session_start_derivation?: "approved_lifecycle_reopen";
+  session_start_derivation?: "approved_lifecycle_reopen" | "validated_current_session_heal";
   delegated_child?: {
     generation_id: `gen_${string}`;
     parent_generation_id: `gen_${string}`;
@@ -607,8 +632,23 @@ function processHookSignalLocked(
       : control.activation.event.event_id;
   const rootFingerprintContext = fingerprintContextV3(input.coordRoot, rootId, undefined, epochId);
   const sessionId = `sid_${sessionHash.slice(4)}` as `sid_${string}`;
+  const genesisId = control.genesis.event.payload.genesis_id as `gex_${string}`;
+  // Every write below carries the epoch fence: an event produced for this
+  // epoch is refused (or quarantined from the spool) once the epoch has been
+  // replaced, instead of poisoning the successor's authority.
+  input = {
+    ...input,
+    writerOptions: { ...input.writerOptions, expectedGenesisId: genesisId },
+  };
   try {
     let state = existsSync(path) ? readProducerState(path) : undefined;
+    if (state && state.epoch_genesis_id !== genesisId) {
+      // A producer state from a replaced epoch (or one that predates the
+      // field) is never adopted: its boot sequences and causal links only
+      // validate inside the epoch that recorded them. The session re-onboards
+      // below exactly as it does after an automatic epoch refresh.
+      state = undefined;
+    }
     if (
       state &&
       (state.adapter !== input.adapter ||
@@ -634,7 +674,7 @@ function processHookSignalLocked(
       const pendingSource = state.pending.source_id;
       const incomingSource = sourceIdForSignal(input, rootFingerprintContext);
       const pendingEvent = state.pending.event;
-      const durability = writeEventV3(input.coordRoot, pendingEvent);
+      const durability = writeEventV3(input.coordRoot, pendingEvent, input.writerOptions);
       applyCommittedEvent(state, pendingEvent);
       state.pending = undefined;
       publishProducerState(path, state);
@@ -648,10 +688,19 @@ function processHookSignalLocked(
       if (state && !state.terminal && state.started_event_id) {
         return { state: "already_started", event_id: state.started_event_id };
       }
-      if (input.session_start_derivation && !state?.terminal) {
+      if (
+        (input.session_start_derivation === "approved_lifecycle_reopen" && !state?.terminal) ||
+        (input.session_start_derivation === "validated_current_session_heal" && state?.terminal)
+      ) {
         return { state: "missing_session_start" };
       }
-      state = newProducerState(input, sessionId, epochId, boundaryEventId as `evt_${string}`);
+      state = newProducerState(
+        input,
+        sessionId,
+        epochId,
+        boundaryEventId as `evt_${string}`,
+        genesisId,
+      );
     } else if (!state || state.terminal) {
       // Mid-flight onboarding (ADR 0078): a live session with no producer
       // state in this epoch (fresh epoch, lost session-start hook) opens a
@@ -678,7 +727,13 @@ function processHookSignalLocked(
         });
         return { state: "missing_session_start" };
       }
-      state = newProducerState(input, sessionId, epochId, boundaryEventId as `evt_${string}`);
+      state = newProducerState(
+        input,
+        sessionId,
+        epochId,
+        boundaryEventId as `evt_${string}`,
+        genesisId,
+      );
       const cursorPromptBootstrap = isCursorPromptBootstrap(input);
       const onboarding = buildMidFlightSessionStart(input, state, rootId, cursorPromptBootstrap);
       commitEventLocked(input, state, path, onboarding);
@@ -688,6 +743,7 @@ function processHookSignalLocked(
           instance_id: input.instance_id,
           signal: input.signal,
           session_hash: sessionHash,
+          ...(input.adapter === "codex" ? codexMidFlightDiagnosticContext(input.payload) : {}),
         });
       }
     }
@@ -1145,12 +1201,16 @@ function processHookSignalLocked(
     }
     if (
       input.signal === "session-start" &&
-      input.session_start_derivation === "approved_lifecycle_reopen" &&
+      input.session_start_derivation &&
       event.event_type === "session.started"
     ) {
+      const lifecycleReopen = input.session_start_derivation === "approved_lifecycle_reopen";
+      const reason = lifecycleReopen
+        ? "approved_lifecycle_reopen"
+        : "validated_current_session_heal";
       event.provenance = {
         ...event.provenance,
-        source_event: `${input.adapter}.approved-lifecycle-reopen`,
+        source_event: `${input.adapter}.${reason.replaceAll("_", "-")}`,
         attestation: "derived",
         confidence: "high",
         attribution: {
@@ -1161,7 +1221,7 @@ function processHookSignalLocked(
       };
       event.payload.resume = {
         state: "unknown",
-        reason: "approved_lifecycle_reopen",
+        reason,
       };
       assertEventV3(event);
     }
@@ -1170,7 +1230,20 @@ function processHookSignalLocked(
       span.open_event_id = event.event_id as `evt_${string}`;
       stampSpanTurn(span, event, eventInput, state);
     }
+    // A turn terminal clears current_native_turn_id when it commits. Retain the
+    // native identity long enough to seed a delayed context retry afterward.
+    const nativeTurnIdForContext = input.payload.turn_id ?? state.current_native_turn_id;
     const durability = commitEventLocked(input, state, path, event, sourceId);
+    if (event.event_type === "context.compaction_started" && input.signal === "pre-compact") {
+      maybeCommitNativeHookContextObservation(
+        input,
+        state,
+        path,
+        rootId,
+        fingerprintContext,
+        event,
+      );
+    }
     if (event.event_type === "tool.requested" && sourceId) {
       const explicitWait = explicitNativeWait(input);
       if (explicitWait) {
@@ -1183,9 +1256,25 @@ function processHookSignalLocked(
     if (progressKind) {
       commitProgressObservation(input, state, path, rootId, event, progressKind);
     }
+    if (event.event_type === "tool.completed" && input.signal === "post-tool-use") {
+      maybeCommitActiveRuntimeContextObservation(
+        input,
+        state,
+        path,
+        rootId,
+        fingerprintContext,
+        event,
+      );
+    }
     if (turnTelemetry) {
       const contextTarget = turnContextTarget(event);
-      queuePendingRuntimeContext(input, state, contextTarget, turnTelemetry.context);
+      queuePendingRuntimeContext(
+        input,
+        state,
+        contextTarget,
+        turnTelemetry.context,
+        nativeTurnIdForContext,
+      );
       commitTurnContextObservation(
         input,
         state,
@@ -1652,6 +1741,53 @@ function commitTurnContextObservation(
   observedAt?: string,
 ): void {
   if (!target) return;
+  commitContextObservation(
+    input,
+    state,
+    path,
+    rootId,
+    fingerprintContext,
+    {
+      caused_by_event_id: target.terminal_event_id,
+      observed_at: observedAt ?? target.terminal_observed_at,
+      turn_id: target.turn_id,
+      ...(target.run_id ? { run_id: target.run_id } : {}),
+      ...(target.workflow_id ? { workflow_id: target.workflow_id } : {}),
+      ...(target.workflow_agent_id ? { workflow_agent_id: target.workflow_agent_id } : {}),
+    },
+    measurement,
+    contextProvenance,
+  );
+}
+
+function commitContextObservation(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  path: string,
+  rootId: `root_${string}`,
+  fingerprintContext: ReturnType<typeof fingerprintContextV3>,
+  target: {
+    caused_by_event_id: `evt_${string}`;
+    observed_at: string;
+    turn_id: `tid_${string}`;
+    run_id?: `run_${string}`;
+    workflow_id?: `wf_${string}`;
+    workflow_agent_id?: string;
+  },
+  measurement: TelemetryObservationV3<ContextMeasurementV3>,
+  contextProvenance?: ContextTelemetryProvenanceV3,
+): void {
+  if (
+    measurement.state === "observed" &&
+    contextProvenance?.source_witness &&
+    state.last_context_source_witness === contextProvenance.source_witness
+  ) {
+    publishProducerState(path, state);
+    return;
+  }
+  if (measurement.state === "observed" && contextProvenance?.source_witness) {
+    state.last_context_source_witness = contextProvenance.source_witness;
+  }
   const event = buildEventV3("context.observed", {
     producer: {
       producer_id: input.producer_id,
@@ -1673,7 +1809,7 @@ function commitTurnContextObservation(
       ...(target.workflow_agent_id ? { workflow_agent_id: target.workflow_agent_id } : {}),
     },
     attestation_id: state.attestation_id,
-    links: { caused_by: [target.terminal_event_id] },
+    links: { caused_by: [target.caused_by_event_id] },
     provenance: {
       source_event: safeRole(
         [
@@ -1700,10 +1836,10 @@ function commitTurnContextObservation(
         subject_instance_id: state.instance_id,
       },
     },
-    // The source sample may precede native task completion. The event itself
-    // is committed after turn.completed, while measurement.measured_at keeps
-    // the sample clock without creating a causal wall-clock regression.
-    observed_at: observedAt ?? target.terminal_observed_at,
+    // The source sample may precede the hook boundary that admits it.
+    // measurement.measured_at preserves the sample clock without creating a
+    // causal wall-clock regression in the producer event chain.
+    observed_at: target.observed_at,
     monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
     clock_id: state.clock_id,
     payload: {
@@ -1714,6 +1850,198 @@ function commitTurnContextObservation(
   maybeAttestContextCapabilityChange(input, state, path, rootId, measurement, contextProvenance);
 }
 
+/**
+ * Admit fresh adapter-native or bounded runtime context while a turn is open.
+ * Tool completions are safe sampling boundaries. Persistent owner-only cadence
+ * state prevents short-lived hook processes from reading on every request,
+ * and the source witness prevents duplicate public events.
+ */
+function maybeCommitActiveRuntimeContextObservation(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  path: string,
+  rootId: `root_${string}`,
+  fingerprintContext: ReturnType<typeof fingerprintContextV3>,
+  sourceEvent: EventV3,
+): void {
+  if (input.signal !== "post-tool-use" || state.terminal || !state.current_turn_id) {
+    return;
+  }
+  const nativeSessionId = input.payload.session_id ?? input.payload.conversation_id;
+  const nativeTurnId = input.payload.turn_id ?? state.current_native_turn_id;
+  if (!nativeSessionId || (!nativeTurnId && input.adapter !== "cursor")) return;
+
+  const now = Date.now();
+  const configuredInterval = input.runtimeTelemetryOptions?.activeContextProbeIntervalMs;
+  const intervalMs =
+    configuredInterval !== undefined && Number.isFinite(configuredInterval)
+      ? Math.max(0, Math.floor(configuredInterval))
+      : ACTIVE_RUNTIME_CONTEXT_PROBE_INTERVAL_MS;
+  const prior = state.active_runtime_context_probe;
+  const priorAttempt = prior ? Date.parse(prior.attempted_at) : Number.NaN;
+  if (
+    prior?.turn_id === state.current_turn_id &&
+    prior.boundary === "tool_completed" &&
+    Number.isFinite(priorAttempt) &&
+    now - priorAttempt >= 0 &&
+    now - priorAttempt < intervalMs
+  ) {
+    return;
+  }
+  state.active_runtime_context_probe = {
+    turn_id: state.current_turn_id,
+    attempted_at: new Date(now).toISOString(),
+    boundary: "tool_completed",
+  };
+
+  const native = extractTurnTelemetryV3(
+    input.adapter,
+    input.payload.raw,
+    sourceEvent.time.observed_at,
+  ).context;
+  if (native.state === "observed") {
+    commitActiveContextObservation(
+      input,
+      state,
+      path,
+      rootId,
+      fingerprintContext,
+      sourceEvent,
+      native,
+      nativeContextProvenance(input, state, native),
+    );
+    return;
+  }
+  if (input.adapter === "cursor" && state.cursor_mode === "cloud") {
+    publishProducerState(path, state);
+    return;
+  }
+
+  const transcriptPath = runtimeTranscriptPath(input, state);
+  if (!transcriptPath && input.adapter !== "cursor") {
+    publishProducerState(path, state);
+    return;
+  }
+  const runtime = readRuntimeContextTelemetry(
+    {
+      adapter: input.adapter,
+      session_id: nativeSessionId,
+      ...(nativeTurnId ? { turn_id: nativeTurnId } : {}),
+      ...(state.current_turn_span?.opened_at
+        ? { turn_started_at: state.current_turn_span.opened_at }
+        : {}),
+      transcript_path: transcriptPath,
+      observed_at: sourceEvent.time.observed_at,
+      mode: "active_turn",
+    },
+    input.runtimeTelemetryOptions,
+  );
+  if (runtime.bytes_read > 0) recordRuntimeTelemetryTiming(state, runtime.io_duration_ms);
+  if (runtime.state !== "observed") {
+    publishProducerState(path, state);
+    return;
+  }
+
+  commitActiveContextObservation(
+    input,
+    state,
+    path,
+    rootId,
+    fingerprintContext,
+    sourceEvent,
+    runtimeContextObservation(runtime),
+    {
+      source_event: runtime.source_event,
+      source_witness: runtime.source_witness,
+      ...(input.adapterVersion ? { runtime_version: input.adapterVersion } : {}),
+      attestation: runtime.attestation,
+      confidence: runtime.confidence,
+    },
+  );
+}
+
+function commitActiveContextObservation(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  path: string,
+  rootId: `root_${string}`,
+  fingerprintContext: ReturnType<typeof fingerprintContextV3>,
+  sourceEvent: EventV3,
+  measurement: TelemetryObservationV3<ContextMeasurementV3>,
+  provenance: ContextTelemetryProvenanceV3,
+): void {
+  if (!state.current_turn_id) return;
+  const scope = sourceEvent.scope as {
+    run_id?: `run_${string}`;
+    workflow_id?: `wf_${string}`;
+    workflow_agent_id?: string;
+  };
+  commitContextObservation(
+    input,
+    state,
+    path,
+    rootId,
+    fingerprintContext,
+    {
+      caused_by_event_id: sourceEvent.event_id as `evt_${string}`,
+      observed_at: sourceEvent.time.observed_at,
+      turn_id: state.current_turn_id,
+      ...(scope.run_id ? { run_id: scope.run_id } : {}),
+      ...(scope.workflow_id ? { workflow_id: scope.workflow_id } : {}),
+      ...(scope.workflow_agent_id ? { workflow_agent_id: scope.workflow_agent_id } : {}),
+    },
+    measurement,
+    provenance,
+  );
+}
+
+function nativeContextProvenance(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  measurement: Extract<TelemetryObservationV3<ContextMeasurementV3>, { state: "observed" }>,
+): ContextTelemetryProvenanceV3 {
+  const { measured_at: _measuredAt, ...stableValue } = measurement.value;
+  const witness = canonicalJsonV3({
+    adapter: input.adapter,
+    session_id: state.session_id,
+    turn_id: state.current_turn_id,
+    value: stableValue,
+  });
+  return {
+    source_event: `${input.adapter}.native_context`,
+    source_witness: createHash("sha256").update(witness).digest("hex"),
+    ...(input.adapterVersion ? { runtime_version: input.adapterVersion } : {}),
+    attestation: measurement.attestation,
+    confidence: measurement.confidence,
+  };
+}
+
+function maybeCommitNativeHookContextObservation(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  path: string,
+  rootId: `root_${string}`,
+  fingerprintContext: ReturnType<typeof fingerprintContextV3>,
+  sourceEvent: EventV3,
+): void {
+  const measurement = extractTurnTelemetryV3(
+    input.adapter,
+    input.payload.raw,
+    sourceEvent.time.observed_at,
+  ).context;
+  if (measurement.state !== "observed") return;
+  commitActiveContextObservation(
+    input,
+    state,
+    path,
+    rootId,
+    fingerprintContext,
+    sourceEvent,
+    measurement,
+    nativeContextProvenance(input, state, measurement),
+  );
+}
+
 function maybeAttestContextCapabilityChange(
   input: RecordHookSignalV3Input,
   state: HookProducerStateV3,
@@ -1729,6 +2057,12 @@ function maybeAttestContextCapabilityChange(
           source: provenance?.source_event ?? `${input.adapter}.turn_context`,
           attestation: provenance?.attestation ?? measurement.attestation,
           confidence: provenance?.confidence ?? measurement.confidence,
+          completeness:
+            "used_percent" in measurement.value
+              ? ("percentage_only" as const)
+              : (provenance?.attestation ?? measurement.attestation) === "inferred"
+                ? ("inferred" as const)
+                : ("exact" as const),
         }
       : measurement.state === "expected_but_missing"
         ? { state: "partial" as const, reason: measurement.reason }
@@ -1777,6 +2111,7 @@ function queuePendingRuntimeContext(
   state: HookProducerStateV3,
   target: TurnContextTargetV3 | undefined,
   measurement: TelemetryObservationV3<ContextMeasurementV3>,
+  nativeTurnId: string | undefined,
 ): void {
   if (
     input.adapter !== "codex" ||
@@ -1787,7 +2122,6 @@ function queuePendingRuntimeContext(
     return;
   }
   const nativeSessionId = input.payload.session_id ?? input.payload.conversation_id;
-  const nativeTurnId = input.payload.turn_id;
   if (!nativeSessionId || !nativeTurnId) return;
   const pending: PendingRuntimeContextV3 = {
     ...target,
@@ -1925,19 +2259,36 @@ function turnTelemetryForTerminal(
   observedAt: string,
 ): TurnTelemetryV3 {
   const native = extractTurnTelemetryV3(input.adapter, input.payload.raw, observedAt);
-  if (native.context.state === "observed" || input.adapter === "cursor") return native;
+  if (native.context.state === "observed") return native;
+  if (input.adapter === "cursor" && state.cursor_mode === "cloud") {
+    return {
+      ...native,
+      context: { state: "unsupported", capability: "context_usage" },
+    };
+  }
 
-  const runtime = readRuntimeContextTelemetry(
-    {
-      adapter: input.adapter,
-      session_id: input.payload.session_id ?? input.payload.conversation_id,
-      turn_id: input.payload.turn_id ?? state.current_native_turn_id,
-      transcript_path: runtimeTranscriptPath(input, state),
-      mode: "turn",
-    },
-    input.runtimeTelemetryOptions,
-  );
+  const request = {
+    adapter: input.adapter,
+    session_id: input.payload.session_id ?? input.payload.conversation_id,
+    turn_id: input.payload.turn_id ?? state.current_native_turn_id,
+    transcript_path: runtimeTranscriptPath(input, state),
+    observed_at: observedAt,
+    mode: "turn" as const,
+  };
+  let runtime = readRuntimeContextTelemetry(request, input.runtimeTelemetryOptions);
   if (runtime.bytes_read > 0) recordRuntimeTelemetryTiming(state, runtime.io_duration_ms);
+  if (
+    input.adapter === "codex" &&
+    runtime.state === "partial" &&
+    retryableRuntimeContextReason(runtime.reason)
+  ) {
+    for (const delayMs of STOP_RUNTIME_CONTEXT_RETRY_DELAYS_MS) {
+      sleepSync(delayMs);
+      runtime = readRuntimeContextTelemetry(request, input.runtimeTelemetryOptions);
+      if (runtime.bytes_read > 0) recordRuntimeTelemetryTiming(state, runtime.io_duration_ms);
+      if (runtime.state !== "partial" || !retryableRuntimeContextReason(runtime.reason)) break;
+    }
+  }
   if (runtime.state === "unsupported") return native;
   return {
     ...native,
@@ -1947,8 +2298,8 @@ function turnTelemetryForTerminal(
         runtime.state === "observed" ? runtime.source_event : `${input.adapter}.runtime_context`,
       ...(runtime.state === "observed" ? { source_witness: runtime.source_witness } : {}),
       ...(input.adapterVersion ? { runtime_version: input.adapterVersion } : {}),
-      attestation: "derived",
-      confidence: runtime.state === "observed" ? "exact" : "high",
+      attestation: runtime.state === "observed" ? runtime.attestation : "derived",
+      confidence: runtime.state === "observed" ? runtime.confidence : "high",
     },
   };
 }
@@ -2001,6 +2352,19 @@ function runtimeContextObservation(
   runtime: RuntimeContextTelemetry,
 ): TelemetryObservationV3<ContextMeasurementV3> {
   if (runtime.state === "observed") {
+    if ("used_percent" in runtime) {
+      return {
+        state: "observed",
+        value: {
+          used_percent: runtime.used_percent,
+          remaining_percent: Math.max(0, 100 - runtime.used_percent),
+          measured_at: runtime.measured_at,
+          method: runtime.method,
+        },
+        attestation: runtime.attestation,
+        confidence: runtime.confidence,
+      };
+    }
     return {
       state: "observed",
       value: {
@@ -2010,8 +2374,8 @@ function runtimeContextObservation(
         measured_at: runtime.measured_at,
         method: runtime.method,
       },
-      attestation: "derived",
-      confidence: "exact",
+      attestation: runtime.attestation,
+      confidence: runtime.confidence,
     };
   }
   return {
@@ -2176,8 +2540,8 @@ interface RuntimeAttestationChangeV3 {
   telemetry: RuntimeTelemetryCapabilitiesV3;
   reason: string;
   source_event: string;
-  attestation: "native" | "derived";
-  confidence: "exact" | "high";
+  attestation: "native" | "derived" | "inferred";
+  confidence: "exact" | "high" | "medium" | "low";
 }
 
 function commitRuntimeAttestationChange(
@@ -2527,6 +2891,40 @@ function isCursorPromptBootstrap(input: RecordHookSignalV3Input): boolean {
   );
 }
 
+/** Privacy-safe environment and recovery provenance for Codex mid-flight
+ * onboarding. WSLENV values are never recorded, only normalized variable
+ * names, and the native session identifier itself remains fingerprinted. */
+export function codexMidFlightDiagnosticContext(
+  payload: ParsedPayload,
+  env: NodeJS.ProcessEnv = process.env,
+): Record<string, string | boolean> {
+  const wslenv = env.WSLENV?.trim() ?? "";
+  const wslenvNames = [
+    ...new Set(
+      wslenv
+        .split(":")
+        .map((entry) => entry.split("/", 1)[0]?.trim() ?? "")
+        .filter((name) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(name)),
+    ),
+  ]
+    .sort()
+    .join(":")
+    .slice(0, 512);
+  const identityRecoverySource = payload.session_id
+    ? "native_session_id"
+    : payload.conversation_id
+      ? "native_conversation_id"
+      : payload.agent_id
+        ? "native_agent_id"
+        : "unavailable";
+  return {
+    thread_id_present: Boolean(env.CODEX_THREAD_ID?.trim()),
+    wslenv_present: wslenv.length > 0,
+    wslenv_names: wslenvNames,
+    identity_recovery_source: identityRecoverySource,
+  };
+}
+
 function suppressClosedSpanSignal(
   input: RecordHookSignalV3Input,
   sessionHash: `hid_${string}`,
@@ -2555,6 +2953,13 @@ export function recordApprovedSessionEndV3(
   if (control.state !== input.mode) {
     return { state: "gate_closed", reason: control.state };
   }
+  input = {
+    ...input,
+    writerOptions: {
+      ...input.writerOptions,
+      expectedGenesisId: control.genesis.event.payload.genesis_id as `gex_${string}`,
+    },
+  };
   const matches = listHookProducerStateRecordsV3(input.coordRoot, { includeTerminal: true }).filter(
     ({ state }) =>
       state.instance_id === input.instance_id && state.generation_id === input.generation_id,
@@ -2716,6 +3121,13 @@ export function salvageOpenSpansV3(input: SalvageOpenSpansV3Input): SalvageOpenS
   if (control.state !== input.mode) {
     return { state: "gate_closed", reason: control.state };
   }
+  input = {
+    ...input,
+    writerOptions: {
+      ...input.writerOptions,
+      expectedGenesisId: control.genesis.event.payload.genesis_id as `gex_${string}`,
+    },
+  };
   const matches = listHookProducerStateRecordsV3(input.coordRoot).filter(
     ({ state }) =>
       state.instance_id === input.instance_id && state.generation_id === input.generation_id,
@@ -2824,6 +3236,9 @@ export function listHookProducerStateRecordsV3(
     )) {
       const path = join(directory, name);
       const state = readProducerState(path);
+      // Skip authorities left behind by a replaced epoch: their sequences and
+      // causal links belong to the archived ledger, not this one.
+      if (state.epoch_genesis_id !== control.genesis.event.payload.genesis_id) continue;
       if (!options.includeTerminal && state.terminal) continue;
       records.push({ path, modified_at_ms: lstatSync(path).mtimeMs, state });
     }
@@ -2880,7 +3295,101 @@ export function readHookProducerStateV3(
   );
   const sessionHash = normalizeNativeIdV3(context, `${adapter}.session`, nativeSessionId);
   const path = producerStatePath(coordRoot, adapter, sessionHash);
-  return existsSync(path) ? readProducerState(path) : undefined;
+  if (!existsSync(path)) return undefined;
+  const state = readProducerState(path);
+  // A state left behind by a replaced epoch is not this epoch's authority.
+  return state.epoch_genesis_id === control.genesis.event.payload.genesis_id ? state : undefined;
+}
+
+export interface ReconcilePendingRuntimeContextV3Input {
+  coordRoot: string;
+  mode: EventV3WriteMode;
+  nativeSessionId: string;
+  producer_id: `prd_${string}`;
+  build_id: `build_${string}`;
+  platform: "linux" | "windows" | "macos" | "unknown";
+  finalAttempt?: boolean;
+  runtimeTelemetryOptions?: RuntimeTelemetryOptions;
+  writerOptions?: WriteEventV3Options;
+}
+
+export type ReconcilePendingRuntimeContextV3Result =
+  | { state: "gate_closed" }
+  | { state: "missing" }
+  | { state: "busy" }
+  | { state: "not_pending" }
+  | { state: "pending" }
+  | { state: "settled" };
+
+/**
+ * Retry one Codex session's owner-only context join without replaying its Stop
+ * signal. Codex appends `task_complete` only after the synchronous Stop hook
+ * exits, so this is invoked by a bounded detached worker after that exit.
+ */
+export function reconcilePendingRuntimeContextV3(
+  input: ReconcilePendingRuntimeContextV3Input,
+): ReconcilePendingRuntimeContextV3Result {
+  const control = readEventV3ControlState(input.coordRoot);
+  if (control.state !== input.mode) return { state: "gate_closed" };
+  if (control.state !== "candidate" && control.state !== "active") {
+    return { state: "gate_closed" };
+  }
+  const rootId = control.genesis.event.scope.root_id as `root_${string}`;
+  const rootContext = fingerprintContextV3(
+    input.coordRoot,
+    rootId,
+    undefined,
+    control.genesis.profile.privacy_key_epoch,
+  );
+  const sessionHash = normalizeNativeIdV3(rootContext, "codex.session", input.nativeSessionId);
+  const path = producerStatePath(input.coordRoot, "codex", sessionHash);
+  if (!existsSync(path)) return { state: "missing" };
+  const lease = acquireStateLeaseWithRetry(input.coordRoot, path, STATE_LEASE_RETRY_ATTEMPTS);
+  if (!lease) return { state: "busy" };
+  try {
+    const state = readProducerState(path);
+    if (state.epoch_genesis_id !== control.genesis.event.payload.genesis_id) {
+      // The pending contexts belong to a replaced epoch; its archive already
+      // holds everything this producer durably recorded.
+      return { state: "missing" };
+    }
+    if (state.adapter !== "codex" || !state.pending_runtime_contexts?.length) {
+      return { state: "not_pending" };
+    }
+    const context = fingerprintContextV3(
+      input.coordRoot,
+      rootId,
+      state.generation_id,
+      state.privacy_epoch_id,
+    );
+    reconcilePendingRuntimeContexts(
+      {
+        coordRoot: input.coordRoot,
+        mode: input.mode,
+        signal: "stop",
+        payload: { raw: {}, session_id: input.nativeSessionId },
+        adapter: "codex",
+        instance_id: state.instance_id,
+        producer_id: input.producer_id,
+        build_id: input.build_id,
+        platform: input.platform,
+        observed_at: new Date().toISOString(),
+        runtimeTelemetryOptions: input.runtimeTelemetryOptions,
+        writerOptions: {
+          ...input.writerOptions,
+          expectedGenesisId: control.genesis.event.payload.genesis_id as `gex_${string}`,
+        },
+      },
+      state,
+      path,
+      rootId,
+      context,
+      { deferRetryLimit: true, finalAttempt: input.finalAttempt },
+    );
+    return state.pending_runtime_contexts?.length ? { state: "pending" } : { state: "settled" };
+  } finally {
+    lease.release();
+  }
 }
 
 /** Resolve one terminal producer only when native session and instance identity agree. */
@@ -2918,6 +3427,7 @@ export function readHookProducerStateByInstanceV3(
       /^hid_[a-f0-9]{64}\.json$/.test(entry),
     )) {
       const state = readProducerState(join(directory, name));
+      if (state.epoch_genesis_id !== control.genesis.event.payload.genesis_id) continue;
       if (state.instance_id === instanceId && !state.terminal) matches.push(state);
     }
   }
@@ -2949,6 +3459,7 @@ function newProducerState(
   sessionId: `sid_${string}`,
   epochId: `pep_${string}`,
   boundaryEventId: `evt_${string}`,
+  genesisId: `gex_${string}`,
 ): HookProducerStateV3 {
   const bootId = `boot_${randomUUID()}` as const;
   return {
@@ -2962,6 +3473,7 @@ function newProducerState(
     capability_profile: adapterCapabilityProfileDigestV3(input.adapter),
     cursor_mode: input.adapter === "cursor" ? (input.payload.cursor_mode ?? "unknown") : undefined,
     privacy_epoch_id: epochId,
+    epoch_genesis_id: genesisId,
     boot_id: bootId,
     clock_id: clockIdV3(),
     next_sequence: 1,
@@ -2972,6 +3484,7 @@ function newProducerState(
       boot_id: bootId,
       clock: signalClock(input),
     }),
+    session_start_derivation: input.session_start_derivation,
     terminal: false,
     spans: [],
     delegations: [],
@@ -3002,6 +3515,7 @@ function applyCommittedEvent(state: HookProducerStateV3, event: EventV3): void {
   if (event.event_type === "turn.started") {
     const nextTurnId = (event.scope as { turn_id: `tid_${string}` }).turn_id;
     state.current_turn_id = nextTurnId;
+    state.session_start_derivation = undefined;
     if (state.tool_call_count_turn_id !== nextTurnId) {
       state.tool_call_count = 0;
       state.tool_call_count_turn_id = nextTurnId;
@@ -3378,6 +3892,7 @@ function readProducerState(path: string): HookProducerStateV3 {
   }
   if (state.adapter === "cursor") state.cursor_mode ??= "unknown";
   const allowedKeys = new Set([
+    "active_runtime_context_probe",
     "adapter",
     "attestation_id",
     "boot_id",
@@ -3390,6 +3905,7 @@ function readProducerState(path: string): HookProducerStateV3 {
     "current_turn_span",
     "cursor_mode",
     "delegations",
+    "epoch_genesis_id",
     "format",
     "format_version",
     "generation_id",
@@ -3399,6 +3915,7 @@ function readProducerState(path: string): HookProducerStateV3 {
     "last_attested_telemetry",
     "last_attested_tuning",
     "last_attested_tuning_observation",
+    "last_context_source_witness",
     "tuning_probe_turn_id",
     "last_event_id",
     "last_monotonic_ns",
@@ -3409,6 +3926,7 @@ function readProducerState(path: string): HookProducerStateV3 {
     "runtime_transcript_path",
     "privacy_epoch_id",
     "session_id",
+    "session_start_derivation",
     "session_span",
     "spans",
     "started_event_id",
@@ -3432,6 +3950,7 @@ function readProducerState(path: string): HookProducerStateV3 {
     !/^att_[0-9a-f-]{36}$/.test(state.attestation_id) ||
     !/^cap_[a-f0-9]{64}$/.test(state.capability_profile) ||
     !/^pep_[a-zA-Z0-9._-]+$/.test(state.privacy_epoch_id) ||
+    (state.epoch_genesis_id !== undefined && !/^gex_[0-9a-f-]{36}$/.test(state.epoch_genesis_id)) ||
     !/^boot_[a-zA-Z0-9._-]+$/.test(state.boot_id) ||
     !/^clk_[0-9a-f-]{36}$/.test(state.clock_id) ||
     !Number.isSafeInteger(state.next_sequence) ||
@@ -3507,11 +4026,18 @@ function readProducerState(path: string): HookProducerStateV3 {
     (state.last_observed_at !== undefined &&
       !Number.isFinite(Date.parse(state.last_observed_at))) ||
     (state.started_event_id !== undefined && !/^evt_[0-9a-f-]{36}$/.test(state.started_event_id)) ||
+    (state.session_start_derivation !== undefined &&
+      state.session_start_derivation !== "approved_lifecycle_reopen" &&
+      state.session_start_derivation !== "validated_current_session_heal") ||
     (state.pending_runtime_contexts !== undefined &&
       (!Array.isArray(state.pending_runtime_contexts) ||
         state.pending_runtime_contexts.length === 0 ||
         state.pending_runtime_contexts.length > PENDING_RUNTIME_CONTEXT_CAP ||
         state.pending_runtime_contexts.some((pending) => !validPendingRuntimeContext(pending)))) ||
+    (state.active_runtime_context_probe !== undefined &&
+      !validActiveRuntimeContextProbe(state.active_runtime_context_probe)) ||
+    (state.last_context_source_witness !== undefined &&
+      !/^[a-f0-9]{64}$/.test(state.last_context_source_witness)) ||
     (state.runtime_transcript_path !== undefined &&
       (typeof state.runtime_transcript_path !== "string" ||
         state.runtime_transcript_path.length === 0 ||
@@ -3629,6 +4155,18 @@ function validPendingRuntimeContext(value: unknown): value is PendingRuntimeCont
   );
 }
 
+function validActiveRuntimeContextProbe(value: unknown): value is ActiveRuntimeContextProbeV3 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const probe = value as ActiveRuntimeContextProbeV3;
+  return (
+    typeof probe.turn_id === "string" &&
+    /^tid_[a-f0-9]{64}$/.test(probe.turn_id) &&
+    typeof probe.attempted_at === "string" &&
+    Number.isFinite(Date.parse(probe.attempted_at)) &&
+    (probe.boundary === undefined || probe.boundary === "tool_completed")
+  );
+}
+
 function pidIsAlive(pid: number): boolean {
   if (!Number.isSafeInteger(pid) || pid < 1) return false;
   try {