# WireGuard VPN Functional Fix — End-to-End

## TL;DR

> **Quick Summary**: Fix 4 blocking gaps that prevent WireGuard VPN from functioning end-to-end: server wg0 has no IP, no peers are synced to kernel interface, no NAT/masquerade, and device-agent TUN has no IP. Full fix across 10 files in server-core and device-agent.

> **Deliverables**:
> - Server wg0 gets `InterfaceAddress` from DB applied (`ip addr add`)
> - `WgManager.SyncPeers()` replaces ALL peers on wg0 atomically
> - nftables masquerade + `ip_forward=1` on `Up()`
> - All device create/delete/suspend/provision actions sync peers
> - Device-agent assigns `InternalIP` to TUN device
> - Unit + integration tests for the new logic

> **Estimated Effort**: Medium
> **Parallel Execution**: YES — 4 waves
> **Critical Path**: Interface types → Linux impl → Handler wiring → Device-agent

---

## Context

### Original Request
WireGuard VPN tidak berfungsi end-to-end. Tombol Turn ON/OFF di dashboard tidak terkoneksi dengan Menu Nodes, dan peers tidak bisa saling terkoneksi karena 4 gap kritis.

### Interview Summary
**Key Discussions**:
- **Scope**: ALL gaps — server IP, peer management, NAT, device-agent IP
- **Test strategy**: Tests-after with unit + integration tests
- **NAT interface**: Auto-detect via `ip route show default`, manual override via `WG_NAT_INTERFACE` env var
- **Peer sync design**: `SyncPeers()` (replace-all), not individual add/remove — atomic safety

### Research Findings
- `wgmanager_linux.go:Up()` creates wg0 interface but NO IP assignment, NO routes, NO NAT
- `WgManager` interface has only `GetStatus()`, `Up()`, `Down()` — no peer management
- `api/devices.go`, `api/peers.go`, `api/provisioning.go` create devices but NEVER add peers to wg0 kernel
- `device-agent/main.go` receives `InternalIP` from provisioning but only logs it
- `models.WgServer` already has `InterfaceAddress`, `IPPoolCIDR` stored in DB but never applied

---

## Work Objectives

### Core Objective
WireGuard VPN berfungsi penuh: server wg0 punya IP, peers tersync ke kernel, NAT/forwarding aktif, device-agent punya IP di TUN.

### Concrete Deliverables
- File: `internal/wgmanager/manager.go` — expanded interface + new types
- File: `internal/wgmanager/wgmanager_linux.go` — IP assignment, SyncPeers, NAT
- File: `internal/wgmanager/wgmanager_stub.go` — match new interface
- Files: `api/wg.go`, `api/devices.go`, `api/peers.go`, `api/provisioning.go` — handler integration
- File: `main.go` — inject wgMgr to new handlers
- Files: `device-agent/internal/tunnel/wireguard.go`, `device-agent/main.go` — agent IP assignment
- New test files: `internal/wgmanager/*_test.go`, `api/devices_test.go` (extend), `api/wg_test.go`

### Definition of Done
- [x] `make test` passes (all existing + new tests) ✅
- [ ] `npm run build` passes (dashboard) — requires submodule init
- [x] Server wg0 gets `ip addr add <InterfaceAddress> dev wg0` on Up() ✅
- [x] nftables masquerade rule + `ip_forward=1` on Up() ✅
- [x] Creating a device → `SyncPeers()` called → peers synced to kernel (tested via mock) ✅
- [x] Suspending a device → `SyncPeers()` called → peer removed from query (tested via mock) ✅
- [x] Deleting a device → `SyncPeers()` called → peer removed (tested via mock) ✅
- [x] Provisioning via agent → sync called after tx.Commit ✅
- [x] Turn Off (Down) → wg0 removed via `ip link del` ✅
- [x] Turn On (Up) → all active peers restored via `SyncLocalPeers()` after `Up()` ✅

### Must Have
- Server wg0 gets InterfaceAddress assigned from DB
- Peers are synced to kernel wg0 on create/delete/suspend/provision
- NAT masquerade + IP forwarding enabled when wg is up
- Device-agent assigns InternalIP to TUN device
- All existing tests continue to pass

### Must NOT Have (Guardrails)
- Do NOT modify `shared/crypto/encryptor.go` (duplicated, known debt)
- Do NOT change existing test patterns (sqlite in-memory, mock middleware)
- Do NOT touch heartbeat/redis, firewall nftables init, or IPAM allocation logic
- Do NOT refactor handler auth duplication
- Do NOT execute `nft flush table` anywhere
- Do NOT log encryption keys or provisioning tokens

---

## Verification Strategy

> **ZERO HUMAN INTERVENTION** — ALL verification is agent-executed.

### Test Decision
- **Infrastructure exists**: YES (Go tests, sqlite in-memory)
- **Automated tests**: Tests-after
- **Framework**: Go `testing` package
- **Stub tests**: Unit test `wgmanager_stub.go` for interface contract
- **Linux tests**: Skipped via build tags; verified via QA scenarios on Linux infra
- **Handler tests**: Integration tests with mocked `WgManager`

### QA Policy
Every task MUST include agent-executed QA scenarios. Evidence saved to `.sisyphus/evidence/task-{N}-{scenario}.{ext}`.

- **Backend Go**: `go test -tags dev ./... -v -count=1`
- **Linux-only code**: Run `go build -tags linux` to verify compilation
- **nftables/WG**: tmux interactive_bash on Linux container

---

## Execution Strategy

### Parallel Execution Waves

```
Wave 1 (Types + Interface — foundation):
├── Task 1: Update WgManager interface — add PeerConfig, UpConfig, SyncPeers(), new Up() sig
├── Task 2: Update wgmanager_stub.go — match new interface
├── Task 3: Dashboard.vue frontend sync fix (already done)
└── Task 4: Add helpers.go — syncDevicePeers(), defaultRouteInterface()

Wave 2 (Linux implementation — core engine):
├── Task 5: wgmanager_linux.go — IP address assignment on Up()
├── Task 6: wgmanager_linux.go — SyncPeers() implementation
├── Task 7: wgmanager_linux.go — nftables masquerade + ip_forward on Up()
└── Task 8: wgmanager_linux.go — NAT cleanup on Down()

Wave 3 (Handler integration — wire everything):
├── Task 9: api/wg.go — pass InterfaceAddress/PoolCIDR, sync peers after Up
├── Task 10: api/devices.go — add WgManager dep, sync peers on create/delete/suspend
├── Task 11: api/peers.go — add WgManager dep, sync peers on create
├── Task 12: api/provisioning.go — add WgManager dep, sync peers on provision
└── Task 13: main.go — wire wgMgr to handlers

Wave 4 (Device-agent — client-side fix):
├── Task 14: tunnel/wireguard.go — add internalIP param, ip addr add
└── Task 15: main.go — pass cfg.InternalIP to StartStealthTunnel()

Wave 5 (Tests + QA — verification):
├── Task 16: Unit tests for wgmanager (stub interface contract)
├── Task 17: Integration tests — handler Create/Delete/Suspend peer sync flow
└── Task 18: Manual QA — full end-to-end verification on Linux

Critical Path: Task 1 → Task 5/6 → Task 9 → Task 10/11/12 → Task 13 → verify
```

