harnery 0.34.1 → 0.35.0

package/src/core/events/v3/base-contract.ts

@@ -100,6 +100,24 @@ export function ObservationV3BaseSchema<T extends TSchema>(value: T) {
   ]);
 }
 
+const RuntimeTelemetryCapabilityValueV3BaseSchema = StrictObject({
+  support: Type.Union([
+    Type.Literal("native"),
+    Type.Literal("derived"),
+    Type.Literal("conditional"),
+  ]),
+  source: SafeToken,
+  completeness: Type.Union([
+    Type.Literal("exact"),
+    Type.Literal("lower_bound"),
+    Type.Literal("unknown"),
+  ]),
+});
+
+const RuntimeTelemetryCapabilityObservationV3BaseSchema = ObservationV3BaseSchema(
+  RuntimeTelemetryCapabilityValueV3BaseSchema,
+);
+
 export const RuntimeAttestationV3BaseSchema = StrictObject({
   attestation_id: AttestationId,
   generation_id: GenerationId,
@@ -110,6 +128,27 @@ export const RuntimeAttestationV3BaseSchema = StrictObject({
     StrictObject({ id: SafeToken, version: Type.Optional(SafeToken) }),
   ),
   model: ObservationV3BaseSchema(StrictObject({ provider: SafeToken, id: SafeToken })),
+  /** Runtime tuning identity: the effort dial (and speed tier where the
+   * runtime reports one). `observed` with a missing `effort` never occurs —
+   * a runtime that proved the model has no dial attests `unsupported` with
+   * capability `effort_selection` instead. Values pass through verbatim
+   * (`low`…`max`, `standard`/`fast`); display labels are a renderer concern. */
+  tuning: ObservationV3BaseSchema(
+    StrictObject({
+      effort: Type.Optional(SafeToken),
+      speed: Type.Optional(SafeToken),
+    }),
+  ),
+  /** Effective telemetry support proven for this runtime session. This is
+   * intentionally separate from the static capability profile digest: a
+   * missing or late local source changes evidence, not the gated profile. */
+  telemetry: StrictObject({
+    context_usage: RuntimeTelemetryCapabilityObservationV3BaseSchema,
+    wait_spans: RuntimeTelemetryCapabilityObservationV3BaseSchema,
+    wait_completeness: RuntimeTelemetryCapabilityObservationV3BaseSchema,
+    response_latency: RuntimeTelemetryCapabilityObservationV3BaseSchema,
+    inference_timing: RuntimeTelemetryCapabilityObservationV3BaseSchema,
+  }),
   capability_profile: Type.String({ pattern: "^cap_[a-f0-9]{64}$" }),
   declared_by_event_id: EventId,
 });

package/src/core/events/v3/capabilities.ts

@@ -14,6 +14,21 @@ export type AdapterWaitKindV3 =
   | "rate_limit"
   | "unknown";
 
+export const ADAPTER_WAIT_KINDS_V3: readonly AdapterWaitKindV3[] = [
+  "permission",
+  "needs_input",
+  "decision",
+  "approval",
+  "scheduled",
+  "rate_limit",
+  "unknown",
+] as const;
+
+export interface WaitKindCapabilityV3 {
+  span_delivery: CapabilitySupportV3;
+  turn_completeness: CapabilitySupportV3;
+}
+
 export type BaseAdapterSignalV3 =
   | "session_start"
   | "session_end"
@@ -159,6 +174,25 @@ export function adapterTurnWaitCountSupportV3(_adapter: Adapter): CapabilitySupp
   return "unsupported";
 }
 
+/**
+ * Per-kind wait matrix for native adapter turns. Span delivery and independent
+ * completed-turn completeness are deliberately separate: observing a span
+ * never proves that an absent span means zero.
+ */
+export function adapterWaitCoverageMatrixV3(
+  adapter: Adapter,
+): Record<AdapterWaitKindV3, WaitKindCapabilityV3> {
+  return Object.fromEntries(
+    ADAPTER_WAIT_KINDS_V3.map((kind) => [
+      kind,
+      {
+        span_delivery: adapterWaitKindSupportV3(adapter, kind),
+        turn_completeness: adapterTurnWaitCountSupportV3(adapter),
+      },
+    ]),
+  ) as Record<AdapterWaitKindV3, WaitKindCapabilityV3>;
+}
+
 /**
  * Local Cursor sessions expose the generic tool channel. Cloud/private-worker
  * sessions cannot guarantee whole-turn delivery because hooks may start only

package/src/core/events/v3/generated.ts

@@ -1,6 +1,6 @@
 /** Generated by scripts/generate-event-v3-contract.ts. Do not edit. */
 export const EVENT_V3_SCHEMA_DIGEST =
