@bubblebrain-ai/bubble 0.0.58 → 0.0.60

package/dist/sdk/replay-event-log.js

@@ -3,17 +3,28 @@
  * consumer, and consumers can attach again with their last seen sequence.
  */
 export class ReplayEventLog {
-    entries = [];
+    retention;
+    entries = new Map();
+    nextIndex = 0;
+    firstIndex = 0;
+    readers = new Map();
     signal = deferredSignal();
     closed = false;
     failure;
+    constructor(retention = Infinity) {
+        this.retention = retention;
+        if (retention !== Infinity && (!Number.isSafeInteger(retention) || retention < 1))
+            throw new Error('Invalid event retention');
+    }
     get length() {
-        return this.entries.length;
+        return this.nextIndex;
     }
+    get retainedCount() { return this.entries.size; }
     append(value) {
         if (this.closed)
             return;
-        this.entries.push(value);
+        this.entries.set(this.nextIndex++, value);
+        this.prune();
         this.wake();
     }
     close(error) {
@@ -25,23 +36,62 @@ export class ReplayEventLog {
     }
     iterate(options = {}) {
         const start = Math.max(0, options.from ?? 0);
-        return this.readFrom(start, options.signal);
+        const reader = {};
+        const cancelled = new AbortController();
+        const signal = options.signal ? AbortSignal.any([options.signal, cancelled.signal]) : cancelled.signal;
+        const release = () => { this.readers.delete(reader); this.prune(); };
+        // Reserve the cursor when subscribing, before a synchronous producer can
+        // prune events and before the consumer calls next(). close/return also
+        // release subscriptions which were never advanced.
+        if (!signal.aborted)
+            this.readers.set(reader, start);
+        signal.addEventListener('abort', release, { once: true });
+        const cleanup = () => { signal.removeEventListener('abort', release); release(); };
+        const iterator = this.readFrom(start, reader, signal, cleanup);
+        const finish = iterator.return.bind(iterator);
+        const fail = iterator.throw.bind(iterator);
+        iterator.return = async (value) => { cancelled.abort(); cleanup(); return finish(value); };
+        iterator.throw = async (error) => { cancelled.abort(); cleanup(); return fail(error); };
+        return iterator;
     }
-    async *readFrom(start, abortSignal) {
+    async *readFrom(start, reader, abortSignal, cleanup) {
         let index = start;
-        while (true) {
-            while (index < this.entries.length)
-                yield this.entries[index++];
-            if (this.closed) {
-                if (this.failure !== undefined)
-                    throw this.failure;
-                return;
+        try {
+            while (true) {
+                while (index < this.nextIndex) {
+                    if (abortSignal.aborted)
+                        return;
+                    if (index < this.firstIndex) {
+                        throw new Error('Replay cursor expired; restore persisted history and subscribe from the latest sequence.');
+                    }
+                    const value = this.entries.get(index);
+                    this.readers.set(reader, ++index);
+                    this.prune();
+                    yield value;
+                }
+                if (this.closed) {
+                    if (this.failure !== undefined)
+                        throw this.failure;
+                    return;
+                }
+                if (abortSignal.aborted)
+                    return;
+                const currentSignal = this.signal.promise;
+                await waitForSignal(currentSignal, abortSignal);
             }
-            if (abortSignal?.aborted)
-                return;
-            const currentSignal = this.signal.promise;
-            await waitForSignal(currentSignal, abortSignal);
         }
+        finally {
+            cleanup();
+        }
+    }
+    prune() {
+        if (this.retention === Infinity)
+            return;
+        let before = this.nextIndex - this.retention;
+        for (const index of this.readers.values())
+            before = Math.min(before, index);
+        while (this.firstIndex < before)
+            this.entries.delete(this.firstIndex++);
     }
     wake() {
         const previous = this.signal;

package/dist/session-context-fence.d.ts

@@ -0,0 +1,16 @@
+import type { SessionManager } from "./session.js";
+/** The revision of a host's resident history, not the manager's refreshed log.
+ * Reads and audit/metadata refreshes never legitimize a foreign conversation.
+ * Local clear/rewind/manual compaction replace history explicitly; other local
+ * writes advance the fence only when they extend the host's existing snapshot.
+ */
+export declare class SessionContextFence {
+    private readonly session;
+    private revision;
+    private readonly unsubscribe;
+    constructor(session: SessionManager);
+    getRevision(): string;
+    /** Call only alongside replacing the host's resident messages. */
+    reloadHistory(): import("./types.js").Message[];
+    dispose(): void;
+}

package/dist/session-context-fence.js

@@ -0,0 +1,26 @@
+/** The revision of a host's resident history, not the manager's refreshed log.
+ * Reads and audit/metadata refreshes never legitimize a foreign conversation.
+ * Local clear/rewind/manual compaction replace history explicitly; other local
+ * writes advance the fence only when they extend the host's existing snapshot.
+ */
+export class SessionContextFence {
+    session;
+    revision;
+    unsubscribe;
+    constructor(session) {
+        this.session = session;
+        this.revision = session.getRevision();
+        this.unsubscribe = session.subscribeContextCommits((previous, revision, replacement) => {
+            if (replacement || previous === this.revision)
+                this.revision = revision;
+        });
+    }
+    getRevision() { return this.revision; }
+    /** Call only alongside replacing the host's resident messages. */
+    reloadHistory() {
+        const messages = this.session.getMessages();
+        this.revision = this.session.getRevision();
+        return messages;
+    }
+    dispose() { this.unsubscribe(); }
+}

package/dist/session-log.d.ts

@@ -1,15 +1,24 @@
 import type { Message } from "./types.js";
-import type { SessionLogEntry, SessionMarkerKind, SessionMetadata, SessionProviderErrorEntry, SessionSummaryEntry } from "./session-types.js";
+import type { SessionLogEntry, SessionMarkerKind, SessionMetadata, SessionProviderErrorEntry } from "./session-types.js";
 import type { SanitizedProviderError } from "./provider-error-record.js";
+/** Records that change conversational context or its execution state.
+ * Keep this shared by revision hashing and checkpoint receipt supersession.
+ * Unknown/new markers are conservative: only known diagnostics are excluded.
+ */
+export declare function affectsContextRevision(entry: SessionLogEntry): boolean;
 export declare class SessionLog {
     private entries;
+    private nextId;
+    private contextRevision;
+    private allocateId;
+    appendEntries(entries: SessionLogEntry[]): void;
+    getRevision(): string;
     load(lines: string[]): void;
     replace(entries: SessionLogEntry[]): void;
     list(): SessionLogEntry[];
     getMetadata(): SessionMetadata;
     setMetadata(metadata: SessionMetadata): SessionLogEntry[];
     appendMessage(message: Message): SessionLogEntry[];
-    appendSummary(summary: string): SessionSummaryEntry;
     appendMarker(kind: SessionMarkerKind, value: string): SessionLogEntry;
     appendProviderError(error: SanitizedProviderError): SessionProviderErrorEntry;
     toMessages(): Message[];

package/dist/session-log.js

@@ -1,12 +1,42 @@
+import { createHash } from "node:crypto";
 import { sanitizeAssistantProviderMetadata, sanitizeInternalReasoningText, sanitizeInternalReminderBlocks, } from "./agent/internal-reminder-sanitizer.js";
+import { tryCheckpointMessages } from "./context/checkpoint.js";
+import { isPermissionModeReminder, reminderForMode } from "./prompt/reminders.js";
+/** Records that change conversational context or its execution state.
+ * Keep this shared by revision hashing and checkpoint receipt supersession.
+ * Unknown/new markers are conservative: only known diagnostics are excluded.
+ */
+export function affectsContextRevision(entry) {
+    if (entry.type === "metadata" || entry.type === "provider_error")
+        return false;
+    if (entry.type === "marker") {
+        return !["task_started", "task_finished", "task_killed"].includes(entry.kind);
+    }
+    return true;
+}
 export class SessionLog {
     entries = [];
+    nextId = 1;
+    contextRevision = "empty";
+    allocateId() { return String(this.nextId++); }
+    appendEntries(entries) {
+        this.entries.push(...entries);
+        for (const entry of entries) {
+            this.nextId = Math.max(this.nextId, (parseInt(entry.id, 10) || 0) + 1);
+            if (affectsContextRevision(entry)) {
+                this.contextRevision = createHash("sha256").update(this.contextRevision).update(JSON.stringify(entry)).digest("hex");
+            }
+        }
+    }
+    getRevision() { return this.contextRevision; }
     load(lines) {
         this.entries = [];
+        this.nextId = 1;
+        this.contextRevision = "empty";
         for (const line of lines) {
             try {
                 const raw = JSON.parse(line);
-                this.entries.push(...normalizeEntry(raw));
+                this.appendEntries(normalizeEntry(raw));
             }
             catch {
                 // skip corrupt lines
@@ -14,13 +44,23 @@ export class SessionLog {
         }
     }
     replace(entries) {
-        this.entries = entries;
+        this.entries = [];
+        this.nextId = 1;
+        this.contextRevision = "empty";
+        this.appendEntries(entries);
     }
     list() {
         return [...this.entries];
     }
     getMetadata() {
-        const entry = this.entries.find((item) => item.type === "metadata");
+        let entry;
+        for (let i = this.entries.length - 1; i >= 0; i--) {
+            const item = this.entries[i];
+            if (item.type === "metadata") {
+                entry = item;
+                break;
+            }
+        }
         const metadata = entry?.metadata ?? {};
         return {
             ...metadata,
@@ -46,50 +86,49 @@ export class SessionLog {
         return next;
     }
     appendMessage(message) {
-        const normalized = normalizeMessageToEntries(message, nextEntryId(this.entries), Date.now());
-        this.entries.push(...normalized);
+        const normalized = normalizeMessageToEntries(message, this.allocateId(), Date.now());
+        this.appendEntries(normalized);
         return normalized;
     }
-    appendSummary(summary) {
-        const entry = {
-            id: nextEntryId(this.entries),
-            type: "summary",
-            summary,
-            timestamp: Date.now(),
-        };
-        this.entries.push(entry);
-        return entry;
-    }
     appendMarker(kind, value) {
         const entry = {
-            id: nextEntryId(this.entries),
+            id: this.allocateId(),
             type: "marker",
             kind,
             value,
             timestamp: Date.now(),
         };
-        this.entries.push(entry);
+        this.appendEntries([entry]);
         return entry;
     }
     appendProviderError(error) {
         const entry = {
-            id: nextEntryId(this.entries),
+            id: this.allocateId(),
             type: "provider_error",
             error,
             timestamp: Date.now(),
         };
-        this.entries.push(entry);
+        this.appendEntries([entry]);
         return entry;
     }
     toMessages() {
         const messages = [];
         let latestSummaryIndex = -1;
         let latestClearIndex = -1;
+        // An unreadable checkpoint is skipped, not fatal: its originals are still in
+        // the log, so replay continues from the previous readable boundary.
+        let checkpointProjection;
         for (let index = this.entries.length - 1; index >= 0; index--) {
-            if (this.entries[index].type === "summary") {
-                latestSummaryIndex = index;
-                break;
+            const entry = this.entries[index];
+            if (entry.type === "context_checkpoint") {
+                checkpointProjection = tryCheckpointMessages(entry.checkpoint);
+                if (!checkpointProjection)
+                    continue;
             }
+            else if (entry.type !== "summary")
+                continue;
+            latestSummaryIndex = index;
+            break;
         }
         for (let index = this.entries.length - 1; index >= 0; index--) {
             const entry = this.entries[index];
@@ -99,17 +138,49 @@ export class SessionLog {
             }
         }
         if (latestSummaryIndex > latestClearIndex) {
-            const summary = this.entries[latestSummaryIndex];
-            messages.push({
-                role: "system",
-                content: `Previous conversation summary: ${summary.summary}`,
-            });
+            const entry = this.entries[latestSummaryIndex];
+            if (entry.type === "context_checkpoint") {
+                messages.push(...(checkpointProjection ?? []));
+            }
+            else if (entry.type === "summary") {
+                // Legacy summaries remain readable; already discarded originals cannot be reconstructed.
+                messages.push({ role: "system", content: `Previous conversation summary: ${entry.summary}` });
+            }
         }
         const startIndex = Math.max(latestSummaryIndex > latestClearIndex ? latestSummaryIndex + 1 : 0, latestClearIndex + 1);
+        const committedPrefixLength = latestSummaryIndex > latestClearIndex
+            && this.entries[latestSummaryIndex].type === "context_checkpoint" ? messages.length : 0;
+        // Every checkpoint past the readable boundary is unreadable by construction.
+        // Its projection is unusable, but its position still proves the originals
+        // before it were committed at a complete-tool-group model boundary.
+        let unreadableBoundaryLength = 0;
+        // Permission-mode switches become mode reminders where they happened, so
+        // the model reads the mode timeline in order: a later "plan mode is
+        // active" outranks an earlier tool result saying the mode went back to
+        // default. A switch is written out before the next user message (never
+        // inside a tool group); one from before a compaction/clear boundary still
+        // applies and opens the replayed history.
+        let pendingMode = lastModeSwitchBefore(this.entries, startIndex);
+        const flushMode = () => {
+            if (pendingMode === undefined)
+                return;
+            messages.push({ role: "meta", kind: "system-reminder", content: reminderForMode(pendingMode) });
+            pendingMode = undefined;
+        };
         for (let index = startIndex; index < this.entries.length; index++) {
             const entry = this.entries[index];
             switch (entry.type) {
+                case "marker": {
+                    const mode = entry.kind === "mode_switch" ? permissionModeOf(entry.value) : undefined;
+                    if (mode)
+                        pendingMode = mode;
+                    break;
+                }
+                case "context_checkpoint":
+                    unreadableBoundaryLength = messages.length;
+                    break;
                 case "user_message":
+                    flushMode();
                     messages.push(cloneMessage(entry.message));
                     break;
                 case "assistant_message":
@@ -120,7 +191,7 @@ export class SessionLog {
                         reasoning: entry.message.reasoning !== undefined
                             ? sanitizeInternalReasoningText(entry.message.reasoning)
                             : undefined,
-                        providerMetadata: sanitizeAssistantProviderMetadata(cloneProviderMetadata(entry.message.providerMetadata)),
+                        providerMetadata: sanitizeAssistantProviderMetadata(cloneProviderMetadata(entry.message.providerMetadata), entry.message.modelId ?? entry.message.model),
                     });
                     break;
                 case "tool_call": {
@@ -145,6 +216,34 @@ export class SessionLog {
                     break;
             }
         }
+        flushMode();
+        retireStaleModeReminders(messages);
+        // A committed checkpoint may end in completed tools without a final text
+        // response. It is a resumable model boundary, not an interrupted user turn.
+        const boundary = Math.max(committedPrefixLength, unreadableBoundaryLength);
+        if (boundary > 0) {
+            let head = messages.slice(0, boundary);
+            if (unreadableBoundaryLength > committedPrefixLength) {
+                // Replayed originals, not a validated projection: hold the turn the
+                // boundary split to complete-tool-group semantics, as its continuation is.
+                let turnStart = head.length;
+                for (let i = head.length - 1; i >= committedPrefixLength; i--) {
+                    if (head[i].role === "user") {
+                        turnStart = i;
+                        break;
+                    }
+                }
+                head = [...head.slice(0, turnStart), ...pruneIncompleteToolGroups(head.slice(turnStart))];
+            }
+            const tail = messages.slice(boundary);
+            const nextUser = tail.findIndex(message => message.role === "user");
+            const continuationEnd = nextUser < 0 ? tail.length : nextUser;
+            return [
+                ...head,
+                ...pruneIncompleteToolGroups(tail.slice(0, continuationEnd)),
+                ...pruneIncompleteTail(tail.slice(continuationEnd)),
+            ];
+        }
         return pruneIncompleteTail(messages);
     }
 }
@@ -193,7 +292,7 @@ function normalizeMessageToEntries(message, id, timestamp) {
                     usage: message.usage,
                     systemFingerprint: message.systemFingerprint,
                     error: message.error,
-                    providerMetadata: sanitizeAssistantProviderMetadata(cloneProviderMetadata(message.providerMetadata)),
+                    providerMetadata: sanitizeAssistantProviderMetadata(cloneProviderMetadata(message.providerMetadata), message.modelId ?? message.model),
                 },
                 timestamp,
             };
@@ -221,6 +320,7 @@ function normalizeMessageToEntries(message, id, timestamp) {
 function isSessionLogEntry(entry) {
     return [
         "metadata",
+        "context_checkpoint",
         "summary",
         "marker",
         "user_message",
@@ -230,16 +330,6 @@ function isSessionLogEntry(entry) {
         "provider_error",
     ].includes(entry.type);
 }
-function nextEntryId(entries) {
-    let max = 0;
-    for (const entry of entries) {
-        const match = /^(\d+)/.exec(entry.id);
-        if (!match)
-            continue;
-        max = Math.max(max, Number(match[1]));
-    }
-    return `${max + 1}`;
-}
 function cloneMessage(message) {
     if (message.role === "assistant") {
         return {
@@ -264,6 +354,64 @@ function cloneProviderMetadata(metadata) {
         return undefined;
     return JSON.parse(JSON.stringify(metadata));
 }
+// A checkpoint can split a user turn. Its continuation has no user anchor,
+// so validate complete tool groups directly rather than relying on turn pruning.
+const PERMISSION_MODES = new Set(["default", "plan", "bypassPermissions"]);
+function permissionModeOf(value) {
+    return PERMISSION_MODES.has(value) ? value : undefined;
+}
+function lastModeSwitchBefore(entries, end) {
+    for (let index = end - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry.type === "marker" && entry.kind === "mode_switch") {
+            const mode = permissionModeOf(entry.value);
+            if (mode)
+                return mode;
+        }
+    }
+    return undefined;
+}
+/** Only the latest mode reminder speaks to the model, as in a live agent. */
+function retireStaleModeReminders(messages) {
+    let latest = true;
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message.role !== "meta" || message.kind !== "system-reminder" || !isPermissionModeReminder(message.content))
+            continue;
+        if (latest)
+            latest = false;
+        else
+            message.includeInLlm = false;
+    }
+}
+function pruneIncompleteToolGroups(messages) {
+    const pending = new Set();
+    let groupStart = -1;
+    for (let index = 0; index < messages.length; index++) {
+        const message = messages[index];
+        if (message.role === "system" || message.role === "meta")
+            continue;
+        if (message.role === "tool") {
+            if (!pending.delete(message.toolCallId))
+                return messages.slice(0, groupStart < 0 ? index : groupStart);
+            if (pending.size === 0)
+                groupStart = -1;
+        }
+        else {
+            if (pending.size)
+                return messages.slice(0, groupStart);
+            if (message.role === "assistant" && message.toolCalls?.length) {
+                groupStart = index;
+                for (const call of message.toolCalls) {
+                    if (!call.id || pending.has(call.id))
+                        return messages.slice(0, groupStart);
+                    pending.add(call.id);
+                }
+            }
+        }
+    }
+    return pending.size ? messages.slice(0, groupStart) : messages;
+}
 function pruneIncompleteTail(messages) {
     let currentTurnStart = -1;
     let hasCompletedAssistant = false;

package/dist/session-types.d.ts

@@ -41,6 +41,10 @@ export interface SessionMetadataEntry extends BaseSessionLogEntry {
     type: "metadata";
     metadata: SessionMetadata;
 }
+export interface SessionContextCheckpointEntry extends BaseSessionLogEntry {
+    type: "context_checkpoint";
+    checkpoint: import("./context/checkpoint.js").ContextCheckpoint;
+}
 export interface SessionSummaryEntry extends BaseSessionLogEntry {
     type: "summary";
     summary: string;
@@ -70,7 +74,7 @@ export interface SessionProviderErrorEntry extends BaseSessionLogEntry {
     type: "provider_error";
     error: SanitizedProviderError;
 }
-export type SessionLogEntry = SessionMetadataEntry | SessionSummaryEntry | SessionMarkerEntry | SessionUserMessageEntry | SessionAssistantMessageEntry | SessionToolCallEntry | SessionToolResultEntry | SessionProviderErrorEntry;
+export type SessionLogEntry = SessionMetadataEntry | SessionSummaryEntry | SessionContextCheckpointEntry | SessionMarkerEntry | SessionUserMessageEntry | SessionAssistantMessageEntry | SessionToolCallEntry | SessionToolResultEntry | SessionProviderErrorEntry;
 export interface LegacySessionEntry {
     id: string;
     type: "metadata" | "message" | "compaction";

package/dist/session.d.ts

@@ -4,6 +4,7 @@
 import { CheckpointStore } from "./checkpoints.js";
 import { type CompactOptions, type CompactResult } from "./context/compact.js";
 import type { Message } from "./types.js";
+import { type ContextCheckpoint } from "./context/checkpoint.js";
 import type { SessionLogEntry, SessionMarkerKind, SessionMetadata } from "./session-types.js";
 import type { SanitizedProviderError } from "./provider-error-record.js";
 export interface SessionSummary {
@@ -27,6 +28,15 @@ export interface UserTurn {
     text: string;
     timestamp: number;
 }
+/** A fenced write found the session log diverged from the writer's resident
+ * snapshot — a foreign append, clear, or rewind landed while a turn was in
+ * flight. The write is refused; the host must roll its resident history back
+ * to the file's truth (SessionContextFence.reloadHistory, then replace the
+ * agent's messages) before writing again, or every later fenced write keeps
+ * rejecting on the stale revision. */
+export declare class SessionHistoryDivergedError extends Error {
+    constructor(message?: string);
+}
 export interface RewindResult {
     /** Number of log entries removed. */
     removedEntries: number;
@@ -37,7 +47,18 @@ export declare class SessionManager {
     private sessionFile;
     private log;
     private checkpoints?;
+    private diskRevision;
+    private pendingCompaction?;
+    /** Conversational revision excludes metadata-only writes (for example titles). */
+    getRevision(): string;
+    private refresh;
+    private currentDiskRevision;
+    private withWriteLock;
     private readonly metadataListeners;
+    private readonly contextListeners;
+    /** Local commits only: disk refreshes must never advance a host's history fence. */
+    subscribeContextCommits(listener: (previous: string, revision: string, replacement: boolean) => void): () => void;
+    private publishContextCommit;
     constructor(sessionFile: string);
     static create(cwd: string, sessionName?: string): SessionManager;
     static resume(cwd: string, sessionName?: string): SessionManager | undefined;
@@ -47,6 +68,8 @@ export declare class SessionManager {
     static listAllSessions(): SessionSummary[];
     private load;
     private persist;
+    /** Refresh, derive the replacement from the refreshed log, and swap the file
+     * as one locked transaction; `derive` returning undefined leaves it untouched. */
     private rewrite;
     getMetadata(): SessionMetadata;
     /**
@@ -57,13 +80,17 @@ export declare class SessionManager {
     subscribeMetadata(listener: (metadata: SessionMetadata) => void): () => void;
     getOrCreatePromptCacheKey(): string;
     setMetadata(metadata: SessionMetadata): void;
+    /** Refresh, derive, and append as one locked transaction. Metadata records
+     * are full snapshots, so a snapshot built outside the lock would silently
+     * overwrite a concurrent writer's fields. */
+    mutateMetadata(build: (current: SessionMetadata) => SessionMetadata): void;
     updateMetadata(patch: Partial<SessionMetadata>): void;
     clearTitleMetadata(): void;
     clearExternalRuntimeMetadata(): void;
-    appendMessage(message: Message): void;
-    appendCompaction(summary: string): void;
-    appendMarker(kind: SessionMarkerKind, value: string): void;
-    appendProviderError(error: SanitizedProviderError): void;
+    appendMessage(message: Message, expectedRevision?: string): void;
+    private reloadAfterWriteFailure;
+    appendMarker(kind: SessionMarkerKind, value: string, expectedRevision?: string): void;
+    appendProviderError(error: SanitizedProviderError, expectedRevision?: string): void;
     compact(options?: CompactOptions): CompactResult;
     /**
      * Inspect whether the session is large enough to compact and, if so, return
@@ -76,7 +103,7 @@ export declare class SessionManager {
     } | null;
     /**
      * Apply a precomputed (typically LLM-generated) summary as the compaction
-     * checkpoint, rewriting the log to [metadata, summary, kept turns]. Mirrors
+     * checkpoint, appending an exact projection without deleting originals. Mirrors
      * `compact()` but skips the built-in heuristic summarizer. Returns
      * `{ compacted: false }` if the session is no longer compactable.
      */
@@ -87,7 +114,11 @@ export declare class SessionManager {
      * Lives next to the session JSONL as `<session>.checkpoints/`.
      */
     getCheckpoints(): CheckpointStore;
-    /** Entry id of the most recent user message, or "0" before the first one. */
+    /**
+     * Entry id of the most recent user turn (as listUserTurns counts them), or
+     * "0" before the first one. Checkpoints are keyed by it, so edits made after
+     * a tool screenshot or a harness-injected block stay with the user's turn.
+     */
     lastUserEntryId(): string;
     /** User messages after the latest /clear, oldest first — the valid rewind anchors. */
     listUserTurns(): UserTurn[];
@@ -98,6 +129,7 @@ export declare class SessionManager {
     rewindToEntry(entryId: string): RewindResult | undefined;
     getEntries(): SessionLogEntry[];
     getSessionFile(): string;
-    private maybeAutoCompact;
+    /** Commit the exact conversational projection, never delete its source history. */
+    commitContextCheckpoint(checkpoint: ContextCheckpoint, expectedRevision?: string): void;
 }
 export declare function getSessionsDir(cwd: string): string;