AIBotza Fleet

  Telegram / Slack / Teams / Email
          │
  ┌───────▼────────┐
  │  Gateway Layer  │  ← Thin adapters (14 PM2 processes, ports 9604-9620)
  │  Long-polling   │     Each bot has GATEWAY_IDENTITY + BOT_TOKEN
  └───────┬────────┘     Transform → Forward → Respond
          │ POST /message (unified format)
  ┌───────▼────────┐
  │ Conversational  │  ← Stateless router (port 9600)
  │ API (conv-api)  │     Identity → Session → Budget → Governance → Dispatch
  └───┬────────┬───┘
      │        │
  ┌───▼──┐ ┌──▼───────────┐
  │Exec  │ │ Task Engine   │  ← Runner (port 9606), API (port 9610)
  │Layer │ │ PostgreSQL    │     Cron, LLM Review, Hygiene, Webhooks
  │Claude│ │ queue + drain │
  │Code  │ └──────────────┘
  │CLI   │
  └──────┘  ← ALL execution happens on Ubuntu server
      │        Claude Code CLI spawned per request
  ┌───▼──────────────┐
  │ PostgreSQL       │  ← Source of truth for all state
  │ (fleet_aibotza)  │     identities, conversations, tasks, budgets,
  └──────────────────┘     governance, improvements, experience
      │
  ┌───▼──────────────┐
  │ Redis            │  ← Pub/sub notifications, heartbeats, digest cache
  │ (port 6379)      │     NOT for state — warm restart safe
  └──────────────────┘

1. User sends Telegram message → Gateway polls via getUpdates
2. Gateway transforms to unified format, injects GATEWAY_IDENTITY
3. POST /message to conv-api (port 9600)
4. Conv-api: resolve identity → load soul/skills/tools → persist message → check budget
5. If task intent (/task, /qtask): create task → governance gates → inline exec or queue
6. Dispatch to Claude Code CLI on Ubuntu server (spawns process)
7. Record usage in token_ledger → persist response → return to gateway
8. Gateway sends response back to Telegram

Task Flow: Task created → pending in PostgreSQL → fleet-runner polls → picks up → executes via conv-api → LLM review (Haiku) → rework/escalate/approve → lesson → improvement proposal

All 14 bots execute on the Ubuntu server. The gateway processes only handle Telegram polling.

Previous model: Each device (phone, Docker container) ran Claude CLI locally.
Current model: Centralized execution via conv-api dispatch. Phones/Docker are idle.

Execution providers: Claude Code CLI (default), Codex CLI (fallback), Mock (testing)
Workspace isolation: Per-identity workspaces at ~/.claude/projects/
Session management: Auto-rotation after 4h idle, parent session tracking, failure count rotation after 3 failures

/task <title> — Create and execute inline task
/qtask <title> — Queue task for background execution
/usage [botId] — Check token usage / budget status
/budget — View all identity budgets
/approve <taskId> — Approve a Gate3 pending task
/tasks [status] — List tasks by status
/improvements [status] — List improvement proposals
/impapprove <id> [note] — Approve improvement
/impreject <id> [note] — Reject improvement
/impapply <id> [note] — Apply approved improvement

npm run guard:fast    # Lint + test + secrets scan
npm run guard:full    # + coverage + audit + compose validation
npm run test:e2e      # Full pipeline E2E (needs Docker PG)
npm run test:e2e:business-day # Business day regression
pm2 status            # All PM2 services
pm2 logs fleet-gw-ubuntu --lines 20 # Gateway logs
pm2 restart conv-api  # Restart conversational API
node platform/scripts/retire-fleet-tasks.mjs --dry-run # Preview retirement