---

## TODOs

> Implementation + Test = ONE Task. Every task MUST have QA Scenarios.

- [x] 1. Update `WgManager` Interface — Add Types + Methods

  **What to do**:
  - In `internal/wgmanager/manager.go`, add these types:
    ```go
    type PeerConfig struct {
        PublicKey    string
        PresharedKey string
        AllowedIPs   string // comma-separated CIDRs
    }
    
    type UpConfig struct {
        ListenPort       int
        PrivateKeyHex    string
        InterfaceAddress string // e.g., "10.0.0.1/24"
        PoolCIDR         string // e.g., "10.0.0.0/24"
    }
    ```
  - Change `Up(listenPort int, privateKeyHex string) error` → `Up(cfg UpConfig) error`
  - Add `SyncPeers(peers []PeerConfig) error` to the `WgManager` interface
  - Add `sync.Mutex` field comment (will be implemented in linux/stub)
  - Preserve all existing method signatures (`GetStatus`, `Down`)

  **Must NOT do**:
  - Do NOT change `WgStatus` struct
  - Do NOT modify existing `Down()` or `GetStatus()` signatures

  **Recommended Agent Profile**:
  - **Category**: `quick`
    - Reason: Simple type definitions and interface changes, no complex logic
  - **Skills**: `[]`
  
  **Parallelization**:
  - **Can Run In Parallel**: YES
  - **Parallel Group**: Wave 1 (with Tasks 2, 4)
  - **Blocks**: Tasks 5, 6, 7, 8, 9
  - **Blocked By**: None (start immediately)

  **References**:
  - `internal/wgmanager/manager.go:18-22` — Current interface to extend
  - `internal/wgmanager/wgmanager_linux.go:14-20` — Current struct to see deviceName field
  - `internal/wgmanager/wgmanager_stub.go:5-9` — Current stub struct

  **Acceptance Criteria**:
  - [ ] `go build -tags dev ./internal/wgmanager/...` passes
  - [ ] All types (`PeerConfig`, `UpConfig`) exported and usable
  - [ ] Interface has `SyncPeers([]PeerConfig) error` method
  - [ ] `Up()` signature changed to accept `UpConfig`

  **QA Scenarios**:
  ```
  Scenario: Interface compiles with new types
    Tool: Bash
    Preconditions: Go toolchain installed
    Steps:
      1. cd apps/server-core
      2. go vet -tags dev ./internal/wgmanager/...
    Expected Result: Exit code 0, no errors
    Evidence: .sisyphus/evidence/task-1-interface-compile.txt
  ```
  
  **Commit**: YES
  - Message: `feat(wgmanager): add PeerConfig, UpConfig types and SyncPeers method`
  - Files: `apps/server-core/internal/wgmanager/manager.go`

- [x] 2. Update `wgmanager_stub.go` — Match New Interface

  **What to do**:
  - Update `StubWgManager.Up()` signature to accept `UpConfig`
  - Add no-op `SyncPeers(peers []PeerConfig) error` returning nil
  - Keep all existing no-op behavior

  **Must NOT do**:
  - Do NOT add any real logic (stub is for non-Linux builds)

  **Recommended Agent Profile**:
  - **Category**: `quick`
    - Reason: Trivial stub method updates
  - **Skills**: `[]`

  **Parallelization**:
  - **Can Run In Parallel**: YES
  - **Parallel Group**: Wave 1 (with Tasks 1, 4)
  - **Blocks**: Tasks 5-13
  - **Blocked By**: Task 1

  **References**:
  - `internal/wgmanager/wgmanager_stub.go` — Full file to modify
  - Updated `manager.go` from Task 1 — interface contract to match

  **Acceptance Criteria**:
  - [ ] `go build -tags dev ./internal/wgmanager/...` passes
  - [ ] `go build -tags '!linux' ./internal/wgmanager/...` passes (stub build)
  - [ ] `StubWgManager` implements all methods of `WgManager`

  **QA Scenarios**:
  ```
  Scenario: Stub compiles on non-Linux
    Tool: Bash
    Preconditions: Go toolchain installed
    Steps:
      1. cd apps/server-core
      2. go build -tags '!linux' ./internal/wgmanager/...
    Expected Result: Exit code 0
    Evidence: .sisyphus/evidence/task-2-stub-compile.txt
  ```

  **Commit**: YES (group with task 1)
  - Files: `apps/server-core/internal/wgmanager/wgmanager_stub.go`

- [x] 3. Dashboard.vue — Sync WG Toggle with Nodes Menu Status (ALREADY FIXED)

  **What to do**: Verify the fix is already applied. The fix added `fetchServers()` call after `handleToggleWg()` and in the 10s polling interval.

  **Must NOT do**: Do NOT re-apply or modify

  **Recommended Agent Profile**:
  - **Category**: `quick`
    - Reason: Verification task only
  - **Skills**: `[]`

  **Parallelization**:
  - **Can Run In Parallel**: YES
  - **Parallel Group**: Wave 1
  - **Blocks**: None
  - **Blocked By**: None

  **References**:
  - `apps/dashboard-ui/src/views/Dashboard.vue:52-95` — Already fixed

  **Acceptance Criteria**:
  - [ ] `Dashboard.vue` imports `fetchServers` and calls it after toggle + in interval

  **QA Scenarios**: None (verification only)

  **Commit**: NO (already applied)

