@loicngr/kobo 1.11.16 → 1.11.18

package/dist/server/services/websocket-service.js

@@ -4,6 +4,10 @@ import { getAllPersistedSnapshots } from './usage/db.js';
 // ── State ──────────────────────────────────────────────────────────────────────
 /** Maps each WS client to the set of workspaceIds they are subscribed to */
 const clients = new Map();
+/** Above this many bytes queued for a single client, we stop sending it events
+ *  rather than growing the process heap on its behalf. It will catch up through
+ *  `sync:request` on its next reconnect. */
+const MAX_BUFFERED_BYTES = 1024 * 1024;
 let messageHandler = null;
 /** Register the handler that processes routed WS messages (e.g. chat:message, workspace:start). */
 export function setMessageHandler(handler) {
@@ -82,14 +86,28 @@ export function handleConnection(ws) {
                 ws.send(JSON.stringify({ type: 'error', payload: { message: `Unknown message type: ${type}` } }));
         }
     });
-    // Ping every 30s to keep the connection alive and detect stale clients
+    // Heartbeat with a verdict. Pinging without ever waiting for a pong detected
+    // nothing: half-open sockets stayed in `clients` for ever, and every emit
+    // kept serialising a message for a peer that will never read it.
+    let isAlive = true;
+    ws.on('pong', () => {
+        isAlive = true;
+    });
     const pingInterval = setInterval(() => {
-        if (ws.readyState === ws.OPEN) {
-            ws.ping();
+        if (ws.readyState !== 1 /* WebSocket.OPEN */) {
+            clearInterval(pingInterval);
+            clients.delete(ws);
+            return;
         }
-        else {
+        if (!isAlive) {
+            console.warn('[ws] client missed the heartbeat — terminating the connection');
             clearInterval(pingInterval);
+            clients.delete(ws);
+            ws.terminate();
+            return;
         }
+        isAlive = false;
+        ws.ping();
     }, 30_000);
     ws.on('close', () => {
         clearInterval(pingInterval);
@@ -127,6 +145,13 @@ export function emit(workspaceId, type, payload, sessionId) {
     let emitSendErrorLogged = false;
     for (const [ws, subs] of clients) {
         if (subs.has(workspaceId) && ws.readyState === 1 /* WebSocket.OPEN */) {
+            if ((ws.bufferedAmount ?? 0) > MAX_BUFFERED_BYTES) {
+                if (!emitSendErrorLogged) {
+                    console.warn(`[ws] client backlogged, dropping live events (workspace=${workspaceId}, type=${type})`);
+                    emitSendErrorLogged = true;
+                }
+                continue;
+            }
             try {
                 ws.send(message);
             }
@@ -152,6 +177,13 @@ export function emitEphemeral(workspaceId, type, payload) {
     let sendErrorLogged = false;
     for (const [ws, subs] of clients) {
         if (subs.has(workspaceId) && ws.readyState === 1 /* WebSocket.OPEN */) {
+            if ((ws.bufferedAmount ?? 0) > MAX_BUFFERED_BYTES) {
+                if (!sendErrorLogged) {
+                    console.warn(`[ws] client backlogged, dropping ephemeral event (workspace=${workspaceId}, type=${type})`);
+                    sendErrorLogged = true;
+                }
+                continue;
+            }
             try {
                 ws.send(message);
             }
@@ -180,66 +212,100 @@ export function handleSyncRequest(ws, lastEventId, workspaceIds) {
         ws.send(JSON.stringify({ type: 'sync:empty', payload: { message: 'No subscriptions' } }));
         return;
     }
-    const db = getDb();
-    // Build a query with placeholders for all subscribed workspaces
-    const placeholders = resolvedIds.map(() => '?').join(', ');
-    let rows;
     // Initial window size: on a fresh connection (no lastEventId), we only
     // replay the most recent slice of history. The client fetches older
     // events on-demand via GET /api/workspaces/:id/events as the user scrolls
     // up. This keeps first-paint fast on long-lived workspaces with tens of
     // thousands of events without ever deleting anything from the DB.
     const INITIAL_WINDOW = 300;
-    let mode = 'snapshot';
-    if (lastEventId) {
-        // Resume path: replay every event strictly after the cursor (delta
-        // since last seen). If the cursor is stale/unknown, fall back to the
-        // recent window rather than streaming the entire history.
-        const lastRow = db.prepare('SELECT rowid FROM ws_events WHERE id = ?').get(lastEventId);
+    /** Hard ceiling on one replay message. A tab left open overnight used to ask
+     *  for every row since its cursor at once; the client simply asks again with
+     *  the new cursor when `truncated` is set. */
+    const MAX_REPLAY_EVENTS = 2_000;
+    try {
+        const db = getDb();
+        let mode = 'snapshot';
+        let truncated = false;
+        const rows = [];
+        const lastRow = lastEventId
+            ? db.prepare('SELECT rowid FROM ws_events WHERE id = ?').get(lastEventId)
+            : undefined;
+        // One bounded query PER workspace. With `workspace_id IN (...)` SQLite
+        // materialised and sorted the whole history of every requested workspace
+        // before applying the limit — so the limit protected the message, not the
+        // server.
         if (lastRow) {
             mode = 'delta';
-            rows = db
-                .prepare(`SELECT * FROM ws_events WHERE workspace_id IN (${placeholders}) AND rowid > ? ORDER BY rowid ASC`)
-                .all(...resolvedIds, lastRow.rowid);
+            const statement = db.prepare('SELECT rowid AS rid, * FROM ws_events WHERE workspace_id = ? AND rowid > ? ORDER BY rowid ASC LIMIT ?');
+            for (const workspaceId of resolvedIds) {
+                const batch = statement.all(workspaceId, lastRow.rowid, MAX_REPLAY_EVENTS);
+                if (batch.length === MAX_REPLAY_EVENTS)
+                    truncated = true;
+                rows.push(...batch);
+            }
         }
         else {
-            rows = db
-                .prepare(`SELECT * FROM ws_events WHERE workspace_id IN (${placeholders}) ORDER BY rowid DESC LIMIT ?`)
-                .all(...resolvedIds, INITIAL_WINDOW);
-            rows.reverse();
+            const statement = db.prepare('SELECT rowid AS rid, * FROM ws_events WHERE workspace_id = ? ORDER BY rowid DESC LIMIT ?');
+            for (const workspaceId of resolvedIds) {
+                const batch = statement.all(workspaceId, INITIAL_WINDOW);
+                rows.push(...batch);
+            }
         }
+        rows.sort((a, b) => a.rid - b.rid);
+        if (rows.length > MAX_REPLAY_EVENTS) {
+            if (mode === 'delta') {
+                // Keep the OLDEST slice: the client's cursor then advances and its next
+                // sync:request picks up exactly where this message stopped.
+                rows.length = MAX_REPLAY_EVENTS;
+            }
+            else {
+                // Snapshot mode has no cursor to advance — the client is looking at a
+                // fresh window and wants what just happened. Dropping the head here
+                // (rather than the tail) is the difference between "the last few
+                // minutes" and "ancient history with no way to reach the present".
+                rows.splice(0, rows.length - MAX_REPLAY_EVENTS);
+            }
+            truncated = true;
+        }
+        const events = rows.map((row) => {
+            let parsedPayload;
+            try {
+                parsedPayload = JSON.parse(row.payload);
+            }
+            catch {
+                console.error('[ws] corrupt ws_events row, falling back to raw:', {
+                    id: row.id,
+                    workspace_id: row.workspace_id,
+                    type: row.type,
+                });
+                parsedPayload = { raw: row.payload };
+            }
+            return {
+                id: row.id,
+                workspaceId: row.workspace_id,
+                type: row.type,
+                payload: parsedPayload,
+                sessionId: row.session_id ?? undefined,
+                createdAt: row.created_at,
+                replayable: true,
+            };
+        });
+        ws.send(JSON.stringify({ type: 'sync:response', payload: { events, mode, truncated } }));
     }
-    else {
-        // Fresh connect: most recent INITIAL_WINDOW events, in chronological order.
-        rows = db
-            .prepare(`SELECT * FROM ws_events WHERE workspace_id IN (${placeholders}) ORDER BY rowid DESC LIMIT ?`)
-            .all(...resolvedIds, INITIAL_WINDOW);
-        rows.reverse();
-    }
-    const events = rows.map((row) => {
-        let parsedPayload;
+    catch (err) {
+        // This handler runs inside ws's 'message' callback: an uncaught SQLite
+        // error here used to reach the process, not the client.
+        console.error('[ws] sync request failed:', err);
         try {
-            parsedPayload = JSON.parse(row.payload);
+            ws.send(JSON.stringify({
+                type: 'sync:error',
+                payload: { message: err instanceof Error ? err.message : String(err) },
+            }));
         }
         catch {
-            console.error('[ws] corrupt ws_events row, falling back to raw:', {
-                id: row.id,
-                workspace_id: row.workspace_id,
-                type: row.type,
-            });
-            parsedPayload = { raw: row.payload };
+            /* the client is gone too — nothing left to tell it */
         }
-        return {
-            id: row.id,
-            workspaceId: row.workspace_id,
-            type: row.type,
-            payload: parsedPayload,
-            sessionId: row.session_id ?? undefined,
-            createdAt: row.created_at,
-            replayable: true,
-        };
-    });
-    ws.send(JSON.stringify({ type: 'sync:response', payload: { events, mode } }));
+    }
 }
 // ── Utilities ──────────────────────────────────────────────────────────────────
 /**

package/dist/server/services/workspace-service.js

@@ -10,8 +10,13 @@ import { emitEphemeral } from './websocket-service.js';
 /** Allowed status transitions per current status. Enforced by updateWorkspaceStatus. */
 const VALID_TRANSITIONS = {
     created: ['extracting', 'brainstorming', 'idle', 'error'],
-    extracting: ['extracting', 'brainstorming', 'idle', 'error', 'awaiting-user'],
-    brainstorming: ['executing', 'completed', 'idle', 'error', 'awaiting-user'],
+    // `quota` is reachable from every state that can be running a live session.
+    // It used to be missing here and on `brainstorming`, so an auto-loop
+    // workspace with a distinct brainstormModel silently lost its backoff: the
+    // transition threw, the error was swallowed, and the very next lines
+    // cancelled the timer that had just been armed.
+    extracting: ['extracting', 'brainstorming', 'idle', 'error', 'awaiting-user', 'quota'],
+    brainstorming: ['executing', 'completed', 'idle', 'error', 'awaiting-user', 'quota'],
     executing: ['completed', 'idle', 'error', 'quota', 'awaiting-user'],
     'awaiting-user': ['executing', 'brainstorming', 'extracting', 'idle', 'error', 'completed', 'quota'],
     completed: ['idle', 'executing'],
@@ -840,3 +845,50 @@ export function deleteSession(sessionId, workspaceId) {
     transaction();
     return true;
 }
+/**
+ * Recompute one session's persisted metrics from the events that remain, on an
+ * explicit database handle.
+ *
+ * Until v36 an `AFTER DELETE ... FOR EACH ROW` trigger did this per deleted
+ * row, re-aggregating the whole session every time — 79.7 s for 20 000 events,
+ * with the SQLite write lock held throughout. The trigger is gone; every code
+ * path that deletes `agent:event` rows while KEEPING the session calls this
+ * once, at the end of its transaction.
+ */
+export function recomputeSessionMetricsOn(db, workspaceId, sessionId) {
+    db.prepare('DELETE FROM session_event_metrics WHERE workspace_id = ? AND session_id = ?').run(workspaceId, sessionId);
+    db.prepare(`INSERT INTO session_event_metrics (
+       workspace_id, session_id, tool_calls, errors, input_tokens, output_tokens
+     )
+     SELECT
+       e.workspace_id,
+       e.session_id,
+       SUM(CASE WHEN json_extract(e.payload, '$.kind') = 'tool:call' THEN 1 ELSE 0 END),
+       SUM(CASE
+         WHEN json_extract(e.payload, '$.kind') = 'error'
+           OR (json_extract(e.payload, '$.kind') = 'tool:result'
+             AND json_extract(e.payload, '$.isError') = 1)
+         THEN 1 ELSE 0
+       END),
+       MAX(CASE
+         WHEN json_extract(e.payload, '$.kind') = 'usage'
+           AND json_type(e.payload, '$.inputTokens') IN ('integer', 'real')
+         THEN CAST(json_extract(e.payload, '$.inputTokens') AS INTEGER) ELSE 0
+       END),
+       MAX(CASE
+         WHEN json_extract(e.payload, '$.kind') = 'usage'
+           AND json_type(e.payload, '$.outputTokens') IN ('integer', 'real')
+         THEN CAST(json_extract(e.payload, '$.outputTokens') AS INTEGER) ELSE 0
+       END)
+     FROM ws_events e
+     JOIN agent_sessions s ON s.id = e.session_id AND s.workspace_id = e.workspace_id
+     WHERE e.workspace_id = ?
+       AND e.session_id = ?
+       AND e.type = 'agent:event'
+       AND json_valid(e.payload)
+     GROUP BY e.workspace_id, e.session_id`).run(workspaceId, sessionId);
+}
+/** Same, on the singleton connection. */
+export function recomputeSessionMetrics(workspaceId, sessionId) {
+    recomputeSessionMetricsOn(getDb(), workspaceId, sessionId);
+}

package/dist/server/services/worktree-purge-service.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { logError, logWarn } from '../utils/logger.js';
 import * as agentManager from './agent/orchestrator.js';
 import * as devServerService from './dev-server-service.js';
 import { getForgeProvider } from './forge/registry.js';
@@ -16,19 +17,21 @@ export async function purgeWorktree(workspaceId) {
     if (!workspace.worktreeOwned)
         return { outcome: 'worktree-not-owned', warnings: [] };
     const warnings = [];
+    // `removeWorktree` runs later in this same function — the agent must be dead
+    // by then, not merely asked to stop.
     try {
-        agentManager.stopAgent(workspaceId);
+        await agentManager.stopAgentAndWait(workspaceId);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        console.error(`[purge] stopAgent failed for '${workspace.name}':`, msg);
+        logError('purge', `stopAgent failed for '${workspace.name}'`, { workspaceId: workspace.id, error: msg });
     }
     try {
         await devServerService.stopDevServer(workspaceId);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        console.error(`[purge] stopDevServer failed for '${workspace.name}':`, msg);
+        logError('purge', `stopDevServer failed for '${workspace.name}'`, { workspaceId: workspace.id, error: msg });
     }
     try {
         destroyTerminal(workspaceId);
@@ -49,13 +52,21 @@ export async function purgeWorktree(workspaceId) {
     }
     if (fs.existsSync(workspace.worktreePath)) {
         try {
-            removeWorktree(workspace.projectPath, workspace.worktreePath);
+            await removeWorktree(workspace.projectPath, workspace.worktreePath);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             warnings.push(buildRemovalFailureMessage(workspace.worktreePath, workspace.projectPath, msg));
         }
     }
+    // `worktree_purged_at` is not cosmetic: it drives the "restore" UI and the
+    // PR watcher's auto-restore probe, which tests whether the folder reappeared.
+    // Setting it on a directory that never left puts both in contradiction with
+    // the disk — and told the user the space was reclaimed when it wasn't.
+    if (fs.existsSync(workspace.worktreePath)) {
+        emitEphemeral(workspaceId, 'workspace:worktree-purge-failed', { workspaceId, warnings });
+        return { outcome: 'removal-failed', warnings };
+    }
     try {
         markWorktreePurged(workspaceId, restoreData);
     }
@@ -101,7 +112,10 @@ async function captureRestoreData(workspace) {
             }
         }
         catch (err) {
-            console.warn(`[purge] PR lookup for restore data failed:`, err instanceof Error ? err.message : err);
+            logWarn('purge', 'PR lookup for restore data failed', {
+                workspaceId: workspace.id,
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
     }
     return {

package/dist/server/services/worktree-service.js

@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { isGitBranchExistsError } from '../utils/git-ops.js';
+import { withGitRepoLock } from '../utils/git-repo-lock.js';
 import { resolveWorkspaceWorktreePath, resolveWorktreesRoot } from '../utils/worktree-paths.js';
 function git(repoPath, args) {
     return execFileSync('git', args, {
@@ -93,6 +94,10 @@ export function createWorktree(projectPath, branchName, baseRef, worktreesPath,
     }
     const worktreePath = resolveWorkspaceWorktreePath(projectPath, branchName, worktreesPath, projectSlug);
     const base = baseRef.startsWith('origin/') ? 'origin' : 'local';
+    // Tracks which of the two git commands below actually ran. Callers use it to
+    // decide whether a rollback may delete the branch: deleting one we merely
+    // attached to would destroy commits Kobo never created.
+    let branchCreated = true;
     try {
         git(projectPath, ['worktree', 'add', '-b', branchName, worktreePath, baseRef]);
     }
@@ -101,13 +106,33 @@ export function createWorktree(projectPath, branchName, baseRef, worktreesPath,
         // If branch already exists, add worktree without creating the branch
         if (isGitBranchExistsError(message)) {
             git(projectPath, ['worktree', 'add', worktreePath, branchName]);
+            branchCreated = false;
         }
         else {
             throw new Error(`Failed to create worktree for branch '${branchName}': ${message}`);
         }
     }
     addToExclude(projectPath, worktreePath);
-    return { worktreePath, base };
+    return { worktreePath, base, branchCreated };
+}
+/** `git worktree remove` drops the administrative entry even when it fails to
+ *  delete the directory, and the prune only ever ran in the Docker fallback.
+ *  Prune the stale metadata, then refuse to report success while the folder is
+ *  still there — the purge feature marked workspaces as purged on that false
+ *  success, telling the user the disk space was reclaimed when it wasn't.
+ *
+ *  Callers hold the repository lock: acquiring it again here would deadlock on
+ *  the same key, since the chain is strictly sequential per common git dir. */
+function assertWorktreeGone(projectPath, worktreePath) {
+    try {
+        git(projectPath, ['worktree', 'prune']);
+    }
+    catch (err) {
+        console.warn(`[worktree] prune after removing '${worktreePath}' failed:`, err instanceof Error ? err.message : err);
+    }
+    if (fs.existsSync(worktreePath)) {
+        throw new Error(`Failed to remove worktree '${worktreePath}': the directory is still on disk after removal`);
+    }
 }
 /** Remove a git worktree and clean up the .git/info/exclude entry.
  *
@@ -116,6 +141,16 @@ export function createWorktree(projectPath, branchName, baseRef, worktreesPath,
  * ownership with a throwaway container (`chown -R <uid>:<gid>`) and retry once.
  * Otherwise rethrow so the caller's recovery toast (sudo rm -rf …) fires. */
 export function removeWorktree(projectPath, worktreePath) {
+    // `git worktree remove` and `git worktree prune` both rewrite the worktree
+    // administrative files of the COMMON git dir — the very state a concurrent
+    // source-branch change (fetch / reset / cherry-pick) is manipulating under
+    // the same lock. The whole removal sequence is held, Docker chown included:
+    // it sits between the `remove` and the `prune` that repairs its metadata, so
+    // releasing in the middle would expose a half-removed repository.
+    return withGitRepoLock(projectPath, () => removeWorktreeLocked(projectPath, worktreePath));
+}
+/** The actual removal. Always called with the repository lock held. */
+function removeWorktreeLocked(projectPath, worktreePath) {
     try {
         git(projectPath, ['worktree', 'remove', worktreePath, '--force']);
     }
@@ -136,6 +171,7 @@ export function removeWorktree(projectPath, worktreePath) {
                 git(projectPath, ['worktree', 'prune']);
                 console.log(`[worktree] Docker cleanup succeeded; removed '${worktreePath}'`);
                 removeFromExclude(projectPath, worktreePath);
+                assertWorktreeGone(projectPath, worktreePath);
                 return;
             }
             catch (retryErr) {
@@ -147,6 +183,7 @@ export function removeWorktree(projectPath, worktreePath) {
         throw new Error(`Failed to remove worktree '${worktreePath}': ${message}`);
     }
     removeFromExclude(projectPath, worktreePath);
+    assertWorktreeGone(projectPath, worktreePath);
 }
 /** List all git worktrees for a repository by parsing `git worktree list --porcelain`. */
 export function listWorktrees(projectPath) {

package/dist/server/services/ws-events-retention-service.js

@@ -0,0 +1,133 @@
+import { recomputeSessionMetricsOn } from './workspace-service.js';
+/** Rows deleted per transaction. Small enough that the SQLite write lock is
+ *  never held for more than a few milliseconds at a time — the whole point of
+ *  doing this AFTER the quadratic AFTER DELETE trigger was removed. */
+const BATCH_SIZE = 5_000;
+/** Free-page ratio above which a full VACUUM is worth its cost. Production was
+ *  measured at 620 free pages out of 656 (95 %) for zero remaining rows. */
+const VACUUM_FREE_PAGE_RATIO = 0.25;
+/** Retention is OPT-IN: absent or invalid settings mean "delete nothing". */
+const DISABLED = 0;
+/** Anything that is not a non-negative integer falls back to "disabled": a bad
+ *  value must never be read as a licence to delete. */
+function normalize(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : DISABLED;
+}
+/** Read the retention window from the global settings. */
+export function resolveRetentionConfig(global) {
+    return {
+        retentionDays: normalize(global.wsEventsRetentionDays),
+        keepPerWorkspace: normalize(global.wsEventsKeepPerWorkspace),
+    };
+}
+/** Shared candidate selection: rows older than the cutoff that fall outside the
+ *  per-workspace tail. Used both to count (preview) and to delete. */
+const CANDIDATE_CTE = `
+  WITH ranked AS (
+    SELECT rowid AS rid,
+           workspace_id,
+           session_id,
+           created_at,
+           ROW_NUMBER() OVER (PARTITION BY workspace_id ORDER BY rowid DESC) AS rn
+    FROM ws_events
+  )`;
+function cutoffFor(config, nowMs) {
+    return new Date(nowMs - config.retentionDays * 24 * 60 * 60 * 1000).toISOString();
+}
+/**
+ * How many events `config` would delete right now. Deletes nothing — this backs
+ * the confirmation dialog, so the user is told the real volume before agreeing
+ * to destroy it.
+ */
+export function countPrunableWsEvents(db, config, nowMs = Date.now()) {
+    if (config.retentionDays <= 0)
+        return 0;
+    const row = db
+        .prepare(`${CANDIDATE_CTE}
+       SELECT COUNT(*) AS c FROM ranked WHERE created_at < ? AND rn > ?`)
+        .get(cutoffFor(config, nowMs), config.keepPerWorkspace);
+    return row.c;
+}
+/**
+ * Delete `ws_events` rows older than the retention window, batch by batch, then
+ * recompute the metrics of the sessions touched and reclaim the freed pages.
+ *
+ * Deletes agent output ONLY: workspaces, tasks, sessions, branches and worktrees
+ * are never touched.
+ *
+ * Order matters: this must never run while the removed `AFTER DELETE` trigger
+ * is present — it re-aggregated the whole session per deleted row and held the
+ * write lock long enough to make every concurrent WebSocket emit time out and
+ * lose its event.
+ */
+export function pruneWsEvents(db, config, nowMs = Date.now()) {
+    const freePagesBefore = db.pragma('freelist_count', { simple: true }) ?? 0;
+    const result = {
+        deleted: 0,
+        sessionsRecomputed: 0,
+        vacuumed: false,
+        freePagesBefore,
+        freePagesAfter: freePagesBefore,
+    };
+    if (config.retentionDays <= 0)
+        return result;
+    const cutoff = cutoffFor(config, nowMs);
+    const selectBatch = db.prepare(`${CANDIDATE_CTE}
+     SELECT rid, workspace_id, session_id
+     FROM ranked
+     WHERE created_at < ? AND rn > ?
+     ORDER BY rid ASC
+     LIMIT ?`);
+    const deleteOne = db.prepare('DELETE FROM ws_events WHERE rowid = ?');
+    const touched = new Set();
+    for (;;) {
+        const batch = selectBatch.all(cutoff, config.keepPerWorkspace, BATCH_SIZE);
+        if (batch.length === 0)
+            break;
+        db.transaction(() => {
+            for (const row of batch) {
+                deleteOne.run(row.rid);
+                if (row.session_id)
+                    touched.add(`${row.workspace_id}::${row.session_id}`);
+            }
+        })();
+        result.deleted += batch.length;
+        if (batch.length < BATCH_SIZE)
+            break;
+    }
+    // Once per session, at the very end — never per deleted row.
+    for (const key of touched) {
+        const separator = key.indexOf('::');
+        const workspaceId = key.slice(0, separator);
+        const sessionId = key.slice(separator + 2);
+        try {
+            recomputeSessionMetricsOn(db, workspaceId, sessionId);
+            result.sessionsRecomputed += 1;
+        }
+        catch (err) {
+            console.error(`[retention] metric recompute failed (workspace=${workspaceId}, session=${sessionId}):`, err);
+        }
+    }
+    if (result.deleted === 0)
+        return result;
+    // Truncate the WAL, then compact only when it is actually worth it.
+    try {
+        db.pragma('wal_checkpoint(TRUNCATE)');
+    }
+    catch (err) {
+        console.error('[retention] wal_checkpoint failed:', err);
+    }
+    const freelist = db.pragma('freelist_count', { simple: true }) ?? 0;
+    const pageCount = db.pragma('page_count', { simple: true }) ?? 0;
+    if (pageCount > 0 && freelist / pageCount >= VACUUM_FREE_PAGE_RATIO) {
+        try {
+            db.exec('VACUUM');
+            result.vacuumed = true;
+        }
+        catch (err) {
+            console.error('[retention] VACUUM failed:', err);
+        }
+    }
+    result.freePagesAfter = db.pragma('freelist_count', { simple: true }) ?? 0;
+    return result;
+}