-  "sha256:682272a35f16177217a272e119c4dea2bf1980a522a183fefd6dceaf1e4509b8" as const;
+  "sha256:297ed06021fd046c6f1a2061de4341c7765840bf4f0d9b597ad7c9d78b7a9ba6" as const;
 export const EVENT_V3_GENERATED_CORE_TYPES = [
   "ledger.genesis",
   "ledger.activated",

package/src/core/events/v3/index.ts

@@ -34,12 +34,18 @@ export {
 } from "./canonical.ts";
 export {
   ADAPTER_CAPABILITY_PROFILES_V3,
+  ADAPTER_WAIT_KINDS_V3,
   type AdapterCapabilityProfileV3,
   type AdapterSignalV3,
+  type AdapterWaitKindV3,
   adapterCapabilityProfileDigestV3,
   adapterCapabilityProfileV3,
   adapterSignalSupportV3,
+  adapterWaitCoverageMatrixV3,
+  adapterWaitKindSupportV3,
   type CapabilitySupportV3,
+  type CursorExecutionModeV3,
+  type WaitKindCapabilityV3,
 } from "./capabilities.ts";
 export {
   type CapabilityDeliveryV3,
@@ -153,8 +159,12 @@ export {
   type LatencyProjectionDiagnosticV3,
   type LatencyProjectionV3,
   projectLatencyV3,
+  type ResponseLatencyV3,
+  runtimeTelemetryEvidenceKeyV3,
   type ToolLatencyV3,
   type TurnLatencyV3,
+  type WaitKindCompletenessV3,
+  type WaitKindCoverageV3,
 } from "./latency.ts";
 export {
   EVENT_V3_LIVE_RELATIVE_ROOT,
@@ -245,6 +255,7 @@ export {
 } from "./projection.ts";
 export {
   digestEventV3AuthorityDirectoryV3,
+  eventV3ActiveWatchPath,
   inspectInvalidActiveAuthorityV3,
   type LedgerCursorV3,
   type LedgerDiagnosticCodeV3,
@@ -277,6 +288,16 @@ export {
   validateEventV3RecoveryIntent,
   validateEventV3RecoveryReceipt,
 } from "./recovery-record.ts";
+export {
+  effectiveRuntimeTelemetryCapabilitiesV3,
+  type RuntimeContextCapabilityEvidenceV3,
+  type RuntimeTelemetryCapabilitiesV3,
+  type RuntimeTelemetryCapabilityEvidenceV3,
+  type RuntimeTelemetryCapabilityObservationV3,
+  type RuntimeTelemetryCapabilityValueV3,
+  type RuntimeTelemetryChannelV3,
+  type RuntimeTelemetryCompletenessV3,
+} from "./runtime-telemetry-capabilities.ts";
 export {
   type CloseSpanV3Input,
   captureSpanClockV3,

package/src/core/events/v3/latency.ts

@@ -1,6 +1,9 @@
+import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
+import { ADAPTER_WAIT_KINDS_V3, type AdapterWaitKindV3 } from "./capabilities.ts";
 import type { ReadLedgerV3Result } from "./reader.ts";
+import type { RuntimeTelemetryCapabilitiesV3 } from "./runtime-telemetry-capabilities.ts";
 
-export const EVENT_V3_LATENCY_PROJECTION_VERSION = "event-v3-latency-v1" as const;
+export const EVENT_V3_LATENCY_PROJECTION_VERSION = "event-v3-latency-v3" as const;
 
 export type LatencyMetricV3 =
   | { state: "observed"; value_ms: number }
@@ -25,6 +28,30 @@ export interface ContextCoverageV3 {
   reason: string | null;
 }
 
+export interface ResponseLatencyV3 {
+  /** Turn start to first tool request, or terminal response for an attested no-tool turn. */
+  agent_action_ms: LatencyMetricV3;
+  /** Turn start to first tool request; unknown with `no_tool_request` for no-tool turns. */
+  first_tool_request_ms: LatencyMetricV3;
+  /** Last complete tool terminal to the turn terminal. */
+  post_tool_response_ms: LatencyMetricV3;
+  /** Turn start to terminal response, only when an attested turn used no tools. */
+  no_tool_terminal_response_ms: LatencyMetricV3;
+  method: "canonical_event_timestamps_v1";
+}
+
+export type WaitKindCompletenessV3 = "complete" | "lower_bound" | "unknown" | "unsupported";
+
+export interface WaitKindCoverageV3 {
+  kind: AdapterWaitKindV3;
+  started_count: number;
+  ended_count: number;
+  open_count: number;
+  duration_ms: LatencyMetricV3;
+  completeness: WaitKindCompletenessV3;
+  reason: string | null;
+}
+
 export interface TurnLatencyV3 {
   generation_id: string;
   turn_id: string;
@@ -39,6 +66,7 @@ export interface TurnLatencyV3 {
   wait_ms: LatencyMetricV3;
   occupied_ms: LatencyMetricV3;
   inference_ms: LatencyMetricV3;
+  response_latency: ResponseLatencyV3;
   harness_ms: LatencyMetricV3;
   slowest_hook: string | null;
   slowest_hook_ms: number | null;
@@ -46,6 +74,10 @@ export interface TurnLatencyV3 {
   over_attributed_ms: number;
   context_percent: number | null;
   context_coverage: ContextCoverageV3;
+  telemetry_capabilities: RuntimeTelemetryCapabilitiesV3 | null;
+  /** Equal keys are required before a report compares telemetry-backed values. */
+  telemetry_evidence_key: `sha256:${string}` | null;
+  wait_coverage_by_kind: Record<AdapterWaitKindV3, WaitKindCoverageV3>;
   span_counts: { tool: number; command: number; wait: number };
   tool_breakdown: ToolLatencyV3[];
 }
@@ -72,6 +104,7 @@ interface EventShape {
   event_id: string;
   event_type: string;
   scope: { generation_id?: string; turn_id?: string };
+  time: { observed_at?: string };
   payload: Record<string, unknown>;
 }
 
@@ -92,6 +125,7 @@ export function projectLatencyV3(read: ReadLedgerV3Result): LatencyProjectionV3
   const events = read.events.map(({ event }) => event as unknown as EventShape);
   const diagnostics: LatencyProjectionDiagnosticV3[] = [];
   const terminalByTurn = new Map<string, EventShape>();
+  const telemetryByGeneration = latestTelemetryByGeneration(events);
 
   for (const event of events) {
     if (event.event_type !== "turn.completed") continue;
@@ -104,7 +138,12 @@ export function projectLatencyV3(read: ReadLedgerV3Result): LatencyProjectionV3
   const turns = [...terminalByTurn.values()].map((terminal) => {
     const key = turnKey(terminal);
     const turnEvents = events.filter((event) => turnKey(event) === key);
-    return projectTurn(terminal, turnEvents, diagnostics);
+    return projectTurn(
+      terminal,
+      turnEvents,
+      diagnostics,
+      telemetryByGeneration.get(terminal.scope.generation_id ?? "") ?? null,
+    );
   });
   turns.sort(
     (left, right) =>
@@ -118,6 +157,7 @@ function projectTurn(
   terminal: EventShape,
   events: EventShape[],
   diagnostics: LatencyProjectionDiagnosticV3[],
+  telemetryCapabilities: RuntimeTelemetryCapabilitiesV3 | null,
 ): TurnLatencyV3 {
   const span = record(terminal.payload.span);
   const wall = metricFromObservation(span.duration_ms, "turn_duration_unknown");
@@ -157,6 +197,10 @@ function projectTurn(
   ) {
     waits.reasons.push("wait_terminal_count_mismatch");
   }
+  const waitCoverageComplete =
+    expectedWaitCount !== undefined &&
+    expectedWaitCount === endedWaitIds.size &&
+    !waitStartEvents.some(({ payload }) => !endedWaitIds.has(string(record(payload).wait_id)));
 
   const tool = metricFromIntervals(tools);
   const command = metricFromIntervals(commands);
@@ -176,6 +220,7 @@ function projectTurn(
     "api_time_ms",
     "inference_timing_unknown",
   );
+  const responseLatency = projectResponseLatency(terminal, events, wall, tools, expectedToolCount);
   const harness = metricFromNestedObservation(
     terminal.payload.harness,
     "hook_time_ms",
@@ -217,6 +262,7 @@ function projectTurn(
     wait_ms: wait,
     occupied_ms: occupied,
     inference_ms: inference,
+    response_latency: responseLatency,
     harness_ms: harness,
     slowest_hook: slowestHook.name,
     slowest_hook_ms: slowestHook.duration_ms,
@@ -224,6 +270,18 @@ function projectTurn(
     over_attributed_ms: overAttributed,
     context_percent: context.percent,
     context_coverage: context.coverage,
+    telemetry_capabilities: telemetryCapabilities,
+    telemetry_evidence_key: telemetryCapabilities
+      ? runtimeTelemetryEvidenceKeyV3(telemetryCapabilities)
+      : null,
+    wait_coverage_by_kind: projectWaitCoverageByKind(
+      waitStartEvents,
+      waitEvents,
+      wallInterval,
+      waitCoverageComplete,
+      waitCount,
+      diagnostics,
+    ),
     span_counts: {
       tool: toolEvents.length,
       command: commandEvents.length,
@@ -233,6 +291,159 @@ function projectTurn(
   };
 }
 
+/** Reports may compare a telemetry-backed channel only inside one evidence key. */
+export function runtimeTelemetryEvidenceKeyV3(
+  telemetry: RuntimeTelemetryCapabilitiesV3,
+): `sha256:${string}` {
+  return sha256V3(canonicalJsonV3(telemetry));
+}
+
+function latestTelemetryByGeneration(
+  events: EventShape[],
+): Map<string, RuntimeTelemetryCapabilitiesV3> {
+  const result = new Map<string, RuntimeTelemetryCapabilitiesV3>();
+  for (const event of events) {
+    if (
+      event.event_type !== "session.started" &&
+      event.event_type !== "session.attestation_changed"
+    ) {
+      continue;
+    }
+    const attestation = record(event.payload.runtime_attestation);
+    const telemetry = record(attestation.telemetry);
+    if (Object.keys(telemetry).length === 0) continue;
+    result.set(event.scope.generation_id ?? "", telemetry as RuntimeTelemetryCapabilitiesV3);
+  }
+  return result;
+}
+
+function projectResponseLatency(
+  terminal: EventShape,
+  events: EventShape[],
+  wall: LatencyMetricV3,
+  tools: IntervalSet,
+  expectedToolCount: number | undefined,
+): ResponseLatencyV3 {
+  const turnStart = Date.parse(string(record(terminal.payload.span).opened_at));
+  const turnEnd =
+    Number.isFinite(turnStart) && wall.state === "observed" ? turnStart + wall.value_ms : undefined;
+  const requests = events
+    .filter(({ event_type }) => event_type === "tool.requested")
+    .map(({ time }) => Date.parse(string(time.observed_at)))
+    .filter(Number.isFinite)
+    .sort((left, right) => left - right);
+  const firstRequest = requests[0];
+  const firstTool =
+    Number.isFinite(turnStart) && firstRequest !== undefined
+      ? observedLatency(firstRequest - turnStart)
+      : unknownLatency(expectedToolCount === 0 ? "no_tool_request" : "tool_request_unobserved");
+  const noToolTerminal =
+    expectedToolCount === 0
+      ? wall
+      : unknownLatency(
+          expectedToolCount === undefined ? "tool_channel_unattested" : "turn_contains_tools",
+        );
+  const agentAction =
+    firstRequest !== undefined
+      ? firstTool
+      : expectedToolCount === 0
+        ? noToolTerminal
+        : unknownLatency(
+            expectedToolCount === undefined ? "tool_channel_unattested" : "tool_request_unobserved",
+          );
+
+  let postTool = unknownLatency(
+    expectedToolCount === 0
+      ? "no_tool_completion"
+      : expectedToolCount === undefined
+        ? "tool_channel_unattested"
+        : "final_tool_completion_unknown",
+  );
+  if (
+    turnEnd !== undefined &&
+    expectedToolCount !== undefined &&
+    expectedToolCount > 0 &&
+    tools.reasons.length === 0 &&
+    tools.intervals.length === expectedToolCount
+  ) {
+    postTool = observedLatency(turnEnd - Math.max(...tools.intervals.map(({ end }) => end)));
+  }
+
+  return {
+    agent_action_ms: agentAction,
+    first_tool_request_ms: firstTool,
+    post_tool_response_ms: postTool,
+    no_tool_terminal_response_ms: noToolTerminal,
+    method: "canonical_event_timestamps_v1",
+  };
+}
+
+function projectWaitCoverageByKind(
+  starts: EventShape[],
+  ends: EventShape[],
+  wall: Interval | undefined,
+  complete: boolean,
+  waitCount: Record<string, unknown>,
+  diagnostics: LatencyProjectionDiagnosticV3[],
+): Record<AdapterWaitKindV3, WaitKindCoverageV3> {
+  const endedIds = new Set(ends.map(({ payload }) => string(record(payload).wait_id)));
+  const unsupported = waitCount.state === "unsupported";
+  return Object.fromEntries(
+    ADAPTER_WAIT_KINDS_V3.map((kind) => {
+      const kindStarts = starts.filter(({ payload }) => waitKind(payload) === kind);
+      const kindEnds = ends.filter(({ payload }) => waitKind(payload) === kind);
+      const openCount = kindStarts.filter(
+        ({ payload }) => !endedIds.has(string(record(payload).wait_id)),
+      ).length;
+      const set = intervalSet(kindEnds, wall, diagnostics);
+      if (!complete) set.reasons.push("wait_kind_completeness_unattested");
+      const completeness: WaitKindCompletenessV3 = complete
+        ? "complete"
+        : unsupported
+          ? kindStarts.length > 0 || kindEnds.length > 0
+            ? "lower_bound"
+            : "unsupported"
+          : kindStarts.length > 0 || kindEnds.length > 0
+            ? "lower_bound"
+            : "unknown";
+      const reason = complete
+        ? null
+        : unsupported
+          ? "turn_wait_count_unsupported"
+          : "turn_wait_count_unattested";
+      return [
+        kind,
+        {
+          kind,
+          started_count: kindStarts.length,
+          ended_count: kindEnds.length,
+          open_count: openCount,
+          duration_ms: metricFromIntervals(set),
+          completeness,
+          reason,
+        },
+      ];
+    }),
+  ) as Record<AdapterWaitKindV3, WaitKindCoverageV3>;
+}
+
+function waitKind(payload: Record<string, unknown>): AdapterWaitKindV3 {
+  const value = string(record(payload).kind);
+  return ADAPTER_WAIT_KINDS_V3.includes(value as AdapterWaitKindV3)
+    ? (value as AdapterWaitKindV3)
+    : "unknown";
+}
+
+function observedLatency(value: number): LatencyMetricV3 {
+  return Number.isFinite(value) && value >= 0
+    ? { state: "observed", value_ms: Math.floor(value) }
+    : unknownLatency("event_time_order_invalid");
+}
+
+function unknownLatency(reason: string): LatencyMetricV3 {
+  return { state: "unknown", known_ms: 0, reasons: [reason] };
+}
+
 function groupByTool(events: EventShape[]): Map<string, EventShape[]> {
   const groups = new Map<string, EventShape[]>();
   for (const event of events) {

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import type { Adapter } from "../../adapter.ts";
 import type { ParsedPayload } from "../../hooks/adapter/parse.ts";
+import type { EventV3 } from "./contract.ts";
 import {
   type EventV3WriteMode,
   readEventV3ControlState,
@@ -84,6 +85,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 +119,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,6 +158,94 @@ export function recordLiveHookSignalV3(input: {
   });
 }
 
+/**
+ * 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;
+}
+
 export function livePlatformV3(): "linux" | "windows" | "macos" | "unknown" {
   if (process.platform === "linux") return "linux";
   if (process.platform === "win32") return "windows";

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
   );
 }