# Emacs Sovereign Control Plane

Real-time, programmable orchestration hub for the Timmy Foundation fleet.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Emacs Control Plane                       │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  dispatch.org│  │  shared     │  │  org-babel  │        │
│  │  (Task Queue)│  │  buffers    │  │  notebooks   │        │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │
│         │                │                │                │
│         └────────────────┼────────────────┘                │
│                          │                                  │
│                    ┌─────▼─────┐                           │
│                    │  Emacs    │                           │
│                    │  Daemon   │                           │
│                    │  (bezalel)│                           │
│                    └─────┬─────┘                           │
└──────────────────────────┼──────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
   ┌────▼────┐       ┌────▼────┐       ┌────▼────┐
   │  Ezra   │       │ Allegro │       │  Timmy  │
   │  (VPS)  │       │  (VPS)  │       │  (Mac)  │
   └─────────┘       └─────────┘       └─────────┘
```

## Infrastructure

| Component | Location | Details |
|-----------|----------|---------|
| Daemon Host | Bezalel (`159.203.146.185`) | Shared Emacs daemon |
| Socket Path | `/root/.emacs.d/server/bezalel` | emacsclient socket |
| Dispatch Hub | `/srv/fleet/workspace/dispatch.org` | Central task queue |
| Wrapper | `/usr/local/bin/fleet-append` | Quick message append |

## Quick Start

### From Local Machine (Timmy)
```bash
# Append a message to the fleet log
scripts/fleet_dispatch.sh append "Status: all systems nominal"

# Check for pending tasks assigned to Timmy
scripts/fleet_dispatch.sh poll timmy

# Claim a task
scripts/fleet_dispatch.sh claim 42 timmy

# Report task completion
scripts/emacs_fleet_bridge.py complete 42 "PR merged: #123"
```

### From Other VPS Agents (Ezra, Allegro, etc.)
```bash
# Direct emacsclient via SSH
ssh root@bezalel 'emacsclient -s /root/.emacs.d/server/bezalel -e "(your-elisp-here)"'

# Or use the wrapper
ssh root@bezalel '/usr/local/bin/fleet-append "Ezra: task #42 complete"'
```

## dispatch.org Structure

The central dispatch hub uses Org mode format:

```org
* TODO [timmy] Review PR #123 from gitea
  SCHEDULED: <2026-04-13 Sun>
  :PROPERTIES:
  :PRIORITY: A
  :ASSIGNEE: timmy
  :GITEA_PR: https://forge.alexanderwhitestone.com/...
  :END:

* IN_PROGRESS [ezra] Deploy monitoring to VPS
  SCHEDULED: <2026-04-13 Sun>
  :PROPERTIES:
  :PRIORITY: B
  :ASSIGNEE: ezra
  :STARTED: 2026-04-13T15:30:00Z
  :END:

* DONE [allegro] Fix cron reliability
  CLOSED: [2026-04-13 Sun 14:00]
  :PROPERTIES:
  :ASSIGNEE: allegro
  :RESULT: PR #456 merged
  :END:
```

### Status Keywords
- `TODO` — Available for claiming
- `IN_PROGRESS` — Being worked on
- `WAITING` — Blocked on external dependency
- `DONE` — Completed
- `CANCELLED` — No longer needed

### Priority Levels
- `[#A]` — Critical / P0
- `[#B]` — Important / P1
- `[#C]` — Normal / P2

## Agent Workflow

1. **Poll:** Check `dispatch.org` for `TODO` items matching your agent name
2. **Claim:** Update status from `TODO` to `IN_PROGRESS`, add `:STARTED:` timestamp
3. **Execute:** Do the work (implement, deploy, test, etc.)
4. **Report:** Update status to `DONE`, add `:RESULT:` property with outcome

## Integration with Existing Systems

### Gitea Issues
- `dispatch.org` tasks can reference Gitea issues via `:GITEA_PR:` or `:GITEA_ISSUE:` properties
- Completion can auto-close Gitea issues via API

### Hermes Cron
- Hermes cron jobs can check `dispatch.org` before running
- Tasks in `dispatch.org` take priority over ambient issue burning

### Nostr Protocol
- Heartbeats still go through Nostr (kind 1)
- `dispatch.org` is for tactical coordination, Nostr is for strategic announcements

## Files

```
infrastructure/emacs-control-plane/
├── README.md                   # This file
├── dispatch.org.template       # Template dispatch file
└── fleet_bridge.el             # Emacs Lisp helpers

scripts/
├── fleet_dispatch.sh           # Shell wrapper for fleet operations
├── emacs_fleet_bridge.py       # Python bridge for Emacs daemon
└── emacs_task_poller.py        # Poll for tasks assigned to an agent
```