# CUTOVER — sovereign-org-engine Telegram → chairman-agent bridge

Consolidates @Wazier_bot into the Chairman. One brain (agent.py + CHAIRMAN-MEMORY.md),
every channel (iMessage webhook, heartbeat, now Telegram). Drafted 2026-07-04. Nothing
in this document has been executed — no plists created, no services touched.

## What moved

| org-engine (old) | chairman-agent (new) |
|---|---|
| `bot.py` + python-telegram-bot polling | `telegram_bridge.py` — stdlib long-poll, same mode |
| `core/orchestrator.py` (own Claude client, own tool set) | `agent.py:agent_loop()` — Chairman's existing decision path + tools |
| `config/agents.py` 32-agent roster | copied verbatim to `chairman-agent/config/agents.py` |
| `core/cost_guard.py` (monthly caps, 80% auto-cutoff) | ported to `chairman-agent/cost_guard.py` — same caps/threshold/state schema; real usage metered by wrapping `agent.api_call` |
| `core/supabase_bus.py` writes (task ledger, decisions, reports) | ported to `chairman-agent/agent_bus.py` — same tables/project, stdlib urllib, fail-soft |
| `/pulse` `/costs` `/update` `/musa` `/unlock` handlers | ported into the bridge, plain-text formatting |
| Mansu Musa AUTONOMOUS cycle | retired; `/musa audit\|agents\|leaks\|brief` runs on demand via the MANSU_MUSA persona |
| `agent-memory/mempal.md` | NOT carried — Chairman memory is the single memory (see §6) |
| crash on network loss (exit 1, KeepAlive loop) | retry-forever with backoff, 409-conflict aware |

