clauderipple 0.9.5 → 0.11.0

package/dist/router/src/tether.js

@@ -0,0 +1,712 @@
+// Fail over to a phone's hotspot (iPhone or Android) when Wi-Fi has no internet, and come back to a known
+// Wi-Fi later. The probe/decision loop below is shared; the OS part is a TetherBackend — macOS here,
+// Windows in tether-win.ts (netsh, no elevation).
+//
+// What decides "no internet" is a real HTTP probe through the Wi-Fi interface, not the OS path
+// status: a router with a dead uplink or a captive portal reads "satisfied" to NWPathMonitor, which
+// is why Insomnia never failed over in that state (research §1.3, §3.3). Behaviour follows wifihop
+// (captive.apple.com "Success" + gstatic 204, 3 of the last 5 rounds) and WiFiGuard (switch back when
+// a better network returns); the code is our own.
+//
+//   failover  on Wi-Fi (or none), 3 of the last 5 probe rounds failed → `sudo -n networksetup
+//             -setairportnetwork <dev> <hotspot>`; macOS takes the password from the System keychain.
+//   return    on the hotspot, at 5, 10, 20, 30, 40, 50 and 60 min after landing and every 10 min
+//             after that, while no model call runs → disassociate (CoreWLAN through JXA, as the
+//             console user — the router is a launchd agent in the user's session) so macOS
+//             auto-joins the best known network in range; probe it; if that does not give working
+//             Wi-Fi within 20s, rejoin the hotspot and wait for the next point. The times are fixed
+//             from landing rather than a doubling backoff (owner's decision, 2026-10-20): at most
+//             ~10 min on the hotspot after arriving at a known Wi-Fi, and a brief drop every 10 min
+//             on the move, instead of a cap of 15 min.
+//   gap       a return still postponed RETURN_FORCE_AFTER_MS past due (calls back-to-back, so never
+//             a quiet moment — 2026-10-20) makes the gap itself: new model calls are held (hold.ts:
+//             they wait, they are not refused), the running ones get up to RETURN_DRAIN_WAIT_MS to
+//             finish, then the return above runs and the hold is released whatever the outcome.
+//
+// Never more than one switch per 60s; nothing switches while the user has pinned the network.
+// "On the hotspot" is read from the address, not the SSID (macOS redacts it without Location;
+// Windows 11 24H2 gates the query that returns it, see tether-win.ts): an iPhone hotspot hands out
+// 172.20.10.0/28, and any other phone's network is learned. An Android hotspot hands out a /24 that
+// is not fixed — 192.168.43.x up to Android 10 (IpServer WIFI_HOST_IFACE_ADDR), a random /24 of
+// 192.168.0.0/16 from Android 11, of 192.168.0.0/16, 172.16.0.0/12 or 10.0.0.0/8 by Android 14
+// (PrivateAddressCoordinator) — so after our own join of the hotspot SSID succeeds, the subnet the
+// Wi-Fi interface then has (os.networkInterfaces(): address + netmask, no process, no privilege) is
+// remembered as the hotspot's network and kept in <home>/tether.json.
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { SUDO, sudoRefused } from "./awake.js";
+import { HoldGate } from "./hold.js";
+import { HOTSPOT_NOT_VISIBLE_STEPS, WinTetherBackend } from "./tether-win.js";
+export const NETWORKSETUP = "/usr/sbin/networksetup";
+export const OSASCRIPT = "/usr/bin/osascript";
+/** wifihop's exact call (verified in its source, `mac_disassociate_js`): a zero-argument ObjC method is invoked by reading it. */
+export const DISASSOCIATE_JS = 'ObjC.import("CoreWLAN"); $.CWWiFiClient.sharedWiFiClient.interface.disassociate; "ok";';
+export const PROBE_URLS = {
+    apple: "http://captive.apple.com/hotspot-detect.html",
+    google: "http://connectivitycheck.gstatic.com/generate_204",
+};
+export const PROBE_TIMEOUT_MS = 4_000;
+export const MIN_SWITCH_INTERVAL_MS = 60_000;
+export const RETURN_PROBE_MS = 20_000;
+/**
+ * When to try the way back, counted from the moment the Mac landed on the hotspot: 5, 10, 20, 30,
+ * 40, 50 and 60 min, then every 10 min for as long as it stays there (owner's decision, 2026-10-20 —
+ * a fixed schedule rather than a doubling one: at most ~10 min on the hotspot after arriving at a
+ * known Wi-Fi, and only a brief drop every 10 min on the move).
+ */
+export const RETURN_SCHEDULE_MINUTES = [5, 10, 20, 30, 40, 50, 60];
+/** After the last scheduled point, every this long. */
+export const RETURN_INTERVAL_AFTER_MS = 10 * 60_000;
+/** A model call this recent counts as "Claude is working": no return attempt (it drops the link for seconds). */
+export const RETURN_QUIET_MS = 20_000;
+/** Failover waits at most this long for an in-flight call; a dead network cannot serve it anyway. */
+export const FAILOVER_IDLE_WAIT_MS = 30_000;
+/** A return postponed this long past due stops waiting for a quiet moment and makes one. */
+export const RETURN_FORCE_AFTER_MS = 2 * 60_000;
+/**
+ * With new calls held, the running ones get this long to finish before the attempt is given up.
+ * With the switch after it (up to ~35s) it stays inside a held call's HOLD_MAX_MS, so no held call
+ * goes ahead and refills the gap before the switch; and well under the ~180s after which Claude
+ * Code gave up on a call that had no answer yet (13 Google turns closed at 182–190s, 2026-10-20).
+ */
+export const RETURN_DRAIN_WAIT_MS = 60_000;
+/** The hold releases itself after this even if the return never comes back to release it. */
+export const RETURN_HOLD_FAILSAFE_MS = RETURN_DRAIN_WAIT_MS + 3 * 60_000;
+const JOIN_SETTLE_MS = 15_000;
+/** States that say why the last join failed; they stay (with their hint) until the next attempt. */
+const JOIN_FAILURES = new Set(["hotspot-not-visible", "join-failed", "needs-setup", "no-hotspot-profile", "needs-location"]);
+// ---- Pure helpers -------------------------------------------------------------------------------
+/** The Wi-Fi device from `networksetup -listallhardwareports` ("Hardware Port: Wi-Fi\nDevice: en0"). */
+export function parseWifiDevice(text) {
+    const blocks = text.split(/\n\s*\n/);
+    for (const b of blocks) {
+        if (!/Hardware Port:\s*(Wi-Fi|AirPort)\s*$/m.test(b))
+            continue;
+        const dev = /Device:\s*(\S+)/.exec(b)?.[1];
+        if (dev && /^en\d+$/.test(dev))
+            return dev;
+    }
+    return null;
+}
+/** The interface's IPv4 address, or null when it has none (not associated, or no DHCP yet). */
+export function wifiIPv4(ifaces, device) {
+    return ifaces[device]?.find((a) => a.family === "IPv4" && !a.internal)?.address ?? null;
+}
+/** An iPhone Personal Hotspot hands out 172.20.10.0/28 (172.20.10.0–15). */
+export function isHotspotAddress(ip) {
+    const m = ip ? /^172\.20\.10\.(\d{1,3})$/.exec(ip) : null;
+    return !!m && Number(m[1]) <= 15;
+}
+function ipv4ToInt(ip) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ip);
+    if (!m)
+        return null;
+    const parts = m.slice(1).map(Number);
+    if (parts.some((p) => p > 255))
+        return null;
+    return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
+}
+function intToIpv4(n) {
+    return [n >>> 24, (n >>> 16) & 255, (n >>> 8) & 255, n & 255].join(".");
+}
+/** "192.168.43.17" + "255.255.255.0" → "192.168.43.0/24"; null for anything else (no or a non-contiguous mask). */
+export function ipv4Network(address, netmask) {
+    const a = ipv4ToInt(address);
+    const m = ipv4ToInt(netmask);
+    if (a === null || m === null)
+        return null;
+    const bits = m.toString(2).replace(/0+$/, "");
+    if (m !== 0 && bits.includes("0"))
+        return null;
+    const len = m === 0 ? 0 : bits.length;
+    if (len < 8 || len > 30)
+        return null; // a /31 or /32 is no DHCP network; shorter than /8 is no hotspot
+    return `${intToIpv4((a & m) >>> 0)}/${len}`;
+}
+/** Whether `ip` is inside `network` ("a.b.c.d/len"). */
+export function inNetwork(ip, network) {
+    if (!ip || !network)
+        return false;
+    const [base, lenText] = network.split("/");
+    const a = ipv4ToInt(ip);
+    const b = base ? ipv4ToInt(base) : null;
+    const len = Number(lenText);
+    if (a === null || b === null || !Number.isInteger(len) || len < 0 || len > 32)
+        return false;
+    const mask = len === 0 ? 0 : (0xffffffff << (32 - len)) >>> 0;
+    return ((a & mask) >>> 0) === ((b & mask) >>> 0);
+}
+/** 169.254.0.0/16: what an interface gives itself when DHCP did not answer — not a join. */
+export function isLinkLocal(ip) {
+    return inNetwork(ip, "169.254.0.0/16");
+}
+/** The iPhone range, or the network remembered from our own join of the hotspot (`learned`). */
+export function classifyNetwork(ip, learned = null) {
+    return ip === null ? "none" : isHotspotAddress(ip) || inNetwork(ip, learned) ? "hotspot" : "wifi";
+}
+/** The interface's IPv4 network ("a.b.c.d/len"), from the same os.networkInterfaces() entry as wifiIPv4. */
+export function wifiIPv4Network(ifaces, device) {
+    const a = ifaces[device]?.find((x) => x.family === "IPv4" && !x.internal);
+    return a ? ipv4Network(a.address, a.netmask) : null;
+}
+export function readLearnedHotspot(file) {
+    try {
+        const j = JSON.parse(fs.readFileSync(file, "utf8"));
+        const h = j.hotspot;
+        if (!h || typeof h.ssid !== "string" || typeof h.network !== "string")
+            return null;
+        const [base, len] = h.network.split("/");
+        const bits = Number(len);
+        // Only a canonical "network/len" this module could have written; anything else is forgotten.
+        if (!base || !Number.isInteger(bits) || bits < 8 || bits > 30)
+            return null;
+        if (ipv4Network(base, intToIpv4((0xffffffff << (32 - bits)) >>> 0)) !== h.network)
+            return null;
+        return { ssid: h.ssid, network: h.network, learnedAt: String(h.learnedAt ?? "") };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeLearnedHotspot(file, h) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify({ hotspot: h }) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+/**
+ * The next scheduled return time at or after `now + minGapMs`, on the fixed schedule counted from
+ * `landedAt` (5, 10, 20, 30, 40, 50, 60 min, then every 10). A point already passed is skipped, so a
+ * long gap attempt or a slow tick never retries in the past or bursts two switches together.
+ */
+export function nextReturnPoint(landedAt, now, minGapMs = MIN_SWITCH_INTERVAL_MS) {
+    const floor = now + minGapMs;
+    for (const minutes of RETURN_SCHEDULE_MINUTES) {
+        const at = landedAt + minutes * 60_000;
+        if (at >= floor)
+            return at;
+    }
+    const last = landedAt + RETURN_SCHEDULE_MINUTES[RETURN_SCHEDULE_MINUTES.length - 1] * 60_000;
+    const steps = Math.max(1, Math.ceil((floor - last) / RETURN_INTERVAL_AFTER_MS));
+    return last + steps * RETURN_INTERVAL_AFTER_MS;
+}
+/** The last five probe rounds; an outage is 3 failures among them, so a 1s blip never switches. */
+export class ProbeWindow {
+    rounds = [];
+    push(ok) {
+        this.rounds.push(ok);
+        if (this.rounds.length > 5)
+            this.rounds.shift();
+    }
+    failures() {
+        return this.rounds.filter((ok) => !ok).length;
+    }
+    outage() {
+        return this.failures() >= 3;
+    }
+    reset() {
+        this.rounds = [];
+    }
+}
+/** One HTTP GET bound to a local address (so the request leaves through that interface). */
+export const httpGet = (url, localAddress, timeoutMs) => new Promise((resolve, reject) => {
+    const req = http.get(url, { localAddress, timeout: timeoutMs, headers: { "cache-control": "no-cache" } }, (res) => {
+        let body = "";
+        res.setEncoding("utf8");
+        res.on("data", (c) => {
+            if (body.length < 4096)
+                body += c;
+        });
+        res.on("end", () => resolve({ status: res.statusCode ?? 0, body }));
+        res.on("error", reject);
+    });
+    req.on("timeout", () => req.destroy(new Error("probe timed out")));
+    req.on("error", reject);
+});
+/** One round: both endpoints at once; the round fails only if both fail. */
+export async function probeRound(localAddress, get = httpGet) {
+    const apple = get(PROBE_URLS.apple, localAddress, PROBE_TIMEOUT_MS).then((r) => r.status === 200 && r.body.includes("Success"), () => false);
+    const google = get(PROBE_URLS.google, localAddress, PROBE_TIMEOUT_MS).then((r) => r.status === 204, () => false);
+    const [a, g] = await Promise.all([apple, google]);
+    return a || g;
+}
+/**
+ * `networksetup -setairportnetwork` reports failure on stdout and may still exit 0
+ * ("Could not find network X." / "Failed to join network X."), so the text decides.
+ */
+export function classifyJoin(r) {
+    if (sudoRefused(r))
+        return "needs-setup";
+    const text = `${r.stdout}\n${r.stderr}`;
+    if (/could not find network/i.test(text))
+        return "hotspot-not-visible";
+    if (r.code !== 0 || /failed|error/i.test(text))
+        return "join-failed";
+    return null;
+}
+/** Waiting this long after leave() with no address at all, a backend may join a known network itself. */
+export const JOIN_KNOWN_AFTER_MS = 8_000;
+const MAC_HINTS = {
+    "hotspot-not-visible": `The phone is not broadcasting its hotspot, so the Mac cannot see it. ${HOTSPOT_NOT_VISIBLE_STEPS}`,
+    "needs-setup": "Run `clauderipple awake setup --ssid <hotspot name>` once: joining the hotspot needs the rule it installs (and the name must match it).",
+    "no-hotspot-ssid": "Set the phone hotspot's name: `clauderipple awake setup --ssid <hotspot name>`.",
+    "no-wifi": "Wi-Fi is not connected. macOS joins an iPhone hotspot by itself when no Wi-Fi is available if System Settings → Wi-Fi → \"Ask to join hotspots\" is Automatic (ClaudeRipple cannot read that setting: the file is root-only); an Android hotspot is joined like any known Wi-Fi with Auto-Join on.",
+    "join-failed": "Joining the hotspot failed. Check the hotspot name, and that the Mac has joined it once before (macOS keeps its password).",
+    pinned: "Switching is paused because the network was pinned.",
+};
+class MacTetherBackend {
+    noAddressOutcome = "join-failed";
+    hints = MAC_HINTS;
+    run;
+    log;
+    device = null;
+    constructor(run, log) {
+        this.run = run;
+        this.log = log;
+    }
+    async findWifi() {
+        const r = await this.run(NETWORKSETUP, ["-listallhardwareports"]);
+        this.device = r.code === 0 ? parseWifiDevice(r.stdout) : null;
+        return this.device;
+    }
+    /** `sudo -n networksetup -setairportnetwork <dev> <ssid>`. */
+    async join(ssid) {
+        const r = await this.run(SUDO, ["-n", NETWORKSETUP, "-setairportnetwork", this.device, ssid], { timeoutMs: 30_000 });
+        const failed = classifyJoin(r);
+        if (failed && failed !== "needs-setup")
+            this.log.warn(`tether: networksetup said: ${(r.stdout + r.stderr).trim().slice(0, 200)}`);
+        return failed;
+    }
+    async leave() {
+        const r = await this.run(OSASCRIPT, ["-l", "JavaScript", "-e", DISASSOCIATE_JS], { timeoutMs: 15_000 });
+        return r.code === 0 ? null : (r.stderr || r.stdout).trim().slice(0, 200);
+    }
+}
+export class TetherController {
+    deps;
+    now;
+    sleep;
+    interfaces;
+    probe;
+    backend;
+    window = new ProbeWindow();
+    device = null;
+    network = "none";
+    state = "off";
+    pinned = false;
+    lastSwitchAt = 0;
+    lastSwitch = null;
+    lastProbe = null;
+    /** When the Mac landed on the hotspot (ours or by hand); null off the hotspot. The schedule counts from here. */
+    landedOnHotspotAt = null;
+    nextReturnAt = 0;
+    busy = null;
+    cancel = null;
+    lastLogged = "";
+    hold;
+    /** True while this controller has the gate engaged (stop() releases it). */
+    holding = false;
+    stopped = false;
+    /** The hotspot's network learned from our own join (outside the iPhone range); see learn(). */
+    learned;
+    /** The subnet last watched as ordinary Wi-Fi: a join landing on it cannot be told apart from it. */
+    lastWifiNetwork = null;
+    constructor(deps) {
+        this.deps = deps;
+        this.learned = deps.stateFile ? readLearnedHotspot(deps.stateFile) : null;
+        this.hold = deps.hold ?? new HoldGate();
+        this.now = deps.now ?? Date.now;
+        this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.interfaces = deps.interfaces ?? os.networkInterfaces;
+        this.probe = deps.probe ?? ((addr) => probeRound(addr));
+        this.backend =
+            deps.platform === "darwin" ? new MacTetherBackend(deps.run, deps.log) : deps.platform === "win32" ? new WinTetherBackend(deps.run, deps.log) : null;
+        if (!this.backend)
+            this.state = "unsupported";
+    }
+    get supported() {
+        return this.backend !== null;
+    }
+    start() {
+        if (!this.supported)
+            return;
+        this.stopped = false;
+        this.loop();
+    }
+    /** Stops the loop; a hold this controller engaged is released now (a return in progress gives up). */
+    stop() {
+        this.stopped = true;
+        this.cancel?.();
+        this.cancel = null;
+        if (this.holding)
+            this.releaseHold("the controller stopped");
+    }
+    /** Run a tick soon (after the settings changed) without waiting for it. */
+    kick() {
+        if (this.supported)
+            void this.tick();
+    }
+    setPin(on) {
+        if (this.pinned === on)
+            return;
+        this.pinned = on;
+        this.deps.log.info(`tether: network ${on ? "pinned; switching paused" : "unpinned; switching resumes"}`);
+        if (on)
+            this.state = "pinned";
+        this.window.reset();
+    }
+    status() {
+        const s = this.deps.settings();
+        return {
+            enabled: s.enabled,
+            network: this.network,
+            state: this.state,
+            pinned: this.pinned,
+            hotspotSsid: s.hotspotSsid,
+            lastSwitch: this.lastSwitch,
+            lastProbe: this.lastProbe,
+            hint: this.backend?.hints[this.state] ?? null,
+        };
+    }
+    loop() {
+        const schedule = this.deps.schedule ?? ((fn, ms) => {
+            const t = setTimeout(fn, ms);
+            t.unref();
+            return () => clearTimeout(t);
+        });
+        const every = Math.max(5, this.deps.settings().probeEverySec) * 1000;
+        this.cancel = schedule(() => {
+            void this.tick().finally(() => {
+                if (this.cancel)
+                    this.loop();
+            });
+        }, every);
+    }
+    tick() {
+        if (!this.supported)
+            return Promise.resolve();
+        if (!this.busy)
+            this.busy = this.evaluate().catch((e) => this.deps.log.warn(`tether: ${e.message}`)).finally(() => (this.busy = null));
+        return this.busy;
+    }
+    decide(line) {
+        if (line === this.lastLogged)
+            return;
+        this.lastLogged = line;
+        this.deps.log.info(`tether: ${line}`);
+    }
+    currentIp() {
+        return this.device ? wifiIPv4(this.interfaces(), this.device) : null;
+    }
+    currentNetwork() {
+        return this.device ? wifiIPv4Network(this.interfaces(), this.device) : null;
+    }
+    /** The learned network, while it belongs to the hotspot name configured now. */
+    learnedNetwork() {
+        return this.learned && this.learned.ssid === this.deps.settings().hotspotSsid ? this.learned.network : null;
+    }
+    onHotspot(ip) {
+        return classifyNetwork(ip, this.learnedNetwork()) === "hotspot";
+    }
+    idle() {
+        const a = this.deps.activity();
+        return a.inFlight === 0 && (a.lastStartedAt === undefined || this.now() - a.lastStartedAt >= RETURN_QUIET_MS);
+    }
+    async evaluate() {
+        const settings = this.deps.settings();
+        if (!settings.enabled) {
+            if (this.state !== "off")
+                this.decide("disabled");
+            this.state = "off";
+            this.landedOnHotspotAt = null;
+            this.window.reset();
+            return;
+        }
+        if (!this.device) {
+            this.device = await this.backend.findWifi();
+            if (!this.device) {
+                this.state = "no-wifi-device";
+                this.decide("no Wi-Fi interface found");
+                return;
+            }
+        }
+        const ip = this.currentIp();
+        this.network = classifyNetwork(ip, this.learnedNetwork());
+        if (this.network === "wifi")
+            this.lastWifiNetwork = this.currentNetwork();
+        const ok = ip ? await this.probe(ip) : false;
+        this.window.push(ok);
+        this.lastProbe = { at: new Date(this.now()).toISOString(), ok, network: this.network };
+        if (this.pinned) {
+            this.state = "pinned";
+            return;
+        }
+        if (this.network === "hotspot") {
+            // Landed here by our own failover or by hand: either way, plan the way back from here.
+            if (this.landedOnHotspotAt === null) {
+                this.landedOnHotspotAt = this.now();
+                this.nextReturnAt = nextReturnPoint(this.landedOnHotspotAt, this.now());
+            }
+            if (this.state !== "on-hotspot")
+                this.decide(`on the hotspot; next try for Wi-Fi in ${Math.round((this.nextReturnAt - this.now()) / 1000)}s`);
+            this.state = "on-hotspot";
+            if (this.now() >= this.nextReturnAt)
+                await this.tryReturn(settings);
+            return;
+        }
+        // On Wi-Fi (or none): the way back is no longer pending, and landing again starts the schedule over.
+        this.landedOnHotspotAt = null;
+        if (!this.window.outage()) {
+            this.state = this.network === "wifi" ? "watching" : "no-wifi";
+            if (this.network === "wifi")
+                this.decide(`watching Wi-Fi (${5 - this.window.failures()}/5 recent probes ok)`);
+            else
+                this.decide("Wi-Fi has no address");
+            return;
+        }
+        await this.failover(settings);
+    }
+    async failover(settings) {
+        const why = this.network === "wifi" ? "Wi-Fi has no internet (3 of the last 5 probes failed)" : "Wi-Fi is not connected";
+        if (!settings.hotspotSsid) {
+            this.state = "no-hotspot-ssid";
+            this.decide(`${why}, but no hotspot name is set`);
+            return;
+        }
+        const since = this.now() - this.lastSwitchAt;
+        if (since < MIN_SWITCH_INTERVAL_MS) {
+            // A failed join keeps saying why (and its hint) until the next attempt.
+            if (!JOIN_FAILURES.has(this.state))
+                this.state = "outage";
+            this.decide(`${why}; waiting ${Math.ceil((MIN_SWITCH_INTERVAL_MS - since) / 1000)}s (at most one switch per minute)`);
+            return;
+        }
+        // A call in flight on a dead network cannot finish anyway; give it a short chance, no more.
+        const waitUntil = this.now() + FAILOVER_IDLE_WAIT_MS;
+        while (this.deps.activity().inFlight > 0 && this.now() < waitUntil)
+            await this.sleep(1_000);
+        this.state = "joining-hotspot";
+        this.lastSwitchAt = this.now();
+        this.decide(`${why}: joining hotspot "${settings.hotspotSsid}"`);
+        const outcome = await this.join(settings.hotspotSsid);
+        this.recordSwitch("hotspot", outcome === "joined", outcome === "joined" ? why : outcome);
+        if (outcome === "joined" && !this.onHotspot(this.currentIp())) {
+            // Joined, but on a network that could not be remembered (see learn()): it reads as Wi-Fi.
+            this.window.reset();
+            this.network = "wifi";
+            this.state = "watching";
+            this.decide("joined the hotspot, but its network cannot be told apart from Wi-Fi; watching it as Wi-Fi (no way back is planned)");
+        }
+        else if (outcome === "joined") {
+            this.window.reset();
+            this.network = "hotspot";
+            this.state = "on-hotspot";
+            this.landedOnHotspotAt = this.now();
+            this.nextReturnAt = nextReturnPoint(this.landedOnHotspotAt, this.now());
+            this.decide(`joined the hotspot; next try for Wi-Fi in ${Math.round((this.nextReturnAt - this.now()) / 1000)}s`);
+        }
+        else {
+            this.state = outcome;
+            this.decide(`could not join the hotspot: ${outcome}`);
+        }
+    }
+    /**
+     * Asks the OS to join, then waits for the hotspot's address: one in the iPhone range or the learned
+     * network, or else — after a join the OS accepted — any new address that is not link-local, whose
+     * network is then learned. Neither OS lets us read the SSID without Location (macOS redacts it;
+     * Windows 24H2 gates `netsh wlan show interfaces`), so "the OS accepted a join of this SSID, and
+     * the address changed" is the strongest evidence there is.
+     */
+    async join(ssid) {
+        const before = this.currentIp();
+        const wifiBefore = [before && !this.onHotspot(before) ? this.currentNetwork() : null, this.lastWifiNetwork];
+        const failed = await this.backend.join(ssid);
+        if (failed)
+            return failed;
+        const deadline = this.now() + JOIN_SETTLE_MS;
+        for (;;) {
+            const ip = this.currentIp();
+            if (this.onHotspot(ip))
+                return "joined";
+            if (ip && ip !== before && !isLinkLocal(ip)) {
+                this.learn(ssid, ip, wifiBefore);
+                return "joined";
+            }
+            if (this.now() >= deadline)
+                return this.backend.noAddressOutcome;
+            await this.sleep(1_000);
+        }
+    }
+    /**
+     * Remembers the network our join of `ssid` landed on. Only a join we made replaces it, and never
+     * with a network just watched as ordinary Wi-Fi: that one would read as the hotspot from then on.
+     */
+    learn(ssid, ip, wifiBefore) {
+        const network = this.currentNetwork();
+        if (!network) {
+            this.step(`joined "${ssid}" at ${ip}, but its netmask could not be read; its network is not remembered`);
+            return;
+        }
+        if (wifiBefore.includes(network)) {
+            this.step(`joined "${ssid}", but its network ${network} is the one watched as Wi-Fi before; not remembering it (the two could not be told apart)`);
+            return;
+        }
+        if (this.learned?.ssid === ssid && this.learned.network === network)
+            return;
+        const was = this.learned?.ssid === ssid ? ` (was ${this.learned.network})` : "";
+        this.learned = { ssid, network, learnedAt: new Date(this.now()).toISOString() };
+        this.step(`remembering ${network} as hotspot "${ssid}"'s network${was}`);
+        if (!this.deps.stateFile)
+            return;
+        try {
+            writeLearnedHotspot(this.deps.stateFile, this.learned);
+        }
+        catch (e) {
+            this.deps.log.warn(`tether: could not save the hotspot's network: ${e.message}`);
+        }
+    }
+    async tryReturn(settings) {
+        if (this.now() - this.lastSwitchAt < MIN_SWITCH_INTERVAL_MS)
+            return;
+        const idle = this.idle();
+        if (!idle && (this.now() - this.nextReturnAt < RETURN_FORCE_AFTER_MS || this.hold.closed)) {
+            this.decide(`Wi-Fi return postponed: a model call is running or just started (after ${RETURN_FORCE_AFTER_MS / 1000}s of this, new calls are held to make a gap)`);
+            return;
+        }
+        const blocked = (await this.backend.returnBlocked?.(settings.hotspotSsid)) ?? null;
+        if (blocked) {
+            this.backOff(blocked);
+            return;
+        }
+        if (idle)
+            await this.leaveHotspot(settings);
+        else
+            await this.returnWithGap(settings);
+    }
+    /**
+     * Calls never stop (Claude and subagents back-to-back), so make the quiet moment: hold new model
+     * calls, let the running ones finish, go back to Wi-Fi, release. The hold is released on every
+     * path out of here, a thrown error included.
+     */
+    async returnWithGap(settings) {
+        const late = Math.round((this.now() - this.nextReturnAt) / 1000);
+        if (!this.hold.engage("going back to Wi-Fi", RETURN_HOLD_FAILSAFE_MS))
+            return;
+        this.holding = true;
+        try {
+            const running = this.deps.activity().inFlight;
+            this.step(`Wi-Fi return postponed ${late}s past due while model calls keep running: holding new model calls to make a gap (waiting up to ${RETURN_DRAIN_WAIT_MS / 1000}s for ${running} running)`);
+            const started = this.now();
+            const until = started + RETURN_DRAIN_WAIT_MS;
+            while (!this.stopped && !this.pinned && this.deps.activity().inFlight > 0 && this.now() < until)
+                await this.sleep(1_000);
+            // stop() already released; a pin made meanwhile pauses switching, so the attempt is dropped.
+            if (this.stopped || this.pinned)
+                return;
+            const left = this.deps.activity().inFlight;
+            if (left > 0) {
+                this.backOff(`${left} model call${left === 1 ? "" : "s"} still running after ${Math.round((this.now() - started) / 1000)}s; held calls released`);
+                return;
+            }
+            this.step(`running model calls finished after ${Math.round((this.now() - started) / 1000)}s; ${this.hold.waiting} held`);
+            await this.leaveHotspot(settings);
+        }
+        finally {
+            this.releaseHold();
+        }
+    }
+    releaseHold(why) {
+        if (!this.holding)
+            return;
+        this.holding = false;
+        const n = this.hold.release();
+        this.step(`hold released${why ? ` (${why})` : ""}; ${n} held model call${n === 1 ? "" : "s"} going ahead`);
+    }
+    /** A one-off step: always logged, and the next state line is logged again after it. */
+    step(line) {
+        this.lastLogged = "";
+        this.deps.log.info(`tether: ${line}`);
+    }
+    /** Leave the hotspot so the OS joins its best known network; keep it only if it has internet. */
+    async leaveHotspot(settings) {
+        const backend = this.backend;
+        this.state = "returning";
+        this.lastSwitchAt = this.now();
+        this.decide(`trying to go back to Wi-Fi: leaving the hotspot so ${this.deps.platform === "win32" ? "Windows" : "macOS"} joins the best known network`);
+        const left = await backend.leave();
+        if (left !== null) {
+            this.deps.log.warn(`tether: leaving the hotspot failed: ${left}`);
+            this.state = "on-hotspot";
+            this.backOff("leaving the hotspot failed");
+            return;
+        }
+        // Back on Wi-Fi only after two good probes through it (one could be a lucky blip).
+        let good = 0;
+        let askedKnown = false;
+        const started = this.now();
+        const deadline = started + RETURN_PROBE_MS;
+        while (this.now() < deadline) {
+            await this.sleep(2_000);
+            const ip = this.currentIp();
+            if (!ip && !askedKnown && backend.joinKnown && this.now() - started >= JOIN_KNOWN_AFTER_MS) {
+                askedKnown = true;
+                await backend.joinKnown(settings.hotspotSsid);
+            }
+            if (ip && !this.onHotspot(ip) && (await this.probe(ip))) {
+                if (++good >= 2)
+                    break;
+            }
+            else
+                good = 0;
+        }
+        this.window.reset();
+        if (good >= 2) {
+            this.network = "wifi";
+            this.state = "watching";
+            this.landedOnHotspotAt = null;
+            this.recordSwitch("wifi", true, "a known Wi-Fi with internet was in range");
+            this.decide("back on Wi-Fi with internet");
+            return;
+        }
+        const ip = this.currentIp();
+        let reason;
+        const osName = this.deps.platform === "win32" ? "Windows" : "macOS";
+        let rejoined = false;
+        if (this.onHotspot(ip))
+            reason = `${osName} rejoined the hotspot (no better network in range)`;
+        else {
+            reason = ip ? `the Wi-Fi ${osName} chose has no internet` : "no network was joined";
+            const outcome = await this.join(settings.hotspotSsid);
+            rejoined = outcome === "joined";
+            if (!rejoined)
+                reason += `; rejoining the hotspot failed: ${outcome}`;
+        }
+        this.network = classifyNetwork(this.currentIp(), this.learnedNetwork());
+        this.recordSwitch("wifi", false, reason);
+        if (this.network !== "hotspot" && rejoined) {
+            // Rejoined, but on a network that could not be remembered (see learn()): it reads as Wi-Fi.
+            this.state = "watching";
+            this.landedOnHotspotAt = null;
+            this.step(`${reason}; rejoined the hotspot, but its network cannot be told apart from Wi-Fi; watching it as Wi-Fi`);
+            return;
+        }
+        this.state = this.network === "hotspot" ? "on-hotspot" : "join-failed";
+        this.backOff(reason);
+    }
+    /**
+     * Stay on the hotspot until the next scheduled point (never doubling; see RETURN_SCHEDULE_MINUTES).
+     * A point already passed — a slow tick, a long gap attempt — is skipped for the next one at least
+     * MIN_SWITCH_INTERVAL_MS out, so a failed try never lands on top of the one just made.
+     */
+    backOff(reason) {
+        const landed = this.landedOnHotspotAt ?? this.now();
+        this.nextReturnAt = nextReturnPoint(landed, this.now());
+        this.lastLogged = "";
+        this.decide(`staying on the hotspot (${reason}); next try in ${Math.round((this.nextReturnAt - this.now()) / 1000)}s`);
+    }
+    recordSwitch(to, ok, reason) {
+        this.lastSwitch = { at: new Date(this.now()).toISOString(), to, ok, reason };
+    }
+}