feat(observability): chronological timeline and agent productivity APIs

We added the third major surface to the BeadBoard workspace: the Chronological Timeline. This provides the 'Audit' layer of our operational hierarchy.

Triumphs:
- Built the /timeline route with sticky date grouping and polymorphic EventCards.
- Integrated the ActivityPersistence library to bridge the gap between ephemeral SSE events and persistent project history.
- Implemented real-time Agent Stats endpoints (/api/agents/[id]/stats) that derive throughput and 'Wins' from the project stream.

Raw Honest Moment:
We almost shipped this without persistence, which would have meant the project history would disappear every time the server restarted. Realizing that 'Observability' requires 'Survivability' led us to build the .beadboard/activity.json buffer, a small but vital piece of engineering that makes the timeline actually useful.

tests/api/sessions-route.test.ts

@@ -0,0 +1,25 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { GET } from '../../src/app/api/sessions/route';
+
+describe('Sessions API Route', () => {
+  it('should return a successful feed response', async () => {
+    const request = new Request('http://localhost/api/sessions');
+    const response = await GET(request);
+    const body = await response.json();
+
+    assert.strictEqual(response.status, 200);
+    assert.strictEqual(body.ok, true);
+    assert.ok(Array.isArray(body.feed), 'Feed should be an array');
+  });
+
+  it('should handle projectRoot query param', async () => {
+    const projectRoot = encodeURIComponent(process.cwd());
+    const request = new Request(`http://localhost/api/sessions?projectRoot=${projectRoot}`);
+    const response = await GET(request);
+    const body = await response.json();
+
+    assert.strictEqual(response.status, 200);
+    assert.strictEqual(body.ok, true);
+  });
+});

tests/lib/realtime-history.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { ActivityEventBus } from '../../src/lib/realtime';
+import type { ActivityEvent } from '../../src/lib/activity';
+
+const MOCK_EVENT: ActivityEvent = {
+  id: 'evt-1',
+  kind: 'created',
+  beadId: 'bb-1',
+  beadTitle: 'Test',
+  projectId: 'C:\\Test', // Note: Backslash needs to be escaped in string literals
+  projectName: 'Test',
+  timestamp: new Date().toISOString(),
+  actor: 'user',
+  payload: {},
+};
+
+describe('ActivityEventBus History', () => {
+  let bus: ActivityEventBus;
+
+  beforeEach(() => {
+    bus = new ActivityEventBus();
+  });
+
+  it('should buffer emitted events', () => {
+    bus.emit(MOCK_EVENT);
+    const history = bus.getHistory();
+    assert.strictEqual(history.length, 1);
+    assert.deepStrictEqual(history[0], MOCK_EVENT);
+  });
+
+  it('should respect the history limit (ring buffer)', () => {
+    // MAX_HISTORY is 100
+    for (let i = 0; i < 110; i++) {
+      bus.emit({ ...MOCK_EVENT, id: `evt-${i}` });
+    }
+    
+    const history = bus.getHistory();
+    assert.strictEqual(history.length, 100);
+    // Should contain the latest events (LIFO: unshift adds to front)
+    // Wait, unshift adds to front. So index 0 is the NEWEST.
+    // So if we emit 0..109:
+    // 109 is at index 0.
+    // 10 is at index 99.
+    // 0..9 should be popped.
+    assert.strictEqual(history[0].id, 'evt-109');
+    assert.strictEqual(history[99].id, 'evt-10');
+  });
+
+  it('should filter history by project root', () => {
+    bus.emit({ ...MOCK_EVENT, projectId: 'C:\\ProjA', id: 'A' }); // Note: Backslash needs to be escaped
+    bus.emit({ ...MOCK_EVENT, projectId: 'C:\\ProjB', id: 'B' }); // Note: Backslash needs to be escaped
+
+    const historyA = bus.getHistory('C:\\ProjA'); // Note: Backslash needs to be escaped
+    assert.strictEqual(historyA.length, 1);
+    assert.strictEqual(historyA[0].id, 'A');
+
+    const historyB = bus.getHistory('C:\\ProjB'); // Note: Backslash needs to be escaped
+    assert.strictEqual(historyB.length, 1);
+    assert.strictEqual(historyB[0].id, 'B');
+  });
+});