@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/core/repl/store/index.js

@@ -1,5 +1,5 @@
 /**
- * Public re-exports for the SessionStore module — Sprint α6.4.
+ * Public re-exports for the SessionStore module — Sprint .
  *
  * Consumers (`repl/session.ts`, `runtime/cli.ts`, the `/resume`
  * dispatcher) import from `./store/index.js` so the internal split

package/dist/core/repl/store/jsonl-log.js

@@ -1,5 +1,5 @@
 /**
- * Append-only JSONL event log — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ * Append-only JSONL event log — Sprint .
  *
  * Durable truth for the session. The SQLite index is rebuildable from
  * the JSONL; if the index is lost or corrupt, `pugi sessions --rebuild`
@@ -8,10 +8,10 @@
  *
  * File layout per session directory:
  *
- *   <sessionDir>/events.0.jsonl       active rotation file
- *   <sessionDir>/events.1.jsonl       previous rotation, oldest event first
- *   <sessionDir>/events.2.jsonl       older still
- *   ...
+ *  <sessionDir>/events.0.jsonl      active rotation file
+ *  <sessionDir>/events.1.jsonl      previous rotation, oldest event first
+ *  <sessionDir>/events.2.jsonl      older still
+ *  ...
  *
  * Rotation threshold is 50 MB per spec §4.2 must-ship #2. When the
  * active file exceeds the threshold AFTER a write, we close it, rename
@@ -21,23 +21,23 @@
  *
  * Crash safety:
  *
- *   - Each write is a single `appendFileSync` of `JSON.stringify(event)\n`.
- *     On Linux/macOS, append-mode writes of bytes < PIPE_BUF (4096) are
- *     atomic with respect to other appends. Our events are well under
- *     4 KB so the OS guarantees per-line atomicity even if two
- *     processes hold append fds (the lockfile already prevents that,
- *     but defence-in-depth).
- *   - After each write we call `fsync(fd)` so the bytes are durable
- *     against power loss / kernel panic. Slow but correct — the
- *     conversation-flow path is throughput-bound by the LLM, not by
- *     the disk, so a few hundred extra microseconds per event is
- *     invisible to the operator.
- *   - On reopen we walk every line and drop any that fail JSON parse.
- *     A crash mid-write leaves a truncated tail; we treat it as
- *     "event was never written" and continue from there. The next
- *     write may overlap with the truncated bytes; that is acceptable
- *     because the truncated line is invalid JSON either way and the
- *     reader is already designed to skip it.
+ *  - Each write is a single `appendFileSync` of `JSON.stringify(event)\n`.
+ *    On Linux/macOS, append-mode writes of bytes < PIPE_BUF (4096) are
+ *    atomic with respect to other appends. Our events are well under
+ *    4 KB so the OS guarantees per-line atomicity even if two
+ *    processes hold append fds (the lockfile already prevents that,
+ *    but defence-in-depth).
+ *  - After each write we call `fsync(fd)` so the bytes are durable
+ *    against power loss / kernel panic. Slow but correct — the
+ *    conversation-flow path is throughput-bound by the LLM, not by
+ *    the disk, so a few hundred extra microseconds per event is
+ *    invisible to the operator.
+ *  - On reopen we walk every line and drop any that fail JSON parse.
+ *    A crash mid-write leaves a truncated tail; we treat it as
+ *    "event was never written" and continue from there. The next
+ *    write may overlap with the truncated bytes; that is acceptable
+ *    because the truncated line is invalid JSON either way and the
+ *    reader is already designed to skip it.
  */
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, writeSync, } from 'node:fs';
 import { resolve } from 'node:path';

package/dist/core/repl/store/lockfile.js

