windscout 0.6.5 → 0.7.1

package/README.md

@@ -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:
@@ -54,17 +105,18 @@ Run `windscout` with no arguments to open the interactive picker:
 | `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 the speed-test 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 `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.
+**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, 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.
+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 or `0` to connect to the best one, type another one's number and press enter to connect to that, or press `q` to quit. `0` and `q` work right away, without enter.
 
 ### Non-interactive
 
@@ -86,10 +138,47 @@ windscout -t 40 -a                          # longer connect timeout, also list
 | `-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 | |
 
+## 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. Its country list shows just the countries this scan tries, all selected; your own selection comes back when you change the type, and 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.
@@ -109,7 +198,7 @@ Both modes show an **availability grid**: one row per country, and ✓ / ✗ for
 ╰─────────────────────────┴────────────────────────┴─────────┴───────────┴─────╯
 ```
 
-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.
+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. The scan starts on the ranking (*Working so far*) until you switch: then the next scans start on the table you left it on (saved to `~/.config/windscout/view.json`).
 
 ## All ports
 
@@ -159,7 +248,7 @@ Then the first parallel scan builds a local image, `windscout-worker`, with Node
 
 The mirrors come from [Mirava](https://github.com/MiravaOrg/Mirava)'s list of mirrors in Iran; they come and go, and that's where to look for new ones.
 
-**Kernel check:** each container first checks that docker's Linux kernel gives it what Windscribe needs: a tunnel device (tun) and a firewall (nftables). If not, the scan stops and says so, rather than showing every location as blocked. Windscribe's WireGuard also needs nftables' `fib` in its firewall table, which Docker Desktop's own Linux VM lacks (on macOS, and on Windows without WSL 2). There, WireGuard runs on this computer instead (see below).
+**Kernel check:** each container first checks that docker's Linux kernel gives it what Windscribe needs: a tunnel device (tun) and a firewall (nftables). If not, the scan stops and says so, rather than showing every location as blocked. Windscribe's WireGuard also needs nftables' `fib` in its firewall table, which Docker Desktop's own Linux VM lacks (on macOS, and on Windows without WSL 2). There, a parallel scan skips WireGuard (see below).
 
 **Login:** the containers' Windscribe apps log in with the session that the Windscribe app on this computer is logged in with, so they never log in with your password. Windscribe locks an account that logs in many times at once, and a login per container would do that. WindScout reads the session from the app's settings (`~/.config/Windscribe/Windscribe2.conf` on Linux, the `com.windscribe.Windscribe2` defaults on macOS, `HKEY_CURRENT_USER\Software\Windscribe\Windscribe2` in the registry on Windows) and hands it to each container on its standard input, not on a command line, where other programs could see it. Each container's docker volume (`windscout-1`, `windscout-2`, …) keeps its app's settings for the next scans, with the WireGuard keys it registered with your account. A volume that another account used starts over. If you log out of the Windscribe app, the containers' session ends too, and the next scan gives them the new one.
 
@@ -171,7 +260,7 @@ WindScout 0.6.0 asked for your username and password instead, and could save the
 
 **Differences from a normal scan:**
 
-- IKEv2, and WireGuard when the kernel check finds it can't run in the containers, are tried on this computer once the containers are done, one at a time like a normal scan. The scan screen shows them on a line of their own (`this computer`), and the picker's estimate counts them. Windscribe's Linux app has no IKEv2.
+- The containers do the whole scan: nothing runs on this computer. What they can't run is skipped: IKEv2 (Windscribe's Linux app has none), and WireGuard when the kernel check finds it can't run in the containers. The picker's docker line says so (`ikev2 skipped`), its estimate leaves them out, and a line after the scan lists them. To try them, scan without docker. If every container stops, the scan ends there, with what they found, and says why.
 - This computer's own Windscribe connection is disconnected at the start and stays off while the containers scan, since it would carry their traffic too.
 - No firewall: "block internet while scanning" isn't used, since it would block the containers' traffic too.
 

package/dist/cli.js

