@winspan/claude-forge 8.41.0 → 8.51.0

package/tests/unit/storage/sqlite-refactor-harness.test.ts

@@ -0,0 +1,314 @@
+/**
+ * Characterization tests for SQLiteStorage refactoring
+ *
+ * Purpose: Capture current behavior before refactoring sqlite.ts
+ * These tests document ACTUAL behavior, not necessarily CORRECT behavior
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+import type { ForgeEvent } from '../../../src/core/types.js';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+describe('SQLiteStorage - Characterization Tests (Pre-Refactor)', () => {
+  let storage: SQLiteStorage;
+  let tempDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'forge-harness-'));
+    dbPath = join(tempDir, 'test.db');
+    storage = new SQLiteStorage(dbPath);
+  });
+
+  afterEach(() => {
+    storage.close();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('Event Operations', () => {
+    it('writeEvent stores event and triggers session upsert', () => {
+      const event: ForgeEvent = {
+        session_id: 'test-session',
+        project_path: '/test/project',
+        timestamp: new Date().toISOString(),
+        hook_type: 'PreToolUse',
+        tool_name: 'Bash',
+        tool_input: { command: 'ls' },
+      };
+
+      storage.writeEvent(event);
+
+      const events = storage.queryEvents({ session_id: 'test-session' });
+      expect(events).toHaveLength(1);
+      expect(events[0].tool_name).toBe('Bash');
+      expect(events[0].session_id).toBe('test-session');
+
+      // Verify session was auto-created
+      const sessions = storage.querySessions({ limit: 10 });
+      expect(sessions.length).toBeGreaterThan(0);
+      expect(sessions[0].session_id).toBe('test-session');
+    });
+
+    it('queryEvents filters by session_id', () => {
+      storage.writeEvent({
+        session_id: 'session-1',
+        project_path: '/project-a',
+        timestamp: new Date().toISOString(),
+        hook_type: 'PreToolUse',
+      });
+      storage.writeEvent({
+        session_id: 'session-2',
+        project_path: '/project-a',
+        timestamp: new Date().toISOString(),
+        hook_type: 'PostToolUse',
+      });
+
+      const events = storage.queryEvents({ session_id: 'session-1' });
+      expect(events).toHaveLength(1);
+      expect(events[0].session_id).toBe('session-1');
+    });
+
+    it('countEvents returns total count', () => {
+      storage.writeEvent({
+        session_id: 'test',
+        project_path: '/test',
+        timestamp: new Date().toISOString(),
+        hook_type: 'PreToolUse',
+      });
+      expect(storage.countEvents()).toBe(1);
+    });
+  });
+
+  describe('Session Operations', () => {
+    it('querySessions returns session summaries', () => {
+      storage.writeEvent({
+        session_id: 'session-1',
+        project_path: '/project-a',
+        timestamp: '2026-01-01T00:00:00Z',
+        hook_type: 'UserPromptSubmit',
+        user_prompt: 'Test prompt',
+      });
+
+      const sessions = storage.querySessions({ limit: 10 });
+      expect(sessions).toHaveLength(1);
+      expect(sessions[0].session_id).toBe('session-1');
+      expect(sessions[0].first_prompt).toBe('Test prompt');
+      expect(sessions[0].event_count).toBe(1);
+    });
+
+    it('upsertSession updates existing session', () => {
+      const event1: ForgeEvent = {
+        session_id: 'session-1',
+        project_path: '/project-a',
+        timestamp: '2026-01-01T00:00:00Z',
+        hook_type: 'PreToolUse',
+      };
+      storage.writeEvent(event1);
+
+      const event2: ForgeEvent = {
+        session_id: 'session-1',
+        project_path: '/project-a',
+        timestamp: '2026-01-01T01:00:00Z',
+        hook_type: 'PostToolUse',
+      };
+      storage.writeEvent(event2);
+
+      const sessions = storage.querySessions({ limit: 10 });
+      expect(sessions).toHaveLength(1);
+      expect(sessions[0].event_count).toBe(2);
+    });
+  });
+
+  describe('Task Operations', () => {
+    it('writeTask and queryTasks work correctly', () => {
+      storage.writeTask({
+        id: 'task-1',
+        session_id: 'session-1',
+        title: 'Test Task',
+        start_time: '2026-01-01T00:00:00Z',
+      });
+
+      const tasks = storage.queryTasks({ session_id: 'session-1' });
+      expect(tasks).toHaveLength(1);
+      expect(tasks[0].id).toBe('task-1');
+      expect(tasks[0].title).toBe('Test Task');
+    });
+
+    it('updateTask modifies task fields', () => {
+      storage.writeTask({
+        id: 'task-1',
+        session_id: 'session-1',
+        title: 'Test Task',
+        start_time: '2026-01-01T00:00:00Z',
+      });
+
+      storage.updateTask('task-1', {
+        status: 'completed',
+        end_time: '2026-01-01T01:00:00Z',
+      });
+
+      const tasks = storage.queryTasks({ session_id: 'session-1' });
+      expect(tasks[0].status).toBe('completed');
+      expect(tasks[0].end_time).toBe('2026-01-01T01:00:00Z');
+    });
+
+    it('linkEventToTask associates events with tasks', () => {
+      storage.writeTask({
+        id: 'task-1',
+        session_id: 'session-1',
+        title: 'Test Task',
+        start_time: '2026-01-01T00:00:00Z',
+      });
+
+      storage.writeEvent({
+        event_id: 'event-1',
+        session_id: 'session-1',
+        project_path: '/test',
+        timestamp: '2026-01-01T00:00:00Z',
+        hook_type: 'PreToolUse',
+      });
+
+      storage.linkEventToTask('task-1', 'event-1');
+
+      const eventIds = storage.getTaskEventIds('task-1');
+      expect(eventIds).toContain('event-1');
+    });
+  });
+
+  describe('Injection Operations', () => {
+    it('writeInjection and queryInjections work correctly', () => {
+      storage.writeInjection({
+        session_id: 'session-1',
+        timestamp: '2026-01-01T00:00:00Z',
+        source_handler: 'test-handler',
+        injection_type: 'systemMessage',
+        content: 'Test injection',
+      });
+
+      const injections = storage.queryInjections({ session_id: 'session-1' });
+      expect(injections).toHaveLength(1);
+      expect(injections[0].content).toBe('Test injection');
+    });
+  });
+
+  describe('Routing Operations', () => {
+    it('writeRoutingEvent and queryRoutingEvents work correctly', () => {
+      const id = storage.writeRoutingEvent({
+        session_id: 'session-1',
+        project_path: '/test',
+        ts: Date.now(),
+        prompt: 'test prompt',
+        intent_json: '{}',
+      });
+
+      expect(id).toBeGreaterThan(0);
+
+      const events = storage.queryRoutingEvents({ session_id: 'session-1' });
+      expect(events).toHaveLength(1);
+      expect(events[0].prompt).toBe('test prompt');
+    });
+
+    it('updateRoutingEvent modifies routing event', () => {
+      const id = storage.writeRoutingEvent({
+        session_id: 'session-1',
+        project_path: '/test',
+        ts: Date.now(),
+        prompt: 'test prompt',
+        intent_json: '{}',
+      });
+
+      storage.updateRoutingEvent(id, { obeyed: 1 });
+
+      const events = storage.queryRoutingEvents({ session_id: 'session-1' });
+      expect(events[0].obeyed).toBe(1);
+    });
+  });
+
+  describe('Token Usage Operations', () => {
+    it('writeTokenUsage and getTokenUsageBySession work correctly', () => {
+      storage.writeTokenUsage({
+        session_id: 'session-1',
+        input_tokens: 100,
+        output_tokens: 50,
+        model: 'claude-opus-4',
+      });
+
+      const usage = storage.getTokenUsageBySession('session-1');
+      expect(usage.input_tokens).toBe(100);
+      expect(usage.output_tokens).toBe(50);
+      expect(usage.total_tokens).toBe(150);
+    });
+
+    it('listTokenUsage returns usage records', () => {
+      storage.writeTokenUsage({
+        session_id: 'session-1',
+        input_tokens: 100,
+        output_tokens: 50,
+      });
+
+      const records = storage.listTokenUsage({ session_id: 'session-1' });
+      expect(records).toHaveLength(1);
+      expect(records[0].input_tokens).toBe(100);
+    });
+  });
+
+  describe('Skill Invocation Operations', () => {
+    it('writeSkillInvocation and querySkillInvocations work correctly', () => {
+      storage.writeSkillInvocation({
+        id: 'skill-1',
+        route_request_id: 'route-1',
+        session_id: 'session-1',
+        agent_id: 'agent-1',
+        skill_id: 'test-skill',
+        invocation_type: 'auto',
+        reason: 'test/phase',
+        workflow: 'test',
+        phase: 'phase',
+        feature_slug: null,
+        artifact_path: null,
+        depth: 0,
+        success: 1,
+        error: null,
+        timestamp: Date.now(),
+      });
+
+      const invocations = storage.querySkillInvocations({ session_id: 'session-1' });
+      expect(invocations).toHaveLength(1);
+      expect(invocations[0].skill_id).toBe('test-skill');
+    });
+  });
+
+  describe('Maintenance Operations', () => {
+    it('cleanOldEvents removes old events', () => {
+      storage.writeEvent({
+        session_id: 'test',
+        project_path: '/test',
+        timestamp: '2020-01-01T00:00:00Z',
+        hook_type: 'PreToolUse',
+      });
+
+      const deleted = storage.cleanOldEvents(30);
+      expect(deleted).toBe(1);
+    });
+
+    it('vacuum runs without error', () => {
+      expect(() => storage.vacuum()).not.toThrow();
+    });
+  });
+
+  describe('Database Accessors', () => {
+    it('getDatabase returns database instance', () => {
+      const db = storage.getDatabase();
+      expect(db).toBeDefined();
+    });
+
+    it('getDbPath returns database path', () => {
+      const path = storage.getDbPath();
+      expect(path).toBe(dbPath);
+    });
+  });
+});
+

package/tests/unit/storage/task-operations-counts.test.ts

@@ -0,0 +1,46 @@
+/**
+ * H2: TaskOperations 新增 countTasksByRange 方法测试
+ */
+
+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';
+
+describe('TaskOperations H2: countTasksByRange', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h2-tasks-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('空表返回 0', () => {
+    expect(storage.countTasksByRange({ since: '2026-05-01T00:00:00.000Z' })).toBe(0);
+  });
+
+  it('按 start_time 区间过滤', () => {
+    storage.writeTask({ id: 't1', session_id: 's1', title: 'old', start_time: '2026-05-01T10:00:00.000Z' });
+    storage.writeTask({ id: 't2', session_id: 's1', title: 'mid', start_time: '2026-05-10T10:00:00.000Z' });
+    storage.writeTask({ id: 't3', session_id: 's1', title: 'new', start_time: '2026-05-20T10:00:00.000Z' });
+
+    expect(storage.countTasksByRange({
+      since: '2026-05-05T00:00:00.000Z',
+      until: '2026-05-15T00:00:00.000Z',
+    })).toBe(1);
+  });
+
+  it('无 until 不限上界', () => {
+    storage.writeTask({ id: 't1', session_id: 's1', title: 'a', start_time: '2026-05-10T10:00:00.000Z' });
+    storage.writeTask({ id: 't2', session_id: 's1', title: 'b', start_time: '2026-05-20T10:00:00.000Z' });
+
+    expect(storage.countTasksByRange({ since: '2026-05-01T00:00:00.000Z' })).toBe(2);
+  });
+});