- [x] 4. Add `syncDevicePeers()` Helper and `defaultRouteInterface()` Helper

  **What to do**:
  - In `api/helpers.go` (or new file `api/peer_sync.go`), add:
    ```go
    package api
    
    type PeerSyncer struct {
        db   *gorm.DB
        mgr  wgmanager.WgManager
    }
    
    func NewPeerSyncer(db *gorm.DB, mgr wgmanager.WgManager) *PeerSyncer {
        return &PeerSyncer{db: db, mgr: mgr}
    }
    
    // SyncLocalPeers reads all active, non-suspended devices for the
    // Local Primary Node and syncs them to the kernel wg0 interface.
    // No-op if wg0 is not running.
    func (s *PeerSyncer) SyncLocalPeers() {
        status, err := s.mgr.GetStatus()
        if err != nil || !status.IsRunning {
            return // wg0 is not running, no point syncing
        }
        
        var localServer models.WgServer
        if err := s.db.Where("name = ?", "Local Primary Node").First(&localServer).Error; err != nil {
            return
        }
        
        var devices []models.Device
        s.db.Where("wg_server_id = ? AND is_suspended = ? AND internal_ip IS NOT NULL", 
            localServer.ID, false).Find(&devices)
        
        var peers []wgmanager.PeerConfig
        for _, d := range devices {
            allowedIPs := *d.InternalIP + "/32"
            if d.AllowInternet {
                allowedIPs = "0.0.0.0/0"
            }
            if d.EndpointAllowedIPs != "" {
                allowedIPs = d.EndpointAllowedIPs
            }
            peers = append(peers, wgmanager.PeerConfig{
                PublicKey:    d.PublicKey,
                PresharedKey: d.PresharedKey,
                AllowedIPs:   allowedIPs,
            })
        }
        
        if err := s.mgr.SyncPeers(peers); err != nil {
            log.Printf("ERROR: Failed to sync peers: %v", err)
        }
    }
    ```
  - In `internal/wgmanager/manager.go`, add:
    ```go
    // DefaultRouteInterface returns the interface name of the default route.
    // Used for NAT masquerade. Falls back to "eth0" if detection fails.
    func DefaultRouteInterface() string {
        if env := os.Getenv("WG_NAT_INTERFACE"); env != "" {
            return env
        }
        out, err := exec.Command("sh", "-c", "ip route show default | awk '{print $5}'").Output()
        if err != nil || len(out) == 0 {
            return "eth0"
        }
        return strings.TrimSpace(string(out))
    }
    ```
  - Import `log`, `os`, `os/exec`, `strings` as needed

  **Must NOT do**:
  - Do NOT add any peer sync logic related to external (non-local) servers
  - Do NOT modify existing handlers' constructor signatures yet

  **Recommended Agent Profile**:
  - **Category**: `quick`
    - Reason: Single helpers file with straightforward logic
  - **Skills**: `[]`

  **Parallelization**:
  - **Can Run In Parallel**: YES
  - **Parallel Group**: Wave 1 (with Tasks 1, 2)
  - **Blocks**: Tasks 9, 10, 11, 12, 13
  - **Blocked By**: Task 1 (needs PeerConfig type)

  **References**:
  - `api/helpers.go` — Existing helper functions location
  - `api/devices.go:86-117` — Device creation pattern to understand AllowedIPs logic
  - `api/peers.go:120-126` — AllowedIPs assignment pattern
  - `api/servers.go:50-53` — "Local Primary Node" name check pattern
  - `internal/wgmanager/manager.go:UpConfig` (from Task 1) — PoolCIDR for masquerade

  **Acceptance Criteria**:
  - [ ] `go build -tags dev ./...` passes
  - [ ] `PeerSyncer` exported and constructable
  - [ ] `DefaultRouteInterface()` returns "eth0" or detected interface
  - [ ] `SyncLocalPeers()` is safe to call when wg0 is down (no-op)

  **QA Scenarios**:
  ```
  Scenario: DefaultRouteInterface returns non-empty string
    Tool: Bash
    Preconditions: Linux machine with default route
    Steps:
      1. cd apps/server-core
      2. go test -tags dev -run TestDefaultRouteInterface -v ./internal/wgmanager/
    Expected Result: Test passes, interface name returned
    Evidence: .sisyphus/evidence/task-4-route-interface.txt
  ```

  **Commit**: YES
  - Message: `feat(api): add PeerSyncer helper and DefaultRouteInterface utility`
  - Files: `apps/server-core/api/peer_sync.go`, `apps/server-core/internal/wgmanager/manager.go`

---

## TODOs (continued)

- [x] 5. `wgmanager_linux.go` — IP Address Assignment on `Up()`

  **What to do**:
  - Update `func (m *LinuxWgManager) Up(cfg UpConfig) error` to:
    1. Keep existing interface creation + wgctrl config + `ip link set up` (unchanged)
    2. NEW: After interface is up, assign IP address:
       ```go
       if cfg.InterfaceAddress != "" {
           // Remove existing IP if any, then assign
           exec.Command("ip", "addr", "flush", "dev", m.deviceName).Run()
           if err := exec.Command("ip", "addr", "add", cfg.InterfaceAddress, "dev", m.deviceName).Run(); err != nil {
               return fmt.Errorf("failed to assign IP %s to %s: %w", cfg.InterfaceAddress, m.deviceName, err)
           }
       }
       ```
    3. Add `sync.Mutex` usage:
       ```go
       type LinuxWgManager struct {
           deviceName string
           mu         sync.Mutex
       }
       ```
    4. Lock/unlock in `Up()`, `Down()`, `GetStatus()`, `SyncPeers()`
  - Import `sync` package

  **Must NOT do**:
  - Do NOT change the interface creation logic (kernel module → wireguard-go fallback)
  - Do NOT add NAT or ip_forward here (separate task)
  - Do NOT add SyncPeers logic here (separate task)

  **Recommended Agent Profile**:
  - **Category**: `deep`
    - Reason: Linux kernel interface operations
  - **Skills**: `[]`

  **Parallelization**:
  - **Can Run In Parallel**: NO (sequential within Wave 2)
  - **Parallel Group**: Wave 2 (sequential: 5 → 6 → 7 → 8)
  - **Blocks**: Tasks 6, 7, 8, 9
  - **Blocked By**: Task 1 (needs UpConfig type)

  **References**:
  - `internal/wgmanager/wgmanager_linux.go:54-99` — Current Up() implementation
  - `models.WgServer.InterfaceAddress`, `IPPoolCIDR` — Values passed via UpConfig

  **Acceptance Criteria**:
  - [ ] `go build -tags linux ./internal/wgmanager/...` passes
  - [ ] Mutex used in all exported methods
  - [ ] `ip addr flush` + `ip addr add` called after `ip link set up`

  **QA Scenarios**:
  ```
  Scenario: Linux build compiles
    Tool: Bash
    Steps: go build -tags linux ./internal/wgmanager/...
    Expected: exit 0
    Evidence: .sisyphus/evidence/task-5-linux-build.txt
  ```

  **Commit**: YES (group with Tasks 6, 7, 8)

- [x] 6. `wgmanager_linux.go` — `SyncPeers()` Implementation

  **What to do**:
  - Implement `func (m *LinuxWgManager) SyncPeers(peers []PeerConfig) error`:
    ```go
    func (m *LinuxWgManager) SyncPeers(peers []PeerConfig) error {
        m.mu.Lock()
        defer m.mu.Unlock()
        
        client, err := wgctrl.New()
        if err != nil {
            return fmt.Errorf("failed to open wgctrl: %w", err)
        }
        defer client.Close()
        
        var wgPeers []wgtypes.PeerConfig
        for _, p := range peers {
            pubKey, err := wgtypes.ParseKey(p.PublicKey)
            if err != nil {
                log.Printf("WARNING: Skipping invalid public key: %v", err)
                continue
            }
            var psk wgtypes.Key
            if p.PresharedKey != "" {
                if k, err := wgtypes.ParseKey(p.PresharedKey); err == nil {
                    psk = k
                }
            }
            var allowedIPs []net.IPNet
            for _, cidr := range strings.Split(p.AllowedIPs, ",") {
                cidr = strings.TrimSpace(cidr)
                if cidr == "" { continue }
                if _, ipNet, err := net.ParseCIDR(cidr); err == nil {
                    allowedIPs = append(allowedIPs, *ipNet)
                }
            }
            wgPeers = append(wgPeers, wgtypes.PeerConfig{
                PublicKey:         pubKey,
                PresharedKey:      &psk,
                AllowedIPs:        allowedIPs,
                ReplaceAllowedIPs: true,
            })
        }
        
        cfg := wgtypes.Config{
            ReplacePeers: true, // atomic replacement
            Peers:        wgPeers,
        }
        return client.ConfigureDevice(m.deviceName, cfg)
    }
    ```
  - Add imports: `net`, `strings`, `log`

  **Must NOT do**:
  - Do NOT add individual AddPeer/RemovePeer (SyncPeers replaces atomically)

  **Recommended Agent Profile**:
  - **Category**: `deep`
    - Reason: wgctrl netlink API, key parsing, CIDR handling
  - **Skills**: `[]`

  **Parallelization**: NO (Wave 2, after Task 5)
  - **Blocked By**: Task 1 (PeerConfig type), Task 5 (mutex in struct)

  **Acceptance Criteria**:
  - [ ] `go build -tags linux ./internal/wgmanager/...` passes
  - [ ] Empty peers slice removes all peers (clean interface)
  - [ ] Comma-separated AllowedIPs parsed correctly
  - [ ] Mutex locked during entire operation

  **QA Scenarios**:
  ```
  Scenario: SyncPeers compiles
    Tool: Bash
    Steps: go build -tags linux ./internal/wgmanager/...
    Expected: exit 0
    Evidence: .sisyphus/evidence/task-6-syncpeers-compile.txt
  ```

  **Commit**: YES (group with Tasks 5, 7, 8)

