openplan-mcp 0.8.2__tar.gz

openplan_mcp-0.8.2/.dockerignore

@@ -0,0 +1,8 @@
+__pycache__
+*.pyc
+.env
+.git
+.gitignore
+*.db
+tests/
+scripts/

openplan_mcp-0.8.2/.github/workflows/deploy.yml

@@ -0,0 +1,18 @@
+name: Deploy API
+on:
+  push:
+    branches: [main]
+    paths:
+      - "services/**"
+      - "Dockerfile"
+      - "fly.toml"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      - run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

openplan_mcp-0.8.2/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environment
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Database
+*.db
+*.db-wal
+*.db-shm
+openplan.db
+backups/
+
+# Pytest
+.pytest_cache/
+
+# Environment
+.env
+.env.local
+
+# OpenCode
+.opencode/

openplan_mcp-0.8.2/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## 0.7.0 (2026-06-15)
+
+- Evidence filesystem verification: `verify` now stats file URIs to confirm existence. Missing files get `status=unverified` instead of `verified`. Metadata (size, mtime) recorded per evidence.
+- Sequential defaults: `options` on `act()` auto-sequences items (0→1→2→...) instead of creating flat siblings. Use `parallel=true` for explicit fan-out. The `sequence` field becomes an order override, not the only way to chain.
+- Test coverage: 3 new tests for evidence stat verification (existing file, missing file, metadata). 162 total.
+
+## 0.6.0 (2026-06-14)
+
+- Sequential options: `options` on `act()` now support `sequence` field to create ordered DAG chains instead of flat siblings.
+- Auto-check goal markers on state completion: setting status="done" automatically checks state labels against unachieved goal criteria.
+- `project_complete: true` flag in `recommend()` output when all goal markers are achieved.
+- Fix: Inverted goal-evidence matching — `verify` now correctly checks `description LIKE '%criterion%'` instead of `criterion LIKE '%description%'`.
+- Fix: Version triplication — single source of truth via `openplan.__init__.VERSION`.
+- Fix: Removed dead `detail` parameter from `act` tool definition.
+- Fix: goal_satisfied in act() now requires ALL markers achieved, not just any single one.
+- Fix: export tool missing from MCP tool listing — now listed as 4th official tool.
+- Tests: 6 new tests for goal markers, evidence matching, sequential options, version consistency.
+
+## 0.5.0 (2026-06-14)
+
+- Goal markers: goals parsed into achievement criteria, tracked in `goal_markers` table.
+- Evidence layer: structured evidence items (file, commit, test, verification) attachable to states.
+- `verify` action: attach evidence, auto-match against goal markers.
+- Cursor fix: `abandon()` moves cursor to nearest active ancestor instead of getting stuck.
+- Prompt cleanup: all 4 prompts rewritten to reference only existing tools.
+- New recommend modes: `plan`, `retro`, `learnings`.
+
+## 0.1.0 (2026-06-11)
+
+- Initial release.
+- State space navigation model with activation heuristic.
+- 10 MCP tools: init, observe, act, branch, plan, learn, diagnostics, export, project_list, compress.
+- A* pathfinding with bimodal heuristic (cross-cluster via embeddings, within-cluster via min cost).
+- Self-calibrating edge weights via learn tool.
+- Embedding similarity search via fastembed (optional).
+- ANN vector search via sqlite-vec (optional).
+- RW lock for concurrent read/serialized write.
+- Session tracking via OPENCODE_SESSION_ID env var.
+- Idempotency keys on all events.
+- Cycle detection on every act() transition.
+- FTS5 full-text search with AFTER UPDATE trigger.
+- Event archival and orphan state merging (compress tool).
+- 55 tests across all tools and scales.

openplan_mcp-0.8.2/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.14-slim
+
+WORKDIR /app
+
+COPY services/telemetry/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8080
+
+CMD ["python3", "run_api.py"]

openplan_mcp-0.8.2/HANDOFF.md

