cursorconnect 0.1.7 → 0.1.9

package/bridge-runtime/dist/keep-awake.js

@@ -0,0 +1,48 @@
+import { spawn } from 'child_process';
+let caffeinate = null;
+/** macOS: `caffeinate -w <pid>` — Mac не уходит в сон, пока живёт bridge. */
+export function startKeepAwake(enabled) {
+    if (!enabled || process.platform !== 'darwin')
+        return;
+    if (caffeinate)
+        return;
+    try {
+        caffeinate = spawn('caffeinate', ['-w', String(process.pid)], {
+            stdio: 'ignore',
+        });
+        caffeinate.on('error', (err) => {
+            console.warn(`[keep-awake] caffeinate error: ${err.message}`);
+            caffeinate = null;
+        });
+        caffeinate.on('exit', (code, signal) => {
+            if (code != null && code !== 0) {
+                console.warn(`[keep-awake] caffeinate exited code=${code} signal=${signal ?? '-'}`);
+            }
+            caffeinate = null;
+        });
+        console.log('[keep-awake] macOS sleep prevention on (caffeinate -w bridge)');
+    }
+    catch (e) {
+        console.warn(`[keep-awake] start failed: ${e.message}`);
+    }
+}
+export function stopKeepAwake() {
+    if (!caffeinate)
+        return;
+    try {
+        caffeinate.kill('SIGTERM');
+    }
+    catch {
+        /* already dead */
+    }
+    caffeinate = null;
+}
+export function isKeepAwakeActive() {
+    return caffeinate != null && caffeinate.exitCode == null;
+}
+export function installKeepAwakeShutdown() {
+    const stop = () => stopKeepAwake();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    process.once('exit', stop);
+}

package/bridge-runtime/dist/lenta-capture.d.ts

@@ -0,0 +1,46 @@
+import type { ChatMessage, HistoryMessage } from './types.js';
+export type LentaCaptureReason = 'jsonl_file' | 'dom_ingest' | 'emit_agent_messages' | 'manual';
+export interface LentaCaptureConfig {
+    enabled: boolean;
+    agentId: string;
+    title?: string;
+}
+export interface LentaCapturePayload {
+    reason: LentaCaptureReason;
+    source?: 'dom' | 'jsonl' | 'hybrid';
+    emitSeq?: number;
+    seqHeld?: boolean;
+    transition?: string;
+    jsonlRowCount?: number;
+    historyMessages: ChatMessage[];
+    liveMessages: ChatMessage[];
+    messages: ChatMessage[];
+    domRaw?: ChatMessage[];
+    domViewport?: ChatMessage[];
+    jsonlRawRows?: HistoryMessage[];
+    jsonlFilePath?: string;
+    activeComposerId?: string;
+    agentWorking?: boolean;
+}
+export declare function captureConfigPath(): string;
+export declare function readCaptureConfig(): LentaCaptureConfig | null;
+export declare function writeCaptureConfig(cfg: LentaCaptureConfig): void;
+export declare function clearCaptureConfig(): void;
+export declare function captureSessionDir(agentId: string): string;
+export declare class LentaCaptureSession {
+    private readonly agentId;
+    private step;
+    private lastSig;
+    constructor(agentId: string);
+    shouldCapture(targetAgentId: string): boolean;
+    record(payload: LentaCapturePayload): string | null;
+}
+export declare function getLentaCaptureSession(agentId: string): LentaCaptureSession | null;
+export declare function captureLentaIfEnabled(agentId: string, payload: LentaCapturePayload): void;
+export declare function resolveAgentJsonlPath(projectsDir: string, agentId: string, opts: {
+    title?: string;
+    composerIdByTitle?: Record<string, string>;
+    activeComposerId?: string;
+    activeTabTitle?: string;
+}): string | undefined;
+export declare function listCaptureSteps(agentId: string): string[];

package/bridge-runtime/dist/lenta-capture.js

