windscout 0.6.5 → 0.7.0

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 to connect to the best one, type another one's number to connect to that, or `q` to quit.
 
 ### 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 (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.

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,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" },
@@ -91,7 +125,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 +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,7 +1,8 @@
-// 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";
 // false hides the speed test: every scan is connect-only, and a saved "on" reads as off
 export const SPEED_TEST = true;
@@ -9,6 +10,7 @@ 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;

package/dist/probe.js

@@ -1,62 +1,100 @@
 // One attempt: connect to a location over a protocol, measure through the tunnel, disconnect.
-import { latencyMs, speedMbps } from "./measure.js";
+// windscout connect makes the same attempt and, when it works, stays connected.
+import { latencyMs, SPEED_SECONDS, speedMbps } from "./measure.js";
 import { now, sleep } from "./time.js";
 import { connectState, windscribe } from "./windscribe.js";
+// Stop at the first ends the scan at one connection, so that one has to last: a tunnel can connect and then be cut or throttled
+// once traffic flows. It counts once it downloads at MIN_MBPS or more, then stays up with internet for STEADY_CHECKS round trips
+export const MIN_MBPS = 1;
+const STEADY_CHECKS = 5, STEADY_GAP = 2; // seconds between the round trips
+// shortcut: guesses ~5 s to connect and the whole speed test; refine from real runs
+export const STEADY_SECONDS = 5 + SPEED_SECONDS + STEADY_CHECKS * (STEADY_GAP + 0.5);
+/** Whether stop at the first can stop at this result: it worked, held up, and is fast enough for real use */
+export const reliable = (r) => r.status === "ok" && (r.speedMbps ?? 0) >= MIN_MBPS;
 // "Connected: Miami - Vice" → "Miami - Vice"
 const place = (state) => state.split(":").slice(1).join(":").trim();