@@ -0,0 +1,54 @@
+# OpenPlan v0.7.0 — Session Handoff
+
+**Date:** 2026-06-15
+**Next session should read this first.**
+
+## What Changed (v0.7.0)
+
+### Evidence Filesystem Verification
+`verify` now stats file URIs to confirm they actually exist on disk before marking them verified:
+- File found → `status = 'verified'`, metadata recorded (size, mtime)
+- File missing → `status = 'unverified'`, error stored in metadata
+- Only `type: "file"` evidence is stat'd; other types (commit, test, checkpoint) remain `verified`
+- The goal-marker matching loop already filters on `status = 'verified'`, so only real files trigger goal achievement
+
+### Sequential Defaults for Branch Options
+Options now auto-sequence by default:
+```
+act(options=[{label: A}, {label: B}, {label: C}])
+# v0.6.0: root → A, root → B, root → C  (flat, depth=1)
+# v0.7.0: root → A → B → C               (chain, depth=3)
+```
+Use `parallel: true` for flat siblings (old default):
+```
+act(options=[{label: A}, {label: B}, {label: C}], parallel=true)
+# root → A, root → B, root → C  (flat)
+```
+The `sequence` field overrides positioning within the chain.
+
+## Files Changed
+
+| File | What |
+|------|------|
+| `server.py:345-367` | Stat evidence URIs on verify; conditional status; metadata JSON |
+| `db/schema.py:165` | New `metadata TEXT DEFAULT '{}'` column on evidence table |
+| `db/schema.py:174-176` | ALTER TABLE migration for existing databases |
+| `core/state.py:594-614` | Auto-sequence when no `sequence` fields and not `parallel` |
+| `tools/definitions.py:68` | Added `parallel` param; updated options description |
+| `server.py:295` | Pass `parallel` from args to `branch()` |
+| `tests/test_act.py` | +3 evidence stat tests (existing, missing, metadata) |
+| `tests/test_diagnostics.py` | Updated flat tree assertions; new `test_diagnostics_parallel_tree` |
+
+## Quick Commands
+
+```bash
+.venv/bin/pip install -e ".[dev]"         # reinstall after changes
+.venv/bin/python -m pytest tests/ -v      # 162 pass
+```
+
+## Next Priorities
+
+1. **Visible effective costs** — surface bandit-adjusted costs in recommend output instead of raw cost_tokens
+2. **Goal marker parser improvements** — handle more natural phrasing in goal text splitting
+3. **Multi-cursor** — one graph, multiple cursors per project for concurrent agents
+4. **Workflow state machines** — encode the agent loop as a state machine in the graph itself

openplan_mcp-0.8.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenPlan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openplan_mcp-0.8.2/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include CHANGELOG.md
+include LICENSE
+include pyproject.toml
+recursive-include src/openplan_v3 *.py
+recursive-include tests *.py

