windscout 0.6.4 → 0.7.0

package/README.md

@@ -1,8 +1,8 @@
 # WindScout
 
-Find which Windscribe locations and protocols actually work from your network, ranked by latency. Runs on Linux, macOS and Windows.
+Find which Windscribe locations and protocols actually work from your network, ranked by speed. Runs on Linux, macOS and Windows.
 
-WindScout drives the official `windscribe-cli`: it connects to each country × protocol pair, measures latency through the tunnel, disconnects, and prints a ranked table.
+WindScout drives the official `windscribe-cli`: it connects to each country × protocol pair, measures latency and download speed through the tunnel, disconnects, and prints a ranked table.
 
 ![WindScout picking countries, scanning, and printing the availability grid and ranked results](demo.gif)
 
@@ -23,6 +23,57 @@ npm install -g windscout   # or run once with: npx windscout
 
 On startup, WindScout checks npm for a newer version. Above the repository link at the bottom of the screen, it shows the installed version in grey (`windscout 0.5.6 · latest` once npm confirms nothing newer is out), or, when a newer one is out, an update notice in yellow. In the picker, press `u` to update and restart on the new version. The update runs `npm install -g windscout@latest`, with `sudo` when your global npm folder belongs to root (sudo then asks for your password). The update command is also printed after the final report.
 