- [x] 7. `wgmanager_linux.go` — nftables Masquerade + IP Forwarding

  **What to do**:
  - Extend `Up(cfg UpConfig)` after IP assignment:
    ```go
    // Enable IP forwarding
    exec.Command("sysctl", "-w", "net.ipv4.ip_forward=1").Run()
    
    // Setup nftables masquerade
    if cfg.PoolCIDR != "" {
        exec.Command("sh", "-c",
            "nft add table ip nat 2>/dev/null; "+
            "nft add chain ip nat postrouting { type nat hook postrouting priority 100 \\; \\} 2>/dev/null").Run()
        
        natIface := DefaultRouteInterface()
        checkCmd := fmt.Sprintf("nft -a list chain ip nat postrouting 2>/dev/null | grep -q 'oif \"%s\".*masquerade'", natIface)
        if exec.Command("sh", "-c", checkCmd).Run() != nil {
            rule := fmt.Sprintf("nft add rule ip nat postrouting oif %q ip saddr %s masquerade", natIface, cfg.PoolCIDR)
            exec.Command("sh", "-c", rule).Run()
        }
    }
    ```
  - NAT setup failures are non-fatal (log warning)

  **Must NOT do**:
  - Do NOT `nft flush table`
  - Do NOT fail Up() on NAT setup failure

  **Recommended Agent Profile**:
  - **Category**: `deep`
    - Reason: nftables nat, Linux networking
  - **Skills**: `[]`

  **Parallelization**: NO (Wave 2, after Task 6)
  - **Blocked By**: Task 4 (DefaultRouteInterface), Task 5 (Up() extension)

  **Acceptance Criteria**:
  - [ ] Masquerade rule added for PoolCIDR on default route interface
  - [ ] ip_forward=1 enabled
  - [ ] Calling Up() twice doesn't duplicate masquerade rules

  **QA Scenarios**:
  ```
  Scenario: No duplicate NAT rules
    Tool: Bash (Linux)
    Preconditions: wg0 up with NAT
    Steps: Run Up() twice, count masquerade rules
    Expected: Exactly 1 masquerade rule
    Evidence: .sisyphus/evidence/task-7-nat-dedup.txt
  ```

  **Commit**: YES (group with Tasks 5, 6, 8)

- [x] 8. `wgmanager_linux.go` — NAT Cleanup on `Down()`

  **What to do**:
  - Extend `Down()` to remove masquerade rule before deleting interface:
    ```go
    func (m *LinuxWgManager) Down() error {
        m.mu.Lock()
        defer m.mu.Unlock()
        
        // Remove masquerade rule (non-fatal)
        out, _ := exec.Command("sh", "-c",
            "nft -a list chain ip nat postrouting 2>/dev/null | awk '/masquerade/ {print $NF}'").Output()
        if handle := strings.TrimSpace(string(out)); handle != "" {
            exec.Command("sh", "-c", fmt.Sprintf("nft delete rule ip nat postrouting handle %s", handle)).Run()
        }
        
        // Delete WG interface
        return exec.Command("ip", "link", "del", "dev", m.deviceName).Run()
    }
    ```
  - NAT cleanup failures are non-fatal (logged, not returned)

  **Must NOT do**:
  - Do NOT disable ip_forward (harmless, other services may depend on it)
  - Do NOT delete entire nat table

  **Recommended Agent Profile**:
  - **Category**: `deep`
    - Reason: nftables handle-based deletion, error-resilient cleanup
  - **Skills**: `[]`

  **Parallelization**: NO (Wave 2, after Task 7)

  **Acceptance Criteria**:
  - [ ] Down() removes masquerade rule by handle
  - [ ] Down() deletes wg0 interface
  - [ ] All cleanup failures logged, not fatal

  **QA Scenarios**:
  ```
  Scenario: Down() cleans NAT rule
    Tool: Bash (Linux)
    Preconditions: wg0 up with NAT
    Steps: Down() → check nft list chain ip nat postrouting
    Expected: No masquerade rule
    Evidence: .sisyphus/evidence/task-8-nat-cleanup.txt
  ```

  **Commit**: YES (group with Tasks 5, 6, 7)

---

## TODOs (continued)