openplan_mcp-0.8.2/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: openplan-mcp
+Version: 0.8.2
+Summary: Waze for AI agents planning — MCP server that improves cost estimates by learning from every project
+Author: OpenPlan Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/anomalyco/opencode
+Project-URL: Documentation, https://opencode.ai/docs/openplan
+Project-URL: Source, https://github.com/anomalyco/opencode/tree/main/docs/workflow/openplan
+Project-URL: Changelog, https://github.com/anomalyco/opencode/blob/main/docs/workflow/openplan/CHANGELOG.md
+Keywords: mcp,planning,ai-agent,state-space,project-management,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2.0.0,>=1.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: httpx>=0.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Provides-Extra: embed
+Requires-Dist: fastembed>=0.5.0; extra == "embed"
+Provides-Extra: ann
+Requires-Dist: sqlite-vec>=0.1.9; extra == "ann"
+Provides-Extra: all
+Requires-Dist: openplan[ann,dev,embed]; extra == "all"
+Dynamic: license-file
+
+# OpenPlan
+
+**AI-native state space planner. MCP server. Python. 4 tools.**
+
+OpenPlan is an MCP server that gives AI agents a structured planning and memory system. Instead of tasks and milestones, everything is a **state** in a directed graph with probabilistic edges, auto-calibrating costs, and A* pathfinding that tells the agent where to go next.
+
+## Tools (4)
+
+`init` — Create a new project context (idempotent). Accepts `project_type` for cost baselines and `goal` for tracked achievement markers.
+
+`act` — The only mutation tool. Traverses edges, creates branches (auto-sequenced by default, `parallel=True` for fan-out), sets status, attaches evidence (with filesystem verification), prunes subtrees, reverts, and verifies goal satisfaction.
+
+`recommend` — Returns the best next target with an A* path, confidence intervals, effective costs, project health, goal progress, cross-project estimation by type, and self-tuning bandit state.
+
+`export` — Export the full graph as JSON, GraphML, or adjacency matrix.
+
+## Quick Start
+
+```bash
+pip install -e ".[dev]"
+
+# Start the MCP server
+openplan-server
+```
+
+Configure MCP in your opencode.json / claude_desktop_config.json:
+
+```json
+{
+  "mcp": {
+    "openplan": {
+      "type": "local",
+      "command": ["/path/to/.venv/bin/python", "-m", "openplan.server"],
+      "cwd": "/path/to/openplan"
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+  MCP transport (stdio)
+       │
+  server.py (dispatch)
+  ┌──────┴──────┐
+  core/         db/
+  ├─ state.py   ├─ connection.py
+  ├─ graph.py   ├─ schema.py
+  ├─ planner.py ├─ ...
+  ├─ activation.py
+  ├─ embedding.py
+  ├─ export.py
+  ├─ recommend.py
+  ├─ telemetry.py
+  └─ maintenance.py
+```
+
+**Shell imports core. Core never imports shell.**
+SQLite with WAL mode, foreign keys, savepoints. RW lock for concurrency.
+
+## Data Model
+
+```
+nodes:    id, label, activation, frontier, project, props, parent_id, status, project_type
+edges:    source_id, target_id, action, cost_tokens, cost_risk, prob, weight_history
+events:   id, project, node_id, event_type, payload, version, idempotency_key, session_id
+goal_markers: project, criterion, achieved, achieved_by
+evidence: id, project, state_id, evidence_type, uri, status, metadata (size, mtime)
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## License
+
+MIT

openplan_mcp-0.8.2/README.md

@@ -0,0 +1,81 @@
+# OpenPlan
+
+**AI-native state space planner. MCP server. Python. 4 tools.**
+
+OpenPlan is an MCP server that gives AI agents a structured planning and memory system. Instead of tasks and milestones, everything is a **state** in a directed graph with probabilistic edges, auto-calibrating costs, and A* pathfinding that tells the agent where to go next.
+
+## Tools (4)
+
+`init` — Create a new project context (idempotent). Accepts `project_type` for cost baselines and `goal` for tracked achievement markers.
+
+`act` — The only mutation tool. Traverses edges, creates branches (auto-sequenced by default, `parallel=True` for fan-out), sets status, attaches evidence (with filesystem verification), prunes subtrees, reverts, and verifies goal satisfaction.
+
+`recommend` — Returns the best next target with an A* path, confidence intervals, effective costs, project health, goal progress, cross-project estimation by type, and self-tuning bandit state.
+
+`export` — Export the full graph as JSON, GraphML, or adjacency matrix.
+
+## Quick Start
+
+```bash
+pip install -e ".[dev]"
+
+# Start the MCP server
+openplan-server
+```
+
+Configure MCP in your opencode.json / claude_desktop_config.json:
+
+```json
+{
+  "mcp": {
+    "openplan": {
+      "type": "local",
+      "command": ["/path/to/.venv/bin/python", "-m", "openplan.server"],
+      "cwd": "/path/to/openplan"
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+  MCP transport (stdio)
+       │
+  server.py (dispatch)
+  ┌──────┴──────┐
+  core/         db/
+  ├─ state.py   ├─ connection.py
+  ├─ graph.py   ├─ schema.py
+  ├─ planner.py ├─ ...
+  ├─ activation.py
+  ├─ embedding.py
+  ├─ export.py
+  ├─ recommend.py
+  ├─ telemetry.py
+  └─ maintenance.py
+```
+
+**Shell imports core. Core never imports shell.**
+SQLite with WAL mode, foreign keys, savepoints. RW lock for concurrency.
+
+## Data Model
+
+```
+nodes:    id, label, activation, frontier, project, props, parent_id, status, project_type
+edges:    source_id, target_id, action, cost_tokens, cost_risk, prob, weight_history
+events:   id, project, node_id, event_type, payload, version, idempotency_key, session_id
+goal_markers: project, criterion, achieved, achieved_by
+evidence: id, project, state_id, evidence_type, uri, status, metadata (size, mtime)
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## License
+
+MIT

openplan_mcp-0.8.2/fly.toml

@@ -0,0 +1,16 @@
+app = "openplan-api"
+primary_region = "iad"
+
+[build]
+  dockerfile = "Dockerfile"
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = false
+  min_machines_running = 1
+
+[[vm]]
+  cpu_kind = "shared"
+  cpus = 1
+  memory_mb = 512

openplan_mcp-0.8.2/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openplan-mcp"
+version = "0.8.2"
+description = "Waze for AI agents planning — MCP server that improves cost estimates by learning from every project"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "OpenPlan Contributors"},
+]
+keywords = ["mcp", "planning", "ai-agent", "state-space", "project-management", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.0.0,<2.0.0",
+    "numpy>=1.24.0",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "ruff>=0.5.0"]
+embed = ["fastembed>=0.5.0"]
+ann = ["sqlite-vec>=0.1.9"]
+all = ["openplan[embed,ann,dev]"]
+
+[project.urls]
+Homepage = "https://github.com/anomalyco/opencode"
+Documentation = "https://opencode.ai/docs/openplan"
+Source = "https://github.com/anomalyco/opencode/tree/main/docs/workflow/openplan"
+Changelog = "https://github.com/anomalyco/opencode/blob/main/docs/workflow/openplan/CHANGELOG.md"
+
+[project.scripts]
+openplan = "openplan.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["openplan*"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 110
+
+[tool.pytest.ini_options]
+markers = [
+    "slow: performance benchmarks that create 5k+ nodes",
+]
+testpaths = ["tests"]

openplan_mcp-0.8.2/run_api.py

@@ -0,0 +1,11 @@
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from services.telemetry.main import app
+
+if __name__ == "__main__":
+    import uvicorn
+    port = int(os.environ.get("PORT", 8080))
+    uvicorn.run(app, host="0.0.0.0", port=port)

openplan_mcp-0.8.2/scripts/telemetry_server.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+OpenPlan Telemetry Server — stdlib-only, single-file, zero dependencies.
+
+Usage:
+    python scripts/telemetry_server.py [--port PORT] [--db DB_PATH]
+
+Routes:
+    POST /telemetry  — accepts {"events": [{project_type, action, expected_cost, actual_cost, outcome}, ...]}
+    GET  /calibration — returns {"baselines": [{project_type, action, cost_tokens, sample_count}, ...]}
+    GET  /health     — returns {"ok": true, "events_count": N}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import sys
+import time
+import urllib.parse
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from typing import Any
+
+DB_PATH = os.environ.get("TELEMETRY_DB", "telemetry.db")
+
+
+def init_db(conn: sqlite3.Connection) -> None:
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS calibration_events (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            project_type TEXT NOT NULL DEFAULT '',
+            action TEXT NOT NULL,
+            expected_cost REAL,
+            actual_cost REAL NOT NULL,
+            outcome TEXT NOT NULL DEFAULT 'success',
+            session_id TEXT NOT NULL DEFAULT '',
+            created_at REAL NOT NULL
+        )
+    """)
+    conn.execute("""
+        CREATE INDEX IF NOT EXISTS idx_calibration_lookup
+        ON calibration_events (project_type, action, created_at)
+    """)
+    conn.commit()
+
+
+def record_event(conn: sqlite3.Connection, event: dict[str, Any]) -> None:
+    conn.execute(
+        "INSERT INTO calibration_events (project_type, action, expected_cost, actual_cost, outcome, session_id, created_at) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?)",
+        (
+            event.get("project_type", ""),
+            event.get("action", ""),
+            event.get("expected_cost"),
+            event.get("actual_cost", 0),
+            event.get("outcome", "success"),
+            event.get("session_id", ""),
+            event.get("timestamp", time.time()),
+        ),
+    )
+
+
+def get_calibration(conn: sqlite3.Connection) -> list[dict[str, Any]]:
+    rows = conn.execute("""
+        SELECT
+            project_type,
+            action,
+            COUNT(*) AS sample_count,
+            AVG(actual_cost) AS cost_tokens
+        FROM calibration_events
+        WHERE actual_cost IS NOT NULL AND actual_cost > 0
+        GROUP BY project_type, action
+        HAVING sample_count >= 3
+        ORDER BY sample_count DESC
+    """).fetchall()
+    return [
+        {"project_type": r["project_type"], "action": r["action"],
+         "cost_tokens": round(r["cost_tokens"], 2), "sample_count": r["sample_count"]}
+        for r in rows
+    ]
+
+
+def get_health(conn: sqlite3.Connection) -> dict[str, Any]:
+    row = conn.execute("SELECT COUNT(*) AS cnt FROM calibration_events").fetchone()
+    return {"ok": True, "events_count": row["cnt"] if row else 0}
+
+
+class TelemetryHandler(BaseHTTPRequestHandler):
+    conn: sqlite3.Connection = None  # type: ignore[assignment]
+
+    def _respond(self, code: int, data: dict[str, Any]) -> None:
+        body = json.dumps(data).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_OPTIONS(self) -> None:
+        self.send_response(204)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type")
+        self.end_headers()
+
+    def do_GET(self) -> None:
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path == "/calibration":
+            baselines = get_calibration(self.conn)
+            self._respond(200, {"baselines": baselines})
+        elif parsed.path == "/health":
+            health = get_health(self.conn)
+            self._respond(200, health)
+        else:
+            self._respond(404, {"error": "not found"})
+
+    def do_POST(self) -> None:
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/telemetry":
+            self._respond(404, {"error": "not found"})
+            return
+        length = int(self.headers.get("Content-Length", 0))
+        if not length:
+            self._respond(400, {"error": "empty body"})
+            return
+        try:
+            body = json.loads(self.rfile.read(length))
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            self._respond(400, {"error": "invalid JSON"})
+            return
+        events = body if isinstance(body, list) else body.get("events", [body])
+        count = 0
+        for ev in events:
+            if ev.get("actual_cost") is not None:
+                record_event(self.conn, ev)
+                count += 1
+        self.conn.commit()
+        self._respond(200, {"ok": True, "accepted": count})
+
+    def log_message(self, fmt: str, *args: Any) -> None:
+        timestamp = time.strftime("%H:%M:%S")
+        sys.stderr.write(f"[{timestamp}] {args[0]} {args[1]} {args[2]}\n")
+
+
+def main() -> None:
+    port = int(sys.argv[sys.argv.index("--port") + 1]) if "--port" in sys.argv else int(os.environ.get("PORT", 8888))
+    db = sys.argv[sys.argv.index("--db") + 1] if "--db" in sys.argv else DB_PATH
+
+    conn = sqlite3.connect(db, check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    init_db(conn)
+
+    TelemetryHandler.conn = conn
+    server = HTTPServer(("0.0.0.0", port), TelemetryHandler)
+
+    print(f"telemetry endpoint listening on http://0.0.0.0:{port}")
+    print(f"  POST /telemetry  — submit calibration events")
+    print(f"  GET  /calibration — get aggregated baselines")
+    print(f"  GET  /health       — server status")
+    print(f"  DB: {db}")
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nshutting down")
+        server.server_close()
+        conn.close()
+
+
+if __name__ == "__main__":
+    main()