@@ -1,5 +1,5 @@
 /**
- * PID lockfile — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ * PID lockfile — Sprint .
  *
  * Prevents two REPL processes in the same project directory from
  * writing to the same `session.db` concurrently. SQLite's WAL handles
@@ -9,15 +9,15 @@
  *
  * Algorithm:
  *
- *   1. Try `O_CREAT | O_EXCL` open of `<dir>/session.lock`. Write the
- *      caller's PID + process start time as the body. If the open
- *      succeeds, we hold the lock; return.
- *   2. If `EEXIST`, read the existing PID. Probe with `kill(pid, 0)`
- *      (signal 0 = "check liveness, do not deliver"). If the probe
- *      returns ESRCH, the holder is dead — unlink the stale lock and
- *      retry the exclusive create.
- *   3. If the probe says the PID is alive, throw `SessionLockBusyError`
- *      so the caller surfaces a clean message to the operator.
+ *  1. Try `O_CREAT | O_EXCL` open of `<dir>/session.lock`. Write the
+ *     caller's PID + process start time as the body. If the open
+ *     succeeds, we hold the lock; return.
+ *  2. If `EEXIST`, read the existing PID. Probe with `kill(pid, 0)`
+ *     (signal 0 = "check liveness, do not deliver"). If the probe
+ *     returns ESRCH, the holder is dead — unlink the stale lock and
+ *     retry the exclusive create.
+ *  3. If the probe says the PID is alive, throw `SessionLockBusyError`
+ *     so the caller surfaces a clean message to the operator.
  *
  * Why not `proper-lockfile`: pulling a 14kB dependency for a 60-line
  * PID file is poor cost/benefit. The stale-detection loop is the only

package/dist/core/repl/store/session-store.js

@@ -1,15 +1,15 @@
 /**
- * SessionStore — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ * SessionStore — Sprint .
  *
  * SQLite-indexed, JSONL-durable session store. The JSONL log is the
  * source of truth; the SQLite tables are a queryable cache. Layout:
  *
- *   ~/.pugi/projects/<project-slug>/
- *     session.db                 SQLite index (sessions + FTS5)
- *     session.lock               PID lockfile
- *     sessions/<session-id>/
- *       events.0.jsonl           active append log
- *       events.1.jsonl           older rotations (50 MB threshold)
+ *  ~/.pugi/projects/<project-slug>/
+ *    session.db                SQLite index (sessions + FTS5)
+ *    session.lock              PID lockfile
+ *    sessions/<session-id>/
+ *      events.0.jsonl          active append log
+ *      events.1.jsonl          older rotations (50 MB threshold)
  *
  * The store lives entirely under `$HOME/.pugi/` per the local-first
  * invariants memo (`feedback_no_landing_oes_secondary_2026_05_23.md`)
@@ -19,20 +19,20 @@
  *
  * Why node:sqlite over better-sqlite3:
  *
- *   - Zero install-time native build. better-sqlite3 needs prebuilt
- *     binaries for every Node ABI × platform; missing a wheel forces
- *     a node-gyp compile that fails on bare-metal CI agents without
- *     a C++ toolchain. Pugi CLI ships via npm to operators who almost
- *     certainly do not have build-essential installed.
- *   - Available since Node 22.5.0 (stable subset; LTS as of 2026). Our
- *     `engines.node` is pinned to `>=22.5.0` in apps/pugi-cli +
- *     packages/pugi-sdk so npm refuses to install the CLI on Node 20.x
- *     instead of crash-on-import. CI runs Node 22 (matrix-free; see
- *     `.github/workflows/ci.yml`).
- *   - Marked Experimental by Node — silenced via process.emitWarning
- *     suppression at boot. The API surface we use (DatabaseSync,
- *     StatementSync, exec/prepare) is the stable subset that has
- *     shipped unchanged since Node 22.5.
+ *  - Zero install-time native build. better-sqlite3 needs prebuilt
+ *    binaries for every Node ABI × platform; missing a wheel forces
+ *    a node-gyp compile that fails on bare-metal CI agents without
+ *    a C++ toolchain. Pugi CLI ships via npm to operators who almost
+ *    certainly do not have build-essential installed.
+ *  - Available since Node 22.5.0 (stable subset; LTS as of 2026). Our
+ *    `engines.node` is pinned to `>=22.5.0` in apps/pugi-cli +
+ *    packages/pugi-sdk so npm refuses to install the CLI on Node 20.x
+ *    instead of crash-on-import. CI runs Node 22 (matrix-free; see
+ *    `.github/workflows/ci.yml`).
+ *  - Marked Experimental by Node — silenced via process.emitWarning
+ *    suppression at boot. The API surface we use (DatabaseSync,
+ *    StatementSync, exec/prepare) is the stable subset that has
+ *    shipped unchanged since Node 22.5.
  *
  * Schema is created at first open. `schema_meta` carries a single row
  * `('version', '1')`; future migrations bump the version + run the
@@ -47,32 +47,32 @@ import { takeLock } from './lockfile.js';
 import { uuidV7 } from './uuid-v7.js';
 const SCHEMA_VERSION = '1';
 const SCHEMA_SQL = `
-  CREATE TABLE IF NOT EXISTS sessions (
-    id TEXT PRIMARY KEY,
-    created_at INTEGER NOT NULL,
-    updated_at INTEGER NOT NULL,
-    workspace_root TEXT NOT NULL,
-    branch TEXT,
-    project_slug TEXT NOT NULL,
-    title TEXT,
-    turn_count INTEGER NOT NULL DEFAULT 0,
-    event_count INTEGER NOT NULL DEFAULT 0,
-    model TEXT,
-    tenant_id TEXT,
-    status TEXT NOT NULL DEFAULT 'active'
-  );
-  CREATE INDEX IF NOT EXISTS idx_sessions_updated ON sessions(updated_at DESC);
-  CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_slug, updated_at DESC);
-  CREATE VIRTUAL TABLE IF NOT EXISTS sessions_fts USING fts5(
-    id UNINDEXED,
-    title,
-    body,
-    tokenize='unicode61'
-  );
-  CREATE TABLE IF NOT EXISTS schema_meta (
-    key TEXT PRIMARY KEY,
-    value TEXT NOT NULL
-  );
+ CREATE TABLE IF NOT EXISTS sessions (
+   id TEXT PRIMARY KEY,
+   created_at INTEGER NOT NULL,
+   updated_at INTEGER NOT NULL,
+   workspace_root TEXT NOT NULL,
+   branch TEXT,
+   project_slug TEXT NOT NULL,
+   title TEXT,
+   turn_count INTEGER NOT NULL DEFAULT 0,
+   event_count INTEGER NOT NULL DEFAULT 0,
+   model TEXT,
+   tenant_id TEXT,
+   status TEXT NOT NULL DEFAULT 'active'
+ );
+ CREATE INDEX IF NOT EXISTS idx_sessions_updated ON sessions(updated_at DESC);
+ CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_slug, updated_at DESC);
+ CREATE VIRTUAL TABLE IF NOT EXISTS sessions_fts USING fts5(
+   id UNINDEXED,
+   title,
+   body,
+   tokenize='unicode61'
+ );
+ CREATE TABLE IF NOT EXISTS schema_meta (
+   key TEXT PRIMARY KEY,
+   value TEXT NOT NULL
+ );
 `;
 /** Default list limit. Operators rarely scroll past the most recent 50. */
 const DEFAULT_LIST_LIMIT = 50;
