harnery 0.34.0 → 0.35.0

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

@@ -17,10 +17,18 @@ import { hostname } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { Adapter } from "../../../adapter.ts";
 import { extractBashCommand, type ParsedPayload } from "../../../hooks/adapter/parse.ts";
+import {
+  discoverCodexSessionTranscript,
+  type RuntimeContextTelemetry,
+  type RuntimeTelemetryOptions,
+  readRuntimeContextTelemetry,
+  readRuntimeTuning,
+} from "../../../hooks/adapter/runtime-telemetry.ts";
 import { fsyncParentDirectory } from "../../../workflow/durable-record.ts";
 import { acquireNoClobberLease } from "../../../workflow/workspaces/leases.ts";
+import type { RuntimeAttestationV3Base } from "../base-contract.ts";
 import { buildEventV3 } from "../builder.ts";
-import { fingerprintV3, normalizeNativeIdV3 } from "../canonical.ts";
+import { canonicalJsonV3, fingerprintV3, normalizeNativeIdV3 } from "../canonical.ts";
 import {
   type AdapterSignalV3,
   adapterCapabilityProfileDigestV3,
@@ -33,8 +41,19 @@ import { markObservedClockRegressionV3 } from "../clock-order.ts";
 import type { EventV3 } from "../contract.ts";
 import { type EventV3WriteMode, readEventV3ControlState } from "../control.ts";
 import { fingerprintContextV3 } from "../fingerprint-keys.ts";
-import { attestationIdV3, clockIdV3, delegationIdV3, generationIdV3, spanIdV3 } from "../ids.ts";
+import {
+  attestationIdV3,
+  clockIdV3,
+  delegationIdV3,
+  eventIdV3,
+  generationIdV3,
+  spanIdV3,
+} from "../ids.ts";
 import { readLedgerV3 } from "../reader.ts";
+import {
+  effectiveRuntimeTelemetryCapabilitiesV3,
+  type RuntimeTelemetryCapabilitiesV3,
+} from "../runtime-telemetry-capabilities.ts";
 import {
   closeSpanStateV3,
   type OpenSpanStateV3,
@@ -44,8 +63,10 @@ import {
 } from "../span-state.ts";
 import {
   type ContextMeasurementV3,
+  type ContextTelemetryProvenanceV3,
   extractTurnTelemetryV3,
   type TelemetryObservationV3,
+  type TurnTelemetryV3,
 } from "../turn-telemetry.ts";
 import { assertEventV3, validateEventV3 } from "../validate.ts";
 import {
@@ -74,6 +95,10 @@ const CLOSED_SPAN_TURN_RETENTION = 2;
 const CLOSED_SPAN_MEMORY_CAP = 512;
 const CLOSED_TURN_MEMORY_CAP = 16;
 const SPAN_SOFT_WATERMARK = 128;
+const PENDING_RUNTIME_CONTEXT_CAP = 4;
+const RUNTIME_CONTEXT_RETRY_LIMIT = 2;
+/** 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;
 /**
  * Adapters whose turn-boundary recovery and mid-flight onboarding are enabled.
  * Kept in code, outside the digested capability profiles, so tuning recovery
@@ -117,6 +142,23 @@ interface PendingEventV3 {
   event: EventV3;
 }
 
+interface TurnContextTargetV3 {
+  terminal_event_id: `evt_${string}`;
+  terminal_observed_at: string;
+  turn_id: `tid_${string}`;
+  run_id?: `run_${string}`;
+  workflow_id?: `wf_${string}`;
+  workflow_agent_id?: string;
+}
+
+interface PendingRuntimeContextV3 extends TurnContextTargetV3 {
+  native_session_id: string;
+  native_turn_id: string;
+  transcript_path?: string;
+  runtime_version?: string;
+  attempts: number;
+}
+
 interface DelegationStateV3 extends OpenSpanStateV3 {
   source_id: `hid_${string}`;
   delegation_id: `del_${string}`;
@@ -139,6 +181,8 @@ export interface HookProducerStateV3 {
   clock_id: `clk_${string}`;
   next_sequence: number;
   current_turn_id?: `tid_${string}`;
+  /** Native turn identity retained owner-only for transcript attribution. */
+  current_native_turn_id?: string;
   tool_call_count: number;
   tool_call_count_turn_id?: `tid_${string}`;
   last_event_id?: `evt_${string}`;
@@ -156,6 +200,25 @@ export interface HookProducerStateV3 {
   turn_harness: TurnHarnessTimingV3;
   turn_ordinal: number;
   pending?: PendingEventV3;
+  pending_runtime_contexts?: PendingRuntimeContextV3[];
+  /** Verified adapter-native transcript path retained only in owner-only state. */
+  runtime_transcript_path?: string;
+  /** Tuning carried by the current attestation; {} means attested-none.
+   * Absent on pre-upgrade state files, which seed silently on first sight. */
+  last_attested_tuning?: { effort?: string; speed?: string };
+  /** Model observation carried forward into a refreshed attestation when the
+   * change-time transcript read does not pair a model with the new tuning. */
+  last_attested_model?: { provider: string; id: string };
+  /** Telemetry evidence carried forward verbatim: a tuning change does not
+   * alter what telemetry the runtime proved it can deliver. */
+  last_attested_telemetry?: RuntimeTelemetryCapabilitiesV3;
+  /** Full observations preserve missing and unsupported states when a
+   * different attestation channel changes. */
+  last_attested_model_observation?: RuntimeAttestationV3Base["model"];
+  last_attested_tuning_observation?: RuntimeAttestationV3Base["tuning"];
+  /** Turn already probed for Codex tuning while effort is unknown; bounds the
+   * rollout forward-scan to one attempt per turn. */
+  tuning_probe_turn_id?: `tid_${string}`;
 }
 
 export interface RecordHookSignalV3Input {
@@ -181,6 +244,14 @@ export interface RecordHookSignalV3Input {
   stop_remediation?: boolean;
   turn_ritual?: TurnRitualEvidenceV3;
   session_start_derivation?: "approved_lifecycle_reopen";
+  delegated_child?: {
+    generation_id: `gen_${string}`;
+    parent_generation_id: `gen_${string}`;
+    delegation_id: `del_${string}`;
+    caused_by_event_id: `evt_${string}`;
+  };
+  /** Optional roots and read budgets for runtime telemetry adapters. */
+  runtimeTelemetryOptions?: RuntimeTelemetryOptions;
   writerOptions?: WriteEventV3Options;
 }
 
@@ -310,11 +381,21 @@ function hookSignalGate(
 }
 
 function sessionHashForSignal(
-  input: Pick<RecordHookSignalV3Input, "coordRoot" | "payload" | "adapter" | "instance_id">,
+  input: Pick<
+    RecordHookSignalV3Input,
+    "coordRoot" | "payload" | "adapter" | "instance_id" | "signal"
+  >,
   context: ReturnType<typeof fingerprintContextV3>,
 ): `hid_${string}` {
-  const nativeSession =
-    input.payload.session_id ?? input.payload.conversation_id ?? input.payload.agent_id;
+  const nativeChild = input.payload.subagent_id ?? input.payload.agent_id;
+  const childOwnsSignal =
+    input.signal !== "sub-agent-start" &&
+    input.signal !== "sub-agent-stop" &&
+    nativeChild !== undefined &&
+    input.instance_id === asLiveInstanceId(nativeChild);
+  const nativeSession = childOwnsSignal
+    ? nativeChild
+    : (input.payload.session_id ?? input.payload.conversation_id ?? input.payload.agent_id);
   if (nativeSession !== undefined) {
     return normalizeNativeIdV3(context, `${input.adapter}.session`, nativeSession);
   }
@@ -360,6 +441,7 @@ function intakeRecord(input: RecordHookSignalV3Input): HookIntakeRecordV3 {
       : {}),
     ...(input.stop_remediation !== undefined ? { stop_remediation: input.stop_remediation } : {}),
     ...(input.turn_ritual ? { turn_ritual: input.turn_ritual } : {}),
+    ...(input.delegated_child ? { delegated_child: input.delegated_child } : {}),
   };
 }
 
@@ -386,6 +468,7 @@ function inputForIntakeRecord(
     ...(record.hook_duration_ms !== undefined ? { hook_duration_ms: record.hook_duration_ms } : {}),
     ...(record.stop_remediation !== undefined ? { stop_remediation: record.stop_remediation } : {}),
     ...(record.turn_ritual ? { turn_ritual: record.turn_ritual } : {}),
+    ...(record.delegated_child ? { delegated_child: record.delegated_child } : {}),
   };
 }
 
@@ -669,6 +752,9 @@ function processHookSignalLocked(
         (nativeTid !== undefined && state.current_turn_id === nativeTid));
 
     recordTurnHarnessTiming(state, input, !duplicateOpenTurnStart);
+    reconcilePendingRuntimeContexts(input, state, path, rootId, fingerprintContext, {
+      finalAttempt: input.signal === "session-end",
+    });
 
     closeResolvedWaits(input, state, path, rootId, fingerprintContext, nativeTid);
     if (input.signal === "permission-request") {
@@ -736,6 +822,7 @@ function processHookSignalLocked(
         boot_id: state.boot_id,
         clock: eventClock,
       });
+      state.current_native_turn_id = input.payload.turn_id;
     }
 
     let sourceId = sourceIdForSignal(input, rootFingerprintContext);
@@ -933,7 +1020,7 @@ function processHookSignalLocked(
 
     const turnTelemetry =
       input.signal === "stop" || input.signal === "stop-failure"
-        ? extractTurnTelemetryV3(input.adapter, input.payload.raw, eventClock.observed_at)
+        ? turnTelemetryForTerminal(input, state, eventClock.observed_at)
         : undefined;
     const cursorToolChannelSupport =
       input.adapter === "cursor"
@@ -950,6 +1037,9 @@ function processHookSignalLocked(
     const toolCallCountScopeMismatch =
       (input.signal === "stop" || input.signal === "stop-failure") &&
       (!state.current_turn_id || state.tool_call_count_turn_id !== state.current_turn_id);
+    // Before the signal's own event: the tool call or turn that carries the
+    // new effort already ran under it, so it must ride the new attestation.
+    maybeAttestTuningChange(input, state, path, rootId);
     const event = normalizeHookEventV3(input.signal, eventInput.payload, {
       coordRoot: input.coordRoot,
       adapter: input.adapter,
@@ -973,6 +1063,7 @@ function processHookSignalLocked(
       platform: input.platform,
       bridge: input.bridge,
       capability_profile: state.capability_profile,
+      cursor_mode: state.cursor_mode,
       fingerprintContext,
       turn_id: state.current_turn_id,
       span_id: openingSpan?.span_id ?? closingSpan?.span_id,
@@ -1010,6 +1101,48 @@ function processHookSignalLocked(
       turn_ritual: input.turn_ritual,
     });
     if (!event) return { state: "ignored" };
+    if (
+      input.signal === "session-start" &&
+      input.delegated_child &&
+      event.event_type === "session.started"
+    ) {
+      event.links = {
+        caused_by: [input.delegated_child.caused_by_event_id],
+        parent_generation_id: input.delegated_child.parent_generation_id,
+        delegation_id: input.delegated_child.delegation_id,
+      };
+      event.provenance = {
+        ...event.provenance,
+        source_event: `${input.adapter}.subagent-start.child-generation`,
+        attestation: "derived",
+        confidence: "high",
+        attribution: {
+          method: "native_payload",
+          state: "verified",
+          subject_instance_id: state.instance_id,
+        },
+      };
+      assertEventV3(event);
+    }
+    if (
+      input.signal === "user-prompt-submit" &&
+      input.delegated_child &&
+      event.event_type === "turn.started"
+    ) {
+      event.links = { caused_by: [input.delegated_child.caused_by_event_id] };
+      event.provenance = {
+        ...event.provenance,
+        source_event: `${input.adapter}.subagent-start.child-turn`,
+        attestation: "derived",
+        confidence: "high",
+        attribution: {
+          method: "native_payload",
+          state: "verified",
+          subject_instance_id: state.instance_id,
+        },
+      };
+      assertEventV3(event);
+    }
     if (
       input.signal === "session-start" &&
       input.session_start_derivation === "approved_lifecycle_reopen" &&
@@ -1051,7 +1184,18 @@ function processHookSignalLocked(
       commitProgressObservation(input, state, path, rootId, event, progressKind);
     }
     if (turnTelemetry) {
-      commitTurnContextObservation(input, state, path, rootId, event, turnTelemetry.context);
+      const contextTarget = turnContextTarget(event);
+      queuePendingRuntimeContext(input, state, contextTarget, turnTelemetry.context);
+      commitTurnContextObservation(
+        input,
+        state,
+        path,
+        rootId,
+        fingerprintContext,
+        contextTarget,
+        turnTelemetry.context,
+        turnTelemetry.context_provenance,
+      );
     }
     if (event.event_type === "session.ended") {
       commitCapabilityDriftEvents(input, state, path, rootId);
@@ -1501,10 +1645,13 @@ function commitTurnContextObservation(
   state: HookProducerStateV3,
   path: string,
   rootId: `root_${string}`,
-  turnTerminal: EventV3,
+  fingerprintContext: ReturnType<typeof fingerprintContextV3>,
+  target: TurnContextTargetV3 | undefined,
   measurement: TelemetryObservationV3<ContextMeasurementV3>,
+  contextProvenance?: ContextTelemetryProvenanceV3,
+  observedAt?: string,
 ): void {
-  if (turnTerminal.event_type !== "turn.completed") return;
+  if (!target) return;
   const event = buildEventV3("context.observed", {
     producer: {
       producer_id: input.producer_id,
@@ -1520,36 +1667,631 @@ function commitTurnContextObservation(
       instance_id: state.instance_id,
       session_id: state.session_id,
       generation_id: state.generation_id,
-      turn_id: (turnTerminal.scope as { turn_id: `tid_${string}` }).turn_id,
-      ...(input.run_id ? { run_id: input.run_id } : {}),
-      ...(input.workflow_id ? { workflow_id: input.workflow_id } : {}),
-      ...(input.workflow_agent_id ? { workflow_agent_id: input.workflow_agent_id } : {}),
+      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 } : {}),
     },
     attestation_id: state.attestation_id,
-    links: { caused_by: [turnTerminal.event_id] },
+    links: { caused_by: [target.terminal_event_id] },
     provenance: {
-      source_event: `${input.adapter}.turn-context`,
+      source_event: safeRole(
+        [
+          contextProvenance?.source_event ?? `${input.adapter}.turn-context`,
+          contextProvenance?.runtime_version,
+        ]
+          .filter(Boolean)
+          .join("."),
+      ),
+      attestation: contextProvenance?.attestation ?? "native",
+      confidence: contextProvenance?.confidence ?? "exact",
+      ...(contextProvenance?.source_witness
+        ? {
+            source_record_id: normalizeNativeIdV3(
+              fingerprintContext,
+              `${input.adapter}.runtime-context`,
+              contextProvenance.source_witness,
+            ),
+          }
+        : {}),
+      attribution: {
+        method: "native_payload",
+        state: "verified",
+        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,
+    monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+    clock_id: state.clock_id,
+    payload: {
+      measurement,
+    },
+  }) as EventV3;
+  commitEventLocked(input, state, path, event);
+  maybeAttestContextCapabilityChange(input, state, path, rootId, measurement, contextProvenance);
+}
+
+function maybeAttestContextCapabilityChange(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  path: string,
+  rootId: `root_${string}`,
+  measurement: TelemetryObservationV3<ContextMeasurementV3>,
+  provenance?: ContextTelemetryProvenanceV3,
+): void {
+  const context =
+    measurement.state === "observed"
+      ? {
+          state: "observed" as const,
+          source: provenance?.source_event ?? `${input.adapter}.turn_context`,
+          attestation: provenance?.attestation ?? measurement.attestation,
+          confidence: provenance?.confidence ?? measurement.confidence,
+        }
+      : measurement.state === "expected_but_missing"
+        ? { state: "partial" as const, reason: measurement.reason }
+        : { state: "unsupported" as const };
+  const telemetry = effectiveRuntimeTelemetryCapabilitiesV3({
+    adapter: input.adapter,
+    ...(state.cursor_mode ? { cursor_mode: state.cursor_mode } : {}),
+    context,
+    canonical_turn_boundaries: true,
+  });
+  if (!state.last_attested_telemetry) return;
+  if (canonicalJsonV3(telemetry) === canonicalJsonV3(state.last_attested_telemetry)) return;
+  if (!state.last_attested_model_observation || !state.last_attested_tuning_observation) return;
+
+  commitRuntimeAttestationChange(input, state, path, rootId, {
+    model: state.last_attested_model_observation,
+    tuning: state.last_attested_tuning_observation,
+    telemetry,
+    reason: "runtime_telemetry_changed",
+    source_event: provenance?.source_event ?? `${input.adapter}.turn_context`,
+    attestation: provenance?.attestation ?? "derived",
+    confidence: provenance?.confidence ?? (measurement.state === "observed" ? "exact" : "high"),
+  });
+}
+
+function turnContextTarget(turnTerminal: EventV3): TurnContextTargetV3 | undefined {
+  if (turnTerminal.event_type !== "turn.completed") return undefined;
+  const scope = turnTerminal.scope as {
+    turn_id: `tid_${string}`;
+    run_id?: `run_${string}`;
+    workflow_id?: `wf_${string}`;
+    workflow_agent_id?: string;
+  };
+  return {
+    terminal_event_id: turnTerminal.event_id as `evt_${string}`,
+    terminal_observed_at: turnTerminal.time.observed_at,
+    turn_id: scope.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 } : {}),
+  };
+}
+
+function queuePendingRuntimeContext(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  target: TurnContextTargetV3 | undefined,
+  measurement: TelemetryObservationV3<ContextMeasurementV3>,
+): void {
+  if (
+    input.adapter !== "codex" ||
+    !target ||
+    measurement.state !== "expected_but_missing" ||
+    !retryableRuntimeContextReason(measurement.reason)
+  ) {
+    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,
+    native_session_id: nativeSessionId,
+    native_turn_id: nativeTurnId,
+    ...((input.payload.transcript_path ?? state.runtime_transcript_path)
+      ? { transcript_path: input.payload.transcript_path ?? state.runtime_transcript_path }
+      : {}),
+    ...(input.adapterVersion ? { runtime_version: input.adapterVersion } : {}),
+    attempts: 0,
+  };
+  state.pending_runtime_contexts = [
+    ...(state.pending_runtime_contexts ?? []).filter(
+      (candidate) => candidate.turn_id !== target.turn_id,
+    ),
+    pending,
+  ].slice(-PENDING_RUNTIME_CONTEXT_CAP);
+}
+
+function reconcilePendingRuntimeContexts(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  path: string,
+  rootId: `root_${string}`,
+  fingerprintContext: ReturnType<typeof fingerprintContextV3>,
+  options: { deferRetryLimit?: boolean; finalAttempt?: boolean } = {},
+): void {
+  if (state.adapter !== "codex" || !state.pending_runtime_contexts?.length) return;
+  for (const pending of [...state.pending_runtime_contexts]) {
+    const runtime = readRuntimeContextTelemetry(
+      {
+        adapter: "codex",
+        session_id: pending.native_session_id,
+        turn_id: pending.native_turn_id,
+        transcript_path: pending.transcript_path,
+        mode: "turn",
+      },
+      input.runtimeTelemetryOptions,
+    );
+    if (runtime.bytes_read > 0) recordRuntimeTelemetryTiming(state, runtime.io_duration_ms);
+    const queue = state.pending_runtime_contexts;
+    if (!queue) break;
+    const index = queue.findIndex((candidate) => candidate.turn_id === pending.turn_id);
+    if (index < 0) continue;
+    if (runtime.state === "observed") {
+      queue.splice(index, 1);
+      if (queue.length === 0) {
+        state.pending_runtime_contexts = undefined;
+      }
+      commitTurnContextObservation(
+        input,
+        state,
+        path,
+        rootId,
+        fingerprintContext,
+        pending,
+        runtimeContextObservation(runtime),
+        {
+          source_event: runtime.source_event,
+          source_witness: runtime.source_witness,
+          ...(pending.runtime_version ? { runtime_version: pending.runtime_version } : {}),
+          attestation: "derived",
+          confidence: "exact",
+        },
+        signalClock(input).observed_at,
+      );
+      continue;
+    }
+    const attempts = pending.attempts + 1;
+    if (
+      options.finalAttempt ||
+      runtime.state === "unsupported" ||
+      !retryableRuntimeContextReason(runtime.reason) ||
+      (!options.deferRetryLimit && attempts >= RUNTIME_CONTEXT_RETRY_LIMIT)
+    ) {
+      queue.splice(index, 1);
+    } else {
+      queue[index] = { ...pending, attempts };
+    }
+  }
+  if (state.pending_runtime_contexts?.length === 0) {
+    state.pending_runtime_contexts = undefined;
+  }
+  publishProducerState(path, state);
+}
+
+function reconcilePendingRuntimeContextsBeforeApprovedEnd(
+  input: RecordApprovedSessionEndV3Input,
+  state: HookProducerStateV3,
+  path: string,
+  rootId: `root_${string}`,
+  fingerprintContext: ReturnType<typeof fingerprintContextV3>,
+): void {
+  if (state.adapter !== "codex" || !state.pending_runtime_contexts?.length) return;
+  for (const [index, delayMs] of APPROVED_END_RUNTIME_CONTEXT_RETRY_DELAYS_MS.entries()) {
+    if (delayMs > 0) sleepSync(delayMs);
+    reconcilePendingRuntimeContexts(
+      {
+        coordRoot: input.coordRoot,
+        mode: input.mode,
+        signal: "session-end",
+        payload: { raw: {} },
+        adapter: state.adapter,
+        instance_id: state.instance_id,
+        producer_id: "prd_agent-finalizer",
+        build_id: input.build_id,
+        platform: input.platform,
+        observed_at: new Date().toISOString(),
+        writerOptions: input.writerOptions,
+      },
+      state,
+      path,
+      rootId,
+      fingerprintContext,
+      {
+        deferRetryLimit: true,
+        finalAttempt: index === APPROVED_END_RUNTIME_CONTEXT_RETRY_DELAYS_MS.length - 1,
+      },
+    );
+    if (!state.pending_runtime_contexts?.length) return;
+  }
+}
+
+function retryableRuntimeContextReason(reason: string | undefined): boolean {
+  return (
+    reason === "codex_transcript_turn_not_found" ||
+    reason === "codex_transcript_turn_not_terminal" ||
+    reason === "codex_transcript_token_count_missing"
+  );
+}
+
+function turnTelemetryForTerminal(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  observedAt: string,
+): TurnTelemetryV3 {
+  const native = extractTurnTelemetryV3(input.adapter, input.payload.raw, observedAt);
+  if (native.context.state === "observed" || input.adapter === "cursor") return native;
+
+  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,
+  );
+  if (runtime.bytes_read > 0) recordRuntimeTelemetryTiming(state, runtime.io_duration_ms);
+  if (runtime.state === "unsupported") return native;
+  return {
+    ...native,
+    context: runtimeContextObservation(runtime),
+    context_provenance: {
+      source_event:
+        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",
+    },
+  };
+}
+
+/**
+ * Resolve Codex's rollout once, retain it in owner-only producer state, and
+ * verify the cached path against the native session before every reuse. Public
+ * events receive only numeric telemetry and an opaque source witness.
+ */
+function runtimeTranscriptPath(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+): string | undefined {
+  if (input.adapter !== "codex") return input.payload.transcript_path;
+  const nativeSessionId = input.payload.session_id ?? input.payload.conversation_id;
+  if (!nativeSessionId) return input.payload.transcript_path;
+
+  const supplied = input.payload.transcript_path;
+  if (supplied) {
+    const verified = discoverCodexSessionTranscript(
+      nativeSessionId,
+      supplied,
+      input.runtimeTelemetryOptions,
+    );
+    if (verified) state.runtime_transcript_path = verified;
+    // Preserve a supplied mismatch so the typed reader reports it honestly.
+    return verified ?? supplied;
+  }
+
+  if (state.runtime_transcript_path) {
+    const verified = discoverCodexSessionTranscript(
+      nativeSessionId,
+      state.runtime_transcript_path,
+      input.runtimeTelemetryOptions,
+    );
+    if (verified) return verified;
+    state.runtime_transcript_path = undefined;
+  }
+
+  const discovered = discoverCodexSessionTranscript(
+    nativeSessionId,
+    undefined,
+    input.runtimeTelemetryOptions,
+  );
+  if (discovered) state.runtime_transcript_path = discovered;
+  return discovered;
+}
+
+function runtimeContextObservation(
+  runtime: RuntimeContextTelemetry,
+): TelemetryObservationV3<ContextMeasurementV3> {
+  if (runtime.state === "observed") {
+    return {
+      state: "observed",
+      value: {
+        used_tokens: runtime.used_tokens,
+        limit_tokens: runtime.limit_tokens,
+        remaining_tokens: Math.max(0, runtime.limit_tokens - runtime.used_tokens),
+        measured_at: runtime.measured_at,
+        method: runtime.method,
+      },
+      attestation: "derived",
+      confidence: "exact",
+    };
+  }
+  return {
+    state: "expected_but_missing",
+    capability: "context_usage",
+    reason: runtime.reason,
+  };
+}
+
+/** Seed the change-detection baseline from a committed session.started. */
+function seedAttestedTuning(state: HookProducerStateV3, event: { payload: unknown }): void {
+  const attestation = (event.payload as { runtime_attestation?: RuntimeAttestationV3Base })
+    .runtime_attestation;
+  if (!attestation) return;
+  const tuning = attestation.tuning;
+  state.last_attested_tuning =
+    tuning?.state === "observed"
+      ? {
+          ...(tuning.value?.effort ? { effort: tuning.value.effort } : {}),
+          ...(tuning.value?.speed ? { speed: tuning.value.speed } : {}),
+        }
+      : {};
+  const model = attestation.model;
+  if (model.state === "observed") {
+    state.last_attested_model = { provider: model.value.provider, id: model.value.id };
+  }
+  state.last_attested_model_observation = model;
+  state.last_attested_tuning_observation = tuning;
+  state.last_attested_telemetry = attestation.telemetry as RuntimeTelemetryCapabilitiesV3;
+}
+
+/**
+ * Emit `session.attestation_changed` when the observed tuning moves.
+ *
+ * Detection channels are deliberately cheap: CC stamps `effort.level` on
+ * every tool hook and Stop (zero I/O), and Codex tuning is read from the
+ * rollout only at turn terminals, where the context enrichment already pays
+ * for a bounded tail read. A pre-upgrade state file (no baseline) seeds
+ * silently so existing sessions do not fire a spurious change on their next
+ * tool event; a fresh session's baseline comes from its session.started.
+ */
+function maybeAttestTuningChange(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  path: string,
+  rootId: `root_${string}`,
+): void {
+  if (
+    input.signal !== "pre-tool-use" &&
+    input.signal !== "post-tool-use" &&
+    input.signal !== "stop"
+  ) {
+    return;
+  }
+  if (state.terminal) return;
+
+  let candidate: { effort?: string; speed?: string; model?: string } | undefined;
+  let attestationSource: "native" | "derived" = "native";
+  let sourceEvent = `${input.adapter}.effort-payload`;
+  if (input.adapter === "claude-code" || input.adapter === "cursor") {
+    if (!input.payload.effort) return;
+    candidate = { effort: input.payload.effort };
+  } else if (
+    input.adapter === "codex" &&
+    (input.signal === "stop" ||
+      // Early probe: without it, a Codex card shows no effort until the first
+      // turn terminal. One rollout read per turn while effort is unknown.
+      (input.signal === "post-tool-use" &&
+        !state.last_attested_tuning?.effort &&
+        state.current_turn_id !== undefined &&
+        state.tuning_probe_turn_id !== state.current_turn_id))
+  ) {
+    if (input.signal === "post-tool-use") state.tuning_probe_turn_id = state.current_turn_id;
+    const runtime = readRuntimeTuning(
+      {
+        adapter: "codex",
+        session_id: input.payload.session_id ?? input.payload.conversation_id,
+        transcript_path: runtimeTranscriptPath(input, state),
+      },
+      input.runtimeTelemetryOptions,
+    );
+    if (runtime.bytes_read > 0) recordRuntimeTelemetryTiming(state, runtime.io_duration_ms);
+    if (runtime.state !== "observed") return;
+    candidate = {
+      ...(runtime.effort ? { effort: runtime.effort } : {}),
+      ...(runtime.speed ? { speed: runtime.speed } : {}),
+      ...(runtime.model ? { model: runtime.model } : {}),
+    };
+    attestationSource = "derived";
+    sourceEvent = runtime.source_event;
+  } else {
+    return;
+  }
+
+  const baseline = state.last_attested_tuning;
+  const next = { effort: candidate.effort, speed: candidate.speed ?? baseline?.speed };
+  if (baseline === undefined || state.last_attested_telemetry === undefined) {
+    // Pre-upgrade state: adopt without emitting; there is no attested prior.
+    state.last_attested_tuning = { ...(next.effort ? { effort: next.effort } : {}) };
+    if (next.speed) state.last_attested_tuning.speed = next.speed;
+    return;
+  }
+  if (baseline.effort === next.effort && (candidate.speed ?? baseline.speed) === baseline.speed) {
+    return;
+  }
+
+  // CC change detection rides the payload; the paired transcript row also
+  // carries speed and the (possibly swapped) model, so refresh from it.
+  if (input.adapter === "claude-code") {
+    const runtime = readRuntimeTuning({
+      adapter: "claude-code",
+      transcript_path: input.payload.transcript_path,
+    });
+    if (runtime.bytes_read > 0) recordRuntimeTelemetryTiming(state, runtime.io_duration_ms);
+    if (runtime.state === "observed" && runtime.effort === candidate.effort) {
+      if (runtime.speed) candidate.speed = runtime.speed;
+      if (runtime.model) candidate.model = runtime.model;
+    }
+  }
+
+  const model: RuntimeAttestationV3Base["model"] = candidate.model
+    ? {
+        state: "observed",
+        value: { provider: modelProviderFor(input.adapter), id: safeRole(candidate.model) },
+        attestation: "derived",
+        confidence: "high",
+      }
+    : state.last_attested_model
+      ? {
+          state: "observed",
+          value: state.last_attested_model,
+          attestation: "derived",
+          confidence: "high",
+        }
+      : { state: "expected_but_missing", capability: "model_identity", reason: "not_reported" };
+  const tuning: RuntimeAttestationV3Base["tuning"] =
+    candidate.effort || candidate.speed
+      ? {
+          state: "observed",
+          value: {
+            ...(candidate.effort ? { effort: candidate.effort } : {}),
+            ...(candidate.speed ? { speed: candidate.speed } : {}),
+          },
+          attestation: attestationSource,
+          confidence: "exact",
+        }
+      : { state: "unsupported", capability: "effort_selection" };
+  commitRuntimeAttestationChange(input, state, path, rootId, {
+    model,
+    tuning,
+    telemetry: state.last_attested_telemetry,
+    reason: "runtime_tuning_changed",
+    source_event: sourceEvent,
+    attestation: attestationSource,
+    confidence: attestationSource === "native" ? "exact" : "high",
+  });
+}
+
+interface RuntimeAttestationChangeV3 {
+  model: RuntimeAttestationV3Base["model"];
+  tuning: RuntimeAttestationV3Base["tuning"];
+  telemetry: RuntimeTelemetryCapabilitiesV3;
+  reason: string;
+  source_event: string;
+  attestation: "native" | "derived";
+  confidence: "exact" | "high";
+}
+
+function commitRuntimeAttestationChange(
+  input: RecordHookSignalV3Input,
+  state: HookProducerStateV3,
+  path: string,
+  rootId: `root_${string}`,
+  change: RuntimeAttestationChangeV3,
+): void {
+  const priorAttestationId = state.attestation_id;
+  const nextAttestationId = attestationIdV3();
+  const eventId = eventIdV3();
+  const runtimeAttestation: RuntimeAttestationV3Base = {
+    attestation_id: nextAttestationId,
+    generation_id: state.generation_id,
+    adapter: {
+      state: "observed",
+      value: {
+        id: input.adapter,
+        ...(input.adapterVersion ? { version: input.adapterVersion } : {}),
+      },
+      attestation: "native",
+      confidence: "exact",
+    },
+    harness: {
+      state: "observed",
+      value: {
+        id: input.adapter,
+        ...(input.harnessVersion ? { version: input.harnessVersion } : {}),
+      },
       attestation: "native",
       confidence: "exact",
+    },
+    model: change.model,
+    tuning: change.tuning,
+    telemetry: change.telemetry,
+    capability_profile: state.capability_profile,
+    declared_by_event_id: eventId,
+  };
+  const event = buildEventV3("session.attestation_changed", {
+    event_id: eventId,
+    producer: {
+      producer_id: input.producer_id,
+      boot_id: state.boot_id,
+      sequence: state.next_sequence,
+      component: "agent-hook",
+      build_id: input.build_id,
+      platform: input.platform,
+      ...(input.bridge ? { bridge: input.bridge } : {}),
+    },
+    scope: {
+      root_id: rootId,
+      instance_id: state.instance_id,
+      session_id: state.session_id,
+      generation_id: state.generation_id,
+      ...(input.run_id ? { run_id: input.run_id } : {}),
+      ...(input.workflow_id ? { workflow_id: input.workflow_id } : {}),
+      ...(input.workflow_agent_id ? { workflow_agent_id: input.workflow_agent_id } : {}),
+    },
+    attestation_id: nextAttestationId,
+    links: { caused_by: state.last_event_id ? [state.last_event_id] : [] },
+    provenance: {
+      source_event: safeRole(change.source_event),
+      attestation: change.attestation,
+      confidence: change.confidence,
       attribution: {
         method: "native_payload",
         state: "verified",
         subject_instance_id: state.instance_id,
       },
     },
-    observed_at:
-      measurement.state === "observed"
-        ? measurement.value.measured_at
-        : turnTerminal.time.observed_at,
+    observed_at: input.observed_at ?? new Date().toISOString(),
     monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
     clock_id: state.clock_id,
     payload: {
-      measurement,
+      prior_attestation_id: priorAttestationId,
+      runtime_attestation: runtimeAttestation,
+      reason: change.reason,
     },
   }) as EventV3;
+  // Mutate BEFORE the commit: commitEventLocked publishes the state file, so
+  // post-commit mutations would be dropped by the next signal's fresh read.
+  // A crash between publishes replays the pending event against a state that
+  // already carries the new attestation id, which is the id the event declares.
+  state.attestation_id = nextAttestationId;
+  state.last_attested_model_observation = change.model;
+  state.last_attested_tuning_observation = change.tuning;
+  state.last_attested_telemetry = change.telemetry;
+  state.last_attested_model =
+    change.model.state === "observed" ? { ...change.model.value } : undefined;
+  state.last_attested_tuning = change.tuning.state === "observed" ? { ...change.tuning.value } : {};
   commitEventLocked(input, state, path, event);
 }
 
+function modelProviderFor(adapter: Adapter): string {
+  if (adapter === "claude-code") return "anthropic";
+  if (adapter === "codex") return "openai";
+  return "cursor";
+}
+
+function recordRuntimeTelemetryTiming(state: HookProducerStateV3, durationMs: number): void {
+  const duration = Math.max(0, Math.ceil(durationMs));
+  if (!Number.isSafeInteger(duration)) return;
+  state.turn_harness = {
+    hook_time_ms: state.turn_harness.hook_time_ms + duration,
+    hook_count: state.turn_harness.hook_count + 1,
+    slowest_hook:
+      duration >= state.turn_harness.slowest_hook_ms
+        ? "runtime-context"
+        : state.turn_harness.slowest_hook,
+    slowest_hook_ms: Math.max(duration, state.turn_harness.slowest_hook_ms),
+  };
+}
+
 function commitCapabilityDriftEvents(
   input: RecordHookSignalV3Input,
   state: HookProducerStateV3,
@@ -1854,6 +2596,7 @@ export function recordApprovedSessionEndV3(
       state.generation_id,
       state.privacy_epoch_id,
     );
+    reconcilePendingRuntimeContextsBeforeApprovedEnd(input, state, record.path, rootId, context);
     const expected = [
       "session_started",
       "turn_closed",
@@ -2181,6 +2924,26 @@ export function readHookProducerStateByInstanceV3(
   return matches.length === 1 ? matches[0] : undefined;
 }
 
+/**
+ * Join a coordination actor to its hook producer.
+ *
+ * Native subagent commands can retain the parent's session id even after the
+ * child has its own canonical generation. Prefer the native session join, but
+ * when that points at a different instance accept only one exact live
+ * instance match for the same adapter.
+ */
+export function readJoinableHookProducerStateV3(
+  coordRoot: string,
+  adapter: Adapter,
+  nativeSessionId: string,
+  instanceId: `inst_${string}`,
+): HookProducerStateV3 | undefined {
+  const direct = readHookProducerStateV3(coordRoot, adapter, nativeSessionId);
+  if (direct?.instance_id === instanceId && !direct.terminal) return direct;
+  const byInstance = readHookProducerStateByInstanceV3(coordRoot, instanceId);
+  return byInstance?.adapter === adapter && !byInstance.terminal ? byInstance : undefined;
+}
+
 function newProducerState(
   input: RecordHookSignalV3Input,
   sessionId: `sid_${string}`,
@@ -2194,7 +2957,7 @@ function newProducerState(
     adapter: input.adapter,
     instance_id: input.instance_id,
     session_id: sessionId,
-    generation_id: generationIdV3(),
+    generation_id: input.delegated_child?.generation_id ?? generationIdV3(),
     attestation_id: attestationIdV3(),
     capability_profile: adapterCapabilityProfileDigestV3(input.adapter),
     cursor_mode: input.adapter === "cursor" ? (input.payload.cursor_mode ?? "unknown") : undefined,
@@ -2234,6 +2997,7 @@ function applyCommittedEvent(state: HookProducerStateV3, event: EventV3): void {
   if (event.event_type === "session.started") {
     state.started_event_id = event.event_id as `evt_${string}`;
     state.session_span.open_event_id = event.event_id as `evt_${string}`;
+    seedAttestedTuning(state, event);
   }
   if (event.event_type === "turn.started") {
     const nextTurnId = (event.scope as { turn_id: `tid_${string}` }).turn_id;
@@ -2321,6 +3085,7 @@ function applyCommittedEvent(state: HookProducerStateV3, event: EventV3): void {
       }
     }
     state.current_turn_id = undefined;
+    state.current_native_turn_id = undefined;
     state.current_turn_span = undefined;
     state.tool_call_count = 0;
     state.tool_call_count_turn_id = undefined;
@@ -2511,6 +3276,14 @@ function safeRole(value: unknown): string {
   return /^[a-zA-Z0-9]/.test(normalized) ? normalized : "agent";
 }
 
+function asLiveInstanceId(nativeInstanceId: string): `inst_${string}` {
+  if (/^inst_[a-zA-Z0-9._-]{1,128}$/.test(nativeInstanceId)) {
+    return nativeInstanceId as `inst_${string}`;
+  }
+  if (/^[a-zA-Z0-9._-]{1,128}$/.test(nativeInstanceId)) return `inst_${nativeInstanceId}`;
+  return `inst_${createHash("sha256").update(nativeInstanceId.normalize("NFC")).digest("hex")}`;
+}
+
 function safeTokenOrUndefined(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const normalized = value.normalize("NFC");
@@ -2597,6 +3370,12 @@ function readProducerState(path: string): HookProducerStateV3 {
   state.waits ??= [];
   state.closed_turn_ids ??= [];
   state.turn_harness ??= emptyTurnHarnessTiming();
+  if (
+    Array.isArray(state.pending_runtime_contexts) &&
+    state.pending_runtime_contexts.length === 0
+  ) {
+    state.pending_runtime_contexts = undefined;
+  }
   if (state.adapter === "cursor") state.cursor_mode ??= "unknown";
   const allowedKeys = new Set([
     "adapter",
@@ -2607,6 +3386,7 @@ function readProducerState(path: string): HookProducerStateV3 {
     "closed_spans",
     "closed_turn_ids",
     "current_turn_id",
+    "current_native_turn_id",
     "current_turn_span",
     "cursor_mode",
     "delegations",
@@ -2614,11 +3394,19 @@ function readProducerState(path: string): HookProducerStateV3 {
     "format_version",
     "generation_id",
     "instance_id",
+    "last_attested_model",
+    "last_attested_model_observation",
+    "last_attested_telemetry",
+    "last_attested_tuning",
+    "last_attested_tuning_observation",
+    "tuning_probe_turn_id",
     "last_event_id",
     "last_monotonic_ns",
     "last_observed_at",
     "next_sequence",
     "pending",
+    "pending_runtime_contexts",
+    "runtime_transcript_path",
     "privacy_epoch_id",
     "session_id",
     "session_span",
@@ -2710,11 +3498,25 @@ function readProducerState(path: string): HookProducerStateV3 {
     !Number.isSafeInteger(state.turn_ordinal) ||
     state.turn_ordinal < 0 ||
     (state.current_turn_id !== undefined && !/^tid_[a-f0-9]{64}$/.test(state.current_turn_id)) ||
+    (state.current_native_turn_id !== undefined &&
+      (typeof state.current_native_turn_id !== "string" ||
+        state.current_native_turn_id.length === 0 ||
+        state.current_native_turn_id.length > 512)) ||
     (state.last_event_id !== undefined && !/^evt_[0-9a-f-]{36}$/.test(state.last_event_id)) ||
     (state.last_monotonic_ns !== undefined && !/^\d+$/.test(state.last_monotonic_ns)) ||
     (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.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.runtime_transcript_path !== undefined &&
+      (typeof state.runtime_transcript_path !== "string" ||
+        state.runtime_transcript_path.length === 0 ||
+        state.runtime_transcript_path.length > 4096 ||
+        state.runtime_transcript_path.includes("\0"))) ||
     (state.pending?.source_id !== undefined &&
       !/^hid_[a-f0-9]{64}$/.test(state.pending.source_id)) ||
     (state.pending && !validateEventV3(state.pending.event).ok)
@@ -2794,6 +3596,39 @@ function validTurnHarnessTiming(value: TurnHarnessTimingV3): boolean {
   );
 }
 
+function validPendingRuntimeContext(value: unknown): value is PendingRuntimeContextV3 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const pending = value as PendingRuntimeContextV3;
+  return (
+    typeof pending.terminal_event_id === "string" &&
+    /^evt_[0-9a-f-]{36}$/.test(pending.terminal_event_id) &&
+    typeof pending.terminal_observed_at === "string" &&
+    Number.isFinite(Date.parse(pending.terminal_observed_at)) &&
+    typeof pending.turn_id === "string" &&
+    /^tid_[a-f0-9]{64}$/.test(pending.turn_id) &&
+    (pending.run_id === undefined || /^run_[0-9a-f-]{36}$/.test(pending.run_id)) &&
+    (pending.workflow_id === undefined || /^wf_[0-9a-f-]{36}$/.test(pending.workflow_id)) &&
+    (pending.workflow_agent_id === undefined ||
+      /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(pending.workflow_agent_id)) &&
+    typeof pending.native_session_id === "string" &&
+    pending.native_session_id.length > 0 &&
+    pending.native_session_id.length <= 512 &&
+    typeof pending.native_turn_id === "string" &&
+    pending.native_turn_id.length > 0 &&
+    pending.native_turn_id.length <= 512 &&
+    (pending.transcript_path === undefined ||
+      (typeof pending.transcript_path === "string" &&
+        pending.transcript_path.length > 0 &&
+        pending.transcript_path.length <= 4096)) &&
+    (pending.runtime_version === undefined ||
+      (typeof pending.runtime_version === "string" &&
+        /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(pending.runtime_version))) &&
+    Number.isSafeInteger(pending.attempts) &&
+    pending.attempts >= 0 &&
+    pending.attempts < RUNTIME_CONTEXT_RETRY_LIMIT
+  );
+}
+
 function pidIsAlive(pid: number): boolean {
   if (!Number.isSafeInteger(pid) || pid < 1) return false;
   try {