@@ -0,0 +1,146 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { messagesFingerprint } from './lenta-seq-journal.js';
+import { resolveJsonlFilePath } from './agent-title-match.js';
+const CAPTURE_ROOT = join(homedir(), '.cursorconnect', 'capture');
+export function captureConfigPath() {
+    return join(CAPTURE_ROOT, 'config.json');
+}
+export function readCaptureConfig() {
+    const path = captureConfigPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        if (!raw.enabled || !raw.agentId?.trim())
+            return null;
+        return { ...raw, agentId: raw.agentId.trim() };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCaptureConfig(cfg) {
+    mkdirSync(CAPTURE_ROOT, { recursive: true });
+    writeFileSync(captureConfigPath(), `${JSON.stringify(cfg, null, 2)}\n`);
+}
+export function clearCaptureConfig() {
+    writeCaptureConfig({ enabled: false, agentId: '' });
+}
+export function captureSessionDir(agentId) {
+    return join(CAPTURE_ROOT, 'sessions', agentId);
+}
+export class LentaCaptureSession {
+    agentId;
+    step = 0;
+    lastSig = '';
+    constructor(agentId) {
+        this.agentId = agentId;
+        const dir = captureSessionDir(agentId);
+        mkdirSync(dir, { recursive: true });
+        const manifestPath = join(dir, 'manifest.jsonl');
+        if (!existsSync(manifestPath)) {
+            writeFileSync(manifestPath, `${JSON.stringify({
+                startedAt: new Date().toISOString(),
+                agentId,
+                note: 'Full JSONL+DOM snapshots per bridge event',
+            })}\n`);
+        }
+    }
+    shouldCapture(targetAgentId) {
+        return targetAgentId === this.agentId;
+    }
+    record(payload) {
+        const sig = messagesFingerprint(payload.messages);
+        if (sig === this.lastSig && payload.reason !== 'jsonl_file') {
+            return null;
+        }
+        this.lastSig = sig;
+        this.step += 1;
+        const stepId = `${String(this.step).padStart(5, '0')}-${payload.reason}`;
+        const dir = join(captureSessionDir(this.agentId), stepId);
+        mkdirSync(dir, { recursive: true });
+        const meta = {
+            at: new Date().toISOString(),
+            step: this.step,
+            stepId,
+            agentId: this.agentId,
+            reason: payload.reason,
+            source: payload.source,
+            emitSeq: payload.emitSeq,
+            seqHeld: payload.seqHeld,
+            transition: payload.transition,
+            jsonlRowCount: payload.jsonlRowCount,
+            counts: {
+                messages: payload.messages.length,
+                history: payload.historyMessages.length,
+                live: payload.liveMessages.length,
+                domRaw: payload.domRaw?.length ?? 0,
+                domViewport: payload.domViewport?.length ?? 0,
+                jsonlRaw: payload.jsonlRawRows?.length ?? 0,
+            },
+            messagesSig: sig.slice(0, 500),
+            activeComposerId: payload.activeComposerId,
+            agentWorking: payload.agentWorking,
+            jsonlFile: payload.jsonlFilePath,
+        };
+        writeFileSync(join(dir, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);
+        writeFileSync(join(dir, 'messages.json'), `${JSON.stringify(payload.messages, null, 2)}\n`);
+        writeFileSync(join(dir, 'historyMessages.json'), `${JSON.stringify(payload.historyMessages, null, 2)}\n`);
+        writeFileSync(join(dir, 'liveMessages.json'), `${JSON.stringify(payload.liveMessages, null, 2)}\n`);
+        if (payload.domRaw?.length) {
+            writeFileSync(join(dir, 'domRaw.json'), `${JSON.stringify(payload.domRaw, null, 2)}\n`);
+        }
+        if (payload.domViewport?.length) {
+            writeFileSync(join(dir, 'domViewport.json'), `${JSON.stringify(payload.domViewport, null, 2)}\n`);
+        }
+        if (payload.jsonlRawRows?.length) {
+            writeFileSync(join(dir, 'jsonl.rows.json'), `${JSON.stringify(payload.jsonlRawRows, null, 2)}\n`);
+        }
+        if (payload.jsonlFilePath && existsSync(payload.jsonlFilePath)) {
+            try {
+                copyFileSync(payload.jsonlFilePath, join(dir, 'transcript.jsonl'));
+            }
+            catch {
+                /* non-fatal */
+            }
+        }
+        const manifestLine = JSON.stringify(meta);
+        writeFileSync(join(captureSessionDir(this.agentId), 'manifest.jsonl'), manifestLine + '\n', { flag: 'a' });
+        bridgeCaptureLog(stepId, meta.counts, payload.reason);
+        return dir;
+    }
+}
+function bridgeCaptureLog(stepId, counts, reason) {
+    console.log(`[lenta-capture] ${stepId} reason=${reason} msgs=${counts.messages} hist=${counts.history} live=${counts.live} domRaw=${counts.domRaw}`);
+}
+let session = null;
+let sessionAgentId = '';
+export function getLentaCaptureSession(agentId) {
+    const cfg = readCaptureConfig();
+    if (!cfg || cfg.agentId !== agentId)
+        return null;
+    if (!session || sessionAgentId !== agentId) {
+        session = new LentaCaptureSession(agentId);
+        sessionAgentId = agentId;
+    }
+    return session;
+}
+export function captureLentaIfEnabled(agentId, payload) {
+    const cap = getLentaCaptureSession(agentId);
+    if (!cap)
+        return;
+    cap.record(payload);
+}
+export function resolveAgentJsonlPath(projectsDir, agentId, opts) {
+    return resolveJsonlFilePath(projectsDir, agentId, opts) ?? undefined;
+}
+export function listCaptureSteps(agentId) {
+    const dir = captureSessionDir(agentId);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((n) => /^\d{5}-/.test(n))
+        .sort();
+}

package/bridge-runtime/dist/lenta-debug.d.ts

@@ -0,0 +1,42 @@
+import type { ChatMessage } from './types.js';
+export type LentaRowPreview = {
+    source: string;
+    role: string;
+    flat: number | null;
+    domSeq: number | null;
+    id: string;
+    len: number;
+    head: string;
+};
+export type LentaInvariantIssue = {
+    type: string;
+    detail?: string;
+    dom?: LentaRowPreview;
+    bridge?: LentaRowPreview;
+    skipped?: string[];
+    index?: number;
+};
+export declare function normPreviewText(t: string | undefined): string;
+export declare function previewRow(m: ChatMessage, source: string): LentaRowPreview;
+/** `messages` must equal `[...historyMessages, ...liveMessages]` (socket/HTTP payload). */
+export declare function checkPayloadCompose(messages: ChatMessage[], historyMessages: ChatMessage[], liveMessages: ChatMessage[]): LentaInvariantIssue[];
+/** In-memory store: `messages` = jsonlHistory + domOverlay. */
+export declare function checkStoreCompose(jsonlHistory: ChatMessage[], domOverlay: ChatMessage[], messages: ChatMessage[]): LentaInvariantIssue[];
+export declare function checkMonotonicOrder(messages: ChatMessage[], label: string): LentaInvariantIssue[];
+/** DOM overlay must not repeat a turn already in JSONL archive. */
+export declare function checkOverlayDuplicatesArchive(jsonlHistory: ChatMessage[], domOverlay: ChatMessage[]): LentaInvariantIssue[];
+export declare function checkOverlayAfterArchive(jsonlHistory: ChatMessage[], domOverlay: ChatMessage[]): LentaInvariantIssue[];
+/** When not synced with Cursor, DOM overlay for subscribed chat should stay empty. */
+export declare function checkSyncGate(synced: boolean, domOverlay: ChatMessage[], domRawCount: number): LentaInvariantIssue[];
+export declare function rowSimilar(a: LentaRowPreview, b: LentaRowPreview): boolean;
+/** DOM viewport vs full lenta — match each viewport row to lenta from the end (avoids duplicate-text false gaps). */
+export declare function compareDomTailToLenta(domRows: LentaRowPreview[], lentaRows: LentaRowPreview[], tail: number, opts?: {
+    hasDomOverlay?: boolean;
+    hasJsonlArchive?: boolean;
+    agentWorking?: boolean;
+}): {
+    issues: LentaInvariantIssue[];
+    domTail: LentaRowPreview[];
+    lentaTail: LentaRowPreview[];
+};
+export declare function checkApiMatchesStore(apiMessages: ChatMessage[], storeMessages: ChatMessage[]): LentaInvariantIssue[];

package/bridge-runtime/dist/lenta-debug.js

@@ -0,0 +1,221 @@
+import { archiveCoversOverlay, messageOrderKey } from './chat-display.js';
+export function normPreviewText(t) {
+    return String(t ?? '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 400);
+}
+export function previewRow(m, source) {
+    const text = normPreviewText(m.text);
+    return {
+        source,
+        role: m.role ?? '?',
+        flat: m.flatIndex ?? null,
+        domSeq: m.domSeq ?? null,
+        id: (m.id ?? '').slice(0, 28),
+        len: text.length,
+        head: text.slice(0, 72),
+    };
+}
+function rowFingerprint(m) {
+    const text = normPreviewText(m.text);
+    return `${m.role}|${m.id ?? ''}|${text.length}|${text.slice(0, 64)}`;
+}
+function rowsFingerprint(rows) {
+    return rows.map(rowFingerprint);
+}
+/** `messages` must equal `[...historyMessages, ...liveMessages]` (socket/HTTP payload). */
+export function checkPayloadCompose(messages, historyMessages, liveMessages) {
+    const issues = [];
+    const expectedLen = historyMessages.length + liveMessages.length;
+    if (messages.length !== expectedLen) {
+        issues.push({
+            type: 'PAYLOAD_COMPOSE_LEN',
+            detail: `messages=${messages.length} history+live=${expectedLen} (${historyMessages.length}+${liveMessages.length})`,
+        });
+    }
+    const composed = [...historyMessages, ...liveMessages];
+    const a = rowsFingerprint(messages);
+    const b = rowsFingerprint(composed);
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        if (a[i] !== b[i]) {
+            issues.push({
+                type: 'PAYLOAD_COMPOSE_ROW',
+                index: i,
+                detail: `messages[${i}] !== concat(history,live)[${i}]`,
+            });
+            break;
+        }
+    }
+    if (a.length !== b.length && !issues.some((x) => x.type === 'PAYLOAD_COMPOSE_LEN')) {
+        issues.push({
+            type: 'PAYLOAD_COMPOSE_ROW',
+            detail: `fingerprint len ${a.length} vs ${b.length}`,
+        });
+    }
+    return issues;
+}
+/** In-memory store: `messages` = jsonlHistory + domOverlay. */
+export function checkStoreCompose(jsonlHistory, domOverlay, messages) {
+    const issues = [];
+    const expectedLen = jsonlHistory.length + domOverlay.length;
+    if (messages.length !== expectedLen) {
+        issues.push({
+            type: 'STORE_COMPOSE_LEN',
+            detail: `messages=${messages.length} jsonl+overlay=${expectedLen}`,
+        });
+    }
+    const composed = [...jsonlHistory, ...domOverlay];
+    const a = rowsFingerprint(messages);
+    const b = rowsFingerprint(composed);
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        if (a[i] !== b[i]) {
+            issues.push({
+                type: 'STORE_COMPOSE_ROW',
+                index: i,
+                detail: `messages[${i}] !== jsonl+overlay[${i}]`,
+            });
+            break;
+        }
+    }
+    return issues;
+}
+export function checkMonotonicOrder(messages, label) {
+    const issues = [];
+    for (let i = 1; i < messages.length; i++) {
+        const prev = messageOrderKey(messages[i - 1]);
+        const cur = messageOrderKey(messages[i]);
+        if (cur < prev) {
+            issues.push({
+                type: 'LENTA_ORDER_INVERSION',
+                index: i,
+                detail: `${label} i=${i} ${prev}>${cur}`,
+            });
+            break;
+        }
+    }
+    return issues;
+}
+/** DOM overlay must not repeat a turn already in JSONL archive. */
+export function checkOverlayDuplicatesArchive(jsonlHistory, domOverlay) {
+    const issues = [];
+    for (const dom of domOverlay) {
+        const hit = jsonlHistory.find((h) => archiveCoversOverlay(h, dom));
+        if (hit) {
+            issues.push({
+                type: 'OVERLAY_DUPLICATES_ARCHIVE',
+                detail: `dom flat=${dom.flatIndex ?? '?'} covered by jsonl flat=${hit.flatIndex ?? '?'}`,
+                dom: previewRow(dom, 'domOverlay'),
+                bridge: previewRow(hit, 'jsonlHistory'),
+            });
+        }
+    }
+    return issues;
+}
+export function checkOverlayAfterArchive(jsonlHistory, domOverlay) {
+    if (!jsonlHistory.length || !domOverlay.length)
+        return [];
+    let floor = 0;
+    for (const m of jsonlHistory) {
+        floor = Math.max(floor, messageOrderKey(m));
+    }
+    const minOverlay = Math.min(...domOverlay.map((m) => messageOrderKey(m)));
+    if (minOverlay <= floor) {
+        return [
+            {
+                type: 'OVERLAY_NOT_AFTER_ARCHIVE',
+                detail: `archive floor=${floor} overlay min key=${minOverlay}`,
+            },
+        ];
+    }
+    return [];
+}
+/** When not synced with Cursor, DOM overlay for subscribed chat should stay empty. */
+export function checkSyncGate(synced, domOverlay, domRawCount) {
+    if (synced)
+        return [];
+    if (domOverlay.length > 0) {
+        return [
+            {
+                type: 'OVERLAY_WHILE_UNSYNCED',
+                detail: `overlay=${domOverlay.length} domRaw=${domRawCount}`,
+            },
+        ];
+    }
+    return [];
+}
+export function rowSimilar(a, b) {
+    if (a.role !== b.role)
+        return false;
+    const ah = a.head.toLowerCase();
+    const bh = b.head.toLowerCase();
+    if (!ah || !bh)
+        return ah === bh;
+    if (ah === bh)
+        return true;
+    const short = ah.length <= bh.length ? ah : bh;
+    const long = ah.length <= bh.length ? bh : ah;
+    if (short.length >= 8 && long.includes(short))
+        return true;
+    return long.includes(short) && short.length >= 16;
+}
+/** DOM viewport vs full lenta — match each viewport row to lenta from the end (avoids duplicate-text false gaps). */
+export function compareDomTailToLenta(domRows, lentaRows, tail, opts) {
+    const issues = [];
+    const domTailN = opts?.hasJsonlArchive ? Math.min(tail, 4) : tail;
+    const d = domRows.slice(-domTailN);
+    const full = lentaRows;
+    const lentaTail = full.slice(-Math.max(tail, 16));
+    if (!d.length || !full.length) {
+        return { issues, domTail: d, lentaTail };
+    }
+    const searchWindow = Math.min(full.length, Math.max(tail * 10, full.length > 80 ? 120 : 48));
+    let searchEnd = full.length;
+    for (let di = d.length - 1; di >= 0; di--) {
+        const dom = d[di];
+        let found = -1;
+        const from = Math.max(0, searchEnd - searchWindow);
+        for (let j = searchEnd - 1; j >= from; j--) {
+            if (rowSimilar(dom, full[j])) {
+                found = j;
+                break;
+            }
+        }
+        if (found < 0) {
+            const domFlat = dom.flat ?? 0;
+            const maxLentaFlat = full.reduce((m, r) => Math.max(m, r.flat ?? 0), 0);
+            const type = !opts?.hasDomOverlay && (opts?.agentWorking || domFlat > maxLentaFlat + 5)
+                ? 'NEEDS_DOM_OVERLAY'
+                : 'DOM_MISSING_IN_LENTA';
+            issues.push({ type, dom, detail: `domFlat=${domFlat} lentaMax=${maxLentaFlat}` });
+            continue;
+        }
+        searchEnd = found;
+    }
+    return { issues, domTail: d, lentaTail };
+}
+export function checkApiMatchesStore(apiMessages, storeMessages) {
+    const a = rowsFingerprint(apiMessages);
+    const b = rowsFingerprint(storeMessages);
+    if (a.length !== b.length) {
+        return [
+            {
+                type: 'API_STORE_LEN',
+                detail: `api=${a.length} store=${b.length}`,
+            },
+        ];
+    }
+    for (let i = Math.max(0, a.length - 8); i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return [
+                {
+                    type: 'API_STORE_TAIL',
+                    index: i,
+                    detail: `tail mismatch at ${i}`,
+                },
+            ];
+        }
+    }
+    return [];
+}

