@brunosps00/dev-workflow 1.1.2 → 1.1.3

package/README.md

@@ -26,7 +26,7 @@ npx @brunosps00/dev-workflow install-deps
 
 ## Commands
 
-dev-workflow v1.1.2 ships **31 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v1.1.3 ships **31 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (3)
 
@@ -310,7 +310,7 @@ npx @brunosps00/dev-workflow list-installed                # Show managed instal
 npx @brunosps00/dev-workflow doctor                        # Check wrappers, agents, skills, MCPs, gates
 npx @brunosps00/dev-workflow repair                        # Reconcile managed files from recorded install state
 npx @brunosps00/dev-workflow install-deps                  # Install Playwright, react-doctor; check security scanners + Docker
-npx @brunosps00/dev-workflow setup-wsl-browser             # WSL NAT: install prebuilt CDP relay + add Hyper-V firewall rule
+npx @brunosps00/dev-workflow setup-wsl-browser             # WSL NAT: install user-level prebuilt CDP relay (no admin)
 npx @brunosps00/dev-workflow install-azure-skills          # Opt-in: Azure skills + Microsoft Learn MCP
 npx @brunosps00/dev-workflow install-azure-skills --products=azure-aks,azure-openai  # Subset override
 npx @brunosps00/dev-workflow install-aws-skills            # Opt-in: AWS skills + AWS MCP Server (needs uv + aws cli + creds)

package/bin/dev-workflow.js