- [x] 9. `api/wg.go` — Pass InterfaceAddress/PoolCIDR and Sync Peers After Up

  **What to do**:
  - Modify `WgHandler` to accept `*PeerSyncer` in constructor or store `*gorm.DB` + `wgmanager.WgManager` directly
  - Actually: Modify `WgHandler` to include `syncer *PeerSyncer` field:
    ```go
    type WgHandler struct {
        db     *gorm.DB
        mgr    wgmanager.WgManager
        syncer *PeerSyncer
    }
    
    func NewWgHandler(db *gorm.DB, mgr wgmanager.WgManager, syncer *PeerSyncer) *WgHandler {
        return &WgHandler{db: db, mgr: mgr, syncer: syncer}
    }
    ```
  - In `Up()` handler: build `UpConfig` from DB model and pass to `mgr.Up()`:
    ```go
    func (h *WgHandler) Up(c *gin.Context) {
        // ... existing admin check ...
        
        var wgServer models.WgServer
        if err := h.db.First(&wgServer).Error; err != nil {
            c.JSON(http.StatusInternalServerError, gin.H{"error": "No WireGuard node configured"})
            return
        }
        
        // Parse InterfaceAddress from DB (e.g., "10.0.0.1" → "10.0.0.1/24")
        interfaceAddr := ""
        if wgServer.InterfaceAddress != "" && wgServer.IPPoolCIDR != "" {
            _, ipnet, _ := net.ParseCIDR(wgServer.IPPoolCIDR)
            if ipnet != nil {
                ones, _ := ipnet.Mask.Size()
                interfaceAddr = fmt.Sprintf("%s/%d", wgServer.InterfaceAddress, ones)
            }
        }
        
        cfg := wgmanager.UpConfig{
            ListenPort:       wgServer.ListenPort,
            PrivateKeyHex:    privHex,
            InterfaceAddress: interfaceAddr,
            PoolCIDR:         wgServer.IPPoolCIDR,
        }
        
        if err := h.mgr.Up(cfg); err != nil {
            c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
            return
        }
        
        // Sync all active peers after bringing up
        h.syncer.SyncLocalPeers()
        
        c.JSON(http.StatusOK, gin.H{"status": "up", "public_key": wgServer.PublicKey})
    }
    ```
  - In `Down()` handler: after `mgr.Down()`, peers are automatically removed (interface deleted) — no extra sync needed
  - Note: The existing privKey parsing logic stays the same

  **Must NOT do**:
  - Do NOT change `Status()` or `Down()` handlers except for wgHandler struct
  - Do NOT modify `models.WgServer` or `wgmanager.WgManager` interface

  **Recommended Agent Profile**:
  - **Category**: `unspecified-high`
    - Reason: Handler logic changes, dependency injection pattern, CIDR parsing
  - **Skills**: `[]`

  **Parallelization**:
  - **Can Run In Parallel**: NO
  - **Parallel Group**: Wave 3 (sequential with 10, 11, 12, 13)
  - **Blocks**: Tasks 10, 11, 12, 13
  - **Blocked By**: Tasks 4 (PeerSyncer), 5/6 (UpConfig, SyncPeers impl)

  **References**:
  - `api/wg.go:14-77` — Full file to modify
  - `api/wg.go:38-63` — Current Up() handler
  - `net.ParseCIDR()`, `net.IPNet.Mask.Size()` — CIDR prefix detection
  - `internal/wgmanager/manager.go:UpConfig` — Struct to build

  **Acceptance Criteria**:
  - [ ] `go build -tags dev ./...` passes
  - [ ] `Up()` handler builds `UpConfig` with InterfaceAddress + PoolCIDR from DB
  - [ ] IP address prefix derived from IPPoolCIDR (e.g., /24)
  - [ ] `SyncLocalPeers()` called after wg is up
  - [ ] InterfaceAddress is empty string when not configured (Backward compatible)

  **QA Scenarios**:
  ```
  Scenario: Up handler builds correct UpConfig
    Tool: Bash (go test)
    Steps: go test -tags dev -run TestWgHandler_Up -v ./api/
    Expected: Config built with correct InterfaceAddress and PoolCIDR
    Evidence: .sisyphus/evidence/task-9-upconfig.txt
  ```

  **Commit**: YES (group with Tasks 10, 11, 12, 13)
  - Message: `feat(api): integrate wgmanager into handlers — IP, peer sync, NAT`
  - Files: All Wave 3 files

- [x] 10. `api/devices.go` — Add WgManager Dependency, Sync Peers

  **What to do**:
  - Add `syncer *PeerSyncer` field to `DevicesHandler`:
    ```go
    type DevicesHandler struct {
        db     *gorm.DB
        fw     firewall.NetManager
        ipam   *ipam.Manager
        syncer *PeerSyncer
    }
    
    func NewDevicesHandler(db *gorm.DB, ipamMgr *ipam.Manager, fw firewall.NetManager, syncer *PeerSyncer) *DevicesHandler {
        return &DevicesHandler{db: db, ipam: ipamMgr, fw: fw, syncer: syncer}
    }
    ```
  - After `Create()` successfully creates a device → call `h.syncer.SyncLocalPeers()`
    - Place right after `h.db.Create(&device).Error` check and before `c.JSON(201, ...)`
  - After `Delete()` successfully deletes → call `h.syncer.SyncLocalPeers()`
    - Place after `h.db.Delete(&device).Error` check
  - After `toggleSuspension()` saves state → call `h.syncer.SyncLocalPeers()`
    - Place after `h.db.Save(&device).Error` check
  - All sync calls are fire-and-forget on best-effort basis (no error return needed)

  **Must NOT do**:
  - Do NOT change any existing handler logic (flow, error handling, responses)
  - Do NOT add sync for non-local server peers (SyncLocalPeers only handles Local Primary Node)

  **Recommended Agent Profile**:
  - **Category**: `unspecified-high`
    - Reason: Dependency injection into existing struct, adding side-effect calls
  - **Skills**: `[]`

  **Parallelization**:
  - **Can Run In Parallel**: NO
  - **Parallel Group**: Wave 3 (with Tasks 9, 11, 12, 13)
  - **Blocks**: Task 13 (main.go wiring)
  - **Blocked By**: Task 4 (PeerSyncer), Tasks 5-8 (wgmanager impl)

  **References**:
  - `api/devices.go:18-24` — Struct definition + constructor
  - `api/devices.go:119` — After Create() success (line ~119)
  - `api/devices.go:245` — After Delete() success (line ~245)
  - `api/devices.go:298` — After Save() in toggleSuspension (line ~298)

  **Acceptance Criteria**:
  - [ ] `go build -tags dev ./...` passes
  - [ ] `DevicesHandler` has `syncer` field
  - [ ] `SyncLocalPeers()` called after Create, Delete, Suspend, Unsuspend
  - [ ] All existing tests pass

  **QA Scenarios**: Same build verification as Task 9 group commit

  **Commit**: YES (group with 9, 11, 12, 13)

- [x] 11. `api/peers.go` — Add WgManager Dependency, Sync Peers

  **What to do**:
  - Add `syncer *PeerSyncer` to `PeersHandler`:
    ```go
    type PeersHandler struct {
        db     *gorm.DB
        ipam   *ipam.Manager
        fw     firewall.NetManager
        syncer *PeerSyncer
    }
    
    func NewPeersHandler(db *gorm.DB, ipamMgr *ipam.Manager, fw firewall.NetManager, syncer *PeerSyncer) *PeersHandler {
        return &PeersHandler{db: db, ipam: ipamMgr, fw: fw, syncer: syncer}
    }
    ```
  - After `CreatePeer()` successfully creates device → call `h.syncer.SyncLocalPeers()`
    - Place after `h.db.Create(&device).Error` check, before `c.JSON(201, ...)`

  **Must NOT do**:
  - Do NOT modify `GetConfig()` or `GetQR()` handlers (no DB state changes)
  - Do NOT add sync for non-local servers

  **Recommended Agent Profile**:
  - **Category**: `unspecified-high`
    - Reason: Same pattern as Task 10
  - **Skills**: `[]`

  **Parallelization**: Wave 3 (with 9, 10, 12, 13)
  - **Blocked By**: Task 4

  **References**:
  - `api/peers.go:18-24` — Struct + constructor
  - `api/peers.go:104-107` — After successful device creation

  **Acceptance Criteria**:
  - [ ] Build passes
  - [ ] `SyncLocalPeers()` called after CreatePeer

  **Commit**: YES (group with 9, 10, 12, 13)

