@ironbee-ai/cli 0.6.2 → 0.7.0

package/dist/analytics/emit.js

@@ -0,0 +1,901 @@
+"use strict";
+/**
+ * IronBee CLI — Analytics Emit Orchestrator
+ *
+ * Per-trigger algorithm:
+ *
+ *   1. Load state (or initialState on miss)
+ *   2. Reset detection: schema_version, inode, size, first-KB hash
+ *   3. Tail-parse new transcript bytes (with truncate-during-read sanity)
+ *   4. Turn-safe boundary detection
+ *   5. Project delta + merge into accumulated
+ *   6. Substantive filter
+ *   7. Idempotency check (offset + final-flag)
+ *   8. EMIT-FIRST then atomic-rename state file
+ *
+ * Hook adapters call {@link emitAnalytics} after their existing primary
+ * work; failures here log and swallow — never affect the hook outcome.
+ *
+ * Submission goes DIRECTLY to the collector (`src/lib/collector.ts:sendToCollector`)
+ * — bypasses the queue intentionally. The queue's 4 KB per-line limit fits
+ * `tool_call` events but is too tight for full session aggregates. Direct
+ * HTTPS POST has no size limit; emit's own retry semantics (state isn't
+ * advanced on submit failure → next trigger retries) replace the queue's
+ * retry layer for this event type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__test = void 0;
+exports.emitAnalytics = emitAnalytics;
+const logger_1 = require("../lib/logger");
+const actions_1 = require("../hooks/core/actions");
+const types_1 = require("./types");
+const transcript_1 = require("./transcript");
+const state_1 = require("./state");
+const merge_1 = require("./merge");
+const projection_1 = require("./projection");
+const collector_1 = require("../lib/collector");
+const config_1 = require("../lib/config");
+/**
+ * Drive a full per-trigger projection and (maybe) emit. Fail-safe:
+ * any internal exception is caught + logged + swallowed; returns an
+ * outcome describing what happened.
+ */
+async function emitAnalytics(opts) {
+    try {
+        return await runEmit(opts);
+    }
+    catch (e) {
+        logger_1.logger.debug(`analytics emit: unexpected error: ${e instanceof Error ? e.message : e}`);
+        return { status: "error", reason: e instanceof Error ? e.message : String(e) };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Internal: the algorithm
+// ─────────────────────────────────────────────────────────────────────────
+async function runEmit(opts) {
+    const { projectDir, sessionId, triggerType, endReason, log } = opts;
+    const isFinal = triggerType === "SessionEnd";
+    const transcriptSource = opts.transcriptSource ?? "claude-code";
+    const projectName = (0, actions_1.resolveProjectName)(projectDir);
+    // Per-event-type opt-ins (default false). Resolved once per emit so the
+    // gating decisions in the projection / force-close / drain branches
+    // below all see a consistent snapshot of the operator's config.
+    const turnEventsEnabled = (0, config_1.isAnalyticsTurnEventsEnabled)(projectDir);
+    const stepEventsEnabled = (0, config_1.isAnalyticsStepEventsEnabled)(projectDir);
+    const apiRequestEventsEnabled = (0, config_1.isAnalyticsApiRequestEventsEnabled)(projectDir);
+    log?.debug(`gating: emitTurnEvents=${turnEventsEnabled} emitStepEvents=${stepEventsEnabled} emitApiRequestEvents=${apiRequestEventsEnabled}`);
+    // ── Resolve transcript path ──────────────────────────────────────────
+    const transcriptPath = transcriptSource === "claude-code"
+        ? (0, transcript_1.findClaudeTranscriptPath)(projectDir, sessionId)
+        : null; // Cursor TBD — return early below
+    if (transcriptPath === null) {
+        logger_1.logger.debug(`analytics emit: transcript not found for session ${sessionId}`);
+        log?.warn(`transcript: not found (source=${transcriptSource}) — skipping`);
+        return { status: "no-transcript", reason: "transcript path unresolved or missing" };
+    }
+    log?.info(`transcript: path=${transcriptPath} source=${transcriptSource} project=${projectName}`);
+    // ── 1. Load state (or fresh init) ────────────────────────────────────
+    const loaded = (0, state_1.readState)(projectDir, sessionId);
+    let state = loaded
+        ?? (0, state_1.initialState)(sessionId, transcriptPath, projectName, transcriptSource);
+    if (loaded) {
+        log?.info(`state: loaded offset=${loaded.offset} last_emitted_offset=${loaded.last_emitted_offset} `
+            + `last_emitted_is_final=${loaded.last_emitted_is_final} schema=${loaded.accumulated.schema_version} `
+            + `user_count=${loaded.accumulated.turns.user_count} duration_min=${loaded.accumulated.time.duration_minutes}`);
+    }
+    else {
+        log?.info("state: fresh init (no existing state.json)");
+    }
+    // ── 2. Reset detection ───────────────────────────────────────────────
+    let stat;
+    try {
+        stat = (0, transcript_1.statTranscript)(transcriptPath);
+    }
+    catch (e) {
+        logger_1.logger.debug(`analytics emit: stat failed for ${transcriptPath}: ${e instanceof Error ? e.message : e}`);
+        log?.error(`transcript: stat failed: ${e instanceof Error ? e.message : e}`);
+        return { status: "no-transcript", reason: "stat failed (file missing or unreadable)" };
+    }
+    // For the reset check we MUST hash the SAME byte range that produced
+    // the recorded `transcript_first_kb_sha256`. Recorded hash covered
+    // min(1024, transcript_size_at_last_read) bytes — using a different
+    // range here would spuriously trigger "content_replaced" on growing
+    // small files (size < 1KB) where the new hash naturally covers more
+    // bytes. The fresh persist below uses min(1024, current size) so the
+    // window expands as the file grows past 1KB and locks at 1KB after.
+    const recordedHashLen = Math.min(transcript_1.FIRST_KB_HASH_LENGTH, state.transcript_size_at_last_read);
+    const currentRecheckHash = recordedHashLen > 0
+        ? (0, transcript_1.firstKbSha256)(transcriptPath, recordedHashLen)
+        : "";
+    const currentFirstKbHash = (0, transcript_1.firstKbSha256)(transcriptPath);
+    log?.debug(`transcript: stat inode=${stat.inode} size=${stat.size} first_kb_hash=${currentFirstKbHash.slice(0, 12)}…`);
+    let resetReason = null;
+    if (state.accumulated.schema_version !== types_1.SCHEMA_VERSION) {
+        resetReason = "schema_version_changed";
+    }
+    else if (stat.inode !== state.transcript_inode && state.transcript_inode !== 0) {
+        resetReason = "inode_changed";
+    }
+    else if (stat.size < state.offset) {
+        resetReason = "size_shrunk";
+    }
+    else if (currentRecheckHash !== ""
+        && state.transcript_first_kb_sha256 !== ""
+        && currentRecheckHash !== state.transcript_first_kb_sha256) {
+        resetReason = "content_replaced";
+    }
+    if (resetReason !== null) {
+        logger_1.logger.debug(`analytics emit: reset state for session ${sessionId}: ${resetReason}`);
+        log?.warn(`reset: ${resetReason} — discarding accumulated state and re-parsing from offset 0`);
+        state = (0, state_1.initialState)(sessionId, transcriptPath, projectName, transcriptSource);
+        // Re-stat after reset to capture current values.
+        stat = (0, transcript_1.statTranscript)(transcriptPath);
+    }
+    // ── 2b. SessionEnd carve-out for stat.size == state.offset ──────────
+    let cameFromCarveOut = false;
+    let consumedLines = [];
+    let merged = state.accumulated;
+    let newInternal = state.internal;
+    let readSize = stat.size;
+    let boundaryOffset = state.offset;
+    if (stat.size === state.offset) {
+        if (!isFinal) {
+            log?.debug(`carve-out: no new bytes (offset=${state.offset}) and trigger=Stop — skipping`);
+            return { status: "skipped", reason: "no new bytes" };
+        }
+        if (state.last_emitted_is_final) {
+            log?.debug("carve-out: session already finalized — skipping");
+            return { status: "skipped", reason: "session already finalized" };
+        }
+        // Fall through with empty delta — emit is_final=true on existing accumulated.
+        cameFromCarveOut = true;
+        readSize = state.offset;
+        log?.info(`carve-out: SessionEnd with no new bytes (offset=${state.offset}) — emitting is_final on existing accumulated`);
+        // Skip steps 3-5; merged stays = state.accumulated, internal unchanged.
+    }
+    else {
+        // ── 3. Read new bytes (with truncate-during-read sanity) ────────
+        const slice = (0, transcript_1.readSlice)(transcriptPath, state.offset, stat.size);
+        if (slice.truncated) {
+            logger_1.logger.debug(`analytics emit: file truncated mid-read (session ${sessionId}); deferring to next trigger`);
+            log?.warn(`read: file truncated mid-read (offset=${state.offset}, expected_end=${stat.size}) — deferring`);
+            return { status: "skipped", reason: "truncated mid-read; eventual consistency" };
+        }
+        readSize = stat.size;
+        log?.debug(`read: bytes=${slice.bytes.length} (offset ${state.offset} → ${stat.size})`);
+        // ── 4. Parse + boundary detection ───────────────────────────────
+        const parseResult = (0, transcript_1.parseJsonl)(slice.bytes, state.offset);
+        boundaryOffset = (0, transcript_1.findTurnSafeBoundary)(parseResult.lines, parseResult.last_complete_byte, isFinal);
+        log?.debug(`parse: lines=${parseResult.lines.length} last_complete_byte=${parseResult.last_complete_byte} `
+            + `boundary_offset=${boundaryOffset} is_final=${isFinal}`);
+        // ── 5. Project + merge ──────────────────────────────────────────
+        consumedLines = parseResult.lines.filter((ln) => ln.parsed !== null && ln.end <= boundaryOffset);
+        const linesForProjection = consumedLines
+            .filter((ln) => ln.parsed !== null)
+            .map((ln) => ln.parsed);
+        // Cross-slice idle attribution needs the prior session's last
+        // activity timestamp. Parse from accumulated.last_activity_time —
+        // empty / unparseable → undefined (first slice case).
+        const priorLastActivityParsed = state.accumulated.last_activity_time !== ""
+            ? Date.parse(state.accumulated.last_activity_time)
+            : Number.NaN;
+        const priorLastActivityTsMs = Number.isFinite(priorLastActivityParsed)
+            ? priorLastActivityParsed
+            : undefined;
+        const projectionInput = {
+            lines: linesForProjection,
+            startingTurnIndex: state.accumulated.turns.assistant_count + 1,
+            sessionId,
+            projectName,
+            transcriptSource,
+            priorLastAssistantTsMs: state.internal.last_assistant_ts_ms,
+            priorPendingToolUses: state.internal.pending_tool_uses,
+            priorLastActivityTsMs,
+            priorCurrentTurn: state.internal.current_turn,
+            priorNextTurnIndex: state.internal.next_turn_index,
+            priorSeenAssistantMessageIds: state.internal.seen_assistant_message_ids,
+        };
+        const delta = (0, projection_1.projectDelta)(projectionInput);
+        const deltaInternal = (0, projection_1.projectDeltaInternal)(projectionInput);
+        // Gate per-event-type opt-ins BEFORE merge: drop completed turn / step
+        // records from the delta when the flag is off so the pending queues
+        // never accumulate them. Session-level aggregation upstream of
+        // `delta.completed_turns` (turns_with_retry, one_shot_turns,
+        // category_breakdown) is unaffected — projection has already folded
+        // those into the delta's session-level fields.
+        if (!turnEventsEnabled && delta.completed_turns.length > 0) {
+            log?.debug(`gating: emitTurnEvents=false → dropping ${delta.completed_turns.length} completed turn(s) from delta`);
+            delta.completed_turns = [];
+        }
+        if (!stepEventsEnabled && delta.completed_steps.length > 0) {
+            log?.debug(`gating: emitStepEvents=false → dropping ${delta.completed_steps.length} completed step(s) from delta`);
+            delta.completed_steps = [];
+        }
+        if (!apiRequestEventsEnabled && delta.api_request_events.length > 0) {
+            log?.debug(`gating: emitApiRequestEvents=false → dropping ${delta.api_request_events.length} api_request event(s) from delta`);
+            delta.api_request_events = [];
+        }
+        log?.debug(`delta: user_count+=${delta.turns.user_count} assistant_msgs+=${delta.turns.assistant_count} `
+            + `tool_uses=${Object.values(delta.tools).reduce((a, t) => a + t.count, 0)} `
+            + `files_modified+=${delta.code_changes.files_modified} lines_added+=${delta.code_changes.lines_added} lines_removed+=${delta.code_changes.lines_removed} `
+            + `errors+=${delta.errors.tool_errors_total} interruptions+=${delta.errors.user_interruptions} `
+            + `pending_tool_uses=${Object.keys(delta.closing_pending_tool_uses).length}`);
+        const result = (0, merge_1.mergeAccumulated)(state.accumulated, state.internal, delta, deltaInternal);
+        merged = result.accumulated;
+        newInternal = result.internal;
+        const mergedToolCalls = Object.values(merged.tools).reduce((a, t) => a + t.count, 0);
+        log?.debug(`merged: user_count=${merged.turns.user_count} duration_min=${merged.time.duration_minutes.toFixed(2)} `
+            + `tool_calls=${mergedToolCalls} files_modified=${merged.code_changes.files_modified} `
+            + `lines_added=${merged.code_changes.lines_added} lines_removed=${merged.code_changes.lines_removed} `
+            + `ctx_latest=${merged.context_tokens.latest} ctx_peak=${merged.context_tokens.peak}`);
+    }
+    // ── Resolve collector target ONCE per emit ──────────────────────────
+    // Avoid N redundant `loadConfig` fs reads (each drainPendingTurns /
+    // drainPendingSteps invocation, plus each per-batch
+    // sendEventsBatchToCollector call inside them, would otherwise re-read
+    // config from disk).
+    const collectorTarget = (0, collector_1.getCollectorTarget)(projectDir);
+    // ── 7. Idempotency check (offset + final-flag) ──────────────────────
+    const effectiveOffset = cameFromCarveOut ? state.offset : boundaryOffset;
+    const sameOffset = effectiveOffset === state.last_emitted_offset;
+    const finalNewlyTrue = isFinal && !state.last_emitted_is_final;
+    if (sameOffset && !finalNewlyTrue) {
+        // Idempotency: same offset + same final-flag → no new session_analytics
+        // payload to send. BUT if there are pending_turn_events OR
+        // pending_step_events queued from a prior trigger (session_analytics
+        // succeeded but individual turn / step sends failed), drain them
+        // here. Otherwise queues would only retry when fresh transcript
+        // bytes arrived — for an idle session they would stagnate
+        // indefinitely. Backend dedupes via deterministic turn_id /
+        // step_id so re-sends are safe.
+        //
+        // Force-close pre-flight: under Stop-closes-turn semantics every
+        // successful prior emit clears `current_turn` from state, so
+        // normally there is none to close here. But if state was restored
+        // from a sub-substantive snapshot (or other partial-persist edge
+        // case), an open turn might be carried over. Run the same §7b
+        // logic so the queue drain below covers it. Empty (0-assistant)
+        // turns are intentionally skipped — see §7b for the rationale.
+        if (newInternal.current_turn !== undefined && newInternal.current_turn.assistant_messages > 0) {
+            const openTurnState = newInternal.current_turn;
+            const closeEndTime = openTurnState.last_activity_time !== ""
+                ? openTurnState.last_activity_time
+                : merged.last_activity_time;
+            const triggerEndReason = isFinal ? "session_end" : "stop";
+            const r = (0, projection_1.closeTurn)(openTurnState, {
+                endTime: closeEndTime,
+                endReason: triggerEndReason,
+                sessionId, projectName, transcriptSource,
+            });
+            (0, projection_1.applyBreakdownDelta)(merged.classification.category_breakdown, r);
+            merged.turns.with_retry += r.turns_with_retry_inc;
+            merged.turns.one_shot += r.one_shot_inc;
+            // Gate per-event-type opt-ins: session-level aggregates above
+            // (category_breakdown, turns.with_retry, turns.one_shot) are
+            // ALWAYS applied — they belong to session_analytics. The wire
+            // records below (turn_event, step_events) only push to their
+            // pending queues when the corresponding flag is on.
+            const finalQueue = turnEventsEnabled
+                ? [...(newInternal.pending_turn_events ?? []), r.turn_event]
+                : (newInternal.pending_turn_events ?? []);
+            const finalStepQueue = stepEventsEnabled && r.step_events.length > 0
+                ? [...(newInternal.pending_step_events ?? []), ...r.step_events]
+                : (newInternal.pending_step_events ?? []);
+            newInternal = {
+                ...newInternal,
+                ...(finalQueue.length > 0 ? { pending_turn_events: finalQueue } : {}),
+                ...(finalStepQueue.length > 0 ? { pending_step_events: finalStepQueue } : {}),
+            };
+            delete newInternal.current_turn;
+            log?.debug(`force-close (idempotent path): turn_index=${r.turn_event.turn_index} `
+                + `turn_id=${r.turn_event.turn_id} end_reason=${triggerEndReason} `
+                + `category=${r.turn_event.category} duration=${r.turn_event.duration}ms `
+                + `step_events=${r.step_events.length} `
+                + `gates: turn=${turnEventsEnabled} step=${stepEventsEnabled}`);
+        }
+        else if (newInternal.current_turn !== undefined) {
+            // Open turn with 0 assistants — drop silently. Decrement
+            // merged.turns.user_count so the session-level count matches
+            // the number of turn events the backend will actually see.
+            const dropped = newInternal.current_turn;
+            log?.debug(`force-close (idempotent path): skipping empty turn `
+                + `turn_index=${dropped.turn_index} (assistant_messages=0)`);
+            if (merged.turns.user_count > 0) {
+                merged.turns.user_count -= 1;
+            }
+            newInternal = { ...newInternal };
+            delete newInternal.current_turn;
+        }
+        const queuedTurns = newInternal.pending_turn_events ?? [];
+        const queuedSteps = newInternal.pending_step_events ?? [];
+        const queuedApiRequests = newInternal.pending_api_request_events ?? [];
+        if (queuedTurns.length === 0 && queuedSteps.length === 0 && queuedApiRequests.length === 0) {
+            const persistedState = {
+                ...state,
+                offset: effectiveOffset,
+                accumulated: merged,
+                internal: newInternal,
+                last_read_at: new Date().toISOString(),
+                transcript_inode: cameFromCarveOut ? state.transcript_inode : stat.inode,
+                transcript_size_at_last_read: cameFromCarveOut ? state.transcript_size_at_last_read : readSize,
+                transcript_first_kb_sha256: cameFromCarveOut ? state.transcript_first_kb_sha256 : currentFirstKbHash,
+            };
+            (0, state_1.writeState)(projectDir, sessionId, persistedState);
+            log?.info(`skip: idempotent — offset=${effectiveOffset} matches last_emitted_offset and is_final unchanged`);
+            return { status: "skipped", reason: "offset unchanged and final-flag unchanged" };
+        }
+        // Drain-only path: re-attempt every queued turn + step + api_request
+        // via the shared helpers. State is persisted with the residual queues
+        // so the next trigger can keep retrying.
+        log?.info(`idempotent-with-drain: offset=${effectiveOffset} pending_turn_events=${queuedTurns.length} `
+            + `pending_step_events=${queuedSteps.length} pending_api_request_events=${queuedApiRequests.length} — attempting drain`);
+        const drainBase = (0, actions_1.baseFields)(`${projectDir}/.ironbee/sessions/${sessionId}/actions.jsonl`);
+        let postDrainInternal = newInternal;
+        let turnDrainSent = 0;
+        let stepDrainSent = 0;
+        let apiRequestDrainSent = 0;
+        let turnDrainRetained = queuedTurns.length;
+        let stepDrainRetained = queuedSteps.length;
+        let apiRequestDrainRetained = queuedApiRequests.length;
+        // Defense-in-depth: when the per-event-type flag is OFF but the
+        // queue carries stale events from a prior session/state.json (e.g.
+        // operator just toggled the flag from true to false), DROP without
+        // sending — the contract is "flag false ⇒ zero events on the wire."
+        // The remainder is cleared from state so subsequent triggers don't
+        // re-attempt. (When the flag was already false during projection,
+        // the queues are empty and this branch is a no-op.)
+        if (queuedTurns.length > 0) {
+            if (turnEventsEnabled) {
+                const drain = await drainPendingTurns(queuedTurns, drainBase, sessionId, projectDir, log, "drain submit", collectorTarget);
+                postDrainInternal = withPendingTurnEvents(postDrainInternal, drain.remaining);
+                turnDrainSent = drain.sent;
+                turnDrainRetained = drain.remaining.length;
+            }
+            else {
+                log?.info(`gating: emitTurnEvents=false → dropping ${queuedTurns.length} stale pending turn event(s) without sending`);
+                postDrainInternal = withPendingTurnEvents(postDrainInternal, []);
+                turnDrainRetained = 0;
+            }
+        }
+        if (queuedSteps.length > 0) {
+            if (stepEventsEnabled) {
+                const stepDrain = await drainPendingSteps(queuedSteps, drainBase, sessionId, projectDir, log, "drain submit", collectorTarget);
+                postDrainInternal = withPendingStepEvents(postDrainInternal, stepDrain.remaining);
+                stepDrainSent = stepDrain.sent;
+                stepDrainRetained = stepDrain.remaining.length;
+            }
+            else {
+                log?.info(`gating: emitStepEvents=false → dropping ${queuedSteps.length} stale pending step event(s) without sending`);
+                postDrainInternal = withPendingStepEvents(postDrainInternal, []);
+                stepDrainRetained = 0;
+            }
+        }
+        if (queuedApiRequests.length > 0) {
+            if (apiRequestEventsEnabled) {
+                const apiDrain = await drainPendingApiRequests(queuedApiRequests, drainBase, sessionId, projectDir, log, "drain submit", collectorTarget);
+                postDrainInternal = withPendingApiRequestEvents(postDrainInternal, apiDrain.remaining);
+                apiRequestDrainSent = apiDrain.sent;
+                apiRequestDrainRetained = apiDrain.remaining.length;
+            }
+            else {
+                log?.info(`gating: emitApiRequestEvents=false → dropping ${queuedApiRequests.length} stale pending api_request event(s) without sending`);
+                postDrainInternal = withPendingApiRequestEvents(postDrainInternal, []);
+                apiRequestDrainRetained = 0;
+            }
+        }
+        const persistedState = {
+            ...state,
+            offset: effectiveOffset,
+            accumulated: merged,
+            internal: postDrainInternal,
+            last_read_at: new Date().toISOString(),
+            transcript_inode: cameFromCarveOut ? state.transcript_inode : stat.inode,
+            transcript_size_at_last_read: cameFromCarveOut ? state.transcript_size_at_last_read : readSize,
+            transcript_first_kb_sha256: cameFromCarveOut ? state.transcript_first_kb_sha256 : currentFirstKbHash,
+        };
+        (0, state_1.writeState)(projectDir, sessionId, persistedState);
+        log?.info(`idempotent-with-drain: turn_sent=${turnDrainSent}/${queuedTurns.length} retained=${turnDrainRetained} `
+            + `step_sent=${stepDrainSent}/${queuedSteps.length} retained=${stepDrainRetained} `
+            + `api_request_sent=${apiRequestDrainSent}/${queuedApiRequests.length} retained=${apiRequestDrainRetained}`);
+        const reasonParts = ["offset unchanged"];
+        if (queuedTurns.length > 0) {
+            reasonParts.push(`drained ${turnDrainSent}/${queuedTurns.length} pending turn events`);
+        }
+        if (queuedSteps.length > 0) {
+            reasonParts.push(`drained ${stepDrainSent}/${queuedSteps.length} pending step events`);
+        }
+        if (queuedApiRequests.length > 0) {
+            reasonParts.push(`drained ${apiRequestDrainSent}/${queuedApiRequests.length} pending api_request events`);
+        }
+        return { status: "skipped", reason: reasonParts.join("; ") };
+    }
+    // ── 7b. Force-close open turn on EVERY trigger ───────────────────────
+    // Claude Code's "Stop" semantically means the agent has finished its
+    // current task — for analytics purposes, each Stop = one completed
+    // agent run = one closed turn. SessionEnd is the same shape with a
+    // different `end_reason`. This eliminates the open-turn discipline's
+    // wait-for-next-prompt latency (without it, step events for the just-
+    // finished agent run would not flow until the user's next prompt).
+    //
+    // closeTurn is pure — we build the per-turn record + per-step events
+    // from the projection's in-flight `current_turn`, apply the per-
+    // category breakdown delta, then drop `current_turn` from the persisted
+    // state so the next slice's projection starts fresh at the next user
+    // message.
+    //
+    // `end_reason` reflects which trigger fired:
+    //   - SessionEnd → "session_end"
+    //   - Stop       → "stop"
+    //
+    // Guard: skip force-close when the open turn has zero assistant
+    // messages. Slash command host-meta filtering (isHumanTextUser →
+    // false on `<command-message>` blocks) eliminates the common cause
+    // of empty leading turns, but defense-in-depth: rare cases like
+    // host-killed-before-asst or a slice ending right at a user msg
+    // could still leave an empty open turn. Emitting it would pollute
+    // analytics with a 0-asst turn record (and 0 step events).
+    if (newInternal.current_turn !== undefined && newInternal.current_turn.assistant_messages > 0) {
+        const openTurnState = newInternal.current_turn;
+        const closeEndTime = openTurnState.last_activity_time !== ""
+            ? openTurnState.last_activity_time
+            : merged.last_activity_time;
+        const triggerEndReason = isFinal ? "session_end" : "stop";
+        const r = (0, projection_1.closeTurn)(openTurnState, {
+            endTime: closeEndTime,
+            endReason: triggerEndReason,
+            sessionId, projectName, transcriptSource,
+        });
+        (0, projection_1.applyBreakdownDelta)(merged.classification.category_breakdown, r);
+        merged.turns.with_retry += r.turns_with_retry_inc;
+        merged.turns.one_shot += r.one_shot_inc;
+        // Gate per-event-type opt-ins: session-level aggregates above are
+        // ALWAYS applied; the wire records only push when their flag is on.
+        const finalQueue = turnEventsEnabled
+            ? [...(newInternal.pending_turn_events ?? []), r.turn_event]
+            : (newInternal.pending_turn_events ?? []);
+        // Step events from this finalized turn — append to the step pending
+        // queue alongside any prior pending steps. The last entry in
+        // r.step_events carries `is_last_step=true` + the turn-bookend
+        // fields (turn_end_reason, turn_end_time, etc.).
+        const finalStepQueue = stepEventsEnabled && r.step_events.length > 0
+            ? [...(newInternal.pending_step_events ?? []), ...r.step_events]
+            : (newInternal.pending_step_events ?? []);
+        newInternal = {
+            ...newInternal,
+            ...(finalQueue.length > 0 ? { pending_turn_events: finalQueue } : {}),
+            ...(finalStepQueue.length > 0 ? { pending_step_events: finalStepQueue } : {}),
+        };
+        delete newInternal.current_turn;
+        log?.debug(`force-close: turn_index=${r.turn_event.turn_index} turn_id=${r.turn_event.turn_id} `
+            + `end_reason=${triggerEndReason} category=${r.turn_event.category} `
+            + `duration=${r.turn_event.duration}ms step_events=${r.step_events.length} `
+            + `gates: turn=${turnEventsEnabled} step=${stepEventsEnabled}`);
+    }
+    else if (newInternal.current_turn !== undefined) {
+        // Open turn with 0 assistants (defensive: the slash-command empty
+        // leading turn case is already filtered upstream in
+        // isHumanTextUser, so this is rare). Drop without emitting — a
+        // 0-asst turn carries no analytic signal and would only pollute
+        // the backend's per-turn series. Decrement merged.user_turns so the
+        // session-level count stays in sync with the wire — an inflated
+        // user_turns vs zero corresponding turn event would confuse backend
+        // dashboards.
+        const dropped = newInternal.current_turn;
+        log?.debug(`force-close: skipping empty turn turn_index=${dropped.turn_index} `
+            + `(assistant_messages=0) — no event emitted`);
+        if (merged.turns.user_count > 0) {
+            merged.turns.user_count -= 1;
+        }
+        newInternal = { ...newInternal };
+        delete newInternal.current_turn;
+    }
+    // ── 8. Compose snapshot, emit, then persist ─────────────────────────
+    // EMIT FIRST. Compose the full Event-shaped envelope. baseFields()
+    // populates id + session_id + project_name + user_email from the per-session
+    // actions.jsonl path; we add type + timestamp + the analytics body. This gives
+    // every IronBee event the same wire shape — collector schema stays uniform.
+    const actionsFile = `${projectDir}/.ironbee/sessions/${sessionId}/actions.jsonl`;
+    const base = (0, actions_1.baseFields)(actionsFile);
+    // Compose snapshot in canonical SessionAnalytics field order — per-trigger
+    // fields (`user_email`, `is_final`, `snapshot_at`, `offset`, `end_reason`)
+    // need to be slotted in their correct positions.
+    const snapshot = {
+        // Identity / provenance (flat)
+        session_id: merged.session_id,
+        project_name: merged.project_name,
+        // user_email is per-trigger composition (NOT in accumulated) — single
+        // source is `getUserEmail(sessionDir)` via baseFields. Omit when unset.
+        ...(base.user_email !== undefined ? { user_email: base.user_email } : {}),
+        schema_version: types_1.SCHEMA_VERSION,
+        transcript_source: merged.transcript_source,
+        // Snapshot metadata
+        is_final: isFinal,
+        snapshot_at: new Date().toISOString(),
+        offset: effectiveOffset,
+        end_reason: isFinal ? endReason : undefined,
+        // Time bounds (flat ISO strings)
+        start_time: merged.start_time,
+        last_activity_time: merged.last_activity_time,
+        // Logical groups
+        time: merged.time,
+        turns: merged.turns,
+        classification: merged.classification,
+        usage: merged.usage,
+        // Per-model + user_messages
+        models: merged.models,
+        user_messages: merged.user_messages,
+        // Per-tool breakdown maps (top-level)
+        tools: merged.tools,
+        mcp_servers: merged.mcp_servers,
+        skills: merged.skills,
+        sub_agents: merged.sub_agents,
+        bash_binaries: merged.bash_binaries,
+        // Group rollups
+        tool_meta: merged.tool_meta,
+        code_changes: merged.code_changes,
+        errors: merged.errors,
+        user_activity: merged.user_activity,
+        context_tokens: merged.context_tokens,
+        process_errors: merged.process_errors,
+    };
+    const eventPayload = {
+        ...base,
+        // Deterministic Event.id — re-emits at the same `(session_id, offset)`
+        // produce the same id so backend treats them as updates to the same
+        // logical checkpoint (interim → final, crash-recovery re-project,
+        // concurrent-worker race). `snapshot_at` lives in the body for
+        // collision tiebreaking, not in the id.
+        id: (0, projection_1.deriveSessionAnalyticsEventId)(merged.session_id, effectiveOffset),
+        type: actions_1.EventType.SESSION_ANALYTICS,
+        timestamp: Date.now(),
+        analytics: snapshot,
+    };
+    const wireBytes = Buffer.byteLength(JSON.stringify(eventPayload), "utf-8");
+    const totalToolCalls = Object.values(snapshot.tools).reduce((a, t) => a + t.count, 0);
+    const modelLabels = Object.entries(snapshot.models)
+        .sort((a, b) => b[1].count - a[1].count)
+        .map(([m, u]) => `${m}:${u.count}@$${u.cost_usd.toFixed(4)}`)
+        .join(",") || "none";
+    // Sort by output_size (best proxy for "tool footprint" / context
+    // contribution since per-tool cost isn't tracked).
+    const toolLabels = Object.entries(snapshot.tools)
+        .sort((a, b) => b[1].output_size - a[1].output_size)
+        .slice(0, 5)
+        .map(([n, u]) => `${n}:${u.count}/err${u.errors}/in:${u.input_size}/out:${u.output_size}`)
+        .join(",") || "none";
+    const mcpLabels = Object.entries(snapshot.mcp_servers)
+        .sort((a, b) => b[1].output_size - a[1].output_size)
+        .map(([n, u]) => `${n}:${u.count}/err${u.errors}/in:${u.input_size}/out:${u.output_size}`)
+        .join(",") || "none";
+    const errCount = Object.values(snapshot.process_errors.items)
+        .reduce((a, e) => a + e.count, 0);
+    const errSignatures = Object.keys(snapshot.process_errors.items).length;
+    const topCategories = Object.entries(snapshot.classification.category_breakdown)
+        .sort((a, b) => b[1].turns - a[1].turns)
+        .slice(0, 5)
+        .map(([n, c]) => `${n}:${c.turns}`)
+        .join(",") || "none";
+    log?.info(`submit: type=session_analytics event_id=${eventPayload.id} offset=${effectiveOffset} `
+        + `is_final=${isFinal}${endReason ? ` end_reason=${endReason}` : ""} `
+        + `wire_bytes=${wireBytes} user_count=${snapshot.turns.user_count} `
+        + `duration_min=${snapshot.time.duration_minutes} active_min=${snapshot.time.active_minutes} `
+        + `idle_min=${snapshot.time.idle_minutes} tool_calls=${totalToolCalls} `
+        + `session_type=${snapshot.classification.session_type} categories=${topCategories} `
+        + `retries=${snapshot.turns.with_retry} one_shot=${snapshot.turns.one_shot} `
+        + `tokens=in:${snapshot.usage.input_tokens}/out:${snapshot.usage.output_tokens}/`
+        + `cache_w:${snapshot.usage.cache_creation_tokens}/cache_r:${snapshot.usage.cache_read_tokens} `
+        + `cost_usd=${snapshot.usage.cost_usd.toFixed(4)} `
+        + `models=${modelLabels} mcp_servers=${mcpLabels} top_tools=${toolLabels}`
+        + (snapshot.process_errors.has ? ` process_errors=${errCount}/${errSignatures}` : ""));
+    let submitted = false;
+    try {
+        // Direct HTTPS POST to collector — bypasses the 4 KB queue line
+        // limit. `sendEventsBatchToCollector` no-ops silently when the
+        // collector is disabled / not configured. Throws on network /
+        // timeout / non-2xx responses; we leave state un-advanced so the
+        // next trigger retries. Single-event array here keeps the wire
+        // shape uniform with the turn / step batch path so the collector
+        // sees one consistent endpoint contract.
+        //
+        // Pass the once-resolved `collectorTarget` so the helper does not
+        // re-load config from disk (mirrors the drain helpers below).
+        await (0, collector_1.sendEventsBatchToCollector)([eventPayload], sessionId, projectDir, collectorTarget);
+        submitted = true;
+    }
+    catch (e) {
+        logger_1.logger.debug(`analytics emit: send failed: ${e instanceof Error ? e.message : e}`);
+        log?.error(`submit: failed event_id=${eventPayload.id}: ${e instanceof Error ? e.message : e}`);
+    }
+    // ── 8b. Drain pending_turn_events + pending_step_events AFTER ────────
+    //         session_analytics. Each SessionTurnEvent / SessionTurnStepEvent
+    //         goes out as its own POST (deterministic turn_id / step_id →
+    //         backend LWW deduplicates re-emits). Independent of the
+    //         session_analytics submission: failed entries stay in their
+    //         respective queue for retry next trigger; succeeded entries
+    //         are removed. We only attempt drain when session_analytics
+    //         succeeded — if the collector is unreachable for the primary
+    //         event, no point hammering it with N+M more requests; the
+    //         next trigger will retry the whole batch. Same helpers as the
+    //         §7 idempotency-skip path uses.
+    const pendingTurns = newInternal.pending_turn_events ?? [];
+    const pendingSteps = newInternal.pending_step_events ?? [];
+    if (submitted && pendingTurns.length > 0) {
+        if (turnEventsEnabled) {
+            const drain = await drainPendingTurns(pendingTurns, base, sessionId, projectDir, log, "submit", collectorTarget);
+            log?.info(`turn-events: sent=${drain.sent}/${pendingTurns.length} retained=${drain.remaining.length}`);
+            newInternal = withPendingTurnEvents(newInternal, drain.remaining);
+        }
+        else {
+            // Defense-in-depth: stale queue from a prior toggle-true state.
+            // Drop without sending so the contract holds; clear the queue
+            // so subsequent triggers don't re-process.
+            log?.info(`gating: emitTurnEvents=false → dropping ${pendingTurns.length} stale pending turn event(s) without sending`);
+            newInternal = withPendingTurnEvents(newInternal, []);
+        }
+    }
+    if (submitted && pendingSteps.length > 0) {
+        if (stepEventsEnabled) {
+            const stepDrain = await drainPendingSteps(pendingSteps, base, sessionId, projectDir, log, "submit", collectorTarget);
+            log?.info(`step-events: sent=${stepDrain.sent}/${pendingSteps.length} retained=${stepDrain.remaining.length}`);
+            newInternal = withPendingStepEvents(newInternal, stepDrain.remaining);
+        }
+        else {
+            log?.info(`gating: emitStepEvents=false → dropping ${pendingSteps.length} stale pending step event(s) without sending`);
+            newInternal = withPendingStepEvents(newInternal, []);
+        }
+    }
+    // Per-API-request drain — same gate/drop pattern as turn/step. Only attempt
+    // when session_analytics succeeded; on submit failure leave queue intact.
+    const pendingApiRequests = newInternal.pending_api_request_events ?? [];
+    if (submitted && pendingApiRequests.length > 0) {
+        if (apiRequestEventsEnabled) {
+            const apiDrain = await drainPendingApiRequests(pendingApiRequests, base, sessionId, projectDir, log, "submit", collectorTarget);
+            log?.info(`api-request-events: sent=${apiDrain.sent}/${pendingApiRequests.length} retained=${apiDrain.remaining.length}`);
+            newInternal = withPendingApiRequestEvents(newInternal, apiDrain.remaining);
+        }
+        else {
+            log?.info(`gating: emitApiRequestEvents=false → dropping ${pendingApiRequests.length} stale pending api_request event(s) without sending`);
+            newInternal = withPendingApiRequestEvents(newInternal, []);
+        }
+    }
+    // (When submitted is false, all three queues stay intact for next trigger.)
+    if (submitted) {
+        // THEN write state. A crash between send and write means the next
+        // trigger re-derives the same delta and re-sends — backend's LWW
+        // overwrites with identical content (idempotent). No data loss.
+        const persistedState = {
+            session_id: sessionId,
+            transcript_path: transcriptPath,
+            transcript_inode: cameFromCarveOut ? state.transcript_inode : stat.inode,
+            transcript_size_at_last_read: cameFromCarveOut ? state.transcript_size_at_last_read : readSize,
+            transcript_first_kb_sha256: cameFromCarveOut ? state.transcript_first_kb_sha256 : currentFirstKbHash,
+            offset: effectiveOffset,
+            last_read_at: new Date().toISOString(),
+            last_emitted_offset: effectiveOffset,
+            last_emitted_is_final: isFinal,
+            accumulated: merged,
+            internal: newInternal,
+        };
+        (0, state_1.writeState)(projectDir, sessionId, persistedState);
+        log?.info(`state persisted: offset=${effectiveOffset} last_emitted_offset=${effectiveOffset} last_emitted_is_final=${isFinal}`);
+        return { status: "emitted", reason: isFinal ? "final snapshot" : "interim snapshot", offset: effectiveOffset };
+    }
+    return { status: "error", reason: "submit failed; state not advanced" };
+}
+/**
+ * Default per-POST batch size for turn / step drains. Used when
+ * `collector.batchSize` isn't configured. Mirrors the default used by
+ * the queue's `send-event` handler (`DEFAULT_BATCH_SIZE = 100`).
+ *
+ * Why batched POSTs: a 100-turn (or 100-step) drain at 1 event per POST
+ * = 100 RTTs ≈ 20s sequential or ~2.5s with concurrency 8 — easily
+ * exceeds the host's SessionEnd hook timeout. Batching collapses that
+ * to 1 RTT (~200ms) for the same payload size, fitting comfortably in
+ * any reasonable hook budget.
+ */
+const DEFAULT_DRAIN_BATCH_SIZE = 100;
+/** Resolves the configured `collector.batchSize` or falls back to the default. */
+function resolveBatchSize(target) {
+    if (typeof target.batchSize === "number" && target.batchSize >= 1) {
+        return Math.floor(target.batchSize);
+    }
+    return DEFAULT_DRAIN_BATCH_SIZE;
+}
+/**
+ * Batched POST of every queued turn event to the collector. Events are
+ * chunked into {@link resolveBatchSize}-sized slices and each slice is
+ * sent as a SINGLE HTTP POST containing the full array — collapses an
+ * N-event drain from N RTTs to ~`ceil(N/batchSize)` RTTs.
+ *
+ * Per-batch failure granularity: if a batch POST fails (network /
+ * timeout / non-2xx), every event in that batch is retained for the
+ * next trigger. Backend deduplicates via deterministic `turn_id` so
+ * re-sending events that were partially delivered (collector accepted
+ * some but the response was lost) is safe.
+ *
+ * Pure with respect to `state.json` — caller is responsible for
+ * persisting `remaining` back into `state.internal.pending_turn_events`.
+ */
+async function drainPendingTurns(pending, base, sessionId, projectDir, log, logPrefix, target) {
+    const events = pending.map((turn) => ({
+        ...base,
+        // Deterministic — derived from turn_id (sha256(session|index|start)).
+        // Re-emits of the same turn produce the same Event.id.
+        id: (0, projection_1.deriveTurnEventId)(sessionId, turn.turn_id),
+        type: actions_1.EventType.SESSION_TURN,
+        timestamp: Date.now(),
+        turn,
+    }));
+    // Resolve batch size from collector config (default 100). When the
+    // collector isn't configured, sendEventsBatchToCollector is a silent
+    // no-op below — but we still chunk by some sensible default to keep
+    // the loop bounded.
+    const batchSize = target !== null ? resolveBatchSize(target) : DEFAULT_DRAIN_BATCH_SIZE;
+    const remaining = [];
+    let sent = 0;
+    for (let i = 0; i < events.length; i += batchSize) {
+        const batchEnd = Math.min(i + batchSize, events.length);
+        const batch = events.slice(i, batchEnd);
+        const batchPending = pending.slice(i, batchEnd);
+        try {
+            await (0, collector_1.sendEventsBatchToCollector)(batch, sessionId, projectDir, target);
+            sent += batch.length;
+            log?.debug(`${logPrefix}: type=session_turn_analytics batch_count=${batch.length} `
+                + `first_turn_index=${batchPending[0].turn_index}`);
+        }
+        catch (e) {
+            // Whole-batch retain on failure — backend dedupes via turn_id
+            // so re-sending events that may have partially landed is safe.
+            for (const t of batchPending) {
+                remaining.push(t);
+            }
+            logger_1.logger.debug(`analytics emit: turn batch send failed: ${e instanceof Error ? e.message : e}`);
+            log?.error(`${logPrefix} failed: type=session_turn_analytics batch_count=${batch.length}: `
+                + `${e instanceof Error ? e.message : e}`);
+        }
+    }
+    return { sent, remaining };
+}
+/**
+ * Apply a `DrainResult` back onto an `internal` map. Returns a fresh
+ * internal copy with `pending_turn_events` either replaced (still has
+ * remaining items) or fully removed (queue cleared).
+ */
+function withPendingTurnEvents(internal, remaining) {
+    if (remaining.length > 0) {
+        return { ...internal, pending_turn_events: remaining };
+    }
+    const next = { ...internal };
+    delete next.pending_turn_events;
+    return next;
+}
+/**
+ * Batched POST of every queued step event. Mirrors {@link drainPendingTurns}
+ * one level deeper. Step queues are typically larger (N×K entries — N
+ * turns × K steps/turn) so batching is the bigger win here: a 100-step
+ * drain becomes a single ~200ms POST instead of 100 round-trips.
+ *
+ * Per-batch failure: every event in the failed batch is retained for
+ * retry. Backend dedupes via deterministic `step_id` so re-sends are
+ * idempotent.
+ */
+async function drainPendingSteps(pending, base, sessionId, projectDir, log, logPrefix, target) {
+    const events = pending.map((step) => ({
+        ...base,
+        // Deterministic — derived from step_id (sha256(turn|index|start)).
+        // Re-emits of the same step produce the same Event.id.
+        id: (0, projection_1.deriveStepEventId)(sessionId, step.step_id),
+        type: actions_1.EventType.SESSION_TURN_STEP,
+        timestamp: Date.now(),
+        step,
+    }));
+    const batchSize = target !== null ? resolveBatchSize(target) : DEFAULT_DRAIN_BATCH_SIZE;
+    const remaining = [];
+    let sent = 0;
+    for (let i = 0; i < events.length; i += batchSize) {
+        const batchEnd = Math.min(i + batchSize, events.length);
+        const batch = events.slice(i, batchEnd);
+        const batchPending = pending.slice(i, batchEnd);
+        try {
+            await (0, collector_1.sendEventsBatchToCollector)(batch, sessionId, projectDir, target);
+            sent += batch.length;
+            log?.debug(`${logPrefix}: type=session_turn_step_analytics batch_count=${batch.length} `
+                + `first=(turn_index=${batchPending[0].turn_index},step_index=${batchPending[0].step_index})`);
+        }
+        catch (e) {
+            for (const s of batchPending) {
+                remaining.push(s);
+            }
+            logger_1.logger.debug(`analytics emit: step batch send failed: ${e instanceof Error ? e.message : e}`);
+            log?.error(`${logPrefix} failed: type=session_turn_step_analytics batch_count=${batch.length}: `
+                + `${e instanceof Error ? e.message : e}`);
+        }
+    }
+    return { sent, remaining };
+}
+/**
+ * Same shape as {@link withPendingTurnEvents} but for the step queue.
+ */
+function withPendingStepEvents(internal, remaining) {
+    if (remaining.length > 0) {
+        return { ...internal, pending_step_events: remaining };
+    }
+    const next = { ...internal };
+    delete next.pending_step_events;
+    return next;
+}
+/**
+ * Batched POST of every queued api_request body. Each batch wraps the
+ * body-only `APIRequestAnalytics` records with the {@link Event} envelope
+ * (id from `api.id` — transcript line uuid, deterministic across re-
+ * projections; type=`api_request`; timestamp from the body's
+ * `timestamp_ms` so the wire timestamp reflects when the API call
+ * completed — NOT when the wire envelope was constructed).
+ *
+ * Per-batch failure: every record in the failed batch is retained for
+ * retry. Backend dedup key is `(session_id, request_id)` for successes;
+ * failures (request_id=null) rely on (session_id, id) best-effort.
+ */
+async function drainPendingApiRequests(pending, base, sessionId, projectDir, log, logPrefix, target) {
+    const events = pending.map((api) => ({
+        ...base,
+        // Event.id is the transcript line's deterministic uuid (carried
+        // through projection). Re-projections of the same bytes produce
+        // identical ids — backend can dedup on `(session_id, id)`.
+        id: api.id,
+        type: actions_1.EventType.API_REQUEST,
+        timestamp: api.timestamp_ms,
+        request_id: api.request_id,
+        success: api.success,
+        error: api.error,
+        status_code: api.status_code,
+        model: api.model,
+        speed: api.speed,
+        input_tokens: api.input_tokens,
+        output_tokens: api.output_tokens,
+        cache_read_tokens: api.cache_read_tokens,
+        cache_creation_tokens: api.cache_creation_tokens,
+        cost_usd: api.cost_usd,
+        duration: api.duration,
+    }));
+    const batchSize = target !== null ? resolveBatchSize(target) : DEFAULT_DRAIN_BATCH_SIZE;
+    const remaining = [];
+    let sent = 0;
+    for (let i = 0; i < events.length; i += batchSize) {
+        const batchEnd = Math.min(i + batchSize, events.length);
+        const batch = events.slice(i, batchEnd);
+        const batchPending = pending.slice(i, batchEnd);
+        try {
+            await (0, collector_1.sendEventsBatchToCollector)(batch, sessionId, projectDir, target);
+            sent += batch.length;
+            log?.debug(`${logPrefix}: type=api_request batch_count=${batch.length} `
+                + `first_request_id=${batchPending[0].request_id ?? "<null>"} `
+                + `success_count=${batchPending.filter((a) => a.success).length}`);
+        }
+        catch (e) {
+            for (const a of batchPending) {
+                remaining.push(a);
+            }
+            logger_1.logger.debug(`analytics emit: api_request batch send failed: ${e instanceof Error ? e.message : e}`);
+            log?.error(`${logPrefix} failed: type=api_request batch_count=${batch.length}: `
+                + `${e instanceof Error ? e.message : e}`);
+        }
+    }
+    return { sent, remaining };
+}
+/**
+ * Same shape as {@link withPendingTurnEvents} but for the api_request queue.
+ */
+function withPendingApiRequestEvents(internal, remaining) {
+    if (remaining.length > 0) {
+        return { ...internal, pending_api_request_events: remaining };
+    }
+    const next = { ...internal };
+    delete next.pending_api_request_events;
+    return next;
+}
+/** Exposed for tests — never call from prod code. */
+exports.__test = {
+    emptyAccumulated: state_1.emptyAccumulated,
+};
+//# sourceMappingURL=emit.js.map