@winspan/claude-forge 8.50.6 → 8.51.1

package/tests/unit/web/routes-rules.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Unit tests for /api/rules/hit-rate.
+ *
+ * H1 baseline — establishes contract before migrating rules.ts to SQL aggregates.
+ * Response shape must remain identical after the route refactor.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import express, { type Application } from 'express';
+import request from 'supertest';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+import { registerRulesRoutes } from '../../../src/web/routes/rules.js';
+import type { SkillRegistry } from '../../../src/skills/registry.js';
+
+const SESSION = 'sess-rules';
+const PROJECT = '/tmp/proj-rules';
+
+/** Minimal SkillRegistry stub for the never-triggered list. */
+function makeRegistry(ids: string[]): SkillRegistry {
+  return {
+    getAll: () => ids.map(id => ({ id })),
+  } as unknown as SkillRegistry;
+}
+
+function makeInv(opts: {
+  id: string;
+  skill_id: string;
+  success: 0 | 1;
+  timestamp: number;
+}) {
+  return {
+    id: opts.id,
+    route_request_id: null,
+    session_id: SESSION,
+    agent_id: null,
+    skill_id: opts.skill_id,
+    invocation_type: 'dynamic' as const,
+    reason: null,
+    workflow: null, phase: null, feature_slug: null, artifact_path: null,
+    depth: 0,
+    success: opts.success,
+    error: opts.success === 0 ? 'boom' : null,
+    timestamp: opts.timestamp,
+  };
+}
+
+describe('GET /api/rules/hit-rate', () => {
+  let app: Application;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    storage = new SQLiteStorage(':memory:');
+    app = express();
+    app.use(express.json());
+  });
+
+  afterEach(() => {
+    storage.close();
+  });
+
+  it('空数据：summary 全 0，skills/agents 为空，neverTriggered 列出 registry 全部', async () => {
+    registerRulesRoutes(app, { storage, skillRegistry: makeRegistry(['tdd', 'debug']) });
+
+    const res = await request(app).get('/api/rules/hit-rate').query({ days: 7 });
+    expect(res.status).toBe(200);
+    expect(res.body.period.days).toBe(7);
+    expect(typeof res.body.period.since).toBe('string');
+    expect(res.body.summary).toEqual({
+      totalPrompts: 0,
+      agentDelegations: 0,
+      agentRate: '0%',
+      skillInvocations: 0,
+      skillRate: '0%',
+    });
+    expect(res.body.skills).toEqual([]);
+    expect(res.body.agents).toEqual([]);
+    expect(res.body.neverTriggered.sort()).toEqual(['debug', 'tdd']);
+  });
+
+  it('混合数据：totalPrompts、agentDelegations(obeyed=1)、agents 排序、skills 频次、neverTriggered 排除已触发', async () => {
+    registerRulesRoutes(app, { storage, skillRegistry: makeRegistry(['tdd', 'debug', 'unused-skill']) });
+
+    const now = Date.now();
+    // 5 个 routing events，3 个 obeyed (2 researcher + 1 coder)
+    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,
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p3', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'coder', obeyed: 1,
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p4', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'tester', obeyed: 0,
+    });
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: now,
+      prompt: 'p5', intent_json: '{}',
+      routed_to_type: 'skill', routed_to_name: 'tdd', obeyed: null,
+    });
+
+    // 3 个 skill invocations
+    storage.writeSkillInvocation(makeInv({ id: 's1', skill_id: 'tdd', success: 1, timestamp: now }));
+    storage.writeSkillInvocation(makeInv({ id: 's2', skill_id: 'tdd', success: 0, timestamp: now }));
+    storage.writeSkillInvocation(makeInv({ id: 's3', skill_id: 'debug', success: 1, timestamp: now }));
+
+    const res = await request(app).get('/api/rules/hit-rate').query({ days: 7 });
+    expect(res.status).toBe(200);
+
+    // Summary
+    expect(res.body.summary.totalPrompts).toBe(5);
+    expect(res.body.summary.agentDelegations).toBe(3);
+    expect(res.body.summary.agentRate).toBe('60.0%');
+    expect(res.body.summary.skillInvocations).toBe(3);
+    expect(res.body.summary.skillRate).toBe('60.0%');
+
+    // Skills 排序 by total desc
+    expect(res.body.skills).toHaveLength(2);
+    expect(res.body.skills[0]).toEqual({
+      skill_id: 'tdd', total: 2, success: 1, failed: 1, rate: '40.0%',
+    });
+    expect(res.body.skills[1]).toEqual({
+      skill_id: 'debug', total: 1, success: 1, failed: 0, rate: '20.0%',
+    });
+
+    // Agents 排序 by count desc，仅 obeyed=1
+    expect(res.body.agents).toHaveLength(2);
+    expect(res.body.agents[0]).toEqual({ agent: 'researcher', count: 2, rate: '40.0%' });
+    expect(res.body.agents[1]).toEqual({ agent: 'coder', count: 1, rate: '20.0%' });
+
+    // neverTriggered = registry - skills with invocations
+    expect(res.body.neverTriggered).toEqual(['unused-skill']);
+  });
+
+  it('days 默认 7、可被 query 覆盖', async () => {
+    registerRulesRoutes(app, { storage, skillRegistry: makeRegistry([]) });
+
+    const res1 = await request(app).get('/api/rules/hit-rate');
+    expect(res1.body.period.days).toBe(7);
+
+    const res2 = await request(app).get('/api/rules/hit-rate').query({ days: 30 });
+    expect(res2.body.period.days).toBe(30);
+  });
+
+  it('days 窗口过滤：旧 routing/skill 数据不计入', async () => {
+    registerRulesRoutes(app, { storage, skillRegistry: makeRegistry(['tdd']) });
+
+    const old = Date.now() - 30 * 24 * 3600 * 1000;
+    storage.writeRoutingEvent({
+      session_id: SESSION, project_path: PROJECT, ts: old,
+      prompt: 'old', intent_json: '{}',
+      routed_to_type: 'agent', routed_to_name: 'researcher', obeyed: 1,
+    });
+    storage.writeSkillInvocation(makeInv({ id: 's-old', skill_id: 'tdd', success: 1, timestamp: old }));
+
+    const res = await request(app).get('/api/rules/hit-rate').query({ days: 7 });
+    expect(res.body.summary.totalPrompts).toBe(0);
+    expect(res.body.summary.skillInvocations).toBe(0);
+    expect(res.body.skills).toEqual([]);
+    expect(res.body.agents).toEqual([]);
+    // 旧数据没触发 → tdd 仍在 neverTriggered
+    expect(res.body.neverTriggered).toEqual(['tdd']);
+  });
+
+  it('skillRegistry 缺失：neverTriggered 为空', async () => {
+    // 不传 skillRegistry
+    registerRulesRoutes(app, { storage });
+
+    const res = await request(app).get('/api/rules/hit-rate');
+    expect(res.status).toBe(200);
+    expect(res.body.neverTriggered).toEqual([]);
+  });
+});

