feat: harden Bezalel tailscale bootstrap packet (#535)

docs/BEZALEL_TAILSCALE_BOOTSTRAP.md

@@ -0,0 +1,96 @@
+# Bezalel Tailscale Bootstrap
+
+Refs #535
+
+This is the repo-side operator packet for installing Tailscale on the Bezalel VPS and verifying the internal network path for federation work.
+
+Important truth:
+- issue #535 names `104.131.15.18`
+- older Bezalel control-plane docs also mention `159.203.146.185`
+- the current source of truth in this repo is `ansible/inventory/hosts.ini`, which currently resolves `bezalel` to `67.205.155.108`
+
+Because of that drift, `scripts/bezalel_tailscale_bootstrap.py` now resolves the target host from `ansible/inventory/hosts.ini` by default instead of trusting a stale hardcoded IP.
+
+## What the script does
+
+`python3 scripts/bezalel_tailscale_bootstrap.py`
+
+Safe by default:
+- builds the remote bootstrap script
+- writes it locally to `/tmp/bezalel_tailscale_bootstrap.sh`
+- prints the SSH command needed to run it
+- does **not** touch the VPS unless `--apply` is passed
+
+When applied, the remote script does all of the issue’s repo-side bootstrap steps:
+- installs Tailscale
+- runs `tailscale up --ssh --hostname bezalel`
+- appends the provided Mac SSH public key to `~/.ssh/authorized_keys`
+- prints `tailscale status --json`
+- pings the expected peer targets:
+  - Mac: `100.124.176.28`
+  - Ezra: `100.126.61.75`
+
+## Required secrets / inputs
+
+- Tailscale auth key
+- Mac SSH public key
+
+Provide them either directly or through files:
+- `--auth-key` or `--auth-key-file`
+- `--ssh-public-key` or `--ssh-public-key-file`
+
+## Dry-run example
+
+```bash
+python3 scripts/bezalel_tailscale_bootstrap.py \
+  --auth-key-file ~/.config/tailscale/auth_key \
+  --ssh-public-key-file ~/.ssh/id_ed25519.pub \
+  --json
+```
+
+This prints:
+- resolved host
+- host source (`inventory:<path>` when pulled from `ansible/inventory/hosts.ini`)
+- local script path
+- SSH command to execute
+- peer targets
+
+## Apply example
+
+```bash
+python3 scripts/bezalel_tailscale_bootstrap.py \
+  --auth-key-file ~/.config/tailscale/auth_key \
+  --ssh-public-key-file ~/.ssh/id_ed25519.pub \
+  --apply \
+  --json
+```
+
+## Verifying success after apply
+
+The script now parses the remote stdout into structured verification data:
+- `verification.tailscale.self.tailscale_ips`
+- `verification.tailscale.self.dns_name`
+- `verification.peers`
+- `verification.ping_ok`
+
+A successful run should show:
+- at least one Bezalel Tailscale IP under `tailscale_ips`
+- `ping_ok.mac = 100.124.176.28`
+- `ping_ok.ezra = 100.126.61.75`
+
+## Expected remote install commands
+
+```bash
+curl -fsSL https://tailscale.com/install.sh | sh
+tailscale up --ssh --hostname bezalel
+install -d -m 700 ~/.ssh
+touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys
+tailscale status --json
+```
+
+## Why this PR does not claim live completion
+
+This repo can safely ship the bootstrap script, host resolution logic, structured proof parsing, and operator packet.
+It cannot honestly claim that Bezalel was actually joined to the tailnet unless a human/operator runs the script with a real auth key and real SSH access to the VPS.
+
+That means the correct PR language for #535 is advancement, not pretend closure.

docs/LOCAL_HARDWARE_MCP.md

@@ -1,144 +0,0 @@
-# Local Hardware MCP Integration
-
-Integrate the Model Context Protocol (MCP) to allow Timmy agents to control local hardware securely: file system, smart home (Hue lights), and system information.
-
-## Components
-
-- **MCP Server**: `scripts/hardware_mcp_server.py` — stdio-based MCP server exposing 8 tools
-- **Config Template**: `timmy-local/hardware_mcp_config.yaml` — runtime tuning
-- **Smoke Tests**: `tests/test_hardware_mcp_server.py`
-
-## Prerequisites
-
-```bash
-# MCP SDK
-pip install mcp
-
-# OpenHue CLI (for smart home control)
-brew install openhue/cli/openhue   # macOS
-# or see: https://github.com/openhue/openhue-cli
-
-# Optional: psutil for detailed system_info
-pip install psutil
-```
-
-## Quick Start
-
-### 1. Start the MCP server
-
-The server runs as a subprocess launched by Hermes Agent via the native-MCP integration.
-
-Add to `~/.hermes/config.yaml`:
-
-```yaml
-mcp_servers:
-  hardware:
-    command: "python"
-    args: ["/full/path/to/timmy-home/scripts/hardware_mcp_server.py"]
-    # Optional: add env vars if needed
-    # env:
-    #   OPENHUE_BRIDGE_IP: "192.168.1.100"
-```
-
-### 2. Restart Hermes
-
-On startup, Hermes will:
-1. Launch the hardware MCP server
-2. Discover all 8 tools
-3. Register them with `hardware_*` prefixes (e.g., `hardware_file_read`, `hardware_light_control`)
-
-### 3. Use in conversation
-
-```
-User: Read my Timmy report file.
-Agent: [calls hardware_file_read with path="~/LOCAL_Timmy_REPORT.md"]
-
-User: Turn off the bedroom lights.
-Agent: [calls hardware_light_control with name="Bedroom Lamp", on=false]
-
-User: List files in my downloads folder.
-Agent: [calls hardware_file_list with directory="~/Downloads"]
-
-User: What's my system status?
-Agent: [calls hardware_system_info]
-```
-
-## Tool Reference
-
-| Tool | Purpose | Parameters |
-|------|---------|------------|
-| `hardware_file_read` | Read file (≤10 MB) from home/tmp | `path` (string) |
-| `hardware_file_write` | Write text file | `path`, `content` |
-| `hardware_file_list` | List directory contents | `directory` (default: ~) |
-| `hardware_light_list` | List all Hue lights/rooms/scenes | none |
-| `hardware_light_control` | Control individual light | `name`, `on`, `brightness`, `color`, `temperature` |
-| `hardware_room_control` | Control all lights in a room | `name`, `on`, `brightness` |
-| `hardware_scene_set` | Activate Hue scene | `scene`, `room` |
-| `hardware_system_info` | System info (OS, CPU, memory, disk) | none |
-
-## Security Model
-
-- **File path allowlist**: Only paths under `~` (home), `/tmp`, and `/private/tmp` are permitted.
-- **File size cap**: 10 MB max per read.
-- **No arbitrary commands**: Only explicit tool operations; no shell execution.
-- **Smart home requires OpenHue CLI**: Light control goes through the official Hue CLI which handles bridge authentication.
-- **Graceful degradation**: If `psutil` is missing, `system_info` returns basic platform data; if `openhue` is missing, light tools return install instructions.
-
-## Runtime Configuration
-
-Edit `~/.timmy/hardware/hardware_mcp_config.yaml` (copy from `timmy-local/hardware_mcp_config.yaml`) to adjust:
-
-```yaml
-guards:
-  max_consecutive_errors: 3
-  max_mcp_calls_per_session: 0  # 0 = unlimited
-allowed_dirs:
-  - "~"
-  - "/tmp"
-  - "/private/tmp"
-max_file_size_bytes: 10485760  # 10 MB
-```
-
-## Testing
-
-```bash
-# Validate Python syntax
-python3 -m py_compile scripts/hardware_mcp_server.py
-
-# Run smoke tests
-pytest tests/test_hardware_mcp_server.py -v
-```
-
-## Troubleshooting
-
-**MCP tools not appearing in Hermes**
-
-- Verify `mcp` Python package is installed: `pip show mcp`
-- Check `~/.hermes/config.yaml` syntax (YAML parse)
-- Restart Hermes (MCP connects at startup only)
-- Check Hermes logs: `~/.hermes/logs/` for MCP connection errors
-
-**"openhue CLI not found"**
-
-- Install OpenHue: `brew install openhue/cli/openhue`
-- First run requires pressing the Hue Bridge button to pair
-- Ensure bridge is on same local network
-
-**"Path not allowed"**
-
-- Only home (`~`), `/tmp`, and `/private/tmp` are accessible
-- Use absolute paths or `~/` expansion; relative paths are resolved from home
-
-**File too large**
-
-- Max read size is 10 MB. Split or compress large files.
-
-## Dependencies
-
-| Package | Purpose | Install |
-|---------|---------|---------|
-| `mcp` | MCP SDK (server framework) | `pip install mcp` |
-| `openhue` | Hue light control CLI | `brew install openhue/cli/openhue` |
-| `psutil` (optional) | Detailed memory/disk metrics | `pip install psutil` |
-
-## Closes #466

docs/RUNBOOK_INDEX.md

@@ -14,6 +14,7 @@ Quick-reference index for common operational tasks across the Timmy Foundation i
 | Agent scorecard | fleet-ops | `python3 scripts/agent_scorecard.py` |
 | View fleet manifest | fleet-ops | `cat manifest.yaml` |
 | Run nightly codebase genome pass | timmy-home | `python3 scripts/codebase_genome_nightly.py --dry-run` |
+| Prepare Bezalel Tailscale bootstrap | timmy-home | `python3 scripts/bezalel_tailscale_bootstrap.py --auth-key-file <path> --ssh-public-key-file <path> --json` |
 
 ## the-nexus (Frontend + Brain)
 

scripts/bezalel_tailscale_bootstrap.py

@@ -16,11 +16,14 @@ import argparse
 import json
 import shlex
 import subprocess
+import re
+from json import JSONDecoder
 from pathlib import Path
 from typing import Any
 
-DEFAULT_HOST = "159.203.146.185"
+DEFAULT_HOST = "67.205.155.108"
 DEFAULT_HOSTNAME = "bezalel"
+DEFAULT_INVENTORY_PATH = Path(__file__).resolve().parents[1] / "ansible" / "inventory" / "hosts.ini"
 DEFAULT_PEERS = {
     "mac": "100.124.176.28",
     "ezra": "100.126.61.75",
@@ -66,6 +69,37 @@ def parse_tailscale_status(payload: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+def resolve_host(host: str | None, inventory_path: Path = DEFAULT_INVENTORY_PATH, hostname: str = DEFAULT_HOSTNAME) -> tuple[str, str]:
+    if host:
+        return host, "explicit"
+    if inventory_path.exists():
+        pattern = re.compile(rf"^{re.escape(hostname)}\s+.*ansible_host=([^\s]+)")
+        for line in inventory_path.read_text().splitlines():
+            match = pattern.search(line.strip())
+            if match:
+                return match.group(1), f"inventory:{inventory_path}"
+    return DEFAULT_HOST, "default"
+
+
+def parse_apply_output(stdout: str) -> dict[str, Any]:
+    result: dict[str, Any] = {"tailscale": None, "ping_ok": {}}
+    text = stdout or ""
+    start = text.find("{")
+    if start != -1:
+        try:
+            payload, _ = JSONDecoder().raw_decode(text[start:])
+            if isinstance(payload, dict):
+                result["tailscale"] = parse_tailscale_status(payload)
+        except Exception:
+            pass
+
+    for line in text.splitlines():
+        if line.startswith("PING_OK:"):
+            _, name, ip = line.split(":", 2)
+            result["ping_ok"][name] = ip
+    return result
+
+
 def build_ssh_command(host: str, remote_script_path: str = "/tmp/bezalel_tailscale_bootstrap.sh") -> list[str]:
     return ["ssh", host, f"bash {shlex.quote(remote_script_path)}"]
 
@@ -89,8 +123,9 @@ def parse_peer_args(items: list[str]) -> dict[str, str]:
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description="Prepare or execute Tailscale bootstrap for the Bezalel VPS.")
-    parser.add_argument("--host", default=DEFAULT_HOST)
+    parser.add_argument("--host")
     parser.add_argument("--hostname", default=DEFAULT_HOSTNAME)
+    parser.add_argument("--inventory-path", type=Path, default=DEFAULT_INVENTORY_PATH)
     parser.add_argument("--auth-key", help="Tailscale auth key")
     parser.add_argument("--auth-key-file", type=Path, help="Path to file containing the Tailscale auth key")
     parser.add_argument("--ssh-public-key", help="SSH public key to append to authorized_keys")
@@ -116,6 +151,7 @@ def main() -> None:
     auth_key = _read_secret(args.auth_key, args.auth_key_file)
     ssh_public_key = _read_secret(args.ssh_public_key, args.ssh_public_key_file)
     peers = parse_peer_args(args.peer)
+    resolved_host, host_source = resolve_host(args.host, args.inventory_path, args.hostname)
 
     if not auth_key:
         raise SystemExit("Missing Tailscale auth key. Use --auth-key or --auth-key-file.")
@@ -126,28 +162,31 @@ def main() -> None:
     write_script(args.script_out, script)
 
     payload: dict[str, Any] = {
-        "host": args.host,
+        "host": resolved_host,
+        "host_source": host_source,
         "hostname": args.hostname,
+        "inventory_path": str(args.inventory_path),
         "script_out": str(args.script_out),
         "remote_script_path": args.remote_script_path,
-        "ssh_command": build_ssh_command(args.host, args.remote_script_path),
+        "ssh_command": build_ssh_command(resolved_host, args.remote_script_path),
         "peer_targets": peers,
         "applied": False,
     }
 
     if args.apply:
-        result = run_remote(args.host, args.remote_script_path)
+        result = run_remote(resolved_host, args.remote_script_path)
         payload["applied"] = True
         payload["exit_code"] = result.returncode
         payload["stdout"] = result.stdout
         payload["stderr"] = result.stderr
+        payload["verification"] = parse_apply_output(result.stdout)
 
     if args.json:
         print(json.dumps(payload, indent=2))
         return
 
     print("--- Bezalel Tailscale Bootstrap ---")
-    print(f"Host: {args.host}")
+    print(f"Host: {resolved_host} ({host_source})")
     print(f"Local script: {args.script_out}")
     print("SSH command: " + " ".join(payload["ssh_command"]))
     if args.apply:

scripts/hardware_mcp_integration.py

@@ -1,56 +0,0 @@
-#!/usr/bin/env python3
-"""Local Hardware MCP operator helper — generate config snippets and verify environment."""
-
-import os
-import sys
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parents[1]
-HERMES_CONFIG = Path.home() / ".hermes" / "config.yaml"
-HARDWARE_MCP_CONFIG = Path.home() / ".timmy" / "hardware" / "hardware_mcp_config.yaml"
-HARDWARE_SERVER = REPO_ROOT / "scripts" / "hardware_mcp_server.py"
-
-
-def build_mcp_config_snippet() -> str:
-    """Return the mcp_servers YAML snippet for ~/.hermes/config.yaml."""
-    return f"""mcp_servers:
-  hardware:
-    command: "python"
-    args: ["{HARDWARE_SERVER}"]
-"""
-
-
-def build_wakeup_hook() -> str:
-    """Return a bash snippet that can be sourced before Hermes starts (optional)."""
-    return f"""#!/usr/bin/env bash
-# Hardware MCP environment check
-if command -v openhue >/dev/null 2>&1; then
-  echo "[Hardware MCP] OpenHue found: $(openhue version)"
-else
-  echo "[Hardware MCP] Warning: openhue CLI not installed — light control disabled"
-fi
-"""
-
-
-def main():
-    import argparse
-    p = argparse.ArgumentParser(description="Hardware MCP integration helper")
-    p.add_argument("--print-config", action="store_true", help="Print mcp_servers YAML snippet")
-    p.add_argument("--print-hook", action="store_true", help="Print optional session-start hook")
-    p.add_argument("--verify", action="store_true", help="Verify server script exists and is executable")
-    args = p.parse_args()
-
-    if args.print_config:
-        print(build_mcp_config_snippet())
-    elif args.print_hook:
-        print(build_wakeup_hook())
-    elif args.verify:
-        ok = HARDWARE_SERVER.exists()
-        print(f"Server script: {'OK' if ok else 'MISSING'} at {HARDWARE_SERVER}")
-        sys.exit(0 if ok else 1)
-    else:
-        p.print_help()
-
-
-if __name__ == "__main__":
-    main()

scripts/hardware_mcp_server.py

@@ -1,206 +0,0 @@
-#!/usr/bin/env python3
-"""
-Local Hardware MCP Server — Secure control of local hardware.
-
-Exposes tools for:
-  - File system operations (read, write, list) within allowed directories
-  - Smart home control via OpenHue (Philips Hue lights)
-  - System information (safe, read-only)
-
-Security: Enforces directory allowlist for file access.
-"""
-
-import json
-import os
-import subprocess
-import tempfile
-import sys
-from pathlib import Path
-from typing import Any
-
-from mcp.server import Server
-from mcp.server.stdio import stdio_server
-from mcp.types import Tool, TextContent
-
-ALLOWED_DIRS = [
-    str(Path.home()),          # User home directory
-    "/tmp",                    # macOS symlink to /private/tmp
-    "/private/tmp",            # real tmp path
-    str(Path(tempfile.gettempdir())),  # actual system temp dir
-]
-OPENHUE_CMD = "openhue"
-MAX_FILE_SIZE = 10 * 1024 * 1024
-app = Server("hardware")
-
-
-def is_path_allowed(path: Path) -> bool:
-    try:
-        resolved = path.resolve()
-        return any(resolved.is_relative_to(Path(d).resolve()) for d in ALLOWED_DIRS)
-    except (ValueError, OSError):
-        return False
-
-
-def run_openhue(args: list[str]) -> dict[str, Any]:
-    try:
-        result = subprocess.run([OPENHUE_CMD] + args, capture_output=True, text=True, timeout=30)
-        return {
-            "success": result.returncode == 0,
-            "stdout": result.stdout.strip(),
-            "stderr": result.stderr.strip(),
-            "returncode": result.returncode,
-        }
-    except FileNotFoundError:
-        return {"success": False,
-                "error": "openhue CLI not found. Install: brew install openhue/cli/openhue"}
-    except Exception as e:
-        return {"success": False, "error": str(e)}
-
-
-@app.list_tools()
-async def list_tools():
-    return [
-        Tool(name="file_read",
-             description="Read a file from allowed directories (home, /tmp) up to 10 MB.",
-             inputSchema={"type": "object", "properties": {"path": {"type": "string",
-                          "description": "File path to read (e.g., ~/notes.txt)"}}, "required": ["path"]}),
-        Tool(name="file_write",
-             description="Write text content to a file within allowed directories.",
-             inputSchema={"type": "object", "properties": {"path": {"type": "string"},
-                          "content": {"type": "string"}}, "required": ["path", "content"]}),
-        Tool(name="file_list",
-             description="List files and directories in a given folder.",
-             inputSchema={"type": "object", "properties": {"directory": {"type": "string", "default": "~"}}, "required": []}),
-        Tool(name="light_list",
-             description="List all Hue lights, rooms, and scenes.",
-             inputSchema={"type": "object", "properties": {}, "required": []}),
-        Tool(name="light_control",
-             description="Control a Hue light: on/off, brightness 0-100, color name/hex, temperature 153-500 mirek.",
-             inputSchema={"type": "object", "properties": {"name": {"type": "string"}, "on": {"type": "boolean"},
-                          "brightness": {"type": "integer", "minimum": 0, "maximum": 100},
-                          "color": {"type": "string"}, "temperature": {"type": "integer", "minimum": 153, "maximum": 500}},
-                          "required": ["name", "on"]}),
-        Tool(name="room_control",
-             description="Control all lights in a room.",
-             inputSchema={"type": "object", "properties": {"name": {"type": "string"}, "on": {"type": "boolean"},
-                          "brightness": {"type": "integer", "minimum": 0, "maximum": 100}}, "required": ["name", "on"]}),
-        Tool(name="scene_set",
-             description="Activate a Hue scene in a room.",
-             inputSchema={"type": "object", "properties": {"scene": {"type": "string"}, "room": {"type": "string"}}, "required": ["scene", "room"]}),
-        Tool(name="system_info",
-             description="Get safe system info: OS, CPU count, memory, disk usage.",
-             inputSchema={"type": "object", "properties": {}, "required": []}),
-    ]
-
-
-@app.call_tool()
-async def call_tool(name: str, arguments: dict):
-    if name == "file_read":
-        path = Path(arguments["path"].strip()).expanduser()
-        if not is_path_allowed(path):
-            return [TextContent(type="text", text=json.dumps({"error": f"Path not allowed: {path}"}))]
-        if not path.is_file():
-            return [TextContent(type="text", text=json.dumps({"error": f"File not found: {path}"}))]
-        try:
-            size = path.stat().st_size
-            if size > MAX_FILE_SIZE:
-                return [TextContent(type="text", text=json.dumps({"error": f"File too large: {size} bytes"}))]
-            content = path.read_text()
-            return [TextContent(type="text", text=json.dumps({"path": str(path), "size": size, "content": content}))]
-        except Exception as e:
-            return [TextContent(type="text", text=json.dumps({"error": str(e)}))]
-
-    elif name == "file_write":
-        path = Path(arguments["path"].strip()).expanduser()
-        if not is_path_allowed(path):
-            return [TextContent(type="text", text=json.dumps({"error": f"Path not allowed: {path}"}))]
-        try:
-            path.parent.mkdir(parents=True, exist_ok=True)
-            path.write_text(arguments["content"])
-            return [TextContent(type="text", text=json.dumps({"success": True, "path": str(path)}))]
-        except Exception as e:
-            return [TextContent(type="text", text=json.dumps({"error": str(e)}))]
-
-    elif name == "file_list":
-        directory = Path(arguments.get("directory", "~").strip()).expanduser()
-        if not is_path_allowed(directory):
-            return [TextContent(type="text", text=json.dumps({"error": f"Directory not allowed: {directory}"}))]
-        if not directory.is_dir():
-            return [TextContent(type="text", text=json.dumps({"error": f"Not a directory: {directory}"}))]
-        try:
-            entries = []
-            for entry in sorted(directory.iterdir()):
-                try:
-                    stat = entry.stat()
-                    entries.append({"name": entry.name, "is_dir": entry.is_dir(),
-                                    "size": stat.st_size if entry.is_file() else None})
-                except (OSError, PermissionError):
-                    pass
-            return [TextContent(type="text", text=json.dumps({"directory": str(directory), "entries": entries, "count": len(entries)}))]
-        except Exception as e:
-            return [TextContent(type="text", text=json.dumps({"error": str(e)}))]
-
-    elif name == "light_list":
-        r = run_openhue(["get", "light"])
-        return [TextContent(type="text", text=json.dumps(r))]
-
-    elif name == "light_control":
-        args = ["set", "light", f'"{arguments["name"]}"']
-        if arguments.get("on") is not None:
-            args.append("--on" if arguments["on"] else "--off")
-        if brightness := arguments.get("brightness"):
-            args.append(f"--brightness {brightness}")
-        if color := arguments.get("color"):
-            args.append(f"--color {color}")
-        if temperature := arguments.get("temperature"):
-            args.append(f"--temperature {temperature}")
-        return [TextContent(type="text", text=json.dumps(run_openhue(args)))]
-
-    elif name == "room_control":
-        args = ["set", "room", f'"{arguments["name"]}"']
-        if arguments.get("on") is not None:
-            args.append("--on" if arguments["on"] else "--off")
-        if brightness := arguments.get("brightness"):
-            args.append(f"--brightness {brightness}")
-        return [TextContent(type="text", text=json.dumps(run_openhue(args)))]
-
-    elif name == "scene_set":
-        args = ["set", "scene", arguments["scene"], "--room", arguments["room"]]
-        return [TextContent(type="text", text=json.dumps(run_openhue(args)))]
-
-    elif name == "system_info":
-        try:
-            import platform
-            info = {"platform": platform.system(), "release": platform.release(),
-                    "arch": platform.machine(), "hostname": platform.node(),
-                    "cpu_count": os.cpu_count()}
-            try:
-                import psutil
-                mem = psutil.virtual_memory()
-                info["memory_gb"] = round(mem.total / (1024**3), 2)
-                disk = psutil.disk_usage(str(Path.home()))
-                info["disk_home_gb"] = round(disk.total / (1024**3), 2)
-            except ImportError:
-                info["memory_gb"] = "psutil not installed"
-                info["disk_home_gb"] = "psutil not installed"
-            return [TextContent(type="text", text=json.dumps(info, indent=2))]
-        except Exception as e:
-            return [TextContent(type="text", text=json.dumps({"error": str(e)}))]
-
-    else:
-        return [TextContent(type="text", text=json.dumps({
-            "error": f"Unknown tool: {name}",
-            "available": ["file_read", "file_write", "file_list", "light_list",
-                         "light_control", "room_control", "scene_set", "system_info"],
-        }))]
-
-
-async def main():
-    async with stdio_server() as (rs, ws):
-        await app.run(rs, ws, app.create_initialization_options())
-
-
-if __name__ == "__main__":
-    import asyncio
-    asyncio.run(main())
-

tests/test_bezalel_tailscale_bootstrap.py

@@ -2,9 +2,12 @@ from scripts.bezalel_tailscale_bootstrap import (
     DEFAULT_PEERS,
     build_remote_script,
     build_ssh_command,
+    parse_apply_output,
     parse_peer_args,
     parse_tailscale_status,
+    resolve_host,
 )
+from pathlib import Path
 
 
 def test_build_remote_script_contains_install_up_and_key_append():
@@ -78,3 +81,46 @@ def test_parse_peer_args_merges_overrides_into_defaults():
         "ezra": "100.126.61.76",
         "forge": "100.70.0.9",
     }
+
+
+def test_resolve_host_prefers_inventory_over_stale_default(tmp_path: Path):
+    inventory = tmp_path / "hosts.ini"
+    inventory.write_text(
+        "[fleet]\n"
+        "ezra ansible_host=143.198.27.163 ansible_user=root\n"
+        "bezalel ansible_host=67.205.155.108 ansible_user=root\n"
+    )
+
+    host, source = resolve_host(None, inventory)
+
+    assert host == "67.205.155.108"
+    assert source == f"inventory:{inventory}"
+
+
+def test_parse_apply_output_extracts_status_and_ping_markers():
+    stdout = (
+        '{"Self": {"HostName": "bezalel", "DNSName": "bezalel.tailnet.ts.net", "TailscaleIPs": ["100.90.0.10"]}, '
+        '"Peer": {"node-1": {"HostName": "ezra", "TailscaleIPs": ["100.126.61.75"]}}}'
+        "\nPING_OK:mac:100.124.176.28\n"
+        "PING_OK:ezra:100.126.61.75\n"
+    )
+
+    result = parse_apply_output(stdout)
+
+    assert result["tailscale"]["self"]["tailscale_ips"] == ["100.90.0.10"]
+    assert result["ping_ok"] == {"mac": "100.124.176.28", "ezra": "100.126.61.75"}
+
+
+def test_runbook_doc_exists_and_mentions_inventory_auth_and_peer_checks():
+    doc = Path("docs/BEZALEL_TAILSCALE_BOOTSTRAP.md")
+    assert doc.exists(), "missing docs/BEZALEL_TAILSCALE_BOOTSTRAP.md"
+    text = doc.read_text()
+    assert "ansible/inventory/hosts.ini" in text
+    assert "tailscale up" in text
+    assert "authorized_keys" in text
+    assert "100.124.176.28" in text
+    assert "100.126.61.75" in text
+
+    runbook = Path("docs/RUNBOOK_INDEX.md").read_text()
+    assert "Prepare Bezalel Tailscale bootstrap" in runbook
+    assert "scripts/bezalel_tailscale_bootstrap.py" in runbook

tests/test_hardware_mcp_functional.py

@@ -1,51 +0,0 @@
-#!/usr/bin/env python3
-"""Functional test for hardware_mcp_server — uses asyncio.get_event_loop for restricted envs."""
-
-import asyncio, json, tempfile, sys
-from pathlib import Path
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-from scripts.hardware_mcp_server import call_tool, is_path_allowed
-
-async def run_tests():
-    # Path allowlist
-    assert is_path_allowed(Path.home() / "any.txt")
-    assert is_path_allowed(Path("/tmp/foo"))
-    assert not is_path_allowed(Path("/etc/passwd"))
-    print("✓ Path allowlist")
-
-    # file_list on home
-    res = await call_tool("file_list", {"directory": "~"})
-    data = json.loads(res[0].text)
-    assert "entries" in data and data["count"] >= 0
-    print(f"✓ file_list works, entries: {data['count']}")
-
-    # file_write + file_read round-trip in temp dir
-    with tempfile.TemporaryDirectory() as td:
-        fp = Path(td) / "hmcp_test.txt"
-        content = "Hardware MCP round-trip OK"
-        w = await call_tool("file_write", {"path": str(fp), "content": content})
-        assert json.loads(w[0].text).get("success")
-        r = await call_tool("file_read", {"path": str(fp)})
-        assert json.loads(r[0].text)["content"] == content
-    print("✓ file write/read round-trip")
-
-    # file_read error: missing file
-    err = await call_tool("file_read", {"path": str(Path.home() / "no_such_file_xyz")})
-    assert "error" in json.loads(err[0].text)
-    print("✓ file_read reports missing file")
-
-    # Security: path traversal blocked
-    block = await call_tool("file_read", {"path": "/etc/passwd"})
-    bd = json.loads(block[0].text)
-    assert "not allowed" in bd.get("error", "").lower()
-    print("✓ Path traversal blocked")
-
-    print("\nAll functional checks passed!")
-
-if __name__ == "__main__":
-    # Use get_event_loop for environments where asyncio.run is disabled
-    try:
-        asyncio.run(run_tests())
-    except RuntimeError:
-        loop = asyncio.get_event_loop()
-        loop.run_until_complete(run_tests())

tests/test_hardware_mcp_server.py

@@ -1,126 +0,0 @@
-#!/usr/bin/env python3
-"""Smoke tests for hardware_mcp_server."""
-
-import json
-import os
-import subprocess
-import sys
-import tempfile
-from pathlib import Path
-from unittest import TestCase
-
-# Add repo root to path
-ROOT = Path(__file__).resolve().parent.parent
-sys.path.insert(0, str(ROOT))
-
-
-class TestHardwareMCPToolDefinitions(TestCase):
-    """Verify the MCP server is well-formed and tools have required schemas."""
-
-    def test_server_imports(self):
-        """Server module must import cleanly."""
-        import importlib.util
-        spec = importlib.util.spec_from_file_location(
-            "hardware_mcp_server",
-            ROOT / "scripts" / "hardware_mcp_server.py"
-        )
-        self.assertIsNotNone(spec)
-        mod = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(mod)
-        self.assertTrue(hasattr(mod, "app"))
-        self.assertTrue(hasattr(mod, "list_tools"))
-        self.assertTrue(hasattr(mod, "call_tool"))
-
-    def test_list_tools_returns_at_least_five_tools(self):
-        """list_tools() must return multiple tools covering file ops, lights, and system info."""
-        import asyncio
-        from scripts.hardware_mcp_server import list_tools
-        tools = asyncio.run(list_tools())
-        tool_names = [t.name for t in tools]
-        # Core capabilities
-        self.assertIn("file_read", tool_names)
-        self.assertIn("file_write", tool_names)
-        self.assertIn("file_list", tool_names)
-        self.assertIn("light_list", tool_names)
-        self.assertIn("light_control", tool_names)
-        self.assertIn("room_control", tool_names)
-        self.assertIn("scene_set", tool_names)
-        self.assertIn("system_info", tool_names)
-        self.assertGreaterEqual(len(tools), 8)
-
-    def test_file_read_schema_requires_path(self):
-        """file_read tool must require 'path' parameter."""
-        import asyncio
-        from scripts.hardware_mcp_server import list_tools
-        tools = asyncio.run(list_tools())
-        ft = next(t for t in tools if t.name == "file_read")
-        self.assertIn("path", ft.inputSchema["properties"])
-        self.assertIn("path", ft.inputSchema["required"])
-
-    def test_light_control_schema_requires_name_and_on(self):
-        """light_control requires name and on."""
-        import asyncio
-        from scripts.hardware_mcp_server import list_tools
-        tools = asyncio.run(list_tools())
-        ft = next(t for t in tools if t.name == "light_control")
-        self.assertIn("name", ft.inputSchema["required"])
-        self.assertIn("on", ft.inputSchema["required"])
-
-    def test_system_info_is_readonly(self):
-        """system_info tool takes no arguments."""
-        import asyncio
-        from scripts.hardware_mcp_server import list_tools
-        tools = asyncio.run(list_tools())
-        ft = next(t for t in tools if t.name == "system_info")
-        self.assertEqual(ft.inputSchema.get("required", []), [])
-        self.assertEqual(len(ft.inputSchema.get("properties", {})), 0)
-
-    def test_file_write_path_allowed_check(self):
-        """File write must enforce path allowlist (regression guard)."""
-        from scripts.hardware_mcp_server import is_path_allowed, Path
-        self.assertTrue(is_path_allowed(Path.home() / "test.txt"))
-        self.assertTrue(is_path_allowed(Path("/tmp/test.txt")))
-        # Outside allowed dirs should be rejected
-        self.assertFalse(is_path_allowed(Path("/etc/passwd")))
-
-    def test_run_openhue_error_handling(self):
-        """openhue runner returns structured error when CLI missing."""
-        from scripts.hardware_mcp_server import run_openhue
-        result = run_openhue(["get", "light"])
-        # On a system without openhue, must return success=False with helpful error
-        self.assertIn("success", result)
-        if not result.get("success"):
-            self.assertIn("error", result)
-            self.assertIn("openhue", result.get("error", "").lower())
-
-
-class TestHardwareMCPConfigCompleteness(TestCase):
-    """Validate config template matches tool set."""
-
-    def test_config_template_exists(self):
-        self.assertTrue((ROOT / "timmy-local" / "hardware_mcp_config.yaml").exists())
-
-    def test_config_lists_all_tools(self):
-        with open(ROOT / "timmy-local" / "hardware_mcp_config.yaml") as f:
-            content = f.read()
-        # All tool names should appear in the tools: section
-        for tool in ["file_read", "file_write", "file_list", "light_list",
-                     "light_control", "room_control", "scene_set", "system_info"]:
-            self.assertIn(tool, content, f"Tool {tool} missing from config tools list")
-
-    def test_config_has_security_guards(self):
-        with open(ROOT / "timmy-local" / "hardware_mcp_config.yaml") as f:
-            content = f.read()
-        self.assertIn("max_consecutive_errors", content)
-        self.assertIn("allowed_dirs", content)
-        self.assertIn("max_file_size_bytes", content)
-
-    def test_config_has_server_key(self):
-        with open(ROOT / "timmy-local" / "hardware_mcp_config.yaml") as f:
-            content = f.read()
-        self.assertIn("server_key: hardware", content)
-
-
-if __name__ == "__main__":
-    import unittest
-    unittest.main()

timmy-local/hardware/README.md

@@ -1,3 +0,0 @@
-# hardware MCP config
-
-Copy `hardware_mcp_config.yaml` to `~/.timmy/hardware/hardware_mcp_config.yaml` to enable runtime tuning.

timmy-local/hardware_mcp_config.yaml

@@ -1,67 +0,0 @@
-# ═══════════════════════════════════════════════════════════════════════
-# Local Hardware MCP — Runtime Configuration
-# ═══════════════════════════════════════════════════════════════════════
-# Edit this file to tune hardware control settings.
-# Hermes loads this at session start when the hardware MCP server is enabled.
-#
-# Location: ~/.timmy/hardware/hardware_mcp_config.yaml
-# ═══════════════════════════════════════════════════════════════════════
-
-# ── Server Identity ───────────────────────────────────────────────────
-server_key: hardware
-
-# ── Tool Names ────────────────────────────────────────────────────────
-# Exact tool names Hermes registers.  Update if you rename tools in
-# hardware_mcp_server.py.
-tools:
-  - name: file_read
-    hint: "Read a file from an allowed directory (home, /tmp). Max 10 MB."
-  - name: file_write
-    hint: "Write text content to a file within allowed directories."
-  - name: file_list
-    hint: "List files and directories in a given folder."
-  - name: light_list
-    hint: "List all Hue lights, rooms, and scenes from OpenHue."
-  - name: light_control
-    hint: "Control a specific Hue light: on/off, brightness, color, temperature."
-  - name: room_control
-    hint: "Control all lights in a room: on/off, brightness."
-  - name: scene_set
-    hint: "Activate a Hue scene in a room."
-  - name: system_info
-    hint: "Get safe system information: OS, CPU count, memory usage, disk space."
-
-# ── Security Guards ───────────────────────────────────────────────────
-guards:
-  # Maximum consecutive tool errors before stopping.
-  max_consecutive_errors: 3
-
-  # Max total hardware MCP calls per session (0 = unlimited).
-  max_mcp_calls_per_session: 0
-
-  # Allowed directories for file operations (expanded paths).
-  allowed_dirs:
-    - "~"
-    - "/tmp"
-    - "/private/tmp"
-
-  # Maximum file size for reads (bytes).
-  max_file_size_bytes: 10485760  # 10 MB
-
-# ── OpenHue ───────────────────────────────────────────────────────────
-# Path to openhue CLI (auto-detected if in PATH).
-openhue_command: "openhue"
-
-# ── Dependencies ───────────────────────────────────────────────────────
-# Prerequisites:
-#   - OpenHue CLI: brew install openhue/cli/openhue (macOS) or see https://github.com/openhue/openhue-cli
-#   - MCP SDK: pip install mcp
-#   - For system_info: pip install psutil (optional, for detailed memory/disk metrics)
-#
-# Config in ~/.hermes/config.yaml:
-#   mcp_servers:
-#     hardware:
-#       command: "python"
-#       args: ["/Users/you/path/to/timmy-home/scripts/hardware_mcp_server.py"]
-#       env:
-#         OPENHUE_BRIDGE_IP: "192.168.1.xx"  # optional, if openhue needs it