package/bridge-runtime/dist/lenta-delivery.d.ts

@@ -0,0 +1,3 @@
+import type { ChatMessage } from './types.js';
+/** Canonical lenta in store vs last socket `agent:messages` emit. */
+export declare function isLentaDeliveryPending(agentId: string, storeMessages: ChatMessage[]): boolean;

package/bridge-runtime/dist/lenta-delivery.js

@@ -0,0 +1,10 @@
+import { getLastLentaEmit, messagesFingerprint } from './lenta-seq-journal.js';
+/** Canonical lenta in store vs last socket `agent:messages` emit. */
+export function isLentaDeliveryPending(agentId, storeMessages) {
+    if (!storeMessages.length)
+        return false;
+    const last = getLastLentaEmit(agentId);
+    if (!last)
+        return true;
+    return messagesFingerprint(storeMessages) !== last.messagesSig;
+}

package/bridge-runtime/dist/lenta-seq-journal.d.ts

@@ -0,0 +1,48 @@
+import type { ChatMessage } from './types.js';
+export type LentaSeqReason = 'dom_overlay' | 'jsonl_live' | 'agents_history' | 'subscribe_refresh' | 'delivery_flush' | 'push_ready' | 'emit';
+export type LentaSeqTransition = 'dom_to_jsonl' | 'overlay_grow' | 'overlay_shrink' | 'jsonl_grow' | 'none';
+export interface LentaSeqEmitMeta {
+    reason: LentaSeqReason;
+    source: 'dom' | 'jsonl' | 'hybrid';
+    historyLen: number;
+    liveLen: number;
+    messagesLen: number;
+    append?: boolean;
+}
+export interface LentaSeqEntry {
+    at: number;
+    agentId: string;
+    seq: number;
+    prevSeq: number;
+    seqHeld: boolean;
+    reason: LentaSeqReason;
+    transition: LentaSeqTransition;
+    source: string;
+    historyLen: number;
+    liveLen: number;
+    messagesLen: number;
+    messagesSig: string;
+    tailPreview: string;
+    append?: boolean;
+}
+export declare function messagesFingerprint(messages: ChatMessage[]): string;
+export declare function tailPreview(messages: ChatMessage[], n?: number): string;
+export declare function detectSeqTransition(prev: {
+    historyLen: number;
+    liveLen: number;
+    source: string;
+} | undefined, next: {
+    historyLen: number;
+    liveLen: number;
+    source: string;
+}): LentaSeqTransition;
+export declare function recordLentaSeqEmit(agentId: string, seq: number, prevSeq: number, seqHeld: boolean, messages: ChatMessage[], meta: LentaSeqEmitMeta): LentaSeqEntry;
+export declare function getLastLentaEmit(agentId: string): {
+    seq: number;
+    messagesSig: string;
+    historyLen: number;
+    liveLen: number;
+    source: string;
+} | undefined;
+export declare function getLentaSeqJournal(agentId?: string): LentaSeqEntry[];
+export declare function getLentaSeqLogPath(): string;

