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.

src/app/api/activity/route.ts

@@ -0,0 +1,10 @@
+import { activityEventBus } from '../../../lib/realtime';
+
+export async function GET(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  const projectRoot = url.searchParams.get('projectRoot') || undefined;
+
+  const history = activityEventBus.getHistory(projectRoot);
+
+  return Response.json(history);
+}

src/app/api/agents/[agentId]/stats/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from 'next/server';
+import { readIssuesFromDisk } from '../../../../../lib/read-issues';
+import { activityEventBus } from '../../../../../lib/realtime';
+import { getAgentMetrics } from '../../../../../lib/agent-sessions';
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ agentId: string }> }
+): Promise<Response> {
+  const { agentId } = await params;
+  const url = new URL(request.url);
+  const projectRoot = url.searchParams.get('projectRoot') ?? process.cwd();
+
+  try {
+    const issues = await readIssuesFromDisk({ projectRoot, preferBd: true });
+    const activity = activityEventBus.getHistory(projectRoot);
+
+    const metrics = await getAgentMetrics(agentId, issues, activity);
+
+    return NextResponse.json({ ok: true, metrics });
+  } catch (error) {
+    console.error('[API/Agents/Stats] Failed:', error);
+    return NextResponse.json({ ok: false, error: String(error) }, { status: 500 });
+  }
+}

src/app/timeline/page.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+import { useEffect } from 'react';
+import { TimelineFeed } from '../../components/timeline/timeline-feed';
+import { useTimelineStore } from '../../components/timeline/timeline-store';
+
+export default function TimelinePage() {
+  return (
+    <div className="mx-auto max-w-3xl px-4 py-8">
+      <header className="mb-8">
+        <h1 className="text-2xl font-bold text-text-strong">Activity Timeline</h1>
+        <p className="text-text-muted">Real-time stream of project mutations.</p>
+      </header>
+      
+      <TimelineControls />
+      <TimelineSubscription />
+      <TimelineFeed />
+    </div>
+  );
+}
+
+function TimelineControls() {
+    return (
+      <div className="mb-6 flex gap-2">
+        {/* Placeholder for future filters */}
+        <div className="text-sm text-text-muted">Showing all activity</div>
+      </div>
+    );
+}
+
+function TimelineSubscription() {
+  const { addEvent, setHistory } = useTimelineStore();
+
+  useEffect(() => {
+    // 1. Fetch history
+    fetch('/api/activity')
+      .then(res => {
+        if (!res.ok) throw new Error('History fetch failed');
+        return res.json();
+      })
+      .then(data => setHistory(data))
+      .catch(err => console.error('Failed to load history', err));
+
+    // 2. Subscribe to SSE
+    const es = new EventSource('/api/events'); 
+
+    es.addEventListener('activity', (e) => {
+      try {
+        const event = JSON.parse(e.data);
+        addEvent(event);
+      } catch (err) {
+        console.error('Failed to parse activity event', err);
+      }
+    });
+    
+    return () => es.close();
+  }, [setHistory, addEvent]);
+
+  return null;
+}