agentic-orchestrator 0.1.25 → 0.1.26

package/apps/control-plane/test/dashboard-api.integration.spec.ts

@@ -17,6 +17,38 @@ const readFeatureLogMock = vi.hoisted(() =>
     total: 1,
   })),
 );
+const readFeatureCostMock = vi.hoisted(() =>
+  vi.fn(async () => ({
+    feature_id: 'feature_checkout',
+    tokens_used: 120,
+    estimated_cost_usd: 1.23,
+    recorded_at: '2026-03-05T00:00:00Z',
+  })),
+);
+const readFeatureQaTestIndexMock = vi.hoisted(() =>
+  vi.fn(async () => ({
+    feature_id: 'feature_checkout',
+    version: 1,
+    items: [
+      {
+        path: 'src/a.ts',
+        status: 'passed',
+        required_tests: ['a.spec.ts'],
+      },
+    ],
+  })),
+);
+const readFeatureReviewBriefMock = vi.hoisted(() =>
+  vi.fn(async () => ({
+    intent_summary: 'Intent',
+    scope_summary: 'Scope',
+    contract_risk_summary: 'Risk',
+    gate_matrix: { fast: 'pass' },
+    unresolved_questions: [],
+    evidence_refs: [],
+    generated_at: '2026-03-05T00:00:00Z',
+  })),
+);
 const getAopRootMock = vi.hoisted(() => vi.fn(() => process.cwd()));
 const approveFeatureReviewMock = vi.hoisted(() =>
   vi.fn(async () => ({ ok: true, data: { merged: true } })),
@@ -33,6 +65,9 @@ const sendFeatureMessageMock = vi.hoisted(() =>
 const retryFeatureMock = vi.hoisted(() =>
   vi.fn(async () => ({ ok: true, data: { retry_mode: 'full' } })),
 );
+const callOrchestratorToolMock = vi.hoisted(() =>
+  vi.fn(async () => ({ ok: true, data: {} as Record<string, unknown> })),
+);
 const execFileMock = vi.hoisted(() => vi.fn());
 
 vi.mock('../../../packages/web-dashboard/src/lib/aop-client.js', () => ({
@@ -40,6 +75,9 @@ vi.mock('../../../packages/web-dashboard/src/lib/aop-client.js', () => ({
   readDashboardStatus: readDashboardStatusMock,
   readFeatureState: readFeatureStateMock,
   readFeatureLog: readFeatureLogMock,
+  readFeatureCost: readFeatureCostMock,
+  readFeatureQaTestIndex: readFeatureQaTestIndexMock,
+  readFeatureReviewBrief: readFeatureReviewBriefMock,
   getAopRoot: getAopRootMock,
 }));
 
@@ -49,6 +87,7 @@ vi.mock('../../../packages/web-dashboard/src/lib/orchestrator-tools.js', () => (
   requestFeatureChanges: requestFeatureChangesMock,
   sendFeatureMessage: sendFeatureMessageMock,
   retryFeature: retryFeatureMock,
+  callOrchestratorTool: callOrchestratorToolMock,
 }));
 
 vi.mock('node:child_process', () => ({
@@ -67,9 +106,17 @@ vi.mock('node:child_process', () => ({
 
 import { POST as actionsPost } from '../../../packages/web-dashboard/src/app/api/actions/route.js';
 import { POST as checkoutPost } from '../../../packages/web-dashboard/src/app/api/features/[id]/checkout/route.js';
+import { GET as collisionsGet } from '../../../packages/web-dashboard/src/app/api/collisions/route.js';
+import { GET as costGet } from '../../../packages/web-dashboard/src/app/api/features/[id]/cost/route.js';
 import { GET as logGet } from '../../../packages/web-dashboard/src/app/api/features/[id]/log/route.js';
+import { GET as reviewBriefGet } from '../../../packages/web-dashboard/src/app/api/features/[id]/review-brief/route.js';
 import { GET as statusGet } from '../../../packages/web-dashboard/src/app/api/status/route.js';
+import { GET as testIndexGet } from '../../../packages/web-dashboard/src/app/api/features/[id]/test-index/route.js';
 import { GET as projectsGet } from '../../../packages/web-dashboard/src/app/api/projects/route.js';
+import {
+  GET as runGet,
+  POST as runPost,
+} from '../../../packages/web-dashboard/src/app/api/run/route.js';
 
 describe('dashboard api integration', () => {
   let repoRoot: string;
@@ -84,12 +131,16 @@ describe('dashboard api integration', () => {
     readDashboardStatusMock.mockReset();
     readFeatureStateMock.mockReset();
     readFeatureLogMock.mockReset();
+    readFeatureCostMock.mockReset();
+    readFeatureQaTestIndexMock.mockReset();
+    readFeatureReviewBriefMock.mockReset();
     getAopRootMock.mockReset();
     approveFeatureReviewMock.mockReset();
     denyFeatureReviewMock.mockReset();
     requestFeatureChangesMock.mockReset();
     sendFeatureMessageMock.mockReset();
     retryFeatureMock.mockReset();
+    callOrchestratorToolMock.mockReset();
     execFileMock.mockReset();
 
     resolveProjectRootMock.mockResolvedValue(repoRoot);
@@ -112,6 +163,31 @@ describe('dashboard api integration', () => {
       entries: [{ timestamp: '2026-03-05T00:00:00Z', message: 'log message', type: 'log' }],
       total: 1,
     });
+    readFeatureCostMock.mockResolvedValue({
+      feature_id: 'feature_checkout',
+      tokens_used: 120,
+      estimated_cost_usd: 1.23,
+      recorded_at: '2026-03-05T00:00:00Z',
+    });
+    readFeatureQaTestIndexMock.mockResolvedValue({
+      feature_id: 'feature_checkout',
+      version: 1,
+      items: [{ path: 'src/a.ts', status: 'passed', required_tests: ['a.spec.ts'] }],
+    });
+    readFeatureReviewBriefMock.mockResolvedValue({
+      intent_summary: 'Intent',
+      scope_summary: 'Scope',
+      contract_risk_summary: 'Risk',
+      gate_matrix: { fast: 'pass' },
+      unresolved_questions: [],
+      evidence_refs: [],
+      generated_at: '2026-03-05T00:00:00Z',
+    });
+    callOrchestratorToolMock.mockResolvedValue({
+      ok: true,
+      data: { feature_id: 'feature_checkout' } as Record<string, unknown>,
+    });
+    delete process.env.AOP_DASHBOARD_QUICK_LAUNCH;
   });
 
   afterEach(async () => {
@@ -299,14 +375,113 @@ describe('dashboard api integration', () => {
     resolveProjectRootMock.mockResolvedValue(path.join(repoRoot, 'project-beta'));
 
     const response = await statusGet(new Request('http://localhost/api/status?project=beta'));
-    const body = (await response.json()) as { ok: boolean; data: { features: unknown[] } };
+    const body = (await response.json()) as {
+      ok: boolean;
+      data: { features: unknown[] };
+      meta: { source: string };
+    };
 
     expect(response.status).toBe(200);
     expect(body.ok).toBe(true);
+    expect(body.meta.source).toBe('derived');
     expect(resolveProjectRootMock).toHaveBeenCalledWith('beta');
     expect(readDashboardStatusMock).toHaveBeenCalledWith(path.join(repoRoot, 'project-beta'));
   });
 
+  it('GIVEN_feature_cost_route_WHEN_artifact_present_THEN_returns_uniform_envelope', async () => {
+    readFeatureStateMock.mockResolvedValue({
+      id: 'feature_checkout',
+      feature_id: 'feature_checkout',
+      status: 'ready_to_merge',
+      phase: 'ready_to_merge',
+    });
+    const response = await costGet(
+      new Request('http://localhost/api/features/feature_checkout/cost'),
+      {
+        params: Promise.resolve({ id: 'feature_checkout' }),
+      },
+    );
+    const body = (await response.json()) as {
+      ok: boolean;
+      data?: { estimated_cost_usd: number };
+      meta?: { source: string };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.data?.estimated_cost_usd).toBe(1.23);
+    expect(body.meta?.source).toBe('artifact');
+  });
+
+  it('GIVEN_feature_cost_route_WHEN_artifact_missing_THEN_returns_artifact_missing', async () => {
+    readFeatureStateMock.mockResolvedValue({
+      id: 'feature_checkout',
+      feature_id: 'feature_checkout',
+      status: 'ready_to_merge',
+      phase: 'ready_to_merge',
+    });
+    readFeatureCostMock.mockResolvedValue(null);
+
+    const response = await costGet(
+      new Request('http://localhost/api/features/feature_checkout/cost'),
+      {
+        params: Promise.resolve({ id: 'feature_checkout' }),
+      },
+    );
+    const body = (await response.json()) as { ok: boolean; error: { code: string } };
+
+    expect(response.status).toBe(404);
+    expect(body.ok).toBe(false);
+    expect(body.error.code).toBe('artifact_missing');
+  });
+
+  it('GIVEN_feature_test_index_route_WHEN_requested_THEN_returns_qa_index', async () => {
+    readFeatureStateMock.mockResolvedValue({
+      id: 'feature_checkout',
+      feature_id: 'feature_checkout',
+      status: 'qa',
+      phase: 'qa',
+    });
+    const response = await testIndexGet(
+      new Request('http://localhost/api/features/feature_checkout/test-index'),
+      { params: Promise.resolve({ id: 'feature_checkout' }) },
+    );
+    const body = (await response.json()) as {
+      ok: boolean;
+      data?: { feature_id: string; items: unknown[] };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.data?.feature_id).toBe('feature_checkout');
+    expect(body.data?.items).toHaveLength(1);
+  });
+
+  it('GIVEN_feature_review_brief_route_WHEN_requested_THEN_returns_review_brief', async () => {
+    readFeatureStateMock.mockResolvedValue({
+      id: 'feature_checkout',
+      feature_id: 'feature_checkout',
+      status: 'ready_to_merge',
+      phase: 'ready_to_merge',
+    });
+    const response = await reviewBriefGet(
+      new Request('http://localhost/api/features/feature_checkout/review-brief'),
+      {
+        params: Promise.resolve({ id: 'feature_checkout' }),
+      },
+    );
+    const body = (await response.json()) as {
+      ok: boolean;
+      data?: { intent_summary: string };
+      meta?: { source: string };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.data?.intent_summary).toBe('Intent');
+    expect(body.meta?.source).toBe('artifact');
+  });
+
   it('GIVEN_multi_project_config_WHEN_projects_endpoint_called_THEN_returns_switchable_projects', async () => {
     const projectAlpha = path.join(repoRoot, 'project-alpha');
     const projectBeta = path.join(repoRoot, 'project-beta');
@@ -352,6 +527,140 @@ describe('dashboard api integration', () => {
     expect(body.data.projects.map((project) => project.path)).toEqual([projectAlpha, projectBeta]);
   });
 
+  it('GIVEN_quick_launch_disabled_policy_WHEN_run_get_called_THEN_returns_unavailable_state', async () => {
+    const policyPath = path.join(repoRoot, 'config', 'agentic', 'orchestrator');
+    await fs.mkdir(policyPath, { recursive: true });
+    await fs.writeFile(
+      path.join(policyPath, 'policy.yaml'),
+      ['dashboard:', '  enabled: true', '  port: 3000', '  quick_launch: false'].join('\n'),
+      'utf8',
+    );
+
+    const response = await runGet(new Request('http://localhost/api/run?project=alpha'));
+    const body = (await response.json()) as {
+      ok: boolean;
+      data?: { available: boolean; enabled: boolean; authorized: boolean; reason: string | null };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.data).toEqual({
+      available: false,
+      enabled: false,
+      authorized: false,
+      reason:
+        'Quick launch is disabled by policy. Enable dashboard.quick_launch or AOP_DASHBOARD_QUICK_LAUNCH=true.',
+    });
+  });
+
+  it('GIVEN_quick_launch_enabled_WHEN_run_post_called_THEN_calls_feature_init_tool', async () => {
+    const policyPath = path.join(repoRoot, 'config', 'agentic', 'orchestrator');
+    await fs.mkdir(policyPath, { recursive: true });
+    await fs.writeFile(
+      path.join(policyPath, 'policy.yaml'),
+      ['dashboard:', '  enabled: true', '  port: 3000', '  quick_launch: true'].join('\n'),
+      'utf8',
+    );
+
+    const response = await runPost(
+      new Request('http://localhost/api/run?project=alpha', {
+        method: 'POST',
+        body: JSON.stringify({
+          feature_id: 'feature_checkout',
+          goal: 'Implement checkout flow updates',
+          confirm_launch: true,
+        }),
+      }),
+    );
+    const body = (await response.json()) as {
+      ok: boolean;
+      data?: { feature_id: string; status: string };
+    };
+
+    expect(response.status).toBe(201);
+    expect(body.ok).toBe(true);
+    expect(body.data?.feature_id).toBe('feature_checkout');
+    expect(callOrchestratorToolMock).toHaveBeenCalledWith(
+      'feature.init',
+      {
+        feature_id: 'feature_checkout',
+        goal: 'Implement checkout flow updates',
+      },
+      {
+        mutating: true,
+        featureId: 'feature_checkout',
+        repoRoot,
+      },
+    );
+  });
+
+  it('GIVEN_collision_count_with_50_or_fewer_features_WHEN_collisions_route_called_THEN_returns_matrix_mode', async () => {
+    callOrchestratorToolMock.mockResolvedValue({
+      ok: true,
+      data: {
+        collisions: [
+          {
+            feature_id: 'feature_a',
+            with_feature_id: 'feature_b',
+            collisions: [{ type: 'same_file' }],
+            fingerprint: 'ab',
+          },
+          {
+            feature_id: 'feature_b',
+            with_feature_id: 'feature_c',
+            collisions: [{ type: 'same_file' }, { type: 'same_hunk' }],
+            fingerprint: 'bc',
+          },
+        ],
+      },
+    });
+
+    const response = await collisionsGet(
+      new Request('http://localhost/api/collisions?project=alpha'),
+    );
+    const body = (await response.json()) as {
+      ok: boolean;
+      data?: { mode: string; matrix?: unknown[] };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.data?.mode).toBe('matrix');
+    expect(body.data?.matrix).toHaveLength(2);
+  });
+
+  it('GIVEN_collision_count_with_more_than_50_features_WHEN_collisions_route_called_THEN_returns_ranked_pairs_mode', async () => {
+    const collisions = Array.from({ length: 51 }, (_, index) => ({
+      feature_id: `feature_${index}`,
+      with_feature_id: `feature_${index + 1}`,
+      collisions: Array.from({ length: (index % 3) + 1 }, () => ({ type: 'same_file' })),
+      fingerprint: `${index}`,
+    }));
+    callOrchestratorToolMock.mockResolvedValue({
+      ok: true,
+      data: { collisions },
+    });
+
+    const response = await collisionsGet(
+      new Request('http://localhost/api/collisions?project=alpha'),
+    );
+    const body = (await response.json()) as {
+      ok: boolean;
+      data?: {
+        mode: string;
+        ranked_pairs?: Array<{ feature_id: string; with_feature_id: string; count: number }>;
+      };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.data?.mode).toBe('ranked_pairs');
+    expect(body.data?.ranked_pairs?.length).toBe(51);
+    expect(body.data?.ranked_pairs?.[0].count).toBeGreaterThanOrEqual(
+      body.data?.ranked_pairs?.[1].count ?? 0,
+    );
+  });
+
   it('GIVEN_feature_history_route_WHEN_requested_THEN_returns_log_entries', async () => {
     const response = await logGet(
       new Request('http://localhost/api/features/feature_checkout/log?project=alpha'),

package/apps/control-plane/test/dashboard-client.spec.ts

@@ -2,7 +2,13 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
-import { readDashboardStatus, readFeatureLog } from '@/lib/aop-client.js';
+import {
+  readDashboardStatus,
+  readFeatureCost,
+  readFeatureLog,
+  readFeatureQaTestIndex,
+  readFeatureReviewBrief,
+} from '@/lib/aop-client.js';
 
 async function writeState(repoRoot: string, featureId: string, frontMatter: string): Promise<void> {
   const featureDir = path.join(repoRoot, '.aop', 'features', featureId);
@@ -224,4 +230,133 @@ describe('dashboard aop client mapping', () => {
     expect(log.entries.some((entry) => entry.type === 'evidence')).toBe(true);
     expect(log.entries.some((entry) => entry.type === 'state_change')).toBe(true);
   });
+
+  it('GIVEN_index_with_runtime_locks_and_dep_blocked_WHEN_readDashboardStatus_THEN_maps_operator_payload_fields', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features', 'feature_lock'), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'index.json'),
+      JSON.stringify({
+        active: ['feature_lock'],
+        blocked: [],
+        merged: [],
+        blocked_queue: [],
+        dep_blocked: [{ feature_id: 'feature_waiting', depends_on_unresolved: ['dep_a'] }],
+        lock_leases: {
+          'repo:write': {
+            holder: 'feature_lock',
+            lease_id: 'lease-1',
+            expires_at: '2099-01-01T00:00:00Z',
+          },
+        },
+        runtime_sessions: {
+          run_id: 'run:1',
+          orchestrator_session_id: 'session-1',
+          provider: 'codex',
+          model: 'gpt-5',
+          provider_config_ref_hash: 'hash',
+          owner_instance_id: 'instance-1',
+          lease_id: 'lease',
+          started_at: '2026-03-05T00:00:00Z',
+          last_heartbeat_at: '2026-03-05T00:01:00Z',
+          lease_expires_at: '2026-03-05T00:02:00Z',
+          orchestrator_epoch: 1,
+        },
+      }),
+      'utf8',
+    );
+    await writeState(
+      repoRoot,
+      'feature_lock',
+      ['feature_id: feature_lock', 'status: building', 'last_updated: 2026-03-05T00:00:00Z'].join(
+        '\n',
+      ),
+    );
+
+    const payload = await readDashboardStatus(repoRoot);
+    expect(payload.runtime?.run_id).toBe('run:1');
+    expect(payload.lock_map).toEqual([
+      {
+        resource: 'repo:write',
+        holder: 'feature_lock',
+        expires_at: '2099-01-01T00:00:00Z',
+        is_stale: false,
+      },
+    ]);
+    expect(payload.dep_blocked).toEqual([
+      { feature_id: 'feature_waiting', depends_on_unresolved: ['dep_a'] },
+    ]);
+    expect(payload.metrics?.merge_histogram_14d).toHaveLength(14);
+  });
+
+  it('GIVEN_feature_artifacts_WHEN_readers_called_THEN_return_normalized_cost_qa_and_review_brief', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    const featureRoot = path.join(repoRoot, '.aop', 'features', 'feature_artifacts');
+    await fs.mkdir(featureRoot, { recursive: true });
+    await fs.writeFile(
+      path.join(featureRoot, 'cost.json'),
+      JSON.stringify({
+        feature_id: 'feature_artifacts',
+        tokens_used: 50,
+        estimated_cost_usd: 0.52,
+        last_updated: '2026-03-05T00:00:00Z',
+      }),
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(featureRoot, 'qa_test_index.json'),
+      JSON.stringify({
+        feature_id: 'feature_artifacts',
+        version: 3,
+        source_diff_ref: 'abc',
+        items: [
+          {
+            path: 'src/a.ts',
+            hunks: [],
+            required_tests: ['a.spec.ts'],
+            status: 'passed',
+            last_run_at: '2026-03-05T00:00:00Z',
+          },
+        ],
+      }),
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(featureRoot, 'review_brief.json'),
+      JSON.stringify({
+        intent_summary: 'Intent',
+        scope_summary: 'Scope',
+        contract_risk_summary: 'Risk',
+        gate_matrix: { fast: 'pass' },
+        unresolved_questions: ['Q1'],
+        evidence_refs: ['evidence/qa.txt'],
+        generated_at: '2026-03-05T00:00:00Z',
+      }),
+      'utf8',
+    );
+
+    await expect(readFeatureCost('feature_artifacts', repoRoot)).resolves.toMatchObject({
+      feature_id: 'feature_artifacts',
+      tokens_used: 50,
+      estimated_cost_usd: 0.52,
+    });
+    await expect(readFeatureQaTestIndex('feature_artifacts', repoRoot)).resolves.toMatchObject({
+      feature_id: 'feature_artifacts',
+      version: 3,
+      items: [
+        {
+          path: 'src/a.ts',
+          status: 'passed',
+          required_tests: ['a.spec.ts'],
+        },
+      ],
+    });
+    await expect(readFeatureReviewBrief('feature_artifacts', repoRoot)).resolves.toMatchObject({
+      intent_summary: 'Intent',
+      scope_summary: 'Scope',
+      contract_risk_summary: 'Risk',
+    });
+  });
 });

package/apps/control-plane/test/dashboard-live-feed.spec.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest';
+import {
+  appendFeedEvents,
+  deriveFeedEventsFromSnapshotDiff,
+  reduceLiveFeedState,
+} from '../../../packages/web-dashboard/src/lib/live-feed.js';
+import type { DashboardStatusPayload } from '../../../packages/web-dashboard/src/lib/types.js';
+
+function payload(overrides: Partial<DashboardStatusPayload>): DashboardStatusPayload {
+  return {
+    index: { active: [], blocked: [], merged: [], blocked_queue: [] },
+    features: [],
+    ...overrides,
+  };
+}
+
+describe('dashboard live feed utils', () => {
+  it('derives phase and gate events from snapshot diffs', () => {
+    const previous = payload({
+      features: [
+        {
+          id: 'feature_a',
+          feature_id: 'feature_a',
+          status: 'building',
+          phase: 'building',
+          gates: { fast: 'na' },
+          activity_state: 'active',
+          pr: null,
+        },
+      ],
+      lock_map: [
+        {
+          resource: 'repo:write',
+          holder: 'feature_a',
+          expires_at: '2099-01-01T00:00:00Z',
+          is_stale: false,
+        },
+      ],
+    });
+    const next = payload({
+      features: [
+        {
+          id: 'feature_a',
+          feature_id: 'feature_a',
+          status: 'qa',
+          phase: 'qa',
+          gates: { fast: 'pass' },
+          activity_state: 'idle',
+          pr: null,
+        },
+      ],
+      lock_map: [
+        {
+          resource: 'repo:write',
+          holder: 'feature_b',
+          expires_at: '2099-01-01T00:00:00Z',
+          is_stale: false,
+        },
+      ],
+    });
+
+    const events = deriveFeedEventsFromSnapshotDiff(previous, next, '2026-03-05T00:00:00Z');
+    expect(events.some((event) => event.type === 'phase_change')).toBe(true);
+    expect(events.some((event) => event.type === 'gate_update')).toBe(true);
+    expect(events.some((event) => event.type === 'activity_change')).toBe(true);
+    expect(events.some((event) => event.type === 'lock_change')).toBe(true);
+  });
+
+  it('de-duplicates identical events within ten seconds and keeps bounded length', () => {
+    const seed = [
+      {
+        id: 'a',
+        timestamp: '2026-03-05T00:00:00Z',
+        feature_id: 'feature_a',
+        type: 'phase_change' as const,
+        message: 'feature_a moved planning -> building',
+        severity: 'info' as const,
+      },
+    ];
+    const duplicate = [
+      {
+        id: 'b',
+        timestamp: '2026-03-05T00:00:05Z',
+        feature_id: 'feature_a',
+        type: 'phase_change' as const,
+        message: 'feature_a moved planning -> building',
+        severity: 'info' as const,
+      },
+    ];
+
+    const unchanged = appendFeedEvents(seed, duplicate);
+    expect(unchanged).toHaveLength(1);
+  });
+
+  it('caps retained feed events to last 100 entries', () => {
+    const baseTimestamp = Date.parse('2026-03-05T00:00:00Z');
+    const existing = Array.from({ length: 99 }, (_, index) => ({
+      id: `existing-${index}`,
+      timestamp: new Date(baseTimestamp + index * 1000).toISOString(),
+      feature_id: 'feature_a',
+      type: 'activity_change' as const,
+      message: `message-${index}`,
+      severity: 'info' as const,
+    }));
+    const incoming = [
+      {
+        id: 'incoming-1',
+        timestamp: '2026-03-05T00:02:00Z',
+        feature_id: 'feature_a',
+        type: 'activity_change' as const,
+        message: 'message-new-1',
+        severity: 'info' as const,
+      },
+      {
+        id: 'incoming-2',
+        timestamp: '2026-03-05T00:02:01Z',
+        feature_id: 'feature_a',
+        type: 'activity_change' as const,
+        message: 'message-new-2',
+        severity: 'info' as const,
+      },
+    ];
+
+    const updated = appendFeedEvents(existing, incoming);
+    expect(updated).toHaveLength(100);
+    expect(updated[0].id).toBe('incoming-2');
+    expect(updated[1].id).toBe('incoming-1');
+  });
+
+  it('applies live-feed pause and clear controls deterministically', () => {
+    const base = {
+      paused: false,
+      events: [
+        {
+          id: 'event-1',
+          timestamp: '2026-03-05T00:00:00Z',
+          feature_id: 'feature_a',
+          type: 'phase_change' as const,
+          message: 'feature_a moved planning -> building',
+          severity: 'info' as const,
+        },
+      ],
+    };
+
+    const paused = reduceLiveFeedState(base, { type: 'toggle_pause' });
+    expect(paused.paused).toBe(true);
+    expect(paused.events).toHaveLength(1);
+
+    const cleared = reduceLiveFeedState(paused, { type: 'clear' });
+    expect(cleared.paused).toBe(true);
+    expect(cleared.events).toEqual([]);
+  });
+});