@@ -180,13 +180,13 @@ export class SqliteSessionStore {
         // bump turn_count and set title. Splitting into multiple statements
         // would race the lockfile if a second process slipped through.
         const sql = `
-      UPDATE sessions
-         SET event_count = event_count + 1,
-             updated_at  = ?,
-             turn_count  = turn_count + ${isUserTurn ? 1 : 0},
-             title       = COALESCE(title, ?)
-       WHERE id = ?
-    `;
+     UPDATE sessions
+        SET event_count = event_count + 1,
+            updated_at = ?,
+            turn_count = turn_count + ${isUserTurn ? 1 : 0},
+            title      = COALESCE(title, ?)
+      WHERE id = ?
+   `;
         db.prepare(sql).run(ts, titlePatch ?? null, sessionId);
         // Mirror the user-turn body into FTS so substring search hits
         // every previous user turn, not just the most recent one.
@@ -237,13 +237,13 @@ export class SqliteSessionStore {
         }
         const whereClause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
         const sql = `
-      SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
-             title, turn_count, event_count, model, tenant_id, status
-        FROM sessions
-        ${whereClause}
-       ORDER BY updated_at DESC
-       LIMIT ?
-    `;
+     SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
+            title, turn_count, event_count, model, tenant_id, status
+       FROM sessions
+       ${whereClause}
+      ORDER BY updated_at DESC
+      LIMIT ?
+   `;
         const stmt = db.prepare(sql);
         const rows = stmt.all(...params, limit);
         return rows.map(rawToSession);
@@ -294,15 +294,15 @@ export class SqliteSessionStore {
         // `unable to use function MATCH in the requested context`. We
         // search title+body together by matching against `sessions_fts`.
         const sql = `
-      SELECT s.id, s.created_at, s.updated_at, s.workspace_root, s.branch,
-             s.project_slug, s.title, s.turn_count, s.event_count, s.model,
-             s.tenant_id, s.status
-        FROM sessions_fts f
-        JOIN sessions s ON s.id = f.id
-       WHERE sessions_fts MATCH ?
-       ORDER BY s.updated_at DESC
-       LIMIT ?
-    `;
+     SELECT s.id, s.created_at, s.updated_at, s.workspace_root, s.branch,
+            s.project_slug, s.title, s.turn_count, s.event_count, s.model,
+            s.tenant_id, s.status
+       FROM sessions_fts f
+       JOIN sessions s ON s.id = f.id
+      WHERE sessions_fts MATCH ?
+      ORDER BY s.updated_at DESC
+      LIMIT ?
+   `;
         let rows;
         try {
             rows = db.prepare(sql).all(ftsQuery, limit);
@@ -361,10 +361,10 @@ export class SqliteSessionStore {
         // which maps to SQLITE_OPEN_READONLY. The option form is the
         // documented API; the file-URI form (file:...?mode=ro) also works.
         const db = new DatabaseSync(dbPath, { readOnly: true });
-        return new SqliteSessionStoreReadOnlyView(db);
+        return new SqliteSessionStoreReadOnlyView(db, projectStoreDir);
     }
     /* ------------------------------------------------------------ */
-    /* Internals                                                    */
+    /* Internals                                                   */
     /* ------------------------------------------------------------ */
     takeLockOrThrow() {
         const lockPath = resolve(this.projectDir, 'session.lock');
@@ -420,11 +420,11 @@ export class SqliteSessionStore {
     getSessionSync(sessionId) {
         const db = this.requireDb();
         const stmt = db.prepare(`
-      SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
-             title, turn_count, event_count, model, tenant_id, status
-        FROM sessions
-       WHERE id = ?
-    `);
+     SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
+            title, turn_count, event_count, model, tenant_id, status
+       FROM sessions
+      WHERE id = ?
+   `);
         const row = stmt.get(sessionId);
         return row ? rawToSession(row) : null;
     }
