feat: SwarmSync routing, context compaction, PTY sessions, MCP runtime, pipeline workers, Telegram bridge, desktop fixes

Core agent improvements:
- SwarmSync routing enabled and verified (routes calls to best model via complexity score)
- Context compaction: _maybe_compact() distils old turns at 2500 token/30 turn threshold
  keeping live window of 12 turns; distilled summaries injected into system prompt
- /api/routing/status endpoint for live SwarmSync diagnostics
- Model badge suppression for default model in ChatView

New subsystems:
- PTY session manager (cato/orchestrator/pty_session.py) + API routes
- MCP runtime server (cato/mcp/runtime.py) with JSON-RPC tool dispatch
- Pipeline workers + models + phase validation (cato/pipeline/)
- Memory upkeep service (cato/core/memory_upkeep.py)
- Telegram bridge (cato_telegram_bridge.py) + autostart installer

Desktop app:
- TerminalPane and InteractiveCLIView components
- Updated Sidebar, ChatView, SettingsView, useChatStream hook
- Tauri sidecar improvements (sidecar.rs, build.rs)
- Build script improvements (build_release.ps1, pre_bundle.py)

Tests (1661 passing, 100%):
- test_compaction.py (19 tests): compaction trigger/no-op/storage/formatting
- test_mcp_runtime.py, test_gateway_mcp.py, test_memory_upkeep.py
- test_pty_session.py, test_pty_routes_integration.py
- test_pipeline_runtime.py, test_router.py, test_start_channel.py
- test_empire_cli.py, test_port_fallback_integration.py

Docs: setup guides (Windows/macOS/Linux), audit pipeline, remote-MCP, TESTING
GitHub Actions: python-verify.yml CI workflow
Genesis_meta_agent.py: reference implementation for meta-agent design

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Cato

.github/workflows/python-verify.yml

@@ -0,0 +1,25 @@
+name: Python Verify
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: windows-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and test dependencies
+        run: python -m pip install --upgrade pip && python -m pip install .[dev]
+
+      - name: Verify Python source and built wheel
+        run: python scripts/verify_python_build.py

CLAUDE.md

@@ -58,28 +58,111 @@ CODE COMPLETE
 
 ## PROJECT OVERVIEW
 
-**Cato** — Privacy-focused AI agent daemon. Alternative to OpenClaw/ClawdBot.
-- Python 3.11+, asyncio, aiohttp, websockets
+**Cato** — Privacy-focused AI agent daemon. Alternative to OpenClaw/ClawdBot/MoltBot.
+- Package: `cato-daemon` v0.2.0, entry point `cato.cli:main`
+- Python 3.11+, asyncio, aiohttp, websockets, patchright, tiktoken, sentence-transformers
 - Tauri v2 desktop app (`desktop/`) — React 19 + TypeScript + Rust sidecar
