orc-hestrator-server 2.0.0__py3-none-any.whl

orc_hestrator_server-2.0.0.dist-info/METADATA

@@ -0,0 +1,302 @@
+Metadata-Version: 2.5
+Name: orc-hestrator-server
+Version: 2.0.0
+Summary: MCP server for AI agent work management — persistent work item graph for AI agents
+Project-URL: Homepage, https://github.com/filhocf/orc-hestrator
+Project-URL: Repository, https://github.com/filhocf/orc-hestrator
+Author: Claudio Ferreira Filho
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,mcp,task-management,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: croniter>=2.0.0
+Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Provides-Extra: ui
+Requires-Dist: fastapi>=0.115.0; extra == 'ui'
+Requires-Dist: jinja2>=3.1.0; extra == 'ui'
+Requires-Dist: python-multipart>=0.0.9; extra == 'ui'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'ui'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/orc-logo.png" alt="Orc[hestrator]" width="260">
+</p>
+
+<h1 align="center">Orc[hestrator]</h1>
+
+<p align="center"><strong>The shared work board for humans and AI agents.</strong><br>
+One source of truth for what is being worked on, by whom, right now — enforced by the server,
+not by the operator's discipline.</p>
+
+[![PyPI](https://img.shields.io/pypi/v/orc-hestrator-server)](https://pypi.org/project/orc-hestrator-server/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/filhocf/orc-hestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/filhocf/orc-hestrator/actions/workflows/ci.yml)
+
+Orc[hestrator] is an MCP server that keeps the work of a team of AI agents and their human
+in one place. Agents read and write it over MCP; the human reads and intervenes through a web
+UI. The state lives in a single SQLite database on one host, so switching machines, restarting
+a session, or running three agents in parallel does not fork reality.
+
+Distribution: `orc-hestrator-server` on PyPI, commands `orc`, `orc-mcp`, `orc-serve` and `orc-ui`, site [orc-hestrator.dev](https://orc-hestrator.dev).
+Formerly published as `task-orchestrator-py`.
+
+## The problem
+
+An AI agent forgets. Context compacts, the session ends, you open a different machine, and the
+agent no longer knows what was done, what is blocked, or what comes next. The usual answers do
+not survive contact with real work:
+
+- **Prompt-based reminders** disappear with the context window.
+- **A markdown or JSON task file** has no rules: nothing stops an agent from marking work done
+  that never ran, and two agents will happily pick the same task.
+- **A hosted issue tracker** is built for humans typing tickets. Its API can be called by an
+  agent, but nothing in it is designed for agents as first-class actors.
+
+So you end up being the router: retyping state, reconciling boards, and noticing by accident
+that two machines implemented the same feature.
+
+## What Orc does
+
+- **Server-enforced workflow.** Items move `queue → work → review → done` through explicit
+  triggers. The server rejects an invalid transition; the client cannot skip a step.
+- **Dependencies that actually block.** Advancement waits for prerequisites, with cycle
+  detection and a configurable `unblock_at` threshold (unblock at review, not only at done).
+- **Gates as required notes.** A YAML schema declares which notes a phase requires. Missing
+  documentation blocks the transition, so "done" means something.
+- **Presence and claims across machines.** Every session registers as a triple
+  `hostname / agent_id / session_id`, heartbeats, and is reaped when it dies. Claims answer
+  "who is on this item or file right now" before two agents duplicate the work.
+- **Attribution per request.** `agent_id` is resolved per call
+  (argument → `X-Agent-ID` header → `MCP_AGENT_ID` → OAuth client id) and recorded on writes,
+  so the board can say who did what.
+- **One database, many clients.** Run it locally over stdio, or as a central HTTP service that
+  every machine and every agent points at.
+
+## Who it is for
+
+- **A developer running agent CLIs on more than one machine.** Continuity is the whole point:
+  the task you started on the laptop is the task the desktop agent picks up.
+- **A small team putting agents into the loop.** Two to ten people, several agents, and a need
+  to see who is doing what without a daily sync to rebuild the picture.
+- **Anyone who tried a task file and watched it drift.** If you have ever found two divergent
+  copies of the same plan, this is the fix.
+
+It is not a runtime orchestrator: Orc does not spawn or supervise agent processes. It is not a
+memory system either: memory stores facts, Orc stores the structure of work. They compose.
+
+## Quick start
+
+### Single machine, stdio
+
+```bash
+uvx orc-hestrator-server
+```
+
+Register it with any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "orc": {
+      "command": "uvx",
+      "args": ["orc-hestrator-server"],
+      "env": { "ORC_DB": "/path/to/tasks.db" }
+    }
+  }
+}
+```
+
+Without `ORC_DB` the database defaults to `~/.orc/tasks.db`. The previous name,
+`TASK_ORCHESTRATOR_DB`, still works as a fallback with a deprecation notice.
+
+### One server, many machines
+
+```bash
+# on the host that owns the database
+MCP_HOST=127.0.0.1 MCP_PORT=8005 \
+ORC_DB=~/.local/share/orc/tasks.db \
+uvx --from 'orc-hestrator-server[ui]' orc-serve
+```
+
+Then point every client at `http://<host>:8005/mcp`. The web UI is served from the same app
+(`/ui/`), and the REST API from `/api`. Put a TLS proxy in front: the UI and API use cookie
+sessions, and an initial admin is seeded from `ORC_ADMIN_USER` / `ORC_ADMIN_PASSWORD` on first
+boot when no user exists.
+
+The `[ui]` extra carries `fastapi` + `uvicorn`, which the HTTP transport needs; a plain install
+does not pull it in — hence `--from 'orc-hestrator-server[ui]'`. From a checkout the equivalent
+is `uv sync --extra ui` then `uv run orc-serve`.
+
+## Screens
+
+The management UI is a React app (Vite, TypeScript, Tailwind) with nine screens: login,
+overview, live team presence, kanban board, arc tree, dependency graph, task detail,
+users/RBAC, and profile.
+
+![Orc dashboard](frontend/screenshots/orc-dashboard.png)
+
+The screen that matters most is **live team presence**: which host, which agent, which session,
+on which item, right now.
+
+## How it compares
+
+| | Hosted issue trackers | Agent memory servers | Task file in the repo | Orc |
+|---|---|---|---|---|
+| Designed for agents as primary actors | No | Yes, for facts | No | Yes |
+| Workflow enforced by the server | Partly, configurable | Not applicable | No | Yes |
+| Blocks advancement on unmet dependencies | Sometimes | No | No | Yes |
+| Cross-machine single source of truth | Yes | Usually per host | No, it forks | Yes |
+| Presence and claims ("who is on this") | Human assignee only | No | No | Yes, with heartbeat |
+| Gates that require evidence | Paid tiers, human-driven | No | No | Yes |
+| Runs on your own box, one SQLite file | No | Yes | Yes | Yes |
+
+## The tools you will actually use
+
+Thirty-one tools exist; a normal session touches eight of them.
+
+| Tool | What it is for |
+|---|---|
+| `get_context` | Dashboard of the current state, or the detail of one item |
+| `get_next_item` | Highest-priority item with no unsatisfied dependency |
+| `manage_items` | Create, update, delete; batch and hierarchy |
+| `create_work_tree` | Root plus children plus dependency wiring in one call |
+| `advance_item` | Move an item through a trigger, with enforcement |
+| `manage_notes` | Phase notes, including the ones gates require |
+| `agent_register` / `agent_heartbeat` / `agent_end` | Presence lifecycle |
+| `claim` / `release` / `conflicts` | Take and free an item or a free-form resource |
+
+Full reference: [docs/TOOLS.md](docs/TOOLS.md). Seven MCP prompts ship with the server
+(`session_start`, `work_summary`, `quick_start`, `create_item_from_context`,
+`status_progression`, `dependency_manager`, `batch_complete`).
+
+## Workflow
+
+```
+          start         start         start
+  queue ────────→ work ────────→ review ────────→ done
+    │               │               │
+    │    block       │    block      │    block
+    └──────→ blocked ←──────────────┘
+                │
+                │  resume
+                └──────→ (previous status)
+
+  done/cancelled ──reopen──→ queue
+```
+
+Triggers: `start`, `complete`, `block`/`hold`, `resume`, `cancel`, `reopen`.
+
+Enforcement: dependencies must be satisfied before an item leaves `queue`; note-gate schemas are
+checked on every `start` and `complete`; reopening cascades to the parent when the parent is
+terminal.
+
+## Example
+
+```python
+create_work_tree(
+  root_title="User authentication",
+  children_json='[
+    {"ref": "schema", "title": "Design auth schema", "priority": "high"},
+    {"ref": "api",    "title": "Implement auth endpoints", "priority": "high"},
+    {"ref": "tests",  "title": "Write auth tests", "priority": "medium"}
+  ]',
+  deps_json='[
+    {"from": "schema", "to": "api"},
+    {"from": "api",    "to": "tests"}
+  ]'
+)
+
+agent_register(cli="hermes")            # presence: host/agent/session
+get_next_item()                         # -> "Design auth schema"
+claim(subject_type="work_item", subject_ref="a1b2", session_id="...")
+advance_item(item_id="a1b2", trigger="start")
+manage_notes(operation="upsert", item_id="a1b2", key="requirements", role="queue",
+             body="RS256, refresh tokens, 15 min access expiry")
+advance_item(item_id="a1b2", trigger="complete")
+# -> unblocked_items: ["Implement auth endpoints"]
+agent_end(session_id="...")             # releases the claim
+```
+
+## Architecture
+
+A thin MCP layer over a modular domain engine, SQLite with WAL, plus an optional web layer.
+
+```
+src/task_orchestrator/
+├── server.py        MCP tools (FastMCP) and per-request agent identity
+├── engine/          domain logic, one module per concern:
+│   ├── base, items, transitions, dependencies, notes, queries, trees
+│   ├── metrics, archive, portability, workspace_view
+│   └── presence, claims, users        coordination and access
+├── db.py            schema, additive migrations, FTS5
+├── schemas.py       note-gate schemas
+├── workspace.py     workspace configs
+├── web/             REST API (/api) and graph endpoints
+└── ui/              server-rendered board (FastAPI + HTMX)
+frontend/            React management UI (isolated from the Python tree)
+```
+
+Modules form a strict import DAG and `engine/` re-exports its public surface, so clients keep a
+stable `engine.X` interface. Design decisions are recorded in [docs/adr/](docs/adr/):
+central service, session registry incorporation, single-source-of-truth before hybrid,
+edge security, per-request agent identity.
+
+## Security
+
+- `/api/*` requires an authenticated user session except login, logout and `/health`.
+- Passwords use scrypt with a per-user salt; sessions are opaque tokens in an HTTP-only cookie
+  with server-side revocation; roles are `admin` and `user`.
+- MCP clients can add a second barrier: OAuth2 resource-server mode (`MCP_OAUTH_ENABLED`) verifies
+  opaque pre-shared tokens, behind the reverse proxy's basic auth.
+- The admin user is seeded from `ORC_ADMIN_USER` / `ORC_ADMIN_PASSWORD` on first boot.
+
+## Roadmap
+
+Shipped through 1.5.0: workflow engine, dependency graph with cycle detection, note-gate
+schemas, workspaces, metrics and graph analytics, scheduling, archive and checkpoints,
+export/import, central presence and claims, per-request attribution, REST API, user auth with
+RBAC, and the React management UI.
+
+Next, in rough order:
+
+| Area | Focus |
+|---|---|
+| Event ingestion | Git, CI and webhooks move items instead of a human remembering to |
+| Typed gates | Blocking predicates: CI status, coverage, approver role, no bypass |
+| Work-item types | First-class incident (`detect → mitigate → resolve → postmortem`) and spike flows |
+| Claim leases | TTL on claims so a dead agent does not hold an item forever |
+| Authoring UI | Create and edit items from the browser, not only from MCP |
+| Hybrid mode | Local primary with a central secondary, for offline work |
+
+## Origins
+
+Orc started as a Python port of [jpicklyk/task-orchestrator](https://github.com/jpicklyk/task-orchestrator)
+(Kotlin). It has since diverged: tags, batch operations, work trees, short hex ids, stale
+detection, structured errors, graph analytics, central presence, claims, attribution, and the
+web layer are Python-only. The Kotlin project deserves credit for the original design.
+
+## Contributing
+
+```bash
+git clone https://github.com/filhocf/orc-hestrator
+cd orc-hestrator
+uv sync --extra test --extra ui
+uv run pytest tests/ -q
+```
+
+Changes go to a branch and a PR against `main`. Product requirements live in
+[docs/PRD.md](docs/PRD.md); architecture in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## License
+
+[MIT](LICENSE)

orc_hestrator_server-2.0.0.dist-info/RECORD

@@ -0,0 +1,43 @@
+task_orchestrator/__init__.py,sha256=jPs0aALQshSz4KFQCcu2aTl0J4GurPh3s4J-52P36zM,95
+task_orchestrator/auth.py,sha256=e1Q9CaZ8pFx4wD1i2mcGpf9xiMxFB-hkvHOTxNt7gmo,2967
+task_orchestrator/checkpoints.py,sha256=dq1NaMbyomWeBAgEOlSspaU-m5XB7WHU77Eu5gfoegY,1981
+task_orchestrator/db.py,sha256=8E2Xm9PoD7lAgDnGrjuYX02nY19lYYKt4j6y2XFzGKQ,12219
+task_orchestrator/onboarding.py,sha256=p3Om-aCvGHEwmfeb8YBiw6lmxDyo-RHpmKtnnbx9k3A,19671
+task_orchestrator/prompts.py,sha256=H5kAM4S-UWhUaKeQ7AjdmNqez-jGuMIVLlTWgtfJV-g,5983
+task_orchestrator/schemas.py,sha256=w9v3MIAQ9dVHsxjvULXP6Qcf6ppOutJzTLvfoloDBow,6199
+task_orchestrator/server.py,sha256=o3RNMOKBtgv0KZl5jBWXf0Qaj35bHzD8TLNqdWTjiFE,39790
+task_orchestrator/workspace.py,sha256=Rv8CpN9N9i3rgvKCd7BpKB_Dxr9L-Igek_5-LdtbiIg,2937
+task_orchestrator/engine/__init__.py,sha256=3dESUZCZJKK_EOQrHIiQtMuesaOAP2wDEA-Q1sDKD3g,4156
+task_orchestrator/engine/archive.py,sha256=gk0-YHA-gE2yzotQ_yaiZhsv-meRXsfUa2x0tlDYSGY,2648
+task_orchestrator/engine/base.py,sha256=hoqqiQjNwoincD40XQBfuboiQMBCsA7z17BCli6gAfs,4914
+task_orchestrator/engine/claims.py,sha256=7h6HQWjoQ0LBW4SEGdtaewWg01F1lhZZ25GsSatr3e4,6749
+task_orchestrator/engine/dependencies.py,sha256=E3q1Xm-n_v5lbvFtuWuocwbt1-dl6Of5v_J1f6lEu-A,7059
+task_orchestrator/engine/items.py,sha256=P22fr4Y1ZNT0jvJfRJAlA3dUrXyznMByogCmBwCP_RA,12930
+task_orchestrator/engine/metrics.py,sha256=uxmMVmIBo0r-4bXDGbhG7699xnJ_Jx5n6pJ8aK-cxa8,11588
+task_orchestrator/engine/notes.py,sha256=sQdpjw_rMtI5sICyEk69Chrwm12v_aD-F65cqTwcyCY,2706
+task_orchestrator/engine/portability.py,sha256=nE52VCxH-vRmXSOQht7wo7RujnDpGFbMHEw2wfqFm-I,8169
+task_orchestrator/engine/presence.py,sha256=ZldTXqOD2U7wh1WOH3HTLp6Dwk1oFHt_kEtZnYScyEY,4995
+task_orchestrator/engine/queries.py,sha256=KuT-dgm0dVreYRjA0sKfZ3Ape3j9dpVKwwbDpRLnCIA,8693
+task_orchestrator/engine/transitions.py,sha256=OXCkxRV1GxO_1mO6Nqa_-LcdFioGO0xVCuR8J4ortt4,10927
+task_orchestrator/engine/trees.py,sha256=6uF_QgNHKtig15NeYTlOShcBEPwoa6CPOK8ZJ5PR_fI,3526
+task_orchestrator/engine/users.py,sha256=aufkO2uWhAgwFnsqUfrS5n8CQ8WXl0B0OnXqVowJn_0,11227
+task_orchestrator/engine/workspace_view.py,sha256=v8mO38dEWFfKJxUvxdNuHz8sOCGD5Ctj2YLkq_SkpZ0,4557
+task_orchestrator/ui/__init__.py,sha256=-_32roXmM7or5RlP-MPfTlT51608bsDMlUJavBeJmPU,43
+task_orchestrator/ui/app.py,sha256=kPT7PTbQY9CwMXCSJD-YVrWO943_pL-rj0in0aeoEB8,18943
+task_orchestrator/ui/templates/arc_detail.html,sha256=AIxwcRObQnKi1aaDxBlDV-mcoGWrZvFN4F_7ynQA_KE,8232
+task_orchestrator/ui/templates/arcs.html,sha256=nCV4dyehcSFvN3lrECarTTx1f3JDoCsIK5_8JnORl90,2631
+task_orchestrator/ui/templates/base.html,sha256=QC9lWoM5tO1t7w36nlfgBrFvksgFYuC-yjxoSodc5No,657
+task_orchestrator/ui/templates/board.html,sha256=yK4ut5CzFrxWuYX4GVJH4-JpWEPHzM2-3E9mZNEjOE0,9013
+task_orchestrator/ui/templates/timeline.html,sha256=8-RFcMCzwCvN34KDX12AGi4CVSUIJsD9W8gd0ZjtjGw,6085
+task_orchestrator/ui/templates/partials/card.html,sha256=koHu3nP44x32Z45LH5TIVymWUeg71lgPtLGFcCBg5qo,801
+task_orchestrator/ui/templates/partials/column.html,sha256=-8mA1dZRJl1E8K3UyQFklNmi2HG8BDGpYtDMZCdzgdQ,300
+task_orchestrator/ui/templates/partials/item_detail.html,sha256=kai5Vgy2z6blqks14WOgEDy1A_qVkP5I_S9ByeEMMX4,1727
+task_orchestrator/ui/templates/partials/tree_node.html,sha256=HikdrkpvjecjBx3oCmgEfWwgDgn-rbRUlXKrDryA6Fw,2160
+task_orchestrator/web/__init__.py,sha256=fmXEU1h-eE8A9uhJorfHAF9oS8t2bBhisQTVzkipuXQ,178
+task_orchestrator/web/api.py,sha256=0Onpmewsq3Yj93Nkxyj1UGzO2-UtrEcJI2bEAwRftDw,16039
+task_orchestrator/web/graph.py,sha256=VVEx1uxKVeGmQo__doykthI0l5HkQY7xhRNhfxl7HoM,3981
+orc_hestrator_server-2.0.0.dist-info/METADATA,sha256=NbDSZXc4eSc3DuZ2NN2l7HKqgxnWLVr1xIl23LE2IcU,13387
+orc_hestrator_server-2.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+orc_hestrator_server-2.0.0.dist-info/entry_points.txt,sha256=hUC7tIDTOCkKwfnop5qCKrtyz3nvPYYkoPwVDBeIfPs,399
+orc_hestrator_server-2.0.0.dist-info/licenses/LICENSE,sha256=zYn23Qf0BnHSrScYg5N_5UKnPZ_3niJaq5eGAE7TKXo,1079
+orc_hestrator_server-2.0.0.dist-info/RECORD,,

orc_hestrator_server-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

orc_hestrator_server-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,9 @@
+[console_scripts]
+orc = task_orchestrator.server:main
+orc-hestrator = task_orchestrator.server:main
+orc-hestrator-server = task_orchestrator.server:main
+orc-mcp = task_orchestrator.server:main
+orc-serve = task_orchestrator.server:main_http
+orc-ui = task_orchestrator.ui.app:main
+task-orchestrator-py = task_orchestrator.server:main_legacy
+task-orchestrator-ui = task_orchestrator.ui.app:main_legacy

orc_hestrator_server-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claudio Ferreira Filho
+
+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.

task_orchestrator/__init__.py

@@ -0,0 +1,3 @@
+"""orc-hestrator-server — MCP server for AI agent work management."""
+
+__version__ = "0.8.0"

task_orchestrator/auth.py

@@ -0,0 +1,92 @@
+"""OAuth2 resource-server authentication with opaque pre-shared tokens.
+
+Implements TokenVerifier interface for MCP FastMCP auth.
+"""
+
+import hmac
+import os
+
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+from mcp.server.auth.settings import AuthSettings
+
+
+class OpaqueTokenVerifier:
+    """Token verifier for opaque pre-shared tokens."""
+
+    def __init__(self, persona_secrets: dict[str, str] | None = None) -> None:
+        """Initialize with persona->secret mapping.
+
+        Args:
+            persona_secrets: Dict of persona names to their secrets.
+                            If None, will read from MCP_OAUTH_TOKENS env var.
+        """
+        if persona_secrets is None:
+            self.persona_secrets = self._load_tokens_from_env()
+        else:
+            self.persona_secrets = persona_secrets
+
+    def _load_tokens_from_env(self) -> dict[str, str]:
+        """Load persona->secret mapping from MCP_OAUTH_TOKENS environment variable.
+
+        Expected format: "persona1:secret1,persona2:secret2"
+        """
+        tokens_env = os.environ.get("MCP_OAUTH_TOKENS", "")
+        if not tokens_env:
+            return {}
+
+        result = {}
+        for pair in tokens_env.split(","):
+            if ":" not in pair:
+                continue
+            persona, secret = pair.split(":", 1)
+            result[persona.strip()] = secret.strip()
+        return result
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify bearer token against configured secrets.
+
+        Args:
+            token: Bearer token to verify
+
+        Returns:
+            AccessToken if valid, None if invalid/empty
+        """
+        if not token:
+            return None
+
+        # Check against all configured secrets using constant-time comparison
+        for persona, secret in self.persona_secrets.items():
+            if hmac.compare_digest(token, secret):
+                return AccessToken(
+                    token=token, client_id=persona, scopes=["orc"], expires_at=None
+                )
+
+        return None
+
+
+def build_auth() -> tuple[TokenVerifier | None, AuthSettings | None]:
+    """Build auth configuration from environment variables.
+
+    Returns:
+        Tuple of (TokenVerifier, AuthSettings) if OAuth is enabled,
+        (None, None) if disabled.
+    """
+    # Check if OAuth is enabled
+    oauth_enabled = os.environ.get("MCP_OAUTH_ENABLED", "").lower()
+    if oauth_enabled not in ("true", "1", "yes"):
+        return (None, None)
+
+    # Create token verifier
+    verifier = OpaqueTokenVerifier()
+
+    # Build AuthSettings with required fields
+    issuer_url = os.environ.get("MCP_OAUTH_ISSUER", "https://cfnarede.dev/orc")
+    resource_server_url = os.environ.get("MCP_OAUTH_RESOURCE_SERVER_URL", issuer_url)
+
+    auth_settings = AuthSettings(
+        issuer_url=issuer_url,
+        resource_server_url=resource_server_url,
+        required_scopes=["orc"],
+    )
+
+    return (verifier, auth_settings)

task_orchestrator/checkpoints.py

@@ -0,0 +1,63 @@
+"""Checkpoint management — export snapshots and DB integrity verification."""
+
+import json
+import os
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+
+from . import db as _db
+from . import engine
+
+
+def _default_output_dir() -> str:
+    """Default checkpoint dir: same directory as the SQLite DB file."""
+    return str(Path(_db.DB_PATH).parent)
+
+
+def create_checkpoint(output_dir: str | None = None) -> str:
+    """Export graph and save to checkpoint-{ISO-timestamp}.json. Returns file path."""
+    out = output_dir or _default_output_dir()
+    os.makedirs(out, exist_ok=True)
+    data = engine.export_graph()
+    ts = datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ")
+    filename = f"checkpoint-{ts}.json"
+    filepath = os.path.join(out, filename)
+    with open(filepath, "w") as f:
+        json.dump(data, f, default=str)
+    return filepath
+
+
+def list_checkpoints(output_dir: str | None = None) -> list[str]:
+    """List .json checkpoint files in output dir sorted by date (newest first)."""
+    out = output_dir or _default_output_dir()
+    if not os.path.isdir(out):
+        return []
+    files = sorted(
+        (
+            os.path.join(out, name)
+            for name in os.listdir(out)
+            if name.startswith("checkpoint-") and name.endswith(".json")
+        ),
+        reverse=True,
+    )
+    return files
+
+
+def restore_checkpoint(path: str) -> bool:
+    """Restore graph from a checkpoint file using import_graph(replace). Returns True on success."""
+    with open(path) as f:
+        data = json.load(f)
+    engine.import_graph(data, mode="replace")
+    return True
+
+
+def verify_db_integrity() -> bool:
+    """Run PRAGMA integrity_check on the DB. Returns True if healthy."""
+    try:
+        conn = sqlite3.connect(_db.DB_PATH)
+        result = conn.execute("PRAGMA integrity_check").fetchone()
+        conn.close()
+        return result[0] == "ok"
+    except (sqlite3.DatabaseError, sqlite3.OperationalError):
+        return False