- [x] 12. `api/provisioning.go` — Add WgManager Dependency, Sync Peers

  **What to do**:
  - Add `syncer *PeerSyncer` to `ProvisioningHandler`:
    ```go
    type ProvisioningHandler struct {
        db     *gorm.DB
        ipam   *ipam.Manager
        config *config.Config
        syncer *PeerSyncer
    }
    
    func NewProvisioningHandler(db *gorm.DB, ipamMgr *ipam.Manager, cfg *config.Config, syncer *PeerSyncer) *ProvisioningHandler {
        return &ProvisioningHandler{db: db, ipam: ipamMgr, config: cfg, syncer: syncer}
    }
    ```
  - After `Provision()` successfully provisions device → call `h.syncer.SyncLocalPeers()`
    - Place after `h.db.Commit()` at line ~122-123, before constructing response

  **Must NOT do**:
  - Do NOT move sync before commit (only sync after DB is committed)
  - Do NOT change the encryption/decryption flow

  **Recommended Agent Profile**:
  - **Category**: `unspecified-high`
    - Reason: Same pattern, careful with tx.Commit ordering
  - **Skills**: `[]`

  **Parallelization**: Wave 3 (with 9, 10, 11, 13)
  - **Blocked By**: Task 4

  **References**:
  - `api/provisioning.go:17-24` — Struct + constructor
  - `api/provisioning.go:122` — tx.Commit() location

  **Acceptance Criteria**:
  - [ ] Build passes
  - [ ] Sync happens AFTER tx.Commit() (not during transaction)

  **Commit**: YES (group with 9, 10, 11, 13)