Cost state lives in `chairman-agent/data/api_costs.json` (same JSON schema as
org-engine's `data/api_costs.json`). To carry this month's spend across the cutover,
copy the org-engine file to that path before first launch — optional; a fresh file
starts the month at $0. While the cutoff is tripped, API-calling routes are refused
with a notice; `/costs` `/pulse` `/update` `/status` `/agents` `/unlock` still work.

Routing semantics preserved: plain text goes to the Chairman who delegates to roster
personas (creative chain Philosophy CEO → Taste Manager → Brand Designer → production
is enforced in the system addendum); `/agent AGENT_ID task` runs a persona charter
directly; `/agents` lists the roster. Verified live 2026-07-04 via `--test` — the
Chairman answered with the correct Philosophy-CEO-first routing.

## 1. Pre-flight (no service impact)

1. Telegram creds: `TELEGRAM_BOT_TOKEN` + `TELEGRAM_USER_ID` currently live only in
   `sovereign-org-engine/config/.env`. The bridge falls back to reading that file, so
   cutover works with zero env surgery — but **copy both lines into
   `content-os/config/.env`** so the org-engine directory can eventually be archived
   without breaking the bridge.
2. Offline checks (already passing as of drafting):
   ```
   cd ~/sovereign-empire-sweep/chairman-agent
   python3 telegram_bridge.py --roster            # 32 agents, grouped by tier
   python3 telegram_bridge.py --test "ping"       # full agent_loop round-trip, no Telegram
   ```
   `--test` never contacts Telegram, so it is safe while org-engine still owns the bot.

## 2. Cut over (order matters — one poller per bot token)

Telegram allows exactly ONE `getUpdates` consumer per token. The bridge will log
`409 Conflict` and wait if org-engine is still polling — nothing breaks, but it won't
receive messages until org-engine is gone.

1. **Stop org-engine** (frees the token):
   ```
   launchctl bootout gui/$(id -u)/com.sovereign.org-engine
   ```
   KeepAlive dies with the job; confirm with
   `launchctl list | grep org-engine` (should be empty) and
   `pgrep -f sovereign-org-engine/bot.py` (no PID).
2. **Manual soak test** — run the bridge in a foreground shell first:
   ```
   cd ~/sovereign-empire-sweep/chairman-agent && python3 telegram_bridge.py
   ```
   From the phone, send to @Wazier_bot: `/start`, `/agents`, `/status`, `/pulse`,
   `/costs`, `/update`, a plain message, `/musa brief`, and
   `/agent RESEARCH_AGENT summarize today's AI headlines`.
   Watch `logs/telegram.log` (bridge ops) and `logs/telegram-chat.log` (transcripts).
   Note: messages sent during the gap between steps 1 and 2 queue server-side and
   deliver when the bridge starts — expected, not a bug.
3. **Create the LaunchAgent** (describe only — create it by hand at cutover time):
   `~/Library/LaunchAgents/com.chairman.telegram.plist` with
   - Label `com.chairman.telegram`
   - ProgramArguments: `/opt/homebrew/bin/python3`,
     `/Users/19keys/sovereign-empire-sweep/chairman-agent/telegram_bridge.py`
   - WorkingDirectory `/Users/19keys/sovereign-empire-sweep/chairman-agent`
   - RunAtLoad true, KeepAlive true, ThrottleInterval 30
   - StandardOutPath/StandardErrorPath →
     `/Users/19keys/sovereign-empire-sweep/chairman-agent/logs/telegram-launchd.log`
   (Mirrors com.chairman.webhook.plist; no PYTHONPATH needed — the bridge sets its own
   sys.path.)
4. Ctrl-C the manual run from step 2, then:
   ```
   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.chairman.telegram.plist
   ```
   Re-run the phone smoke test.
5. **Retire org-engine's plist** so a reboot doesn't resurrect it:
   ```
   launchctl disable gui/$(id -u)/com.sovereign.org-engine
   mv ~/Library/LaunchAgents/com.sovereign.org-engine.plist \
      ~/sovereign-empire-sweep/_Archive/com.sovereign.org-engine.plist
   ```
   Leave `sovereign-org-engine/` on disk untouched until §6 is done and a week of
   bridge uptime has passed.

## 3. Rollback (any point, ~1 minute)

```
launchctl bootout gui/$(id -u)/com.chairman.telegram        # or Ctrl-C the manual run
mv ~/sovereign-empire-sweep/_Archive/com.sovereign.org-engine.plist ~/Library/LaunchAgents/
launchctl enable gui/$(id -u)/com.sovereign.org-engine
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.sovereign.org-engine.plist
```
org-engine code and its .env were never modified, so this is a clean restore. The two
systems track Telegram offsets independently (bridge: `logs/.telegram_offset`); messages
already consumed by one will not replay to the other — acceptable single-user loss.

## 4. Post-cutover verification

- `tail -f chairman-agent/logs/telegram.log` — inbound/replied lines, no 409s.
- Pull the network for 60s mid-session: bridge must log `poll failed ... retry` and
  recover, not exit (this is the org-engine crash it replaces).
- `launchctl list | grep chairman` — telegram job present, last exit 0.
- Ledger freshness: after one plain message + one `/agent` run, check
  `agent_decisions` and `agent_tasks` for fresh rows (see §5 service-key note),
  and `chairman-agent/data/api_costs.json` for accrued spend.

## 5. Intentionally NOT carried over (needs a human decision)

Short list now — cost_guard, the one-tap commands, and the agent-bus writes were
ported on 2026-07-04 (table in "What moved"):
- **Mansu Musa autonomous cycle** (`agents/mansu_musa.py`, started in bot post_init)
  — the ONLY remaining functional gap. `/musa` works on demand; if the scheduled
  audit cadence matters, add it to the heartbeat checklist or its own LaunchAgent.
- **/forecast, /predict commands** — thin wrappers around
  `content-os/layer_10_simulation`; the Chairman can run those modules via bash on
  request. Re-add as one-tap commands only if actually missed.

### Intentional behavior changes vs org-engine (small, all stricter or safer)

- **Cutoff = hard stop, not Ollama fallback.** org-engine degraded to a local
  Ollama reply when the budget tripped; the Chairman has no Ollama path, so the
  bridge refuses API-calling routes (plain text, /agent, /musa runs) with a notice
  + `/unlock` instruction. The metered wrapper also stops a tool loop mid-run if
  the cutoff trips during it (org only checked between conversations).
- **Supabase writes prefer the service key.** VERIFIED 2026-07-04: the shared anon
  key returns 401 on `agent_decisions` INSERT since the RLS lockdown — and
  org-engine uses that SAME anon key, so its ledger writes were already failing
  silently before any cutover (the dashboards' staleness predates this work).
  `agent_bus.py` prefers `SUPABASE_SERVICE_KEY` (already loaded from
  content-os/config/.env). **VERIFY AT CUTOVER (human eyes):** after the first
  routed message, confirm a fresh row lands in `agent_decisions`, and in
  `agent_tasks` after one `/agent` run. If the service key is also blocked, the
  fix is a Supabase policy decision, not a bridge change.
- **No `agent_registry` startup sync** — org-engine re-inserted missing roster
  agents at every boot; the registry already holds 34 rows, so this was dropped.
- **`/musa cycle`** replies "retired — use /musa audit". `/musa audit` also files
  an `agent_reports` row (type `audit`) so `/pulse`'s LAST AUDIT stays live.
- **/costs display** adds an OpenRouter line (org budgeted it but never showed it).

## 6. mempal.md disposition

`sovereign-org-engine/agent-memory/mempal.md` is referenced by zero Python files —
it was a passive doc, so nothing breaks. To preserve the learning:
1. Diff it against `sovereign-wiki/memory/CHAIRMAN-MEMORY.md` — identity context and
   crown-jewel IP sections are largely duplicated there already.
2. Fold any unique facts into CHAIRMAN-MEMORY.md under a heading
   `## Imported from org-engine MEMPAL (2026-07-04)`.
3. Archive the originals (copy, don't move, until org-engine is retired):
   ```
   mkdir -p ~/sovereign-empire-sweep/sovereign-wiki/memory/archive
   cp ~/sovereign-empire-sweep/sovereign-org-engine/agent-memory/mempal.md \
      ~/sovereign-empire-sweep/sovereign-org-engine/agent-memory/learning-log.jsonl \
      ~/sovereign-empire-sweep/sovereign-wiki/memory/archive/
   ```

## Appendix: the exit-1 crash, diagnosed

`/tmp/sovereign-org-engine.log` line 4 (2026-06-28 17:18:16): python-telegram-bot's
bootstrap failed with `httpx.ConnectError: [Errno 8] nodename nor servname provided,
or not known` (DNS/network unavailable at boot) → `Network Retry Loop (Bootstrap
Initialize Application): Failed run number 0 of 0. Aborting.` → process exit 1 →
launchd KeepAlive relaunch every 30s until the network returned. The same NetworkError
also spammed the log at runtime ("No error handlers are registered", thousands of
tracebacks, 7.2 MB log). The bridge's poll loop retries with capped backoff instead
of exiting, so this failure class disappears at cutover.