@winspan/claude-forge 8.41.0 → 8.51.0

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

@@ -0,0 +1,342 @@
+/**
+ * H2: EventOperations 新增 aggregate / count / query 方法测试
+ *
+ * 覆盖 11 个方法：
+ *   countAllEvents
+ *   aggregateToolUsage（含 hook_type 过滤）
+ *   aggregateDailyEventCounts
+ *   aggregateHookTypeBySession
+ *   aggregateAgentTypeBySession
+ *   aggregateToolUsageBySession
+ *   countActiveDays
+ *   aggregateOverviewByRange
+ *   queryDistinctProjects
+ *   aggregateToolFailureRate
+ *   queryFileEditInputs
+ *   queryEventsByTimeRange
+ */
+
+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('EventOperations H2 aggregates', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h2-events-'));
+    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: 'PreToolUse',
+      ...overrides,
+    };
+  }
+
+  // ── countAllEvents ─────────────────────────────────────────────────
+  describe('countAllEvents', () => {
+    it('空表返回 0', () => {
+      expect(storage.countAllEvents()).toBe(0);
+    });
+    it('多条事件返回总数', () => {
+      storage.writeEvent(makeEvent({ session_id: 'a' }));
+      storage.writeEvent(makeEvent({ session_id: 'b' }));
+      storage.writeEvent(makeEvent({ session_id: 'c' }));
+      expect(storage.countAllEvents()).toBe(3);
+    });
+  });
+
+  // ── aggregateToolUsage ─────────────────────────────────────────────
+  describe('aggregateToolUsage', () => {
+    it('空表返回空数组', () => {
+      expect(storage.aggregateToolUsage()).toEqual([]);
+    });
+    it('按 count 降序，跳过空 tool_name', () => {
+      storage.writeEvent(makeEvent({ tool_name: 'Bash' }));
+      storage.writeEvent(makeEvent({ tool_name: 'Bash' }));
+      storage.writeEvent(makeEvent({ tool_name: 'Read' }));
+      storage.writeEvent(makeEvent({ hook_type: 'UserPromptSubmit' })); // null tool_name
+      const r = storage.aggregateToolUsage();
+      expect(r).toEqual([
+        { tool_name: 'Bash', count: 2 },
+        { tool_name: 'Read', count: 1 },
+      ]);
+    });
+    it('hook_type 过滤只统计指定类型', () => {
+      storage.writeEvent(makeEvent({ tool_name: 'Bash', hook_type: 'PreToolUse' }));
+      storage.writeEvent(makeEvent({ tool_name: 'Bash', hook_type: 'PostToolUse' }));
+      storage.writeEvent(makeEvent({ tool_name: 'Read', hook_type: 'PreToolUse' }));
+      const r = storage.aggregateToolUsage({ hook_type: 'PreToolUse' });
+      expect(r.find(x => x.tool_name === 'Bash')?.count).toBe(1);
+      expect(r.find(x => x.tool_name === 'Read')?.count).toBe(1);
+    });
+    it('since 过滤排除早期事件', () => {
+      storage.writeEvent(makeEvent({ tool_name: 'Bash', timestamp: '2026-01-01T00:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ tool_name: 'Bash', timestamp: '2026-05-10T00:00:00.000Z', session_id: 's2' }));
+      const r = storage.aggregateToolUsage({ since: '2026-03-01T00:00:00.000Z' });
+      expect(r).toEqual([{ tool_name: 'Bash', count: 1 }]);
+    });
+  });
+
+  // ── aggregateDailyEventCounts ──────────────────────────────────────
+  describe('aggregateDailyEventCounts', () => {
+    it('按 date 分组并升序', () => {
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-10T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-10T15:00:00.000Z', session_id: 's2' }));
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-11T10:00:00.000Z', session_id: 's3' }));
+      const r = storage.aggregateDailyEventCounts({ 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({ timestamp: '2026-05-10T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-15T10:00:00.000Z', session_id: 's2' }));
+      const r = storage.aggregateDailyEventCounts({
+        since: '2026-05-01T00:00:00.000Z',
+        until: '2026-05-12T00:00:00.000Z',
+      });
+      expect(r).toEqual([{ date: '2026-05-10', count: 1 }]);
+    });
+  });
+
+  // ── aggregateHookTypeBySession ─────────────────────────────────────
+  describe('aggregateHookTypeBySession', () => {
+    it('空表返回空', () => {
+      expect(storage.aggregateHookTypeBySession('nope')).toEqual([]);
+    });
+    it('只统计指定 session 的 hook_type', () => {
+      storage.writeEvent(makeEvent({ session_id: 'a', hook_type: 'PreToolUse' }));
+      storage.writeEvent(makeEvent({ session_id: 'a', hook_type: 'PostToolUse' }));
+      storage.writeEvent(makeEvent({ session_id: 'a', hook_type: 'PreToolUse' }));
+      storage.writeEvent(makeEvent({ session_id: 'b', hook_type: 'PreToolUse' }));
+      const r = storage.aggregateHookTypeBySession('a');
+      const map = Object.fromEntries(r.map(x => [x.hook_type, x.count]));
+      expect(map).toEqual({ PreToolUse: 2, PostToolUse: 1 });
+    });
+  });
+
+  // ── aggregateAgentTypeBySession ────────────────────────────────────
+  describe('aggregateAgentTypeBySession', () => {
+    it('json_extract subagent_type 并分组', () => {
+      storage.writeEvent(makeEvent({
+        session_id: 'a',
+        tool_name: 'Task',
+        tool_input: { subagent_type: 'researcher' },
+      }));
+      storage.writeEvent(makeEvent({
+        session_id: 'a',
+        tool_name: 'Task',
+        tool_input: { subagent_type: 'researcher' },
+      }));
+      storage.writeEvent(makeEvent({
+        session_id: 'a',
+        tool_name: 'Agent',
+        tool_input: { subagent_type: 'coder' },
+      }));
+      // 非 Agent/Task 不应被纳入
+      storage.writeEvent(makeEvent({
+        session_id: 'a',
+        tool_name: 'Bash',
+        tool_input: { foo: 'bar' },
+      }));
+      const r = storage.aggregateAgentTypeBySession('a');
+      const map = Object.fromEntries(r.map(x => [x.agent_type, x.count]));
+      expect(map.researcher).toBe(2);
+      expect(map.coder).toBe(1);
+    });
+  });
+
+  // ── aggregateToolUsageBySession ────────────────────────────────────
+  describe('aggregateToolUsageBySession', () => {
+    it('按 session_id 统计 tool_name', () => {
+      storage.writeEvent(makeEvent({ session_id: 'a', tool_name: 'Bash' }));
+      storage.writeEvent(makeEvent({ session_id: 'a', tool_name: 'Bash' }));
+      storage.writeEvent(makeEvent({ session_id: 'a', tool_name: 'Read' }));
+      storage.writeEvent(makeEvent({ session_id: 'b', tool_name: 'Bash' }));
+      const r = storage.aggregateToolUsageBySession('a');
+      expect(r).toEqual([
+        { tool_name: 'Bash', count: 2 },
+        { tool_name: 'Read', count: 1 },
+      ]);
+    });
+  });
+
+  // ── countActiveDays ────────────────────────────────────────────────
+  describe('countActiveDays', () => {
+    it('distinct date 计数', () => {
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-10T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-10T11:00:00.000Z', session_id: 's2' }));
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-11T10:00:00.000Z', session_id: 's3' }));
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-12T10:00:00.000Z', session_id: 's4' }));
+      expect(storage.countActiveDays({ since: '2026-05-01T00:00:00.000Z' })).toBe(3);
+    });
+    it('空范围返回 0', () => {
+      expect(storage.countActiveDays({ since: '2026-05-01T00:00:00.000Z' })).toBe(0);
+    });
+  });
+
+  // ── aggregateOverviewByRange ───────────────────────────────────────
+  describe('aggregateOverviewByRange', () => {
+    it('返回 event/session/day 复合计数', () => {
+      storage.writeEvent(makeEvent({ session_id: 'a', timestamp: '2026-05-10T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ session_id: 'a', timestamp: '2026-05-10T11:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ session_id: 'b', timestamp: '2026-05-11T10:00:00.000Z' }));
+      const r = storage.aggregateOverviewByRange({
+        since: '2026-05-01T00:00:00.000Z',
+        until: '2026-06-01T00:00:00.000Z',
+      });
+      expect(r.event_count).toBe(3);
+      expect(r.session_count).toBe(2);
+      expect(r.day_count).toBe(2);
+    });
+    it('空表返回全 0', () => {
+      const r = storage.aggregateOverviewByRange({
+        since: '2026-05-01T00:00:00.000Z',
+        until: '2026-06-01T00:00:00.000Z',
+      });
+      expect(r).toEqual({ event_count: 0, session_count: 0, day_count: 0 });
+    });
+  });
+
+  // ── queryDistinctProjects ──────────────────────────────────────────
+  describe('queryDistinctProjects', () => {
+    it('返回 distinct project_path', () => {
+      storage.writeEvent(makeEvent({ project_path: '/a' }));
+      storage.writeEvent(makeEvent({ project_path: '/a', session_id: 's2' }));
+      storage.writeEvent(makeEvent({ project_path: '/b', session_id: 's3' }));
+      const r = storage.queryDistinctProjects({
+        since: '2026-05-01T00:00:00.000Z',
+        until: '2026-06-01T00:00:00.000Z',
+      });
+      expect(r.sort()).toEqual(['/a', '/b']);
+    });
+  });
+
+  // ── aggregateToolFailureRate ───────────────────────────────────────
+  describe('aggregateToolFailureRate', () => {
+    it('LIKE %error% 三个分支正确识别失败', () => {
+      // PostToolUse with error
+      storage.writeEvent(makeEvent({
+        hook_type: 'PostToolUse',
+        tool_name: 'Bash',
+        tool_output: { error: 'oops' }, // becomes '"error":"oops"' in JSON
+      }));
+      storage.writeEvent(makeEvent({
+        hook_type: 'PostToolUse',
+        tool_name: 'Bash',
+        tool_output: { is_error: true },
+        session_id: 's2',
+      }));
+      storage.writeEvent(makeEvent({
+        hook_type: 'PostToolUse',
+        tool_name: 'Bash',
+        tool_output: { isError: true },
+        session_id: 's3',
+      }));
+      // PostToolUse OK
+      storage.writeEvent(makeEvent({
+        hook_type: 'PostToolUse',
+        tool_name: 'Bash',
+        tool_output: { result: 'ok' },
+        session_id: 's4',
+      }));
+      // PreToolUse should not count
+      storage.writeEvent(makeEvent({
+        hook_type: 'PreToolUse',
+        tool_name: 'Bash',
+        tool_output: { error: 'should not count' },
+        session_id: 's5',
+      }));
+
+      const r = storage.aggregateToolFailureRate({
+        since: '2026-05-01T00:00:00.000Z',
+        until: '2026-06-01T00:00:00.000Z',
+      });
+      expect(r.post_total).toBe(4);
+      expect(r.failed).toBe(3);
+    });
+    it('空范围返回 0/0', () => {
+      const r = storage.aggregateToolFailureRate({
+        since: '2026-05-01T00:00:00.000Z',
+        until: '2026-06-01T00:00:00.000Z',
+      });
+      expect(r).toEqual({ post_total: 0, failed: 0 });
+    });
+  });
+
+  // ── queryFileEditInputs ────────────────────────────────────────────
+  describe('queryFileEditInputs', () => {
+    it('IN 展开多个 tool_name', () => {
+      storage.writeEvent(makeEvent({
+        hook_type: 'PreToolUse',
+        tool_name: 'Edit',
+        tool_input: { file_path: '/a.ts' },
+      }));
+      storage.writeEvent(makeEvent({
+        hook_type: 'PreToolUse',
+        tool_name: 'Write',
+        tool_input: { file_path: '/b.ts' },
+        session_id: 's2',
+      }));
+      storage.writeEvent(makeEvent({
+        hook_type: 'PreToolUse',
+        tool_name: 'Bash', // not file edit
+        tool_input: { command: 'ls' },
+        session_id: 's3',
+      }));
+      const r = storage.queryFileEditInputs({
+        since: '2026-05-01T00:00:00.000Z',
+        until: '2026-06-01T00:00:00.000Z',
+        tool_names: ['Edit', 'Write', 'MultiEdit'],
+      });
+      expect(r.length).toBe(2);
+      expect(r.map(x => JSON.parse(x.tool_input).file_path).sort()).toEqual(['/a.ts', '/b.ts']);
+    });
+    it('空 tool_names 返回空', () => {
+      storage.writeEvent(makeEvent({ tool_name: 'Edit', tool_input: { file_path: '/a.ts' } }));
+      expect(storage.queryFileEditInputs({
+        since: '2026-05-01T00:00:00.000Z',
+        until: '2026-06-01T00:00:00.000Z',
+        tool_names: [],
+      })).toEqual([]);
+    });
+  });
+
+  // ── queryEventsByTimeRange ─────────────────────────────────────────
+  describe('queryEventsByTimeRange', () => {
+    it('返回 [since, until) 区间事件，升序', () => {
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-10T10:00:00.000Z', tool_name: 'A' }));
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-11T10:00:00.000Z', tool_name: 'B', session_id: 's2' }));
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-12T10:00:00.000Z', tool_name: 'C', session_id: 's3' }));
+      const r = storage.queryEventsByTimeRange({
+        since: '2026-05-10T00:00:00.000Z',
+        until: '2026-05-12T00:00:00.000Z',
+      });
+      expect(r.length).toBe(2);
+      expect(r[0].tool_name).toBe('A');
+      expect(r[1].tool_name).toBe('B');
+    });
+    it('未指定 until 返回 since 起始的全部', () => {
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-10T10:00:00.000Z' }));
+      storage.writeEvent(makeEvent({ timestamp: '2026-05-20T10:00:00.000Z', session_id: 's2' }));
+      const r = storage.queryEventsByTimeRange({ since: '2026-05-15T00:00:00.000Z' });
+      expect(r.length).toBe(1);
+    });
+  });
+});

package/tests/unit/storage/migration-idempotent.test.ts

@@ -0,0 +1,304 @@
+/**
+ * H4: migration idempotent
+ *
+ * 覆盖 schema.sql 与 base.ts::runMigrations 的去重边界：
+ *   1. baseline — 老库缺索引/列，SQLiteStorage 启动后必须补齐
+ *   2. 新库无害 — 走完整 schema.sql 后，再 new SQLiteStorage 不抛错，不重复创建
+ *   3. idempotent — 连续 new 多次，索引/列数量不变
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import Database from 'better-sqlite3';
+import { mkdtempSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+import { logger } from '../../../src/core/utils/logger.js';
+
+// 与 base.ts::initSchema 解析方式一致
+const THIS_DIR = dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = join(THIS_DIR, '../../../src/core/storage/schema.sql');
+
+function listIndexes(db: Database.Database): Set<string> {
+  const rows = db
+    .prepare(`SELECT name FROM sqlite_master WHERE type='index' AND name NOT LIKE 'sqlite_%'`)
+    .all() as Array<{ name: string }>;
+  return new Set(rows.map(r => r.name));
+}
+
+function listColumns(db: Database.Database, table: string): Set<string> {
+  const rows = db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+  return new Set(rows.map(r => r.name));
+}
+
+/**
+ * 写入一份"老库"——故意删掉若干索引，模拟存量库。
+ * 列定义保持与最新 schema.sql 等价（不缺列），因为 schema.sql 的
+ * CREATE TABLE IF NOT EXISTS 在表已存在时不会补列；同时 schema.sql 中
+ * 多个索引（如 idx_skill_invocations_workflow）依赖 workflow 列存在。
+ * 故"老库缺列"测试见单独 case，与"老库缺索引"分开覆盖，避免初始化期失败。
+ */
+function execLegacySchemaMissingIndexes(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE events (
+      event_id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      project_path TEXT NOT NULL,
+      timestamp TEXT NOT NULL,
+      hook_type TEXT NOT NULL,
+      tool_name TEXT,
+      tool_input TEXT,
+      tool_output TEXT,
+      user_prompt TEXT,
+      ai_response TEXT,
+      distilled INTEGER DEFAULT 0,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE sessions (
+      session_id TEXT PRIMARY KEY,
+      project_path TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active',
+      first_prompt TEXT,
+      start_time TEXT NOT NULL,
+      end_time TEXT,
+      last_event_time TEXT,
+      event_count INTEGER DEFAULT 0,
+      created_at TEXT DEFAULT (datetime('now')),
+      updated_at TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE injections (
+      id TEXT PRIMARY KEY,
+      event_id TEXT,
+      session_id TEXT NOT NULL,
+      timestamp TEXT NOT NULL,
+      source_handler TEXT NOT NULL,
+      injection_type TEXT NOT NULL,
+      content TEXT NOT NULL,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE tasks (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      title TEXT NOT NULL,
+      description TEXT,
+      start_time TEXT NOT NULL,
+      end_time TEXT,
+      status TEXT DEFAULT 'active',
+      event_count INTEGER DEFAULT 0,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE task_events (
+      task_id TEXT NOT NULL,
+      event_id TEXT NOT NULL,
+      PRIMARY KEY (task_id, event_id)
+    );
+
+    CREATE TABLE routing_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      route_request_id TEXT,
+      project_path TEXT NOT NULL,
+      ts INTEGER NOT NULL,
+      prompt TEXT NOT NULL,
+      intent_json TEXT NOT NULL,
+      routed_to_type TEXT,
+      routed_to_name TEXT,
+      is_forced INTEGER DEFAULT 0,
+      obeyed INTEGER,
+      classification_ms INTEGER,
+      fallback_used INTEGER DEFAULT 0,
+      refusal_reason TEXT,
+      first_tool_name TEXT,
+      first_tool_ts INTEGER,
+      completed_ts INTEGER,
+      total_execution_ms INTEGER,
+      completion_reason TEXT,
+      downstream_task_chain TEXT,
+      injection_version TEXT,
+      experiment_id TEXT,
+      experiment_group TEXT,
+      skill_confidence REAL,
+      skill_source TEXT,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE token_usage (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      timestamp INTEGER NOT NULL,
+      input_tokens INTEGER NOT NULL,
+      output_tokens INTEGER NOT NULL,
+      total_tokens INTEGER NOT NULL,
+      model TEXT,
+      tool_name TEXT,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE skill_invocations (
+      id TEXT PRIMARY KEY,
+      route_request_id TEXT,
+      session_id TEXT NOT NULL,
+      agent_id TEXT,
+      skill_id TEXT NOT NULL,
+      invocation_type TEXT NOT NULL,
+      reason TEXT,
+      workflow TEXT,
+      phase TEXT,
+      feature_slug TEXT,
+      artifact_path TEXT,
+      depth INTEGER DEFAULT 0,
+      success INTEGER DEFAULT 1,
+      error TEXT,
+      timestamp INTEGER NOT NULL,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+    -- 故意不创建以下任何索引（migration 必须补齐）
+  `);
+}
+
+/**
+ * 老库——只缺 sessions.first_prompt 列（其他列齐全 + 完整索引）。
+ * 单独 case，验证 addColumnIfMissing 补齐。
+ */
+function execLegacySchemaMissingFirstPrompt(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE sessions (
+      session_id TEXT PRIMARY KEY,
+      project_path TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active',
+      start_time TEXT NOT NULL,
+      end_time TEXT,
+      last_event_time TEXT,
+      event_count INTEGER DEFAULT 0,
+      created_at TEXT DEFAULT (datetime('now')),
+      updated_at TEXT DEFAULT (datetime('now'))
+    );
+  `);
+}
+
+describe('H4: storage migration idempotent', () => {
+  let tmp: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h4-migration-'));
+    dbPath = join(tmp, 'data.db');
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it('baseline (缺索引): 老库索引齐缺，SQLiteStorage 启动后补齐全部 migration 索引', () => {
+    // 1) 手工写入只缺索引的旧 schema
+    const raw = new Database(dbPath);
+    execLegacySchemaMissingIndexes(raw);
+    const beforeIdx = listIndexes(raw);
+    expect(beforeIdx.has('idx_routing_events_type_ts')).toBe(false);
+    expect(beforeIdx.has('idx_skill_invocations_workflow')).toBe(false);
+    expect(beforeIdx.has('idx_skill_invocations_feature')).toBe(false);
+    expect(beforeIdx.has('idx_sessions_start_time')).toBe(false);
+    expect(beforeIdx.has('idx_events_session_ts')).toBe(false);
+    raw.close();
+
+    // 2) 用 SQLiteStorage 打开 → 触发 schema.sql + runMigrations
+    const storage = new SQLiteStorage(dbPath);
+    const db = storage.getDatabase();
+
+    // 3) 关键索引全部补齐（涵盖 spec 重复清单中所有 migration-only / 双写索引）
+    const idx = listIndexes(db);
+    const expected = [
+      'idx_sessions_start_time',
+      'idx_events_session_ts',
+      'idx_routing_events_session_ts',
+      'idx_skill_invocations_session_ts',
+      'idx_routing_events_obeyed_ts',
+      'idx_events_session_hook',
+      'idx_injections_session_handler',
+      'idx_routing_events_type_ts',
+      'idx_skill_invocations_workflow',
+      'idx_skill_invocations_feature',
+    ];
+    for (const name of expected) {
+      expect(idx.has(name), `expected index ${name} to exist after migration`).toBe(true);
+    }
+
+    storage.close();
+  });
+
+  it('baseline (缺列): 老库缺 sessions.first_prompt，migration ALTER 补齐', () => {
+    const raw = new Database(dbPath);
+    execLegacySchemaMissingFirstPrompt(raw);
+    expect(listColumns(raw, 'sessions').has('first_prompt')).toBe(false);
+    raw.close();
+
+    const storage = new SQLiteStorage(dbPath);
+    const db = storage.getDatabase();
+
+    // first_prompt 列由 addColumnIfMissing 补齐
+    expect(listColumns(db, 'sessions').has('first_prompt')).toBe(true);
+
+    storage.close();
+  });
+
+  it('新库（完整 schema.sql 初始化）再启动 SQLiteStorage：migration 不会重复创建索引', () => {
+    // 1) 用完整 schema.sql 初始化（模拟 base.initSchema 已跑完，sqlite-base 同样这么干）
+    expect(existsSync(SCHEMA_PATH)).toBe(true);
+    const schemaSql = readFileSync(SCHEMA_PATH, 'utf-8');
+    const raw = new Database(dbPath);
+    raw.exec(schemaSql);
+    const indexesAfterSchema = listIndexes(raw);
+    raw.close();
+
+    // 2) 监听 logger.debug，统计"migration created idx_xxx"次数
+    const debugSpy = vi.spyOn(logger, 'debug').mockImplementation(() => {});
+    const warnSpy = vi.spyOn(logger, 'warn').mockImplementation(() => {});
+    const errorSpy = vi.spyOn(logger, 'error').mockImplementation(() => {});
+
+    // 3) new SQLiteStorage → runMigrations 应当跳过所有 createIndexIfMissing
+    const storage = new SQLiteStorage(dbPath);
+
+    const createdCalls = debugSpy.mock.calls.filter(
+      args => typeof args[0] === 'string' && args[0].includes('migration created'),
+    );
+    expect(createdCalls.length).toBe(0);
+
+    // 不应有 warn/error
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(errorSpy).not.toHaveBeenCalled();
+
+    // 索引集合相比 schema.sql 初始化后无变化
+    const indexesAfterMigration = listIndexes(storage.getDatabase());
+    expect(indexesAfterMigration).toEqual(indexesAfterSchema);
+
+    storage.close();
+  });
+
+  it('idempotent: 连续多次 new SQLiteStorage 不改变索引/列数量', () => {
+    const snapshots: Array<{ idx: Set<string>; cols: Set<string> }> = [];
+
+    for (let i = 0; i < 3; i++) {
+      const storage = new SQLiteStorage(dbPath);
+      const db = storage.getDatabase();
+      snapshots.push({
+        idx: listIndexes(db),
+        cols: listColumns(db, 'skill_invocations'),
+      });
+      storage.close();
+    }
+
+    // 索引集合在三次之间完全一致
+    expect(snapshots[0].idx).toEqual(snapshots[1].idx);
+    expect(snapshots[1].idx).toEqual(snapshots[2].idx);
+
+    // skill_invocations 列集合在三次之间一致
+    expect(snapshots[0].cols).toEqual(snapshots[1].cols);
+    expect(snapshots[1].cols).toEqual(snapshots[2].cols);
+  });
+});