resonance-engine/results/TOOLS.md.bak.pre-migration

# TOOLS.md - Beast Server Environment

## System Access

You have **full exec access** via the `exec` tool. You can run any command on this Windows machine.
Use exec freely - you are NOT sandboxed. Do not generate code blocks for the user to run manually.
When you need to run a command, **call the exec tool directly**.

## Server: Beast

- **OS:** Windows 11, x86_64
- **IP:** 192.168.1.34
- **Role:** Primary compute server (GPU workloads, model hosting, experiments)
- **GPU:** NVIDIA (CUDA capable)

### Key Paths

- OpenClaw state: `D:\openclaw-local\state\`
- Workspace: `D:\openclaw-local\workspace-main\`
- Gateway logs: `D:\openclaw-local\state\logs\openclaw.log`

### Available Tools

- **Git:** `C:\Program Files\Git\bin\git.exe`
- **Node.js:** `C:\Program Files\nodejs\node.exe`
- **Python:** Check `where python` or `where python3`
- **WSL:** Windows Subsystem for Linux available via `wsl` command
- **Docker:** Check `docker --version`
- **Ollama:** Running at `http://localhost:11434`

## Lattice Observer API (Embodied Participant)

The qwen3-vl:30b observer is embodied in the Khra'gixx v4 CUDA lattice. Access it via `exec curl`:

- **Port:** 28820 (localhost, runs in WSL)
- **IMPORTANT:** Use `exec curl`, NOT `web_fetch` (SSRF protection blocks internal IPs)
- **TIMEOUT:** The model takes up to 180s to respond. Always use `--max-time 300` on /ask requests.
- **Script:** `D:\fractal-brain\beast-build\lattice_observer.py`

### Endpoints
```
GET  http://127.0.0.1:28820/status          # Health, cycle, coherence, turn count
GET  http://127.0.0.1:28820/telemetry       # Latest raw lattice telemetry JSON
GET  http://127.0.0.1:28820/snapshot        # Density PNG image
GET  http://127.0.0.1:28820/chronicle?last=N # Last N chronicle entries (default 5)
POST http://127.0.0.1:28820/ask             # Ask the participant a question
POST http://127.0.0.1:28820/chronicle/on    # Enable auto-chronicle (periodic observations)
POST http://127.0.0.1:28820/chronicle/off   # Disable auto-chronicle (frees GPU for /ask)
```

### Example: Ask the participant
```powershell
curl.exe -s --max-time 300 -X POST http://127.0.0.1:28820/ask -H "Content-Type: application/json" -d '{"question":"What do you perceive?","sender":"CTO"}'
```

### Notes
- **ALWAYS use --max-time 300 for /ask** — the model needs up to 180s to respond with vision
- Auto-chronicle is OFF by default — toggle with /chronicle/on and /chronicle/off
- The observer calls Ollama qwen3-vl:30b with vision (density snapshots as PNG)
- Chronicle history is stored in `D:\fractal-brain\beast-build\chronicle.jsonl`

## Managed Services (Beast)

### OpenClaw Gateway
- **Scheduled Task:** `OpenClaw Gateway` (AtLogOn trigger, auto-restart)
- **Port:** 28810 (bind lan)
- **Service script:** `D:\openclaw-local\services\OpenClaw_Gateway_Service.ps1` (while-loop auto-restart wrapper)
- **Task XML:** `D:\openclaw-local\services\OpenClaw_Gateway_Task.xml`
- **Launcher:** `D:\openclaw-local\start-gateway.ps1` (calls `Start-ScheduledTask`)
- **Logs:** `D:\openclaw-local\state\logs\gateway-console.log` (stdout/stderr), `D:\openclaw-local\state\logs\openclaw.log` (structured)
- **Process tree:** Task Scheduler (svchost.exe) → powershell.exe → node.exe (independent of VS Code)
- **Check:** `netstat -ano | Select-String "28810" | Select-String "LISTEN"`
- **Start:** `Start-ScheduledTask -TaskName "OpenClaw Gateway"`
- **Stop:** `Stop-ScheduledTask -TaskName "OpenClaw Gateway"`
- **Restart:** Stop then Start; the service script's while-loop also auto-restarts if the gateway process crashes

### OpenClaw Node (Beast → the-craw)
- **Scheduled Task:** `OpenClaw Node`
- **Port:** 18790 (localhost, exposed via reverse SSH tunnel from the-craw)
- **Check:** `(Get-ScheduledTask -TaskName "OpenClaw Node").State`
- **Start:** `Start-ScheduledTask -TaskName "OpenClaw Node"`
- **Stop:** `Stop-ScheduledTask -TaskName "OpenClaw Node"`

### GPU Clock Service
- **Scheduled Task:** `GPU_Clock_Control_Service` (runs as SYSTEM)
- **Script:** `D:\openclaw-local\services\GPU_Clock_Service.ps1`
- **Signal dir:** `D:\openclaw-local\services\gpu_clock_signal\`
- **Python module:** `D:\openclaw-local\services\gpu_clock_signaling.py`

### Service Recovery After Reboot
If services are down after a reboot, run:
```powershell
Start-ScheduledTask -TaskName "OpenClaw Gateway"
Start-ScheduledTask -TaskName "OpenClaw Node"
```
Wait ~30s for the gateway (embedding model load time) before checking.

## SSH Tunnels (the-craw side, systemd user services)

These run on the-craw and bridge the two servers. If node connectivity breaks, check these on the-craw:
- `openclaw-tunnel.service` — forwards the-craw:28810 → Beast:28810 (so the-craw node can reach Beast gateway)
- `openclaw-reverse-tunnel.service` — forwards Beast:18790 → the-craw:18789 (so Beast node can reach the-craw gateway)
- `openclaw-gateway.service` — the-craw's own gateway on port 18789
- `openclaw-node.service` — the-craw's node host connecting to Beast gateway

Check/restart from Beast via the-craw SSH MCP tool:
```bash
systemctl --user is-active openclaw-gateway openclaw-node openclaw-tunnel openclaw-reverse-tunnel
systemctl --user restart openclaw-gateway openclaw-node openclaw-tunnel openclaw-reverse-tunnel
```

## Network

- **NAS (Squirrel):** 192.168.1.33 - Synology, shared storage
  - SMB: `\\192.168.1.33\homes\Tiger\openclaw_shared\`
- **the-craw:** 192.168.1.55 / 192.168.1.63 - Ubuntu server, secondary compute
  - OpenClaw gateway: port 18789 (tunneled to Beast localhost:18789 via SSH)
  - Beast node connects via reverse tunnel on Beast localhost:18790

## Exec Guidelines

- Use `exec` for ALL system operations - file I/O, installations, diagnostics, builds
- You have `security: full` and `ask: off` - no confirmation needed
- For long commands, consider splitting into steps
- NAS files accessible via SMB paths above