@winspan/claude-forge 8.41.0 → 8.51.0

package/tests/unit/storage/routing-aggregates.test.ts

@@ -0,0 +1,276 @@
+/**
+ * H1 storage aggregates: routing_events
+ *
+ * 覆盖：
+ *   - 空表返回 0
+ *   - 混合 obeyed=1/0/NULL 的计数
+ *   - since_ts 过滤边界
+ *   - by_agent 排除 obeyed != 1 / routed_to_name IS NULL
+ *   - by_skill_routed 只统计 routed_to_type='skill'
+ *   - aggregateRoutingTrendByDay 跨日聚合（UTC）
+ *   - ts <= 0 兜底（不应崩，不进入 trend 结果）
+ *   - project_path 过滤
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+
+const SESSION = 'sess-r';
+const PROJECT = '/tmp/p';
+
+describe('storage.aggregateRoutingStats', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h1-routing-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('空表返回全 0 / 空数组', () => {
+    const r = storage.aggregateRoutingStats({ since_ts: 0 });
+    expect(r.total).toBe(0);
+    expect(r.obeyed).toBe(0);
+    expect(r.refused).toBe(0);
+    expect(r.unknown).toBe(0);
+    expect(r.by_type).toEqual([]);
+    expect(r.by_agent).toEqual([]);
+    expect(r.by_skill_routed).toEqual([]);
+  });
+
+  it('混合 obeyed=1/0/NULL 的计数正确', () => {
+    const now = Date.now();
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p1', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'researcher', obeyed: 1,
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p2', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'coder', obeyed: 0,
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p3', intent_json: '{}',
+      routed_to_type: 'skill', routed_to_name: 'tdd', obeyed: null,
+    });
+
+    const r = storage.aggregateRoutingStats({ since_ts: 0 });
+    expect(r.total).toBe(3);
+    expect(r.obeyed).toBe(1);
+    expect(r.refused).toBe(1);
+    expect(r.unknown).toBe(1);
+  });
+
+  it('by_type 分布（含 NULL → "none"）', () => {
+    const now = Date.now();
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'a', intent_json: '{}', routed_to_type: 'agent', routed_to_name: 'x',
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'b', intent_json: '{}', routed_to_type: 'skill', routed_to_name: 'y',
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'c', intent_json: '{}', routed_to_type: null, routed_to_name: null,
+    });
+
+    const r = storage.aggregateRoutingStats({ since_ts: 0 });
+    const map = Object.fromEntries(r.by_type.map(e => [e.type, e.count]));
+    expect(map.agent).toBe(1);
+    expect(map.skill).toBe(1);
+    expect(map.none).toBe(1);
+  });
+
+  it('by_agent 仅含 obeyed=1 且 routed_to_name 非 NULL', () => {
+    const now = Date.now();
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p1', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'researcher', obeyed: 1,
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p2', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'researcher', obeyed: 1,
+    });
+    // obeyed = 0 → 不计入 by_agent
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p3', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'tester', obeyed: 0,
+    });
+    // obeyed = NULL → 不计入 by_agent
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p4', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'planner', obeyed: null,
+    });
+    // routed_to_name NULL → 不计入
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p5', intent_json: '{}',
+      routed_to_type: null, routed_to_name: null, obeyed: 1,
+    });
+
+    const r = storage.aggregateRoutingStats({ since_ts: 0 });
+    expect(r.by_agent).toEqual([{ agent: 'researcher', count: 2 }]);
+  });
+
+  it('by_skill_routed 仅含 routed_to_type=skill 且 routed_to_name 非 NULL', () => {
+    const now = Date.now();
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p1', intent_json: '{}',
+      routed_to_type: 'skill', routed_to_name: 'official-tdd',
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p2', intent_json: '{}',
+      routed_to_type: 'skill', routed_to_name: 'official-tdd',
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p3', intent_json: '{}',
+      routed_to_type: 'skill', routed_to_name: 'debug',
+    });
+    // agent 不计入
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p4', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'researcher',
+    });
+
+    const r = storage.aggregateRoutingStats({ since_ts: 0 });
+    expect(r.by_skill_routed).toEqual([
+      { skill: 'official-tdd', count: 2 },
+      { skill: 'debug', count: 1 },
+    ]);
+  });
+
+  it('since_ts 严格 >= 边界（等于通过 / 小于排除）', () => {
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: 1000,
+      prompt: 'old', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'a', obeyed: 1,
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: 2000,
+      prompt: 'mid', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'a', obeyed: 1,
+    });
+
+    const r1 = storage.aggregateRoutingStats({ since_ts: 2000 });
+    expect(r1.total).toBe(1); // 仅 ts=2000
+
+    const r2 = storage.aggregateRoutingStats({ since_ts: 1500 });
+    expect(r2.total).toBe(1); // 仅 ts=2000
+
+    const r3 = storage.aggregateRoutingStats({ since_ts: 1000 });
+    expect(r3.total).toBe(2);
+  });
+
+  it('project_path 过滤', () => {
+    const now = Date.now();
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: '/proj/a', ts: now,
+      prompt: 'pa', intent_json: '{}', routed_to_type: 'agent', routed_to_name: 'x', obeyed: 1,
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: '/proj/b', ts: now,
+      prompt: 'pb', intent_json: '{}', routed_to_type: 'agent', routed_to_name: 'y', obeyed: 1,
+    });
+
+    const r = storage.aggregateRoutingStats({ since_ts: 0, project_path: '/proj/a' });
+    expect(r.total).toBe(1);
+    expect(r.by_agent).toEqual([{ agent: 'x', count: 1 }]);
+  });
+
+  it('ts <= 0 被 WHERE ts > 0 兜底排除', () => {
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: 0,
+      prompt: 'zero', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'a', obeyed: 1,
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: 1000,
+      prompt: 'ok', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'a', obeyed: 1,
+    });
+
+    const r = storage.aggregateRoutingStats({ since_ts: 0 });
+    // ts=0 被排除
+    expect(r.total).toBe(1);
+  });
+});
+
+describe('storage.aggregateRoutingTrendByDay', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h1-trend-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('空表返回 []', () => {
+    expect(storage.aggregateRoutingTrendByDay({ since_ts: 0 })).toEqual([]);
+  });
+
+  it('跨日聚合（UTC），返回每日 total + skill 计数', () => {
+    // 2026-01-01T00:00:01Z, 01-01T23:00:00Z, 01-02T00:00:01Z
+    const day1 = Date.UTC(2026, 0, 1, 0, 0, 1);   // 2026-01-01
+    const day1b = Date.UTC(2026, 0, 1, 23, 0, 0); // 2026-01-01
+    const day2 = Date.UTC(2026, 0, 2, 0, 0, 1);   // 2026-01-02
+
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: day1,
+      prompt: 'a', intent_json: '{}', routed_to_type: 'agent', routed_to_name: 'x',
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: day1b,
+      prompt: 'b', intent_json: '{}', routed_to_type: 'skill', routed_to_name: 'y',
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: day2,
+      prompt: 'c', intent_json: '{}', routed_to_type: 'skill', routed_to_name: 'y',
+    });
+
+    const trend = storage.aggregateRoutingTrendByDay({ since_ts: 0 });
+    expect(trend).toHaveLength(2);
+    expect(trend[0]).toEqual({ day: '2026-01-01', total: 2, skill: 1 });
+    expect(trend[1]).toEqual({ day: '2026-01-02', total: 1, skill: 1 });
+  });
+
+  it('ts <= 0 不出现在结果中（strftime 兜底）', () => {
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: 0,
+      prompt: 'zero', intent_json: '{}', routed_to_type: 'agent', routed_to_name: 'x',
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: Date.UTC(2026, 0, 1, 0, 0, 0),
+      prompt: 'ok', intent_json: '{}', routed_to_type: 'skill', routed_to_name: 'y',
+    });
+
+    const trend = storage.aggregateRoutingTrendByDay({ since_ts: 0 });
+    expect(trend.every(t => t.day !== null && t.day.length > 0)).toBe(true);
+    expect(trend).toHaveLength(1);
+    expect(trend[0].day).toBe('2026-01-01');
+  });
+});

package/tests/unit/storage/routing.test.ts

@@ -0,0 +1,117 @@
+/**
+ * M7: getRecentPendingRoutingEvent semantics.
+ *
+ * Verifies the "pending only" filter that the PostToolUseHandler relies on
+ * to associate Agent invocations with the still-unfilled routing_event from
+ * the current user prompt (rather than re-overwriting a completed one).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+
+const PROJECT = '/tmp/m7-proj';
+
+describe('storage.getRecentPendingRoutingEvent', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-m7-routing-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('case 1: older obeyed=1 + newer pending → returns newer pending', () => {
+    const sess = 'sess-1';
+    const oldId = storage.writeRoutingEvent({
+      session_id: sess, project_path: PROJECT, ts: 1000,
+      prompt: 'old', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'a', obeyed: 1,
+    });
+    const newId = storage.writeRoutingEvent({
+      session_id: sess, project_path: PROJECT, ts: 2000,
+      prompt: 'new', intent_json: '{}',
+      obeyed: null,
+    });
+
+    const recent = storage.getRecentPendingRoutingEvent(sess);
+    expect(recent).not.toBeNull();
+    expect(recent!.id).toBe(newId);
+    expect(recent!.id).not.toBe(oldId);
+  });
+
+  it('case 2: all events obeyed=1 → returns null', () => {
+    const sess = 'sess-2';
+    storage.writeRoutingEvent({
+      session_id: sess, project_path: PROJECT, ts: 1000,
+      prompt: 'p1', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'a', obeyed: 1,
+    });
+    storage.writeRoutingEvent({
+      session_id: sess, project_path: PROJECT, ts: 2000,
+      prompt: 'p2', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'b', obeyed: 1,
+    });
+
+    expect(storage.getRecentPendingRoutingEvent(sess)).toBeNull();
+  });
+
+  it('case 3: session isolation — pending in another session is ignored', () => {
+    const sessA = 'sess-A';
+    const sessB = 'sess-B';
+    const aId = storage.writeRoutingEvent({
+      session_id: sessA, project_path: PROJECT, ts: 1000,
+      prompt: 'a-pending', intent_json: '{}',
+      obeyed: null,
+    });
+    storage.writeRoutingEvent({
+      session_id: sessB, project_path: PROJECT, ts: 2000,
+      prompt: 'b-pending', intent_json: '{}',
+      obeyed: null,
+    });
+
+    const rA = storage.getRecentPendingRoutingEvent(sessA);
+    expect(rA).not.toBeNull();
+    expect(rA!.id).toBe(aId);
+
+    // Session with no rows at all returns null.
+    expect(storage.getRecentPendingRoutingEvent('sess-none')).toBeNull();
+  });
+
+  it('case 4: single pending row → returns that row', () => {
+    const sess = 'sess-4';
+    const id = storage.writeRoutingEvent({
+      session_id: sess, project_path: PROJECT, ts: 1234,
+      prompt: 'only', intent_json: '{}',
+      obeyed: null,
+    });
+
+    const recent = storage.getRecentPendingRoutingEvent(sess);
+    expect(recent).not.toBeNull();
+    expect(recent!.id).toBe(id);
+  });
+
+  it('legacy getRecentRoutingEvent still returns most-recent regardless of obeyed', () => {
+    const sess = 'sess-legacy';
+    storage.writeRoutingEvent({
+      session_id: sess, project_path: PROJECT, ts: 1000,
+      prompt: 'old-pending', intent_json: '{}', obeyed: null,
+    });
+    const newerCompletedId = storage.writeRoutingEvent({
+      session_id: sess, project_path: PROJECT, ts: 2000,
+      prompt: 'new-completed', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'x', obeyed: 1,
+    });
+
+    const recent = storage.getRecentRoutingEvent(sess);
+    expect(recent).not.toBeNull();
+    expect(recent!.id).toBe(newerCompletedId);
+  });
+});

package/tests/unit/storage/schema-missing.test.ts

@@ -0,0 +1,81 @@
+/**
+ * H3: schema.sql 缺失时 fail-fast
+ *
+ * 覆盖 base.ts::initSchema 的两个分支：
+ *   1. schema.sql 存在 → 正常初始化 8 张表
+ *   2. schema.sql 缺失 → 立即抛 Error，不再走旧 inline fallback（events 表不会被创建）
+ *
+ * case 2 的实现：用 vi.doMock + 动态 import，对 'node:fs' 的 existsSync 做选择性 mock —
+ * 只让 schema.sql 路径返回 false，其他路径保留真实行为（避免破坏 mkdirSync 的目录检查）。
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import Database from 'better-sqlite3';
+
+describe('H3: schema.sql missing fail-fast', () => {
+  let tmp: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h3-schema-missing-'));
+    dbPath = join(tmp, 'data.db');
+  });
+
+  afterEach(() => {
+    vi.resetModules();
+    vi.restoreAllMocks();
+    vi.doUnmock('node:fs');
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('case 1: schema.sql 存在 → 正常初始化，sessions 表已创建', async () => {
+    const { SQLiteStorage } = await import('../../../src/core/storage/sqlite.js');
+    const storage = new SQLiteStorage(dbPath);
+    const db = storage.getDatabase();
+
+    const row = db
+      .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='sessions'`)
+      .get();
+    expect(row).toBeTruthy();
+
+    storage.close();
+  });
+
+  it('case 2: schema.sql 缺失 → 抛 Error，且未创建任何业务表（确认不走旧 fallback）', async () => {
+    vi.resetModules();
+
+    // 选择性 mock：只让 schema.sql 返回 false，其余路径保留真实 fs 行为
+    vi.doMock('node:fs', async () => {
+      const realFs = await vi.importActual<typeof import('node:fs')>('node:fs');
+      return {
+        ...realFs,
+        existsSync: (p: import('node:fs').PathLike) => {
+          const s = typeof p === 'string' ? p : p.toString();
+          if (s.endsWith('schema.sql')) return false;
+          return realFs.existsSync(p);
+        },
+      };
+    });
+
+    const { SQLiteStorage } = await import('../../../src/core/storage/sqlite.js');
+    expect(() => new SQLiteStorage(dbPath)).toThrow(/schema\.sql not found/);
+
+    // 验证未走旧 inline fallback：events 表不应存在
+    const raw = new Database(dbPath);
+    const eventsRow = raw
+      .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='events'`)
+      .get();
+    expect(eventsRow).toBeFalsy();
+
+    // sessions 表也不存在（schema.sql 完全没跑）
+    const sessionsRow = raw
+      .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='sessions'`)
+      .get();
+    expect(sessionsRow).toBeFalsy();
+
+    raw.close();
+  });
+});

package/tests/unit/storage/session-operations-aggregates.test.ts

@@ -0,0 +1,120 @@
+/**
+ * H2: SessionOperations 新增 aggregate / count / query 方法测试
+ *
+ * 覆盖 4 个方法：
+ *   countAllSessions
+ *   aggregateDailySessionCounts
+ *   querySessionsByTimeRange
+ *   countSessionsByRange
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+import type { ForgeEvent } from '../../../src/core/types.js';
+
+describe('SessionOperations H2 aggregates', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h2-sessions-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  function makeEvent(overrides: Partial<ForgeEvent>): ForgeEvent {
+    return {
+      session_id: 's1',
+      project_path: '/tmp/proj',
+      timestamp: '2026-05-10T10:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'hello',
+      ...overrides,
+    };
+  }
+
+  describe('countAllSessions', () => {
+    it('空表返回 0', () => {
+      expect(storage.countAllSessions()).toBe(0);
+    });
+    it('多 session 返回总数', () => {
+      storage.writeEvent(makeEvent({ session_id: 'a' }));
+      storage.writeEvent(makeEvent({ session_id: 'b' }));
+      storage.writeEvent(makeEvent({ session_id: 'a' })); // same session, upsert
+      expect(storage.countAllSessions()).toBe(2);
+    });
+  });
+
+  describe('aggregateDailySessionCounts', () => {
+    it('按 date(start_time) 分组', () => {
+      storage.writeEvent(makeEvent({ session_id: 'a', timestamp: '2026-05-10T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ session_id: 'b', timestamp: '2026-05-10T15:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ session_id: 'c', timestamp: '2026-05-11T10:00:00.000Z' }));
+      const r = storage.aggregateDailySessionCounts({ since: '2026-05-01T00:00:00.000Z' });
+      expect(r).toEqual([
+        { date: '2026-05-10', count: 2 },
+        { date: '2026-05-11', count: 1 },
+      ]);
+    });
+    it('until 过滤排除上界', () => {
+      storage.writeEvent(makeEvent({ session_id: 'a', timestamp: '2026-05-10T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ session_id: 'b', timestamp: '2026-05-20T10:00:00.000Z' }));
+      const r = storage.aggregateDailySessionCounts({
+        since: '2026-05-01T00:00:00.000Z',
+        until: '2026-05-15T00:00:00.000Z',
+      });
+      expect(r).toEqual([{ date: '2026-05-10', count: 1 }]);
+    });
+    it('空返回空数组', () => {
+      expect(storage.aggregateDailySessionCounts({ since: '2026-05-01T00:00:00.000Z' })).toEqual([]);
+    });
+  });
+
+  describe('querySessionsByTimeRange', () => {
+    it('按 start_time DESC，区间过滤', () => {
+      storage.writeEvent(makeEvent({ session_id: 'old', timestamp: '2026-05-01T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ session_id: 'mid', timestamp: '2026-05-10T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ session_id: 'new', timestamp: '2026-05-15T10:00:00.000Z' }));
+      const r = storage.querySessionsByTimeRange({ since: '2026-05-05T00:00:00.000Z' });
+      expect(r.length).toBe(2);
+      expect(r[0].session_id).toBe('new');
+      expect(r[1].session_id).toBe('mid');
+    });
+    it('暴露 first_prompt 字段', () => {
+      storage.writeEvent(makeEvent({
+        session_id: 'a',
+        timestamp: '2026-05-10T10:00:00.000Z',
+        user_prompt: 'hello world',
+      }));
+      const r = storage.querySessionsByTimeRange({ since: '2026-05-01T00:00:00.000Z' });
+      expect(r[0].first_prompt).toBe('hello world');
+    });
+  });
+
+  describe('countSessionsByRange', () => {
+    it('空表返回 0', () => {
+      expect(storage.countSessionsByRange({ since: '2026-05-01T00:00:00.000Z' })).toBe(0);
+    });
+    it('区间内 session 计数', () => {
+      storage.writeEvent(makeEvent({ session_id: 'a', timestamp: '2026-05-01T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ session_id: 'b', timestamp: '2026-05-10T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ session_id: 'c', timestamp: '2026-05-20T10:00:00.000Z' }));
+      expect(storage.countSessionsByRange({
+        since: '2026-05-05T00:00:00.000Z',
+        until: '2026-05-15T00:00:00.000Z',
+      })).toBe(1);
+    });
+    it('无 until 不限上界', () => {
+      storage.writeEvent(makeEvent({ session_id: 'a', timestamp: '2026-05-10T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ session_id: 'b', timestamp: '2026-05-20T10:00:00.000Z' }));
+      expect(storage.countSessionsByRange({ since: '2026-05-01T00:00:00.000Z' })).toBe(2);
+    });
+  });
+});