harnery 0.33.0 → 0.34.1

package/dist/core/events/v3/producers/recorder.js

@@ -0,0 +1,2176 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { extractBashCommand } from "../../../hooks/adapter/parse.js";
+import { fsyncParentDirectory } from "../../../workflow/durable-record.js";
+import { acquireNoClobberLease } from "../../../workflow/workspaces/leases.js";
+import { buildEventV3 } from "../builder.js";
+import { fingerprintV3, normalizeNativeIdV3 } from "../canonical.js";
+import { adapterCapabilityProfileDigestV3, adapterSignalSupportV3, cursorToolChannelSupportV3, } from "../capabilities.js";
+import { capabilityDriftPayloadsV3 } from "../capability-drift.js";
+import { markObservedClockRegressionV3 } from "../clock-order.js";
+import { readEventV3ControlState } from "../control.js";
+import { fingerprintContextV3 } from "../fingerprint-keys.js";
+import { attestationIdV3, clockIdV3, delegationIdV3, generationIdV3, spanIdV3 } from "../ids.js";
+import { readLedgerV3 } from "../reader.js";
+import { closeSpanStateV3, openSpanStateV3, recoverSpanUpperBoundV3, } from "../span-state.js";
+import { extractTurnTelemetryV3, } from "../turn-telemetry.js";
+import { assertEventV3, validateEventV3 } from "../validate.js";
+import { EVENT_V3_LEDGER_RELATIVE_ROOT, writeEventV3, } from "../writer.js";
+import { normalizeHookEventV3 } from "./hook.js";
+import { appendHookIntakeRecordV3, hookIntakeGroupDirV3, listHookIntakeGroupsV3, listHookIntakeRecordsV3, removeIntakeRecordV3, writeProducerDiagnosticV3, } from "./intake.js";
+const STATE_FORMAT = "harnery-v3-hook-producer";
+const STATE_VERSION = 3;
+/** ADR 0078 recovery policy constants. */
+const CLOSED_SPAN_TURN_RETENTION = 2;
+const CLOSED_SPAN_MEMORY_CAP = 512;
+const CLOSED_TURN_MEMORY_CAP = 16;
+const SPAN_SOFT_WATERMARK = 128;
+/**
+ * Adapters whose turn-boundary recovery and mid-flight onboarding are enabled.
+ * Kept in code, outside the digested capability profiles, so tuning recovery
+ * never changes an adapter capability digest (ADR 0078).
+ */
+const RECOVERY_ENABLED_ADAPTERS = new Set(["claude-code", "codex", "cursor"]);
+const STATE_LEASE_RETRY_ATTEMPTS = 8;
+const STATE_LEASE_RETRY_DELAY_MS = 25;
+/**
+ * Record one hook signal through a private, crash-recoverable producer state file.
+ * The function is inert unless the exact requested candidate or active gate is open.
+ *
+ * Delivery guarantee: the parsed signal is appended to a durable intake spool
+ * BEFORE any producer state is read or validated, so a lost lease, a crash, or
+ * a state-format mismatch never destroys a delivered signal. Whichever process
+ * holds the session's state lease drains the spool in append order and rescans
+ * until an empty pass; reconcile and session-start hooks drain any group whose
+ * final appender never got the lease.
+ */
+export function recordHookSignalV3(input) {
+    const control = readEventV3ControlState(input.coordRoot);
+    if (control.state !== input.mode) {
+        return { state: "gate_closed", reason: control.state };
+    }
+    const gate = hookSignalGate(control, input.adapter, input.signal);
+    if (gate)
+        return gate;
+    const rootId = control.genesis.event.scope.root_id;
+    const epochId = control.genesis.profile.privacy_key_epoch;
+    const rootFingerprintContext = fingerprintContextV3(input.coordRoot, rootId, undefined, epochId);
+    const sessionHash = sessionHashForSignal(input, rootFingerprintContext);
+    const path = producerStatePath(input.coordRoot, input.adapter, sessionHash);
+    const spoolPath = appendHookIntakeRecordV3(input.coordRoot, sessionHash, intakeRecord(input));
+    const lease = acquireStateLeaseWithRetry(input.coordRoot, path, STATE_LEASE_RETRY_ATTEMPTS);
+    if (!lease)
+        return { state: "spooled" };
+    try {
+        return (drainSessionIntakeLocked(input.coordRoot, control, input.adapter, sessionHash, path, {
+            path: spoolPath,
+            input,
+        }) ?? { state: "spooled" });
+    }
+    finally {
+        lease.release();
+    }
+}
+function hookSignalGate(control, adapter, signal) {
+    const expectedCapabilityDigest = `sha256:${adapterCapabilityProfileDigestV3(adapter).slice(4)}`;
+    if (!control.genesis.profile.adapter_capability_profile_digests.includes(expectedCapabilityDigest)) {
+        return { state: "gate_closed", reason: "capability_profile_not_approved" };
+    }
+    const requiredCapability = hookSignalCapability(signal);
+    if (adapterSignalSupportV3(adapter, requiredCapability) === "unsupported") {
+        return {
+            state: "gate_closed",
+            reason: `signal_not_approved:${requiredCapability}`,
+        };
+    }
+    return undefined;
+}
+function sessionHashForSignal(input, context) {
+    const nativeSession = input.payload.session_id ?? input.payload.conversation_id ?? input.payload.agent_id;
+    if (nativeSession !== undefined) {
+        return normalizeNativeIdV3(context, `${input.adapter}.session`, nativeSession);
+    }
+    // Cursor carries native session identity only on its start signal. Later
+    // hooks may still have an exact coordination instance, so reuse its single
+    // live producer authority instead of hashing the instance into a second
+    // state path. Ambiguous or absent matches keep the fail-closed fallback.
+    if (input.adapter === "cursor") {
+        const matches = listHookProducerStateRecordsV3(input.coordRoot).filter(({ state }) => state.adapter === input.adapter && state.instance_id === input.instance_id);
+        if (matches.length === 1) {
+            const name = basename(matches[0].path);
+            if (/^hid_[a-f0-9]{64}\.json$/.test(name)) {
+                return name.slice(0, -".json".length);
+            }
+        }
+    }
+    return normalizeNativeIdV3(context, `${input.adapter}.session`, input.instance_id);
+}
+function intakeRecord(input) {
+    return {
+        format: "harnery-v3-hook-intake",
+        format_version: 1,
+        mode: input.mode,
+        signal: input.signal,
+        payload: input.payload,
+        adapter: input.adapter,
+        instance_id: input.instance_id,
+        producer_id: input.producer_id,
+        build_id: input.build_id,
+        platform: input.platform,
+        ...(input.bridge ? { bridge: input.bridge } : {}),
+        ...(input.adapterVersion ? { adapterVersion: input.adapterVersion } : {}),
+        ...(input.harnessVersion ? { harnessVersion: input.harnessVersion } : {}),
+        ...(input.monotonic_ns ? { monotonic_ns: input.monotonic_ns } : {}),
+        ...(input.observed_at ? { observed_at: input.observed_at } : {}),
+        ...(input.hook_name ? { hook_name: safeRole(input.hook_name) } : {}),
+        ...(input.hook_duration_ms !== undefined
+            ? { hook_duration_ms: Math.max(0, Math.floor(input.hook_duration_ms)) }
+            : {}),
+        ...(input.stop_remediation !== undefined ? { stop_remediation: input.stop_remediation } : {}),
+        ...(input.turn_ritual ? { turn_ritual: input.turn_ritual } : {}),
+    };
+}
+function inputForIntakeRecord(coordRoot, record) {
+    return {
+        coordRoot,
+        mode: record.mode,
+        signal: record.signal,
+        payload: record.payload,
+        adapter: record.adapter,
+        instance_id: record.instance_id,
+        producer_id: record.producer_id,
+        build_id: record.build_id,
+        platform: record.platform,
+        ...(record.bridge ? { bridge: record.bridge } : {}),
+        ...(record.adapterVersion ? { adapterVersion: record.adapterVersion } : {}),
+        ...(record.harnessVersion ? { harnessVersion: record.harnessVersion } : {}),
+        ...(record.monotonic_ns ? { monotonic_ns: record.monotonic_ns } : {}),
+        ...(record.observed_at ? { observed_at: record.observed_at } : {}),
+        ...(record.hook_name ? { hook_name: record.hook_name } : {}),
+        ...(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 } : {}),
+    };
+}
+/**
+ * Drain one session's intake spool under its held state lease. Records are
+ * processed in append order and deleted only after their outcome is durably
+ * published; the loop rescans until an empty pass so appends that landed while
+ * draining are still picked up. A record that throws is preserved in the
+ * diagnostics spool and removed so it cannot poison the drain; the caller's
+ * own record rethrows to keep today's error visibility.
+ */
+function drainSessionIntakeLocked(coordRoot, control, adapter, sessionHash, statePath, own) {
+    const directory = hookIntakeGroupDirV3(coordRoot, adapter, sessionHash);
+    let ownResult;
+    for (;;) {
+        const entries = listHookIntakeRecordsV3(directory);
+        if (entries.length === 0)
+            break;
+        for (const entry of entries) {
+            const isOwn = own !== undefined && entry.path === own.path;
+            let result;
+            if (!entry.record) {
+                writeProducerDiagnosticV3(coordRoot, "intake_unreadable", { path: entry.path });
+            }
+            else if (entry.record.mode !== control.state) {
+                writeProducerDiagnosticV3(coordRoot, "intake_gate_mismatch", {
+                    observed_gate: control.state,
+                    ...entry.record,
+                });
+            }
+            else {
+                const recordInput = isOwn ? own.input : inputForIntakeRecord(coordRoot, entry.record);
+                try {
+                    result = processHookSignalLocked(control, recordInput, sessionHash, statePath);
+                }
+                catch (error) {
+                    writeProducerDiagnosticV3(coordRoot, "intake_poison", {
+                        error: String(error),
+                        ...entry.record,
+                    });
+                    removeIntakeRecordV3(entry.path);
+                    if (isOwn)
+                        throw error;
+                    continue;
+                }
+            }
+            removeIntakeRecordV3(entry.path);
+            if (isOwn)
+                ownResult = result ?? { state: "spooled" };
+        }
+    }
+    return ownResult;
+}
+/**
+ * Drain every session's pending intake records. This is the terminal drainer:
+ * it does not depend on a "next signal" ever arriving for a session, so it is
+ * wired into reconcile and session-start paths to pick up a final signal whose
+ * appender lost the lease and exited.
+ */
+export function drainHookIntakeSpoolV3(coordRoot) {
+    const result = {
+        groups_with_records: 0,
+        groups_drained: 0,
+        groups_skipped_busy: 0,
+    };
+    const control = readEventV3ControlState(coordRoot);
+    if (control.state !== "candidate" && control.state !== "active")
+        return result;
+    for (const group of listHookIntakeGroupsV3(coordRoot)) {
+        if (listHookIntakeRecordsV3(group.directory).length === 0)
+            continue;
+        result.groups_with_records += 1;
+        const statePath = producerStatePath(coordRoot, group.adapter, group.session_hash);
+        const lease = acquireStateLeaseWithRetry(coordRoot, statePath, 2);
+        if (!lease) {
+            result.groups_skipped_busy += 1;
+            continue;
+        }
+        try {
+            drainSessionIntakeLocked(coordRoot, control, group.adapter, group.session_hash, statePath);
+            result.groups_drained += 1;
+        }
+        finally {
+            lease.release();
+        }
+    }
+    return result;
+}
+function acquireStateLeaseWithRetry(coordRoot, statePath, attempts) {
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            return acquireStateLease(coordRoot, statePath);
+        }
+        catch (error) {
+            const message = String(error);
+            const contended = message.includes("held by a live or unexpired owner") ||
+                message.includes("recovery is already in progress");
+            if (!contended)
+                throw error;
+            if (attempt < attempts)
+                sleepSync(STATE_LEASE_RETRY_DELAY_MS);
+        }
+    }
+    return undefined;
+}
+function sleepSync(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+/** The pre-spool body of the recorder: requires the session's state lease to be held. */
+function processHookSignalLocked(control, input, sessionHash, path) {
+    const rootId = control.genesis.event.scope.root_id;
+    const epochId = control.genesis.profile.privacy_key_epoch;
+    const boundaryEventId = control.state === "candidate"
+        ? control.genesis.event.event_id
+        : control.activation.event.event_id;
+    const rootFingerprintContext = fingerprintContextV3(input.coordRoot, rootId, undefined, epochId);
+    const sessionId = `sid_${sessionHash.slice(4)}`;
+    try {
+        let state = existsSync(path) ? readProducerState(path) : undefined;
+        if (state &&
+            (state.adapter !== input.adapter ||
+                state.session_id !== sessionId ||
+                state.privacy_epoch_id !== epochId ||
+                state.capability_profile !== adapterCapabilityProfileDigestV3(input.adapter))) {
+            throw new Error("V3 producer state authority does not match the active boundary");
+        }
+        if (state?.adapter === "cursor" &&
+            input.payload.cursor_mode &&
+            input.payload.cursor_mode !== "unknown") {
+            if (!state.cursor_mode || state.cursor_mode === "unknown") {
+                state.cursor_mode = input.payload.cursor_mode;
+            }
+            else if (state.cursor_mode !== input.payload.cursor_mode) {
+                throw new Error("Cursor execution mode changed within one V3 generation");
+            }
+        }
+        let recovered;
+        if (state?.pending) {
+            const pendingSource = state.pending.source_id;
+            const incomingSource = sourceIdForSignal(input, rootFingerprintContext);
+            const pendingEvent = state.pending.event;
+            const durability = writeEventV3(input.coordRoot, pendingEvent);
+            applyCommittedEvent(state, pendingEvent);
+            state.pending = undefined;
+            publishProducerState(path, state);
+            if (pendingSource && incomingSource === pendingSource) {
+                recovered = { state: "recorded", event: pendingEvent, durability, recovered: true };
+            }
+        }
+        if (recovered)
+            return recovered;
+        if (input.signal === "session-start") {
+            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) {
+                return { state: "missing_session_start" };
+            }
+            state = newProducerState(input, sessionId, epochId, boundaryEventId);
+        }
+        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
+            // new generation with a derived session.started so its activity is
+            // recorded instead of refused. A TERMINAL state never re-onboards:
+            // resurrection after authoritative termination stays forbidden.
+            // Onboarding requires the payload's own native session identity: an
+            // env-attributed signal must not mint a generation under a hash derived
+            // from the observer instance (that would split the real session).
+            const nativeSessionIdentity = input.payload.session_id ?? input.payload.conversation_id ?? input.payload.agent_id;
+            const onboardable = !state &&
+                RECOVERY_ENABLED_ADAPTERS.has(input.adapter) &&
+                input.signal !== "session-end" &&
+                nativeSessionIdentity !== undefined;
+            if (!onboardable) {
+                writeProducerDiagnosticV3(input.coordRoot, "missing_session_start", {
+                    adapter: input.adapter,
+                    instance_id: input.instance_id,
+                    signal: input.signal,
+                    session_hash: sessionHash,
+                    payload: input.payload,
+                });
+                return { state: "missing_session_start" };
+            }
+            state = newProducerState(input, sessionId, epochId, boundaryEventId);
+            const cursorPromptBootstrap = isCursorPromptBootstrap(input);
+            const onboarding = buildMidFlightSessionStart(input, state, rootId, cursorPromptBootstrap);
+            commitEventLocked(input, state, path, onboarding);
+            if (!cursorPromptBootstrap) {
+                writeProducerDiagnosticV3(input.coordRoot, "mid_flight_onboarding", {
+                    adapter: input.adapter,
+                    instance_id: input.instance_id,
+                    signal: input.signal,
+                    session_hash: sessionHash,
+                });
+            }
+        }
+        const fingerprintContext = fingerprintContextV3(input.coordRoot, rootId, state.generation_id, state.privacy_epoch_id);
+        const recoveryEnabled = RECOVERY_ENABLED_ADAPTERS.has(input.adapter);
+        const nativeTid = input.payload.turn_id
+            ? normalizeNativeIdV3(fingerprintContext, `${input.adapter}.turn`, input.payload.turn_id).replace(/^hid_/, "tid_")
+            : undefined;
+        const cursorPromptWithinOpenTurn = input.adapter === "cursor" &&
+            input.signal === "user-prompt-submit" &&
+            state.current_turn_id !== undefined &&
+            state.current_turn_span !== undefined;
+        const startsDifferentNativeTurn = recoveryEnabled &&
+            input.signal === "user-prompt-submit" &&
+            !cursorPromptWithinOpenTurn &&
+            nativeTid !== undefined &&
+            state.current_turn_id !== undefined &&
+            state.current_turn_id !== nativeTid &&
+            state.current_turn_span !== undefined;
+        if (startsDifferentNativeTurn) {
+            closeResolvedWaits(input, state, path, rootId, fingerprintContext, nativeTid);
+            const endingTid = state.current_turn_id;
+            sweepOpenSpans(input, state, path, rootId, (candidate) => candidate.turn_id === endingTid, "completion_not_observed_before_next_turn");
+            commitRecoveredTurnCompleted(input, state, path, rootId, fingerprintContext);
+        }
+        const staleClosedTurnTool = recoveryEnabled &&
+            isToolSignal(input.signal) &&
+            nativeTid !== undefined &&
+            state.closed_turn_ids.includes(nativeTid) &&
+            state.current_turn_id !== nativeTid;
+        if (staleClosedTurnTool && !state.current_turn_id) {
+            commitRecoveredToolTurnStart(input, state, path, rootId, fingerprintContext);
+        }
+        const eventInput = staleClosedTurnTool
+            ? { ...input, payload: withoutNativeTurnId(input.payload) }
+            : input;
+        const duplicateOpenTurnStart = input.signal === "user-prompt-submit" &&
+            state.current_turn_span !== undefined &&
+            (cursorPromptWithinOpenTurn ||
+                (nativeTid !== undefined && state.current_turn_id === nativeTid));
+        recordTurnHarnessTiming(state, input, !duplicateOpenTurnStart);
+        closeResolvedWaits(input, state, path, rootId, fingerprintContext, nativeTid);
+        if (input.signal === "permission-request") {
+            const waitId = waitIdForInput(input, fingerprintContext);
+            if (waitId && state.waits.some((wait) => wait.wait_id === waitId)) {
+                return { state: "ignored" };
+            }
+        }
+        // Turn-boundary recovery (ADR 0078): a turn terminal is authoritative for
+        // the spans it owns. Derived terminals land BEFORE the native turn event.
+        if (recoveryEnabled && (input.signal === "stop" || input.signal === "stop-failure")) {
+            // The open producer turn is authoritative for a terminal. Cursor may
+            // report a different generation_id on Stop than beforeSubmitPrompt.
+            const endingTid = state.current_turn_id ?? nativeTid;
+            if (endingTid) {
+                sweepOpenSpans(input, state, path, rootId, (candidate) => candidate.turn_id !== undefined && candidate.turn_id === endingTid, "completion_not_observed_before_turn_end");
+            }
+        }
+        else if (recoveryEnabled && input.signal === "user-prompt-submit") {
+            sweepOpenSpans(input, state, path, rootId, (candidate) => candidate.turn_id !== undefined &&
+                (nativeTid === undefined || candidate.turn_id !== nativeTid), "completion_not_observed_before_next_turn");
+        }
+        if (duplicateOpenTurnStart) {
+            writeProducerDiagnosticV3(input.coordRoot, "duplicate_turn_start_suppressed", {
+                adapter: input.adapter,
+                signal: input.signal,
+                reason: cursorPromptWithinOpenTurn
+                    ? "cursor_prompt_while_turn_open"
+                    : "native_turn_already_open",
+                instance_id: input.instance_id,
+                session_hash: sessionHash,
+                generation_id: state.generation_id,
+                turn_id: state.current_turn_id ?? nativeTid,
+                span_id: state.current_turn_span?.span_id,
+                payload: input.payload,
+            });
+            publishProducerState(path, state);
+            return { state: "ignored" };
+        }
+        // Every event derived before the native signal has now been committed.
+        // Sample once for the native event and every span it opens or closes so
+        // their self-contained timing cannot drift by a millisecond.
+        const eventClock = signalClock(input);
+        if (input.signal === "user-prompt-submit" && !state.current_turn_span) {
+            state.current_turn_span = openSpanStateV3({
+                span_id: spanIdV3(),
+                parent_span_id: state.session_span.span_id,
+                boot_id: state.boot_id,
+                clock: eventClock,
+            });
+        }
+        let sourceId = sourceIdForSignal(input, rootFingerprintContext);
+        const semanticKey = cursorShellSemanticKey(input, rootFingerprintContext);
+        let span;
+        let delegation;
+        if (input.signal === "pre-tool-use") {
+            span = semanticKey
+                ? state.spans.find((candidate) => candidate.semantic_key === semanticKey)
+                : undefined;
+            if (span?.requested_event_id)
+                return { state: "ignored" };
+            if (!sourceId && semanticKey) {
+                sourceId = cursorShellFallbackSourceId(semanticKey, state, rootFingerprintContext);
+            }
+            if (!sourceId)
+                return unpairableTool(input, sessionHash, "missing_tool_use_id");
+            if (state.closed_spans.some((closed) => closed.source_id === sourceId)) {
+                // A late pre for a closed span must never open a fresh span: that is
+                // the pre/post-inversion orphan (ADR 0078).
+                return suppressClosedSpanSignal(input, sessionHash, "late_pre_suppressed");
+            }
+            if (recoveryEnabled && state.spans.length >= SPAN_SOFT_WATERMARK) {
+                const currentTid = nativeTid ?? state.current_turn_id;
+                sweepOpenSpans(input, state, path, rootId, (candidate) => candidate.turn_id !== undefined && candidate.turn_id !== currentTid, "span_cap_pressure");
+            }
+            span ??= state.spans.find((candidate) => candidate.source_id === sourceId);
+            if (span?.requested_event_id)
+                return { state: "ignored" };
+            if (!span) {
+                const opened = openSpanStateV3({
+                    span_id: spanIdV3(),
+                    parent_span_id: state.current_turn_span?.span_id ?? state.session_span.span_id,
+                    boot_id: state.boot_id,
+                    clock: eventClock,
+                });
+                span = {
+                    source_id: sourceId,
+                    ...(semanticKey ? { semantic_key: semanticKey } : {}),
+                    ...opened,
+                    ...(input.payload.tool_name ? { tool_name: safeRole(input.payload.tool_name) } : {}),
+                };
+                state.spans.push(span);
+            }
+        }
+        else if (input.signal === "post-tool-use" || input.signal === "post-tool-use-failure") {
+            span = sourceId
+                ? state.spans.find((candidate) => candidate.source_id === sourceId)
+                : undefined;
+            span ??= semanticKey
+                ? state.spans.find((candidate) => candidate.semantic_key === semanticKey)
+                : undefined;
+            if (span)
+                sourceId = span.source_id;
+            if (!sourceId && semanticKey) {
+                sourceId = cursorShellFallbackSourceId(semanticKey, state, rootFingerprintContext);
+            }
+            if (!sourceId)
+                return unpairableTool(input, sessionHash, "missing_tool_use_id");
+            if (!span) {
+                if (semanticKey &&
+                    state.closed_spans.some((closed) => closed.semantic_key === semanticKey)) {
+                    return { state: "ignored" };
+                }
+                if (state.closed_spans.some((closed) => closed.source_id === sourceId)) {
+                    return suppressClosedSpanSignal(input, sessionHash, "late_post_suppressed");
+                }
+                if (!recoveryEnabled)
+                    return unpairableTool(input, sessionHash, "no_open_span");
+                // Unmatched post (ADR 0078): record a derived request and pair the
+                // native completion on a fresh span instead of discarding the result.
+                const opened = openSpanStateV3({
+                    span_id: spanIdV3(),
+                    parent_span_id: state.current_turn_span?.span_id ?? state.session_span.span_id,
+                    boot_id: state.boot_id,
+                    clock: eventClock,
+                });
+                span = {
+                    source_id: sourceId,
+                    ...(semanticKey ? { semantic_key: semanticKey } : {}),
+                    ...opened,
+                    recovery_reason: "request_not_observed",
+                    ...(input.payload.tool_name ? { tool_name: safeRole(input.payload.tool_name) } : {}),
+                };
+                const derivedRequest = normalizeHookEventV3("pre-tool-use", eventInput.payload, {
+                    coordRoot: input.coordRoot,
+                    adapter: input.adapter,
+                    adapterVersion: input.adapterVersion,
+                    harnessVersion: input.harnessVersion,
+                    root_id: rootId,
+                    run_id: input.run_id,
+                    workflow_id: input.workflow_id,
+                    workflow_agent_id: input.workflow_agent_id,
+                    instance_id: input.instance_id,
+                    generation_id: state.generation_id,
+                    attestation_id: state.attestation_id,
+                    producer_id: input.producer_id,
+                    boot_id: state.boot_id,
+                    sequence: state.next_sequence,
+                    build_id: input.build_id,
+                    platform: input.platform,
+                    bridge: input.bridge,
+                    capability_profile: state.capability_profile,
+                    fingerprintContext,
+                    turn_id: state.current_turn_id,
+                    span_id: span.span_id,
+                    caused_by: state.last_event_id ? [state.last_event_id] : [],
+                    observed_at: eventClock.observed_at,
+                    monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+                    clock_id: state.clock_id,
+                });
+                if (!derivedRequest)
+                    return unpairableTool(input, sessionHash, "no_open_span");
+                derivedRequest.provenance = {
+                    ...derivedRequest.provenance,
+                    attestation: "derived",
+                    confidence: input.payload.tool_input !== undefined ? "high" : "medium",
+                };
+                derivedRequest.payload.recovery = {
+                    reason: "request_not_observed",
+                };
+                state.spans.push(span);
+                commitEventLocked(input, state, path, derivedRequest);
+                span.requested_event_id = derivedRequest.event_id;
+                span.open_event_id = derivedRequest.event_id;
+                stampSpanTurn(span, derivedRequest, eventInput, state);
+            }
+        }
+        if (input.signal === "sub-agent-start") {
+            if (!sourceId)
+                return { state: "ignored" };
+            delegation = state.delegations.find((candidate) => candidate.source_id === sourceId);
+            if (!delegation) {
+                const opened = openSpanStateV3({
+                    span_id: spanIdV3(),
+                    parent_span_id: state.current_turn_span?.span_id ?? state.session_span.span_id,
+                    boot_id: state.boot_id,
+                    clock: eventClock,
+                });
+                delegation = {
+                    source_id: sourceId,
+                    ...opened,
+                    delegation_id: delegationIdV3(),
+                    child_generation_id: generationIdV3(),
+                    role: safeRole(input.payload.raw.agent_type),
+                };
+                state.delegations.push(delegation);
+            }
+        }
+        else if (input.signal === "sub-agent-stop") {
+            if (!sourceId)
+                return { state: "ignored" };
+            delegation = state.delegations.find((candidate) => candidate.source_id === sourceId);
+            if (!delegation)
+                return { state: "ignored" };
+        }
+        const waitSpan = input.signal === "permission-request"
+            ? openSpanStateV3({
+                span_id: spanIdV3(),
+                parent_span_id: state.current_turn_span?.span_id ?? state.session_span.span_id,
+                boot_id: state.boot_id,
+                clock: eventClock,
+            })
+            : undefined;
+        const openingSpan = input.signal === "session-start"
+            ? state.session_span
+            : input.signal === "user-prompt-submit"
+                ? state.current_turn_span
+                : input.signal === "pre-tool-use"
+                    ? span
+                    : input.signal === "permission-request"
+                        ? waitSpan
+                        : input.signal === "sub-agent-start"
+                            ? delegation
+                            : undefined;
+        const closingSpan = input.signal === "session-end"
+            ? state.session_span
+            : input.signal === "stop" || input.signal === "stop-failure"
+                ? state.current_turn_span
+                : input.signal === "post-tool-use" || input.signal === "post-tool-use-failure"
+                    ? span
+                    : input.signal === "sub-agent-stop"
+                        ? delegation
+                        : undefined;
+        const terminalSpan = closingSpan
+            ? closeSpanStateV3(closingSpan, {
+                boot_id: state.boot_id,
+                clock: eventClock,
+                ...(span && closingSpan === span && span.recovery_reason
+                    ? { recovery_reason: span.recovery_reason }
+                    : {}),
+            })
+            : undefined;
+        const turnTelemetry = input.signal === "stop" || input.signal === "stop-failure"
+            ? extractTurnTelemetryV3(input.adapter, input.payload.raw, eventClock.observed_at)
+            : undefined;
+        const cursorToolChannelSupport = input.adapter === "cursor"
+            ? cursorToolChannelSupportV3(state.cursor_mode ?? "unknown")
+            : undefined;
+        const cursorToolChannelUnattested = (input.signal === "stop" || input.signal === "stop-failure") &&
+            input.adapter === "cursor" &&
+            cursorToolChannelSupport !== "unsupported" &&
+            state.tool_call_count === 0;
+        if (input.signal === "sub-agent-start" && delegation && !delegation.open_event_id) {
+            commitAgentDelegated(input, state, path, rootId, fingerprintContext, delegation);
+        }
+        const toolCallCountScopeMismatch = (input.signal === "stop" || input.signal === "stop-failure") &&
+            (!state.current_turn_id || state.tool_call_count_turn_id !== state.current_turn_id);
+        const event = normalizeHookEventV3(input.signal, eventInput.payload, {
+            coordRoot: input.coordRoot,
+            adapter: input.adapter,
+            adapterVersion: input.adapterVersion,
+            harnessVersion: input.harnessVersion,
+            root_id: rootId,
+            run_id: input.run_id,
+            workflow_id: input.workflow_id,
+            workflow_agent_id: input.workflow_agent_id,
+            // Native subagent tool hooks can carry the parent's session id while
+            // resolving to a child process instance. The session-keyed producer
+            // state remains the generation authority; route those signals through
+            // its instance instead of rejecting or forging a child/parent scope.
+            instance_id: state.instance_id,
+            generation_id: state.generation_id,
+            attestation_id: state.attestation_id,
+            producer_id: input.producer_id,
+            boot_id: state.boot_id,
+            sequence: state.next_sequence,
+            build_id: input.build_id,
+            platform: input.platform,
+            bridge: input.bridge,
+            capability_profile: state.capability_profile,
+            fingerprintContext,
+            turn_id: state.current_turn_id,
+            span_id: openingSpan?.span_id ?? closingSpan?.span_id,
+            parent_span_id: openingSpan?.parent_span_id ?? closingSpan?.parent_span_id,
+            terminal_span: terminalSpan,
+            harness_timing: state.turn_harness,
+            turn_telemetry: turnTelemetry,
+            caused_by: [
+                ...(state.last_event_id ? [state.last_event_id] : []),
+                ...(terminalSpan?.open_event_id ? [terminalSpan.open_event_id] : []),
+            ].filter((value, index, values) => values.indexOf(value) === index),
+            observed_at: eventClock.observed_at,
+            monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+            clock_id: state.clock_id,
+            duration_ms: durationMilliseconds(span?.opened_monotonic_ns, input.monotonic_ns),
+            // Cursor's terminal payload has no native tool aggregate. With no
+            // delivered tool hook, the recorder has no evidence that zero calls
+            // occurred; emitting an exact zero would turn hook loss into false data.
+            tool_call_count: cursorToolChannelSupport === "unsupported" ||
+                cursorToolChannelUnattested ||
+                toolCallCountScopeMismatch
+                ? undefined
+                : state.tool_call_count,
+            tool_call_count_support: cursorToolChannelSupport,
+            tool_call_count_missing_reason: cursorToolChannelUnattested
+                ? "tool_channel_unattested"
+                : toolCallCountScopeMismatch
+                    ? "tool_count_turn_scope_unattested"
+                    : undefined,
+            delegation_id: delegation?.delegation_id,
+            child_generation_id: delegation?.child_generation_id,
+            agent_role: delegation?.role,
+            stop_remediation: input.stop_remediation,
+            turn_ritual: input.turn_ritual,
+        });
+        if (!event)
+            return { state: "ignored" };
+        if (input.signal === "session-start" &&
+            input.session_start_derivation === "approved_lifecycle_reopen" &&
+            event.event_type === "session.started") {
+            event.provenance = {
+                ...event.provenance,
+                source_event: `${input.adapter}.approved-lifecycle-reopen`,
+                attestation: "derived",
+                confidence: "high",
+                attribution: {
+                    method: "session_env",
+                    state: "verified",
+                    subject_instance_id: state.instance_id,
+                },
+            };
+            event.payload.resume = {
+                state: "unknown",
+                reason: "approved_lifecycle_reopen",
+            };
+            assertEventV3(event);
+        }
+        if (input.signal === "pre-tool-use" && span && !span.requested_event_id) {
+            span.requested_event_id = event.event_id;
+            span.open_event_id = event.event_id;
+            stampSpanTurn(span, event, eventInput, state);
+        }
+        const durability = commitEventLocked(input, state, path, event, sourceId);
+        if (event.event_type === "tool.requested" && sourceId) {
+            const explicitWait = explicitNativeWait(input);
+            if (explicitWait) {
+                commitNativeWait(input, state, path, rootId, sourceId, explicitWait);
+            }
+            else if (input.payload.tool_name === "request_user_input") {
+                commitNativeWait(input, state, path, rootId, sourceId, { kind: "needs_input" });
+            }
+        }
+        const progressKind = progressKindForCompletedTool(event, input);
+        if (progressKind) {
+            commitProgressObservation(input, state, path, rootId, event, progressKind);
+        }
+        if (turnTelemetry) {
+            commitTurnContextObservation(input, state, path, rootId, event, turnTelemetry.context);
+        }
+        if (event.event_type === "session.ended") {
+            commitCapabilityDriftEvents(input, state, path, rootId);
+        }
+        return { state: "recorded", event, durability, recovered: false };
+    }
+    finally {
+        // The session's state lease is held by the draining caller.
+    }
+}
+function commitAgentDelegated(input, state, path, rootId, fingerprintContext, delegation) {
+    const event = buildEventV3("agent.delegated", {
+        producer: producerForDerivedEvent(input, state),
+        scope: scopeForDerivedEvent(input, state, rootId),
+        attestation_id: state.attestation_id,
+        links: {
+            span_id: delegation.span_id,
+            ...(delegation.parent_span_id ? { parent_span_id: delegation.parent_span_id } : {}),
+            caused_by: state.last_event_id ? [state.last_event_id] : [],
+        },
+        provenance: derivedProvenance(input, state, "subagent-delegated"),
+        observed_at: signalClock(input).observed_at,
+        monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+        clock_id: state.clock_id,
+        payload: {
+            delegation_id: delegation.delegation_id,
+            child_generation_id: delegation.child_generation_id,
+            role: delegation.role,
+            ownership_fingerprint: fingerprintV3(fingerprintContext, "delegation-ownership", {
+                role: delegation.role,
+                source_id: delegation.source_id,
+            }),
+        },
+    });
+    commitEventLocked(input, state, path, event);
+}
+function commitNativeWait(input, state, path, rootId, waitId, observation) {
+    if (!state.current_turn_id || state.waits.some((wait) => wait.wait_id === waitId))
+        return;
+    const span = openSpanStateV3({
+        span_id: spanIdV3(),
+        parent_span_id: state.current_turn_span?.span_id ?? state.session_span.span_id,
+        boot_id: state.boot_id,
+        clock: signalClock(input),
+    });
+    const event = buildEventV3("wait.started", {
+        producer: producerForDerivedEvent(input, state),
+        scope: scopeForDerivedEvent(input, state, rootId),
+        attestation_id: state.attestation_id,
+        links: {
+            span_id: span.span_id,
+            ...(span.parent_span_id ? { parent_span_id: span.parent_span_id } : {}),
+            caused_by: state.last_event_id ? [state.last_event_id] : [],
+        },
+        provenance: derivedProvenance(input, state, "native-typed-wait"),
+        observed_at: signalClock(input).observed_at,
+        monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+        clock_id: state.clock_id,
+        payload: {
+            wait_id: waitId,
+            kind: observation.kind,
+            ...(observation.wake_at ? { wake_at: observation.wake_at } : {}),
+            ...(observation.authority_reference
+                ? { authority_reference: observation.authority_reference }
+                : {}),
+        },
+    });
+    commitEventLocked(input, state, path, event);
+}
+function progressKindForCompletedTool(event, input) {
+    if (event.event_type !== "tool.completed" || event.payload.outcome !== "succeeded")
+        return;
+    const explicit = explicitNativeProgress(input);
+    if (explicit)
+        return explicit;
+    const name = event.payload.tool.name;
+    if (["apply_patch", "Edit", "Write", "MultiEdit", "NotebookEdit"].includes(name))
+        return "write";
+    if (name === "view_image")
+        return "review";
+    const leaf = name
+        .split(/__|[/:]/)
+        .at(-1)
+        ?.toLowerCase() ?? name.toLowerCase();
+    if (["run_tests", "test", "vitest", "jest", "playwright_test"].includes(leaf))
+        return "test";
+    if (["git_commit", "commit"].includes(leaf))
+        return "commit";
+    if (["deploy", "deploy_app", "deploy_service"].includes(leaf))
+        return "deploy";
+    if (["publish", "wiki_publish", "publish_page"].includes(leaf))
+        return "publication";
+    if (["build", "compile", "bundle"].includes(leaf))
+        return "artifact";
+    if (/imagegen|create_document|create_spreadsheet|create_presentation/i.test(name)) {
+        return "artifact";
+    }
+    return undefined;
+}
+function commitProgressObservation(input, state, path, rootId, terminal, kind) {
+    const event = buildEventV3("progress.observed", {
+        producer: producerForDerivedEvent(input, state),
+        scope: scopeForDerivedEvent(input, state, rootId),
+        attestation_id: state.attestation_id,
+        links: { caused_by: [terminal.event_id] },
+        provenance: derivedProvenance(input, state, "semantic-progress"),
+        observed_at: terminal.time.observed_at,
+        monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+        clock_id: state.clock_id,
+        payload: {
+            kind,
+            evidence_event_ids: [terminal.event_id],
+            reducer_build_id: input.build_id,
+        },
+    });
+    commitEventLocked(input, state, path, event);
+}
+function explicitNativeProgress(input) {
+    const value = input.payload.raw.harnery_progress_kind ?? input.payload.raw.progress_kind;
+    return value === "write" ||
+        value === "test" ||
+        value === "commit" ||
+        value === "deploy" ||
+        value === "publication" ||
+        value === "review" ||
+        value === "artifact"
+        ? value
+        : undefined;
+}
+function explicitNativeWait(input) {
+    if (input.signal !== "pre-tool-use")
+        return undefined;
+    const raw = input.payload.raw;
+    const value = raw.harnery_wait_kind ?? raw.wait_kind;
+    const kind = value === "permission" ||
+        value === "needs_input" ||
+        value === "decision" ||
+        value === "approval" ||
+        value === "scheduled" ||
+        value === "rate_limit" ||
+        value === "unknown"
+        ? value
+        : undefined;
+    if (!kind)
+        return undefined;
+    const wakeCandidate = raw.harnery_wake_at ?? raw.wake_at;
+    const wake_at = typeof wakeCandidate === "string" &&
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(wakeCandidate) &&
+        Number.isFinite(Date.parse(wakeCandidate))
+        ? wakeCandidate
+        : undefined;
+    const authorityCandidate = raw.harnery_authority_reference ?? raw.authority_reference;
+    const authority_reference = safeTokenOrUndefined(authorityCandidate);
+    return {
+        kind,
+        ...(wake_at ? { wake_at } : {}),
+        ...(authority_reference ? { authority_reference } : {}),
+    };
+}
+function producerForDerivedEvent(input, state) {
+    return {
+        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 } : {}),
+    };
+}
+function scopeForDerivedEvent(input, state, rootId) {
+    return {
+        root_id: rootId,
+        instance_id: state.instance_id,
+        session_id: state.session_id,
+        generation_id: state.generation_id,
+        ...(state.current_turn_id ? { turn_id: state.current_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 } : {}),
+    };
+}
+function derivedProvenance(input, state, signal) {
+    return {
+        source_event: `${input.adapter}.${signal}`,
+        attestation: "derived",
+        confidence: "high",
+        attribution: {
+            method: "session_env",
+            state: "verified",
+            subject_instance_id: state.instance_id,
+        },
+    };
+}
+/**
+ * Stamp the span with the turn its request event was attributed to. No stamp
+ * is written without a real turn context: a native payload turn id or an open
+ * producer-state turn. Unstamped spans are excluded from every boundary and
+ * cap sweep (fail closed; explicit-end salvage may still reach them).
+ */
+function stampSpanTurn(span, requestEvent, input, state) {
+    if (input.payload.turn_id) {
+        span.turn_id = requestEvent.scope.turn_id;
+        span.turn_stamp = "native_payload";
+    }
+    else if (state.current_turn_id) {
+        span.turn_id = state.current_turn_id;
+        span.turn_stamp = "producer_state";
+    }
+}
+function isToolSignal(signal) {
+    return (signal === "pre-tool-use" || signal === "post-tool-use" || signal === "post-tool-use-failure");
+}
+function withoutNativeTurnId(payload) {
+    const { turn_id: _turnId, ...rest } = payload;
+    return rest;
+}
+function recoveryBoundaryPayload(payload) {
+    return {
+        raw: {},
+        ...(payload.session_id ? { session_id: payload.session_id } : {}),
+        ...(payload.conversation_id ? { conversation_id: payload.conversation_id } : {}),
+        ...(payload.agent_id ? { agent_id: payload.agent_id } : {}),
+    };
+}
+/** Close an open turn when a different native prompt proves the next boundary. */
+function commitRecoveredTurnCompleted(input, state, path, rootId, fingerprintContext) {
+    const turnId = state.current_turn_id;
+    const span = state.current_turn_span;
+    if (!turnId || !span)
+        return;
+    const clock = signalClock(input);
+    const terminalSpan = closeSpanStateV3(span, {
+        boot_id: state.boot_id,
+        clock,
+        recovery_reason: "completion_not_observed_before_next_turn",
+    });
+    const toolCountAttested = state.tool_call_count_turn_id === turnId;
+    const event = normalizeHookEventV3("stop", recoveryBoundaryPayload(input.payload), {
+        coordRoot: input.coordRoot,
+        adapter: input.adapter,
+        adapterVersion: input.adapterVersion,
+        harnessVersion: input.harnessVersion,
+        root_id: rootId,
+        run_id: input.run_id,
+        workflow_id: input.workflow_id,
+        workflow_agent_id: input.workflow_agent_id,
+        instance_id: state.instance_id,
+        generation_id: state.generation_id,
+        attestation_id: state.attestation_id,
+        producer_id: input.producer_id,
+        boot_id: state.boot_id,
+        sequence: state.next_sequence,
+        build_id: input.build_id,
+        platform: input.platform,
+        bridge: input.bridge,
+        capability_profile: state.capability_profile,
+        fingerprintContext,
+        turn_id: turnId,
+        span_id: span.span_id,
+        terminal_span: terminalSpan,
+        harness_timing: state.turn_harness,
+        caused_by: [
+            ...(state.last_event_id ? [state.last_event_id] : []),
+            ...(terminalSpan.open_event_id ? [terminalSpan.open_event_id] : []),
+        ].filter((value, index, values) => values.indexOf(value) === index),
+        observed_at: clock.observed_at,
+        monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+        clock_id: state.clock_id,
+        tool_call_count: toolCountAttested ? state.tool_call_count : undefined,
+        tool_call_count_missing_reason: toolCountAttested
+            ? undefined
+            : "tool_count_turn_scope_unattested",
+    });
+    if (event?.event_type !== "turn.completed") {
+        throw new Error("recovered turn terminal could not be normalized");
+    }
+    event.provenance = {
+        ...event.provenance,
+        source_event: `${input.adapter}.recovery`,
+        attestation: "derived",
+        confidence: "medium",
+        attribution: {
+            method: "native_payload",
+            state: "verified",
+            subject_instance_id: state.instance_id,
+        },
+    };
+    event.payload.outcome = "unknown";
+    assertEventV3(event);
+    commitEventLocked(input, state, path, event);
+}
+/** Open a derived turn for tools that arrive after their native turn closed. */
+function commitRecoveredToolTurnStart(input, state, path, rootId, fingerprintContext) {
+    const clock = signalClock(input);
+    const span = openSpanStateV3({
+        span_id: spanIdV3(),
+        parent_span_id: state.session_span.span_id,
+        boot_id: state.boot_id,
+        clock,
+    });
+    state.current_turn_span = span;
+    const event = normalizeHookEventV3("user-prompt-submit", recoveryBoundaryPayload(input.payload), {
+        coordRoot: input.coordRoot,
+        adapter: input.adapter,
+        adapterVersion: input.adapterVersion,
+        harnessVersion: input.harnessVersion,
+        root_id: rootId,
+        run_id: input.run_id,
+        workflow_id: input.workflow_id,
+        workflow_agent_id: input.workflow_agent_id,
+        instance_id: state.instance_id,
+        generation_id: state.generation_id,
+        attestation_id: state.attestation_id,
+        producer_id: input.producer_id,
+        boot_id: state.boot_id,
+        sequence: state.next_sequence,
+        build_id: input.build_id,
+        platform: input.platform,
+        bridge: input.bridge,
+        capability_profile: state.capability_profile,
+        fingerprintContext,
+        turn_native_id: `post-terminal:${state.generation_id}:${state.turn_ordinal + 1}`,
+        span_id: span.span_id,
+        caused_by: state.last_event_id ? [state.last_event_id] : [],
+        observed_at: clock.observed_at,
+        monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+        clock_id: state.clock_id,
+    });
+    if (event?.event_type !== "turn.started") {
+        throw new Error("recovered tool turn start could not be normalized");
+    }
+    event.provenance = {
+        ...event.provenance,
+        source_event: `${input.adapter}.recovery`,
+        attestation: "derived",
+        confidence: "medium",
+        attribution: {
+            method: "session_env",
+            state: "verified",
+            subject_instance_id: state.instance_id,
+        },
+    };
+    assertEventV3(event);
+    commitEventLocked(input, state, path, event);
+}
+/** The single pending-publish/write/apply/publish cycle every locked event commit uses. */
+function commitEventLocked(input, state, path, event, sourceId) {
+    markObservedClockRegressionV3(event, state.last_observed_at);
+    assertEventV3(event);
+    state.pending = { ...(sourceId ? { source_id: sourceId } : {}), event };
+    publishProducerState(path, state);
+    const durability = writeEventV3(input.coordRoot, event, input.writerOptions);
+    applyCommittedEvent(state, event);
+    state.pending = undefined;
+    publishProducerState(path, state);
+    return durability;
+}
+function commitTurnContextObservation(input, state, path, rootId, turnTerminal, measurement) {
+    if (turnTerminal.event_type !== "turn.completed")
+        return;
+    const event = buildEventV3("context.observed", {
+        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,
+            turn_id: turnTerminal.scope.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 } : {}),
+        },
+        attestation_id: state.attestation_id,
+        links: { caused_by: [turnTerminal.event_id] },
+        provenance: {
+            source_event: `${input.adapter}.turn-context`,
+            attestation: "native",
+            confidence: "exact",
+            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,
+        monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+        clock_id: state.clock_id,
+        payload: {
+            measurement,
+        },
+    });
+    commitEventLocked(input, state, path, event);
+}
+function commitCapabilityDriftEvents(input, state, path, rootId) {
+    const read = readLedgerV3(input.coordRoot);
+    if (!read.complete)
+        return;
+    const generationEvents = read.events
+        .map(({ event }) => event)
+        .filter((event) => "generation_id" in event.scope && event.scope.generation_id === state.generation_id);
+    const emittedSignals = new Set(generationEvents
+        .filter((event) => event.event_type === "health.capability_drift")
+        .map((event) => event.payload.signal));
+    for (const payload of capabilityDriftPayloadsV3(input.adapter, generationEvents)) {
+        if (emittedSignals.has(payload.signal))
+            continue;
+        const event = buildEventV3("health.capability_drift", {
+            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,
+            },
+            attestation_id: state.attestation_id,
+            links: { caused_by: state.last_event_id ? [state.last_event_id] : [] },
+            provenance: {
+                source_event: `${input.adapter}.capability-coherence`,
+                attestation: "derived",
+                confidence: "exact",
+                attribution: {
+                    method: "session_env",
+                    state: "verified",
+                    subject_instance_id: state.instance_id,
+                },
+            },
+            observed_at: signalClock(input).observed_at,
+            monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+            clock_id: state.clock_id,
+            payload,
+        });
+        commitEventLocked(input, state, path, event);
+    }
+}
+/**
+ * Terminalize every open span matching the predicate with a derived
+ * `tool.completed` (ADR 0078). One event per span, committed sequentially
+ * through the pending cycle so a crash replays exactly one.
+ */
+function sweepOpenSpans(input, state, path, rootId, matches, reason) {
+    for (const span of [...state.spans]) {
+        if (!matches(span))
+            continue;
+        const event = buildDerivedToolCompleted(input, state, rootId, span, reason);
+        commitEventLocked(input, state, path, event);
+    }
+}
+function buildDerivedToolCompleted(input, state, rootId, span, reason, producerOverride, observedAt) {
+    const clock = signalClock(input);
+    if (observedAt !== undefined)
+        clock.observed_at = observedAt;
+    const baseConfidence = reason === "completion_not_observed_before_turn_end" || reason === "explicit_end_salvage"
+        ? "medium"
+        : "low";
+    const confidence = span.turn_stamp === "producer_state" && baseConfidence === "medium" ? "low" : baseConfidence;
+    const terminalSpan = closeSpanStateV3(span, {
+        boot_id: state.boot_id,
+        clock,
+        recovery_reason: reason,
+    });
+    const elapsedUpperBound = recoverSpanUpperBoundV3(span, {
+        boot_id: state.boot_id,
+        clock,
+    });
+    const event = buildEventV3("tool.completed", {
+        producer: {
+            producer_id: producerOverride?.producer_id ?? input.producer_id,
+            boot_id: producerOverride?.boot_id ?? state.boot_id,
+            sequence: producerOverride?.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,
+            turn_id: span.turn_id,
+        },
+        attestation_id: state.attestation_id,
+        links: {
+            caused_by: [
+                ...(state.last_event_id ? [state.last_event_id] : []),
+                ...(span.open_event_id ? [span.open_event_id] : []),
+            ].filter((value, index, values) => values.indexOf(value) === index),
+            span_id: span.span_id,
+        },
+        provenance: {
+            source_event: `${input.adapter}.recovery`,
+            attestation: "derived",
+            confidence,
+            attribution: {
+                method: span.turn_stamp === "native_payload" ? "native_payload" : "session_env",
+                state: "verified",
+                subject_instance_id: state.instance_id,
+            },
+        },
+        observed_at: clock.observed_at,
+        monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+        clock_id: state.clock_id,
+        payload: {
+            tool: { namespace: input.adapter, name: span.tool_name ?? "unknown_tool" },
+            outcome: "unknown",
+            duration_ms: structuredClone(terminalSpan.duration_ms),
+            span: terminalSpan,
+            result: { storage: "omitted", media_type: "application/octet-stream", bytes: 0 },
+            recovery: {
+                reason,
+                ...(span.requested_event_id ? { requested_event_id: span.requested_event_id } : {}),
+                elapsed_upper_bound_ms: elapsedUpperBound,
+            },
+        },
+    });
+    assertEventV3(event);
+    return event;
+}
+/**
+ * A derived `session.started` for a live session Harnery first observed
+ * mid-flight (fresh epoch or lost session-start hook). Records that the
+ * session exists without claiming the adapter delivered a start signal.
+ */
+function buildMidFlightSessionStart(input, state, rootId, cursorPromptBootstrap = false) {
+    const fingerprintContext = fingerprintContextV3(input.coordRoot, rootId, state.generation_id, state.privacy_epoch_id);
+    const event = normalizeHookEventV3("session-start", input.payload, {
+        coordRoot: input.coordRoot,
+        adapter: input.adapter,
+        adapterVersion: input.adapterVersion,
+        harnessVersion: input.harnessVersion,
+        root_id: rootId,
+        run_id: input.run_id,
+        workflow_id: input.workflow_id,
+        workflow_agent_id: input.workflow_agent_id,
+        instance_id: input.instance_id,
+        generation_id: state.generation_id,
+        attestation_id: state.attestation_id,
+        producer_id: input.producer_id,
+        boot_id: state.boot_id,
+        sequence: state.next_sequence,
+        build_id: input.build_id,
+        platform: input.platform,
+        bridge: input.bridge,
+        capability_profile: state.capability_profile,
+        fingerprintContext,
+        caused_by: state.last_event_id ? [state.last_event_id] : [],
+        monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+        clock_id: state.clock_id,
+    });
+    if (!event)
+        throw new Error("mid-flight session start could not be normalized");
+    event.provenance = {
+        ...event.provenance,
+        attestation: "derived",
+        confidence: cursorPromptBootstrap ? "high" : "medium",
+    };
+    event.payload.resume = {
+        state: "unknown",
+        reason: cursorPromptBootstrap ? "cursor_prompt_bootstrap" : "mid_flight_onboarding",
+    };
+    assertEventV3(event);
+    return event;
+}
+/**
+ * Cursor can deliver its native `beforeSubmitPrompt` signal before its
+ * `sessionStart` hook. The prompt carries both conversation and turn identity,
+ * so it is a high-confidence session boundary rather than degraded recovery.
+ */
+function isCursorPromptBootstrap(input) {
+    return (input.adapter === "cursor" &&
+        input.signal === "user-prompt-submit" &&
+        (input.payload.conversation_id !== undefined || input.payload.session_id !== undefined) &&
+        input.payload.turn_id !== undefined);
+}
+function suppressClosedSpanSignal(input, sessionHash, category) {
+    writeProducerDiagnosticV3(input.coordRoot, category, {
+        adapter: input.adapter,
+        instance_id: input.instance_id,
+        signal: input.signal,
+        session_hash: sessionHash,
+        payload: input.payload,
+    });
+    return { state: "suppressed", reason: "closed_span" };
+}
+/**
+ * End one exact live generation under the same private-state lease used by its
+ * native hook producer. This is the only approved-authority terminal writer:
+ * archive reconciliation, explicit `harn-end`, and policy cascades all converge
+ * here so they cannot race each other or append activity after termination.
+ */
+export function recordApprovedSessionEndV3(input) {
+    const control = readEventV3ControlState(input.coordRoot);
+    if (control.state !== input.mode) {
+        return { state: "gate_closed", reason: control.state };
+    }
+    const matches = listHookProducerStateRecordsV3(input.coordRoot, { includeTerminal: true }).filter(({ state }) => state.instance_id === input.instance_id && state.generation_id === input.generation_id);
+    if (matches.length !== 1) {
+        return {
+            state: "generation_unavailable",
+            reason: matches.length === 0 ? "not_found" : "ambiguous",
+        };
+    }
+    const record = matches[0];
+    const lease = acquireStateLease(input.coordRoot, record.path);
+    try {
+        const state = readProducerState(record.path);
+        if (state.instance_id !== input.instance_id || state.generation_id !== input.generation_id) {
+            return { state: "generation_unavailable", reason: "authority_changed" };
+        }
+        let recovered = false;
+        if (state.pending) {
+            const pending = state.pending.event;
+            const durability = writeEventV3(input.coordRoot, pending, input.writerOptions);
+            applyCommittedEvent(state, pending);
+            state.pending = undefined;
+            publishProducerState(record.path, state);
+            recovered = true;
+            if (pending.event_type === "session.ended") {
+                return { state: "recorded", event: pending, durability, recovered };
+            }
+        }
+        if (state.terminal)
+            return { state: "already_ended", event_id: state.last_event_id };
+        if (!state.started_event_id || !state.last_event_id) {
+            return { state: "generation_unavailable", reason: "session_start_missing" };
+        }
+        const rootId = control.genesis.event.scope.root_id;
+        const context = fingerprintContextV3(input.coordRoot, rootId, state.generation_id, state.privacy_epoch_id);
+        const expected = [
+            "session_started",
+            "turn_closed",
+            "tool_spans_closed",
+            "delegated_children_closed",
+            "coordination_finalized",
+        ];
+        const observed = [
+            ...(state.started_event_id ? ["session_started"] : []),
+            ...(!state.current_turn_id ? ["turn_closed"] : []),
+            ...(state.spans.length === 0 ? ["tool_spans_closed"] : []),
+            ...(state.delegations.length === 0 ? ["delegated_children_closed"] : []),
+            ...(input.coordination_finalized ? ["coordination_finalized"] : []),
+        ];
+        const observedSet = new Set(observed);
+        const missing = expected.filter((field) => !observedSet.has(field));
+        const causedBy = [
+            ...new Set([state.last_event_id, input.caused_by_event_id, state.session_span.open_event_id].filter(Boolean)),
+        ];
+        const event = buildEventV3("session.ended", {
+            producer: {
+                producer_id: "prd_agent-finalizer",
+                boot_id: `boot_${randomUUID()}`,
+                sequence: 1,
+                component: "agent-coord",
+                build_id: input.build_id,
+                platform: input.platform,
+            },
+            scope: {
+                root_id: rootId,
+                instance_id: state.instance_id,
+                session_id: state.session_id,
+                generation_id: state.generation_id,
+            },
+            attestation_id: state.attestation_id,
+            links: { caused_by: causedBy },
+            provenance: {
+                source_event: `agent-coord.session-finalizer.${input.reason}`,
+                attestation: "derived",
+                confidence: input.confidence ?? "high",
+                source_record_id: normalizeNativeIdV3(context, "agent-coord.approved-session-end", `${input.reason}\0${state.generation_id}\0${input.observed_at ?? "now"}`),
+                attribution: {
+                    method: "explicit_argument",
+                    state: "verified",
+                    observer_instance_id: state.instance_id,
+                    subject_instance_id: state.instance_id,
+                },
+            },
+            observed_at: input.observed_at,
+            clock_id: state.clock_id,
+            payload: {
+                outcome: input.outcome,
+                authority: "approved",
+                reason: input.reason,
+                span: closeSpanStateV3(state.session_span, {
+                    boot_id: state.boot_id,
+                    clock: { observed_at: input.observed_at ?? new Date().toISOString() },
+                }),
+                completeness: {
+                    state: "observed",
+                    value: { expected, observed, missing },
+                    attestation: "derived",
+                    confidence: input.confidence ?? "high",
+                },
+            },
+        });
+        markObservedClockRegressionV3(event, state.last_observed_at);
+        assertEventV3(event);
+        state.pending = { event };
+        publishProducerState(record.path, state);
+        const durability = writeEventV3(input.coordRoot, event, input.writerOptions);
+        applyCommittedEvent(state, event);
+        state.pending = undefined;
+        publishProducerState(record.path, state);
+        return { state: "recorded", event, durability, recovered };
+    }
+    finally {
+        lease.release();
+    }
+}
+/**
+ * Explicit-end salvage (ADR 0078): terminalize exactly the approved open-span
+ * set with derived recovery terminals so an authorized end stops wedging
+ * behind spans nothing else can close. Runs under the same private-state
+ * lease as the native producer; spans outside the approved set are refused by
+ * the caller's eligibility gate and never touched here.
+ */
+export function salvageOpenSpansV3(input) {
+    const control = readEventV3ControlState(input.coordRoot);
+    if (control.state !== input.mode) {
+        return { state: "gate_closed", reason: control.state };
+    }
+    const matches = listHookProducerStateRecordsV3(input.coordRoot).filter(({ state }) => state.instance_id === input.instance_id && state.generation_id === input.generation_id);
+    if (matches.length !== 1) {
+        return {
+            state: "generation_unavailable",
+            reason: matches.length === 0 ? "not_found" : "ambiguous",
+        };
+    }
+    const record = matches[0];
+    const lease = acquireStateLeaseWithRetry(input.coordRoot, record.path, 2);
+    if (!lease)
+        return { state: "generation_unavailable", reason: "busy" };
+    try {
+        const state = readProducerState(record.path);
+        if (state.instance_id !== input.instance_id ||
+            state.generation_id !== input.generation_id ||
+            state.terminal) {
+            return { state: "generation_unavailable", reason: "authority_changed" };
+        }
+        const rootId = control.genesis.event.scope.root_id;
+        const salvageInput = {
+            coordRoot: input.coordRoot,
+            mode: input.mode,
+            signal: "stop",
+            payload: { raw: {} },
+            adapter: state.adapter,
+            instance_id: state.instance_id,
+            producer_id: "prd_agent-finalizer",
+            build_id: input.build_id,
+            platform: input.platform,
+            writerOptions: input.writerOptions,
+        };
+        if (state.pending) {
+            const pendingEvent = state.pending.event;
+            writeEventV3(input.coordRoot, pendingEvent, input.writerOptions);
+            applyCommittedEvent(state, pendingEvent);
+            state.pending = undefined;
+            publishProducerState(record.path, state);
+        }
+        const allowed = new Set(input.allowed_span_ids);
+        const fingerprintContext = fingerprintContextV3(input.coordRoot, rootId, state.generation_id, state.privacy_epoch_id);
+        // Salvage runs outside the hook producer chain: a fresh boot starting at
+        // sequence 1 keeps the reader's per-(producer, boot) continuity intact.
+        const salvageBoot = `boot_${randomUUID()}`;
+        let salvageSequence = 1;
+        let closed = 0;
+        for (const span of [...state.spans]) {
+            if (!allowed.has(span.span_id))
+                continue;
+            if (!span.turn_id) {
+                // An unstamped span still needs a turn scope; the requested turn is
+                // the only honest owner the explicit end named, and a salvage-scoped
+                // synthetic id is the last resort.
+                span.turn_id =
+                    input.requested_turn_id ??
+                        `tid_${normalizeNativeIdV3(fingerprintContext, `${state.adapter}.turn`, `salvage:${span.span_id}`).slice(4)}`;
+            }
+            const event = buildDerivedToolCompleted(salvageInput, state, rootId, span, "explicit_end_salvage", { producer_id: "prd_agent-finalizer", boot_id: salvageBoot, sequence: salvageSequence }, input.observed_at);
+            salvageSequence += 1;
+            commitEventLocked(salvageInput, state, record.path, event);
+            closed += 1;
+        }
+        return { state: "salvaged", closed };
+    }
+    finally {
+        lease.release();
+    }
+}
+export function listHookProducerStateRecordsV3(coordRoot, options = {}) {
+    const control = readEventV3ControlState(coordRoot);
+    if (control.state !== "candidate" && control.state !== "active")
+        return [];
+    const producerRoot = join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers");
+    if (!existsSync(producerRoot))
+        return [];
+    const records = [];
+    for (const adapter of ["claude-code", "codex", "cursor"]) {
+        const directory = join(producerRoot, adapter);
+        if (!existsSync(directory))
+            continue;
+        const metadata = lstatSync(directory);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+            throw new Error("V3 producer state directory is unsafe");
+        }
+        for (const name of readdirSync(directory).filter((entry) => /^hid_[a-f0-9]{64}\.json$/.test(entry))) {
+            const path = join(directory, name);
+            const state = readProducerState(path);
+            if (!options.includeTerminal && state.terminal)
+                continue;
+            records.push({ path, modified_at_ms: lstatSync(path).mtimeMs, state });
+        }
+    }
+    return records.sort((left, right) => left.state.generation_id.localeCompare(right.state.generation_id) ||
+        left.path.localeCompare(right.path));
+}
+function hookSignalCapability(signal) {
+    switch (signal) {
+        case "session-start":
+            return "session_start";
+        case "session-end":
+            return "session_end";
+        case "user-prompt-submit":
+            return "prompt";
+        case "stop":
+        case "stop-failure":
+            return "turn_completion";
+        case "pre-tool-use":
+            return "tool_request";
+        case "post-tool-use":
+            return "tool_result";
+        case "post-tool-use-failure":
+            return "tool_failure";
+        case "permission-request":
+            return "permission";
+        case "sub-agent-start":
+        case "sub-agent-stop":
+            return "subagent";
+        case "pre-compact":
+            return "pre_compaction";
+        case "post-compact":
+            return "post_compaction";
+    }
+}
+export function readHookProducerStateV3(coordRoot, adapter, nativeSessionId) {
+    const control = readEventV3ControlState(coordRoot);
+    if (control.state !== "candidate" && control.state !== "active")
+        return undefined;
+    const rootId = control.genesis.event.scope.root_id;
+    const context = fingerprintContextV3(coordRoot, rootId, undefined, control.genesis.profile.privacy_key_epoch);
+    const sessionHash = normalizeNativeIdV3(context, `${adapter}.session`, nativeSessionId);
+    const path = producerStatePath(coordRoot, adapter, sessionHash);
+    return existsSync(path) ? readProducerState(path) : undefined;
+}
+/** Resolve one terminal producer only when native session and instance identity agree. */
+export function readTerminalHookProducerStateV3(coordRoot, nativeSessionId, instanceId) {
+    const matches = ["claude-code", "codex", "cursor"]
+        .map((adapter) => readHookProducerStateV3(coordRoot, adapter, nativeSessionId))
+        .filter((state) => state?.terminal === true && state.instance_id === instanceId);
+    return matches.length === 1 ? matches[0] : undefined;
+}
+export function readHookProducerStateByInstanceV3(coordRoot, instanceId) {
+    const control = readEventV3ControlState(coordRoot);
+    if (control.state !== "candidate" && control.state !== "active")
+        return undefined;
+    const producerRoot = join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers");
+    if (!existsSync(producerRoot))
+        return undefined;
+    const matches = [];
+    for (const adapter of ["claude-code", "codex", "cursor"]) {
+        const directory = join(producerRoot, adapter);
+        if (!existsSync(directory))
+            continue;
+        const metadata = lstatSync(directory);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+            throw new Error("V3 producer state directory is unsafe");
+        }
+        for (const name of readdirSync(directory).filter((entry) => /^hid_[a-f0-9]{64}\.json$/.test(entry))) {
+            const state = readProducerState(join(directory, name));
+            if (state.instance_id === instanceId && !state.terminal)
+                matches.push(state);
+        }
+    }
+    return matches.length === 1 ? matches[0] : undefined;
+}
+function newProducerState(input, sessionId, epochId, boundaryEventId) {
+    const bootId = `boot_${randomUUID()}`;
+    return {
+        format: STATE_FORMAT,
+        format_version: STATE_VERSION,
+        adapter: input.adapter,
+        instance_id: input.instance_id,
+        session_id: sessionId,
+        generation_id: generationIdV3(),
+        attestation_id: attestationIdV3(),
+        capability_profile: adapterCapabilityProfileDigestV3(input.adapter),
+        cursor_mode: input.adapter === "cursor" ? (input.payload.cursor_mode ?? "unknown") : undefined,
+        privacy_epoch_id: epochId,
+        boot_id: bootId,
+        clock_id: clockIdV3(),
+        next_sequence: 1,
+        tool_call_count: 0,
+        last_event_id: boundaryEventId,
+        session_span: openSpanStateV3({
+            span_id: spanIdV3(),
+            boot_id: bootId,
+            clock: signalClock(input),
+        }),
+        terminal: false,
+        spans: [],
+        delegations: [],
+        closed_spans: [],
+        closed_turn_ids: [],
+        waits: [],
+        turn_harness: emptyTurnHarnessTiming(),
+        turn_ordinal: 0,
+    };
+}
+function applyCommittedEvent(state, event) {
+    // Sequence continuity is keyed on (producer_id, boot_id): only events that
+    // ride the state's own producer chain advance it. Finalizer-authored events
+    // (fresh boot, sequence 1) must not create gaps in the hook chain.
+    if (event.producer.boot_id === state.boot_id)
+        state.next_sequence += 1;
+    if (event.time.monotonic_ns)
+        state.last_monotonic_ns = event.time.monotonic_ns;
+    // Mirrors the reader, which tracks the last observed value per clock even
+    // when that value regressed. Holding the maximum instead would hide a
+    // second regression behind the first.
+    state.last_observed_at = event.time.observed_at;
+    state.last_event_id = event.event_id;
+    if (event.event_type === "session.started") {
+        state.started_event_id = event.event_id;
+        state.session_span.open_event_id = event.event_id;
+    }
+    if (event.event_type === "turn.started") {
+        const nextTurnId = event.scope.turn_id;
+        state.current_turn_id = nextTurnId;
+        if (state.tool_call_count_turn_id !== nextTurnId) {
+            state.tool_call_count = 0;
+            state.tool_call_count_turn_id = nextTurnId;
+        }
+        if (state.current_turn_span) {
+            state.current_turn_span.open_event_id = event.event_id;
+        }
+        state.turn_ordinal += 1;
+        state.closed_spans = state.closed_spans.filter((closed) => closed.turn_ordinal >= state.turn_ordinal - CLOSED_SPAN_TURN_RETENTION);
+    }
+    if (event.event_type === "tool.requested") {
+        const requestTurnId = event.scope.turn_id;
+        if (state.tool_call_count_turn_id !== requestTurnId) {
+            state.tool_call_count = 0;
+            state.tool_call_count_turn_id = requestTurnId;
+        }
+        state.tool_call_count += 1;
+    }
+    if (event.event_type === "wait.started") {
+        const waitId = event.payload.wait_id;
+        const turnId = event.scope.turn_id;
+        const waitLinks = event.links;
+        if (!state.waits.some((wait) => wait.wait_id === waitId)) {
+            state.waits.push({
+                wait_id: waitId,
+                started_event_id: event.event_id,
+                turn_id: turnId,
+                span_id: waitLinks.span_id,
+                ...(waitLinks.parent_span_id ? { parent_span_id: waitLinks.parent_span_id } : {}),
+                opened_at: event.time.observed_at,
+                boot_id: state.boot_id,
+                ...(event.time.monotonic_ns ? { opened_monotonic_ns: event.time.monotonic_ns } : {}),
+                open_event_id: event.event_id,
+            });
+        }
+    }
+    if (event.event_type === "wait.ended") {
+        const waitId = event.payload.wait_id;
+        state.waits = state.waits.filter((wait) => wait.wait_id !== waitId);
+    }
+    if (event.event_type === "tool.completed") {
+        const completedSpan = event.links.span_id;
+        const closing = state.spans.find((span) => span.span_id === completedSpan);
+        if (closing) {
+            state.closed_spans.push({
+                source_id: closing.source_id,
+                ...(closing.semantic_key ? { semantic_key: closing.semantic_key } : {}),
+                span_id: closing.span_id,
+                closed_event_id: event.event_id,
+                turn_ordinal: state.turn_ordinal,
+            });
+            if (state.closed_spans.length > CLOSED_SPAN_MEMORY_CAP) {
+                state.closed_spans = state.closed_spans.slice(-CLOSED_SPAN_MEMORY_CAP);
+            }
+        }
+        state.spans = state.spans.filter((span) => span.span_id !== completedSpan);
+    }
+    if (event.event_type === "agent.completed") {
+        const completedDelegation = event.payload.delegation_id;
+        state.delegations = state.delegations.filter((delegation) => delegation.delegation_id !== completedDelegation);
+    }
+    if (event.event_type === "agent.started") {
+        const openedDelegation = state.delegations.find((candidate) => candidate.delegation_id === event.payload.delegation_id);
+        if (openedDelegation)
+            openedDelegation.open_event_id = event.event_id;
+    }
+    if (event.event_type === "turn.completed") {
+        const completedTurnId = event.scope.turn_id;
+        if (!state.closed_turn_ids.includes(completedTurnId)) {
+            state.closed_turn_ids.push(completedTurnId);
+            if (state.closed_turn_ids.length > CLOSED_TURN_MEMORY_CAP) {
+                state.closed_turn_ids = state.closed_turn_ids.slice(-CLOSED_TURN_MEMORY_CAP);
+            }
+        }
+        state.current_turn_id = undefined;
+        state.current_turn_span = undefined;
+        state.tool_call_count = 0;
+        state.tool_call_count_turn_id = undefined;
+        state.turn_harness = emptyTurnHarnessTiming();
+    }
+    if (event.event_type === "session.ended")
+        state.terminal = true;
+}
+function unpairableTool(input, sessionHash, reason) {
+    writeProducerDiagnosticV3(input.coordRoot, "unpairable_tool", {
+        reason,
+        adapter: input.adapter,
+        instance_id: input.instance_id,
+        signal: input.signal,
+        session_hash: sessionHash,
+        payload: input.payload,
+    });
+    return { state: "unpairable_tool", reason };
+}
+function sourceIdForSignal(input, context) {
+    const toolSignal = input.signal === "pre-tool-use" ||
+        input.signal === "post-tool-use" ||
+        input.signal === "post-tool-use-failure";
+    const subagentSignal = input.signal === "sub-agent-start" || input.signal === "sub-agent-stop";
+    const native = toolSignal
+        ? input.payload.tool_use_id
+        : subagentSignal
+            ? (input.payload.subagent_id ?? input.payload.agent_id)
+            : (input.payload.turn_id ??
+                (input.signal === "session-start"
+                    ? (input.payload.session_id ?? input.payload.conversation_id ?? input.payload.agent_id)
+                    : undefined));
+    return native
+        ? normalizeNativeIdV3(context, `${input.adapter}.hook-source`, `${toolSignal ? "tool" : subagentSignal ? "subagent" : input.signal}:${native}`)
+        : undefined;
+}
+function cursorShellSemanticKey(input, context) {
+    if (input.adapter !== "cursor")
+        return undefined;
+    const command = extractBashCommand(input.payload.tool_name, input.payload.tool_input);
+    return command
+        ? normalizeNativeIdV3(context, "cursor.shell-operation", command.normalize("NFC"))
+        : undefined;
+}
+function cursorShellFallbackSourceId(semanticKey, state, context) {
+    return normalizeNativeIdV3(context, "cursor.hook-source", `shell:${semanticKey}:${state.turn_ordinal}:${state.tool_call_count}`);
+}
+function closeResolvedWaits(input, state, path, rootId, fingerprintContext, nativeTid) {
+    const toolResolution = input.signal === "pre-tool-use" ||
+        input.signal === "post-tool-use" ||
+        input.signal === "post-tool-use-failure";
+    const resolvedWaitId = toolResolution ? waitIdForInput(input, fingerprintContext) : undefined;
+    const endingTurnId = input.signal === "stop" || input.signal === "stop-failure"
+        ? (nativeTid ?? state.current_turn_id)
+        : undefined;
+    let waits = state.waits.filter((wait) => wait.wait_id === resolvedWaitId || wait.turn_id === endingTurnId);
+    if (endingTurnId && waits.length === 0)
+        waits = [...state.waits];
+    if (toolResolution && waits.length === 0 && state.current_turn_id) {
+        const turnWaits = state.waits.filter((wait) => wait.turn_id === state.current_turn_id);
+        if (turnWaits.length === 1)
+            waits = turnWaits;
+    }
+    for (const wait of waits) {
+        const outcome = endingTurnId
+            ? "interrupted"
+            : input.signal === "post-tool-use-failure"
+                ? "denied"
+                : "succeeded";
+        const event = buildEventV3("wait.ended", {
+            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,
+                turn_id: wait.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 } : {}),
+            },
+            attestation_id: state.attestation_id,
+            links: { caused_by: [wait.started_event_id] },
+            provenance: {
+                source_event: `${input.adapter}.permission-resolution`,
+                attestation: "derived",
+                confidence: "high",
+                attribution: {
+                    method: "native_payload",
+                    state: "verified",
+                    subject_instance_id: state.instance_id,
+                },
+            },
+            monotonic_ns: orderedEventMonotonic(state, input.monotonic_ns),
+            clock_id: state.clock_id,
+            payload: {
+                wait_id: wait.wait_id,
+                outcome,
+                resolution_reference: endingTurnId ? "turn_terminal" : input.signal,
+                span: closeSpanStateV3(wait, {
+                    boot_id: state.boot_id,
+                    clock: signalClock(input),
+                }),
+            },
+        });
+        commitEventLocked(input, state, path, event);
+    }
+}
+function waitIdForInput(input, fingerprintContext) {
+    return input.payload.tool_use_id
+        ? normalizeNativeIdV3(fingerprintContext, `${input.adapter}.wait`, input.payload.tool_use_id)
+        : undefined;
+}
+function signalClock(input) {
+    return {
+        observed_at: input.observed_at ?? new Date().toISOString(),
+        ...(input.monotonic_ns ? { monotonic_ns: input.monotonic_ns } : {}),
+    };
+}
+function durationMilliseconds(start, end) {
+    if (!start || !end || !/^\d+$/.test(start) || !/^\d+$/.test(end))
+        return undefined;
+    const delta = BigInt(end) - BigInt(start);
+    if (delta < 0n)
+        return undefined;
+    const milliseconds = Number(delta / 1000000n);
+    return Number.isSafeInteger(milliseconds) ? milliseconds : undefined;
+}
+function safeRole(value) {
+    if (typeof value !== "string")
+        return "agent";
+    const normalized = value
+        .normalize("NFC")
+        .replace(/[^a-zA-Z0-9._:/+-]/g, "_")
+        .slice(0, 128);
+    return /^[a-zA-Z0-9]/.test(normalized) ? normalized : "agent";
+}
+function safeTokenOrUndefined(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.normalize("NFC");
+    return /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(normalized) ? normalized : undefined;
+}
+function producerStatePath(coordRoot, adapter, sessionHash) {
+    return join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers", adapter, `${sessionHash}.json`);
+}
+function acquireStateLease(coordRoot, statePath) {
+    const directory = join(statePath, "..");
+    const producerRoot = join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers");
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    chmodSync(producerRoot, 0o700);
+    chmodSync(directory, 0o700);
+    return acquireNoClobberLease({
+        path: `${statePath}.lease`,
+        scope: "event-v3-hook-producer",
+        authoritySha256: createHash("sha256")
+            .update(resolve(coordRoot))
+            .update("\0")
+            .update(statePath)
+            .digest("hex"),
+        staleAfterMs: 5_000,
+        validateStaleOwner: (owner) => owner.host === hostname() && !pidIsAlive(owner.pid),
+    });
+}
+function publishProducerState(path, state) {
+    const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    let fd;
+    try {
+        fd = openSync(temporary, "wx", 0o600);
+        writeFileSync(fd, `${JSON.stringify(state)}\n`, "utf8");
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        renameSync(temporary, path);
+        chmodSync(path, 0o600);
+        fsyncParentDirectory(path);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+}
+function readProducerState(path) {
+    const metadata = lstatSync(path);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) {
+        throw new Error("V3 producer state path is unsafe");
+    }
+    if ((metadata.mode & 0o077) !== 0)
+        throw new Error("V3 producer state is not owner-only");
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error("V3 producer state is unreadable");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("V3 producer state is invalid");
+    }
+    const state = parsed;
+    // In-place additive upgrade from format 1 (pre-ADR-0078): the new fields
+    // default empty; an old build reading a version-2 file still throws, and its
+    // signal is already durable in the intake spool.
+    if (state.format_version === 1 && state.format === STATE_FORMAT) {
+        state.format_version = STATE_VERSION;
+        state.closed_spans ??= [];
+        state.turn_ordinal ??= 0;
+    }
+    // Additive format-2 state: existing files predate wait tracking but remain
+    // valid and acquire an empty set on their next read.
+    state.waits ??= [];
+    state.closed_turn_ids ??= [];
+    state.turn_harness ??= emptyTurnHarnessTiming();
+    if (state.adapter === "cursor")
+        state.cursor_mode ??= "unknown";
+    const allowedKeys = new Set([
+        "adapter",
+        "attestation_id",
+        "boot_id",
+        "capability_profile",
+        "clock_id",
+        "closed_spans",
+        "closed_turn_ids",
+        "current_turn_id",
+        "current_turn_span",
+        "cursor_mode",
+        "delegations",
+        "format",
+        "format_version",
+        "generation_id",
+        "instance_id",
+        "last_event_id",
+        "last_monotonic_ns",
+        "last_observed_at",
+        "next_sequence",
+        "pending",
+        "privacy_epoch_id",
+        "session_id",
+        "session_span",
+        "spans",
+        "started_event_id",
+        "terminal",
+        "tool_call_count",
+        "tool_call_count_turn_id",
+        "turn_harness",
+        "turn_ordinal",
+        "waits",
+    ]);
+    if (Object.keys(state).some((key) => !allowedKeys.has(key)) ||
+        state.format !== STATE_FORMAT ||
+        state.format_version !== STATE_VERSION ||
+        !["claude-code", "codex", "cursor"].includes(state.adapter) ||
+        (state.cursor_mode !== undefined &&
+            !["local", "cloud", "unknown"].includes(state.cursor_mode)) ||
+        !/^inst_[a-zA-Z0-9._-]{1,128}$/.test(state.instance_id) ||
+        !/^sid_[a-f0-9]{64}$/.test(state.session_id) ||
+        !/^gen_[0-9a-f-]{36}$/.test(state.generation_id) ||
+        !/^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) ||
+        !/^boot_[a-zA-Z0-9._-]+$/.test(state.boot_id) ||
+        !/^clk_[0-9a-f-]{36}$/.test(state.clock_id) ||
+        !Number.isSafeInteger(state.next_sequence) ||
+        state.next_sequence < 1 ||
+        !Number.isSafeInteger(state.tool_call_count) ||
+        state.tool_call_count < 0 ||
+        (state.tool_call_count_turn_id !== undefined &&
+            !/^tid_[a-f0-9]{64}$/.test(state.tool_call_count_turn_id)) ||
+        !validTurnHarnessTiming(state.turn_harness) ||
+        !validOpenSpanState(state.session_span) ||
+        (state.current_turn_span !== undefined && !validOpenSpanState(state.current_turn_span)) ||
+        typeof state.terminal !== "boolean" ||
+        !Array.isArray(state.spans) ||
+        !Array.isArray(state.delegations) ||
+        state.delegations.length > 256 ||
+        state.delegations.some((delegation) => !/^hid_[a-f0-9]{64}$/.test(delegation.source_id) ||
+            !/^del_[0-9a-f-]{36}$/.test(delegation.delegation_id) ||
+            !/^gen_[0-9a-f-]{36}$/.test(delegation.child_generation_id) ||
+            !validOpenSpanState(delegation) ||
+            !/^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(delegation.role)) ||
+        state.spans.length > 256 ||
+        state.spans.some((span) => !/^hid_[a-f0-9]{64}$/.test(span.source_id) ||
+            !validOpenSpanState(span) ||
+            (span.recovery_reason !== undefined &&
+                !/^[a-z0-9][a-z0-9._-]{0,79}$/.test(span.recovery_reason)) ||
+            (span.turn_id !== undefined && !/^tid_[a-f0-9]{64}$/.test(span.turn_id)) ||
+            (span.turn_stamp !== undefined &&
+                span.turn_stamp !== "native_payload" &&
+                span.turn_stamp !== "producer_state") ||
+            (span.requested_event_id !== undefined &&
+                !/^evt_[0-9a-f-]{36}$/.test(span.requested_event_id)) ||
+            (span.semantic_key !== undefined && !/^hid_[a-f0-9]{64}$/.test(span.semantic_key)) ||
+            (span.tool_name !== undefined &&
+                !/^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(span.tool_name))) ||
+        !Array.isArray(state.closed_spans) ||
+        state.closed_spans.length > CLOSED_SPAN_MEMORY_CAP ||
+        state.closed_spans.some((closed) => !/^hid_[a-f0-9]{64}$/.test(closed.source_id) ||
+            (closed.semantic_key !== undefined && !/^hid_[a-f0-9]{64}$/.test(closed.semantic_key)) ||
+            !/^span_[0-9a-f-]{36}$/.test(closed.span_id) ||
+            !/^evt_[0-9a-f-]{36}$/.test(closed.closed_event_id) ||
+            !Number.isSafeInteger(closed.turn_ordinal) ||
+            closed.turn_ordinal < 0) ||
+        !Array.isArray(state.closed_turn_ids) ||
+        state.closed_turn_ids.length > CLOSED_TURN_MEMORY_CAP ||
+        state.closed_turn_ids.some((turnId) => !/^tid_[a-f0-9]{64}$/.test(turnId)) ||
+        !Array.isArray(state.waits) ||
+        state.waits.length > 256 ||
+        state.waits.some((wait) => !/^hid_[a-f0-9]{64}$/.test(wait.wait_id) ||
+            !/^evt_[0-9a-f-]{36}$/.test(wait.started_event_id) ||
+            !/^tid_[a-f0-9]{64}$/.test(wait.turn_id) ||
+            !validOpenSpanState(wait)) ||
+        !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.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?.source_id !== undefined &&
+            !/^hid_[a-f0-9]{64}$/.test(state.pending.source_id)) ||
+        (state.pending && !validateEventV3(state.pending.event).ok)) {
+        throw new Error("V3 producer state is invalid");
+    }
+    return state;
+}
+function recordTurnHarnessTiming(state, input, resetForTurnStart = true) {
+    if (input.signal === "user-prompt-submit" && resetForTurnStart) {
+        state.turn_harness = emptyTurnHarnessTiming();
+    }
+    if (input.hook_duration_ms === undefined ||
+        (!state.current_turn_id && input.signal !== "user-prompt-submit")) {
+        return;
+    }
+    const duration = Math.max(0, Math.floor(input.hook_duration_ms));
+    if (!Number.isSafeInteger(duration))
+        return;
+    const hook = safeRole(input.hook_name ?? input.signal);
+    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 ? hook : state.turn_harness.slowest_hook,
+        slowest_hook_ms: Math.max(duration, state.turn_harness.slowest_hook_ms),
+    };
+}
+/**
+ * Concurrent hook processes can acquire the session lease in a different
+ * order from their clock capture. Preserve raw readings in span state for
+ * pairing, but omit an out-of-order reading from the producer event chain so
+ * a valid global clock is never asserted falsely.
+ */
+function orderedEventMonotonic(state, candidate) {
+    if (!candidate || !/^\d+$/.test(candidate))
+        return undefined;
+    if (!state.last_monotonic_ns)
+        return candidate;
+    return BigInt(candidate) < BigInt(state.last_monotonic_ns) ? undefined : candidate;
+}
+function emptyTurnHarnessTiming() {
+    return { hook_time_ms: 0, hook_count: 0, slowest_hook_ms: 0 };
+}
+function validOpenSpanState(value) {
+    return Boolean(value &&
+        /^span_[0-9a-f-]{36}$/.test(value.span_id) &&
+        (value.parent_span_id === undefined || /^span_[0-9a-f-]{36}$/.test(value.parent_span_id)) &&
+        Number.isFinite(Date.parse(value.opened_at)) &&
+        /^boot_[a-zA-Z0-9._-]+$/.test(value.boot_id) &&
+        (value.opened_monotonic_ns === undefined || /^\d+$/.test(value.opened_monotonic_ns)) &&
+        (value.open_event_id === undefined || /^evt_[0-9a-f-]{36}$/.test(value.open_event_id)));
+}
+function validTurnHarnessTiming(value) {
+    return (Number.isSafeInteger(value.hook_time_ms) &&
+        value.hook_time_ms >= 0 &&
+        Number.isSafeInteger(value.hook_count) &&
+        value.hook_count >= 0 &&
+        Number.isSafeInteger(value.slowest_hook_ms) &&
+        value.slowest_hook_ms >= 0 &&
+        (value.slowest_hook === undefined ||
+            /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(value.slowest_hook)));
+}
+function pidIsAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}