@@ -47,7 +47,7 @@ const HELP_TEXT = `
     repair                 Reconcile managed files using the recorded install state
     subtask                Create, complete, consume, and list local subagent handoffs
     install-deps           Install system dependencies (Playwright browsers, MCP servers)
-    setup-wsl-browser      (WSL) Install the prebuilt CDP relay + add the Hyper-V firewall rule so flows can drive the real Windows browser
+    setup-wsl-browser      (WSL) Install the user-level prebuilt CDP relay so flows can drive the real Windows browser without admin
     install-azure-skills   Opt-in: clone curated Azure skills from MicrosoftDocs/Agent-Skills
                            into .agents/skills/azure/ and register the Microsoft Learn MCP
                            server (HTTP, no-auth). Interactive category selection.

package/lib/install-deps.js

@@ -173,7 +173,7 @@ function printBrowserGuidance() {
     console.log('    Mirrored networking detected — connects to the Windows browser on 127.0.0.1 directly.');
   } else {
     console.log('    NAT networking — run `npx @brunosps00/dev-workflow setup-wsl-browser` once to install the');
-    console.log('    bundled cdp-relay.exe and add the Hyper-V firewall rule. Otherwise flows');
+    console.log('    bundled user-level cdp-relay.exe. No admin prompt or firewall rule is required. Otherwise flows');
     console.log('    fall back to the local headless Chromium (faithful video, no Windows browser).');
   }
   console.log('    Details: .dw/skills/dw-testing-discipline/references/playwright-recipes.md ("Browser on WSL").');

package/lib/setup-wsl-browser.js

@@ -2,17 +2,13 @@ const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 
-// Installs the prebuilt CDP relay (cdp-relay.exe) on Windows and adds the one-time
-// Hyper-V firewall rule so WSL (NAT networking) can drive the real Windows browser over CDP.
-// Idempotent.
+// Installs the prebuilt CDP relay (cdp-relay.exe) in the Windows user profile. Idempotent.
 //
-// Why: Chromium binds its debug port to Windows loopback only, and the WSL Hyper-V firewall
-// defaults inbound to Block. A fixed-port relay + one Hyper-V allow rule bridges WSL -> browser.
+// Why: Chromium binds its debug port to Windows loopback only. On WSL NAT, dev-workflow uses
+// a reverse relay where the Windows-side .exe connects outbound to a WSL broker, so no admin
+// prompt, firewall rule, Rust, Node, or Python runtime is required on the Windows target.
 // The relay is a tiny prebuilt .exe — no Rust/Node/Python runtime dependency on the Windows target.
 
-const RELAY_PORT = 39222;
-const WSL_VM_CREATOR_ID = '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}'; // standard WSL VM creator id
-const RULE_NAME = 'dw-cdp-relay';
 const RELAY_EXE_SRC = path.join(__dirname, '..', 'scaffold', 'scripts', 'cdp-relay', 'bin', 'cdp-relay.exe');
 
 function isWsl() {
@@ -50,7 +46,7 @@ function run() {
   const destWin = `${localAppData}\\dev-workflow`;
   const destWsl = execSync(`wslpath -u "${destWin}"`, { stdio: 'pipe' }).toString().trim();
 
-  // 1) Install the prebuilt Windows relay bundled in the npm package.
+  // Install the prebuilt Windows relay bundled in the npm package.
   if (!fs.existsSync(RELAY_EXE_SRC)) {
     console.log(`  \x1b[31m✗\x1b[0m Prebuilt relay not found at ${RELAY_EXE_SRC}`);
     console.log('    The dev-workflow package is incomplete. Reinstall or update @brunosps00/dev-workflow.');
@@ -69,48 +65,12 @@ function run() {
     return;
   }
 
-  // 2) Add the Hyper-V firewall inbound rule (one-time, elevated -> UAC prompt).
-  console.log(`\n  Adding Hyper-V firewall rule for TCP ${RELAY_PORT} (a UAC prompt will appear — accept it)...`);
-  const inner = [
-    `Remove-NetFirewallHyperVRule -Name '${RULE_NAME}' -ErrorAction SilentlyContinue;`,
-    `New-NetFirewallHyperVRule -Name '${RULE_NAME}' -DisplayName 'dev-workflow cdp-relay'`,
-    `-Direction Inbound -Action Allow -VMCreatorId '${WSL_VM_CREATOR_ID}' -Protocol TCP -LocalPorts ${RELAY_PORT}`,
-  ].join(' ');
-  try {
-    execSync(
-      `powershell.exe -NoProfile -Command "Start-Process powershell -Verb RunAs -WindowStyle Hidden -ArgumentList '-NoProfile','-Command',\\"${inner}\\""`,
-      { stdio: 'pipe', timeout: 60000 },
-    );
-  } catch {
-    // Start-Process returns before the elevated process finishes; verify below regardless.
-  }
-
-  // 3) Verify.
-  let ok = false;
-  for (let i = 0; i < 10 && !ok; i += 1) {
-    try {
-      const out = execSync(
-        `powershell.exe -NoProfile -c "Get-NetFirewallHyperVRule -Name '${RULE_NAME}' -ErrorAction SilentlyContinue | Select-Object -Expand Action"`,
-        { stdio: 'pipe', timeout: 15000 },
-      ).toString();
-      ok = /Allow/i.test(out);
-    } catch {
-      ok = false;
-    }
-    if (!ok) execSync('sleep 1');
-  }
-
   console.log(`  ${'='.repeat(40)}`);
-  if (ok) {
-    console.log('  \x1b[32m✓ Done.\x1b[0m The Windows browser is reachable from WSL over CDP.');
-    console.log(`    Set BROWSER_TEST to a Windows browser exe to use it, e.g.`);
-    console.log('    BROWSER_TEST="/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"');
-  } else {
-    console.log('  \x1b[33m⚠ Hyper-V firewall rule not confirmed.\x1b[0m UAC may have been declined, or this Windows lacks');
-    console.log('    Hyper-V firewall cmdlets. Flows will fall back to the local headless Chromium (faithful video, no');
-    console.log('    Windows browser). You can also enable mirrored networking instead. Re-run to retry.');
-  }
+  console.log('  \x1b[32m✓ Done.\x1b[0m The CDP relay is installed in the Windows user profile.');
+  console.log('    No admin prompt, firewall rule, or Windows Rust toolchain is required.');
+  console.log(`    Set BROWSER_TEST to a Windows browser exe to use it, e.g.`);
+  console.log('    BROWSER_TEST="/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"');
   console.log();
 }
 
-module.exports = { run, RELAY_PORT };
+module.exports = { run };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

package/scaffold/en/commands/dw-functional-doc.md

@@ -298,7 +298,7 @@ The runner drives Playwright via the Node API and records video with `page.scree
 mechanism that works over CDP). It generates `scripts/<slug>.flow.mjs` — a plain ESM module exporting
 `async function flow({ page, context, expect, baseURL, step, shot })` — not a `@playwright/test` spec,
 so it needs no project `playwright.config.*`. The browser is chosen by `.dw/scripts/lib/resolve-browser.mjs`
-(WSL-resilient: full headless Chromium by default; set `BROWSER_TEST` to a Windows browser exe to drive it over CDP — in NAT run `npx @brunosps00/dev-workflow setup-wsl-browser` once to install the prebuilt cdp-relay.exe + Hyper-V rule, mirrored networking works directly);
+(WSL-resilient: full headless Chromium by default; set `BROWSER_TEST` to a Windows browser exe to drive it over CDP — in NAT run `npx @brunosps00/dev-workflow setup-wsl-browser` once to install the user-level reverse cdp-relay.exe, mirrored networking works directly);
 see the "Browser on WSL" section of `dw-testing-discipline/references/playwright-recipes.md`. Chromium
 only — `screencast`/CDP do not support Firefox/WebKit.
 

package/scaffold/en/commands/dw-help.md

@@ -124,7 +124,7 @@ Match the keyword and suggest:
 | `docker`, `compose`, `container` | `/dw-dockerize` |
 | `new project`, `bootstrap`, `scaffold` | `/dw-new-project` |
 | `functional doc`, `screen map`, `e2e doc` | `/dw-functional-doc` |
-| `wsl`, `browser`, `playwright browser`, `cdp` | `npx @brunosps00/dev-workflow setup-wsl-browser` installs the prebuilt relay when WSL NAT must drive the real Windows browser |
+| `wsl`, `browser`, `playwright browser`, `cdp` | `npx @brunosps00/dev-workflow setup-wsl-browser` installs the user-level reverse relay when WSL NAT must drive the real Windows browser |
 | `azure`, `microsoft learn`, `azure skills` | `/dw-install-azure-skills` |
 | `aws`, `aws mcp`, `aws skills` | `/dw-install-aws-skills` |
 | `incident`, `outage`, `postmortem`, `sev-1`, `sev-2` | (Skill `dw-incident-response` auto-invoked from `/dw-bugfix` for prod-critical) |

package/scaffold/pt-br/commands/dw-functional-doc.md

@@ -298,7 +298,7 @@ O runner dirige o Playwright pela API Node e grava vídeo com `page.screencast`
 funciona via CDP). Ele gera `scripts/<slug>.flow.mjs` — um módulo ESM simples que exporta
 `async function flow({ page, context, expect, baseURL, step, shot })`, não um spec `@playwright/test`,
 então dispensa o `playwright.config.*` do projeto. O browser é escolhido por `.dw/scripts/lib/resolve-browser.mjs`