+### In a sandbox (Docker)
+
+To run WindScout without installing it or Node on your computer, run it in a container. The container has its own Windscribe app (Windscribe's Linux CLI app) and, for [parallel scans](#parallel-scan-with-docker), its own docker daemon inside it (Docker-in-Docker). You need Docker: on Linux, docker itself; on macOS and Windows, [Docker Desktop](https://docs.docker.com/desktop/) (on Windows with its WSL 2 engine, set to Linux containers). Build the image once, the same way on every system. Docker fetches this repository from GitHub itself, so there's nothing to clone (add `#` and a branch, tag or commit to the URL to build that one, as in `windscout.git#main`; in a clone, use `.` in place of the URL to build your copy):
+
+```sh
+docker build -t windscout-sandbox -f sandbox/Dockerfile https://github.com/Diercohen/windscout.git
+```
+
+Then run it with the command for your system, below. If the Windscribe app on your computer is logged in, the container's app logs in with that app's session, as the [parallel scan's containers](#parallel-scan-with-docker) do: the command hands it to the container in a file mounted read-only, and the container copies only the session (`userId` and `authHash`) into its own app's settings. Without the app, or when its session doesn't work, the container asks for your Windscribe username and password (and 2FA code, if you use one), and the `windscout-home` volume keeps that login for the next runs. Then the picker opens as usual. Options after the image name go to WindScout: `windscout-sandbox -c "DE,NL" -d`. The `windscout-docker` volume keeps the inner docker's `windscout-worker` image and its containers' volumes, so only the first parallel scan builds them.
+
+**Linux:** the app's settings file is mounted as it is (read-only, never changed). Without the Windscribe app, leave out the `Windscribe2.conf` line: otherwise docker creates an empty folder in its place.
+
+```sh
+docker run -it --rm --privileged \
+  -v ~/.config/Windscribe/Windscribe2.conf:/host/Windscribe2.conf:ro \
+  -v windscout-home:/home/ws -v windscout-docker:/var/lib/docker \
+  windscout-sandbox
+```
+
+**macOS** (Terminal): the app keeps its session in its defaults, so the first line writes it to a private temporary file, which the last line deletes after the run.
+
+```sh
+s=$(mktemp) && printf '[General]\nuserId=%s\nauthHash=%s\n' "$(defaults read com.windscribe.Windscribe2 userId)" "$(defaults read com.windscribe.Windscribe2 authHash)" > "$s"
+docker run -it --rm --privileged \
+  -v "$s:/host/Windscribe2.conf:ro" \
+  -v windscout-home:/home/ws -v windscout-docker:/var/lib/docker \
+  windscout-sandbox
+rm -f "$s"
+```
+
+**Windows** (PowerShell): the app keeps its session in the registry, so the first lines write it to a private temporary file, which the last line deletes after the run.
+
+```powershell
+$k = Get-ItemProperty HKCU:\Software\Windscribe\Windscribe2
+$s = New-TemporaryFile
+Set-Content $s "[General]`nuserId=$($k.userId)`nauthHash=$($k.authHash)"
+docker run -it --rm --privileged `
+  -v "$($s.FullName):/host/Windscribe2.conf:ro" `
+  -v windscout-home:/home/ws -v windscout-docker:/var/lib/docker `
+  windscout-sandbox
+Remove-Item $s
+```
+
+Without the Windscribe app on macOS or Windows, run only the `docker run` command, without its `Windscribe2.conf` line.
+
+- `--privileged` is needed: the inner docker, and the Windscribe app's tunnel and firewall, need it. It gives the container broad control of docker's Linux kernel (on Linux, your computer's), so this isolates files and installs, not security. VPN connections stay inside the container: your computer's own connection doesn't change.
+- Docker Desktop's own Linux VM (macOS, Windows without WSL 2) can't run Windscribe's WireGuard (see the kernel check under [parallel scans](#parallel-scan-with-docker)), and in the sandbox that goes for its own app too. Windscribe's Linux app has no IKEv2, so the sandbox doesn't try it.
+- Where Docker Hub refuses (Iran), take the base image from a mirror: `docker build --build-arg BASE=registry.docker.ir/library/node:22-bookworm-slim -t windscout-sandbox -f sandbox/Dockerfile https://github.com/Diercohen/windscout.git`
+- Updating from inside (`u`) doesn't last, since each run starts fresh from the image: run the build command again instead, for the latest WindScout; add `--no-cache` to get the latest Windscribe app too.
+- To remove everything: `docker rmi windscout-sandbox` and `docker volume rm windscout-home windscout-docker`.
+
 ## Usage
 
 Run `windscout` with no arguments to open the interactive picker:
@@ -30,7 +81,7 @@ Run `windscout` with no arguments to open the interactive picker:
 ```
 ╭─ WindScout ──────────────────────────────────── 2/68 selected ─╮
 │ 1 ● wireguard   2 ● stealth   3 ○ wstunnel   4 ● udp   5 ● tcp │
-│ p ○ all ports  off: each protocol on its default port          │
+│ s ○ speed test  off: connect-only, ranks by latency            │
 ╰────────────────────────────────────────────────────────────────╯
 ╭────────────────────────────────────────────────────────────────╮
 │ 🔍 an▏                                              1–16 of 18 │
@@ -52,18 +103,20 @@ Run `windscout` with no arguments to open the interactive picker:
 | `a` / `n` | select all / unselect all (only the matching countries while a search is active) |
 | `1`–`6` | toggle a protocol (`1`–`5` on Linux, which has no IKEv2) |
 | `p` | toggle [all ports](#all-ports): each protocol on every port it has, not just its default |
+| `s` | toggle the speed test (off = connect-only mode) |
 | `f` | toggle "block internet while scanning" (firewall) |
-| `r` | toggle random order: scan the selected countries shuffled, a new order each run |
 | `d` | toggle the [parallel scan in docker containers](#parallel-scan-with-docker) (installs or starts docker first, after asking) |
+| `o` | change the [scanning type](#scanning-type): default, by random country, by last success result first, only the last results |
+| `w` | toggle [stop at the first working connection](#stop-at-the-first-working-connection) that holds up |
 | `u` | update to the newer version and restart (only when the picker shows one is out) |
 | `enter` | start scanning |
 | `q` | quit (during a scan: stop and show partial results; press again to force quit) |
 
-**Mouse:** click a country to select or unselect it, click a protocol or a setting's line to toggle it, click the search box to start typing (click anywhere else to leave it), and scroll the list with the wheel. The `[ ▶ Start ]  [ All ]  [ None ]  [ Quit ]` buttons under the table do the same as their keys; the shortcut key is underlined on screen (on the buttons, the protocol numbers and the settings' letters). This needs a terminal with mouse support, which most have. On Windows, use Windows Terminal; if clicks do nothing there, the keyboard does everything.
+**Mouse:** click a country to select or unselect it, click a protocol or a setting's line to toggle it (the scanning type's line changes the type), click the search box to start typing (click anywhere else to leave it), and scroll the list with the wheel. The `[ ▶ Start ]  [ All ]  [ None ]  [ Quit ]` buttons under the table do the same as their keys; the shortcut key is underlined on screen (on the buttons, the protocol numbers and `s`). This needs a terminal with mouse support, which most have. On Windows, use Windows Terminal; if clicks do nothing there, the keyboard does everything.
 
 Your selection is saved to `~/.config/windscout/config.json` (`%USERPROFILE%\.config\windscout\config.json` on Windows) and preselected next time.
 
-While scanning, WindScout shows a progress bar, elapsed time and remaining time. It also shows what it's doing right now (connecting or measuring latency). The table of working locations refreshes after each country. When the scan finishes, the final report is printed to your normal terminal. It ends with the best connection and the other working ones, each with its `windscribe-cli connect` command. At the prompt, press enter to connect to the best one, type another one's number to connect to that, or `q` to quit.
+After you start, the Start button spins (`[ ⠋ Starting… ]`) until the scan's screen shows, which can take a moment when it turns the firewall on or starts docker. While scanning, WindScout shows a progress bar, elapsed time and remaining time. It also shows what it's doing right now (connecting, measuring latency or measuring speed). The table of working locations refreshes after each country. When the scan finishes, the final report is printed to your normal terminal. It ends with the best connection and the other working ones, each with its `windscribe-cli connect` command. At the prompt, press enter to connect to the best one, type another one's number to connect to that, or `q` to quit.
 
 ### Non-interactive
 
@@ -83,14 +136,54 @@ windscout -t 40 -a                          # longer connect timeout, also list
 | `-P, --all-ports` | try each protocol on [every port](#all-ports) Windscribe offers for it, not just its default | picker: saved, or off; with `-c`: off |
 | `-t, --timeout` | seconds to wait for each connection, at least 10 | picker: saved, or 15; with `-c`: 15 |
 | `-a, --all` | include failed attempts in the final table | off |
+| `-n, --no-speed` | connect-only mode: skip the download test, rank by latency | picker: saved, or connect-only on first run; with `-c`: speed test on |
 | `-f, --firewall` | block internet while scanning, except through the VPN | picker: saved, or off; with `-c`: off |
-| `-r, --random` | scan the countries in a random order | picker: saved, or off; with `-c`: off |
+| `-o, --order` | [scanning type](#scanning-type): `default`, `random`, `last-first` or `last-only` (`-r` still works: the same as `-o random`) | picker: saved, or `default`; with `-c`: `default` |
+| `-w, --stop-at-first` | [stop at the first working connection](#stop-at-the-first-working-connection) that holds up | picker: saved, or off; with `-c`: off |
 | `-d, --docker` | [scan in parallel, in docker containers](#parallel-scan-with-docker) | picker: saved, or off; with `-c`: off |
 | `-v, --version` | print the installed version; if a newer one is on npm, show the update command (with `sudo` when needed) and ask (y/n) to run it | |
 
-## Availability grid
+## Last result: rescan and connect
+
+After each scan, WindScout saves its working connections, best first, to `~/.config/windscout/last.json`. That includes a partial scan you stopped, and a scan started with `-c`. A scan's working connections replace the saved ones it tried, so the ones that stopped working drop out. The saved connections it didn't try stay, after its own: those of countries it didn't scan, and what a stopped scan didn't get to. A scan where nothing worked keeps the previous result as it is, since the network may just be down.
+
+- **Rescan:** the [scanning types](#scanning-type) *by last success result first* and *only the last results* use the saved connections: the first tries the ones in your selection before the rest of it, the second tries only them.
+- **Connect:** `windscout connect` connects to the best saved connection, without a scan. It checks each as the scan does: when one doesn't connect within the timeout (`-t`, or the saved one), or has no internet through it, it tries the next, until one connects. When none does, or there's no saved scan, it says so and suggests a rescan or a new scan.
+
+```sh
+windscout connect          # the best saved connection that still works
+windscout connect -t 30    # wait longer for each
+```
+
+## Scanning type
+
+Press `o` in the picker, or pass `-o`, to choose what a scan tries and in which order. The picker's line shows the type, and the estimate under the table counts what that type scans. The type is remembered with your other settings.
+
+| Type | `-o` | What it scans |
+|---|---|---|
+| default | `default` | the selected countries × protocols, the countries in list order |
+| by random country | `random` | the same, with the countries shuffled, a new order each run |
+| by last success result first | `last-first` | the same, but the [last result](#last-result-rescan-and-connect)'s working connections among them go first, best first and on their own port, then the rest. With one country selected, only that country is scanned, its saved connections first. The line shows how many saved connections are in your selection (`1 of 7 saved selected · 3h ago`) |
+| only the last results | `last-only` | only the last result's working connections, each on its own protocol and port. The countries, protocols and all ports are skipped, so the picker greys them out and locks them (your selection stays for next time). With `-o last-only`, `-c` isn't needed |
+
+The two types by the last result need a saved scan. Until there is one, choosing either turns `[ ▶ Start ]` off (greyed out), and a warning takes the estimate's place: `no saved scan yet, so start is off: press o for another scanning type`. Without the picker, `-o last-first` and `-o last-only` stop with an error instead. The estimate counts each saved connection once: `tcp` and `tcp:443` are the same attempt when 443 is tcp's default port.
+
+### Stop at the first working connection
+
+Press `w` in the picker, or pass `-w`, to end the scan at the first connection that works and holds up: the attempts still connecting give up, and no more start. The scan stops at one connection, so that one has to be good for long use. A tunnel can connect and then be cut or throttled once traffic flows, so each connection that connects is checked first:
+
+1. A speed test, even with the speed test off (`s`, `-n`). It must reach at least 1 Mbps.
+2. Then it has to stay connected, with internet through it, for 5 round trips 2 s apart (about 10 s), each round trip allowed one retry.
+
+A connection that drops during the check gets the status `unreliable` and doesn't count as working: it isn't saved, or offered to connect to. One that stays up but is slower than 1 Mbps still counts as working, but the scan doesn't stop there and keeps looking. If nothing passes, the scan runs to the end, and the report shows whatever worked.
+
+The check adds up to about 30 s to each connection that connects (the speed test alone takes up to 15 s). The estimate reads `up to N attempts · at most ≈ …`, for when none holds up. With a type by the last result, the best saved connection goes first, and the line shows about how long the scan takes if it still holds up (`≈ 33s if DE stealth still holds up`). It's the quickest way back online: *only the last results* or *by last success result first*, with `w`.
+
+## Connect-only mode
+
+Often you only need to know **what connects**, not how fast it is. Turn the speed test off with `s` in the picker or with `--no-speed`. Each working connection is then checked with a quick latency test only. That saves about 15 s per working connection, and results are ranked by latency. Connect-only is the default on the first run, and the choice is remembered.
 
-Each working connection gets a quick latency test, and the working ones are ranked by latency. The scan screen and the final report show an **availability grid**: one row per country, and ✓ / ✗ for each protocol (`·` = not tried yet; `key limit`, in a [parallel scan](#parallel-scan-with-docker): WireGuard couldn't be tried). With [all ports](#all-ports), it counts how many of a protocol's ports worked: `✓ 3/11`. Location(s) lists each datacenter that connected, one per line, since protocols can land on different ones:
+Both modes show an **availability grid**: one row per country, and ✓ / ✗ for each protocol (`·` = not tried yet; `key limit`, in a [parallel scan](#parallel-scan-with-docker): WireGuard couldn't be tried). With [all ports](#all-ports), it counts how many of a protocol's ports worked: `✓ 3/11`. Location(s) lists each datacenter that connected, one per line, since protocols can land on different ones:
 
 ```
 ╭──────────────────────────────────────────────────────────────────────────────╮
@@ -105,7 +198,7 @@ Each working connection gets a quick latency test, and the working ones are rank
 ╰─────────────────────────┴────────────────────────┴─────────┴───────────┴─────╯
 ```
 
-While scanning, press `tab` to switch between the availability grid and the latency ranking. Press `p` (or `space`) to pause: the current attempt finishes, the VPN disconnects, and the scan waits until you press `p` again. Paused time doesn't count toward elapsed or remaining. The scan starts on the availability grid.
+While scanning, press `tab` to switch between the availability grid and the speed or latency ranking. Press `p` (or `space`) to pause: the current attempt finishes, the VPN disconnects, and the scan waits until you press `p` again. Paused time doesn't count toward elapsed or remaining. In connect-only mode the scan starts on the availability grid.
 
 ## All ports
 
@@ -119,7 +212,7 @@ Each protocol is normally tried on its default port, the first one Windscribe li
 | udp | 443, 80, 53, 123, 1194, 54783 | 6 |
 | tcp | 443, 587, 21, 22, 80, 123, 143, 3306, 8080, 54783, 1194 | 11 |
 
-With every protocol selected, that's 35 attempts per country instead of 5, 7 times as many (on macOS and Windows, IKEv2 adds its own ports). The picker shows the count (`35 attempts per country, not 5`) and the estimate: one country takes about 11m 40s instead of 1m 40s in a normal scan, and about 2 minutes in a [parallel scan](#parallel-scan-with-docker), which helps most here. To try fewer, select only the protocols you need, or give a port yourself: a protocol with a port (`-p tcp:443`) stays on that one.
+With every protocol selected, that's 35 attempts per country instead of 5, 7 times as many (on macOS and Windows, IKEv2 adds its own ports). The picker shows the count (`35 attempts per country, not 5`) and the estimate: one country takes about 11m 40s instead of 1m 40s in a normal scan, and about 2 minutes in a [parallel scan](#parallel-scan-with-docker), which helps most here. With the speed test on, every working port gets a speed test too, about 15 s each, so connect-only mode finds the working ports sooner. To try fewer, select only the protocols you need, or give a port yourself: a protocol with a port (`-p tcp:443`) stays on that one.
 
 The availability grid keeps one column per protocol and counts how many of its ports worked (`✓ 3/11`, or `✗ 0/11` when none did). The results list each working protocol with its port, and the per-protocol table has a line per port.
 
@@ -163,7 +256,7 @@ The mirrors come from [Mirava](https://github.com/MiravaOrg/Mirava)'s list of mi
 
 WindScout 0.6.0 asked for your username and password instead, and could save them in `~/.config/windscout/login.json`. WindScout now deletes that file.
 
-**Measuring:** the containers share your internet connection, so they take turns measuring latency while the connecting happens in parallel. Numbers stay comparable with a normal scan. Most of the time saved comes from attempts that hang until the timeout, which overlap now.
+**Measuring:** the containers share your internet connection, so they take turns measuring latency and speed while the connecting happens in parallel. Numbers stay comparable with a normal scan. Most of the time saved comes from attempts that hang until the timeout, which overlap now.
 
 **Differences from a normal scan:**
 
@@ -183,23 +276,23 @@ While scanning:
 │  ██████████████████████████████████████████▌░░░░░░░░░░░░░░░░   72%   │
 │                                                                      │
 │  ⠏ 🇳🇱 Netherlands · stealth                                          │
-│    measuring latency · Amsterdam - Tulip · 1s                        │
+│    measuring speed · Amsterdam - Tulip · 3s                          │
 ├──────────────────────────────────────────────────────────────────────┤
 │  elapsed 25s   │   remaining ≈ 13s   │   ✓ 2 working   │   ✗ 1 blocked │
 ╰──────────────────────────────────────────────────────────────────────╯
 ╭──────────────────────────────────────────────────────────────────────╮
 │ Working so far                                               2 found │
 ├───┬────────────┬───────────────────────┬───────────┬───────────┬─────┤
-│ # │ Country    │ Location              │ Protocol  │   Latency │ ... │
+│ # │ Country    │ Location              │ Protocol  │     Speed │ ... │
 ```
 
 At the end, the results, a per-protocol summary and the best pick are printed to your normal terminal:
 
 ```
-╭─ ★ Best (lowest latency) ────────────────────╮
-│ 🇳🇱 Amsterdam - Tulip over wireguard · 109 ms │
-│ windscribe-cli connect "Tulip" wireguard     │
-╰──────────────────────────────────────────────╯
+╭─ ★ Best ─────────────────────────────────────────────────╮
+│ 🇳🇱 Amsterdam - Tulip over wireguard · 27.0 Mbps · 109 ms │
+│ windscribe-cli connect "Tulip" wireguard                 │
+╰──────────────────────────────────────────────────────────╯
 ```
 
 ## Notes

package/dist/cli.js

@@ -1,28 +1,31 @@
 #!/usr/bin/env node
 // WindScout: find which Windscribe locations and protocols actually work from here.
 // Drives the official windscribe-cli: connects to each country/protocol pair,
-// measures latency through the tunnel, prints a ranked table.
+// measures latency and download speed through the tunnel, prints a ranked table.
 import { createInterface } from "node:readline";
 import { spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
-import { CONFIG, DEFAULT_TIMEOUT, forgetLogin, loadConfig, loadDockerWireGuard, MIN_TIMEOUT, saveDockerWireGuard, SPEED_TEST } from "./config.js";
+import { CONFIG, DEFAULT_TIMEOUT, forgetLogin, LAST_FILE, loadConfig, loadDockerWireGuard, loadLast, MIN_TIMEOUT, saveDockerWireGuard, saveLast, SPEED_TEST } from "./config.js";
 import { notInContainers, stopWorkers } from "./docker.js";
-import { probe } from "./probe.js";
-import { Scan } from "./scan.js";
+import { attempt, disconnect, MIN_MBPS, probe } from "./probe.js";
+import { ORDERS, plan, Scan } from "./scan.js";
 import { startParallel } from "./tui/docker.js";
 import { pick } from "./tui/picker.js";
 import { logProgress, showProgress } from "./tui/progress.js";
 import { command, report, target } from "./tui/report.js";
 import { leaveScreen, out } from "./tui/terminal.js";
 import { cyan, green, yellow } from "./tui/text.js";
-import { now, sleep } from "./time.js";
+import { duration, now } from "./time.js";
 import { canUpdate, checkUpdate, runUpdate, updateNotice, versionLines } from "./update.js";
-import { blockInternet, CLI, connectState, isFirewallOn, protocolPorts, PROTOCOLS, restoreFirewall, waitForLogin, windscribe, withPorts } from "./windscribe.js";
+import { blockInternet, CLI, isFirewallOn, protocolPorts, PROTOCOLS, restoreFirewall, waitForLogin, windscribe, withPorts } from "./windscribe.js";
 import { worker } from "./worker.js";
 const HELP = `Usage: windscout [options]
+       windscout connect [-t SEC]
 
 Find which Windscribe locations and protocols work from your network, ranked by ${SPEED_TEST ? "speed" : "latency"}.
 Without -c it opens an interactive country picker (your selection is remembered).
+Each scan's working connections are saved: the scanning type (-o, or o in the picker) can try
+them first or only them, and windscout connect connects to the best of them that still works.
 
 Options:
   -c, --countries LIST  comma-separated ISO codes, city names or nicknames (skips the picker)
@@ -31,14 +34,19 @@ Options:
   -t, --timeout SEC     seconds to wait for each connection, at least ${MIN_TIMEOUT} (default: saved, or ${DEFAULT_TIMEOUT})
   -a, --all             also show failed attempts in the final table
 ${SPEED_TEST ? "  -n, --no-speed        connect-only: skip the download test, rank by latency (faster scan)\n" : ""}  -f, --firewall        block internet while scanning, except through the VPN (turned back off afterwards)
-  -r, --random          scan the countries in a random order
+  -o, --order TYPE      scanning type: default (list order), random (countries shuffled), last-first (the last
+                        result's working connections among them first, then the rest) or last-only (only those,
+                        whatever -c and -p say; needs no -c)
+  -w, --stop-at-first   stop at the first working connection that holds up: a speed test (even with -n) of at least
+                        ${MIN_MBPS} Mbps, then about 10 more seconds connected, with internet through it
   -d, --docker          scan in parallel, in docker containers (one per attempt, up to 16, as docker's CPUs and memory allow)
   -v, --version         show the installed version (and offer to update if a newer one is out)
   -h, --help            show this help
 
-Selection is stored in ${CONFIG}
+Selection is stored in ${CONFIG}, the last result in ${LAST_FILE}
 Examples: windscout -c DE,NL,TR -p stealth,tcp:443
-          windscout -c DE -p stealth,tcp -P`;
+          windscout -c DE -p stealth,tcp -P
+          windscout connect`;
 // "DE, NL,,TR" → ["DE", "NL", "TR"]
 const list = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
 const ask = (question) => new Promise((resolve) => {
@@ -47,6 +55,17 @@ const ask = (question) => new Promise((resolve) => {
     rl.on("close", () => resolve(null));
     rl.question(question, (a) => (resolve(a.trim()), rl.close()));
 });
+/** Runs a result's connect command and checks it as the scan does: connected, on its port, with internet through it.
+ * True once it is; otherwise disconnects (and waits until the app has), so the next connect isn't swallowed */
+async function connectTo(r, timeout) {
+    console.log(cyan(command(r)));
+    const t = now(), { status, location } = await attempt(target(r), r.protocol, { timeout, speedTest: false });
+    if (status === "ok")
+        return console.log(green(`Connected: ${location}`)), true;
+    console.log(yellow(`${status} after ${duration(now() - t)}`));
+    await disconnect();
+    return false;
+}
 /** Asks which numbered connection to make (enter: the best), then runs its command and waits for it to connect */
 async function offerConnect(choices, timeout) {
     const others = choices.length > 2 ? `, 1-${choices.length - 1} = other` : choices.length > 1 ? ", 1 = other" : "";
@@ -59,15 +78,29 @@ async function offerConnect(choices, timeout) {
             console.log(yellow(`no #${a} in the tables`));
             continue;
         }
-        console.log(cyan(command(r)));
-        await windscribe("connect", target(r), r.protocol);
-        let state = "";
-        for (const t = now(); now() - t < timeout && !(state = await connectState()).startsWith("Connected");)
-            await sleep(1000);
-        console.log(state.startsWith("Connected") ? green(state) : yellow(`${state || "not connected"} after ${timeout} s`));
+        await connectTo(r, timeout);
         return;
     }
 }