package/tests/unit/web/routes-tasks.test.ts

@@ -128,6 +128,40 @@ describe('Tasks Routes', () => {
       expect(task).toHaveProperty('status');
       expect(task).toHaveProperty('event_count');
     });
+
+    // ── safety-net:task-title-summary-real ─────────────────────────────────
+    // These tests assert the first_prompt field must be present in API items.
+    // They will be RED until the backend SQL subquery is added (Phase 2 fix).
+
+    it('safety-net: every item has first_prompt key (may be null)', async () => {
+      seedSession(storage, SESSION, PROJECT_A);
+      storage.writeTask({ id: 'fp-check', session_id: SESSION, title: '<task-notification>', start_time: ts() });
+      const res = await request(app).get('/api/tasks');
+      expect(res.status).toBe(200);
+      expect(res.body.items).toHaveLength(1);
+      // first_prompt key must exist in the response (value may be null when no event)
+      expect(res.body.items[0]).toHaveProperty('first_prompt');
+    });
+
+    it('safety-net: first_prompt contains user_prompt text when event exists', async () => {
+      seedSession(storage, SESSION, PROJECT_A);
+      const taskStart = ts();
+      storage.writeTask({ id: 'fp-event', session_id: SESSION, title: '<task-notification>', start_time: taskStart });
+      // Write a UserPromptSubmit event for this session after task start
+      storage.writeEvent({
+        event_id: EV_PROMPT,
+        session_id: SESSION, project_path: PROJECT_A,
+        timestamp: ts(100),
+        hook_type: 'UserPromptSubmit',
+        user_prompt: '<task-notification>\n<summary>Fix the login bug</summary>\n</task-notification>',
+      });
+      const res = await request(app).get('/api/tasks');
+      expect(res.status).toBe(200);
+      expect(res.body.items).toHaveLength(1);
+      const fp = res.body.items[0].first_prompt as string | null;
+      expect(fp).not.toBeNull();
+      expect(fp).toContain('Fix the login bug');
+    });
   });
 
   // ─────────────────────────────────────────────────────────────────────────