@@ -5,24 +5,27 @@
 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,27 +34,48 @@ 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) => {
+/** The typed answer; one of instant is taken as soon as it's the whole answer, without enter */
+const ask = (question, instant = []) => new Promise((resolve) => {
     const rl = createInterface({ input: process.stdin, output: out });
+    // runs after readline's own keypress listener, so rl.line has the key in it
+    const onKey = () => instant.includes(rl.line.toLowerCase()) && (out.write("\n"), resolve(rl.line), rl.close());
+    process.stdin.on("keypress", onKey);
     rl.on("SIGINT", () => rl.close()); // Ctrl-C / Ctrl-D: no answer, null
-    rl.on("close", () => resolve(null));
+    rl.on("close", () => (process.stdin.off("keypress", onKey), resolve(null)));
     rl.question(question, (a) => (resolve(a.trim()), rl.close()));
 });
-/** Asks which numbered connection to make (enter: the best), then runs its command and waits for it to connect */
+/** 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.
+ * 0 and q need no enter; the other numbers do, since 1 may be the start of 10 */
 async function offerConnect(choices, timeout) {
     const others = choices.length > 2 ? `, 1-${choices.length - 1} = other` : choices.length > 1 ? ", 1 = other" : "";
     for (;;) {
-        const a = await ask(`\nconnect to # (enter or 0 = best${others}, q = quit): `);
+        const a = await ask(`\nconnect to # (enter or 0 = best${others}, q = quit): `, ["0", "q"]);
         if (a === null || /^q(uit)?$/i.test(a))
             return;
         const r = a === "" ? choices[0] : /^\d+$/.test(a) ? choices[Number(a)] : undefined;
@@ -59,14 +83,28 @@ 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() {
@@ -80,7 +118,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" },
@@ -91,7 +130,9 @@ async function main() {
             version: { type: "boolean", short: "v", default: false },
             "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 +144,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 +160,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 +187,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,47 +201,71 @@ 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);
-    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;
-    if (docker && inContainers) {
-        const started = await startParallel(inContainers);
+    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)])];
+    // a parallel scan is the containers' alone: the protocols they can't run (IKEv2, WireGuard on some kernels) aren't tried
+    let probers = [probe], skipped = new Set();
+    const inContainers = () => attempts.filter((x) => !skipped.has(x.protocol));
+    const nothingLeft = () => new Error(`the docker containers can't run ${[...skipped].join(" or ")}, and nothing else is selected:`
+        + " scan without --docker (d in the picker)");
+    if (docker && attempts.length) {
+        skipped = notInContainers(scanned, loadDockerWireGuard()); // as far as the last parallel scan knows
+        if (!inContainers().length)
+            throw nothingLeft();
+        const started = await startParallel(inContainers().length);
         if (!started)
             return leaveScreen();
         saveDockerWireGuard(started.wireguard);
         probers = started.probers;
-        after = { prober: probe, protocols: notInContainers(protocols, started.wireguard), name: "this computer" };
+        skipped = notInContainers(scanned, started.wireguard); // their kernel may not run WireGuard after all, or may now
+        if (!inContainers().length) {
+            await stopWorkers();
+            throw nothingLeft();
+        }
         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.filter((p) => !skipped.has(p)), { timeout, speedTest, only: inContainers(), stopAtFirst }, probers);
     // not with containers: their traffic goes out through this computer, and the firewall would block it
-    const blocking = firewall && !after && (await blockInternet());
+    const blocking = firewall && !docker && (await blockInternet());
     const view = tty ? showProgress(scan, blocking) : logProgress(scan);
     await scan.run(view);
-    if (after)
+    if (docker)
         await stopWorkers();
     await restoreFirewall();
     view.close();
     for (const e of new Set(scan.errors))
         console.error(yellow(e));
-    if (scan.stopping)
+    if (skipped.size)
+        console.error(yellow(`not tried: ${[...skipped].join(", ")}, which the docker containers can't run (a scan without --docker can)`));
+    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, scan.protocols, { 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,7 +1,9 @@
-// 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, the last scan's working results, and the
+// scan screen's table, 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";
 // false hides the speed test: every scan is connect-only, and a saved "on" reads as off
 export const SPEED_TEST = true;
@@ -9,6 +11,8 @@ 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
+const VIEW_FILE = join(dirname(CONFIG), "view.json"); // the table the scan screen was left on
 /** The saved choice, minus anything this version doesn't offer; null on first run or an unreadable file */
 export function loadConfig() {
     try {
@@ -18,7 +22,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 +56,46 @@ export function saveDockerWireGuard(wireguard) {
     }
     catch { } // not being able to remember isn't worth failing the scan
 }
+/** The table the last scan was left on; the ranking until the user switches */
+export function loadView() {
+    try {
+        return JSON.parse(readFileSync(VIEW_FILE, "utf8")).view === "availability" ? "availability" : "ranking";
+    }
+    catch {
+        return "ranking";
+    }
+}
+export function saveView(view) {
+    try {
+        mkdirSync(dirname(VIEW_FILE), { recursive: true });
+        writeFileSync(VIEW_FILE, JSON.stringify({ view }) + "\n");
+    }
+    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

@@ -29,7 +29,7 @@ const REGISTRIES = [...(process.env.WINDSCOUT_REGISTRY_MIRRORS?.split(",").map((
 // openresolv: the app sets the tunnel's DNS through resolvconf; without it, DNS goes nowhere once connected.
 // The CMD first checks the kernel (WSL's builds tun and parts of nftables as modules): no tun or nftables, no tunnel, so
 // the container stops saying so instead of scanning. The helper's WireGuard routing also puts a fib rule in an inet table,
-// which Docker Desktop's own kernel (macOS, Windows without WSL) can't run: WS_WIREGUARD=0 then, and it runs on this computer.
+// which Docker Desktop's own kernel (macOS, Windows without WSL) can't run: WS_WIREGUARD=0 then, and a parallel scan skips it.
 // No systemd in a container: start the helper (root) like its unit would; the worker starts the app once it has the session
 const DOCKERFILE = `FROM ${BASE_TAG}
 ENV LANG=C.UTF-8
@@ -107,8 +107,8 @@ export async function dockerState() {
 const WORKER_MEMORY = 250e6; // bytes per container: Windscribe's app and helper, a tunnel and node take ~120 MB
 // ponytail: past this, more containers mostly add load on the one uplink, and WireGuard keys on the account; raise if real scans say so
 const MAX_WORKERS = 16;
-/** Protocols the containers can't do, which a parallel scan runs on this computer after them: IKEv2 (Windscribe's Linux app
- * has none), and WireGuard when their kernel can't run its routing (see DOCKERFILE) */
+/** Protocols the containers can't do, which a parallel scan skips: IKEv2 (Windscribe's Linux app has none), and WireGuard
+ * when their kernel can't run its routing (see DOCKERFILE) */
 export const notInContainers = (protocols, wireguard) => new Set(protocols.filter((p) => /^ikev2(:|$)/.test(p) || (!wireguard && /^wireguard(:|$)/.test(p))));
 /** Containers for this many attempts, when docker can run at most `most`: one per attempt; past that, the fewest that need no
  * more rounds (17 attempts, 16 at most: 9 containers make 2 rounds, as 16 would), since fewer log in sooner and register fewer keys */
@@ -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;