-export async function probe(query, protocol, { timeout, speedTest, stopped = () => false, onStep = () => { }, measure = (fn) => fn() }) {
+export async function probe(query, protocol, options) {
+    try {
+        return await attempt(query, protocol, options);
+    }
+    finally {
+        options.onStep?.("disconnecting");
+        await disconnect();
+    }
+}
+/** Disconnects, and waits until the app has */
+export async function disconnect() {
+    await windscribe("disconnect");
+    // the CLI's disconnect can return while the app is still tearing down (it does after a timed-out connect);
+    // a connect sent then is swallowed and the next attempt reads as an instant "failed", so wait it out
+    for (let i = 0; i < 30 && (await connectState()) === "Disconnecting"; i++)
+        await sleep(1000);
+}
+/** Connects and measures through the tunnel, as probe does, but leaves the connection as it is: up when it worked */
+export async function attempt(query, protocol, { timeout, speedTest, steady = false, stopped = () => false, onStep = () => { }, measure = (fn) => fn() }) {
     const r = { query, protocol, location: "", connectS: null, latencyMs: null, speedMbps: null };
     const end = (status) => ({ ...r, status });
     onStep("connecting");
     await windscribe("connect", "-n", query, protocol);
     const t = now();
-    try {
-        for (;;) {
-            if (stopped())
-                return end("interrupted");
-            if (now() - t >= timeout)
-                return end("timeout");
-            const s = await connectState();
-            if (s.startsWith("Connecting:"))
+    for (;;) {
+        if (stopped())
+            return end("interrupted");
+        if (now() - t >= timeout)
+            return end("timeout");
+        const s = await connectState();
+        if (s.startsWith("Connecting:"))
+            r.location = place(s);
+        else if (s.startsWith("Connected")) {
+            if (s.includes(":"))
                 r.location = place(s);
-            else if (s.startsWith("Connected")) {
-                if (s.includes(":"))
-                    r.location = place(s);
-                r.connectS = now() - t;
-                break;
-            }
-            else if (s.includes("does not exist"))
-                return end("no such location");
-            // Windscribe refused this app another WireGuard key for the account: says nothing about this network
-            else if (s.includes("WireGuard key limit") && now() - t > 3)
-                return end("key limit");
-            else if (s === "Disconnected" && now() - t > 3)
-                return end("failed");
-            onStep(`connecting ${r.location}`.trim());
-            await sleep(1000);
+            r.connectS = now() - t;
+            break;
         }
-        // a port the app doesn't offer for the protocol: it connects on the protocol's default instead, so this port wasn't tried
-        const port = protocol.split(":")[1], shown = (await windscribe("status")).match(/^Protocol: .*:(\d+)\s*$/m)?.[1];
-        if (port && shown && shown !== port)
-            return end("no such port");
-        await measure(async () => {
-            onStep(`measuring latency · ${r.location}`);
-            r.latencyMs = await latencyMs();
-            if (r.latencyMs !== null && speedTest) {
-                onStep(`measuring speed · ${r.location}`);
-                r.speedMbps = await speedMbps();
-            }
-        });
-        return end(r.latencyMs === null ? "no internet" : "ok");
+        else if (s.includes("does not exist"))
+            return end("no such location");
+        // Windscribe refused this app another WireGuard key for the account: says nothing about this network
+        else if (s.includes("WireGuard key limit") && now() - t > 3)
+            return end("key limit");
+        else if (s === "Disconnected" && now() - t > 3)
+            return end("failed");
+        onStep(`connecting ${r.location}`.trim());
+        await sleep(1000);
     }
-    finally {
-        onStep("disconnecting");
-        await windscribe("disconnect");
-        // the CLI's disconnect can return while the app is still tearing down (it does after a timed-out connect);
-        // a connect sent then is swallowed and the next attempt reads as an instant "failed", so wait it out
-        for (let i = 0; i < 30 && (await connectState()) === "Disconnecting"; i++)
-            await sleep(1000);
+    // a port the app doesn't offer for the protocol: it connects on the protocol's default instead, so this port wasn't tried
+    const port = protocol.split(":")[1], shown = (await windscribe("status")).match(/^Protocol: .*:(\d+)\s*$/m)?.[1];
+    if (port && shown && shown !== port)
+        return end("no such port");
+    let measured = false, holds = true;
+    await measure(async () => {
+        // a stopping scan waits for no more measurements: a parallel scan's containers measure one at a time, so they'd queue up
+        if (stopped())
+            return;
+        measured = true;
+        onStep(`measuring latency · ${r.location}`);
+        r.latencyMs = await latencyMs();
+        if (r.latencyMs === null)
+            return;
+        if (speedTest || steady) {
+            onStep(`measuring speed · ${r.location}`);
+            r.speedMbps = await speedMbps();
+        }
+        if (steady)
+            holds = await holdsUp(r.location, onStep);
+    });
+    if (!measured)
+        return end("interrupted");
+    return end(r.latencyMs === null ? "no internet" : holds ? "ok" : "unreliable");
+}
+/** Whether the connection stays up with internet through it: STEADY_CHECKS round trips, STEADY_GAP seconds apart, each with a retry */
+async function holdsUp(location, onStep) {
+    for (let i = 1; i <= STEADY_CHECKS; i++) {
+        onStep(`checking it holds up ${i}/${STEADY_CHECKS} · ${location}`);
+        await sleep(STEADY_GAP * 1000);
+        if (!(await connectState()).startsWith("Connected") || (await latencyMs(2)) === null)
+            return false;
     }
+    return true;
 }
 /** The attempts that worked, best first: fastest, then lowest latency */
 export const sortOk = (results) => results.filter((r) => r.status === "ok")

package/dist/scan.js

@@ -1,10 +1,28 @@
-// A scan: every country × protocol pair, tried in order, with pause and stop.
+// A scan: the attempts its scanning type plans (plan()), tried in order, with pause and stop.
 // Each slot runs one attempt at a time: one slot here, or one per docker container in a parallel scan.
-import { probe } from "./probe.js";
+import { probe, reliable } from "./probe.js";
 import { now } from "./time.js";
 // ponytail: rough per-attempt cost: a failure burns the timeout, a success ~connect+speed test; refine from real runs
 export const attemptSeconds = (timeout) => timeout + 5;
 export const estimate = (attempts, timeout, slots = 1) => Math.ceil(attempts / slots) * attemptSeconds(timeout);
+export const ORDERS = ["default", "random", "last-first", "last-only"];
+const base = (protocol) => protocol.split(":")[0]; // "tcp:443" → "tcp"
+/** What a scan of these countries and protocols tries, in the order of the scanning type, each once. saved: the last result's
+ * connections, best first. ports: each protocol's ports, its default first, so "tcp" and "tcp:443" are one attempt */
+export function plan(order, countries, protocols, saved = [], ports = new Map()) {
+    const seen = new Set();
+    const once = ({ country, protocol }) => {
+        const [p, port] = protocol.split(":"), key = `${country} ${p}:${port ?? ports.get(p)?.[0] ?? ""}`;
+        return !seen.has(key) && !!seen.add(key);
+    };
+    const last = saved.map((r) => ({ country: r.query, protocol: r.protocol, saved: true }));
+    if (order === "last-only")
+        return last.filter(once);
+    const bases = new Set(protocols.map(base));
+    const first = order === "last-first" ? last.filter((a) => countries.includes(a.country) && bases.has(base(a.protocol))) : [];
+    const list = order === "random" ? countries.map((c) => [Math.random(), c]).sort(([x], [y]) => x - y).map(([, c]) => c) : countries;
+    return [...first, ...list.flatMap((country) => protocols.map((protocol) => ({ country, protocol })))].filter(once);
+}
 /** Progress views read the fields; their keys call togglePause() and stop() */
 export class Scan {
     countries;
@@ -20,6 +38,7 @@ export class Scan {
     started = now();
     done = 0;
     stopping = false; // stop after the current attempts
+    found = false; // stopAtFirst: a connection held up, so the scan is stopping
     // a pause lands between attempts, so the VPN is disconnected while waiting
     paused = false;
     waiting = false; // paused, and no attempt running
@@ -33,7 +52,7 @@ export class Scan {
         this.options = options;
         this.probers = probers;
         this.after = after;
-        this.total = countries.length * protocols.length;
+        this.total = this.attempts().length;
         this.slots = probers.map(() => ({ current: null, step: "", attemptStart: now() }));
         if (after)
             this.slots.push({ current: null, step: "", attemptStart: now(), name: after.name });
@@ -59,9 +78,15 @@ export class Scan {
         this.waiting = false;
         this.resume();
     }
+    attempts() {
+        return this.options.only?.map((a) => ({ ...a }))
+            ?? this.countries.flatMap((country) => this.protocols.map((protocol) => ({ country, protocol })));
+    }
     async run(hooks = {}) {
-        const queue = this.countries.flatMap((country) => this.protocols.map((protocol) => ({ country, protocol })));
-        const left = new Map(this.countries.map((c) => [c, this.protocols.length])); // attempts to go, per country
+        const queue = this.attempts();
+        const left = new Map(); // attempts to go, per country
+        for (const { country } of queue)
+            left.set(country, (left.get(country) ?? 0) + 1);
         const later = this.after?.protocols ?? new Set();
         await Promise.all(this.probers.map((prober, i) => this.work(prober, this.slots[i], (p) => !later.has(p), queue, left, hooks)));
         // then the rest, also what slots whose container stopped left over
@@ -71,7 +96,7 @@ export class Scan {
     }
     /** One slot: takes the attempts it can make from the queue, one at a time, until there are none */
     async work(prober, slot, can, queue, left, hooks) {
-        const { timeout, speedTest } = this.options;
+        const { timeout, speedTest, stopAtFirst = false } = this.options;
         for (;;) {
             while (this.paused && !this.stopping) {
                 if (!this.waiting && this.slots.every((s) => !s.current)) { // the last running attempt is over
@@ -89,7 +114,7 @@ export class Scan {
             hooks.attempt?.(country, protocol);
             let r;
             try {
-                r = await prober(country, protocol, { timeout, speedTest, stopped: () => this.stopping, onStep: (s) => (slot.step = s) });
+                r = await prober(country, protocol, { timeout, speedTest, steady: stopAtFirst, stopped: () => this.stopping, onStep: (s) => (slot.step = s) });
             }
             catch (e) { // this slot is done for (its container stopped): the others take over its attempt
                 queue.unshift(next);
@@ -109,6 +134,10 @@ export class Scan {
             if (!left.get(country))
                 this.finished.push(country);
             hooks.result?.(r);
+            if (stopAtFirst && reliable(r) && !this.stopping) {
+                this.found = true;
+                this.stop();
+            }
         }
     }
 }

package/dist/tui/docker.js

@@ -3,7 +3,7 @@ import { duration, now } from "../time.js";
 import { session } from "../windscribe.js";
 import { draw, enterScreen, input, leaveScreen, out } from "./terminal.js";
 import { bold, cyan, dim, vw, yellow } from "./text.js";
-import { box, centerIn } from "./widgets.js";
+import { box, centerIn, spin } from "./widgets.js";
 const tty = () => Boolean(process.stdin.isTTY && out.isTTY);
 const clip = (s, n = 76) => (s.length > n ? s.slice(0, n - 1) + "…" : s);
 // lines of at most n columns, broken at spaces: an error can be longer than the screen is wide
@@ -75,7 +75,7 @@ async function busy(status, work) {
     }
     const t = now();
     let frame = 0;
-    const tick = () => paint({ lines: [`${cyan("⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"[frame++ % 10])} ${status.label} ${dim("· " + duration(now() - t))}`,
+    const tick = () => paint({ lines: [`${cyan(spin(frame++))} ${status.label} ${dim("· " + duration(now() - t))}`,
             dim(clip(status.line)), "", dim("esc quits")] });
     // the exit handlers remove containers already started
     const quit = (_, key = {}) => (key.name === "escape" || key.name === "q" || (key.ctrl && key.name === "c"))

package/dist/tui/picker.js

@@ -1,23 +1,39 @@
 import { loadDockerWireGuard, MIN_TIMEOUT, saveConfig, SPEED_TEST } from "../config.js";
 import { dockerState, loginSeconds, notInContainers, workerCount } from "../docker.js";
-import { attemptSeconds, estimate } from "../scan.js";
+import { STEADY_SECONDS } from "../probe.js";
+import { attemptSeconds, estimate, ORDERS, plan } from "../scan.js";
 import { duration } from "../time.js";
 import { canUpdate, checkUpdate, versionLines } from "../update.js";
-import { COUNTRIES, protocolPorts, PROTOCOLS } from "../windscribe.js";
+import { COUNTRIES, protocolPorts, PROTOCOLS, withPorts } from "../windscribe.js";
 import { countryName, flag } from "./country.js";
 import { setupDocker } from "./docker.js";
-import { draw, enterScreen, input, leaveScreen, out, repoLink } from "./terminal.js";
+import { draw, drawUntilNext, enterScreen, input, leaveScreen, out, repoLink } from "./terminal.js";
 import { bold, cyan, dim, green, under, vw, yellow } from "./text.js";
-import { box, centerIn, grid } from "./widgets.js";
+import { box, centerIn, grid, spin } from "./widgets.js";
+const ORDER_NAMES = {
+    default: "default",
+    random: "by random country",
+    "last-first": "by last success result first",
+    "last-only": "only the last results",
+};
+const needsLast = (o) => o === "last-first" || o === "last-only";
+// only the last results: the countries, protocols and ports are greyed out, and their keys and clicks say why
+const SKIPPED = "skipped with only the last results: o changes the scanning type";
 const flip = (set, value) => (set.has(value) ? set.delete(value) : set.add(value));
+// "5m ago", "3h ago", "2 days ago"
+const ago = (ms) => {
+    const m = Math.max(0, Math.round((Date.now() - ms) / 60000)), h = Math.round(m / 60), d = Math.round(h / 24);
+    return m < 1 ? "just now" : m < 60 ? `${m}m ago` : h < 48 ? `${h}h ago` : `${d} days ago`;
+};
 /** Resolves to the choice (also saved for next time), null when the user quits, or "update" for u */
-export function pick(saved, { timeout, speedTest, firewall, random, allPorts, docker }) {
+export function pick(saved, { timeout, speedTest, firewall, order, stopAtFirst, allPorts, docker, last }) {
     const selected = new Set(saved?.countries ?? []);
     const protos = new Set(saved?.protocols.length ? saved.protocols : PROTOCOLS);
     let cursor = 0, top = 0, message = "", query = "", searching = false;
     let seconds = String(timeout), editing = false; // the timeout, as typed
     let dockerAt = null, inDialog = false; // docker's state once checked; a docker dialog has the screen
     let portLists = null; // each protocol's ports, once the app said
+    let starting = -1; // once start is pressed: the start button's spinner frame, until the next screen shows
     let hit;
     const visible = () => {
         const q = query.toLowerCase();
@@ -25,7 +41,11 @@ export function pick(saved, { timeout, speedTest, firewall, random, allPorts, do
     };
     const ports = (p) => (allPorts && portLists?.get(p)?.length) || 1; // attempts per country for the protocol
     const perCountry = (ps) => [...ps].reduce((n, p) => n + ports(p), 0);
-    const attempts = () => selected.size * perCountry(protos);
+    // what start scans, in its order: as the CLI plans it, so the estimate counts the same attempts
+    const todo = () => {
+        const ps = PROTOCOLS.filter((p) => protos.has(p));
+        return plan(order, COUNTRIES.filter((c) => selected.has(c)), allPorts && portLists ? withPorts(ps, portLists) : ps, last?.results, portLists ?? undefined);
+    };
     const wireguard = loadDockerWireGuard(); // in docker containers, as the last parallel scan found
     enterScreen();
     return new Promise((resolve) => {
@@ -35,88 +55,112 @@ export function pick(saved, { timeout, speedTest, firewall, random, allPorts, do
             const rows = out.rows || 24;
             const version = versionLines(true);
             const matches = visible();
-            const height = Math.max(3, rows - 23 - version.length);
+            const height = Math.max(3, rows - 24 - version.length);
             cursor = Math.max(0, Math.min(cursor, matches.length - 1));
             if (cursor < top)
                 top = cursor;
             if (cursor >= top + height)
                 top = cursor - height + 1;
             top = Math.max(0, Math.min(top, matches.length - height));
-            const protoLine = PROTOCOLS.map((p, i) => `${dim(under(String(i + 1)))} ${protos.has(p) ? green("● " + p) : dim("○ " + p)}`).join("   ");
+            const off = order === "last-only"; // only the saved connections: the countries, protocols and ports are skipped
+            const missing = needsLast(order) && !last; // a type by the last result, and no saved scan: start is off
+            timeout = Number(seconds);
+            const list = todo(), n = list.length;
+            const base = (p) => p.split(":")[0]; // "wireguard:443" → "wireguard"
+            const scanned = new Set(list.map((a) => base(a.protocol)));
+            const here = PROTOCOLS.filter((p) => docker && scanned.has(p) && notInContainers(PROTOCOLS, wireguard).has(p)); // after the containers
+            const inContainers = list.filter((a) => !here.includes(base(a.protocol))).length;
+            const parallel = docker && dockerAt === "ready" && inContainers > 0;
+            const slots = parallel ? workerCount(inContainers) : 1;
+            const login = parallel ? loginSeconds(slots) : 0; // the containers log in before the scan starts
+            const protoLine = PROTOCOLS.map((p, i) => `${dim(under(String(i + 1)))} ${protos.has(p) ? (off ? dim : green)("● " + p) : dim("○ " + p)}`).join("   ");
             const listed = portLists && [...portLists.values()].some((l) => l.length), each = perCountry(protos);
-            const portsLine = `${dim(under("p"))} ${allPorts ? green("● all ports") : dim("○ all ports")}  ${dim(!allPorts
-                ? "off: each protocol on its default port"
-                : !portLists ? "checking the ports…"
-                    : !listed ? "this Windscribe app can't list its ports: 2.22 and newer can"
-                        : `every port of each protocol: ${each} attempt${each === 1 ? "" : "s"} per country${each > protos.size ? `, not ${protos.size}` : ""}`)}`;
+            const portsLine = `${dim(under("p"))} ${allPorts ? (off ? dim : green)("● all ports") : dim("○ all ports")}  ${dim(off
+                ? "not used: each saved connection on its own protocol and port"
+                : !allPorts
+                    ? "off: each protocol on its default port"
+                    : !portLists ? "checking the ports…"
+                        : !listed ? "this Windscribe app can't list its ports: 2.22 and newer can"
+                            : `every port of each protocol: ${each} attempt${each === 1 ? "" : "s"} per country${each > protos.size ? `, not ${protos.size}` : ""}`)}`;
             const speedLine = `${dim(under("s"))} ${speedTest ? green("● speed test") : dim("○ speed test")}  ${dim(speedTest
                 ? "ranks by download speed · adds ~15s per working connection"
-                : "off: connect-only, ranks by latency")}`;
+                : stopAtFirst ? "off · stop at the first still runs it on each connection"
+                    : "off: connect-only, ranks by latency")}`;
             const fwLabel = "block internet while scanning (firewall)";
             const fwLine = `${dim(under("f"))} ${firewall ? green("● " + fwLabel) : dim("○ " + fwLabel)}  ${dim(docker
                 ? "not used with docker"
                 : firewall ? "only VPN traffic gets through" : "off: apps may leak in between")}`;
-            const randomLine = `${dim(under("r"))} ${random ? green("● random order") : dim("○ random order")}  ${dim(random
-                ? "scans the countries shuffled, a new order each run"
-                : "off: scans in list order")}`;
-            timeout = Number(seconds);
             const short = timeout < MIN_TIMEOUT;
             const timeoutLine = `${dim(under("t"))} timeout ${editing ? bold(seconds) + cyan("▏") : (short ? yellow : bold)(seconds || "?")} s  ${dim(`per connection · at least ${MIN_TIMEOUT}`)}`;
-            const n = attempts();
-            const here = PROTOCOLS.filter((p) => docker && protos.has(p) && notInContainers(PROTOCOLS, wireguard).has(p)); // after the containers
-            const inContainers = selected.size * perCountry([...protos].filter((p) => !here.includes(p)));
-            const parallel = docker && dockerAt === "ready" && inContainers > 0;
-            const slots = parallel ? workerCount(inContainers) : 1;
-            const login = parallel ? loginSeconds(slots) : 0; // the containers log in before the scan starts
             const dockerLabel = "parallel scan in docker containers";
             const dockerLine = `${dim(under("d"))} ${docker ? green("● " + dockerLabel) : dim("○ " + dockerLabel)}  ${dim(!docker
                 ? "off: one attempt at a time"
                 : dockerAt === "ready" ? `${slots} at a time${here.length ? ` · ${here.join(" and ")} here, after them` : ""}`
                     : dockerAt ? "docker isn't ready: start sets it up" : "checking docker…")}`;
-            const search = searching
-                ? `${cyan("🔍")} ${bold(query)}${cyan("▏")}`
-                : query ? `🔍 ${query}` : dim("🔍 press / to search");
+            const saves = last ? plan("last-only", [], [], last.results, portLists ?? undefined).length : 0; // the saved connections, each once
+            const firsts = list.filter((a) => a.saved).length; // those this scan tries first
+            const orderLine = `${dim(under("o"))} scanning type ${bold(ORDER_NAMES[order])}  ${dim(missing
+                ? "no saved scan yet"
+                : order === "default" ? "countries in list order"
+                    : order === "random" ? "countries shuffled, a new order each run"
+                        : order === "last-first" ? `${firsts} of ${saves} saved selected · ${ago(last.at)}`
+                            : `${saves} saved working connection${saves === 1 ? "" : "s"} · ${ago(last.at)}`)}`;
+            const stopLabel = "stop at the first working connection";
+            // the best saved connection goes first (unless it waits for the containers): when it still holds up, the scan ends there
+            const lead = list[0]?.saved && !here.includes(base(list[0].protocol)) ? list[0] : null;
+            const stopLine = `${dim(under("w"))} ${stopAtFirst ? green("● " + stopLabel) : dim("○ " + stopLabel)}  ${dim(!stopAtFirst
+                ? "off: tries every attempt"
+                : lead ? `≈ ${duration(login + STEADY_SECONDS)} if ${lead.country} ${lead.protocol} still holds up`
+                    : "after a speed and stability check")}`;
+            const search = off
+                ? yellow("countries skipped: only the last results are scanned")
+                : searching ? `${cyan("🔍")} ${bold(query)}${cyan("▏")}`
+                    : query ? `🔍 ${query}` : dim("🔍 press / to search");
             const shown = matches.slice(top, top + height);
             const range = matches.length > height ? `${top + 1}–${top + shown.length} of ${matches.length}` : `${matches.length} countries`;
             const body = shown.map((code, j) => {
-                const here = top + j === cursor;
-                const mark = selected.has(code) ? green("●") : dim("○");
+                const current = !off && top + j === cursor;
+                const mark = selected.has(code) ? (off ? dim : green)("●") : dim("○");
                 const name = `${flag(code)} ${countryName(code)}`;
-                return [`${here ? cyan("❯") : " "} ${mark}`, here ? bold(code) : dim(code), here ? bold(cyan(name)) : name];
+                return [`${current ? cyan("❯") : " "} ${mark}`, current ? bold(code) : dim(code), current ? bold(cyan(name)) : off ? dim(name) : name];
             });
             if (!body.length)
                 body.push(["   ", "", dim("no country matches")]);
             const buttons = [
-                ["start", "▶ Start"],
+                ["start", starting < 0 ? "▶ Start" : `${spin(starting++)} Starting…`],
                 ["all", under("A") + (query ? "ll shown" : "ll")],
                 ["none", under("N") + (query ? "one shown" : "one")],
                 ["quit", under("Q") + "uit"],
             ];
-            const buttonLine = buttons.map(([id, label]) => (id === "start" ? bold(cyan(`[ ${label} ]`)) : dim(`[ ${label} ]`))).join("  ");
-            const settings = [protoLine, portsLine, ...(SPEED_TEST ? [speedLine] : []), fwLine, randomLine, timeoutLine, dockerLine];
+            const buttonLine = buttons.map(([id, label]) => (id === "start" && n && !missing ? bold(cyan(`[ ${label} ]`)) : dim(`[ ${label} ]`))).join("  ");
+            const settings = [protoLine, portsLine, ...(SPEED_TEST ? [speedLine] : []), fwLine, timeoutLine, dockerLine, orderLine, stopLine];
             const table = grid([{ title: "" }, { title: "Code" }, { title: "Country" }], body, { caption: search, captionRight: dim(range), minWidth: Math.max(...settings.map(vw)) + 4 });
             const width = vw(table[0]);
             const head = box(settings, {
                 title: bold(cyan("WindScout")),
-                right: `${bold(String(selected.size))}${dim(`/${COUNTRIES.length} selected`)}`,
+                right: `${(off ? dim : bold)(String(selected.size))}${dim(`/${COUNTRIES.length} selected`)}`,
                 width: width - 4,
             });
+            const total = login + estimate(inContainers, timeout, slots) + estimate(n - inContainers, timeout);
+            const costs = dim(`(~${attemptSeconds(timeout)}s each${slots > 1 ? `, ${slots} at a time` : ""}${login ? `, + ~${duration(login)} login` : ""})`);
             const lines = [
                 ...head,
                 ...table,
                 "",
                 centerIn(buttonLine, width),
                 "",
-                centerIn(n
-                    ? `${bold(String(n))} attempts · estimated ${bold("≈ " + duration(login + estimate(inContainers, timeout, slots) + estimate(n - inContainers, timeout)))} ${dim(`(~${attemptSeconds(timeout)}s each${slots > 1 ? `, ${slots} at a time` : ""}${login ? `, + ~${duration(login)} login` : ""})`)}`
-                    : yellow("select at least one country and one protocol"), width),
+                centerIn(missing
+                    ? yellow("no saved scan yet, so start is off: press o for another scanning type")
+                    : !n ? yellow(`select at least one country and one protocol${last ? ", or o for only the last results" : ""}`)
+                        : stopAtFirst // it can end at any attempt: this is when none holds up
+                            ? `up to ${bold(String(n))} attempts · at most ${bold("≈ " + duration(total))} ${costs}`
+                            : `${bold(String(n))} attempts · estimated ${bold("≈ " + duration(total))} ${costs}`, width),
                 centerIn(dim(editing
                     ? "type the seconds to wait for each connection · enter/esc done"
                     : searching
                         ? "type to filter · ↑↓ move · enter/esc done"
-                        // both lines fit 80 columns
                         : `↑↓ move · space select · a/n ${query ? "all/none shown · esc clear" : "all/none · / search"} · enter start · q quit`), width),
-                centerIn(dim(searching || editing ? "" : `1-${PROTOCOLS.length} protocols · p ports${SPEED_TEST ? " · s speed" : ""} · f firewall · r random · t timeout · d docker`), width),
+                centerIn(dim(searching || editing ? "" : `1-${PROTOCOLS.length} protocols · p ports${SPEED_TEST ? " · s speed" : ""} · f firewall · t timeout · d docker · o type · w first`), width),
             ];
             if (message)
                 lines.push(centerIn(yellow(message), width));
@@ -140,7 +184,7 @@ export function pick(saved, { timeout, speedTest, firewall, random, allPorts, do
             });
             hit = {
                 protoRow: row(protoLine), protoHits, portsRow: row(portsLine), speedRow: SPEED_TEST ? row(speedLine) : -1,
-                firewallRow: row(fwLine), randomRow: row(randomLine), timeoutRow: row(timeoutLine), dockerRow: row(dockerLine),
+                firewallRow: row(fwLine), timeoutRow: row(timeoutLine), dockerRow: row(dockerLine), orderRow: row(orderLine), stopRow: row(stopLine),
                 searchRow: at.top + head.length + 1,
                 firstRow: at.top + head.length + 5, shown: shown.length,
                 buttonRow: at.top + head.length + table.length + 1, buttonHits,
@@ -161,7 +205,9 @@ export function pick(saved, { timeout, speedTest, firewall, random, allPorts, do
             resolve(value);
         };
         const start = () => {
-            if (!attempts()) {
+            if (needsLast(order) && !last)
+                return false; // start is off: the warning under the table says why
+            if (!todo().length) {
                 message = "nothing to scan yet";
                 return false;
             }
@@ -175,15 +221,20 @@ export function pick(saved, { timeout, speedTest, firewall, random, allPorts, do
                 protocols: PROTOCOLS.filter((p) => protos.has(p)),
                 speed: speedTest,
                 firewall,
-                random,
+                order,
+                stopAtFirst,
                 allPorts,
                 timeout,
                 docker,
             };
             saveConfig(choice);
             finish(choice);
+            // the scan can take a moment to show (the firewall, docker): the button spins until its screen, or a docker one, draws
+            starting = 0;
+            drawUntilNext(render);
             return true;
         };
+        const cycleOrder = () => (order = ORDERS[(ORDERS.indexOf(order) + 1) % ORDERS.length]); // o: the next scanning type
         // turning it on gets docker going first: installs or starts it (after asking), unless it answers already
         const toggleDocker = async () => {
             if (!docker && (dockerAt = await dockerState()) !== "ready") {
@@ -205,14 +256,20 @@ export function pick(saved, { timeout, speedTest, firewall, random, allPorts, do
             if (!m.press)
                 return;
             message = "";
-            const matches = visible();
+            const matches = visible(), off = order === "last-only";
             const { x, y } = m;
+            const button = y === hit.buttonRow ? hit.buttonHits.find(([, a, b]) => x >= a && x < b)?.[0] : undefined;
+            const onCountries = y === hit.searchRow || (y >= hit.firstRow && y < hit.firstRow + hit.shown) || button === "all" || button === "none";
+            if (off && (m.button === 64 || m.button === 65))
+                return; // the skipped countries don't scroll
             if (m.button === 64)
                 cursor = Math.max(0, cursor - 3); // wheel up
             else if (m.button === 65)
                 cursor = Math.min(matches.length - 1, cursor + 3); // wheel down
             else if (m.button !== 0)
                 return; // left button only
+            else if (off && (onCountries || y === hit.protoRow || y === hit.portsRow))
+                message = SKIPPED;
             else if (y === hit.searchRow)
                 searching = true, editing = false;
             else if (y === hit.timeoutRow)
@@ -236,19 +293,20 @@ export function pick(saved, { timeout, speedTest, firewall, random, allPorts, do
                     speedTest = !speedTest;
                 else if (y === hit.firewallRow)
                     firewall = !firewall;
-                else if (y === hit.randomRow)
-                    random = !random;
                 else if (y === hit.dockerRow)
                     return void toggleDocker();
+                else if (y === hit.orderRow)
+                    cycleOrder();
+                else if (y === hit.stopRow)
+                    stopAtFirst = !stopAtFirst;
                 else if (y === hit.buttonRow) {
-                    const id = hit.buttonHits.find(([, a, b]) => x >= a && x < b)?.[0];
-                    if (id === "start" && start())
+                    if (button === "start" && start())
                         return;
-                    if (id === "quit")
+                    if (button === "quit")
                         return finish(null);
-                    if (id === "all")
+                    if (button === "all")
                         matches.forEach((c) => selected.add(c));
-                    if (id === "none")
+                    if (button === "none")
                         matches.forEach((c) => selected.delete(c));
                 }
             }
@@ -267,9 +325,14 @@ export function pick(saved, { timeout, speedTest, firewall, random, allPorts, do
                 flip(selected, c);
                 cursor = Math.min(matches.length - 1, cursor + 1);
             };
+            // only the last results: the keys for the countries, protocols and ports change nothing
+            const skipped = order === "last-only" && !editing && !searching
+                && (["up", "down", "pageup", "pagedown", "home", "end", "j", "k", "space", "a", "n", "p"].includes(k ?? "") || str === "/" || /^[1-9]$/.test(str ?? ""));
             if (key.ctrl && k === "c")
                 return finish(null);
-            if (k === "up")
+            if (skipped)
+                message = SKIPPED;
+            else if (k === "up")
                 cursor = Math.max(0, cursor - 1);
             else if (k === "down")
                 cursor = Math.min(matches.length - 1, cursor + 1);
@@ -318,12 +381,14 @@ export function pick(saved, { timeout, speedTest, firewall, random, allPorts, do
                 speedTest = !speedTest;
             else if (k === "f")
                 firewall = !firewall;
-            else if (k === "r")
-                random = !random;
             else if (k === "t")
                 editing = true, seconds = "";
             else if (k === "d")
                 return void toggleDocker();
+            else if (k === "o")
+                cycleOrder();
+            else if (k === "w")
+                stopAtFirst = !stopAtFirst;
             else if (k === "u" && canUpdate())
                 return finish("update");
             else if (/^[1-9]$/.test(str ?? "") && PROTOCOLS[Number(str) - 1])

package/dist/tui/progress.js

@@ -7,11 +7,13 @@ import { countryName, flag } from "./country.js";
 import { matrix, resultTable } from "./tables.js";
 import { draw, enterScreen, input, leaveScreen, out, repoLink } from "./terminal.js";
 import { bold, cyan, dim, green, red, vw, yellow } from "./text.js";
-import { bar, box, centerIn } from "./widgets.js";
+import { bar, box, centerIn, spin } from "./widgets.js";
 /** Progress bar, current attempt, results so far. tab switches the table, p pauses, q stops (twice: quits).
  * blocking: we turned the firewall on for the scan */
 export function showProgress(scan, blocking) {
-    const { protocols, options: { timeout, speedTest } } = scan;
+    const { protocols, options: { timeout } } = scan;
+    const speedTest = scan.options.speedTest || Boolean(scan.options.stopAtFirst); // stop at the first measures speed too
+    let quitting = false; // q pressed: a second one quits right away
     let view = speedTest ? "ranking" : "availability"; // tab switches
     let frame = 0;
     const render = () => {
@@ -22,7 +24,7 @@ export function showProgress(scan, blocking) {
         const partial = slots.reduce((sum, s) => sum + (s.current ? Math.min(0.95, (now() - s.attemptStart) / attemptSeconds(timeout)) : 0), 0);
         const fraction = (done + (done < total ? partial : 0)) / total;
         const eta = (total - done) * (done ? elapsed / done : attemptSeconds(timeout) / slots.length);
-        const spinner = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"[frame++ % 10];
+        const spinner = spin(frame++);
         const ok = sortOk(results);
         // blocked: nothing worked, and something was really tried (a key limit or a port the app doesn't offer tries nothing)
         const failed = finished.filter((c) => !results.some((r) => r.query === c && r.status === "ok")
@@ -51,9 +53,10 @@ export function showProgress(scan, blocking) {
                 : [];
         const width = Math.max(minW, table.length ? vw(table[0]) : 0);
         const inner = width - 4;
-        const status = stopping ? yellow(` stopping after the current attempt${many ? "s" : ""}…`)
-            : waiting ? yellow(` paused · VPN disconnected${blocking ? " · firewall blocking internet" : ""} · press p to resume`)
-                : "";
+        const status = scan.found ? green(" ✓ a connection held up · stopping the other attempts…")
+            : stopping ? yellow(` stopping after the current attempt${many ? "s" : ""}…`)
+                : waiting ? yellow(` paused · VPN disconnected${blocking ? " · firewall blocking internet" : ""} · press p to resume`)
+                    : "";
         const pausing = paused && !waiting && frame % 8 < 5;
         const slotLine = (s) => {
             if (!s.current)
@@ -102,12 +105,13 @@ export function showProgress(scan, blocking) {
             render();
         }
         else if (key.name === "q" || key.name === "escape" || (key.ctrl && key.name === "c")) {
-            if (scan.stopping) { // second press: bail out now
+            if (quitting) { // second press: bail out now
                 leaveScreen();
                 console.error(`stopped. the VPN may still be connecting: run '${CLI} disconnect'`);
                 await restoreFirewall();
                 process.exit(130);
             }
+            quitting = true;
             scan.stop();
             render();
         }
@@ -126,11 +130,13 @@ const clip = (s, n) => (s.length > n ? s.slice(0, Math.max(0, n - 1)) + "…" :
 /** A line per attempt. Ctrl-C stops after the current attempt, a second one quits */
 export function logProgress(scan) {
     const many = scan.slots.length > 1; // attempts overlap: a whole line once each is done
+    let quitting = false; // Ctrl-C pressed: a second one quits right away
     process.on("SIGINT", async () => {
-        if (scan.stopping) {
+        if (quitting) {
             await restoreFirewall();
             process.exit(130);
         }
+        quitting = true;
         scan.stop();
     });
     return {

package/dist/tui/tables.js

@@ -14,7 +14,7 @@ const resultRow = (r, i) => [
     r.connectS === null ? "-" : `${fmt(r.connectS, 1)} s`,
     r.latencyMs === null ? "-" : `${fmt(r.latencyMs, 0)} ms`,
     r.speedMbps === null ? "-" : bold(`${fmt(r.speedMbps, 1)} Mbps`),
-    r.status === "ok" ? green("✓ ok") : r.status === "key limit" || r.status === "no such port" ? yellow(r.status) : red(r.status),
+    r.status === "ok" ? green("✓ ok") : ["key limit", "no such port", "unreliable"].includes(r.status) ? yellow(r.status) : red(r.status),
 ];
 /** Numbered attempts, in the given order; the Speed column only when the speed test ran */
 export function resultTable(results, speedTest, options) {

package/dist/tui/terminal.js

@@ -13,6 +13,8 @@ export const input = new PassThrough();
 emitKeypressEvents(input);
 let fullscreen = false;
 let link = null; // where draw() last put the repo link
+let waiting; // drawUntilNext()'s timer
+let redrawing = false; // drawUntilNext()'s own redraw is drawing
 const openUrl = (url) => spawn({ darwin: "open", win32: "explorer" }[process.platform] ?? "xdg-open", [url], { stdio: "ignore", detached: true })
     .on("error", () => { }).unref();
 // SGR mouse report: ESC [ < button ; col ; row (M = press, m = release)
@@ -40,6 +42,7 @@ export function enterScreen() {
 }
 /** Back to the normal screen; drops every key and mouse listener */
 export function leaveScreen() {
+    clearInterval(waiting);
     if (!fullscreen)
         return;
     fullscreen = false;
@@ -51,8 +54,26 @@ export function leaveScreen() {
     out.write("\x1b[?1000l\x1b[?1006l\x1b[?25h\x1b[?1049l");
 }
 process.on("exit", leaveScreen);
+/** Calls redraw every 120 ms (for a spinner) while the screen waits for the next one: until another screen draws, or leaveScreen() */
+export function drawUntilNext(redraw) {
+    const tick = () => {
+        redrawing = true;
+        try {
+            redraw();
+        }
+        finally {
+            redrawing = false;
+        }
+    };
+    clearInterval(waiting);
+    waiting = setInterval(tick, 120);
+    waiting.unref(); // never what keeps the process alive
+    tick();
+}
 /** Redraws in place, centered: home, each line cleared to its end, then clear below (no flicker). Returns the top-left corner */
 export function draw(lines) {
+    if (!redrawing)
+        clearInterval(waiting); // another screen: it takes over from drawUntilNext()
     const cols = out.columns || 80, rows = out.rows || 24;
     const w = Math.max(...lines.map(vw));
     const left = " ".repeat(Math.max(0, Math.floor((cols - w) / 2)));

package/dist/tui/widgets.js

@@ -32,6 +32,8 @@ export function grid(cols, rows, { caption, captionRight = "", minWidth = 0, str
     out.push(row(cols.map((c) => bold(c.title))), rule("├", "┼", "┤"), ...rows.map(row), rule("╰", "┴", "╯"));
     return out;
 }
+/** A spinner's character for this frame */
+export const spin = (frame) => "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"[frame % 10];
 /** s, indented to sit centered in width columns */
 export const centerIn = (s, width) => " ".repeat(Math.max(0, Math.floor((width - vw(s)) / 2))) + s;
 /** Gradient bar (cyan → green) with eighth-block precision on the leading edge */

package/dist/worker.js

@@ -55,9 +55,9 @@ export async function worker() {
         if (!m.probe)
             continue;
         stop = false;
-        const { query, protocol, timeout, speedTest } = m.probe;
+        const { query, protocol, timeout, speedTest, steady } = m.probe;
         const result = await probe(query, protocol, {
-            timeout, speedTest,
+            timeout, speedTest, steady,
             stopped: () => stop,
             onStep: (step) => send({ step }),
             measure: async (fn) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windscout",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Find which Windscribe locations and protocols work from your network, ranked by speed (unofficial)",
   "type": "module",
   "bin": {