box/docs/BOX-TMUX-AUTO-HTTPS.md

# Tmux Worker Tally & Regex Auto-Approvals over HTTPS (No SSH)

> **Box is the main surface.** All operator work goes through Box (`box.muse-dev.online`).
> The web UI, `box` CLI, and agents share the same unified API endpoints and runtimes.

**Date:** 2026-10-06  
**Status:** Implemented (`bin/tmux_auto_approver.py`, `bin/box-onboard-tui.py`, `bin/super-cli.py`)  
**Scope:** Tmux worker tallies, automated regex approval engine for on-board Muse Code runs & autonomous agent workers, and dedicated interactive TUI console (`box onboard-tui`).

---

## 1. Architecture

```
                    ┌──────────────────────────────────────────────┐
                    │      https://box.muse-dev.online/            │
                    │        (Web Dashboard & API Gateway)         │
                    └──────────────────────┬───────────────────────┘
                                           │
                           HTTPS Signed Ops / CLI Dispatch
                                           │
                    ┌──────────────────────▼───────────────────────┐
                    │            Unified Box CLI Engine            │
                    │     (box tmux tally / box tmux auto ...)     │
                    └───────┬───────────────────────────────┬──────┘
                            │                               │
             ┌──────────────▼─────────────┐   ┌─────────────▼──────────────┐
             │    bin/box-onboard-tui.py  │   │  bin/tmux_auto_approver.py │
             │  (Dedicated 4-Tab Console) │   │ (Multi-Socket Regex Daemon)│
             └──────────────┬─────────────┘   └─────────────┬──────────────┘
                            │                               │
                            │                               │
    ┌───────────────────────┴───────────────────────────────┴───────────────────────┐
    │                               Tmux Sockets Monitored                          │
    │  • /tmp/tmux-muse.sock (shared host workers)                                  │
    │  • /tmp/tmux-1000/default (dev/def runner panes & muse-code %37)              │
    │  • /tmp/tmux-1000/lte (lte operator pane)                                    │
    │  • /tmp/tmux-<agent>.sock (per-agent netns sockets: pip, 646, opm, dev, def)  │
    └───────────────────────────────────────────────────────────────────────────────┘
```

---

## 2. Tmux Auto-Approval Regex Match Engine

The auto-approval engine monitors scrollback across all agent panes and matches approval prompts against priority rules:

| Rule ID | Category | Trigger Pattern | Response Key | Press Enter | Description |
|---|---|---|---|---|---|
| `muse_code_run_numbered` | `muse_code` | `Would you like to run the following[\s\S]*?›\s*1\.\s*Yes,?\s*proceed` | `1` | `false` | Muse Code interactive run menu (selects option 1) |
| `muse_code_run_yn` | `muse_code` | `›\s*1\.\s*Yes,?\s*proceed\s*\(y\)` | `1` | `false` | Active selection indicator on `1. Yes, proceed (y)` |
| `muse_code_allow_execution` | `muse_code` | `Allow\s+execution\s+of\b[\s\S]*?\[y/N\]` | `y` | `true` | Approves script execution confirmation |
| `choice_abc` | `choice` | `(?i)(?:choose\|choice\|select)[\s\S]*?^\s*[A-Z]\s*[.\)\-:]\s+\S` | `A` | `true` | Lettered decision choice menus |
| `menu_numbered` | `menu` | `(?i)(?:Option:\|Selection:)[\s\S]*?^\s*\(?1\)?\s+[A-Za-z]` | `1` | `true` | Numbered selection menus |
| `confirm_yn` | `confirm` | `([yY]/[nN]\|\[[yY]/[nN]\])\s*[\]:)>]?\s*$` | `y` | `true` | Line-end confirmation prompts |
| `enter_to_continue` | `enter` | `(?i)(?:Press\s+\[?Enter\]?\s+to\s+continue)` | `Enter` | `false` | Enter-to-continue banners |

### Guardrails (Never Auto-Approved)
- `[sudo] password for ...` / `password:` prompts
- Passkeys, private key passphrases, and PIN prompts
- Destructive operations (`rm -rf /`, `mkfs.*`)

When a guardrail pattern is detected, the engine flags `is_blocked=true`, emits a warning audit log, and notifies the human operator.

---

## 3. CLI Commands

### Tmux Worker Tally & Management
```bash
# Tally all active tmux sessions, panes, and workers across sockets
box tmux tally
box tmux tally --json

# List active sessions
box tmux list

# Spawn new background worker session
box tmux new my-worker -c "python3 run_tasks.py"
```

### Auto-Approval Control
```bash
# Query master state and per-agent policies
box tmux auto status
box tmux auto status --json

# Master enable / disable
box tmux auto on
box tmux auto off

# Enable / disable for specific agent
box tmux auto on --node muse
box tmux auto off --node 646

# Execute single-pass scan and auto-approve all active prompts right now
box tmux auto once
box tmux auto once --dry-run

# Run background monitor daemon
box tmux auto watch --interval 1.0

# Tail structured audit log stream
box tmux auto logs -n 20

# Test regex match against custom prompt text
box tmux auto match "Would you like to run the following ... › 1. Yes, proceed (y)"
```

### Onboard Connects
```bash
# View all fleet nodes & client onboard connects
box onboard connects
box onboard connects --json

# Start client onboarding
box onboard start dev2 --email client@example.com --for 646

# Submit OTP verification code
box onboard submit-otp dev2 123456
```

### Dedicated Interactive TUI
```bash
# Launch full 4-tab interactive TUI
box onboard-tui
box tui onboard
```

---

## 4. HTTPS Remote Operations (`exec-constrained.py`)

Available via `https://exec.muse-dev.online/exec` with signature verification:

| Op | Parameters | Description | Permission |
|---|---|---|---|
| `tmux.tally` | `{}` | Returns complete worker tally across all sockets (JSON) | `DEFAULT_PERMS` (Read-only) |
| `tmux.auto_status` | `{}` | Returns auto-approval toggle state & rule set (JSON) | `DEFAULT_PERMS` (Read-only) |
| `onboard.connects` | `{}` | Returns consolidated fleet and client connects (JSON) | `DEFAULT_PERMS` (Read-only) |
| `tmux.auto_toggle` | `{"enabled": bool, "node"?: str}` | Toggles master or per-agent auto-approval state | Known-Identities-Only |

---

## 5. Audit Logging

Every auto-approval and blocked guardrail event is written to:
`/home/super/Projects/NetVM/logs/tmux/auto-approvals.jsonl`

Sample event payload:
```json
{
  "action": "AUTO_APPROVED",
  "socket": "/tmp/tmux-1000/default",
  "pane": "%37",
  "session": "muse",
  "agent": "muse",
  "rule_id": "muse_code_run_numbered",
  "rule_name": "Muse Code Run (Numbered)",
  "key_sent": "1",
  "press_enter": false,
  "excerpt": "Would you like to run the following ... › 1. Yes, proceed (y)",
  "dry_run": false,
  "success": true,
  "timestamp": "2026-10-06T19:34:19.599811+00:00",
  "ts": 1791315259.6
}
```