@martian-engineering/lossless-claw 0.6.3 → 0.7.0

package/src/plugin/lcm-command.ts

@@ -710,35 +710,41 @@ async function buildDoctorApplyText(params: {
 }
 
 export function createLcmCommand(params: {
-  db: DatabaseSync;
+  db: DatabaseSync | (() => DatabaseSync | Promise<DatabaseSync>);
   config: LcmConfig;
   deps?: LcmDependencies;
   summarize?: LcmSummarizeFn;
 }): OpenClawPluginCommandDefinition {
+  const getDb = async (): Promise<DatabaseSync> =>
+    typeof params.db === "function" ? await params.db() : params.db;
+
   return {
     name: "lcm",
     nativeNames: {
       default: "lossless",
     },
+    nativeProgressMessages: {
+      telegram: "Lossless Claw is working...",
+    },
     description: "Show Lossless Claw health, scan broken summaries, and repair scoped doctor issues.",
     acceptsArgs: true,
     handler: async (ctx) => {
       const parsed = parseLcmCommand(ctx.args);
       switch (parsed.kind) {
         case "status":
-          return { text: await buildStatusText({ ctx, db: params.db, config: params.config }) };
+          return { text: await buildStatusText({ ctx, db: await getDb(), config: params.config }) };
         case "doctor":
           return parsed.apply
             ? {
                 text: await buildDoctorApplyText({
                   ctx,
-                  db: params.db,
+                  db: await getDb(),
                   config: params.config,
                   deps: params.deps,
                   summarize: params.summarize,
                 }),
               }
-            : { text: await buildDoctorText({ ctx, db: params.db }) };
+            : { text: await buildDoctorText({ ctx, db: await getDb() }) };
         case "help":
           return { text: buildHelpText(parsed.error) };
       }

package/src/plugin/shared-init.ts

@@ -0,0 +1,59 @@
+/**
+ * Process-global singleton state for LCM plugin initialization.
+ *
+ * OpenClaw v2026.4.5+ calls plugin register() per-agent-context (main,
+ * subagents, cron lanes). Without sharing, each call opens a new DB
+ * connection and runs migrations — causing lock storms on large databases.
+ *
+ * Uses the same globalThis + Symbol.for() pattern as startup-banner-log.ts
+ * to ensure one DB connection and engine per database path per process.
+ *
+ * The shared state stores the waitForEngine/waitForDatabase closures from
+ * the first register() call. These closures close over the local init
+ * variables (database, lcm, initPromise, etc.) so all subsequent callers
+ * share the same deferred init chain without stale-reference issues.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { LcmContextEngine } from "../engine.js";
+
+export type SharedLcmInit = {
+  /** Whether gateway_stop has been called. */
+  stopped: boolean;
+  /** Sync accessor — returns the engine if already initialized, null otherwise. */
+  getCachedEngine: () => LcmContextEngine | null;
+  /** Async accessor for the initialized engine (waits for deferred init). */
+  waitForEngine: () => Promise<LcmContextEngine>;
+  /** Async accessor for the initialized DB handle (waits for deferred init). */
+  waitForDatabase: () => Promise<DatabaseSync>;
+};
+
+const SHARED_KEY = Symbol.for(
+  "@martian-engineering/lossless-claw/shared-init",
+);
+
+function getStore(): Map<string, SharedLcmInit> {
+  const g = globalThis as typeof globalThis & {
+    [key: symbol]: Map<string, SharedLcmInit> | undefined;
+  };
+  if (!g[SHARED_KEY]) {
+    g[SHARED_KEY] = new Map();
+  }
+  return g[SHARED_KEY]!;
+}
+
+export function getSharedInit(dbPath: string): SharedLcmInit | undefined {
+  return getStore().get(dbPath);
+}
+
+export function setSharedInit(dbPath: string, init: SharedLcmInit): void {
+  getStore().set(dbPath, init);
+}
+
+export function removeSharedInit(dbPath: string): void {
+  getStore().delete(dbPath);
+}
+
+/** Clear all shared init state. Intended for tests only. */
+export function clearAllSharedInit(): void {
+  getStore().clear();
+}

package/src/prune.ts

@@ -0,0 +1,391 @@
+/**
+ * Conversation pruning for data retention.
+ *
+ * Identifies and deletes conversations where ALL messages are older than a
+ * given threshold.  Relies on ON DELETE CASCADE foreign keys in the schema
+ * to clean up messages, summaries, context_items, and other dependent rows.
+ */
+import type { DatabaseSync } from "node:sqlite";
+
+// ── Duration parsing ────────────────────────────────────────────────────────
+
+const DURATION_RE = /^(\d+)\s*(d|day|days|w|week|weeks|m|month|months|y|year|years)$/i;
+
+const UNIT_TO_DAYS: Record<string, number> = {
+  d: 1,
+  day: 1,
+  days: 1,
+  w: 7,
+  week: 7,
+  weeks: 7,
+  m: 30,
+  month: 30,
+  months: 30,
+  y: 365,
+  year: 365,
+  years: 365,
+};
+
+/**
+ * Parse a human-friendly duration string (e.g. "90d", "3m", "1y") into
+ * a number of days.  Returns `null` when the input is not recognized.
+ */
+export function parseDuration(input: string): number | null {
+  const trimmed = input.trim().toLowerCase();
+  const match = DURATION_RE.exec(trimmed);
+  if (!match) {
+    return null;
+  }
+  const amount = Number(match[1]);
+  const unit = match[2]!.toLowerCase();
+  const multiplier = UNIT_TO_DAYS[unit];
+  if (multiplier == null || !Number.isFinite(amount) || amount <= 0) {
+    return null;
+  }
+  return amount * multiplier;
+}
+
+// ── Prune types ─────────────────────────────────────────────────────────────
+
+export type PruneCandidate = {
+  conversationId: number;
+  sessionKey: string | null;
+  messageCount: number;
+  summaryCount: number;
+  latestMessageAt: string;
+  createdAt: string;
+};
+
+export type PruneResult = {
+  /** Conversations that matched the age threshold. */
+  candidates: PruneCandidate[];
+  /** Number of conversations actually deleted (0 in dry-run mode). */
+  deleted: number;
+  /** Whether VACUUM was executed after deletion. */
+  vacuumed: boolean;
+  /** The cutoff date used (ISO-8601 UTC string). */
+  cutoffDate: string;
+};
+
+export type PruneOptions = {
+  /** Duration string, e.g. "90d", "30d", "1y". */
+  before: string;
+  /** When true, actually delete. Default is dry-run (false). */
+  confirm?: boolean;
+  /** Maximum conversations to delete per write transaction. Default 100. */
+  batchSize?: number;
+  /** Maximum delete batches to run before returning. Default unlimited. */
+  maxBatches?: number;
+  /** When true, run VACUUM after deletion. Default false. */
+  vacuum?: boolean;
+  /** Override "now" for testing. ISO-8601 UTC string. */
+  now?: string;
+};
+
+// ── Core prune logic ────────────────────────────────────────────────────────
+
+type PruneCandidateRow = {
+  conversation_id: number;
+  session_key: string | null;
+  message_count: number;
+  summary_count: number;
+  latest_message_at: string;
+  created_at: string;
+};
+
+const SELECT_PRUNE_CANDIDATES_SQL = `SELECT
+   c.conversation_id,
+   c.session_key,
+   COALESCE(msg_stats.message_count, 0) AS message_count,
+   COALESCE(sum_stats.summary_count, 0) AS summary_count,
+   COALESCE(msg_stats.latest_message_at, c.created_at) AS latest_message_at,
+   c.created_at
+ FROM conversations c
+ LEFT JOIN (
+   SELECT conversation_id,
+          COUNT(*) AS message_count,
+          MAX(created_at) AS latest_message_at
+   FROM messages
+   GROUP BY conversation_id
+ ) msg_stats ON msg_stats.conversation_id = c.conversation_id
+ LEFT JOIN (
+   SELECT conversation_id,
+          COUNT(*) AS summary_count
+   FROM summaries
+   GROUP BY conversation_id
+ ) sum_stats ON sum_stats.conversation_id = c.conversation_id
+ WHERE julianday(COALESCE(msg_stats.latest_message_at, c.created_at)) < julianday(?)
+ ORDER BY julianday(COALESCE(msg_stats.latest_message_at, c.created_at)) ASC,
+          c.conversation_id ASC`;
+
+/**
+ * Compute the UTC cutoff date by subtracting `days` from `now`.
+ */
+function computeCutoffDate(days: number, now?: string): string {
+  const base = now ? new Date(now) : new Date();
+  base.setUTCDate(base.getUTCDate() - days);
+  return base.toISOString();
+}
+
+/**
+ * Normalize prune batch size to a small positive integer.
+ */
+function resolveBatchSize(batchSize?: number): number {
+  if (batchSize == null) {
+    return 100;
+  }
+  if (!Number.isFinite(batchSize) || batchSize <= 0) {
+    throw new Error(`Invalid batch size "${batchSize}". Expected a positive integer.`);
+  }
+  return Math.floor(batchSize);
+}
+
+/**
+ * Normalize the optional batch cap for confirm-mode pruning.
+ */
+function resolveMaxBatches(maxBatches?: number): number | null {
+  if (maxBatches == null) {
+    return null;
+  }
+  if (!Number.isFinite(maxBatches) || maxBatches <= 0) {
+    throw new Error(`Invalid max batches "${maxBatches}". Expected a positive integer.`);
+  }
+  return Math.floor(maxBatches);
+}
+
+/**
+ * Load prune candidates using SQLite date math so mixed timestamp formats are
+ * compared chronologically instead of lexically.
+ */
+function loadPruneCandidates(
+  db: DatabaseSync,
+  cutoffDate: string,
+  limit?: number,
+): PruneCandidate[] {
+  const sql = limit == null ? SELECT_PRUNE_CANDIDATES_SQL : `${SELECT_PRUNE_CANDIDATES_SQL}\n LIMIT ?`;
+  const rows = (
+    limit == null
+      ? db.prepare(sql).all(cutoffDate)
+      : db.prepare(sql).all(cutoffDate, limit)
+  ) as PruneCandidateRow[];
+  return rows.map((row) => ({
+    conversationId: row.conversation_id,
+    sessionKey: row.session_key,
+    messageCount: row.message_count,
+    summaryCount: row.summary_count,
+    latestMessageAt: row.latest_message_at,
+    createdAt: row.created_at,
+  }));
+}
+
+/**
+ * Detect whether an optional SQLite table exists.
+ */
+function hasTable(db: DatabaseSync, tableName: string): boolean {
+  const row = db
+    .prepare(`SELECT 1 AS found FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1`)
+    .get(tableName) as { found: number } | undefined;
+  return row?.found === 1;
+}
+
+/**
+ * Create temp tables containing the conversations, summaries, and messages
+ * selected for pruning so dependent deletes can use simple indexed lookups.
+ */
+function stageCandidateConversationIds(
+  db: DatabaseSync,
+  candidates: PruneCandidate[],
+): void {
+  db.exec(`DROP TABLE IF EXISTS temp.prune_candidate_ids`);
+  db.exec(`DROP TABLE IF EXISTS temp.prune_candidate_summary_ids`);
+  db.exec(`DROP TABLE IF EXISTS temp.prune_candidate_message_ids`);
+  db.exec(`CREATE TEMP TABLE prune_candidate_ids (conversation_id INTEGER PRIMARY KEY)`);
+  db.exec(`CREATE TEMP TABLE prune_candidate_summary_ids (summary_id TEXT PRIMARY KEY)`);
+  db.exec(`CREATE TEMP TABLE prune_candidate_message_ids (message_id INTEGER PRIMARY KEY)`);
+  const insertStmt = db.prepare(
+    `INSERT INTO temp.prune_candidate_ids (conversation_id) VALUES (?)`,
+  );
+  for (const candidate of candidates) {
+    insertStmt.run(candidate.conversationId);
+  }
+  db.exec(`
+    INSERT INTO temp.prune_candidate_summary_ids (summary_id)
+    SELECT s.summary_id
+    FROM summaries s
+    JOIN temp.prune_candidate_ids p ON p.conversation_id = s.conversation_id
+  `);
+  db.exec(`
+    INSERT INTO temp.prune_candidate_message_ids (message_id)
+    SELECT m.message_id
+    FROM messages m
+    JOIN temp.prune_candidate_ids p ON p.conversation_id = m.conversation_id
+  `);
+}
+
+/**
+ * Remove the temp candidate table.
+ */
+function dropCandidateConversationIds(db: DatabaseSync): void {
+  db.exec(`DROP TABLE IF EXISTS temp.prune_candidate_message_ids`);
+  db.exec(`DROP TABLE IF EXISTS temp.prune_candidate_summary_ids`);
+  db.exec(`DROP TABLE IF EXISTS temp.prune_candidate_ids`);
+}
+
+/**
+ * Delete candidate conversations and return the number of rows removed.
+ */
+function deleteCandidates(db: DatabaseSync, candidates: PruneCandidate[]): number {
+  if (candidates.length === 0) {
+    return 0;
+  }
+
+  const tableOptions = {
+    hasMessagesFts: hasTable(db, "messages_fts"),
+    hasSummariesFts: hasTable(db, "summaries_fts"),
+    hasSummariesFtsCjk: hasTable(db, "summaries_fts_cjk"),
+  };
+
+  stageCandidateConversationIds(db, candidates);
+  try {
+    db.prepare(
+      `DELETE FROM summary_messages
+       WHERE summary_id IN (SELECT summary_id FROM temp.prune_candidate_summary_ids)`,
+    ).run();
+
+    db.prepare(
+      `DELETE FROM summary_messages
+       WHERE message_id IN (SELECT message_id FROM temp.prune_candidate_message_ids)`,
+    ).run();
+
+    db.prepare(
+      `DELETE FROM summary_parents
+       WHERE summary_id IN (SELECT summary_id FROM temp.prune_candidate_summary_ids)`,
+    ).run();
+
+    db.prepare(
+      `DELETE FROM summary_parents
+       WHERE parent_summary_id IN (SELECT summary_id FROM temp.prune_candidate_summary_ids)`,
+    ).run();
+
+    db.prepare(
+      `DELETE FROM context_items
+       WHERE message_id IN (SELECT message_id FROM temp.prune_candidate_message_ids)`,
+    ).run();
+
+    db.prepare(
+      `DELETE FROM context_items
+       WHERE summary_id IN (SELECT summary_id FROM temp.prune_candidate_summary_ids)`,
+    ).run();
+
+    db.prepare(
+      `DELETE FROM context_items
+       WHERE conversation_id IN (SELECT conversation_id FROM temp.prune_candidate_ids)`,
+    ).run();
+
+    if (tableOptions.hasMessagesFts) {
+      db.prepare(
+        `DELETE FROM messages_fts
+         WHERE rowid IN (SELECT message_id FROM temp.prune_candidate_message_ids)`,
+      ).run();
+    }
+
+    if (tableOptions.hasSummariesFts) {
+      db.prepare(
+        `DELETE FROM summaries_fts
+         WHERE summary_id IN (SELECT summary_id FROM temp.prune_candidate_summary_ids)`,
+      ).run();
+    }
+
+    if (tableOptions.hasSummariesFtsCjk) {
+      db.prepare(
+        `DELETE FROM summaries_fts_cjk
+         WHERE summary_id IN (SELECT summary_id FROM temp.prune_candidate_summary_ids)`,
+      ).run();
+    }
+
+    return Number(
+      db
+        .prepare(
+          `DELETE FROM conversations
+           WHERE conversation_id IN (SELECT conversation_id FROM temp.prune_candidate_ids)`,
+        )
+        .run().changes ?? 0,
+    );
+  } finally {
+    dropCandidateConversationIds(db);
+  }
+}
+
+/**
+ * Prune old conversations from the LCM database.
+ *
+ * In dry-run mode (default), returns the list of conversations that would be
+ * deleted without modifying the database.  With `confirm: true`, deletes them
+ * and relies on ON DELETE CASCADE for cleanup of child rows.
+ */
+export function pruneConversations(
+  db: DatabaseSync,
+  options: PruneOptions,
+): PruneResult {
+  const days = parseDuration(options.before);
+  if (days == null) {
+    throw new Error(
+      `Invalid duration "${options.before}". Expected a value like "90d", "30d", "3m", or "1y".`,
+    );
+  }
+
+  const cutoffDate = computeCutoffDate(days, options.now);
+  const batchSize = resolveBatchSize(options.batchSize);
+  const maxBatches = resolveMaxBatches(options.maxBatches);
+
+  let deleted = 0;
+  let vacuumed = false;
+  let candidates: PruneCandidate[];
+
+  if (!options.confirm) {
+    candidates = loadPruneCandidates(db, cutoffDate);
+  } else {
+    candidates = [];
+    let batchesRun = 0;
+    while (true) {
+      let batchCount = 0;
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        const batch = loadPruneCandidates(db, cutoffDate, batchSize);
+        batchCount = batch.length;
+        if (batch.length === 0) {
+          db.exec("COMMIT");
+          break;
+        }
+        deleted += deleteCandidates(db, batch);
+        candidates.push(...batch);
+        db.exec("COMMIT");
+      } catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+      }
+      if (batchCount < batchSize) {
+        break;
+      }
+      batchesRun += 1;
+      if (maxBatches != null && batchesRun >= maxBatches) {
+        break;
+      }
+    }
+  }
+
+  if (options.vacuum && deleted > 0) {
+    db.exec("VACUUM");
+    // VACUUM in WAL mode can leave the reclaimed pages in the WAL file until
+    // a checkpoint folds them back into the main database.
+    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    vacuumed = true;
+  }
+
+  return {
+    candidates,
+    deleted,
+    vacuumed,
+    cutoffDate,
+  };
+}

package/src/retrieval.ts

@@ -9,6 +9,7 @@ import type {
   SummarySearchResult,
   LargeFileRecord,
 } from "./store/summary-store.js";
+import type { SearchSort } from "./store/full-text-sort.js";
 
 // ── Public interfaces ────────────────────────────────────────────────────────
 
@@ -68,6 +69,10 @@ export interface GrepInput {
   since?: Date;
   before?: Date;
   limit?: number;
+  /** Sort order for results. Default "recency" (newest first).
+   *  "relevance" sorts by FTS5 BM25 rank (full_text mode only).
+   *  "hybrid" blends relevance with recency. */
+  sort?: SearchSort;
 }
 
 export interface GrepResult {
@@ -222,9 +227,9 @@ export class RetrievalEngine {
    * Depending on `scope`, searches messages, summaries, or both (in parallel).
    */
   async grep(input: GrepInput): Promise<GrepResult> {
-    const { query, mode, scope, conversationId, since, before, limit } = input;
+    const { query, mode, scope, conversationId, since, before, limit, sort } = input;
 
-    const searchInput = { query, mode, conversationId, since, before, limit };
+    const searchInput = { query, mode, conversationId, since, before, limit, sort };
 
     let messages: MessageSearchResult[] = [];
     let summaries: SummarySearchResult[] = [];
@@ -241,9 +246,6 @@ export class RetrievalEngine {
       ]);
     }
 
-    messages.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
-    summaries.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
-
     return {
       messages,
       summaries,

package/src/startup-banner-log.ts

@@ -1,6 +1,7 @@
 type StartupBannerKey =
   | "plugin-loaded"
   | "compaction-model"
+  | "fallback-providers"
   | "ignore-session-patterns"
   | "stateless-session-patterns";
 

package/src/store/compaction-telemetry-store.ts

@@ -0,0 +1,156 @@
+import type { DatabaseSync } from "node:sqlite";
+import { withDatabaseTransaction } from "../transaction-mutex.js";
+import { parseUtcTimestampOrNull } from "./parse-utc-timestamp.js";
+
+export type CacheState = "hot" | "cold" | "unknown";
+export type ActivityBand = "low" | "medium" | "high";
+
+export type ConversationCompactionTelemetryRecord = {
+  conversationId: number;
+  lastObservedCacheRead: number | null;
+  lastObservedCacheWrite: number | null;
+  lastObservedCacheHitAt: Date | null;
+  lastObservedCacheBreakAt: Date | null;
+  cacheState: CacheState;
+  retention: string | null;
+  lastLeafCompactionAt: Date | null;
+  turnsSinceLeafCompaction: number;
+  tokensAccumulatedSinceLeafCompaction: number;
+  lastActivityBand: ActivityBand;
+  updatedAt: Date;
+};
+
+export type UpsertConversationCompactionTelemetryInput = {
+  conversationId: number;
+  lastObservedCacheRead?: number | null;
+  lastObservedCacheWrite?: number | null;
+  lastObservedCacheHitAt?: Date | null;
+  lastObservedCacheBreakAt?: Date | null;
+  cacheState: CacheState;
+  retention?: string | null;
+  lastLeafCompactionAt?: Date | null;
+  turnsSinceLeafCompaction?: number;
+  tokensAccumulatedSinceLeafCompaction?: number;
+  lastActivityBand?: ActivityBand;
+};
+
+type ConversationCompactionTelemetryRow = {
+  conversation_id: number;
+  last_observed_cache_read: number | null;
+  last_observed_cache_write: number | null;
+  last_observed_cache_hit_at: string | null;
+  last_observed_cache_break_at: string | null;
+  cache_state: CacheState;
+  retention: string | null;
+  last_leaf_compaction_at: string | null;
+  turns_since_leaf_compaction: number | null;
+  tokens_accumulated_since_leaf_compaction: number | null;
+  last_activity_band: ActivityBand | null;
+  updated_at: string;
+};
+
+function toConversationCompactionTelemetryRecord(
+  row: ConversationCompactionTelemetryRow,
+): ConversationCompactionTelemetryRecord {
+  return {
+    conversationId: row.conversation_id,
+    lastObservedCacheRead: row.last_observed_cache_read,
+    lastObservedCacheWrite: row.last_observed_cache_write,
+    lastObservedCacheHitAt: parseUtcTimestampOrNull(row.last_observed_cache_hit_at),
+    lastObservedCacheBreakAt: parseUtcTimestampOrNull(row.last_observed_cache_break_at),
+    cacheState: row.cache_state,
+    retention: row.retention,
+    lastLeafCompactionAt: parseUtcTimestampOrNull(row.last_leaf_compaction_at),
+    turnsSinceLeafCompaction: row.turns_since_leaf_compaction ?? 0,
+    tokensAccumulatedSinceLeafCompaction: row.tokens_accumulated_since_leaf_compaction ?? 0,
+    lastActivityBand: row.last_activity_band ?? "low",
+    updatedAt: parseUtcTimestampOrNull(row.updated_at) ?? new Date(0),
+  };
+}
+
+/**
+ * Persist and query per-conversation prompt-cache telemetry used by
+ * cache-aware incremental compaction.
+ */
+export class CompactionTelemetryStore {
+  constructor(private readonly db: DatabaseSync) {}
+
+  /** Execute multiple telemetry writes atomically. */
+  withTransaction<T>(fn: () => Promise<T>): Promise<T> {
+    return withDatabaseTransaction(this.db, "BEGIN", fn);
+  }
+
+  /** Load the latest persisted telemetry for a conversation. */
+  async getConversationCompactionTelemetry(
+    conversationId: number,
+  ): Promise<ConversationCompactionTelemetryRecord | null> {
+    const row = this.db
+      .prepare(
+        `SELECT
+           conversation_id,
+           last_observed_cache_read,
+           last_observed_cache_write,
+           last_observed_cache_hit_at,
+           last_observed_cache_break_at,
+           cache_state,
+           retention,
+           last_leaf_compaction_at,
+           turns_since_leaf_compaction,
+           tokens_accumulated_since_leaf_compaction,
+           last_activity_band,
+           updated_at
+         FROM conversation_compaction_telemetry
+         WHERE conversation_id = ?`,
+      )
+      .get(conversationId) as ConversationCompactionTelemetryRow | undefined;
+    return row ? toConversationCompactionTelemetryRecord(row) : null;
+  }
+
+  /** Upsert the current cache telemetry snapshot for a conversation. */
+  async upsertConversationCompactionTelemetry(
+    input: UpsertConversationCompactionTelemetryInput,
+  ): Promise<void> {
+    this.db
+      .prepare(
+        `INSERT INTO conversation_compaction_telemetry (
+           conversation_id,
+           last_observed_cache_read,
+           last_observed_cache_write,
+           last_observed_cache_hit_at,
+           last_observed_cache_break_at,
+           cache_state,
+           retention,
+           last_leaf_compaction_at,
+           turns_since_leaf_compaction,
+           tokens_accumulated_since_leaf_compaction,
+           last_activity_band,
+           updated_at
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+         ON CONFLICT(conversation_id) DO UPDATE SET
+           last_observed_cache_read = excluded.last_observed_cache_read,
+           last_observed_cache_write = excluded.last_observed_cache_write,
+           last_observed_cache_hit_at = excluded.last_observed_cache_hit_at,
+           last_observed_cache_break_at = excluded.last_observed_cache_break_at,
+           cache_state = excluded.cache_state,
+           retention = excluded.retention,
+           last_leaf_compaction_at = excluded.last_leaf_compaction_at,
+           turns_since_leaf_compaction = excluded.turns_since_leaf_compaction,
+           tokens_accumulated_since_leaf_compaction = excluded.tokens_accumulated_since_leaf_compaction,
+           last_activity_band = excluded.last_activity_band,
+           updated_at = datetime('now')`,
+      )
+      .run(
+        input.conversationId,
+        input.lastObservedCacheRead ?? null,
+        input.lastObservedCacheWrite ?? null,
+        input.lastObservedCacheHitAt?.toISOString() ?? null,
+        input.lastObservedCacheBreakAt?.toISOString() ?? null,
+        input.cacheState,
+        input.retention ?? null,
+        input.lastLeafCompactionAt?.toISOString() ?? null,
+        input.turnsSinceLeafCompaction ?? 0,
+        input.tokensAccumulatedSinceLeafCompaction ?? 0,
+        input.lastActivityBand ?? "low",
+      );
+  }
+}