-- SQLite memory, YAML config, AES-256-GCM vault
-- Ports: HTTP 8080, WS 8081 (canonical defaults)
-- Live install: `pip install -e .` at this directory
+- SQLite memory, YAML config, AES-256-GCM encrypted vault
+- **Ports: HTTP 8080, WS 8081** (canonical defaults)
+- Live install: `pip install -e .` at `C:\Users\Administrator\Desktop\Cato`
+
+## DAEMON CONFIGURATION
+
+- Config: `%APPDATA%\cato\config.yaml`
+- Default model: `openrouter/minimax/minimax-m2.5`
+- **workspace_dir**: defaults to `%APPDATA%\cato\workspace` on Windows, `~/.cato/workspace` on macOS/Linux (critical for identity files)
+- **swarmsync_enabled: true** — SwarmSync routing is enabled; routes calls to the best model based on complexity
+- Vault: `%APPDATA%\cato\vault.enc` — stores `OPENROUTER_API_KEY`, `TELEGRAM_BOT_TOKEN`, `SWARMSYNC_API_KEY`
+- Vault password: `CATO_VAULT_PASSWORD=mypassword123` (**example only — always choose a unique, strong password in real installs**)
+- Run daemon: `CATO_VAULT_PASSWORD=<your-strong-password> python cato_svc_runner.py`
+- Health check: `curl http://localhost:8080/health`
+
+## TELEGRAM INTEGRATION (2026-03-09)
+
+- **Status**: ENABLED and bidirectional
+- **Bot token**: Stored in encrypted vault as `TELEGRAM_BOT_TOKEN` (NOT in config.yaml)
+- config.yaml has `telegram_bot_token: ''` and `telegram_enabled: 'true'`
+- Messages flow: Telegram → TelegramAdapter → gateway.ingest() → WebSocket broadcast → desktop app
+- Responses flow: Agent loop → gateway.send() → WebSocket (desktop) + Telegram adapter (phone)
+- Desktop app: `useChatStream.ts` handles `type: "message"` for incoming Telegram user messages
+- Gateway: Both `ingest()` and `send()` broadcast telegram/whatsapp channels to WebSocket clients
 
 ## KEY DIRECTORIES
 
 ```
 cato/                  Python daemon source
   api/                 aiohttp web + WebSocket handlers
   orchestrator/        Multi-model CLI fan-out (Claude/Codex/Gemini/Cursor)
-  audit/               Hash-chained audit log
+    cli_invoker.py     Claude/Codex/Gemini/Cursor invocation with timeouts
+    cli_process_pool.py Warm pool for Claude/Codex
+  audit/               Hash-chained audit log (PACKAGE)
+  auth/                Token store + checker
   core/                Memory, context, scheduling
-  ui/                  Web UI (coding_agent.html)
+    memory.py          MemorySystem
+    context_builder.py ContextBuilder (loads SOUL.md, IDENTITY.md, SKILL.md)
+    schedule_manager.py SchedulerDaemon
+  ui/
+    server.py          aiohttp server, workspace_put/get endpoints, CORS middleware
+    dashboard.html     Web UI (monolithic SPA, ~1700 lines)
+  adapters/
+    telegram.py        Telegram long-polling adapter
+  cli.py               Main Click CLI
+  agent_loop.py        Core agent loop + register_all_tools
+  gateway.py           Message routing hub — WebSocket broadcast + adapter delivery
+  vault.py             AES-256-GCM vault
+  budget.py            Hard spend caps
 desktop/               Tauri v2 desktop app
   src/                 React/TypeScript frontend
+    hooks/
+      useChatStream.ts WebSocket hook — handles web + Telegram messages, 5s history poll
+    views/
+      ChatView.tsx     Main chat interface
+      SettingsView.tsx Settings tabs (general/memory/channels/scheduling/workspace)
   src-tauri/           Rust sidecar
-tests/                 pytest test suite (1285+ tests, must stay 100%)
+    target/release/    cato-desktop.exe (17MB release build)
+tests/                 pytest test suite (1346+ tests, must stay 100%)
 ```
 
+## DESKTOP APP DETAILS
+
+- Built: `desktop/src-tauri/target/release/cato-desktop.exe`
+- Desktop shortcut: `C:\Users\Administrator\Desktop\Cato.lnk` → points to exe above
+- Build script: `desktop/build_release.ps1`
+- Build env: MSVC 14.44.35207 + Windows SDK 10.0.26100.0
+- **Heartbeat timeout**: 45s (server sends every 30s)
+- **CORS**: `cors_middleware` in `cato/ui/server.py` adds `Access-Control-Allow-Origin: *`
+- Coding agent WS is on port 8080 (aiohttp), NOT 8081 (gateway)
+- Logo: `cato-logo.png` (transparent 1024×1024 PNG), 44×44px in sidebar
+
+## SKILLS SYSTEM
+
+- Skills directory: `~/.cato/skills/` (18+ skills: add-notion, coding-agent, daily-digest, etc.)
+- System prompt injection: `agent_loop.py` builds prompt with `skills_dir` parameter
+- SwarmSync routing is enabled (`swarmsync_enabled: true`) — routes each call to the best model
+- Workspace files (`SOUL.md`, `IDENTITY.md`, `AGENTS.md`, `TOOLS.md`) loaded from `workspace_dir`
+
+## CODING AGENT STATUS
+
+Fan-out to Claude/Codex/Gemini/Cursor in parallel (60s timeout each):
+- **Claude**: cli_process_pool (warm) — nested execution, blocked in production
+- **Codex**: cli_process_pool (warm) — works
+- **Gemini**: Subprocess only — hangs on Windows (stdin pipe detection issue)
+- **Cursor**: Subprocess only — most reliable on this system
+- All timeouts return degraded response with confidence 0.5
+
+## WINDOWS-SPECIFIC NOTES
+
+- npm CLIs (codex, gemini) are .CMD files; resolved via `shutil.which()` + `["cmd.exe", "/c", path]`
+- ANTHROPIC_API_KEY loaded from `.env` (python-dotenv); OpenRouter env key in `.env` is STALE — use vault
+- Cato is run as SEPARATE daemon — Claude CLI is NOT nested in production
+- PowerShell required for build scripts; bash available via Git Bash
+
+## TEST INFRASTRUCTURE
+
+- pytest asyncio_mode=auto, tests/ directory
+- Coverage via pytest-cov; `norecursedirs` excludes `.claude`, `BRAINSTORM`, `venv`
+- **1346/1346 tests passing** as of 2026-03-09
+
 ## AUDIT REPORT LOCATIONS
 
 - Alex audit: `CATO_ALEX_AUDIT.md` (repo root)