package/tests/unit/web/task-title-contract.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Safety-net + TDD contract tests for normalizeTaskTitle()
+ *
+ * harness/safety-net:task-title-summary
+ *
+ * Root cause: Tasks stored with title = raw <task-notification> XML (sub-agent
+ * completion callbacks). The frontend renders the literal XML string, making
+ * task titles completely unreadable.
+ *
+ * This file locks the contract for the pure helper `normalizeTaskTitle`:
+ *   - written BEFORE the implementation (TDD red phase)
+ *   - no React / DOM dependency — pure function only
+ *   - covers passthrough, fallback, XML extraction, edge cases
+ */
+
+import { describe, it, expect } from 'vitest';
+
+// ── Import under test (will fail until task-title.ts is created) ─────────────
+// Adjust path to match web/src/utils/task-title.ts resolved from project root.
+// Because vitest.config.ts only includes tests/unit/**, we use a relative path
+// from this file up to web/src/utils/.
+import { normalizeTaskTitle } from '../../../web/src/utils/task-title';
+
+// ── Fixtures ──────────────────────────────────────────────────────────────────
+
+const TASK_NOTIFICATION_FULL = `<task-notification>
+<task-id>aefe161c3350644df</task-id>
+<tool-use-id>toolu_01XxXxXxXx</tool-use-id>
+<output-file>/private/tmp/something/xxx.output</output-file>
+<status>completed</status>
+<summary>Agent "Hotfix Tasks 返回丢筛选" completed</summary>
+<result>Task finished successfully</result>
+<usage><total_tokens>57809</total_tokens><tool_uses>37</tool_uses><duration_ms>289676</duration_ms></usage>
+</task-notification>`;
+
+const TASK_NOTIFICATION_NO_SUMMARY = `<task-notification>
+<task-id>deadbeef</task-id>
+<status>completed</status>
+</task-notification>`;
+
+const TASK_NOTIFICATION_EMOJI_SUMMARY = `<task-notification>
+<summary>Agent "修复 Bug 🐛" completed — see /tmp/report.md</summary>
+</task-notification>`;
+
+const TASK_NOTIFICATION_QUOTES_SUMMARY = `<task-notification>
+<summary>Agent "it's a 'test' with "quotes"" done</summary>
+</task-notification>`;
+
+const LONG_SUMMARY_NOTIFICATION = `<task-notification>
+<summary>Agent completed a very long task description that exceeds the maximum allowed display length of eighty characters in the UI widget</summary>
+</task-notification>`;
+
+const INLINE_CLOSING_TAG = `<task-notification>
+<summary>First match</summary><summary>Should not appear</summary>
+</task-notification>`;
+
+// ── Tests ──────────────────────────────────────────────────────────────────────
+
+describe('normalizeTaskTitle — contract (harness/safety-net:task-title-summary)', () => {
+
+  // ── 1. Passthrough ─────────────────────────────────────────────────────────
+  describe('passthrough for regular titles', () => {
+    it('returns a normal title unchanged', () => {
+      expect(normalizeTaskTitle('批准')).toBe('批准');
+    });
+
+    it('returns a regular English title unchanged', () => {
+      expect(normalizeTaskTitle('Fix login crash')).toBe('Fix login crash');
+    });
+
+    it('trims leading and trailing whitespace', () => {
+      expect(normalizeTaskTitle('  hello world  ')).toBe('hello world');
+    });
+  });
+
+  // ── 2. Fallback for empty / null / undefined ────────────────────────────────
+  describe('fallback for empty / null / undefined', () => {
+    it('returns fallback for empty string', () => {
+      expect(normalizeTaskTitle('')).toBe('(无标题)');
+    });
+
+    it('returns fallback for whitespace-only string', () => {
+      expect(normalizeTaskTitle('   ')).toBe('(无标题)');
+    });
+
+    it('returns fallback for null', () => {
+      expect(normalizeTaskTitle(null)).toBe('(无标题)');
+    });
+
+    it('returns fallback for undefined', () => {
+      expect(normalizeTaskTitle(undefined)).toBe('(无标题)');
+    });
+  });
+
+  // ── 3. task-notification XML extraction ────────────────────────────────────
+  describe('<task-notification> XML extraction', () => {
+    it('extracts <summary> content from a full notification blob', () => {
+      expect(normalizeTaskTitle(TASK_NOTIFICATION_FULL)).toBe(
+        'Agent "Hotfix Tasks 返回丢筛选" completed'
+      );
+    });
+
+    it('returns "(子任务回调)" when <summary> tag is absent', () => {
+      expect(normalizeTaskTitle(TASK_NOTIFICATION_NO_SUMMARY)).toBe('(子任务回调)');
+    });
+
+    it('returns "(子任务回调)" for bare <task-notification> tag alone', () => {
+      expect(normalizeTaskTitle('<task-notification>')).toBe('(子任务回调)');
+    });
+
+    it('preserves emoji and Chinese characters in summary', () => {
+      expect(normalizeTaskTitle(TASK_NOTIFICATION_EMOJI_SUMMARY)).toBe(
+        'Agent "修复 Bug 🐛" completed — see /tmp/report.md'
+      );
+    });
+
+    it('preserves single quotes and double quotes inside summary', () => {
+      expect(normalizeTaskTitle(TASK_NOTIFICATION_QUOTES_SUMMARY)).toBe(
+        `Agent "it's a 'test' with "quotes"" done`
+      );
+    });
+
+    it('takes the first <summary> match when multiple are present (defensive)', () => {
+      expect(normalizeTaskTitle(INLINE_CLOSING_TAG)).toBe('First match');
+    });
+  });
+
+  // ── 4. Truncation ──────────────────────────────────────────────────────────
+  describe('truncation at 80 characters', () => {
+    it('truncates a summary longer than 80 chars and appends ellipsis', () => {
+      const result = normalizeTaskTitle(LONG_SUMMARY_NOTIFICATION);
+      expect(result.endsWith('…')).toBe(true);
+      // The visible text portion is exactly 80 chars (before the ellipsis)
+      expect(result.slice(0, -1).length).toBe(80);
+    });
+
+    it('does not truncate a summary of exactly 80 chars', () => {
+      const exactly80 = 'A'.repeat(80);
+      const notification = `<task-notification><summary>${exactly80}</summary></task-notification>`;
+      const result = normalizeTaskTitle(notification);
+      expect(result).toBe(exactly80);
+      expect(result.endsWith('…')).toBe(false);
+    });
+
+    it('truncates a plain title longer than 80 chars', () => {
+      const long = 'B'.repeat(90);
+      const result = normalizeTaskTitle(long);
+      expect(result.endsWith('…')).toBe(true);
+      expect(result.slice(0, -1).length).toBe(80);
+    });
+
+    it('does not truncate a plain title of exactly 80 chars', () => {
+      const exactly80 = 'C'.repeat(80);
+      expect(normalizeTaskTitle(exactly80)).toBe(exactly80);
+    });
+  });
+
+  // ── 5. Summary whitespace trimming ────────────────────────────────────────
+  describe('summary whitespace trimming', () => {
+    it('trims whitespace inside <summary> tags', () => {
+      const withPad = `<task-notification><summary>  trimmed  </summary></task-notification>`;
+      expect(normalizeTaskTitle(withPad)).toBe('trimmed');
+    });
+
+    it('falls back to "(子任务回调)" when summary is whitespace-only', () => {
+      const whitespaceSummary = `<task-notification><summary>   </summary></task-notification>`;
+      expect(normalizeTaskTitle(whitespaceSummary)).toBe('(子任务回调)');
+    });
+  });
+
+  // ── 6. safety-net:task-title-summary-real — dual-param with firstPrompt ──
+  // These tests will be RED until normalizeTaskTitle is updated to accept a
+  // second parameter (firstPrompt). Phase 2 fix turns them GREEN.
+  describe('dual-param: title=<task-notification> (19 chars) + firstPrompt', () => {
+    const BARE_NOTIFICATION = '<task-notification>';
+
+    it('extracts summary from firstPrompt when title is bare 19-char token', () => {
+      const firstPrompt = '<task-notification>\n<summary>Fix the login bug</summary>\n</task-notification>';
+      expect(normalizeTaskTitle(BARE_NOTIFICATION, firstPrompt)).toBe('Fix the login bug');
+    });
+
+    it('shows head of firstPrompt when it has no summary tag', () => {
+      const firstPrompt = 'Please investigate the database performance issue and report findings.';
+      const result = normalizeTaskTitle(BARE_NOTIFICATION, firstPrompt);
+      expect(result).toMatch(/^\(子任务回调\) — /);
+      expect(result).toContain('Please investigate');
+    });
+
+    it('falls back to "(子任务回调)" when firstPrompt is null', () => {
+      expect(normalizeTaskTitle(BARE_NOTIFICATION, null)).toBe('(子任务回调)');
+    });
+
+    it('falls back to "(子任务回调)" when firstPrompt is undefined', () => {
+      expect(normalizeTaskTitle(BARE_NOTIFICATION, undefined)).toBe('(子任务回调)');
+    });
+
+    it('plain title ignores firstPrompt entirely (no contamination)', () => {
+      const fp = '<task-notification><summary>Should be ignored</summary></task-notification>';
+      expect(normalizeTaskTitle('Fix login crash', fp)).toBe('Fix login crash');
+    });
+
+    it('truncates a long summary from firstPrompt at 80 chars with ellipsis', () => {
+      const longSummary = 'A'.repeat(90);
+      const fp = `<task-notification><summary>${longSummary}</summary></task-notification>`;
+      const result = normalizeTaskTitle(BARE_NOTIFICATION, fp);
+      expect(result.endsWith('…')).toBe(true);
+      expect(result.slice(0, -1).length).toBe(80);
+    });
+  });
+});