-(resiliente no WSL: Chromium headless full por padrão; defina `BROWSER_TEST` com o caminho do exe do browser do Windows para dirigi-lo via CDP — em NAT rode `npx @brunosps00/dev-workflow setup-wsl-browser` uma vez para instalar o cdp-relay.exe precompilado + regra Hyper-V, em mirrored funciona direto);
+(resiliente no WSL: Chromium headless full por padrão; defina `BROWSER_TEST` com o caminho do exe do browser do Windows para dirigi-lo via CDP — em NAT rode `npx @brunosps00/dev-workflow setup-wsl-browser` uma vez para instalar o cdp-relay.exe reverso no contexto do usuário, em mirrored funciona direto);
 veja a seção "Browser on WSL" de `dw-testing-discipline/references/playwright-recipes.md`. Só Chromium —
 `screencast`/CDP não suportam Firefox/WebKit.
 

package/scaffold/pt-br/commands/dw-help.md

@@ -120,7 +120,7 @@ Auto-invocados por comandos primários mas disponíveis standalone.
 | `docker`, `compose`, `container` | `/dw-dockerize` |
 | `new project`, `bootstrap`, `scaffold` | `/dw-new-project` |
 | `functional doc`, `screen map` | `/dw-functional-doc` |
-| `wsl`, `browser`, `playwright browser`, `cdp` | `npx @brunosps00/dev-workflow setup-wsl-browser` instala o relay precompilado quando WSL NAT precisa dirigir o browser real do Windows |
+| `wsl`, `browser`, `playwright browser`, `cdp` | `npx @brunosps00/dev-workflow setup-wsl-browser` instala o relay reverso no contexto do usuário quando WSL NAT precisa dirigir o browser real do Windows |
 | `azure`, `microsoft learn`, `azure skills` | `/dw-install-azure-skills` |
 | `aws`, `aws mcp`, `aws skills` | `/dw-install-aws-skills` |
 | `incident`, `outage`, `postmortem`, `sev-1` | (Skill `dw-incident-response` auto-invocada de `/dw-bugfix`) |

package/scaffold/scripts/cdp-relay/Cargo.toml

@@ -2,7 +2,7 @@
 name = "cdp-relay"
 version = "0.1.0"
 edition = "2021"
-description = "Tiny TCP forwarder so WSL can reach a Windows browser's CDP debug port in NAT mode. Source for the prebuilt dev-workflow relay; no runtime dependency."
+description = "Tiny forward/reverse TCP relay so WSL can reach a Windows browser's CDP debug port in NAT mode without admin setup."
 
 [[bin]]
 name = "cdp-relay"

package/scaffold/scripts/cdp-relay/src/main.rs

@@ -1,15 +1,20 @@
 //! cdp-relay — a tiny TCP forwarder.
 //!