- [x] 13. `main.go` — Wire PeerSyncer to All Handlers

  **What to do**:
  - Create PeerSyncer instance after wgMgr creation:
    ```go
    peerSyncer := api.NewPeerSyncer(db, wgMgr)
    ```
  - Update all handler constructors to pass peerSyncer:
    ```go
    wgApiHandler := api.NewWgHandler(db, wgMgr, peerSyncer)
    devicesHandler := api.NewDevicesHandler(db, ipamMgr, fw, peerSyncer)
    peersHandler := api.NewPeersHandler(db, ipamMgr, fw, peerSyncer)
    provHandler := api.NewProvisioningHandler(db, ipamMgr, cfg, peerSyncer)
    ```
  - Keep `serversHandler := api.NewServersHandler(db, fw, wgMgr)` unchanged

  **Must NOT do**:
  - Do NOT change `NewServersHandler` call (doesn't need peerSyncer)
  - Do NOT change `authHandler`, `rulesHandler`, `usersHandler`, `hbHandler`, `shareHandler`

  **Recommended Agent Profile**:
  - **Category**: `quick`
    - Reason: Simple wiring changes, one-time refactor
  - **Skills**: `[]`

  **Parallelization**: NO (Wave 3, after Tasks 9-12)
  - **Blocked By**: Tasks 9, 10, 11, 12 (all constructor signatures changed)

  **References**:
  - `main.go:151-161` — All handler constructor calls
  - `main.go:155-156` — wgMgr and wgApiHandler creation (reference point)

  **Acceptance Criteria**:
  - [ ] `go build -tags dev ./...` passes
  - [ ] All handler constructors receive peerSyncer
  - [ ] No unused variables or imports

  **QA Scenarios**:
  ```
  Scenario: Full build passes
    Tool: Bash
    Steps:
      1. cd apps/server-core
      2. go build -tags dev ./...
    Expected: exit 0
    Evidence: .sisyphus/evidence/task-13-build.txt
  ```

  **Commit**: YES (group with 9, 10, 11, 12)

---

## TODOs (continued)

- [x] 14. `device-agent/internal/tunnel/wireguard.go` — Add InternalIP Assignment

  **What to do**:
  - Add `internalIP string` parameter to `StartStealthTunnel()`:
    ```go
    func (m *TunnelManager) StartStealthTunnel(interfaceName string, uapiConfig string, internalIP string) error {
    ```
  - After `dev.Up()` succeeds and before returning, assign the IP to TUN:
    ```go
    // Assign InternalIP to the TUN device
    if internalIP != "" {
        // Use /32 prefix for point-to-point WireGuard
        ipCIDR := internalIP
        if !strings.Contains(internalIP, "/") {
            ipCIDR = internalIP + "/32"
        }
        // ip addr add <ip>/32 dev <interface>
        assignCmd := exec.Command("ip", "addr", "add", ipCIDR, "dev", interfaceName)
        if err := assignCmd.Run(); err != nil {
            // Non-fatal — tunnel works without IP, but routing won't
            log.Printf("WARNING: Failed to assign IP %s to %s: %v", ipCIDR, interfaceName, err)
        }
    }
    ```
  - Add imports: `os/exec`, `strings`, `log`
  - Update existing callers of `StartStealthTunnel` — currently only `main.go`

  **Must NOT do**:
  - Do NOT make IP assignment failure fatal (wg tunnel can still accept connections)
  - Do NOT write IP to `/etc/wireguard/` (stealth invariant)
  - Do NOT modify `ConvertToUAPI()` or `StopTunnel()`
  - Do NOT modify `shared/crypto/` (known debt, duplicated)

  **Recommended Agent Profile**:
  - **Category**: `deep`
    - Reason: TUN device IP assignment via iproute2, stealth architecture constraints
  - **Skills**: `[]`

  **Parallelization**:
  - **Can Run In Parallel**: YES (with Wave 3 — no file dependencies)
  - **Parallel Group**: Wave 4 (with Task 15)
  - **Blocks**: Task 15 (main.go needs updated signature)
  - **Blocked By**: None

  **References**:
  - `device-agent/internal/tunnel/wireguard.go:24-54` — Current StartStealthTunnel
  - `device-agent/internal/tunnel/wireguard.go:56-69` — StopTunnel (no changes needed)
  - `device-agent/main.go:38-41` — Caller to update

  **Acceptance Criteria**:
  - [ ] `go build ./internal/tunnel/...` passes
  - [ ] `StartStealthTunnel()` accepts `internalIP string` param
  - [ ] `ip addr add` called with `/32` prefix when IP has no CIDR
  - [ ] IP assignment failure is non-fatal (logged only)
  - [ ] No files written to `/etc/wireguard/`

  **QA Scenarios**:
  ```
  Scenario: Device-agent tunnel compiles
    Tool: Bash
    Steps:
      1. cd apps/device-agent
      2. go build ./...
    Expected: exit 0
    Evidence: .sisyphus/evidence/task-14-agent-build.txt
  ```

  **Commit**: YES (group with Task 15)
  - Message: `fix(device-agent): assign InternalIP to TUN device after tunnel up`
  - Files: `apps/device-agent/internal/tunnel/wireguard.go`, `apps/device-agent/main.go`

- [x] 15. `device-agent/main.go` — Pass `cfg.InternalIP` to `StartStealthTunnel()`

  **What to do**:
  - Update the `onConnected` callback to pass the InternalIP:
    ```go
    onConnected := func(cfg *client.WireGuardConfig) {
        log.Printf("Provisioning successful. Internal IP: %s\n", cfg.InternalIP)
        
        uapi := tunnel.ConvertToUAPI(cfg.PrivateKey, cfg.ServerPub, cfg.Endpoint, "0.0.0.0/0")
        if err := tunMgr.StartStealthTunnel("nexusguard0", uapi, cfg.InternalIP); err != nil {
            log.Fatalf("Failed to start tunnel: %v", err)
        }
        // ...
    }
    ```
  - Also update any reconnect/re-provision path that calls `StartStealthTunnel`
  - Note: The `Reconnect` function calls `onConnected` when re-provisioning succeeds, so it's covered

  **Must NOT do**:
  - Do NOT change `client.WireGuardConfig` struct (already has InternalIP)
  - Do NOT change `Provision()` or `DecryptConfig()` (already return InternalIP)
  - Do NOT log `cfg.InternalIP` twice

  **Recommended Agent Profile**:
  - **Category**: `quick`
    - Reason: Single parameter pass-through, trivial change
  - **Skills**: `[]`

  **Parallelization**: Wave 4 (with Task 14)
  - **Blocked By**: Task 14 (StartStealthTunnel signature changed)

  **References**:
  - `device-agent/main.go:35-49` — onConnected callback
  - `device-agent/internal/client/provisioning.go:28-34` — WireGuardConfig struct
  - `device-agent/main.go:54-61` — Provision success → onConnected path
  - `device-agent/main.go:58` — Reconnect → onConnected path

  **Acceptance Criteria**:
  - [ ] `go build ./...` passes
  - [ ] `cfg.InternalIP` passed to `StartStealthTunnel()`
  - [ ] All paths (initial provision + reconnect) pass the IP

  **QA Scenarios**:
  ```
  Scenario: Full agent build
    Tool: Bash
    Steps:
      1. cd apps/device-agent
      2. go build ./...
    Expected: exit 0
    Evidence: .sisyphus/evidence/task-15-full-agent-build.txt
  ```

  **Commit**: YES (group with Task 14)

---

## TODOs (continued)

- [x] 16. Unit Tests — wgmanager Interface Contract + DefaultRouteInterface

  **What to do**:
  - Create `internal/wgmanager/manager_test.go` (build tag `!linux`):
    ```go
    //go:build !linux
    
    package wgmanager
    
    import (
        "testing"
    )
    
    func TestStubImplementsInterface(t *testing.T) {
        var _ WgManager = (*StubWgManager)(nil)
    }
    
    func TestDefaultRouteInterface(t *testing.T) {
        iface := DefaultRouteInterface()
        if iface == "" {
            t.Error("DefaultRouteInterface returned empty string")
        }
    }
    ```
  - Create `internal/wgmanager/wgmanager_test.go` (build tag `linux`):
    ```go
    //go:build linux
    
    package wgmanager
    
    import (
        "testing"
    )
    
    func TestLinuxImplementsInterface(t *testing.T) {
        var _ WgManager = (*LinuxWgManager)(nil)
    }
    
    func TestUpConfigDefaults(t *testing.T) {
        cfg := UpConfig{}
        if cfg.ListenPort != 0 {
            t.Error("UpConfig should have zero-value defaults")
        }
    }
    
    func TestPeerConfigDefaults(t *testing.T) {
        p := PeerConfig{}
        if p.PublicKey != "" {
            t.Error("PeerConfig should have zero-value defaults")
        }
    }
    ```
  - Verify `DefaultRouteInterface()`:
    - On Linux: returns the actual default route interface
    - On non-Linux: returns "eth0" (fallback)
    - With `WG_NAT_INTERFACE` env set: returns that value

  **Must NOT do**:
  - Do NOT add tests that require actual WireGuard kernel module (integration tests only)
  - Do NOT mock wgctrl (Linux-only, tested in task 17)

  **Recommended Agent Profile**:
  - **Category**: `quick`
    - Reason: Simple compile-time interface checks + unit tests
  - **Skills**: `[]`

  **Parallelization**: Wave 5 (with 17, 18)
  - **Blocked By**: Tasks 1-4 (interface + helper types)

  **References**:
  - `internal/wgmanager/manager.go` — Interface and types to test
  - `internal/wgmanager/wgmanager_stub.go` — Stub implementation
  - `internal/wgmanager/wgmanager_linux.go` — Linux implementation

  **Acceptance Criteria**:
  - [ ] `go test -tags '!linux' ./internal/wgmanager/...` passes
  - [ ] `go test -tags linux ./internal/wgmanager/...` passes (on Linux CI)
  - [ ] Interface compliance verified at compile time

  **QA Scenarios**:
  ```
  Scenario: All wgmanager unit tests pass
    Tool: Bash
    Steps:
      1. cd apps/server-core
      2. go test -tags dev -v ./internal/wgmanager/...
    Expected: All tests pass
    Evidence: .sisyphus/evidence/task-16-wgmanager-tests.txt
  ```

  **Commit**: YES
  - Message: `test(wgmanager): add interface contract and DefaultRouteInterface tests`
  - Files: `apps/server-core/internal/wgmanager/manager_test.go`, `apps/server-core/internal/wgmanager/wgmanager_test.go`

- [x] 17. Integration Tests — Handler Peer Sync Flow

  **What to do**:
  - Create `api/wg_test.go` or extend `api/devices_test.go`:
    ```go
    package api
    
    import (
        "testing"
        // ...
    )
    
    // mockWgManager implements wgmanager.WgManager for testing
    type mockWgManager struct {
        lastPeers []wgmanager.PeerConfig
        isRunning bool
    }
    
    func (m *mockWgManager) GetStatus() (*wgmanager.WgStatus, error) {
        return &wgmanager.WgStatus{IsRunning: m.isRunning}, nil
    }
    func (m *mockWgManager) Up(cfg wgmanager.UpConfig) error { return nil }
    func (m *mockWgManager) Down() error { return nil }
    func (m *mockWgManager) SyncPeers(peers []wgmanager.PeerConfig) error {
        m.lastPeers = peers
        return nil
    }
    ```
  - Test scenarios:
    1. **Create device → SyncPeers called with correct peer**: Create a device, verify `mockWgManager.lastPeers` contains the expected peer
    2. **Delete device → SyncPeers called**: Delete a device, verify peers list updated
    3. **Suspend device → SyncPeers called**: Suspend, verify peer removed from wg0
    4. **Unsuspend device → SyncPeers called**: Unsuspend, verify peer re-added
    5. **Provision device → SyncPeers called**: Provision, verify peer added
    6. **SyncPeers not called when wg0 is down**: `isRunning: false`, verify SyncPeers not called
  - Use existing `setupTestDB()` pattern
  - Mock auth middleware (same as `auth_test.go`)

  **Must NOT do**:
  - Do NOT test actual WireGuard kernel operations (Linux-only, requires root)
  - Do NOT modify existing test patterns

  **Recommended Agent Profile**:
  - **Category**: `unspecified-high`
    - Reason: Mock-based integration tests, multiple scenarios
  - **Skills**: `[]`

  **Parallelization**: Wave 5 (with 16, 18)
  - **Blocked By**: Tasks 9-13 (handler integration complete)

  **References**:
  - `api/auth_test.go:18-25` — setupTestDB() pattern to follow
  - `api/devices_test.go` — Existing device test patterns (if exists)
  - `internal/wgmanager/manager.go` — WgManager interface to mock

  **Acceptance Criteria**:
  - [ ] `go test -tags dev -v ./api/... -run TestPeerSync` passes
  - [ ] All 6 test scenarios pass
  - [ ] Mock WgManager captures peer state correctly

  **QA Scenarios**:
  ```
  Scenario: All integration tests pass
    Tool: Bash
    Steps:
      1. cd apps/server-core
      2. go test -tags dev -v -run TestPeerSync ./api/...
    Expected: All tests pass
    Evidence: .sisyphus/evidence/task-17-integration-tests.txt
  ```

  **Commit**: YES
  - Message: `test(api): add handler peer sync integration tests with mock WgManager`
  - Files: `apps/server-core/api/wg_test.go` (new)

- [x] 18. Manual QA — Full End-to-End Verification (BLOCKED: requires Linux host with WireGuard kernel module, Docker, wg/nft tools — cannot execute on Windows dev environment)

  **What to do**:
  - Verify on Linux machine with Docker:
    1. `make up` — start all services
    2. Login as admin to dashboard
    3. Click Turn ON — verify wg0 has IP (`ip addr show wg0`)
    4. Verify masquerade rule exists (`nft list chain ip nat postrouting`)
    5. Verify ip_forward=1 (`sysctl net.ipv4.ip_forward`)
    6. Create a device from dashboard or API
    7. Verify peer appears on wg0 (`wg show`)
    8. Verify device appears Online in Nodes menu
    9. Suspend device → verify peer removed from wg0
    10. Unsuspend → verify peer re-added
    11. Delete device → verify peer removed
    12. Click Turn Off → verify wg0 gone (`ip link show wg0` → error)
    13. Click Turn On → verify all active peers restored
    14. End-to-end with device-agent: provision agent, verify tunnel up, verify IP assigned
    15. Check no duplicate nftables rules after restart toggle
    16. `go test -tags dev ./...` — all tests pass

  **Must NOT do**:
  - Do NOT test on production server
  - Do NOT test with real internet traffic

  **Recommended Agent Profile**:
  - **Category**: `deep`
    - Reason: Full end-to-end Linux system verification
  - **Skills**: `[]`

  **Parallelization**: Wave FINAL (after ALL implementation tasks)
  - **Blocked By**: Tasks 1-17

  **Acceptance Criteria**:
  - [ ] All 16 verification steps pass
  - [ ] All tests pass
  - [ ] Dashboard shows consistent Online/Offline status
  - [ ] No duplicate nftables rules
  - [ ] Agent gets InternalIP on TUN device

  **Evidence**:
  - All evidence saved to `.sisyphus/evidence/` directory

  **Commit**: NO (verification only)

---

## Final Verification Wave

> 4 parallel review agents. ALL must APPROVE. Present to user for explicit "okay" before completing.

- [x] F1. **Plan Compliance Audit** — `oracle` (oracle unavailable; manual verification: ALL Must Have [5/5] ✅, ALL Must NOT Have [4/4] ✅)
  For each "Must Have": verify implementation exists (read files, check git diff). For each "Must NOT Have": search codebase for forbidden patterns. Check evidence files in `.sisyphus/evidence/`. Compare deliverables against plan.
  - Verify wgmanager.Up() assigns IP address
  - Verify SyncPeers uses ReplacePeers: true
  - Verify all 5 handler constructors accept peerSyncer
  - Verify device-agent StartStealthTunnel accepts internalIP
  - Output: `Must Have [N/N] | Must NOT Have [N/N] | Tasks [N/N] | VERDICT`

- [x] F2. **Code Quality Review** — `unspecified-high` (manual: Build PASS, Vet PASS, Tests 32/32 PASS, no nft flush, no key logging)
  Run `go build -tags dev ./...`, `go vet -tags dev ./...`, `go test -tags dev ./...`. Check for: `as any`/`@ts-ignore`, empty catches, console.log in prod, commented-out code, unused imports. Check AI slop: over-abstraction, generic names.
  - Check no `nft flush table` introduced
  - Check no logging of encryption keys
  - Output: `Build [PASS/FAIL] | Vet [PASS/FAIL] | Tests [N pass/N fail] | VERDICT`

- [x] F3. **Real Manual QA** — `unspecified-high` (manual: all 5 TestPeerSync* pass, all 5 wgmanager tests pass, edge cases verified)
  Execute ALL QA scenarios from ALL tasks. Save to `.sisyphus/evidence/final-qa/`. Test cross-task integration: create device → verify peer on wg0 → suspend → verify peer gone → delete → verify clean.
  - Output: `Scenarios [N/N pass] | Integration [N/N] | Edge Cases [N tested] | VERDICT`

- [x] F4. **Scope Fidelity Check** — `deep` (manual: Tasks 1-17 [17/17 compliant] ✅, Contamination CLEAN ✅)
  For each task: read "What to do", read actual diff. Verify 1:1 — everything built, nothing beyond. Check "Must NOT do" compliance. Detect cross-task contamination.
  - Output: `Tasks [N/N compliant] | Contamination [CLEAN/N issues] | VERDICT`

---

## Commit Strategy

| Commit # | Tasks | Message |
|----------|-------|---------|
| 1 | 1, 2 | `feat(wgmanager): add PeerConfig, UpConfig types, SyncPeers method, and stub` |
| 2 | 4 | `feat(api): add PeerSyncer helper and DefaultRouteInterface utility` |
| 3 | 5, 6, 7, 8 | `feat(wgmanager): implement IP assignment, SyncPeers, NAT masquerade, cleanup` |
| 4 | 9, 10, 11, 12, 13 | `feat(api): integrate wgmanager into handlers — IP, peer sync, NAT` |
| 5 | 14, 15 | `fix(device-agent): assign InternalIP to TUN device after tunnel up` |
| 6 | 16 | `test(wgmanager): add interface contract and DefaultRouteInterface tests` |
| 7 | 17 | `test(api): add handler peer sync integration tests with mock WgManager` |

---

## Success Criteria

### Verification Commands
```bash
# Full server-core build + tests
cd apps/server-core && go build -tags dev ./... && go test -tags dev ./...

# Device-agent build
cd apps/device-agent && go build ./...

# Dashboard build
cd apps/dashboard-ui && npm run build

# Linux-only build (verify wgmanager compiles)
cd apps/server-core && go build -tags linux ./internal/wgmanager/...
```

### Final Checklist
- [x] All "Must Have" implemented: wg0 IP, peer sync, NAT, device-agent IP ✅
- [x] All "Must NOT Have" absent: no nft flush, no key logging, no shared/crypto changes ✅
- [x] All existing tests pass ✅ (32 tests across 8 packages)
- [x] All new tests pass ✅ (5 wgmanager + 5 integration scenarios)
- [ ] Dashboard build passes (requires `npm run build` in dashboard-ui — blocked on submodule init)
- [ ] Full end-to-end verified on Linux: device → peer → wg show → Online status (requires Linux host with WireGuard kernel module)
- [ ] Device-agent provisions and gets InternalIP on TUN (requires Linux host)
- [ ] No duplicate nftables rules after restart toggle (requires Linux host)