+const RESCAN_HINT = "rescan them with windscout -o last-only, or start a new scan";
+/** windscout connect: the last result's connections, best first, until one connects */
+async function connectLast(timeout) {
+    const last = loadLast();
+    if (!last) {
+        console.log(yellow("no saved scan yet: run windscout to scan first"));
+        process.exitCode = 1;
+        return;
+    }
+    await waitForLogin();
+    await disconnect(); // a connection already up would read as the first one connecting
+    for (const [i, r] of last.results.entries()) {
+        console.log(`\n${i + 1}/${last.results.length} ${r.location || r.query} over ${r.protocol}`);
+        if (await connectTo(r, timeout))
+            return;
+    }
+    console.log(yellow(`\nnone of the last result's ${last.results.length} connection${last.results.length === 1 ? "" : "s"} works now: ${RESCAN_HINT}`));
+    process.exitCode = 1;
+}
 /** u in the picker: update, then run the new version in this one's place, with the same arguments */
 function updateAndRestart() {
     const status = runUpdate();
@@ -80,7 +113,8 @@ function updateAndRestart() {
     process.exitCode = spawnSync(process.execPath, [...process.execArgv, ...process.argv.slice(1)], { stdio: "inherit" }).status ?? 1;
 }
 async function main() {
-    const { values: a } = parseArgs({
+    const { values: a, positionals } = parseArgs({
+        allowPositionals: true,
         options: {
             countries: { type: "string", short: "c" },
             protocols: { type: "string", short: "p" },
@@ -89,9 +123,11 @@ async function main() {
             all: { type: "boolean", short: "a", default: false },
             help: { type: "boolean", short: "h", default: false },
             version: { type: "boolean", short: "v", default: false },
-            "no-speed": { type: "boolean", short: "n", default: false }, // still accepted while the speed test is hidden
+            "no-speed": { type: "boolean", short: "n", default: false },
             firewall: { type: "boolean", short: "f", default: false },
-            random: { type: "boolean", short: "r", default: false },
+            order: { type: "string", short: "o" },
+            "stop-at-first": { type: "boolean", short: "w", default: false },
+            random: { type: "boolean", short: "r", default: false }, // from before scanning types: -o random
             docker: { type: "boolean", short: "d", default: false },
             worker: { type: "boolean", default: false }, // in a parallel scan's container
         },
@@ -103,6 +139,11 @@ async function main() {
     forgetLogin();
     if (a.help)
         return console.log(HELP);
+    const [subcommand, ...extra] = positionals;
+    if (subcommand !== undefined && (subcommand !== "connect" || extra.length))
+        throw new Error(`unknown command '${positionals.join(" ")}': see --help`);
+    if (subcommand === "connect" && Object.entries(a).some(([k, v]) => k !== "timeout" && v))
+        throw new Error("windscout connect takes only -t: see --help");
     checkUpdate(); // runs while the app starts and the user picks, before the VPN starts switching
     if (a.version) {
         await checkUpdate();
@@ -114,16 +155,23 @@ async function main() {
     let timeout = a.timeout ? Number(a.timeout) : undefined;
     if (timeout !== undefined && !(timeout >= MIN_TIMEOUT))
         throw new Error(`--timeout must be at least ${MIN_TIMEOUT} seconds`);
+    if (a.order !== undefined && !ORDERS.includes(a.order))
+        throw new Error(`--order must be one of: ${ORDERS.join(", ")}`);
+    if (subcommand === "connect")
+        return connectLast(timeout ?? loadConfig()?.timeout ?? DEFAULT_TIMEOUT);
     const status = await waitForLogin();
     const tty = Boolean(process.stdin.isTTY && out.isTTY);
     let countries = a.countries ? list(a.countries) : undefined;
     let protocols = a.protocols ? list(a.protocols) : undefined;
     let speedTest = SPEED_TEST && !a["no-speed"];
     let firewall = a.firewall;
-    let random = a.random;
+    let order = (a.order ?? (a.random ? "random" : undefined));
+    let stopAtFirst = a["stop-at-first"];
     let allPorts = a["all-ports"];
     let docker = a.docker;
-    if (!countries) {
+    const last = loadLast();
+    // only the last results needs no countries: without a terminal, it goes without the picker
+    if (!countries && !(order === "last-only" && !tty)) {
         if (!tty)
             throw new Error("no terminal for the picker: pass countries with -c");
         const saved = loadConfig();
@@ -134,9 +182,11 @@ async function main() {
             speedTest: speedTest && (saved?.speed ?? false), // first run: connect-only
             // already on in the app: show it on, since the scan won't turn it off
             firewall: firewall || isFirewallOn(status) || (saved?.firewall ?? false),
-            random: random || (saved?.random ?? false),
+            order: order ?? saved?.order ?? "default",
+            stopAtFirst: stopAtFirst || (saved?.stopAtFirst ?? false),
             allPorts: allPorts || (saved?.allPorts ?? false),
             docker: docker || (saved?.docker ?? false),
+            last,
         });
         if (!choice)
             return;
@@ -146,34 +196,41 @@ async function main() {
         protocols ??= choice.protocols;
         speedTest = choice.speed;
         firewall = choice.firewall;
-        random = choice.random;
+        order = choice.order;
+        stopAtFirst = choice.stopAtFirst;
         allPorts = choice.allPorts;
         timeout = choice.timeout;
         docker = choice.docker;
     }
+    countries ??= [];
     protocols ??= PROTOCOLS;
     timeout ??= DEFAULT_TIMEOUT;
-    // the picker asked for the ports already: waiting for that keeps windscribe-cli free for the scan
-    if (allPorts || !a.countries) {
-        const lists = await protocolPorts();
-        if (allPorts)
-            protocols = withPorts(protocols, lists);
-    }
-    if (random)
-        countries = countries.map((c) => [Math.random(), c]).sort(([x], [y]) => x - y).map(([, c]) => c);
+    order ??= "default";
+    const byLast = order === "last-first" || order === "last-only"; // a type by the last result: it needs a saved scan
+    if (byLast && !last)
+        throw new Error(`no saved scan yet: -o ${order} needs one, so run a scan with another scanning type first`);
+    const fromLast = byLast ? last : null; // the saved connections this scan uses
+    // the picker asked for the ports already: waiting for that keeps windscribe-cli free for the scan.
+    // The saved connections need them too, to tell a saved "tcp:443" from tcp on its default port
+    const lists = allPorts || !a.countries || fromLast ? await protocolPorts() : undefined;
+    if (allPorts && lists)
+        protocols = withPorts(protocols, lists);
+    const attempts = plan(order, countries, protocols, fromLast?.results, lists);
+    // the tables' columns: the protocols asked for, and the saved connections' own (only those, when only they are scanned)
+    const scanned = [...new Set([...(order === "last-only" ? [] : protocols), ...attempts.map((x) => x.protocol)])];
     let probers = [probe], after; // after: what runs here once the containers are done
-    const later = notInContainers(protocols, loadDockerWireGuard()); // as far as the last parallel scan knows
-    const inContainers = countries.length * protocols.filter((p) => !later.has(p)).length;
+    const later = notInContainers(scanned, loadDockerWireGuard()); // as far as the last parallel scan knows
+    const inContainers = attempts.filter((x) => !later.has(x.protocol)).length;
     if (docker && inContainers) {
         const started = await startParallel(inContainers);
         if (!started)
             return leaveScreen();
         saveDockerWireGuard(started.wireguard);
         probers = started.probers;
-        after = { prober: probe, protocols: notInContainers(protocols, started.wireguard), name: "this computer" };
+        after = { prober: probe, protocols: notInContainers(scanned, started.wireguard), name: "this computer" };
         await windscribe("disconnect"); // a VPN connection here would carry the containers' traffic too
     }
-    const scan = new Scan(countries, protocols, { timeout, speedTest }, probers, after);
+    const scan = new Scan(countries, scanned, { timeout, speedTest, only: attempts, stopAtFirst }, probers, after);
     // not with containers: their traffic goes out through this computer, and the firewall would block it
     const blocking = firewall && !after && (await blockInternet());
     const view = tty ? showProgress(scan, blocking) : logProgress(scan);
@@ -184,9 +241,15 @@ async function main() {
     view.close();
     for (const e of new Set(scan.errors))
         console.error(yellow(e));
-    if (scan.stopping)
+    if (scan.found)
+        console.log(green("stopped at the first connection that held up (a speed test, then staying up)"));
+    else if (scan.stopping)
         console.log(yellow("interrupted, showing partial results"));
-    const choices = report(scan.results, protocols, { all: a.all, speedTest });
+    const choices = report(scan.results, scanned, { all: a.all, speedTest: speedTest || stopAtFirst }); // stop at the first measures speed
+    // its working connections replace the saved ones it tried, so what stopped working drops out; the saved ones it didn't try
+    // (other countries, or what a stopped scan didn't get to) stay, after its own; a scan where nothing worked keeps the last
+    const tried = new Set(scan.results.filter((r) => r.status !== "interrupted").map((r) => `${r.query} ${r.protocol}`));
+    saveLast(choices, undefined, tried);
     await checkUpdate();
     if (updateNotice())
         console.error("\n" + versionLines().join("\n"));

package/dist/config.js

@@ -1,14 +1,16 @@
-// The picker's selection, and what the last parallel scan found its containers can do, remembered between runs.
+// The picker's selection, what the last parallel scan found its containers can do, and the last scan's working results, remembered between runs.
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { ORDERS } from "./scan.js";
 import { COUNTRIES, PROTOCOLS } from "./windscribe.js";
-// The speed test is hidden: every scan is connect-only, and a saved "on" reads as off. Its code stays; true brings it back
-export const SPEED_TEST = false;
+// false hides the speed test: every scan is connect-only, and a saved "on" reads as off
+export const SPEED_TEST = true;
 export const DEFAULT_TIMEOUT = 15;
 export const MIN_TIMEOUT = 10; // seconds; shorter cuts off connections that would have worked
 export const CONFIG = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "windscout", "config.json");
 const DOCKER_FILE = join(dirname(CONFIG), "docker.json"); // what the last parallel scan found its containers can do
+export const LAST_FILE = join(dirname(CONFIG), "last.json"); // the last scan's working connections
 /** The saved choice, minus anything this version doesn't offer; null on first run or an unreadable file */
 export function loadConfig() {
     try {
@@ -18,7 +20,8 @@ export function loadConfig() {
             protocols: (c.protocols ?? []).filter((x) => PROTOCOLS.includes(x)),
             speed: SPEED_TEST && c.speed !== false,
             firewall: c.firewall === true,
-            random: c.random === true,
+            order: ORDERS.includes(c.order) ? c.order : c.random === true ? "random" : "default", // before scanning types: random on or off
+            stopAtFirst: c.stopAtFirst === true,
             allPorts: c.allPorts === true,
             timeout: c.timeout >= MIN_TIMEOUT ? c.timeout : DEFAULT_TIMEOUT,
             docker: c.docker === true,
@@ -51,6 +54,30 @@ export function saveDockerWireGuard(wireguard) {
     }
     catch { } // not being able to remember isn't worth failing the scan
 }
+/** The last scan that found something; null when there's none or the file is unreadable */
+export function loadLast() {
+    try {
+        const l = JSON.parse(readFileSync(LAST_FILE, "utf8"));
+        const results = (l.results ?? []).filter((r) => r?.status === "ok" && typeof r.query === "string" && typeof r.protocol === "string");
+        return results.length && typeof l.at === "number" ? { at: l.at, results } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Saves a scan's working connections; a scan where nothing worked keeps the last one that found something (the network may
+ * just be down). With tried (the "query protocol" pairs the scan tried), the saved connections it didn't try stay, after its own */
+export function saveLast(results, at = Date.now(), tried) {
+    if (!results.length)
+        return;
+    if (tried)
+        results = [...results, ...(loadLast()?.results ?? []).filter((r) => !tried.has(`${r.query} ${r.protocol}`))];
+    try {
+        mkdirSync(dirname(LAST_FILE), { recursive: true });
+        writeFileSync(LAST_FILE, JSON.stringify({ at, results }, null, 2) + "\n");
+    }
+    catch { } // not being able to remember isn't worth failing the scan
+}
 /** Deletes the Windscribe username and password that 0.6.0 saved for the docker containers: they log in with this computer's session now */
 export function forgetLogin() {
     try {

package/dist/docker.js

@@ -288,7 +288,7 @@ export async function startWorkers(n, session, onStatus) {
         };
         p.on("error", (e) => gone(e.message));
         p.on("close", (code) => gone(lastLine(err) || `exited (${code})`));
-        const prober = (query, protocol, { timeout, speedTest, stopped = () => false, onStep = () => { } }) => new Promise((done, reject) => {
+        const prober = (query, protocol, { timeout, speedTest, steady = false, stopped = () => false, onStep = () => { } }) => new Promise((done, reject) => {
             if (dead)
                 return reject(new Error(`container ${i + 1} stopped: ${dead}`));
             let leave = null, over = false;
@@ -311,7 +311,7 @@ export async function startWorkers(n, session, onStatus) {
                 else if (m.result)
                     end(), done(m.result);
             };
-            send({ probe: { query, protocol, timeout, speedTest } });
+            send({ probe: { query, protocol, timeout, speedTest, steady } });
         });
         fail = (why) => (onStatus(`container ${i + 1}: ${why}`), resolve(null));
         on = (m) => {

package/dist/measure.js

@@ -9,7 +9,7 @@ setDefaultAutoSelectFamily(false);
 setDefaultResultOrder("ipv4first");
 const LATENCY_URL = "https://www.gstatic.com/generate_204";
 const SPEED_URL = "https://speed.cloudflare.com/__down?bytes=10000000";
-const SPEED_SECONDS = 15;
+export const SPEED_SECONDS = 15;
 /** Best round trip of a few tries, in ms; null if none got through */
 export async function latencyMs(tries = 3) {
     let best = null;