-//! Listens on 0.0.0.0:<listen> and forwards every connection to 127.0.0.1:<target>.
-//! dev-workflow runs this on the Windows side so WSL (NAT networking) can reach a Windows
-//! browser's CDP remote-debugging port, which Chromium binds to loopback only. std-only:
-//! no crates, no runtime. dev-workflow ships a prebuilt Windows x64 .exe; this source is
-//! kept for maintainers who need to rebuild it.
+//! Default mode listens on 0.0.0.0:<listen> and forwards every connection to
+//! 127.0.0.1:<target>. Reverse mode connects outbound to a WSL broker, then forwards
+//! each broker-approved session to 127.0.0.1:<target>. dev-workflow uses reverse mode
+//! on WSL NAT so no Windows admin/firewall rule is required. std-only: no crates, no
+//! runtime. dev-workflow ships a prebuilt Windows x64 .exe; this source is kept for
+//! maintainers who need to rebuild it.
 
 use std::env;
-use std::io;
+use std::io::{self, Read};
 use std::net::{Shutdown, TcpListener, TcpStream};
 use std::thread;
+use std::time::Duration;
+
+const DEFAULT_REVERSE_POOL: usize = 8;
+const RETRY_DELAY: Duration = Duration::from_millis(200);
 
 fn pump(mut from: TcpStream, mut to: TcpStream) {
     let _ = io::copy(&mut from, &mut to);
@@ -17,29 +22,36 @@ fn pump(mut from: TcpStream, mut to: TcpStream) {
     let _ = to.shutdown(Shutdown::Write);
 }
 
+fn bridge(left: TcpStream, right: TcpStream) -> io::Result<()> {
+    left.set_nodelay(true).ok();
+    right.set_nodelay(true).ok();
+
+    let left_rx = left.try_clone()?;
+    let right_rx = right.try_clone()?;
+    thread::spawn(move || pump(left, right_rx));
+    thread::spawn(move || pump(right, left_rx));
+    Ok(())
+}
+
 fn handle(client: TcpStream, target_port: u16) -> io::Result<()> {
-    client.set_nodelay(true).ok();
     let upstream = TcpStream::connect(("127.0.0.1", target_port))?;
-    upstream.set_nodelay(true).ok();
-
-    let client_rx = client.try_clone()?;
-    let upstream_rx = upstream.try_clone()?;
-    // client -> upstream
-    thread::spawn(move || pump(client, upstream));
-    // upstream -> client
-    thread::spawn(move || pump(upstream_rx, client_rx));
-    Ok(())
+    bridge(client, upstream)
 }
 
-fn main() {
-    let args: Vec<String> = env::args().collect();
-    if args.len() < 3 {
-        eprintln!("usage: cdp-relay <listen_port> <target_port>");
-        std::process::exit(2);
+fn wait_for_go(stream: &mut TcpStream) -> io::Result<()> {
+    let mut seen = Vec::with_capacity(3);
+    let mut byte = [0u8; 1];
+    while seen.len() < 3 {
+        stream.read_exact(&mut byte)?;
+        seen.push(byte[0]);
+        if seen == b"GO\n" {
+            return Ok(());
+        }
     }
-    let listen_port: u16 = args[1].parse().expect("invalid listen port");
-    let target_port: u16 = args[2].parse().expect("invalid target port");
+    Err(io::Error::new(io::ErrorKind::InvalidData, "expected GO"))
+}
 
+fn run_listen(listen_port: u16, target_port: u16) -> io::Result<()> {
     let listener = TcpListener::bind(("0.0.0.0", listen_port)).expect("bind failed");
     for stream in listener.incoming() {
         if let Ok(client) = stream {
@@ -47,4 +59,89 @@ fn main() {
             let _ = handle(client, target_port);
         }
     }
+    Ok(())
+}
+
+fn handle_reverse_session(mut broker: TcpStream, target_port: u16) -> io::Result<()> {
+    broker.set_nodelay(true).ok();
+    wait_for_go(&mut broker)?;
+    let upstream = TcpStream::connect(("127.0.0.1", target_port))?;
+    bridge(broker, upstream)
+}
+
+fn reverse_worker(broker_host: String, broker_port: u16, target_port: u16) {
+    loop {
+        match TcpStream::connect((broker_host.as_str(), broker_port)) {
+            Ok(broker) => {
+                if handle_reverse_session(broker, target_port).is_err() {
+                    thread::sleep(RETRY_DELAY);
+                }
+            }
+            Err(_) => thread::sleep(RETRY_DELAY),
+        }
+    }
+}
+
+fn run_reverse(broker_host: String, broker_port: u16, target_port: u16, pool_size: usize) {
+    let pool_size = pool_size.max(1);
+    for _ in 0..pool_size {
+        let host = broker_host.clone();
+        thread::spawn(move || reverse_worker(host, broker_port, target_port));
+    }
+    loop {
+        thread::sleep(Duration::from_secs(3600));
+    }
+}
+
+fn usage() -> ! {
+    eprintln!("usage:");
+    eprintln!("  cdp-relay <listen_port> <target_port>");
+    eprintln!("  cdp-relay --reverse <broker_host> <broker_port> <target_port> [pool_size]");
+    std::process::exit(2);
+}
+
+fn parse_port(value: &str, name: &str) -> u16 {
+    value.parse().unwrap_or_else(|_| {
+        eprintln!("invalid {name}");
+        std::process::exit(2);
+    })
+}
+
+fn parse_pool(value: Option<&String>) -> usize {
+    value
+        .map(|s| {
+            s.parse().unwrap_or_else(|_| {
+                eprintln!("invalid pool_size");
+                std::process::exit(2);
+            })
+        })
+        .unwrap_or(DEFAULT_REVERSE_POOL)
+}
+
+fn main() {
+    let args: Vec<String> = env::args().collect();
+    if args.get(1).map(String::as_str) == Some("--reverse") {
+        if args.len() < 5 {
+            usage();
+        }
+        let broker_host = args[2].clone();
+        let broker_port = parse_port(&args[3], "broker_port");
+        let target_port = parse_port(&args[4], "target_port");
+        run_reverse(
+            broker_host,
+            broker_port,
+            target_port,
+            parse_pool(args.get(5)),
+        );
+    }
+
+    if args.len() < 3 {
+        usage();
+    }
+    let listen_port = parse_port(&args[1], "listen_port");
+    let target_port = parse_port(&args[2], "target_port");
+    if let Err(err) = run_listen(listen_port, target_port) {
+        eprintln!("cdp-relay: {err}");
+        std::process::exit(1);
+    }
 }

package/scaffold/scripts/lib/resolve-browser.mjs

@@ -19,10 +19,9 @@
 //
 // NOTE on WSL networking: the Chromium debug port binds Windows loopback only. In mirrored
 // networking mode WSL shares that loopback, so 127.0.0.1 connects directly. In NAT mode the
-// helper starts the prebuilt cdp-relay.exe on Windows (0.0.0.0:<fixed port> -> 127.0.0.1:debug)
-// and connects via the Windows host gateway. That needs the one-time setup performed by
-// `npx @brunosps00/dev-workflow setup-wsl-browser` (installs the prebuilt relay + adds the Hyper-V firewall
-// rule). Without it, the helper falls back to the local headless Chromium.
+// helper starts the prebuilt cdp-relay.exe on Windows in reverse mode: the Windows process
+// connects outbound to a WSL broker, and Playwright connects to a local WSL proxy. The one-time
+// setup only installs the relay in the Windows user profile; no admin/firewall rule is needed.
 
 import fs from "node:fs";
 import net from "node:net";
@@ -35,6 +34,8 @@ const BUNDLED_LAUNCH = { channel: "chromium" };
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const dedupe = (items) => [...new Set(items.filter(Boolean))];
+const REVERSE_RELAY_POOL = 8;
+const CLIENT_WAIT_TIMEOUT_MS = 5000;
 
 export function detectWsl() {
   if (process.env.WSL_DISTRO_NAME) {
@@ -96,6 +97,42 @@ function getFreePort() {
   });
 }
 
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve(server.address().port);
+    };
+    server.once("error", onError);
+    server.listen(port, host, onListening);
+  });
+}
+
+function removeItem(items, item) {
+  const index = items.indexOf(item);
+  if (index >= 0) items.splice(index, 1);
+}
+
+function destroyQuietly(item) {
+  try {
+    item.destroy();
+  } catch {
+    // ignore
+  }
+}
+
+function closeServerQuietly(server) {
+  try {
+    server.close();
+  } catch {
+    // ignore
+  }
+}
+
 function windowsHostIp() {
   // In WSL2 NAT mode the Windows host is the default-route gateway (the vEthernet
   // adapter), NOT the /etc/resolv.conf nameserver (which can be a DNS-tunneling proxy
@@ -120,6 +157,27 @@ function windowsHostIp() {
   return null;
 }
 
+function wslBrokerHosts() {
+  const hosts = ["127.0.0.1"];
+  try {
+    const out = spawnSync("ip", ["-4", "-o", "addr", "show", "dev", "eth0", "scope", "global"], { encoding: "utf8" }).stdout ?? "";
+    const match = out.match(/\binet\s+([0-9.]+)\//);
+    if (match) hosts.push(match[1]);
+  } catch {
+    // ignore
+  }
+  if (hosts.length === 1) {
+    try {
+      const out = spawnSync("hostname", ["-I"], { encoding: "utf8" }).stdout ?? "";
+      const fallback = out.split(/\s+/).find((ip) => /^[0-9.]+$/.test(ip) && !ip.startsWith("127."));
+      if (fallback) hosts.push(fallback);
+    } catch {
+      // ignore
+    }
+  }
+  return dedupe(hosts);
+}
+
 function httpGetJson(url, timeoutMs = 1000) {
   return new Promise((resolve) => {
     const request = http.get(url, { timeout: timeoutMs }, (response) => {
@@ -190,21 +248,19 @@ function windowsTempDir() {
   return wslPath ? { winPath, wslPath } : null;
 }
 
-// Fixed port the Windows-side relay listens on, so a single Hyper-V firewall rule covers it.
-const DEFAULT_RELAY_PORT = 39222;
-
 function relayPort(projectRoot) {
   const fromEnv = Number(process.env.DW_RELAY_PORT);
-  if (fromEnv) return fromEnv;
+  if (Number.isInteger(fromEnv) && fromEnv > 0 && fromEnv < 65536) return fromEnv;
   if (projectRoot) {
     try {
       const cfg = JSON.parse(fs.readFileSync(path.join(projectRoot, ".dw", "config.json"), "utf8"));
-      if (Number(cfg?.relayPort)) return Number(cfg.relayPort);
+      const fromConfig = Number(cfg?.relayPort);
+      if (Number.isInteger(fromConfig) && fromConfig > 0 && fromConfig < 65536) return fromConfig;
     } catch {
       // ignore
     }
   }
-  return DEFAULT_RELAY_PORT;
+  return 0;
 }
 
 // The prebuilt Windows relay (cdp-relay.exe), installed by `setup-wsl-browser`. Order:
@@ -237,13 +293,183 @@ function findRelayExe(projectRoot) {
   return null;
 }
 
+async function startReverseRelayBroker({ relay, debugPort, projectRoot }) {
+  const idleRelays = [];
+  const pendingClients = [];
+  const relaySockets = [];
+  const localSockets = [];
+  const relayChildren = [];
+  const relayWaiters = [];
+  let closed = false;
+
+  const notifyRelayReady = () => {
+    while (idleRelays.length > 0 && relayWaiters.length > 0) {
+      const waiter = relayWaiters.shift();
+      clearTimeout(waiter.timer);
+      waiter.resolve(true);
+    }
+  };
+
+  const waitForRelayReady = (timeoutMs) => {
+    if (idleRelays.length > 0) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const waiter = { resolve, timer: null };
+      waiter.timer = setTimeout(() => {
+        removeItem(relayWaiters, waiter);
+        resolve(false);
+      }, timeoutMs);
+      relayWaiters.push(waiter);
+    });
+  };
+
+  const removePendingClient = (pending) => {
+    clearTimeout(pending.timer);
+    removeItem(pendingClients, pending);
+  };
+
+  const pairSockets = (client, relaySocket) => {
+    const closePair = () => {
+      destroyQuietly(client);
+      destroyQuietly(relaySocket);
+    };
+    client.on("error", closePair);
+    relaySocket.on("error", closePair);
+    client.on("close", () => destroyQuietly(relaySocket));
+    relaySocket.on("close", () => destroyQuietly(client));
+    relaySocket.write("GO\n", (error) => {
+      if (error) closePair();
+    });
+    client.pipe(relaySocket);
+    relaySocket.pipe(client);
+  };
+
+  const drainPending = () => {
+    while (pendingClients.length > 0 && idleRelays.length > 0) {
+      const pending = pendingClients.shift();
+      clearTimeout(pending.timer);
+      const relaySocket = idleRelays.shift();
+      if (pending.client.destroyed || relaySocket.destroyed) {
+        destroyQuietly(pending.client);
+        destroyQuietly(relaySocket);
+        continue;
+      }
+      pairSockets(pending.client, relaySocket);
+    }
+  };
+
+  const brokerServer = net.createServer((socket) => {
+    if (closed) {
+      socket.destroy();
+      return;
+    }
+    socket.setNoDelay(true);
+    relaySockets.push(socket);
+    idleRelays.push(socket);
+    socket.on("error", () => destroyQuietly(socket));
+    socket.on("close", () => {
+      removeItem(relaySockets, socket);
+      removeItem(idleRelays, socket);
+    });
+    notifyRelayReady();
+    drainPending();
+  });
+
+  const localServer = net.createServer((client) => {
+    if (closed) {
+      client.destroy();
+      return;
+    }
+    client.setNoDelay(true);
+    localSockets.push(client);
+    client.on("close", () => removeItem(localSockets, client));
+    client.on("error", () => destroyQuietly(client));
+    const pending = {
+      client,
+      timer: setTimeout(() => {
+        removePendingClient(pending);
+        destroyQuietly(client);
+      }, CLIENT_WAIT_TIMEOUT_MS),
+    };
+    client.on("close", () => removePendingClient(pending));
+    pendingClients.push(pending);
+    drainPending();
+  });
+
+  const cleanup = async () => {
+    closed = true;
+    for (const waiter of relayWaiters.splice(0)) {
+      clearTimeout(waiter.timer);
+      waiter.resolve(false);
+    }
+    for (const pending of pendingClients.splice(0)) {
+      clearTimeout(pending.timer);
+      destroyQuietly(pending.client);
+    }
+    for (const socket of [...localSockets, ...relaySockets]) destroyQuietly(socket);
+    for (const child of relayChildren) {
+      try {
+        child.kill();
+      } catch {
+        // ignore
+      }
+    }
+    closeServerQuietly(localServer);
+    closeServerQuietly(brokerServer);
+  };
+
+  let localPort;
+  let brokerPort;
+  try {
+    localPort = await listen(localServer, relayPort(projectRoot), "127.0.0.1");
+    brokerPort = await listen(brokerServer, 0, "0.0.0.0");
+  } catch (error) {
+    await cleanup();
+    throw new Error(`Could not start the WSL reverse relay broker: ${error.message}`);
+  }
+
+  let selectedHost = null;
+  for (const brokerHost of wslBrokerHosts()) {
+    const child = spawn(
+      relay.wslPath,
+      ["--reverse", brokerHost, String(brokerPort), String(debugPort), String(REVERSE_RELAY_POOL)],
+      { detached: true, stdio: "ignore" },
+    );
+    relayChildren.push(child);
+    child.unref();
+
+    if (await waitForRelayReady(brokerHost === "127.0.0.1" ? 1800 : 3000)) {
+      selectedHost = brokerHost;
+      break;
+    }
+
+    try {
+      child.kill();
+    } catch {
+      // ignore
+    }
+  }
+
+  if (!selectedHost) {
+    await cleanup();
+    throw new Error(
+      "WSL is in NAT mode, but the Windows relay could not connect back to the WSL broker. " +
+        "Run `npx @brunosps00/dev-workflow setup-wsl-browser` to reinstall the relay, or enable mirrored networking.",
+    );
+  }
+
+  return {
+    hosts: ["127.0.0.1", "localhost"],
+    port: localPort,
+    relayHost: selectedHost,
+    cleanup,
+  };
+}
+
 // Launches the Windows browser in remote-debugging mode and returns a CDP descriptor.
 // - mirrored networking: WSL shares the Windows loopback (Hyper-V LoopbackEnabled), connect 127.0.0.1.
-// - NAT networking: the prebuilt cdp-relay.exe bridges 0.0.0.0:<relayPort> -> 127.0.0.1:<debug> on the
-//   Windows side, and WSL connects via the Windows host gateway. This needs a one-time Hyper-V firewall
-//   inbound rule for <relayPort> (added by `setup-wsl-browser`), because WSL's Hyper-V firewall defaults
-//   inbound to Block. The browser echoes the request Host into webSocketDebuggerUrl, so the ws stays
-//   reachable through the relay.
+// - NAT networking: the prebuilt cdp-relay.exe runs on Windows in reverse mode. It connects outbound
+//   to a WSL broker, which exposes a local proxy for Playwright. The browser echoes the request Host
+//   into webSocketDebuggerUrl, so the ws stays reachable through the local proxy.
 // --remote-allow-origins=* is required or Chromium drops the DevTools ws (anti-DNS-rebinding).
 async function launchWindowsBrowser(exePath, { headless, projectRoot }) {
   const mirrored = isMirroredNetworking();
@@ -282,39 +508,42 @@ async function launchWindowsBrowser(exePath, { headless, projectRoot }) {
     }
   };
 
-  let hosts;
-  let port;
-  if (mirrored) {
-    hosts = ["127.0.0.1", "localhost"];
-    port = debugPort;
-  } else {
-    const relay = findRelayExe(projectRoot);
-    if (!relay) {
-      await cleanup();
+  try {
+    let hosts;
+    let port;
+    let sourceSuffix = "";
+    if (mirrored) {
+      hosts = ["127.0.0.1", "localhost"];
+      port = debugPort;
+    } else {
+      const relay = findRelayExe(projectRoot);
+      if (!relay) {
+        throw new Error(
+          "WSL is in NAT mode; reaching the Windows browser needs cdp-relay.exe. Run " +
+            "`npx @brunosps00/dev-workflow setup-wsl-browser` to install the prebuilt relay in your Windows user profile. " +
+            "Alternatively enable mirrored networking or set BROWSER_TEST to a CDP URL.",
+        );
+      }
+      const reverseRelay = await startReverseRelayBroker({ relay, debugPort, projectRoot });
+      cleanups.unshift(reverseRelay.cleanup);
+      hosts = reverseRelay.hosts;
+      port = reverseRelay.port;
+      sourceSuffix = "+reverse-relay";
+    }
+
+    const found = await waitForCdp(hosts, port);
+    if (!found) {
       throw new Error(
-        "WSL is in NAT mode; reaching the Windows browser needs cdp-relay.exe. Run " +
-          "`npx @brunosps00/dev-workflow setup-wsl-browser` (installs the prebuilt relay and adds the " +
-          "Hyper-V firewall rule). Alternatively enable mirrored networking or set BROWSER_TEST to a CDP URL.",
+        `Launched ${path.basename(exePath)} but its CDP endpoint was not reachable (${hosts.join("/")}:${port}). ` +
+          "Run `npx @brunosps00/dev-workflow setup-wsl-browser` to reinstall the user-level relay, or enable mirrored networking.",
       );
     }
-    const rport = relayPort(projectRoot);
-    const relayChild = spawn(relay.wslPath, [String(rport), String(debugPort)], { detached: true, stdio: "ignore" });
-    relayChild.unref();
-    cleanups.unshift(() => relayChild.kill());
-    hosts = [windowsHostIp(), "127.0.0.1"].filter(Boolean);
-    port = rport;
-  }
 
-  const found = await waitForCdp(hosts, port);
-  if (!found) {
+    return { mode: "cdp", endpoint: found.base, source: `launched:${path.basename(exePath)}${sourceSuffix}`, cleanup };
+  } catch (error) {
     await cleanup();
-    throw new Error(
-      `Launched ${path.basename(exePath)} but its CDP endpoint was not reachable (${hosts.join("/")}:${port}). ` +
-        "The Hyper-V firewall rule may be missing — run `npx @brunosps00/dev-workflow setup-wsl-browser`.",
-    );
+    throw error;
   }
-
-  return { mode: "cdp", endpoint: found.base, source: `launched:${path.basename(exePath)}${mirrored ? "" : "+relay"}`, cleanup };
 }
 
 const noopCleanup = async () => {};

package/scaffold/skills/dw-testing-discipline/references/playwright-recipes.md

@@ -289,21 +289,21 @@ Resolution order: `BROWSER_TEST` env → `.dw/config.json` (`browserTest`) → d
 - **`BROWSER_TEST` = Windows exe** (e.g. `/mnt/c/.../msedge.exe`): launches it with a temp profile in
   remote-debugging mode (`--remote-allow-origins=*`) and connects over CDP. **Works in both WSL2 modes:**
   in mirrored networking it connects to `127.0.0.1` directly; in NAT mode it starts the bundled
-  **`cdp-relay.exe`** (a tiny prebuilt Windows x64 binary, no runtime) on Windows — `0.0.0.0:39222` → `127.0.0.1:<debug>` —
-  and connects via the Windows host gateway. Falls back to headless Chromium if the relay/rule is absent.
+  **`cdp-relay.exe`** (a tiny prebuilt Windows x64 binary, no runtime) on Windows in reverse mode.
+  The relay opens outbound connections to a WSL broker, which exposes a local CDP proxy. Falls back
+  to headless Chromium if the relay is absent.
 - **`BROWSER_TEST` = channel** (`chrome` | `msedge` | `chromium`): launches that channel locally.
 
-NAT mode needs a one-time setup (the WSL **Hyper-V firewall** defaults inbound to Block, and Chromium
-binds its debug port to loopback only):
+NAT mode needs a one-time user-level setup because Chromium binds its debug port to Windows loopback only:
 
 ```bash
 npx @brunosps00/dev-workflow setup-wsl-browser
 ```
 
-This installs the `cdp-relay.exe` bundled with dev-workflow and adds a Hyper-V firewall inbound allow
-rule for TCP 39222 (one UAC prompt). No Rust toolchain is required on the Windows target. After that, the *real* Windows browser is
-driven from WSL — including `page.screencast` video — under NAT. The launched browser and relay use a
-throwaway profile and are killed on exit.
+This installs the `cdp-relay.exe` bundled with dev-workflow into `%LOCALAPPDATA%\dev-workflow`.
+No admin prompt, firewall rule, or Rust toolchain is required on the Windows target. After that,
+the *real* Windows browser is driven from WSL — including `page.screencast` video — under NAT.
+The launched browser and relay use a throwaway profile and are killed on exit.
 
 Two env vars, two jobs — keep them distinct:
 - `BROWSER` — opens URLs for a human (used by `/dw-generate-pr`).