clauderipple 0.9.5 → 0.11.0

package/dist/router/src/awake.js

@@ -0,0 +1,432 @@
+// Keep a laptop awake with its lid closed while Claude works: macOS here, Windows in awake-win.ts
+// (the decision, journal and controller below are shared; each OS is an AwakeBackend).
+//
+// macOS: the only mechanism that holds a closed MacBook awake on battery or without an external display is
+// `pmset -a disablesleep 1`, run as root. It is undocumented (absent from `man pmset`) but it is what
+// every working open-source tool uses (Insomnia, MacMiniMode, Sleepless, Capsomnia, WiFiGuard), and
+// `pmset -g` reports it as `SleepDisabled`. Root comes from a narrow sudoers rule installed once by
+// `clauderipple awake setup`; here it is only ever `sudo -n`, which fails instead of prompting.
+//
+// Rules this module keeps (docs/ARCHITECTURE.md "Lid-closed awake and hotspot failover"):
+//   - The bit is set only while it is wanted, and a journal (`<home>/awake.json`) records that we
+//     set it, so a router that died with it set clears it on its next start.
+//   - Battery below the floor, a thermal warning, or any error reading either forces it off.
+//   - Turning it off with the lid closed (and nothing else holding the Mac awake) sends the Mac to
+//     sleep, because clearing the bit alone leaves a bagged Mac running (MacMiniMode does the same).
+//   - The router's exit does not touch the bit: a restart's successor reconciles within one tick,
+//     and clearing it here then setting it again a second later is exactly the off-then-on window in
+//     which a closed lid could sleep mid-work. `clauderipple stop`/`uninstall` clear it.
+//
+// Every command goes through an injected `Runner`, never a shell, so tests run against fakes.
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { WinAwakeBackend } from "./awake-win.js";
+export const PMSET = "/usr/bin/pmset";
+export const SUDO = "/usr/bin/sudo";
+export const IOREG = "/usr/sbin/ioreg";
+export const SUDOERS_FILE = "/etc/sudoers.d/clauderipple";
+export function execRunner() {
+    return (file, args, opts = {}) => new Promise((resolve) => {
+        execFile(file, args, {
+            timeout: opts.timeoutMs ?? 10_000,
+            encoding: "utf8",
+            maxBuffer: 4 * 1024 * 1024,
+            env: opts.env ?? { ...process.env, LC_ALL: "C" },
+            windowsHide: true,
+            ...(opts.verbatim ? { windowsVerbatimArguments: true } : {}),
+        }, (error, stdout, stderr) => {
+            if (!error)
+                return resolve({ code: 0, stdout, stderr });
+            // A non-zero exit carries its status as a number; a spawn failure or timeout does not.
+            const code = error.code;
+            resolve({ code: typeof code === "number" ? code : -1, stdout: stdout ?? "", stderr: stderr || error.message });
+        });
+    });
+}
+/**
+ * `pmset -g batt`:
+ *   Now drawing from 'AC Power'
+ *    -InternalBattery-0 (id=7995491)	55%; AC attached; not charging present: true
+ * A Mac without a battery prints no InternalBattery line: percent null, never "on battery".
+ */
+export function parseBattery(text) {
+    const source = /Now drawing from '([^']+)'/.exec(text)?.[1] ?? "";
+    const pct = /InternalBattery[^\n]*?\t?(\d{1,3})%/.exec(text)?.[1];
+    return { percent: pct === undefined ? null : Number(pct), onBattery: /battery/i.test(source) };
+}
+/**
+ * `pmset -g therm`. Measured with nothing recorded:
+ *   Note: No thermal warning level has been recorded
+ * When a level is recorded pmset prints "Thermal warning level set to N." (any N > 0 is a warning).
+ * Output that says neither is "unknown": reported, not acted on, because a wording change in a new
+ * macOS must not switch the feature off for good. A failed command is an error, which is acted on.
+ */
+export function parseThermal(text) {
+    const level = /thermal warning level set to (\d+)/i.exec(text)?.[1];
+    if (level !== undefined)
+        return Number(level) > 0 ? "warning" : "normal";
+    if (/no thermal warning level has been recorded/i.test(text))
+        return "normal";
+    return "unknown";
+}
+/**
+ * `ioreg -r -k AppleClamshellState -d 4` (no privilege needed):
+ *   |   "AppleClamshellCausesSleep" = No
+ *   |   "AppleClamshellState" = Yes
+ *   |   "SleepDisabled" = No
+ * `AppleClamshellCausesSleep` is No while an external display keeps a closed Mac in closed-display
+ * mode — the state in which a closed lid must never be put to sleep by us.
+ */
+export function parseClamshell(text) {
+    const flag = (key) => {
+        const m = new RegExp(`"${key}"\\s*=\\s*(Yes|No)`).exec(text);
+        return m ? m[1] === "Yes" : null;
+    };
+    return { lidClosed: flag("AppleClamshellState"), causesSleep: flag("AppleClamshellCausesSleep"), sleepDisabled: flag("SleepDisabled") };
+}
+// ---- The decision -----------------------------------------------------------------------------
+export const WORKING_GRACE_MS = 10 * 60_000;
+/** Whether the Mac should be held awake now, and the one-line reason. Pure. */
+export function decideAwake(i) {
+    const { mode, until, batteryFloorPercent } = i.settings;
+    if (mode === "off")
+        return { wanted: false, reason: "off" };
+    const untilMs = until ? Date.parse(until) : NaN;
+    if (!Number.isNaN(untilMs) && i.now >= untilMs)
+        return { wanted: false, reason: `until ${until} has passed` };
+    let reason;
+    if (mode === "on")
+        reason = "on";
+    else if (i.inFlight > 0)
+        reason = `working: ${i.inFlight} model call${i.inFlight === 1 ? "" : "s"} running`;
+    else if (i.lastActivityAt !== undefined && i.now - i.lastActivityAt < WORKING_GRACE_MS)
+        reason = `working: last model call ${Math.round((i.now - i.lastActivityAt) / 1000)}s ago`;
+    else
+        return { wanted: false, reason: "idle: no model call in the last 10 min" };
+    // Guards only matter when something wants the Mac awake.
+    if (i.error)
+        return { wanted: false, reason: `error: ${i.error}` };
+    if (i.battery?.onBattery && i.battery.percent !== null && i.battery.percent < batteryFloorPercent) {
+        return { wanted: false, reason: `battery ${i.battery.percent}% is below ${batteryFloorPercent}%` };
+    }
+    if (i.thermal === "warning")
+        return { wanted: false, reason: "thermal warning" };
+    return { wanted: true, reason };
+}
+function journalLid(v) {
+    const l = v;
+    if (!l || typeof l.scheme !== "string" || !/^[0-9a-f-]{36}$/i.test(l.scheme))
+        return undefined;
+    const ok = (n) => typeof n === "number" && Number.isInteger(n) && n >= 0 && n <= 3;
+    return ok(l.ac) && ok(l.dc) ? { scheme: l.scheme.toLowerCase(), ac: l.ac, dc: l.dc } : undefined;
+}
+export function readJournal(file) {
+    try {
+        const j = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof j.applied !== "boolean")
+            return null;
+        const lid = journalLid(j.lid);
+        return {
+            applied: j.applied,
+            since: String(j.since ?? ""),
+            reason: String(j.reason ?? ""),
+            ...(typeof j.lastActivityAt === "number" ? { lastActivityAt: j.lastActivityAt } : {}),
+            ...(lid ? { lid } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeJournal(file, j) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(j) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+/** `sudo -n` refused: the rule is missing or does not cover this exact command. */
+export function sudoRefused(r) {
+    return r.code !== 0 && /password is required|not allowed|sudoers|sorry, user|a terminal is required/i.test(r.stderr + r.stdout);
+}
+export const AWAKE_TICK_MS = 15_000;
+/** Pause between clearing the bit and reading whether a closed lid now causes sleep. */
+export const SLEEPNOW_SETTLE_MS = 3_000;
+export class AwakeController {
+    applied = false;
+    reason = "not started";
+    battery = null;
+    thermal = null;
+    lidClosed = null;
+    sudoFailed = false;
+    lastActivityAt;
+    journaledActivityAt;
+    busy = null;
+    cancel = null;
+    lastLogged = "";
+    deps;
+    now;
+    sleep;
+    backend;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        const j = readJournal(deps.journalFile);
+        // Reconcile starts from what the last process recorded: if it set the bit and died (or was
+        // restarted), we own it now and the first tick keeps or clears it.
+        if (j) {
+            this.applied = j.applied;
+            this.lastActivityAt = j.lastActivityAt;
+            this.journaledActivityAt = j.lastActivityAt;
+        }
+        const log = deps.log;
+        if (deps.platform === "darwin") {
+            this.backend = new MacAwakeBackend({ run: deps.run, sleep: this.sleep, log, fileExists: deps.fileExists ?? ((f) => fs.existsSync(f)) });
+        }
+        else if (deps.platform === "win32") {
+            this.backend = new WinAwakeBackend({ run: deps.run, sleep: this.sleep, now: this.now, log, save: () => this.persist(true), ...(deps.winHelper ? { helper: deps.winHelper } : {}) }, j);
+        }
+        else
+            this.backend = null;
+    }
+    get supported() {
+        return this.backend !== null;
+    }
+    /** First tick now (the reconcile), then every 15s. A no-op where unsupported. */
+    async start() {
+        if (!this.supported) {
+            this.reason = "unsupported on this platform";
+            return;
+        }
+        await this.tick();
+        const schedule = this.deps.schedule ?? ((fn, ms) => {
+            const t = setInterval(fn, ms);
+            t.unref();
+            return () => clearInterval(t);
+        });
+        this.cancel = schedule(() => void this.tick(), AWAKE_TICK_MS);
+    }
+    stop() {
+        this.cancel?.();
+        this.cancel = null;
+    }
+    status() {
+        const s = this.deps.settings();
+        return {
+            mode: s.mode,
+            applied: this.applied,
+            reason: this.reason,
+            setup: this.backend ? this.backend.setup(this.sudoFailed) : "unsupported",
+            battery: this.battery,
+            thermal: this.thermal,
+            lidClosed: this.lidClosed,
+            until: s.until ?? null,
+        };
+    }
+    /** One evaluation. Concurrent callers share the running one. */
+    tick() {
+        if (!this.supported)
+            return Promise.resolve();
+        if (!this.busy)
+            this.busy = this.evaluate().finally(() => (this.busy = null));
+        return this.busy;
+    }
+    /** A fresh evaluation after a settings change: one already running read the old settings. */
+    async refresh() {
+        if (this.busy)
+            await this.busy;
+        // A refresh follows `awake setup` or a settings change: a sudo refusal from before the setup
+        // must not keep saying "needs setup" while the mode is off and nothing calls pmset to retry.
+        this.sudoFailed = false;
+        await this.tick();
+    }
+    /**
+     * The router is exiting. Only the journal is written (with the latest activity, so a successor
+     * remembers the working window); the bit stays as it is. See the header comment for why.
+     */
+    beforeExit() {
+        if (!this.supported)
+            return;
+        this.noteActivity();
+        this.persist(true);
+        // Windows: the execution-state child exits with stdin closed (it would with the process anyway);
+        // the lid action stays as journaled for the successor, like the macOS bit.
+        this.backend?.shutdown();
+    }
+    noteActivity() {
+        const a = this.deps.activity();
+        const latest = Math.max(a.lastStartedAt ?? 0, a.lastEndedAt ?? 0, a.inFlight > 0 ? this.now() : 0);
+        if (latest > 0 && (this.lastActivityAt === undefined || latest > this.lastActivityAt))
+            this.lastActivityAt = latest;
+    }
+    persist(force = false) {
+        // The activity time is written at most once a minute: it only has to survive a restart.
+        const stale = this.lastActivityAt !== undefined && (this.journaledActivityAt === undefined || this.lastActivityAt - this.journaledActivityAt >= 60_000);
+        if (!force && !stale)
+            return;
+        try {
+            const prev = readJournal(this.deps.journalFile);
+            writeJournal(this.deps.journalFile, {
+                applied: this.applied,
+                since: prev && prev.applied === this.applied ? prev.since : new Date(this.now()).toISOString(),
+                reason: this.reason,
+                ...(this.lastActivityAt !== undefined ? { lastActivityAt: this.lastActivityAt } : {}),
+                ...(this.backend?.journalExtra() ?? {}),
+            });
+            this.journaledActivityAt = this.lastActivityAt;
+        }
+        catch (e) {
+            this.deps.log.warn(`awake: cannot write journal: ${e.message}`);
+        }
+    }
+    logOnce(line) {
+        if (line === this.lastLogged)
+            return;
+        this.lastLogged = line;
+        this.deps.log.info(line);
+    }
+    async evaluate() {
+        const settings = this.deps.settings();
+        this.noteActivity();
+        const activity = this.deps.activity();
+        const backend = this.backend;
+        // Nothing to watch: no reads, no processes, unless a hold we took still has to be released.
+        if (settings.mode === "off" && !this.applied) {
+            this.reason = "off";
+            this.battery = null;
+            this.thermal = null;
+            this.lidClosed = null;
+            backend.shutdown();
+            this.persist();
+            return;
+        }
+        const decide = (g) => decideAwake({
+            settings,
+            now: this.now(),
+            inFlight: activity.inFlight,
+            ...(this.lastActivityAt !== undefined ? { lastActivityAt: this.lastActivityAt } : {}),
+            battery: g?.battery ?? null,
+            thermal: g?.thermal ?? "unknown",
+            ...(g?.error ? { error: g.error } : {}),
+        });
+        // Whether anything wants the machine awake before the guards are read: a backend may skip
+        // reads (on Windows, a whole child process) when nothing does.
+        const guards = await backend.readGuards(decide().wanted);
+        this.battery = guards.battery;
+        this.thermal = guards.thermal;
+        this.lidClosed = guards.lidClosed;
+        // What we set reads as undone: a reboot (the macOS bit does not survive one), another tool
+        // (Insomnia saw one reset it every 2s), or the user changing the Windows lid action. Take it as
+        // not applied, so a wanted state is set again below — re-asserting at most once per tick — and an
+        // unwanted one is not "cleared" twice.
+        if (this.applied && !(await backend.stillHeld())) {
+            this.logOnce("awake: sleep was re-enabled outside ClaudeRipple (reboot or another tool)");
+            this.applied = false;
+        }
+        const d = decide(guards);
+        this.reason = d.reason;
+        if (d.wanted && !this.applied)
+            await this.set(true, d.reason);
+        else if (!d.wanted && this.applied) {
+            if (await this.set(false, d.reason))
+                await backend.afterRelease();
+        }
+        this.persist();
+    }
+    /** Hold or release. The journal is written before holding and after releasing. */
+    async set(on, reason) {
+        const backend = this.backend;
+        if (on) {
+            this.applied = true;
+            this.persist(true);
+        }
+        const r = on ? await backend.hold() : await backend.release();
+        if (!r.ok) {
+            this.sudoFailed = r.refused;
+            if (on) {
+                this.applied = false;
+                this.persist(true);
+            }
+            this.reason = r.refused ? "needs setup: run `clauderipple awake setup` once" : r.message;
+            this.logOnce(`awake: could not ${on ? "disable" : "re-enable"} sleep (${reason}): ${this.reason}`);
+            return false;
+        }
+        this.sudoFailed = false;
+        this.applied = on;
+        this.persist(true);
+        this.lastLogged = "";
+        this.deps.log.info(`awake: sleep ${on ? "disabled" : "re-enabled"} (${reason})`);
+        return true;
+    }
+}
+class MacAwakeBackend {
+    deps;
+    clamshell = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    setup(sudoFailed) {
+        return sudoFailed || !this.deps.fileExists(SUDOERS_FILE) ? "needs-setup" : "ok";
+    }
+    journalExtra() {
+        return {};
+    }
+    shutdown() { }
+    async readGuards() {
+        let error;
+        let battery = null;
+        let thermal = null;
+        const batt = await this.deps.run(PMSET, ["-g", "batt"]);
+        if (batt.code === 0)
+            battery = parseBattery(batt.stdout);
+        else
+            error = `pmset -g batt failed (${batt.code})`;
+        const therm = await this.deps.run(PMSET, ["-g", "therm"]);
+        if (therm.code === 0)
+            thermal = parseThermal(therm.stdout);
+        else
+            error ??= `pmset -g therm failed (${therm.code})`;
+        this.clamshell = await this.readClamshell();
+        return { battery, thermal, lidClosed: this.clamshell?.lidClosed ?? null, ...(error ? { error } : {}) };
+    }
+    async stillHeld() {
+        return this.clamshell?.sleepDisabled !== false;
+    }
+    async readClamshell() {
+        const r = await this.deps.run(IOREG, ["-r", "-k", "AppleClamshellState", "-d", "4"]);
+        return r.code === 0 ? parseClamshell(r.stdout) : null;
+    }
+    /** `sudo -n pmset -a disablesleep 1|0`. */
+    async disableSleep(on) {
+        const r = await this.deps.run(SUDO, ["-n", PMSET, "-a", "disablesleep", on ? "1" : "0"]);
+        if (r.code === 0)
+            return { ok: true };
+        return { ok: false, refused: sudoRefused(r), message: `pmset failed: ${(r.stderr || r.stdout).trim().slice(0, 200)}` };
+    }
+    hold() {
+        return this.disableSleep(true);
+    }
+    release() {
+        return this.disableSleep(false);
+    }
+    /**
+     * With the bit cleared, a Mac whose lid is shut keeps running: nothing re-evaluates the lid. If the
+     * lid is closed and macOS says a closed lid now causes sleep (no external display holding it in
+     * closed-display mode), put it to sleep so a bagged Mac does not run on. Tried unprivileged first,
+     * then through the sudoers rule.
+     */
+    async afterRelease() {
+        await this.deps.sleep(SLEEPNOW_SETTLE_MS);
+        const c = await this.readClamshell();
+        if (!c?.lidClosed || c.causesSleep !== true)
+            return;
+        this.deps.log.info("awake: lid is closed and nothing else holds the Mac awake; sleeping now");
+        const r = await this.deps.run(PMSET, ["sleepnow"]);
+        if (r.code === 0)
+            return;
+        const s = await this.deps.run(SUDO, ["-n", PMSET, "sleepnow"]);
+        if (s.code !== 0)
+            this.deps.log.warn(`awake: pmset sleepnow failed: ${(s.stderr || s.stdout || r.stderr).trim().slice(0, 200)}`);
+    }
+}

package/dist/router/src/config.js

@@ -7,6 +7,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { PRESETS } from "./presets.js";
+import { hostProblem, portProblem } from "./remote-host.js";
 /**
  * The provider's own key, re-sent under the header another wire on the same account expects.
  *
@@ -98,6 +99,69 @@ export function searchProviderFor(provider, model) {
         ...(presetId ? { preset: presetId } : {}),
     };
 }
+export const AWAKE_DEFAULTS = { mode: "off", batteryFloorPercent: 20 };
+export const TETHER_DEFAULTS = { enabled: false, hotspotSsid: "", probeEverySec: 10 };
+export function awakeSettings(c) {
+    return { ...AWAKE_DEFAULTS, ...(c.awake ?? {}) };
+}
+export function tetherSettings(c) {
+    const t = { ...TETHER_DEFAULTS, ...(c.tether ?? {}) };
+    // A config from before 2026-10-20 still carries `returnEverySec`; it loads fine (unknown keys are
+    // not refused) and is dropped here rather than carried into the controller's settings.
+    return { enabled: t.enabled, hotspotSsid: t.hotspotSsid, probeEverySec: t.probeEverySec };
+}
+/**
+ * A hotspot name is written into a sudoers rule and handed to `networksetup` as one argument, so it
+ * is held to a charset that is literal in both: letters, digits, single spaces, `. _ -`, and the
+ * straight and typographic apostrophes iPhone names use ("Name’s iPhone"). Nothing sudoers or fnmatch
+ * reads specially (`, : = \ * ? [ ] #` and quotes) can get through. Returns what is wrong, or null.
+ */
+export function ssidProblem(ssid) {
+    if (typeof ssid !== "string" || !ssid)
+        return "the hotspot name is empty";
+    if (Buffer.byteLength(ssid, "utf8") > 32)
+        return "a Wi-Fi name is at most 32 bytes";
+    if (!/^[A-Za-z0-9 ._'’-]+$/u.test(ssid))
+        return "the hotspot name may contain only letters, digits, spaces and . _ - ' ’";
+    if (/^ | $|  /.test(ssid))
+        return "the hotspot name cannot start or end with a space or contain two in a row";
+    if (ssid.startsWith("-"))
+        return "the hotspot name cannot start with -";
+    return null;
+}
+function validatePower(c, errors) {
+    if (c.awake !== undefined) {
+        const a = c.awake;
+        if (!a || typeof a !== "object" || Array.isArray(a))
+            errors.push("awake must be an object");
+        else {
+            if (a.mode !== undefined && a.mode !== "off" && a.mode !== "working" && a.mode !== "on")
+                errors.push('awake.mode must be "off", "working" or "on"');
+            if (a.until !== undefined && (typeof a.until !== "string" || Number.isNaN(Date.parse(a.until))))
+                errors.push("awake.until must be an ISO date-time");
+            if (a.batteryFloorPercent !== undefined && !(typeof a.batteryFloorPercent === "number" && a.batteryFloorPercent >= 0 && a.batteryFloorPercent <= 100))
+                errors.push("awake.batteryFloorPercent must be a number from 0 to 100");
+        }
+    }
+    if (c.tether !== undefined) {
+        const t = c.tether;
+        if (!t || typeof t !== "object" || Array.isArray(t))
+            errors.push("tether must be an object");
+        else {
+            if (t.enabled !== undefined && typeof t.enabled !== "boolean")
+                errors.push("tether.enabled must be true or false");
+            if (t.hotspotSsid !== undefined && t.hotspotSsid !== "") {
+                const problem = ssidProblem(t.hotspotSsid);
+                if (problem)
+                    errors.push(`tether.hotspotSsid: ${problem}`);
+            }
+            if (t.probeEverySec !== undefined && !(typeof t.probeEverySec === "number" && t.probeEverySec >= 5 && t.probeEverySec <= 3600))
+                errors.push("tether.probeEverySec must be a number from 5 to 3600");
+            // `tether.returnEverySec` was dropped on 2026-10-20 (the way back is a fixed schedule now).
+            // A config still carrying it is left alone: unknown keys are not refused here.
+        }
+    }
+}
 export const PICKER_HOSTS_DEFAULT = ["claude.ai"];
 export function terminateHosts(c) {
     const hosts = [c.upstream];
@@ -323,6 +387,8 @@ export function validate(c) {
             errors.push(`provider ${name}: identity must be true or false`);
         if (shared.instructionsAppend !== undefined && typeof shared.instructionsAppend !== "string")
             errors.push(`provider ${name}: instructionsAppend must be a string`);
+        if (shared.limits !== undefined && typeof shared.limits !== "boolean")
+            errors.push(`provider ${name}: limits must be true or false`);
         // Ids key the router's cooldown and quarantine state, so a duplicate would make two credentials
         // share one health record and take each other down.
         const pool = p.credentials;
@@ -465,6 +531,34 @@ export function validate(c) {
         errors.push("cli.limitWorkerTools must be true or false");
     if (c.listen.openaiPort !== undefined && !(c.listen.openaiPort >= 0 && c.listen.openaiPort < 65536))
         errors.push("listen.openaiPort out of range");
+    if (c.remote !== undefined) {
+        const hosts = c.remote?.hosts;
+        if (!Array.isArray(hosts))
+            errors.push("remote.hosts must be a list");
+        else {
+            const seen = new Set();
+            hosts.forEach((entry, i) => {
+                const h = entry;
+                if (!h || typeof h !== "object") {
+                    errors.push(`remote.hosts ${i} must be an object`);
+                    return;
+                }
+                // Handed to ssh as an argument: the same check `remote add` applies, so a hand edit cannot
+                // slip an option such as -oProxyCommand into the router's own ssh.
+                const hostError = hostProblem(h.host);
+                if (hostError)
+                    errors.push(`remote.hosts ${i}: ${hostError}`);
+                else if (seen.has(h.host))
+                    errors.push(`remote.hosts ${i}: "${String(h.host)}" is listed twice`);
+                else
+                    seen.add(h.host);
+                const portError = portProblem(h.port);
+                if (portError)
+                    errors.push(`remote.hosts ${i}: ${portError}`);
+            });
+        }
+    }
+    validatePower(c, errors);
     return errors;
 }
 export class ConfigStore {

package/dist/router/src/health.js

@@ -2,6 +2,16 @@
 // stays bad (observed: 10h of ENOTFOUND, 11 remote-control workers lost). After N
 // consecutive upstream *connect-level* failures with no success in between, exit
 // with a distinctive code so the supervisor restarts a fresh process.
+//
+// But only when a fresh process would do better. When the counter trips, a child process (curl,
+// with its own resolver and sockets) asks the internet first: if it gets through, this process is
+// the broken part and it exits; if it does not, the machine itself is offline, a restart cannot
+// help, and the process stays (logged once per outage; the counter re-arms). On 2026-10-20 a
+// MacBook that lost Wi-Fi on the commute restarted the router 27 times in 18 minutes, and every
+// restart threw away the hotspot failover's probe history before it could act (tether.ts).
+// A check that cannot run (no curl) exits as before: the documented fix stays the default.
+import path from "node:path";
+import { PROBE_URLS } from "./tether.js";
 /** Only definite billing/quota exhaustion, never a bare rate limit or RESOURCE_EXHAUSTED.
  * 402 is already `exhausted` in pool.ts; Codex's usage_limit_reached is named in
  * providers/chatgpt/translate.ts. Other vendors share the explicit billing vocabulary.
@@ -51,26 +61,99 @@ export function isConnectError(e) {
     const code = e?.code;
     return typeof code === "string" && CONNECT_ERRORS.has(code);
 }
+/** curl exits that mean "the network did not get us there" (man curl, EXIT CODES). Any other is the check failing. */
+const CURL_NETWORK_EXITS = new Set([5, 6, 7, 28, 35, 52, 55, 56]);
+export const CONNECTIVITY_TIMEOUT_S = 5;
+/** The curl the OS ships: macOS/Linux /usr/bin/curl, Windows 10 1803+ %SystemRoot%\System32\curl.exe. */
+export function curlPath(platform, env = process.env) {
+    if (platform === "win32")
+        return path.win32.join(env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows", "System32", "curl.exe");
+    return "/usr/bin/curl";
+}
+async function curlProbe(run, curl, url, ok) {
+    // -q first: no ~/.curlrc. --noproxy: the answer must be the network's, never a proxy's (ours included).
+    const r = await run(curl, ["-q", "-s", "--noproxy", "*", "-m", String(CONNECTIVITY_TIMEOUT_S), "-w", "\n%{http_code}", url], { timeoutMs: (CONNECTIVITY_TIMEOUT_S + 5) * 1000 });
+    if (r.code === 0) {
+        const at = r.stdout.lastIndexOf("\n");
+        const status = Number(r.stdout.slice(at + 1).trim());
+        const body = at >= 0 ? r.stdout.slice(0, at) : "";
+        // Anything but the exact answer (a captive portal's page, a redirect) is not the internet either.
+        return ok(status, body) ? { probe: "ok", detail: `HTTP ${status}` } : { probe: "fail", detail: `unexpected HTTP ${status}` };
+    }
+    if (CURL_NETWORK_EXITS.has(r.code))
+        return { probe: "fail", detail: `curl exit ${r.code}` };
+    return { probe: "error", detail: `curl could not run (${r.code}: ${r.stderr.trim().slice(0, 120)})` };
+}
+/** The same two endpoints as the hotspot probe (tether.ts), asked by a child process. Never throws. */
+export async function checkConnectivity(run, platform, env = process.env) {
+    const curl = curlPath(platform, env);
+    const [apple, google] = await Promise.all([
+        curlProbe(run, curl, PROBE_URLS.apple, (s, b) => s === 200 && b.includes("Success")),
+        curlProbe(run, curl, PROBE_URLS.google, (s) => s === 204),
+    ]);
+    const detail = `captive.apple.com: ${apple.detail}, gstatic: ${google.detail}`;
+    if (apple.probe === "ok" || google.probe === "ok")
+        return { result: "online", detail };
+    if (apple.probe === "error" || google.probe === "error")
+        return { result: "unknown", detail };
+    return { result: "offline", detail };
+}
 export class UpstreamHealth {
     consecutive = 0;
     tripped = false;
+    /** An offline verdict was logged and no success has been seen since. */
+    offline = false;
+    /** Bumped by every success, so a check that raced one does not exit a process that works. */
+    successes = 0;
     limit;
     onTrip;
-    constructor(limit, onTrip) {
+    opts;
+    constructor(limit, onTrip, opts = {}) {
         this.limit = limit;
         this.onTrip = onTrip;
+        this.opts = opts;
     }
     success() {
         this.consecutive = 0;
+        this.offline = false;
+        this.successes++;
     }
     failure(e) {
         if (!isConnectError(e))
             return;
         this.consecutive++;
-        if (!this.tripped && this.consecutive >= this.limit()) {
-            this.tripped = true;
+        if (this.tripped || this.consecutive < this.limit())
+            return;
+        this.tripped = true;
+        if (!this.opts.connectivity)
             this.onTrip(this.consecutive);
+        else
+            void this.confirm(this.opts.connectivity);
+    }
+    async confirm(check) {
+        const before = this.successes;
+        let c;
+        try {
+            c = await check();
+        }
+        catch (e) {
+            c = { result: "unknown", detail: `check failed: ${e.message}` };
         }
+        if (this.successes !== before) {
+            // An upstream call got through while we asked: this process works. Re-arm.
+            this.tripped = false;
+            return;
+        }
+        if (c.result !== "offline") {
+            this.onTrip(this.consecutive, c);
+            return;
+        }
+        if (!this.offline) {
+            this.offline = true;
+            this.opts.onOffline?.(this.consecutive, c);
+        }
+        this.consecutive = 0;
+        this.tripped = false;
     }
     get consecutiveFailures() {
         return this.consecutive;