Merge branch 'master' into feat/issue-637-timeline-model

# Conflicts:
#	webui/app.py

docs/webui-local-dev.md

@@ -74,11 +74,6 @@ status, onboarding checklist state, and the fail-closed error payloads (#635).
 | `/api/actions/{id}/preview` | Mutation ledger preview (GET, read-only) |
 | `/leases` | Lease and collision visibility (#433) |
 | `/api/leases` | JSON lease/collision export |
-| `/sessions` | Phase 1 shell stub — session inventory (backed by #636) |
-| `/inventory` | Phase 1 shell stub — unified inventory (backed by #636) |
-| `/timeline` | Phase 1 shell stub — workflow event timeline |
-| `/policy` | Phase 1 shell stub — capability/role policy placeholder |
-| `/insights` | Phase 1 shell stub — operational insights placeholder |
 
 Most routes are GET-only. POST/PUT/PATCH/DELETE return `405` with
 `read-only-mvp`, except `/audit` and `/api/audit` which accept POST for
@@ -238,26 +233,6 @@ health, workflow/schema SHA-256 hashes, and stale-runtime warnings when the
 checkout is behind merged safety-gate changes. Restart guidance links to #420;
 no tokens or MCP restart actions are exposed.
 
-## Application shell — Phase 1 (#638)
-
-The console shell (`webui/layout.py`) renders a grouped navigation driven by a
-single nav-config module, `webui/nav.py`. Nav groups follow the epic #631
-Phase 1 information architecture: **Health, Traffic, Runtime/Sessions,
-Projects, Inventory, Timeline, Policy** (placeholder), and **Insights**
-(placeholder). Live views and Phase 1 placeholders (`stub`) are declared in one
-place so the layout and the route table cannot drift.
-
-The header carries two read-only status badges — an **environment** badge
-(`local` for loopback binds, `remote` otherwise, derived from `WEBUI_HOST`) and
-a **mode: read-only** badge — plus a **Docs** link to this document. No
-privileged action controls are present in the Phase 1 shell.
-
-Not-yet-implemented surfaces (`/sessions`, `/inventory`, `/timeline`,
-`/policy`, `/insights`) resolve to graceful read-only stub pages instead of
-404s; their backing views land in later child issues of #631 (the inventory
-surfaces are backed by #636). Mutating methods on stub routes still fail closed
-with `read-only-mvp`.
-
 ## Deployment boundary (#435)
 
 MVP serves on loopback by default. Binding `0.0.0.0` or `::` is **refused**
@@ -317,6 +292,76 @@ health, workflow/schema SHA-256 hashes, and stale-runtime warnings when the
 checkout is behind merged safety-gate changes. Restart guidance links to #420;
 no tokens or MCP restart actions are exposed.
 
+## Workflow-event timeline (#637)
+
+`GET /api/v1/timeline` is a read-only, versioned aggregation of workflow
+events from every available source into one normalised, filterable stream. It
+is the model layer for the Phase 1 timeline console view (a later child issue
+of #631); this issue ships the schema, adapters, and read API only.
+
+### Schema (versioned)
+
+`webui/timeline.py` declares `TIMELINE_SCHEMA_VERSION` (currently `1`) and the
+frozen `WorkflowEvent` record. Every response carries `schema_version` so a
+consumer can branch on shape. One event:
+
+```json
+{
+  "source": "control_plane",
+  "event_type": "lease.renew",
+  "event_key": "cp:1421",
+  "timestamp": "2026-07-23T02:00:00Z",
+  "actor": null,
+  "role": null,
+  "issue_number": 637,
+  "pr_number": null,
+  "session_id": null,
+  "tool_name": null,
+  "decision": null,
+  "message": "lease renewed",
+  "correlation_id": "issue#637",
+  "evidence_refs": [],
+  "sensitive": true
+}
+```
+
+`event_key` is stable and unique per source (`cp:<event_id>`,
+`cth:<kind>:<number>:<comment_id>`), so pagination and dedup are deterministic.
+
+### Sources and field authority
+
+| Source | Adapter | Authority |
+|---|---|---|
+| Control-plane `events` ⋈ `work_items` | `adapt_cp_events` | `event_type`, `message`, `timestamp`, issue/PR scope come from the CP database, read through a `mode=ro` URI (never creates the DB or runs migrations) |
+| Gitea Canonical Thread Handoff comments | `adapt_cth_comments` | `actor`, `role` (next owner), `decision`, `evidence_refs`, `timestamp` come from the parsed CTH comment body (`canonical_thread_handoff`) |
+
+Handoff comments are thread-scoped: they are only read when the request filters
+by a single `issue` or `pr`. Otherwise the handoff source reports `not run`
+with a reason — it is never rendered as empty-and-healthy. Each source degrades
+independently: an unavailable control-plane DB or a failed comment fetch is a
+`sources[]` entry with `ok:false` and a `reason`, never a dropped timeline.
+
+### Query parameters
+
+`issue`, `pr`, `session` (conjunctive filters); `limit` (default 50, max 500)
+and `offset` for pagination; `remote`, `org`, `repo` to override the default
+registry-project scope. Events sort ascending by
+`(timestamp, source_rank, event_key)`; missing timestamps sort last.
+
+### Redaction
+
+Every free-text field (event messages, decision/proof text, roles) is passed
+through the console redaction policy (`webui.console_redaction`, backed by
+`gitea_audit.redact`) before it leaves the module, failing closed to the
+placeholder. No unredacted tool arguments or secrets are ever emitted, and a
+generation error never drops raw data to a caller or a log.
+
+### Tests
+
+```bash
+pytest tests/test_webui_timeline.py -q
+```
+
 ## Tests
 
 ```bash

tests/test_webui_shell.py

@@ -1,135 +0,0 @@
-"""Tests for the Phase 1 operator console application shell (#638)."""
-import sys
-import unittest
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-
-from starlette.routing import Route
-from starlette.testclient import TestClient
-
-from webui import layout
-from webui.app import create_app
-from webui.nav import NAV_GROUPS, STUB_PAGES, nav_hrefs
-
-
-class TestShellNav(unittest.TestCase):
-    def setUp(self):
-        self.client = TestClient(create_app())
-
-    def test_nav_group_labels_present(self):
-        text = self.client.get("/").text
-        for group in NAV_GROUPS:
-            with self.subTest(group=group.label):
-                self.assertIn(f">{group.label}<", text)
-
-    def test_phase1_group_labels_cover_expected_ia(self):
-        labels = {group.label for group in NAV_GROUPS}
-        for expected in (
-            "Health",
-            "Traffic",
-            "Runtime/Sessions",
-            "Projects",
-            "Inventory",
-            "Timeline",
-            "Policy",
-            "Insights",
-        ):
-            with self.subTest(label=expected):
-                self.assertIn(expected, labels)
-
-    def test_every_nav_href_resolves_to_a_get_route(self):
-        app = create_app()
-        get_paths = {
-            route.path
-            for route in app.routes
-            if isinstance(route, Route) and "GET" in route.methods
-        }
-        for href in nav_hrefs():
-            with self.subTest(href=href):
-                self.assertIn(href, get_paths, f"nav href {href} has no GET route")
-
-    def test_legacy_hrefs_still_navigable(self):
-        text = self.client.get("/").text
-        for href in ("/queue", "/projects", "/prompts", "/runtime",
-                     "/audit", "/worktrees", "/leases", "/actions"):
-            with self.subTest(href=href):
-                self.assertIn(f'href="{href}"', text)
-
-
-class TestShellBadges(unittest.TestCase):
-    def setUp(self):
-        self.client = TestClient(create_app())
-
-    def test_mode_badge_present(self):
-        self.assertIn("mode: read-only", self.client.get("/").text)
-
-    def test_environment_badge_present(self):
-        self.assertIn("env:", self.client.get("/").text)
-
-    def test_default_environment_is_local(self):
-        self.assertEqual(layout.environment_label(), "local")
-
-    def test_remote_bind_reports_remote_environment(self):
-        import os
-
-        prior = os.environ.get("WEBUI_HOST")
-        os.environ["WEBUI_HOST"] = "10.0.0.5"
-        try:
-            self.assertEqual(layout.environment_label(), "remote")
-        finally:
-            if prior is None:
-                os.environ.pop("WEBUI_HOST", None)
-            else:
-                os.environ["WEBUI_HOST"] = prior
-
-    def test_docs_link_present(self):
-        text = self.client.get("/").text
-        self.assertIn(layout.DOCS_URL, text)
-        self.assertIn(">Docs<", text)
-
-
-class TestShellStubs(unittest.TestCase):
-    def setUp(self):
-        self.client = TestClient(create_app())
-
-    def test_stub_routes_render_200(self):
-        for path, (title, _desc) in STUB_PAGES.items():
-            with self.subTest(path=path):
-                response = self.client.get(path)
-                self.assertEqual(response.status_code, 200, path)
-                self.assertIn(title, response.text)
-                self.assertIn("placeholder", response.text)
-
-    def test_stub_routes_are_read_only(self):
-        for path in STUB_PAGES:
-            with self.subTest(path=path):
-                response = self.client.post(path)
-                self.assertEqual(response.status_code, 405)
-                self.assertEqual(response.json()["error"], "read-only-mvp")
-
-    def test_stub_pages_carry_nav_and_badges(self):
-        response = self.client.get("/inventory")
-        self.assertIn("mode: read-only", response.text)
-        self.assertIn('href="/queue"', response.text)
-
-
-class TestShellHome(unittest.TestCase):
-    def setUp(self):
-        self.client = TestClient(create_app())
-
-    def test_home_summarizes_console(self):
-        text = self.client.get("/").text
-        self.assertIn("Operator console", text)
-        self.assertIn("Phase 1", text)
-
-    def test_home_links_legacy_pages(self):
-        text = self.client.get("/").text
-        self.assertIn("MVP legacy pages", text)
-        for href in ("/queue", "/audit", "/leases"):
-            with self.subTest(href=href):
-                self.assertIn(f'href="{href}"', text)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_webui_timeline.py

@@ -0,0 +1,364 @@
+"""Tests for the workflow-event timeline model and read API (#637).
+
+Covers the acceptance criteria: versioned schema, adaptation of control-plane
+events and Gitea handoff comments, filter by issue/PR/session, redaction of
+secret-like payloads, and stable pagination.
+"""
+import os
+import sqlite3
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from starlette.testclient import TestClient
+
+import control_plane_db
+from canonical_thread_handoff import format_cth_body
+from webui import timeline
+from webui.app import create_app
+
+
+def _seed_db(path: str) -> None:
+    """Create a control-plane DB and seed scoped work_items + events."""
+    # Constructing ControlPlaneDB runs the schema migration once.
+    control_plane_db.ControlPlaneDB(db_path=path)
+    conn = sqlite3.connect(path)
+    try:
+        conn.execute(
+            "INSERT INTO work_items(remote, org, repo, kind, number, state, updated_at) "
+            "VALUES (?,?,?,?,?,?,?)",
+            ("prgs", "Scaled-Tech-Consulting", "Gitea-Tools", "issue", 637, "open", "2026-07-23T00:00:00Z"),
+        )
+        issue_wid = conn.execute("SELECT last_insert_rowid()").fetchone()[0]
+        conn.execute(
+            "INSERT INTO work_items(remote, org, repo, kind, number, state, updated_at) "
+            "VALUES (?,?,?,?,?,?,?)",
+            ("prgs", "Scaled-Tech-Consulting", "Gitea-Tools", "pr", 813, "open", "2026-07-23T00:00:00Z"),
+        )
+        pr_wid = conn.execute("SELECT last_insert_rowid()").fetchone()[0]
+        # A work item for a different repo — must never appear in prgs/Gitea-Tools scope.
+        conn.execute(
+            "INSERT INTO work_items(remote, org, repo, kind, number, state, updated_at) "
+            "VALUES (?,?,?,?,?,?,?)",
+            ("dadeschools", "Other", "Elsewhere", "issue", 1, "open", "2026-07-23T00:00:00Z"),
+        )
+        other_wid = conn.execute("SELECT last_insert_rowid()").fetchone()[0]
+
+        rows = [
+            (issue_wid, "allocation", "assigned author work", "2026-07-23T01:00:00Z"),
+            (issue_wid, "lease.renew", "token=ghs_ABCDEF1234567890abcdef lease renewed", "2026-07-23T02:00:00Z"),
+            (pr_wid, "pr.opened", "PR opened for review", "2026-07-23T03:00:00Z"),
+            (other_wid, "allocation", "off-scope event", "2026-07-23T04:00:00Z"),
+        ]
+        conn.executemany(
+            "INSERT INTO events(work_item_id, event_type, message, created_at) VALUES (?,?,?,?)",
+            rows,
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+class TestSchema(unittest.TestCase):
+    def test_schema_is_versioned(self):
+        self.assertIsInstance(timeline.TIMELINE_SCHEMA_VERSION, int)
+        self.assertGreaterEqual(timeline.TIMELINE_SCHEMA_VERSION, 1)
+
+    def test_event_to_dict_shape(self):
+        ev = timeline.WorkflowEvent(
+            source=timeline.SOURCE_CONTROL_PLANE,
+            event_type="allocation",
+            event_key="cp:1",
+            timestamp="2026-07-23T01:00:00Z",
+            issue_number=637,
+        )
+        d = ev.to_dict()
+        for key in (
+            "source", "event_type", "event_key", "timestamp", "actor", "role",
+            "issue_number", "pr_number", "session_id", "tool_name", "decision",
+            "message", "correlation_id", "evidence_refs", "sensitive",
+        ):
+            self.assertIn(key, d)
+        self.assertEqual(d["evidence_refs"], [])
+
+
+class TestCpAdapter(unittest.TestCase):
+    def test_issue_and_pr_mapping(self):
+        rows = [
+            {"event_id": 1, "event_type": "allocation", "message": "x", "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 637},
+            {"event_id": 2, "event_type": "pr.opened", "message": "y", "created_at": "2026-07-23T02:00:00Z", "kind": "pr", "number": 813},
+        ]
+        events = timeline.adapt_cp_events(rows)
+        self.assertEqual(len(events), 2)
+        self.assertEqual(events[0].issue_number, 637)
+        self.assertIsNone(events[0].pr_number)
+        self.assertEqual(events[0].correlation_id, "issue#637")
+        self.assertIsNone(events[1].issue_number)
+        self.assertEqual(events[1].pr_number, 813)
+
+    def test_malformed_rows_skipped(self):
+        rows = [
+            {"event_id": None, "event_type": "x", "kind": "issue", "number": 1},
+            {"event_id": 5, "event_type": "", "kind": "issue", "number": 1},
+            {"event_id": 6, "event_type": "ok", "message": "m", "created_at": None, "kind": "issue", "number": 1},
+        ]
+        events = timeline.adapt_cp_events(rows)
+        self.assertEqual(len(events), 1)
+        self.assertIsNone(events[0].timestamp)
+
+    def test_sensitive_event_flagged(self):
+        rows = [{"event_id": 1, "event_type": "lease.renew", "message": "m", "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 1}]
+        events = timeline.adapt_cp_events(rows)
+        self.assertTrue(events[0].sensitive)
+
+
+class TestCthAdapter(unittest.TestCase):
+    def test_cth_comment_becomes_event(self):
+        body = format_cth_body(
+            cth_type="Author Handoff",
+            status="ready",
+            next_owner="reviewer",
+            decision="implement timeline",
+            proof="commit abc1234 closes #637",
+            next_action="review PR",
+            ready_to_paste_prompt="Review PR #900 as reviewer",
+        )
+        comments = [{"id": 42, "body": body, "created_at": "2026-07-23T05:00:00Z", "user": {"login": "jcwalker3"}}]
+        events = timeline.adapt_cth_comments(comments, kind="issue", number=637)
+        self.assertEqual(len(events), 1)
+        ev = events[0]
+        self.assertEqual(ev.source, timeline.SOURCE_GITEA_HANDOFF)
+        self.assertEqual(ev.event_type, "handoff:Author Handoff")
+        self.assertEqual(ev.actor, "jcwalker3")
+        self.assertEqual(ev.issue_number, 637)
+        self.assertEqual(ev.event_key, "cth:issue:637:42")
+        self.assertIn("#637", ev.evidence_refs)
+        self.assertIn("abc1234", ev.evidence_refs)
+
+    def test_non_cth_comment_ignored(self):
+        comments = [{"id": 1, "body": "just a normal comment", "created_at": "2026-07-23T05:00:00Z", "user": {"login": "x"}}]
+        self.assertEqual(timeline.adapt_cth_comments(comments, kind="issue", number=1), [])
+
+
+class TestRedaction(unittest.TestCase):
+    def test_cp_message_redacted(self):
+        rows = [{"event_id": 1, "event_type": "lease", "message": "token=ghs_ABCDEF1234567890abcdef here", "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 1}]
+        events = timeline.adapt_cp_events(rows)
+        self.assertNotIn("ghs_ABCDEF1234567890abcdef", events[0].message or "")
+
+    def test_handoff_decision_redacted(self):
+        body = format_cth_body(
+            cth_type="Blocker",
+            status="blocked",
+            next_owner="author",
+            decision="password=SuperSecret123! must rotate",
+            proof="none",
+            next_action="rotate",
+            ready_to_paste_prompt="Rotate the credential and retry",
+        )
+        comments = [{"id": 7, "body": body, "created_at": "2026-07-23T05:00:00Z", "user": {"login": "x"}}]
+        events = timeline.adapt_cth_comments(comments, kind="issue", number=1)
+        self.assertNotIn("SuperSecret123!", events[0].decision or "")
+
+
+class TestFilterSortPaginate(unittest.TestCase):
+    def _events(self):
+        return [
+            timeline.WorkflowEvent(source="control_plane", event_type="a", event_key="cp:3", timestamp="2026-07-23T03:00:00Z", pr_number=813),
+            timeline.WorkflowEvent(source="control_plane", event_type="b", event_key="cp:1", timestamp="2026-07-23T01:00:00Z", issue_number=637),
+            timeline.WorkflowEvent(source="control_plane", event_type="c", event_key="cp:2", timestamp="2026-07-23T02:00:00Z", issue_number=637, session_id="sess-1"),
+        ]
+
+    def test_filter_by_issue(self):
+        out = timeline.filter_events(self._events(), issue=637)
+        self.assertEqual({e.event_key for e in out}, {"cp:1", "cp:2"})
+
+    def test_filter_by_pr(self):
+        out = timeline.filter_events(self._events(), pr=813)
+        self.assertEqual([e.event_key for e in out], ["cp:3"])
+
+    def test_filter_by_session(self):
+        out = timeline.filter_events(self._events(), session="sess-1")
+        self.assertEqual([e.event_key for e in out], ["cp:2"])
+
+    def test_stable_sort_ascending(self):
+        out = timeline.sort_events(self._events())
+        self.assertEqual([e.event_key for e in out], ["cp:1", "cp:2", "cp:3"])
+
+    def test_missing_timestamp_sorts_last(self):
+        evs = self._events() + [
+            timeline.WorkflowEvent(source="control_plane", event_type="z", event_key="cp:9", timestamp=None)
+        ]
+        out = timeline.sort_events(evs)
+        self.assertEqual(out[-1].event_key, "cp:9")
+
+    def test_pagination_windows_and_next_offset(self):
+        evs = timeline.sort_events(self._events())
+        page1 = timeline.paginate(evs, limit=2, offset=0)
+        self.assertEqual(len(page1.events), 2)
+        self.assertEqual(page1.total, 3)
+        self.assertEqual(page1.next_offset, 2)
+        page2 = timeline.paginate(evs, limit=2, offset=2)
+        self.assertEqual(len(page2.events), 1)
+        self.assertIsNone(page2.next_offset)
+
+    def test_pagination_bounds_coerced(self):
+        evs = self._events()
+        page = timeline.paginate(evs, limit=-5, offset=-3)
+        self.assertGreaterEqual(page.limit, 1)
+        self.assertEqual(page.offset, 0)
+
+
+class TestCpReader(unittest.TestCase):
+    def test_reads_scoped_events_only(self):
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp:
+            db = os.path.join(tmp, "cp.sqlite3")
+            _seed_db(db)
+            events, status = timeline.read_cp_events(
+                remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", db_path=db
+            )
+            self.assertTrue(status.ok)
+            # 3 scoped events; the dadeschools/Other event is excluded.
+            self.assertEqual(len(events), 3)
+            self.assertTrue(all(e.source == "control_plane" for e in events))
+            # Redaction applied to the token-bearing message.
+            joined = " ".join(e.message or "" for e in events)
+            self.assertNotIn("ghs_ABCDEF1234567890abcdef", joined)
+
+    def test_missing_db_degrades(self):
+        events, status = timeline.read_cp_events(
+            remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools",
+            db_path="/nonexistent/path/to/cp.sqlite3",
+        )
+        self.assertEqual(events, [])
+        self.assertFalse(status.ok)
+        self.assertIsNotNone(status.reason)
+
+
+class TestLoadTimeline(unittest.TestCase):
+    def test_handoff_not_run_without_thread_filter(self):
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp:
+            db = os.path.join(tmp, "cp.sqlite3")
+            _seed_db(db)
+            snap = timeline.load_timeline(
+                remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", db_path=db
+            )
+            d = snap.to_dict()
+            handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0]
+            self.assertFalse(handoff["ok"])
+            self.assertIn("thread-scoped", handoff["reason"])
+            self.assertEqual(d["schema_version"], timeline.TIMELINE_SCHEMA_VERSION)
+
+    def test_handoff_included_via_injected_source(self):
+        import tempfile
+
+        body = format_cth_body(
+            cth_type="Author Handoff", status="ready", next_owner="reviewer",
+            decision="d", proof="#637", next_action="review", ready_to_paste_prompt="Review PR #1 now",
+        )
+
+        def source(kind, number):
+            return [{"id": 1, "body": body, "created_at": "2026-07-23T09:00:00Z", "user": {"login": "jcwalker3"}}]
+
+        with tempfile.TemporaryDirectory() as tmp:
+            db = os.path.join(tmp, "cp.sqlite3")
+            _seed_db(db)
+            snap = timeline.load_timeline(
+                remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools",
+                issue=637, db_path=db, comment_source=source,
+            )
+            d = snap.to_dict()
+            handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0]
+            self.assertTrue(handoff["ok"])
+            self.assertEqual(handoff["count"], 1)
+            # Both a CP event and the handoff event for issue 637 appear, sorted.
+            kinds = {e["source"] for e in d["events"]}
+            self.assertEqual(kinds, {"control_plane", "gitea_handoff"})
+
+    def test_failing_comment_source_degrades_only_handoff(self):
+        import tempfile
+
+        def boom(kind, number):
+            raise RuntimeError("network down")
+
+        with tempfile.TemporaryDirectory() as tmp:
+            db = os.path.join(tmp, "cp.sqlite3")
+            _seed_db(db)
+            snap = timeline.load_timeline(
+                remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools",
+                issue=637, db_path=db, comment_source=boom,
+            )
+            d = snap.to_dict()
+            cp = [s for s in d["sources"] if s["name"] == "control_plane"][0]
+            handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0]
+            self.assertTrue(cp["ok"])
+            self.assertFalse(handoff["ok"])
+            self.assertIn("network down", handoff["reason"])
+
+
+class TestTimelineApi(unittest.TestCase):
+    def setUp(self):
+        self._prev_db = os.environ.get(control_plane_db.DB_PATH_ENV)
+        self._prev_offline = os.environ.get("WEBUI_TEST_OFFLINE")
+        import tempfile
+
+        self._tmpdir = tempfile.TemporaryDirectory()
+        self._db = os.path.join(self._tmpdir.name, "cp.sqlite3")
+        _seed_db(self._db)
+        os.environ[control_plane_db.DB_PATH_ENV] = self._db
+        os.environ["WEBUI_TEST_OFFLINE"] = "1"
+        self.client = TestClient(create_app())
+
+    def tearDown(self):
+        if self._prev_db is None:
+            os.environ.pop(control_plane_db.DB_PATH_ENV, None)
+        else:
+            os.environ[control_plane_db.DB_PATH_ENV] = self._prev_db
+        if self._prev_offline is None:
+            os.environ.pop("WEBUI_TEST_OFFLINE", None)
+        else:
+            os.environ["WEBUI_TEST_OFFLINE"] = self._prev_offline
+        self._tmpdir.cleanup()
+
+    def test_api_returns_timeline(self):
+        resp = self.client.get("/api/v1/timeline")
+        self.assertEqual(resp.status_code, 200)
+        body = resp.json()
+        self.assertEqual(body["schema_version"], timeline.TIMELINE_SCHEMA_VERSION)
+        self.assertIn("events", body)
+        self.assertIn("pagination", body)
+        self.assertGreaterEqual(body["pagination"]["total"], 1)
+
+    def test_api_filter_by_issue(self):
+        resp = self.client.get("/api/v1/timeline?issue=637")
+        self.assertEqual(resp.status_code, 200)
+        events = resp.json()["events"]
+        self.assertTrue(events)
+        self.assertTrue(all(e["issue_number"] == 637 for e in events))
+
+    def test_api_pagination(self):
+        resp = self.client.get("/api/v1/timeline?limit=1&offset=0")
+        self.assertEqual(resp.status_code, 200)
+        pg = resp.json()["pagination"]
+        self.assertEqual(pg["limit"], 1)
+        self.assertEqual(len(resp.json()["events"]), 1)
+        if pg["total"] > 1:
+            self.assertTrue(pg["has_more"])
+
+    def test_api_is_read_only(self):
+        resp = self.client.post("/api/v1/timeline")
+        self.assertIn(resp.status_code, (404, 405))
+
+    def test_api_no_secret_leak(self):
+        resp = self.client.get("/api/v1/timeline?issue=637")
+        self.assertNotIn("ghs_ABCDEF1234567890abcdef", resp.text)
+
+
+if __name__ == "__main__":
+    unittest.main()

webui/app.py

@@ -12,7 +12,6 @@ from starlette.routing import Route
 
 from webui.deployment_boundary import deployment_snapshot
 from webui.layout import render_page
-from webui.nav import NAV_GROUPS, STUB_PAGES
 from webui.project_registry import (
     ProjectRegistry,
     RegistryError,
@@ -46,6 +45,7 @@ from webui.worktree_scanner import load_hygiene_snapshot, snapshot_to_dict as wo
 from webui.worktree_views import render_worktrees_page
 from webui.runtime_health import load_runtime_snapshot, snapshot_to_dict as runtime_snapshot_to_dict
 from webui.runtime_views import render_runtime_page
+from webui.timeline import load_timeline, snapshot_to_dict as timeline_snapshot_to_dict
 from webui.system_health import (
     API_PATH as SYSTEM_HEALTH_API_PATH,
     load_system_health,
@@ -66,62 +66,24 @@ def _stub_page(title: str, description: str) -> HTMLResponse:
     return HTMLResponse(render_page(title=title, body_html=body))
 
 
-_LEGACY_PAGES = (
-    ("/queue", "Queue", "live PR and issue dashboard (#429)"),
-    ("/projects", "Projects", "registry and onboarding (#427)"),
-    ("/prompts", "Prompts", "canonical workflow prompt library (#428)"),
-    ("/runtime", "Runtime", "MCP health and stale-runtime detection (#430)"),
-    ("/audit", "Audit", "final-report paste and validator preview (#431)"),
-    ("/worktrees", "Worktrees", "branch hygiene dashboard (#432)"),
-    ("/leases", "Leases", "collision and lease visibility (#433)"),
-    ("/actions", "Actions", "gated write-action framework (#434)"),
-)
-
-
-def _render_home_nav_groups() -> str:
-    groups = []
-    for group in NAV_GROUPS:
-        items = "".join(
-            f'<li><a href="{item.href}">{item.label}</a>'
-            + ("" if item.status == "live" else " <span class=\"muted\">(stub)</span>")
-            + "</li>"
-            for item in group.items
-        )
-        groups.append(f"<h3>{group.label}</h3><ul>{items}</ul>")
-    return "".join(groups)
-
-
 async def home(_request: Request) -> HTMLResponse:
-    legacy = "".join(
-        f"<li><strong>{label}</strong> — {desc} "
-        f'(<a href="{href}">{href}</a>)</li>'
-        for href, label, desc in _LEGACY_PAGES
-    )
     body = (
         "<h2>Operator console</h2>"
-        "<p>Read-only home for the MCP Control Plane Phase 1 operator console. "
-        "Gitea, MCP capability gates, and canonical workflows remain the source "
-        "of truth; this console never mutates them.</p>"
-        "<h2>Phase 1 surfaces</h2>"
-        + _render_home_nav_groups()
-        + "<h2>MVP legacy pages</h2>"
-        "<ul>" + legacy + "</ul>"
+        "<p>Local entry point for MCP Control Plane operational views.</p>"
+        "<ul>"
+        "<li><strong>Queue</strong> — live PR and issue dashboard (#429)</li>"
+        "<li><strong>Projects</strong> — registry and onboarding (#427)</li>"
+        "<li><strong>Prompts</strong> — canonical workflow prompt library (#428)</li>"
+        "<li><strong>Runtime</strong> — MCP health and stale-runtime detection (#430)</li>"
+        "<li><strong>Audit</strong> — final-report paste and validator preview (#431)</li>"
+        "<li><strong>Worktrees</strong> — branch hygiene dashboard (#432)</li>"
+        "<li><strong>Leases</strong> — collision and lease visibility (#433)</li>"
+        "<li><strong>Actions</strong> — gated write-action framework (#434)</li>"
+        "</ul>"
     )
     return HTMLResponse(render_page(title="Home", body_html=body))
 
 
-async def phase_stub(request: Request) -> HTMLResponse:
-    """Graceful read-only placeholder for a not-yet-implemented Phase 1 surface."""
-    title, description = STUB_PAGES[request.url.path]
-    body = (
-        f"<h2>{title}</h2>"
-        f'<div class="stub"><p>{description}</p>'
-        "<p>Phase 1 shell placeholder — no write actions. Tracked under "
-        "epic #631.</p></div>"
-    )
-    return HTMLResponse(render_page(title=title, body_html=body))
-
-
 async def health(_request: Request) -> JSONResponse:
     """Liveness only — deliberately cheap, runs no dependency probe (#634).
 
@@ -449,6 +411,101 @@ async def api_console_security_model(_request: Request) -> JSONResponse:
     })
 
 
+def _query_int(request: Request, key: str) -> int | None:
+    """Parse an optional integer query parameter; None when absent/invalid."""
+    raw = request.query_params.get(key)
+    if raw is None or not str(raw).strip():
+        return None
+    try:
+        return int(str(raw).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def _derive_remote(host: str) -> str:
+    """Map a Gitea host to its known short remote name (control-plane scope key)."""
+    text = (host or "").lower()
+    if "prgs" in text:
+        return "prgs"
+    if "dadeschools" in text:
+        return "dadeschools"
+    return text.split(".")[0] if text else ""
+
+
+def _timeline_comment_source(host: str, org: str, repo: str):
+    """Build a fail-soft CTH-comment fetcher for one repo, or None when offline.
+
+    Returns a callable ``(kind, number) -> list[comment]``. Credentials or
+    network failures raise inside the callable so ``load_timeline`` degrades the
+    handoff source rather than the whole timeline. Offline test mode yields no
+    live source so the handoff section reports ``not run``.
+    """
+    import os
+
+    from gitea_auth import api_fetch_page, get_auth_header, repo_api_url
+
+    offline = (os.environ.get("WEBUI_TEST_OFFLINE") or "").strip().lower() in {"1", "true", "yes"}
+    if offline:
+        return None
+    auth = get_auth_header(host)
+    if not auth:
+        return None
+
+    def _fetch(kind: str, number: int) -> list:
+        segment = "pulls" if kind == "pr" else "issues"
+        url = f"{repo_api_url(host, org, repo)}/{segment}/{int(number)}/comments"
+        comments: list = []
+        page = 1
+        while page <= 20:
+            raw, meta = api_fetch_page(url, auth, page=page, limit=50)
+            comments.extend(raw)
+            if bool(meta["is_final_page"]):
+                break
+            page += 1
+        return comments
+
+    return _fetch
+
+
+async def api_v1_timeline(request: Request) -> JSONResponse:
+    """Read-only workflow-event timeline (#637). Filter by issue/PR/session."""
+    from webui.queue_loader import _host_from_url  # host normalisation helper
+
+    registry, error = _load_project_registry()
+    if error is not None:
+        return JSONResponse(error.to_dict(), status_code=500)
+    project = registry.projects[0] if registry.projects else None
+
+    org = request.query_params.get("org") or (project.gitea_owner if project else "")
+    repo = request.query_params.get("repo") or (project.repo_name if project else "")
+    host = _host_from_url(project.remote_host) if project else ""
+    remote = request.query_params.get("remote") or _derive_remote(host)
+
+    if not (remote and org and repo):
+        return JSONResponse(
+            {
+                "error": "timeline_scope_unresolved",
+                "detail": "no project in registry and no remote/org/repo query params provided",
+            },
+            status_code=400,
+        )
+
+    comment_source = _timeline_comment_source(host, org, repo) if (host and org and repo) else None
+
+    snapshot = load_timeline(
+        remote=remote,
+        org=org,
+        repo=repo,
+        issue=_query_int(request, "issue"),
+        pr=_query_int(request, "pr"),
+        session=(request.query_params.get("session") or None),
+        limit=_query_int(request, "limit"),
+        offset=_query_int(request, "offset"),
+        comment_source=comment_source,
+    )
+    return JSONResponse(timeline_snapshot_to_dict(snapshot))
+
+
 async def method_not_allowed(request: Request, _exc: Exception) -> Response:
     path = request.url.path
     if path in _AUDIT_MUTATION_PATHS and request.method == "POST":
@@ -488,6 +545,7 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
             Route("/api/prompts", api_prompts, methods=["GET"]),
             Route("/runtime", runtime, methods=["GET"]),
             Route("/api/runtime", api_runtime, methods=["GET"]),
+            Route("/api/v1/timeline", api_v1_timeline, methods=["GET"]),
             Route("/audit", audit, methods=["GET", "POST"]),
             Route("/api/audit", api_audit, methods=["GET", "POST"]),
             Route("/worktrees", worktrees, methods=["GET"]),
@@ -511,10 +569,6 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
                 api_console_security_model,
                 methods=["GET"],
             ),
-            *[
-                Route(path, phase_stub, methods=["GET"])
-                for path in STUB_PAGES
-            ],
         ],
         exception_handlers={405: method_not_allowed},
     )

webui/layout.py

@@ -2,66 +2,28 @@
 
 from __future__ import annotations
 
-import os
-
-from webui.nav import NAV_GROUPS
+NAV_ITEMS = (
+    ("/", "Home"),
+    ("/queue", "Queue"),
+    ("/projects", "Projects"),
+    ("/prompts", "Prompts"),
+    ("/runtime", "Runtime"),
+    ("/audit", "Audit"),
+    ("/worktrees", "Worktrees"),
+    ("/leases", "Leases"),
+    ("/actions", "Actions"),
+)
 
 MVP_NOTICE = (
     "Read-only MVP — Gitea, MCP tools, and canonical workflows remain the "
     "source of truth. No mutation endpoints."
 )
 
-# Canonical docs entry point surfaced from the shell header (#638).
-DOCS_URL = (
-    "https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/src/branch/"
-    "master/docs/webui-local-dev.md"
-)
-
-_LOCAL_HOSTS = frozenset({"", "127.0.0.1", "localhost", "::1"})
-
-
-def environment_label() -> str:
-    """Classify the serving environment as ``local`` or ``remote`` (#638).
-
-    Derived from the same ``WEBUI_HOST`` default the app binds to; loopback
-    hosts are ``local``, anything else is ``remote``. Read-only signal only.
-    """
-    host = (os.environ.get("WEBUI_HOST", "127.0.0.1") or "").strip().lower()
-    return "local" if host in _LOCAL_HOSTS else "remote"
-
-
-def _render_nav() -> str:
-    groups_html = []
-    for group in NAV_GROUPS:
-        links = "".join(
-            f'<a href="{item.href}"'
-            + (' class="nav-stub"' if item.status == "stub" else "")
-            + f'>{item.label}</a>'
-            for item in group.items
-        )
-        groups_html.append(
-            '<div class="nav-group">'
-            f'<span class="nav-group-label">{group.label}</span>'
-            f'<span class="nav-group-links">{links}</span>'
-            "</div>"
-        )
-    return "".join(groups_html)
-
-
-def _render_badges() -> str:
-    env = environment_label()
-    return (
-        '<div class="header-badges">'
-        f'<span class="badge env-badge env-{env}">env: {env}</span>'
-        '<span class="badge mode-badge">mode: read-only</span>'
-        f'<a class="badge docs-link" href="{DOCS_URL}">Docs</a>'
-        "</div>"
-    )
-
 
 def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
-    nav_links = _render_nav()
-    header_badges = _render_badges()
+    nav_links = "".join(
+        f'<a href="{href}">{label}</a>' for href, label in NAV_ITEMS
+    )
     return f"""<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -91,58 +53,21 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
       padding: 0.75rem 1.25rem;
     }}
     header h1 {{
-      margin: 0;
+      margin: 0 0 0.5rem;
       font-size: 1.1rem;
       font-weight: 600;
     }}
-    .header-top {{
-      display: flex;
-      flex-wrap: wrap;
-      align-items: center;
-      justify-content: space-between;
-      gap: 0.5rem 1rem;
-      margin-bottom: 0.6rem;
-    }}
-    .header-badges {{ display: inline-flex; flex-wrap: wrap; gap: 0.4rem; }}
-    .env-badge.env-local {{ color: #8fd19e; border-color: #3d6b4a; }}
-    .env-badge.env-remote {{ color: #e0c27a; border-color: #6b5730; }}
-    .mode-badge {{ color: #9ec8f0; border-color: #3d5f7a; }}
-    a.docs-link {{
-      color: var(--accent);
-      border-color: var(--accent);
-      text-decoration: none;
-      text-transform: none;
-    }}
-    a.docs-link:hover {{ filter: brightness(1.12); }}
     nav {{
       display: flex;
       flex-wrap: wrap;
-      gap: 0.5rem 1.25rem;
+      gap: 0.75rem 1rem;
     }}
-    .nav-group {{
-      display: flex;
-      flex-direction: column;
-      gap: 0.15rem;
-    }}
-    .nav-group-label {{
-      font-size: 0.68rem;
-      text-transform: uppercase;
-      letter-spacing: 0.04em;
-      color: var(--muted);
-    }}
-    .nav-group-links {{ display: inline-flex; flex-wrap: wrap; gap: 0.6rem; }}
     nav a {{
       color: var(--accent);
       text-decoration: none;
       font-size: 0.9rem;
     }}
     nav a:hover {{ text-decoration: underline; }}
-    nav a.nav-stub {{ color: var(--muted); }}
-    nav a.nav-stub::after {{
-      content: " ·stub";
-      font-size: 0.7rem;
-      color: var(--muted);
-    }}
     main {{
       max-width: 52rem;
       margin: 0 auto;
@@ -241,10 +166,7 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
 </head>
 <body>
   <header>
-    <div class="header-top">
-      <h1>MCP Control Plane</h1>
-      {header_badges}
-    </div>
+    <h1>MCP Control Plane</h1>
     <nav>{nav_links}</nav>
   </header>
   <main>

webui/nav.py

@@ -1,111 +0,0 @@
-"""Navigation IA for the Phase 1 operator console shell (#638).
-
-Single source of truth for the console navigation so ``webui/layout.py`` and
-the ``webui/app.py`` route table stay aligned with epic #631. Read-only: every
-destination is a GET view or a Phase 1 placeholder. No mutation links.
-
-Nav groups follow the #631 Phase 1 information architecture: Health, Traffic,
-Runtime/Sessions, Projects, Inventory, Timeline, Policy (placeholder), and
-Insights (placeholder). Later-phase surfaces are declared as ``stub`` items and
-backed by ``STUB_PAGES`` so their nav links resolve to a graceful placeholder
-instead of a 404.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-
-@dataclass(frozen=True)
-class NavItem:
-    """A single navigation destination.
-
-    ``status`` is ``"live"`` for implemented views and ``"stub"`` for Phase 1
-    placeholders whose backing view lands in a later child issue.
-    """
-
-    href: str
-    label: str
-    status: str = "live"
-
-
-@dataclass(frozen=True)
-class NavGroup:
-    label: str
-    items: tuple[NavItem, ...]
-
-
-NAV_GROUPS: tuple[NavGroup, ...] = (
-    NavGroup("Health", (
-        NavItem("/health", "Liveness"),
-    )),
-    NavGroup("Traffic", (
-        NavItem("/queue", "Queue"),
-        NavItem("/leases", "Leases"),
-        NavItem("/actions", "Actions"),
-    )),
-    NavGroup("Runtime/Sessions", (
-        NavItem("/runtime", "Runtime health"),
-        NavItem("/sessions", "Sessions", "stub"),
-    )),
-    NavGroup("Projects", (
-        NavItem("/projects", "Projects"),
-    )),
-    NavGroup("Inventory", (
-        NavItem("/inventory", "Inventory", "stub"),
-        NavItem("/worktrees", "Worktrees"),
-    )),
-    NavGroup("Timeline", (
-        NavItem("/timeline", "Timeline", "stub"),
-    )),
-    NavGroup("Policy", (
-        NavItem("/policy", "Policy", "stub"),
-        NavItem("/prompts", "Prompts"),
-    )),
-    NavGroup("Insights", (
-        NavItem("/insights", "Insights", "stub"),
-        NavItem("/audit", "Audit"),
-    )),
-)
-
-
-# Phase 1 placeholder destinations whose backing views land in later child
-# issues of epic #631. Each maps a path to (title, description). Routes are
-# registered so nav links resolve to a graceful, read-only stub page.
-STUB_PAGES: dict[str, tuple[str, str]] = {
-    "/sessions": (
-        "Sessions",
-        "Active session, capability, and role inventory. Backed by the unified "
-        "inventory API (#636) once it lands.",
-    ),
-    "/inventory": (
-        "Inventory",
-        "Unified sessions, leases, locks, namespaces, and worktree inventory. "
-        "Backed by the Phase 1 inventory API (#636).",
-    ),
-    "/timeline": (
-        "Timeline",
-        "Workflow event timeline across issues and PRs. A later Phase 1 surface.",
-    ),
-    "/policy": (
-        "Policy",
-        "Capability and role policy surface. Placeholder until a later phase.",
-    ),
-    "/insights": (
-        "Insights",
-        "Aggregate operational insights and trends. Placeholder until a later "
-        "phase.",
-    ),
-}
-
-
-def iter_nav_items():
-    """Yield every ``NavItem`` across all groups in declared order."""
-    for group in NAV_GROUPS:
-        for item in group.items:
-            yield item
-
-
-def nav_hrefs() -> tuple[str, ...]:
-    """Return every navigation href in declared order."""
-    return tuple(item.href for item in iter_nav_items())

webui/timeline.py

@@ -0,0 +1,539 @@
+"""Workflow-event and conversation timeline model (#637, Phase 1).
+
+Operators cannot browse a unified timeline of workflow events, decisions,
+tool calls, and handoffs: the evidence is scattered across control-plane
+events, Gitea canonical handoff comments, and local logs. This module defines
+one durable, versioned event schema and per-source adapters that normalise
+those scattered records into a single ``WorkflowEvent`` stream, plus a
+read-only query layer (filter by issue / PR / session, stable ordering,
+pagination) that the ``/api/v1/timeline`` route serves.
+
+Design rules honoured here:
+
+- **Read-only.** Sources are read; nothing is mutated. The control-plane
+  database is opened through a ``mode=ro`` URI so a missing or unwritable DB
+  degrades to a reason instead of creating directories or running migrations.
+- **Fail-soft per source.** An unavailable source degrades to a status with a
+  reason rather than raising, and a source that could not run is never
+  rendered as an empty-and-healthy timeline.
+- **Redaction at the boundary, fail closed.** Every free-text field (event
+  messages, redacted tool arguments, decision/proof text) is run through the
+  console redaction policy before it leaves this module. An unredactable value
+  becomes the placeholder — an unredacted payload is never emitted, and a
+  generation error never drops raw data to a caller or a log.
+- **Stable ordering.** Events sort by ``(timestamp, source_rank, event_key)``
+  with a deterministic tiebreak, so pagination is stable across calls and
+  events with equal or missing timestamps keep a fixed order.
+
+Non-goals (from the issue): no full chat replay, no mutation of historical
+events, no unredacted tool-argument storage.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Iterable
+
+import control_plane_db
+from webui import console_redaction
+
+# The schema is versioned so consumers can branch on shape. Bump on any
+# breaking change to WorkflowEvent's serialized form.
+TIMELINE_SCHEMA_VERSION = 1
+
+# Known event sources and their deterministic ordering rank. When two events
+# carry the same timestamp, the source rank breaks the tie before the
+# per-source event key, so a control-plane event and a handoff comment minted
+# in the same second always sort in a fixed order.
+SOURCE_CONTROL_PLANE = "control_plane"
+SOURCE_GITEA_HANDOFF = "gitea_handoff"
+_SOURCE_RANK = {
+    SOURCE_CONTROL_PLANE: 0,
+    SOURCE_GITEA_HANDOFF: 1,
+}
+
+# A timestamp far in the future so events with no parseable timestamp sort
+# last (after everything real) instead of first, without raising.
+_MISSING_TS_SORT = "9999-12-31T23:59:59Z"
+
+
+def _parse_ts(value: str | None) -> str | None:
+    """Normalise a timestamp to ``...Z`` UTC, or None when unparseable."""
+    if not value:
+        return None
+    text = str(value).strip()
+    if not text:
+        return None
+    candidate = text[:-1] + "+00:00" if text.endswith("Z") else text
+    try:
+        parsed = datetime.fromisoformat(candidate)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _redact(value: Any) -> Any:
+    """Redact a single free-text field, failing closed to the placeholder."""
+    if value is None:
+        return None
+    return console_redaction.redact_text(str(value))
+
+
+@dataclass(frozen=True)
+class WorkflowEvent:
+    """One normalised timeline event.
+
+    Every field is optional except ``source``/``event_type``/``event_key``
+    because sources carry different subsets. The class is frozen so an adapted
+    event is an immutable record; a consumer that needs a variant builds a new
+    one rather than mutating history.
+    """
+
+    source: str
+    event_type: str
+    event_key: str
+    timestamp: str | None = None
+    actor: str | None = None
+    role: str | None = None
+    issue_number: int | None = None
+    pr_number: int | None = None
+    session_id: str | None = None
+    tool_name: str | None = None
+    decision: str | None = None
+    message: str | None = None
+    correlation_id: str | None = None
+    evidence_refs: tuple[str, ...] = ()
+    sensitive: bool = False
+
+    def sort_key(self) -> tuple[str, int, str]:
+        return (
+            self.timestamp or _MISSING_TS_SORT,
+            _SOURCE_RANK.get(self.source, 99),
+            self.event_key,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source": self.source,
+            "event_type": self.event_type,
+            "event_key": self.event_key,
+            "timestamp": self.timestamp,
+            "actor": self.actor,
+            "role": self.role,
+            "issue_number": self.issue_number,
+            "pr_number": self.pr_number,
+            "session_id": self.session_id,
+            "tool_name": self.tool_name,
+            "decision": self.decision,
+            "message": self.message,
+            "correlation_id": self.correlation_id,
+            "evidence_refs": list(self.evidence_refs),
+            "sensitive": self.sensitive,
+        }
+
+
+# --------------------------------------------------------------------------- #
+# Adapters — pure functions from a source's raw records to WorkflowEvents.     #
+# Each is total: a malformed record is skipped, never raised on.               #
+# --------------------------------------------------------------------------- #
+
+# Event types whose payload is treated as sensitive and always redaction-hard
+# (they can carry lease/session provenance or tool arguments).
+_SENSITIVE_EVENT_HINTS = ("lease", "capability", "token", "auth", "secret")
+
+# Reference tokens (issue/PR/comment ids) and SHAs parsed out of proof text.
+_EVIDENCE_REF_RE = re.compile(r"(?:#|PR\s*#?|issue\s*#?|comment\s*#?)(\d+)", re.IGNORECASE)
+_SHA_RE = re.compile(r"\b[0-9a-f]{7,40}\b")
+
+
+def _kind_to_numbers(kind: str | None, number: int | None) -> tuple[int | None, int | None]:
+    """Map a control-plane work-item (kind, number) to (issue_no, pr_no)."""
+    if number is None:
+        return (None, None)
+    if kind == "pr":
+        return (None, int(number))
+    if kind == "issue":
+        return (int(number), None)
+    return (None, None)
+
+
+def _correlation_for(kind: str | None, number: int | None) -> str | None:
+    if number is None or kind not in ("issue", "pr"):
+        return None
+    return f"{kind}#{number}"
+
+
+def _extract_evidence_refs(*texts: str | None) -> tuple[str, ...]:
+    refs: list[str] = []
+    for text in texts:
+        if not text:
+            continue
+        for match in _EVIDENCE_REF_RE.finditer(text):
+            token = f"#{match.group(1)}"
+            if token not in refs:
+                refs.append(token)
+        for match in _SHA_RE.finditer(text):
+            token = match.group(0)
+            if token not in refs:
+                refs.append(token)
+    return tuple(refs)
+
+
+def adapt_cp_events(rows: Iterable[dict[str, Any]]) -> list[WorkflowEvent]:
+    """Adapt control-plane ``events`` rows (joined to work_items) into events.
+
+    Each row is expected to carry ``event_id``, ``event_type``, ``message``,
+    ``created_at`` and the joined work-item ``kind``/``number``. Rows missing
+    an id or type are skipped so a partially written table never raises.
+    """
+    events: list[WorkflowEvent] = []
+    for row in rows or []:
+        try:
+            event_id = row.get("event_id")
+            event_type = (row.get("event_type") or "").strip()
+            if event_id is None or not event_type:
+                continue
+            kind = row.get("kind")
+            number = row.get("number")
+            issue_no, pr_no = _kind_to_numbers(kind, number)
+            sensitive = any(hint in event_type.lower() for hint in _SENSITIVE_EVENT_HINTS)
+            events.append(
+                WorkflowEvent(
+                    source=SOURCE_CONTROL_PLANE,
+                    event_type=event_type,
+                    event_key=f"cp:{event_id}",
+                    timestamp=_parse_ts(row.get("created_at")),
+                    issue_number=issue_no,
+                    pr_number=pr_no,
+                    session_id=(row.get("session_id") or None),
+                    message=_redact(row.get("message")),
+                    correlation_id=_correlation_for(kind, number),
+                    sensitive=sensitive,
+                )
+            )
+        except Exception:
+            # A single malformed row must not sink the whole adaptation.
+            continue
+    return events
+
+
+def adapt_cth_comments(
+    comments: Iterable[dict[str, Any]],
+    *,
+    kind: str,
+    number: int,
+) -> list[WorkflowEvent]:
+    """Adapt Gitea Canonical Thread Handoff (CTH) comments into events.
+
+    Only comments that parse as a CTH (``canonical_thread_handoff.parse_cth_comment``)
+    become events; ordinary comments are ignored. ``kind``/``number`` scope the
+    events to the issue or PR the comments belong to.
+    """
+    # Imported lazily so this module has no import-time dependency on the
+    # handoff parser when only the control-plane adapter is used.
+    from canonical_thread_handoff import parse_cth_comment
+
+    issue_no, pr_no = _kind_to_numbers(kind, number)
+    correlation = _correlation_for(kind, number)
+    events: list[WorkflowEvent] = []
+    for comment in comments or []:
+        try:
+            body = comment.get("body") or ""
+            parsed = parse_cth_comment(body)
+            if not parsed:
+                continue
+            fields = parsed.get("fields") or {}
+            cth_type = parsed.get("cth_type") or "handoff"
+            comment_id = comment.get("id")
+            actor = (comment.get("user") or {}).get("login")
+            decision = fields.get("decision")
+            proof = fields.get("proof")
+            next_action = fields.get("next action")
+            events.append(
+                WorkflowEvent(
+                    source=SOURCE_GITEA_HANDOFF,
+                    event_type=f"handoff:{cth_type}",
+                    event_key=f"cth:{kind}:{number}:{comment_id}",
+                    timestamp=_parse_ts(comment.get("created_at")),
+                    actor=actor,
+                    role=_redact(fields.get("next owner")),
+                    issue_number=issue_no,
+                    pr_number=pr_no,
+                    decision=_redact(decision),
+                    message=_redact(next_action or fields.get("status")),
+                    correlation_id=correlation,
+                    evidence_refs=_extract_evidence_refs(proof, decision),
+                    sensitive=False,
+                )
+            )
+        except Exception:
+            continue
+    return events
+
+
+# --------------------------------------------------------------------------- #
+# Read-only control-plane event source.                                       #
+# --------------------------------------------------------------------------- #
+
+_CP_EVENTS_QUERY = """
+SELECT e.event_id   AS event_id,
+       e.event_type AS event_type,
+       e.message    AS message,
+       e.created_at AS created_at,
+       w.kind       AS kind,
+       w.number     AS number
+FROM events e
+JOIN work_items w ON e.work_item_id = w.work_item_id
+WHERE w.remote = ? AND w.org = ? AND w.repo = ?
+"""
+
+
+@dataclass(frozen=True)
+class SourceStatus:
+    """Fail-soft status for one timeline source."""
+
+    name: str
+    ok: bool
+    reason: str | None = None
+    count: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"name": self.name, "ok": self.ok, "reason": self.reason, "count": self.count}
+
+
+def read_cp_events(
+    *,
+    remote: str,
+    org: str,
+    repo: str,
+    db_path: str | None = None,
+) -> tuple[list[WorkflowEvent], SourceStatus]:
+    """Read scoped control-plane events read-only. Never creates the DB.
+
+    Opens the SQLite file through a ``mode=ro`` URI: a health/timeline read
+    must never create directories or run the schema migration that
+    ``ControlPlaneDB()`` performs on construction. A missing or unreadable DB
+    degrades to a status with a reason.
+    """
+    path = (db_path or control_plane_db.default_db_path()).strip()
+    conn: sqlite3.Connection | None = None
+    try:
+        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+        conn.row_factory = sqlite3.Row
+        cursor = conn.execute(_CP_EVENTS_QUERY, (remote, org, repo))
+        rows = [dict(r) for r in cursor.fetchall()]
+    except sqlite3.OperationalError as exc:
+        return ([], SourceStatus(SOURCE_CONTROL_PLANE, ok=False, reason=f"control-plane DB unavailable: {exc}"))
+    except sqlite3.Error as exc:
+        return ([], SourceStatus(SOURCE_CONTROL_PLANE, ok=False, reason=f"control-plane read failed: {exc}"))
+    finally:
+        if conn is not None:
+            conn.close()
+    events = adapt_cp_events(rows)
+    return (events, SourceStatus(SOURCE_CONTROL_PLANE, ok=True, count=len(events)))
+
+
+# --------------------------------------------------------------------------- #
+# Filter, sort, paginate.                                                     #
+# --------------------------------------------------------------------------- #
+
+
+def filter_events(
+    events: Iterable[WorkflowEvent],
+    *,
+    issue: int | None = None,
+    pr: int | None = None,
+    session: str | None = None,
+) -> list[WorkflowEvent]:
+    """Filter events by issue number, PR number, and/or session id.
+
+    Filters are conjunctive. A filter that names a dimension an event does not
+    carry excludes that event (an issue filter excludes PR-only events).
+    """
+    out: list[WorkflowEvent] = []
+    for ev in events:
+        if issue is not None and ev.issue_number != issue:
+            continue
+        if pr is not None and ev.pr_number != pr:
+            continue
+        if session is not None and ev.session_id != session:
+            continue
+        out.append(ev)
+    return out
+
+
+def sort_events(events: Iterable[WorkflowEvent]) -> list[WorkflowEvent]:
+    """Return events in stable timeline order (ascending)."""
+    return sorted(events, key=lambda ev: ev.sort_key())
+
+
+@dataclass(frozen=True)
+class TimelinePage:
+    """One page of the sorted, filtered timeline."""
+
+    events: tuple[WorkflowEvent, ...]
+    total: int
+    limit: int
+    offset: int
+
+    @property
+    def next_offset(self) -> int | None:
+        nxt = self.offset + len(self.events)
+        return nxt if nxt < self.total else None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "events": [ev.to_dict() for ev in self.events],
+            "pagination": {
+                "total": self.total,
+                "limit": self.limit,
+                "offset": self.offset,
+                "returned": len(self.events),
+                "next_offset": self.next_offset,
+                "has_more": self.next_offset is not None,
+            },
+        }
+
+
+_MAX_LIMIT = 500
+_DEFAULT_LIMIT = 50
+
+
+def _coerce_bounds(limit: int | None, offset: int | None) -> tuple[int, int]:
+    try:
+        lim = int(limit) if limit is not None else _DEFAULT_LIMIT
+    except (TypeError, ValueError):
+        lim = _DEFAULT_LIMIT
+    try:
+        off = int(offset) if offset is not None else 0
+    except (TypeError, ValueError):
+        off = 0
+    lim = max(1, min(lim, _MAX_LIMIT))
+    off = max(0, off)
+    return (lim, off)
+
+
+def paginate(events: list[WorkflowEvent], *, limit: int | None, offset: int | None) -> TimelinePage:
+    lim, off = _coerce_bounds(limit, offset)
+    window = events[off : off + lim]
+    return TimelinePage(events=tuple(window), total=len(events), limit=lim, offset=off)
+
+
+# --------------------------------------------------------------------------- #
+# Composition — load_timeline aggregates all sources, fail-soft.              #
+# --------------------------------------------------------------------------- #
+
+# A comment source is a callable that, given (kind, number), returns the raw
+# Gitea comment list for that issue/PR. The route supplies a live fail-soft
+# fetcher; tests supply a fixture. When None, the handoff source is reported as
+# not-run (never silently empty-and-healthy).
+CommentSource = Callable[[str, int], list[dict[str, Any]]]
+
+
+@dataclass(frozen=True)
+class TimelineSnapshot:
+    schema_version: int
+    remote: str
+    org: str
+    repo: str
+    filters: dict[str, Any]
+    page: TimelinePage
+    sources: tuple[SourceStatus, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "scope": {"remote": self.remote, "org": self.org, "repo": self.repo},
+            "filters": self.filters,
+            "sources": [s.to_dict() for s in self.sources],
+            **self.page.to_dict(),
+        }
+
+
+def load_timeline(
+    *,
+    remote: str,
+    org: str,
+    repo: str,
+    issue: int | None = None,
+    pr: int | None = None,
+    session: str | None = None,
+    limit: int | None = None,
+    offset: int | None = None,
+    db_path: str | None = None,
+    comment_source: CommentSource | None = None,
+) -> TimelineSnapshot:
+    """Aggregate every timeline source into one filtered, paginated snapshot.
+
+    Sources are read independently and fail soft: an unavailable source
+    contributes a ``SourceStatus`` with ``ok=False`` and a reason, and never
+    collapses the whole timeline. The handoff source only runs when a specific
+    issue or PR is requested (a handoff comment belongs to one thread) and a
+    ``comment_source`` is available; otherwise it is reported as ``not run``
+    rather than as an empty-and-healthy source.
+    """
+    all_events: list[WorkflowEvent] = []
+    statuses: list[SourceStatus] = []
+
+    cp_events, cp_status = read_cp_events(remote=remote, org=org, repo=repo, db_path=db_path)
+    all_events.extend(cp_events)
+    statuses.append(cp_status)
+
+    # Gitea handoff comments are thread-scoped: only fetch when the caller
+    # narrowed to one issue or PR, and only when a source was provided.
+    handoff_target: tuple[str, int] | None = None
+    if pr is not None:
+        handoff_target = ("pr", pr)
+    elif issue is not None:
+        handoff_target = ("issue", issue)
+
+    if handoff_target is None:
+        statuses.append(
+            SourceStatus(
+                SOURCE_GITEA_HANDOFF,
+                ok=False,
+                reason="not run: handoff comments are thread-scoped; filter by issue or pr to include them",
+            )
+        )
+    elif comment_source is None:
+        statuses.append(
+            SourceStatus(
+                SOURCE_GITEA_HANDOFF,
+                ok=False,
+                reason="not run: no comment source configured for this timeline read",
+            )
+        )
+    else:
+        kind, number = handoff_target
+        try:
+            comments = comment_source(kind, number) or []
+            handoff_events = adapt_cth_comments(comments, kind=kind, number=number)
+            all_events.extend(handoff_events)
+            statuses.append(SourceStatus(SOURCE_GITEA_HANDOFF, ok=True, count=len(handoff_events)))
+        except Exception as exc:  # fail soft: a fetch/parse error degrades this source only
+            statuses.append(
+                SourceStatus(SOURCE_GITEA_HANDOFF, ok=False, reason=f"handoff source failed: {exc}")
+            )
+
+    filtered = filter_events(all_events, issue=issue, pr=pr, session=session)
+    ordered = sort_events(filtered)
+    page = paginate(ordered, limit=limit, offset=offset)
+
+    return TimelineSnapshot(
+        schema_version=TIMELINE_SCHEMA_VERSION,
+        remote=remote,
+        org=org,
+        repo=repo,
+        filters={"issue": issue, "pr": pr, "session": session},
+        page=page,
+        sources=tuple(statuses),
+    )
+
+
+def snapshot_to_dict(snapshot: TimelineSnapshot) -> dict[str, Any]:
+    return snapshot.to_dict()