@vibescope/mcp-server 0.2.5 → 0.2.6

package/src/handlers/session.test.ts

@@ -1,875 +1,875 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import {
-	startWorkSession,
-	heartbeat,
-	endWorkSession,
-	getHelp,
-	getTokenUsage,
-	reportTokenUsage,
-} from './session.js';
-import { createMockContext } from './__test-utils__.js';
-import { mockApiClient } from './__test-setup__.js';
-
-// ============================================================================
-// heartbeat Tests
-// ============================================================================
-
-describe('heartbeat', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should record heartbeat successfully', async () => {
-		const ctx = createMockContext();
-		mockApiClient.heartbeat.mockResolvedValue({
-			ok: true,
-			data: { timestamp: '2026-01-14T10:00:00Z' },
-		});
-		mockApiClient.syncSession.mockResolvedValue({ ok: true });
-
-		const result = await heartbeat({}, ctx);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			session_id: 'session-123',
-		});
-		expect(result.result).toHaveProperty('timestamp');
-		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('session-123', expect.objectContaining({ current_worktree_path: undefined }));
-	});
-
-	it('should use provided session_id over current session', async () => {
-		const ctx = createMockContext();
-		mockApiClient.heartbeat.mockResolvedValue({
-			ok: true,
-			data: { timestamp: '2026-01-14T10:00:00Z' },
-		});
-		mockApiClient.syncSession.mockResolvedValue({ ok: true });
-
-		const result = await heartbeat({ session_id: 'other-session-456' }, ctx);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			session_id: 'other-session-456',
-		});
-		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('other-session-456', expect.objectContaining({ current_worktree_path: undefined }));
-	});
-
-	it('should pass worktree_path to API', async () => {
-		const ctx = createMockContext();
-		mockApiClient.heartbeat.mockResolvedValue({
-			ok: true,
-			data: { timestamp: '2026-01-14T10:00:00Z' },
-		});
-		mockApiClient.syncSession.mockResolvedValue({ ok: true });
-
-		await heartbeat({ current_worktree_path: '../project-task-abc123' }, ctx);
-
-		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('session-123', expect.objectContaining({ current_worktree_path: '../project-task-abc123' }));
-	});
-
-	it('should return error when no active session', async () => {
-		const ctx = createMockContext({ sessionId: null });
-
-		const result = await heartbeat({}, ctx);
-
-		expect(result.result).toMatchObject({
-			error: 'No active session. Call start_work_session first.',
-		});
-	});
-
-	it('should sync session with token usage', async () => {
-		const ctx = createMockContext({
-			tokenUsage: {
-				callCount: 10,
-				totalTokens: 5000,
-				byTool: {
-					get_task: { calls: 3, tokens: 1500 },
-					update_task: { calls: 4, tokens: 2000 },
-					complete_task: { calls: 3, tokens: 1500 },
-				},
-				byModel: {},
-				currentModel: null,
-			},
-		});
-		mockApiClient.heartbeat.mockResolvedValue({
-			ok: true,
-			data: { timestamp: '2026-01-14T10:00:00Z' },
-		});
-		mockApiClient.syncSession.mockResolvedValue({ ok: true });
-
-		await heartbeat({}, ctx);
-
-		expect(mockApiClient.syncSession).toHaveBeenCalledWith(
-			'session-123',
-			expect.objectContaining({
-				total_tokens: 5000,
-			})
-		);
-	});
-});
-
-// ============================================================================
-// getHelp Tests
-// ============================================================================
-
-describe('getHelp', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should return help content for valid topic', async () => {
-		const ctx = createMockContext();
-		mockApiClient.getHelpTopic.mockResolvedValue({
-			ok: true,
-			data: { slug: 'tasks', title: 'Task Workflow', content: '# Task Workflow\nTest content' },
-		});
-
-		const result = await getHelp({ topic: 'tasks' }, ctx);
-
-		expect(result.result).toHaveProperty('topic', 'tasks');
-		expect(result.result).toHaveProperty('content');
-	});
-
-	it('should return getting_started help', async () => {
-		const ctx = createMockContext();
-		mockApiClient.getHelpTopic.mockResolvedValue({
-			ok: true,
-			data: { slug: 'getting_started', title: 'Getting Started', content: '# Getting Started\nTest content' },
-		});
-
-		const result = await getHelp({ topic: 'getting_started' }, ctx);
-
-		expect(result.result).toHaveProperty('topic', 'getting_started');
-		expect(result.result).toHaveProperty('content');
-	});
-
-	it('should return error for unknown topic', async () => {
-		const ctx = createMockContext();
-		mockApiClient.getHelpTopic.mockResolvedValue({ ok: true, data: null });
-		mockApiClient.getHelpTopics.mockResolvedValue({
-			ok: true,
-			data: [{ slug: 'tasks', title: 'Tasks' }, { slug: 'getting_started', title: 'Getting Started' }],
-		});
-
-		const result = await getHelp({ topic: 'unknown_topic' }, ctx);
-
-		expect(result.result).toMatchObject({
-			error: 'Unknown topic: unknown_topic',
-		});
-		expect(result.result).toHaveProperty('available');
-	});
-
-	it('should list available topics for unknown topic', async () => {
-		const ctx = createMockContext();
-		mockApiClient.getHelpTopic.mockResolvedValue({ ok: true, data: null });
-		mockApiClient.getHelpTopics.mockResolvedValue({
-			ok: true,
-			data: [
-				{ slug: 'tasks', title: 'Tasks' },
-				{ slug: 'getting_started', title: 'Getting Started' },
-				{ slug: 'validation', title: 'Validation' },
-			],
-		});
-
-		const result = await getHelp({ topic: 'nonexistent' }, ctx);
-
-		const available = (result.result as { available: string[] }).available;
-		expect(Array.isArray(available)).toBe(true);
-		expect(available.length).toBeGreaterThan(0);
-	});
-});
-
-// ============================================================================
-// getTokenUsage Tests
-// ============================================================================
-
-describe('getTokenUsage', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should return token usage stats', async () => {
-		const ctx = createMockContext();
-
-		const result = await getTokenUsage({}, ctx);
-
-		expect(result.result).toHaveProperty('session');
-		expect(result.result).toHaveProperty('top_tools');
-		expect(result.result).toHaveProperty('note');
-	});
-
-	it('should return correct session stats', async () => {
-		const ctx = createMockContext({
-			tokenUsage: {
-				callCount: 10,
-				totalTokens: 5000,
-				byTool: {},
-				byModel: {},
-				currentModel: null,
-			},
-		});
-
-		const result = await getTokenUsage({}, ctx);
-		const session = (result.result as { session: { calls: number; tokens: number; avg_per_call: number } }).session;
-
-		expect(session.calls).toBe(10);
-		expect(session.tokens).toBe(5000);
-		expect(session.avg_per_call).toBe(500);
-	});
-
-	it('should return top tools sorted by tokens', async () => {
-		const ctx = createMockContext({
-			tokenUsage: {
-				callCount: 10,
-				totalTokens: 5000,
-				byTool: {
-					tool_a: { calls: 2, tokens: 1000 },
-					tool_b: { calls: 5, tokens: 3000 },
-					tool_c: { calls: 3, tokens: 1000 },
-				},
-				byModel: {},
-				currentModel: null,
-			},
-		});
-
-		const result = await getTokenUsage({}, ctx);
-		const topTools = (result.result as { top_tools: Array<{ tool: string; tokens: number }> }).top_tools;
-
-		// Should be sorted by tokens descending
-		expect(topTools[0].tool).toBe('tool_b');
-		expect(topTools[0].tokens).toBe(3000);
-	});
-
-	it('should handle zero calls gracefully', async () => {
-		const ctx = createMockContext({
-			tokenUsage: {
-				callCount: 0,
-				totalTokens: 0,
-				byTool: {},
-				byModel: {},
-				currentModel: null,
-			},
-		});
-
-		const result = await getTokenUsage({}, ctx);
-		const session = (result.result as { session: { calls: number; tokens: number; avg_per_call: number } }).session;
-
-		expect(session.calls).toBe(0);
-		expect(session.tokens).toBe(0);
-		expect(session.avg_per_call).toBe(0);
-	});
-
-	it('should limit top_tools to 5', async () => {
-		const ctx = createMockContext({
-			tokenUsage: {
-				callCount: 20,
-				totalTokens: 10000,
-				byTool: {
-					tool_1: { calls: 1, tokens: 100 },
-					tool_2: { calls: 2, tokens: 200 },
-					tool_3: { calls: 3, tokens: 300 },
-					tool_4: { calls: 4, tokens: 400 },
-					tool_5: { calls: 5, tokens: 500 },
-					tool_6: { calls: 6, tokens: 600 },
-					tool_7: { calls: 7, tokens: 700 },
-				},
-				byModel: {},
-				currentModel: null,
-			},
-		});
-
-		const result = await getTokenUsage({}, ctx);
-		const topTools = (result.result as { top_tools: Array<{ tool: string }> }).top_tools;
-
-		expect(topTools.length).toBe(5);
-	});
-});
-
-// ============================================================================
-// endWorkSession Tests
-// ============================================================================
-
-describe('endWorkSession', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should handle no active session gracefully', async () => {
-		const ctx = createMockContext({ sessionId: null });
-
-		const result = await endWorkSession({}, ctx);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			message: 'No active session to end',
-		});
-	});
-
-	it('should use provided session_id over current session', async () => {
-		const ctx = createMockContext();
-		mockApiClient.syncSession.mockResolvedValue({ ok: true });
-		mockApiClient.endSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_summary: {
-					agent_name: 'Wave',
-					tasks_completed_this_session: 3,
-					tasks_awaiting_validation: 1,
-					tasks_released: 0,
-				},
-			},
-		});
-
-		const result = await endWorkSession({ session_id: 'other-session-456' }, ctx);
-
-		expect(result.result).toHaveProperty('ended_session_id', 'other-session-456');
-		expect(mockApiClient.endSession).toHaveBeenCalledWith('other-session-456');
-	});
-
-	it('should call updateSession to clear current session', async () => {
-		const ctx = createMockContext();
-		mockApiClient.syncSession.mockResolvedValue({ ok: true });
-		mockApiClient.endSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_summary: {
-					agent_name: 'Wave',
-					tasks_completed_this_session: 0,
-					tasks_awaiting_validation: 0,
-					tasks_released: 0,
-				},
-			},
-		});
-
-		await endWorkSession({}, ctx);
-
-		expect(ctx.updateSession).toHaveBeenCalledWith({ currentSessionId: null });
-	});
-
-	it('should return session summary', async () => {
-		const ctx = createMockContext();
-		mockApiClient.syncSession.mockResolvedValue({ ok: true });
-		mockApiClient.endSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_summary: {
-					agent_name: 'Wave',
-					tasks_completed_this_session: 2,
-					tasks_awaiting_validation: 1,
-					tasks_released: 0,
-				},
-			},
-		});
-
-		const result = await endWorkSession({}, ctx);
-
-		expect(result.result).toHaveProperty('session_summary');
-		const summary = (result.result as { session_summary: { agent_name: string; token_usage: unknown } }).session_summary;
-		expect(summary.agent_name).toBe('Wave');
-		expect(summary).toHaveProperty('token_usage');
-	});
-
-	it('should not call updateSession when ending a different session', async () => {
-		const ctx = createMockContext({ sessionId: 'session-123' });
-		mockApiClient.syncSession.mockResolvedValue({ ok: true });
-		mockApiClient.endSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_summary: {
-					agent_name: 'Wave',
-					tasks_completed_this_session: 0,
-					tasks_awaiting_validation: 0,
-					tasks_released: 0,
-				},
-			},
-		});
-
-		await endWorkSession({ session_id: 'different-session' }, ctx);
-
-		// Should NOT clear the current session since we're ending a different one
-		expect(ctx.updateSession).not.toHaveBeenCalledWith({ currentSessionId: null });
-	});
-});
-
-// ============================================================================
-// startWorkSession Tests
-// ============================================================================
-
-describe('startWorkSession', () => {
-	beforeEach(() => {
-		vi.clearAllMocks();
-	});
-
-	it('should return error when project_id and git_url are both missing', async () => {
-		const ctx = createMockContext({ sessionId: null });
-
-		const result = await startWorkSession({}, ctx);
-
-		expect(result.result).toMatchObject({
-			error: 'Please provide project_id or git_url to start a session',
-		});
-	});
-
-	it('should return project_not_found when no project matches', async () => {
-		const ctx = createMockContext({ sessionId: null });
-		mockApiClient.startSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_started: false,
-				project_not_found: true,
-				message: 'No project found',
-				suggestion: {
-					action: 'create_project',
-					example: 'create_project(name: "repo")',
-					note: 'After creating the project, call start_work_session again.',
-				},
-			},
-		});
-
-		const result = await startWorkSession({ git_url: 'https://github.com/test/repo' }, ctx);
-
-		expect(result.result).toMatchObject({
-			session_started: false,
-			project_not_found: true,
-		});
-		expect(result.result).toHaveProperty('suggestion');
-	});
-
-	it('should reuse existing persona when session already has one', async () => {
-		const ctx = createMockContext({ sessionId: null });
-		mockApiClient.startSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_started: true,
-				session_id: 'existing-session-123',
-				persona: 'Pixel',
-				role: 'developer',
-				project: { id: 'project-123', name: 'Test Project' },
-			},
-		});
-
-		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
-
-		expect(result.result).toMatchObject({
-			session_started: true,
-			persona: 'Pixel',
-		});
-	});
-
-	it('should call updateSession with session ID and persona', async () => {
-		const ctx = createMockContext({ sessionId: null });
-		mockApiClient.startSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_started: true,
-				session_id: 'new-session-123',
-				persona: 'Wave',
-				role: 'developer',
-				project: { id: 'project-123', name: 'Test Project' },
-			},
-		});
-
-		await startWorkSession({ project_id: 'project-123' }, ctx);
-
-		expect(ctx.updateSession).toHaveBeenCalledWith(
-			expect.objectContaining({
-				currentSessionId: 'new-session-123',
-				currentPersona: 'Wave',
-			})
-		);
-	});
-
-	it('should return lite mode response by default', async () => {
-		const ctx = createMockContext({ sessionId: null });
-		mockApiClient.startSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_started: true,
-				session_id: 'new-session-123',
-				persona: 'Wave',
-				role: 'developer',
-				project: { id: 'project-123', name: 'Test Project' },
-				directive: 'ACTION_REQUIRED: Start working immediately.',
-			},
-		});
-
-		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
-
-		expect(result.result).toMatchObject({
-			session_started: true,
-		});
-		expect(result.result).toHaveProperty('project');
-		expect(result.result).toHaveProperty('directive');
-	});
-
-	it('should return error when API call fails', async () => {
-		const ctx = createMockContext({ sessionId: null });
-		mockApiClient.startSession.mockResolvedValue({
-			ok: false,
-			error: 'Internal server error',
-		});
-
-		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
-
-		expect(result.result).toMatchObject({
-			error: 'Internal server error',
-		});
-	});
-
-	it('should include next_task when available', async () => {
-		const ctx = createMockContext({ sessionId: null });
-		mockApiClient.startSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_started: true,
-				session_id: 'new-session-123',
-				persona: 'Wave',
-				role: 'developer',
-				project: { id: 'project-123', name: 'Test Project' },
-				next_task: { id: 'task-1', title: 'Fix bug', priority: 1 },
-			},
-		});
-
-		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
-
-		expect(result.result).toHaveProperty('next_task');
-		expect((result.result as { next_task: { id: string } }).next_task.id).toBe('task-1');
-	});
-
-	it('should include pending_requests when available in full mode', async () => {
-		const ctx = createMockContext({ sessionId: null });
-		const mockRequests = [
-			{ id: 'req-1', request_type: 'question', message: 'What is the status?', created_at: '2026-01-14T10:00:00Z' },
-			{ id: 'req-2', request_type: 'instruction', message: 'Please prioritize task X', created_at: '2026-01-14T11:00:00Z' },
-		];
-		mockApiClient.startSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_started: true,
-				session_id: 'new-session-123',
-				persona: 'Wave',
-				role: 'developer',
-				project: { id: 'project-123', name: 'Test Project' },
-				pending_requests: mockRequests,
-			},
-		});
-
-		const result = await startWorkSession({ project_id: 'project-123', mode: 'full' }, ctx);
-
-		expect(result.result).toHaveProperty('pending_requests');
-		expect(result.result).toHaveProperty('pending_requests_count', 2);
-		const pendingRequests = (result.result as { pending_requests: typeof mockRequests }).pending_requests;
-		expect(pendingRequests.length).toBe(2);
-		expect(pendingRequests[0].request_type).toBe('question');
-	});
-
-	it('should not include pending_requests when empty', async () => {
-		const ctx = createMockContext({ sessionId: null });
-		mockApiClient.startSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_started: true,
-				session_id: 'new-session-123',
-				persona: 'Wave',
-				role: 'developer',
-				project: { id: 'project-123', name: 'Test Project' },
-				pending_requests: [],
-			},
-		});
-
-		const result = await startWorkSession({ project_id: 'project-123', mode: 'full' }, ctx);
-
-		expect(result.result).not.toHaveProperty('pending_requests');
-		expect(result.result).not.toHaveProperty('pending_requests_count');
-	});
-
-	it('should surface awaiting_validation tasks when present', async () => {
-		const ctx = createMockContext({ sessionId: null });
-		const mockValidationTasks = [
-			{ id: 'task-1', title: 'Implement login' },
-			{ id: 'task-2', title: 'Add tests' },
-		];
-		mockApiClient.startSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_started: true,
-				session_id: 'new-session-123',
-				persona: 'Wave',
-				role: 'developer',
-				project: { id: 'project-123', name: 'Test Project' },
-				awaiting_validation: mockValidationTasks,
-				validation_count: 2,
-				validation_priority: 'VALIDATE FIRST: 2 task(s) need review before starting new work.',
-				directive: 'VALIDATE FIRST: 2 task(s) need review before starting new work. Call claim_validation(task_id) to start reviewing.',
-			},
-		});
-
-		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
-
-		expect(result.result).toHaveProperty('awaiting_validation');
-		expect(result.result).toHaveProperty('validation_count', 2);
-		expect(result.result).toHaveProperty('validation_priority');
-		const awaitingValidation = (result.result as { awaiting_validation: typeof mockValidationTasks }).awaiting_validation;
-		expect(awaitingValidation.length).toBe(2);
-		expect(awaitingValidation[0].id).toBe('task-1');
-	});
-
-	it('should include next_action when validation tasks are present', async () => {
-		const ctx = createMockContext({ sessionId: null });
-		mockApiClient.startSession.mockResolvedValue({
-			ok: true,
-			data: {
-				session_started: true,
-				session_id: 'new-session-123',
-				persona: 'Wave',
-				role: 'developer',
-				project: { id: 'project-123', name: 'Test Project' },
-				awaiting_validation: [{ id: 'task-abc', title: 'Fix bug' }],
-				validation_count: 1,
-				next_action: 'claim_validation(task_id: "task-abc")',
-			},
-		});
-
-		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
-
-		expect(result.result).toHaveProperty('next_action');
-		expect((result.result as { next_action: string }).next_action).toContain('task-abc');
-	});
-});
-
-// ============================================================================
-// reportTokenUsage Tests
-// ============================================================================
-
-describe('reportTokenUsage', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should report token usage successfully with session', async () => {
-		const ctx = createMockContext();
-		mockApiClient.reportTokenUsage.mockResolvedValue({
-			ok: true,
-			data: {
-				success: true,
-				reported: {
-					session_id: 'session-123',
-					model: 'sonnet',
-					input_tokens: 1000,
-					output_tokens: 500,
-					total_tokens: 1500,
-					estimated_cost_usd: 0.0105,
-				},
-				task_attributed: true,
-				task_id: 'task-123',
-			},
-		});
-
-		const result = await reportTokenUsage(
-			{ input_tokens: 1000, output_tokens: 500, model: 'sonnet' },
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			task_attributed: true,
-			task_id: 'task-123',
-		});
-		expect(result.result).toHaveProperty('reported');
-		expect(mockApiClient.reportTokenUsage).toHaveBeenCalledWith('session-123', {
-			input_tokens: 1000,
-			output_tokens: 500,
-			model: 'sonnet',
-		});
-	});
-
-	it('should default to sonnet model when not specified', async () => {
-		const ctx = createMockContext();
-		mockApiClient.reportTokenUsage.mockResolvedValue({
-			ok: true,
-			data: {
-				success: true,
-				reported: {
-					session_id: 'session-123',
-					model: 'sonnet',
-					input_tokens: 1000,
-					output_tokens: 500,
-					total_tokens: 1500,
-					estimated_cost_usd: 0.0105,
-				},
-				task_attributed: false,
-			},
-		});
-
-		await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
-
-		expect(mockApiClient.reportTokenUsage).toHaveBeenCalledWith('session-123', {
-			input_tokens: 1000,
-			output_tokens: 500,
-			model: 'sonnet',
-		});
-	});
-
-	it('should use session currentModel if available', async () => {
-		const ctx = createMockContext({
-			tokenUsage: {
-				callCount: 0,
-				totalTokens: 0,
-				byTool: {},
-				byModel: {},
-				currentModel: 'opus',
-			},
-		});
-		mockApiClient.reportTokenUsage.mockResolvedValue({
-			ok: true,
-			data: {
-				success: true,
-				reported: {
-					session_id: 'session-123',
-					model: 'opus',
-					input_tokens: 1000,
-					output_tokens: 500,
-					total_tokens: 1500,
-					estimated_cost_usd: 0.0525,
-				},
-				task_attributed: false,
-			},
-		});
-
-		await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
-
-		expect(mockApiClient.reportTokenUsage).toHaveBeenCalledWith('session-123', {
-			input_tokens: 1000,
-			output_tokens: 500,
-			model: 'opus',
-		});
-	});
-
-	it('should return error for negative token counts', async () => {
-		const ctx = createMockContext();
-
-		const result = await reportTokenUsage({ input_tokens: -100, output_tokens: 500 }, ctx);
-
-		expect(result.result).toMatchObject({
-			error: 'Token counts must be non-negative',
-		});
-		expect(mockApiClient.reportTokenUsage).not.toHaveBeenCalled();
-	});
-
-	it('should handle local-only reporting when no session', async () => {
-		const ctx = createMockContext({ sessionId: null });
-
-		const result = await reportTokenUsage(
-			{ input_tokens: 1000, output_tokens: 500, model: 'haiku' },
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: true,
-		});
-		expect(result.result).toHaveProperty('reported');
-		const reported = (result.result as { reported: { model: string } }).reported;
-		expect(reported.model).toBe('haiku');
-		expect(result.result).toHaveProperty('note');
-		expect(mockApiClient.reportTokenUsage).not.toHaveBeenCalled();
-	});
-
-	it('should update local token tracking', async () => {
-		const ctx = createMockContext({
-			tokenUsage: {
-				callCount: 5,
-				totalTokens: 2500,
-				byTool: {},
-				byModel: { sonnet: { input: 1000, output: 500 } },
-				currentModel: null,
-			},
-		});
-		mockApiClient.reportTokenUsage.mockResolvedValue({
-			ok: true,
-			data: {
-				success: true,
-				reported: {
-					session_id: 'session-123',
-					model: 'sonnet',
-					input_tokens: 1000,
-					output_tokens: 500,
-					total_tokens: 1500,
-					estimated_cost_usd: 0.0105,
-				},
-				task_attributed: false,
-			},
-		});
-
-		await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
-
-		expect(ctx.updateSession).toHaveBeenCalledWith(
-			expect.objectContaining({
-				tokenUsage: expect.objectContaining({
-					callCount: 6,
-					totalTokens: 4000,
-					byModel: { sonnet: { input: 2000, output: 1000 } },
-				}),
-			})
-		);
-	});
-
-	it('should handle backend failure gracefully', async () => {
-		const ctx = createMockContext();
-		mockApiClient.reportTokenUsage.mockResolvedValue({
-			ok: false,
-			error: 'Server error',
-		});
-
-		const result = await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
-
-		// Should still succeed with local calculation
-		expect(result.result).toMatchObject({
-			success: true,
-		});
-		expect(result.result).toHaveProperty('warning');
-	});
-
-	it('should indicate when task attribution succeeds', async () => {
-		const ctx = createMockContext();
-		mockApiClient.reportTokenUsage.mockResolvedValue({
-			ok: true,
-			data: {
-				success: true,
-				reported: {
-					session_id: 'session-123',
-					model: 'sonnet',
-					input_tokens: 1000,
-					output_tokens: 500,
-					total_tokens: 1500,
-					estimated_cost_usd: 0.0105,
-				},
-				task_attributed: true,
-				task_id: 'task-abc123',
-			},
-		});
-
-		const result = await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
-
-		expect(result.result).toMatchObject({
-			task_attributed: true,
-			task_id: 'task-abc123',
-		});
-		expect((result.result as { note: string }).note).toContain('attributed to current task');
-	});
-
-	it('should indicate when no task to attribute to', async () => {
-		const ctx = createMockContext();
-		mockApiClient.reportTokenUsage.mockResolvedValue({
-			ok: true,
-			data: {
-				success: true,
-				reported: {
-					session_id: 'session-123',
-					model: 'sonnet',
-					input_tokens: 1000,
-					output_tokens: 500,
-					total_tokens: 1500,
-					estimated_cost_usd: 0.0105,
-				},
-				task_attributed: false,
-			},
-		});
-
-		const result = await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
-
-		expect(result.result).toMatchObject({
-			task_attributed: false,
-		});
-		expect((result.result as { note: string }).note).toContain('No active task');
-	});
-});
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+	startWorkSession,
+	heartbeat,
+	endWorkSession,
+	getHelp,
+	getTokenUsage,
+	reportTokenUsage,
+} from './session.js';
+import { createMockContext } from './__test-utils__.js';
+import { mockApiClient } from './__test-setup__.js';
+
+// ============================================================================
+// heartbeat Tests
+// ============================================================================
+
+describe('heartbeat', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should record heartbeat successfully', async () => {
+		const ctx = createMockContext();
+		mockApiClient.heartbeat.mockResolvedValue({
+			ok: true,
+			data: { timestamp: '2026-01-14T10:00:00Z' },
+		});
+		mockApiClient.syncSession.mockResolvedValue({ ok: true });
+
+		const result = await heartbeat({}, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			session_id: 'session-123',
+		});
+		expect(result.result).toHaveProperty('timestamp');
+		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('session-123', expect.objectContaining({ current_worktree_path: undefined }));
+	});
+
+	it('should use provided session_id over current session', async () => {
+		const ctx = createMockContext();
+		mockApiClient.heartbeat.mockResolvedValue({
+			ok: true,
+			data: { timestamp: '2026-01-14T10:00:00Z' },
+		});
+		mockApiClient.syncSession.mockResolvedValue({ ok: true });
+
+		const result = await heartbeat({ session_id: 'other-session-456' }, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			session_id: 'other-session-456',
+		});
+		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('other-session-456', expect.objectContaining({ current_worktree_path: undefined }));
+	});
+
+	it('should pass worktree_path to API', async () => {
+		const ctx = createMockContext();
+		mockApiClient.heartbeat.mockResolvedValue({
+			ok: true,
+			data: { timestamp: '2026-01-14T10:00:00Z' },
+		});
+		mockApiClient.syncSession.mockResolvedValue({ ok: true });
+
+		await heartbeat({ current_worktree_path: '../project-task-abc123' }, ctx);
+
+		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('session-123', expect.objectContaining({ current_worktree_path: '../project-task-abc123' }));
+	});
+
+	it('should return error when no active session', async () => {
+		const ctx = createMockContext({ sessionId: null });
+
+		const result = await heartbeat({}, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'No active session. Call start_work_session first.',
+		});
+	});
+
+	it('should sync session with token usage', async () => {
+		const ctx = createMockContext({
+			tokenUsage: {
+				callCount: 10,
+				totalTokens: 5000,
+				byTool: {
+					get_task: { calls: 3, tokens: 1500 },
+					update_task: { calls: 4, tokens: 2000 },
+					complete_task: { calls: 3, tokens: 1500 },
+				},
+				byModel: {},
+				currentModel: null,
+			},
+		});
+		mockApiClient.heartbeat.mockResolvedValue({
+			ok: true,
+			data: { timestamp: '2026-01-14T10:00:00Z' },
+		});
+		mockApiClient.syncSession.mockResolvedValue({ ok: true });
+
+		await heartbeat({}, ctx);
+
+		expect(mockApiClient.syncSession).toHaveBeenCalledWith(
+			'session-123',
+			expect.objectContaining({
+				total_tokens: 5000,
+			})
+		);
+	});
+});
+
+// ============================================================================
+// getHelp Tests
+// ============================================================================
+
+describe('getHelp', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return help content for valid topic', async () => {
+		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({
+			ok: true,
+			data: { slug: 'tasks', title: 'Task Workflow', content: '# Task Workflow\nTest content' },
+		});
+
+		const result = await getHelp({ topic: 'tasks' }, ctx);
+
+		expect(result.result).toHaveProperty('topic', 'tasks');
+		expect(result.result).toHaveProperty('content');
+	});
+
+	it('should return getting_started help', async () => {
+		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({
+			ok: true,
+			data: { slug: 'getting_started', title: 'Getting Started', content: '# Getting Started\nTest content' },
+		});
+
+		const result = await getHelp({ topic: 'getting_started' }, ctx);
+
+		expect(result.result).toHaveProperty('topic', 'getting_started');
+		expect(result.result).toHaveProperty('content');
+	});
+
+	it('should return error for unknown topic', async () => {
+		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({ ok: true, data: null });
+		mockApiClient.getHelpTopics.mockResolvedValue({
+			ok: true,
+			data: [{ slug: 'tasks', title: 'Tasks' }, { slug: 'getting_started', title: 'Getting Started' }],
+		});
+
+		const result = await getHelp({ topic: 'unknown_topic' }, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'Unknown topic: unknown_topic',
+		});
+		expect(result.result).toHaveProperty('available');
+	});
+
+	it('should list available topics for unknown topic', async () => {
+		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({ ok: true, data: null });
+		mockApiClient.getHelpTopics.mockResolvedValue({
+			ok: true,
+			data: [
+				{ slug: 'tasks', title: 'Tasks' },
+				{ slug: 'getting_started', title: 'Getting Started' },
+				{ slug: 'validation', title: 'Validation' },
+			],
+		});
+
+		const result = await getHelp({ topic: 'nonexistent' }, ctx);
+
+		const available = (result.result as { available: string[] }).available;
+		expect(Array.isArray(available)).toBe(true);
+		expect(available.length).toBeGreaterThan(0);
+	});
+});
+
+// ============================================================================
+// getTokenUsage Tests
+// ============================================================================
+
+describe('getTokenUsage', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return token usage stats', async () => {
+		const ctx = createMockContext();
+
+		const result = await getTokenUsage({}, ctx);
+
+		expect(result.result).toHaveProperty('session');
+		expect(result.result).toHaveProperty('top_tools');
+		expect(result.result).toHaveProperty('note');
+	});
+
+	it('should return correct session stats', async () => {
+		const ctx = createMockContext({
+			tokenUsage: {
+				callCount: 10,
+				totalTokens: 5000,
+				byTool: {},
+				byModel: {},
+				currentModel: null,
+			},
+		});
+
+		const result = await getTokenUsage({}, ctx);
+		const session = (result.result as { session: { calls: number; tokens: number; avg_per_call: number } }).session;
+
+		expect(session.calls).toBe(10);
+		expect(session.tokens).toBe(5000);
+		expect(session.avg_per_call).toBe(500);
+	});
+
+	it('should return top tools sorted by tokens', async () => {
+		const ctx = createMockContext({
+			tokenUsage: {
+				callCount: 10,
+				totalTokens: 5000,
+				byTool: {
+					tool_a: { calls: 2, tokens: 1000 },
+					tool_b: { calls: 5, tokens: 3000 },
+					tool_c: { calls: 3, tokens: 1000 },
+				},
+				byModel: {},
+				currentModel: null,
+			},
+		});
+
+		const result = await getTokenUsage({}, ctx);
+		const topTools = (result.result as { top_tools: Array<{ tool: string; tokens: number }> }).top_tools;
+
+		// Should be sorted by tokens descending
+		expect(topTools[0].tool).toBe('tool_b');
+		expect(topTools[0].tokens).toBe(3000);
+	});
+
+	it('should handle zero calls gracefully', async () => {
+		const ctx = createMockContext({
+			tokenUsage: {
+				callCount: 0,
+				totalTokens: 0,
+				byTool: {},
+				byModel: {},
+				currentModel: null,
+			},
+		});
+
+		const result = await getTokenUsage({}, ctx);
+		const session = (result.result as { session: { calls: number; tokens: number; avg_per_call: number } }).session;
+
+		expect(session.calls).toBe(0);
+		expect(session.tokens).toBe(0);
+		expect(session.avg_per_call).toBe(0);
+	});
+
+	it('should limit top_tools to 5', async () => {
+		const ctx = createMockContext({
+			tokenUsage: {
+				callCount: 20,
+				totalTokens: 10000,
+				byTool: {
+					tool_1: { calls: 1, tokens: 100 },
+					tool_2: { calls: 2, tokens: 200 },
+					tool_3: { calls: 3, tokens: 300 },
+					tool_4: { calls: 4, tokens: 400 },
+					tool_5: { calls: 5, tokens: 500 },
+					tool_6: { calls: 6, tokens: 600 },
+					tool_7: { calls: 7, tokens: 700 },
+				},
+				byModel: {},
+				currentModel: null,
+			},
+		});
+
+		const result = await getTokenUsage({}, ctx);
+		const topTools = (result.result as { top_tools: Array<{ tool: string }> }).top_tools;
+
+		expect(topTools.length).toBe(5);
+	});
+});
+
+// ============================================================================
+// endWorkSession Tests
+// ============================================================================
+
+describe('endWorkSession', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should handle no active session gracefully', async () => {
+		const ctx = createMockContext({ sessionId: null });
+
+		const result = await endWorkSession({}, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			message: 'No active session to end',
+		});
+	});
+
+	it('should use provided session_id over current session', async () => {
+		const ctx = createMockContext();
+		mockApiClient.syncSession.mockResolvedValue({ ok: true });
+		mockApiClient.endSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_summary: {
+					agent_name: 'Wave',
+					tasks_completed_this_session: 3,
+					tasks_awaiting_validation: 1,
+					tasks_released: 0,
+				},
+			},
+		});
+
+		const result = await endWorkSession({ session_id: 'other-session-456' }, ctx);
+
+		expect(result.result).toHaveProperty('ended_session_id', 'other-session-456');
+		expect(mockApiClient.endSession).toHaveBeenCalledWith('other-session-456');
+	});
+
+	it('should call updateSession to clear current session', async () => {
+		const ctx = createMockContext();
+		mockApiClient.syncSession.mockResolvedValue({ ok: true });
+		mockApiClient.endSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_summary: {
+					agent_name: 'Wave',
+					tasks_completed_this_session: 0,
+					tasks_awaiting_validation: 0,
+					tasks_released: 0,
+				},
+			},
+		});
+
+		await endWorkSession({}, ctx);
+
+		expect(ctx.updateSession).toHaveBeenCalledWith({ currentSessionId: null });
+	});
+
+	it('should return session summary', async () => {
+		const ctx = createMockContext();
+		mockApiClient.syncSession.mockResolvedValue({ ok: true });
+		mockApiClient.endSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_summary: {
+					agent_name: 'Wave',
+					tasks_completed_this_session: 2,
+					tasks_awaiting_validation: 1,
+					tasks_released: 0,
+				},
+			},
+		});
+
+		const result = await endWorkSession({}, ctx);
+
+		expect(result.result).toHaveProperty('session_summary');
+		const summary = (result.result as { session_summary: { agent_name: string; token_usage: unknown } }).session_summary;
+		expect(summary.agent_name).toBe('Wave');
+		expect(summary).toHaveProperty('token_usage');
+	});
+
+	it('should not call updateSession when ending a different session', async () => {
+		const ctx = createMockContext({ sessionId: 'session-123' });
+		mockApiClient.syncSession.mockResolvedValue({ ok: true });
+		mockApiClient.endSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_summary: {
+					agent_name: 'Wave',
+					tasks_completed_this_session: 0,
+					tasks_awaiting_validation: 0,
+					tasks_released: 0,
+				},
+			},
+		});
+
+		await endWorkSession({ session_id: 'different-session' }, ctx);
+
+		// Should NOT clear the current session since we're ending a different one
+		expect(ctx.updateSession).not.toHaveBeenCalledWith({ currentSessionId: null });
+	});
+});
+
+// ============================================================================
+// startWorkSession Tests
+// ============================================================================
+
+describe('startWorkSession', () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it('should return error when project_id and git_url are both missing', async () => {
+		const ctx = createMockContext({ sessionId: null });
+
+		const result = await startWorkSession({}, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'Please provide project_id or git_url to start a session',
+		});
+	});
+
+	it('should return project_not_found when no project matches', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: false,
+				project_not_found: true,
+				message: 'No project found',
+				suggestion: {
+					action: 'create_project',
+					example: 'create_project(name: "repo")',
+					note: 'After creating the project, call start_work_session again.',
+				},
+			},
+		});
+
+		const result = await startWorkSession({ git_url: 'https://github.com/test/repo' }, ctx);
+
+		expect(result.result).toMatchObject({
+			session_started: false,
+			project_not_found: true,
+		});
+		expect(result.result).toHaveProperty('suggestion');
+	});
+
+	it('should reuse existing persona when session already has one', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'existing-session-123',
+				persona: 'Pixel',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
+
+		expect(result.result).toMatchObject({
+			session_started: true,
+			persona: 'Pixel',
+		});
+	});
+
+	it('should call updateSession with session ID and persona', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+			},
+		});
+
+		await startWorkSession({ project_id: 'project-123' }, ctx);
+
+		expect(ctx.updateSession).toHaveBeenCalledWith(
+			expect.objectContaining({
+				currentSessionId: 'new-session-123',
+				currentPersona: 'Wave',
+			})
+		);
+	});
+
+	it('should return lite mode response by default', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+				directive: 'ACTION_REQUIRED: Start working immediately.',
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
+
+		expect(result.result).toMatchObject({
+			session_started: true,
+		});
+		expect(result.result).toHaveProperty('project');
+		expect(result.result).toHaveProperty('directive');
+	});
+
+	it('should return error when API call fails', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		mockApiClient.startSession.mockResolvedValue({
+			ok: false,
+			error: 'Internal server error',
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'Internal server error',
+		});
+	});
+
+	it('should include next_task when available', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+				next_task: { id: 'task-1', title: 'Fix bug', priority: 1 },
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
+
+		expect(result.result).toHaveProperty('next_task');
+		expect((result.result as { next_task: { id: string } }).next_task.id).toBe('task-1');
+	});
+
+	it('should include pending_requests when available in full mode', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		const mockRequests = [
+			{ id: 'req-1', request_type: 'question', message: 'What is the status?', created_at: '2026-01-14T10:00:00Z' },
+			{ id: 'req-2', request_type: 'instruction', message: 'Please prioritize task X', created_at: '2026-01-14T11:00:00Z' },
+		];
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+				pending_requests: mockRequests,
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123', mode: 'full' }, ctx);
+
+		expect(result.result).toHaveProperty('pending_requests');
+		expect(result.result).toHaveProperty('pending_requests_count', 2);
+		const pendingRequests = (result.result as { pending_requests: typeof mockRequests }).pending_requests;
+		expect(pendingRequests.length).toBe(2);
+		expect(pendingRequests[0].request_type).toBe('question');
+	});
+
+	it('should not include pending_requests when empty', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+				pending_requests: [],
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123', mode: 'full' }, ctx);
+
+		expect(result.result).not.toHaveProperty('pending_requests');
+		expect(result.result).not.toHaveProperty('pending_requests_count');
+	});
+
+	it('should surface awaiting_validation tasks when present', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		const mockValidationTasks = [
+			{ id: 'task-1', title: 'Implement login' },
+			{ id: 'task-2', title: 'Add tests' },
+		];
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+				awaiting_validation: mockValidationTasks,
+				validation_count: 2,
+				validation_priority: 'VALIDATE FIRST: 2 task(s) need review before starting new work.',
+				directive: 'VALIDATE FIRST: 2 task(s) need review before starting new work. Call claim_validation(task_id) to start reviewing.',
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
+
+		expect(result.result).toHaveProperty('awaiting_validation');
+		expect(result.result).toHaveProperty('validation_count', 2);
+		expect(result.result).toHaveProperty('validation_priority');
+		const awaitingValidation = (result.result as { awaiting_validation: typeof mockValidationTasks }).awaiting_validation;
+		expect(awaitingValidation.length).toBe(2);
+		expect(awaitingValidation[0].id).toBe('task-1');
+	});
+
+	it('should include next_action when validation tasks are present', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+				awaiting_validation: [{ id: 'task-abc', title: 'Fix bug' }],
+				validation_count: 1,
+				next_action: 'claim_validation(task_id: "task-abc")',
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123' }, ctx);
+
+		expect(result.result).toHaveProperty('next_action');
+		expect((result.result as { next_action: string }).next_action).toContain('task-abc');
+	});
+});
+
+// ============================================================================
+// reportTokenUsage Tests
+// ============================================================================
+
+describe('reportTokenUsage', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should report token usage successfully with session', async () => {
+		const ctx = createMockContext();
+		mockApiClient.reportTokenUsage.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				reported: {
+					session_id: 'session-123',
+					model: 'sonnet',
+					input_tokens: 1000,
+					output_tokens: 500,
+					total_tokens: 1500,
+					estimated_cost_usd: 0.0105,
+				},
+				task_attributed: true,
+				task_id: 'task-123',
+			},
+		});
+
+		const result = await reportTokenUsage(
+			{ input_tokens: 1000, output_tokens: 500, model: 'sonnet' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			task_attributed: true,
+			task_id: 'task-123',
+		});
+		expect(result.result).toHaveProperty('reported');
+		expect(mockApiClient.reportTokenUsage).toHaveBeenCalledWith('session-123', {
+			input_tokens: 1000,
+			output_tokens: 500,
+			model: 'sonnet',
+		});
+	});
+
+	it('should default to sonnet model when not specified', async () => {
+		const ctx = createMockContext();
+		mockApiClient.reportTokenUsage.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				reported: {
+					session_id: 'session-123',
+					model: 'sonnet',
+					input_tokens: 1000,
+					output_tokens: 500,
+					total_tokens: 1500,
+					estimated_cost_usd: 0.0105,
+				},
+				task_attributed: false,
+			},
+		});
+
+		await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
+
+		expect(mockApiClient.reportTokenUsage).toHaveBeenCalledWith('session-123', {
+			input_tokens: 1000,
+			output_tokens: 500,
+			model: 'sonnet',
+		});
+	});
+
+	it('should use session currentModel if available', async () => {
+		const ctx = createMockContext({
+			tokenUsage: {
+				callCount: 0,
+				totalTokens: 0,
+				byTool: {},
+				byModel: {},
+				currentModel: 'opus',
+			},
+		});
+		mockApiClient.reportTokenUsage.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				reported: {
+					session_id: 'session-123',
+					model: 'opus',
+					input_tokens: 1000,
+					output_tokens: 500,
+					total_tokens: 1500,
+					estimated_cost_usd: 0.0525,
+				},
+				task_attributed: false,
+			},
+		});
+
+		await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
+
+		expect(mockApiClient.reportTokenUsage).toHaveBeenCalledWith('session-123', {
+			input_tokens: 1000,
+			output_tokens: 500,
+			model: 'opus',
+		});
+	});
+
+	it('should return error for negative token counts', async () => {
+		const ctx = createMockContext();
+
+		const result = await reportTokenUsage({ input_tokens: -100, output_tokens: 500 }, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'Token counts must be non-negative',
+		});
+		expect(mockApiClient.reportTokenUsage).not.toHaveBeenCalled();
+	});
+
+	it('should handle local-only reporting when no session', async () => {
+		const ctx = createMockContext({ sessionId: null });
+
+		const result = await reportTokenUsage(
+			{ input_tokens: 1000, output_tokens: 500, model: 'haiku' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+		});
+		expect(result.result).toHaveProperty('reported');
+		const reported = (result.result as { reported: { model: string } }).reported;
+		expect(reported.model).toBe('haiku');
+		expect(result.result).toHaveProperty('note');
+		expect(mockApiClient.reportTokenUsage).not.toHaveBeenCalled();
+	});
+
+	it('should update local token tracking', async () => {
+		const ctx = createMockContext({
+			tokenUsage: {
+				callCount: 5,
+				totalTokens: 2500,
+				byTool: {},
+				byModel: { sonnet: { input: 1000, output: 500 } },
+				currentModel: null,
+			},
+		});
+		mockApiClient.reportTokenUsage.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				reported: {
+					session_id: 'session-123',
+					model: 'sonnet',
+					input_tokens: 1000,
+					output_tokens: 500,
+					total_tokens: 1500,
+					estimated_cost_usd: 0.0105,
+				},
+				task_attributed: false,
+			},
+		});
+
+		await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
+
+		expect(ctx.updateSession).toHaveBeenCalledWith(
+			expect.objectContaining({
+				tokenUsage: expect.objectContaining({
+					callCount: 6,
+					totalTokens: 4000,
+					byModel: { sonnet: { input: 2000, output: 1000 } },
+				}),
+			})
+		);
+	});
+
+	it('should handle backend failure gracefully', async () => {
+		const ctx = createMockContext();
+		mockApiClient.reportTokenUsage.mockResolvedValue({
+			ok: false,
+			error: 'Server error',
+		});
+
+		const result = await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
+
+		// Should still succeed with local calculation
+		expect(result.result).toMatchObject({
+			success: true,
+		});
+		expect(result.result).toHaveProperty('warning');
+	});
+
+	it('should indicate when task attribution succeeds', async () => {
+		const ctx = createMockContext();
+		mockApiClient.reportTokenUsage.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				reported: {
+					session_id: 'session-123',
+					model: 'sonnet',
+					input_tokens: 1000,
+					output_tokens: 500,
+					total_tokens: 1500,
+					estimated_cost_usd: 0.0105,
+				},
+				task_attributed: true,
+				task_id: 'task-abc123',
+			},
+		});
+
+		const result = await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
+
+		expect(result.result).toMatchObject({
+			task_attributed: true,
+			task_id: 'task-abc123',
+		});
+		expect((result.result as { note: string }).note).toContain('attributed to current task');
+	});
+
+	it('should indicate when no task to attribute to', async () => {
+		const ctx = createMockContext();
+		mockApiClient.reportTokenUsage.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				reported: {
+					session_id: 'session-123',
+					model: 'sonnet',
+					input_tokens: 1000,
+					output_tokens: 500,
+					total_tokens: 1500,
+					estimated_cost_usd: 0.0105,
+				},
+				task_attributed: false,
+			},
+		});
+
+		const result = await reportTokenUsage({ input_tokens: 1000, output_tokens: 500 }, ctx);
+
+		expect(result.result).toMatchObject({
+			task_attributed: false,
+		});
+		expect((result.result as { note: string }).note).toContain('No active task');
+	});
+});