feat: initial project structure

README.md

@@ -0,0 +1,68 @@
+# claude-failover
+
+Go daemon for Claude Code multi-account session orchestration with automatic
+quota-based failover.
+
+## Overview
+
+`claude-failover` orchestrates a pool of Claude Code sessions running under
+multiple Anthropic accounts. When the active account reaches its quota
+threshold (5-hour usage window or weekly cap), the daemon transparently fails
+over the workload to a backup account without losing in-flight session state.
+
+It is the runtime glue behind the SecuAAS agent pool (`ccl-0`..`ccl-9`,
+`ccl-auto-11`..`ccl-auto-20`) and is engineered to hold sessions warm across
+account swaps by sharing the `~/.claude/projects/` transcript tree via
+symlinks.
+
+## Architecture (goroutines)
+
+The daemon is a single Go binary composed of cooperating goroutines:
+
+- **dispatcher** — reads `.agent-queue/inbox/*.md` across registered projects
+  and assigns tasks to idle sessions.
+- **quota-monitor** — polls each configured Anthropic account's usage window
+  and triggers a failover when the active account crosses its threshold.
+- **session-watcher** — tracks tmux session liveness (`ccl-*`), heartbeats,
+  and `.agent-queue/status.json` transitions (idle / working).
+- **checkpoint** — periodically snapshots session context (current task,
+  last tool call, working dir) so an interrupted session can resume on a
+  different account.
+- **janitor** — cleans stale `.dispatched` markers, archives old
+  `done/` tasks, prunes expired checkpoints.
+- **notifier** — pushes state changes (failover fired, session degraded,
+  task failed) to Telegram / MCP dashboard / log aggregator.
+- **account-switcher** — performs the actual swap: stop sessions on account
+  A, rehome symlinks, relaunch sessions on account B, replay last
+  checkpoint. Serialized via a single mutex so only one swap can happen at
+  a time.
+
+All goroutines communicate through typed channels plus a shared state struct
+behind a `sync.RWMutex`. The daemon exposes an HTTP control plane for the
+MCP server to query status and force-trigger operations.
+
+## Relationship to SecuAAS agent-orchestrator
+
+This project extracts the session-management and failover logic that
+currently lives in `dev-management/agent-orchestrator/` (shell scripts:
+`launch-agent.sh`, `graceful-switch.sh`, `watchdog.sh`,
+`checkpoint-daemon.sh`, `start-dedicated-agents.sh`) and reimplements it
+as a single Go service. See the orchestrator docs for the operational
+context this daemon is designed to replace.
+
+## Repository layout
+
+```
+cmd/claude-failover/     Main entrypoint
+docs/                    Architecture, configuration, analysis notes
+scripts/                 Setup helpers (shared-projects symlink, etc.)
+config.example.yaml      Annotated example config
+```
+
+## Status
+
+Pre-alpha. Design and scaffolding only — no working binary yet.
+
+## License
+
+MIT — see `LICENSE`.