package/tests/unit/storage/tasks-getById.test.ts

@@ -0,0 +1,343 @@
+/**
+ * H1 storage: tasks detail PK 直查 / JOIN 接口
+ *
+ * 覆盖：
+ *   - getTask 命中 / null
+ *   - getTask 通过 LEFT JOIN sessions 取 project_path
+ *   - queryEventsByTaskId JOIN 正确性 + timestamp ASC 排序 + limit
+ *   - queryInjectionsByTaskId event_id 关联
+ *   - querySkillInvocationsByTaskWindow 时间窗包含/排除
+ *   - querySkillInvocationsByTaskWindow end_time IS NULL 时取 now_ms
+ */
+
+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 { randomUUID } from 'node:crypto';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+import type { ForgeEvent } from '../../../src/core/types.js';
+
+const SESSION = 'sess-t';
+const PROJECT = '/tmp/proj-t';
+
+/** Map a friendly short id to a deterministic-per-test UUID. */
+const idMap = new Map<string, string>();
+function uid(short: string): string {
+  let v = idMap.get(short);
+  if (!v) {
+    v = randomUUID();
+    idMap.set(short, v);
+  }
+  return v;
+}
+function resetIdMap() { idMap.clear(); }
+
+function makeEvent(overrides: Partial<ForgeEvent> & { event_id: string; timestamp: string }): ForgeEvent {
+  return {
+    event_id: overrides.event_id,
+    session_id: overrides.session_id ?? SESSION,
+    project_path: overrides.project_path ?? PROJECT,
+    timestamp: overrides.timestamp,
+    hook_type: overrides.hook_type ?? 'UserPromptSubmit',
+    user_prompt: overrides.user_prompt ?? 'hi',
+    ...overrides,
+  } as ForgeEvent;
+}
+
+function makeInv(overrides: {
+  id: string;
+  skill_id: string;
+  timestamp: number;
+  session_id?: string;
+}) {
+  return {
+    id: overrides.id,
+    route_request_id: null,
+    session_id: overrides.session_id ?? SESSION,
+    agent_id: null,
+    skill_id: overrides.skill_id,
+    invocation_type: 'dynamic' as const,
+    reason: null,
+    workflow: null,
+    phase: null,
+    feature_slug: null,
+    artifact_path: null,
+    depth: 0,
+    success: 1 as 0 | 1,
+    error: null,
+    timestamp: overrides.timestamp,
+  };
+}
+
+/** 让 sessions 表有这条 session_id（写一条事件就会 upsertSession） */
+function seedSession(storage: SQLiteStorage, sessionId: string, projectPath: string) {
+  storage.writeEvent(makeEvent({
+    event_id: randomUUID(),
+    session_id: sessionId,
+    project_path: projectPath,
+    timestamp: '2026-01-01T00:00:00.000Z',
+    hook_type: 'UserPromptSubmit',
+    user_prompt: 'seed',
+  }));
+}
+
+describe('storage.getTask', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h1-tasks-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+    resetIdMap();
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('未知 taskId 返回 null', () => {
+    expect(storage.getTask('no-such-task')).toBeNull();
+  });
+
+  it('命中：返回 TaskRecord，含 LEFT JOIN 来的 project_path', () => {
+    seedSession(storage, SESSION, PROJECT);
+    storage.writeTask({
+      id: 't1',
+      session_id: SESSION,
+      title: 'Build something',
+      start_time: '2026-01-01T10:00:00.000Z',
+    });
+
+    const t = storage.getTask('t1');
+    expect(t).not.toBeNull();
+    expect(t!.id).toBe('t1');
+    expect(t!.session_id).toBe(SESSION);
+    expect(t!.title).toBe('Build something');
+    expect(t!.start_time).toBe('2026-01-01T10:00:00.000Z');
+    expect(t!.status).toBe('active');
+    expect(t!.event_count).toBe(0);
+    expect(t!.project_path).toBe(PROJECT);
+  });
+
+  it('session 不存在时 project_path 为 undefined（LEFT JOIN）', () => {
+    storage.writeTask({
+      id: 't-orphan',
+      session_id: 'missing-session',
+      title: 'Orphan',
+      start_time: '2026-01-01T10:00:00.000Z',
+    });
+    const t = storage.getTask('t-orphan');
+    expect(t).not.toBeNull();
+    expect(t!.project_path).toBeUndefined();
+  });
+});
+
+describe('storage.queryEventsByTaskId', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h1-tasks-evt-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+    resetIdMap();
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('未知 taskId 返回 []', () => {
+    expect(storage.queryEventsByTaskId('nope')).toEqual([]);
+  });
+
+  it('JOIN 仅返回 link 过的事件，且按 timestamp ASC 排序', () => {
+    seedSession(storage, SESSION, PROJECT);
+    storage.writeTask({
+      id: 't1', session_id: SESSION, title: 'T', start_time: '2026-01-01T10:00:00.000Z',
+    });
+
+    // 写 3 条事件，乱序 timestamp
+    storage.writeEvent(makeEvent({ event_id: uid('e3'), timestamp: '2026-01-01T10:30:00.000Z', hook_type: 'PostToolUse' }));
+    storage.writeEvent(makeEvent({ event_id: uid('e1'), timestamp: '2026-01-01T10:10:00.000Z', hook_type: 'PreToolUse' }));
+    storage.writeEvent(makeEvent({ event_id: uid('e2'), timestamp: '2026-01-01T10:20:00.000Z', hook_type: 'Stop' }));
+    // 一条不 link 的事件
+    storage.writeEvent(makeEvent({ event_id: uid('e-unlinked'), timestamp: '2026-01-01T10:15:00.000Z', hook_type: 'Notification' }));
+
+    storage.linkEventToTask('t1', uid('e1'));
+    storage.linkEventToTask('t1', uid('e2'));
+    storage.linkEventToTask('t1', uid('e3'));
+
+    const evts = storage.queryEventsByTaskId('t1');
+    expect(evts.map(e => e.event_id)).toEqual([uid('e1'), uid('e2'), uid('e3')]);
+    // 未 link 的不出现
+    expect(evts.find(e => e.event_id === uid('e-unlinked'))).toBeUndefined();
+    // hook_type 字段被正确还原
+    expect(evts[0].hook_type).toBe('PreToolUse');
+  });
+
+  it('limit 生效', () => {
+    seedSession(storage, SESSION, PROJECT);
+    storage.writeTask({
+      id: 't1', session_id: SESSION, title: 'T', start_time: '2026-01-01T10:00:00.000Z',
+    });
+    for (let i = 0; i < 5; i++) {
+      const short = `e${i}`;
+      const id = uid(short);
+      storage.writeEvent(makeEvent({ event_id: id, timestamp: `2026-01-01T10:0${i}:00.000Z` }));
+      storage.linkEventToTask('t1', id);
+    }
+    const evts = storage.queryEventsByTaskId('t1', { limit: 3 });
+    expect(evts).toHaveLength(3);
+    expect(evts.map(e => e.event_id)).toEqual([uid('e0'), uid('e1'), uid('e2')]);
+  });
+});
+
+describe('storage.queryInjectionsByTaskId', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h1-tasks-inj-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+    resetIdMap();
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('未知 taskId 返回 []', () => {
+    expect(storage.queryInjectionsByTaskId('nope')).toEqual([]);
+  });
+
+  it('仅返回 event_id 关联到 task 的 injections，按 timestamp ASC', () => {
+    seedSession(storage, SESSION, PROJECT);
+    storage.writeTask({
+      id: 't1', session_id: SESSION, title: 'T', start_time: '2026-01-01T10:00:00.000Z',
+    });
+
+    // 两条 link 到 t1 的事件
+    storage.writeEvent(makeEvent({ event_id: uid('e1'), timestamp: '2026-01-01T10:10:00.000Z' }));
+    storage.writeEvent(makeEvent({ event_id: uid('e2'), timestamp: '2026-01-01T10:20:00.000Z' }));
+    // 一条未 link 的事件
+    storage.writeEvent(makeEvent({ event_id: uid('e-other'), timestamp: '2026-01-01T10:15:00.000Z' }));
+    storage.linkEventToTask('t1', uid('e1'));
+    storage.linkEventToTask('t1', uid('e2'));
+
+    storage.writeInjection({
+      id: 'i2', event_id: uid('e2'), session_id: SESSION,
+      timestamp: '2026-01-01T10:20:01.000Z',
+      source_handler: 'h', injection_type: 'systemMessage', content: 'b',
+    });
+    storage.writeInjection({
+      id: 'i1', event_id: uid('e1'), session_id: SESSION,
+      timestamp: '2026-01-01T10:10:01.000Z',
+      source_handler: 'h', injection_type: 'additionalContext', content: 'a',
+    });
+    // 未关联到 t1 的 injection
+    storage.writeInjection({
+      id: 'i-other', event_id: uid('e-other'), session_id: SESSION,
+      timestamp: '2026-01-01T10:15:01.000Z',
+      source_handler: 'h', injection_type: 'reason', content: 'x',
+    });
+
+    const injs = storage.queryInjectionsByTaskId('t1');
+    expect(injs.map(i => i.id)).toEqual(['i1', 'i2']);
+    expect(injs[0].event_id).toBe(uid('e1'));
+    expect(injs[1].injection_type).toBe('systemMessage');
+  });
+});
+
+describe('storage.querySkillInvocationsByTaskWindow', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h1-tasks-skill-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+    resetIdMap();
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('未知 taskId 返回 []', () => {
+    expect(storage.querySkillInvocationsByTaskWindow('nope')).toEqual([]);
+  });
+
+  it('时间窗：仅包含 [start_time, end_time] 内 且 session 匹配 的 invocations，按 timestamp ASC', () => {
+    seedSession(storage, SESSION, PROJECT);
+    // task: 2026-01-01T10:00:00Z .. 2026-01-01T11:00:00Z
+    const startMs = Date.UTC(2026, 0, 1, 10, 0, 0);
+    const endMs = Date.UTC(2026, 0, 1, 11, 0, 0);
+    storage.writeTask({
+      id: 't1', session_id: SESSION, title: 'T',
+      start_time: '2026-01-01T10:00:00.000Z',
+    });
+    storage.updateTask('t1', { end_time: '2026-01-01T11:00:00.000Z' });
+
+    // 之前（排除）
+    storage.writeSkillInvocation(makeInv({
+      id: 'inv-before', skill_id: 'tdd', timestamp: startMs - 1000,
+    }));
+    // 边界 start（包含）
+    storage.writeSkillInvocation(makeInv({
+      id: 'inv-start', skill_id: 'tdd', timestamp: startMs,
+    }));
+    // 中间（包含）
+    storage.writeSkillInvocation(makeInv({
+      id: 'inv-mid', skill_id: 'debug', timestamp: startMs + 30 * 60 * 1000,
+    }));
+    // 边界 end（包含；implementation 给 end 加了 +999ms 容差）
+    storage.writeSkillInvocation(makeInv({
+      id: 'inv-end', skill_id: 'tdd', timestamp: endMs,
+    }));
+    // 之后（排除）
+    storage.writeSkillInvocation(makeInv({
+      id: 'inv-after', skill_id: 'tdd', timestamp: endMs + 5000,
+    }));
+    // 不同 session（排除）
+    seedSession(storage, 'other-sess', PROJECT);
+    storage.writeSkillInvocation(makeInv({
+      id: 'inv-other-session', skill_id: 'tdd', timestamp: startMs + 60000, session_id: 'other-sess',
+    }));
+
+    const invs = storage.querySkillInvocationsByTaskWindow('t1');
+    expect(invs.map(i => i.id)).toEqual(['inv-start', 'inv-mid', 'inv-end']);
+  });
+
+  it('end_time IS NULL → 取 now_ms 参数作为上界', () => {
+    seedSession(storage, SESSION, PROJECT);
+    const startMs = Date.UTC(2026, 0, 1, 10, 0, 0);
+    storage.writeTask({
+      id: 't-open', session_id: SESSION, title: 'Active',
+      start_time: '2026-01-01T10:00:00.000Z',
+    });
+    // 不 updateTask end_time → 保持 NULL
+
+    storage.writeSkillInvocation(makeInv({
+      id: 'inv-in-window', skill_id: 'tdd', timestamp: startMs + 60000,
+    }));
+    storage.writeSkillInvocation(makeInv({
+      id: 'inv-past-now', skill_id: 'tdd', timestamp: startMs + 999_000,
+    }));
+
+    // now_ms = startMs + 120_000 → inv-past-now 落在窗外
+    const invs = storage.querySkillInvocationsByTaskWindow('t-open', {
+      now_ms: startMs + 120_000,
+    });
+    expect(invs.map(i => i.id)).toEqual(['inv-in-window']);
+
+    // now_ms = startMs + 999_999 → 两条都在
+    const invs2 = storage.querySkillInvocationsByTaskWindow('t-open', {
+      now_ms: startMs + 999_999,
+    });
+    expect(invs2.map(i => i.id)).toEqual(['inv-in-window', 'inv-past-now']);
+  });
+});