@unerr-ai/unerr 0.1.0 → 0.1.2

package/dist/tracking/session-history.js

@@ -0,0 +1,128 @@
+/**
+ * Session History Persistence — one row per session in
+ * `.unerr/metrics.db` (`session_history`).
+ *
+ * T.8: Was append-only JSONL at `.unerr/state/session-history.jsonl`;
+ * migrated to SQLite for cross-session aggregations used by `unerr stats`.
+ * Same wire types — the table is a 1:1 mirror of the old record shape.
+ */
+import { openMetricsStore } from "./metrics-store.js";
+function rowToEntry(r) {
+    const entry = {
+        sessionId: r.session_id,
+        startedAt: r.started_at,
+        endedAt: r.ended_at,
+        durationMs: r.duration_ms,
+        toolCalls: r.tool_calls,
+        tokensSaved: r.tokens_saved,
+        tokensProcessed: r.tokens_processed,
+        efficiency: r.efficiency,
+        dollarsSaved: r.dollars_saved,
+        modelId: r.model_id,
+        entityCount: r.entity_count,
+    };
+    if (r.agent_name)
+        entry.agentName = r.agent_name;
+    if (r.token_flow_summary) {
+        try {
+            entry.tokenFlowSummary = JSON.parse(r.token_flow_summary);
+        }
+        catch {
+            /* malformed JSON — drop the summary field */
+        }
+    }
+    return entry;
+}
+/**
+ * Append (or upsert) a session entry to the history store.
+ * The store uses `session_id` as a unique key — re-recording the same
+ * session updates the existing row.
+ */
+export function appendSessionHistory(unerrDir, entry) {
+    try {
+        const store = openMetricsStore(unerrDir);
+        store.upsertSessionHistory({
+            session_id: entry.sessionId,
+            started_at: entry.startedAt,
+            ended_at: entry.endedAt,
+            duration_ms: entry.durationMs,
+            tool_calls: entry.toolCalls,
+            tokens_saved: entry.tokensSaved,
+            tokens_processed: entry.tokensProcessed,
+            efficiency: entry.efficiency,
+            dollars_saved: entry.dollarsSaved,
+            model_id: entry.modelId,
+            entity_count: entry.entityCount,
+            agent_name: entry.agentName ?? null,
+            token_flow_summary: entry.tokenFlowSummary
+                ? JSON.stringify(entry.tokenFlowSummary)
+                : null,
+        });
+    }
+    catch {
+        /* best effort — session history is observability, never block exit */
+    }
+}
+/**
+ * Read all session history entries.
+ */
+export function readSessionHistory(unerrDir) {
+    try {
+        return openMetricsStore(unerrDir).allSessionHistory().map(rowToEntry);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Aggregate stats for a time period.
+ */
+export function aggregateStats(entries, periodLabel) {
+    if (entries.length === 0) {
+        return {
+            sessions: 0,
+            tokensSaved: 0,
+            dollarsSaved: 0,
+            avgEfficiency: 0,
+            totalToolCalls: 0,
+            periodLabel,
+        };
+    }
+    const tokensSaved = entries.reduce((s, e) => s + e.tokensSaved, 0);
+    const dollarsSaved = entries.reduce((s, e) => s + e.dollarsSaved, 0);
+    const totalToolCalls = entries.reduce((s, e) => s + e.toolCalls, 0);
+    const avgEfficiency = entries.reduce((s, e) => s + e.efficiency, 0) / entries.length;
+    return {
+        sessions: entries.length,
+        tokensSaved,
+        dollarsSaved,
+        avgEfficiency: Math.round(avgEfficiency),
+        totalToolCalls,
+        periodLabel,
+    };
+}
+/**
+ * Get stats for this week (last 7 days).
+ */
+export function getWeeklyStats(unerrDir) {
+    const all = readSessionHistory(unerrDir);
+    const cutoff = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const thisWeek = all.filter((e) => e.startedAt >= cutoff);
+    return aggregateStats(thisWeek, "This week");
+}
+/**
+ * Get stats for this month (last 30 days).
+ */
+export function getMonthlyStats(unerrDir) {
+    const all = readSessionHistory(unerrDir);
+    const cutoff = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
+    const thisMonth = all.filter((e) => e.startedAt >= cutoff);
+    return aggregateStats(thisMonth, "This month");
+}
+/**
+ * Get all-time stats.
+ */
+export function getAllTimeStats(unerrDir) {
+    const all = readSessionHistory(unerrDir);
+    return aggregateStats(all, "All time");
+}

package/dist/tracking/session-receipt.js

@@ -0,0 +1,88 @@
+/**
+ * Session Receipt — the viral artifact.
+ *
+ * Layer 10 TF-C.4: Produces a formatted, screenshot-worthy receipt on session
+ * disconnect showing token savings with full mechanism attribution.
+ *
+ * Output goes to stderr (stdout is MCP JSON-RPC only).
+ */
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+const EMERALD = "\x1b[38;2;52;211;153m";
+const CYAN = "\x1b[38;2;34;211;238m";
+const VIOLET = "\x1b[38;2;139;92;246m";
+const MUTED = "\x1b[38;2;161;161;170m";
+function formatTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return String(n);
+}
+function padRight(s, len) {
+    return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+/**
+ * Format a session receipt as a bordered box for stderr display.
+ * Returns the complete ANSI-formatted string.
+ */
+export function formatSessionReceipt(input) {
+    const { summary, durationMs, toolCalls } = input;
+    const W = 47;
+    const durationMin = Math.max(1, Math.round(durationMs / 60_000));
+    const lines = [];
+    const border = (s) => `  ${DIM}│${RESET} ${s}${" ".repeat(Math.max(0, W - stripAnsi(s).length - 1))}${DIM}│${RESET}`;
+    const empty = () => border("");
+    lines.push(`  ${DIM}┌${"─".repeat(W)}┐${RESET}`);
+    lines.push(border(`${VIOLET}${BOLD}unerr${RESET} session receipt`));
+    lines.push(empty());
+    lines.push(border(`Duration:     ${CYAN}${durationMin} minutes${RESET}`));
+    lines.push(border(`Tool calls:   ${CYAN}${toolCalls}${RESET}`));
+    lines.push(border(`Tokens saved:     ${EMERALD}${formatTokens(summary.total_tokens_saved).padEnd(10)}${RESET}`));
+    lines.push(border(`Tokens delivered: ${CYAN}${formatTokens(summary.total_tokens_with).padEnd(10)}${RESET}`));
+    lines.push(border(`Efficiency:       ${EMERALD}${summary.efficiency_pct}%${RESET}`));
+    lines.push(empty());
+    // Mechanism breakdown — top 4
+    const mechs = Object.entries(summary.by_mechanism)
+        .sort(([, a], [, b]) => b.tokens_saved - a.tokens_saved)
+        .slice(0, 4);
+    if (mechs.length > 0) {
+        lines.push(border(`${MUTED}Top savings:${RESET}`));
+        for (const [mech, data] of mechs) {
+            const pctStr = `(${Math.round(data.pct_of_total)}%)`;
+            lines.push(border(`  ${padRight(mech, 20)} ${EMERALD}${formatTokens(data.tokens_saved).padStart(6)}${RESET}  ${MUTED}${pctStr}${RESET}`));
+        }
+        lines.push(empty());
+    }
+    // Most efficient turn
+    if (summary.top_turns.length > 0) {
+        const top = summary.top_turns[0];
+        lines.push(border(`${MUTED}Most efficient:${RESET} ${BOLD}${top.tool}${RESET} ${MUTED}→${RESET} ${EMERALD}${formatTokens(top.tokens_saved)}${RESET} saved`));
+    }
+    // Weekly context
+    if (input.weeklyTokensSaved && input.weeklyTokensSaved > 0) {
+        const weekLabel = `This week: ${formatTokens(input.weeklyTokensSaved)} saved across ${input.weeklySessions ?? 0} sessions`;
+        lines.push(border(`${MUTED}${weekLabel}${RESET}`));
+    }
+    lines.push(`  ${DIM}└${"─".repeat(W)}┘${RESET}`);
+    return `\n${lines.join("\n")}\n`;
+}
+/**
+ * Print the session receipt to stderr.
+ * Safe to call in shutdown — never throws.
+ */
+export function printSessionReceipt(input) {
+    try {
+        const receipt = formatSessionReceipt(input);
+        process.stderr.write(receipt);
+    }
+    catch {
+        /* best effort — never block shutdown */
+    }
+}
+function stripAnsi(s) {
+    const ESC = "\x1b";
+    const CSI = new RegExp(`${ESC}\\[[0-9;?]*[A-Za-z~]`, "g");
+    return s.replace(CSI, "");
+}

package/dist/tracking/session-summary-writer.js

@@ -0,0 +1,157 @@
+/**
+ * Session Summary Writer — SQLite persistence on session disconnect.
+ *
+ * Layer 9 PI-3/PI-4: When an --mcp session ends (stdin close / SIGTERM),
+ * this module upserts a structured summary into `.unerr/metrics.db`
+ * (`session_summaries` table — was JSONL at `.unerr/sessions/{id}.jsonl`).
+ *
+ * The daemon's fact generation pipeline (PI-5) reads these summaries to
+ * extract facts, detect patterns, and reinforce/contradict existing knowledge.
+ *
+ * Key invariant: `session_id` is the row PK. Re-running for the same session
+ * upserts (latest write wins) — matches the JSONL "append + last wins" model.
+ *
+ * Graceful degradation: if write fails, session data is lost but MCP
+ * connection closes cleanly without error.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { extractChains } from "./ledger-chains.js";
+import { openMetricsStore } from "./metrics-store.js";
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Upsert a session summary into `.unerr/metrics.db` (session_summaries).
+ * Called on graceful shutdown of --mcp mode.
+ *
+ * Returns the written record on success, null on failure (silent degradation).
+ */
+export function writeSessionSummary(unerrDir, ctx) {
+    if (ctx.entries.length === 0)
+        return null;
+    try {
+        const sorted = [...ctx.entries].sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
+        const first = sorted[0];
+        const last = sorted[sorted.length - 1];
+        const chains = extractChains(sorted);
+        const files = new Set();
+        const entities = new Set();
+        const toolCounts = {};
+        const featureAreas = new Set();
+        let revertCount = 0;
+        for (const entry of sorted) {
+            toolCounts[entry.tool] = (toolCounts[entry.tool] ?? 0) + 1;
+            const filePath = extractFilePath(entry);
+            if (filePath)
+                files.add(filePath);
+            const entityKeys = extractEntityKeysFromEntry(entry);
+            for (const key of entityKeys)
+                entities.add(key);
+            if (entry.feature_area)
+                featureAreas.add(entry.feature_area);
+        }
+        for (const chain of chains) {
+            if (chain.outcome === "reverted")
+                revertCount++;
+        }
+        const record = {
+            session_id: ctx.sessionId,
+            written_at: new Date().toISOString(),
+            started_at: first.ts,
+            ended_at: last.ts,
+            duration_ms: new Date(last.ts).getTime() - new Date(first.ts).getTime(),
+            tool_calls: sorted.length,
+            chains: chains.length,
+            files_modified: [...files],
+            entities_touched: [...entities].slice(0, 50),
+            tools_used: toolCounts,
+            feature_areas: [...featureAreas],
+            facts_recorded: ctx.factsRecordedIds.length,
+            facts_surfaced: ctx.factsSurfacedIds.slice(0, 20),
+            revert_count: revertCount,
+            rot_score: ctx.rotScore,
+            token_estimate: ctx.tokenEstimate,
+            branch: last.branch ?? "unknown",
+        };
+        // Persist to .unerr/metrics.db (session_summaries) — was JSONL pre-Layer 12.
+        const store = openMetricsStore(unerrDir);
+        store.upsertSessionSummary({
+            session_id: record.session_id,
+            written_at: record.written_at,
+            started_at: record.started_at,
+            ended_at: record.ended_at,
+            duration_ms: record.duration_ms,
+            tool_calls: record.tool_calls,
+            chains: record.chains,
+            files_modified: JSON.stringify(record.files_modified),
+            entities_touched: JSON.stringify(record.entities_touched),
+            tools_used: JSON.stringify(record.tools_used),
+            feature_areas: JSON.stringify(record.feature_areas),
+            facts_recorded: record.facts_recorded,
+            facts_surfaced: JSON.stringify(record.facts_surfaced),
+            revert_count: record.revert_count,
+            rot_score: record.rot_score,
+            token_estimate: record.token_estimate,
+            branch: record.branch,
+        });
+        // last_session.json stays JSON — atomic single-file pointer, stable
+        // across daemon restarts, used by the "next session" resume strip.
+        writeLastSessionPointer(unerrDir, ctx.sessionId, record);
+        return record;
+    }
+    catch (err) {
+        process.stderr.write(`[unerr:session] WARN: Failed to write session summary: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+/**
+ * Read the last session summary (from last_session.json pointer).
+ * Returns null if no prior session exists.
+ */
+export function readLastSession(unerrDir) {
+    try {
+        const pointerPath = join(unerrDir, "state", "last_session.json");
+        if (!existsSync(pointerPath))
+            return null;
+        const content = readFileSync(pointerPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+// ── Internal ─────────────────────────────────────────────────────────
+function writeLastSessionPointer(unerrDir, sessionId, record) {
+    try {
+        const stateDir = join(unerrDir, "state");
+        if (!existsSync(stateDir)) {
+            mkdirSync(stateDir, { recursive: true });
+        }
+        const pointerPath = join(stateDir, "last_session.json");
+        writeFileSync(pointerPath, JSON.stringify(record, null, 2), "utf-8");
+    }
+    catch {
+        // Non-critical — pointer failure doesn't affect session integrity
+    }
+}
+function extractFilePath(entry) {
+    const args = entry.args_summary;
+    if (typeof args.file_path === "string")
+        return args.file_path;
+    if (typeof args.path === "string")
+        return args.path;
+    if (typeof args.key === "string" && args.key.includes("/")) {
+        return args.key.includes("::") ? args.key.split("::")[0] : args.key;
+    }
+    return null;
+}
+function extractEntityKeysFromEntry(entry) {
+    const keys = [];
+    const args = entry.args_summary;
+    if (typeof args.key === "string" && args.key.length > 0) {
+        keys.push(args.key);
+    }
+    if (typeof args.entity === "string" && args.entity.length > 0) {
+        keys.push(args.entity);
+    }
+    return keys;
+}

package/dist/tracking/shadow-ledger.js

@@ -0,0 +1,321 @@
+/**
+ * Shadow Ledger Writer — append-only JSONL intent journal.
+ *
+ * Every MCP tool call that passes through the proxy gets an intent entry appended
+ * to `.unerr/ledger/shadow.jsonl`. The in-memory buffer keeps the last 100 entries
+ * for correlation lookups (no full-file parse needed).
+ *
+ * Entry format: one JSON object per line (JSONL / newline-delimited JSON).
+ * On startup, the file is validated — partial writes are truncated to the last
+ * valid line.
+ *
+ * Performance: append is O(1) via fs.appendFileSync. Buffer is a fixed-size ring.
+ * All logging to stderr.
+ */
+import { randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { redactArgs } from "./redactor.js";
+import { TurnSegmenter } from "./turn-segmenter.js";
+const MAX_BUFFER_SIZE = 100;
+const CORRELATION_WINDOW_MS = 30_000; // 30 seconds
+const MAX_ARG_VALUE_LENGTH = 200;
+export class ShadowLedger {
+    ledgerDir;
+    filePath;
+    sessionId;
+    buffer = [];
+    lastEntryTime = 0;
+    currentRootId = null;
+    turnSegmenter;
+    constructor(unerrDir, options = {}) {
+        this.ledgerDir = join(unerrDir, "ledger");
+        this.filePath = join(this.ledgerDir, "shadow.jsonl");
+        this.sessionId = generateId();
+        this.turnSegmenter = options.turnSegmenter ?? new TurnSegmenter();
+        // Ensure directory exists
+        if (!existsSync(this.ledgerDir)) {
+            mkdirSync(this.ledgerDir, { recursive: true });
+        }
+        // Recover from corruption on startup
+        this.recoverFile();
+        // Load recent entries into buffer
+        this.loadRecentEntries();
+    }
+    /**
+     * Subscribers (e.g., the timeline subsystem) get the same segmenter so they
+     * can observe turn-close events to roll up turns into timeline.db.
+     */
+    getTurnSegmenter() {
+        return this.turnSegmenter;
+    }
+    /**
+     * Close the current turn for this ledger's session. Called by Stop hooks
+     * (Claude Code) or on shutdown. The next recorded entry will open a fresh
+     * turn with confidence "first_call".
+     */
+    closeTurn(reason = "stop_hook") {
+        this.turnSegmenter.closeTurn(this.sessionId, reason);
+    }
+    /**
+     * Record a tool call as a ledger entry.
+     */
+    record(tool, args, resultSummary, branch, headSha, promptContext) {
+        const now = Date.now();
+        const correlationId = this.computeCorrelation(tool, now);
+        const entry = {
+            id: generateId(),
+            ts: new Date(now).toISOString(),
+            tool,
+            // ST-6: redact known secret patterns BEFORE truncating so the regex
+            // catches whole values; then truncate any remaining long strings.
+            args_summary: truncateArgs(redactArgs(args)),
+            result_summary: resultSummary,
+            branch,
+            head_sha: headSha,
+            session_id: this.sessionId,
+            correlation_id: correlationId,
+            ...(promptContext?.planSummary
+                ? { plan_summary: promptContext.planSummary }
+                : {}),
+            ...(promptContext?.changeType
+                ? { change_type: promptContext.changeType }
+                : {}),
+            ...(promptContext?.featureArea
+                ? { feature_area: promptContext.featureArea }
+                : {}),
+        };
+        // ST-1: stamp turn_id / turn_confidence in place before persist.
+        this.turnSegmenter.observe(entry);
+        // Append to file
+        this.appendEntry(entry);
+        // Update in-memory buffer
+        this.buffer.push(entry);
+        if (this.buffer.length > MAX_BUFFER_SIZE) {
+            this.buffer.shift();
+        }
+        this.lastEntryTime = now;
+        return entry;
+    }
+    /**
+     * Get the last N entries from the in-memory buffer.
+     */
+    getRecentEntries(limit = 20) {
+        return this.buffer.slice(-limit);
+    }
+    /**
+     * Get the current root intent ID for correlation.
+     */
+    getCurrentRootId() {
+        return this.currentRootId;
+    }
+    /**
+     * Get the session ID.
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Get the timestamp (ms) of the last sync_local_diff call.
+     * Used by AI attribution heuristic to determine change origin.
+     * Returns 0 if no sync has been recorded this session.
+     */
+    getLastSyncTimestamp() {
+        for (let i = this.buffer.length - 1; i >= 0; i--) {
+            const entry = this.buffer[i];
+            if (entry?.tool === "sync_local_diff") {
+                return new Date(entry.ts).getTime();
+            }
+        }
+        return 0;
+    }
+    /**
+     * Get ledger stats for `unerr status`.
+     */
+    getStats() {
+        const lastEntry = this.buffer.length > 0 ? this.buffer[this.buffer.length - 1] : null;
+        return {
+            totalEntries: this.countEntries(),
+            bufferSize: this.buffer.length,
+            sessionId: this.sessionId,
+            lastEntryAt: lastEntry?.ts ?? null,
+        };
+    }
+    /**
+     * Get count of entries in the current session.
+     */
+    getSessionEntryCount() {
+        return this.buffer.filter((e) => e.session_id === this.sessionId).length;
+    }
+    /**
+     * Get count of pending correlations (entries with correlation_id that are roots).
+     */
+    getPendingRootCount() {
+        const roots = new Set();
+        for (const entry of this.buffer) {
+            if (entry.correlation_id === null) {
+                roots.add(entry.id);
+            }
+        }
+        return roots.size;
+    }
+    /**
+     * Flush the in-memory buffer to disk (for graceful shutdown).
+     * Since we appendFileSync on each record, this is mostly a no-op
+     * but ensures any pending state is consistent.
+     */
+    flush() {
+        // Buffer is already synced via appendFileSync — nothing to do
+        // This method exists for the shutdown contract
+    }
+    /**
+     * Get all entries (read from file). Used sparingly — prefer buffer.
+     */
+    readAllEntries() {
+        if (!existsSync(this.filePath))
+            return [];
+        try {
+            const content = readFileSync(this.filePath, "utf-8");
+            const lines = content.split("\n").filter((l) => l.trim().length > 0);
+            return lines.map((line) => JSON.parse(line));
+        }
+        catch {
+            return [];
+        }
+    }
+    // ── Internal ───────────────────────────────────────────────────
+    computeCorrelation(tool, now) {
+        const gap = now - this.lastEntryTime;
+        // sync_local_diff always correlates to active root
+        if (tool === "sync_local_diff" && this.currentRootId) {
+            return this.currentRootId;
+        }
+        // If gap > 30s or no previous entry → new root intent
+        if (gap > CORRELATION_WINDOW_MS || this.lastEntryTime === 0) {
+            this.currentRootId = null; // will be set to this entry's ID after creation
+            // Return null — this IS the root
+            return null;
+        }
+        // Within window → correlate to current root
+        return this.currentRootId;
+    }
+    appendEntry(entry) {
+        // If this is a root entry (correlation_id is null), update currentRootId
+        if (entry.correlation_id === null) {
+            this.currentRootId = entry.id;
+        }
+        try {
+            appendFileSync(this.filePath, `${JSON.stringify(entry)}\n`, "utf-8");
+        }
+        catch (err) {
+            process.stderr.write(`[unerr:ledger] WARN: Failed to append entry: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    /**
+     * Recover from file corruption: truncate to last valid JSONL line.
+     */
+    recoverFile() {
+        if (!existsSync(this.filePath))
+            return;
+        try {
+            const content = readFileSync(this.filePath, "utf-8");
+            const lines = content.split("\n");
+            const validLines = [];
+            for (const line of lines) {
+                if (line.trim().length === 0)
+                    continue;
+                try {
+                    JSON.parse(line);
+                    validLines.push(line);
+                }
+                catch {
+                    // Invalid line — stop here (truncate from this point)
+                    process.stderr.write(`[unerr:ledger] Recovered: truncated ${lines.length - validLines.length} corrupt line(s)\n`);
+                    break;
+                }
+            }
+            // Rewrite file with only valid lines
+            if (validLines.length < lines.filter((l) => l.trim().length > 0).length) {
+                writeFileSync(this.filePath, validLines.join("\n") + (validLines.length > 0 ? "\n" : ""), "utf-8");
+            }
+        }
+        catch {
+            // File unreadable — start fresh
+            writeFileSync(this.filePath, "", "utf-8");
+        }
+    }
+    /**
+     * Load the most recent entries from the file into the buffer.
+     */
+    loadRecentEntries() {
+        if (!existsSync(this.filePath))
+            return;
+        try {
+            const content = readFileSync(this.filePath, "utf-8");
+            const lines = content.split("\n").filter((l) => l.trim().length > 0);
+            // Load last MAX_BUFFER_SIZE entries
+            const start = Math.max(0, lines.length - MAX_BUFFER_SIZE);
+            for (let i = start; i < lines.length; i++) {
+                try {
+                    const line = lines[i];
+                    if (!line)
+                        continue;
+                    const entry = JSON.parse(line);
+                    this.buffer.push(entry);
+                }
+                catch {
+                    // Skip invalid lines
+                }
+            }
+            // Restore correlation state from last root entry
+            for (let i = this.buffer.length - 1; i >= 0; i--) {
+                const entry = this.buffer[i];
+                if (!entry)
+                    continue;
+                if (entry.correlation_id === null) {
+                    this.currentRootId = entry.id;
+                    this.lastEntryTime = new Date(entry.ts).getTime();
+                    break;
+                }
+            }
+        }
+        catch {
+            // Start with empty buffer
+        }
+    }
+    /**
+     * Count total entries in the file.
+     */
+    countEntries() {
+        if (!existsSync(this.filePath))
+            return 0;
+        try {
+            const content = readFileSync(this.filePath, "utf-8");
+            return content.split("\n").filter((l) => l.trim().length > 0).length;
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+/**
+ * Generate a 12-char hex ID (6 random bytes).
+ */
+function generateId() {
+    return randomBytes(6).toString("hex");
+}
+/**
+ * Truncate argument values to prevent JSONL bloat.
+ */
+function truncateArgs(args) {
+    const result = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (typeof value === "string" && value.length > MAX_ARG_VALUE_LENGTH) {
+            result[key] = `${value.slice(0, MAX_ARG_VALUE_LENGTH)}...`;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}