@@ -432,11 +432,11 @@ export class SqliteSessionStore {
         const db = this.requireDb();
         const ts = this.now();
         db.prepare(`
-      INSERT INTO sessions
-        (id, created_at, updated_at, workspace_root, branch, project_slug,
-         title, turn_count, event_count, model, tenant_id, status)
-      VALUES (?, ?, ?, ?, ?, ?, NULL, 0, 0, ?, ?, 'active')
-    `).run(input.id, ts, ts, input.workspaceRoot, input.branch, input.projectSlug, input.model, input.tenantId);
+     INSERT INTO sessions
+       (id, created_at, updated_at, workspace_root, branch, project_slug,
+        title, turn_count, event_count, model, tenant_id, status)
+     VALUES (?, ?, ?, ?, ?, ?, NULL, 0, 0, ?, ?, 'active')
+   `).run(input.id, ts, ts, input.workspaceRoot, input.branch, input.projectSlug, input.model, input.tenantId);
         // Seed an empty FTS row so the title patch path can rely on a
         // single UPDATE OR REPLACE without first checking for the row.
         this.upsertFtsRow(input.id, '', '');
@@ -584,8 +584,37 @@ export class SqliteSessionStore {
  */
 export class SqliteSessionStoreReadOnlyView {
     db;
-    constructor(db) {
+    projectStoreDir;
+    constructor(db, 
+    /**
+     * Project store directory — required for the JSONL event read path.
+     * L9 : `/rewind` + `/resume` need to walk events from
+     * inside the read-only view so the rewind picker + resume preview
+     * never take the writer lockfile.
+     */
+    projectStoreDir) {
         this.db = db;
+        this.projectStoreDir = projectStoreDir;
+    }
+    /**
+     * Read every event for a session via the durable JSONL log. The
+     * SQLite cache is NOT used here — JSONL is the source of truth and
+     * the cache only holds counters. The walk stitches across rotation
+     * files (`events.<n>.jsonl`) in the same order `JsonlEventLog.read`
+     * uses inside the writer path so consumers see one consistent stream
+     * whether they came in via the writer store OR the read-only view.
+     */
+    async events(sessionId, opts) {
+        const sessionDir = resolve(this.projectStoreDir, 'sessions', sessionId);
+        if (!existsSync(sessionDir))
+            return [];
+        const log = new JsonlEventLog({ sessionDir });
+        try {
+            return log.read(opts);
+        }
+        finally {
+            log.close();
+        }
     }
     async list(opts) {
         const limit = clampLimit(opts?.limit ?? DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT);
@@ -613,13 +642,13 @@ export class SqliteSessionStoreReadOnlyView {
         }
         const whereClause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
         const sql = `
-      SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
-             title, turn_count, event_count, model, tenant_id, status
-        FROM sessions
-        ${whereClause}
-       ORDER BY updated_at DESC
-       LIMIT ?
-    `;
+     SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
+            title, turn_count, event_count, model, tenant_id, status
+       FROM sessions
+       ${whereClause}
+      ORDER BY updated_at DESC
+      LIMIT ?
+   `;
         const rows = this.db
             .prepare(sql)
             .all(...params, limit);
@@ -633,15 +662,15 @@ export class SqliteSessionStoreReadOnlyView {
         const limit = clampLimit(opts?.limit ?? DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT);
         const ftsQuery = sanitiseFtsQuery(trimmed);
         const sql = `
-      SELECT s.id, s.created_at, s.updated_at, s.workspace_root, s.branch,
-             s.project_slug, s.title, s.turn_count, s.event_count, s.model,
-             s.tenant_id, s.status
-        FROM sessions_fts f
-        JOIN sessions s ON s.id = f.id
-       WHERE sessions_fts MATCH ?
-       ORDER BY s.updated_at DESC
-       LIMIT ?
-    `;
+     SELECT s.id, s.created_at, s.updated_at, s.workspace_root, s.branch,
+            s.project_slug, s.title, s.turn_count, s.event_count, s.model,
+            s.tenant_id, s.status
+       FROM sessions_fts f
+       JOIN sessions s ON s.id = f.id
+      WHERE sessions_fts MATCH ?
+      ORDER BY s.updated_at DESC
+      LIMIT ?
+   `;
         let rows;
         try {
             rows = this.db.prepare(sql).all(ftsQuery, limit);
@@ -656,11 +685,11 @@ export class SqliteSessionStoreReadOnlyView {
     }
     async get(sessionId) {
         const stmt = this.db.prepare(`
-      SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
-             title, turn_count, event_count, model, tenant_id, status
-        FROM sessions
-       WHERE id = ?
-    `);
+     SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
+            title, turn_count, event_count, model, tenant_id, status
+       FROM sessions
+      WHERE id = ?
+   `);
         const row = stmt.get(sessionId);
         return row ? rawToSession(row) : null;
     }