package/tests/unit/web/tasks-component-contract.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Safety-net: Tasks component API contract test
+ *
+ * harness/safety-net:tasks-page-white-screen
+ *
+ * Root cause: Tasks.tsx called GET /api/tasks and treated the response as
+ * Task[] (bare array), but the API returns { items: Task[], total, has_more }.
+ * Iterating a plain object as an array caused a runtime error → white screen.
+ *
+ * This test locks the correct API contract so a regression is immediately
+ * visible. It also validates the TypeScript-level interface that Tasks.tsx
+ * must use when consuming the /api/tasks endpoint.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+// ── Types mirroring the API contract ────────────────────────────────────────
+
+interface TaskRecord {
+  id: string;
+  session_id: string;
+  title: string;
+  status: 'active' | 'completed' | 'abandoned';
+  start_time: string;
+  end_time?: string;
+  event_count: number;
+  project_path?: string;
+}
+
+interface TaskPage {
+  items: TaskRecord[];
+  total: number;
+  has_more: boolean;
+}
+
+// ── Simulated fetch helpers (pure functions, no DOM needed) ──────────────────
+
+/**
+ * BROKEN: simulates what the old Tasks.tsx code did — treated the entire
+ * response body as a Task[] and tried to .filter() on it.
+ * This is the defect we are safety-netting.
+ */
+function consumeTasksResponseBROKEN(responseBody: unknown): TaskRecord[] {
+  // Old code: `return res.json()` then `tasks.filter(...)` — treats body as array
+  return responseBody as TaskRecord[];
+}
+
+/**
+ * CORRECT: extracts items from the paginated wrapper that /api/tasks returns.
+ */
+function consumeTasksResponseCORRECT(responseBody: TaskPage): TaskRecord[] {
+  return responseBody.items;
+}
+
+// ── Test fixtures ─────────────────────────────────────────────────────────────
+
+const TASK_RECORD: TaskRecord = {
+  id: 'abc-123',
+  session_id: 'sess-001',
+  title: 'Test task',
+  status: 'active',
+  start_time: '2026-05-18T00:00:00.000Z',
+  event_count: 5,
+  project_path: '/home/user/project',
+};
+
+const API_RESPONSE: TaskPage = {
+  items: [TASK_RECORD],
+  total: 1,
+  has_more: false,
+};
+
+// ── Contract: /api/tasks must return { items, total, has_more } ───────────────
+
+describe('Tasks API contract (safety-net: tasks-page-white-screen)', () => {
+  describe('API response shape', () => {
+    it('response body is an object with items array, not a bare array', () => {
+      expect(Array.isArray(API_RESPONSE)).toBe(false);
+      expect(typeof API_RESPONSE).toBe('object');
+    });
+
+    it('response.items is the array of task records', () => {
+      expect(Array.isArray(API_RESPONSE.items)).toBe(true);
+      expect(API_RESPONSE.items).toHaveLength(1);
+    });
+
+    it('response.total is a number >= 0', () => {
+      expect(typeof API_RESPONSE.total).toBe('number');
+      expect(API_RESPONSE.total).toBeGreaterThanOrEqual(0);
+    });
+
+    it('response.has_more is a boolean', () => {
+      expect(typeof API_RESPONSE.has_more).toBe('boolean');
+    });
+
+    it('each item has required fields: id, session_id, title, status, start_time, event_count', () => {
+      const item = API_RESPONSE.items[0];
+      expect(item).toHaveProperty('id');
+      expect(item).toHaveProperty('session_id');
+      expect(item).toHaveProperty('title');
+      expect(item).toHaveProperty('status');
+      expect(item).toHaveProperty('start_time');
+      expect(item).toHaveProperty('event_count');
+    });
+  });
+
+  describe('[CHAR] broken consumer — documents the white-screen defect', () => {
+    it('treating response body as Task[] gives an object not an array (this was the bug)', () => {
+      // consumeTasksResponseBROKEN returns the whole { items, total, has_more } object
+      // as if it were Task[]. Calling array methods on it would throw.
+      const result = consumeTasksResponseBROKEN(API_RESPONSE);
+      // The broken code returns an object where an array is expected
+      expect(Array.isArray(result)).toBe(false);
+      // Accessing .filter would succeed (it's on Object.prototype? No — it would
+      // return undefined because plain objects don't have .filter)
+      expect(typeof (result as unknown as { filter?: unknown }).filter).toBe('undefined');
+    });
+
+    it('[CHAR] calling .map on the broken result throws or returns undefined', () => {
+      const result = consumeTasksResponseBROKEN(API_RESPONSE) as unknown;
+      // When Tasks.tsx does tasks.filter(...), tasks is { items, total, has_more }
+      // which has no .filter → calling it throws TypeError
+      expect(() => {
+        (result as TaskRecord[]).filter(() => true);
+      }).toThrow(TypeError);
+    });
+  });
+
+  describe('correct consumer — contract the fix must satisfy', () => {
+    it('correct consumer returns an actual array', () => {
+      const result = consumeTasksResponseCORRECT(API_RESPONSE);
+      expect(Array.isArray(result)).toBe(true);
+    });
+
+    it('correct consumer exposes task fields for rendering', () => {
+      const result = consumeTasksResponseCORRECT(API_RESPONSE);
+      expect(result[0].id).toBe('abc-123');
+      expect(result[0].title).toBe('Test task');
+      expect(result[0].status).toBe('active');
+    });
+
+    it('total is preserved from response for pagination display', () => {
+      expect(API_RESPONSE.total).toBe(1);
+    });
+
+    it('has_more drives next-page button state', () => {
+      expect(API_RESPONSE.has_more).toBe(false);
+    });
+
+    it('empty page shape is valid', () => {
+      const empty: TaskPage = { items: [], total: 0, has_more: false };
+      const result = consumeTasksResponseCORRECT(empty);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('pagination parameters', () => {
+    it('default limit is 50', () => {
+      // The API uses Zod default(50) — component should default to 50 items/page
+      const defaultLimit = 50;
+      expect(defaultLimit).toBeGreaterThan(0);
+    });
+
+    it('supported page sizes are 20, 50, 100', () => {
+      const PAGE_SIZES = [20, 50, 100];
+      PAGE_SIZES.forEach(size => {
+        expect(size).toBeGreaterThan(0);
+        expect(size).toBeLessThanOrEqual(200); // API max is 200
+      });
+    });
+
+    it('offset is computed as (page - 1) * pageSize', () => {
+      const page = 3;
+      const pageSize = 50;
+      const offset = (page - 1) * pageSize;
+      expect(offset).toBe(100);
+    });
+  });
+});

package/vitest.config.ts

@@ -5,7 +5,7 @@ export default defineConfig({
   test: {
     globals: true,
     environment: 'node',
-    include: ['tests/unit/**/*.test.ts'],
+    include: ['tests/unit/**/*.test.ts', 'tests/integration/**/*.test.ts'],
     exclude: ['tests-old/**', 'src-old/**', 'node_modules/**'],
     coverage: {
       provider: 'v8',