package/bridge-runtime/dist/lenta-seq-journal.js

@@ -0,0 +1,109 @@
+import { appendFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+const RING_BY_AGENT = new Map();
+const LAST_BY_AGENT = new Map();
+const MAX_PER_AGENT = 80;
+const LOG_DIR = join(homedir(), '.cursorconnect');
+const LOG_FILE = join(LOG_DIR, 'lenta-seq.jsonl');
+export function messagesFingerprint(messages) {
+    return messages
+        .map((m) => {
+        const t = String(m.text ?? '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, 80);
+        return `${m.role}|${m.id ?? ''}|${t.length}|${t}`;
+    })
+        .join(';;');
+}
+export function tailPreview(messages, n = 3) {
+    return messages
+        .slice(-n)
+        .map((m) => `${m.role}:${(m.text ?? '').replace(/\s+/g, ' ').trim().slice(0, 48)}`)
+        .join(' | ');
+}
+export function detectSeqTransition(prev, next) {
+    if (!prev)
+        return 'none';
+    if (prev.liveLen > 0 && next.liveLen === 0 && next.historyLen >= prev.historyLen) {
+        return 'dom_to_jsonl';
+    }
+    if (next.liveLen > prev.liveLen && next.historyLen === prev.historyLen) {
+        return 'overlay_grow';
+    }
+    if (next.liveLen < prev.liveLen && next.historyLen >= prev.historyLen) {
+        return 'overlay_shrink';
+    }
+    if (next.historyLen > prev.historyLen)
+        return 'jsonl_grow';
+    return 'none';
+}
+export function recordLentaSeqEmit(agentId, seq, prevSeq, seqHeld, messages, meta) {
+    const prev = LAST_BY_AGENT.get(agentId);
+    const messagesSig = messagesFingerprint(messages);
+    const transition = detectSeqTransition(prev, {
+        historyLen: meta.historyLen,
+        liveLen: meta.liveLen,
+        source: meta.source,
+    });
+    const entry = {
+        at: Date.now(),
+        agentId,
+        seq,
+        prevSeq,
+        seqHeld,
+        reason: meta.reason,
+        transition,
+        source: meta.source,
+        historyLen: meta.historyLen,
+        liveLen: meta.liveLen,
+        messagesLen: meta.messagesLen,
+        messagesSig: messagesSig.slice(0, 400),
+        tailPreview: tailPreview(messages),
+        append: meta.append,
+    };
+    LAST_BY_AGENT.set(agentId, {
+        seq,
+        messagesSig,
+        historyLen: meta.historyLen,
+        liveLen: meta.liveLen,
+        source: meta.source,
+    });
+    let ring = RING_BY_AGENT.get(agentId);
+    if (!ring) {
+        ring = [];
+        RING_BY_AGENT.set(agentId, ring);
+    }
+    ring.push(entry);
+    while (ring.length > MAX_PER_AGENT)
+        ring.shift();
+    try {
+        mkdirSync(LOG_DIR, { recursive: true });
+        appendFileSync(LOG_FILE, `${JSON.stringify(entry)}\n`);
+    }
+    catch {
+        /* non-fatal */
+    }
+    if (process.env.LENTA_SEQ_ASSERT === '1') {
+        if (!seqHeld && prev && prev.messagesSig === messagesSig) {
+            console.warn(`[lenta-seq] seq bump without lenta change agent=${agentId.slice(0, 8)} seq ${prevSeq}→${seq} transition=${transition}`);
+        }
+        if (transition === 'dom_to_jsonl' && !seqHeld && prevSeq === seq) {
+            console.warn(`[lenta-seq] dom→jsonl handoff but seq held agent=${agentId.slice(0, 8)} seq=${seq}`);
+        }
+    }
+    return entry;
+}
+export function getLastLentaEmit(agentId) {
+    return LAST_BY_AGENT.get(agentId);
+}
+export function getLentaSeqJournal(agentId) {
+    if (!agentId) {
+        return [...RING_BY_AGENT.values()].flat().sort((a, b) => a.at - b.at).slice(-MAX_PER_AGENT);
+    }
+    return [...(RING_BY_AGENT.get(agentId) ?? [])];
+}
+export function getLentaSeqLogPath() {
+    return LOG_FILE;
+}