@@ -722,9 +751,9 @@ function sanitiseSlugForFs(raw) {
  * Pull a human-readable text body out of an event payload. We support
  * three shapes the producer commonly emits:
  *
- *   - `{ text: string }`   — explicit text body.
- *   - `{ brief: string }`  — REPL `dispatch` brief.
- *   - `string`             — payload is the body itself.
+ *  - `{ text: string }`  — explicit text body.
+ *  - `{ brief: string }` — REPL `dispatch` brief.
+ *  - `string`            — payload is the body itself.
  *
  * Anything else returns the empty string so a typo at the call site
  * silently degrades to "no FTS body" rather than crashing the writer.

package/dist/core/repl/store/types.js

@@ -1,26 +1,26 @@
 /**
- * Persistent REPL session store — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ * Persistent REPL session store — Sprint .
  *
  * Public types consumed by the REPL session module + the `pugi sessions`
  * / `pugi resume` dispatchers. Wire format is stable:
  *
- *   - `SessionRow` mirrors the SQLite `sessions` table one-to-one and is
- *     also the JSON shape returned by `pugi sessions --json`. Field names
- *     are camelCase (PascalCase types, camelCase fields per CLAUDE.md
- *     conventions). The SQL columns themselves stay snake_case because
- *     they originate from raw SQL.
+ *  - `SessionRow` mirrors the SQLite `sessions` table one-to-one and is
+ *    also the JSON shape returned by `pugi sessions --json`. Field names
+ *    are camelCase (PascalCase types, camelCase fields per CLAUDE.md
+ *    conventions). The SQL columns themselves stay snake_case because
+ *    they originate from raw SQL.
  *
- *   - `SessionEvent` is the on-disk shape of one line in
- *     `events.<n>.jsonl`. `kind` is a closed union; `payload` is an
- *     opaque JSON value so the producer can attach whatever fields the
- *     event type requires without forcing the store to change.
+ *  - `SessionEvent` is the on-disk shape of one line in
+ *    `events.<n>.jsonl`. `kind` is a closed union; `payload` is an
+ *    opaque JSON value so the producer can attach whatever fields the
+ *    event type requires without forcing the store to change.
  *
- *   - `SessionListOptions` / `SessionLoadEventsOptions` /
- *     `SessionSearchOptions` are inputs the store accepts. Defaults are
- *     spec'd inline so the test plan can pin them without reading the
- *     implementation.
+ *  - `SessionListOptions` / `SessionLoadEventsOptions` /
+ *    `SessionSearchOptions` are inputs the store accepts. Defaults are
+ *    spec'd inline so the test plan can pin them without reading the
+ *    implementation.
  *
- * The blob store + `pugi undo` + named checkpoints are α6.4b follow-ups
+ * The blob store + `pugi undo` + named checkpoints are follow-ups
  * — out of scope for THIS PR per spec. The types here intentionally do
  * NOT model blob refs so a future blob-store landing can extend without
  * a wire break.

package/dist/core/repl/store/uuid-v7.js

@@ -1,5 +1,5 @@
 /**
- * UUID v7 generator — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ * UUID v7 generator — Sprint .
  *
  * uuid v7 (RFC 9562 draft) is a time-sortable 128-bit identifier whose
  * first 48 bits are the unix-epoch milliseconds, the next 4 bits are
@@ -9,17 +9,17 @@
  *
  * Why v7 and not v4 (random) or v6 (gregorian time):
  *
- *   - The session id IS the primary key of the SQLite table. We want
- *     inserts to land at the end of the b-tree to keep page fanout
- *     small. v4 fragments the tree (uniformly random keys); v7 sorts
- *     in time order so inserts are append-only.
- *   - `pugi sessions` sorts by `updated_at DESC` for display, but the
- *     pagination cursor uses the session id directly — a v7 id IS the
- *     creation timestamp, so the cursor is a single column compare
- *     instead of (updated_at, id) tuple.
- *   - Operators see ids in `/resume` picker; v7 prefix is monotonically
- *     increasing so the most recent session lands at the bottom of an
- *     id sort, matching the human expectation of "newest last".
+ *  - The session id IS the primary key of the SQLite table. We want
+ *    inserts to land at the end of the b-tree to keep page fanout
+ *    small. v4 fragments the tree (uniformly random keys); v7 sorts
+ *    in time order so inserts are append-only.
+ *  - `pugi sessions` sorts by `updated_at DESC` for display, but the
+ *    pagination cursor uses the session id directly — a v7 id IS the
+ *    creation timestamp, so the cursor is a single column compare
+ *    instead of (updated_at, id) tuple.
+ *  - Operators see ids in `/resume` picker; v7 prefix is monotonically
+ *    increasing so the most recent session lands at the bottom of an
+ *    id sort, matching the human expectation of "newest last".
  *
  * Node 22 does not ship a v7 generator (`crypto.randomUUID()` is v4
  * only). We implement it inline with `crypto.randomBytes(10)` for the